Deploy ephemeral-object issuer wiring (session 210)

Dockerfile

@@ -7,7 +7,7 @@ RUN npm ci --no-audit --no-fund && chown -R node:node /app
 
 # HF Spaces는 app_port(7860)로 트래픽을 보냄. 서버는 PORT env를 읽음.
 ENV PORT=7860
-ENV SERVICE_VERSION=24f010d
+ENV SERVICE_VERSION=1dc600b
 EXPOSE 7860
 
 USER node

README.md

@@ -14,15 +14,17 @@ Remote MCP editing service for HWPX documents (experimental v0).
 
 - Endpoints: `POST /mcp`, `POST /mcp-claude`, `GET /.well-known/oauth-protected-resource`, and `GET /oauth/consent`.
 - MCP endpoints accept the fixed bearer fallback or a Supabase-issued OAuth access token.
-- Documents are held in memory only (TTL, no persistence, no content logging).
+- Supabase-authenticated remote sessions keep document generations in private, expiring object storage; the service hydrates bytes only while an operation runs and does not log document content. The fixed bearer fallback keeps the legacy in-process session path.
 
 ## Required Space secrets
 
 - `MCP_AUTH_TOKEN` — Bearer token; the server refuses to start without it.
 - `PUBLIC_BASE_URL` — this Space's public URL (e.g. `https://<user>-<space>.hf.space`), used for expiring download URLs.
 - `OPENAI_APPS_CHALLENGE` — optional; ChatGPT Apps domain challenge value.
-- `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` — optional together; enable OAuth discovery, JWT verification, and consent UI.
-- `SUPABASE_JWT_AUDIENCE` — optional; when set, bearer tokens must also carry this `aud` claim. Leave unset until the audience of real tokens has been observed: setting a wrong value rejects every caller.
+- `SUPABASE_URL` and `SUPABASE_JWT_AUDIENCE` — optional together; enable OAuth discovery and JWT verification. Measure the real token audience before enabling this mode: a wrong value rejects every caller.
+- `SUPABASE_PUBLISHABLE_KEY` — optional; together with `SUPABASE_URL`, enables the consent UI.
+- `WEBAPP_EPHEMERAL_OBJECT_BASE_URL` — required when Supabase authentication is enabled; the separate HTTPS webapp origin that issues owner-bound upload and download capabilities. It must differ from `PUBLIC_BASE_URL`.
+- `MCP_REQUIRED_SCOPES` — optional ASCII-space-delimited OAuth scope-token list. The default is the empty set; configure a measured baseline to make OAuth grant tokens missing that baseline fail with HTTP 403 `insufficient_scope`.
 
 ## Platform-provided memory observation (provided by the platform — do not configure)
 

packages/mcp-remote/src/config.ts

@@ -1,8 +1,8 @@
 import type { RemoteMcpConfig, RemoteMcpEnv } from "./types.js";
 import { DEFAULT_SESSION_SWEEP_INTERVAL_MS } from "./runtime-defaults.js";
 
-const DEFAULT_SESSION_TTL_MS = 3_600_000;
-const DEFAULT_SESSION_IDLE_TTL_MS = 1_800_000;
+export const DEFAULT_SESSION_TTL_MS = 3_600_000;
+export const DEFAULT_SESSION_IDLE_TTL_MS = 1_800_000;
 const DEFAULT_MAX_FILE_BYTES = 20 * 1024 * 1024;
 const DEFAULT_MAX_TARGETS = 5_000;
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 4;
@@ -22,12 +22,25 @@ export function configFromEnv(env: RemoteMcpEnv = process.env): RemoteMcpConfig
   if (!publicBaseUrl) {
     throw new Error("PUBLIC_BASE_URL is required for expiring download URLs.");
   }
+  const normalizedPublicBaseUrl = normalizeBaseUrl(publicBaseUrl);
 
   const supabaseUrl = env.SUPABASE_URL ? normalizeHttpUrl(env.SUPABASE_URL, "SUPABASE_URL") : undefined;
   const supabaseJwtAudience = env.SUPABASE_JWT_AUDIENCE || undefined;
+  const webappEphemeralObjectBaseUrl = env.WEBAPP_EPHEMERAL_OBJECT_BASE_URL
+    ? normalizeCredentialBearingUrl(env.WEBAPP_EPHEMERAL_OBJECT_BASE_URL, "WEBAPP_EPHEMERAL_OBJECT_BASE_URL")
+    : undefined;
   if (Boolean(supabaseUrl) !== Boolean(supabaseJwtAudience)) {
     throw new Error("SUPABASE_URL and SUPABASE_JWT_AUDIENCE must be configured together.");
   }
+  if (supabaseUrl && !webappEphemeralObjectBaseUrl) {
+    throw new Error("WEBAPP_EPHEMERAL_OBJECT_BASE_URL is required with Supabase authentication.");
+  }
+  if (!supabaseUrl && webappEphemeralObjectBaseUrl) {
+    throw new Error("WEBAPP_EPHEMERAL_OBJECT_BASE_URL requires Supabase authentication.");
+  }
+  if (webappEphemeralObjectBaseUrl === normalizedPublicBaseUrl) {
+    throw new Error("WEBAPP_EPHEMERAL_OBJECT_BASE_URL must be distinct from PUBLIC_BASE_URL.");
+  }
 
   const maxConcurrentSessions = parsePositiveInteger(
     env.MAX_CONCURRENT_SESSIONS,
@@ -57,7 +70,8 @@ export function configFromEnv(env: RemoteMcpEnv = process.env): RemoteMcpConfig
 
   return {
     authToken,
-    publicBaseUrl: normalizeBaseUrl(publicBaseUrl),
+    publicBaseUrl: normalizedPublicBaseUrl,
+    requiredScopes: parseRequiredScopes(env.MCP_REQUIRED_SCOPES),
     sessionTtlMs: parsePositiveInteger(env.SESSION_TTL_MS, DEFAULT_SESSION_TTL_MS, "SESSION_TTL_MS"),
     sessionIdleTtlMs: parsePositiveInteger(
       env.SESSION_IDLE_TTL_MS,
@@ -91,11 +105,21 @@ export function configFromEnv(env: RemoteMcpEnv = process.env): RemoteMcpConfig
     supabaseUrl,
     supabasePublishableKey: env.SUPABASE_PUBLISHABLE_KEY,
     supabaseJwtAudience,
+    webappEphemeralObjectBaseUrl,
     serviceVersion: env.SERVICE_VERSION ?? "dev",
     statusAllowedOrigin: env.STATUS_ALLOWED_ORIGIN ?? "*"
   };
 }
 
+function parseRequiredScopes(value: string | undefined): readonly string[] {
+  if (value === undefined || value === "") return Object.freeze([]);
+  const scopeToken = "[!#-\\[\\]-~]+";
+  if (!new RegExp(`^${scopeToken}(?: ${scopeToken})*$`, "u").test(value)) {
+    throw new Error("MCP_REQUIRED_SCOPES must be an ASCII-space-delimited scope-token list.");
+  }
+  return Object.freeze([...new Set(value.split(" "))]);
+}
+
 export function deriveMaxConcurrentSessionsPerPrincipal(maxConcurrentSessions: number): number {
   return Math.max(1, Math.floor(maxConcurrentSessions / 2));
 }
@@ -158,3 +182,11 @@ function normalizeHttpUrl(value: string, name: string): string {
   }
   return url.toString().replace(/\/$/u, "");
 }
+
+function normalizeCredentialBearingUrl(value: string, name: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password) {
+    throw new Error(`${name} must be an HTTPS URL without embedded credentials.`);
+  }
+  return url.toString().replace(/\/$/u, "");
+}

packages/mcp-remote/src/ephemeral-object-client.ts

