@metalabel/dfos-client 0.37.0 → 0.38.0

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.37.0",
+  "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.37.0",
-    "@metalabel/dfos-web-relay": "^0.37.0"
+    "@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.37.0",
-    "@metalabel/dfos-web-relay": "0.37.0"
+    "@metalabel/dfos-protocol": "0.38.0",
+    "@metalabel/dfos-web-relay": "0.38.0"
   },
   "scripts": {
     "build": "tsup",