@forgezero/runtime 0.1.24 → 0.1.25

package/README.md

@@ -814,7 +814,7 @@ Threshold-share parsing, validation and reconstruction. This is a supported entr
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 ```
 
@@ -824,10 +824,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 
-export const selectedCapability = PROBE_BYTES;
+export const selectedCapability = CUSTODY_ENVELOPE_SUITE;
 ```
 
 <a id="forgezero-runtime-custody-crypto"></a>

package/dist/custody-share.d.ts

@@ -1,8 +1,55 @@
 import { type CipherBox, type SealedToKey } from './custody-crypto';
+export declare const CUSTODY_ENVELOPE_VERSION: 3;
+export declare const CUSTODY_ENVELOPE_SUITE: "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+export declare const CUSTODY_FACTOR_PROOF_VERSION: 1;
+export type CustodyCredentialPurpose = 'custody';
+export type CustodyCredentialLifecycle = 'pending' | 'active' | 'retired';
+export type CustodyFactor = 'ceremony_passkey' | 'recovery_phrase';
+export type CustodyEnvelopeGeneration = number;
+export type CustodyTransactionOutcome = 'completed' | 'factor_mismatch' | 'credential_mismatch' | 'replayed' | 'expired' | 'batch_mismatch' | 'seed_fingerprint_mismatch';
+export interface CustodyFactorBinding {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    factor: CustodyFactor;
+    requestKey: string;
+    method: 'POST';
+    path: string;
+    payloadDigest: string;
+    challenge: string;
+    expiresAtSec: number;
+}
+export interface CustodyPasskeyProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'ceremony_passkey';
+    credentialId: string;
+    signature: string;
+}
+export interface CustodyPhraseProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'recovery_phrase';
+    signature: string;
+}
+export type CustodyFactorProof = CustodyPasskeyProofV1 | CustodyPhraseProofV1;
+export interface CustodyActionRequest {
+    _key: string;
+    ceremonyKey: string;
+    ownerUserKey: string;
+    operation: 'seal' | 'verify' | 'reshare' | 'unlock' | 'rotate' | 'verify_rotation';
+    allowedFactors: CustodyFactor[];
+    payloadDigest: string;
+    challenge: string;
+    status: 'open' | 'consumed' | 'expired';
+    expiresAtSec: number;
+    revision: number;
+}
 export interface SealedShare {
     shareIndex: number;
-    /** Account credential whose PRF deterministically derives this passkey key. */
+    /** Dedicated custody credential whose PRF deterministically derives this passkey key. */
     passkeyCredentialId?: string;
+    /** Base64url ceremony salt persisted with that exact custody credential. */
+    passkeyPrfSalt?: string;
     passkeyEnvelope: CipherBox;
     phraseEnvelope: CipherBox;
     /** base64 — the HKDF salt for the phrase key and the verifier. */
@@ -10,6 +57,22 @@ export interface SealedShare {
     /** hex — proves the right phrase without being able to rebuild it. */
     phraseVerifier: string;
 }
+/** New writes use this shape. V2 is retained only for bounded unlock-and-rotate migration. */
+export interface CustodyEnvelopeV3 extends SealedShare {
+    version: typeof CUSTODY_ENVELOPE_VERSION;
+    suite: typeof CUSTODY_ENVELOPE_SUITE;
+    generation: CustodyEnvelopeGeneration;
+    passkeyGeneration?: CustodyEnvelopeGeneration;
+    phraseGeneration?: CustodyEnvelopeGeneration;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    passkeyCredentialId: string;
+    passkeyPrfSalt: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
+}
+export declare function isCustodyEnvelopeV3(value: SealedShare): value is CustodyEnvelopeV3;
 type EnvelopeKind = 'passkey' | 'phrase';
 /** The x-coordinate a share was cut at — its custodian-facing share number. */
 export declare function shareIndexOf(share: Uint8Array): number;
@@ -44,12 +107,15 @@ export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: s
  * ever sent.
  */
 export interface WrappingKeys {
-    /** The verified, PRF-capable account credential selected by the browser. */
+    /** The verified, PRF-capable custody credential selected by the browser. */
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPublicKey: string;
     phrasePublicKey: string;
     phraseSalt: string;
     phraseVerifier: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
 }
 /** The private half for one factor. Never leaves the machine that made it. */
 export declare function passkeyWrappingKey(custodianKey: string, passkeyPrfOutput: Uint8Array): {
@@ -65,9 +131,25 @@ export declare function phraseWrappingKey(custodianKey: string, phraseWords: str
 export declare function wrappingKeysFor(args: {
     custodianKey: string;
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPrfOutput: Uint8Array;
     phraseWords: string[];
 }): WrappingKeys;
+export declare function custodyFactorActionPublicKey(factor: CustodyFactor, custodianKey: string, factorMaterial: Uint8Array): string;
+/** Stable browser/API digest used to bind a custody proof to one exact payload. */
+export declare function custodyActionPayloadDigest(value: unknown): string;
+export declare function createCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    factorMaterial: Uint8Array;
+    credentialId?: string;
+}): CustodyFactorProof;
+export declare function createCustodyPasskeyProof(binding: CustodyFactorBinding, passkeyPrfOutput: Uint8Array, credentialId: string): CustodyPasskeyProofV1;
+export declare function createCustodyPhraseProof(binding: CustodyFactorBinding, phraseWords: string[], phraseSalt: string): CustodyPhraseProofV1;
+export declare function verifyCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    proof: CustodyFactorProof;
+    publicKey: string;
+}): boolean;
 /** Open something the server sealed to one of those public keys. */
 export declare function openSealedToFactor(args: {
     custodianKey: string;
@@ -76,9 +158,12 @@ export declare function openSealedToFactor(args: {
     passkeyPrfOutput?: Uint8Array;
     phraseWords?: string[];
     phraseSalt?: string;
+    aad?: string;
 }): Uint8Array;
 /** The aad the server must use when sealing to a custodian's factor key. */
 export declare const factorWrapAad: (custodianKey: string, factor: EnvelopeKind) => string;
+/** Canonical AAD for V3. Length-prefixing prevents ambiguous concatenation. */
+export declare function custodyEnvelopeV3Aad(envelope: Pick<CustodyEnvelopeV3, 'version' | 'suite' | 'realmId' | 'ceremonyKey' | 'custodianKey' | 'shareIndex' | 'passkeyCredentialId' | 'generation' | 'passkeyGeneration' | 'phraseGeneration'>, factor: EnvelopeKind): string;
 /**
  * A share plus a probe, sealed together.
  *

package/dist/custody-share.js

@@ -174,9 +174,18 @@ function phraseVerifier(words, salt) {
 }
 
 // src/custody-share.ts
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { hkdf as hkdf3 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+var CUSTODY_ENVELOPE_VERSION = 3;
+var CUSTODY_ENVELOPE_SUITE = "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+var CUSTODY_FACTOR_PROOF_VERSION = 1;
 var KEY_BYTES3 = 32;
 var MIN_PRF_BYTES = 32;
 var PASSKEY_KEY_SALT = "forgezero:custodian:passkey:v1";
+function isCustodyEnvelopeV3(value) {
+  return value.version === CUSTODY_ENVELOPE_VERSION && value.suite === CUSTODY_ENVELOPE_SUITE;
+}
 var utf82 = (value) => new TextEncoder().encode(value);
 var toBase642 = (bytes) => {
   let binary = "";
@@ -283,31 +292,167 @@ function phraseWrappingKey(custodianKey, phraseWords, salt) {
 function wrappingKeysFor(args) {
   if (!args.passkeyCredentialId)
     throw new Error("custody-share: passkey credential id is required");
+  if (!/^[A-Za-z0-9_-]{43}$/.test(args.passkeyPrfSalt)) {
+    throw new Error("custody-share: ceremony passkey PRF salt is required");
+  }
   const salt = newSalt();
   const passkey = passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput);
   const phrase = phraseWrappingKey(args.custodianKey, args.phraseWords, salt);
+  const passkeyAction = custodyFactorActionKeyPair("ceremony_passkey", args.custodianKey, args.passkeyPrfOutput);
+  const phraseMaterial = phraseToKey(args.phraseWords, salt);
+  const phraseAction = custodyFactorActionKeyPair("recovery_phrase", args.custodianKey, phraseMaterial);
   try {
     return {
       passkeyCredentialId: args.passkeyCredentialId,
+      passkeyPrfSalt: args.passkeyPrfSalt,
       passkeyPublicKey: toBase642(passkey.publicKey),
       phrasePublicKey: toBase642(phrase.publicKey),
       phraseSalt: toBase642(salt),
-      phraseVerifier: phraseVerifier(args.phraseWords, salt)
+      phraseVerifier: phraseVerifier(args.phraseWords, salt),
+      passkeyActionPublicKey: toBase642(passkeyAction.publicKey),
+      phraseActionPublicKey: toBase642(phraseAction.publicKey)
     };
   } finally {
     passkey.secretKey.fill(0);
     phrase.secretKey.fill(0);
+    passkeyAction.secretKey.fill(0);
+    phraseAction.secretKey.fill(0);
+    phraseMaterial.fill(0);
+  }
+}
+var actionInfo = (factor, custodianKey) => `forgezero:custody:factor-action:ml-dsa-65:v1:${factor}:${custodianKey.length}:${custodianKey}`;
+function custodyFactorActionKeyPair(factor, custodianKey, factorMaterial) {
+  assertCustodianKey(custodianKey);
+  if (factorMaterial.length < 32)
+    throw new Error("custody-share: action factor must be at least 32 bytes");
+  const seed = hkdf3(sha2563, factorMaterial, utf82("forgezero:custody:factor-action:ml-dsa-65:v1"), utf82(actionInfo(factor, custodianKey)), 32);
+  try {
+    const pair = ml_dsa65.keygen(seed);
+    return { publicKey: Uint8Array.from(pair.publicKey), secretKey: Uint8Array.from(pair.secretKey) };
+  } finally {
+    seed.fill(0);
+  }
+}
+function custodyFactorActionPublicKey(factor, custodianKey, factorMaterial) {
+  const pair = custodyFactorActionKeyPair(factor, custodianKey, factorMaterial);
+  try {
+    return toBase642(pair.publicKey);
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+var proofBytes = (binding) => {
+  const values = [
+    "forgezero-custody-factor-proof-v1",
+    String(binding.version),
+    binding.realmId,
+    binding.ceremonyKey,
+    binding.custodianKey,
+    binding.factor,
+    binding.requestKey,
+    binding.method,
+    binding.path,
+    binding.payloadDigest,
+    binding.challenge,
+    String(binding.expiresAtSec)
+  ];
+  return utf82(values.map((value) => `${utf82(value).length}:${value}`).join(`
+`));
+};
+function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("custody-share: non-finite action payload number");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object") {
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  }
+  throw new Error("custody-share: unsupported action payload value");
+}
+function custodyActionPayloadDigest(value) {
+  return Array.from(sha2563(utf82(canonicalJson(value))), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createCustodyFactorProof(args) {
+  if (args.binding.version !== CUSTODY_FACTOR_PROOF_VERSION) {
+    throw new Error("custody-share: unsupported factor proof version");
+  }
+  const pair = custodyFactorActionKeyPair(args.binding.factor, args.binding.custodianKey, args.factorMaterial);
+  try {
+    const signature = toBase642(ml_dsa65.sign(proofBytes(args.binding), pair.secretKey));
+    return args.binding.factor === "ceremony_passkey" ? {
+      version: CUSTODY_FACTOR_PROOF_VERSION,
+      factor: "ceremony_passkey",
+      credentialId: args.credentialId ?? "",
+      signature
+    } : { version: CUSTODY_FACTOR_PROOF_VERSION, factor: "recovery_phrase", signature };
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+function createCustodyPasskeyProof(binding, passkeyPrfOutput, credentialId) {
+  if (binding.factor !== "ceremony_passkey") {
+    throw new Error("custody-share: passkey proof requires ceremony_passkey binding");
+  }
+  return createCustodyFactorProof({
+    binding,
+    factorMaterial: passkeyPrfOutput,
+    credentialId
+  });
+}
+function createCustodyPhraseProof(binding, phraseWords, phraseSalt) {
+  if (binding.factor !== "recovery_phrase") {
+    throw new Error("custody-share: phrase proof requires recovery_phrase binding");
+  }
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  const material = phraseToKey(phraseWords, fromBase642(phraseSalt));
+  try {
+    return createCustodyFactorProof({ binding, factorMaterial: material });
+  } finally {
+    material.fill(0);
+  }
+}
+function verifyCustodyFactorProof(args) {
+  try {
+    if (args.proof.version !== CUSTODY_FACTOR_PROOF_VERSION || args.proof.factor !== args.binding.factor)
+      return false;
+    const publicKey = fromBase642(args.publicKey);
+    const signature = fromBase642(args.proof.signature);
+    return publicKey.length === ml_dsa65.lengths.publicKey && signature.length === ml_dsa65.lengths.signature && ml_dsa65.verify(signature, proofBytes(args.binding), publicKey);
+  } catch {
+    return false;
   }
 }
 function openSealedToFactor(args) {
   const pair = args.factor === "passkey" ? passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput) : phraseWrappingKey(args.custodianKey, args.phraseWords, fromBase642(args.phraseSalt));
   try {
-    return openFromKey(pair.secretKey, args.box, wrapInfo(args.custodianKey, args.factor));
+    return openFromKey(pair.secretKey, args.box, args.aad ?? wrapInfo(args.custodianKey, args.factor));
   } finally {
     pair.secretKey.fill(0);
   }
 }
 var factorWrapAad = (custodianKey, factor) => wrapInfo(custodianKey, factor);
+function custodyEnvelopeV3Aad(envelope, factor) {
+  const values = [
+    "forgezero-custody-envelope-aad",
+    String(envelope.version),
+    envelope.suite,
+    envelope.realmId,
+    envelope.ceremonyKey,
+    envelope.custodianKey,
+    String(envelope.shareIndex),
+    factor,
+    factor === "passkey" ? envelope.passkeyCredentialId : "recovery_phrase",
+    String(factor === "passkey" ? envelope.passkeyGeneration ?? envelope.generation : envelope.phraseGeneration ?? envelope.generation)
+  ];
+  return values.map((value) => `${utf82(value).length}:${value}`).join(`
+`);
+}
 var PROBE_BYTES = 32;
 function joinProbeAndShare(probe, share) {
   if (probe.length !== PROBE_BYTES)
@@ -324,17 +469,20 @@ function splitProbeAndShare(opened) {
 }
 function openFactorEnvelope(args) {
   const box = args.factor === "passkey" ? args.sealed.passkeyEnvelope : args.sealed.phraseEnvelope;
+  const aad = isCustodyEnvelopeV3(args.sealed) ? custodyEnvelopeV3Aad(args.sealed, args.factor) : undefined;
   return splitProbeAndShare(openSealedToFactor({
     custodianKey: args.custodianKey,
     factor: args.factor,
     box,
     passkeyPrfOutput: args.passkeyPrfOutput,
     phraseWords: args.phraseWords,
-    phraseSalt: args.sealed.phraseSalt
+    phraseSalt: args.sealed.phraseSalt,
+    aad
   }));
 }
 export {
   wrappingKeysFor,
+  verifyCustodyFactorProof,
   splitProbeAndShare,
   shareIndexOf,
   sealShare,
@@ -345,6 +493,16 @@ export {
   openSealedToFactor,
   openFactorEnvelope,
   joinProbeAndShare,
+  isCustodyEnvelopeV3,
   factorWrapAad,
-  PROBE_BYTES
+  custodyFactorActionPublicKey,
+  custodyEnvelopeV3Aad,
+  custodyActionPayloadDigest,
+  createCustodyPhraseProof,
+  createCustodyPasskeyProof,
+  createCustodyFactorProof,
+  PROBE_BYTES,
+  CUSTODY_FACTOR_PROOF_VERSION,
+  CUSTODY_ENVELOPE_VERSION,
+  CUSTODY_ENVELOPE_SUITE
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/runtime",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "type": "module",
   "publishConfig": {
     "access": "public",