@appstrate/afps-shared 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,57 @@
+# `@appstrate/afps-shared`
+
+Zero-internal-dependency leaf package holding the primitives that both
+[`@appstrate/core`](https://www.npmjs.com/package/@appstrate/core) (platform side)
+and the AFPS runtime (in-sandbox side) need to agree on byte-for-byte.
+
+It exists so those two layers cannot drift: an integrity hash, an SSRF verdict or
+a capability-token signature computed on one side must validate on the other.
+If you are building on Appstrate, you almost certainly want `@appstrate/core`
+instead — this package is its foundation, published separately because the
+runtime cannot depend on the platform.
+
+```sh
+npm install @appstrate/afps-shared
+```
+
+**Requires Bun ≥ 1.3.9.** The package ships raw TypeScript sources rather than a
+compiled bundle, so Node cannot import it directly. There is no barrel export —
+import each module by subpath.
+
+## Exports
+
+| Subpath                              | What it does                                                                                                                                                |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `./guarded-fetch`                    | The single outbound-request primitive for any URL whose host comes from a less-trusted input (manifest URLs, OAuth endpoints). Wraps the SSRF checks below. |
+| `./ssrf` · `./ssrf-dns`              | SSRF host/address validation, including DNS resolution so a hostname cannot rebind to a private range between check and connect.                            |
+| `./signed-token`                     | Keyring-HMAC capability tokens — the one codec behind every short-lived, URL-carried capability (upload URLs, document previews, hosted connect sessions).  |
+| `./unzip-bounded`                    | Memory-bounded ZIP decompression for untrusted archives (AFPS bundles, package ZIPs, integration bundles).                                                  |
+| `./integrity`                        | Package integrity digests.                                                                                                                                  |
+| `./companion-files`                  | Companion-file enforcement, shared between the platform ZIP-import path and the runtime bundle loader.                                                      |
+| `./credential-template`              | Credential-template placeholder substitution.                                                                                                               |
+| `./delivery-http`                    | Shared HTTP delivery contract.                                                                                                                              |
+| `./semver-resolve`                   | Version-range resolution against a published version list.                                                                                                  |
+| `./api-tool-naming` · `./mcp-naming` | Deterministic tool and MCP-server naming.                                                                                                                   |
+| `./file-field`                       | File-field parsing helpers.                                                                                                                                 |
+| `./token-usage`                      | Token-usage accounting shapes.                                                                                                                              |
+| `./backoff`                          | Retry backoff computation.                                                                                                                                  |
+
+```ts
+import { guardedFetch } from "@appstrate/afps-shared/guarded-fetch";
+
+// Refuses private ranges, link-local addresses and DNS-rebinding attempts.
+const res = await guardedFetch(untrustedUrlFromManifest);
+```
+
+## Versioning
+
+`@appstrate/core` depends on this package by caret range, so **a release here
+must be published before any `@appstrate/core` release that bumps its
+range** — otherwise `npm install @appstrate/core` cannot resolve.
+
+Publishing is triggered by pushing an `afps-shared@X.Y.Z` git tag; CI handles the
+rest (`.github/workflows/publish-afps-shared.yml`).
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -47,22 +47,21 @@
     "./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"
+    "./backoff": "./src/backoff.ts",
+    "./mime": "./src/mime.ts"
   },
   "dependencies": {
+    "@types/semver": "^7.8.0",
     "fflate": "^0.8.3",
     "semver": "^7.8.4"
   },
-  "devDependencies": {
-    "@types/semver": "^7.7.1"
-  },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": ">=5 <8"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "check": "tsc --noEmit",
     "test": "bun test"
   }
 }

package/src/companion-files.ts

@@ -7,9 +7,14 @@
  * (`@appstrate/afps-runtime/bundle/build:extractRootFromAfps`).
  *
  * This is the SINGLE source of truth for the §3.3 / §3.4 companion-file
