@metalabel/dfos-client 0.31.0 → 0.33.0

package/README.md

@@ -1,6 +1,8 @@
 # @metalabel/dfos-client
 
-The high-level read client for the [DFOS protocol](https://protocol.dfos.com). The protocol library owns the crypto truth (CID re-derivation, signature verification, chain folding); this client owns the four things it deliberately refuses to do: **fetch, resolve, verify-orchestration, and cache** — over an untrusted set of relays. It holds no keys and never writes.
+The client-side kit for participating in the [DFOS protocol](https://protocol.dfos.com) — **resolve, verify, prove**. The protocol library owns the crypto truth (CID re-derivation, signature verification, chain folding); this client owns the four things it deliberately refuses to do: **fetch, resolve, verify-orchestration, and cache** — over an untrusted set of relays — plus the two proof surfaces that ride on top of them, [SIWD](#metalabeldfos-clientsiwd) and [API-AUTH](#metalabeldfos-clientapi-auth).
+
+**It holds no keys.** Signing is always a `sign` callback the caller supplies: this kit composes the exact bytes that must be signed and hands them over, and key material never crosses into it.
 
 If verification logic appears in this package, that is the bug: every proof comes from `@metalabel/dfos-protocol`.
 
@@ -73,6 +75,65 @@ import { indexedDbStore, memoryStore } from '@metalabel/dfos-client/store';
 
 `memoryStore()` (the isomorphic default) caches the **log**. Chain reads fully drain from zero, require the fetched JWS tokens to match the trusted cached prefix, and verify forward only the suffix, so a key rotation costs one verification op and the cache is never stale-wrong. `indexedDbStore()` is the browser-only durable adapter — the only heavy dependency, quarantined behind this subpath.
 
+### `@metalabel/dfos-client/api-auth`
+
+API Authentication request proofs. A proof is a short-lived JWS, signed by the key a DFOS credential was issued to, that binds one exact HTTP request — method, host, path, body — to that credential. The credential says what its holder may do; the proof says the holder is the one doing it, and doing exactly this. See the [API-AUTH specification](https://protocol.dfos.com/api-auth).
+
+**Spending a credential: a signing `fetch`.** Hand it to any API client with a fetch seam, and every request that client composes goes out credential-gated.
+
+```typescript
+import { createDfosApi } from '@metalabel/dfos-api';
+import { createApiAuthFetch } from '@metalabel/dfos-client/api-auth';
+
+const api = createDfosApi({ fetch: createApiAuthFetch({ credential, kid, sign }) });
+
+const { data } = await api.GET('/profile');
+```
+
+Three inputs, and they are the irreducible ones: the credential JWS to present, the DID URL of the key it was issued to, and a `sign` callback over bytes. The proof's `credentialCID` is read from the credential's own header, so the two can never drift apart. Pass `fetch` to supply the underlying transport (default `globalThis.fetch`).
+
+It signs **exactly the `Request` it receives** — the method, the origin-form target, and the body octets already composed — rather than a description of one. That is what keeps the binding honest: the bytes the proof covers are the bytes that go on the wire.
+
+Three consequences worth knowing before you wire it up:
+
+- **It refuses to sign a plaintext request** to anything but loopback (`localhost`, `127.0.0.1`, `[::1]`). `api:` surfaces are HTTPS surfaces, and a proof sent in the clear replays for its whole freshness window.
+- **It does not follow redirects** (`redirect: 'manual'`): a 3xx comes back to you as-is, because following it would re-issue the request at coordinates the proof does not cover and carry `X-Credential` to whatever authority the `Location` names.
+- **It buffers the request body before sending.** The proof covers the whole body, so there is nothing to sign until the last octet is in hand — size-bounded requests only. An unbounded or live stream cannot be proof-signed, in any implementation.
+
+**A backend that must not proxy uses the decomposed form.** A signing backend fronting a browser must authorize the coordinates it is about to sign against its own session, not sign whatever `{method, path, body}` the browser hands it — a backend that signs blindly is an oracle for every credential it holds ([Security Considerations](https://protocol.dfos.com/api-auth#security-considerations)). Such a backend describes the one request it is willing to make, so there is no `Request` for the adapter above to cover:
+
+```typescript
+import { buildApiAuthHeaders, signApiRequest } from '@metalabel/dfos-client/api-auth';
+
+const { proof } = await signApiRequest({
+  method: 'GET',
+  host: 'api.example',
+  path: '/profile',
+  credentialCID,
+  kid,
+  sign,
+});
+const headers = buildApiAuthHeaders({ proof, credential });
+```
+
+**Verifying** is the other half, and it lives here so that an API host's middleware is a thin adapter over the kit rather than a second implementation of the spec's eleven steps:
+
+```typescript
+import { verifyApiRequest } from '@metalabel/dfos-client/api-auth';
+
+await verifyApiRequest(client, {
+  proof,
+  credential,
+  method: 'GET',
+  host: 'api.example', // the verifier's OWN configured authority, never a request header
+  path: '/profile',
+});
+```
+
+It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `unverifiable` / `config`), `phase`, and the recommended `status` — branch on those, never on message text.
+
+`apiRequestSigningInput(payload)` is the pure byte contract both halves share, and the one place per language the canonical bytes are built.
+
 ### `@metalabel/dfos-client/siwd`
 
 ```typescript
@@ -86,7 +147,19 @@ import {
 
 Sign In With DFOS. The three verbs above are the relying-party login kit, in the order a login uses them: `createSiwdLoginRequest` mints the challenge and builds the `/authorize` URL to redirect to, `readSiwdCallback` parses what comes back, and `verifySiwd` verifies it — mint → redirect, read → verify. The `expect` object `createSiwdLoginRequest` returns (nonce, domain, and the DID when the challenge is bound to one) is what `verifySiwd` checks against, so the relying party MUST persist it across the redirect: a verifier that takes its expectation from the callback has implemented the check and none of the protection. See [`examples/siwd-demo`](../../examples/siwd-demo) for the reference consumer.
 
-In production, spend the nonce instead of comparing it:
+The `nonce`/`consumeNonce` pair on the expectation (supply exactly one) is the spec's [two replay disciplines](../../specs/SIWD.md#replay-prevention), one field each:
+
+**`expect.nonce` — flow-bound login.** For a backend granting only a browser session (`scope=identity`), source the expected nonce from state you bound to that browser at mint time — a server-side session, or the nonce sealed under your own key in an `httpOnly` cookie — and compare:
+
+```typescript
+// mint: cookie = `${nonce}.${hmacSha256(secret, nonce)}`, httpOnly, Max-Age ≤ your window
+// verify: unseal the cookie back to `nonce` (full-length tag, constant-time compare), then
+await verifySiwd(client, jws, { domain, nonce });
+```
+
+The seal (or the session) is what makes this a defense at all: a _bare_ cookie value is presenter-supplied, and an attacker replaying a captured JWS can read the nonce out of the artifact and send it as the cookie. Never compare against anything the presenter could have authored.
+
+**`consumeNonce` — spend the nonce.** Required the moment success grants anything beyond a session with the presenting browser (a credential-returning scope, a portable token, a profile-B mailbox flow):
 
 ```typescript
 await verifySiwd(client, jws, {
@@ -95,7 +168,7 @@ await verifySiwd(client, jws, {
 });
 ```
 
-`consumeNonce` replaces `expect.nonce` (supply exactly one) and returns true iff **this** verifier minted the nonce and it was unspent — membership in verifier-minted state is what satisfies the spec's rule that the verifier MUST have minted the nonce it checks, and deleting it in the same operation is what makes it single-use. The atomicity is the caller's: a get-then-delete lets two concurrent replays both win, where a Redis `GETDEL` or a `DELETE … RETURNING` does not. It is called at most once, and only after every other check has passed, so an invalid presentation can never burn a nonce the user is still holding.
+`consumeNonce` returns true iff **this** verifier minted the nonce and it was unspent — membership in verifier-minted state is what satisfies the spec's rule that the verifier MUST have minted the nonce it checks, and deleting it in the same operation is what makes it single-use. The atomicity is the caller's: a get-then-delete lets two concurrent replays both win, where a Redis `GETDEL` or a `DELETE … RETURNING` does not. Under either discipline the nonce check runs at most once, and only after every other check has passed, so an invalid presentation can never burn a nonce the user is still holding.
 
 `createSiwdLoginRequest` throws rather than returning an error on the two things that are RP misconfiguration: an `authorizeUrl` or `redirectUri` that is not an absolute URL, and any scope other than `identity` over a loopback redirect (a local port holds no `client_did` for a credential to be issued to — see [SIWD.md](../../specs/SIWD.md)).
 

package/dist/api-auth.d.ts

@@ -0,0 +1,296 @@
+import { a as Client } from './types-ByxTj1u-.js';
+import '@metalabel/dfos-protocol/chain';
+import '@metalabel/dfos-protocol/credentials';
+import '@metalabel/dfos-web-relay/peer-client';
+
+/**
+ * The normative JWS header `typ` for a request proof (API-AUTH.md). Signers MUST
+ * set it; `verifyApiRequest` rejects anything else — it is also what lets
+ * typ-routing dispatchers tell a proof apart from credentials and chain ops.
+ */
+declare const REQUEST_PROOF_JWS_TYP = "did:dfos:request-proof";
+/**
+ * The digest of zero octets. A request with no body hashes the empty string —
+ * there is deliberately no absent-member form for bodyless requests, so every
+ * proof is checked the same way.
+ */
+declare const EMPTY_BODY_SHA256 = "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU";
+/** Size cap on the serialized proof token, checked BEFORE any decode. */
+declare const MAX_REQUEST_PROOF_SIZE = 4096;
+/** RECOMMENDED acceptance window `W` — how old a proof may be, in seconds. */
+declare const DEFAULT_PROOF_WINDOW_SECONDS = 60;
+/** RECOMMENDED clock-skew allowance `S` — how forward-dated a proof may be. */
+declare const DEFAULT_PROOF_SKEW_SECONDS = 60;
+/**
+ * The binding cap on `W + S`: the total span over which any one proof is
+ * accepted, and therefore its worst-case replay window. A configuration
+ * exceeding it is refused rather than clamped — a deployment that silently got a
+ * 10-minute replay window it did not ask for is the failure this forbids.
+ */
+declare const MAX_PROOF_FRESHNESS_SPAN_SECONDS = 300;
+/** The v0 action registry's only token. */
+declare const DEFAULT_API_ACTION = "read:profile";
+/**
+ * Default cap on the decoded body a verifier will hash, in bytes (1 MiB). The v0
+ * action registry is bodyless, so this never binds today; it is the defensive
+ * ceiling for the first body-bearing action, overridable per verifier.
+ */
+declare const MAX_BODY_BYTES = 1048576;
+interface RequestProofPayload {
+    /** The HTTP method, uppercase. */
+    method: string;
+    /** The API's lowercase authority — `host` on 443, `host:port` otherwise. */
+    host: string;
+    /** The exact origin-form request target — path plus query string, byte for byte. */
+    path: string;
+    /** Canonical unpadded base64url of the SHA-256 of the raw request body octets. */
+    bodyHash: string;
+    /** CID of the leaf credential presented alongside this proof. */
+    credentialCID: string;
+    /** Issued-at — unix seconds (positive integer). */
+    iat: number;
+}
+/**
+ * THE BYTE CONTRACT. Serializes a payload to the canonical bytes that ARE the
+ * JWS payload segment — a fixed key order (method, host, path, bodyHash,
+ * credentialCID, iat) with no insignificant whitespace, and `iat` as a bare JSON
+ * integer.
+ *
+ * HTML ESCAPING IS OFF, by construction: `path` routinely carries `&` and admits
+ * `<` and `>`, and `JSON.stringify` emits all three literally. The Go byte-twin
+ * hand-rolls the same serialization (`ApiRequestSigningInput`) precisely because
+ * `encoding/json` would emit `\u0026` / `\u003c` / `\u003e` instead and silently fork
+ * the signed bytes.
+ *
+ * PURE and clientless: import it in a signing backend and in a verifier alike.
+ */
+declare const apiRequestSigningInput: (payload: RequestProofPayload) => Uint8Array;
+/**
+ * The `bodyHash` member: canonical unpadded base64url of the SHA-256 of the
+ * APPLICATION body octets — the bytes the sender handed its HTTP client, which a
+ * verifier obtains after reversing transfer encoding and content encoding. Zero
+ * octets hash to `EMPTY_BODY_SHA256`.
+ */
+declare const sha256BodyHash: (body: Uint8Array) => string;
+interface SignApiRequestInput {
+    /** The HTTP method, uppercase. */
+    method: string;
+    /** The API's lowercase authority — `host` on 443, `host:port` otherwise. */
+    host: string;
+    /** The exact origin-form request target this proof will ride. */
+    path: string;
+    /** Application body octets; omitted or empty hashes to `EMPTY_BODY_SHA256`. */
+    body?: Uint8Array;
+    /** CID of the leaf credential presented alongside this proof. */
+    credentialCID: string;
+    /**
+     * The signing key's DID URL. Its DID portion MUST be the leaf credential's
+     * `aud` — that equality IS the possession being proven.
+     */
+    kid: string;
+    /** Raw Ed25519 signer over the JWS signing input. */
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+    /** Issued-at override — unix seconds. Default `Math.floor(Date.now() / 1000)`. */
+    iat?: number;
+}
+/**
+ * Sign one request. The producer half of the byte contract.
+ *
+ * `createJws` serializes the payload with `JSON.stringify`, so passing the
+ * fixed-order object makes the emitted payload segment EXACTLY
+ * `apiRequestSigningInput(payload)` — the equivalence is pinned by a test rather
+ * than assumed, because it is the whole reason there is one byte contract and
+ * not two.
+ */
+declare const signApiRequest: (input: SignApiRequestInput) => Promise<{
+    proof: string;
+    payload: RequestProofPayload;
+}>;
+/**
+ * The two headers a credential-gated request carries. The `Authorization` scheme
+ * is the token `DFOS`, deliberately NOT `Bearer`: nothing carried here is a
+ * bearer token, and naming it one invites bearer handling (logging, caching,
+ * forwarding) that this artifact exists to make useless.
+ */
+declare const buildApiAuthHeaders: (input: {
+    proof: string;
+    credential: string;
+}) => {
+    Authorization: string;
+    "X-Credential": string;
+};
+interface CreateApiAuthFetchOptions {
+    /**
+     * The leaf credential JWS to present — the `X-Credential` value, and the
+     * source of every proof's `credentialCID`. It embeds its chain in `prf`.
+     */
+    credential: string;
+    /**
+     * The signing key's DID URL. Its DID portion MUST be the credential's `aud` —
+     * that equality IS the possession being proven.
+     */
+    kid: string;
+    /** Raw Ed25519 signer over the JWS signing input. Never key material. */
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+    /** The underlying transport. Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * A signing `fetch`. Hand it to any API client with a fetch seam and every
+ * request that client composes goes out credential-gated:
+ *
+ * ```ts
+ * createDfosApi({ fetch: createApiAuthFetch({ credential, kid, sign }) })
+ * ```
+ *
+ * It signs EXACTLY the `Request` it receives — the method, the origin-form
+ * target, and the body octets already composed — rather than a description of
+ * one. That is what keeps the binding honest: the bytes the proof covers are the
+ * bytes that go on the wire.
+ *
+ * `signApiRequest` stays exported for the backends that must NOT proxy. A
+ * signing backend fronting a browser MUST authorize the coordinates it is about
+ * to sign against its own session (API-AUTH.md, Security Considerations) — it
+ * describes the one request it is willing to make rather than receiving one, so
+ * there is no `Request` for this adapter to cover.
+ *
+ * Two things are deliberately absent. There is no credential-provider callback:
+ * a caller whose credential rotates builds a new fetch, which is one line and
+ * has no lifecycle to get wrong. And there is no host allowlist: the caller
+ * composing the URL is already the party choosing the host, so an allowlist here
+ * would guard a decision it does not make.
+ *
+ * TWO REFUSALS, both because the adapter is the last place that can see them.
+ * It will not sign a plaintext request to a real host (`api:` surfaces are HTTPS
+ * surfaces — the proof and the credential would go out in the clear, and the
+ * proof replays over HTTPS for its whole freshness window), and it will not
+ * follow redirects.
+ *
+ * BUFFERING IS INHERENT. The byte contract hashes the complete body before
+ * signing, so a request body is buffered in full before anything is sent. This
+ * adapter is for size-bounded requests; an unbounded or live stream cannot be
+ * proof-signed at all, in any implementation.
+ */
+declare const createApiAuthFetch: (options: CreateApiAuthFetchOptions) => typeof fetch;
+/**
+ * The verdict class. Branch on `reason`, never on message text.
+ *
+ * - `invalid` — checked and failed.
+ * - `unverifiable` — could not check (an unresolvable presenter, an unreachable
+ *   revocation source). A transient resolution failure is the server's
+ *   condition, not the caller's.
+ * - `config` — the DEPLOYMENT is misconfigured (a `W + S` over the 300-second
+ *   ceiling, or an empty required action). Not a judgment about the artifact.
+ */
+type RequestProofFailureReason = 'invalid' | 'unverifiable' | 'config';
+/**
+ * The verification phase a failure arose in. Load-bearing for HTTP mapping: an
+ * `invalid` proof-layer failure is a 401 (with a `WWW-Authenticate: DFOS`
+ * challenge), an `invalid` credential-layer failure is a 403. `status` carries
+ * the recommended code directly so middleware never has to re-derive it.
+ */
+type RequestProofFailurePhase = 'proof' | 'credential' | 'config';
+/** Branch on `reason`/`phase`/`status`, never on message text. */
+declare class ApiRequestVerifyError extends Error {
+    readonly reason: RequestProofFailureReason;
+    readonly phase: RequestProofFailurePhase;
+    /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid, 503 unverifiable, 500 config. */
+    readonly status: number;
+    constructor(reason: RequestProofFailureReason, phase: RequestProofFailurePhase, status: number, message: string);
+}
+interface VerifyApiRequestInput {
+    /** The request-proof JWS — the `Authorization: DFOS <token>` token, scheme stripped. */
+    proof: string;
+    /** The leaf credential JWS — the `X-Credential` value. It embeds its chain in `prf`. */
+    credential: string;
+    /**
+     * THE VERIFIER'S OWN CONFIGURED AUTHORITY for the route being served — a value
+     * the deployment holds, NEVER one read from the request. `Host`,
+     * `X-Forwarded-Host`, and the request URL's authority are all attacker-supplied:
+     * a verifier that compared the proof's `host` against a request header would
+     * have no host binding at all. Include the port when it is not 443.
+     *
+     * It is also the id half of the `api:<host>` resource string this verifier
+     * requires, so the request binding and the grant name the same origin.
+     */
+    host: string;
+    /** The received request's method. */
+    method: string;
+    /** The received origin-form request target — path plus query string, byte for byte. */
+    path: string;
+    /** The received application body octets, post-content-decoding. Omitted = no body. */
+    body?: Uint8Array;
+    /**
+     * Cap on the decoded body this verifier will hash, in bytes. Default
+     * `MAX_BODY_BYTES`. A body over the cap is refused BEFORE the SHA-256 (a
+     * proof-layer `413`), so a well-formed proof with a bad signature cannot force
+     * an unbounded hash. NOTE: the spec's "abort decode at the cap" is a MIDDLEWARE
+     * obligation — by the time the body reaches this helper it is already a buffered
+     * `Uint8Array`, so this is the second, defensive cap; the middleware must still
+     * bound decoding upstream (a decompression bomb inflates before the kit sees it).
+     */
+    maxBodyBytes?: number;
+    /** The action token this route requires. Default `read:profile`. */
+    action?: string;
+    /** Acceptance window `W`, seconds. Default 60. `W + S` MUST NOT exceed 300. */
+    windowSeconds?: number;
+    /** Clock-skew allowance `S`, seconds. Default 60. `W + S` MUST NOT exceed 300. */
+    skewSeconds?: number;
+    /**
+     * Accept a presenter resolution whose tip could not be verified (cache-only or
+     * empty-delta-against-cache). Default FALSE: key resolution is CURRENT-STATE,
+     * and a rotated-out key must not keep minting proofs against a stale cache.
+     */
+    allowStale?: boolean;
+    /** Clock injection (unix ms). Default `Date.now()`. */
+    now?: () => number;
+}
+interface VerifiedRequestProof {
+    /** The chain's root `iss` — the DID whose data this request serves. */
+    subjectDID: string;
+    /** The authority the grant and the binding both name. */
+    host: string;
+    /** The action token the leaf's attenuation was found to cover. */
+    action: string;
+    /** The proof's issued-at, unix seconds. */
+    iat: number;
+    /** The leaf credential's CID, re-derived and equal to the proof's member. */
+    credentialCID: string;
+}
+/**
+ * Verify a credential-gated request — API-AUTH.md's eleven steps, in an order
+ * that honors both load-bearing ordering rules: the proof signature gates every
+ * credential-chain step, and body hashing runs after the cheaper binding checks.
+ *
+ * `client` supplies the resolver seam (current-state identity resolution plus the
+ * revocation checker) exactly as `verifySiwd` does. Everything the verifier
+ * compares against — host, method, path, body, action — is passed in BY THE
+ * DEPLOYMENT: this helper never reads a request object, because the one thing a
+ * host binding must not be sourced from is the request.
+ *
+ * Throws `ApiRequestVerifyError`; branch on `reason`/`phase`/`status`, never on
+ * message text. `status` is the recommended HTTP code (401 proof-invalid, 403
+ * credential-invalid, 503 unverifiable, 500 config).
+ *
+ * REVOCATION AND RESOLUTION AVAILABILITY — read before deploying. This helper
+ * rejects a credential it KNOWS is revoked (`isRevoked` true at any chain level).
+ * It does NOT, with the default client, fail closed when the revocation source is
+ * unreachable: the stock `createRevocationChecker` is fail-open by design
+ * ("no revocation found" and "could not reach any relay" both return false), the
+ * system-wide v1 stance that "non-revocation is never provable." Likewise a
+ * credential-issuer that is unresolvable because relays are down surfaces from the
+ * protocol verifier as a `CredentialVerificationError` and is reported here as
+ * `invalid` (403), not `unverifiable` (503) — the underlying callback cannot
+ * distinguish "genuinely absent" from "transiently unreachable." The PRESENTER
+ * side is availability-aware (a resolution failure or unverified/stale tip is
+ * `unverifiable`, failing closed unless `allowStale`); the CREDENTIAL side inherits
+ * the v1 primitives' limitation. A deployment that needs fail-closed-on-outage for
+ * the credential/revocation phase MUST inject an availability-aware `isRevoked`
+ * (one that THROWS when it reaches zero sources — the throw is surfaced here as
+ * `unverifiable`) via the client config. Tightening the default is a client-level
+ * change to the shared revocation/resolution contract (it governs SIWD and relay
+ * verification too), tracked outside this kit.
+ */
+declare const verifyApiRequest: (client: Client, input: VerifyApiRequestInput) => Promise<VerifiedRequestProof>;
+
+export { ApiRequestVerifyError, type CreateApiAuthFetchOptions, DEFAULT_API_ACTION, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, EMPTY_BODY_SHA256, MAX_BODY_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, REQUEST_PROOF_JWS_TYP, type RequestProofFailurePhase, type RequestProofFailureReason, type RequestProofPayload, type SignApiRequestInput, type VerifiedRequestProof, type VerifyApiRequestInput, apiRequestSigningInput, buildApiAuthHeaders, createApiAuthFetch, sha256BodyHash, signApiRequest, verifyApiRequest };

package/dist/api-auth.js

@@ -0,0 +1,385 @@
+// src/api-auth.ts
+import { decodeMultikey } from "@metalabel/dfos-protocol/chain";
+import {
+  CredentialVerificationError,
+  decodeDFOSCredentialUnsafe,
+  matchesResource,
+  MAX_CREDENTIAL_SIZE,
+  verifyDelegationChain,
+  verifyDFOSCredential
+} from "@metalabel/dfos-protocol/credentials";
+import {
+  assertJwsProfile,
+  base64urlDecode,
+  base64urlEncode,
+  createJws,
+  decodeJwsUnsafe,
+  sha256,
+  verifyJws
+} from "@metalabel/dfos-protocol/crypto";
+var REQUEST_PROOF_JWS_TYP = "did:dfos:request-proof";
+var EMPTY_BODY_SHA256 = "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU";
+var MAX_REQUEST_PROOF_SIZE = 4096;
+var DEFAULT_PROOF_WINDOW_SECONDS = 60;
+var DEFAULT_PROOF_SKEW_SECONDS = 60;
+var MAX_PROOF_FRESHNESS_SPAN_SECONDS = 300;
+var DEFAULT_API_ACTION = "read:profile";
+var MAX_BODY_BYTES = 1048576;
+var MAX_DELEGATION_DEPTH = 16;
+var encoder = new TextEncoder();
+var EMPTY_BODY = new Uint8Array(0);
+var UPPERCASE_METHOD = /^[A-Z0-9!#$%&'*+.^_`|~-]+$/;
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+var CTL_OR_SPACE = /[\u0000-\u0020\u007f]/;
+var BASE64URL_32 = /^[A-Za-z0-9_-]{43}$/;
+var assertNoLoneSurrogate = (value, field) => {
+  if (LONE_SURROGATE.test(value)) {
+    throw new Error(`invalid request proof: ${field} must be well-formed Unicode`);
+  }
+};
+var validateRequestProofPayload = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("invalid request proof: expected a JSON object");
+  }
+  const raw = value;
+  for (const field of ["method", "host", "path", "bodyHash", "credentialCID"]) {
+    if (typeof raw[field] !== "string" || raw[field] === "") {
+      throw new Error(`invalid request proof: ${field} must be a non-empty string`);
+    }
+    assertNoLoneSurrogate(raw[field], field);
+  }
+  const method = raw["method"];
+  if (!UPPERCASE_METHOD.test(method)) {
+    throw new Error("invalid request proof: method must be an uppercase HTTP method token");
+  }
+  const host = raw["host"];
+  if (host !== host.toLowerCase() || /[\s/\\?#]/.test(host)) {
+    throw new Error("invalid request proof: host must be a lowercase authority, without a scheme");
+  }
+  const path = raw["path"];
+  if (!path.startsWith("/")) {
+    throw new Error("invalid request proof: path must begin with /");
+  }
+  if (path.includes("#")) {
+    throw new Error("invalid request proof: path must not carry a fragment");
+  }
+  if (CTL_OR_SPACE.test(path)) {
+    throw new Error(
+      "invalid request proof: path must not contain whitespace or control characters"
+    );
+  }
+  const bodyHash = raw["bodyHash"];
+  if (!BASE64URL_32.test(bodyHash) || base64urlEncode(base64urlDecode(bodyHash)) !== bodyHash) {
+    throw new Error(
+      "invalid request proof: bodyHash must be the canonical unpadded base64url of 32 bytes"
+    );
+  }
+  const iat = raw["iat"];
+  if (typeof iat !== "number" || !Number.isSafeInteger(iat) || iat <= 0) {
+    throw new Error("invalid request proof: iat must be a positive integer");
+  }
+  return {
+    method,
+    host,
+    path,
+    bodyHash,
+    credentialCID: raw["credentialCID"],
+    iat
+  };
+};
+var apiRequestSigningInput = (payload) => {
+  const parsed = validateRequestProofPayload(payload);
+  return encoder.encode(
+    JSON.stringify({
+      method: parsed.method,
+      host: parsed.host,
+      path: parsed.path,
+      bodyHash: parsed.bodyHash,
+      credentialCID: parsed.credentialCID,
+      iat: parsed.iat
+    })
+  );
+};
+var sha256BodyHash = (body) => base64urlEncode(sha256(body));
+var signApiRequest = async (input) => {
+  const payload = validateRequestProofPayload({
+    method: input.method,
+    host: input.host,
+    path: input.path,
+    bodyHash: sha256BodyHash(input.body ?? EMPTY_BODY),
+    credentialCID: input.credentialCID,
+    iat: input.iat ?? Math.floor(Date.now() / 1e3)
+  });
+  if (!input.kid.includes("#")) {
+    throw new Error("invalid request proof: kid must be a DID URL");
+  }
+  const proof = await createJws({
+    header: { alg: "EdDSA", typ: REQUEST_PROOF_JWS_TYP, kid: input.kid },
+    payload: {
+      method: payload.method,
+      host: payload.host,
+      path: payload.path,
+      bodyHash: payload.bodyHash,
+      credentialCID: payload.credentialCID,
+      iat: payload.iat
+    },
+    sign: input.sign
+  });
+  if (proof.length > MAX_REQUEST_PROOF_SIZE) {
+    throw new Error(`request proof exceeds max size: ${proof.length} > ${MAX_REQUEST_PROOF_SIZE}`);
+  }
+  return { proof, payload };
+};
+var buildApiAuthHeaders = (input) => ({
+  Authorization: `DFOS ${input.proof}`,
+  "X-Credential": input.credential
+});
+var credentialCIDFromHeader = (credential) => {
+  const decoded = decodeJwsUnsafe(credential);
+  if (!decoded) throw new Error("invalid credential: failed to decode the credential JWS");
+  const cid = decoded.header.cid;
+  if (typeof cid !== "string" || cid === "") {
+    throw new Error("invalid credential: the credential JWS carries no cid header");
+  }
+  return cid;
+};
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var createApiAuthFetch = (options) => {
+  const credentialCID = credentialCIDFromHeader(options.credential);
+  const send = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  return async (input, init) => {
+    const request = init === void 0 && input instanceof Request ? input : new Request(input, init);
+    const url = new URL(request.url);
+    if (url.protocol !== "https:" && !LOOPBACK_HOSTNAMES.has(url.hostname)) {
+      throw new Error(
+        `refusing to sign a ${url.protocol}// request to ${url.host}: api: surfaces are HTTPS surfaces, and a proof sent in the clear replays for its whole freshness window (plaintext is allowed only to localhost, 127.0.0.1, and [::1])`
+      );
+    }
+    const { proof } = await signApiRequest({
+      method: request.method,
+      // `host`, never `hostname`: the authority carries the port when there is
+      // one, and the verifier compares it byte for byte.
+      host: url.host,
+      // Path plus query, byte for byte — no normalization, because the verifier
+      // compares against the request target it actually received. Dropping
+      // `.search` is the classic silent 401.
+      path: url.pathname + url.search,
+      // Hash the CLONE and forward the original: buffering the request's own
+      // stream would leave nothing to send. Buffering at all is inherent — the
+      // proof covers the WHOLE body, so there is nothing to sign until the last
+      // octet is in hand.
+      body: new Uint8Array(await request.clone().arrayBuffer()),
+      credentialCID,
+      kid: options.kid,
+      sign: options.sign
+    });
+    const headers = new Headers(request.headers);
+    for (const [name, value] of Object.entries(
+      buildApiAuthHeaders({ proof, credential: options.credential })
+    )) {
+      headers.set(name, value);
+    }
+    return send(new Request(request, { headers, redirect: "manual" }));
+  };
+};
+var ApiRequestVerifyError = class extends Error {
+  reason;
+  phase;
+  /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid, 503 unverifiable, 500 config. */
+  status;
+  constructor(reason, phase, status, message) {
+    super(message);
+    this.name = "ApiRequestVerifyError";
+    this.reason = reason;
+    this.phase = phase;
+    this.status = status;
+  }
+};
+var invalidProof = (message) => new ApiRequestVerifyError("invalid", "proof", 401, message);
+var invalidCredential = (message) => new ApiRequestVerifyError("invalid", "credential", 403, message);
+var unverifiableProof = (message) => new ApiRequestVerifyError("unverifiable", "proof", 503, message);
+var unverifiableCredential = (message) => new ApiRequestVerifyError("unverifiable", "credential", 503, message);
+var misconfigured = (message) => new ApiRequestVerifyError("config", "config", 500, message);
+var discoverChainRoot = (leafToken) => {
+  let token = leafToken;
+  for (let depth = 0; depth < MAX_DELEGATION_DEPTH; depth++) {
+    const decoded = decodeDFOSCredentialUnsafe(token);
+    if (!decoded) throw invalidCredential("failed to decode presented credential");
+    if (decoded.payload.prf.length === 0) return decoded.payload.iss;
+    if (decoded.payload.prf.length > 1) {
+      throw invalidCredential("delegation chain: multi-parent credentials are not supported");
+    }
+    token = decoded.payload.prf[0];
+  }
+  throw invalidCredential("delegation chain too deep (max 16 credentials)");
+};
+var verifyApiRequest = async (client, input) => {
+  const window = input.windowSeconds ?? DEFAULT_PROOF_WINDOW_SECONDS;
+  const skew = input.skewSeconds ?? DEFAULT_PROOF_SKEW_SECONDS;
+  for (const [name, value] of [
+    ["windowSeconds", window],
+    ["skewSeconds", skew]
+  ]) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw misconfigured(`${name} must be a non-negative integer`);
+    }
+  }
+  if (window + skew > MAX_PROOF_FRESHNESS_SPAN_SECONDS) {
+    throw misconfigured(
+      `request proof freshness span W + S exceeds ${MAX_PROOF_FRESHNESS_SPAN_SECONDS} seconds: ${window} + ${skew}`
+    );
+  }
+  const action = input.action ?? DEFAULT_API_ACTION;
+  if (action.split(",").every((token) => token.trim() === "")) {
+    throw misconfigured("required action must name a non-empty token");
+  }
+  const maxBodyBytes = input.maxBodyBytes ?? MAX_BODY_BYTES;
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 0) {
+    throw misconfigured("maxBodyBytes must be a non-negative integer");
+  }
+  if (input.proof.length > MAX_REQUEST_PROOF_SIZE) {
+    throw invalidProof(
+      `request proof exceeds max size: ${input.proof.length} > ${MAX_REQUEST_PROOF_SIZE}`
+    );
+  }
+  if (input.credential.length > MAX_CREDENTIAL_SIZE) {
+    throw invalidProof(
+      `credential exceeds max size: ${input.credential.length} > ${MAX_CREDENTIAL_SIZE}`
+    );
+  }
+  const decoded = decodeJwsUnsafe(input.proof);
+  if (!decoded) throw invalidProof("failed to decode request proof JWS");
+  const rawHeader = decoded.header;
+  if (typeof rawHeader !== "object" || rawHeader === null || Array.isArray(rawHeader)) {
+    throw invalidProof("request proof protected header must be an object");
+  }
+  assertJwsProfile(rawHeader, invalidProof);
+  if (decoded.header.typ !== REQUEST_PROOF_JWS_TYP) {
+    throw invalidProof(`invalid typ: expected ${REQUEST_PROOF_JWS_TYP}, got ${decoded.header.typ}`);
+  }
+  const kid = decoded.header.kid;
+  if (typeof kid !== "string" || !kid.includes("#")) {
+    throw invalidProof("request proof kid must be a DID URL");
+  }
+  const presenterDID = kid.substring(0, kid.indexOf("#"));
+  const presenterKeyId = kid.substring(kid.indexOf("#") + 1);
+  const payloadSegment = input.proof.split(".")[1];
+  if (payloadSegment === void 0) throw invalidProof("failed to decode request proof payload");
+  let payload;
+  try {
+    const source = new TextDecoder("utf-8", { fatal: true }).decode(
+      base64urlDecode(payloadSegment)
+    );
+    payload = validateRequestProofPayload(JSON.parse(source));
+  } catch (err) {
+    throw invalidProof(err instanceof Error ? err.message : "invalid request proof payload");
+  }
+  const now = Math.floor((input.now ? input.now() : Date.now()) / 1e3);
+  if (now - payload.iat > window) throw invalidProof("request proof is stale");
+  if (payload.iat - now > skew) {
+    throw invalidProof("request proof iat is beyond the clock-skew allowance");
+  }
+  if (payload.method !== input.method) throw invalidProof("request proof method mismatch");
+  if (payload.host !== input.host) throw invalidProof("request proof host mismatch");
+  if (payload.path !== input.path) throw invalidProof("request proof path mismatch");
+  const body = input.body ?? EMPTY_BODY;
+  if (body.length > maxBodyBytes) {
+    throw new ApiRequestVerifyError(
+      "invalid",
+      "proof",
+      413,
+      `request body exceeds max size: ${body.length} > ${maxBodyBytes}`
+    );
+  }
+  if (payload.bodyHash !== sha256BodyHash(body)) {
+    throw invalidProof("request proof bodyHash mismatch");
+  }
+  let resolved;
+  try {
+    resolved = await client.identity(presenterDID);
+  } catch (err) {
+    throw unverifiableProof(
+      `failed to resolve request proof presenter: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const axes = resolved.trust.unverifiable ?? [];
+  if (!input.allowStale && (axes.includes("tip") || resolved.provenance.fromCache)) {
+    throw unverifiableProof(
+      "presenter identity resolution is stale (tip unverified) \u2014 refusing to authenticate against a cached identity state; pass allowStale: true to accept the risk"
+    );
+  }
+  const state = resolved.value;
+  if (state.isDeleted) throw invalidProof("request proof presenter identity is deleted");
+  const key = [...state.authKeys, ...state.assertKeys, ...state.controllerKeys].find(
+    (candidate) => candidate.id === presenterKeyId
+  );
+  if (!key) throw invalidProof("request proof signing key is not a current key of the presenter");
+  try {
+    verifyJws({ token: input.proof, publicKey: decodeMultikey(key.publicKeyMultibase).keyBytes });
+  } catch (err) {
+    throw invalidProof(err instanceof Error ? err.message : "invalid request proof signature");
+  }
+  const { isRevoked, resolveIdentity } = client.callbacks();
+  const rootDID = discoverChainRoot(input.credential);
+  let leaf;
+  let chain;
+  try {
+    leaf = await verifyDFOSCredential(input.credential, { resolveIdentity, now });
+    if (await isRevoked(leaf.iss, leaf.credentialCID)) {
+      throw new CredentialVerificationError("credential is revoked");
+    }
+    const verifiedChain = await verifyDelegationChain(leaf, {
+      resolveIdentity,
+      rootDID,
+      now,
+      isRevoked
+    });
+    chain = verifiedChain.chain;
+  } catch (err) {
+    if (err instanceof ApiRequestVerifyError) throw err;
+    if (err instanceof CredentialVerificationError) throw invalidCredential(err.message);
+    throw unverifiableCredential(
+      `credential verification could not complete: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (leaf.credentialCID !== payload.credentialCID) {
+    throw invalidCredential("request proof credentialCID does not match the presented credential");
+  }
+  for (const hop of chain) {
+    if (hop.aud === "*") {
+      throw invalidCredential(
+        'a credential in the presented chain carries a public audience (aud: "*")'
+      );
+    }
+  }
+  if (leaf.aud !== presenterDID) {
+    throw invalidCredential("credential audience does not match the request proof signing key");
+  }
+  if (!await matchesResource(leaf.att, `api:${input.host}`, action)) {
+    throw invalidCredential(`credential does not cover ${action} on api:${input.host}`);
+  }
+  return {
+    subjectDID: rootDID,
+    host: input.host,
+    action,
+    iat: payload.iat,
+    credentialCID: leaf.credentialCID
+  };
+};
+export {
+  ApiRequestVerifyError,
+  DEFAULT_API_ACTION,
+  DEFAULT_PROOF_SKEW_SECONDS,
+  DEFAULT_PROOF_WINDOW_SECONDS,
+  EMPTY_BODY_SHA256,
+  MAX_BODY_BYTES,
+  MAX_PROOF_FRESHNESS_SPAN_SECONDS,
+  MAX_REQUEST_PROOF_SIZE,
+  REQUEST_PROOF_JWS_TYP,
+  apiRequestSigningInput,
+  buildApiAuthHeaders,
+  createApiAuthFetch,
+  sha256BodyHash,
+  signApiRequest,
+  verifyApiRequest
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "type": "module",
-  "description": "DFOS Client — read-only resolve + verify orchestration over untrusted relays. Fetch, resolve, verify-orchestration, cache; all crypto truth comes from @metalabel/dfos-protocol",
+  "description": "DFOS Client — the client-side kit for participating in the protocol: resolve, verify, prove. Fetch, resolve, verify-orchestration and cache over untrusted relays, plus the SIWD and API-AUTH proof surfaces. Holds no keys; all crypto truth comes from @metalabel/dfos-protocol",
   "license": "MIT",
   "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
   "repository": {
@@ -27,6 +27,10 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./api-auth": {
+      "import": "./dist/api-auth.js",
+      "types": "./dist/api-auth.d.ts"
+    },
     "./siwd": {
       "import": "./dist/siwd.js",
       "types": "./dist/siwd.d.ts"
@@ -43,15 +47,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.31.0",
-    "@metalabel/dfos-web-relay": "^0.31.0"
+    "@metalabel/dfos-protocol": "^0.33.0",
+    "@metalabel/dfos-web-relay": "^0.33.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.31.0",
-    "@metalabel/dfos-web-relay": "0.31.0"
+    "@metalabel/dfos-protocol": "0.33.0",
+    "@metalabel/dfos-web-relay": "0.33.0"
   },
   "scripts": {
     "build": "tsup",