@metalabel/dfos-protocol 0.39.0 → 0.41.0

package/README.md

@@ -22,6 +22,8 @@ import { verifyContentChain, verifyIdentityChain } from '@metalabel/dfos-protoco
 import { createDFOSCredential, signApiIdentityRequest } from '@metalabel/dfos-protocol/credentials';
 // Crypto primitives
 import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-protocol/crypto';
+// KEY-PROOF — the challenge-bound proof that a candidate key is held
+import { signKeyProof, verifyKeyProof } from '@metalabel/dfos-protocol/key-proof';
 ```
 
 ## Subpath Exports
@@ -31,6 +33,7 @@ import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-pr
 | `@metalabel/dfos-protocol/chain`       | Identity & content chains, services, artifacts, countersigns, revocations, credit claims, sign requests |
 | `@metalabel/dfos-protocol/credentials` | DFOS credentials for authorization, and the API-AUTH request-proof / identity-proof envelopes           |
 | `@metalabel/dfos-protocol/crypto`      | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation                                                   |
+| `@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                                           |
 
 ## Specifications
@@ -45,6 +48,7 @@ import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-pr
 | [SIGNING.md](../../specs/SIGNING.md)             | A transport-agnostic way for one party to ask another to produce a DFOS signature |
 | [SIWD.md](../../specs/SIWD.md)                   | Sign In With DFOS — cryptographic identity verification for third-party apps      |
 | [API-AUTH.md](../../specs/API-AUTH.md)           | Proof-of-possession authentication for credential-gated HTTP APIs                 |
+| [KEY-PROOF.md](../../specs/KEY-PROOF.md)         | Challenge-bound, single-shot proof that a candidate key is held                   |
 
 Release history lives at https://github.com/metalabel/dfos/releases.
 

package/dist/chain/index.js