- * invariants. Both `@appstrate/core/companion-files` and
- * `@appstrate/afps-runtime/bundle/companion-files` re-export from here, so
- * the two call sites can never drift.
+ * invariants. Both call sites import THIS module directly — there is no
+ * intermediate re-export to drift against:
+ *   - `packages/core/src/zip.ts` calls `checkCompanionFiles` +
+ *     `companionFilesFromRecord` inline (core no longer publishes a
+ *     `./companion-files` subpath — removed in core 6.0.0).
+ *   - `packages/afps-runtime/src/bundle/companion-files.ts` is a thin
+ *     internal adapter (Map-accepting, throws `BundleError`) consumed by
+ *     `bundle/validate-bundle.ts`; it is not a package subpath either.
  */
 
 /**

package/src/credential-template.ts

@@ -3,7 +3,11 @@
 
 /**
  * Canonical `{$credential.<field>}` value-template renderer — the SINGLE
- * source of truth, re-exported by `@appstrate/core/credential-template`.
+ * source of truth. Consumers import this module directly; core no longer
+ * publishes a `./credential-template` subpath (removed in core 6.0.0). The
+ * only importer today is `apps/api/src/services/integration-manifest-helpers.ts`,
+ * which re-exports it pre-bound to `emptyAs: "null"` for
+ * `integration-spawn-resolver.ts`.
  *
  * AFPS `delivery.http` / `delivery.env` / `delivery.files` value templates
  * reference an auth's decrypted credential bag via the `{$credential.<field>}`

package/src/mime.ts

@@ -0,0 +1,134 @@
+// Copyright 2025-2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * MIME classification primitives — the ONE place that answers "is this media
+ * type a text payload or an opaque binary container?".
+ *
+ * Lives in the zero-dependency shared package because the question is asked at
+ * four layers that cannot import each other:
+ *
+ *  - **Platform API** (`apps/api/src/services/mime-policy.ts`) — sniff
+ *    enforcement on uploads, MCP `resources/read` inlining.
+ *  - **AFPS runtime** (`packages/afps-runtime` → `http-call-core.ts`) — decides
+ *    whether an `http_call` response body is decoded as text or base64'd.
+ *  - **Sidecar** (`runtime-pi/sidecar/mcp.ts`) — decides whether an `api_call`
+ *    response is inlined as text or spilled to the blob store as bytes.
+ *  - **Core** (`@appstrate/core/mime`) — re-exports this module verbatim, so
+ *    the platform surface is unchanged.
+ *
+ * Every one of those had its own hand-rolled list, and the lists drifted:
+ *
+ *  - The MCP copy did not know about the YAML family, so a YAML document was
+ *    base64-blobbed instead of being handed to the model as readable text.
+ *  - The sidecar matched `contentType.includes("xml")`, which classifies
+ *    `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (an
+ *    XLSX — a ZIP binary) as text. The UTF-8 decode replaced invalid bytes with
+ *    U+FFFD and the re-encode wrote that corruption to disk, destroying every
+ *    OOXML file downloaded through `responseMode.toFile`.
+ *
+ * Both bugs are the same bug: an ad-hoc list, matched by substring instead of
+ * by media type. Add a format HERE, not at a call site.
+ *
+ * WHY this module sits in `@appstrate/afps-shared` rather than in core:
+ * `@appstrate/afps-runtime` deliberately carries no runtime dependency on core
+ * (it ships as a portable bundle runner and a standalone `afps` CLI; core sits
+ * beside it in the dependency graph, not below it). For that reason the set
+ * used to be hand-copied into `http-call-core.ts` with a parity test guarding
+ * the copy — and it drifted three times anyway, once classifying XLSX as XML.
+ * afps-shared is a `workspace:*` dependency of afps-runtime AND a published
+ * dependency of core, so a single definition now reaches both without either
+ * importing the other. That is the same "canonical source, core re-exports
+ * verbatim" arrangement used by `ssrf.ts`, `credential-template.ts` and
+ * `guarded-fetch.ts`.
+ */
+
+/**
+ * Strip charset / boundary / other parameters from a MIME string and lowercase
+ * it, so `text/csv; charset=utf-8` compares equal to `text/csv`.
+ *
+ * Every predicate in this module expects an already-normalized value —
+ * classification and normalization stay separate so a caller that already holds
+ * a bare media type does not pay for the split twice.
+ */
+export function normalizeMime(mime: string | null | undefined): string {
+  if (!mime) return "";
+  return mime.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+
+/**
+ * Media types whose payload is text, matched EXACTLY. A substring test would
+ * classify `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+ * as XML — see the module doc.
+ */
+export const TEXT_SHAPED_MEDIA_TYPES: ReadonlySet<string> = new Set([
+  // JSON family
+  "application/json",
+  "application/ld+json",
+  "application/x-ndjson",
+  "application/jsonl",
+  "application/json-seq",
+  // XML family
+  "application/xml",
+  "application/xml-dtd",
+  "application/xml-external-parsed-entity", // RFC 7303
+  "image/svg+xml", // XML-based, file-type never matches it
+  // YAML family
+  "application/yaml",
+  "application/x-yaml",
+  // Scripting / tabular / form encodings with no magic signature
+  "application/javascript",
+  "application/x-javascript",
+  "application/ecmascript",
+  "application/csv",
+  "application/x-sh",
+  "application/x-httpd-php",
+  "application/x-www-form-urlencoded",
+]);
+
+/**
+ * Is this MIME text-shaped — i.e. does the format carry its payload as text
+ * (plain text, JSON, CSV, XML source, YAML, JS, …) rather than as a binary
+ * container?
+ *
+ * Expects a NORMALIZED media type ({@link normalizeMime}); a value carrying
+ * `; charset=…` never matches the exact sets below.
+ *
+ * Four consumers ask this same question and must answer it identically:
+ *
+ *  - **Sniff enforcement** (`shouldEnforceSniffedMime`): text-shaped formats
+ *    have no magic bytes, so `file-type` can never confirm them — the strict
+ *    declared-vs-sniffed check is skipped and the declared mime trusted.
+ *    Callers needing strict binary validation should declare a concrete binary
+ *    MIME (application/pdf, image/*, …) which `file-type` can identify.
+ *  - **MCP `resources/read`**: text-shaped bytes are inlined as a `text` block;
+ *    anything else goes out as a base64 `blob`.
+ *  - **HTTP response classification** (`api_call` / `http_call`): text-shaped
+ *    bodies are UTF-8 decoded; anything else stays raw bytes. A false positive
+ *    here is data loss, not a cosmetic mislabel — the decode is lossy
+ *    (`fatal: false` → U+FFFD) and irreversible once re-encoded.
+ *
+ * `application/octet-stream` is deliberately absent: it is the explicit "opaque
+ * blob" marker and MUST stay on the binary path even when its bytes happen to
+ * be ASCII.
+ */
+export function isTextShapedMime(mime: string): boolean {
+  if (mime.startsWith("text/")) return true;
+  if (TEXT_SHAPED_MEDIA_TYPES.has(mime)) return true;
+  // Structured-syntax suffixes (RFC 6839) — `+json`, `+xml`, `+yaml`.
+  // Anything in these families is text-shaped and cannot be magic-sniffed.
+  return mime.endsWith("+json") || mime.endsWith("+xml") || mime.endsWith("+yaml");
+}
+
+/**
+ * Convenience wrapper for the common HTTP shape: classify a raw `Content-Type`
+ * header value (parameters included) in one call.
+ *
+ * An absent or empty header is NOT text — a caller that wants to treat a
+ * missing Content-Type as text must say so explicitly at its own call site,
+ * because the safe default for unknown bytes is the binary path.
+ */
+export function isTextShapedContentType(contentType: string | null | undefined): boolean {
+  const mime = normalizeMime(contentType);
+  return mime !== "" && isTextShapedMime(mime);
+}

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;
+  }
+}