@metalabel/dfos-client 0.36.1 → 0.38.0

package/README.md

@@ -77,7 +77,7 @@ import { indexedDbStore, memoryStore } from '@metalabel/dfos-client/store';
 
 ### `@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).
+API Authentication request proofs — the per-request proof-of-possession envelope defined by the [API-AUTH specification](https://protocol.dfos.com/api-auth), which owns the semantics; this subpath signs and verifies it.
 
 **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.
 
@@ -100,7 +100,7 @@ Three consequences worth knowing before you wire it up:
 - **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:
+**A backend that must not proxy uses the decomposed form.** A signing backend fronting a browser describes the one request it is willing to make — never signing coordinates the browser supplies ([API-AUTH § Security Considerations](https://protocol.dfos.com/api-auth#security-considerations)) — so there is no `Request` for the adapter above to cover:
 
 ```typescript
 import { buildApiAuthHeaders, signApiRequest } from '@metalabel/dfos-client/api-auth';
@@ -149,7 +149,7 @@ 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.
 
-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:
+The `nonce`/`consumeNonce` pair on the expectation (supply exactly one) maps one field each to the spec's two replay disciplines — which discipline a given scope obliges, and why, is [SIWD § Replay prevention](https://protocol.dfos.com/siwd#replay-prevention)'s argument to make:
 
 **`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:
 
@@ -159,9 +159,7 @@ The `nonce`/`consumeNonce` pair on the expectation (supply exactly one) is the s
 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):
+**`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). Return true iff **this** verifier minted the nonce and it was unspent, deleting it in the same atomic operation (a Redis `GETDEL`, a `DELETE … RETURNING` — never get-then-delete):
 
 ```typescript
 await verifySiwd(client, jws, {
@@ -170,13 +168,11 @@ await verifySiwd(client, jws, {
 });
 ```
 
-`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.
+Under either discipline `verifySiwd` checks the nonce 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 that names no client identity.
 
-**Loopback redirects** — `http://localhost`, `http://127.0.0.1`, or `http://[::1]`, on any port — come in two shapes. The **anonymous** one is unchanged: no `client_did`, `scope=identity` only, and the consent screen shows the local delivery target and nothing else. The **key-proven** one is the [loopback credential tier](../../specs/SIWD.md#loopback-clients): the request carries a `client_did`, an ask proof over its own challenge bytes, and — unless the DID is already resident on the host — the client's identity chain. That is what lets local software receive a credential. It cannot prove where it came from, but it can prove it controls the keys, and the host's consent screen says exactly that. Credentials minted this way come back in the URL **fragment** and carry a hard expiry ceiling the host enforces; 14 days is the spec's recommendation.
-
-The fragment is what keeps the credential off every server, and it is also why a CLI needs one extra step: a browser does not send the fragment to your loopback listener either, so the request line your local server sees carries the query and nothing else. Answer it with a small page whose script reads `location.href` and posts the whole URL back to your server, then feed _that_ to `readSiwdCallback`. A browser relying party just passes `location.href`.
+**Loopback redirects** — `http://localhost`, `http://127.0.0.1`, or `http://[::1]`, on any port — come in two shapes: the **anonymous** one (no `client_did`, `scope=identity` only) and the **key-proven** one, the [loopback credential tier](https://protocol.dfos.com/siwd#loopback-clients), which is what lets local software receive a credential — the spec defines both. The one integration consequence to know: a credential comes back in the URL **fragment**, which a browser sends to no server — your loopback listener's request line included — so a CLI answers the callback with a small page whose script reads `location.href` and posts the whole URL back, then feeds _that_ to `readSiwdCallback`. A browser relying party just passes `location.href`.
 
 ```typescript
 import {

package/dist/api-auth.d.ts

@@ -1,124 +1,10 @@
+export { ApiRequestVerifyError, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, DFOS_AUTH_SCHEME, EMPTY_BODY_SHA256, IDENTITY_PROOF_JWS_TYP, IdentityProofPayload, MAX_BODY_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, ProofExtraMembers, REQUEST_PROOF_JWS_TYP, RequestProofFailurePhase, RequestProofFailureReason, RequestProofPayload, SignApiIdentityRequestInput, SignApiRequestInput, apiIdentitySigningInput, apiRequestSigningInput, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, parseDfosAuthorization, sha256BodyHash, signApiIdentityRequest, signApiRequest } from '@metalabel/dfos-protocol/credentials';
 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
@@ -172,32 +58,6 @@ interface CreateApiAuthFetchOptions {
  * 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;
@@ -292,5 +152,91 @@ interface VerifiedRequestProof {
  * verification too), tracked outside this kit.
  */
 declare const verifyApiRequest: (client: Client, input: VerifyApiRequestInput) => Promise<VerifiedRequestProof>;
+interface VerifyApiIdentityRequestInput {
+    /** The identity-proof JWS — the `Authorization: DFOS <token>` token, scheme stripped. */
+    proof: 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.
+     */
+    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`). As in `verifyApiRequest`, aborting DECODE at the cap
+     * remains a middleware obligation upstream — a decompression bomb inflates
+     * before this helper sees a buffered `Uint8Array`.
+     */
+    maxBodyBytes?: number;
+    /** 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 VerifiedIdentityProof {
+    /**
+     * THE PRINCIPAL — the `kid`'s DID, which is who the request is from. What that
+     * DID may do is the resource's local policy (quotas, reputation, self-access
+     * rules, admission tiers); this kit deliberately says nothing about it.
+     * Authentication travels on the wire; authorization stays home.
+     */
+    presenterDID: string;
+    /** The full `kid` DID URL that signed, key fragment included. */
+    kid: string;
+    /** The authority the binding names — the verifier's own configured value. */
+    host: string;
+    /** The proof's issued-at, unix seconds. */
+    iat: number;
+    /**
+     * The DECODED payload, unknown members included — where a caller reads an
+     * ADDITIVE member (`jti`) the envelope verifier ignored. The signature already
+     * covers it; the canonical member set stays closed.
+     */
+    rawPayload: Record<string, unknown>;
+}
+/**
+ * Verify an identity-proven request — API-AUTH.md's PROOF PHASE (steps 1–7) with
+ * the identity `typ`, and nothing more. Steps 8–11 do not exist for this
+ * artifact: there is no credential to walk, so there is no chain, no revocation
+ * lookup, and no attenuation coverage.
+ *
+ * The verdicts are therefore two, not three: `invalid` → 401, `unverifiable` →
+ * 503 (plus `config` → 500 for a deployment whose `W + S` is out of bounds).
+ * NOTHING credential-shaped can fail, so there is no 403 tier.
+ *
+ * A REQUEST PROOF PRESENTED HERE IS REJECTED at the header gate, and an identity
+ * proof presented to `verifyApiRequest` is rejected at the same gate. The typ
+ * scoping is what keeps a grant-bearing claim from ever being spent as a bare
+ * one, or the reverse.
+ *
+ * The header-layer rule this helper cannot see: on an `api:<host>` surface a
+ * request carrying `X-Credential` alongside an identity proof is MALFORMED (401)
+ * — the headers assert two different claims at once and a verifier MUST NOT pick
+ * one. That refusal belongs to the middleware, which is the only layer holding
+ * the header bag. (A relay content-plane read is a different surface: there the
+ * identity proof is the AuthN half and a DFOS credential presentation is the
+ * separate authorization artifact.)
+ *
+ * Throws `ApiRequestVerifyError`; branch on `reason`/`phase`/`status`, never on
+ * message text. `phase` is always `'proof'` or `'config'` here.
+ */
+declare const verifyApiIdentityRequest: (client: Client, input: VerifyApiIdentityRequestInput) => Promise<VerifiedIdentityProof>;
 
-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 };
+export { type CreateApiAuthFetchOptions, DEFAULT_API_ACTION, type VerifiedIdentityProof, type VerifiedRequestProof, type VerifyApiIdentityRequestInput, type VerifyApiRequestInput, createApiAuthFetch, verifyApiIdentityRequest, verifyApiRequest };

package/dist/api-auth.js

@@ -1,139 +1,36 @@
 // src/api-auth.ts
-import { decodeMultikey } from "@metalabel/dfos-protocol/chain";
 import {
+  apiIdentitySigningInput,
+  apiRequestSigningInput,
+  ApiRequestVerifyError,
+  assertProofVerifierConfig,
+  buildApiAuthHeaders,
+  buildApiIdentityHeaders,
   CredentialVerificationError,
   decodeDFOSCredentialUnsafe,
+  DEFAULT_PROOF_SKEW_SECONDS,
+  DEFAULT_PROOF_WINDOW_SECONDS,
+  DFOS_AUTH_SCHEME,
+  EMPTY_BODY_SHA256,
+  IDENTITY_PROOF_JWS_TYP,
   matchesResource,
+  MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
+  MAX_PROOF_FRESHNESS_SPAN_SECONDS,
+  MAX_REQUEST_PROOF_SIZE,
+  parseDfosAuthorization,
+  REQUEST_PROOF_JWS_TYP,
+  sha256BodyHash,
+  signApiIdentityRequest,
+  signApiRequest,
   verifyDelegationChain,
-  verifyDFOSCredential
+  verifyDFOSCredential,
+  verifyIdentityProofEnvelope,
+  verifyRequestProofEnvelope
 } 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;
+import { decodeJwsUnsafe } from "@metalabel/dfos-protocol/crypto";
 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");
@@ -182,24 +79,25 @@ var createApiAuthFetch = (options) => {
     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 clientPresenterResolver = (client, allowStale) => async (did) => {
+  const resolved = await client.identity(did);
+  const axes = resolved.trust.unverifiable ?? [];
+  if (!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;
+  return {
+    isDeleted: state.isDeleted,
+    keys: [...state.authKeys, ...state.assertKeys, ...state.controllerKeys]
+  };
+};
 var discoverChainRoot = (leafToken) => {
   let token = leafToken;
   for (let depth = 0; depth < MAX_DELEGATION_DEPTH; depth++) {
@@ -214,111 +112,21 @@ var discoverChainRoot = (leafToken) => {
   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}`
-    );
-  }
+  assertProofVerifierConfig(input);
   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
+  const { payload, presenterDID, now } = await verifyRequestProofEnvelope(
+    input,
+    clientPresenterResolver(client, input.allowStale === true)
   );
-  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 proofCredentialCID = payload.credentialCID;
   const { isRevoked, resolveIdentity } = client.callbacks();
   const rootDID = discoverChainRoot(input.credential);
   let leaf;
@@ -342,7 +150,7 @@ var verifyApiRequest = async (client, input) => {
       `credential verification could not complete: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  if (leaf.credentialCID !== payload.credentialCID) {
+  if (leaf.credentialCID !== proofCredentialCID) {
     throw invalidCredential("request proof credentialCID does not match the presented credential");
   }
   for (const hop of chain) {
@@ -366,20 +174,35 @@ var verifyApiRequest = async (client, input) => {
     credentialCID: leaf.credentialCID
   };
 };
+var verifyApiIdentityRequest = async (client, input) => {
+  const { payload, rawPayload, presenterDID, kid } = await verifyIdentityProofEnvelope(
+    input,
+    clientPresenterResolver(client, input.allowStale === true)
+  );
+  return { presenterDID, kid, host: input.host, iat: payload.iat, rawPayload };
+};
 export {
   ApiRequestVerifyError,
   DEFAULT_API_ACTION,
   DEFAULT_PROOF_SKEW_SECONDS,
   DEFAULT_PROOF_WINDOW_SECONDS,
+  DFOS_AUTH_SCHEME,
   EMPTY_BODY_SHA256,
+  IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
   REQUEST_PROOF_JWS_TYP,
+  apiIdentitySigningInput,
   apiRequestSigningInput,
+  assertProofVerifierConfig,
   buildApiAuthHeaders,
+  buildApiIdentityHeaders,
   createApiAuthFetch,
+  parseDfosAuthorization,
   sha256BodyHash,
+  signApiIdentityRequest,
   signApiRequest,
+  verifyApiIdentityRequest,
   verifyApiRequest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.36.1",
+  "version": "0.38.0",
   "type": "module",
   "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",
@@ -47,15 +47,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.36.1",
-    "@metalabel/dfos-web-relay": "^0.36.1"
+    "@metalabel/dfos-protocol": "^0.38.0",
+    "@metalabel/dfos-web-relay": "^0.38.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.36.1",
-    "@metalabel/dfos-web-relay": "0.36.1"
+    "@metalabel/dfos-protocol": "0.38.0",
+    "@metalabel/dfos-web-relay": "0.38.0"
   },
   "scripts": {
     "build": "tsup",