@appstrate/afps-shared 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.4.0",
+  "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,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/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
 ]);
 
 /**