@@ -49,13 +49,14 @@ import {
   verifyIdentityExtensionFromTrustedState,
   verifyRevocation,
   verifySignRequest
-} from "../chunk-SGPSXM56.js";
+} from "../chunk-4YBXPYEU.js";
+import "../chunk-D4IZXFPM.js";
 import {
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
   decodeMultikey,
   encodeEd25519Multikey
-} from "../chunk-NXQW6EBF.js";
+} from "../chunk-IDVYITX7.js";
 import "../chunk-4LG2GEB2.js";
 export {
   ARTIFACT_CID_ANCHOR_RE,

package/dist/{chunk-SGPSXM56.js → chunk-4YBXPYEU.js}

@@ -1,11 +1,13 @@
 import {
   MAX_CREDENTIAL_SIZE,
   decodeDFOSCredentialUnsafe,
-  decodeMultikey,
   matchesResource,
   verifyDFOSCredential,
   verifyDelegationChain
-} from "./chunk-NXQW6EBF.js";
+} from "./chunk-D4IZXFPM.js";
+import {
+  decodeMultikey
+} from "./chunk-IDVYITX7.js";
 import {
   assertJwsProfile,
   base64urlDecode,

package/dist/chunk-73YLK7GK.js

@@ -0,0 +1,191 @@
+import {
+  ED25519_PUB_MULTICODEC,
+  decodeMultikey,
+  encodeEd25519Multikey
+} from "./chunk-IDVYITX7.js";
+import {
+  base64urlDecode,
+  base64urlEncode,
+  importEd25519Keypair,
+  isValidEd25519Signature,
+  signPayloadEd25519
+} from "./chunk-4LG2GEB2.js";
+
+// src/key-proof/key-proof.ts
+var KEY_ADD_JWS_TYP = "did:dfos:key-add";
+var MAX_KEY_PROOF_SIZE = 4096;
+var DEFAULT_KEY_PROOF_SKEW_SECONDS = 300;
+var KeyProofVerifyError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "KeyProofVerifyError";
+    this.reason = reason;
+  }
+};
+var invalid = (reason, message) => new KeyProofVerifyError(reason, `invalid key proof: ${message}`);
+var encoder = new TextEncoder();
+var KEY_PROOF_MEMBERS = ["nonce", "audience", "publicKeyMultibase", "timestamp"];
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+var WHOLE_SECOND_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$/;
+var PROTOCOL_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var validateKeyProofPayload = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalid("schema", "expected a JSON object");
+  }
+  const raw = value;
+  for (const member of Object.keys(raw)) {
+    if (!KEY_PROOF_MEMBERS.includes(member)) {
+      throw invalid("schema", `unknown member ${JSON.stringify(member)} \u2014 the payload is closed`);
+    }
+  }
+  for (const member of KEY_PROOF_MEMBERS) {
+    if (typeof raw[member] !== "string" || raw[member] === "") {
+      throw invalid("schema", `${member} must be a non-empty string`);
+    }
+    if (LONE_SURROGATE.test(raw[member])) {
+      throw invalid("schema", `${member} must be well-formed Unicode`);
+    }
+  }
+  const nonce = raw["nonce"];
+  const audience = raw["audience"];
+  const publicKeyMultibase = raw["publicKeyMultibase"];
+  const timestamp = raw["timestamp"];
+  if (audience !== audience.toLowerCase() || /[\s/\\?#]/.test(audience)) {
+    throw invalid("schema", "audience must be a lowercase authority, without a scheme or path");
+  }
+  if (!WHOLE_SECOND_TIMESTAMP.test(timestamp) || !Number.isFinite(Date.parse(timestamp))) {
+    throw invalid("schema", "timestamp must be ISO-8601 UTC whole-second .000Z");
+  }
+  return { nonce, audience, publicKeyMultibase, timestamp };
+};
+var keyProofSigningInput = (payload) => encoder.encode(JSON.stringify(keyProofPayloadObject(validateKeyProofPayload(payload))));
+var keyProofPayloadObject = (payload) => ({
+  nonce: payload.nonce,
+  audience: payload.audience,
+  publicKeyMultibase: payload.publicKeyMultibase,
+  timestamp: payload.timestamp
+});
+var normalizeTimestamp = (ms) => new Date(Math.floor(ms / 1e3) * 1e3).toISOString();
+var signKeyProof = async (input) => {
+  if (input.typ === "") {
+    throw new Error("invalid key proof: typ must be a registered purpose value");
+  }
+  const { publicKey } = importEd25519Keypair(input.privateKey);
+  let timestamp;
+  if (input.timestamp === void 0) {
+    timestamp = normalizeTimestamp(input.now ? input.now() : Date.now());
+  } else {
+    const ms = Date.parse(input.timestamp);
+    if (!PROTOCOL_TIMESTAMP.test(input.timestamp) || !Number.isFinite(ms) || new Date(ms).toISOString() !== input.timestamp) {
+      throw new Error(`invalid key proof: unparseable timestamp: ${input.timestamp}`);
+    }
+    timestamp = normalizeTimestamp(ms);
+  }
+  const payload = validateKeyProofPayload({
+    nonce: input.nonce,
+    audience: input.audience,
+    publicKeyMultibase: encodeEd25519Multikey(publicKey),
+    timestamp
+  });
+  const headerB64 = base64urlEncode(JSON.stringify({ alg: "EdDSA", typ: input.typ }));
+  const payloadB64 = base64urlEncode(keyProofSigningInput(payload));
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signature = signPayloadEd25519(encoder.encode(signingInput), input.privateKey);
+  const proof = `${signingInput}.${base64urlEncode(signature)}`;
+  if (proof.length > MAX_KEY_PROOF_SIZE) {
+    throw new Error(`key proof exceeds max size: ${proof.length} > ${MAX_KEY_PROOF_SIZE}`);
+  }
+  return { proof, payload };
+};
+var verifyKeyProof = (jws, options) => {
+  const maxSkew = options.maxSkewSeconds ?? DEFAULT_KEY_PROOF_SKEW_SECONDS;
+  if (!Number.isSafeInteger(maxSkew) || maxSkew < 0) {
+    throw new Error("invalid key proof verifier: maxSkewSeconds must be a non-negative integer");
+  }
+  if (jws.length > MAX_KEY_PROOF_SIZE) {
+    throw invalid("size", `envelope exceeds max size: ${jws.length} > ${MAX_KEY_PROOF_SIZE}`);
+  }
+  const parts = jws.split(".");
+  if (parts.length !== 3) throw invalid("header", "failed to decode JWS");
+  const [headerB64, payloadB64] = parts;
+  let header;
+  try {
+    const decoded = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(base64urlDecode(headerB64))
+    );
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+      throw new Error("protected header must be an object");
+    }
+    header = decoded;
+  } catch (err) {
+    throw invalid("header", err instanceof Error ? err.message : "failed to decode header");
+  }
+  if (header["alg"] !== "EdDSA") {
+    throw invalid("header", `unsupported algorithm: ${String(header["alg"])}`);
+  }
+  if ("crit" in header) throw invalid("header", "crit header is not supported");
+  for (const member of ["jwk", "jku", "x5c", "x5u"]) {
+    if (member in header) {
+      throw invalid("header", `${member} header is not allowed (the key rides in the payload)`);
+    }
+  }
+  if ("kid" in header) {
+    throw invalid("header", "kid must be absent \u2014 the candidate key is in no chain");
+  }
+  const typ = header["typ"];
+  if (typeof typ !== "string" || typ !== options.expectedTyp) {
+    throw invalid("header", `invalid typ: expected ${options.expectedTyp}, got ${String(typ)}`);
+  }
+  let payload;
+  try {
+    const source = new TextDecoder("utf-8", { fatal: true }).decode(base64urlDecode(payloadB64));
+    payload = validateKeyProofPayload(JSON.parse(source));
+  } catch (err) {
+    if (err instanceof KeyProofVerifyError) throw err;
+    throw invalid("schema", err instanceof Error ? err.message : "payload is not valid UTF-8 JSON");
+  }
+  if (payload.audience !== options.expectedAudience) {
+    throw invalid("audience", "audience does not match this verifier authority");
+  }
+  const now = Math.floor((options.now ? options.now() : Date.now()) / 1e3);
+  const issued = Math.floor(Date.parse(payload.timestamp) / 1e3);
+  if (Math.abs(now - issued) > maxSkew) {
+    throw invalid("freshness", "timestamp is outside the acceptance window");
+  }
+  let keyBytes;
+  try {
+    const decoded = decodeMultikey(payload.publicKeyMultibase);
+    if (decoded.codec !== ED25519_PUB_MULTICODEC) {
+      throw new Error("publicKeyMultibase is not an Ed25519 public key");
+    }
+    keyBytes = decoded.keyBytes;
+  } catch (err) {
+    throw invalid(
+      "signature",
+      err instanceof Error ? err.message : "undecodable publicKeyMultibase"
+    );
+  }
+  let verified = false;
+  try {
+    verified = isValidEd25519Signature(
+      encoder.encode(`${headerB64}.${payloadB64}`),
+      base64urlDecode(parts[2]),
+      keyBytes
+    );
+  } catch {
+    verified = false;
+  }
+  if (!verified) throw invalid("signature", "signature does not verify against publicKeyMultibase");
+  return { payload, typ, now };
+};
+
+export {
+  KEY_ADD_JWS_TYP,
+  MAX_KEY_PROOF_SIZE,
+  DEFAULT_KEY_PROOF_SKEW_SECONDS,
+  KeyProofVerifyError,
+  keyProofSigningInput,
+  signKeyProof,
+  verifyKeyProof
+};

