@metalabel/dfos-client 0.52.1 → 0.54.0

package/README.md

@@ -158,7 +158,11 @@ await verifyApiRequest(client, {
 });
 ```
 
-It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `unverifiable` / `config`), `phase`, and the recommended `status` — branch on those, never on message text.
+It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `replayed` / `uncovered` / `unverifiable` / `config`), `phase`, and the recommended `status` — branch on those, never on message text.
+
+The two 403s say different things. `invalid` means the credential does not hold: a broken chain, a revocation, a public audience, an audience that is not the signer. `uncovered` means it holds and does not reach this route's resource and action. A route offering optional authentication serves its anonymous projection on `uncovered`, because a credential only ever adds, and refuses `invalid` outright.
+
+**Space-scoped grants, and per-request uniqueness.** A route that serves one space passes `resource: 'api:<host>/spaces/<id>'`, resolving the id by its own routing; a grant naming the bare host covers it by ancestor coverage, and a grant naming one space covers only that space. The host half must match `host`, so a mismatch is a deployment error (500) rather than a verdict about the caller. A route that gates writes passes `requireJti: true` and records the returned `jti` under the presenter DID until the proof expires; the second presentation of the same value is a replay, which `replayedProof` classifies as a 409. On the signing side `createApiAuthFetch` attaches a fresh `jti` to every write by default — pass `jti: 'always'` or `jti: 'never'` to change that.
 
 `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.
 
@@ -179,6 +183,8 @@ 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.
 
+`spaces` on the login request locks consent to a named set of places — `'all'`, or up to 31 distinct 31-character space ids. A host honors it only when `scope` names a space-level action, and refuses the request whole otherwise. Absent, the user chooses the places at the consent screen. Either way the returned credential's `att` is the answer: consent may narrow the set, so read it rather than assuming the ask was honored whole.
+
 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:

package/dist/api-auth.d.ts

@@ -1,9 +1,9 @@
-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-BbIEz7BN.js';
+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_JTI_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, ProofExtraMembers, REQUEST_PROOF_JWS_TYP, RequestProofFailurePhase, RequestProofFailureReason, RequestProofPayload, SignApiIdentityRequestInput, SignApiRequestInput, apiIdentitySigningInput, apiRequestSigningInput, apiResourceCovers, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, generateJti, parseApiResource, parseDfosAuthorization, replayedProof, sha256BodyHash, signApiIdentityRequest, signApiRequest, uncoveredProof } from '@metalabel/dfos-protocol/credentials';
+import { a as Client } from './types-DClhQw33.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-web-relay/peer-client';
 
-/** The v0 action registry's only token. */
+/** The registry's account-level default action. */
 declare const DEFAULT_API_ACTION = "read:profile";
 interface CreateApiAuthFetchOptions {
     /**
@@ -20,6 +20,13 @@ interface CreateApiAuthFetchOptions {
     sign: (message: Uint8Array) => Promise<Uint8Array>;
     /** The underlying transport. Default `globalThis.fetch`. */
     fetch?: typeof fetch;
+    /**
+     * When to attach a freshly minted `jti`. Default `'writes'` — every method
+     * except GET, HEAD, and OPTIONS — which is what a write-gating host requires.
+     * `'always'` covers a host that requires it on reads too; `'never'` is for a
+     * host that has no replay cache and would only be paying for the bytes.
+     */
+    jti?: 'writes' | 'always' | 'never';
 }
 /**
  * A signing `fetch`. Hand it to any API client with a fetch seam and every
@@ -70,8 +77,8 @@ interface VerifyApiRequestInput {
      * 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.
      *
-     * It is also the id half of the `api:<host>` resource string this verifier
-     * requires, so the request binding and the grant name the same origin.
+     * It is also the host half of the `api:` resource this verifier requires, so
+     * the request binding and the grant name the same origin.
      */
     host: string;
     /** The received request's method. */
