@forgezero/runtime 0.1.0 → 0.1.1

package/dist/custody-crypto.d.ts

@@ -0,0 +1,53 @@
+/** The wire shape, identical to the server's `CipherBox`. */
+export interface CipherBox {
+    alg: 'aes-256-gcm';
+    nonce: string;
+    ciphertext: string;
+}
+/** HKDF-SHA256, the same construction and parameter order as `hkdfSync`. */
+export declare function deriveKey(secret: Uint8Array, salt: Uint8Array, info: string, length?: number): Uint8Array;
+/**
+ * Seal under a key, with AAD bound but not encrypted.
+ *
+ * `randomBytes` comes from the platform: `crypto.getRandomValues` exists in
+ * every browser and in Bun, and a nonce from anywhere else is not a nonce.
+ */
+export declare function sealWithKey(key: Uint8Array, plaintext: Uint8Array, aad: string): CipherBox;
+/** Open a box. Throws on a wrong key, a wrong AAD, or any modification. */
+export declare function openWithKey(key: Uint8Array, box: CipherBox, aad: string): Uint8Array;
+/**
+ * Sealing to a PUBLIC key, so the holder of the private half is the only reader.
+ *
+ * This exists because the server was handing custodians their raw Shamir share
+ * and trusting them to report that both envelopes opened. Capturing one
+ * enrolment response therefore bypassed both recovery factors permanently, and
+ * the two factor "tests" were attestations by the client rather than evidence.
+ *
+ * With this, the client derives a wrapping key pair from each factor and sends
+ * only the public halves. The server seals the share to those and never emits
+ * plaintext — so a captured response is ciphertext, and opening it requires the
+ * factor itself.
+ *
+ * X25519 + HKDF-SHA256 + AES-256-GCM, with the ephemeral public key carried in
+ * the box. Nothing bespoke: the ephemeral-static shape is what every sealed-box
+ * construction uses, and doing it by hand is how people lose the AAD.
+ */
+export interface SealedToKey extends CipherBox {
+    /** base64 — the ephemeral public key this box was sealed with. */
+    ephemeral: string;
+}
+/** Seal to a recipient's public key. */
+export declare function sealToKey(recipientPublicKey: Uint8Array, plaintext: Uint8Array, aad: string): SealedToKey;
+/** Open a box sealed to this private key. */
+export declare function openFromKey(recipientSecretKey: Uint8Array, box: SealedToKey, aad: string): Uint8Array;
+/**
+ * A wrapping key pair derived from factor material.
+ *
+ * Deterministic, because a custodian must reproduce the same private key on a
+ * different machine months later from the same passkey or the same words. The
+ * factor never leaves the caller — only the public half is ever sent.
+ */
+export declare function wrappingKeyPair(factorMaterial: Uint8Array, info: string): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};

package/dist/custody-crypto.js

