@ethisyscore/extension-runtime 1.136.0 → 1.138.0

package/README.md

@@ -13,8 +13,8 @@ Built on top of `@ethisyscore/protocol` (canonical bridge / manifest / SDUI / ca
 | ----- | --- | ------- |
 | `@ethisyscore/extension-runtime` | Root re-exports | Stable consumer-facing types and helpers. |
 | `@ethisyscore/extension-runtime/host` | Host integration | `WorkerRemoteDomTransport`, declarative interpreter, semantic component registry, offscreen-canvas helpers. |
-| `@ethisyscore/extension-runtime/plugin` | Plugin side | `ExtensionRuntimeProvider`, `useMcpResource`, `useMcpTool`, transport abstraction. |
-| `@ethisyscore/extension-runtime/mock-host` | Local dev | `DeclarativeMockHost` and the `mock-host` CLI entry. |
+| `@ethisyscore/extension-runtime/plugin` | Plugin side | `ExtensionRuntimeProvider`, `useMcpResource`, `useMcpTool`, transport abstraction, `uploadFileToPluginStorage` (browser file → the app's own plugin storage via the `uploadToStorage` request kind). |
+| `@ethisyscore/extension-runtime/mock-host` | Local dev | `DeclarativeMockHost`, `InMemoryMcpTransport` (its `uploadToStorage` writes to an in-memory `MockPluginStorage`) and the `mock-host` CLI entry. |
 
 The `mock-host` bin (`npx mock-host <dir>`) is shipped — boots a Vite dev page that mounts the declarative interpreter against a directory of SDUI JSON resources. Run `--render-mode remote-runtime <bundle>` for the Contract B variant.
 

package/dist/MockPluginStorage-DF3DL1dI.d.ts

@@ -0,0 +1,59 @@
+import { g as UploadToStorageMeta, h as UploadToStorageResult } from './bridge-envelopes-BcKu-nQm.js';
+
+/** A file the mock host stored for an `uploadToStorage` call. */
+interface MockStoredFile {
+    readonly path: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+/** Optional per-user request rate limit for {@link MockPluginStorage}, mirroring the kernel route's 429. */
+interface MockPluginStorageRateLimit {
+    /** Requests allowed per window. The kernel default is 60. */
+    readonly maxRequests: number;
+    /** Window length in seconds. Defaults to 60, the kernel default. */
+    readonly windowSeconds?: number;
+}
+/** Options for {@link MockPluginStorage}. Everything is off by default. */
+interface MockPluginStorageOptions {
+    /** Refuse uploads past this rate with 429 `rate_limited`. Off when omitted. */
+    readonly rateLimit?: MockPluginStorageRateLimit;
+    /** Clock in epoch milliseconds, for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * In-memory stand-in for an app's plugin storage, answering the `uploadToStorage` request kind for
+ * `dev:mock` and tests.
+ *
+ * It behaves like the kernel route where a plugin can observe the difference:
+ * - the prefix is validated with the same rules (an invalid one rejects with status 400);
+ * - the file type is checked against the same allow-list (415), and the CANONICAL type is stored;
+ * - a body over 30 MB rejects with 413;
+ * - the path is server-chosen, `{prefix}/{32 hex}{ext}` with the kernel's extension rule, so two
+ *   uploads never share a path.
+ *
+ * - with `rateLimit` set, a request over the rate rejects with 429 and `retryAfterSeconds` (off by
+ *   default; a fixed window like the kernel's, counting every request, accepted or not).
+ *
+ * It does not model quota (507), the storage lock or upload slots (503), or the deadline (408).
+ */
+declare class MockPluginStorage {
+    private readonly files;
+    private readonly rateLimit?;
+    private readonly now;
+    private windowStartMs;
+    private windowCount;
+    constructor(options?: MockPluginStorageOptions);
+    /** Store `buffer` under a new path below `meta.pathPrefix`. */
+    store(meta: UploadToStorageMeta, buffer: ArrayBuffer): UploadToStorageResult;
+    /** The kernel refuses before the handler runs, so this is checked before anything else. */
+    private enforceRateLimit;
+    /** The stored file at `path`, or `undefined`. */
+    get(path: string): MockStoredFile | undefined;
+    /** Every stored file, in upload order. */
+    list(): readonly MockStoredFile[];
+    /** Forget every stored file. */
+    clear(): void;
+}
+
+export { MockPluginStorage as M, type MockPluginStorageOptions as a, type MockPluginStorageRateLimit as b, type MockStoredFile as c };

package/dist/MockPluginStorage-QKfz8CMt.d.cts

@@ -0,0 +1,59 @@
+import { g as UploadToStorageMeta, h as UploadToStorageResult } from './bridge-envelopes-BcKu-nQm.cjs';
+
+/** A file the mock host stored for an `uploadToStorage` call. */
+interface MockStoredFile {
+    readonly path: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+/** Optional per-user request rate limit for {@link MockPluginStorage}, mirroring the kernel route's 429. */
+interface MockPluginStorageRateLimit {
+    /** Requests allowed per window. The kernel default is 60. */
+    readonly maxRequests: number;
+    /** Window length in seconds. Defaults to 60, the kernel default. */
+    readonly windowSeconds?: number;
+}
+/** Options for {@link MockPluginStorage}. Everything is off by default. */
+interface MockPluginStorageOptions {
+    /** Refuse uploads past this rate with 429 `rate_limited`. Off when omitted. */
+    readonly rateLimit?: MockPluginStorageRateLimit;
+    /** Clock in epoch milliseconds, for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * In-memory stand-in for an app's plugin storage, answering the `uploadToStorage` request kind for
+ * `dev:mock` and tests.
+ *
+ * It behaves like the kernel route where a plugin can observe the difference:
+ * - the prefix is validated with the same rules (an invalid one rejects with status 400);
+ * - the file type is checked against the same allow-list (415), and the CANONICAL type is stored;
+ * - a body over 30 MB rejects with 413;
+ * - the path is server-chosen, `{prefix}/{32 hex}{ext}` with the kernel's extension rule, so two
+ *   uploads never share a path.
+ *
+ * - with `rateLimit` set, a request over the rate rejects with 429 and `retryAfterSeconds` (off by
+ *   default; a fixed window like the kernel's, counting every request, accepted or not).
+ *
+ * It does not model quota (507), the storage lock or upload slots (503), or the deadline (408).
+ */
+declare class MockPluginStorage {
+    private readonly files;
+    private readonly rateLimit?;
+    private readonly now;
+    private windowStartMs;
+    private windowCount;
+    constructor(options?: MockPluginStorageOptions);
+    /** Store `buffer` under a new path below `meta.pathPrefix`. */
+    store(meta: UploadToStorageMeta, buffer: ArrayBuffer): UploadToStorageResult;
+    /** The kernel refuses before the handler runs, so this is checked before anything else. */
+    private enforceRateLimit;
+    /** The stored file at `path`, or `undefined`. */
+    get(path: string): MockStoredFile | undefined;
+    /** Every stored file, in upload order. */
+    list(): readonly MockStoredFile[];
+    /** Forget every stored file. */
+    clear(): void;
+}
+
+export { MockPluginStorage as M, type MockPluginStorageOptions as a, type MockPluginStorageRateLimit as b, type MockStoredFile as c };

package/dist/{bridge-client-RJOl8WlU.d.ts → bridge-client-CkxYcZcm.d.ts}

@@ -1,4 +1,4 @@
-import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-M5a42rAy.js';
+import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-BcKu-nQm.js';
 
 /**
  * Plugin-side bridge client for the host ↔ plugin platform contract

package/dist/{bridge-client-D9EYFq1l.d.cts → bridge-client-DkogtCvn.d.cts}

@@ -1,4 +1,4 @@
-import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-M5a42rAy.cjs';
+import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-BcKu-nQm.cjs';
 
 /**
  * Plugin-side bridge client for the host ↔ plugin platform contract

package/dist/{bridge-envelopes-M5a42rAy.d.cts → bridge-envelopes-BcKu-nQm.d.cts}

@@ -107,6 +107,77 @@ interface McpTransport {
      * completion.
      */
     uploadDocument?(meta: UploadDocumentMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadDocumentResult>;
+    /**
+     * Stream a browser file into the calling app's OWN plugin storage via the host shell, and
+     * resolve the {@link UploadToStorageResult}: the plugin-relative `path` the server chose, which
+     * is exactly the string the plugin's backend `IPluginStorage` reads, deletes or links.
+     *
+     * This is the route for every browser upload that a plugin's backend will later read. Never
+     * base64 a file through a tool call: the bytes would cross the MCP JSON pipe, the tool's
+     * argument limits and the audit payload. Unlike {@link uploadDocument} (legacy CORE storage,
+     * `StoredDocument` ids), the destination is the app's own storage namespace, which the kernel
+     * derives from the capability token alone.
+     *
+     * **Optional capability**, for the same reason as {@link uploadDocument}: a transport that
+     * predates it simply omits the member, and `uploadFileToPluginStorage` fails with a typed
+     * `unsupported` error rather than a `not a function` TypeError.
+     *
+     * The bytes are handed off as an {@link ArrayBuffer} the transport moves as a transferable
+     * (zero-copy) across the worker↔host port, so the caller's buffer is detached afterwards. The
+     * worker never sees the capability token or the kernel URL: the host mints the token, POSTs the
+     * octet-stream to `extensions/storage/upload-stream` with `x-cc-storage-prefix`,
+     * `x-cc-file-name` and `x-cc-content-type`, and returns only the result.
+     *
+     * When provided, implementations MUST observe `signal`. A host failure SHOULD reject with an
+     * error carrying the HTTP `status` (see `PluginStorageUploadError`), so a plugin can tell an
+     * over-size file (413) from an exhausted quota (507).
+     */
+    uploadToStorage?(meta: UploadToStorageMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadToStorageResult>;
+}
+/**
+ * Metadata accompanying an {@link McpTransport.uploadToStorage} call. There is no module key and
+ * no organisation: the kernel derives the storage namespace from the capability token, so there is
+ * nothing for the client to claim.
+ */
+interface UploadToStorageMeta {
+    /**
+     * Folder inside the app's own storage namespace: one or more `/`-separated segments of
+     * `[A-Za-z0-9_-]` (HR: `cvs`; Legal: `governance/{documentId}/{versionId}`), at most 84
+     * characters, with no leading or trailing `/`. A malformed prefix is refused (400), never
+     * repaired. Sent as `x-cc-storage-prefix`. The server re-validates it and is authoritative.
+     */
+    pathPrefix: string;
+    /**
+     * Client-supplied file name: display metadata, and its extension decides the stored type. It
+     * must end in an allow-listed extension (`PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES`) or the server
+     * answers 415. Sent as `x-cc-file-name`.
+     */
+    fileName: string;
+    /**
+     * Declared MIME type. It must be the extension's canonical type or a listed alias (415
+     * otherwise); empty or `application/octet-stream` means "use the extension's type". Sent as
+     * `x-cc-content-type`.
+     */
+    contentType: string;
+    /** Byte length of the buffer (advisory; the server reports what actually reached storage). */
+    sizeBytes: number;
+}
+/**
+ * Result of a successful {@link McpTransport.uploadToStorage} call.
+ */
+interface UploadToStorageResult {
+    /**
+     * Plugin-relative storage path, `{pathPrefix}/{guid}{ext}`, chosen by the server: exactly the
+     * string the plugin backend's `IPluginStorage` accepts. Not a URI. Record it with the app's own
+     * command.
+     */
+    path: string;
+    /** The sanitised file name the server recorded. */
+    fileName: string;
+    /** The content type the server recorded. */
+    contentType: string;
+    /** Bytes that actually reached storage, counted by the server. */
+    sizeBytes: number;
 }
 /**
  * Metadata accompanying an {@link McpTransport.uploadDocument} call. All fields
@@ -205,4 +276,4 @@ interface BridgeSessionTokenPushEnvelope {
     readonly expiresAtMs: number;
 }
 
-export type { BridgeNavPushEnvelope as B, McpTransport as M, UploadDocumentMeta as U, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e, UploadDocumentResult as f };
+export type { BridgeNavPushEnvelope as B, McpTransport as M, UploadDocumentMeta as U, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e, UploadDocumentResult as f, UploadToStorageMeta as g, UploadToStorageResult as h };

package/dist/{bridge-envelopes-M5a42rAy.d.ts → bridge-envelopes-BcKu-nQm.d.ts}

@@ -107,6 +107,77 @@ interface McpTransport {
      * completion.
      */
     uploadDocument?(meta: UploadDocumentMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadDocumentResult>;
+    /**
+     * Stream a browser file into the calling app's OWN plugin storage via the host shell, and
+     * resolve the {@link UploadToStorageResult}: the plugin-relative `path` the server chose, which
+     * is exactly the string the plugin's backend `IPluginStorage` reads, deletes or links.
+     *
+     * This is the route for every browser upload that a plugin's backend will later read. Never
+     * base64 a file through a tool call: the bytes would cross the MCP JSON pipe, the tool's
+     * argument limits and the audit payload. Unlike {@link uploadDocument} (legacy CORE storage,
+     * `StoredDocument` ids), the destination is the app's own storage namespace, which the kernel
+     * derives from the capability token alone.
+     *
+     * **Optional capability**, for the same reason as {@link uploadDocument}: a transport that
+     * predates it simply omits the member, and `uploadFileToPluginStorage` fails with a typed
+     * `unsupported` error rather than a `not a function` TypeError.
+     *
+     * The bytes are handed off as an {@link ArrayBuffer} the transport moves as a transferable
+     * (zero-copy) across the worker↔host port, so the caller's buffer is detached afterwards. The
+     * worker never sees the capability token or the kernel URL: the host mints the token, POSTs the
+     * octet-stream to `extensions/storage/upload-stream` with `x-cc-storage-prefix`,
+     * `x-cc-file-name` and `x-cc-content-type`, and returns only the result.
+     *
+     * When provided, implementations MUST observe `signal`. A host failure SHOULD reject with an
+     * error carrying the HTTP `status` (see `PluginStorageUploadError`), so a plugin can tell an
+     * over-size file (413) from an exhausted quota (507).
+     */
+    uploadToStorage?(meta: UploadToStorageMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadToStorageResult>;
+}
+/**
+ * Metadata accompanying an {@link McpTransport.uploadToStorage} call. There is no module key and
+ * no organisation: the kernel derives the storage namespace from the capability token, so there is
+ * nothing for the client to claim.
+ */
+interface UploadToStorageMeta {
+    /**
+     * Folder inside the app's own storage namespace: one or more `/`-separated segments of
+     * `[A-Za-z0-9_-]` (HR: `cvs`; Legal: `governance/{documentId}/{versionId}`), at most 84
+     * characters, with no leading or trailing `/`. A malformed prefix is refused (400), never
+     * repaired. Sent as `x-cc-storage-prefix`. The server re-validates it and is authoritative.
+     */
+    pathPrefix: string;
+    /**
+     * Client-supplied file name: display metadata, and its extension decides the stored type. It
+     * must end in an allow-listed extension (`PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES`) or the server
+     * answers 415. Sent as `x-cc-file-name`.
+     */
+    fileName: string;
+    /**
+     * Declared MIME type. It must be the extension's canonical type or a listed alias (415
+     * otherwise); empty or `application/octet-stream` means "use the extension's type". Sent as
+     * `x-cc-content-type`.
+     */
+    contentType: string;
+    /** Byte length of the buffer (advisory; the server reports what actually reached storage). */
+    sizeBytes: number;
+}
+/**
+ * Result of a successful {@link McpTransport.uploadToStorage} call.
+ */
+interface UploadToStorageResult {
+    /**
+     * Plugin-relative storage path, `{pathPrefix}/{guid}{ext}`, chosen by the server: exactly the
+     * string the plugin backend's `IPluginStorage` accepts. Not a URI. Record it with the app's own
+     * command.
+     */
+    path: string;
+    /** The sanitised file name the server recorded. */
+    fileName: string;
+    /** The content type the server recorded. */
+    contentType: string;
+    /** Bytes that actually reached storage, counted by the server. */
+    sizeBytes: number;
 }
 /**
  * Metadata accompanying an {@link McpTransport.uploadDocument} call. All fields
@@ -205,4 +276,4 @@ interface BridgeSessionTokenPushEnvelope {
     readonly expiresAtMs: number;
 }
 
-export type { BridgeNavPushEnvelope as B, McpTransport as M, UploadDocumentMeta as U, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e, UploadDocumentResult as f };
+export type { BridgeNavPushEnvelope as B, McpTransport as M, UploadDocumentMeta as U, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e, UploadDocumentResult as f, UploadToStorageMeta as g, UploadToStorageResult as h };

package/dist/host/index.cjs

@@ -380,6 +380,20 @@ function classifyHostError(err) {
   }
   return "internal";
 }
+function parsePluginStorageRetryAfter(raw, nowMs = Date.now()) {
+  if (typeof raw === "number") {
+    return Number.isFinite(raw) && raw >= 0 ? Math.ceil(raw) : void 0;
+  }
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return void 0;
+  }
+  const text = raw.trim();
+  if (/^\d+$/.test(text)) {
+    return Number(text);
+  }
+  const at = /[A-Za-z]/.test(text) ? Date.parse(text) : Number.NaN;
+  return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - nowMs) / 1e3));
+}
 
 // src/host/version-skew.ts
 var EXTENSION_VERSION_HEADER = "x-extension-version";
@@ -694,6 +708,9 @@ var WorkerRemoteDomTransport = class {
       case "ethisys:mcp:uploadDocument":
         this.dispatchMcp(message, "ethisys:mcp:uploadDocument:result", (m) => this.handleUploadDocument(m));
         return;
+      case "ethisys:mcp:uploadToStorage":
+        this.dispatchMcp(message, "ethisys:mcp:uploadToStorage:result", (m) => this.handleUploadToStorage(m));
+        return;
       case "ethisys:mcp:abort":
         this.inFlightAborts.get(message.id ?? "")?.abort();
         return;
@@ -931,11 +948,76 @@ var WorkerRemoteDomTransport = class {
       this.replyError(message.id, "ethisys:mcp:uploadDocument:result", err);
     }
   }
-  replyError(id, type, err) {
+  async handleUploadToStorage(message) {
+    const resultType = "ethisys:mcp:uploadToStorage:result";
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, resultType, err, true);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "uploadToStorage",
+        meta: message.meta,
+        buffer: message.buffer,
+        capabilityToken: token,
+        signal: this.requestSignal(message.id)
+      });
+      this.reportVersionSkew(result);
+      this.safePostMessage({
+        id: message.id,
+        type: resultType,
+        ok: result.ok,
+        data: result.data,
+        error: result.error,
+        code: classifyHostResponse(result),
+        // The HTTP status, on failure only. A bare number carries no host internals, and it
+        // is the only way the plugin can tell 413 (file too large) from 507 (quota) from 503
+        // (storage lock busy): the closed MCP code folds all three into `internal`/`unavailable`.
+        ...!result.ok && typeof result.status === "number" ? { status: result.status } : {},
+        // The server's `Retry-After` (429), as whole seconds, so a plugin can show how long
+        // to wait. Never acted on here: an upload is not retried automatically.
+        ...retryAfterField(result)
+      });
+    } catch (err) {
+      this.replyError(message.id, resultType, err, true);
+    }
+  }
+  replyError(id, type, err, includeStatus = false) {
     const message = err instanceof Error ? err.message : "MCP request failed";
-    this.safePostMessage({ id, type, ok: false, error: message, code: classifyHostError(err) });
+    const status = includeStatus ? statusOf(err) : void 0;
+    const retryAfterSeconds = includeStatus && err !== null && typeof err === "object" ? parsePluginStorageRetryAfter(err.retryAfterSeconds) : void 0;
+    this.safePostMessage({
+      id,
+      type,
+      ok: false,
+      error: message,
+      code: classifyHostError(err),
+      ...status !== void 0 ? { status } : {},
+      ...retryAfterSeconds !== void 0 ? { retryAfterSeconds } : {}
+    });
   }
 };
+function retryAfterField(result) {
+  if (result.ok || !result.headers) {
+    return {};
+  }
+  const key = Object.keys(result.headers).find((k) => k.toLowerCase() === "retry-after");
+  const seconds = key === void 0 ? void 0 : parsePluginStorageRetryAfter(result.headers[key]);
+  return seconds === void 0 ? {} : { retryAfterSeconds: seconds };
+}
+function statusOf(err) {
+  if (err === null || typeof err !== "object") {
+    return void 0;
+  }
+  const candidate = err;
+  return typeof candidate.status === "number" ? candidate.status : typeof candidate.statusCode === "number" ? candidate.statusCode : void 0;
+}
 var IFRAME_BRIDGE_PROTOCOL = "ethisys.iframe.bridge.v1";
 var InboundEnvelope = zod.z.discriminatedUnion("type", [
   zod.z.object({ type: zod.z.literal("ethisys:mcp:invokeTool"), id: zod.z.string().min(1), name: zod.z.string().min(1), args: zod.z.unknown(), nonce: zod.z.string() }),