@metalabel/dfos-client 0.30.0 → 0.32.0

package/README.md

@@ -6,8 +6,6 @@ If verification logic appears in this package, that is the bug: every proof come
 
 ## Install
 
-> **Not yet published — pre-release.** This package is `private` until it ships with a stamped release; until then it is consumable only inside this workspace.
-
 ```bash
 npm install @metalabel/dfos-client @metalabel/dfos-protocol @metalabel/dfos-web-relay
 ```
@@ -78,10 +76,42 @@ import { indexedDbStore, memoryStore } from '@metalabel/dfos-client/store';
 ### `@metalabel/dfos-client/siwd`
 
 ```typescript
-import { createSiwdChallenge, siwdSigningInput, verifySiwd } from '@metalabel/dfos-client/siwd';
+import {
+  createSiwdLoginRequest,
+  readSiwdCallback,
+  siwdSigningInput,
+  verifySiwd,
+} from '@metalabel/dfos-client/siwd';
+```
+
+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.
+
+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 });
 ```
 
-Sign In With DFOS. `siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [SIWD.md](../../specs/SIWD.md)); `verifySiwd` is a no-throw verifier that accepts only a current `authKeys` entry of a non-deleted identity.
+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, {
+  domain,
+  consumeNonce: async (nonce) => (await store.getdel(nonce)) !== null,
+});
+```
+
+`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)).
+
+`siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [SIWD.md](../../specs/SIWD.md)); `createSiwdChallenge` mints a challenge on its own for a caller building its own redirect; `verifySiwd` is a no-throw verifier that accepts only a current `authKeys` entry of a non-deleted identity.
 
 ## License
 

package/dist/api-auth.d.ts

@@ -0,0 +1,243 @@
+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;
+};
+/**
+ * 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, 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, sha256BodyHash, signApiRequest, verifyApiRequest };

package/dist/api-auth.js

@@ -0,0 +1,336 @@
+// 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 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,
+  sha256BodyHash,
+  signApiRequest,
+  verifyApiRequest
+};

package/dist/siwd.d.ts

@@ -103,7 +103,10 @@ interface SiwdLoginRequest {
      * a `domain` or `did` that drifts between mint and verify is a check that
      * silently stops checking.
      *
-     * SINGLE USE: consume the nonce on the way back, pass or fail.
+     * SINGLE USE: consume the nonce on the way back, pass or fail. A backend
+     * holding its minted nonces in shared state should hand `verifySiwd` a
+     * `consumeNonce` instead of this object's `nonce`, so the consumption is
+     * atomic and is the last thing that happens before a session is granted.
      *
      * WHOEVER VERIFIES MUST HAVE MINTED. A verifier that accepts an expectation
      * supplied by the party presenting the JWS is comparing a value against
@@ -111,8 +114,14 @@ interface SiwdLoginRequest {
      * expectation comes from the verifier's own prior state (this object, held
      * server-side or in the session that began the sign-in) or from an
      * independent validation of it.
+     *
+     * `nonce` is REQUIRED here even though `SiwdExpectations` leaves it optional
+     * for the `consumeNonce` form: what this function mints into the challenge is
+     * always a string, and an RP persisting this object must get it back.
      */
-    expect: Pick<SiwdExpectations, 'domain' | 'nonce' | 'did'>;
+    expect: Pick<SiwdExpectations, 'domain' | 'did'> & {
+        nonce: string;
+    };
     /** base64url canonical challenge bytes, exactly as embedded in `url`. */
     challenge: string;
     /** ISO whole-second mint timestamp, exactly as embedded in the signed bytes. */
@@ -131,15 +140,22 @@ interface SiwdLoginRequest {
  * not downgraded, so the param is dropped here instead of being forwarded into
  * a guaranteed refusal.
  *
+ * The same judgment BOUNDS THE SCOPE. Every scope past `identity` returns a
+ * credential issued to a `client_did` — the one param a loopback request cannot
+ * carry — so specs/SIWD.md admits a loopback target for `scope=identity` only.
+ * Asking for more from a local port is not a downgrade the way `client_did` is;
+ * there is nothing to drop, so it throws.
+ *
  * It also owns the WIRE PARAM NAMES (`challenge`, `redirect_uri`, `scope`,
  * `client_did`) as their single source in this package. They are snake_case on
  * the wire and camelCase everywhere else, which is exactly the kind of seam
  * every hand-rolled RP re-implements and eventually gets wrong.
  *
  * PURE: no DOM, no storage, no navigation, no fetch — identical in a browser
- * and in Node. Throws on an unparseable `authorizeUrl` or `redirectUri`,
- * because those are mistakes in the RP's own configuration rather than runtime
- * conditions a result type would help a caller recover from.
+ * and in Node. Throws on an unparseable `authorizeUrl` or `redirectUri`, and on
+ * a non-`identity` scope over a loopback redirect, because those are mistakes
+ * in the RP's own configuration rather than runtime conditions a result type
+ * would help a caller recover from.
  */
 declare const createSiwdLoginRequest: (input: SiwdLoginRequestInput) => SiwdLoginRequest;
 /**
@@ -214,8 +230,26 @@ declare const validateSiwdSignRequest: (jwsToken: string, options: ValidateSiwdS
 interface SiwdExpectations {
     /** The verifier's own origin — MUST match the challenge domain. */
     domain: string;
-    /** The nonce this verifier issued for the session. */
-    nonce: string;
+    /**
+     * The nonce this verifier issued for the session. Supply EXACTLY ONE of
+     * `nonce` and `consumeNonce`.
+     */
+    nonce?: string;
+    /**
+     * Atomically consume the presented nonce against verifier-minted state — a
+     * Redis `GETDEL`, a `DELETE … RETURNING` row — returning true iff THIS
+     * verifier minted it and it was unspent. Membership in the verifier's own
+     * minted state is what proves the verifier minted it, which is the whole
+     * check; an equality test against a `nonce` fed in from the presented
+     * artifact is a value compared against itself. The ATOMICITY is yours: a
+     * get-then-delete lets two concurrent replays both win.
+     *
+     * Called AT MOST ONCE, and only after every other check has passed —
+     * signature, current-key resolution, did binding, domain, timestamp — so an
+     * otherwise-invalid presentation can never burn a live nonce, and the
+     * consumption is the last gate before the caller grants anything.
+     */
+    consumeNonce?: (nonce: string) => boolean | Promise<boolean>;
     /** If set, the challenge (and identity) MUST bind to this DID. */
     did?: string;
     /** If set, the signed challenge's timestamp MUST equal this exact value. */

package/dist/siwd.js

@@ -124,6 +124,10 @@ var parseUrlOrThrow = (value, field) => {
 var createSiwdLoginRequest = (input) => {
   const authorizeUrl = parseUrlOrThrow(input.authorizeUrl, "authorizeUrl");
   const redirect = parseUrlOrThrow(input.redirectUri, "redirectUri");
+  const isLoopback = SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect));
+  if (isLoopback && input.scope !== "identity") {
+    throw new Error("invalid SIWD login request: loopback redirects support scope=identity only");
+  }
   const { challenge, encoded, nonce } = createSiwdChallenge({
     domain: input.domain,
     ...input.statement !== void 0 ? { statement: input.statement } : {},
@@ -134,7 +138,7 @@ var createSiwdLoginRequest = (input) => {
   url.searchParams.set("challenge", encoded);
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("scope", input.scope);
-  if (input.clientDid !== void 0 && !SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect))) {
+  if (input.clientDid !== void 0 && !isLoopback) {
     url.searchParams.set("client_did", input.clientDid);
   }
   return {
@@ -233,6 +237,9 @@ var validateSiwdSignRequest = async (jwsToken, options) => {
 var fail = (error) => ({ ok: false, error });
 var verifySiwd = async (client, jws, expect) => {
   try {
+    if (expect.nonce === void 0 === (expect.consumeNonce === void 0)) {
+      return fail("provide exactly one of nonce or consumeNonce");
+    }
     const decoded = decodeJwsUnsafe(jws);
     if (!decoded) return fail("failed to decode JWS");
     const rawHeader = decoded.header;
@@ -275,7 +282,6 @@ var verifySiwd = async (client, jws, expect) => {
     } catch (err) {
       return fail(err instanceof Error ? err.message : "invalid signature");
     }
-    if (payload.nonce !== expect.nonce) return fail("nonce mismatch");
     if (payload.domain !== expect.domain) return fail("domain mismatch");
     if (expect.timestamp !== void 0 && payload.timestamp !== expect.timestamp) {
       return fail("timestamp does not match expected challenge timestamp");
@@ -288,6 +294,13 @@ var verifySiwd = async (client, jws, expect) => {
     if (issuedMs - nowMs > MAX_CLOCK_SKEW_SECONDS * 1e3) {
       return fail("challenge timestamp is in the future");
     }
+    if (expect.consumeNonce !== void 0) {
+      if (!await expect.consumeNonce(payload.nonce)) {
+        return fail("nonce already used or not recognized");
+      }
+    } else if (payload.nonce !== expect.nonce) {
+      return fail("nonce mismatch");
+    }
     const session = {
       did,
       domain: payload.domain,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.30.0",
+  "version": "0.32.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",
   "license": "MIT",
@@ -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.30.0",
-    "@metalabel/dfos-web-relay": "^0.30.0"
+    "@metalabel/dfos-protocol": "^0.32.0",
+    "@metalabel/dfos-web-relay": "^0.32.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.30.0",
-    "@metalabel/dfos-web-relay": "0.30.0"
+    "@metalabel/dfos-protocol": "0.32.0",
+    "@metalabel/dfos-web-relay": "0.32.0"
   },
   "scripts": {
     "build": "tsup",