@appstrate/afps-shared 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.5.0",
+  "version": "0.7.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",

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/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
@@ -80,7 +123,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.
@@ -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.