@metalabel/dfos-client 0.50.0 → 0.51.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-CSKl-wYe.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-web-relay/peer-client';
 

package/dist/api-auth.js

@@ -132,14 +132,14 @@ 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;

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-CSKl-wYe.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-CSKl-wYe.js';
+export { m as memoryStore } from './memory-Ca1F2EBW.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
@@ -72,6 +72,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,10 +277,6 @@ 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,
   ...state.provedKeys ?? {
@@ -289,7 +286,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 +370,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) => {
@@ -574,7 +588,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,7 +618,7 @@ 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);
     const axes = [];
@@ -646,7 +664,7 @@ 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);
         if (revoked) return { ok: false, error: "credential revoked", value: verified };

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

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

package/dist/siwd.d.ts

@@ -1,5 +1,5 @@
 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-CSKl-wYe.js';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
 
@@ -89,13 +89,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 +160,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 +171,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.
  *
@@ -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;

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-Ca1F2EBW.js';
+import { S as Store } from '../types-CSKl-wYe.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-CSKl-wYe.d.ts}

@@ -92,8 +92,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<VerifiedIdentity | 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<VerifiedIdentity | undefined>;
     isRevoked: RevChecker;
 }
 /**
@@ -334,6 +345,7 @@ interface Client {
         issuer?: string;
         resource?: string;
         action?: string;
+        order?: IndexRecencyOrder;
         after?: string;
         limit?: number;
     }, options?: CallOptions): Promise<IndexCredentialsPage>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.50.0",
+  "version": "0.51.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.51.0",
+    "@metalabel/dfos-web-relay": "^0.51.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.51.0",
+    "@metalabel/dfos-web-relay": "0.51.0"
   },
   "scripts": {
     "build": "tsup",