@appstrate/afps-shared 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -56,7 +56,8 @@
   "dependencies": {
     "@types/semver": "^7.8.0",
     "fflate": "^0.8.3",
-    "semver": "^7.8.4"
+    "semver": "^7.8.4",
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "typescript": ">=5 <8"

package/src/companion-files.ts

@@ -17,6 +17,8 @@
  *     `bundle/validate-bundle.ts`; it is not a package subpath either.
  */
 
+import { parse as parseYaml } from "yaml";
+
 /**
  * Stable, machine-readable companion-file violation reasons.
  */
@@ -24,7 +26,11 @@ export type CompanionViolationReason =
   | "AGENT_MISSING_PROMPT"
   | "AGENT_EMPTY_PROMPT"
   | "SKILL_MISSING_SKILL_MD"
+  | "SKILL_INVALID_FRONTMATTER"
   | "SKILL_MISSING_FRONTMATTER_NAME"
+  | "SKILL_INVALID_FRONTMATTER_NAME"
+  | "SKILL_MISSING_FRONTMATTER_DESCRIPTION"
+  | "SKILL_INVALID_FRONTMATTER_DESCRIPTION"
   | "MCP_SERVER_MISSING_ENTRY_POINT";
 
 /**
@@ -77,8 +83,10 @@ export function companionFilesFromRecord(files: Record<string, Uint8Array>): Com
  *
  * The check is intentionally minimal and presence-focused:
  *   - `agent` → `prompt.md` present at root, non-empty bytes (§3.2).
- *   - `skill` → `SKILL.md` present at root, with YAML frontmatter `name`
- *     (§3.3). Missing `description` is tolerated per spec.
+ *   - `skill` → `SKILL.md` present at root, with a YAML frontmatter `name`
+ *     (§3.3). Missing `description` is tolerated here: this function is the
+ *     LOADER-side gate. The stricter producer-side rule lives in
+ *     {@link checkSkillMarkdown}.
  *   - `mcp-server` → file at `manifest.server.entry_point` present in the
  *     archive (§3.4 "self-contained — every runtime dep bundled").
  *   - `integration` → no required companion (§3.5).
@@ -122,6 +130,13 @@ export function checkCompanionFiles(
         path: "SKILL.md",
       };
     }
+    // LENIENT on purpose, and deliberately NOT the shared parser — see
+    // {@link checkSkillMarkdown}. This function runs on the LOADER side too
+    // (`extractRootFromAfps` → the run launcher's package catalog), where the
+    // archive is an already-published, immutable artifact. Its acceptance set
+    // must never shrink: anything it rejects is an agent that stops running
+    // for a defect nobody can fix in place. `hasFrontmatterName` is therefore
+    // frozen — the permissive substring probe, unchanged.
     if (!hasFrontmatterName(new TextDecoder().decode(bytes))) {
       return {
         reason: "SKILL_MISSING_FRONTMATTER_NAME",
@@ -169,6 +184,23 @@ function isEffectivelyEmpty(bytes: Uint8Array): boolean {
   return true;
 }
 
+/**
+ * LOADER-side name probe. FROZEN — byte-for-byte what it was before the
+ * producer-side rule existed, and deliberately NOT routed through
+ * {@link parseSkillFrontmatter}.
+ *
+ * The distinction that forces the duplication: this probe decides whether an
+ * ALREADY-PUBLISHED bundle loads, and a published bundle is immutable. Any
+ * input it used to accept and would now reject is an agent that stops running
+ * for a defect nobody can fix in place. The shared parser reads only column-0
+ * keys — correct for authoring, but it would newly reject `  name: triage`,
+ * `metadata:\n  name: triage` and `skill_name: triage`, all of which this
+ * substring probe accepts and some published artifact may well contain.
+ *
+ * So its acceptance set may never shrink. Nothing here is to be "unified" with
+ * the parser below: they answer different questions for different sides of the
+ * artifact lifecycle.
+ */
 function hasFrontmatterName(content: string): boolean {
   const fmMatch = content.match(/^---[^\S\n]*\n([\s\S]*?)\n---/);
   if (!fmMatch) return false;
@@ -177,8 +209,324 @@ function hasFrontmatterName(content: string): boolean {
   if (!nameMatch) return false;
   const raw = (nameMatch[1] ?? "").trim();
   if (raw.length === 0) return false;
-  // Strip surrounding quotes to mirror extractSkillMeta's stripQuotes.
+  // Strip surrounding quotes, the way a YAML quoted scalar would be read.
   const unquoted = /^(['"])(.*)\1$/.exec(raw);
   const value = unquoted ? unquoted[2] : raw;
   return (value ?? "").trim().length > 0;
 }
+
+// ─────────────────────────────────────────────
+// SKILL.md YAML frontmatter — the PRODUCER-side parser
+// ─────────────────────────────────────────────
+
+/**
+ * Maximum length of a skill frontmatter `name`, in Unicode CODE POINTS (Agent
+ * Skills specification, https://agentskills.io/specification).
+ */
+export const SKILL_NAME_MAX_LENGTH = 64;
+
+/**
+ * Maximum length of a skill frontmatter `description`, in Unicode CODE POINTS
+ * — the Agent Skills specification (https://agentskills.io/specification)
+ * counts characters, and a code point is what "character" means there.
+ *
+ * NOT a parity constant: Pi measures `description.length`, i.e. UTF-16 units,
+ * and only emits a warning past the bound rather than dropping the skill. The
+ * platform enforces the spec instead, because the artifact it mints is
+ * immutable and other consumers (Codex, Claude Code) are not so forgiving.
+ */
+export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+
+/**
+ * Agent Skills `name` rule: lowercase `a-z`, `0-9` and `-` only, no leading or
+ * trailing hyphen, no consecutive hyphens. Length is checked separately
+ * against {@link SKILL_NAME_MAX_LENGTH} so the violation message can name the
+ * bound.
+ *
+ * NOT the same namespace as a package id. A package id is `@scope/name`
+ * validated by `SLUG_PATTERN` (`@appstrate/core/naming`) — unbounded in
+ * length and tolerant of `--`. The frontmatter `name` is the BARE skill slug
+ * an agent runtime addresses (`triage`, never `@acme/triage`), and it is the
+ * Agent Skills rule that governs it. The two are deliberately different and
+ * neither validator may be substituted for the other.
+ */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Length in Unicode code points — `"🙂".length` is 2, this returns 1. */
+function codePointLength(value: string): number {
+  return [...value].length;
+}
+
+/** Does `name` satisfy the Agent Skills `name` rule (shape AND length)? */
+export function isValidSkillName(name: string): boolean {
+  return codePointLength(name) <= SKILL_NAME_MAX_LENGTH && SKILL_NAME_PATTERN.test(name);
+}
+
+/** Parsed `SKILL.md` YAML frontmatter. */
+export interface SkillFrontmatter {
+  /** Whether a closed `--- … ---` frontmatter block was found. */
+  found: boolean;
+  /**
+   * True when the document opens with `---` but never closes the block. Told
+   * apart from "no frontmatter at all" so the author gets the actual fault.
+   */
+  unterminated: boolean;
+  /**
+   * Why the block could not be read as `{ name, description }` — a YAML syntax
+   * error, a document that is not a mapping, or a field that is not a string.
+   * `null` when the block parsed cleanly. Never thrown: `extractSkillMeta`'s
+   * contract is to degrade to empty fields plus a warning.
+   */
+  error: string | null;
+  /** Frontmatter `name`, or `""` when absent/blank. */
+  name: string;
+  /** Frontmatter `description`, or `""` when absent/blank. */
+  description: string;
+}
+
+/**
+ * Parse the `name` / `description` of a `SKILL.md` YAML frontmatter block.
+ *
+ * PARITY WITH THE CONSUMER IS THE POINT. The runtime that actually loads a
+ * skill — `@earendil-works/pi-coding-agent`, `dist/utils/frontmatter.js` —
+ * normalises newlines, requires the document to start with `---`, cuts the
+ * block at the first `\n---`, and hands the slice to `yaml`'s `parse`. This
+ * function does the same, against the same library at the same major, so the
+ * gate cannot accept a document the consumer then fails to PARSE.
+ *
+ * Parsing is where parity is exact. The RULES are not symmetric, on purpose:
+ * Pi only WARNS on a name or description that breaks the Agent Skills spec
+ * (and measures the description in UTF-16 units, so `"🙂".length` is 2), while
+ * this gate refuses it. The bounds below therefore follow the SPEC — which
+ * says characters, hence code points — not Pi's warning threshold. Being
+ * stricter than the consumer is safe: it costs an author one edit. Being
+ * looser is not: it mints an immutable artifact the consumer drops.
+ *
+ * The hand-rolled scanner this replaces got that wrong in both directions: it
+ * accepted `description: a: b` and `name:x`, which `yaml` refuses outright,
+ * and it had to re-implement block scalars, quoted escapes, comments,
+ * continuation lines and duplicate detection — each an opportunity to diverge
+ * from a spec the library already implements. `uniqueKeys` and `strict` are
+ * passed explicitly rather than left to their defaults so a future default
+ * change cannot loosen the gate in silence.
+ *
+ * NOTHING is normalised away that the runtime keeps — a leading BOM above all.
+ * Pi tests `normalized.startsWith("---")`, which a BOM defeats, so it reads no
+ * frontmatter at all and drops the skill. Stripping the BOM here would make
+ * this function read a name and description the runtime never sees, which is
+ * exactly the divergence it exists to prevent; {@link checkSkillMarkdown}
+ * refuses such a file instead.
+ */
+export function parseSkillFrontmatter(content: string): SkillFrontmatter {
+  const empty = { found: false, unterminated: false, error: null, name: "", description: "" };
+
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return empty;
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return { ...empty, unterminated: true };
+
+  const block = normalized.slice(4, endIndex);
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(block, { uniqueKeys: true, strict: true });
+  } catch (err) {
+    return {
+      ...empty,
+      found: true,
+      error: `frontmatter is not valid YAML: ${firstLine(err)}`,
+    };
+  }
+
+  // An empty block yields `null`; the runtime coerces that to `{}` and so do
+  // we, which makes it a missing NAME rather than a malformed document.
+  const mapping = parsed ?? {};
+  if (typeof mapping !== "object" || Array.isArray(mapping)) {
+    return {
+      ...empty,
+      found: true,
+      error: "frontmatter is not valid YAML: expected a mapping of keys to values",
+    };
+  }
+
+  const record = mapping as Record<string, unknown>;
+  const name = readStringField(record, "name");
+  if (typeof name !== "string") return { ...empty, found: true, error: name.error };
+  const description = readStringField(record, "description");
+  if (typeof description !== "string") return { ...empty, found: true, error: description.error };
+
+  return { found: true, unterminated: false, error: null, name, description };
+}
+
+/**
+ * Read one frontmatter field as a trimmed string.
+ *
+ * An ABSENT key and an empty YAML scalar (`description:`, which parses to
+ * `null`, as does an explicit `description: null`) are indistinguishable once
+ * parsed and both mean "not provided" — they yield `""` so the caller reports
+ * the field as MISSING. Any other non-string (a number, a boolean, a list, a
+ * nested mapping) is a malformed document, not a missing field.
+ */
+function readStringField(record: Record<string, unknown>, key: string): string | { error: string } {
+  const value = record[key];
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "string") {
+    return {
+      error: `frontmatter is not valid YAML: '${key}' must be a string, got ${describeType(value)}`,
+    };
+  }
+  return value.trim();
+}
+
+function describeType(value: unknown): string {
+  if (Array.isArray(value)) return "a list";
+  if (typeof value === "object") return "a mapping";
+  return `a ${typeof value}`;
+}
+
+/** Does the text begin with a UTF-8 byte-order mark? */
+function startsWithBom(content: string): boolean {
+  return content.charCodeAt(0) === 0xfeff;
+}
+
+/**
+ * Decode `SKILL.md` bytes for {@link checkSkillMarkdown}.
+ *
+ * `ignoreBOM: true` is the whole point, and its name is backwards: it means
+ * "do not CONSUME the BOM", i.e. keep U+FEFF as a character. A default
+ * `TextDecoder` silently swallows it, so a write path that decoded stored or
+ * archived bytes the ordinary way would hand the gate a BOM-free string, pass
+ * it, and freeze bytes the runtime cannot read. Every write path that starts
+ * from bytes rather than from a request body decodes through THIS function.
+ */
+export function decodeSkillMarkdown(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+}
+
+/** First line of an error message — YAML errors carry a multi-line excerpt. */
+function firstLine(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.split("\n")[0]!.trim();
+}
+
+// ─────────────────────────────────────────────
+// SKILL.md — the PRODUCER-side gate
+// ─────────────────────────────────────────────
+
+/**
+ * Validate a `SKILL.md`'s frontmatter against the FULL AFPS §3.3 rule, as a
+ * producer must: a `name` conforming to the Agent Skills specification
+ * (https://agentskills.io/specification) and a non-empty `description` of at
+ * most {@link SKILL_DESCRIPTION_MAX_LENGTH} code points. Returns the first
+ * violation, or `null`.
+ *
+ * WHY THIS IS SEPARATE FROM {@link checkCompanionFiles}. That function runs on
+ * both sides of the artifact lifecycle, and the loader side reads
+ * already-published, immutable bundles: a skill published before this rule
+ * existed must keep loading, or every run of an agent that depends on it fails
+ * at launch for a defect nobody can now fix in place. So the rule is applied
+ * at the moment content is AUTHORED — editor create, draft save, publish,
+ * restore, fork, and the ROOT of every import — and never at load. AFPS spells
+ * both fields SHOULD; the platform mints these artifacts and holds itself to
+ * MUST.
+ *
+ * Takes the decoded text, not a file source: every write path already has the
+ * `SKILL.md` in hand (a request body, a draft column, a ZIP entry), and
+ * "is SKILL.md present at all" is `checkCompanionFiles`'s question.
+ */
+export function checkSkillMarkdown(content: string): CompanionFileViolation | null {
+  // FIRST, because everything below reads a document the runtime cannot: Pi's
+  // `parseFrontmatter` tests `startsWith("---")`, which a BOM defeats, so it
+  // reads an empty frontmatter and `loadSkillFromFile` returns `skill: null` —
+  // the skill is silently dropped at run time. The platform's own loader is
+  // more forgiving (it decodes archive bytes through a default `TextDecoder`,
+  // which eats the BOM), so nothing downstream would have complained: the
+  // version would be minted, immutable, and simply never load in the agent.
+  //
+  // Rejected rather than stripped: silently rewriting an author's bytes would
+  // make the artifact disagree with the file they wrote.
+  if (startsWithBom(content)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER",
+      message:
+        "skill SKILL.md starts with a byte-order mark (U+FEFF); remove it — " +
+        "the runtime cannot read frontmatter behind a BOM",
+      path: "SKILL.md",
+    };
+  }
+
+  const { unterminated, error, name, description } = parseSkillFrontmatter(content);
+
+  if (unterminated) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_NAME",
+      message: "skill SKILL.md frontmatter block is not closed (expected a second '---' line)",
+      path: "SKILL.md",
+    };
+  }
+  if (error) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER",
+      message: `skill SKILL.md ${error}`,
+      path: "SKILL.md",
+    };
+  }
+  if (!name) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_NAME",
+      message: "skill SKILL.md must declare a 'name' in YAML frontmatter",
+      path: "SKILL.md",
+    };
+  }
+  if (!isValidSkillName(name)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_NAME",
+      message:
+        `skill SKILL.md 'name' must be 1-${SKILL_NAME_MAX_LENGTH} characters of lowercase ` +
+        `a-z, 0-9 and '-', with no leading or trailing hyphen and no consecutive hyphens ` +
+        `(got '${name}')`,
+      path: "SKILL.md",
+    };
+  }
+  if (!description) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_DESCRIPTION",
+      message: "skill SKILL.md must declare a non-empty 'description' in YAML frontmatter",
+      path: "SKILL.md",
+    };
+  }
+  const descriptionLength = codePointLength(description);
+  if (descriptionLength > SKILL_DESCRIPTION_MAX_LENGTH) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_DESCRIPTION",
+      message:
+        `skill SKILL.md 'description' must be at most ${SKILL_DESCRIPTION_MAX_LENGTH} ` +
+        `characters (got ${descriptionLength})`,
+      path: "SKILL.md",
+    };
+  }
+
+  // CONTAINMENT: what this gate accepts must be a SUBSET of what the loader
+  // accepts. The two read the frontmatter differently on purpose — a real YAML
+  // parser here, a frozen substring probe there — and YAML is the more
+  // permissive of the two: `name:\n  triage`, `name : triage` and a
+  // BOM-prefixed document are all valid YAML that `hasFrontmatterName` cannot
+  // see. Without this check, create and publish would mint an IMMUTABLE version
+  // the run launcher then refuses to load — the one failure mode this whole
+  // split exists to prevent, and unfixable once published.
+  //
+  // Stated as a check rather than by loosening the loader, because the loader's
+  // acceptance set may never shrink, and rather than by tightening the parser,
+  // because the parser must keep matching the runtime.
+  if (!hasFrontmatterName(content)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_NAME",
+      message:
+        `skill SKILL.md 'name' must be written inline on one line, e.g. "name: my-skill" ` +
+        `(a name on a following line, or a space before the colon, makes the platform's ` +
+        `package loader unable to read it)`,
+      path: "SKILL.md",
+    };
+  }
+  return null;
+}