@@ -0,0 +1,216 @@
+import type {
+  EphemeralObjectClient,
+  EphemeralObjectReference,
+  StoredEphemeralObject
+} from "./types.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+type UploadIssueResponse = Readonly<{
+  objectId: string;
+  byteLength: number;
+  retentionExpiresAt: string;
+  uploadUrl: string;
+  uploadUrlLifetime: "provider-fixed";
+}>;
+
+type DownloadIssueResponse = Readonly<{
+  objectId: string;
+  byteLength: number;
+  retentionExpiresAt: string;
+  downloadUrl: string;
+  downloadUrlExpiresAt: string;
+}>;
+
+export class WebappEphemeralObjectClient implements EphemeralObjectClient {
+  private readonly baseUrl: URL;
+
+  constructor(
+    baseUrl: string,
+    private readonly fetchImpl: typeof fetch = fetch
+  ) {
+    this.baseUrl = httpsUrl(baseUrl);
+  }
+
+  async storeAndDownload(bytes: Buffer, bearerToken: string): Promise<StoredEphemeralObject> {
+    assertBytes(bytes);
+    assertBearerToken(bearerToken);
+
+    const upload = parseUploadIssueResponse(await this.postJson(
+      "/api/ephemeral-objects/upload-issue",
+      { byteLength: bytes.byteLength },
+      bearerToken
+    ), bytes.byteLength);
+    const ref = referenceFromUpload(upload);
+
+    const uploadBody = Uint8Array.from(bytes).buffer;
+    const uploaded = await this.fetchImpl(providerUrl(upload.uploadUrl), {
+      method: "PUT",
+      redirect: "error",
+      headers: { "content-type": "application/octet-stream" },
+      body: uploadBody
+    });
+    if (!uploaded.ok) throw unavailable();
+
+    const access = await this.issueDownload(ref, bearerToken);
+    const downloaded = await this.fetchObject(access.downloadUrl, ref.byteLength);
+    if (!downloaded.equals(bytes)) throw unavailable();
+
+    return Object.freeze({
+      ref,
+      downloadUrl: access.downloadUrl,
+      downloadExpiresAt: access.downloadExpiresAt,
+      bytes: downloaded
+    });
+  }
+
+  async download(ref: EphemeralObjectReference, bearerToken: string): Promise<Buffer> {
+    assertReference(ref);
+    assertBearerToken(bearerToken);
+    const access = await this.issueDownload(ref, bearerToken);
+    return this.fetchObject(access.downloadUrl, ref.byteLength);
+  }
+
+  private async issueDownload(
+    ref: EphemeralObjectReference,
+    bearerToken: string
+  ): Promise<Readonly<{ downloadUrl: string; downloadExpiresAt: number }>> {
+    const response = parseDownloadIssueResponse(await this.postJson(
+      "/api/ephemeral-objects/download-issue",
+      { objectId: ref.objectId },
+      bearerToken
+    ));
+    const responseRetentionExpiresAt = timestamp(response.retentionExpiresAt);
+    if (response.objectId !== ref.objectId
+      || response.byteLength !== ref.byteLength
+      || responseRetentionExpiresAt !== ref.retentionExpiresAt) {
+      throw unavailable();
+    }
+    const downloadExpiresAt = timestamp(response.downloadUrlExpiresAt);
+    if (downloadExpiresAt > ref.retentionExpiresAt) throw unavailable();
+    return Object.freeze({
+      downloadUrl: providerUrl(response.downloadUrl),
+      downloadExpiresAt
+    });
+  }
+
+  private async postJson(path: string, body: Readonly<Record<string, unknown>>, bearerToken: string): Promise<unknown> {
+    const response = await this.fetchImpl(new URL(path, this.baseUrl), {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        authorization: `Bearer ${bearerToken}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) throw unavailable();
+    try {
+      return await response.json();
+    } catch {
+      throw unavailable();
+    }
+  }
+
+  private async fetchObject(url: string, expectedBytes: number): Promise<Buffer> {
+    const response = await this.fetchImpl(providerUrl(url), { method: "GET", redirect: "error" });
+    if (!response.ok) throw unavailable();
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.byteLength !== expectedBytes) {
+      bytes.fill(0);
+      throw unavailable();
+    }
+    return bytes;
+  }
+}
+
+function parseUploadIssueResponse(value: unknown, expectedBytes: number): UploadIssueResponse {
+  if (!isRecord(value)
+    || !UUID.test(string(value.objectId))
+    || value.byteLength !== expectedBytes
+    || !validTimestamp(value.retentionExpiresAt)
+    || typeof value.uploadUrl !== "string"
+    || value.uploadUrlLifetime !== "provider-fixed") {
+    throw unavailable();
+  }
+  return value as UploadIssueResponse;
+}
+
+function parseDownloadIssueResponse(value: unknown): DownloadIssueResponse {
+  if (!isRecord(value)
+    || !UUID.test(string(value.objectId))
+    || !positiveSafeInteger(value.byteLength)
+    || !validTimestamp(value.retentionExpiresAt)
+    || typeof value.downloadUrl !== "string"
+    || !validTimestamp(value.downloadUrlExpiresAt)) {
+    throw unavailable();
+  }
+  return value as DownloadIssueResponse;
+}
+
+function referenceFromUpload(response: UploadIssueResponse): EphemeralObjectReference {
+  return Object.freeze({
+    objectId: response.objectId,
+    byteLength: response.byteLength,
+    retentionExpiresAt: timestamp(response.retentionExpiresAt)
+  });
+}
+
+function assertReference(ref: EphemeralObjectReference): void {
+  if (!UUID.test(ref.objectId)
+    || !positiveSafeInteger(ref.byteLength)
+    || !Number.isSafeInteger(ref.retentionExpiresAt)
+    || ref.retentionExpiresAt <= 0) {
+    throw new TypeError("Ephemeral object reference is invalid.");
+  }
+}
+
+function assertBytes(bytes: Buffer): void {
+  if (!Buffer.isBuffer(bytes) || !positiveSafeInteger(bytes.byteLength)) {
+    throw new TypeError("Ephemeral object bytes are invalid.");
+  }
+}
+
+function assertBearerToken(value: string): void {
+  if (typeof value !== "string" || value.length === 0 || /[\u0000-\u0020\u007f]/u.test(value)) {
+    throw new TypeError("Ephemeral object authentication is invalid.");
+  }
+}
+
+function httpsUrl(value: string): URL {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password) {
+    throw new TypeError("Ephemeral object URL is invalid.");
+  }
+  return url;
+}
+
+function providerUrl(value: string): string {
+  return httpsUrl(value).toString();
+}
+
+function timestamp(value: string): number {
+  const parsed = Date.parse(value);
+  if (!Number.isSafeInteger(parsed)) throw unavailable();
+  return parsed;
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && Number.isSafeInteger(Date.parse(value));
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function string(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function unavailable(): Error {
+  return new Error("Temporary object storage is unavailable.");
+}

packages/mcp-remote/src/http.ts

@@ -1,14 +1,22 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { getHeapStatistics } from "node:v8";
-import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createRemoteJWKSet, jwtVerify, type JWTVerifyGetKey } from "jose";
 import { writeAuditRecord, type AuditChannel } from "./audit.js";
 import { createMcpServer } from "./mcp.js";
 import { PeriodRateLimitTransport } from "./period-rate-limit-transport.js";
+import { decideScopeAccess } from "./scope-enforcement.js";
+import {
+  ScopeAwareHttpTransport,
+  type ClaimAwareAuthInfo
+} from "./scope-aware-http-transport.js";
 import type { RemoteMcpService } from "./service.js";
-import { LOCAL_PRINCIPAL, type Principal, type RemoteMcpConfig } from "./types.js";
+import {
+  LOCAL_PRINCIPAL,
+  type AuthContext,
+  type AuthenticatedPrincipal,
+  type RemoteMcpConfig
+} from "./types.js";
 
 export interface HttpServerOptions {
   service: RemoteMcpService;
@@ -63,16 +71,16 @@ export function createRemoteMcpHttpServer(options: HttpServerOptions): Server {
         return;
       }
       if (req.method === "GET" && req.url?.startsWith("/download/")) {
-        const principal = await authenticate(req, res, options.config, jwks);
-        if (!principal) return;
-        handleDownload(options.service, req, res, principal);
+        const authenticated = await authenticate(req, res, options.config, jwks);
+        if (!authenticated) return;
+        handleDownload(options.service, req, res, authenticated, options.config);
         return;
       }
       if (req.method === "POST" && (req.url === "/mcp" || req.url === "/mcp-claude")) {
         const channel = req.url;
-        const principal = await authenticate(req, res, options.config, jwks);
-        if (!principal) return;
-        await handleMcpRequest(options.service, req, res, principal, channel);
+        const authenticated = await authenticate(req, res, options.config, jwks);
+        if (!authenticated) return;
+        await handleMcpRequest(options.service, req, res, authenticated, channel, options.config);
         return;
       }
       writeJson(res, 404, { error: "not-found" });
@@ -193,10 +201,16 @@ function handleDownload(
   service: RemoteMcpService,
   req: IncomingMessage,
   res: ServerResponse,
-  principal: Principal
+  authenticated: AuthenticatedPrincipal,
+  config: RemoteMcpConfig
 ): void {
-  let success = false;
+  const { principal, authContext } = authenticated;
+  let auditDeferredUntilSettlement = false;
   try {
+    if (!decideScopeAccess(authContext, config.requiredScopes).allowed) {
+      writeInsufficientScope(res, config);
+      return;
+    }
     const token = decodeURIComponent((req.url ?? "").slice("/download/".length));
     if (!/^[A-Za-z0-9_-]{43,}$/u.test(token)) {
       writeJson(res, 404, { error: "download-not-found" });
@@ -209,26 +223,31 @@ function handleDownload(
     }
     let settled = false;
     const cleanup = (): void => {
-      res.off("finish", finish);
-      res.off("close", abort);
+      res.off("finish", settleFromResponse);
+      res.off("close", settleFromResponse);
       res.off("error", abort);
     };
-    const finish = (): void => {
+    const settle = (deliveryCompleted: boolean): void => {
       if (settled) return;
       settled = true;
       cleanup();
-      if (res.writableFinished) reservation.finish();
-      else reservation.abort();
+      try {
+        if (deliveryCompleted) reservation.finish();
+        else reservation.abort();
+      } finally {
+        writeAuditRecord(principal, "/download", "download", deliveryCompleted);
+      }
+    };
+    const settleFromResponse = (): void => {
+      settle(res.writableFinished);
     };
     const abort = (): void => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reservation.abort();
+      settle(false);
     };
-    res.once("finish", finish);
-    res.once("close", abort);
+    res.once("finish", settleFromResponse);
+    res.once("close", settleFromResponse);
     res.once("error", abort);
+    auditDeferredUntilSettlement = true;
     try {
       res.writeHead(200, {
         "content-type": "application/octet-stream",
@@ -241,9 +260,10 @@ function handleDownload(
       abort();
       throw error;
     }
-    success = true;
   } finally {
-    writeAuditRecord(principal, "/download", "download", success);
+    if (!auditDeferredUntilSettlement) {
+      writeAuditRecord(principal, "/download", "download", false);
+    }
   }
 }
 
@@ -252,7 +272,7 @@ async function authenticate(
   res: ServerResponse,
   config: RemoteMcpConfig,
   jwks: JWTVerifyGetKey | undefined
-): Promise<Principal | undefined> {
+): Promise<AuthenticatedPrincipal | undefined> {
   const authorization = req.headers.authorization;
   if (config.supabaseUrl && jwks && authorization?.startsWith("Bearer ")) {
     try {
@@ -260,12 +280,21 @@ async function authenticate(
         issuer: `${config.supabaseUrl}/auth/v1`,
         audience: config.supabaseJwtAudience
       });
-      if (typeof payload.sub === "string" && payload.sub.length > 0) return payload.sub;
+      if (typeof payload.sub === "string" && payload.sub.length > 0) {
+        return {
+          principal: payload.sub,
+          authContext: authContextFromClaims(payload.client_id, payload.scope),
+          bearerToken: authorization.slice("Bearer ".length)
+        };
+      }
     } catch {
       // Authentication failures deliberately share one challenge without logging token or claims.
     }
   } else if (!config.supabaseUrl && authorization === `Bearer ${config.authToken}`) {
-    return LOCAL_PRINCIPAL;
+    return {
+      principal: LOCAL_PRINCIPAL,
+      authContext: authContextFromClaims(undefined, undefined)
+    };
   }
   const parameters = [`realm="${config.publicBaseUrl}"`];
   if (config.supabaseUrl) {
@@ -360,26 +389,70 @@ async function handleMcpRequest(
   service: RemoteMcpService,
   req: IncomingMessage,
   res: ServerResponse,
-  principal: Principal,
-  channel: Exclude<AuditChannel, "/download">
+  authenticated: AuthenticatedPrincipal,
+  channel: Exclude<AuditChannel, "/download">,
+  config: RemoteMcpConfig
 ): Promise<void> {
+  const { principal, authContext } = authenticated;
   req.headers.accept = req.headers.accept ?? "application/json, text/event-stream";
-  const authenticatedRequest: IncomingMessage & { auth?: AuthInfo } = req;
-  authenticatedRequest.auth = {
+  const transport = new ScopeAwareHttpTransport();
+  const authInfo: ClaimAwareAuthInfo = {
     token: req.headers.authorization!.slice("Bearer ".length),
-    clientId: "",
-    scopes: [],
-    extra: { principal }
+    ...(typeof authContext.clientId === "string" ? { clientId: authContext.clientId } : {}),
+    scopes: authContext.scopes === undefined ? [] : [...authContext.scopes],
+    extra: {
+      principal,
+      authContext,
+      rejectInsufficientScope: () => transport.rejectInsufficientScope()
+    }
   };
-  const mcp = createMcpServer(service, principal);
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-  const rateLimitedTransport = new PeriodRateLimitTransport(transport, service, channel);
+  const mcp = createMcpServer(service, principal, authenticated.bearerToken
+    ? Object.freeze({ bearerToken: authenticated.bearerToken })
+    : undefined);
+  const rateLimitedTransport = new PeriodRateLimitTransport(
+    transport,
+    service,
+    channel,
+    config.requiredScopes
+  );
   await mcp.connect(rateLimitedTransport);
   res.on("close", () => {
     void rateLimitedTransport.close();
     void mcp.close();
   });
-  await transport.handleRequest(authenticatedRequest, res);
+  await transport.handleRequest(
+    req,
+    res,
+    authInfo,
+    () => writeInsufficientScope(res, config)
+  );
+}
+
+function authContextFromClaims(clientId: unknown, scope: unknown): AuthContext {
+  return {
+    clientId,
+    scope,
+    scopes: typeof scope === "string"
+      ? new Set(scope.split(" ").filter((value) => value.length > 0))
+      : undefined
+  };
+}
+
+function writeInsufficientScope(res: ServerResponse, config: RemoteMcpConfig): void {
+  if (res.headersSent) return;
+  const parameters = [
+    `realm="${config.publicBaseUrl}"`,
+    ...(config.supabaseUrl
+      ? [`resource_metadata="${config.publicBaseUrl}/.well-known/oauth-protected-resource"`]
+      : []),
+    'error="insufficient_scope"',
+    ...(config.requiredScopes.length > 0
+      ? [`scope="${config.requiredScopes.join(" ")}"`]
+      : [])
+  ];
+  writeJson(res, 403, { error: "insufficient_scope" }, {
+    "WWW-Authenticate": `Bearer ${parameters.join(", ")}`
+  });
 }
 
 function writeJson(

packages/mcp-remote/src/index.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env tsx
 import { writeSync } from "node:fs";
 import { configFromEnv, portFromEnv } from "./config.js";
+import { WebappEphemeralObjectClient } from "./ephemeral-object-client.js";
 import { createRemoteMcpHttpServer } from "./http.js";
 import { installProcessLifecycle } from "./lifecycle.js";
 import { formatContainerMemoryObservation } from "./memory-observation.js";
 import { RemoteMcpService } from "./service.js";
+import type { EphemeralObjectClient, RemoteMcpConfig } from "./types.js";
 
 export { configFromEnv, portFromEnv } from "./config.js";
 export { createRemoteMcpHttpServer } from "./http.js";
@@ -17,11 +19,28 @@ export {
 } from "./service.js";
 export { SessionStore, randomToken, systemClock } from "./store.js";
 export { downloadDocumentUrl, isPrivateAddress } from "./download.js";
+export { WebappEphemeralObjectClient } from "./ephemeral-object-client.js";
 export type * from "./types.js";
 
+export function ephemeralObjectClientFromConfig(
+  config: RemoteMcpConfig,
+  fetchImpl: typeof fetch = fetch
+): EphemeralObjectClient | undefined {
+  if (config.supabaseUrl && !config.webappEphemeralObjectBaseUrl) {
+    throw new Error("Authenticated remote MCP requires temporary object storage.");
+  }
+  if (!config.supabaseUrl && config.webappEphemeralObjectBaseUrl) {
+    throw new Error("Temporary object storage requires authenticated remote MCP.");
+  }
+  return config.webappEphemeralObjectBaseUrl
+    ? new WebappEphemeralObjectClient(config.webappEphemeralObjectBaseUrl, fetchImpl)
+    : undefined;
+}
+
 function main(): void {
   const config = configFromEnv();
-  const service = new RemoteMcpService({ config });
+  const ephemeralObjects = ephemeralObjectClientFromConfig(config);
+  const service = new RemoteMcpService({ config, ephemeralObjects });
   const server = createRemoteMcpHttpServer({ service, config });
   const lifecycle = installProcessLifecycle({
     server,

packages/mcp-remote/src/mcp.ts

@@ -1,8 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DEFAULT_SESSION_IDLE_TTL_MS, DEFAULT_SESSION_TTL_MS } from "./config.js";
 import { documentToolInputSchemas } from "./mcp-schemas.js";
 import { UNKNOWN_TOOL_AUDIT_ACTION, type AuditAction } from "./audit-contract.js";
 import type { RemoteMcpService } from "./service.js";
-import { LOCAL_PRINCIPAL, type Principal } from "./types.js";
+import {
+  LOCAL_PRINCIPAL,
+  type EphemeralObjectRequestContext,
+  type Principal
+} from "./types.js";
 
 type ToolHint = "readOnlyHint" | "destructiveHint" | "idempotentHint" | "openWorldHint";
 export type RegisteredToolName = Exclude<AuditAction, "download" | typeof UNKNOWN_TOOL_AUDIT_ACTION>;
@@ -24,19 +29,19 @@ export const TOOL_HINT_JUSTIFICATIONS = {
     readOnlyHint: "Inspects active session bytes and returns an aggregate privacy-minimized snapshot without editing the document.",
     destructiveHint: "Leaves session bytes, rollback state, downloads, and source resources unchanged.",
     idempotentHint: "Reanalyzes the same active session bytes without changing the environment.",
-    openWorldHint: "Uses the local adapter and session store only and makes no external network request."
+    openWorldHint: "In object mode, performs network I/O only to the configured webapp issuer and owner-bound private storage object; it never accesses arbitrary external resources."
   },
   apply_edits: {
     readOnlyHint: "Changes the private session document and edit sequence and creates an expiring edited download.",
     destructiveHint: "Edits only a private working copy while preserving the supplied source and retaining a one-step rollback.",
     idempotentHint: "A repeated successful edit changes session state again and can advance edit and structure versions.",
-    openWorldHint: "Applies edits inside the existing private session and does not contact or modify an external host."
+    openWorldHint: "In object mode, performs read-and-write network I/O only through the configured webapp issuer and owner-bound private storage objects; it never accesses arbitrary external resources."
   },
   rollback: {
     readOnlyHint: "Replaces the private session document with its previous bytes, advances the edit sequence, and creates a download.",
     destructiveHint: "Changes only the private session copy and leaves the user's supplied source untouched.",
     idempotentHint: "Consumes a one-step rollback token on success, so repeating the same token fails instead of having no effect.",
-    openWorldHint: "Uses stored session and rollback bytes only and performs no external network operation."
+    openWorldHint: "In object mode, performs rollback network I/O only through the configured webapp issuer and owner-bound private storage objects; it never accesses arbitrary external resources."
   },
   close_document: {
     readOnlyHint: "Deletes the addressed private document session and its retained state when that owned session exists.",
@@ -54,9 +59,29 @@ export function isRegisteredToolName(value: unknown): value is RegisteredToolNam
   return typeof value === "string" && REGISTERED_TOOL_NAMES.has(value);
 }
 
+function formatSessionLifetime(durationMs: number): string {
+  if (durationMs % 3_600_000 === 0) {
+    const hours = durationMs / 3_600_000;
+    return `${hours} ${hours === 1 ? "hour" : "hours"}`;
+  }
+  if (durationMs % 60_000 === 0) {
+    const minutes = durationMs / 60_000;
+    return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+  }
+  const seconds = durationMs / 1_000;
+  return `${seconds} ${seconds === 1 ? "second" : "seconds"}`;
+}
+
+export function createOpenDocumentDescription(): string {
+  const idleLifetime = formatSessionLifetime(DEFAULT_SESSION_IDLE_TTL_MS);
+  const absoluteLifetime = formatSessionLifetime(DEFAULT_SESSION_TTL_MS);
+  return `Download an HWPX file from a provided file object or URL and create an editing session that expires after ${idleLifetime} of inactivity and always within ${absoluteLifetime} of opening.`;
+}
+
 export function createMcpServer(
   service: RemoteMcpService,
-  principal: Principal = LOCAL_PRINCIPAL
+  principal: Principal = LOCAL_PRINCIPAL,
+  requestContext?: EphemeralObjectRequestContext
 ): McpServer {
   const server = new McpServer({
     name: "hwpxkit-mcp-remote",
@@ -70,7 +95,7 @@ export function createMcpServer(
     "open_document",
     {
       title: "Open HWPX Document",
-      description: "Download an HWPX file from a provided file object or URL and create an editing session that expires after 30 minutes of inactivity and always within 1 hour of opening.",
+      description: createOpenDocumentDescription(),
       inputSchema: documentToolInputSchemas.open_document,
       annotations: {
         readOnlyHint: false,
@@ -89,7 +114,7 @@ export function createMcpServer(
       if (url !== undefined && file !== undefined) {
         throw new Error("Both a file and URL were provided; provide exactly one document source.");
       }
-      return toolResult(await service.openDocument({ url: url ?? file!.download_url }, principal));
+      return toolResult(await service.openDocument({ url: url ?? file!.download_url }, principal, requestContext));
     }
   );
 
@@ -106,7 +131,7 @@ export function createMcpServer(
         openWorldHint: false
       }
     },
-    async (input) => toolResult({ targets: service.listTargets(input, principal) })
+    async (input) => toolResult({ targets: service.listTargets(input, principal, requestContext) })
   );
 
   registerTool(
@@ -122,7 +147,7 @@ export function createMcpServer(
         openWorldHint: false
       }
     },
-    async (input) => toolResult(await service.analyzeDocument(input, principal))
+    async (input) => toolResult(await service.analyzeDocument(input, principal, requestContext))
   );
 
   registerTool(
@@ -138,7 +163,7 @@ export function createMcpServer(
         openWorldHint: false
       }
     },
-    async (input) => toolResult(await service.applyEdits(input, principal))
+    async (input) => toolResult(await service.applyEdits(input, principal, requestContext))
   );
 
   registerTool(
@@ -154,7 +179,7 @@ export function createMcpServer(
         openWorldHint: false
       }
     },
-    async (input) => toolResult(await service.rollback(input, principal))
+    async (input) => toolResult(await service.rollback(input, principal, requestContext))
   );
 
   registerTool(
@@ -170,7 +195,7 @@ export function createMcpServer(
         openWorldHint: false
       }
     },
-    async (input) => toolResult(await service.closeDocument(input, principal))
+    async (input) => toolResult(await service.closeDocument(input, principal, requestContext))
   );
 
   return server;

packages/mcp-remote/src/period-rate-limit-transport.ts

@@ -15,8 +15,9 @@ import {
   type AuditChannel
 } from "./audit.js";
 import { isRegisteredToolName, type RegisteredToolName } from "./mcp.js";
+import { decideScopeAccess } from "./scope-enforcement.js";
 import type { RemoteMcpService } from "./service.js";
-import type { Principal } from "./types.js";
+import type { AuthContext, Principal } from "./types.js";
 
 type PendingAudit = {
   principal: Principal;
@@ -31,7 +32,8 @@ export class PeriodRateLimitTransport implements Transport {
   constructor(
     private readonly inner: Transport,
     private readonly service: RemoteMcpService,
-    private readonly channel: Exclude<AuditChannel, "/download">
+    private readonly channel: Exclude<AuditChannel, "/download">,
+    private readonly requiredScopes: readonly string[]
   ) {}
 
   private readonly pendingAudits = new Map<JSONRPCRequest["id"], PendingAudit[]>();
@@ -75,6 +77,13 @@ export class PeriodRateLimitTransport implements Transport {
 
     const principal = transportPrincipal(extra);
     const action = auditAction(toolName(message));
+    const authContext = transportAuthContext(extra);
+    if (!decideScopeAccess(authContext, this.requiredScopes).allowed) {
+      this.service.recordToolCall(principal, false);
+      writeAuditRecord(principal, this.channel, action, false);
+      rejectInsufficientScope(extra);
+      return;
+    }
     const rejectWhenExceeded = action !== "close_document";
     try {
       this.service.recordToolCall(principal, rejectWhenExceeded);
@@ -94,6 +103,28 @@ export class PeriodRateLimitTransport implements Transport {
   }
 }
 
+function transportAuthContext(extra: MessageExtraInfo | undefined): AuthContext {
+  const authContext = extra?.authInfo?.extra?.authContext;
+  if (!isAuthContext(authContext)) {
+    throw new Error("Authenticated claims are unavailable at the MCP transport boundary.");
+  }
+  return authContext;
+}
+
+function isAuthContext(value: unknown): value is AuthContext {
+  return typeof value === "object" && value !== null &&
+    "clientId" in value && "scope" in value && "scopes" in value &&
+    (value.scopes === undefined || value.scopes instanceof Set);
+}
+
+function rejectInsufficientScope(extra: MessageExtraInfo | undefined): void {
+  const reject = extra?.authInfo?.extra?.rejectInsufficientScope;
+  if (typeof reject !== "function") {
+    throw new Error("Scope rejection is unavailable at the MCP transport boundary.");
+  }
+  reject();
+}
+
 function isToolCallRequest(message: JSONRPCMessage): message is JSONRPCRequest & { method: "tools/call" } {
   return "id" in message && "method" in message && message.method === "tools/call";
 }

packages/mcp-remote/src/scope-aware-http-transport.ts

@@ -0,0 +1,122 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import type {
+  Transport,
+  TransportSendOptions
+} from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage, MessageExtraInfo } from "@modelcontextprotocol/sdk/types.js";
+
+export type ClaimAwareAuthInfo = Omit<AuthInfo, "clientId"> & { clientId?: string };
+
+export class ScopeAwareHttpTransport implements Transport {
+  private readonly inner = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined
+  });
+  private scopeRejected = false;
+
+  get sessionId(): string | undefined {
+    return this.inner.sessionId;
+  }
+
+  set onclose(handler: (() => void) | undefined) {
+    this.inner.onclose = handler;
+  }
+
+  get onclose(): (() => void) | undefined {
+    return this.inner.onclose;
+  }
+
+  set onerror(handler: ((error: Error) => void) | undefined) {
+    this.inner.onerror = handler;
+  }
+
+  get onerror(): ((error: Error) => void) | undefined {
+    return this.inner.onerror;
+  }
+
+  set onmessage(
+    handler: (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined
+  ) {
+    this.inner.onmessage = handler;
+  }
+
+  get onmessage(): (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined {
+    return this.inner.onmessage;
+  }
+
+  async start(): Promise<void> {
+    await this.inner.start();
+  }
+
+  async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    await this.inner.send(message, options);
+  }
+
+  async close(): Promise<void> {
+    await this.inner.close();
+  }
+
+  rejectInsufficientScope(): void {
+    this.scopeRejected = true;
+  }
+
+  async handleRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    authInfo: ClaimAwareAuthInfo,
+    writeInsufficientScope: () => void
+  ): Promise<void> {
+    // The SDK type requires clientId even though verified session/static tokens have no such claim.
+    // Its runtime transport does not validate the shape; keep absence truthful at our boundary.
+    const response = await this.inner.handleRequest(toWebRequest(req), { authInfo: authInfo as AuthInfo });
+    if (this.scopeRejected) {
+      await response.body?.cancel().catch(() => {});
+      writeInsufficientScope();
+      return;
+    }
+    await writeWebResponse(res, response);
+  }
+}
+
+function toWebRequest(req: IncomingMessage): Request {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item);
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  }
+  const method = req.method ?? "GET";
+  const init: RequestInit & { duplex?: "half" } = { method, headers };
+  if (method !== "GET" && method !== "HEAD") {
+    init.body = Readable.toWeb(req) as unknown as BodyInit;
+    init.duplex = "half";
+  }
+  return new Request(new URL(req.url ?? "/", requestOrigin(req)), init);
+}
+
+function requestOrigin(req: IncomingMessage): string {
+  const forwardedProto = req.headers["x-forwarded-proto"];
+  const protocol = typeof forwardedProto === "string" && forwardedProto.split(",", 1)[0] === "https"
+    ? "https"
+    : "http";
+  const host = req.headers.host ?? "localhost";
+  return `${protocol}://${host}`;
+}
+
+async function writeWebResponse(res: ServerResponse, response: Response): Promise<void> {
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, name) => {
+    headers[name] = value;
+  });
+  res.writeHead(response.status, headers);
+  if (response.body === null) {
+    res.end();
+    return;
+  }
+  await pipeline(Readable.fromWeb(response.body as never), res);
+}

packages/mcp-remote/src/scope-enforcement.ts

@@ -0,0 +1,18 @@
+import type { AuthContext } from "./types.js";
+
+export interface ScopeDecision {
+  allowed: boolean;
+}
+
+export function decideScopeAccess(
+  authContext: AuthContext,
+  requiredScopes: readonly string[]
+): ScopeDecision {
+  if (authContext.scope !== undefined && typeof authContext.scope !== "string") {
+    return { allowed: false };
+  }
+  if (authContext.clientId === undefined) return { allowed: true };
+  if (requiredScopes.length === 0) return { allowed: true };
+  if (authContext.scopes === undefined) return { allowed: false };
+  return { allowed: requiredScopes.every((scope) => authContext.scopes!.has(scope)) };
+}

packages/mcp-remote/src/service.ts

@@ -26,6 +26,7 @@ import { listRevisionTargets, summarizeRevisionTargets, toPatchTarget, type Revi
 import { downloadDocumentUrl } from "#mcp-remote/download";
 import { deriveMaxConcurrentSessionsPerPrincipal } from "./config.js";
 import {
+  createDownloadBytes,
   AdmissionGuardError,
   randomToken,
   SessionStore,
@@ -37,6 +38,9 @@ import type {
   Clock,
   DocumentAnalysisSnapshot,
   DocumentSession,
+  EphemeralObjectClient,
+  EphemeralObjectReference,
+  EphemeralObjectRequestContext,
   PublicTarget,
   Principal,
   RemoteEdit,
@@ -52,6 +56,7 @@ export interface RemoteMcpServiceOptions {
   config: RemoteMcpConfig;
   store?: SessionStore;
   clock?: Clock;
+  ephemeralObjects?: EphemeralObjectClient;
 }
 
 export interface OpenDocumentResult {
@@ -173,6 +178,7 @@ export class RemoteMcpService {
   readonly store: SessionStore;
   private readonly adapter = new DirectXmlAdapter();
   private readonly clock: Clock;
+  private readonly objectOperationTails = new WeakMap<DocumentSession, Promise<void>>();
 
   private get inFlightSessionCount(): number {
     return this.store.getAccountingTotals().inFlightCount;
@@ -198,7 +204,8 @@ export class RemoteMcpService {
 
   async openDocument(
     input: { url: string },
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    requestContext: EphemeralObjectRequestContext = {}
   ): Promise<OpenDocumentResult> {
     this.assertInputBytesAllowed();
     const reservation = this.store.reserveSession(
@@ -212,7 +219,7 @@ export class RemoteMcpService {
         allowInsecureLocalhost: this.options.config.allowInsecureLocalhostDownloads
       });
       reservation.narrow(bytes.byteLength);
-      return await this.createReservedSession(bytes, principal, reservation);
+      return await this.createReservedSession(bytes, principal, reservation, requestContext);
     } finally {
       reservation.release();
     }
@@ -220,12 +227,13 @@ export class RemoteMcpService {
 
   async createSession(
     bytes: Buffer,
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    requestContext: EphemeralObjectRequestContext = {}
   ): Promise<OpenDocumentResult> {
     this.assertInputBytesAllowed(bytes);
     const reservation = this.store.reserveSession(principal, bytes.byteLength, this.sessionLimits());
     try {
-      return await this.createReservedSession(bytes, principal, reservation);
+      return await this.createReservedSession(bytes, principal, reservation, requestContext);
     } finally {
       reservation.release();
     }
@@ -234,7 +242,8 @@ export class RemoteMcpService {
   private async createReservedSession(
     bytes: Buffer,
     principal: Principal,
-    reservation: WorkReservation
+    reservation: WorkReservation,
+    requestContext: EphemeralObjectRequestContext
   ): Promise<OpenDocumentResult> {
     this.assertInputBytesAllowed(bytes);
     const operationReservation = this.store.reserveOperation(principal, this.sessionLimits());
@@ -271,21 +280,35 @@ export class RemoteMcpService {
     if (!validation.valid) {
       throw new Error(validation.errors[0]?.message ?? "inspect failed");
     }
+    let currentObject: EphemeralObjectReference | undefined;
+    if (this.options.ephemeralObjects) {
+      const stored = await this.options.ephemeralObjects.storeAndDownload(
+        bytes,
+        requiredBearerToken(requestContext)
+      );
+      if (stored.bytes !== bytes) bytes.fill(0);
+      bytes = stored.bytes;
+      currentObject = stored.ref;
+    }
     const targetIndex = buildRemoteTargetIndexFromSelections(selectRemoteTargetSelections(bytes));
+    const cachedPublicTargets = publicTargetsForBytes(bytes, targetIndex, 1);
     const openedAt = this.clock.now();
+    const absoluteExpiresAt = openedAt + this.options.config.sessionTtlMs;
     const session: DocumentSession = {
       docHandle: randomToken(),
       ownerPrincipal: principal,
-      bytes,
+      bytes: currentObject ? Buffer.alloc(0) : bytes,
+      ...(currentObject ? { currentObject } : {}),
       structureVersion: 1,
       editSeq: 0,
       targetIndex,
+      cachedPublicTargets,
       structuralEditCount: 0,
       rollbackEntries: new Map(),
       downloadArtifacts: new Map(),
       paragraphAnchors: injected.state,
       absoluteTtlMs: this.options.config.sessionTtlMs,
-      expiresAt: openedAt + this.options.config.sessionTtlMs,
+      expiresAt: Math.min(absoluteExpiresAt, currentObject?.retentionExpiresAt ?? absoluteExpiresAt),
       idleTtlMs: this.options.config.sessionIdleTtlMs,
       idleExpiresAt: openedAt + this.options.config.sessionIdleTtlMs
     };
@@ -294,6 +317,8 @@ export class RemoteMcpService {
     } catch (error) {
       session.bytes.fill(0);
       throw error;
+    } finally {
+      if (currentObject) bytes.fill(0);
     }
     return {
       docHandle: session.docHandle,
@@ -339,9 +364,17 @@ export class RemoteMcpService {
 
   listTargets(
     input: { docHandle: string; kind?: RemoteTargetKind; fillableOnly?: boolean },
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    _requestContext: EphemeralObjectRequestContext = {}
   ): PublicTarget[] {
     const session = this.requireSession(input.docHandle, principal);
+    if (session.currentObject) {
+      const cached = session.cachedPublicTargets ?? [];
+      return cached
+        .filter((target) => input.kind === undefined || target.kind === input.kind)
+        .filter((target) => !input.fillableOnly || target.fillable === true)
+        .map(copyPublicTarget);
+    }
     const ordinals = session.targetIndex
       .filter((entry) => input.kind === undefined || entry.kind === input.kind)
       .map((entry) => entry.ordinal);
@@ -358,12 +391,15 @@ export class RemoteMcpService {
 
   async analyzeDocument(
     input: { docHandle: string },
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    requestContext: EphemeralObjectRequestContext = {}
   ): Promise<DocumentAnalysisSnapshot> {
     const session = this.requireSessionLease(input.docHandle, principal);
     let operationReservation: WorkReservation | undefined;
+    let releaseObjectBytes: (() => void) | undefined;
     try {
       operationReservation = this.store.reserveOperation(principal, this.sessionLimits());
+      releaseObjectBytes = await this.hydrateObjectSession(session, requestContext);
       const inspect = await this.adapter.inspect(session.bytes);
       this.assertSessionActive(session);
       if (!inspect.inspectSuccess) {
@@ -376,6 +412,7 @@ export class RemoteMcpService {
         )
       );
     } finally {
+      releaseObjectBytes?.();
       operationReservation?.release();
       this.store.releaseSession(session);
     }
@@ -383,13 +420,16 @@ export class RemoteMcpService {
 
   async applyEdits(
     input: ApplyEditsInput,
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    requestContext: EphemeralObjectRequestContext = {}
   ): Promise<ApplyEditsResult> {
     const session = this.requireSessionLease(input.docHandle, principal);
     let operationReservation: WorkReservation | undefined;
     let unownedRollbackBytes: Buffer | undefined;
+    let releaseObjectBytes: (() => void) | undefined;
     try {
     operationReservation = this.store.reserveOperation(principal, this.sessionLimits());
+    releaseObjectBytes = await this.hydrateObjectSession(session, requestContext);
     if (input.edits.length > this.options.config.maxEditsPerBatch) {
       return {
         success: false,
@@ -557,7 +597,7 @@ export class RemoteMcpService {
       return { ...base, operation: "editEquationScript", latex: edit.value! };
     });
 
-    unownedRollbackBytes = structural ? Buffer.from(session.bytes) : undefined;
+    unownedRollbackBytes = structural && !session.currentObject ? Buffer.from(session.bytes) : undefined;
     const patch = await this.adapter.patch(session.bytes, operations, {
       paragraphAnchors: session.paragraphAnchors,
       retainPackageForExport: true
@@ -585,6 +625,67 @@ export class RemoteMcpService {
         : base;
     }
 
+    if (session.currentObject && this.options.ephemeralObjects) {
+      const previousObject = session.currentObject;
+      const bearerToken = requiredBearerToken(requestContext);
+      const exportBytes = createDownloadBytes(session, patch.output, patch.packageForExport);
+      let storedInternal;
+      let storedResult;
+      try {
+        storedInternal = await this.options.ephemeralObjects.storeAndDownload(patch.output, bearerToken);
+        storedResult = await this.options.ephemeralObjects.storeAndDownload(exportBytes, bearerToken);
+      } finally {
+        exportBytes.fill(0);
+      }
+      storedResult.bytes.fill(0);
+      if (storedInternal.bytes !== patch.output) patch.output.fill(0);
+      const nextBytes = storedInternal.bytes;
+      const nextStructureVersion = session.structureVersion + (structural ? 1 : 0);
+      const nextTargetIndex = buildRemoteTargetIndexFromSelections(selectRemoteTargetSelections(nextBytes));
+      const nextPublicTargets = publicTargetsForBytes(nextBytes, nextTargetIndex, nextStructureVersion);
+      const rollbackToken = randomToken();
+      this.store.addRollback(session, {
+        token: rollbackToken,
+        editSeq: session.editSeq + 1,
+        inverse: patch.inverse ?? [],
+        objectBefore: previousObject,
+        targetIndexes: resolved.edits.map((edit) => edit.index),
+        expiresAt: Math.min(session.expiresAt, previousObject.retentionExpiresAt)
+      }, this.options.config.maxRollbackEntriesPerSession);
+
+      replaceSessionBytes(session, nextBytes);
+      session.currentObject = storedInternal.ref;
+      session.editSeq += 1;
+      session.structuralEditCount += structuralEdits.length;
+      session.structureVersion = nextStructureVersion;
+      session.targetIndex = nextTargetIndex;
+      session.cachedPublicTargets = nextPublicTargets;
+
+      const result: ApplyEditsResult = {
+        ...base,
+        downloadUrl: storedResult.downloadUrl,
+        downloadExpiresAt: new Date(storedResult.downloadExpiresAt).toISOString(),
+        rollbackToken,
+        ...(resolved.warnings.length > 0 ? { warnings: resolved.warnings } : {})
+      };
+      if (structural) {
+        result.structureChanged = true;
+        result.structureVersion = session.structureVersion;
+        const addParagraphResult = patch.applied.find(
+          (operation) => operation.operation === "addParagraph"
+        );
+        if (addParagraphResult?.newParagraphIndex !== undefined) {
+          result.newParagraphIndex = addParagraphResult.newParagraphIndex;
+        }
+      } else {
+        result.updatedTargets = this.publicTargetsForIndexes(
+          session,
+          resolved.edits.map((edit) => edit.index)
+        );
+      }
+      return result;
+    }
+
     replaceSessionBytes(session, patch.output);
     session.editSeq += 1;
     session.structuralEditCount += structuralEdits.length;
@@ -636,6 +737,7 @@ export class RemoteMcpService {
       try {
         unownedRollbackBytes?.fill(0);
       } finally {
+        releaseObjectBytes?.();
         operationReservation?.release();
         this.store.releaseSession(session);
       }
@@ -644,12 +746,16 @@ export class RemoteMcpService {
 
   async rollback(
     input: { docHandle: string; rollbackToken: string },
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    requestContext: EphemeralObjectRequestContext = {}
   ): Promise<RollbackResult> {
     const session = this.requireSessionLease(input.docHandle, principal);
     let operationReservation: WorkReservation | undefined;
+    let releaseObjectBytes: (() => void) | undefined;
+    let rollbackObjectBytes: Buffer | undefined;
     try {
     operationReservation = this.store.reserveOperation(principal, this.sessionLimits());
+    releaseObjectBytes = await this.hydrateObjectSession(session, requestContext);
     const rollback = this.store.getRollback(session, input.rollbackToken, principal);
     if (!rollback) {
       return { success: false, code: "rollback-not-found", message: "Rollback token was not found or has expired; call rollback with the rollbackToken returned by the edit you want to undo." };
@@ -670,10 +776,17 @@ export class RemoteMcpService {
       };
     }
 
-    let rollbackPackage = rollback.bytesBefore ? readHwpxPackage(rollback.bytesBefore) : undefined;
+    if (rollback.objectBefore && this.options.ephemeralObjects) {
+      rollbackObjectBytes = await this.options.ephemeralObjects.download(
+        rollback.objectBefore,
+        requiredBearerToken(requestContext)
+      );
+    }
+    const rollbackBytes = rollbackObjectBytes ?? rollback.bytesBefore;
+    let rollbackPackage = rollbackBytes ? readHwpxPackage(rollbackBytes) : undefined;
     if (rollbackPackage) syncActiveParagraphAnchorsInPackage(rollbackPackage, session.paragraphAnchors);
-    const patch = rollback.bytesBefore
-      ? { success: true as const, output: Buffer.from(rollback.bytesBefore), applied: [], errors: [], packageForExport: rollbackPackage }
+    const patch = rollbackBytes
+      ? { success: true as const, output: Buffer.from(rollbackBytes), applied: [], errors: [], packageForExport: rollbackPackage }
       : await this.adapter.patch(session.bytes, rollback.inverse, {
           paragraphAnchors: session.paragraphAnchors,
           retainPackageForExport: true
@@ -688,6 +801,48 @@ export class RemoteMcpService {
       return base;
     }
 
+    if (session.currentObject && this.options.ephemeralObjects) {
+      const bearerToken = requiredBearerToken(requestContext);
+      const exportBytes = createDownloadBytes(session, patch.output, patch.packageForExport);
+      let storedInternal;
+      let storedResult;
+      try {
+        storedInternal = await this.options.ephemeralObjects.storeAndDownload(patch.output, bearerToken);
+        storedResult = await this.options.ephemeralObjects.storeAndDownload(exportBytes, bearerToken);
+      } finally {
+        exportBytes.fill(0);
+      }
+      storedResult.bytes.fill(0);
+      if (storedInternal.bytes !== patch.output) patch.output.fill(0);
+      const nextBytes = storedInternal.bytes;
+      const structural = structuralEditCount > 0;
+      const nextStructureVersion = session.structureVersion + (structural ? 1 : 0);
+      const nextTargetIndex = buildRemoteTargetIndexFromSelections(selectRemoteTargetSelections(nextBytes));
+      const nextPublicTargets = publicTargetsForBytes(nextBytes, nextTargetIndex, nextStructureVersion);
+
+      this.store.deleteRollback(session, input.rollbackToken, principal);
+      replaceSessionBytes(session, nextBytes);
+      session.currentObject = storedInternal.ref;
+      session.editSeq += 1;
+      session.structuralEditCount += structuralEditCount;
+      session.structureVersion = nextStructureVersion;
+      session.targetIndex = nextTargetIndex;
+      session.cachedPublicTargets = nextPublicTargets;
+
+      const result: RollbackResult = {
+        ...base,
+        downloadUrl: storedResult.downloadUrl,
+        downloadExpiresAt: new Date(storedResult.downloadExpiresAt).toISOString()
+      };
+      if (structural) {
+        result.structureChanged = true;
+        result.structureVersion = session.structureVersion;
+      } else {
+        result.updatedTargets = this.publicTargetsForIndexes(session, rollback.targetIndexes);
+      }
+      return result;
+    }
+
     replaceSessionBytes(session, patch.output);
     session.editSeq += 1;
     session.structuralEditCount += structuralEditCount;
@@ -716,6 +871,8 @@ export class RemoteMcpService {
     }
     return result;
     } finally {
+      rollbackObjectBytes?.fill(0);
+      releaseObjectBytes?.();
       operationReservation?.release();
       this.store.releaseSession(session);
     }
@@ -732,7 +889,8 @@ export class RemoteMcpService {
 
   async closeDocument(
     input: { docHandle: string },
-    principal: Principal = LOCAL_PRINCIPAL
+    principal: Principal = LOCAL_PRINCIPAL,
+    _requestContext: EphemeralObjectRequestContext = {}
   ): Promise<CloseDocumentResult> {
     return { closed: await this.store.deleteSession(input.docHandle, principal) };
   }
@@ -761,6 +919,53 @@ export class RemoteMcpService {
     return session;
   }
 
+  private async hydrateObjectSession(
+    session: DocumentSession,
+    requestContext: EphemeralObjectRequestContext
+  ): Promise<(() => void) | undefined> {
+    if (!session.currentObject) return undefined;
+    if (!this.options.ephemeralObjects) throw new Error("Temporary object storage is unavailable.");
+    const previous = this.objectOperationTails.get(session) ?? Promise.resolve();
+    let unlock!: () => void;
+    const gate = new Promise<void>((resolve) => { unlock = resolve; });
+    const tail = previous.catch(() => undefined).then(() => gate);
+    this.objectOperationTails.set(session, tail);
+    await previous.catch(() => undefined);
+    if (!this.store.isSessionActive(session)) {
+      unlock();
+      throw sessionNotFoundError();
+    }
+    let hydrated: Buffer;
+    try {
+      hydrated = await this.options.ephemeralObjects.download(
+        session.currentObject,
+        requiredBearerToken(requestContext)
+      );
+    } catch (error) {
+      unlock();
+      if (this.objectOperationTails.get(session) === tail) this.objectOperationTails.delete(session);
+      throw error;
+    }
+    if (hydrated.byteLength !== session.currentObject.byteLength) {
+      hydrated.fill(0);
+      unlock();
+      if (this.objectOperationTails.get(session) === tail) this.objectOperationTails.delete(session);
+      throw new Error("Temporary object storage is unavailable.");
+    }
+    session.bytes.fill(0);
+    session.bytes = hydrated;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      session.bytes.fill(0);
+      session.bytes = Buffer.alloc(0);
+      if (hydrated !== session.bytes) hydrated.fill(0);
+      unlock();
+      if (this.objectOperationTails.get(session) === tail) this.objectOperationTails.delete(session);
+    };
+  }
+
   private assertSessionActive(session: DocumentSession): void {
     if (!this.store.isSessionActive(session)) throw sessionNotFoundError();
   }
@@ -1240,6 +1445,11 @@ export class RemoteMcpService {
 
   private async refreshTargets(session: DocumentSession): Promise<void> {
     session.targetIndex = buildRemoteTargetIndexFromSelections(selectRemoteTargetSelections(session.bytes));
+    session.cachedPublicTargets = publicTargetsForBytes(
+      session.bytes,
+      session.targetIndex,
+      session.structureVersion
+    );
   }
 
   private publicTargetsForIndexes(session: DocumentSession, indexes: number[]): PublicTarget[] {
@@ -1575,6 +1785,27 @@ function summariesForOrdinals(
     .map((summary, position) => ({ ...summary, index: ordinals[position]! }));
 }
 
+function publicTargetsForBytes(
+  bytes: Buffer,
+  targetIndex: readonly RemoteTargetIndexEntry[],
+  structureVersion: number
+): PublicTarget[] {
+  const ordinals = targetIndex.map((entry) => entry.ordinal);
+  return summariesForOrdinals(materializeRemoteTargets(bytes, ordinals), ordinals, bytes)
+    .map((summary) => publicTarget(summary, structureVersion));
+}
+
+function copyPublicTarget(target: PublicTarget): PublicTarget {
+  return structuredClone(target);
+}
+
+function requiredBearerToken(context: EphemeralObjectRequestContext): string {
+  if (typeof context.bearerToken !== "string" || context.bearerToken.length === 0) {
+    throw new Error("Temporary object access requires an authenticated user request.");
+  }
+  return context.bearerToken;
+}
+
 function publicTarget(summary: RevisionTargetSummary, structureVersion: number): PublicTarget {
   const paragraphLocatorAmbiguous =
     summary.kind === "paragraph" &&

packages/mcp-remote/src/stable-handle.ts

@@ -0,0 +1,180 @@
+import { sha256Hex } from "@hwpxkit/core-ts/sha256";
+import { Buffer } from "node:buffer";
+
+const HANDLE_DOMAIN = "hwpxkit.stable-target-handle.v1";
+const HANDLE_PREFIX = "sh1_";
+
+/**
+ * A 128-bit truncation keeps handles compact while retaining a conservative
+ * birthday bound. The bound and the measured candidate population are recorded
+ * by the m414 report; this constant is the single implementation knob.
+ */
+export const STABLE_HANDLE_TRUNCATED_BITS = 128;
+
+export interface StableHandlePathSegment {
+  /** Structural element role, not document text (for example, "table" or "row"). */
+  readonly kind: string;
+  /** Zero-based ordinal among structural siblings of the same role. */
+  readonly ordinal: number;
+}
+
+declare const fullAncestorPathBrand: unique symbol;
+
+/**
+ * Complete document-root-to-target structural path. It begins with document:0,
+ * then the source part, and callers must not omit any intermediate ancestor.
+ */
+export type FullAncestorPath = readonly StableHandlePathSegment[] & {
+  readonly [fullAncestorPathBrand]: true;
+};
+
+export interface StableHandleCandidate<T> {
+  readonly fullAncestorPath: FullAncestorPath;
+  readonly value: T;
+}
+
+export type StableHandleResolutionErrorCode =
+  | "stable-handle-no-match"
+  | "stable-handle-multiple-matches";
+
+export class StableHandleResolutionError extends Error {
+  readonly code: StableHandleResolutionErrorCode;
+
+  constructor(code: StableHandleResolutionErrorCode) {
+    super(
+      code === "stable-handle-no-match"
+        ? "Stable handle did not resolve to exactly one target."
+        : "Stable handle resolved to more than one target."
+    );
+    this.name = "StableHandleResolutionError";
+    this.code = code;
+  }
+}
+
+export interface StableHandleInput {
+  /** Exact document bytes supplied by the current request. */
+  readonly documentBytes: Uint8Array;
+  readonly structureVersion: number;
+  readonly fullAncestorPath: FullAncestorPath;
+}
+
+export interface ResolveStableHandleInput<T> {
+  /** Exact document bytes supplied by the current request. */
+  readonly documentBytes: Uint8Array;
+  readonly structureVersion: number;
+  readonly handle: string;
+  readonly candidates: readonly StableHandleCandidate<T>[];
+}
+
+/**
+ * Constructs a canonical root-to-target path. The opaque handle never exposes
+ * these segments; they are inputs only to unsigned digest recomputation.
+ */
+export function createFullAncestorPath(
+  segments: readonly StableHandlePathSegment[]
+): FullAncestorPath {
+  if (
+    segments.length < 3 ||
+    segments[0]?.kind !== "document" ||
+    segments[0].ordinal !== 0 ||
+    segments[1]?.kind !== "part"
+  ) {
+    throw new TypeError(
+      "A full ancestor path must start with document:0 and a source part, then end at the target."
+    );
+  }
+
+  const copy = segments.map((segment) => {
+    if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u.test(segment.kind)) {
+      throw new TypeError("A path segment kind must use the canonical structural-token form.");
+    }
+    if (!Number.isSafeInteger(segment.ordinal) || segment.ordinal < 0) {
+      throw new TypeError("A path segment ordinal must be a non-negative safe integer.");
+    }
+    return Object.freeze({ kind: segment.kind, ordinal: segment.ordinal });
+  });
+
+  return Object.freeze(copy) as FullAncestorPath;
+}
+
+/**
+ * Computes an opaque, unsigned handle. There is deliberately no key or secret:
+ * the receiver resolves by recomputing candidates from the request bytes.
+ */
+export function createStableTargetHandle(input: StableHandleInput): string {
+  validateStructureVersion(input.structureVersion);
+  const contentSha = hexToBytes(sha256Hex(input.documentBytes));
+  const preimage = encodeFrames([
+    utf8(HANDLE_DOMAIN),
+    contentSha,
+    utf8(input.structureVersion.toString(10)),
+    utf8(input.fullAncestorPath.length.toString(10)),
+    ...input.fullAncestorPath.flatMap((segment) => [
+      utf8(segment.kind),
+      utf8(segment.ordinal.toString(10))
+    ])
+  ]);
+  const digestHex = sha256Hex(preimage);
+  const truncated = hexToBytes(digestHex).subarray(0, STABLE_HANDLE_TRUNCATED_BITS / 8);
+  return `${HANDLE_PREFIX}${Buffer.from(truncated).toString("base64url")}`;
+}
+
+/**
+ * Recomputes every candidate and succeeds only for exactly one match. In
+ * particular, it never selects the first candidate when paths or truncated
+ * digests collide.
+ */
+export function resolveStableTargetHandle<T>(input: ResolveStableHandleInput<T>): T {
+  validateStructureVersion(input.structureVersion);
+  const matches: T[] = [];
+
+  for (const candidate of input.candidates) {
+    const recomputed = createStableTargetHandle({
+      documentBytes: input.documentBytes,
+      structureVersion: input.structureVersion,
+      fullAncestorPath: candidate.fullAncestorPath
+    });
+    if (recomputed === input.handle) matches.push(candidate.value);
+  }
+
+  if (matches.length === 0) {
+    throw new StableHandleResolutionError("stable-handle-no-match");
+  }
+  if (matches.length !== 1) {
+    throw new StableHandleResolutionError("stable-handle-multiple-matches");
+  }
+  return matches[0] as T;
+}
+
+function validateStructureVersion(structureVersion: number): void {
+  if (!Number.isSafeInteger(structureVersion) || structureVersion <= 0) {
+    throw new TypeError("structureVersion must be a positive safe integer.");
+  }
+}
+
+function utf8(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}
+
+function hexToBytes(value: string): Uint8Array {
+  const result = new Uint8Array(value.length / 2);
+  for (let index = 0; index < result.length; index += 1) {
+    result[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return result;
+}
+
+/** Each field is independently length-framed, avoiding concatenation ambiguity. */
+function encodeFrames(fields: readonly Uint8Array[]): Uint8Array {
+  const byteLength = fields.reduce((total, field) => total + 4 + field.byteLength, 0);
+  const output = new Uint8Array(byteLength);
+  const view = new DataView(output.buffer);
+  let offset = 0;
+  for (const field of fields) {
+    view.setUint32(offset, field.byteLength, false);
+    offset += 4;
+    output.set(field, offset);
+    offset += field.byteLength;
+  }
+  return output;
+}

packages/mcp-remote/src/store.ts

@@ -244,9 +244,7 @@ export class SessionStore {
     if (this.downloads.has(token) || session.downloadArtifacts.has(token)) {
       throw new Error("Download token collision; retry the edit to create a new download.");
     }
-    const exportPackage = packageForExport ?? readHwpxPackage(bytes);
-    stripParagraphAnchorsInPackage(exportPackage, session.paragraphAnchors);
-    const exportBytes = writeHwpxPackage(exportPackage);
+    const exportBytes = createDownloadBytes(session, bytes, packageForExport);
     if (session.downloadArtifacts.size >= maxArtifacts) {
       const oldestToken = session.downloadArtifacts.keys().next().value;
       if (oldestToken !== undefined) {
@@ -467,6 +465,16 @@ export function retainedBytesForSession(session: DocumentSession): number {
   return bytes;
 }
 
+export function createDownloadBytes(
+  session: DocumentSession,
+  bytes: Buffer,
+  packageForExport?: HwpxZipPackage
+): Buffer {
+  const exportPackage = packageForExport ?? readHwpxPackage(bytes);
+  stripParagraphAnchorsInPackage(exportPackage, session.paragraphAnchors);
+  return writeHwpxPackage(exportPackage);
+}
+
 function wipeDownloadArtifact(artifact: DownloadArtifact): void {
   artifact.bytes.fill(0);
   artifact.bytes = Buffer.alloc(0);

packages/mcp-remote/src/test-rate-limit-config.ts

@@ -6,6 +6,7 @@ const resolvedConfig = configFromEnv({
 });
 
 export const TEST_RATE_LIMIT_CONFIG = Object.freeze({
+  requiredScopes: resolvedConfig.requiredScopes,
   rateLimitWindowMs: resolvedConfig.rateLimitWindowMs,
   rateLimitMaxCalls: resolvedConfig.rateLimitMaxCalls
 });

packages/mcp-remote/src/types.ts

@@ -39,6 +39,40 @@ export interface Clock {
 
 export type Principal = string;
 
+export interface AuthContext {
+  clientId: unknown | undefined;
+  scope: unknown | undefined;
+  scopes: ReadonlySet<string> | undefined;
+}
+
+export interface AuthenticatedPrincipal {
+  principal: Principal;
+  authContext: AuthContext;
+  bearerToken?: string;
+}
+
+export type EphemeralObjectRequestContext = Readonly<{
+  bearerToken?: string;
+}>;
+
+export type EphemeralObjectReference = Readonly<{
+  objectId: string;
+  byteLength: number;
+  retentionExpiresAt: number;
+}>;
+
+export type StoredEphemeralObject = Readonly<{
+  ref: EphemeralObjectReference;
+  downloadUrl: string;
+  downloadExpiresAt: number;
+  bytes: Buffer;
+}>;
+
+export interface EphemeralObjectClient {
+  storeAndDownload(bytes: Buffer, bearerToken: string): Promise<StoredEphemeralObject>;
+  download(ref: EphemeralObjectReference, bearerToken: string): Promise<Buffer>;
+}
+
 // Non-OAuth deployments intentionally collapse every authenticated request to
 // one principal while still exercising the same ownership checks.
 export const LOCAL_PRINCIPAL: Principal = "hwpxkit:local-principal";
@@ -56,6 +90,7 @@ export interface RollbackEntry {
   editSeq: number;
   inverse: DirectXmlPatchOperation[];
   bytesBefore?: Buffer;
+  objectBefore?: EphemeralObjectReference;
   targetIndexes: number[];
   expiresAt: number;
 }
@@ -64,9 +99,11 @@ export interface DocumentSession {
   docHandle: string;
   ownerPrincipal: Principal;
   bytes: Buffer;
+  currentObject?: EphemeralObjectReference;
   structureVersion: number;
   editSeq: number;
   targetIndex: RemoteTargetIndexEntry[];
+  cachedPublicTargets?: PublicTarget[];
   structuralEditCount: number;
   rollbackEntries: Map<string, RollbackEntry>;
   downloadArtifacts: Map<string, DownloadArtifact>;
@@ -140,6 +177,7 @@ export interface PublicTarget {
 export interface RemoteMcpConfig {
   authToken: string;
   publicBaseUrl: string;
+  requiredScopes: readonly string[];
   sessionTtlMs: number;
   sessionIdleTtlMs: number;
   maxFileBytes: number;
@@ -158,6 +196,7 @@ export interface RemoteMcpConfig {
   supabaseUrl?: string;
   supabasePublishableKey?: string;
   supabaseJwtAudience?: string;
+  webappEphemeralObjectBaseUrl?: string;
   allowInsecureLocalhostDownloads?: boolean;
   serviceVersion?: string;
   statusAllowedOrigin?: string;
@@ -168,6 +207,7 @@ export interface RemoteMcpEnv {
   MEMORY?: string;
   MCP_AUTH_TOKEN?: string;
   PUBLIC_BASE_URL?: string;
+  MCP_REQUIRED_SCOPES?: string;
   OPENAI_APPS_CHALLENGE?: string;
   SESSION_TTL_MS?: string;
   SESSION_IDLE_TTL_MS?: string;
@@ -186,6 +226,7 @@ export interface RemoteMcpEnv {
   SUPABASE_URL?: string;
   SUPABASE_PUBLISHABLE_KEY?: string;
   SUPABASE_JWT_AUDIENCE?: string;
+  WEBAPP_EPHEMERAL_OBJECT_BASE_URL?: string;
   SERVICE_VERSION?: string;
   STATUS_ALLOWED_ORIGIN?: string;
 }