@@ -0,0 +1,89 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/custody-crypto.ts
+import { gcm } from "@noble/ciphers/aes.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+var KEY_BYTES = 32;
+var NONCE_BYTES = 12;
+var toBase64 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+var fromBase64 = (value) => {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+var utf8 = (value) => new TextEncoder().encode(value);
+function deriveKey(secret, salt, info, length = KEY_BYTES) {
+  return hkdf(sha256, secret, salt, utf8(info), length);
+}
+function sealWithKey(key, plaintext, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const sealed = gcm(key, nonce, utf8(aad)).encrypt(plaintext);
+  return { alg: "aes-256-gcm", nonce: toBase64(nonce), ciphertext: toBase64(sealed) };
+}
+function openWithKey(key, box, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  if (box.alg !== "aes-256-gcm")
+    throw new Error(`custody: unknown algorithm ${box.alg}`);
+  return gcm(key, fromBase64(box.nonce), utf8(aad)).decrypt(fromBase64(box.ciphertext));
+}
+var WRAP_INFO = "forgezero:custody:wrap:v1";
+var wrapKey = (shared, ephemeral, recipient) => hkdf(sha256, shared, concatBytes(ephemeral, recipient), utf8(WRAP_INFO), 32);
+function concatBytes(left, right) {
+  const out = new Uint8Array(left.length + right.length);
+  out.set(left, 0);
+  out.set(right, left.length);
+  return out;
+}
+function sealToKey(recipientPublicKey, plaintext, aad) {
+  const ephemeralSecret = x25519.utils.randomSecretKey();
+  const ephemeralPublic = x25519.getPublicKey(ephemeralSecret);
+  const shared = x25519.getSharedSecret(ephemeralSecret, recipientPublicKey);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublicKey);
+  try {
+    return { ...sealWithKey(key, plaintext, aad), ephemeral: toBase64(ephemeralPublic) };
+  } finally {
+    key.fill(0);
+    ephemeralSecret.fill(0);
+  }
+}
+function openFromKey(recipientSecretKey, box, aad) {
+  const ephemeralPublic = fromBase64(box.ephemeral);
+  const recipientPublic = x25519.getPublicKey(recipientSecretKey);
+  const shared = x25519.getSharedSecret(recipientSecretKey, ephemeralPublic);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublic);
+  try {
+    return openWithKey(key, box, aad);
+  } finally {
+    key.fill(0);
+  }
+}
+function wrappingKeyPair(factorMaterial, info) {
+  const secretKey = hkdf(sha256, factorMaterial, utf8("forgezero:custody:wrapkey:v1"), utf8(info), 32);
+  return { secretKey, publicKey: x25519.getPublicKey(secretKey) };
+}
+export {
+  wrappingKeyPair,
+  sealWithKey,
+  sealToKey,
+  openWithKey,
+  openFromKey,
+  deriveKey
+};

package/dist/custody-share.d.ts

