@ethisyscore/extension-runtime 1.136.0 → 1.138.0

package/dist/mock-host/index.d.cts

@@ -1,8 +1,10 @@
 import { ReactNode, ReactElement } from 'react';
 import { C as ComponentRegistry } from '../registry-DpCx_LxF.cjs';
 import { SduiNode } from '@ethisyscore/protocol';
-import { M as McpTransport, U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.cjs';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload, D as DensityPayload, A as A11yPayload, N as NavPayload, S as SessionTokenPayload } from '../bridge-client-D9EYFq1l.cjs';
+import { M as McpTransport, U as UploadDocumentMeta, f as UploadDocumentResult, g as UploadToStorageMeta, h as UploadToStorageResult } from '../bridge-envelopes-BcKu-nQm.cjs';
+import { M as MockPluginStorage } from '../MockPluginStorage-QKfz8CMt.cjs';
+export { a as MockPluginStorageOptions, b as MockPluginStorageRateLimit, c as MockStoredFile } from '../MockPluginStorage-QKfz8CMt.cjs';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload, D as DensityPayload, A as A11yPayload, N as NavPayload, S as SessionTokenPayload } from '../bridge-client-DkogtCvn.cjs';
 
 /**
  * Handler for a mocked tool invocation. The handler receives the request
@@ -37,12 +39,20 @@ type MockUploadHandler = (meta: UploadDocumentMeta, buffer: ArrayBuffer, signal?
  * contract. `uploadDocument` DOES observe the signal (rejecting with an
  * `AbortError`): its contract mandates it, a mock upload handler may be
  * genuinely async, and dev-host flows need to simulate upload cancellation.
+ *
+ * `uploadToStorage` writes into {@link pluginStorage}, an in-memory {@link MockPluginStorage}, and
+ * returns a server-style `{prefix}/{guid}{ext}` path. It validates the prefix and size with the
+ * kernel's rules, rejecting with a typed `PluginStorageUploadError` (status 400 / 413), and
+ * honours the signal.
  */
 declare class InMemoryMcpTransport implements McpTransport {
     private readonly resources;
     private readonly tools;
     private readonly uploadHandler?;
-    constructor(resources: Record<string, SduiNode>, tools?: Record<string, MockToolHandler>, uploadHandler?: MockUploadHandler);
+    /** Where `uploadToStorage` writes. Read it back in a test, or from devtools under `dev:mock`. */
+    readonly pluginStorage: MockPluginStorage;
+    constructor(resources: Record<string, SduiNode>, tools?: Record<string, MockToolHandler>, uploadHandler?: MockUploadHandler, pluginStorage?: MockPluginStorage);
+    uploadToStorage(meta: UploadToStorageMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadToStorageResult>;
     getResource<T>(uri: string): Promise<{
         uri: string;
         data: T;
@@ -196,4 +206,4 @@ interface WorkerMockHostProps extends DeclarativeMockHostProps {
  */
 declare function WorkerMockHost(props: WorkerMockHostProps): ReactElement;
 
-export { DeclarativeMockHost, type DeclarativeMockHostProps, InMemoryBridgeTransport, InMemoryMcpTransport, type MockToolHandler, WorkerMockHost, type WorkerMockHostProps };
+export { DeclarativeMockHost, type DeclarativeMockHostProps, InMemoryBridgeTransport, InMemoryMcpTransport, MockPluginStorage, type MockToolHandler, WorkerMockHost, type WorkerMockHostProps };

package/dist/mock-host/index.d.ts

@@ -1,8 +1,10 @@
 import { ReactNode, ReactElement } from 'react';
 import { C as ComponentRegistry } from '../registry-DpCx_LxF.js';
 import { SduiNode } from '@ethisyscore/protocol';
-import { M as McpTransport, U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.js';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload, D as DensityPayload, A as A11yPayload, N as NavPayload, S as SessionTokenPayload } from '../bridge-client-RJOl8WlU.js';
+import { M as McpTransport, U as UploadDocumentMeta, f as UploadDocumentResult, g as UploadToStorageMeta, h as UploadToStorageResult } from '../bridge-envelopes-BcKu-nQm.js';
+import { M as MockPluginStorage } from '../MockPluginStorage-DF3DL1dI.js';
+export { a as MockPluginStorageOptions, b as MockPluginStorageRateLimit, c as MockStoredFile } from '../MockPluginStorage-DF3DL1dI.js';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload, D as DensityPayload, A as A11yPayload, N as NavPayload, S as SessionTokenPayload } from '../bridge-client-CkxYcZcm.js';
 
 /**
  * Handler for a mocked tool invocation. The handler receives the request
@@ -37,12 +39,20 @@ type MockUploadHandler = (meta: UploadDocumentMeta, buffer: ArrayBuffer, signal?
  * contract. `uploadDocument` DOES observe the signal (rejecting with an
  * `AbortError`): its contract mandates it, a mock upload handler may be
  * genuinely async, and dev-host flows need to simulate upload cancellation.
+ *
+ * `uploadToStorage` writes into {@link pluginStorage}, an in-memory {@link MockPluginStorage}, and
+ * returns a server-style `{prefix}/{guid}{ext}` path. It validates the prefix and size with the
+ * kernel's rules, rejecting with a typed `PluginStorageUploadError` (status 400 / 413), and
+ * honours the signal.
  */
 declare class InMemoryMcpTransport implements McpTransport {
     private readonly resources;
     private readonly tools;
     private readonly uploadHandler?;
-    constructor(resources: Record<string, SduiNode>, tools?: Record<string, MockToolHandler>, uploadHandler?: MockUploadHandler);
+    /** Where `uploadToStorage` writes. Read it back in a test, or from devtools under `dev:mock`. */
+    readonly pluginStorage: MockPluginStorage;
+    constructor(resources: Record<string, SduiNode>, tools?: Record<string, MockToolHandler>, uploadHandler?: MockUploadHandler, pluginStorage?: MockPluginStorage);
+    uploadToStorage(meta: UploadToStorageMeta, buffer: ArrayBuffer, signal?: AbortSignal): Promise<UploadToStorageResult>;
     getResource<T>(uri: string): Promise<{
         uri: string;
         data: T;
@@ -196,4 +206,4 @@ interface WorkerMockHostProps extends DeclarativeMockHostProps {
  */
 declare function WorkerMockHost(props: WorkerMockHostProps): ReactElement;
 
-export { DeclarativeMockHost, type DeclarativeMockHostProps, InMemoryBridgeTransport, InMemoryMcpTransport, type MockToolHandler, WorkerMockHost, type WorkerMockHostProps };
+export { DeclarativeMockHost, type DeclarativeMockHostProps, InMemoryBridgeTransport, InMemoryMcpTransport, MockPluginStorage, type MockToolHandler, WorkerMockHost, type WorkerMockHostProps };

package/dist/mock-host/index.js

@@ -34,15 +34,289 @@ function ExtensionRuntimeProvider({ transport, clientPush = null, identity = nul
   return /* @__PURE__ */ jsx(ExtensionRuntimeContext.Provider, { value, children: /* @__PURE__ */ jsx(ClientPushContext.Provider, { value: push, children: /* @__PURE__ */ jsx(HostIdentityContext.Provider, { value: id, children: /* @__PURE__ */ jsx(PluginRealtimeContext.Provider, { value: realtimeValue, children }) }) }) });
 }
 
+// src/bridge/mcp-error.ts
+var RETRYABLE = ["rate_limited", "timeout", "unavailable"];
+function isRetryableMcpErrorCode(code) {
+  return RETRYABLE.includes(code);
+}
+var McpToolError = class extends Error {
+  /** Machine-readable classification. `internal` when the host sent none. */
+  code;
+  /**
+   * Marks the instance for {@link isMcpToolError}. A structural marker rather than a prototype
+   * check because the error can be constructed in one bundle and inspected in another, where
+   * `instanceof` compares two different class objects and answers false.
+   */
+  isMcpToolError = true;
+  constructor(message, code = "internal") {
+    super(message);
+    this.name = "McpHostError";
+    this.code = code;
+  }
+  /** True when this failure is worth retrying unchanged. */
+  get retryable() {
+    return isRetryableMcpErrorCode(this.code);
+  }
+};
+function mcpErrorCodeFromHttpStatus(status) {
+  switch (status) {
+    case 401:
+      return "unauthorized";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 400:
+    case 422:
+      return "invalid_request";
+    case 409:
+    case 412:
+      return "conflict";
+    case 429:
+      return "rate_limited";
+    case 408:
+    case 504:
+      return "timeout";
+    case 502:
+    case 503:
+      return "unavailable";
+    default:
+      return "internal";
+  }
+}
+
+// src/plugin/pluginStorageUpload.ts
+var PLUGIN_STORAGE_UPLOAD_MAX_BYTES = 30 * 1024 * 1024;
+var PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
+var PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
+var PluginStorageUploadError = class extends McpToolError {
+  /** What went wrong, in terms a caller branches on. */
+  reason;
+  /** HTTP status from the server, when the host surfaced one. */
+  status;
+  /**
+   * Seconds the server asked the caller to wait (`Retry-After`), on a `rate_limited` failure
+   * when the host forwarded the header. Absent otherwise.
+   */
+  retryAfterSeconds;
+  /** Structural marker for {@link isPluginStorageUploadError}. */
+  isPluginStorageUploadError = true;
+  constructor(message, reason, options = {}) {
+    super(message, options.code ?? codeForReason(reason, options.status));
+    this.name = "PluginStorageUploadError";
+    this.reason = reason;
+    this.status = options.status;
+    if (options.retryAfterSeconds !== void 0) {
+      this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+  }
+};
+function validatePluginStoragePrefix(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return { ok: false, error: "A storage path prefix is required." };
+  }
+  if (raw.length > PLUGIN_STORAGE_PREFIX_MAX_LENGTH) {
+    return {
+      ok: false,
+      error: `The storage path prefix must be at most ${PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, so the stored path fits ${PLUGIN_STORAGE_PATH_MAX_LENGTH}.`
+    };
+  }
+  if (!/^[A-Za-z0-9_\-/]+$/.test(raw)) {
+    return {
+      ok: false,
+      error: "The storage path prefix may contain only letters, digits, '-', '_' and '/' separators."
+    };
+  }
+  if (raw.split("/").some((segment) => segment.length === 0)) {
+    return {
+      ok: false,
+      error: "The storage path prefix must not start or end with '/' or contain an empty segment."
+    };
+  }
+  return { ok: true, prefix: raw };
+}
+var PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES = Object.freeze({
+  pdf: ["application/pdf"],
+  png: ["image/png"],
+  jpg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  jpeg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  gif: ["image/gif"],
+  webp: ["image/webp"],
+  doc: ["application/msword"],
+  docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  xls: ["application/vnd.ms-excel"],
+  xlsx: ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  ppt: ["application/vnd.ms-powerpoint"],
+  pptx: ["application/vnd.openxmlformats-officedocument.presentationml.presentation"],
+  odt: ["application/vnd.oasis.opendocument.text"],
+  ods: ["application/vnd.oasis.opendocument.spreadsheet"],
+  odp: ["application/vnd.oasis.opendocument.presentation"],
+  txt: ["text/plain"],
+  csv: ["text/csv", "application/vnd.ms-excel", "application/csv", "text/plain"],
+  zip: ["application/zip", "application/x-zip-compressed", "application/x-zip"],
+  mp3: ["audio/mpeg", "audio/mp3"],
+  m4a: ["audio/mp4", "audio/x-m4a"],
+  mp4: ["video/mp4"]
+});
+var OCTET_STREAM = "application/octet-stream";
+function pluginStorageSafeExtension(fileName) {
+  if (typeof fileName !== "string" || fileName.trim().length === 0) {
+    return "";
+  }
+  const leaf = fileName.split(/[\\/]/).pop() ?? "";
+  const dot = leaf.lastIndexOf(".");
+  if (dot < 0) {
+    return "";
+  }
+  const body = leaf.slice(dot + 1);
+  return /^[A-Za-z0-9]{1,10}$/.test(body) ? `.${body.toLowerCase()}` : "";
+}
+function resolvePluginStorageContentType(fileName, declaredContentType) {
+  const extension = pluginStorageSafeExtension(fileName).slice(1);
+  const allowed = extension.length > 0 && Object.prototype.hasOwnProperty.call(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, extension) ? PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES[extension] : void 0;
+  if (allowed === void 0) {
+    return {
+      ok: false,
+      error: "This file type is not allowed. Allowed: " + Object.keys(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES).sort().join(", ") + "."
+    };
+  }
+  const declared = mediaTypeOf(declaredContentType);
+  if (declared === void 0 || declared === OCTET_STREAM || allowed.includes(declared)) {
+    return { ok: true, contentType: allowed[0] };
+  }
+  return {
+    ok: false,
+    error: `The declared content type '${declared}' does not match the file extension '.${extension}'.`
+  };
+}
+function mediaTypeOf(raw) {
+  if (typeof raw !== "string") {
+    return void 0;
+  }
+  const mediaType = raw.split(";")[0].trim().toLowerCase();
+  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mediaType) ? mediaType : void 0;
+}
+function codeForReason(reason, status) {
+  if (status !== void 0) {
+    return mcpErrorCodeFromHttpStatus(status);
+  }
+  switch (reason) {
+    case "invalid_prefix":
+    case "too_large":
+    case "unsupported_type":
+      return "invalid_request";
+    case "timeout":
+      return "timeout";
+    case "unauthorized":
+      return "unauthorized";
+    case "forbidden":
+      return "forbidden";
+    case "busy":
+      return "unavailable";
+    case "rate_limited":
+      return "rate_limited";
+    case "aborted":
+      return "timeout";
+    default:
+      return "internal";
+  }
+}
+
+// src/mock-host/MockPluginStorage.ts
+var MockPluginStorage = class {
+  files = /* @__PURE__ */ new Map();
+  rateLimit;
+  now;
+  windowStartMs = 0;
+  windowCount = 0;
+  constructor(options = {}) {
+    this.rateLimit = options.rateLimit;
+    this.now = options.now ?? Date.now;
+  }
+  /** Store `buffer` under a new path below `meta.pathPrefix`. */
+  store(meta, buffer) {
+    this.enforceRateLimit();
+    const prefix = validatePluginStoragePrefix(meta.pathPrefix);
+    if (!prefix.ok) {
+      throw new PluginStorageUploadError(prefix.error, "invalid_prefix", { status: 400 });
+    }
+    if (buffer.byteLength > PLUGIN_STORAGE_UPLOAD_MAX_BYTES) {
+      throw new PluginStorageUploadError(
+        `The upload exceeds the ${PLUGIN_STORAGE_UPLOAD_MAX_BYTES}-byte limit.`,
+        "too_large",
+        { status: 413 }
+      );
+    }
+    const fileName = meta.fileName && meta.fileName.length > 0 ? meta.fileName : "upload.bin";
+    const type = resolvePluginStorageContentType(fileName, meta.contentType);
+    if (!type.ok) {
+      throw new PluginStorageUploadError(type.error, "unsupported_type", { status: 415 });
+    }
+    const path = `${prefix.prefix}/${randomGuidN()}${pluginStorageSafeExtension(fileName)}`;
+    const bytes = new Uint8Array(buffer.slice(0));
+    this.files.set(path, { path, fileName, contentType: type.contentType, bytes });
+    return { path, fileName, contentType: type.contentType, sizeBytes: bytes.byteLength };
+  }
+  /** The kernel refuses before the handler runs, so this is checked before anything else. */
+  enforceRateLimit() {
+    if (this.rateLimit === void 0) {
+      return;
+    }
+    const windowMs = (this.rateLimit.windowSeconds ?? 60) * 1e3;
+    const now = this.now();
+    if (this.windowCount === 0 || now - this.windowStartMs >= windowMs) {
+      this.windowStartMs = now;
+      this.windowCount = 0;
+    }
+    this.windowCount += 1;
+    if (this.windowCount > this.rateLimit.maxRequests) {
+      const retryAfterSeconds = Math.max(1, Math.ceil((this.windowStartMs + windowMs - now) / 1e3));
+      throw new PluginStorageUploadError(
+        "Rate limit exceeded. Please try again later.",
+        "rate_limited",
+        { status: 429, retryAfterSeconds }
+      );
+    }
+  }
+  /** The stored file at `path`, or `undefined`. */
+  get(path) {
+    return this.files.get(path);
+  }
+  /** Every stored file, in upload order. */
+  list() {
+    return [...this.files.values()];
+  }
+  /** Forget every stored file. */
+  clear() {
+    this.files.clear();
+  }
+};
+function randomGuidN() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // src/mock-host/InMemoryMcpTransport.ts
 var InMemoryMcpTransport = class {
   resources;
   tools;
   uploadHandler;
-  constructor(resources, tools = {}, uploadHandler) {
+  /** Where `uploadToStorage` writes. Read it back in a test, or from devtools under `dev:mock`. */
+  pluginStorage;
+  constructor(resources, tools = {}, uploadHandler, pluginStorage = new MockPluginStorage()) {
     this.resources = resources;
     this.tools = tools;
     this.uploadHandler = uploadHandler;
+    this.pluginStorage = pluginStorage;
+  }
+  async uploadToStorage(meta, buffer, signal) {
+    if (signal?.aborted === true) {
+      throw abortError();
+    }
+    return this.pluginStorage.store(meta, buffer);
   }
   async getResource(uri) {
     const data = this.resources[uri];
@@ -194,6 +468,6 @@ function WorkerMockHost(props) {
   return /* @__PURE__ */ jsx(BridgeClientContext.Provider, { value: bridgeTransport, children: /* @__PURE__ */ jsx(DeclarativeMockHost, { ...declarativeProps }) });
 }
 
-export { DeclarativeMockHost, InMemoryBridgeTransport, InMemoryMcpTransport, WorkerMockHost };
+export { DeclarativeMockHost, InMemoryBridgeTransport, InMemoryMcpTransport, MockPluginStorage, WorkerMockHost };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map