@metalabel/dfos-protocol 0.53.0 → 0.54.0

package/README.md

@@ -36,6 +36,12 @@ import { signKeyProof, verifyKeyProof } from '@metalabel/dfos-protocol/key-proof
 | `@metalabel/dfos-protocol/key-proof`   | KEY-PROOF envelopes — compose/sign and verify a challenge-bound proof that a candidate key is held      |
 | `@metalabel/dfos-protocol/fold`        | Canonical linearization and LWW-map folds for index documents                                           |
 
+## `api:` resources and the `jti` member
+
+An `api:` resource takes one of two forms: `api:<host>`, the whole API surface, and `api:<host>/spaces/<id>`, one space on it. A bare host is the ancestor of every space at that host, so a grant naming the host covers a space-addressed request while a space-scoped grant covers only its own space. `parseApiResource` and `apiResourceCovers` are that rule on its own; `isAttenuated` and `matchesResource` apply it. Every other resource type is exact byte equality, and a malformed `api:` id covers nothing — itself included.
+
+`jti` is the envelope's one registered additive member: a per-request unique string of at most `MAX_JTI_BYTES` UTF-8 bytes, emitted after the canonical members. Pass it typed to `signApiRequest` or `signApiIdentityRequest` (`generateJti()` mints one), set `requireJti` on a verifier to refuse a proof without it, and read the verified value back off the envelope to key a replay cache. A proof carrying none has the bytes it always had.
+
 ## Specifications
 
 | Document                                         | Description                                                                     |
@@ -62,6 +68,7 @@ The `examples/` directory contains deterministic reference fixtures that can be
 - `credential-write.json` — DFOS write credential (broad + content-narrowed)
 - `credential-read.json` — DFOS read credential
 - `identity-services.json` — genesis publishing a services set (relay locator + content/artifact anchors)
+- `api-resource-coverage.json` — the `api:` hierarchy's parse, coverage, attenuation, and matching rows, read by the TypeScript and Go suites alike
 
 ## License
 

package/dist/chain/index.d.ts

@@ -1,5 +1,5 @@
-import { I as IdentityOperation, v as Signer, x as VerifiedIdentity, S as ServiceEntry, c as ContentOperation, R as ResolvedIdentity, r as RevocationChecker, d as CountersignPayload, a as ArtifactPayload } from '../dfos-credential-j-kHtFvG.js';
-export { A as ARTIFACT_CID_ANCHOR_RE, C as CONTENT_ID_ANCHOR_RE, f as CreditClaimPayload, g as DeclaredKeyState, h as Iso8601, M as MAX_ARTIFACT_PAYLOAD_SIZE, j as MAX_CREDIT_CLAIM_SIZE, k as MAX_KEY_PROOFS, l as MAX_OPERATION_SIZE, m as MAX_SERVICES_ENTRIES, n as MAX_SERVICES_PAYLOAD_SIZE, o as MAX_SIGN_REQUEST_PAYLOAD_SIZE, p as MAX_SIGN_REQUEST_SIZE, q as MultikeyPublicKey, s as RevocationPayload, t as ServicesArray, u as SignRequestPayload, y as VoidKeyMembership, G as parseProtocolTimestampUnix } from '../dfos-credential-j-kHtFvG.js';
+import { I as IdentityOperation, v as Signer, x as VerifiedIdentity, S as ServiceEntry, c as ContentOperation, R as ResolvedIdentity, r as RevocationChecker, d as CountersignPayload, a as ArtifactPayload } from '../dfos-credential-DgT8XVTm.js';
+export { A as ARTIFACT_CID_ANCHOR_RE, C as CONTENT_ID_ANCHOR_RE, f as CreditClaimPayload, g as DeclaredKeyState, h as Iso8601, M as MAX_ARTIFACT_PAYLOAD_SIZE, j as MAX_CREDIT_CLAIM_SIZE, k as MAX_KEY_PROOFS, l as MAX_OPERATION_SIZE, m as MAX_SERVICES_ENTRIES, n as MAX_SERVICES_PAYLOAD_SIZE, o as MAX_SIGN_REQUEST_PAYLOAD_SIZE, p as MAX_SIGN_REQUEST_SIZE, q as MultikeyPublicKey, s as RevocationPayload, t as ServicesArray, u as SignRequestPayload, y as VoidKeyMembership, J as parseProtocolTimestampUnix } from '../dfos-credential-DgT8XVTm.js';
 import 'zod';
 
 /** Ed25519 public key multicodec value */

package/dist/chain/index.js