package/src/file-field.ts

@@ -2,9 +2,8 @@
 // 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.
+ * Canonical AFPS file-field predicate, used by `@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
@@ -17,10 +16,46 @@
  * 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.
+ *
+ * ── `@appstrate/core/form` HAS A PARALLEL COPY OF THIS RULE, ON PURPOSE ──
+ * `isMultipleFileField` is new in THIS version (0.7.0), which is not on npm
+ * yet; the newest published release, 0.6.0, exports `isFileField` from this
+ * subpath and nothing else. `@appstrate/core` ships as source, so a consumer's
+ * `tsc` compiles core's files against the `@appstrate/afps-shared` their own
+ * install resolves — importing `isMultipleFileField` from here typechecks in
+ * this workspace and cannot resolve for them. Core therefore carries its own
+ * copy, derived from the same single-file-node rule; `packages/core/test/
+ * form.test.ts` asserts the two agree table-wide, so a change made HERE and not
+ * there (or vice versa) fails that test.
+ *
+ * Core has ALREADY raised its floor to `^0.7.0`, so the remaining step is the
+ * publish (`git tag afps-shared@0.7.0`); after it lands, core's copy is
+ * replaced by an import of the two predicates. Not before.
+ *
+ * The helpers below (`asNode`, `isSingleFileNode`, `resolveItems`,
+ * `resolveType`) are deliberately NOT exported and are not part of that plan.
+ * They are implementation detail of the two predicates, they have no importer
+ * anywhere, and every name this package exports is a semver commitment to
+ * out-of-tree consumers that only a breaking release can take back.
  */
 
-/** A single file field: `format: "uri"` + a `contentMediaType`. */
-function isSingleFileNode(node: Record<string, unknown>): boolean {
+/** Narrow an `unknown` schema node to an indexable object, or `undefined`. */
+function asNode(schema: unknown): Record<string, unknown> | undefined {
+  return schema && typeof schema === "object" ? (schema as Record<string, unknown>) : undefined;
+}
+
+/**
+ * A single file field: `format: "uri"` + a DECLARED `contentMediaType`.
+ *
+ * "Declared" is `!= null && !== false`, deliberately NOT truthiness: the
+ * keyword's presence is what marks the field as a file, and whether its value
+ * is a well-formed media type is the manifest validator's job, not this
+ * predicate's. `contentMediaType: ""` is therefore a file field — the same
+ * reading `apps/api/src/services/inline-run.ts` documents and relies on.
+ */
+function isSingleFileNode(schema: unknown): boolean {
+  const node = asNode(schema);
+  if (!node) return false;
   return node.format === "uri" && node.contentMediaType != null && node.contentMediaType !== false;
 }
 
@@ -28,8 +63,9 @@ function isSingleFileNode(node: Record<string, unknown>): boolean {
  * 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;
+function resolveItems(schema: unknown): Record<string, unknown> | undefined {
+  const node = asNode(schema);
+  const items = node?.items;
   if (!items || typeof items === "boolean") return undefined;
   if (Array.isArray(items)) {
     const first = items[0];
@@ -39,7 +75,10 @@ function resolveItems(node: Record<string, unknown>): Record<string, unknown> |
   return undefined;
 }
 
-function resolveType(node: Record<string, unknown>): string | undefined {
+/** Resolve a node's `type` (JSON Schema allows a union array — first wins). */
+function resolveType(schema: unknown): string | undefined {
+  const node = asNode(schema);
+  if (!node) return 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];
@@ -52,12 +91,21 @@ function resolveType(node: Record<string, unknown>): string | undefined {
  * 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;
+  return isSingleFileNode(schema) || isMultipleFileField(schema);
+}
+
+/**
+ * Detect a MULTIPLE-files field: an array whose `items` are a single file node.
+ *
+ * Shares {@link isSingleFileNode} with {@link isFileField} by construction, so
+ * the two can never disagree about the same array node — they did, when
+ * `@appstrate/core/form`'s `isMultipleFileField` tested
+ * `!!items.contentMediaType` (truthiness) against an `isFileField` that tested
+ * "declared": for `contentMediaType: ""` the field was a file field that was
+ * not multiple, and the RJSF adapter rendered a single-file widget bound to an
+ * array property. Core's copy is now derived the same way; see the header for
+ * why it is still a copy.
+ */
+export function isMultipleFileField(schema: unknown): boolean {
+  return resolveType(schema) === "array" && isSingleFileNode(resolveItems(schema));
 }

package/src/guarded-fetch.ts

@@ -54,8 +54,51 @@
 
 import { resolveAndCheckHost, type HostResolver } from "./ssrf-dns.ts";
 
+/**
+ * Redirect hops any guarded chain will chase before giving up — the ONE budget
+ * in the codebase, and the default of both followers.
+ *
+ * It used to be two unrelated numbers: `maxRedirects ?? 5` here and a hard
+ * `MAX_REDIRECTS = 10` in `@appstrate/afps-runtime`'s credential-proxy
+ * follower, neither aware of the other. 10 is the surviving value because it is
+ * the one with a reason: the credential proxy walks multi-step OAuth/CAS dances
+ * whose session cookie lands on an intermediate 302 (#473), and five hops does
+ * not always reach the end of one. Nothing is weakened by the raise — every hop
+ * is independently DNS-checked, allowlist-checked and credential-stripped, so
+ * the cap is a loop/DoS bound, not a trust boundary.
+ *
+ * Raising a SHARED default for one caller's benefit would be a poor trade, so
+ * here is the whole roster it applies to. The callers where a longer chain
+ * would be questionable — a signed payload, an inference endpoint, a
+ * registration POST — already pin their own budget and are untouched by the
+ * value here:
+ *
+ *   pinned `maxRedirects: 0`, unaffected
+ *     - `apps/api/src/modules/webhooks/service.ts` — a signed delivery payload
+ *       must never be re-sent to a `Location` target.
+ *     - `apps/api/src/services/llm-proxy/core.ts` — an inference endpoint has
+ *       no legitimate reason to redirect.
+ *     - `packages/connect/src/dcr.ts` — dynamic client registration is a
+ *       single POST to a discovered endpoint.
+ *
+ *   on this default, and all of them multi-step credential exchanges — the
+ *   exact population #473 is about
+ *     - `apps/api/src/services/credential-proxy/core.ts` — the out-of-container
+ *       twin of the `@appstrate/afps-runtime` follower this value came from;
+ *       same vendor auth dances, and it re-runs the caller's `validateHop`
+ *       allowlist assertion on every hop.
+ *     - `packages/connect/src/oauth-egress.ts` — OAuth discovery, token
+ *       exchange and userinfo.
+ *     - `apps/api/src/services/integration-connections.ts` — OAuth
+ *       protected-resource metadata discovery.
+ *     - `apps/api/src/services/org-models.ts` — model-catalog probes.
+ *     - `runtime-pi/sidecar/integrations-boot.ts` — remote MCP transport
+ *       egress.
+ */
+export const DEFAULT_MAX_REDIRECTS = 10;
+
 export interface GuardedFetchOptions {
-  /** Max redirect hops to follow before giving up. Default 5. */
+  /** Max redirect hops to follow before giving up. Default {@link DEFAULT_MAX_REDIRECTS}. */
   maxRedirects?: number;
   /**
    * Deadline in ms covering the redirect chain up to the final response's
@@ -188,7 +231,7 @@ export async function guardedFetch(
   init?: RequestInit,
   opts?: GuardedFetchOptions,
 ): Promise<Response> {
-  const maxRedirects = opts?.maxRedirects ?? 5;
+  const maxRedirects = opts?.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
 
   let current = stripUserInfoAndFragment(new URL(typeof input === "string" ? input : input.href));
   assertHttp(current);
@@ -338,13 +381,50 @@ export async function guardedFetch(
         }
       }
 
-      // 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";
+      // Standard redirect method/body rewriting, per WHATWG fetch
+      // (HTTP-redirect fetch step 11) + RFC 9110 §15.4:
+      //   - 301/302 downgrade POST → GET; every OTHER method is preserved.
+      //   - 303 downgrades everything except GET/HEAD → GET.
+      //   - 307/308 preserve method + body (already dropped above when
+      //     crossing a host boundary).
+      // The 301/302 clause used to read `method !== "HEAD"`, which turned a
+      // 302'd PUT/PATCH/DELETE into a bodyless GET — a request the caller never
+      // made, and a silent one. `@appstrate/afps-runtime`'s credential-proxy
+      // follower always had the conformant rule; this side did not, and the
+      // two disagreed about the same response.
+      const toGet =
+        ((res.status === 301 || res.status === 302) && method === "POST") ||
+        (res.status === 303 && method !== "GET" && method !== "HEAD");
+      if (toGet) {
+        method = "GET";
         dropBody();
       }
+      // A `ReadableStream` body is single-use: hop 0 consumed it, so any hop
+      // that PRESERVES the body is about to re-send a locked stream. The
+      // runtime answers that with an opaque `TypeError: body already used`
+      // from inside `fetch`, naming neither the redirect nor the stream.
+      //
+      // Callers CAN reach this: `apps/api/src/services/credential-proxy/core.ts`
+      // forwards its caller's request body straight through, sets
+      // `duplex: "half"` for the stream case, and takes the default redirect
+      // budget. It has always been reachable via 307/308 (which preserve
+      // method + body unconditionally); making 301/302 conformant for
+      // PUT/PATCH/DELETE widened WHICH statuses land on it, so it is named
+      // here rather than left to surface as a transport-level type error.
+      //
+      // Fail loudly instead of dropping the body: a bodyless PUT the caller
+      // never made, sent silently, is the worse outcome — that is the exact
+      // shape the 301/302 conformance fix removed. Nothing replayable is
+      // affected (string / `Uint8Array` / `FormData` bodies re-send fine), and
+      // a hop that DROPS the body (`toGet` above, or the cross-host containment
+      // below) never gets here.
+      if (body instanceof ReadableStream) {
+        throw new TypeError(
+          `guardedFetch cannot follow a ${res.status} redirect to ${next.origin}: the request ` +
+            `body is a ReadableStream and was already consumed by the previous hop. Buffer the ` +
+            `body before the call, or pass maxRedirects: 0 and handle the redirect yourself.`,
+        );
+      }
       current = next;
       pinnedAddress = nextPin;
       // Drain the redirect response body so the connection can be reused.

package/src/semver-resolve.ts

@@ -9,8 +9,8 @@
  * string, and for applying yank policy by pre-filtering the
  * `rangeVersions` and `distTags` inputs accordingly.
  *
- * This is the SINGLE source of truth, re-exported by
- * `@appstrate/core/semver` and `@appstrate/afps-runtime/bundle/semver-resolve`.
+ * This is the SINGLE source of truth, re-exported by `@appstrate/core/semver`
+ * and imported directly by `@appstrate/afps-runtime`.
  *
  * Conventional yank policy (matches npm/crates.io):
  * - `exactVersions`: include yanked (exact pins always resolve).