@frontmcp/utils 1.11.2 → 1.12.0-rc.1

package/browser/stdio-bridge/upstream-client.mjs

@@ -1,10 +1,20 @@
 // libs/utils/src/stdio-bridge/upstream-client.ts
-var SESSION_HEADER = "mcp-session-id";
+import {
+  advertisesChannels,
+  declaringChannels,
+  DISCOVER_HEADERS,
+  discoverRequest,
+  namesProtocol20260728,
+  serverRevisionsOf,
+  unsupportedProtocolVersion
+} from "./claude-code-channels.mjs";
+import { createNotificationStream, SESSION_HEADER } from "./notification-stream.mjs";
+import { relaySseFrames } from "./sse-frames.mjs";
 var END_SESSION_TIMEOUT_MS = 2e3;
-var reinitCounter = 0;
-function nextReinitId() {
-  reinitCounter += 1;
-  return `frontmcp-dev-bridge:reinitialize:${reinitCounter}`;
+var bridgeRequestCounter = 0;
+function nextBridgeId(purpose) {
+  bridgeRequestCounter += 1;
+  return `frontmcp-dev-bridge:${purpose}:${bridgeRequestCounter}`;
 }
 function initializedNotification() {
   return { jsonrpc: "2.0", method: "notifications/initialized" };
@@ -18,17 +28,31 @@ function createHttpUpstream(options) {
   const { log, url, onFrame } = options;
   const abortControllers = /* @__PURE__ */ new Set();
   let sessionId;
-  async function post(frame, deliver) {
+  let revisions;
+  let streamAnswered = Promise.resolve();
+  const notifications = createNotificationStream({
+    url,
+    headers: options.headers,
+    fetch: options.fetch,
+    log,
+    onFrame,
+    onLost: options.onNotificationStreamLost
+  });
+  function sessionHeaders(frame) {
+    return sessionId && frame.method !== "initialize" ? { [SESSION_HEADER]: sessionId } : {};
+  }
+  async function post(frame, deliver, statelessHeaders) {
     const abortController = new AbortController();
     abortControllers.add(abortController);
     const signal = abortController.signal;
     try {
+      if (frame.method !== "initialize") await streamAnswered;
       const headers = {
         ...options.headers,
+        ...statelessHeaders ?? sessionHeaders(frame),
         "content-type": "application/json",
         accept: "application/json, text/event-stream"
       };
-      if (sessionId && frame.method !== "initialize") headers[SESSION_HEADER] = sessionId;
       const res = await (options.fetch ?? fetch)(url, {
         method: "POST",
         redirect: "error",
@@ -40,40 +64,21 @@ function createHttpUpstream(options) {
         log.warn("http-upstream-non-ok", { status: res.status, method: frame.method });
         throw new Error(`upstream returned ${res.status} for ${frame.method ?? "request"}`);
       }
-      const issued = res.headers.get(SESSION_HEADER);
-      if (issued && frame.method === "initialize") {
-        sessionId = issued;
+      const startedSession = frame.method === "initialize" ? res.headers.get(SESSION_HEADER) : null;
+      if (startedSession) {
+        sessionId = startedSession;
         log.info("http-upstream-session");
       }
+      const streamOfSession = startedSession && !signal.aborted ? notifications.follow(startedSession) : void 0;
+      if (streamOfSession) streamAnswered = streamOfSession;
       const contentType = res.headers.get("content-type") ?? "";
       if (contentType.includes("text/event-stream")) {
-        const reader = res.body?.getReader();
-        if (!reader) return;
-        const decoder = new TextDecoder();
-        let buffer = "";
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          let nl;
-          while ((nl = buffer.indexOf("\n")) >= 0) {
-            const line = buffer.slice(0, nl).trim();
-            buffer = buffer.slice(nl + 1);
-            if (!line.startsWith("data:")) continue;
-            const json = line.slice(5).trim();
-            if (!json) continue;
-            try {
-              const parsed = JSON.parse(json);
-              await deliver(parsed);
-            } catch (err) {
-              log.warn("sse-parse-error", { error: err.message, raw: json.slice(0, 200) });
-            }
-          }
-        }
+        if (res.body) await relaySseFrames(res.body, deliver, log);
       } else if (contentType.includes("application/json")) {
         const body = await res.json();
         await deliver(body);
       }
+      await streamOfSession;
     } catch (err) {
       if (err.name === "AbortError") {
         log.info("http-upstream-aborted", { method: frame.method });
@@ -85,23 +90,69 @@ function createHttpUpstream(options) {
       abortControllers.delete(abortController);
     }
   }
+  function toServer(initialize) {
+    return options.claudeCodeChannels ? declaringChannels(initialize) : initialize;
+  }
+  function refreshRevisions(initializeResult) {
+    if (revisions && revisions.pushesChannels !== advertisesChannels(initializeResult)) revisions = void 0;
+  }
+  async function discoverRevisions() {
+    const request = discoverRequest(nextBridgeId("discover"));
+    let result;
+    try {
+      await post(
+        request,
+        (frame) => {
+          if (frame.id === request.id) result = frame.result;
+        },
+        DISCOVER_HEADERS
+      );
+    } catch {
+      return void 0;
+    }
+    return serverRevisionsOf(result);
+  }
+  async function declined(frame) {
+    revisions ??= await discoverRevisions();
+    if (!revisions?.pushesChannels) return false;
+    if (frame.id !== void 0 && frame.id !== null) {
+      await onFrame(unsupportedProtocolVersion(frame, revisions.supported));
+    }
+    return true;
+  }
+  async function sendInitialize(initialize) {
+    await post(toServer(initialize), async (frame) => {
+      if (frame.id === initialize.id) refreshRevisions(frame.result);
+      await onFrame(frame);
+    });
+  }
   return {
-    send: (frame) => post(frame, onFrame),
+    async send(frame) {
+      if (frame.method === "initialize") return sendInitialize(frame);
+      if (options.claudeCodeChannels && namesProtocol20260728(frame) && await declined(frame)) return;
+      await post(frame, onFrame);
+    },
     async reinitialize(initialize, initialized) {
-      const id = nextReinitId();
+      const id = nextBridgeId("reinitialize");
       let response;
-      await post({ ...initialize, id }, async (frame) => {
+      await post({ ...toServer(initialize), id }, async (frame) => {
         if (frame.id === id) response = frame;
         else await onFrame(frame);
       });
       const result = resultOf(response, "initialize");
+      refreshRevisions(result);
       if (initialized) await post(initializedNotification(), onFrame);
       return result;
     },
+    leaveSession() {
+      sessionId = void 0;
+      void notifications.follow(void 0);
+    },
     async endSession() {
       const ending = sessionId;
       if (!ending) return;
       sessionId = void 0;
+      void notifications.follow(void 0);
       try {
         const res = await (options.fetch ?? fetch)(url, {
           method: "DELETE",
@@ -115,6 +166,7 @@ function createHttpUpstream(options) {
       }
     },
     close: async () => {
+      void notifications.follow(void 0);
       for (const ac of abortControllers) ac.abort();
       abortControllers.clear();
     }
@@ -158,7 +210,7 @@ function createPipeUpstream(options) {
   return {
     send,
     async reinitialize(initialize, initialized) {
-      const id = nextReinitId();
+      const id = nextBridgeId("reinitialize");
       let timer;
       const response = new Promise((resolve, reject) => {
         pending.set(id, resolve);

package/browser/storage/adapters/filesystem.mjs

@@ -1,9 +1,9 @@
 // libs/utils/src/storage/adapters/filesystem.ts
-import { BaseStorageAdapter } from "./base.mjs";
+import { bytesToHex, randomBytes } from "../../crypto/index.mjs";
+import { ensureDir, fileExists, mkdir, readdir, readJSON, rename, unlink, writeFile } from "../../fs/index.mjs";
 import { StorageOperationError } from "../errors.mjs";
 import { globToRegex } from "../utils/pattern.mjs";
-import { writeFile, readdir, unlink, fileExists, ensureDir, mkdir, rename, readJSON } from "../../fs/index.mjs";
-import { randomBytes, bytesToHex } from "../../crypto/index.mjs";
+import { BaseStorageAdapter } from "./base.mjs";
 var FileSystemStorageAdapter = class extends BaseStorageAdapter {
   backendName = "filesystem";
   baseDir;

package/browser/storage/adapters/indexeddb.mjs

@@ -1,6 +1,6 @@
 // libs/utils/src/storage/adapters/indexeddb.ts
-import { BaseStorageAdapter } from "./base.mjs";
 import { matchesPattern } from "../utils/pattern.mjs";
+import { BaseStorageAdapter } from "./base.mjs";
 var IndexedDBStorageAdapter = class extends BaseStorageAdapter {
   backendName = "indexeddb";
   dbName;

package/browser/storage/adapters/localstorage.mjs

@@ -1,7 +1,7 @@
 // libs/utils/src/storage/adapters/localstorage.ts
-import { BaseStorageAdapter } from "./base.mjs";
-import { encryptAesGcm, decryptAesGcm, randomBytes, base64urlEncode, base64urlDecode } from "../../crypto/index.mjs";
+import { base64urlDecode, base64urlEncode, decryptAesGcm, encryptAesGcm, randomBytes } from "../../crypto/index.mjs";
 import { matchesPattern } from "../utils/pattern.mjs";
+import { BaseStorageAdapter } from "./base.mjs";
 var LocalStorageAdapter = class extends BaseStorageAdapter {
   backendName = "localstorage";
   prefix;

package/browser/storage/encrypted-typed-storage.mjs

@@ -1,5 +1,5 @@
 // libs/utils/src/storage/encrypted-typed-storage.ts
-import { encryptAesGcm, decryptAesGcm, randomBytes, base64urlEncode, base64urlDecode, hkdfSha256 } from "../crypto/index.mjs";
+import { base64urlDecode, base64urlEncode, decryptAesGcm, encryptAesGcm, hkdfSha256, randomBytes } from "../crypto/index.mjs";
 import { EncryptedStorageError } from "./errors.mjs";
 var textEncoder = new TextEncoder();
 var textDecoder = new TextDecoder();

package/crypto/index.d.ts

@@ -162,4 +162,5 @@ export { type EncryptedBlob, EncryptedBlobError, encryptValue, decryptValue, try
 export { MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, type PkcePair, } from './pkce';
 export { type SecretData, type SecretPersistenceOptions, type SecretValidationResult, secretDataSchema, validateSecretData, parseSecretData, isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, } from './secret-persistence';
 export { type SignedData, type HmacSigningConfig, signData, verifyData, isSignedData, verifyOrParseData, } from './hmac-signing';
+export { WEBHOOK_ID_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, signingKeyOf, isStandardWebhookSecret, generateStandardWebhookSecret, generateWebhookMessageId, signWebhookMessage, webhookSignatureHeaders, verifyWebhookSignature, type WebhookMessage, type SignedWebhookMessage, type WebhookSignatureCheck, } from './standard-webhooks';
 export { type BaseKeyData, type SecretKeyData, type AsymmetricKeyData, type AnyKeyData, type KeyPersistenceOptions, type CreateKeyPersistenceOptions, type CreateSecretOptions, type CreateAsymmetricOptions, type KeyValidationResult, asymmetricAlgSchema, secretKeyDataSchema, asymmetricKeyDataSchema, anyKeyDataSchema, validateKeyData, parseKeyData, isSecretKeyData, isAsymmetricKeyData, KeyPersistence, createKeyPersistence, createKeyPersistenceWithStorage, } from './key-persistence';

package/crypto/key-persistence/key-persistence.d.ts

@@ -7,7 +7,7 @@
  * @module @frontmcp/utils/key-persistence
  */
 import type { StorageAdapter } from '../../storage/types';
-import type { AnyKeyData, SecretKeyData, AsymmetricKeyData, KeyPersistenceOptions, CreateSecretOptions } from './types';
+import type { AnyKeyData, AsymmetricKeyData, CreateSecretOptions, KeyPersistenceOptions, SecretKeyData } from './types';
 /**
  * KeyPersistence provides a unified API for storing and retrieving
  * cryptographic keys with any storage backend.

package/crypto/standard-webhooks.d.ts

@@ -0,0 +1,35 @@
+/** Standard Webhooks signatures (https://www.standardwebhooks.com): HMAC-SHA256 over `<id>.<timestamp>.<body>`. */
+export declare const WEBHOOK_ID_HEADER = "webhook-id";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/** How far a signed timestamp may be from the verifier's clock, in seconds. */
+export declare const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+export interface WebhookMessage {
+    /** The `webhook-id`, kept across the retries of one message. */
+    id: string;
+    /** The Unix time of this attempt, in whole seconds. */
+    timestamp: number;
+    /** The request body, exactly as it is sent. */
+    body: string;
+}
+export interface SignedWebhookMessage {
+    id?: string;
+    timestamp?: string;
+    signature?: string;
+    body: string;
+}
+export type WebhookSignatureCheck = 'valid' | 'missing' | 'stale' | 'mismatch';
+/** The HMAC key of a secret: a `whsec_` secret is base64 after the prefix, any other its UTF-8 bytes; never empty. */
+export declare function signingKeyOf(secret: string): Uint8Array;
+/** Whether a secret is `whsec_` followed by base64, padded or not, that decodes to 24 to 64 bytes. */
+export declare function isStandardWebhookSecret(secret: string): boolean;
+/** A new `whsec_` secret of 32 random bytes. */
+export declare function generateStandardWebhookSecret(): string;
+/** A new `webhook-id`, `msg_<random>` or `msg_<kind>_<random>`: ASCII letters, digits, `_` and `-` only. */
+export declare function generateWebhookMessageId(kind?: string): string;
+/** The `webhook-signature` of a message: one `v1,<base64>` per signing key, separated by a space. */
+export declare function signWebhookMessage(message: WebhookMessage, signingKeys: readonly Uint8Array[]): string;
+/** The three headers that sign a message with every signing key. */
+export declare function webhookSignatureHeaders(message: WebhookMessage, signingKeys: readonly Uint8Array[]): Record<string, string>;
+/** Checks a signed message: a timestamp within the tolerance of `now`, and a `v1` signature one of the keys gives. */
+export declare function verifyWebhookSignature(message: SignedWebhookMessage, signingKeys: readonly Uint8Array[], now?: number): WebhookSignatureCheck;

package/env/browser-runtime-context.d.ts

@@ -42,11 +42,11 @@ export declare const entryAvailabilitySchema: import("@frontmcp/lazy-zod").ZodOb
     provider: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     target: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     surface: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodEnum<{
+        agent: "agent";
         cli: "cli";
         mcp: "mcp";
         "http-trigger": "http-trigger";
         job: "job";
-        agent: "agent";
         webmcp: "webmcp";
     }>>>;
     env: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;

package/env/runtime-context.d.ts

@@ -98,11 +98,11 @@ export declare const entryAvailabilitySchema: import("@frontmcp/lazy-zod").ZodOb
     provider: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     target: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     surface: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodEnum<{
+        agent: "agent";
         cli: "cli";
         mcp: "mcp";
         "http-trigger": "http-trigger";
         job: "job";
-        agent: "agent";
         webmcp: "webmcp";
     }>>>;
     env: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;