@metalabel/dfos-client 0.46.0 → 0.48.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Metalabel
+Copyright (c) 2026 DFOS Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -57,6 +57,34 @@ createClient({ relays: [...], quorum: 2 }); // require 2 relays to return the sa
 
 `quorum: 1` (default) is first-wins with failover. `provenance.agreed` reports whether the threshold was met.
 
+### Divergence — and the way out of it
+
+The cached prefix is a **pin**: once a chain's first N operations have verified here, a later read has to extend them. A relay answering with a _different_ operation at a position the pin covers is contradicting proof rather than carrying news, so the read fails with a `DivergenceError`.
+
+```typescript
+import { divergenceErrorFrom } from '@metalabel/dfos-client';
+
+try {
+  await client.identity(did);
+} catch (err) {
+  const d = divergenceErrorFrom(err); // walks `cause` — the fan-out wraps its candidate's failure
+  if (d) {
+    d.chainType; // 'identity' | 'content' — a content read can diverge on its CREATOR's chain
+    d.chainId;
+    d.cachedHeadCID; // the tip this client proved
+    d.liveHeadCID; // the tip the relays serve now
+  }
+}
+```
+
+**Nothing is discarded automatically.** A client that healed itself would erase the only evidence a rewrite happened, which is the reason the prefix is pinned at all. The undo is explicit and per-chain:
+
+```typescript
+await client.discardCachedChain('identity', did); // this chain's prefix only; nothing else, nowhere else
+```
+
+The next read of that chain folds cold from genesis and recomputes every signature and CID. Deleting is local: no relay is touched and no operation is destroyed. It is idempotent, safe for a chain that was never cached, and answers `false` only when the configured `Store` exposes no `delete` (both bundled stores do).
+
 ### The free floor
 
 ```typescript

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-ByxTj1u-.js';
+import { a as Client } from './types-BfzEg_gw.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-web-relay/peer-client';
 

package/dist/{chunk-63XCFYOE.js → chunk-KY632J74.js}

@@ -7,6 +7,9 @@ var memoryStore = () => {
     },
     async set(key, value) {
       map.set(key, value);
+    },
+    async delete(key) {
+      map.delete(key);
     }
   };
 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ClientConfig, a as Client, b as Callbacks, R as RevChecker } from './types-ByxTj1u-.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-ByxTj1u-.js';
-export { m as memoryStore } from './memory-CL1DM6Ud.js';
+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 '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
@@ -12,6 +12,51 @@ declare const createClient: (config: ClientConfig) => Client;
  */
 declare const resolvers: (relays: string[]) => Callbacks;
 
+/**
+ * The relays' log for a chain disagrees with the verified prefix this client
+ * cached: at a position the cache already covers, the operation served is not
+ * the operation this client proved. Distinct from `StaleAnswerError` (a relay
+ * merely behind) and from a failed proof (a chain that does not verify) — here
+ * two histories contradict each other about what already happened, so verifying
+ * forward from the trusted prefix is not a thing that can be done.
+ *
+ * NOTHING IS DISCARDED HERE. Dropping a verified prefix is a decision about
+ * trust, not an error path: a client that healed itself silently would erase the
+ * only evidence that a rewrite happened, which is the whole reason the prefix is
+ * pinned. `client.discardCachedChain()` is the explicit undo, and it is the
+ * caller's to call.
+ *
+ * The error is thrown as a CANDIDATE FILTER, inside the fan-out. A fan-out where
+ * every relay diverges surfaces its own error carrying this one as `cause`, so
+ * callers reach it with `divergenceErrorFrom(err)` rather than a bare
+ * `instanceof` on what they caught.
+ */
+declare class DivergenceError extends Error {
+    readonly chainType: 'identity' | 'content';
+    readonly chainId: string;
+    /** Head CID of the verified prefix this client holds. */
+    readonly cachedHeadCID: string;
+    /**
+     * Head CID of the log the relays served, as that operation's own JWS header
+     * names it — orientation for a human, never a proof. Empty when the served log
+     * was empty or its head named no CID.
+     */
+    readonly liveHeadCID: string;
+    constructor(input: {
+        chainType: 'identity' | 'content';
+        chainId: string;
+        cachedHeadCID: string;
+        liveHeadCID: string;
+    });
+}
+/**
+ * Find the `DivergenceError` behind a caught error, walking the `cause` chain —
+ * the fan-out wraps a candidate's verification failure, and a content read wraps
+ * the identity read inside it. Returns `undefined` when the failure was anything
+ * else, so a caller can branch on the answer instead of matching message text.
+ */
+declare const divergenceErrorFrom: (err: unknown) => DivergenceError | undefined;
+
 /**
  * Build the default revocation checker over an ordered relay set.
  *
@@ -29,4 +74,4 @@ declare const resolvers: (relays: string[]) => Callbacks;
  */
 declare const createRevocationChecker: (relays: string[], fetchImpl: typeof fetch, resolveKey: (kid: string) => Promise<Uint8Array>) => RevChecker;
 
-export { Callbacks, Client, ClientConfig, RevChecker, createClient, createRevocationChecker, resolvers };
+export { Callbacks, Client, ClientConfig, DivergenceError, RevChecker, createClient, createRevocationChecker, divergenceErrorFrom, resolvers };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   memoryStore
-} from "./chunk-63XCFYOE.js";
+} from "./chunk-KY632J74.js";
 
 // src/client.ts
 import {
@@ -111,7 +111,9 @@ var fanOutLog = async (fetchPage, relays, quorum, verifyCandidate) => {
   }
   if (lastVerifyError !== void 0) {
     const message = lastVerifyError instanceof Error ? lastVerifyError.message : "unknown error";
-    throw new Error(`all candidate logs failed verification: ${message}`);
+    throw new Error(`all candidate logs failed verification: ${message}`, {
+      cause: lastVerifyError
+    });
   }
   return {
     outcome: "unreachable",
@@ -238,6 +240,36 @@ import {
 } from "@metalabel/dfos-protocol/chain";
 import { decodeJwsUnsafe } from "@metalabel/dfos-protocol/crypto";
 var DID_PREFIX = "did:dfos";
+var cacheKey = (kind, id) => `${kind}:${id}`;
+var DivergenceError = class extends Error {
+  chainType;
+  chainId;
+  /** Head CID of the verified prefix this client holds. */
+  cachedHeadCID;
+  /**
+   * Head CID of the log the relays served, as that operation's own JWS header
+   * names it — orientation for a human, never a proof. Empty when the served log
+   * was empty or its head named no CID.
+   */
+  liveHeadCID;
+  constructor(input) {
+    super(`${input.chainType} log diverges from the verified cached prefix: ${input.chainId}`);
+    this.name = "DivergenceError";
+    this.chainType = input.chainType;
+    this.chainId = input.chainId;
+    this.cachedHeadCID = input.cachedHeadCID;
+    this.liveHeadCID = input.liveHeadCID;
+  }
+};
+var CAUSE_DEPTH = 8;
+var divergenceErrorFrom = (err) => {
+  let cursor = err;
+  for (let depth = 0; depth < CAUSE_DEPTH && cursor instanceof Error; depth++) {
+    if (cursor instanceof DivergenceError) return cursor;
+    cursor = cursor.cause;
+  }
+  return void 0;
+};
 var opMeta = (jws) => {
   const decoded = decodeJwsUnsafe(jws);
   const cid = typeof decoded?.header.cid === "string" ? decoded.header.cid : "";
@@ -263,7 +295,7 @@ var keyBytesFor = (state, keyId) => {
 var createResolvers = (deps) => {
   const relaysFor = (o) => normalizeRelays(o?.relays ?? deps.relays);
   const getIdentityChain = async (did, options) => {
-    const key = `identity:${did}`;
+    const key = cacheKey("identity", did);
     const cached = options?.fresh ? void 0 : await deps.store.get(key);
     const verifyCandidate = async (entries) => {
       if (!cached) {
@@ -277,7 +309,12 @@ var createResolvers = (deps) => {
         return { state: state2, log: log2, headCID: last.cid, lastCreatedAt: last.createdAt };
       }
       if (cached.log.some((jws, index) => index < entries.length && entries[index].jwsToken !== jws)) {
-        throw new Error(`identity log diverges from the verified cached prefix: ${did}`);
+        throw new DivergenceError({
+          chainType: "identity",
+          chainId: did,
+          cachedHeadCID: cached.headCID,
+          liveHeadCID: opMeta(entries[entries.length - 1]?.jwsToken ?? "").cid
+        });
       }
       if (entries.length < cached.log.length) {
         throw new StaleAnswerError(`identity log is behind the verified cached prefix: ${did}`);
@@ -358,7 +395,7 @@ var createResolvers = (deps) => {
     isRevoked: deps.isRevoked
   });
   const getContentChain = async (contentId, options) => {
-    const key = `content:${contentId}`;
+    const key = cacheKey("content", contentId);
     const cached = options?.fresh ? void 0 : await deps.store.get(key);
     const verifyCandidate = async (entries) => {
       if (!cached) {
@@ -380,7 +417,12 @@ var createResolvers = (deps) => {
         return { state: state2, log: log2, headCID: last.cid, lastCreatedAt: last.createdAt };
       }
       if (cached.log.some((jws, index) => index < entries.length && entries[index].jwsToken !== jws)) {
-        throw new Error(`content log diverges from the verified cached prefix: ${contentId}`);
+        throw new DivergenceError({
+          chainType: "content",
+          chainId: contentId,
+          cachedHeadCID: cached.headCID,
+          liveHeadCID: opMeta(entries[entries.length - 1]?.jwsToken ?? "").cid
+        });
       }
       if (entries.length < cached.log.length) {
         throw new StaleAnswerError(
@@ -439,7 +481,13 @@ var createResolvers = (deps) => {
       tipUnverified: cached !== void 0 && candidate.log.length === cached.log.length
     };
   };
-  return { getIdentityChain, getContentChain, callbacks };
+  const discardCachedChain = async (kind, id) => {
+    const remove = deps.store.delete?.bind(deps.store);
+    if (!remove) return false;
+    await remove(cacheKey(kind, id));
+    return true;
+  };
+  return { getIdentityChain, getContentChain, discardCachedChain, callbacks };
 };
 
 // src/revocation.ts
@@ -690,6 +738,7 @@ var createClient = (config) => {
   return {
     callbacks,
     resolve,
+    discardCachedChain: resolvers2.discardCachedChain,
     identity,
     content,
     credential,
@@ -721,8 +770,10 @@ var fetchBlob = async (contentId, relays, fetchImpl) => {
 };
 var resolvers = (relays) => createClient({ relays }).callbacks();
 export {
+  DivergenceError,
   createClient,
   createRevocationChecker,
+  divergenceErrorFrom,
   memoryStore,
   resolvers
 };

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

@@ -1,4 +1,4 @@
-import { S as Store } from './types-ByxTj1u-.js';
+import { S as Store } from './types-BfzEg_gw.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-ByxTj1u-.js';
+import { a as Client, V as VerifyResult } from './types-BfzEg_gw.js';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
 

package/dist/store/index.d.ts

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

package/dist/store/index.js

@@ -1,6 +1,6 @@
 import {
   memoryStore
-} from "../chunk-63XCFYOE.js";
+} from "../chunk-KY632J74.js";
 
 // src/store/indexeddb.ts
 var STORE_NAME = "dfos-cache";
@@ -40,6 +40,14 @@ var indexedDbStore = (dbName = "dfos-client") => {
       const db = await open();
       const store = db.transaction(STORE_NAME, "readwrite").objectStore(STORE_NAME);
       await promisify(store.put(value, key));
+    },
+    // IndexedDB's own delete succeeds on a key that is not there, which is
+    // exactly the idempotence the caller wants: discarding a chain that was
+    // never cached is not a failure, it is already the requested state.
+    async delete(key) {
+      const db = await open();
+      const store = db.transaction(STORE_NAME, "readwrite").objectStore(STORE_NAME);
+      await promisify(store.delete(key));
     }
   };
 };

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

@@ -104,6 +104,13 @@ interface Callbacks {
 interface Store {
     get(key: string): Promise<unknown | undefined>;
     set(key: string, value: unknown): Promise<void>;
+    /**
+     * Forget one key. Idempotent, and absent keys are not an error. Optional so a
+     * store written against the two-method shape still satisfies this interface;
+     * a store without it makes `client.discardCachedChain()` answer `false`
+     * instead of quietly doing nothing. Both bundled stores implement it.
+     */
+    delete?(key: string): Promise<void>;
 }
 /** A raw JWS operation from a relay log — cid + token, unverified until folded. */
 interface LogOp {
@@ -275,6 +282,17 @@ interface Client {
     document(contentId: string, options?: CallOptions): Promise<Resolved<DocumentBlob>>;
     /** No-throw, self-routing "is this legit". */
     verify(jws: string, options?: CallOptions): Promise<VerifyResult<unknown>>;
+    /**
+     * Forget the verified prefix cached for ONE chain, so the next read of it
+     * folds cold from genesis. The explicit way out of a `DivergenceError`: the
+     * client never discards a pinned prefix on its own, because a contradiction
+     * that heals itself is a contradiction nobody sees. Narrow (this chain only),
+     * idempotent, and local — no relay is touched and no operation is destroyed.
+     *
+     * `false` means the configured store exposes no `delete` and nothing was
+     * forgotten; both bundled stores return `true`.
+     */
+    discardCachedChain(kind: 'identity' | 'content', id: string): Promise<boolean>;
     /** Raw floor. */
     log(kind: 'identity' | 'content', id: string, options?: CallOptions): Promise<Resolved<LogOp[]>>;
     globalLog(after?: string, options?: GlobalLogOptions): Promise<GlobalLogResult>;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.46.0",
+  "version": "0.48.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",
-  "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
+  "author": "DFOS Inc (https://dfos.com)",
   "repository": {
     "type": "git",
     "url": "https://github.com/metalabel/dfos.git",
@@ -47,16 +47,16 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.46.0",
-    "@metalabel/dfos-web-relay": "^0.46.0"
+    "@metalabel/dfos-protocol": "^0.48.0",
+    "@metalabel/dfos-web-relay": "^0.48.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-web-relay": "0.46.0",
-    "@metalabel/dfos-protocol": "0.46.0"
+    "@metalabel/dfos-protocol": "0.48.0",
+    "@metalabel/dfos-web-relay": "0.48.0"
   },
   "scripts": {
     "build": "tsup",