signet-protocol 1.10.0 → 1.11.0

package/dist/utils.js

@@ -18,4 +18,131 @@ export function constantTimeEqual(a, b) {
     }
     return diff === 0;
 }
+/**
+ * One character class for text that is shown to people: C0 controls, DEL, C1
+ * controls, Arabic letter mark (U+061C), zero-width and LRM/RLM (U+200B-U+200F),
+ * line/paragraph separators and bidi embeddings/overrides (U+2028-U+202E), and
+ * bidi isolates (U+2066-U+2069). Not global: build a `g` copy to strip.
+ */
+export const UNSAFE_TEXT_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2066-\u2069]/u;
+/**
+ * `UNSAFE_TEXT_CHARS` minus U+200D (zero-width joiner), which is not a bidi
+ * control and is needed for emoji sequences, plus other invisible/deprecated-
+ * format characters a label has no legitimate use for: soft hyphen (U+00AD),
+ * Mongolian vowel separator (U+180E), word joiner and the deprecated invisible
+ * math operators (U+2060-U+2064), and the BOM / zero width no-break space
+ * (U+FEFF). This is a fixed denylist only; it does not cover every Unicode
+ * "format" (Cf) or Default_Ignorable code point (variation selectors, emoji
+ * tag characters, Hangul fillers, Arabic number-sign marks, deprecated music
+ * format controls, ...). Use `isSafeLabel` to validate labels \u2014 it checks
+ * this denylist plus those two Unicode categories, carving out only the
+ * narrow, positionally-constrained exceptions emoji sequences require.
+ */
+export const UNSAFE_LABEL_CHARS = /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b\u200c\u200e\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/u;
+const CF_OR_DEFAULT_IGNORABLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}]/u;
+const EXTENDED_PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
+const KEYCAP_BASE = /[#*0-9]/;
+// A single unpaired UTF-16 surrogate is not a valid code point. In `u`-mode a
+// correctly paired surrogate combines into one astral code point first and
+// never matches this class; only a lone (unpaired) half does.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+const ZWJ = 0x200d;
+const VS15 = 0xfe0e, VS16 = 0xfe0f;
+const SKIN_TONE_MIN = 0x1f3fb, SKIN_TONE_MAX = 0x1f3ff;
+const TAG_CHAR_MIN = 0xe0020, TAG_CHAR_MAX = 0xe007e, TAG_CANCEL = 0xe007f, FLAG_BASE = 0x1f3f4;
+// RGI emoji tag sequences: only these three UK subdivision flags are
+// well-formed. Each entry is the tag-character run (base and cancel tag
+// excluded) spelling the ISO 3166-2 subdivision code in lowercase ASCII,
+// shifted into the U+E0000 tag-character plane.
+const RGI_FLAG_TAG_SEQUENCES = ['gbeng', 'gbsct', 'gbwls'].map(code => Array.from(code, ch => 0xe0000 + ch.codePointAt(0)));
+/**
+ * Whether `codePoints[index]` is "an emoji element" for the zero-width-joiner
+ * rule below: an Extended_Pictographic code point itself, or U+FE0F / an
+ * emoji skin-tone modifier (U+1F3FB-1F3FF) that directly follows one.
+ */
+function endsInEmojiElement(codePoints, index) {
+    if (index < 0)
+        return false;
+    const ch = codePoints[index];
+    if (EXTENDED_PICTOGRAPHIC.test(ch))
+        return true;
+    const cp = ch.codePointAt(0);
+    if (cp !== VS16 && !(cp >= SKIN_TONE_MIN && cp <= SKIN_TONE_MAX))
+        return false;
+    const prev = codePoints[index - 1];
+    return prev !== undefined && EXTENDED_PICTOGRAPHIC.test(prev);
+}
+/**
+ * A label is unsafe if it contains a lone (unpaired) UTF-16 surrogate, any
+ * `UNSAFE_LABEL_CHARS` character, or any Unicode format (Cf) or
+ * Default_Ignorable_Code_Point code point, EXCEPT the narrow in-context uses
+ * emoji sequences need:
+ *
+ *  1. U+200D (ZWJ) only between two emoji elements: the code point before it
+ *     ends in an emoji element (see `endsInEmojiElement`) and the code point
+ *     after it is Extended_Pictographic. A leading, trailing or doubled ZWJ,
+ *     or one between ordinary letters, is rejected.
+ *  2. U+FE0E / U+FE0F (text/emoji variation selectors) only directly after
+ *     an Extended_Pictographic code point or a keycap base ([#*0-9]). Every
+ *     other variation selector (U+FE00-FE0D, U+E0100-E01EF) is rejected
+ *     everywhere.
+ *  3. Tag characters U+E0020-E007E only inside one of the three RGI UK
+ *     subdivision emoji flag sequences: U+1F3F4 (waving black flag) followed
+ *     by the exact tag-character spelling of "gbeng", "gbsct" or "gbwls"
+ *     then the cancel tag U+E007F, with nothing else in between. Any other
+ *     tag run — a different or misspelled subdivision code, extra or missing
+ *     tag characters, a hidden payload, a missing/extra cancel tag, or tag
+ *     characters with no U+1F3F4 base — is rejected, as is U+E0001 anywhere.
+ *
+ * Iterates by code point, not UTF-16 code unit.
+ */
+export function isSafeLabel(label) {
+    if (LONE_SURROGATE.test(label) || UNSAFE_LABEL_CHARS.test(label))
+        return false;
+    const codePoints = Array.from(label);
+    // Indices that are part of one of the three well-formed RGI subdivision
+    // flag tag sequences: the exact tag-character spelling plus its cancel tag,
+    // immediately following a U+1F3F4.
+    const reservedTagIndex = new Set();
+    for (let i = 0; i < codePoints.length; i++) {
+        if (codePoints[i].codePointAt(0) !== FLAG_BASE)
+            continue;
+        for (const seq of RGI_FLAG_TAG_SEQUENCES) {
+            const cancelIndex = i + 1 + seq.length;
+            if (cancelIndex >= codePoints.length)
+                continue;
+            const matchesSpelling = seq.every((cp, k) => codePoints[i + 1 + k].codePointAt(0) === cp);
+            if (matchesSpelling && codePoints[cancelIndex].codePointAt(0) === TAG_CANCEL) {
+                for (let k = i + 1; k <= cancelIndex; k++)
+                    reservedTagIndex.add(k);
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < codePoints.length; i++) {
+        const ch = codePoints[i];
+        if (!CF_OR_DEFAULT_IGNORABLE.test(ch))
+            continue;
+        const cp = ch.codePointAt(0);
+        if (cp === ZWJ) {
+            const next = codePoints[i + 1];
+            if (endsInEmojiElement(codePoints, i - 1) && next !== undefined && EXTENDED_PICTOGRAPHIC.test(next))
+                continue;
+            return false;
+        }
+        if (cp === VS15 || cp === VS16) {
+            const prev = codePoints[i - 1];
+            if (prev !== undefined && (EXTENDED_PICTOGRAPHIC.test(prev) || KEYCAP_BASE.test(prev)))
+                continue;
+            return false;
+        }
+        if ((cp >= TAG_CHAR_MIN && cp <= TAG_CHAR_MAX) || cp === TAG_CANCEL) {
+            if (reservedTagIndex.has(i))
+                continue;
+            return false;
+        }
+        return false;
+    }
+    return true;
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,UAAU,SAAS,CAAC,GAAe;IACvC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAa,EAAE,CAAa;IAC5D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/vault-checkpoint.d.ts

@@ -0,0 +1,50 @@
+export declare const VAULT_EVENT_KIND = 30078;
+export declare const MAX_VAULT_CHUNKS = 32;
+export declare const MAX_VAULT_DEVICES = 16;
+export declare const MAX_VAULT_CONTROL_BYTES: number;
+export declare const MAX_VAULT_CHUNK_BYTES = 100000;
+export interface VaultChunkRef {
+    /** Exact signed event ID, never a mutable latest-by-tag lookup. */
+    eventId: string;
+    author: string;
+    /** SHA-256 of the UTF-8 encrypted event content. */
+    contentHash: string;
+    contentBytes: number;
+}
+export interface VaultCheckpoint {
+    v: 1;
+    purpose: string;
+    rotation: number;
+    sequence: number;
+    /** SHA-256 of the complete plaintext, checked before accepting a restored copy. */
+    revision: string;
+    /** Device whose independently replaceable checkpoint this is. */
+    publisher?: string;
+    devicePubkeys: string[];
+    /** Ordered chunk references; empty datasets still have one encrypted chunk. */
+    chunks: VaultChunkRef[];
+    /** Optional pointer, exactly rotation + 1; recovery follows it from index zero. */
+    nextRotation?: number;
+}
+/** Publicly computable opaque tag; confidentiality comes from encryption and private keys. */
+export declare function vaultCheckpointTag(author: string, publisher?: string): string;
+/** The single d-tag of a checkpoint-shaped event, or null. Every checkpoint tag
+ * is `vaultCheckpointTag` output: 32 lowercase hex characters. Necessary, not
+ * sufficient: the publisher is encrypted, so the shape cannot prove the tag. */
+export declare function vaultCheckpointShapedTag(event: {
+    tags?: unknown;
+}): string | null;
+export declare function vaultContentHash(content: string): string;
+/** Accept no partial checkpoint. A bad reference must never silently lose data. */
+export declare function parseVaultCheckpoint(raw: string, expected: {
+    purpose: string;
+    rotation: number;
+}): VaultCheckpoint | null;
+/** Integrity check before decrypting. Signature and event-ID verification is also required. */
+export declare function matchesVaultChunk(ref: VaultChunkRef, event: {
+    id: string;
+    pubkey: string;
+    kind: number;
+    content: string;
+}): boolean;
+//# sourceMappingURL=vault-checkpoint.d.ts.map

package/dist/vault-checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-checkpoint.d.ts","sourceRoot":"","sources":["../src/vault-checkpoint.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,gBAAgB,QAAQ,CAAA;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AACnC,eAAO,MAAM,uBAAuB,QAAY,CAAA;AAChD,eAAO,MAAM,qBAAqB,SAAU,CAAA;AAM5C,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,CAAC,CAAA;IACJ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,+EAA+E;IAC/E,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E;AAID;;gFAEgF;AAChF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAKjF;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GAAG,IAAI,CAyBzH;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAInI"}

package/dist/vault-checkpoint.js

@@ -0,0 +1,84 @@
+/** Shared private-vault checkpoint contract. No relay I/O or application data schema. */
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import { parseVaultPurpose } from './vault-keys.js';
+export const VAULT_EVENT_KIND = 30078;
+export const MAX_VAULT_CHUNKS = 32;
+export const MAX_VAULT_DEVICES = 16;
+export const MAX_VAULT_CONTROL_BYTES = 12 * 1024;
+export const MAX_VAULT_CHUNK_BYTES = 100_000;
+const HEX = /^[0-9a-f]{64}$/;
+const encoder = new TextEncoder();
+const uint = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Publicly computable opaque tag; confidentiality comes from encryption and private keys. */
+export function vaultCheckpointTag(author, publisher) {
+    if (!HEX.test(author))
+        throw new Error('Invalid vault author');
+    if (publisher !== undefined && !HEX.test(publisher))
+        throw new Error('Invalid vault publisher');
+    return bytesToHex(hmac(sha256, hexToBytes(author), encoder.encode(`signet-vault-route\u0000checkpoint\u0000${publisher ?? '0'}`))).slice(0, 32);
+}
+const CHECKPOINT_TAG = /^[0-9a-f]{32}$/;
+/** The single d-tag of a checkpoint-shaped event, or null. Every checkpoint tag
+ * is `vaultCheckpointTag` output: 32 lowercase hex characters. Necessary, not
+ * sufficient: the publisher is encrypted, so the shape cannot prove the tag. */
+export function vaultCheckpointShapedTag(event) {
+    if (!event || !Array.isArray(event.tags))
+        return null;
+    const dTags = event.tags.filter((t) => Array.isArray(t) && t[0] === 'd');
+    if (dTags.length !== 1 || dTags[0].length !== 2 || typeof dTags[0][1] !== 'string' || !CHECKPOINT_TAG.test(dTags[0][1]))
+        return null;
+    return dTags[0][1];
+}
+export function vaultContentHash(content) {
+    return bytesToHex(sha256(encoder.encode(content)));
+}
+/** Accept no partial checkpoint. A bad reference must never silently lose data. */
+export function parseVaultCheckpoint(raw, expected) {
+    if (typeof raw !== 'string' || encoder.encode(raw).length > MAX_VAULT_CONTROL_BYTES)
+        return null;
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!object(v) || v.v !== 1 || typeof v.purpose !== 'string' || !parseVaultPurpose(v.purpose)
+        || v.purpose !== expected.purpose || v.rotation !== expected.rotation || !uint(v.rotation) || v.rotation > 0xffff_ffff
+        || !uint(v.sequence) || typeof v.revision !== 'string' || !HEX.test(v.revision))
+        return null;
+    if (!Array.isArray(v.devicePubkeys) || !v.devicePubkeys.length || v.devicePubkeys.length > MAX_VAULT_DEVICES
+        || v.devicePubkeys.some(p => typeof p !== 'string' || !HEX.test(p))
+        || new Set(v.devicePubkeys).size !== v.devicePubkeys.length)
+        return null;
+    if (v.publisher !== undefined && (typeof v.publisher !== 'string' || !v.devicePubkeys.includes(v.publisher)))
+        return null;
+    if (!Array.isArray(v.chunks) || !v.chunks.length || v.chunks.length > MAX_VAULT_CHUNKS)
+        return null;
+    const chunks = [];
+    for (const c of v.chunks) {
+        if (!object(c) || typeof c.eventId !== 'string' || !HEX.test(c.eventId)
+            || typeof c.author !== 'string' || !v.devicePubkeys.includes(c.author)
+            || typeof c.contentHash !== 'string' || !HEX.test(c.contentHash)
+            || !uint(c.contentBytes) || c.contentBytes === 0 || c.contentBytes > MAX_VAULT_CHUNK_BYTES)
+            return null;
+        chunks.push({ eventId: c.eventId, author: c.author, contentHash: c.contentHash, contentBytes: c.contentBytes });
+    }
+    if (new Set(chunks.map(c => c.eventId)).size !== chunks.length)
+        return null;
+    if (v.nextRotation !== undefined && (v.nextRotation !== v.rotation + 1 || v.nextRotation > 0xffff_ffff))
+        return null;
+    return { v: 1, purpose: v.purpose, rotation: v.rotation, sequence: v.sequence,
+        revision: v.revision, ...(v.publisher === undefined ? {} : { publisher: v.publisher }), devicePubkeys: [...v.devicePubkeys], chunks,
+        ...(v.nextRotation === undefined ? {} : { nextRotation: v.nextRotation }) };
+}
+/** Integrity check before decrypting. Signature and event-ID verification is also required. */
+export function matchesVaultChunk(ref, event) {
+    return event.id === ref.eventId && event.pubkey === ref.author && event.kind === VAULT_EVENT_KIND
+        && encoder.encode(event.content).length === ref.contentBytes
+        && vaultContentHash(event.content) === ref.contentHash;
+}
+//# sourceMappingURL=vault-checkpoint.js.map

package/dist/vault-checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-checkpoint.js","sourceRoot":"","sources":["../src/vault-checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/vault-keys.d.ts

@@ -0,0 +1,19 @@
+import type { Identity, TreeRoot } from 'nsec-tree';
+export type VaultDataset = 'profiles' | 'contacts:owner' | 'contacts:bots' | 'credentials' | 'settings' | {
+    dependant: number;
+};
+export declare function vaultPurpose(dataset: VaultDataset): string;
+/** Strict parser: aliases such as dependant-01 would derive a different key. */
+export declare function parseVaultPurpose(purpose: string): VaultDataset | null;
+/** Suitable for Heartwood's per-request context; never a registry persona. */
+export declare function vaultKeyContext(dataset: VaultDataset, rotation?: number): {
+    purpose: string;
+    index: number;
+};
+/** Caller owns and must zeroise the returned child. The supplied root is retained. */
+export declare function deriveVaultIdentity(root: TreeRoot, dataset: VaultDataset, rotation?: number): Identity;
+/** Keep root construction and use in one module instance (roots are opaque).
+ * Caller must zeroise the returned child; the temporary root is always destroyed.
+ */
+export declare function vaultIdentityFromMnemonic(mnemonic: string, dataset: VaultDataset, rotation?: number): Identity;
+//# sourceMappingURL=vault-keys.d.ts.map

package/dist/vault-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-keys.d.ts","sourceRoot":"","sources":["../src/vault-keys.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEnD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,gBAAgB,GAAG,eAAe,GAAG,aAAa,GAAG,UAAU,GACnG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AAWzB,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAO1D;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQtE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,SAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAGvG;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,SAAI,GAAG,QAAQ,CAGjG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,SAAI,GAAG,QAAQ,CAIzG"}

package/dist/vault-keys.js

@@ -0,0 +1,57 @@
+/** Private dataset identities, derived directly from the tree root.
+ * Identity ordinals belong in the purpose; the derivation index is rotation.
+ * This does not change any existing persona derivation.
+ */
+import { derive, fromMnemonic } from 'nsec-tree';
+const FIXED = new Set(['profiles', 'contacts:owner', 'contacts:bots', 'credentials', 'settings']);
+const MAX_INDEX = 0xffff_ffff;
+function ordinal(value) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_INDEX) {
+        throw new Error('Vault ordinal must be an unsigned 32-bit integer');
+    }
+}
+export function vaultPurpose(dataset) {
+    if (typeof dataset === 'string' && FIXED.has(dataset))
+        return `signet:vault:${dataset}`;
+    if (dataset && typeof dataset === 'object' && 'dependant' in dataset) {
+        ordinal(dataset.dependant);
+        return `signet:vault:contacts:dependant-${dataset.dependant}`;
+    }
+    throw new Error('Unknown vault dataset');
+}
+/** Strict parser: aliases such as dependant-01 would derive a different key. */
+export function parseVaultPurpose(purpose) {
+    if (typeof purpose !== 'string' || !purpose.startsWith('signet:vault:'))
+        return null;
+    const suffix = purpose.slice('signet:vault:'.length);
+    if (FIXED.has(suffix))
+        return suffix;
+    const match = /^contacts:dependant-(0|[1-9][0-9]*)$/.exec(suffix);
+    if (!match)
+        return null;
+    const dependant = Number(match[1]);
+    return Number.isInteger(dependant) && dependant <= MAX_INDEX ? { dependant } : null;
+}
+/** Suitable for Heartwood's per-request context; never a registry persona. */
+export function vaultKeyContext(dataset, rotation = 0) {
+    ordinal(rotation);
+    return { purpose: vaultPurpose(dataset), index: rotation };
+}
+/** Caller owns and must zeroise the returned child. The supplied root is retained. */
+export function deriveVaultIdentity(root, dataset, rotation = 0) {
+    const { purpose, index } = vaultKeyContext(dataset, rotation);
+    return derive(root, purpose, index);
+}
+/** Keep root construction and use in one module instance (roots are opaque).
+ * Caller must zeroise the returned child; the temporary root is always destroyed.
+ */
+export function vaultIdentityFromMnemonic(mnemonic, dataset, rotation = 0) {
+    const root = fromMnemonic(mnemonic);
+    try {
+        return deriveVaultIdentity(root, dataset, rotation);
+    }
+    finally {
+        root.destroy();
+    }
+}
+//# sourceMappingURL=vault-keys.js.map

package/dist/vault-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-keys.js","sourceRoot":"","sources":["../src/vault-keys.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAMhD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC,CAAA;AACjG,MAAM,SAAS,GAAG,WAAW,CAAA;AAE7B,SAAS,OAAO,CAAC,KAAa;IAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;IACrE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAqB;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,gBAAgB,OAAO,EAAE,CAAA;IACvF,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,WAAW,IAAI,OAAO,EAAE,CAAC;QACrE,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAC1B,OAAO,mCAAmC,OAAO,CAAC,SAAS,EAAE,CAAA;IAC/D,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAA;AAC1C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAA;IACpF,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAA;IACpD,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,MAAsB,CAAA;IACpD,MAAM,KAAK,GAAG,sCAAsC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACjE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAClC,OAAO,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AACrF,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,OAAqB,EAAE,QAAQ,GAAG,CAAC;IACjE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACjB,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;AAC5D,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,OAAqB,EAAE,QAAQ,GAAG,CAAC;IACrF,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC7D,OAAO,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB,EAAE,OAAqB,EAAE,QAAQ,GAAG,CAAC;IAC7F,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;IACnC,IAAI,CAAC;QAAC,OAAO,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IAAC,CAAC;YACnD,CAAC;QAAC,IAAI,CAAC,OAAO,EAAE,CAAA;IAAC,CAAC;AAC5B,CAAC"}

package/dist/vault-recovery.d.ts

@@ -0,0 +1,99 @@
+import type { NostrEvent } from './types.js';
+import type { VaultCheckpoint } from './vault-checkpoint.js';
+/** A checkpoint dated further than this beyond the reader's clock is rejected,
+ * so one device with a bad clock cannot outrank every later honest head. */
+export declare const VAULT_CLOCK_TOLERANCE_SECONDS = 300;
+type Ready = Extract<VaultReadResult, {
+    state: 'ready';
+}>;
+export type VaultReadResult = {
+    state: 'absent';
+}
+/** `failedRelays`, when known, names the relays that did not answer. */
+ | {
+    state: 'unavailable';
+    failedRelays?: string[];
+} | {
+    state: 'unusable';
+    reason: 'checkpoint' | 'rollback' | 'chunk' | 'revision';
+} | {
+    state: 'ready';
+    plaintext: string;
+    checkpoint: VaultCheckpoint;
+    event: NostrEvent;
+};
+export interface VaultReader {
+    /** Must distinguish an empty reachable query from relay failure (throw).
+     * An error carrying `failedRelays: string[]` is reported in the result. */
+    checkpoints(author: string, dTag?: string): Promise<NostrEvent[]>;
+    /** Exact ID query. Missing data is a failed restore, never an empty dataset. */
+    chunk(eventId: string): Promise<NostrEvent | null>;
+    /** Open the v2 envelope only; sender is the vault key, not the chunk signer. */
+    open(content: string, vaultAuthor: string): Promise<string | null>;
+}
+/** Read one rotation. Callers may fall back to legacy ONLY on `absent`.
+ * Invalid, incomplete, offline and rolled-back backups are distinguishable from
+ * never-migrated accounts. No state is persisted or marked canonical here.
+ * `now` (unix seconds, default the local clock) bounds created_at from above.
+ */
+export declare function readVaultSnapshot(reader: VaultReader, expected: {
+    author: string;
+    purpose: string;
+    rotation: number;
+    minSequence?: number;
+    publisher?: string;
+    now?: number;
+}): Promise<VaultReadResult>;
+/** Read the newest rotation's legacy (publisher-less) checkpoint. Rotations are
+ * contiguous from zero; see `newestRotation` for the revocation boundary. A
+ * `nextRotation` pointer (always rotation + 1) to a rotation with no authentic
+ * checkpoint is damage, not a never-migrated account.
+ *
+ * Any key present in `floors`, whatever its value (including 0), counts as a
+ * rotation this caller has already reached: the walk refuses to land below
+ * the highest such key. Callers must not pre-fill a floor for a rotation they
+ * have not actually reached, or a legitimate read of that rotation would be
+ * refused as a rollback.
+ */
+export declare function readVaultRotations(resolve: (rotation: number) => Promise<{
+    reader: VaultReader;
+    author: string;
+}>, purpose: string, floors?: Readonly<Record<number, number>>, now?: number): Promise<VaultReadResult>;
+export type VaultHeadsResult = Exclude<VaultReadResult, {
+    state: 'ready';
+}> | {
+    state: 'ready';
+    snapshots: Ready[];
+};
+interface HeadsExpected {
+    author: string;
+    purpose: string;
+    rotation: number;
+    sequenceFloors?: Readonly<Record<string, number>>;
+    now?: number;
+}
+/** Mergeable per-device heads prevent last-writer replacement across devices.
+ * Discovery queries only the private vault author. No device roster is public.
+ * Reads one rotation strictly: events without a checkpoint-shaped d-tag are
+ * ignored, then every remaining head must be valid, and more than 16 fails.
+ */
+export declare function readVaultHeads(reader: VaultReader, expected: HeadsExpected): Promise<VaultHeadsResult>;
+/** Read the newest rotation's merged per-device heads. Rotation is a
+ * revocation boundary (see `newestRotation`): heads of a superseded rotation
+ * are never merged, opened or counted, so the rotating writer must carry every
+ * head's state into the new rotation before publishing there. Floors from
+ * `resolve` apply to the rotation that is read.
+ *
+ * `minRotation` is the highest rotation this caller has already reached. If
+ * every relay withholds the true newest rotation's successor, `newestRotation`
+ * cannot distinguish that from a vault that never rotated further, and would
+ * otherwise report a lower rotation's heads as `ready`; a caller-tracked floor
+ * on the walk itself is what catches that withholding.
+ */
+export declare function readVaultHeadRotations(resolve: (rotation: number) => Promise<{
+    reader: VaultReader;
+    author: string;
+    sequenceFloors?: Readonly<Record<string, number>>;
+}>, purpose: string, now?: number, minRotation?: number): Promise<VaultHeadsResult>;
+export {};
+//# sourceMappingURL=vault-recovery.d.ts.map

package/dist/vault-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-recovery.d.ts","sourceRoot":"","sources":["../src/vault-recovery.ts"],"names":[],"mappings":"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"}