@appstrate/afps-shared 0.3.1 → 0.5.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.1",
+  "version": "0.5.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",
@@ -49,21 +49,20 @@
     "./guarded-fetch": "./src/guarded-fetch.ts",
     "./signed-token": "./src/signed-token.ts",
     "./unzip-bounded": "./src/unzip-bounded.ts",
-    "./backoff": "./src/backoff.ts"
+    "./archive-prefix": "./src/archive-prefix.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/archive-prefix.ts

@@ -0,0 +1,81 @@
+// Copyright 2026 Appstrate
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Wrapper-folder stripping for AFPS archives — the ONE place that answers
+ * "did whoever zipped this wrap everything in a top-level directory, and if so
+ * what is it?".
+ *
+ * ZIPs created by macOS Finder or `zip -r folder/` wrap all entries under a
+ * single top-level directory, so a lookup like `files["manifest.json"]` misses.
+ * Only strip when EVERY entry shares one first-level prefix and none sits at
+ * the root; anything else is ambiguous and the collection comes back untouched,
+ * by identity.
+ *
+ * Lives in the zero-dependency shared package because two packages that cannot
+ * import each other both have to strip the same prefix the same way:
+ *
+ *  - **Core** (`@appstrate/core/zip`) — the platform's package-ZIP parser, over
+ *    fflate's `Record<string, Uint8Array>` shape, plus the sanitized `Map`
+ *    shape the bundle path hands it.
+ *  - **AFPS runtime** (`@appstrate/afps-runtime` → `bundle/archive-utils.ts`) —
+ *    the `.afps` ingestion path, over the sanitized `Map` shape.
+ *
+ * The runtime used to keep a hand-copy of core's `Map` branch under a comment
+ * asking a human to "keep the two algorithms in sync", with no parity test to
+ * police it. That is exactly the arrangement `@appstrate/afps-shared/mime`
+ * replaced for the media-type set — where the policing parity test existed and
+ * the copies drifted three times anyway, once corrupting every OOXML download.
+ * `@appstrate/afps-runtime` deliberately carries no runtime dependency on core
+ * (it ships as a portable bundle runner and a standalone `afps` CLI), and
+ * afps-shared is a dependency of both, so one definition reaches both without
+ * either taking on the other.
+ *
+ * Change the rule HERE, not at a call site.
+ */
+
+/**
+ * Detect and strip a single common wrapper folder from archive entries.
+ *
+ * Accepts either a `Record<string, Uint8Array>` (fflate's default ZIP shape) or
+ * a `Map<string, Uint8Array>` (the sanitized bundle shape) and returns the same
+ * type as the input — the ORIGINAL object, by identity, when there is nothing
+ * to strip.
+ */
+export function stripWrapperPrefix(files: Record<string, Uint8Array>): Record<string, Uint8Array>;
+export function stripWrapperPrefix(files: Map<string, Uint8Array>): Map<string, Uint8Array>;
+export function stripWrapperPrefix(
+  files: Record<string, Uint8Array> | Map<string, Uint8Array>,
+): Record<string, Uint8Array> | Map<string, Uint8Array> {
+  const keys = files instanceof Map ? [...files.keys()] : Object.keys(files);
+  const prefix = commonWrapperPrefix(keys);
+  if (prefix === null) return files;
+
+  if (files instanceof Map) {
+    const stripped = new Map<string, Uint8Array>();
+    for (const [key, value] of files) stripped.set(key.slice(prefix.length), value);
+    return stripped;
+  }
+  const stripped: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(files)) {
+    stripped[key.slice(prefix.length)] = value;
+  }
+  return stripped;
+}
+
+/**
+ * The single wrapper prefix (WITH its trailing slash) every key shares, or
+ * `null` when there is none to strip — no entries at all, an entry at the root
+ * level, or more than one top-level folder (ambiguous).
+ */
+function commonWrapperPrefix(keys: readonly string[]): string | null {
+  if (keys.length === 0) return null;
+  const prefixes = new Set<string>();
+  for (const key of keys) {
+    const slashIdx = key.indexOf("/");
+    if (slashIdx === -1) return null; // root-level file → no stripping
+    prefixes.add(key.slice(0, slashIdx));
+  }
+  if (prefixes.size !== 1) return null; // multiple top-level folders → ambiguous
+  return `${[...prefixes][0]}/`;
+}

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,179 @@
+// 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.
+ *
+ * Membership criterion, applied to every entry below:
+ *
+ *  1. the format's specification defines the payload as a character sequence,
+ *     so a UTF-8 decode is lossless and a base64 round-trip is pure noise to
+ *     the model;
+ *  2. it plausibly arrives as an HTTP response body (request-only grammars
+ *     such as `application/sparql-query` or `application/jsonpath` are out);
+ *  3. it is not a container that may embed raw bytes. `application/rtf`
+ *     (`\bin` blocks), `application/postscript` (binary-token PostScript) and
+ *     `application/http` (a message whose body may be anything) all fail this
+ *     and stay on the byte path even though their common form is ASCII.
+ *
+ * Completeness matters more than it used to. `isTextLikeMimeType` in
+ * `@appstrate/afps-runtime` used to treat any `; charset=…` parameter as a
+ * declaration of textness ahead of this set; it now consults that parameter
+ * only for an ambiguous base type, so a text format MISSING from this set is
+ * base64'd to the model even when the upstream declared a charset.
+ */
+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",
+  "application/json5",
+  "application/hjson",
+  // XML / SGML family
+  "application/xml",
+  "application/xml-dtd",
+  "application/xml-external-parsed-entity", // RFC 7303
+  "application/sgml",
+  "image/svg+xml", // XML-based, file-type never matches it
+  // YAML family
+  "application/yaml",
+  "application/x-yaml",
+  // TOML
+  "application/toml",
+  // Markdown — `text/markdown` is the registered spelling and already matches
+  // on the `text/` prefix; these two are the widespread unregistered ones.
+  "application/markdown",
+  "application/x-markdown",
+  // Query / schema languages served as source text
+  "application/sql", // RFC 6922
+  "application/graphql",
+  // RDF text serialisations. The `+json` / `+xml` RDF spellings already match
+  // on their structured suffix, and Turtle is registered as `text/turtle`.
+  "application/n-triples",
+  "application/n-quads",
+  "application/trig",
+  // Scripting / tabular / form encodings with no magic signature
+  "application/javascript",
+  "application/x-javascript",
+  "application/ecmascript",
+  "application/node",
+  "application/typescript",
+  "application/x-typescript",
+  "application/dart",
+  "application/csv",
+  "application/x-sh",
+  "application/x-shellscript",
+  "application/x-httpd-php",
+  "application/x-www-form-urlencoded",
+  // ASCII-armored / PEM blocks — base64 wrapped in text framing. Re-encoding
+  // them as base64 hides the framing the model needs to read.
+  "application/pem-certificate-chain", // RFC 8555
+  "application/pgp-keys", // RFC 3156 — the armored form
+  "application/pgp-signature", // RFC 3156 — the armored form
+]);
+
+/**
+ * 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);
+}