@@ -92,10 +99,26 @@ interface VerifyApiRequestInput {
     maxBodyBytes?: number;
     /** The action token this route requires. Default `read:profile`. */
     action?: string;
+    /**
+     * The `api:` resource this route demands, which the leaf's attenuation must
+     * cover. Default `api:<host>` — the account-level form. A SPACE-ADDRESSED
+     * route passes `api:<host>/spaces/<id>`, resolving the id by its own routing;
+     * a bare-host grant satisfies it by ancestor coverage.
+     *
+     * Its host half MUST byte-equal `host`, so the binding and the grant name the
+     * same origin. Anything else is a deployment error (500), never a verdict.
+     */
+    resource?: string;
     /** 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;
+    /**
+     * Require the registered `jti` member (401 when absent). A deployment gating
+     * WRITES sets it on every write-shaped route and records the returned value in
+     * its own replay cache, keyed with the presenter DID.
+     */
+    requireJti?: boolean;
     /**
      * Accept a presenter resolution whose tip could not be verified (cache-only or
      * empty-delta-against-cache). Default FALSE: key resolution is CURRENT-STATE,
@@ -110,12 +133,18 @@ interface VerifiedRequestProof {
     subjectDID: string;
     /** The authority the grant and the binding both name. */
     host: string;
+    /** The `api:` resource the route demanded and the leaf was found to cover. */
+    resource: string;
     /** The action token the leaf's attenuation was found to cover. */
     action: string;
     /** The proof's issued-at, unix seconds. */
     iat: number;
     /** The leaf credential's CID, re-derived and equal to the proof's member. */
     credentialCID: string;
+    /** The registered `jti`, when the proof carried one — the replay cache's value. */
+    jti?: string;
+    /** The signing key's roles, when the presenter's state named them. */
+    keyRoles?: readonly ('auth' | 'assert' | 'controller')[];
 }
 /**
  * Verify a credential-gated request — INTEGRATIONS.md, Verification algorithm's
@@ -131,7 +160,13 @@ interface VerifiedRequestProof {
  *
  * Throws `ApiRequestVerifyError`; branch on `reason`/`phase`/`status`, never on
  * message text. `status` is the recommended HTTP code (401 proof-invalid, 403
- * credential-invalid, 503 unverifiable, 500 config).
+ * credential-invalid or uncovered, 503 unverifiable, 500 config).
+ *
+ * The two 403s are different answers. `invalid` means the credential itself does
+ * not hold — a broken chain, a revocation, a public audience, an audience that
+ * is not the signer. `uncovered` means it holds and does not reach this route's
+ * resource and action; a route offering optional authentication serves its
+ * anonymous projection on that verdict rather than refusing.
  *
  * Missing issuer dependencies and an unavailable revocation source are
  * unverifiable (503). The default checker throws when no relay answers; an
@@ -168,6 +203,12 @@ interface VerifyApiIdentityRequestInput {
     windowSeconds?: number;
     /** Clock-skew allowance `S`, seconds. Default 60. `W + S` MUST NOT exceed 300. */
     skewSeconds?: number;
+    /**
+     * Require the registered `jti` member (401 when absent). A deployment gating
+     * WRITES with a bare identity sets it on every write-shaped route — the signer
+     * is the principal, and the replay discipline is the same one.
+     */
+    requireJti?: boolean;
     /**
      * Accept a presenter resolution whose tip could not be verified (cache-only or
      * empty-delta-against-cache). Default FALSE: key resolution is CURRENT-STATE,
@@ -193,10 +234,18 @@ interface VerifiedIdentityProof {
     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.
+     * unregistered additive member the envelope verifier ignored. The signature
+     * already covers it; the canonical member set stays closed.
      */
     rawPayload: Record<string, unknown>;