@@ -0,0 +1,117 @@
+import { type CipherBox, type SealedToKey } from './custody-crypto';
+export interface SealedShare {
+    shareIndex: number;
+    passkeyEnvelope: CipherBox;
+    phraseEnvelope: CipherBox;
+    /** base64 — the HKDF salt for the phrase key and the verifier. */
+    phraseSalt: string;
+    /** hex — proves the right phrase without being able to rebuild it. */
+    phraseVerifier: string;
+}
+type EnvelopeKind = 'passkey' | 'phrase';
+/** The x-coordinate a share was cut at — its custodian-facing share number. */
+export declare function shareIndexOf(share: Uint8Array): number;
+/**
+ * Seal one share under BOTH factors.
+ *
+ * The two `sealWithKey` calls are siblings: the same `share` goes into each and
+ * neither output is an input to the other. That is what makes recovery an OR —
+ * lose the passkey, open with the phrase.
+ */
+export declare function sealShare(args: {
+    share: Uint8Array;
+    custodianKey: string;
+    passkeyPrfOutput: Uint8Array;
+    phraseWords: string[];
+}): SealedShare;
+/** Open the share with the passkey alone. The phrase is not consulted. */
+export declare function openShareWithPasskey(sealed: SealedShare, custodianKey: string, passkeyPrfOutput: Uint8Array): Uint8Array;
+/** Open the share with the phrase alone. The passkey is not consulted. */
+export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: string, phraseWords: string[]): Uint8Array;
+/**
+ * The public halves a custodian offers so the server can seal to them.
+ *
+ * The server used to hand over the raw Shamir share and trust the client to
+ * report that both envelopes opened. Capturing one enrolment response therefore
+ * bypassed both recovery factors permanently, and the factor "tests" were
+ * attestations rather than evidence.
+ *
+ * These are derived from the factors themselves and are deterministic, so a
+ * custodian reproduces the same private halves months later on a different
+ * machine from the same passkey or the same words. Only the public halves are
+ * ever sent.
+ */
+export interface WrappingKeys {
+    passkeyPublicKey: string;
+    phrasePublicKey: string;
+    phraseSalt: string;
+    phraseVerifier: string;
+}
+/** The private half for one factor. Never leaves the machine that made it. */
+export declare function passkeyWrappingKey(custodianKey: string, passkeyPrfOutput: Uint8Array): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** The same for the phrase, over the salt that will be stored beside it. */
+export declare function phraseWrappingKey(custodianKey: string, phraseWords: string[], salt: Uint8Array): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** Everything the server needs, and nothing it must not have. */
+export declare function wrappingKeysFor(args: {
+    custodianKey: string;
+    passkeyPrfOutput: Uint8Array;
+    phraseWords: string[];
+}): WrappingKeys;
+/** Open something the server sealed to one of those public keys. */
+export declare function openSealedToFactor(args: {
+    custodianKey: string;
+    factor: EnvelopeKind;
+    box: SealedToKey;
+    passkeyPrfOutput?: Uint8Array;
+    phraseWords?: string[];
+    phraseSalt?: 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;
+/**
+ * A share plus a probe, sealed together.
+ *
+ * The probe is DIFFERENT in each envelope, and that difference is what makes
+ * the two factor tests independent. Sealing only the share would let a client
+ * that opened the passkey envelope answer the phrase test with the same bytes —
+ * proving one factor and being credited with both, which is the attestation
+ * problem this whole change exists to remove.
+ *
+ * Fixed 32-byte probe at the front, so splitting needs no length prefix and a
+ * truncated envelope fails the GCM tag rather than being parsed.
+ */
+export declare const PROBE_BYTES = 32;
+export declare function joinProbeAndShare(probe: Uint8Array, share: Uint8Array): Uint8Array;
+export declare function splitProbeAndShare(opened: Uint8Array): {
+    probe: Uint8Array;
+    share: Uint8Array;
+};
+/**
+ * Open one factor's envelope from the sealed record.
+ *
+ * Takes the whole record rather than a single box, because the phrase salt
+ * lives IN that record and is public — asking every caller to carry it
+ * separately meant each one had somewhere to lose it, and losing it surfaces as
+ * `atob` complaining about invalid characters rather than as anything about
+ * custody.
+ */
+export declare function openFactorEnvelope(args: {
+    sealed: SealedShare & {
+        passkeyEnvelope: SealedToKey;
+        phraseEnvelope: SealedToKey;
+    };
+    custodianKey: string;
+    factor: EnvelopeKind;
+    passkeyPrfOutput?: Uint8Array;
+    phraseWords?: string[];
+}): {
+    probe: Uint8Array;
+    share: Uint8Array;
+};
+export {};

package/dist/custody-share.js

@@ -0,0 +1,313 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/custody-crypto.ts
+import { gcm } from "@noble/ciphers/aes.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+var KEY_BYTES = 32;
+var NONCE_BYTES = 12;
+var toBase64 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+var fromBase64 = (value) => {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+var utf8 = (value) => new TextEncoder().encode(value);
+function deriveKey(secret, salt, info, length = KEY_BYTES) {
+  return hkdf(sha256, secret, salt, utf8(info), length);
+}
+function sealWithKey(key, plaintext, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const sealed = gcm(key, nonce, utf8(aad)).encrypt(plaintext);
+  return { alg: "aes-256-gcm", nonce: toBase64(nonce), ciphertext: toBase64(sealed) };
+}
+function openWithKey(key, box, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  if (box.alg !== "aes-256-gcm")
+    throw new Error(`custody: unknown algorithm ${box.alg}`);
+  return gcm(key, fromBase64(box.nonce), utf8(aad)).decrypt(fromBase64(box.ciphertext));
+}
+var WRAP_INFO = "forgezero:custody:wrap:v1";
+var wrapKey = (shared, ephemeral, recipient) => hkdf(sha256, shared, concatBytes(ephemeral, recipient), utf8(WRAP_INFO), 32);
+function concatBytes(left, right) {
+  const out = new Uint8Array(left.length + right.length);
+  out.set(left, 0);
+  out.set(right, left.length);
+  return out;
+}
+function sealToKey(recipientPublicKey, plaintext, aad) {
+  const ephemeralSecret = x25519.utils.randomSecretKey();
+  const ephemeralPublic = x25519.getPublicKey(ephemeralSecret);
+  const shared = x25519.getSharedSecret(ephemeralSecret, recipientPublicKey);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublicKey);
+  try {
+    return { ...sealWithKey(key, plaintext, aad), ephemeral: toBase64(ephemeralPublic) };
+  } finally {
+    key.fill(0);
+    ephemeralSecret.fill(0);
+  }
+}
+function openFromKey(recipientSecretKey, box, aad) {
+  const ephemeralPublic = fromBase64(box.ephemeral);
+  const recipientPublic = x25519.getPublicKey(recipientSecretKey);
+  const shared = x25519.getSharedSecret(recipientSecretKey, ephemeralPublic);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublic);
+  try {
+    return openWithKey(key, box, aad);
+  } finally {
+    key.fill(0);
+  }
+}
+function wrappingKeyPair(factorMaterial, info) {
+  const secretKey = hkdf(sha256, factorMaterial, utf8("forgezero:custody:wrapkey:v1"), utf8(info), 32);
+  return { secretKey, publicKey: x25519.getPublicKey(secretKey) };
+}
+
+// src/phrase.ts
+import { entropyToMnemonic, mnemonicToSeedSync, validateMnemonic } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { hkdf as hkdf2 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+import { toHex } from "@forgezero/access/security";
+var ENCODER = new TextEncoder;
+var randomBytes = (length) => crypto.getRandomValues(new Uint8Array(length));
+var PHRASE_WORDS = 24;
+var ENTROPY_BYTES = 32;
+var PHRASE_SALT_BYTES = 16;
+var KEY_BYTES2 = 32;
+var KEY_INFO = "forgezero:custodian:phrase-key:v1";
+var VERIFIER_INFO = "forgezero:custodian:phrase-verifier:v1";
+function canonical(words) {
+  return words.map((word) => word.normalize("NFKD").trim().toLowerCase()).join(" ");
+}
+function shapeIsValid(words) {
+  if (!Array.isArray(words) || words.length !== PHRASE_WORDS)
+    return false;
+  return words.every((word) => typeof word === "string" && word.trim().length > 0);
+}
+function generatePhrase() {
+  const entropy = randomBytes(ENTROPY_BYTES);
+  try {
+    const words = entropyToMnemonic(entropy, wordlist).split(" ");
+    if (words.length !== PHRASE_WORDS) {
+      throw new Error("phrase: wordlist produced an unexpected phrase length");
+    }
+    return words;
+  } finally {
+    entropy.fill(0);
+  }
+}
+function validatePhrase(words) {
+  if (!shapeIsValid(words))
+    return false;
+  return validateMnemonic(canonical(words), wordlist);
+}
+function newSalt() {
+  return Uint8Array.from(randomBytes(PHRASE_SALT_BYTES));
+}
+function assertSalt(salt) {
+  if (!(salt instanceof Uint8Array) || salt.length < PHRASE_SALT_BYTES) {
+    throw new Error(`phrase: salt must be at least ${PHRASE_SALT_BYTES} bytes`);
+  }
+}
+function bip39Seed(words) {
+  if (!validatePhrase(words))
+    throw new Error("INVALID_PHRASE");
+  return mnemonicToSeedSync(canonical(words));
+}
+function phraseToKey(words, salt) {
+  assertSalt(salt);
+  const seed = bip39Seed(words);
+  try {
+    return hkdf2(sha2562, seed, salt, ENCODER.encode(KEY_INFO), KEY_BYTES2);
+  } finally {
+    seed.fill(0);
+  }
+}
+function phraseVerifier(words, salt) {
+  assertSalt(salt);
+  const seed = bip39Seed(words);
+  try {
+    return toHex(hkdf2(sha2562, seed, salt, ENCODER.encode(VERIFIER_INFO), KEY_BYTES2));
+  } finally {
+    seed.fill(0);
+  }
+}
+
+// src/custody-share.ts
+var KEY_BYTES3 = 32;
+var MIN_PRF_BYTES = 32;
+var PASSKEY_KEY_SALT = "forgezero:custodian:passkey:v1";
+var utf82 = (value) => new TextEncoder().encode(value);
+var toBase642 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+var fromBase642 = (value) => {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+function passkeyKey(custodianKey, prfOutput) {
+  if (!(prfOutput instanceof Uint8Array) || prfOutput.length < MIN_PRF_BYTES) {
+    throw new Error(`custody-share: PRF output must be at least ${MIN_PRF_BYTES} bytes`);
+  }
+  const info = `forgezero:custodian:passkey-key:v1:${custodianKey.length}:${custodianKey}`;
+  return deriveKey(prfOutput, utf82(PASSKEY_KEY_SALT), info, KEY_BYTES3);
+}
+function shareAad(custodianKey, kind, shareIndex) {
+  return `forgezero:share:v1:${kind}:${shareIndex}:${custodianKey.length}:${custodianKey}`;
+}
+function assertCustodianKey(custodianKey) {
+  if (typeof custodianKey !== "string" || custodianKey.length === 0) {
+    throw new Error("custody-share: custodianKey must be a non-empty string");
+  }
+}
+function shareIndexOf(share) {
+  if (share.length < 2)
+    throw new Error("custody-share: malformed share");
+  const x = share[0];
+  if (x < 1)
+    throw new Error("custody-share: share index 0 is reserved");
+  return x;
+}
+function sealShare(args) {
+  const { share, custodianKey, passkeyPrfOutput, phraseWords } = args;
+  assertCustodianKey(custodianKey);
+  const shareIndex = shareIndexOf(share);
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  const salt = newSalt();
+  const keyFromPasskey = passkeyKey(custodianKey, passkeyPrfOutput);
+  const keyFromPhrase = phraseToKey(phraseWords, salt);
+  try {
+    return {
+      shareIndex,
+      passkeyEnvelope: sealWithKey(keyFromPasskey, share, shareAad(custodianKey, "passkey", shareIndex)),
+      phraseEnvelope: sealWithKey(keyFromPhrase, share, shareAad(custodianKey, "phrase", shareIndex)),
+      phraseSalt: toBase642(salt),
+      phraseVerifier: phraseVerifier(phraseWords, salt)
+    };
+  } finally {
+    keyFromPasskey.fill(0);
+    keyFromPhrase.fill(0);
+  }
+}
+function openShareWithPasskey(sealed, custodianKey, passkeyPrfOutput) {
+  assertCustodianKey(custodianKey);
+  const key = passkeyKey(custodianKey, passkeyPrfOutput);
+  try {
+    return openWithKey(key, sealed.passkeyEnvelope, shareAad(custodianKey, "passkey", sealed.shareIndex));
+  } finally {
+    key.fill(0);
+  }
+}
+function openShareWithPhrase(sealed, custodianKey, phraseWords) {
+  assertCustodianKey(custodianKey);
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  const salt = fromBase642(sealed.phraseSalt);
+  const key = phraseToKey(phraseWords, salt);
+  try {
+    return openWithKey(key, sealed.phraseEnvelope, shareAad(custodianKey, "phrase", sealed.shareIndex));
+  } finally {
+    key.fill(0);
+  }
+}
+var wrapInfo = (custodianKey, kind) => `forgezero:custody:wrap:v1:${kind}:${custodianKey.length}:${custodianKey}`;
+function passkeyWrappingKey(custodianKey, passkeyPrfOutput) {
+  assertCustodianKey(custodianKey);
+  return wrappingKeyPair(passkeyKey(custodianKey, passkeyPrfOutput), wrapInfo(custodianKey, "passkey"));
+}
+function phraseWrappingKey(custodianKey, phraseWords, salt) {
+  assertCustodianKey(custodianKey);
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  return wrappingKeyPair(phraseToKey(phraseWords, salt), wrapInfo(custodianKey, "phrase"));
+}
+function wrappingKeysFor(args) {
+  const salt = newSalt();
+  const passkey = passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput);
+  const phrase = phraseWrappingKey(args.custodianKey, args.phraseWords, salt);
+  try {
+    return {
+      passkeyPublicKey: toBase642(passkey.publicKey),
+      phrasePublicKey: toBase642(phrase.publicKey),
+      phraseSalt: toBase642(salt),
+      phraseVerifier: phraseVerifier(args.phraseWords, salt)
+    };
+  } finally {
+    passkey.secretKey.fill(0);
+    phrase.secretKey.fill(0);
+  }
+}
+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));
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+var factorWrapAad = (custodianKey, factor) => wrapInfo(custodianKey, factor);
+var PROBE_BYTES = 32;
+function joinProbeAndShare(probe, share) {
+  if (probe.length !== PROBE_BYTES)
+    throw new Error("custody-share: probe must be 32 bytes");
+  const out = new Uint8Array(probe.length + share.length);
+  out.set(probe, 0);
+  out.set(share, probe.length);
+  return out;
+}
+function splitProbeAndShare(opened) {
+  if (opened.length <= PROBE_BYTES)
+    throw new Error("custody-share: envelope is too short");
+  return { probe: opened.slice(0, PROBE_BYTES), share: opened.slice(PROBE_BYTES) };
+}
+function openFactorEnvelope(args) {
+  const box = args.factor === "passkey" ? args.sealed.passkeyEnvelope : args.sealed.phraseEnvelope;
+  return splitProbeAndShare(openSealedToFactor({
+    custodianKey: args.custodianKey,
+    factor: args.factor,
+    box,
+    passkeyPrfOutput: args.passkeyPrfOutput,
+    phraseWords: args.phraseWords,
+    phraseSalt: args.sealed.phraseSalt
+  }));
+}
+export {
+  wrappingKeysFor,
+  splitProbeAndShare,
+  shareIndexOf,
+  sealShare,
+  phraseWrappingKey,
+  passkeyWrappingKey,
+  openShareWithPhrase,
+  openShareWithPasskey,
+  openSealedToFactor,
+  openFactorEnvelope,
+  joinProbeAndShare,
+  factorWrapAad,
+  PROBE_BYTES
+};

