@fuguejs/http-auth 0.3.0

package/README.md

@@ -0,0 +1,136 @@
+# @fuguejs/http-auth
+
+A generic **authenticated-REST capability** for the Fugue DAG framework. Any
+DAG that must call a token-auth'd REST API declares `requires: ["authedHttp"]`
+and reads `ctx.authedHttp`. The capability mints and caches a boot-scoped bearer
+token (a generic OAuth2-style password/operator grant), injects it into every
+request, validates responses against Zod schemas, and returns `Result` — no
+exception escapes any method.
+
+This package is **not specific to any single API**. All auth and base-location
+configuration arrives via the factory; nothing is read from `process.env` here
+(FR-060).
+
+## Install
+
+```sh
+bun add @fuguejs/http-auth
+```
+
+`@fuguejs/framework` and `zod` are peer dependencies.
+
+## Usage
+
+```ts
+import { createHttpAuthAdapter } from "@fuguejs/http-auth";
+import { z } from "zod";
+
+const authedHttp = createHttpAuthAdapter({
+  baseUrl: "https://api.example.com",
+  defaultHeaders: { Accept: "application/json" },
+  timeoutMs: 10_000,
+  auth: {
+    tokenUrl: "https://auth.example.com/oauth/token",
+    grantType: "operator_password",
+    params: { brand_key: "acme" },           // static extra form fields
+    basicAuth: { username: "id", password: "secret" }, // optional HTTP Basic
+    credentials: { username: "operator", password: "s3cret" },
+  },
+});
+
+// Register with the host:
+const sharedInfra = { /* ... */ capabilities: [authedHttp] };
+
+// In a node:
+const CustomerSchema = z.object({ id: z.string(), name: z.string() });
+
+createFetchNode({
+  id: "fetch-customer",
+  requires: ["authedHttp"] as const,
+  fetch: (input, ctx) =>
+    ctx.authedHttp.get(`/customers/${input.id}`, { schema: CustomerSchema }),
+});
+```
+
+## Capability surface
+
+`ctx.authedHttp` exposes:
+
+| Method                          | Body | Notes                                  |
+| ------------------------------- | ---- | -------------------------------------- |
+| `get(path, { schema, ... })`    | no   |                                        |
+| `post(path, { schema, body })`  | yes  | body is JSON-stringified               |
+| `put(path, { schema, body })`   | yes  |                                        |
+| `patch(path, { schema, body })` | yes  |                                        |
+| `delete(path, { schema, ... })` | no   |                                        |
+
+No-body verbs (`get`/`delete`) take `AuthedRequestOpts`:
+`{ schema, headers?, timeoutMs? }`. Body verbs (`post`/`put`/`patch`) take
+`AuthedBodyRequestOpts`, which additionally carries `body?` and `contentType?`.
+The body/no-body split lives in the option types alone — passing `body` to a
+no-body verb is a compile error. Every method returns
+`Promise<Result<T, FrameworkError>>`.
+
+## Token management
+
+- **One boot-scoped cached token**, shared across all requests, minted lazily on
+  first use and refreshed when absent or expired (with a 30s clock-skew guard).
+- **Single-flight refresh**: a burst of concurrent callers arriving after expiry
+  mints exactly one token, not N.
+- **401 retry**: on a `401` from any verb, the token is invalidated, re-minted,
+  and the original request retried exactly once.
+
+The boot-scoped cache means steady-state requests inject the cached token without
+a per-request auth round-trip (NFR-001/SC-001). The token and credentials are
+never logged and never returned from any method (NFR-010).
+
+## Error mapping
+
+Mirrors the framework's built-in HTTP capability. The same classification applies
+on **both** the token-mint path and the request path.
+
+| Failure                                       | `FrameworkError.kind`         | Retriable? | Why                                                                                  |
+| --------------------------------------------- | ----------------------------- | ---------- | ------------------------------------------------------------------------------------ |
+| network failure                               | `transient`                   | yes        | A connectivity blip should be retried.                                               |
+| our own timeout (deadline abort, msg "timeout") | `transient`                   | yes        | A slow endpoint should be retried.                                                   |
+| non-timeout `AbortError` (caller/node cancel) | `node-crash` (non-retriable)  | **no**     | A deliberate cancellation must not silently auto-retry the work it stopped.          |
+| HTTP 5xx                                       | `transient` (with httpStatus) | yes        | Server-side fault, typically transient.                                              |
+| HTTP 429 (Too Many Requests)                  | `transient` (with httpStatus) | yes        | Rate-limit — the textbook back-off-and-retry signal.                                 |
+| HTTP 408 (Request Timeout)                    | `transient` (with httpStatus) | yes        | The server timed the request out — retry.                                            |
+| HTTP 4xx (other non-401)                      | `node-crash` (non-retriable)  | **no**     | Deterministic rejection; the same request would just fail again.                     |
+| invalid JSON / schema mismatch                | `node-crash` (non-retriable)  | **no**     | Deterministic payload defect.                                                        |
+| 401 persisting after a token refresh          | `node-crash` (non-retriable)  | **no**     | A second consecutive 401 is settled auth failure, not a transient blip.              |
+
+Timeout vs. cancellation: our **own** deadline abort (we fire it with the message
+`"timeout"`) stays `transient` (retriable), but a non-timeout `AbortError` — a
+caller/node cancellation, including a health-check deadline cancelling its mint —
+maps to a non-retriable `node-crash`, because auto-retrying cancelled work defeats
+the cancellation.
+
+## Lifecycle
+
+The handle returned by `createHttpAuthAdapter` participates in the runtime
+lifecycle:
+
+- `connect()` mints the first token (a bad credential fails boot, not the first
+  run).
+- `healthCheck()` forces a fresh token-mint round-trip, racing a 5s timeout.
+- `close()` is a no-op (no connection pool to drain).
+
+## Testing
+
+Use `createFakeAuthedHttpCapability` to test DAG nodes without network or token
+machinery:
+
+```ts
+import { createFakeAuthedHttpCapability } from "@fuguejs/http-auth";
+
+const fake = createFakeAuthedHttpCapability({
+  "GET /customers/123": { id: "123", name: "Alice" },
+  "POST /orders": { body: { orderId: "ord-1" } },
+  "GET /customers/999": { status: 404, body: "Not Found" },
+});
+```
+
+For unit-testing the real client/provider, inject a fake `fetch` seam via the
+`fetch` config option — no network and no mocking framework required.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fuguejs/http-auth",
+  "version": "0.3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peterstorm/fugue.git",
+    "directory": "packages/http-auth"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@fuguejs/framework": "0.3.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "@fuguejs/framework": {
+      "optional": false
+    },
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@fuguejs/framework": "0.3.0",
+    "@types/bun": "latest",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/__tests__"
+  ]
+}