+    /** The registered `jti`, when the proof carried one — the replay cache's value. */
+    jti?: string;
+    /**
+     * The signing key's roles, when the presenter's state named them. A deployment
+     * gating writes with this artifact should refuse a key whose only effective
+     * role is `controller`.
+     */
+    keyRoles?: readonly ('auth' | 'assert' | 'controller')[];
 }
 /**
  * Verify an identity-proven request — INTEGRATIONS.md, Verification algorithm's

package/dist/api-auth.js

@@ -4,6 +4,7 @@ import {
   apiIdentitySigningInput,
   apiRequestSigningInput,
   ApiRequestVerifyError,
+  apiResourceCovers,
   assertProofVerifierConfig,
   buildApiAuthHeaders,
   buildApiIdentityHeaders,
@@ -13,17 +14,22 @@ import {
   DEFAULT_PROOF_WINDOW_SECONDS,
   DFOS_AUTH_SCHEME,
   EMPTY_BODY_SHA256,
+  generateJti,
   IDENTITY_PROOF_JWS_TYP,
   matchesResource,
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
+  MAX_JTI_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
+  parseApiResource,
   parseDfosAuthorization,
+  replayedProof,
   REQUEST_PROOF_JWS_TYP,
   sha256BodyHash,
   signApiIdentityRequest,
   signApiRequest,
+  uncoveredProof,
   verifyDelegationChain,
   verifyDFOSCredential,
   verifyIdentityProofEnvelope,
@@ -31,6 +37,7 @@ import {
 } from "@metalabel/dfos-protocol/credentials";
 import { decodeJwsUnsafe } from "@metalabel/dfos-protocol/crypto";
 var DEFAULT_API_ACTION = "read:profile";
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
 var MAX_DELEGATION_DEPTH = 16;
 var credentialCIDFromHeader = (credential) => {
   const decoded = decodeJwsUnsafe(credential);
@@ -45,6 +52,7 @@ var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::
 var createApiAuthFetch = (options) => {
   const credentialCID = credentialCIDFromHeader(options.credential);
   const send = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const jtiMode = options.jti ?? "writes";
   return async (input, init) => {
     const request = init === void 0 && input instanceof Request ? input : new Request(input, init);
     const url = new URL(request.url);
@@ -53,6 +61,7 @@ var createApiAuthFetch = (options) => {
         `refusing to sign a ${url.protocol}// request to ${url.host}: api: surfaces are HTTPS surfaces, and a proof sent in the clear replays for its whole freshness window (plaintext is allowed only to localhost, 127.0.0.1, and [::1])`
       );
     }
+    const attachJti = jtiMode === "always" || jtiMode === "writes" && !SAFE_METHODS.has(request.method);
     const { proof } = await signApiRequest({
       method: request.method,
       // `host`, never `hostname`: the authority carries the port when there is
@@ -69,7 +78,8 @@ var createApiAuthFetch = (options) => {
       body: new Uint8Array(await request.clone().arrayBuffer()),
       credentialCID,
       kid: options.kid,
-      sign: options.sign
+      sign: options.sign,
+      ...attachJti ? { jti: generateJti() } : {}
     });
     const headers = new Headers(request.headers);
     for (const [name, value] of Object.entries(
@@ -94,10 +104,24 @@ var clientPresenterResolver = (client, allowStale) => async (did) => {
     );
   }
   const state = resolved.value;
-  return {
-    isDeleted: state.isDeleted,
-    keys: [...state.authKeys, ...state.assertKeys, ...state.controllerKeys]
-  };
+  const byId = /* @__PURE__ */ new Map();
+  for (const [role, keys] of [
+    ["auth", state.authKeys],
+    ["assert", state.assertKeys],
+    ["controller", state.controllerKeys]
+  ]) {
+    for (const key of keys) {
+      const seen = byId.get(key.id);
+      if (seen) seen.roles.push(role);
+      else
+        byId.set(key.id, {
+          id: key.id,
+          publicKeyMultibase: key.publicKeyMultibase,
+          roles: [role]
+        });
+    }
+  }
+  return { isDeleted: state.isDeleted, keys: [...byId.values()] };
 };
 var discoverChainRoot = (leafToken) => {
   let token = leafToken;
@@ -118,12 +142,24 @@ var verifyApiRequest = async (client, input) => {
   if (action.split(",").every((token) => token.trim() === "")) {
     throw misconfigured("required action must name a non-empty token");
   }
+  const resource = input.resource ?? `api:${input.host}`;
+  const parsedResource = parseApiResource(resource);
+  if (!parsedResource) {
+    throw misconfigured(
+      `required resource ${resource} is not a well-formed api: resource (api:<host> or api:<host>/spaces/<id>)`
+    );
+  }
+  if (parsedResource.host !== input.host) {
+    throw misconfigured(
+      `required resource ${resource} names a different authority than the verifier's host ${input.host}`
+    );
+  }
   if (input.credential.length > MAX_CREDENTIAL_SIZE) {
     throw invalidProof(
       `credential exceeds max size: ${input.credential.length} > ${MAX_CREDENTIAL_SIZE}`
     );
   }
-  const { payload, presenterDID, now } = await verifyRequestProofEnvelope(
+  const { payload, presenterDID, now, keyRoles } = await verifyRequestProofEnvelope(
     input,
     clientPresenterResolver(client, input.allowStale === true)
   );
@@ -167,23 +203,34 @@ var verifyApiRequest = async (client, input) => {
   if (leaf.aud !== presenterDID) {
     throw invalidCredential("credential audience does not match the request proof signing key");
   }
-  if (!await matchesResource(leaf.att, `api:${input.host}`, action)) {
-    throw invalidCredential(`credential does not cover ${action} on api:${input.host}`);
+  if (!await matchesResource(leaf.att, resource, action)) {
+    throw uncoveredProof(`credential does not cover ${action} on ${resource}`);
   }
   return {
     subjectDID: rootDID,
     host: input.host,
+    resource,
     action,
     iat: payload.iat,
-    credentialCID: leaf.credentialCID
+    credentialCID: leaf.credentialCID,
+    ...payload.jti !== void 0 ? { jti: payload.jti } : {},
+    ...keyRoles !== void 0 ? { keyRoles } : {}
   };
 };
 var verifyApiIdentityRequest = async (client, input) => {
-  const { payload, rawPayload, presenterDID, kid } = await verifyIdentityProofEnvelope(
+  const { payload, rawPayload, presenterDID, kid, keyRoles } = await verifyIdentityProofEnvelope(
     input,
     clientPresenterResolver(client, input.allowStale === true)
   );
-  return { presenterDID, kid, host: input.host, iat: payload.iat, rawPayload };
+  return {
+    presenterDID,
+    kid,
+    host: input.host,
+    iat: payload.iat,
+    rawPayload,
+    ...payload.jti !== void 0 ? { jti: payload.jti } : {},
+    ...keyRoles !== void 0 ? { keyRoles } : {}
+  };
 };
 export {
   ApiRequestVerifyError,
@@ -194,19 +241,25 @@ export {
   EMPTY_BODY_SHA256,
   IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
+  MAX_JTI_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
   REQUEST_PROOF_JWS_TYP,
   apiIdentitySigningInput,
   apiRequestSigningInput,
+  apiResourceCovers,
   assertProofVerifierConfig,
   buildApiAuthHeaders,
   buildApiIdentityHeaders,
   createApiAuthFetch,
+  generateJti,
+  parseApiResource,
   parseDfosAuthorization,
+  replayedProof,
   sha256BodyHash,
   signApiIdentityRequest,
   signApiRequest,
+  uncoveredProof,
   verifyApiIdentityRequest,
   verifyApiRequest
 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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 { C as ClientConfig, a as Client, b as Callbacks, R as RevChecker } from './types-DClhQw33.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-DClhQw33.js';
+export { m as memoryStore } from './memory-aYqSas8m.js';
 import '@metalabel/dfos-protocol/chain';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
@@ -65,7 +65,9 @@ declare const divergenceErrorFrom: (err: unknown) => DivergenceError | undefined
  * 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 and at least
- * one relay answered with a parseable status body. Zero answers throws.
+ * one relay answered with a parseable status body. Zero answers throws, and so
+ * does a positive answer whose signing key this client could not resolve: a
+ * dependency failure is never a negative status.
  *
  * 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

package/dist/index.js

@@ -12,6 +12,7 @@ import { dagCborCanonicalEncode, decodeJwsUnsafe as decodeJwsUnsafe2 } from "@me
 import { createHttpPeerClient } from "@metalabel/dfos-web-relay/peer-client";
 
 // src/transport.ts
+import { isDependencyMissing, markDependencyMissing } from "@metalabel/dfos-protocol";
 var PAGE_LIMIT = 1e3;
 var MAX_PAGES = 1e4;
 var normalizeRelays = (relays) => {
@@ -62,6 +63,14 @@ var fanOutLog = async (fetchPage, relays, quorum, verifyCandidate) => {
   const byDigest = /* @__PURE__ */ new Map();
   const badDigests = /* @__PURE__ */ new Set();
   let lastVerifyError;
+  let lastDependencyError;
+  const recordFailure = (err, digest) => {
+    if (!(err instanceof StaleAnswerError)) {
+      if (isDependencyMissing(err)) lastDependencyError = err;
+      else lastVerifyError = err;
+    }
+    badDigests.add(digest);
+  };
   for (const url of relays) {
     let entries = null;
     try {
@@ -89,8 +98,7 @@ var fanOutLog = async (fetchPage, relays, quorum, verifyCandidate) => {
           provenance: { answeredBy: group.url, responses, agreed: true, fromCache: false }
         };
       } catch (err) {
-        if (!(err instanceof StaleAnswerError)) lastVerifyError = err;
-        badDigests.add(digest);
+        recordFailure(err, digest);
       }
     }
   }
@@ -105,8 +113,7 @@ var fanOutLog = async (fetchPage, relays, quorum, verifyCandidate) => {
         provenance: { answeredBy: group.url, responses, agreed: false, fromCache: false }
       };
     } catch (err) {
-      if (!(err instanceof StaleAnswerError)) lastVerifyError = err;
-      badDigests.add(digest);
+      recordFailure(err, digest);
     }
   }
   if (lastVerifyError !== void 0) {
@@ -115,6 +122,14 @@ var fanOutLog = async (fetchPage, relays, quorum, verifyCandidate) => {
       cause: lastVerifyError
     });
   }
+  if (lastDependencyError !== void 0) {
+    const message = lastDependencyError instanceof Error ? lastDependencyError.message : "unknown error";
+    throw markDependencyMissing(
+      new Error(`candidate log verification could not complete: ${message}`, {
+        cause: lastDependencyError
+      })
+    );
+  }
   return {
     outcome: "unreachable",
     entries: [],
@@ -234,11 +249,13 @@ var createIndexQueries = (relays, fetchImpl) => {
 // src/resolvers.ts
 import {
   decodeMultikey,
+  IdentityStateNoSeenKeysError,
   verifyContentChain,
   verifyContentExtensionFromTrustedState,
   verifyIdentityChain,
   verifyIdentityExtensionFromTrustedState
 } from "@metalabel/dfos-protocol/chain";
+import { CredentialVerificationError } from "@metalabel/dfos-protocol/credentials";
 import { decodeJwsUnsafe } from "@metalabel/dfos-protocol/crypto";
 var DID_PREFIX = "did:dfos";
 var cacheKey = (kind, id) => `${kind}:${id}`;
@@ -292,6 +309,8 @@ var keyBytesFor = (state, keyId) => {
   );
   return key ? decodeMultikey(key.publicKeyMultibase).keyBytes : null;
 };
+var NoStateAsOfError = class extends CredentialVerificationError {
+};
 var createResolvers = (deps) => {
   const relaysFor = (o) => normalizeRelays(o?.relays ?? deps.relays);
   const getIdentityChain = async (did, options) => {
@@ -323,17 +342,28 @@ var createResolvers = (deps) => {
       let headCID = cached.headCID;
       let lastCreatedAt = cached.lastCreatedAt;
       const log = [...cached.log];
-      for (const entry of entries.slice(cached.log.length)) {
-        const r = await verifyIdentityExtensionFromTrustedState({
-          currentState: state,
-          headCID,
-          lastCreatedAt,
-          newOp: entry.jwsToken
-        });
-        state = r.state;
-        headCID = r.operationCID;
-        lastCreatedAt = r.createdAt;
-        log.push(entry.jwsToken);
+      try {
+        for (const entry of entries.slice(cached.log.length)) {
+          const r = await verifyIdentityExtensionFromTrustedState({
+            currentState: state,
+            headCID,
+            lastCreatedAt,
+            newOp: entry.jwsToken
+          });
+          state = r.state;
+          headCID = r.operationCID;
+          lastCreatedAt = r.createdAt;
+          log.push(entry.jwsToken);
+        }
+      } catch (e) {
+        if (!(e instanceof IdentityStateNoSeenKeysError)) throw e;
+        const full = entries.map((entry) => entry.jwsToken);
+        const replayed = await verifyIdentityChain({ didPrefix: DID_PREFIX, log: full });
+        if (replayed.did !== did) {
+          throw new Error(`relay served a mismatched identity: asked ${did}, got ${replayed.did}`);
+        }
+        const last = opMeta(full[full.length - 1]);
+        return { state: replayed, log: full, headCID: last.cid, lastCreatedAt: last.createdAt };
       }
       return { state, log, headCID, lastCreatedAt };
     };
@@ -375,13 +405,18 @@ var createResolvers = (deps) => {
     const { state, log } = resolution;
     const last = log[log.length - 1];
     if (basis === void 0 || last === void 0 || opMeta(last).createdAt <= basis) return state;
+    const first = log[0];
+    if (first !== void 0 && basis < opMeta(first).createdAt) {
+      throw new NoStateAsOfError(`identity has no state as of ${basis}`);
+    }
     const asOf = await verifyIdentityChain({ didPrefix: DID_PREFIX, log, asOf: basis });
-    return { ...asOf, isDeleted: state.isDeleted };
+    return { ...asOf, isDeleted: state.isDeleted, basisDeterminate: true };
   };
   const resolveIdentity = async (did, basis) => {
     try {
       return await stateAsOf(await getIdentityChain(did), basis);
-    } catch {
+    } catch (err) {
+      if (err instanceof NoStateAsOfError) throw err;
       return void 0;
     }
   };
@@ -506,12 +541,29 @@ var createResolvers = (deps) => {
 };
 
 // src/revocation.ts
+import { isDependencyMissing as isDependencyMissing2 } from "@metalabel/dfos-protocol";
 import { parseProtocolTimestampUnix, verifyRevocation } from "@metalabel/dfos-protocol/chain";
+import { CredentialVerificationError as CredentialVerificationError2 } from "@metalabel/dfos-protocol/credentials";
 import { REVOCATIONS_BASE_PATH } from "@metalabel/dfos-web-relay/peer-client";
+var unavailable = (why) => new Error(`revocation status unavailable: ${why}`);
+var KeyUnresolvableError = class extends Error {
+};
+var isResolverVerdict = (err) => err instanceof CredentialVerificationError2 && !isDependencyMissing2(err);
 var createRevocationChecker = (relays, fetchImpl, resolveKey) => {
   const relaySet = normalizeRelays(relays);
+  const guardedResolveKey = async (kid, basis) => {
+    try {
+      return await resolveKey(kid, basis);
+    } catch (err) {
+      if (isResolverVerdict(err)) throw err;
+      throw new KeyUnresolvableError(`could not resolve the revocation signing key ${kid}`, {
+        cause: err
+      });
+    }
+  };
   return async (issuerDID, credentialCID, asOfUnix) => {
     let answered = false;
+    let unresolvable;
     for (const url of relaySet) {
       let body = null;
       try {
@@ -532,17 +584,22 @@ var createRevocationChecker = (relays, fetchImpl, resolveKey) => {
       }
       if (!body?.revoked || !body.revocation) continue;
       try {
-        const verified = await verifyRevocation({ jwsToken: body.revocation, resolveKey });
+        const verified = await verifyRevocation({
+          jwsToken: body.revocation,
+          resolveKey: guardedResolveKey
+        });
         if (verified.did === issuerDID && verified.credentialCID === credentialCID) {
           if (asOfUnix === void 0 || asOfUnix <= 0) return true;
           const revokedAtUnix = parseProtocolTimestampUnix(verified.createdAt);
           if (revokedAtUnix === null || revokedAtUnix <= asOfUnix) return true;
           continue;
         }
-      } catch {
+      } catch (err) {
+        if (err instanceof KeyUnresolvableError) unresolvable = err;
       }
     }
-    if (!answered) throw new Error("revocation status unavailable: no relay answered");
+    if (!answered) throw unavailable("no relay answered");
+    if (unresolvable) throw unavailable(unresolvable.message);
     return false;
   };
 };

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

@@ -1,4 +1,4 @@
-import { S as Store } from './types-BbIEz7BN.js';
+import { S as Store } from './types-DClhQw33.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-BbIEz7BN.js';
+import { a as Client, V as VerifyResult } from './types-DClhQw33.js';
 import '@metalabel/dfos-protocol/credentials';
 import '@metalabel/dfos-web-relay/peer-client';
 
@@ -96,6 +96,16 @@ interface SiwdLoginRequestInput {
      * would describe something other than what was asked for.
      */
     scope: string;
+    /**
+     * Lock consent to a named set of places: `all`, or up to 31 distinct 31-char
+     * space ids. Absent, the user chooses at the consent screen.
+     *
+     * A host honors it only when `scope` names a space-level action, and refuses
+     * the request whole otherwise. The returned credential's `att` is the answer —
+     * consent MAY narrow the set, so read it rather than assuming the ask was
+     * honored whole.
+     */
+    spaces?: readonly string[] | 'all';
     /** Consent-screen prose. A host MAY decline to render it; see specs/INTEGRATIONS.md. */
     statement?: string;
     /**
@@ -177,8 +187,8 @@ interface SiwdLoginRequest {
  * client identity the tier is open and every scope is available.
  *
  * It also owns the WIRE PARAM NAMES (`challenge`, `redirect_uri`, `scope`,
- * `client_did`, and — via `createSiwdLoopbackLoginRequest` — `client_proof` and
- * `client_chain`) as their single source in this package. They are snake_case
+ * `spaces`, `client_did`, and — via `createSiwdLoopbackLoginRequest` —
+ * `client_proof` and `client_chain`) as their single source in this package. They are snake_case
  * on the wire and camelCase everywhere else, which is exactly the kind of seam
  * every hand-rolled RP re-implements and eventually gets wrong.
  *
@@ -329,6 +339,13 @@ interface SiwdLoopbackLoginRequestInput {
      * a credential to.
      */
     scope: string;
+    /**
+     * Lock consent to a named set of places: `all`, or up to 31 distinct 31-char
+     * space ids. Same rule as `SiwdLoginRequestInput.spaces` — the host honors it
+     * only when `scope` names a space-level action, and refuses the request whole
+     * otherwise.
+     */
+    spaces?: readonly string[] | 'all';
     /** 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). */

package/dist/siwd.js

@@ -122,6 +122,18 @@ var bareHostname = (url) => {
   const host = url.hostname.toLowerCase();
   return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
 };
+var SIWD_SPACE_ID_RE = /^[2346789acdefhknrtvz]{31}$/;
+var MAX_SIWD_SPACES = 31;
+var siwdSpacesParam = (spaces) => {
+  if (spaces === "all") return "all";
+  const malformed = !Array.isArray(spaces) || spaces.length === 0 || spaces.length > MAX_SIWD_SPACES || spaces.some((id) => typeof id !== "string" || !SIWD_SPACE_ID_RE.test(id)) || new Set(spaces).size !== spaces.length;
+  if (malformed) {
+    throw new Error(
+      "invalid SIWD login request: spaces must be 'all' or distinct 31-character space ids"
+    );
+  }
+  return spaces.join(",");
+};
 var parseUrlOrThrow = (value, field) => {
   try {
     return new URL(value);
@@ -138,6 +150,7 @@ var createSiwdLoginRequest = (input) => {
       "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 spaces = input.spaces !== void 0 ? siwdSpacesParam(input.spaces) : void 0;
   const { challenge, encoded, nonce } = createSiwdChallenge({
     domain: input.domain,
     ...input.statement !== void 0 ? { statement: input.statement } : {},
@@ -148,6 +161,9 @@ var createSiwdLoginRequest = (input) => {
   url.searchParams.set("challenge", encoded);
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("scope", input.scope);
+  if (spaces !== void 0) {
+    url.searchParams.set("spaces", spaces);
+  }
   if (input.clientDid !== void 0) {
     url.searchParams.set("client_did", input.clientDid);
   }
@@ -263,6 +279,7 @@ var createSiwdLoopbackLoginRequest = async (input) => {
     redirectUri: input.redirectUri,
     scope: input.scope,
     clientDid: input.client.did,
+    ...input.spaces !== void 0 ? { spaces: input.spaces } : {},
     ...input.statement !== void 0 ? { statement: input.statement } : {},
     ...input.did !== void 0 ? { did: input.did } : {},
     ...input.nonce !== void 0 ? { nonce: input.nonce } : {}

package/dist/store/index.d.ts

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

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

@@ -5,6 +5,12 @@ import { PeerClient } from '@metalabel/dfos-web-relay/peer-client';
 /** Head/as-of state; excludes the credit-claim projection. */
 type EffectiveIdentity = VerifiedIdentity & {
     readonly resolution?: 'effective';
+    /**
+     * True when no operation dated at or before the basis can still arrive and
+     * change this key state — the protocol's `ResolvedIdentity.basisDeterminate`,
+     * which decides whether a missing key is a verdict or a retryable miss.
+     */
+    basisDeterminate?: boolean;
 };
 /** Every key ever proved, including memberships absent from effective state. */
 type EverProvedIdentity = VerifiedIdentity & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.52.1",
+  "version": "0.54.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.52.1",
-    "@metalabel/dfos-web-relay": "^0.52.1"
+    "@metalabel/dfos-protocol": "^0.54.0",
+    "@metalabel/dfos-web-relay": "^0.54.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.52.1",
-    "@metalabel/dfos-web-relay": "0.52.1"
+    "@metalabel/dfos-protocol": "0.54.0",
+    "@metalabel/dfos-web-relay": "0.54.0"
   },
   "scripts": {
     "build": "tsup",