@@ -53,8 +53,8 @@ import {
   verifyIdentityExtensionFromTrustedState,
   verifyRevocation,
   verifySignRequest
-} from "../chunk-WBFWGQTS.js";
-import "../chunk-VEKRLXZ5.js";
+} from "../chunk-QIM3KZXZ.js";
+import "../chunk-RPA44ND4.js";
 import "../chunk-ISHAX5WN.js";
 import {
   ED25519_PRIV_MULTICODEC,

package/dist/{chunk-WBFWGQTS.js → chunk-QIM3KZXZ.js}

@@ -6,7 +6,7 @@ import {
   matchesResource,
   verifyDFOSCredential,
   verifyDelegationChain
-} from "./chunk-VEKRLXZ5.js";
+} from "./chunk-RPA44ND4.js";
 import {
   KEY_ADD_JWS_TYP,
   KEY_ROLES,

package/dist/{chunk-VEKRLXZ5.js → chunk-RPA44ND4.js}

@@ -43,6 +43,7 @@ var REQUEST_PROOF_JWS_TYP = "did:dfos:request-proof";
 var IDENTITY_PROOF_JWS_TYP = "did:dfos:identity-proof";
 var EMPTY_BODY_SHA256 = "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU";
 var MAX_REQUEST_PROOF_SIZE = 4096;
+var MAX_JTI_BYTES = 256;
 var DEFAULT_PROOF_WINDOW_SECONDS = 60;
 var DEFAULT_PROOF_SKEW_SECONDS = 60;
 var MAX_PROOF_FRESHNESS_SPAN_SECONDS = 300;
@@ -66,6 +67,27 @@ var CTL_OR_SPACE = /[\u0000-\u0020\u007f]/;
 var BASE64URL_32 = /^[A-Za-z0-9_-]{43}$/;
 var EXTRA_MEMBER_NAME = /^[A-Za-z0-9_.-]+$/;
 var CANONICAL_MEMBERS = /* @__PURE__ */ new Set(["method", "host", "path", "bodyHash", "credentialCID", "iat"]);
+var assertJtiBound = (jti, label) => {
+  if (jti === "" || encoder.encode(jti).length > MAX_JTI_BYTES) {
+    throw new Error(
+      `invalid ${label}: jti must be a non-empty string of at most ${MAX_JTI_BYTES} bytes`
+    );
+  }
+};
+var withJti = (extra, jti, label) => {
+  if (jti === void 0) return extra;
+  if (extra && "jti" in extra) {
+    throw new Error(`invalid ${label}: jti is named twice \u2014 pass it typed or in extraMembers`);
+  }
+  assertJtiBound(jti, label);
+  return { ...extra, jti };
+};
+var emittedExtraMembers = (parsed, extra, label) => canonicalExtraMembers(withJti(extra, parsed.jti, label), label);
+var generateJti = () => {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return base64urlEncode(bytes);
+};
 var assertNoLoneSurrogate = (value, field, label) => {
   if (LONE_SURROGATE.test(value)) {
     throw new Error(`invalid ${label}: ${field} must be well-formed Unicode`);
@@ -113,7 +135,26 @@ var validateProofPayload = (value, shape) => {
   if (typeof iat !== "number" || !Number.isSafeInteger(iat) || iat <= 0) {
     throw new Error(`invalid ${label}: iat must be a positive integer`);
   }
-  return shape.credentialed ? { method, host, path, bodyHash, credentialCID: raw["credentialCID"], iat } : { method, host, path, bodyHash, iat };
+  const rawJti = raw["jti"];
+  let jti;
+  if (rawJti !== void 0) {
+    if (typeof rawJti !== "string") {
+      throw new Error(
+        `invalid ${label}: jti must be a non-empty string of at most ${MAX_JTI_BYTES} bytes`
+      );
+    }
+    assertJtiBound(rawJti, label);
+    jti = rawJti;
+  }
+  return {
+    method,
+    host,
+    path,
+    bodyHash,
+    ...shape.credentialed ? { credentialCID: raw["credentialCID"] } : {},
+    iat,
+    ...jti !== void 0 ? { jti } : {}
+  };
 };
 var validateRequestProofPayload = (value) => {
   const parsed = validateProofPayload(value, REQUEST_PROOF_SHAPE);
@@ -123,7 +164,8 @@ var validateRequestProofPayload = (value) => {
     path: parsed.path,
     bodyHash: parsed.bodyHash,
     credentialCID: parsed.credentialCID,
-    iat: parsed.iat
+    iat: parsed.iat,
+    ...parsed.jti !== void 0 ? { jti: parsed.jti } : {}
   };
 };
 var validateIdentityProofPayload = (value) => {
@@ -133,7 +175,8 @@ var validateIdentityProofPayload = (value) => {
     host: parsed.host,
     path: parsed.path,
     bodyHash: parsed.bodyHash,
-    iat: parsed.iat
+    iat: parsed.iat,
+    ...parsed.jti !== void 0 ? { jti: parsed.jti } : {}
   };
 };
 var canonicalExtraMembers = (extra, label) => {
@@ -171,16 +214,22 @@ var proofPayloadObject = (parsed, shape, extra) => {
   for (const [name, value] of extra) out[name] = value;
   return out;
 };
-var apiRequestSigningInput = (payload, extraMembers) => proofSigningInput(
-  validateProofPayload(payload, REQUEST_PROOF_SHAPE),
-  REQUEST_PROOF_SHAPE,
-  canonicalExtraMembers(extraMembers, REQUEST_PROOF_SHAPE.label)
-);
-var apiIdentitySigningInput = (payload, extraMembers) => proofSigningInput(
-  validateProofPayload(payload, IDENTITY_PROOF_SHAPE),
-  IDENTITY_PROOF_SHAPE,
-  canonicalExtraMembers(extraMembers, IDENTITY_PROOF_SHAPE.label)
-);
+var apiRequestSigningInput = (payload, extraMembers) => {
+  const parsed = validateProofPayload(payload, REQUEST_PROOF_SHAPE);
+  return proofSigningInput(
+    parsed,
+    REQUEST_PROOF_SHAPE,
+    emittedExtraMembers(parsed, extraMembers, REQUEST_PROOF_SHAPE.label)
+  );
+};
+var apiIdentitySigningInput = (payload, extraMembers) => {
+  const parsed = validateProofPayload(payload, IDENTITY_PROOF_SHAPE);
+  return proofSigningInput(
+    parsed,
+    IDENTITY_PROOF_SHAPE,
+    emittedExtraMembers(parsed, extraMembers, IDENTITY_PROOF_SHAPE.label)
+  );
+};
 var sha256BodyHash = (body) => base64urlEncode(sha256(body));
 var parseDfosAuthorization = (header) => {
   if (!header) return null;
@@ -199,12 +248,13 @@ var signApiRequest = async (input) => {
     path: input.path,
     bodyHash: sha256BodyHash(input.body ?? EMPTY_BODY),
     credentialCID: input.credentialCID,
-    iat: input.iat ?? Math.floor(Date.now() / 1e3)
+    iat: input.iat ?? Math.floor(Date.now() / 1e3),
+    ...input.jti !== void 0 ? { jti: input.jti } : {}
   });
   if (!input.kid.includes("#")) {
     throw new Error("invalid request proof: kid must be a DID URL");
   }
-  const extra = canonicalExtraMembers(input.extraMembers, REQUEST_PROOF_SHAPE.label);
+  const extra = emittedExtraMembers(payload, input.extraMembers, REQUEST_PROOF_SHAPE.label);
   const proof = await createJws({
     header: { alg: "EdDSA", typ: REQUEST_PROOF_JWS_TYP, kid: input.kid },
     payload: proofPayloadObject(payload, REQUEST_PROOF_SHAPE, extra),
@@ -221,12 +271,13 @@ var signApiIdentityRequest = async (input) => {
     host: input.host,
     path: input.path,
     bodyHash: sha256BodyHash(input.body ?? EMPTY_BODY),
-    iat: input.iat ?? Math.floor(Date.now() / 1e3)
+    iat: input.iat ?? Math.floor(Date.now() / 1e3),
+    ...input.jti !== void 0 ? { jti: input.jti } : {}
   });
   if (!input.kid.includes("#")) {
     throw new Error("invalid identity proof: kid must be a DID URL");
   }
-  const extra = canonicalExtraMembers(input.extraMembers, IDENTITY_PROOF_SHAPE.label);
+  const extra = emittedExtraMembers(payload, input.extraMembers, IDENTITY_PROOF_SHAPE.label);
   const proof = await createJws({
     header: { alg: "EdDSA", typ: IDENTITY_PROOF_JWS_TYP, kid: input.kid },
     payload: proofPayloadObject(payload, IDENTITY_PROOF_SHAPE, extra),
@@ -247,7 +298,7 @@ var buildApiIdentityHeaders = (input) => ({
 var ApiRequestVerifyError = class extends Error {
   reason;
   phase;
-  /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid, 503 unverifiable, 500 config. */
+  /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid or uncovered, 409 replayed, 503 unverifiable, 500 config. */
   status;
   constructor(reason, phase, status, message) {
     super(message);
@@ -258,6 +309,8 @@ var ApiRequestVerifyError = class extends Error {
   }
 };
 var invalidProof = (message) => new ApiRequestVerifyError("invalid", "proof", 401, message);
+var replayedProof = (message) => new ApiRequestVerifyError("replayed", "proof", 409, message);
+var uncoveredProof = (message) => new ApiRequestVerifyError("uncovered", "credential", 403, message);
 var unverifiableProof = (message) => new ApiRequestVerifyError("unverifiable", "proof", 503, message);
 var misconfiguredProof = (message) => new ApiRequestVerifyError("config", "config", 500, message);
 var assertProofVerifierConfig = (input) => {
@@ -319,6 +372,9 @@ var verifyProofEnvelope = async (input, shape, resolvePresenter) => {
   } catch (err) {
     throw invalidProof(err instanceof Error ? err.message : `invalid ${shape.label} payload`);
   }
+  if (input.requireJti === true && payload.jti === void 0) {
+    throw invalidProof(`invalid ${shape.label}: jti is required on this route`);
+  }
   const now = Math.floor((input.now ? input.now() : Date.now()) / 1e3);
   if (now - payload.iat > window) throw invalidProof(`${shape.label} is stale`);
   if (payload.iat - now > skew) {
@@ -362,7 +418,15 @@ var verifyProofEnvelope = async (input, shape, resolvePresenter) => {
   } catch (err) {
     throw invalidProof(err instanceof Error ? err.message : `invalid ${shape.label} signature`);
   }
-  return { payload, rawPayload, presenterDID, kid, now };
+  return {
+    payload,
+    rawPayload,
+    presenterDID,
+    kid,
+    now,
+    ...payload.jti !== void 0 ? { jti: payload.jti } : {},
+    ...key.roles !== void 0 ? { keyRoles: key.roles } : {}
+  };
 };
 var verifyIdentityProofEnvelope = (input, resolvePresenter) => verifyProofEnvelope(input, IDENTITY_PROOF_SHAPE, resolvePresenter);
 var verifyRequestProofEnvelope = (input, resolvePresenter) => verifyProofEnvelope(input, REQUEST_PROOF_SHAPE, resolvePresenter);
@@ -538,6 +602,26 @@ var parseResource = (resource) => {
   if (colonIdx < 0) return null;
   return { type: resource.substring(0, colonIdx), id: resource.substring(colonIdx + 1) };
 };
+var SPACE_ID_RE = /^[2346789acdefhknrtvz]{31}$/;
+var parseApiResource = (resource) => {
+  const parsed = parseResource(resource);
+  if (!parsed || parsed.type !== "api") return null;
+  const slash = parsed.id.indexOf("/");
+  if (slash < 0) return parsed.id === "" ? null : { host: parsed.id };
+  const host = parsed.id.substring(0, slash);
+  if (host === "") return null;
+  const child = parsed.id.substring(slash + 1);
+  if (!child.startsWith("spaces/")) return null;
+  const spaceId = child.substring("spaces/".length);
+  if (!SPACE_ID_RE.test(spaceId)) return null;
+  return { host, spaceId };
+};
+var apiResourceCovers = (entryResource, requiredResource) => {
+  const entry = parseApiResource(entryResource);
+  const required = parseApiResource(requiredResource);
+  if (!entry || !required || entry.host !== required.host) return false;
+  return entry.spaceId === void 0 || entry.spaceId === required.spaceId;
+};
 var ASCII_TRIM_RE = /^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g;
 var parseActions = (action) => new Set(
   action.split(",").map((a) => a.replace(ASCII_TRIM_RE, "")).filter((a) => a !== "")
@@ -563,6 +647,9 @@ var isAttenuated = (parentAtt, childAtt) => {
       if (childRes.type === "chain" && parentRes.type === "chain") {
         return childRes.id === parentRes.id;
       }
+      if (childRes.type === "api" && parentRes.type === "api") {
+        return apiResourceCovers(parentEntry.resource, childEntry.resource) || childEntry.resource === parentEntry.resource;
+      }
       if (childRes.type !== "chain" && parentRes.type !== "chain") {
         return childEntry.resource === parentEntry.resource;
       }
@@ -589,6 +676,10 @@ var matchesResource = async (att, resource, action) => {
     if (entryRes.type === "chain" && entryRes.id === "*" && requestedRes.type === "chain") {
       return true;
     }
+    if (entryRes.type === "api" || requestedRes.type === "api") {
+      if (apiResourceCovers(entry.resource, resource)) return true;
+      continue;
+    }
     if (entryRes.type === requestedRes.type && entryRes.id === requestedRes.id) {
       return true;
     }
@@ -623,11 +714,13 @@ export {
   IDENTITY_PROOF_JWS_TYP,
   EMPTY_BODY_SHA256,
   MAX_REQUEST_PROOF_SIZE,
+  MAX_JTI_BYTES,
   DEFAULT_PROOF_WINDOW_SECONDS,
   DEFAULT_PROOF_SKEW_SECONDS,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_BODY_BYTES,
   DFOS_AUTH_SCHEME,
+  generateJti,
   canonicalExtraMembers,
   apiRequestSigningInput,
   apiIdentitySigningInput,
@@ -639,6 +732,8 @@ export {
   buildApiIdentityHeaders,
   ApiRequestVerifyError,
   invalidProof,
+  replayedProof,
+  uncoveredProof,
   unverifiableProof,
   misconfiguredProof,
   assertProofVerifierConfig,
@@ -647,6 +742,8 @@ export {
   createDFOSCredential,
   verifyDFOSCredential,
   verifyDelegationChain,
+  parseApiResource,
+  apiResourceCovers,
   isAttenuated,
   matchesResource,
   decodeDFOSCredentialUnsafe,

package/dist/credentials/index.d.ts

@@ -1,4 +1,4 @@
-export { b as Attenuation, e as CredentialVerificationError, D as DFOSCredentialPayload, i as MAX_CREDENTIAL_SIZE, R as ResolvedIdentity, r as RevocationChecker, V as VerifiedDFOSCredential, w as VerifiedDelegationChain, z as createDFOSCredential, B as decodeDFOSCredentialUnsafe, E as isAttenuated, F as matchesResource, H as verifyDFOSCredential, J as verifyDelegationChain } from '../dfos-credential-j-kHtFvG.js';
+export { b as Attenuation, e as CredentialVerificationError, D as DFOSCredentialPayload, i as MAX_CREDENTIAL_SIZE, R as ResolvedIdentity, r as RevocationChecker, V as VerifiedDFOSCredential, w as VerifiedDelegationChain, z as apiResourceCovers, B as createDFOSCredential, E as decodeDFOSCredentialUnsafe, F as isAttenuated, G as matchesResource, H as parseApiResource, K as verifyDFOSCredential, L as verifyDelegationChain } from '../dfos-credential-DgT8XVTm.js';
 import 'zod';
 
 /**
@@ -27,6 +27,11 @@ declare const IDENTITY_PROOF_JWS_TYP = "did:dfos:identity-proof";
 declare const EMPTY_BODY_SHA256 = "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU";
 /** Size cap on the serialized proof token, checked BEFORE any decode. */
 declare const MAX_REQUEST_PROOF_SIZE = 4096;
+/**
+ * Cap on the `jti` member, in UTF-8 bytes. There is no floor: uniqueness is the
+ * member's job, and a verifier's replay cache is what enforces it.
+ */
+declare const MAX_JTI_BYTES = 256;
 /** RECOMMENDED acceptance window `W` — how old a proof may be, in seconds. */
 declare const DEFAULT_PROOF_WINDOW_SECONDS = 60;
 /** RECOMMENDED clock-skew allowance `S` — how forward-dated a proof may be. */
@@ -64,6 +69,11 @@ interface RequestProofPayload {
     credentialCID: string;
     /** Issued-at — unix seconds (positive integer). */
     iat: number;
+    /**
+     * The registered additive member: a per-request unique value, at most
+     * `MAX_JTI_BYTES` UTF-8 bytes. Emitted after `iat`, in the additive block.
+     */
+    jti?: string;
 }
 /**
  * The identity proof's payload: the request proof's five members MINUS
@@ -81,6 +91,11 @@ interface IdentityProofPayload {
     bodyHash: string;
     /** Issued-at — unix seconds (positive integer). */
     iat: number;
+    /**
+     * The registered additive member: a per-request unique value, at most
+     * `MAX_JTI_BYTES` UTF-8 bytes. Emitted after `iat`, in the additive block.
+     */
+    jti?: string;
 }
 /**
  * ADDITIVE MEMBERS, appended AFTER the canonical order.
@@ -108,7 +123,15 @@ interface ParsedProofPayload {
     bodyHash: string;
     credentialCID?: string;
     iat: number;
+    /** The registered additive member, when the proof carries one. */
+    jti?: string;
 }
+/**
+ * Mint a `jti`: 128 bits from the platform CSPRNG, unpadded base64url (22
+ * characters). Uniqueness is per (presenter DID, freshness window), which this
+ * much randomness makes a collision no deployment will observe.
+ */
+declare const generateJti: () => string;
 /**
  * Validate and normalize additive members into their canonical emission order:
  * lexicographic by name, after every canonical member. Returns `[]` for the
@@ -171,10 +194,17 @@ interface SignApiRequestInput {
     sign: (message: Uint8Array) => Promise<Uint8Array>;
     /** Issued-at override — unix seconds. Default `Math.floor(Date.now() / 1000)`. */
     iat?: number;
+    /**
+     * The registered additive member, per-request unique and at most
+     * `MAX_JTI_BYTES` bytes — required by a deployment that gates WRITES with this
+     * envelope (INTEGRATIONS.md, API security notes). `generateJti()` mints one.
+     * It emits the same bytes as `extraMembers: { jti }`, and naming it both ways
+     * throws.
+     */
+    jti?: string;
     /**
      * ADDITIVE members, appended after the canonical order in lexicographic name
-     * order. `{ jti }` is the registered one — required by a deployment that gates
-     * WRITES with this envelope (INTEGRATIONS.md, API security notes).
+     * order. `{ jti }` is the registered one, and has the typed field above.
      */
     extraMembers?: ProofExtraMembers;
 }
@@ -209,10 +239,17 @@ interface SignApiIdentityRequestInput {
     sign: (message: Uint8Array) => Promise<Uint8Array>;
     /** Issued-at override — unix seconds. Default `Math.floor(Date.now() / 1000)`. */
     iat?: number;
+    /**
+     * The registered additive member, per-request unique and at most
+     * `MAX_JTI_BYTES` bytes. A WRITE-SHAPED surface — relay ingestion, blob
+     * upload — REQUIRES it (INTEGRATIONS.md, API security notes). `generateJti()`
+     * mints one. It emits the same bytes as `extraMembers: { jti }`, and naming it
+     * both ways throws.
+     */
+    jti?: string;
     /**
      * ADDITIVE members, appended after the canonical order in lexicographic name
-     * order. `{ jti }` is the registered one, and a WRITE-SHAPED surface — relay
-     * ingestion, blob upload — REQUIRES it (INTEGRATIONS.md, API security notes).
+     * order. `{ jti }` is the registered one, and has the typed field above.
      */
     extraMembers?: ProofExtraMembers;
 }
@@ -261,13 +298,21 @@ declare const buildApiIdentityHeaders: (input: {
  * The verdict class. Branch on `reason`, never on message text.
  *
  * - `invalid` — checked and failed.
+ * - `replayed` — checked, VALID, and already spent: this `jti` was seen inside
+ *   the proof's own freshness window. Its own verdict rather than an `invalid`
+ *   one because the caller's answer differs — re-read state, do not re-sign the
+ *   same request.
+ * - `uncovered` — the credential is VALID and simply does not reach this route's
+ *   resource and action. Distinct from `invalid` because nothing is wrong with
+ *   the artifact: a route offering optional authentication serves its anonymous
+ *   projection on an `uncovered` verdict, and still refuses an `invalid` one.
  * - `unverifiable` — could not check (an unresolvable presenter, an unreachable
  *   revocation source). A transient resolution failure is the server's
  *   condition, not the caller's.
  * - `config` — the DEPLOYMENT is misconfigured (a `W + S` over the 300-second
  *   ceiling, or an empty required action). Not a judgment about the artifact.
  */
-type RequestProofFailureReason = 'invalid' | 'unverifiable' | 'config';
+type RequestProofFailureReason = 'invalid' | 'replayed' | 'uncovered' | 'unverifiable' | 'config';
 /**
  * The verification phase a failure arose in. Load-bearing for HTTP mapping: an
  * `invalid` proof-layer failure is a 401 (with a `WWW-Authenticate: DFOS`
@@ -279,12 +324,26 @@ type RequestProofFailurePhase = 'proof' | 'credential' | 'config';
 declare class ApiRequestVerifyError extends Error {
     readonly reason: RequestProofFailureReason;
     readonly phase: RequestProofFailurePhase;
-    /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid, 503 unverifiable, 500 config. */
+    /** Recommended HTTP status: 401 proof-invalid, 403 credential-invalid or uncovered, 409 replayed, 503 unverifiable, 500 config. */
     readonly status: number;
     constructor(reason: RequestProofFailureReason, phase: RequestProofFailurePhase, status: number, message: string);
 }
 /** invalid, proof phase → 401. */
 declare const invalidProof: (message: string) => ApiRequestVerifyError;
+/**
+ * replayed, proof phase → 409. The proof verified; its `jti` was already spent.
+ * The cache belongs to the deployment, so this is the constructor every consumer
+ * classifies a replay with rather than a status each one picks.
+ */
+declare const replayedProof: (message: string) => ApiRequestVerifyError;
+/**
+ * uncovered, credential phase → 403. The credential verified and simply does not
+ * reach this route's resource and action. Its own verdict because a route
+ * offering optional authentication answers it with the anonymous projection a
+ * caller presenting nothing would get — a credential only ever ADDS — while an
+ * `invalid` credential is refused outright.
+ */
+declare const uncoveredProof: (message: string) => ApiRequestVerifyError;
 /** unverifiable, proof phase → 503. */
 declare const unverifiableProof: (message: string) => ApiRequestVerifyError;
 /** the DEPLOYMENT is misconfigured → 500. Never a judgment about the artifact. */
@@ -301,10 +360,16 @@ declare const misconfiguredProof: (message: string) => ApiRequestVerifyError;
 interface ProofPresenterState {
     /** Current-state deletion. A deleted presenter's proofs are INVALID (401). */
     isDeleted: boolean;
-    /** Current keys, any role. */
+    /**
+     * Current keys, any role. `roles` is OPTIONAL and the resolver's to supply: a
+     * key may hold several, and a deployment gating writes decides for itself
+     * which role may sign. The verifier never reads it — it hands the matched
+     * key's roles back on the verified envelope.
+     */
     keys: readonly {
         id: string;
         publicKeyMultibase: string;
+        roles?: readonly ('auth' | 'assert' | 'controller')[];
     }[];
 }
 /**
@@ -345,6 +410,12 @@ interface ProofEnvelopeInput {
     skewSeconds?: number;
     /** Clock injection (unix ms). Default `Date.now()`. */
     now?: () => number;
+    /**
+     * Require the registered `jti` member. Default false. A verifier gating WRITES
+     * sets it on every write-shaped route and records the value in its own replay
+     * cache; a read-shaped route may ignore the member entirely.
+     */
+    requireJti?: boolean;
 }
 /**
  * INTEGRATIONS.md, Verification algorithm step 4's freshness configuration,
@@ -372,11 +443,10 @@ interface VerifiedProofEnvelope {
     /**
      * The DECODED payload object, unknown members included.
      *
-     * ADDITIVE MEMBERS ARE READ FROM HERE, at the consuming layer, AFTER
-     * verification — the signature already covers them, and the canonical member
-     * set stays closed. `jti` is the case this exists for: the envelope verifier
-     * ignores it per MUST-ignore-unknown, and a write-gating deployment reads it
-     * off this object and applies its own replay discipline.
+     * UNREGISTERED ADDITIVE MEMBERS ARE READ FROM HERE, at the consuming layer,
+     * AFTER verification — the signature already covers them, and the canonical
+     * member set stays closed. The registered `jti` has its own field above; every
+     * other additive member is ignored per MUST-ignore-unknown and survives here.
      */
     rawPayload: Record<string, unknown>;
     /** THE PRINCIPAL — the `kid`'s DID. */
@@ -385,6 +455,17 @@ interface VerifiedProofEnvelope {
     kid: string;
     /** The integer unix seconds the freshness check used. */
     now: number;
+    /**
+     * The registered `jti`, when the proof carried one — the value a write-gating
+     * deployment records in its replay cache, keyed with `presenterDID`.
+     */
+    jti?: string;
+    /**
+     * The matched key's roles, when the resolver supplied them. A deployment
+     * gating writes with an identity proof applies its own rule here: a key whose
+     * only effective role is `controller` should not stand for a write.
+     */
+    keyRoles?: readonly ('auth' | 'assert' | 'controller')[];
 }
 /**
  * Verify an IDENTITY proof's envelope — for this artifact steps 1–7 ARE the whole
@@ -406,4 +487,4 @@ declare const verifyIdentityProofEnvelope: (input: ProofEnvelopeInput, resolvePr
  */
 declare const verifyRequestProofEnvelope: (input: ProofEnvelopeInput, resolvePresenter: ResolveProofPresenter) => Promise<VerifiedProofEnvelope>;
 
-export { ApiRequestVerifyError, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, DFOS_AUTH_SCHEME, EMPTY_BODY_SHA256, IDENTITY_PROOF_JWS_TYP, type IdentityProofPayload, MAX_BODY_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, type ParsedProofPayload, type ProofEnvelopeInput, type ProofExtraMembers, type ProofPresenterState, REQUEST_PROOF_JWS_TYP, type RequestProofFailurePhase, type RequestProofFailureReason, type RequestProofPayload, type ResolveProofPresenter, type SignApiIdentityRequestInput, type SignApiRequestInput, type VerifiedProofEnvelope, apiIdentitySigningInput, apiRequestSigningInput, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, canonicalExtraMembers, invalidProof, misconfiguredProof, parseDfosAuthorization, sha256BodyHash, signApiIdentityRequest, signApiRequest, unverifiableProof, verifyIdentityProofEnvelope, verifyRequestProofEnvelope };
+export { ApiRequestVerifyError, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, DFOS_AUTH_SCHEME, EMPTY_BODY_SHA256, IDENTITY_PROOF_JWS_TYP, type IdentityProofPayload, MAX_BODY_BYTES, MAX_JTI_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, type ParsedProofPayload, type ProofEnvelopeInput, type ProofExtraMembers, type ProofPresenterState, REQUEST_PROOF_JWS_TYP, type RequestProofFailurePhase, type RequestProofFailureReason, type RequestProofPayload, type ResolveProofPresenter, type SignApiIdentityRequestInput, type SignApiRequestInput, type VerifiedProofEnvelope, apiIdentitySigningInput, apiRequestSigningInput, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, canonicalExtraMembers, generateJti, invalidProof, misconfiguredProof, parseDfosAuthorization, replayedProof, sha256BodyHash, signApiIdentityRequest, signApiRequest, uncoveredProof, unverifiableProof, verifyIdentityProofEnvelope, verifyRequestProofEnvelope };

package/dist/credentials/index.js

@@ -10,31 +10,37 @@ import {
   IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
+  MAX_JTI_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
   REQUEST_PROOF_JWS_TYP,
   apiIdentitySigningInput,
   apiRequestSigningInput,
+  apiResourceCovers,
   assertProofVerifierConfig,
   buildApiAuthHeaders,
   buildApiIdentityHeaders,
   canonicalExtraMembers,
   createDFOSCredential,
   decodeDFOSCredentialUnsafe,
+  generateJti,
   invalidProof,
   isAttenuated,
   matchesResource,
   misconfiguredProof,
+  parseApiResource,
   parseDfosAuthorization,
+  replayedProof,
   sha256BodyHash,
   signApiIdentityRequest,
   signApiRequest,
+  uncoveredProof,
   unverifiableProof,
   verifyDFOSCredential,
   verifyDelegationChain,
   verifyIdentityProofEnvelope,
   verifyRequestProofEnvelope
-} from "../chunk-VEKRLXZ5.js";
+} from "../chunk-RPA44ND4.js";
 import "../chunk-F7RHI2CK.js";
 import "../chunk-NUIIVAZ3.js";
 export {
@@ -49,25 +55,31 @@ export {
   IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
+  MAX_JTI_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
   REQUEST_PROOF_JWS_TYP,
   apiIdentitySigningInput,
   apiRequestSigningInput,
+  apiResourceCovers,
   assertProofVerifierConfig,
   buildApiAuthHeaders,
   buildApiIdentityHeaders,
   canonicalExtraMembers,
   createDFOSCredential,
   decodeDFOSCredentialUnsafe,
+  generateJti,
   invalidProof,
   isAttenuated,
   matchesResource,
   misconfiguredProof,
+  parseApiResource,
   parseDfosAuthorization,
+  replayedProof,
   sha256BodyHash,
   signApiIdentityRequest,
   signApiRequest,
+  uncoveredProof,
   unverifiableProof,
   verifyDFOSCredential,
   verifyDelegationChain,

package/dist/{dfos-credential-j-kHtFvG.d.ts → dfos-credential-DgT8XVTm.d.ts}

@@ -648,6 +648,26 @@ declare const verifyDelegationChain: (credential: VerifiedDFOSCredential, option
      */
     nowUnix?: number;
 }) => Promise<VerifiedDelegationChain>;
+/**
+ * Parse an `api:` resource into its host and, when present, its space id.
+ * Returns `null` for any other resource type and for a malformed `api:` id —
+ * `null` IS the malformed verdict, and a malformed resource covers nothing.
+ *
+ * Two forms are well-formed and no others: `api:<host>` with a non-empty host
+ * carrying no `/`, and `api:<host>/spaces/<id>`. The id half splits on the FIRST
+ * `/`, so a host keeps its port and anything past `spaces/<id>` is malformed.
+ */
+declare const parseApiResource: (resource: string) => {
+    host: string;
+    spaceId?: string;
+} | null;
+/**
+ * Whether one `api:` resource covers another: same host, and either the entry is
+ * the bare host (the registered ancestor of every space on it) or the two name
+ * the same space. False when either side is malformed or is not `api:` —
+ * coverage never crosses hosts and never crosses resource types.
+ */
+declare const apiResourceCovers: (entryResource: string, requiredResource: string) => boolean;
 /**
  * Check if `childAtt` is a valid attenuation of `parentAtt`
  *
@@ -658,11 +678,14 @@ declare const verifyDelegationChain: (credential: VerifiedDFOSCredential, option
  * - `chain:X` covered by `chain:*` (narrowing from wildcard — valid)
  * - `chain:*` covered by `chain:*` (exact match)
  * - `chain:*` NOT covered by `chain:X` (widening — invalid)
- * - Non-`chain` types (`mailbox:<id>`, and any form a future capability
- *   registers): exact byte equality of the full resource string, nothing else.
- *   The wildcard is a `chain:`-only concept — a literal `*` id in any other
- *   type is an ordinary id covering only itself — and coverage never crosses
- *   resource types. See CREDENTIALS.md "Resource Types".
+ * - `api:<host>/spaces/<id>` covered by `api:<host>` (narrowing onto one space)
+ *   or by the same child. A MALFORMED `api:` id narrows only from a
+ *   byte-identical parent, under the rule below — a bare host does not carry it.
+ * - Other types (`mailbox:<id>`, and any form a future capability registers):
+ *   exact byte equality of the full resource string, nothing else. The wildcard
+ *   is a `chain:`-only concept — a literal `*` id in any other type is an
+ *   ordinary id covering only itself — and coverage never crosses resource
+ *   types. See CREDENTIALS.md "Resource Types".
  * - Actions: child action set must be a subset of parent action set
  */
 declare const isAttenuated: (parentAtt: Attenuation[], childAtt: Attenuation[]) => boolean;
@@ -670,7 +693,14 @@ declare const isAttenuated: (parentAtt: Attenuation[], childAtt: Attenuation[])
  * Check if an `att` array covers a requested resource
  *
  * Used at the relay to determine if a credential authorizes access to a
- * specific content chain.
+ * specific content chain, and by an API verifier to decide whether a grant
+ * reaches the route's resource.
+ *
+ * `chain:*` covers any `chain:` request; an `api:` entry covers an `api:`
+ * request under the host/space hierarchy; every other form is exact byte
+ * equality. A malformed `api:` resource covers nothing and is covered by
+ * nothing, itself included — a resource a verifier cannot parse must not
+ * authorize a request. Every entry is scanned, so any one of them may cover.
  */
 declare const matchesResource: (att: Attenuation[], resource: string, action: string) => Promise<boolean>;
 /**
@@ -691,4 +721,4 @@ declare class CredentialVerificationError extends Error {
     constructor(message: string);
 }
 
-export { ARTIFACT_CID_ANCHOR_RE as A, decodeDFOSCredentialUnsafe as B, CONTENT_ID_ANCHOR_RE as C, DFOSCredentialPayload as D, isAttenuated as E, matchesResource as F, parseProtocolTimestampUnix as G, verifyDFOSCredential as H, IdentityOperation as I, verifyDelegationChain as J, MAX_ARTIFACT_PAYLOAD_SIZE as M, type ResolvedIdentity as R, ServiceEntry as S, type VerifiedDFOSCredential as V, ArtifactPayload as a, Attenuation as b, ContentOperation as c, CountersignPayload as d, CredentialVerificationError as e, CreditClaimPayload as f, DeclaredKeyState as g, Iso8601 as h, MAX_CREDENTIAL_SIZE as i, MAX_CREDIT_CLAIM_SIZE as j, MAX_KEY_PROOFS as k, MAX_OPERATION_SIZE as l, MAX_SERVICES_ENTRIES as m, MAX_SERVICES_PAYLOAD_SIZE as n, MAX_SIGN_REQUEST_PAYLOAD_SIZE as o, MAX_SIGN_REQUEST_SIZE as p, MultikeyPublicKey as q, type RevocationChecker as r, RevocationPayload as s, ServicesArray as t, SignRequestPayload as u, type Signer as v, type VerifiedDelegationChain as w, VerifiedIdentity as x, VoidKeyMembership as y, createDFOSCredential as z };
+export { ARTIFACT_CID_ANCHOR_RE as A, createDFOSCredential as B, CONTENT_ID_ANCHOR_RE as C, DFOSCredentialPayload as D, decodeDFOSCredentialUnsafe as E, isAttenuated as F, matchesResource as G, parseApiResource as H, IdentityOperation as I, parseProtocolTimestampUnix as J, verifyDFOSCredential as K, verifyDelegationChain as L, MAX_ARTIFACT_PAYLOAD_SIZE as M, type ResolvedIdentity as R, ServiceEntry as S, type VerifiedDFOSCredential as V, ArtifactPayload as a, Attenuation as b, ContentOperation as c, CountersignPayload as d, CredentialVerificationError as e, CreditClaimPayload as f, DeclaredKeyState as g, Iso8601 as h, MAX_CREDENTIAL_SIZE as i, MAX_CREDIT_CLAIM_SIZE as j, MAX_KEY_PROOFS as k, MAX_OPERATION_SIZE as l, MAX_SERVICES_ENTRIES as m, MAX_SERVICES_PAYLOAD_SIZE as n, MAX_SIGN_REQUEST_PAYLOAD_SIZE as o, MAX_SIGN_REQUEST_SIZE as p, MultikeyPublicKey as q, type RevocationChecker as r, RevocationPayload as s, ServicesArray as t, SignRequestPayload as u, type Signer as v, type VerifiedDelegationChain as w, VerifiedIdentity as x, VoidKeyMembership as y, apiResourceCovers as z };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { JwsHeader, JwsVerificationError, JwtClaims, JwtCreateOptions, JwtHeader, JwtVerificationError, JwtVerifyOptions, PrefixedID, assertCanonicalJsonText, assertJwsProfile, base64urlDecode, base64urlEncode, createJws, createJwt, createNewEd25519Keypair, dagCborCanonicalEncode, decodeJwsUnsafe, decodeJwtUnsafe, generateId, generateIdNoPrefix, importEd25519Keypair, isCanonicallyEqual, isValidEd25519Signature, isValidId, normalizedId, parseDagCborCID, sha256, signPayloadEd25519, verifyJws, verifyJwt } from './crypto/index.js';
-export { A as ARTIFACT_CID_ANCHOR_RE, a as ArtifactPayload, b as Attenuation, C as CONTENT_ID_ANCHOR_RE, c as ContentOperation, d as CountersignPayload, e as CredentialVerificationError, f as CreditClaimPayload, D as DFOSCredentialPayload, g as DeclaredKeyState, I as IdentityOperation, h as Iso8601, M as MAX_ARTIFACT_PAYLOAD_SIZE, i as MAX_CREDENTIAL_SIZE, j as MAX_CREDIT_CLAIM_SIZE, k as MAX_KEY_PROOFS, l as MAX_OPERATION_SIZE, m as MAX_SERVICES_ENTRIES, n as MAX_SERVICES_PAYLOAD_SIZE, o as MAX_SIGN_REQUEST_PAYLOAD_SIZE, p as MAX_SIGN_REQUEST_SIZE, q as MultikeyPublicKey, R as ResolvedIdentity, r as RevocationChecker, s as RevocationPayload, S as ServiceEntry, t as ServicesArray, u as SignRequestPayload, v as Signer, V as VerifiedDFOSCredential, w as VerifiedDelegationChain, x as VerifiedIdentity, y as VoidKeyMembership, z as createDFOSCredential, B as decodeDFOSCredentialUnsafe, E as isAttenuated, F as matchesResource, G as parseProtocolTimestampUnix, H as verifyDFOSCredential, J as verifyDelegationChain } from './dfos-credential-j-kHtFvG.js';
+export { A as ARTIFACT_CID_ANCHOR_RE, a as ArtifactPayload, b as Attenuation, C as CONTENT_ID_ANCHOR_RE, c as ContentOperation, d as CountersignPayload, e as CredentialVerificationError, f as CreditClaimPayload, D as DFOSCredentialPayload, g as DeclaredKeyState, I as IdentityOperation, h as Iso8601, M as MAX_ARTIFACT_PAYLOAD_SIZE, i as MAX_CREDENTIAL_SIZE, j as MAX_CREDIT_CLAIM_SIZE, k as MAX_KEY_PROOFS, l as MAX_OPERATION_SIZE, m as MAX_SERVICES_ENTRIES, n as MAX_SERVICES_PAYLOAD_SIZE, o as MAX_SIGN_REQUEST_PAYLOAD_SIZE, p as MAX_SIGN_REQUEST_SIZE, q as MultikeyPublicKey, R as ResolvedIdentity, r as RevocationChecker, s as RevocationPayload, S as ServiceEntry, t as ServicesArray, u as SignRequestPayload, v as Signer, V as VerifiedDFOSCredential, w as VerifiedDelegationChain, x as VerifiedIdentity, y as VoidKeyMembership, z as apiResourceCovers, B as createDFOSCredential, E as decodeDFOSCredentialUnsafe, F as isAttenuated, G as matchesResource, H as parseApiResource, J as parseProtocolTimestampUnix, K as verifyDFOSCredential, L as verifyDelegationChain } from './dfos-credential-DgT8XVTm.js';
 export { AnchorKind, CreditClaimFailureReason, CreditClaimVerifyError, CreditEntry, CreditEntryState, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityStateNoSeenKeysError, RECOGNIZED_SERVICE_TYPES, SignRequestFailureReason, SignRequestVerifyError, VerifiedArtifact, VerifiedContentChain, VerifiedCountersignature, VerifiedCreditClaim, VerifiedCreditEntry, VerifiedRevocation, VerifiedSignRequest, anchorsByLabel, assertCanonicalSignRequestPayload, assertServicesWithinCap, buildSignRequest, classifyAnchor, decodeEd25519PublicMultikey, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, isRecognizedServiceType, relayEndpoints, signArtifact, signContentOperation, signCountersignature, signCreditClaim, signIdentityOperation, signRevocation, verifyArtifact, verifyContentChain, verifyContentExtensionFromTrustedState, verifyCountersignature, verifyCreditClaim, verifyCreditEntry, verifyIdentityChain, verifyIdentityExtensionFromTrustedState, verifyRevocation, verifySignRequest } from './chain/index.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_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, ParsedProofPayload, ProofEnvelopeInput, ProofExtraMembers, ProofPresenterState, REQUEST_PROOF_JWS_TYP, RequestProofFailurePhase, RequestProofFailureReason, RequestProofPayload, ResolveProofPresenter, SignApiIdentityRequestInput, SignApiRequestInput, VerifiedProofEnvelope, apiIdentitySigningInput, apiRequestSigningInput, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, canonicalExtraMembers, invalidProof, misconfiguredProof, parseDfosAuthorization, sha256BodyHash, signApiIdentityRequest, signApiRequest, unverifiableProof, verifyIdentityProofEnvelope, verifyRequestProofEnvelope } from './credentials/index.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, ParsedProofPayload, ProofEnvelopeInput, ProofExtraMembers, ProofPresenterState, REQUEST_PROOF_JWS_TYP, RequestProofFailurePhase, RequestProofFailureReason, RequestProofPayload, ResolveProofPresenter, SignApiIdentityRequestInput, SignApiRequestInput, VerifiedProofEnvelope, apiIdentitySigningInput, apiRequestSigningInput, assertProofVerifierConfig, buildApiAuthHeaders, buildApiIdentityHeaders, canonicalExtraMembers, generateJti, invalidProof, misconfiguredProof, parseDfosAuthorization, replayedProof, sha256BodyHash, signApiIdentityRequest, signApiRequest, uncoveredProof, unverifiableProof, verifyIdentityProofEnvelope, verifyRequestProofEnvelope } from './credentials/index.js';
 export { DEFAULT_KEY_PROOF_SKEW_SECONDS, KEY_ADD_JWS_TYP, KEY_ROLES, KeyProofFailureReason, KeyProofPayload, KeyProofVerifyError, KeyRole, MAX_KEY_PROOF_SIZE, SignKeyProofInput, VerifiedKeyProof, VerifyChainKeyProofOptions, VerifyKeyProofOptions, isCanonicalRoleSet, keyProofSigningInput, keyWordFingerprint, parseRoleSet, roleSetCovers, serializeRoleSet, signKeyProof, unsafeKeyProofSubject, verifyChainKeyProof, verifyKeyProof } from './key-proof/index.js';
 export { FoldOperation, INDEX_V1_SCHEMA, IndexDelta, IndexDocument, IndexEntry, LwwDelta, OrderKey, byteCompare, compareHeadPreference, compareLinear, foldIndexV1, foldLwwMap, linearize } from './fold/index.js';
 import 'multiformats';

package/dist/index.js

@@ -53,7 +53,7 @@ import {
   verifyIdentityExtensionFromTrustedState,
   verifyRevocation,
   verifySignRequest
-} from "./chunk-WBFWGQTS.js";
+} from "./chunk-QIM3KZXZ.js";
 import {
   ApiRequestVerifyError,
   Attenuation,
@@ -66,11 +66,13 @@ import {
   IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
+  MAX_JTI_BYTES,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
   REQUEST_PROOF_JWS_TYP,
   apiIdentitySigningInput,
   apiRequestSigningInput,
+  apiResourceCovers,
   assertProofVerifierConfig,
   buildApiAuthHeaders,
   buildApiIdentityHeaders,
@@ -78,22 +80,26 @@ import {
   carryDependencyMissing,
   createDFOSCredential,
   decodeDFOSCredentialUnsafe,
+  generateJti,
   invalidProof,
   isAttenuated,
   isDependencyMissing,
   markDependencyMissing,
   matchesResource,
   misconfiguredProof,
+  parseApiResource,
   parseDfosAuthorization,
+  replayedProof,
   sha256BodyHash,
   signApiIdentityRequest,
   signApiRequest,
+  uncoveredProof,
   unverifiableProof,
   verifyDFOSCredential,
   verifyDelegationChain,
   verifyIdentityProofEnvelope,
   verifyRequestProofEnvelope
-} from "./chunk-VEKRLXZ5.js";
+} from "./chunk-RPA44ND4.js";
 import {
   DEFAULT_KEY_PROOF_SKEW_SECONDS,
   KEY_ADD_JWS_TYP,
@@ -187,6 +193,7 @@ export {
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
   MAX_CREDIT_CLAIM_SIZE,
+  MAX_JTI_BYTES,
   MAX_KEY_PROOFS,
   MAX_KEY_PROOF_SIZE,
   MAX_OPERATION_SIZE,
@@ -209,6 +216,7 @@ export {
   anchorsByLabel,
   apiIdentitySigningInput,
   apiRequestSigningInput,
+  apiResourceCovers,
   assertCanonicalJsonText,
   assertCanonicalSignRequestPayload,
   assertJwsProfile,
@@ -242,6 +250,7 @@ export {
   foldLwwMap,
   generateId,
   generateIdNoPrefix,
+  generateJti,
   importEd25519Keypair,
   invalidProof,
   isAttenuated,
@@ -258,11 +267,13 @@ export {
   matchesResource,
   misconfiguredProof,
   normalizedId,
+  parseApiResource,
   parseDagCborCID,
   parseDfosAuthorization,
   parseProtocolTimestampUnix,
   parseRoleSet,
   relayEndpoints,
+  replayedProof,
   roleSetCovers,
   serializeRoleSet,
   sha256,
@@ -277,6 +288,7 @@ export {
   signKeyProof,
   signPayloadEd25519,
   signRevocation,
+  uncoveredProof,
   unsafeKeyProofSubject,
   unverifiableProof,
   verifyArtifact,

package/examples/api-resource-coverage.json

@@ -0,0 +1,413 @@
+{
+  "description": "Reference vectors for the api: resource family — parse, coverage, attenuation, and request matching. Consumed by the TS credentials tests and the Go delegation tests (both twins read this file; neither inlines a row). Space ids are 31 characters of the did:dfos identifier alphabet [2346789acdefhknrtvz]; hosts are lowercase authorities, port included when non-default.",
+  "ids": {
+    "spaceA": "9ctvrdn9vedda7efetrhcdakfh4cr2k",
+    "spaceB": "cv7n8vkvr64cctf3294h9k4eanhff8z"
+  },
+  "parse": [
+    { "resource": "api:api.dfos.com", "valid": true, "host": "api.dfos.com", "spaceId": null },
+    {
+      "resource": "api:api.example.org:8443",
+      "valid": true,
+      "host": "api.example.org:8443",
+      "spaceId": null
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": true,
+      "host": "api.dfos.com",
+      "spaceId": "9ctvrdn9vedda7efetrhcdakfh4cr2k"
+    },
+    {
+      "resource": "api:api.example.org:8443/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": true,
+      "host": "api.example.org:8443",
+      "spaceId": "9ctvrdn9vedda7efetrhcdakfh4cr2k"
+    },
+    {
+      "resource": "api:*",
+      "valid": true,
+      "host": "*",
+      "spaceId": null,
+      "note": "an ordinary id covering only itself; never a served host"
+    },
+    { "resource": "api:", "valid": false, "note": "empty host" },
+    {
+      "resource": "api:/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": false,
+      "note": "empty host"
+    },
+    { "resource": "api:api.dfos.com/", "valid": false, "note": "trailing separator, no child" },
+    {
+      "resource": "api:api.dfos.com/spaces",
+      "valid": false,
+      "note": "child segment without an id"
+    },
+    { "resource": "api:api.dfos.com/spaces/", "valid": false, "note": "empty id" },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2",
+      "valid": false,
+      "note": "30-character id"
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k2",
+      "valid": false,
+      "note": "32-character id"
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2K",
+      "valid": false,
+      "note": "uppercase is outside the identifier alphabet"
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr1b",
+      "valid": false,
+      "note": "1 and b are outside the identifier alphabet"
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k/extra",
+      "valid": false,
+      "note": "the hierarchy is one level deep"
+    },
+    {
+      "resource": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": false,
+      "note": "topics is not a registered child"
+    },
+    {
+      "resource": "api:api.dfos.com/SPACES/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": false,
+      "note": "the child segment is lowercase"
+    },
+    {
+      "resource": "api:api.dfos.com/spaces/did:dfos:9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "valid": false,
+      "note": "the id is prefix-stripped, never a full DID"
+    }
+  ],
+  "covers": [
+    {
+      "entry": "api:api.dfos.com",
+      "required": "api:api.dfos.com",
+      "covers": true,
+      "note": "bare covers bare"
+    },
+    {
+      "entry": "api:api.dfos.com",
+      "required": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": true,
+      "note": "bare host is the registered ancestor of every space at that host"
+    },
+    {
+      "entry": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "required": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": true,
+      "note": "child covers itself"
+    },
+    {
+      "entry": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "required": "api:api.dfos.com",
+      "covers": false,
+      "note": "child never covers the bare host"
+    },
+    {
+      "entry": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "required": "api:api.dfos.com/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+      "covers": false,
+      "note": "sibling space"
+    },
+    {
+      "entry": "api:api.dfos.com",
+      "required": "api:api.example.org/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": false,
+      "note": "coverage never crosses hosts"
+    },
+    {
+      "entry": "api:api.dfos.com",
+      "required": "api:api.dfos.com:8443",
+      "covers": false,
+      "note": "a non-default port is part of the host"
+    },
+    {
+      "entry": "api:api.dfos.com:8443",
+      "required": "api:api.dfos.com:8443/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": true,
+      "note": "the port travels with the host into the child"
+    },
+    {
+      "entry": "api:*",
+      "required": "api:api.dfos.com",
+      "covers": false,
+      "note": "api:* is an ordinary id, not a wildcard"
+    },
+    {
+      "entry": "api:*",
+      "required": "api:*",
+      "covers": true,
+      "note": "an ordinary id covers itself"
+    },
+    {
+      "entry": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "required": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": false,
+      "note": "a malformed api: resource never covers a request, even itself"
+    },
+    {
+      "entry": "api:api.dfos.com",
+      "required": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": false,
+      "note": "a malformed required resource is never covered"
+    },
+    {
+      "entry": "chain:*",
+      "required": "api:api.dfos.com",
+      "covers": false,
+      "note": "coverage never crosses resource types"
+    },
+    {
+      "entry": "api:api.dfos.com",
+      "required": "chain:9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "covers": false,
+      "note": "coverage never crosses resource types"
+    }
+  ],
+  "attenuation": [
+    {
+      "note": "bare host narrows to one space",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:posts,write:comments" }],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "valid": true
+    },
+    {
+      "note": "bare host narrows to two spaces",
+      "parent": [
+        { "resource": "api:api.dfos.com", "action": "read:posts,write:upvotes,write:comments" }
+      ],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts,write:upvotes"
+        },
+        {
+          "resource": "api:api.dfos.com/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+          "action": "read:posts"
+        }
+      ],
+      "valid": true
+    },
+    {
+      "note": "bare host to bare host, fewer actions",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:profile,read:email" }],
+      "child": [{ "resource": "api:api.dfos.com", "action": "read:profile" }],
+      "valid": true
+    },
+    {
+      "note": "child widening to the bare host is refused",
+      "parent": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "child": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "valid": false
+    },
+    {
+      "note": "sibling space is refused",
+      "parent": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+          "action": "read:posts"
+        }
+      ],
+      "valid": false
+    },
+    {
+      "note": "child to the same child is exact",
+      "parent": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts,write:comments"
+        }
+      ],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "write:comments"
+        }
+      ],
+      "valid": true
+    },
+    {
+      "note": "resource narrows but the action widens",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts,write:posts"
+        }
+      ],
+      "valid": false
+    },
+    {
+      "note": "another host is refused",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "child": [
+        {
+          "resource": "api:api.example.org/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "valid": false
+    },
+    {
+      "note": "an account-level token narrows onto a child; the entry is inert, not refused",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:profile,read:posts" }],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:profile"
+        }
+      ],
+      "valid": true
+    },
+    {
+      "note": "a malformed api: id is carried only by byte-identical parent",
+      "parent": [
+        {
+          "resource": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "valid": true
+    },
+    {
+      "note": "a bare host does not carry a malformed api: id",
+      "parent": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "child": [
+        {
+          "resource": "api:api.dfos.com/topics/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "valid": false
+    },
+    {
+      "note": "mailbox: stays exact — the hierarchy is api:-only",
+      "parent": [{ "resource": "mailbox:9ctvrdn9vedda7efetrhcdakfh4cr2k", "action": "deposit" }],
+      "child": [
+        {
+          "resource": "mailbox:9ctvrdn9vedda7efetrhcdakfh4cr2k/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+          "action": "deposit"
+        }
+      ],
+      "valid": false
+    }
+  ],
+  "matches": [
+    {
+      "note": "bare host entry satisfies a space-addressed demand",
+      "att": [{ "resource": "api:api.dfos.com", "action": "read:posts,write:comments" }],
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "write:comments",
+      "covers": true
+    },
+    {
+      "note": "child entry satisfies its own space",
+      "att": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "read:posts",
+      "covers": true
+    },
+    {
+      "note": "child entry does not satisfy the bare host",
+      "att": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:profile"
+        }
+      ],
+      "resource": "api:api.dfos.com",
+      "action": "read:profile",
+      "covers": false
+    },
+    {
+      "note": "child entry does not satisfy a sibling space",
+      "att": [
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts"
+        }
+      ],
+      "resource": "api:api.dfos.com/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+      "action": "read:posts",
+      "covers": false
+    },
+    {
+      "note": "the action must be in the covering entry's set",
+      "att": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "write:comments",
+      "covers": false
+    },
+    {
+      "note": "any one entry may cover; the scan does not stop at the first api: entry",
+      "att": [
+        {
+          "resource": "api:api.dfos.com/spaces/cv7n8vkvr64cctf3294h9k4eanhff8z",
+          "action": "read:posts"
+        },
+        {
+          "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+          "action": "read:posts,write:upvotes"
+        }
+      ],
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "write:upvotes",
+      "covers": true
+    },
+    {
+      "note": "host mismatch",
+      "att": [{ "resource": "api:api.dfos.com", "action": "read:posts" }],
+      "resource": "api:api.example.org/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "read:posts",
+      "covers": false
+    },
+    {
+      "note": "existing bare-host behavior is unchanged: exact host, exact action",
+      "att": [{ "resource": "api:api.dfos.com", "action": "read:profile,read:email" }],
+      "resource": "api:api.dfos.com",
+      "action": "read:email",
+      "covers": true
+    },
+    {
+      "note": "read:* is a literal token and matches no real route",
+      "att": [{ "resource": "api:api.dfos.com", "action": "read:*" }],
+      "resource": "api:api.dfos.com/spaces/9ctvrdn9vedda7efetrhcdakfh4cr2k",
+      "action": "read:posts",
+      "covers": false
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, services, credentials, and verification",
   "license": "MIT",