package/src/auth.ts

@@ -0,0 +1,445 @@
+/**
+ * Generic OAuth2-style token provider for `@fuguejs/http-auth`.
+ *
+ * Mints a single boot-scoped bearer token via an `application/x-www-form-urlencoded`
+ * password/operator grant and caches it. The token is shared across every request;
+ * it is minted lazily on first use, refreshed when absent or expired, and
+ * invalidated on a `401` so the next `get()` re-mints.
+ *
+ * Concurrency: a burst of callers arriving after expiry mints exactly ONE token,
+ * not N — a single in-flight refresh promise de-dups concurrent refreshes.
+ *
+ * NFR-010: the token and credentials never leave this module — `get()` returns
+ * the bearer string only to the client that injects it into an `Authorization`
+ * header, and nothing here logs the token or credentials.
+ *
+ * @see FR-060 — all credentials/locations arrive via config; nothing read from env here.
+ */
+
+import { z } from "zod";
+import type { Result, FrameworkError } from "@fuguejs/framework";
+import { ok, err, nodeId } from "@fuguejs/framework";
+
+// ---------------------------------------------------------------------------
+// Branded bearer token
+// ---------------------------------------------------------------------------
+
+declare const __bearerBrand: unique symbol;
+
+/**
+ * A validated bearer token string. Branded so it cannot be confused with an
+ * arbitrary string (e.g. a username, a header value) at a call site.
+ */
+export type BearerToken = string & { readonly [__bearerBrand]: "BearerToken" };
+
+const asBearerToken = (raw: string): BearerToken => raw as BearerToken;
+
+// ---------------------------------------------------------------------------
+// Fetch seam (single-method port → function type)
+// ---------------------------------------------------------------------------
+
+/**
+ * The slice of the Fetch API the package actually uses. Tests inject a fake;
+ * production passes the platform `fetch`. A single-method port collapses to a
+ * function type — no class, no interface, no mocking framework.
+ */
+export type FetchLike = (
+  url: string,
+  init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+  },
+) => Promise<FetchResponseLike>;
+
+/** The slice of `Response` the package reads. */
+export interface FetchResponseLike {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly statusText: string;
+  readonly text: () => Promise<string>;
+  readonly json: () => Promise<unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Form-field credentials for the password/operator grant. The two mandatory
+ * grant fields are modelled explicitly; any further static fields (a second
+ * factor, a device id) go in `extra` — mirroring how `AuthConfig.params`
+ * carries optional extras. An open index signature is deliberately avoided so a
+ * stray non-string field cannot widen the type and so the shape stays honest.
+ */
+export interface GrantCredentials {
+  readonly username: string;
+  readonly password: string;
+  /** Any further static credential fields (e.g. a second factor). */
+  readonly extra?: Readonly<Record<string, string>>;
+}
+
+/** Optional HTTP Basic auth applied to the token request itself. */
+export interface BasicAuth {
+  readonly username: string;
+  readonly password: string;
+}
+
+/**
+ * Generic OAuth2-style token-grant configuration. All values arrive via config
+ * — nothing is hardcoded or read from `process.env` here (FR-060).
+ */
+export interface AuthConfig {
+  /** Absolute URL of the token endpoint. */
+  readonly tokenUrl: string;
+  /** OAuth2 `grant_type` value (e.g. `"password"`, `"operator_password"`). */
+  readonly grantType: string;
+  /** Static extra form fields merged into the grant body (e.g. a brand key). */
+  readonly params?: Readonly<Record<string, string>>;
+  /** Optional HTTP Basic auth header on the token request. */
+  readonly basicAuth?: BasicAuth;
+  /**
+   * Form-field credentials (username/password and any extras) for resource-owner
+   * style grants (`password`/`operator_password`).
+   *
+   * OPTIONAL because a two-legged `client_credentials` grant carries NO
+   * resource-owner username/password — the client authenticates solely via
+   * `basicAuth` (HTTP Basic `client_id:client_secret`) and any non-secret extras
+   * (brand key, operator) ride in `params`. When omitted, `buildGrantBody` emits
+   * neither `username` nor `password`, so the body is exactly
+   * `grant_type=client_credentials&<params>` — what an OAuth2 client-credentials
+   * token endpoint expects (sending empty `username=`/`password=` would otherwise
+   * be rejected as an `invalid_request`).
+   */
+  readonly credentials?: GrantCredentials;
+  /**
+   * Request timeout for the token mint, in ms. Falls back to the client's
+   * default when absent.
+   */
+  readonly timeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Token provider port
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal capability the client depends on to obtain a bearer token. `get()`
+ * returns a cached token or mints one; `invalidate()` drops the cache so the
+ * next `get()` re-mints (used on a `401`).
+ *
+ * `get()` accepts an optional `AbortSignal`: when a mint is actually performed
+ * (cache miss), aborting the signal cancels the in-flight fetch so a caller that
+ * has given up (e.g. a health check that hit its deadline) does not leave an
+ * orphaned mint that could later repopulate the cache (split-brain). A cancelled
+ * mint maps to a non-retriable `node-crash` (see `mapTokenError`).
+ */
+export interface TokenProvider {
+  get(signal?: AbortSignal): Promise<Result<BearerToken, FrameworkError>>;
+  invalidate(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Token grant — response processing is pure
+// ---------------------------------------------------------------------------
+
+const AUTH_NODE_ID = nodeId("http-auth-token");
+
+/** Sentinel: how long before real expiry we treat a token as stale (clock skew). */
+const EXPIRY_SKEW_MS = 30_000;
+
+/**
+ * Zod schema for a generic OAuth2 token response. `expires_in` is optional —
+ * when absent the token is treated as non-expiring within the boot scope.
+ * Unknown extra fields (scope, refresh_token, …) are tolerated and ignored.
+ */
+const TokenResponseSchema = z.object({
+  access_token: z.string().min(1),
+  expires_in: z.number().optional(),
+});
+
+/** Base64-encode `user:pass` for an HTTP Basic header without leaking via logs. */
+const basicAuthHeader = (basic: BasicAuth): string => {
+  const raw = `${basic.username}:${basic.password}`;
+  // `Buffer` exists under Node and Bun; `btoa` is the browser/edge fallback.
+  const encoded =
+    typeof Buffer !== "undefined"
+      ? Buffer.from(raw, "utf8").toString("base64")
+      : btoa(raw);
+  return `Basic ${encoded}`;
+};
+
+/** Build the `x-www-form-urlencoded` grant body from config. */
+const buildGrantBody = (auth: AuthConfig): string => {
+  const params = new URLSearchParams();
+  params.set("grant_type", auth.grantType);
+  // Resource-owner credentials are emitted ONLY when present. A
+  // `client_credentials` grant omits them entirely (the client authenticates via
+  // `basicAuth`); emitting empty `username=`/`password=` would make a compliant
+  // token endpoint reject the request as `invalid_request`.
+  if (auth.credentials) {
+    params.set("username", auth.credentials.username);
+    params.set("password", auth.credentials.password);
+    if (auth.credentials.extra)
+      for (const [k, v] of Object.entries(auth.credentials.extra)) params.set(k, v);
+  }
+  if (auth.params) for (const [k, v] of Object.entries(auth.params)) params.set(k, v);
+  return params.toString();
+};
+
+/**
+ * HTTP statuses that are retriable despite being non-5xx: `429 Too Many
+ * Requests` (rate-limit — back off and retry) and `408 Request Timeout` (the
+ * server timed the request out — retry). These are the textbook retriable
+ * signals, so we classify them `transient` rather than a non-retriable crash.
+ */
+const RETRIABLE_HTTP_STATUSES: ReadonlySet<number> = new Set([408, 429]);
+
+/**
+ * Map a token-mint failure to a `FrameworkError`. The token/credentials are
+ * never included in the message (NFR-010).
+ *
+ * Retriability policy (see the README error-mapping table):
+ * - `network` / `timeout` (our own timeout abort): `transient` — a blip or a
+ *   slow endpoint should be retried.
+ * - `abort` (a non-timeout `AbortError`, i.e. caller/node cancellation):
+ *   non-retriable `node-crash` — a deliberate cancellation must NOT silently
+ *   auto-retry the very work the caller asked to stop.
+ * - HTTP `5xx`, `429` (rate-limit), `408` (request timeout): `transient` — all
+ *   retriable per `RETRIABLE_HTTP_STATUSES` + the 5xx range.
+ * - any other non-2xx `4xx` or an unparseable body: non-retriable `node-crash`
+ *   (a deterministic rejection — retrying with the same credentials/body would
+ *   just fail again).
+ */
+const mapTokenError = (
+  kind: "network" | "timeout" | "abort" | "http" | "parse",
+  detail: string,
+  status?: number,
+): FrameworkError => {
+  if (kind === "network" || kind === "timeout") {
+    return { kind: "transient", nodeId: AUTH_NODE_ID, message: `Token mint ${kind}: ${detail}` };
+  }
+  // A deliberate (non-timeout) cancellation: do not auto-retry what was cancelled.
+  if (kind === "abort") {
+    return {
+      kind: "node-crash",
+      nodeId: AUTH_NODE_ID,
+      message: `Token mint aborted: ${detail}`,
+      retriability: "non-retriable",
+    };
+  }
+  // 5xx + rate-limit (429) + request-timeout (408) are the retriable HTTP signals.
+  if (kind === "http" && status !== undefined && (status >= 500 || RETRIABLE_HTTP_STATUSES.has(status))) {
+    return { kind: "transient", nodeId: AUTH_NODE_ID, message: `Token mint HTTP ${status}`, httpStatus: status };
+  }
+  if (kind === "http") {
+    return {
+      kind: "node-crash",
+      nodeId: AUTH_NODE_ID,
+      message: `Token mint rejected: HTTP ${status ?? "?"}`,
+      retriability: "non-retriable",
+    };
+  }
+  return {
+    kind: "node-crash",
+    nodeId: AUTH_NODE_ID,
+    message: `Token mint response invalid: ${detail}`,
+    retriability: "non-retriable",
+  };
+};
+
+/** A minted token plus the absolute epoch-ms it expires (or `null` if non-expiring). */
+interface CachedToken {
+  readonly token: BearerToken;
+  readonly expiresAtMs: number | null;
+}
+
+/**
+ * Perform the token grant over the injected fetch seam. Side-effecting I/O is
+ * isolated here; response *processing* (schema, expiry computation) is pure.
+ */
+const mintToken = async (
+  auth: AuthConfig,
+  doFetch: FetchLike,
+  now: () => number,
+  defaultTimeoutMs: number | undefined,
+  externalSignal?: AbortSignal,
+): Promise<Result<CachedToken, FrameworkError>> => {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/x-www-form-urlencoded",
+  };
+  if (auth.basicAuth) headers.Authorization = basicAuthHeader(auth.basicAuth);
+
+  const timeoutMs = auth.timeoutMs ?? defaultTimeoutMs;
+  // A single controller drives BOTH the internal timeout and any external
+  // cancellation. The timeout aborts with an Error("timeout") (→ transient);
+  // an external abort propagates a plain AbortError (→ non-retriable
+  // node-crash), so the two causes stay distinguishable in the catch.
+  let controller: AbortController | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onExternalAbort: (() => void) | undefined;
+  if (timeoutMs != null || externalSignal) {
+    controller = new AbortController();
+    const ctrl = controller;
+    if (timeoutMs != null) {
+      timer = setTimeout(() => ctrl.abort(new Error("timeout")), timeoutMs);
+    }
+    if (externalSignal) {
+      if (externalSignal.aborted) ctrl.abort();
+      else {
+        onExternalAbort = () => ctrl.abort();
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+    }
+  }
+
+  try {
+    const response = await doFetch(auth.tokenUrl, {
+      method: "POST",
+      headers,
+      body: buildGrantBody(auth),
+      signal: controller?.signal,
+    });
+
+    if (!response.ok) {
+      // Best-effort drain so a keep-alive socket is not left dangling; the body
+      // is intentionally NOT surfaced in the error to avoid leaking secrets.
+      await response.text().catch(() => "");
+      return err(mapTokenError("http", "non-2xx", response.status));
+    }
+
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      // Do NOT surface the JSON-parse error text: V8/Bun parse messages echo a
+      // snippet of the offending body, which for a token endpoint can carry the
+      // access_token. A static detail keeps the credential out of logs/errors.
+      return err(mapTokenError("parse", "malformed JSON response"));
+    }
+
+    const parsed = TokenResponseSchema.safeParse(body);
+    if (!parsed.success) {
+      // Surface only the failing field PATHS, never zod's full message (which can
+      // interpolate received values for some issue kinds) — the body may carry a
+      // secret. Paths name which fields were wrong without echoing their values.
+      const paths = parsed.error.issues
+        .map((i) => (i.path.length > 0 ? i.path.join(".") : "(root)"))
+        .join(", ");
+      return err(mapTokenError("parse", `unexpected token response shape (${paths})`));
+    }
+
+    const expiresAtMs =
+      parsed.data.expires_in !== undefined
+        ? now() + parsed.data.expires_in * 1000 - EXPIRY_SKEW_MS
+        : null;
+
+    return ok({ token: asBearerToken(parsed.data.access_token), expiresAtMs });
+  } catch (error) {
+    // Distinguish OUR timeout abort from an external/foreign cancellation. The
+    // abort reason carried on the controller's signal is the source of truth: a
+    // signal-respecting fetch rejects with that reason. Our timeout aborts with
+    // `Error("timeout")`; an external cancel aborts with no/other reason.
+    const reason: unknown = controller?.signal.reason;
+    const isOurTimeout =
+      (reason instanceof Error && reason.message === "timeout") ||
+      (error instanceof Error && (error.message === "timeout" || error.name === "TimeoutError"));
+    const isAbort =
+      controller?.signal.aborted === true ||
+      (error instanceof Error && error.name === "AbortError");
+
+    // Our OWN timeout → transient: a slow auth endpoint should be retried.
+    if (isOurTimeout) {
+      return err(mapTokenError("timeout", `after ${timeoutMs}ms`));
+    }
+    // A non-timeout abort means the caller/node cancelled the mint → must NOT
+    // auto-retry the cancelled work; map to a non-retriable node-crash.
+    if (isAbort) {
+      return err(mapTokenError("abort", "request cancelled"));
+    }
+    return err(mapTokenError("network", error instanceof Error ? error.message : String(error)));
+  } finally {
+    if (timer != null) clearTimeout(timer);
+    if (onExternalAbort && externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Provider factory — the one justified piece of encapsulated mutable state
+// ---------------------------------------------------------------------------
+
+export interface TokenProviderDeps {
+  readonly auth: AuthConfig;
+  readonly fetch: FetchLike;
+  /** Epoch-ms clock seam; defaults to `Date.now`. Injected by tests. */
+  readonly now?: () => number;
+  /** Default mint timeout when `auth.timeoutMs` is absent. */
+  readonly defaultTimeoutMs?: number;
+}
+
+/**
+ * Build a boot-scoped `TokenProvider`. The cached token and the single
+ * in-flight refresh promise are the only mutable state; both are closed over
+ * and never escape. Exported for testing — the adapter factory wires the real
+ * fetch.
+ */
+export const createTokenProvider = (deps: TokenProviderDeps): TokenProvider => {
+  const now = deps.now ?? (() => Date.now());
+  let cached: CachedToken | null = null;
+  // De-dups concurrent refreshes: the first caller to find the cache empty
+  // starts the mint and parks its promise here; later callers in the same burst
+  // await the same promise instead of starting their own mint.
+  let inflight: Promise<Result<CachedToken, FrameworkError>> | null = null;
+  // Cache generation. `invalidate()` bumps it; a refresh captures the
+  // generation when it STARTS and only writes `cached` on settle if the
+  // generation is unchanged. This closes the lost-invalidate race: an
+  // `invalidate()` that lands while a mint is in flight must win — the
+  // resolving mint must not repopulate `cached` with the token the caller just
+  // asked to drop.
+  let generation = 0;
+
+  const isFresh = (entry: CachedToken): boolean =>
+    entry.expiresAtMs === null || entry.expiresAtMs > now();
+
+  const refresh = (signal?: AbortSignal): Promise<Result<CachedToken, FrameworkError>> => {
+    if (inflight) return inflight;
+    const startedGeneration = generation;
+    const p = mintToken(deps.auth, deps.fetch, now, deps.defaultTimeoutMs, signal)
+      .then((result) => {
+        // Only write the cache if no invalidate() intervened since this mint
+        // started — otherwise the just-invalidated token would be resurrected.
+        if (result.ok && generation === startedGeneration) cached = result.value;
+        return result;
+      })
+      .finally(() => {
+        // Clear the in-flight slot so a later expiry can mint afresh. A failed
+        // mint leaves `cached` untouched (still null/stale) so the next call
+        // retries rather than serving a poisoned entry.
+        inflight = null;
+      });
+    inflight = p;
+    return p;
+  };
+
+  return {
+    get: async (signal?: AbortSignal): Promise<Result<BearerToken, FrameworkError>> => {
+      if (cached && isFresh(cached)) return ok(cached.token);
+      const result = await refresh(signal);
+      return result.ok ? ok(result.value.token) : err(result.error);
+    },
+
+    invalidate: (): void => {
+      cached = null;
+      // Bump the generation so any in-flight mint's `.then` write is discarded.
+      generation += 1;
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Exports for the client / adapter
+// ---------------------------------------------------------------------------
+
+export { AUTH_NODE_ID, basicAuthHeader, buildGrantBody, mapTokenError, mintToken };

package/src/client.ts

@@ -0,0 +1,302 @@
+/**
+ * Authenticated REST client for `@fuguejs/http-auth`.
+ *
+ * Wraps the injected fetch seam with:
+ * - automatic injection of the managed bearer token as `Authorization: Bearer …`
+ * - Zod validation of every response body (`Result`, never throws)
+ * - FrameworkError mapping mirroring the framework's built-in HTTP capability
+ *   (timeout/network/5xx → `transient`; invalid JSON/4xx/schema mismatch →
+ *   non-retriable `node-crash`)
+ * - a single `401` retry: on a `401` from any verb, the token is invalidated,
+ *   re-minted, and the original request retried exactly once.
+ *
+ * NFR-010: the token is read from the provider per request and placed only in
+ * the outbound header — it is never logged nor returned from any method.
+ */
+
+import type { z } from "zod";
+import type { Result, FrameworkError } from "@fuguejs/framework";
+import { ok, err, nodeId, frameworkError } from "@fuguejs/framework";
+import type { TokenProvider, FetchLike } from "./auth.js";
+
+const CLIENT_NODE_ID = nodeId("http-auth-client");
+
+// ---------------------------------------------------------------------------
+// Request options & capability surface
+// ---------------------------------------------------------------------------
+
+/** Options for an authenticated request without a body (GET/DELETE). */
+export interface AuthedRequestOpts<T> {
+  /** Zod schema the response body is validated against. */
+  readonly schema: z.ZodType<T>;
+  /** Extra headers merged over the configured defaults (per-call override). */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Per-call timeout in ms; falls back to the client default. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Options for an authenticated request WITH a JSON body (POST/PUT/PATCH). The
+ * body/no-body split is modelled exactly once, here: `body` is a first-class
+ * field of the body-verb opts (not bolted on at the method signature). It is
+ * optional because a body verb with no payload is legitimate (e.g. a `POST`
+ * that signals an action), but it lives on this type alone so `get`/`delete`
+ * cannot accept it and no unsafe cast is needed to read it.
+ */
+export interface AuthedBodyRequestOpts<T> extends AuthedRequestOpts<T> {
+  /** The request payload; always JSON-stringified. Omit for a body-less action. */
+  readonly body?: unknown;
+  /** Content-Type override (header only); the body is always JSON-stringified. */
+  readonly contentType?: string;
+}
+
+/**
+ * The capability nodes see on `ctx.authedHttp`. Every method returns `Result`
+ * — no exception escapes — and auto-injects the managed bearer token. The
+ * body/no-body distinction is carried by the opts types: `get`/`delete` take
+ * `AuthedRequestOpts` (no `body`), `post`/`put`/`patch` take
+ * `AuthedBodyRequestOpts` (with `body`).
+ */
+export interface AuthedHttpCapability {
+  get<T>(path: string, opts: AuthedRequestOpts<T>): Promise<Result<T, FrameworkError>>;
+  post<T>(path: string, opts: AuthedBodyRequestOpts<T>): Promise<Result<T, FrameworkError>>;
+  put<T>(path: string, opts: AuthedBodyRequestOpts<T>): Promise<Result<T, FrameworkError>>;
+  patch<T>(path: string, opts: AuthedBodyRequestOpts<T>): Promise<Result<T, FrameworkError>>;
+  delete<T>(path: string, opts: AuthedRequestOpts<T>): Promise<Result<T, FrameworkError>>;
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/** Join base URL and path, treating an absolute `path` as already complete. */
+export const buildUrl = (baseUrl: string, path: string): string => {
+  if (path.startsWith("http://") || path.startsWith("https://")) return path;
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${suffix}`;
+};
+
+const makeTransientError = (message: string, httpStatus?: number): FrameworkError =>
+  frameworkError.transient(CLIENT_NODE_ID, message, httpStatus);
+
+const makeNodeCrashError = (message: string): FrameworkError => ({
+  kind: "node-crash",
+  nodeId: CLIENT_NODE_ID,
+  message,
+  retriability: "non-retriable",
+});
+
+/**
+ * HTTP statuses that are retriable despite being non-5xx: `429 Too Many
+ * Requests` (rate-limit — back off and retry) and `408 Request Timeout`. These
+ * are the textbook retriable signals, so we classify them `transient` rather
+ * than a non-retriable crash. Mirrors the token-mint path in `auth.ts`.
+ */
+const RETRIABLE_HTTP_STATUSES: ReadonlySet<number> = new Set([408, 429]);
+
+/** A non-2xx response is retriable when it is 5xx, 429 (rate-limit) or 408 (timeout). */
+const isRetriableHttpStatus = (status: number): boolean =>
+  status >= 500 || RETRIABLE_HTTP_STATUSES.has(status);
+
+/**
+ * The raw outcome of a single fetch attempt, before token-refresh logic. We
+ * surface `401` distinctly so the caller can decide to invalidate + retry,
+ * rather than baking the retry into the low-level send.
+ */
+type SendOutcome<T> =
+  | { readonly tag: "ok"; readonly value: T }
+  | { readonly tag: "unauthorized" }
+  | { readonly tag: "error"; readonly error: FrameworkError };
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+export interface AuthedClientConfig {
+  readonly baseUrl: string;
+  readonly defaultHeaders?: Readonly<Record<string, string>>;
+  readonly timeoutMs?: number;
+}
+
+export interface AuthedClientDeps {
+  readonly config: AuthedClientConfig;
+  readonly tokens: TokenProvider;
+  readonly fetch: FetchLike;
+}
+
+// ---------------------------------------------------------------------------
+// Single send attempt (I/O isolated)
+// ---------------------------------------------------------------------------
+
+/**
+ * The body payload for a single send. `body === undefined` means a body-less
+ * request (GET/DELETE, or a body verb invoked with no payload); `contentType`
+ * overrides the default `application/json` header. Extracted from
+ * `AuthedBodyRequestOpts` at the (statically body-typed) call site so neither
+ * `sendOnce` nor `execute` needs an unsafe cast to read body-only fields off
+ * the no-body opts type.
+ */
+interface RequestBody {
+  readonly body: unknown | undefined;
+  readonly contentType?: string;
+}
+
+const NO_BODY: RequestBody = { body: undefined };
+
+const sendOnce = async <T>(
+  deps: AuthedClientDeps,
+  method: string,
+  path: string,
+  token: string,
+  payload: RequestBody,
+  opts: AuthedRequestOpts<T>,
+): Promise<SendOutcome<T>> => {
+  const fullUrl = buildUrl(deps.config.baseUrl, path);
+  const timeoutMs = opts.timeoutMs ?? deps.config.timeoutMs;
+  const body = payload.body;
+
+  const headers: Record<string, string> = {
+    ...deps.config.defaultHeaders,
+    ...opts.headers,
+    Authorization: `Bearer ${token}`,
+  };
+  if (body !== undefined && !headers["Content-Type"] && !headers["content-type"]) {
+    headers["Content-Type"] = payload.contentType ?? "application/json";
+  }
+
+  let controller: AbortController | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  if (timeoutMs != null) {
+    controller = new AbortController();
+    const ctrl = controller;
+    timer = setTimeout(() => ctrl.abort(new Error("timeout")), timeoutMs);
+  }
+
+  try {
+    const response = await deps.fetch(fullUrl, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: controller?.signal,
+    });
+
+    if (response.status === 401) {
+      await response.text().catch(() => "");
+      return { tag: "unauthorized" };
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "<body unreadable>");
+      // 5xx, 429 (rate-limit) and 408 (request timeout) are the retriable HTTP
+      // signals → transient. Every other non-2xx (deterministic 4xx) is a
+      // non-retriable node-crash: retrying the same request would fail again.
+      if (isRetriableHttpStatus(response.status)) {
+        return { tag: "error", error: makeTransientError(`HTTP ${response.status} ${response.statusText}: ${text.slice(0, 500)}`, response.status) };
+      }
+      return { tag: "error", error: makeNodeCrashError(`HTTP ${response.status} ${response.statusText}: ${text.slice(0, 500)}`) };
+    }
+
+    let responseBody: unknown;
+    try {
+      responseBody = await response.json();
+    } catch (parseError) {
+      return {
+        tag: "error",
+        error: makeNodeCrashError(
+          `Response body was not valid JSON: ${parseError instanceof Error ? parseError.message : String(parseError)} (${method} ${fullUrl})`,
+        ),
+      };
+    }
+
+    const parsed = opts.schema.safeParse(responseBody);
+    if (!parsed.success) {
+      return { tag: "error", error: makeNodeCrashError(`Response validation failed: ${parsed.error.message}`) };
+    }
+    return { tag: "ok", value: parsed.data };
+  } catch (error: unknown) {
+    // Distinguish OUR timeout abort from a foreign cancellation. The abort
+    // reason on the controller's signal is the source of truth (a
+    // signal-respecting fetch rejects with that reason): our timeout aborts with
+    // `Error("timeout")`; an external cancel aborts with no/other reason.
+    const reason: unknown = controller?.signal.reason;
+    const isOurTimeout =
+      (reason instanceof Error && reason.message === "timeout") ||
+      (error instanceof Error && (error.message === "timeout" || error.name === "TimeoutError"));
+    const isAbort =
+      controller?.signal.aborted === true ||
+      (error instanceof Error && error.name === "AbortError");
+
+    // Our OWN timeout → transient: a slow endpoint should be retried.
+    if (isOurTimeout) {
+      return { tag: "error", error: makeTransientError(`HTTP request timed out after ${timeoutMs}ms: ${method} ${fullUrl}`) };
+    }
+    // A non-timeout abort means the caller/node cancelled this request →
+    // non-retriable node-crash: auto-retrying cancelled work defeats the cancel.
+    if (isAbort) {
+      return { tag: "error", error: makeNodeCrashError(`HTTP request cancelled: ${method} ${fullUrl}`) };
+    }
+    return {
+      tag: "error",
+      error: makeTransientError(`HTTP request failed: ${error instanceof Error ? error.message : String(error)}`),
+    };
+  } finally {
+    if (timer != null) clearTimeout(timer);
+  }
+};
+
+/**
+ * Execute a request with token injection and a single `401` retry: mint, send;
+ * on `401` invalidate + re-mint + send once more. Any failure to mint a token
+ * short-circuits to that error. No exception escapes.
+ */
+const execute = async <T>(
+  deps: AuthedClientDeps,
+  method: string,
+  path: string,
+  payload: RequestBody,
+  opts: AuthedRequestOpts<T>,
+): Promise<Result<T, FrameworkError>> => {
+  const first = await deps.tokens.get();
+  if (!first.ok) return err(first.error);
+
+  const outcome = await sendOnce(deps, method, path, first.value, payload, opts);
+  if (outcome.tag === "ok") return ok(outcome.value);
+  if (outcome.tag === "error") return err(outcome.error);
+
+  // outcome.tag === "unauthorized": invalidate, re-mint, retry exactly once.
+  deps.tokens.invalidate();
+  const second = await deps.tokens.get();
+  if (!second.ok) return err(second.error);
+
+  const retry = await sendOnce(deps, method, path, second.value, payload, opts);
+  if (retry.tag === "ok") return ok(retry.value);
+  if (retry.tag === "error") return err(retry.error);
+  // A second consecutive 401 — surface as a non-retriable auth failure rather
+  // than looping. The credentials/token are not included (NFR-010).
+  return err(makeNodeCrashError(`Authentication failed after token refresh: ${method} ${path} returned 401`));
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an `AuthedHttpCapability` over an injected token provider and fetch
+ * seam. Exported for testing — `createHttpAuthAdapter` is the production entry
+ * point that owns provider construction and lifecycle.
+ */
+export const createAuthedHttpClient = (deps: AuthedClientDeps): AuthedHttpCapability => ({
+  get: <T>(path: string, opts: AuthedRequestOpts<T>) =>
+    execute(deps, "GET", path, NO_BODY, opts),
+  post: <T>(path: string, opts: AuthedBodyRequestOpts<T>) =>
+    execute(deps, "POST", path, { body: opts.body, contentType: opts.contentType }, opts),
+  put: <T>(path: string, opts: AuthedBodyRequestOpts<T>) =>
+    execute(deps, "PUT", path, { body: opts.body, contentType: opts.contentType }, opts),
+  patch: <T>(path: string, opts: AuthedBodyRequestOpts<T>) =>
+    execute(deps, "PATCH", path, { body: opts.body, contentType: opts.contentType }, opts),
+  delete: <T>(path: string, opts: AuthedRequestOpts<T>) =>
+    execute(deps, "DELETE", path, NO_BODY, opts),
+});
+
+export { CLIENT_NODE_ID };

package/src/index.ts

@@ -0,0 +1,389 @@
+/**
+ * @fuguejs/http-auth — generic authenticated-REST capability for Fugue.
+ *
+ * A reusable building block: any DAG that must call a token-auth'd REST API
+ * declares `requires: ["authedHttp"]` and reads `ctx.authedHttp`. The capability
+ * mints and caches a boot-scoped bearer token (generic OAuth2-style
+ * password/operator grant) and injects it into every request, validating
+ * responses against Zod schemas and returning `Result` — no exception escapes.
+ *
+ * Not specific to any single API: all auth and base-location config arrives via
+ * the factory (FR-060); nothing is read from `process.env` here.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createHttpAuthAdapter } from "@fuguejs/http-auth";
+ *
+ * const authedHttp = createHttpAuthAdapter({
+ *   baseUrl: "https://api.example.com",
+ *   defaultHeaders: { Accept: "application/json" },
+ *   timeoutMs: 10_000,
+ *   auth: {
+ *     tokenUrl: "https://auth.example.com/oauth/token",
+ *     grantType: "operator_password",
+ *     params: { brand_key: "acme" },
+ *     basicAuth: { username: "client-id", password: "client-secret" },
+ *     credentials: { username: "operator", password: "s3cret" },
+ *   },
+ * });
+ *
+ * // Register with the host:
+ * const sharedInfra = { ..., capabilities: [authedHttp] };
+ *
+ * // In a node:
+ * createFetchNode({
+ *   id: "fetch-customer",
+ *   requires: ["authedHttp"] as const,
+ *   fetch: (input, ctx) =>
+ *     ctx.authedHttp.get(`/customers/${input.id}`, { schema: CustomerSchema }),
+ * });
+ * ```
+ *
+ * ## Module Augmentation
+ *
+ * Augments `@fuguejs/framework`'s `CapabilityRegistry` to add `authedHttp`.
+ * After importing this package `requires: ["authedHttp"]` is valid and
+ * `ctx.authedHttp` is typed as `AuthedHttpCapability`.
+ *
+ * @satisfies FR-060, NFR-001/SC-001 (boot-scoped token cache), NFR-010 (no token leak)
+ */
+
+import type { Result, FrameworkError, CapabilityHandle } from "@fuguejs/framework";
+import { ok, err, nodeId, formatFrameworkError } from "@fuguejs/framework";
+
+import {
+  createTokenProvider,
+  type AuthConfig,
+  type BasicAuth,
+  type GrantCredentials,
+  type FetchLike,
+  type FetchResponseLike,
+  type TokenProvider,
+} from "./auth.js";
+import {
+  createAuthedHttpClient,
+  type AuthedHttpCapability,
+  type AuthedRequestOpts,
+  type AuthedBodyRequestOpts,
+} from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Module augmentation
+// ---------------------------------------------------------------------------
+
+declare module "@fuguejs/framework" {
+  interface CapabilityRegistry {
+    /** Authenticated REST capability. Access via `ctx.authedHttp` in nodes. */
+    readonly authedHttp: AuthedHttpCapability;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports (public surface)
+// ---------------------------------------------------------------------------
+
+export {
+  createTokenProvider,
+  createAuthedHttpClient,
+};
+export type {
+  AuthedHttpCapability,
+  AuthedRequestOpts,
+  AuthedBodyRequestOpts,
+  AuthConfig,
+  BasicAuth,
+  GrantCredentials,
+  FetchLike,
+  FetchResponseLike,
+  TokenProvider,
+};
+// Note: `BearerToken` is intentionally NOT exported. It is an internal brand —
+// no public API consumes or produces it (the token never crosses the capability
+// boundary, NFR-010), so exporting it would only leak an internal type.
+export { buildUrl, type AuthedClientConfig } from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Full configuration for the authenticated-HTTP adapter. ALL config — nothing
+ * hardcoded, nothing read from the environment here (FR-060).
+ */
+export interface HttpAuthConfig {
+  /** Base URL prepended to relative request paths. */
+  readonly baseUrl: string;
+  /** Default headers applied to every request (per-call overridable). */
+  readonly defaultHeaders?: Readonly<Record<string, string>>;
+  /** Default request timeout in ms (per-call overridable). */
+  readonly timeoutMs?: number;
+  /** Token-grant configuration. */
+  readonly auth: AuthConfig;
+  /**
+   * Optional fetch seam override. Defaults to the platform `fetch`. Tests pass
+   * a fake; production omits this.
+   */
+  readonly fetch?: FetchLike;
+  /** Optional epoch-ms clock seam for token expiry; defaults to `Date.now`. */
+  readonly now?: () => number;
+}
+
+// ---------------------------------------------------------------------------
+// Default fetch adapter (imperative shell)
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapt the platform `fetch` to the narrow `FetchLike` seam. The vendor type
+ * (`globalThis.fetch`) is confined to this one adapter so the core never sees
+ * it.
+ */
+const platformFetch: FetchLike = async (url, init) => {
+  const response = await fetch(url, {
+    method: init.method,
+    headers: init.headers,
+    body: init.body,
+    signal: init.signal,
+  });
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    text: () => response.text(),
+    json: () => response.json(),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/** Health-check token mints are bounded so a hung auth endpoint reports unhealthy. */
+const HEALTH_CHECK_TIMEOUT_MS = 5_000;
+
+/**
+ * Create an authenticated-HTTP capability handle.
+ *
+ * Lifecycle:
+ * - `connect()` mints the first token (fails boot if credentials are bad).
+ * - `healthCheck()` does a token-mint round-trip, racing a 5s timeout.
+ * - `close()` is a no-op (no pool to drain).
+ *
+ * The boot-scoped token cache means a steady-state request injects the cached
+ * token without a per-request auth round-trip (NFR-001/SC-001).
+ */
+export const createHttpAuthAdapter = (config: HttpAuthConfig): CapabilityHandle<"authedHttp"> => {
+  const doFetch = config.fetch ?? platformFetch;
+
+  const tokens = createTokenProvider({
+    auth: config.auth,
+    fetch: doFetch,
+    now: config.now,
+    defaultTimeoutMs: config.timeoutMs,
+  });
+
+  const client = createAuthedHttpClient({
+    config: {
+      baseUrl: config.baseUrl,
+      defaultHeaders: config.defaultHeaders,
+      timeoutMs: config.timeoutMs,
+    },
+    tokens,
+    fetch: doFetch,
+  });
+
+  return {
+    name: "authedHttp",
+    client,
+
+    connect: async () => {
+      // Mint the first token so a bad credential fails boot, not the first run.
+      const minted = await tokens.get();
+      if (!minted.ok) {
+        // The error message is secret-free by construction (NFR-010).
+        throw new Error(`http-auth connect failed: ${describeError(minted.error)}`);
+      }
+    },
+
+    close: async () => {
+      // Stateless beyond the in-memory token cache — nothing to drain.
+    },
+
+    healthCheck: () => healthCheckWithTimeout(tokens, HEALTH_CHECK_TIMEOUT_MS),
+  };
+};
+
+/**
+ * Render a FrameworkError to a short, secret-free string for boot diagnostics.
+ * Delegates to the framework's exhaustive `formatFrameworkError` so a NEW
+ * `FrameworkError` variant can never silently lose context here — adding a kind
+ * without a case there is a compile error, which this inherits. (NFR-010: the
+ * error variants this package emits never embed the token/credentials.)
+ */
+const describeError = (error: FrameworkError): string => formatFrameworkError(error);
+
+/**
+ * Run a fresh token mint against a deadline. A hung auth endpoint reports
+ * unhealthy instead of stalling the caller, AND the underlying mint is actually
+ * cancelled on timeout via an `AbortController` — so an orphaned mint cannot
+ * later repopulate the cache (split-brain). Exported for testing.
+ */
+export const healthCheckWithTimeout = async (
+  tokens: TokenProvider,
+  timeoutMs: number,
+): Promise<Result<void, string>> => {
+  // Drive the mint off this controller's signal so a deadline hit cancels the
+  // in-flight fetch rather than leaving it running detached.
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined = setTimeout(
+    () => controller.abort(new Error(`health check timed out after ${timeoutMs}ms`)),
+    timeoutMs,
+  );
+  try {
+    // Force a mint round-trip so the check exercises the real auth path. The
+    // signal cancels that mint on timeout (no orphaned, cache-populating fetch).
+    tokens.invalidate();
+    const result = await tokens.get(controller.signal);
+    if (result.ok) return ok(undefined);
+    // A cancelled mint surfaces as a node-crash whose message names the deadline;
+    // formatFrameworkError keeps it secret-free.
+    return err(describeError(result.error));
+  } catch (e) {
+    // get() is Result-based and must not throw; this is defence-in-depth.
+    return err(e instanceof Error ? e.message : String(e));
+  } finally {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Fake for testing
+// ---------------------------------------------------------------------------
+
+/**
+ * A canned response for one route in the fake capability. A `status` outside
+ * 2xx produces the same error classification as the real client (5xx →
+ * transient, other non-2xx → non-retriable node-crash); a `matchBody` that
+ * returns `false` fails the route so a wrong-payload bug surfaces in tests.
+ *
+ * Construct one with {@link shapedRoute} — that brand is how the fake tells a
+ * shaped route apart from a raw payload, so a raw payload that happens to carry
+ * a `body`/`status` field is never misread as control metadata.
+ */
+export interface FakeAuthedHttpRoute {
+  readonly status?: number;
+  readonly body: unknown;
+  readonly matchBody?: (body: unknown) => boolean;
+}
+
+/**
+ * Brand marking a route value as a shaped {@link FakeAuthedHttpRoute} rather
+ * than a raw verbatim payload. A unique symbol (not a `"body" in route` shape
+ * heuristic) so a raw payload can never accidentally look shaped — the only way
+ * to carry it is through {@link shapedRoute}.
+ */
+const SHAPED_ROUTE: unique symbol = Symbol("fuguejs.http-auth.shapedRoute");
+
+type ShapedAuthedHttpRoute = FakeAuthedHttpRoute & { readonly [SHAPED_ROUTE]: true };
+
+/**
+ * Wrap a {@link FakeAuthedHttpRoute} so the fake treats it as control metadata
+ * (status / matchBody / explicit body) instead of a raw response payload. Any
+ * route value NOT built with this helper is returned verbatim, so payloads that
+ * legitimately contain a top-level `body` field round-trip unchanged.
+ *
+ * @example
+ * ```ts
+ * createFakeAuthedHttpCapability({
+ *   "GET /customers/123": { id: "123", name: "Alice" },          // raw — returned verbatim
+ *   "GET /raw": { id: "1", body: "note" },                       // raw — `body` field preserved
+ *   "POST /orders": shapedRoute({ body: { orderId: "ord-1" } }), // shaped — `body` is the response
+ *   "GET /missing": shapedRoute({ status: 404, body: "Not Found" }),
+ * });
+ * ```
+ */
+export const shapedRoute = (route: FakeAuthedHttpRoute): ShapedAuthedHttpRoute => ({
+  ...route,
+  [SHAPED_ROUTE]: true,
+});
+
+const isShapedRoute = (route: unknown): route is ShapedAuthedHttpRoute =>
+  typeof route === "object" && route !== null && (route as Record<symbol, unknown>)[SHAPED_ROUTE] === true;
+
+/**
+ * In-memory fake `AuthedHttpCapability` for testing DAG nodes that use
+ * `ctx.authedHttp`. No network, no token machinery — routes match on
+ * `"METHOD /path"` (or the bare path). Mirrors `createFakeHttpCapability`.
+ *
+ * @remarks
+ * A route value is a *raw* payload (returned verbatim) unless it was built with
+ * {@link shapedRoute}, which brands it as control metadata (`status`/`matchBody`/
+ * explicit `body`). Detection is by that brand — NOT a `"body" in route` shape
+ * heuristic — so a raw payload that legitimately carries a top-level `body`
+ * field round-trips unchanged instead of being misread as a shaped route.
+ *
+ * @example
+ * ```ts
+ * const fake = createFakeAuthedHttpCapability({
+ *   "GET /customers/123": { id: "123", name: "Alice" },               // raw
+ *   "POST /orders": shapedRoute({ body: { orderId: "ord-1" } }),      // shaped
+ *   "GET /customers/999": shapedRoute({ status: 404, body: "Not Found" }),
+ * });
+ * ```
+ */
+export const createFakeAuthedHttpCapability = (
+  routes: Readonly<Record<string, unknown>>,
+): CapabilityHandle<"authedHttp"> => {
+  const client: AuthedHttpCapability = {
+    get: async (path, opts) => matchRoute("GET", path, undefined, opts.schema, routes),
+    post: async (path, opts) => matchRoute("POST", path, opts.body, opts.schema, routes),
+    put: async (path, opts) => matchRoute("PUT", path, opts.body, opts.schema, routes),
+    patch: async (path, opts) => matchRoute("PATCH", path, opts.body, opts.schema, routes),
+    delete: async (path, opts) => matchRoute("DELETE", path, undefined, opts.schema, routes),
+  };
+  return { name: "authedHttp", client };
+};
+
+const FAKE_NODE_ID_KIND = "node-crash" as const;
+const FAKE_NODE_ID = nodeId("http-auth-fake");
+
+const matchRoute = <T>(
+  method: string,
+  path: string,
+  requestBody: unknown,
+  schema: import("zod").z.ZodType<T>,
+  routes: Readonly<Record<string, unknown>>,
+): Result<T, FrameworkError> => {
+  const key = `${method} ${path}`;
+  const route = routes[key] ?? routes[path];
+  if (route == null) {
+    return err({ kind: "transient", nodeId: FAKE_NODE_ID, message: `No fake route matched: ${key}` });
+  }
+
+  const shaped = isShapedRoute(route);
+
+  if (shaped) {
+    const matchBody = route.matchBody;
+    if (matchBody && !matchBody(requestBody)) {
+      return err({ kind: "transient", nodeId: FAKE_NODE_ID, message: `Fake route ${key}: request body did not match matchBody` });
+    }
+    const status = route.status;
+    if (status != null && (status < 200 || status >= 300)) {
+      const bodyText = String(route.body ?? "");
+      if (status >= 500) {
+        return err({ kind: "transient", nodeId: FAKE_NODE_ID, message: `HTTP ${status}: ${bodyText.slice(0, 500)}`, httpStatus: status });
+      }
+      return err({ kind: FAKE_NODE_ID_KIND, nodeId: FAKE_NODE_ID, message: `HTTP ${status}: ${bodyText.slice(0, 500)}`, retriability: "non-retriable" });
+    }
+  }
+
+  const body = shaped ? route.body : route;
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    return err({ kind: FAKE_NODE_ID_KIND, nodeId: FAKE_NODE_ID, message: `Fake route response validation failed: ${parsed.error.message}`, retriability: "non-retriable" });
+  }
+  return ok(parsed.data);
+};