package/dist/outbox.d.ts

@@ -47,6 +47,8 @@ export declare class OutboxError extends Error {
 export declare const EVENT_STATES: readonly ["pending", "delivering", "delivered", "dead"];
 export type EventState = (typeof EVENT_STATES)[number];
 export interface OutboxEvent {
+    /** Set when a drainer claims it; proves ownership at settle time. */
+    claimToken?: string;
     id: string;
     type: string;
     /** The aggregate this concerns. Events sharing one are delivered in order. */
@@ -134,7 +136,14 @@ export interface OutboxStore {
         nowMs: number;
         claimTtlMs: number;
     }): Promise<OutboxEvent[]>;
-    settle(id: string, patch: Partial<OutboxEvent>): Promise<void>;
+    /**
+     * `claimToken` proves the caller still owns this event.
+     *
+     * Without it a drainer whose lease had expired could overwrite the result of
+     * the drainer that took over, landing an old outcome on top of a newer one.
+     * Optional so an in-memory store that cannot lose ownership need not carry it.
+     */
+    settle(id: string, patch: Partial<OutboxEvent>, claimToken?: string): Promise<void>;
     byState(state: EventState, limit?: number): Promise<OutboxEvent[]>;
     get(id: string): Promise<OutboxEvent | null>;
 }

