@metalabel/dfos-client 0.50.0 → 0.52.0

package/README.md

@@ -128,7 +128,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 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:
+**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 ([INTEGRATIONS § API security notes](https://protocol.dfos.com/integrations#api-security-notes)) — so there is no `Request` for the adapter above to cover:
 
 ```typescript
 import { buildApiAuthHeaders, signApiRequest } from '@metalabel/dfos-client/api-auth';
@@ -160,7 +160,7 @@ await verifyApiRequest(client, {
 
 It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `unverifiable` / `config`), `phase`, and the recommended `status` — branch on those, never on message text.
 
-`verifyApiIdentityRequest` is the same verifier for the envelope's credential-less sibling, the [identity proof](https://protocol.dfos.com/api-auth#the-identity-proof) — it establishes only which DID is asking, leaving what that DID may do to the resource's own policy.
+`verifyApiIdentityRequest` is the same verifier for the envelope's credential-less sibling, the [identity proof](https://protocol.dfos.com/integrations#the-identity-proof) — it establishes only which DID is asking, leaving what that DID may do to the resource's own policy.
 
 `apiRequestSigningInput(payload)` is the pure byte contract both halves share, and the one place per language the canonical bytes are built.
 
@@ -179,7 +179,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) 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:
+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 [INTEGRATIONS § Replay prevention](https://protocol.dfos.com/integrations#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:
 
@@ -202,7 +202,7 @@ Under either discipline `verifySiwd` checks the nonce at most once, and only aft
 
 `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 (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`.
+**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/integrations#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 {
@@ -247,7 +247,7 @@ if (result.kind === 'success') {
 }
 ```
 
-`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.
+`siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [INTEGRATIONS.md](../../specs/INTEGRATIONS.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

@@ -1,5 +1,5 @@
 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-BfzEg_gw.js';
+import { a as Client } from './types-BbIEz7BN.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-web-relay/peer-client';
 
@@ -36,7 +36,7 @@ interface CreateApiAuthFetchOptions {
  *
  * `signApiRequest` stays exported for the backends that must NOT proxy. A
  * signing backend fronting a browser MUST authorize the coordinates it is about
- * to sign against its own session (API-AUTH.md, Security Considerations) — it
+ * to sign against its own session (INTEGRATIONS.md, API security notes) — it
  * describes the one request it is willing to make rather than receiving one, so
  * there is no `Request` for this adapter to cover.
  *
@@ -118,7 +118,8 @@ interface VerifiedRequestProof {
     credentialCID: string;
 }
 /**
- * Verify a credential-gated request — API-AUTH.md's eleven steps, in an order
+ * Verify a credential-gated request — INTEGRATIONS.md, Verification algorithm'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.
  *
@@ -132,24 +133,10 @@ interface VerifiedRequestProof {
  * 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.
+ * Missing issuer dependencies and an unavailable revocation source are
+ * unverifiable (503). The default checker throws when no relay answers; an
+ * answered negative still cannot prove non-revocation. Custom checkers must
+ * likewise throw when status cannot be obtained.
  */
 declare const verifyApiRequest: (client: Client, input: VerifyApiRequestInput) => Promise<VerifiedRequestProof>;
 interface VerifyApiIdentityRequestInput {
@@ -212,7 +199,8 @@ interface VerifiedIdentityProof {
     rawPayload: Record<string, unknown>;
 }
 /**
- * Verify an identity-proven request — API-AUTH.md's PROOF PHASE (steps 1–7) with
+ * Verify an identity-proven request — INTEGRATIONS.md, Verification algorithm'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.

package/dist/api-auth.js

@@ -1,4 +1,5 @@
 // src/api-auth.ts
+import { isDependencyMissing } from "@metalabel/dfos-protocol";
 import {
   apiIdentitySigningInput,
   apiRequestSigningInput,
@@ -132,19 +133,22 @@ var verifyApiRequest = async (client, input) => {
   let leaf;
   let chain;
   try {
-    leaf = await verifyDFOSCredential(input.credential, { resolveIdentity, now });
+    leaf = await verifyDFOSCredential(input.credential, { resolveIdentity, nowUnix: now });
     if (await isRevoked(leaf.iss, leaf.credentialCID)) {
       throw new CredentialVerificationError("credential is revoked");
     }
     const verifiedChain = await verifyDelegationChain(leaf, {
       resolveIdentity,
       rootDID,
-      now,
+      nowUnix: now,
       isRevoked
     });
     chain = verifiedChain.chain;
   } catch (err) {
     if (err instanceof ApiRequestVerifyError) throw err;
+    if (isDependencyMissing(err)) {
+      throw unverifiableCredential(err instanceof Error ? err.message : String(err));
+    }
     if (err instanceof CredentialVerificationError) throw invalidCredential(err.message);
     throw unverifiableCredential(
       `credential verification could not complete: ${err instanceof Error ? err.message : String(err)}`

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ClientConfig, a as Client, b as Callbacks, R as RevChecker } from './types-BfzEg_gw.js';
-export { c as CallOptions, D as DocumentBlob, G as GlobalLogOptions, d as GlobalLogPage, e as GlobalLogResult, I as IndexCapabilities, f as IndexContentPage, g as IndexContentRow, h as IndexCountersignatureRow, i as IndexCountersignaturesPage, j as IndexCredentialRow, k as IndexCredentialsPage, l as IndexIdentitiesPage, m as IndexIdentityProfile, n as IndexIdentityRow, o as IndexOrder, p as IndexRecencyOrder, L as LogOp, P as Provenance, q as RelayHealth, r as RelayResponse, s as Resolution, t as Resolved, u as ResolvedContent, v as ResolvedCredential, S as Store, T as Trust, U as UnverifiableAxis, V as VerifyResult } from './types-BfzEg_gw.js';
-export { m as memoryStore } from './memory-BuTsEPZI.js';
+import { C as ClientConfig, a as Client, b as Callbacks, R as RevChecker } from './types-BbIEz7BN.js';
+export { c as CallOptions, D as DocumentBlob, E as EffectiveIdentity, d as EverProvedIdentity, G as GlobalLogOptions, e as GlobalLogPage, f as GlobalLogResult, I as IndexCapabilities, g as IndexContentPage, h as IndexContentRow, i as IndexCountersignatureRow, j as IndexCountersignaturesPage, k as IndexCredentialRow, l as IndexCredentialsPage, m as IndexIdentitiesPage, n as IndexIdentityProfile, o as IndexIdentityRow, p as IndexOrder, q as IndexRecencyOrder, L as LogOp, P as Provenance, r as RelayHealth, s as RelayResponse, t as Resolution, u as Resolved, v as ResolvedContent, w as ResolvedCredential, S as Store, T as Trust, U as UnverifiableAxis, V as VerifyResult } from './types-BbIEz7BN.js';
+export { m as memoryStore } from './memory-B5WMnEUQ.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
@@ -64,7 +64,8 @@ declare const divergenceErrorFrom: (err: unknown) => DivergenceError | undefined
  * (`verifyRevocation`: signature, CID integrity, issuer-only rule) and whose
  * payload binds exactly the queried (issuerDID, credentialCID). Anything less —
  * unreachable relay, negative answer, forged or mismatched proof — moves on to
- * the next relay; false only after the full set has been consulted.
+ * the next relay; false only after the full set has been consulted and at least
+ * one relay answered with a parseable status body. Zero answers throws.
  *
  * When the caller supplies `asOfUnix` (the protocol does, on every cold fold, with
  * each operation's own `createdAt`), a verified revocation only counts if its own
@@ -72,6 +73,6 @@ declare const divergenceErrorFrom: (err: unknown) => DivergenceError | undefined
  * verification of history: without it, revoking a credential today would make
  * every already-committed operation it ever authorized fail to verify tomorrow.
  */
-declare const createRevocationChecker: (relays: string[], fetchImpl: typeof fetch, resolveKey: (kid: string) => Promise<Uint8Array>) => RevChecker;
+declare const createRevocationChecker: (relays: string[], fetchImpl: typeof fetch, resolveKey: (kid: string, basis?: string) => Promise<Uint8Array>) => RevChecker;
 
 export { Callbacks, Client, ClientConfig, DivergenceError, RevChecker, createClient, createRevocationChecker, divergenceErrorFrom, resolvers };

package/dist/index.js

@@ -203,6 +203,7 @@ var createIndexQueries = (relays, fetchImpl) => {
       setParam(url, "issuer", params?.issuer);
       setParam(url, "resource", params?.resource);
       setParam(url, "action", params?.action);
+      setParam(url, "order", params?.order);
       setParam(url, "after", params?.after);
       setParam(url, "limit", params?.limit);
       return url;
@@ -276,12 +277,9 @@ var opMeta = (jws) => {
   const createdAt = typeof decoded?.payload?.["createdAt"] === "string" ? (decoded?.payload)["createdAt"] : "";
   return { cid, createdAt };
 };
-var provedKeys = (state) => {
-  const proved = state.provedKeys ?? state;
-  return [...proved.authKeys, ...proved.assertKeys, ...proved.controllerKeys];
-};
 var historicalIdentity = (state) => ({
   ...state,
+  resolution: "ever-proved",
   ...state.provedKeys ?? {
     authKeys: state.authKeys,
     assertKeys: state.assertKeys,
@@ -289,7 +287,9 @@ var historicalIdentity = (state) => ({
   }
 });
 var keyBytesFor = (state, keyId) => {
-  const key = provedKeys(state).find((k) => k.id === keyId);
+  const key = [...state.authKeys, ...state.assertKeys, ...state.controllerKeys].find(
+    (k) => k.id === keyId
+  );
   return key ? decodeMultikey(key.publicKeyMultibase).keyBytes : null;
 };
 var createResolvers = (deps) => {
@@ -371,27 +371,42 @@ var createResolvers = (deps) => {
       tipUnverified: cached !== void 0 && candidate.log.length === cached.log.length
     };
   };
-  const resolveIdentity = async (did) => {
+  const stateAsOf = async (resolution, basis) => {
+    const { state, log } = resolution;
+    const last = log[log.length - 1];
+    if (basis === void 0 || last === void 0 || opMeta(last).createdAt <= basis) return state;
+    const asOf = await verifyIdentityChain({ didPrefix: DID_PREFIX, log, asOf: basis });
+    return { ...asOf, isDeleted: state.isDeleted };
+  };
+  const resolveIdentity = async (did, basis) => {
     try {
-      const { state } = await getIdentityChain(did);
-      return historicalIdentity(state);
+      return await stateAsOf(await getIdentityChain(did), basis);
     } catch {
       return void 0;
     }
   };
-  const resolveKey = async (kid) => {
+  const resolveKey = async (kid, basis) => {
     const hashIdx = kid.indexOf("#");
     if (hashIdx < 0) throw new Error(`kid must be a DID URL: ${kid}`);
     const did = kid.substring(0, hashIdx);
     const keyId = kid.substring(hashIdx + 1);
-    const { state } = await getIdentityChain(did);
+    const state = await stateAsOf(await getIdentityChain(did), basis);
     const bytes = keyBytesFor(state, keyId);
     if (!bytes) throw new Error(`unknown key ${keyId} on identity ${did}`);
     return bytes;
   };
+  const resolveClaimantIdentity = async (did) => {
+    try {
+      const { state } = await getIdentityChain(did);
+      return historicalIdentity(state);
+    } catch {
+      return void 0;
+    }
+  };
   const callbacks = () => ({
     resolveKey,
     resolveIdentity,
+    resolveClaimantIdentity,
     isRevoked: deps.isRevoked
   });
   const getContentChain = async (contentId, options) => {
@@ -496,6 +511,7 @@ import { REVOCATIONS_BASE_PATH } from "@metalabel/dfos-web-relay/peer-client";
 var createRevocationChecker = (relays, fetchImpl, resolveKey) => {
   const relaySet = normalizeRelays(relays);
   return async (issuerDID, credentialCID, asOfUnix) => {
+    let answered = false;
     for (const url of relaySet) {
       let body = null;
       try {
@@ -507,6 +523,10 @@ var createRevocationChecker = (relays, fetchImpl, resolveKey) => {
         if (res.status === 501) continue;
         if (!res.ok) continue;
         body = await res.json();
+        if (body === null || typeof body !== "object" || typeof body.revoked !== "boolean") {
+          continue;
+        }
+        answered = true;
       } catch {
         continue;
       }
@@ -522,6 +542,7 @@ var createRevocationChecker = (relays, fetchImpl, resolveKey) => {
       } catch {
       }
     }
+    if (!answered) throw new Error("revocation status unavailable: no relay answered");
     return false;
   };
 };
@@ -574,7 +595,11 @@ var createClient = (config) => {
   let isRevokedImpl = async () => false;
   const isRevoked = (issuerDID, credentialCID, asOfUnix) => isRevokedImpl(issuerDID, credentialCID, asOfUnix);
   const resolvers2 = createResolvers({ relays, quorum, store, peerClient, isRevoked });
-  isRevokedImpl = config.isRevoked ?? createRevocationChecker(relays, fetchImpl, (kid) => resolvers2.callbacks().resolveKey(kid));
+  isRevokedImpl = config.isRevoked ?? createRevocationChecker(
+    relays,
+    fetchImpl,
+    (kid, basis) => resolvers2.callbacks().resolveKey(kid, basis)
+  );
   const relaysFor = (o) => normalizeRelays(o?.relays ?? relays);
   const identity = async (did, options) => {
     const { state, provenance, tipUnverified } = await resolvers2.getIdentityChain(did, options);
@@ -600,9 +625,13 @@ var createClient = (config) => {
     const issuer = await resolvers2.getIdentityChain(iss, options);
     const verified = await verifyDFOSCredential(jws, {
       resolveIdentity: resolvers2.callbacks().resolveIdentity,
-      now: Math.floor(nowMs() / 1e3)
+      nowUnix: Math.floor(nowMs() / 1e3)
     });
-    const revoked = await isRevoked(verified.iss, verified.credentialCID);
+    let revoked = false;
+    try {
+      revoked = await isRevoked(verified.iss, verified.credentialCID);
+    } catch {
+    }
     const axes = [];
     if (issuer.tipUnverified) axes.push("tip");
     if (!revoked) axes.push("revocation");
@@ -646,9 +675,13 @@ var createClient = (config) => {
       if (typ === "did:dfos:credential") {
         const verified = await verifyDFOSCredential(jws, {
           resolveIdentity: cb.resolveIdentity,
-          now: Math.floor(nowMs() / 1e3)
+          nowUnix: Math.floor(nowMs() / 1e3)
         });
-        const revoked = await isRevoked(verified.iss, verified.credentialCID);
+        let revoked = false;
+        try {
+          revoked = await isRevoked(verified.iss, verified.credentialCID);
+        } catch {
+        }
         if (revoked) return { ok: false, error: "credential revoked", value: verified };
         return { ok: true, value: verified, unverifiable: ["revocation"] };
       }

package/dist/{memory-BuTsEPZI.d.ts → memory-B5WMnEUQ.d.ts}

@@ -1,4 +1,4 @@
-import { S as Store } from './types-BfzEg_gw.js';
+import { S as Store } from './types-BbIEz7BN.js';
 
 declare const memoryStore: () => Store;
 

package/dist/siwd.d.ts

@@ -1,10 +1,11 @@
 import { Signer, VerifiedIdentity, VerifiedSignRequest } from '@metalabel/dfos-protocol/chain';
-import { a as Client, V as VerifyResult } from './types-BfzEg_gw.js';
+import { a as Client, V as VerifyResult } from './types-BbIEz7BN.js';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
 
 /**
- * The normative JWS header `typ` for a signed SIWD challenge (SIWD.md). Signers
+ * The normative JWS header `typ` for a signed SIWD challenge (INTEGRATIONS.md,
+ * Challenge schema). Signers
  * MUST set it; `verifySiwd` rejects anything else — it is also what lets typ-
  * routing dispatchers tell a SIWD proof apart from credentials and chain ops.
  */
@@ -12,7 +13,7 @@ declare const SIWD_JWS_TYP = "did:dfos:siwd";
 /**
  * The normative JWS header `typ` for a client ASK PROOF — the artifact a
  * loopback client signs to prove key control at ask-time, registered alongside
- * `SIWD_JWS_TYP` by SIWD.md §The ask proof.
+ * `SIWD_JWS_TYP` by INTEGRATIONS.md, The ask proof.
  *
  * The two artifacts cover the SAME canonical challenge bytes, so the distinct
  * `typ` is the only thing keeping them from being fungible: without it, an ask
@@ -89,13 +90,13 @@ interface SiwdLoginRequestInput {
     redirectUri: string;
     /**
      * Requested scope: a space-separated SET of scope tokens (the OAuth `scope`
-     * convention), each of which must be one specs/SIWD.md §Scopes and Credentials
+     * convention), each of which must be one specs/INTEGRATIONS.md §Scopes and credentials
      * registers. A request naming an unregistered token is refused WHOLE rather
      * than partially honored — a consent screen that silently dropped a token
      * would describe something other than what was asked for.
      */
     scope: string;
-    /** Consent-screen prose. A host MAY decline to render it; see specs/SIWD.md. */
+    /** Consent-screen prose. A host MAY decline to render it; see specs/INTEGRATIONS.md. */
     statement?: string;
     /**
      * Bind the challenge to ONE identity — "sign in as this DID, or not at all".
@@ -160,7 +161,7 @@ interface SiwdLoginRequest {
  * on a local port used to be refused outright — there is no domain serving a
  * well-known and no registration to check, so nothing backed the DID and a host
  * would not display an identity it could not stand behind. The LOOPBACK
- * CREDENTIAL TIER (specs/SIWD.md §Loopback Clients) replaces "nothing backs it"
+ * CREDENTIAL TIER (specs/INTEGRATIONS.md §Loopback clients) replaces "nothing backs it"
  * with the one thing local software can prove: control of that identity's
  * current keys. So the param now rides through on a loopback redirect instead
  * of being dropped — but it is honored only when the request ALSO carries an
@@ -171,7 +172,7 @@ interface SiwdLoginRequest {
  *
  * The same judgment BOUNDS THE SCOPE. Every scope past `identity` returns a
  * credential issued to a `client_did`, so a loopback request with no client
- * identity at all still has nothing to issue to and specs/SIWD.md admits it for
+ * identity at all still has nothing to issue to and specs/INTEGRATIONS.md admits it for
  * `scope=identity` only — there is nothing to downgrade, so it throws. With a
  * client identity the tier is open and every scope is available.
  *
@@ -191,8 +192,8 @@ declare const createSiwdLoginRequest: (input: SiwdLoginRequestInput) => SiwdLogi
 /**
  * Sign the ask proof for a loopback authorize request: a JWS over the exact
  * canonical bytes of the request's own challenge, under `SIWD_ASK_JWS_TYP`,
- * signed by a CURRENT auth key of the client identity's chain (SIWD.md §The ask
- * proof). It is what makes a `client_did` on a loopback request mean something
+ * signed by a CURRENT auth key of the client identity's chain (INTEGRATIONS.md,
+ * The ask proof). It is what makes a `client_did` on a loopback request mean something
  * — the host verifies it against the chain's current state before rendering any
  * consent, so key control is established at ask-time, not just at spend-time.
  *
@@ -209,11 +210,9 @@ declare const createSiwdLoginRequest: (input: SiwdLoginRequestInput) => SiwdLogi
  * because a proof that names a key it was not signed with is a lie the wire
  * format has no reason to carry.
  *
- * The `client_proof` param that carries this is the REFERENCE wire surface, not
- * a normative name: SIWD.md defers how the ask proof travels to the hosted
- * endpoint's reference implementation, exactly as it does the endpoint itself.
- * What is normative is that it arrives WITH the ask and verifies BEFORE any
- * consent is rendered.
+ * The `client_proof` param that carries this is the parameter the spec names
+ * (INTEGRATIONS.md, The ask proof): the proof arrives WITH the ask and verifies
+ * BEFORE any consent is rendered.
  */
 declare const signSiwdAskProof: (input: {
     challenge: SiwdChallenge;
@@ -221,7 +220,8 @@ declare const signSiwdAskProof: (input: {
     kid: string;
     signer: Signer;
 }) => Promise<string>;
-/** SIWD.md carriage cap — an identity that has outgrown it has outgrown carriage. */
+/** The carriage cap of INTEGRATIONS.md, `identity_chain`: chain carriage — an
+ *  identity that has outgrown it has outgrown carriage. */
 declare const MAX_SIWD_CLIENT_CHAIN_OPS = 100;
 /**
  * Encode a client identity chain for carriage on the authorize request: the
@@ -231,7 +231,7 @@ declare const MAX_SIWD_CLIENT_CHAIN_OPS = 100;
  * THIS IS THE LOOPBACK CARRIAGE FORM, and only that. An application that holds a
  * domain encodes nothing: it publishes the very same log as the raw JSON array
  * of the `identity_chain` member of its `/.well-known/dfos-app.json` app
- * description (SIWD.md §`identity_chain` — chain carriage), where the origin
+ * description (INTEGRATIONS.md, `identity_chain`: chain carriage), where the origin
  * serving the file is what associates the domain with the DID. Same chain, same
  * carriage rules — a URL is simply the carrier available to software that holds
  * no origin to publish from.
@@ -239,7 +239,7 @@ declare const MAX_SIWD_CLIENT_CHAIN_OPS = 100;
  * The DID derived from the genesis operation MUST equal the `client_did` the
  * request names; a request where the two disagree makes no claim at all and the
  * host refuses it WHOLE rather than ingesting the chain and ignoring the
- * mismatch (SIWD.md §Chain residence). Carriage is only needed when the DID is
+ * mismatch (INTEGRATIONS.md, Chain residence). Carriage is only needed when the DID is
  * not already resident on the verifying host.
  *
  * The 100-operation cap is spec-normative and enforced here. Hosts MAY
@@ -248,10 +248,10 @@ declare const MAX_SIWD_CLIENT_CHAIN_OPS = 100;
  * protocol, so it is not a client-side throw; the practical reading is that a
  * chain anywhere near the op cap belongs on relays, not in a URL.
  *
- * As with the ask proof, the `client_chain` param is the REFERENCE wire surface
- * rather than a normative name — SIWD.md leaves the carriage encoding to the
- * hosted endpoint's reference implementation and pins only that the chain
- * arrives with the ask and verifies before any consent is rendered.
+ * As with the ask proof, the `client_chain` param is the parameter the spec
+ * names (INTEGRATIONS.md, Chain residence): base64url of the JSON array of the
+ * verbatim operation JWS strings, genesis first, arriving with the ask and
+ * verifying before any consent is rendered.
  */
 declare const encodeSiwdClientChain: (log: string[]) => string;
 interface SiwdClientIdentity {
@@ -329,7 +329,7 @@ interface SiwdLoopbackLoginRequestInput {
      * a credential to.
      */
     scope: string;
-    /** Consent-screen prose. A host MAY decline to render it; see specs/SIWD.md. */
+    /** Consent-screen prose. A host MAY decline to render it; see specs/INTEGRATIONS.md. */
     statement?: string;
     /** Bind the challenge to ONE subject DID (sign in as this DID or not at all). */
     did?: string;
@@ -345,14 +345,16 @@ interface SiwdLoopbackLoginRequestInput {
  * Build a loopback authorize URL under the LOOPBACK CREDENTIAL TIER — the
  * outbound half of what `createSiwdLoginRequest` alone cannot produce. It is
  * that function plus the two things that back the `client_did` it now carries:
- * an ask proof (SIWD.md §The ask proof) and, unless the DID is already resident
- * on the host, the client's identity chain (SIWD.md §Chain residence).
+ * an ask proof (INTEGRATIONS.md, The ask proof) and, unless the DID is already
+ * resident on the host, the client's identity chain (INTEGRATIONS.md, Chain
+ * residence).
  *
- * `domain` is DERIVED, not accepted. SIWD.md pins a loopback challenge's domain
- * to the BARE loopback host — the port is not part of the binding, because a
- * local application cannot reserve one — and the host compares that value
- * literally against the redirect's host. Taking a `domain` input here would be
- * an invitation to a mismatch that fails only after the redirect.
+ * `domain` is DERIVED, not accepted. INTEGRATIONS.md, Loopback redirect targets
+ * pins a loopback challenge's domain to the BARE loopback host — the port is
+ * not part of the binding, because a local application cannot reserve one — and
+ * the host compares that value literally against the redirect's host. Taking a
+ * `domain` input here would be an invitation to a mismatch that fails only
+ * after the redirect.
  *
  * WHAT THIS PROVES IS KEY CONTROL, NOT PROVENANCE. The chain says which keys
  * the asking party holds; nothing about a loopback client's origin or authorship
@@ -404,7 +406,7 @@ type SiwdCallbackResult = {
  * THAT SAME PROPERTY IS A PROBLEM FOR A CLI, and this tier's primary consumer is
  * a CLI. A browser does not send the fragment to the loopback listener either,
  * so the request line a local HTTP server sees carries the query and nothing
- * else. The standard resolution (SIWD.md §4's loopback note) is for the listener
+ * else. The standard resolution (INTEGRATIONS.md, 4. Callback) is for the listener
  * to answer with a small page whose script reads `location.href` and posts the
  * whole URL back to the local server; feed THAT to this function. A browser RP
  * passes `location.href` directly and needs no relay.

package/dist/siwd.js

@@ -135,7 +135,7 @@ var createSiwdLoginRequest = (input) => {
   const isLoopback = SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect));
   if (isLoopback && input.scope !== "identity" && input.clientDid === void 0) {
     throw new Error(
-      "invalid SIWD login request: loopback redirects support scope=identity only without a client identity \u2014 a credential scope needs a client_did proven under the loopback credential tier (specs/SIWD.md \xA7Loopback Clients)"
+      "invalid SIWD login request: loopback redirects support scope=identity only without a client identity \u2014 a credential scope needs a client_did proven under the loopback credential tier (specs/INTEGRATIONS.md \xA7Loopback clients)"
     );
   }
   const { challenge, encoded, nonce } = createSiwdChallenge({

package/dist/store/index.d.ts

@@ -1,5 +1,5 @@
-export { m as memoryStore } from '../memory-BuTsEPZI.js';
-import { S as Store } from '../types-BfzEg_gw.js';
+export { m as memoryStore } from '../memory-B5WMnEUQ.js';
+import { S as Store } from '../types-BbIEz7BN.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';

package/dist/{types-BfzEg_gw.d.ts → types-BbIEz7BN.d.ts}

@@ -2,6 +2,14 @@ import { VerifiedIdentity, VerifiedContentChain } from '@metalabel/dfos-protocol
 import { VerifiedDFOSCredential, Attenuation } from '@metalabel/dfos-protocol/credentials';
 import { PeerClient } from '@metalabel/dfos-web-relay/peer-client';
 
+/** Head/as-of state; excludes the credit-claim projection. */
+type EffectiveIdentity = VerifiedIdentity & {
+    readonly resolution?: 'effective';
+};
+/** Every key ever proved, including memberships absent from effective state. */
+type EverProvedIdentity = VerifiedIdentity & {
+    readonly resolution: 'ever-proved';
+};
 /**
  * The two axes v1 genuinely cannot check:
  * - `revocation` — non-revocation is never provable (a relay can only attest to
@@ -48,14 +56,14 @@ interface VerifyResult<T> {
 interface ResolvedContent {
     chain: VerifiedContentChain;
     /** The creator identity — resolved as a side effect of key resolution. */
-    creator: VerifiedIdentity;
+    creator: EffectiveIdentity;
     /** The current document blob, when fetched. */
     document?: DocumentBlob;
 }
 interface ResolvedCredential {
     credential: VerifiedDFOSCredential;
     /** The issuer identity, verified. */
-    issuer: VerifiedIdentity;
+    issuer: EffectiveIdentity;
     /** Revocation status per the effective revocation checker (see Trust.unverifiable). */
     revoked: boolean;
 }
@@ -71,13 +79,13 @@ interface DocumentBlob {
 /** Discriminated result of the paste-a-string dispatcher. */
 type Resolution = ({
     kind: 'identity';
-} & Resolved<VerifiedIdentity>) | ({
+} & Resolved<EffectiveIdentity>) | ({
     kind: 'content';
 } & Resolved<ResolvedContent>) | ({
     kind: 'credential';
 } & Resolved<ResolvedCredential>);
 /**
- * Check whether a credential has been revoked. Default: `() => false` (honest).
+ * Check whether a credential has been revoked. The default queries relays and throws when none answers.
  *
  * `asOfUnix` is the protocol's revocation as-of basis (see the protocol's
  * `RevocationChecker`): supplied when folding committed history, so a credential
@@ -92,8 +100,19 @@ type RevChecker = (issuerDID: string, credentialCID: string, asOfUnix?: number)
  * `verifyDFOSCredential`, or any DFOS verifier. This is the trunk product.
  */
 interface Callbacks {
-    resolveKey: (kid: string) => Promise<Uint8Array>;
-    resolveIdentity: (did: string) => Promise<VerifiedIdentity | undefined>;
+    /**
+     * Resolve a kid to key bytes in the signing identity's state as of `basis` —
+     * a committed artifact's own `createdAt`, or nothing for an ephemeral
+     * presentation, whose basis is now.
+     */
+    resolveKey: (kid: string, basis?: string) => Promise<Uint8Array>;
+    /** Resolve a DID to its verified identity state as of `basis`. */
+    resolveIdentity: (did: string, basis?: string) => Promise<EffectiveIdentity | undefined>;
+    /**
+     * Resolve a DID to its identity with every key it has ever proved — the
+     * credit-claim carve-out, which runs no temporal check and so has no basis.
+     */
+    resolveClaimantIdentity: (did: string) => Promise<EverProvedIdentity | undefined>;
     isRevoked: RevChecker;
 }
 /**
@@ -256,7 +275,7 @@ interface ClientConfig {
     store?: Store;
     /** Distinct-digest agreement threshold. Default 1 (first-wins). */
     quorum?: number;
-    /** Revocation checker. Default `() => false` (honest — status is unverifiable). */
+    /** Revocation checker. Default queries relays; throws when none answers. */
     isRevoked?: RevChecker;
     /** Injected fetch for blob/health/revocation calls. Default `globalThis.fetch`. */
     fetch?: typeof fetch;
@@ -276,7 +295,7 @@ interface Client {
     callbacks(options?: CallOptions): Callbacks;
     /** Paste-a-string dispatcher → a typed, trust-wrapped resolution. */
     resolve(ref: string, options?: CallOptions): Promise<Resolution>;
-    identity(did: string, options?: CallOptions): Promise<Resolved<VerifiedIdentity>>;
+    identity(did: string, options?: CallOptions): Promise<Resolved<EffectiveIdentity>>;
     content(contentId: string, options?: CallOptions): Promise<Resolved<ResolvedContent>>;
     credential(jws: string, options?: CallOptions): Promise<Resolved<ResolvedCredential>>;
     document(contentId: string, options?: CallOptions): Promise<Resolved<DocumentBlob>>;
@@ -334,9 +353,10 @@ interface Client {
         issuer?: string;
         resource?: string;
         action?: string;
+        order?: IndexRecencyOrder;
         after?: string;
         limit?: number;
     }, options?: CallOptions): Promise<IndexCredentialsPage>;
 }
 
-export type { ClientConfig as C, DocumentBlob as D, GlobalLogOptions as G, IndexCapabilities as I, LogOp as L, Provenance as P, RevChecker as R, Store as S, Trust as T, UnverifiableAxis as U, VerifyResult as V, Client as a, Callbacks as b, CallOptions as c, GlobalLogPage as d, GlobalLogResult as e, IndexContentPage as f, IndexContentRow as g, IndexCountersignatureRow as h, IndexCountersignaturesPage as i, IndexCredentialRow as j, IndexCredentialsPage as k, IndexIdentitiesPage as l, IndexIdentityProfile as m, IndexIdentityRow as n, IndexOrder as o, IndexRecencyOrder as p, RelayHealth as q, RelayResponse as r, Resolution as s, Resolved as t, ResolvedContent as u, ResolvedCredential as v };
+export type { ClientConfig as C, DocumentBlob as D, EffectiveIdentity as E, GlobalLogOptions as G, IndexCapabilities as I, LogOp as L, Provenance as P, RevChecker as R, Store as S, Trust as T, UnverifiableAxis as U, VerifyResult as V, Client as a, Callbacks as b, CallOptions as c, EverProvedIdentity as d, GlobalLogPage as e, GlobalLogResult as f, IndexContentPage as g, IndexContentRow as h, IndexCountersignatureRow as i, IndexCountersignaturesPage as j, IndexCredentialRow as k, IndexCredentialsPage as l, IndexIdentitiesPage as m, IndexIdentityProfile as n, IndexIdentityRow as o, IndexOrder as p, IndexRecencyOrder as q, RelayHealth as r, RelayResponse as s, Resolution as t, Resolved as u, ResolvedContent as v, ResolvedCredential as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.50.0",
+  "version": "0.52.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,16 +47,16 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.50.0",
-    "@metalabel/dfos-web-relay": "^0.50.0"
+    "@metalabel/dfos-protocol": "^0.52.0",
+    "@metalabel/dfos-web-relay": "^0.52.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-web-relay": "0.50.0",
-    "@metalabel/dfos-protocol": "0.50.0"
+    "@metalabel/dfos-protocol": "0.52.0",
+    "@metalabel/dfos-web-relay": "0.52.0"
   },
   "scripts": {
     "build": "tsup",