@appstrate/afps-shared 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.1.0",
+  "version": "0.2.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,17 @@
     "./integrity": "./src/integrity.ts",
     "./credential-template": "./src/credential-template.ts",
     "./delivery-http": "./src/delivery-http.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/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,230 @@
+// 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).
+ *
+ * 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.
+ * - Rejects non-http(s) schemes and strips userinfo/fragment from redirect
+ *   targets (defeats `https://user:pass@…` credential-leak + fragment tricks).
+ *
+ * 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.
+ *
+ * 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.
+   */
+  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;
+  /** 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;
+
+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;
+}
+
+async function checkHost(url: URL, opts?: GuardedFetchOptions): Promise<void> {
+  if (opts?.allowHost?.(url.hostname)) return; // 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);
+  }
+}
+
+/**
+ * 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.
+ */
+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);
+  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.
+  const headers = new Headers(init?.headers ?? {});
+
+  // 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++) {
+      const doFetch = opts?.fetchImpl ?? fetch;
+      const res = await doFetch(current, {
+        ...init,
+        method,
+        body,
+        headers,
+        signal,
+        redirect: "manual",
+      });
+
+      // `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);
+      await checkHost(next, opts);
+
+      if (next.origin !== current.origin) {
+        for (const h of ["authorization", "cookie", "proxy-authorization"]) 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.
+        const schemeDowngrade = current.protocol === "https:" && next.protocol === "http:";
+        if (body !== undefined && (next.hostname !== current.hostname || schemeDowngrade)) {
+          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;
+      // 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/ssrf-dns.ts

@@ -0,0 +1,103 @@
+// 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 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.
+ *
+ * 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,148 @@
+// 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;
+}