@appstrate/afps-shared 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Zero-dependency AFPS helpers shared by @appstrate/core and @appstrate/afps-runtime (companion-file checks, semver resolution, SRI integrity, credential templates, delivery.http projection)",
   "license": "Apache-2.0",
   "type": "module",
@@ -40,11 +40,14 @@
     "./integrity": "./src/integrity.ts",
     "./credential-template": "./src/credential-template.ts",
     "./delivery-http": "./src/delivery-http.ts",
+    "./api-tool-naming": "./src/api-tool-naming.ts",
+    "./mcp-naming": "./src/mcp-naming.ts",
     "./file-field": "./src/file-field.ts",
     "./ssrf": "./src/ssrf.ts",
     "./token-usage": "./src/token-usage.ts",
     "./ssrf-dns": "./src/ssrf-dns.ts",
     "./guarded-fetch": "./src/guarded-fetch.ts",
+    "./signed-token": "./src/signed-token.ts",
     "./unzip-bounded": "./src/unzip-bounded.ts",
     "./backoff": "./src/backoff.ts"
   },

package/src/api-tool-naming.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Appstrate
+
+import { MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH } from "./mcp-naming.ts";
+
+/** Canonical unprefixed name of the credential-injecting API tool. */
+export const API_CALL_TOOL_NAME = "api_call";
+
+/** Canonical unprefixed name of the resumable-upload companion. */
+export const API_UPLOAD_TOOL_NAME = "api_upload";
+
+// McpHost can append `_999` (four characters) to a colliding namespace. The
+// longest synthetic prefix is `api_upload__` (12 characters), so an auth token
+// gets at most 56 - 24 - 2 - 12 = 18 characters in every valid allocation.
+const MCP_NAMESPACE_COLLISION_SUFFIX_MAX_LENGTH = 4;
+const MCP_NAMESPACE_SEPARATOR_LENGTH = 2;
+const API_UPLOAD_AUTH_PREFIX_LENGTH = `${API_UPLOAD_TOOL_NAME}__`.length;
+const API_TOOL_AUTH_TOKEN_LENGTH =
+  MCP_TOOL_NAME_MAX_LENGTH -
+  (MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH + MCP_NAMESPACE_COLLISION_SUFFIX_MAX_LENGTH) -
+  MCP_NAMESPACE_SEPARATOR_LENGTH -
+  API_UPLOAD_AUTH_PREFIX_LENGTH;
+const API_TOOL_RAW_AUTH_KEY_MAX_LENGTH = API_TOOL_AUTH_TOKEN_LENGTH - 1;
+const API_TOOL_AUTH_HASH_HEX_LENGTH = API_TOOL_AUTH_TOKEN_LENGTH - 2;
+
+/**
+ * Map an AFPS auth key onto the bounded token used in multi-auth tool names.
+ *
+ * Keys up to 17 characters remain verbatim. Longer keys become `h0` followed
+ * by a 64-bit FNV-1a digest, producing exactly 18 characters. The two output
+ * domains are disjoint by length, so a short raw key can never impersonate a
+ * compacted long key. Consumers also reject duplicate tokens inside one
+ * integration, making the bounded alias fail closed even under a deliberate
+ * hash collision. The full auth key still travels separately in runtime
+ * metadata and is never recovered by parsing this display/routing token.
+ */
+export function apiToolAuthToken(authKey: string): string {
+  if (authKey.length <= API_TOOL_RAW_AUTH_KEY_MAX_LENGTH) return authKey;
+  return `h0${fnv1a64(authKey).slice(0, API_TOOL_AUTH_HASH_HEX_LENGTH)}`;
+}
+
+/** Throw when two distinct auth keys collapse onto the same bounded token. */
+export function assertUniqueApiToolAuthTokens(authKeys: readonly string[]): void {
+  const owners = new Map<string, string>();
+  for (const authKey of authKeys) {
+    const token = apiToolAuthToken(authKey);
+    const existing = owners.get(token);
+    if (existing !== undefined && existing !== authKey) {
+      throw new Error(
+        `api tool auth-token collision between ${JSON.stringify(existing)} and ${JSON.stringify(authKey)}`,
+      );
+    }
+    owners.set(token, authKey);
+  }
+}
+
+function fnv1a64(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = (hash * prime) & mask;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+/** Derive the unprefixed api_call name for one auth surface. */
+export function apiCallToolNameForAuth(authKey: string, multiAuth: boolean): string {
+  return multiAuth ? `${API_CALL_TOOL_NAME}__${apiToolAuthToken(authKey)}` : API_CALL_TOOL_NAME;
+}
+
+/** Derive the api_upload companion while preserving the auth-scoped token. */
+export function apiUploadToolNameFor(apiCallToolName: string): string {
+  return `${API_UPLOAD_TOOL_NAME}${apiCallToolName.slice(API_CALL_TOOL_NAME.length)}`;
+}

package/src/guarded-fetch.ts

@@ -4,7 +4,8 @@
 /**
  * `guardedFetch` — the single outbound-request primitive for any path whose
  * host comes from a less-trusted input (manifest URLs, OAuth endpoints,
- * webhook targets, configurable model/proxy base URLs, MCP discovery).
+ * webhook targets, configurable model/proxy base URLs, MCP discovery,
+ * credential-proxy targets).
  *
  * Two SSRF guards historically coexisted in this codebase: the literal
  * `isBlockedUrl` (string-only, no DNS) and the DNS-rebind-safe
@@ -15,15 +16,36 @@
  * - Follows redirects MANUALLY (`redirect: "manual"`) so every hop is checked.
  * - Runs `resolveAndCheckHost` on the initial host AND on every redirect target
  *   (per-hop DNS resolution + blocklist), failing closed.
+ * - Enforces the CALLER'S reachability contract on every hop when
+ *   `validateHop` is provided: the predicate runs on hop 0 and on every
+ *   redirect target BEFORE any request is sent to it, and a throw ABORTS the
+ *   whole exchange (an off-contract hop is treated as the attack, never
+ *   silently stripped-and-followed). This is how allowlist-scoped callers
+ *   (credential proxy `authorized_uris`) extend their allowlist to the full
+ *   redirect chain instead of only the initial URL.
+ * - Strips credential headers on any cross-origin hop: the builtin
+ *   `authorization`/`cookie`/`proxy-authorization` set UNIONED with the
+ *   caller's `sensitiveHeaders` (vendor-specific names like `X-Api-Key` that
+ *   the primitive cannot know about).
  * - Rejects non-http(s) schemes and strips userinfo/fragment from redirect
  *   targets (defeats `https://user:pass@…` credential-leak + fragment tricks).
+ * - CONNECTS TO THE VALIDATED ADDRESS: under Bun with the global `fetch`, each
+ *   hop's request goes to the `pinnedAddress` returned by the guard (URL host
+ *   rewritten to the resolved IP) while the logical `Host` header and the TLS
+ *   SNI + certificate identity (`tls.serverName`) are preserved. The OS never
+ *   re-resolves the name at connect time, so the classic check-then-fetch
+ *   DNS-rebind TOCTOU is closed, not merely narrowed.
  *
- * Residual: like the platform's other `fetch`-delegating guards, the OS
- * re-resolves the name when `fetch` actually connects, leaving a documented
- * narrow TOCTOU window. Consumers that own the socket (sidecar egress
- * listeners) pin `pinnedAddress` to fully close it; this primitive is for the
- * many `fetch`-based callers that cannot, and is strictly stronger than the
- * literal-only or unguarded status quo it replaces.
+ * The address pin falls back to a name-based connect (re-opening the
+ * documented, narrow re-resolve TOCTOU — still guarded per hop) in exactly
+ * these cases:
+ * - a caller-injected `fetchImpl` (the seam owns its own transport; Bun's
+ *   `tls`/URL-rewrite contract cannot be assumed),
+ * - a non-Bun runtime (no `fetch` `tls.serverName` extension to preserve SNI —
+ *   pinning without it would break certificate validation),
+ * - an operator-trusted host via `allowHost` (blocklist and resolution are
+ *   skipped by design, there is nothing to pin),
+ * - an IP-literal URL (already its own pin; nothing to rebind).
  *
  * Lives in the leaf `@appstrate/afps-shared` (re-exported by
  * `@appstrate/core/ssrf`) so the platform, sidecar, connect and the standalone
@@ -52,7 +74,8 @@ export interface GuardedFetchOptions {
    * (e.g. `login-engine`'s `ctx.fetchImpl`). Production omits it and the global
    * `fetch` is used. Routing an injected fetch THROUGH this primitive keeps the
    * per-hop DNS guard, cross-origin credential/body stripping and scheme checks
-   * that a bare `fetchImpl` call would lose.
+   * that a bare `fetchImpl` call would lose. NOTE: an injected fetch disables
+   * the address pin (see module doc) — the seam owns the connection.
    */
   fetchImpl?: typeof fetch;
   /**
@@ -63,12 +86,53 @@ export interface GuardedFetchOptions {
    * applies — so a trusted host that open-redirects cannot forward the secret.
    */
   allowHost?: (host: string) => boolean;
+  /**
+   * Set to `false` to disable connecting to the DNS-validated address and
+   * connect by name instead (per-hop guard still runs). Default: pin whenever
+   * the runtime supports it. The only known reason to disable is an egress
+   * HTTP proxy whose ACLs match on hostname rather than IP.
+   */
+  pinToResolvedAddress?: boolean;
+  /**
+   * Caller-owned per-hop reachability contract. Called for EVERY hop —
+   * INCLUDING hop 0 — with the logical (userinfo/fragment-stripped) URL,
+   * BEFORE any request is sent to that URL and before DNS resolution.
+   * Throw to abort the entire exchange: an off-contract redirect target must
+   * kill the request, not be followed with stripped credentials — for
+   * allowlist-scoped callers the allowlist IS the security boundary and a
+   * hop that leaves it is the attack. The thrown error propagates to the
+   * caller unwrapped, so callers keep their own error taxonomy and redaction
+   * (do NOT embed secrets in the message — the hop URL itself may carry an
+   * interpolated credential; redact before throwing).
+   */
+  validateHop?: (url: URL, hop: number) => void;
+  /**
+   * Additional header names (case-insensitive) treated as credentials for
+   * cross-origin redirect stripping. UNIONED with the builtin
+   * `authorization`/`cookie`/`proxy-authorization` set — never a
+   * replacement. Callers that inject vendor-specific credential headers
+   * (`X-Api-Key`, `X-Auth-Token`, …) MUST list them here, or a cross-origin
+   * redirect would carry them to the new origin.
+   */
+  sensitiveHeaders?: readonly string[];
   /** Structured logger for blocked/hop events. Values are never secrets. */
   logger?: { warn: (msg: string, meta?: Record<string, unknown>) => void };
 }
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
+/**
+ * Bun extends `fetch` with a per-request `tls` option (`serverName`,
+ * `checkServerIdentity`, …). The address pin depends on `tls.serverName` to
+ * keep SNI + certificate identity on the logical hostname while the TCP
+ * connection goes to the pinned IP — without it, pinning an https URL would
+ * fail certificate validation, so on other runtimes we fall back to a
+ * name-based connect. Verified against Bun 1.3.x: `tls.serverName` drives
+ * both the emitted SNI and the identity check (a mismatching serverName
+ * fails with ERR_TLS_CERT_ALTNAME_INVALID).
+ */
+const runtimeSupportsFetchTls = (globalThis as { Bun?: unknown }).Bun !== undefined;
+
 export class SsrfBlockedError extends Error {
   readonly reason: string;
   readonly host: string;
@@ -94,8 +158,13 @@ function stripUserInfoAndFragment(url: URL): URL {
   return clean;
 }
 
-async function checkHost(url: URL, opts?: GuardedFetchOptions): Promise<void> {
-  if (opts?.allowHost?.(url.hostname)) return; // operator-trusted host — skip blocklist
+/**
+ * Run the per-hop host guard. Returns the address the hop MUST connect to,
+ * or `undefined` when there is nothing to pin (operator-trusted host).
+ * Throws {@link SsrfBlockedError} on a blocked host (fail closed).
+ */
+async function checkHost(url: URL, opts?: GuardedFetchOptions): Promise<string | undefined> {
+  if (opts?.allowHost?.(url.hostname)) return undefined; // operator-trusted host — skip blocklist
   const check = await resolveAndCheckHost(url.hostname, { resolve: opts?.resolve });
   if (check.blocked) {
     opts?.logger?.warn("guardedFetch blocked host", {
@@ -104,13 +173,15 @@ async function checkHost(url: URL, opts?: GuardedFetchOptions): Promise<void> {
     });
     throw new SsrfBlockedError(url.hostname, check.reason);
   }
+  return check.pinnedAddress;
 }
 
 /**
- * SSRF-guarded `fetch` with per-hop DNS re-checking. Signature-compatible with
- * `fetch` for the common `(url, init)` call shape. Manual redirect handling
- * means any `init.redirect` is ignored (always treated as "manual" internally);
- * the returned `Response` is the first non-3xx response.
+ * SSRF-guarded `fetch` with per-hop DNS re-checking and (under Bun) a real
+ * connection pin to the validated address. Signature-compatible with `fetch`
+ * for the common `(url, init)` call shape. Manual redirect handling means any
+ * `init.redirect` is ignored (always treated as "manual" internally); the
+ * returned `Response` is the first non-3xx response.
  */
 export async function guardedFetch(
   input: string | URL,
@@ -121,7 +192,10 @@ export async function guardedFetch(
 
   let current = stripUserInfoAndFragment(new URL(typeof input === "string" ? input : input.href));
   assertHttp(current);
-  await checkHost(current, opts);
+  // Hop 0 runs the caller's reachability contract too — the initial URL is
+  // just the first hop of the chain, not a privileged one.
+  opts?.validateHop?.(current, 0);
+  let pinnedAddress = await checkHost(current, opts);
 
   // Apply a default deadline when the caller supplied no signal of its own, so
   // a single hostile hop cannot hang forever. A caller-provided signal takes
@@ -150,7 +224,23 @@ export async function guardedFetch(
   // credential headers (browser behaviour) so a `302 → other-host` cannot
   // forward the caller's `Authorization`/`Cookie` to a different origin — even
   // when that origin is a legitimate public host the SSRF host-check allows.
+  // The strip set is the builtin trio UNIONED with the caller-declared
+  // `sensitiveHeaders` (vendor-specific credential names the primitive cannot
+  // know, e.g. an injected `X-Api-Key`).
   const headers = new Headers(init?.headers ?? {});
+  const sensitiveHeaderNames = new Set(["authorization", "cookie", "proxy-authorization"]);
+  for (const h of opts?.sensitiveHeaders ?? []) sensitiveHeaderNames.add(h.toLowerCase());
+  // A caller-supplied Host header is honoured only on the first, unpinned hop
+  // (a virtual-host override for the URL the caller chose). On every later or
+  // pinned hop the logical URL owns the Host value.
+  const callerSetHost = headers.has("host");
+
+  // The address pin requires owning the socket semantics: Bun's `fetch` `tls`
+  // extension AND the global fetch (an injected transport seam cannot be
+  // assumed to honour either the URL rewrite or the tls option).
+  const pinningEnabled =
+    runtimeSupportsFetchTls && !opts?.fetchImpl && opts?.pinToResolvedAddress !== false;
+  const callerTls = (init as { tls?: Record<string, unknown> } | undefined)?.tls;
 
   // Drop the request body and the headers that describe it — used both for
   // the standard 303/301/302 → GET rewrite and for the cross-host secret
@@ -163,15 +253,39 @@ export async function guardedFetch(
 
   try {
     for (let hop = 0; hop <= maxRedirects; hop++) {
+      // Pin the hop: connect to the validated address, keep the logical
+      // hostname on the wire (`Host` header) and in the TLS handshake
+      // (`tls.serverName` → SNI + certificate identity). `current` stays the
+      // LOGICAL URL — redirect resolution and origin comparisons never see
+      // the pinned form.
+      const bareHost = current.hostname.replace(/^\[|\]$/g, "");
+      const pin = pinnedAddress;
+      const applyPin = pinningEnabled && pin !== undefined && pin !== bareHost;
+      let requestUrl = current;
+      let tlsOverride: Record<string, unknown> | undefined;
+      if (applyPin) {
+        requestUrl = new URL(current.toString());
+        requestUrl.hostname = pin.includes(":") ? `[${pin}]` : pin;
+        headers.set("host", current.host);
+        if (current.protocol === "https:") {
+          tlsOverride = { ...(callerTls ?? {}), serverName: current.hostname };
+        }
+      } else if (!(hop === 0 && callerSetHost)) {
+        // Unpinned hop: let the runtime derive Host from the URL — a Host
+        // value pinned for a previous hop must not leak onto this one.
+        headers.delete("host");
+      }
+
       const doFetch = opts?.fetchImpl ?? fetch;
-      const res = await doFetch(current, {
+      const res = await doFetch(requestUrl, {
         ...init,
         method,
         body,
         headers,
         signal,
         redirect: "manual",
-      });
+        ...(tlsOverride ? { tls: tlsOverride } : {}),
+      } as RequestInit);
 
       // `fetch` reports opaqueredirect / 3xx: follow manually so each hop is guarded.
       const isRedirect = res.status >= 300 && res.status < 400 && res.headers.has("location");
@@ -184,10 +298,15 @@ export async function guardedFetch(
       const location = res.headers.get("location")!;
       const next = stripUserInfoAndFragment(new URL(location, current));
       assertHttp(next);
-      await checkHost(next, opts);
+      // Caller's reachability contract FIRST (cheap, sync, fail-closed): an
+      // off-contract hop aborts the exchange before we even resolve it. A
+      // same-origin redirect can walk off an allowlisted PATH while keeping
+      // every header and the body — only the caller's predicate can see that.
+      opts?.validateHop?.(next, hop + 1);
+      const nextPin = await checkHost(next, opts);
 
       if (next.origin !== current.origin) {
-        for (const h of ["authorization", "cookie", "proxy-authorization"]) headers.delete(h);
+        for (const h of sensitiveHeaderNames) headers.delete(h);
         // A 307/308 preserves method+body by spec, but re-sending a
         // secret-bearing request body (OAuth `client_secret`/`refresh_token`,
         // a signed webhook payload) to a DIFFERENT HOST is the same
@@ -198,8 +317,17 @@ export async function guardedFetch(
         // IdPs) keeps the body, matching browser 307/308 behaviour; the one
         // same-host case still dropped is an https→http DOWNGRADE, which
         // would re-send the secret in cleartext.
+        //
+        // When the caller declared a `validateHop` contract the request is a
+        // credential-bearing exchange by definition (that is why the caller
+        // scoped it), so belt-and-braces: ANY origin change drops the body,
+        // including the same-host scheme/port cases kept above.
         const schemeDowngrade = current.protocol === "https:" && next.protocol === "http:";
-        if (body !== undefined && (next.hostname !== current.hostname || schemeDowngrade)) {
+        const hasHopContract = opts?.validateHop !== undefined;
+        if (
+          body !== undefined &&
+          (next.hostname !== current.hostname || schemeDowngrade || hasHopContract)
+        ) {
           opts?.logger?.warn("guardedFetch dropped request body on cross-host redirect", {
             status: res.status,
             fromHost: current.hostname,
@@ -218,6 +346,7 @@ export async function guardedFetch(
         dropBody();
       }
       current = next;
+      pinnedAddress = nextPin;
       // Drain the redirect response body so the connection can be reused.
       await res.body?.cancel().catch(() => {});
     }

package/src/mcp-naming.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Appstrate
+
+/** Appstrate's MCP tool-name ceiling, including the namespace. */
+export const MCP_TOOL_NAME_MAX_LENGTH = 56;
+
+/** Maximum namespace length before McpHost adds an optional `_2`…`_999`. */
+export const MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH = 20;
+
+/**
+ * Canonical namespace normalisation shared by McpHost and the portable AFPS
+ * runtime. Package ids such as `@appstrate/google-drive` become a lowercase
+ * snake-case namespace capped before collision suffixing.
+ */
+export function normaliseMcpToolNamespace(raw: string): string {
+  if (typeof raw !== "string") return "";
+  const out = trimUnderscores(
+    raw
+      .replace(/^@/, "")
+      .replace(/[^a-zA-Z0-9]+/g, "_")
+      .toLowerCase(),
+  );
+  return out.slice(0, MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH);
+}
+
+/**
+ * Canonicalise an untrusted upstream tool body before adding our namespace.
+ * An upstream namespace is stripped so `drive__api-call` becomes `api_call`,
+ * matching McpHost's outward naming contract.
+ */
+export function normaliseMcpToolBody(raw: string): string {
+  if (typeof raw !== "string") return "";
+  let out = trimUnderscores(raw.replace(/[^a-zA-Z0-9_]+/g, "_").toLowerCase());
+  const separator = out.indexOf("__");
+  if (separator >= 0 && separator < out.length - 2) {
+    out = out.slice(separator + 2);
+  }
+  return out;
+}
+
+/** Trim underscore runs in linear time without a backtracking expression. */
+function trimUnderscores(value: string): string {
+  let start = 0;
+  while (start < value.length && value.charCodeAt(start) === 95) start += 1;
+  let end = value.length;
+  while (end > start && value.charCodeAt(end - 1) === 95) end -= 1;
+  return value.slice(start, end);
+}
+
+/** Allocate the same `_2`…`_999` namespace suffix used by McpHost. */
+export function allocateMcpToolNamespace(base: string, used: ReadonlySet<string>): string {
+  if (!used.has(base)) return base;
+  for (let suffix = 2; suffix < 1000; suffix += 1) {
+    const candidate = `${base}_${suffix}`;
+    if (!used.has(candidate)) return candidate;
+  }
+  throw new Error(`exhausted MCP namespace suffixes for ${JSON.stringify(base)}`);
+}

package/src/signed-token.ts

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Keyring-HMAC capability tokens — the ONE codec behind every short-lived,
+ * URL-carried capability the platform mints (filesystem/proxy upload URLs,
+ * document previews, hosted connect sessions).
+ *
+ * Wire format: `base64url(JSON payload).base64url(HMAC-SHA256)`.
+ *
+ * Two properties are load-bearing and were previously re-implemented (and
+ * drifted) per token type:
+ *
+ *  - **Keyring rotation.** A secret is a comma-separated list (or an array):
+ *    the FIRST key signs new tokens, ALL keys verify, so a rotation never
+ *    invalidates tokens already in flight. Individual keys must therefore not
+ *    contain commas.
+ *  - **Domain separation.** {@link signKeyringToken} takes the domain as its
+ *    FIRST, REQUIRED argument and mixes it into the signed content, so a token
+ *    minted for one purpose can never be verified as another — including when
+ *    two token types share a signing secret (upload URLs and document previews
+ *    both key off `UPLOAD_SIGNING_SECRET`). Making the parameter mandatory is
+ *    the point: an optional domain is a domain someone forgets, and the
+ *    resulting protection is one-directional — exactly the asymmetry this
+ *    module replaces.
+ *
+ * Deliberately NOT part of the codec: expiry and claim validation. Every token
+ * type names its expiry field differently and enforces its own required
+ * claims, so {@link verifyKeyringToken} returns the decoded payload after the
+ * signature check and leaves semantics to the caller.
+ *
+ * Zero-dependency leaf so `@appstrate/core` (storage), the platform API
+ * (document previews) and `@appstrate/connect` (hosted connect sessions) can
+ * all sit above it without a cycle.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Normalize a signing secret into a keyring. A plain string is split on commas
+ * (rotation: prepend the new key); empty segments are dropped.
+ */
+export function toKeyring(secret: string | readonly string[]): string[] {
+  const keys = typeof secret === "string" ? secret.split(",") : [...secret];
+  return keys.filter((k) => k.length > 0);
+}
+
+/**
+ * Encode + HMAC-sign a payload with the FIRST key of the keyring, binding the
+ * signature to `domain`. Throws when the keyring holds no usable key.
+ *
+ * `domain` is a short, stable, versioned literal (`"doc-preview.v1."`) — change
+ * it and every token already in flight stops verifying.
+ */
+export function signKeyringToken(
+  domain: string,
+  payload: unknown,
+  secret: string | readonly string[],
+): string {
+  const [activeKey] = toKeyring(secret);
+  if (!activeKey) throw new Error("signKeyringToken requires at least one signing key");
+  const body = Buffer.from(JSON.stringify(payload), "utf-8").toString("base64url");
+  const sig = createHmac("sha256", activeKey)
+    .update(domain + body)
+    .digest("base64url");
+  return `${body}.${sig}`;
+}
+
+/**
+ * Verify a token against `domain` and decode its payload. Returns null on any
+ * failure (malformed shape, wrong/absent signature, non-JSON body) — never
+ * throws. Verifies against EVERY key of the keyring (constant-time comparison
+ * per key) so tokens signed before a rotation stay valid.
+ *
+ * The returned value is the raw decoded JSON cast to `T`: the signature proves
+ * WE minted it, not that its fields are the ones the caller expects. Callers
+ * validate expiry + required claims themselves.
+ */
+export function verifyKeyringToken<T>(
+  domain: string,
+  token: string,
+  secret: string | readonly string[],
+): T | null {
+  const dot = token.indexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+  const a = Buffer.from(sig);
+  let valid = false;
+  for (const key of toKeyring(secret)) {
+    const b = Buffer.from(
+      createHmac("sha256", key)
+        .update(domain + body)
+        .digest("base64url"),
+    );
+    if (a.length === b.length && timingSafeEqual(a, b)) {
+      valid = true;
+      break;
+    }
+  }
+  if (!valid) return null;
+  try {
+    return JSON.parse(Buffer.from(body, "base64url").toString("utf-8")) as T;
+  } catch {
+    return null;
+  }
+}

package/src/ssrf-dns.ts

@@ -7,12 +7,13 @@
  * `isBlockedHost` alone is literal-only: a DNS name whose A/AAAA record
  * points at an internal address (10.x, 169.254.169.254, …) passes it, and
  * a consumer that re-resolves the name at connect time is open to a
- * DNS-rebind bypass. Consumers that control the raw connection (sidecar
- * egress listeners) close that gap fully by connecting to the returned
- * `pinnedAddress`; consumers that delegate the connection to `fetch`
- * (platform CIMD guard, MITM upstream, credential proxy, CLI api_call
- * engine) use it as fail-closed defence-in-depth with a documented
- * residual TOCTOU.
+ * DNS-rebind bypass. Consumers that control the connection close that gap
+ * fully by connecting to the returned `pinnedAddress`: sidecar egress
+ * listeners own the raw socket, and `guardedFetch` (./guarded-fetch.ts)
+ * rewrites the request URL to the pin while preserving Host + TLS SNI
+ * (Bun). A consumer that instead delegates the connection to a plain
+ * name-based `fetch` only gets fail-closed defence-in-depth with a
+ * residual re-resolve TOCTOU — prefer `guardedFetch`.
  *
  * Kept in its own subpath (not `./ssrf`) so the literal module stays free
  * of node builtins — this module needs `node:dns` + `node:net` and is

package/src/unzip-bounded.ts

@@ -27,10 +27,7 @@
 import { Unzip, UnzipInflate } from "fflate";
 
 export type DecompressionLimitReason =
-  | "decompressed-budget-exceeded"
-  | "file-too-large"
-  | "too-many-files"
-  | "corrupt-archive";
+  "decompressed-budget-exceeded" | "file-too-large" | "too-many-files" | "corrupt-archive";
 
 export class DecompressionLimitError extends Error {
   readonly reason: DecompressionLimitReason;