@appstrate/afps-shared 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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,19 @@
     "./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"
+    "./token-usage": "./src/token-usage.ts",
+    "./ssrf-dns": "./src/ssrf-dns.ts",
+    "./guarded-fetch": "./src/guarded-fetch.ts",
+    "./unzip-bounded": "./src/unzip-bounded.ts",
+    "./backoff": "./src/backoff.ts"
   },
   "dependencies": {
-    "semver": "^7.7.1"
+    "fflate": "^0.8.3",
+    "semver": "^7.8.4"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1"

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/backoff.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared retry primitives for the isolated runtime packages
+ * (`afps-runtime` sinks, `runtime-pi` provisioning). One place for the
+ * exponential-backoff arithmetic and the "is this HTTP status worth
+ * retrying" rule, so the policies can't silently drift between copies.
+ *
+ * Deliberately NOT adopted by `mcp-transport` (deadline-clamped full
+ * jitter interwoven with its abort handling) or the CLI's `api retry`
+ * (curl semantics: `Retry-After` honouring, 408 in the retryable set) —
+ * those are different, documented policies, not duplicates.
+ */
+
+export interface BackoffOptions {
+  /** Delay before the second attempt (attempt 1 retry), in ms. */
+  baseMs: number;
+  /** Upper bound on the exponential term, in ms. */
+  capMs: number;
+  /**
+   * Additive jitter as a fraction of the (capped) exponential delay:
+   * `0.25` adds up to +25%. Defaults to 0 (no jitter).
+   */
+  jitterRatio?: number;
+  /** Injectable RNG for deterministic tests. Defaults to `Math.random`. */
+  random?: () => number;
+}
+
+/**
+ * Exponential backoff delay for a 1-based retry `attempt`:
+ * `min(baseMs * 2^(attempt-1), capMs)` plus optional additive jitter.
+ */
+export function computeBackoffDelayMs(attempt: number, opts: BackoffOptions): number {
+  const exp = Math.min(opts.baseMs * 2 ** (Math.max(1, attempt) - 1), opts.capMs);
+  const jitter = exp * (opts.jitterRatio ?? 0) * (opts.random ?? Math.random)();
+  return Math.floor(exp + jitter);
+}
+
+/**
+ * Transient-failure rule shared by the runtime HTTP paths: 5xx (upstream
+ * fault) and 429 (throttled) are retryable; any other status is a
+ * deterministic outcome that retrying cannot fix.
+ */
+export function isRetryableHttpStatus(status: number): boolean {
+  return status >= 500 || status === 429;
+}

package/src/delivery-http.ts

@@ -26,10 +26,9 @@
  */
 
 /**
- * Structural subset of the resolver config consumed by
- * `resolveHttpDelivery` (`@appstrate/afps-runtime/resolvers`). Declared here
- * structurally so this zero-dep package does not depend on afps-runtime; the
- * shapes are structurally compatible.
+ * Resolver config consumed by `resolveHttpDelivery`
+ * (`@appstrate/afps-runtime/resolvers`). This zero-dep package is the single
+ * source of truth for the shape; afps-runtime re-exports it.
  */
 export interface HttpDeliveryConfig {
   headerName?: string;

package/src/file-field.ts

@@ -0,0 +1,63 @@
+// Copyright 2025-2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Canonical AFPS file-field predicate — the SINGLE source of truth shared by
+ * `@appstrate/core/form` (apps/web SchemaForm, apps/api) and
+ * `@appstrate/afps-runtime`'s platform-prompt composer.
+ *
+ * AFPS file fields are JSON Schema string nodes carrying `format: "uri"` plus a
+ * `contentMediaType` (single file), or an array whose `items` are such nodes
+ * (multiple files) — NEVER `type: "file"` (AFPS §3.4). The rule deliberately
+ * does NOT require `type === "string"` on the single-field branch: that
+ * preserves the historical observable behaviour of `@appstrate/core/form`'s
+ * `isFileField` (its widest consumer set), and AFPS file fields are strings
+ * anyway so the looser check is sound.
+ *
+ * Accepts a permissive `unknown` input narrowed internally so both the
+ * JSONSchema7-typed core call site and the `unknown`-typed runtime call site
+ * compile against one definition.
+ */
+
+/** A single file field: `format: "uri"` + a `contentMediaType`. */
+function isSingleFileNode(node: Record<string, unknown>): boolean {
+  return node.format === "uri" && node.contentMediaType != null && node.contentMediaType !== false;
+}
+
+/**
+ * Resolve a node's `items` schema, handling the JSON Schema boolean / tuple
+ * forms (`items: false` → none; `items: [first, …]` → first object entry).
+ */
+function resolveItems(node: Record<string, unknown>): Record<string, unknown> | undefined {
+  const items = node.items;
+  if (!items || typeof items === "boolean") return undefined;
+  if (Array.isArray(items)) {
+    const first = items[0];
+    return first && typeof first === "object" ? (first as Record<string, unknown>) : undefined;
+  }
+  if (typeof items === "object") return items as Record<string, unknown>;
+  return undefined;
+}
+
+function resolveType(node: Record<string, unknown>): string | undefined {
+  if (typeof node.type === "string") return node.type;
+  if (Array.isArray(node.type) && node.type.length > 0 && typeof node.type[0] === "string") {
+    return node.type[0];
+  }
+  return undefined;
+}
+
+/**
+ * Detect an AFPS file field: a single string-URI node with `contentMediaType`,
+ * OR an array whose items are such a node.
+ */
+export function isFileField(schema: unknown): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const node = schema as Record<string, unknown>;
+  if (isSingleFileNode(node)) return true;
+  if (resolveType(node) === "array") {
+    const items = resolveItems(node);
+    if (items && isSingleFileNode(items)) return true;
+  }
+  return false;
+}

package/src/guarded-fetch.ts

@@ -0,0 +1,359 @@
+// Copyright 2025-2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * `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,
+ * credential-proxy targets).
+ *
+ * Two SSRF guards historically coexisted in this codebase: the literal
+ * `isBlockedUrl` (string-only, no DNS) and the DNS-rebind-safe
+ * `resolveAndCheckHost`. Several outbound surfaces got only the literal guard —
+ * or none — so a public hostname whose A record points at 169.254.169.254 (or
+ * a `302` to such a name) sailed through. This helper closes that class:
+ *
+ * - 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.
+ *
+ * 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
+ * `afps` runtime can all share ONE implementation.
+ */
+
+import { resolveAndCheckHost, type HostResolver } from "./ssrf-dns.ts";
+
+export interface GuardedFetchOptions {
+  /** Max redirect hops to follow before giving up. Default 5. */
+  maxRedirects?: number;
+  /**
+   * Deadline in ms covering the redirect chain up to the final response's
+   * HEADERS, applied when the caller passes no `init.signal`. A hostile host
+   * must not be able to hold a hop open indefinitely (slowloris) just because
+   * a caller forgot a timeout, so the safe default lives in the primitive.
+   * Consuming the returned body is NOT covered — the timer is detached once
+   * the response is returned, so slow-but-healthy body reads are never
+   * aborted. Default 30_000. Set to 0 to disable.
+   */
+  timeoutMs?: number;
+  /** Injectable resolver for tests. Production omits it. */
+  resolve?: HostResolver;
+  /**
+   * Injectable `fetch` for tests / callers that already own a transport seam
+   * (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. NOTE: an injected fetch disables
+   * the address pin (see module doc) — the seam owns the connection.
+   */
+  fetchImpl?: typeof fetch;
+  /**
+   * Opt-in predicate for hosts the OPERATOR has explicitly trusted (e.g. an
+   * internal IdP on a private address via `OAUTH_ALLOWED_INTERNAL_IDP_HOSTS`).
+   * When it returns true the host blocklist is skipped for that hop, but the
+   * manual-redirect discipline (cross-origin body/credential stripping) still
+   * 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;
+  constructor(host: string, reason: string) {
+    super(`SSRF guard blocked outbound request to host "${host}" (${reason})`);
+    this.name = "SsrfBlockedError";
+    this.host = host;
+    this.reason = reason;
+  }
+}
+
+function assertHttp(url: URL): void {
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new SsrfBlockedError(url.hostname || url.protocol, "non-http-scheme");
+  }
+}
+
+function stripUserInfoAndFragment(url: URL): URL {
+  const clean = new URL(url.toString());
+  clean.username = "";
+  clean.password = "";
+  clean.hash = "";
+  return clean;
+}
+
+/**
+ * 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", {
+      host: url.hostname,
+      reason: check.reason,
+    });
+    throw new SsrfBlockedError(url.hostname, check.reason);
+  }
+  return check.pinnedAddress;
+}
+
+/**
+ * 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,
+  init?: RequestInit,
+  opts?: GuardedFetchOptions,
+): Promise<Response> {
+  const maxRedirects = opts?.maxRedirects ?? 5;
+
+  let current = stripUserInfoAndFragment(new URL(typeof input === "string" ? input : input.href));
+  assertHttp(current);
+  // 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
+  // precedence (it already encodes the caller's own timeout policy). The timer
+  // is cleared once the final response's HEADERS have arrived — it must not
+  // stay attached to the returned body stream, or a caller reading a slow but
+  // healthy body past the deadline gets aborted mid-transfer.
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let signal = init?.signal ?? undefined;
+  if (!signal && timeoutMs > 0) {
+    const deadline = new AbortController();
+    deadlineTimer = setTimeout(
+      () =>
+        deadline.abort(
+          new DOMException(`guardedFetch deadline of ${timeoutMs}ms exceeded`, "TimeoutError"),
+        ),
+      timeoutMs,
+    );
+    signal = deadline.signal;
+  }
+
+  let method = (init?.method ?? "GET").toUpperCase();
+  let body = init?.body;
+  // Mutable header set for the chain. On a CROSS-ORIGIN redirect we drop the
+  // 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
+  // containment below, so the two sites cannot drift (a body-less request
+  // carrying a stale Content-Type/Content-Length confuses strict upstreams).
+  const dropBody = () => {
+    body = undefined;
+    for (const h of ["content-type", "content-length", "content-encoding"]) headers.delete(h);
+  };
+
+  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(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");
+      if (!isRedirect) return res;
+
+      if (hop === maxRedirects) {
+        throw new SsrfBlockedError(current.hostname, "too-many-redirects");
+      }
+
+      const location = res.headers.get("location")!;
+      const next = stripUserInfoAndFragment(new URL(location, current));
+      assertHttp(next);
+      // 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 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
+        // credential-leak class as forwarding the `Authorization` header —
+        // and header-stripping alone does not cover it. The boundary is the
+        // HOST, not the origin: a same-host scheme/port upgrade (http→https
+        // behind a TLS-terminating proxy — routine for allowlisted internal
+        // 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:";
+        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,
+            toHost: next.hostname,
+            downgrade: schemeDowngrade,
+          });
+          dropBody();
+        }
+      }
+
+      // Standard redirect method/body rewriting: 303 (and 301/302 for POST per
+      // browser convention) → GET with no body; 307/308 preserve method + body
+      // (already dropped above when crossing a host boundary).
+      if (res.status === 303 || ((res.status === 301 || res.status === 302) && method !== "HEAD")) {
+        method = method === "HEAD" ? "HEAD" : "GET";
+        dropBody();
+      }
+      current = next;
+      pinnedAddress = nextPin;
+      // Drain the redirect response body so the connection can be reused.
+      await res.body?.cancel().catch(() => {});
+    }
+  } finally {
+    if (deadlineTimer !== undefined) clearTimeout(deadlineTimer);
+  }
+
+  // Unreachable — loop either returns or throws.
+  throw new SsrfBlockedError(current.hostname, "redirect-loop");
+}

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/ssrf-dns.ts

@@ -0,0 +1,104 @@
+// Copyright 2025-2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * DNS-resolving layer over the literal SSRF blocklist (`./ssrf`).
+ *
+ * `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 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
+ * server-side only. Re-exported verbatim by `@appstrate/core/ssrf` and
+ * consumed directly by `@appstrate/afps-runtime` (which cannot depend on
+ * core — it ships standalone with the `afps` CLI).
+ */
+
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+import { isBlockedHost } from "./ssrf.ts";
+
+/**
+ * Resolve a hostname to its IP addresses. Injectable so tests can exercise
+ * the resolution branch deterministically without real DNS. Production uses
+ * `node:dns/promises` `lookup` (honours the system resolver + `/etc/hosts`).
+ */
+export type HostResolver = (hostname: string) => Promise<string[]>;
+
+export const defaultHostResolver: HostResolver = async (hostname) => {
+  const records = await lookup(hostname, { all: true });
+  return records.map((r) => r.address);
+};
+
+export type ResolvedHostCheck =
+  | { blocked: false; pinnedAddress: string }
+  | {
+      blocked: true;
+      reason: "blocked-literal" | "blocked-resolved" | "resolution-failed";
+      /** Human-readable detail for logs (resolution error message). Never a secret. */
+      detail?: string;
+    };
+
+/**
+ * DNS-rebind-safe host check. Never throws; fails closed.
+ *
+ * - IP literals: checked against the literal blocklist, returned as their own
+ *   `pinnedAddress` (no DNS round-trip).
+ * - DNS names: literal blocklist first (known-internal names), then EVERY
+ *   resolved A/AAAA record is checked — if ANY lands in a blocked range, or
+ *   resolution fails / returns nothing, the host is refused.
+ * - On success, `pinnedAddress` is one resolved address (IPv4 preferred) the
+ *   caller MUST connect to directly — connecting by name would re-resolve and
+ *   reopen the rebind window.
+ *
+ * `deps.resolve` injects a resolver for tests; `deps.isBlockedHostFn` lets
+ * callers that already take an injectable blocklist predicate thread it
+ * through. Production callers pass neither.
+ */
+export async function resolveAndCheckHost(
+  host: string,
+  deps?: { resolve?: HostResolver; isBlockedHostFn?: typeof isBlockedHost },
+): Promise<ResolvedHostCheck> {
+  const isBlockedHostFn = deps?.isBlockedHostFn ?? isBlockedHost;
+  // `URL.hostname` / CONNECT targets may carry IPv6 brackets — strip for
+  // uniform handling (`isBlockedHost` normalizes internally either way).
+  const bare = host.replace(/^\[|\]$/g, "");
+
+  // Literal floor — IP literals and known-internal hostnames.
+  if (isBlockedHostFn(bare)) return { blocked: true, reason: "blocked-literal" };
+
+  // IP literal: nothing to resolve — pin the literal itself.
+  if (isIP(bare) !== 0) return { blocked: false, pinnedAddress: bare };
+
+  const resolve = deps?.resolve ?? defaultHostResolver;
+  let addresses: string[];
+  try {
+    addresses = await resolve(bare);
+  } catch (err) {
+    return {
+      blocked: true,
+      reason: "resolution-failed",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+  if (addresses.length === 0) {
+    // No address → nothing legitimate to reach (fail closed).
+    return { blocked: true, reason: "resolution-failed", detail: "no addresses resolved" };
+  }
+  if (addresses.some((addr) => isBlockedHostFn(addr))) {
+    return { blocked: true, reason: "blocked-resolved" };
+  }
+  // Prefer an IPv4 answer for the pin — pinning a AAAA record on a host
+  // without IPv6 egress would regress connectivity that name-based connects
+  // (which try both families) used to have.
+  const pinnedAddress = addresses.find((addr) => isIP(addr) === 4) ?? addresses[0]!;
+  return { blocked: false, pinnedAddress };
+}

package/src/ssrf.ts

@@ -53,12 +53,20 @@ export function isBlockedHost(hostname: string): boolean {
   if (ipv4Match) {
     const a = parseInt(ipv4Match[1]!, 10);
     const b = parseInt(ipv4Match[2]!, 10);
+    const c = parseInt(ipv4Match[3]!, 10);
     if (a === 0) return true; // 0.0.0.0/8
     if (a === 10) return true; // 10.0.0.0/8
     if (a === 127) return true; // 127.0.0.0/8 (full loopback range)
     if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
     if (a === 192 && b === 168) return true; // 192.168.0.0/16
     if (a === 169 && b === 254) return true; // 169.254.0.0/16 (link-local)
+    // 100.64.0.0/10 — RFC 6598 shared/CGN space. Alibaba & Tencent Cloud expose
+    // instance metadata at 100.100.100.200, and K8s/CGN route internal traffic
+    // here; without this the whole cloud-metadata SSRF class stays open.
+    if (a === 100 && b >= 64 && b <= 127) return true;
+    if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 (benchmark)
+    if (a === 192 && b === 0 && c === 0) return true; // 192.0.0.0/24 (IETF protocol assignments)
+    if (a >= 224) return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255
     return false;
   }
 
@@ -88,13 +96,37 @@ export function isBlockedHost(hostname: string): boolean {
     if (mappedDot) {
       return isBlockedHost(mappedDot[1]!);
     }
+
+    // IPv4-compatible IPv6 (deprecated but still routed by some stacks): the
+    // low 32 bits embed an IPv4 with NO `::ffff:` prefix — ::7f00:1 = 127.0.0.1,
+    // ::a9fe:a9fe = 169.254.169.254. Without this branch these slip past the
+    // IPv4 blocklist entirely. (`::ffff:H:L` mapped form is matched above and
+    // won't collide — it carries three hextets, not two.)
+    const compatHex = h.match(/^::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (compatHex) {
+      const high = parseInt(compatHex[1]!, 16);
+      const low = parseInt(compatHex[2]!, 16);
+      const ipv4 = `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+      return isBlockedHost(ipv4);
+    }
+    const compatDot = h.match(/^::(\d+\.\d+\.\d+\.\d+)$/);
+    if (compatDot) {
+      return isBlockedHost(compatDot[1]!);
+    }
   }
 
   return false;
 }
 
-/** Block requests to private/internal networks. Prevents SSRF to cloud metadata, localhost, etc. */
-export function isBlockedUrl(url: string): boolean {
+/**
+ * Block requests to private/internal networks. Prevents SSRF to cloud
+ * metadata, localhost, etc. `allowHost` (optional) exempts an
+ * operator-trusted hostname from the HOST blocklist only — malformed URLs
+ * and non-http(s) schemes stay fail-closed regardless, so every
+ * allowlist-aware consumer (platform egress sites, sidecar gates) shares
+ * this one parse/scheme/blocklist body instead of re-implementing it.
+ */
+export function isBlockedUrl(url: string, allowHost?: (host: string) => boolean): boolean {
   let parsed: URL;
   try {
     parsed = new URL(url);
@@ -106,5 +138,6 @@ export function isBlockedUrl(url: string): boolean {
     return true;
   }
 
+  if (allowHost?.(parsed.hostname)) return false;
   return isBlockedHost(parsed.hostname);
 }

package/src/unzip-bounded.ts

@@ -0,0 +1,145 @@
+// Copyright 2025-2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Memory-bounded ZIP decompression — the single primitive for ingesting
+ * untrusted archives (AFPS bundles, package ZIPs, integration bundles).
+ *
+ * The prior pattern everywhere was `unzipSync(archive)` (fflate, fully
+ * synchronous) followed by a `sumSizes(...) > maxDecompressedBytes` check.
+ * That check runs AFTER the entire archive is already materialized in memory,
+ * so the guard can never prevent the OOM it claims to: a 1 MB archive can
+ * inflate to gigabytes before the cap is ever evaluated, and a single crafted
+ * member is enough.
+ *
+ * This helper feeds the compressed bytes to fflate's streaming `Unzip` in
+ * fixed-size slices and enforces a CUMULATIVE decompressed budget inside each
+ * per-file `ondata` chunk callback — so it aborts mid-inflate the instant the
+ * running total crosses the limit, never allocating materially more than the
+ * budget. It counts ACTUAL decompressed bytes (not the archive's declared
+ * sizes, which a bomb forges), so it is robust against lying headers.
+ *
+ * Lives in leaf `@appstrate/afps-shared` (re-exported by `@appstrate/core/zip`)
+ * so the platform, sidecar, and the standalone `afps` runtime share ONE
+ * bounded implementation.
+ */
+
+import { Unzip, UnzipInflate } from "fflate";
+
+export type DecompressionLimitReason =
+  "decompressed-budget-exceeded" | "file-too-large" | "too-many-files" | "corrupt-archive";
+
+export class DecompressionLimitError extends Error {
+  readonly reason: DecompressionLimitReason;
+  constructor(reason: DecompressionLimitReason, detail?: string) {
+    super(`ZIP decompression refused: ${reason}${detail ? ` (${detail})` : ""}`);
+    this.name = "DecompressionLimitError";
+    this.reason = reason;
+  }
+}
+
+export interface BoundedUnzipLimits {
+  /** Hard cap on the sum of all decompressed bytes. Aborts mid-inflate. */
+  maxDecompressedBytes: number;
+  /** Optional per-file decompressed cap. */
+  maxFileBytes?: number;
+  /** Optional cap on the number of entries. */
+  maxFiles?: number;
+}
+
+const SLICE = 64 * 1024;
+
+/**
+ * Streaming, memory-bounded unzip. Returns a `name → bytes` record of the
+ * archive's file entries (directory entries excluded). Throws
+ * {@link DecompressionLimitError} the moment any budget is crossed — before the
+ * offending bytes accumulate — or on a corrupt/unsupported archive.
+ *
+ * Path sanitization is intentionally NOT done here (callers apply their own
+ * entry-name policy on the returned names); this primitive owns only the
+ * resource-exhaustion boundary.
+ */
+export function unzipBounded(
+  artifact: Uint8Array,
+  limits: BoundedUnzipLimits,
+): Record<string, Uint8Array> {
+  const { maxDecompressedBytes, maxFileBytes, maxFiles } = limits;
+
+  // Streaming `Unzip` scans for local-file-header signatures and silently
+  // yields nothing on a buffer that isn't a ZIP — so guard the archive magic
+  // up front. Every ZIP begins with "PK" (0x50 0x4b): a local file header
+  // (PK\x03\x04) or, for an empty archive, the end-of-central-directory
+  // (PK\x05\x06). Anything else is corrupt/non-ZIP and must fail loudly.
+  if (artifact.length < 4 || artifact[0] !== 0x50 || artifact[1] !== 0x4b) {
+    throw new DecompressionLimitError("corrupt-archive", "not a ZIP archive");
+  }
+
+  const out: Record<string, Uint8Array> = {};
+  let total = 0;
+  let fileCount = 0;
+  let caught: unknown = null;
+
+  const unzipper = new Unzip((file) => {
+    fileCount += 1;
+    if (maxFiles !== undefined && fileCount > maxFiles) {
+      throw new DecompressionLimitError("too-many-files", `> ${maxFiles}`);
+    }
+    // Directory entries carry no data — skip; fflate still requires start().
+    const isDir = file.name.endsWith("/");
+    const chunks: Uint8Array[] = [];
+    let fileSize = 0;
+    file.ondata = (err, chunk, final) => {
+      // Once a limit/corruption verdict is set, fflate may still invoke this
+      // callback again within the same push (as it unwinds the inflate) — never
+      // overwrite the first verdict; just re-throw it so the reason is stable.
+      if (caught) throw caught;
+      if (err) {
+        caught = new DecompressionLimitError("corrupt-archive", err.message);
+        throw caught;
+      }
+      fileSize += chunk.length;
+      total += chunk.length;
+      if (maxFileBytes !== undefined && fileSize > maxFileBytes) {
+        caught = new DecompressionLimitError("file-too-large", file.name);
+        throw caught;
+      }
+      if (total > maxDecompressedBytes) {
+        caught = new DecompressionLimitError("decompressed-budget-exceeded");
+        throw caught;
+      }
+      if (!isDir) chunks.push(chunk);
+      if (final && !isDir) {
+        out[file.name] = concatChunks(chunks, fileSize);
+      }
+    };
+    file.start();
+  });
+  unzipper.register(UnzipInflate);
+
+  try {
+    for (let off = 0; off < artifact.length; off += SLICE) {
+      const end = Math.min(off + SLICE, artifact.length);
+      unzipper.push(artifact.subarray(off, end), end === artifact.length);
+    }
+  } catch (err) {
+    if (err instanceof DecompressionLimitError) throw err;
+    if (caught instanceof DecompressionLimitError) throw caught;
+    throw new DecompressionLimitError(
+      "corrupt-archive",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+
+  return out;
+}
+
+function concatChunks(chunks: Uint8Array[], size: number): Uint8Array {
+  if (chunks.length === 1) return chunks[0]!;
+  const merged = new Uint8Array(size);
+  let pos = 0;
+  for (const c of chunks) {
+    merged.set(c, pos);
+    pos += c.length;
+  }
+  return merged;
+}