@appstrate/afps-shared 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.4.0",
+  "version": "0.6.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,6 +49,7 @@
     "./guarded-fetch": "./src/guarded-fetch.ts",
     "./signed-token": "./src/signed-token.ts",
     "./unzip-bounded": "./src/unzip-bounded.ts",
+    "./archive-prefix": "./src/archive-prefix.ts",
     "./backoff": "./src/backoff.ts",
     "./mime": "./src/mime.ts"
   },

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/delivery-http.ts

@@ -96,3 +96,35 @@ export function projectHttpDeliveryConfig(
   }
   return cfg;
 }
+
+/**
+ * Header names whose value is an RFC 9110 `credentials` production — an auth
+ * scheme token, one SP, then the credentials. Only in these positions is a
+ * bare token prefix a defect; anywhere else (`Cookie: session=`) it is an
+ * ordinary literal.
+ */
+const AUTH_SCHEME_HEADERS = new Set(["authorization", "proxy-authorization"]);
+
+/** RFC 9110 `token` grammar — matches a prefix that is nothing but a scheme. */
+const BARE_AUTH_SCHEME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * True when `prefix` is nothing but an auth-scheme token AND `headerName` is a
+ * position whose value is an RFC 9110 `credentials` production.
+ *
+ * `prefix` is a LITERAL prepended to the rendered credential (AFPS §7.6), so a
+ * bare `"Bearer"` renders `Authorization: BearerTOKEN` — a malformed credential
+ * every upstream answers with a 401 that names nothing. The injector
+ * (`@appstrate/afps-runtime`'s `planHttpDeliveryInjection`) concatenates
+ * verbatim and repairs nothing, so every path that accepts an author-written
+ * prefix must refuse the bare form up front instead. This is the one grammar
+ * those gates share: the integration manifest validator
+ * (`@appstrate/core/integration`, install time) and the portable runtime's
+ * local creds file (`resolvers/integration-api-call.ts`, load time).
+ *
+ * Callers pass the EFFECTIVE header name — the one that will actually be sent,
+ * after their own defaulting has been applied.
+ */
+export function isBareAuthSchemePrefix(headerName: string, prefix: string): boolean {
+  return AUTH_SCHEME_HEADERS.has(headerName.toLowerCase()) && BARE_AUTH_SCHEME.test(prefix);
+}

package/src/guarded-fetch.ts

@@ -80,7 +80,7 @@ export interface GuardedFetchOptions {
   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`).
+   * internal IdP on a private address via `EGRESS_ALLOW_INTERNAL_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.

package/src/mime.ts

@@ -60,6 +60,24 @@ export function normalizeMime(mime: string | null | undefined): string {
  * 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
@@ -68,22 +86,49 @@ export const TEXT_SHAPED_MEDIA_TYPES: ReadonlySet<string> = new Set([
   "application/x-ndjson",
   "application/jsonl",
   "application/json-seq",
-  // XML family
+  "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
 ]);
 
 /**