package/dist/{chunk-NXQW6EBF.js → chunk-D4IZXFPM.js}

@@ -1,3 +1,6 @@
+import {
+  decodeMultikey
+} from "./chunk-IDVYITX7.js";
 import {
   assertJwsProfile,
   base64urlDecode,
@@ -35,45 +38,6 @@ var DFOSCredentialPayload = z.looseObject({
   iat: z.number().int().positive()
 });
 
-// src/chain/multikey.ts
-import { base58btc } from "multiformats/bases/base58";
-var ED25519_PUB_PREFIX = new Uint8Array([237, 1]);
-var ED25519_PRIV_PREFIX = new Uint8Array([128, 38]);
-var ED25519_PUB_MULTICODEC = 237;
-var ED25519_PRIV_MULTICODEC = 4864;
-var encodeEd25519Multikey = (publicKeyBytes) => {
-  if (publicKeyBytes.length !== 32) {
-    throw new Error(`expected 32-byte Ed25519 public key, got ${publicKeyBytes.length}`);
-  }
-  const prefixed = new Uint8Array(ED25519_PUB_PREFIX.length + publicKeyBytes.length);
-  prefixed.set(ED25519_PUB_PREFIX);
-  prefixed.set(publicKeyBytes, ED25519_PUB_PREFIX.length);
-  return base58btc.encode(prefixed);
-};
-var decodeMultikey = (multibase) => {
-  const bytes = base58btc.decode(multibase);
-  if (bytes.length < 2) {
-    throw new Error("multikey too short");
-  }
-  if (bytes[0] === ED25519_PUB_PREFIX[0] && bytes[1] === ED25519_PUB_PREFIX[1]) {
-    const keyBytes = bytes.slice(2);
-    if (keyBytes.length !== 32) {
-      throw new Error(`expected 32-byte Ed25519 public key, got ${keyBytes.length}`);
-    }
-    return { keyBytes, codec: ED25519_PUB_MULTICODEC };
-  }
-  if (bytes[0] === ED25519_PRIV_PREFIX[0] && bytes[1] === ED25519_PRIV_PREFIX[1]) {
-    const keyBytes = bytes.slice(2);
-    if (keyBytes.length !== 32) {
-      throw new Error(`expected 32-byte Ed25519 private key, got ${keyBytes.length}`);
-    }
-    return { keyBytes, codec: ED25519_PRIV_MULTICODEC };
-  }
-  throw new Error(
-    `unsupported multikey codec: [0x${bytes[0]?.toString(16)}, 0x${bytes[1]?.toString(16)}]`
-  );
-};
-
 // src/credentials/api-auth.ts
 var REQUEST_PROOF_JWS_TYP = "did:dfos:request-proof";
 var IDENTITY_PROOF_JWS_TYP = "did:dfos:identity-proof";
@@ -630,10 +594,6 @@ var CredentialVerificationError = class extends Error {
 };
 
 export {
-  ED25519_PUB_MULTICODEC,
-  ED25519_PRIV_MULTICODEC,
-  encodeEd25519Multikey,
-  decodeMultikey,
   MAX_CREDENTIAL_SIZE,
   Attenuation,
   DFOSCredentialPayload,

package/dist/chunk-IDVYITX7.js

@@ -0,0 +1,45 @@
+// src/chain/multikey.ts
+import { base58btc } from "multiformats/bases/base58";
+var ED25519_PUB_PREFIX = new Uint8Array([237, 1]);
+var ED25519_PRIV_PREFIX = new Uint8Array([128, 38]);
+var ED25519_PUB_MULTICODEC = 237;
+var ED25519_PRIV_MULTICODEC = 4864;
+var encodeEd25519Multikey = (publicKeyBytes) => {
+  if (publicKeyBytes.length !== 32) {
+    throw new Error(`expected 32-byte Ed25519 public key, got ${publicKeyBytes.length}`);
+  }
+  const prefixed = new Uint8Array(ED25519_PUB_PREFIX.length + publicKeyBytes.length);
+  prefixed.set(ED25519_PUB_PREFIX);
+  prefixed.set(publicKeyBytes, ED25519_PUB_PREFIX.length);
+  return base58btc.encode(prefixed);
+};
+var decodeMultikey = (multibase) => {
+  const bytes = base58btc.decode(multibase);
+  if (bytes.length < 2) {
+    throw new Error("multikey too short");
+  }
+  if (bytes[0] === ED25519_PUB_PREFIX[0] && bytes[1] === ED25519_PUB_PREFIX[1]) {
+    const keyBytes = bytes.slice(2);
+    if (keyBytes.length !== 32) {
+      throw new Error(`expected 32-byte Ed25519 public key, got ${keyBytes.length}`);
+    }
+    return { keyBytes, codec: ED25519_PUB_MULTICODEC };
+  }
+  if (bytes[0] === ED25519_PRIV_PREFIX[0] && bytes[1] === ED25519_PRIV_PREFIX[1]) {
+    const keyBytes = bytes.slice(2);
+    if (keyBytes.length !== 32) {
+      throw new Error(`expected 32-byte Ed25519 private key, got ${keyBytes.length}`);
+    }
+    return { keyBytes, codec: ED25519_PRIV_MULTICODEC };
+  }
+  throw new Error(
+    `unsupported multikey codec: [0x${bytes[0]?.toString(16)}, 0x${bytes[1]?.toString(16)}]`
+  );
+};
+
+export {
+  ED25519_PUB_MULTICODEC,
+  ED25519_PRIV_MULTICODEC,
+  encodeEd25519Multikey,
+  decodeMultikey
+};

package/dist/credentials/index.js

@@ -34,7 +34,8 @@ import {
   verifyDelegationChain,
   verifyIdentityProofEnvelope,
   verifyRequestProofEnvelope
-} from "../chunk-NXQW6EBF.js";
+} from "../chunk-D4IZXFPM.js";
+import "../chunk-IDVYITX7.js";
 import "../chunk-4LG2GEB2.js";
 export {
   ApiRequestVerifyError,

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { JwsHeader, JwsVerificationError, JwtClaims, JwtCreateOptions, JwtHeader
 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, I as IdentityOperation, g as Iso8601, M as MAX_ARTIFACT_PAYLOAD_SIZE, h as MAX_CREDENTIAL_SIZE, i as MAX_CREDIT_CLAIM_SIZE, j as MAX_OPERATION_SIZE, k as MAX_SERVICES_ENTRIES, l as MAX_SERVICES_PAYLOAD_SIZE, m as MAX_SIGN_REQUEST_PAYLOAD_SIZE, n as MAX_SIGN_REQUEST_SIZE, o as MultikeyPublicKey, R as RevocationChecker, p as RevocationPayload, S as ServiceEntry, q as ServicesArray, r as SignRequestPayload, s as Signer, V as VerifiedDFOSCredential, t as VerifiedDelegationChain, u as VerifiedIdentity, v as createDFOSCredential, w as decodeDFOSCredentialUnsafe, x as isAttenuated, y as matchesResource, z as parseProtocolTimestampUnix, B as verifyDFOSCredential, E as verifyDelegationChain } from './dfos-credential-X6uvPIth.js';
 export { AnchorKind, CreditClaimFailureReason, CreditClaimVerifyError, CreditEntry, CreditEntryState, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, RECOGNIZED_SERVICE_TYPES, SignRequestFailureReason, SignRequestVerifyError, VerifiedArtifact, VerifiedContentChain, VerifiedCountersignature, VerifiedCreditClaim, VerifiedCreditEntry, VerifiedRevocation, VerifiedSignRequest, anchorsByLabel, assertCanonicalSignRequestPayload, assertServicesWithinCap, buildSignRequest, classifyAnchor, 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 { DEFAULT_KEY_PROOF_SKEW_SECONDS, KEY_ADD_JWS_TYP, KeyProofFailureReason, KeyProofPayload, KeyProofVerifyError, MAX_KEY_PROOF_SIZE, SignKeyProofInput, VerifiedKeyProof, VerifyKeyProofOptions, keyProofSigningInput, signKeyProof, 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';
 import 'multiformats/cid';

package/dist/index.js

@@ -49,7 +49,7 @@ import {
   verifyIdentityExtensionFromTrustedState,
   verifyRevocation,
   verifySignRequest
-} from "./chunk-SGPSXM56.js";
+} from "./chunk-4YBXPYEU.js";
 import {
   ApiRequestVerifyError,
   Attenuation,
@@ -58,8 +58,6 @@ import {
   DEFAULT_PROOF_WINDOW_SECONDS,
   DFOSCredentialPayload,
   DFOS_AUTH_SCHEME,
-  ED25519_PRIV_MULTICODEC,
-  ED25519_PUB_MULTICODEC,
   EMPTY_BODY_SHA256,
   IDENTITY_PROOF_JWS_TYP,
   MAX_BODY_BYTES,
@@ -75,8 +73,6 @@ import {
   canonicalExtraMembers,
   createDFOSCredential,
   decodeDFOSCredentialUnsafe,
-  decodeMultikey,
-  encodeEd25519Multikey,
   invalidProof,
   isAttenuated,
   matchesResource,
@@ -90,7 +86,22 @@ import {
   verifyDelegationChain,
   verifyIdentityProofEnvelope,
   verifyRequestProofEnvelope
-} from "./chunk-NXQW6EBF.js";
+} from "./chunk-D4IZXFPM.js";
+import {
+  DEFAULT_KEY_PROOF_SKEW_SECONDS,
+  KEY_ADD_JWS_TYP,
+  KeyProofVerifyError,
+  MAX_KEY_PROOF_SIZE,
+  keyProofSigningInput,
+  signKeyProof,
+  verifyKeyProof
+} from "./chunk-73YLK7GK.js";
+import {
+  ED25519_PRIV_MULTICODEC,
+  ED25519_PUB_MULTICODEC,
+  decodeMultikey,
+  encodeEd25519Multikey
+} from "./chunk-IDVYITX7.js";
 import {
   JwsVerificationError,
   JwtVerificationError,
@@ -136,6 +147,7 @@ export {
   CredentialVerificationError,
   CreditClaimPayload,
   CreditClaimVerifyError,
+  DEFAULT_KEY_PROOF_SKEW_SECONDS,
   DEFAULT_PROOF_SKEW_SECONDS,
   DEFAULT_PROOF_WINDOW_SECONDS,
   DFOSCredentialPayload,
@@ -149,10 +161,13 @@ export {
   Iso8601,
   JwsVerificationError,
   JwtVerificationError,
+  KEY_ADD_JWS_TYP,
+  KeyProofVerifyError,
   MAX_ARTIFACT_PAYLOAD_SIZE,
   MAX_BODY_BYTES,
   MAX_CREDENTIAL_SIZE,
   MAX_CREDIT_CLAIM_SIZE,
+  MAX_KEY_PROOF_SIZE,
   MAX_OPERATION_SIZE,
   MAX_PROOF_FRESHNESS_SPAN_SECONDS,
   MAX_REQUEST_PROOF_SIZE,
@@ -209,6 +224,7 @@ export {
   isRecognizedServiceType,
   isValidEd25519Signature,
   isValidId,
+  keyProofSigningInput,
   linearize,
   matchesResource,
   misconfiguredProof,
@@ -226,6 +242,7 @@ export {
   signCountersignature,
   signCreditClaim,
   signIdentityOperation,
+  signKeyProof,
   signPayloadEd25519,
   signRevocation,
   unverifiableProof,
@@ -242,6 +259,7 @@ export {
   verifyIdentityProofEnvelope,
   verifyJws,
   verifyJwt,
+  verifyKeyProof,
   verifyRequestProofEnvelope,
   verifyRevocation,
   verifySignRequest

package/dist/key-proof/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The first registered purpose in KEY-PROOF.md's purpose registry: the candidate
+ * key presents for addition to a ceremony-named identity's `authKeys`/
+ * `assertKeys` sets.
+ *
+ * The `typ` is a PARAMETER everywhere in this module, not a constant baked into
+ * the algorithm — the grammar and the verification steps are identical for every
+ * registered row, and a new purpose lands by registering a value, never by
+ * minting an envelope. This constant is the one row that exists.
+ */
+declare const KEY_ADD_JWS_TYP = "did:dfos:key-add";
+/** Size cap on the serialized envelope, checked BEFORE any decode. */
+declare const MAX_KEY_PROOF_SIZE = 4096;
+/**
+ * RECOMMENDED acceptance window, in seconds, EITHER SIDE of the verifier's clock
+ * — matching a ceremony's own lifetime (KEY-PROOF.md, Verification step 5).
+ */
+declare const DEFAULT_KEY_PROOF_SKEW_SECONDS = 300;
+/**
+ * The closed payload. Exactly these four members, each a string, in exactly this
+ * order — the member set is EXHAUSTIVE and no amendment may introduce a member
+ * that carries intent or content.
+ */
+interface KeyProofPayload {
+    /** The verifier-minted, single-use challenge, exactly as the carriage delivered it. */
+    nonce: string;
+    /** The completion endpoint's lowercase authority — `host`, or `host:port` off 443. */
+    audience: string;
+    /** The candidate key's Multikey — and the key that signs this envelope. */
+    publicKeyMultibase: string;
+    /** ISO 8601 creation time, floor-normalized to whole seconds (`.000Z`). */
+    timestamp: string;
+}
+/** The verification step a failure arose in. Branch on this, never on message text. */
+type KeyProofFailureReason = 'size' | 'header' | 'schema' | 'audience' | 'freshness' | 'signature';
+/** Thrown by `verifyKeyProof`. Branch on `reason`, never on message text. */
+declare class KeyProofVerifyError extends Error {
+    readonly reason: KeyProofFailureReason;
+    constructor(reason: KeyProofFailureReason, message: string);
+}
+/**
+ * THE BYTE CONTRACT. Serializes a payload to the canonical bytes that ARE the
+ * JWS payload segment: minimal UTF-8 JSON, no insignificant whitespace, members
+ * in exactly the order `nonce, audience, publicKeyMultibase, timestamp`.
+ *
+ * PURE and clientless: import it in a holder's signing tool and in a ceremony
+ * operator's verifier alike. Byte-for-byte identical to Go's
+ * `KeyProofSigningInput`.
+ */
+declare const keyProofSigningInput: (payload: KeyProofPayload) => Uint8Array;
+interface SignKeyProofInput {
+    /** The registered purpose this proof is scoped to — e.g. `KEY_ADD_JWS_TYP`. */
+    typ: string;
+    /** The verifier-minted nonce, exactly as the carriage delivered it. */
+    nonce: string;
+    /** The completion endpoint's lowercase authority — the one the human confirmed. */
+    audience: string;
+    /**
+     * The candidate key's raw 32-byte Ed25519 private key. `publicKeyMultibase` is
+     * DERIVED from it rather than accepted as an input: this envelope is
+     * self-proving, and a signer that could name a key it does not hold would be
+     * the one construction the artifact exists to foreclose.
+     */
+    privateKey: Uint8Array;
+    /** Timestamp override; floor-normalized to `.000Z` if it carries milliseconds. */
+    timestamp?: string;
+    /** Clock injection (unix ms) for the default timestamp. Default `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Sign one key proof. The producer half of the byte contract.
+ *
+ * The protected header is EXACTLY `{"alg":"EdDSA","typ":"<purpose>"}` — two
+ * members, no `kid` (the key is in no chain and rides in the payload) and no
+ * `cid` (there is no operation to bind). It is assembled by hand rather than
+ * through `createJws`, whose `JwsHeader` requires a `kid` this envelope must not
+ * carry.
+ *
+ * HOLDER OBLIGATIONS THIS FUNCTION CANNOT DISCHARGE (KEY-PROOF.md, Holder
+ * Obligations). A holder MUST show its human the audience and the purpose before
+ * calling this, and SHOULD refuse to sign for a key any identity's chain has
+ * ever declared — the `key=` reverse index is has-ever-declared, and one key in
+ * two chains publishes an irreversible public link between them. Both are
+ * decisions about a human and a network, made before there is a signature to
+ * make; neither belongs to a pure signer.
+ */
+declare const signKeyProof: (input: SignKeyProofInput) => Promise<{
+    proof: string;
+    payload: KeyProofPayload;
+}>;
+interface VerifyKeyProofOptions {
+    /**
+     * The registered `typ` THIS ceremony requires. The gate is absolute: it is what
+     * keeps a proof signed for one ceremony from ever being presented for another.
+     */
+    expectedTyp: string;
+    /**
+     * THE VERIFIER'S OWN CONFIGURED AUTHORITY — a value the deployment holds, NEVER
+     * one read from the request. `Host`, `X-Forwarded-Host`, and the request URL's
+     * authority are all attacker-supplied; a verifier that compared against one of
+     * them would have no audience binding at all, and audience binding is the whole
+     * defense against challenge relay.
+     */
+    expectedAudience: string;
+    /** Acceptance window, seconds, EITHER SIDE. Default `DEFAULT_KEY_PROOF_SKEW_SECONDS`. */
+    maxSkewSeconds?: number;
+    /** Clock injection (unix ms). Default `Date.now()`. */
+    now?: () => number;
+}
+/** What a verified key proof hands back. */
+interface VerifiedKeyProof {
+    /**
+     * The validated payload. THE CALLER MUST NOW RUN STEP 6 against `payload.nonce`:
+     * check that it is a nonce this verifier minted, for this ceremony, not yet
+     * consumed, and consume it ATOMICALLY (check-and-delete) so two racing
+     * completions cannot both pass.
+     */
+    payload: KeyProofPayload;
+    /** The header `typ` — equal to `expectedTyp`, since anything else rejected. */
+    typ: string;
+    /** The integer unix seconds the freshness check used. */
+    now: number;
+}
+/**
+ * Verify a key proof — KEY-PROOF.md's verification algorithm steps 1–5 and 7:
+ * size cap, header gates, closed payload schema, audience byte-equality,
+ * freshness, and the signature against the payload's OWN `publicKeyMultibase`.
+ *
+ * STEP 6 (NONCE) IS THE CALLER'S, and this function cannot stand in for it. The
+ * nonce MUST be one this verifier minted, for this ceremony, not yet consumed,
+ * checked and consumed ATOMICALLY — a check-and-delete against the verifier's
+ * own store, which is state this pure function does not hold. It is returned on
+ * `payload.nonce` precisely so the caller can run that step next. Without it a
+ * proof is replayable for the length of the freshness window.
+ *
+ * What the seven steps together establish is exactly one fact: THE NAMED KEY WAS
+ * HELD, AND CONSENTED TO THIS CEREMONY AT THIS VERIFIER, INSIDE THIS WINDOW.
+ * Everything after — appending the key to a chain, custody policy, notification
+ * — is the ceremony operator's.
+ */
+declare const verifyKeyProof: (jws: string, options: VerifyKeyProofOptions) => VerifiedKeyProof;
+
+export { DEFAULT_KEY_PROOF_SKEW_SECONDS, KEY_ADD_JWS_TYP, type KeyProofFailureReason, type KeyProofPayload, KeyProofVerifyError, MAX_KEY_PROOF_SIZE, type SignKeyProofInput, type VerifiedKeyProof, type VerifyKeyProofOptions, keyProofSigningInput, signKeyProof, verifyKeyProof };

package/dist/key-proof/index.js

@@ -0,0 +1,20 @@
+import {
+  DEFAULT_KEY_PROOF_SKEW_SECONDS,
+  KEY_ADD_JWS_TYP,
+  KeyProofVerifyError,
+  MAX_KEY_PROOF_SIZE,
+  keyProofSigningInput,
+  signKeyProof,
+  verifyKeyProof
+} from "../chunk-73YLK7GK.js";
+import "../chunk-IDVYITX7.js";
+import "../chunk-4LG2GEB2.js";
+export {
+  DEFAULT_KEY_PROOF_SKEW_SECONDS,
+  KEY_ADD_JWS_TYP,
+  KeyProofVerifyError,
+  MAX_KEY_PROOF_SIZE,
+  keyProofSigningInput,
+  signKeyProof,
+  verifyKeyProof
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, services, credentials, and verification",
   "license": "MIT",
@@ -41,6 +41,10 @@
       "import": "./dist/credentials/index.js",
       "types": "./dist/credentials/index.d.ts"
     },
+    "./key-proof": {
+      "import": "./dist/key-proof/index.js",
+      "types": "./dist/key-proof/index.d.ts"
+    },
     "./fold": {
       "import": "./dist/fold/index.js",
       "types": "./dist/fold/index.d.ts"