package/dist/outbox.js

@@ -27,13 +27,18 @@ function backoffMs(attempts, policy = DEFAULT_POLICY, random = Math.random) {
   const exponential = Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempts - 1), policy.maxDelayMs);
   return Math.round(exponential * (1 + policy.jitter * random()));
 }
+function randomSuffix() {
+  const bytes = new Uint8Array(4);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 function createOutbox(options) {
   const policy = { ...DEFAULT_POLICY, ...options.policy };
   const now = options.now ?? Date.now;
   const random = options.random ?? Math.random;
   const drainerId = options.drainerId ?? `drainer-${Math.floor(Math.random() * 1e9).toString(36)}`;
   let sequence = 0;
-  const nextId = () => `evt_${now().toString(36)}_${(sequence += 1).toString(36)}`;
+  const nextId = () => `evt_${now().toString(36)}_${(sequence += 1).toString(36)}_${randomSuffix()}`;
   async function settleOne(event) {
     let result;
     try {
@@ -47,7 +52,7 @@ function createOutbox(options) {
         deliveredAtMs: now(),
         claimedBy: undefined,
         claimedUntilMs: undefined
-      });
+      }, event.claimToken);
       return "delivered";
     }
     const attempts = event.attempts + 1;
@@ -67,7 +72,7 @@ function createOutbox(options) {
         lastError: result.error,
         claimedBy: undefined,
         claimedUntilMs: undefined
-      });
+      }, event.claimToken);
       options.onDeadLetter?.(dead);
       return "dead";
     }