signet-protocol 1.10.0 → 1.11.0

package/dist/vault-recovery.js

@@ -0,0 +1,305 @@
+import { verifyEvent } from './crypto.js';
+import { MAX_VAULT_CHUNKS, MAX_VAULT_CONTROL_BYTES, VAULT_EVENT_KIND, matchesVaultChunk, parseVaultCheckpoint, vaultCheckpointShapedTag, vaultCheckpointTag, vaultContentHash } 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 const VAULT_CLOCK_TOLERANCE_SECONDS = 300;
+const MAX_VAULT_HEADS = 16;
+/** Rotations recovery will walk. A vault rotated more than 32 times reads
+ * `unusable`; there is no way past it without raising this bound. */
+const MAX_ROTATION_HOPS = 32;
+const encoder = new TextEncoder();
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+/** Carry the failed relay list from a `VaultRelayError` (or any error with a
+ * string-array `failedRelays`) into the result. */
+function unavailable(error) {
+    const failed = error?.failedRelays;
+    return Array.isArray(failed) && failed.every(f => typeof f === 'string')
+        ? { state: 'unavailable', failedRelays: [...failed] } : { state: 'unavailable' };
+}
+function checkNow(now) {
+    if (!Number.isSafeInteger(now) || now < 0)
+        throw new Error('Vault reader clock must be a non-negative integer');
+    return now;
+}
+function checkMinRotation(minRotation) {
+    if (!Number.isSafeInteger(minRotation) || minRotation < 0) {
+        throw new Error('Vault reader minRotation must be a non-negative integer');
+    }
+    return minRotation;
+}
+/** The highest rotation number a caller's floors already name, ignoring any
+ * non-integer or negative key. -1 when `floors` names none, so a rotation-0
+ * result is never treated as a rollback when nothing has been seen yet. */
+function highestFloorRotation(floors) {
+    let highest = -1;
+    for (const key of Object.keys(floors)) {
+        const rotation = Number(key);
+        if (Number.isInteger(rotation) && rotation >= 0 && rotation > highest)
+            highest = rotation;
+    }
+    return highest;
+}
+/** Ascending (created_at, id): the order used for every newest/tie decision.
+ * Of two events with the same created_at, the lower ID is the newer head,
+ * matching NIP-01 replaceable-event resolution. */
+const older = (a, b) => a.created_at - b.created_at || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0);
+/** Structural, bound and signature checks shared by every checkpoint read. */
+async function authenticCheckpointEvent(event, author, now) {
+    if (!event || event.kind !== VAULT_EVENT_KIND || event.pubkey !== author || typeof event.id !== 'string'
+        || typeof event.content !== 'string' || encoder.encode(event.content).length > MAX_VAULT_CONTROL_BYTES
+        || !Number.isSafeInteger(event.created_at) || event.created_at < 0
+        || event.created_at > now + VAULT_CLOCK_TOLERANCE_SECONDS)
+        return null;
+    const tag = vaultCheckpointShapedTag(event);
+    return tag !== null && await verifyEvent(event) ? tag : 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 async function readVaultSnapshot(reader, expected) {
+    const now = checkNow(expected.now ?? nowSeconds());
+    const tag = vaultCheckpointTag(expected.author, expected.publisher);
+    let candidates;
+    try {
+        candidates = await reader.checkpoints(expected.author, tag);
+    }
+    catch (e) {
+        return unavailable(e);
+    }
+    if (!candidates.length)
+        return { state: 'absent' };
+    if (candidates.length > 128)
+        return { state: 'unusable', reason: 'checkpoint' };
+    // A corrupt newer event does not hide a valid older event. Once a valid signed
+    // event is chosen, however, failed decrypt/schema is not a licence to downgrade.
+    const valid = [];
+    for (const event of candidates) {
+        if (await authenticCheckpointEvent(event, expected.author, now) === tag)
+            valid.push(event);
+    }
+    valid.sort((a, b) => older(b, a));
+    const event = valid[0];
+    if (!event)
+        return { state: 'unusable', reason: 'checkpoint' };
+    let raw;
+    try {
+        raw = await reader.open(event.content, expected.author);
+    }
+    catch {
+        return { state: 'unusable', reason: 'checkpoint' };
+    }
+    const checkpoint = raw === null ? null : parseVaultCheckpoint(raw, expected);
+    if (!checkpoint || checkpoint.publisher !== expected.publisher)
+        return { state: 'unusable', reason: 'checkpoint' };
+    if (checkpoint.sequence < (expected.minSequence ?? 0))
+        return { state: 'unusable', reason: 'rollback' };
+    const parts = [];
+    let totalBytes = 0;
+    for (const ref of checkpoint.chunks) {
+        let chunk;
+        try {
+            chunk = await reader.chunk(ref.eventId);
+        }
+        catch (e) {
+            return unavailable(e);
+        }
+        if (!chunk || typeof chunk.content !== 'string' || !matchesVaultChunk(ref, chunk) || !await verifyEvent(chunk)) {
+            return { state: 'unusable', reason: 'chunk' };
+        }
+        let part;
+        try {
+            part = await reader.open(chunk.content, expected.author);
+        }
+        catch {
+            return { state: 'unusable', reason: 'chunk' };
+        }
+        if (part === null)
+            return { state: 'unusable', reason: 'chunk' };
+        totalBytes += encoder.encode(part).length;
+        if (totalBytes > MAX_VAULT_CHUNKS * 65536)
+            return { state: 'unusable', reason: 'chunk' };
+        parts.push(part);
+    }
+    const plaintext = parts.join('');
+    if (vaultContentHash(plaintext) !== checkpoint.revision)
+        return { state: 'unusable', reason: 'revision' };
+    return { state: 'ready', plaintext, checkpoint, event };
+}
+/** Whether a rotation holds any authentic checkpoint-shaped event (optionally
+ * under one exact tag). Contents are never opened, so nothing written under a
+ * superseded key is decrypted, parsed or counted. */
+async function rotationPresent(reader, author, now, tag) {
+    let events;
+    try {
+        events = await reader.checkpoints(author, tag);
+    }
+    catch (e) {
+        return unavailable(e);
+    }
+    for (const event of events.slice(0, 1024)) {
+        const found = await authenticCheckpointEvent(event, author, now);
+        if (found !== null && (tag === undefined || found === tag))
+            return 'present';
+    }
+    return 'absent';
+}
+/** Find the newest rotation: the first rotation whose successor holds no
+ * authentic checkpoint. Rotation is a revocation boundary: once rotation n + 1
+ * exists, rotation n is never read (only rotation n + 1's key can sign there),
+ * so a holder of a retired key can neither inject heads nor block recovery by
+ * writing to the old rotation, and cannot hide the successor by overwriting
+ * the pointer. Costs one extra resolve and query for the successor.
+ *
+ * A rotation revokes only a holder of THAT rotation's key, not the tree root:
+ * a holder of the root key can derive every rotation regardless, so rotation
+ * is a boundary against a retired per-rotation key, not against root
+ * compromise. This walk can find a rotation older than one a caller has
+ * already read (every relay withholding the successor); callers that track
+ * the highest rotation they have seen must reject a lower result as a
+ * rollback rather than trust it, since "not found" here never means "does
+ * not exist". */
+async function newestRotation(resolve, now, tagFor) {
+    let rotation = 0;
+    let context;
+    try {
+        context = await resolve(0);
+    }
+    catch (e) {
+        return unavailable(e);
+    }
+    for (let hop = 0; hop < MAX_ROTATION_HOPS; hop++) {
+        let next;
+        try {
+            next = await resolve(rotation + 1);
+        }
+        catch (e) {
+            return unavailable(e);
+        }
+        const probe = await rotationPresent(next.reader, next.author, now, tagFor?.(next.author));
+        if (probe === 'absent')
+            return { rotation, context };
+        if (probe !== 'present')
+            return probe;
+        rotation++;
+        context = next;
+    }
+    return { state: 'unusable', reason: 'checkpoint' };
+}
+/** 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 async function readVaultRotations(resolve, purpose, floors = {}, now = nowSeconds()) {
+    checkNow(now);
+    const found = await newestRotation(resolve, now, author => vaultCheckpointTag(author));
+    if (!('context' in found))
+        return found;
+    const { rotation, context } = found;
+    if (rotation < highestFloorRotation(floors))
+        return { state: 'unusable', reason: 'rollback' };
+    const result = await readVaultSnapshot(context.reader, {
+        author: context.author, purpose, rotation, minSequence: floors[rotation], now,
+    });
+    if (result.state === 'absent')
+        return rotation > 0 ? { state: 'unusable', reason: 'checkpoint' } : result;
+    if (result.state === 'ready' && result.checkpoint.nextRotation !== undefined)
+        return { state: 'unusable', reason: 'checkpoint' };
+    return result;
+}
+/** 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 async function readVaultHeads(reader, expected) {
+    const now = checkNow(expected.now ?? nowSeconds());
+    let events;
+    try {
+        events = await reader.checkpoints(expected.author);
+    }
+    catch (e) {
+        return unavailable(e);
+    }
+    const shaped = events.filter(e => !!e && e.pubkey === expected.author && e.kind === VAULT_EVENT_KIND
+        && vaultCheckpointShapedTag(e) !== null);
+    if (!shaped.length)
+        return { state: 'absent' };
+    if (shaped.length > 128)
+        return { state: 'unusable', reason: 'checkpoint' };
+    const heads = new Map();
+    for (const event of shaped) {
+        const tag = await authenticCheckpointEvent(event, expected.author, now);
+        if (tag === null)
+            continue;
+        const previous = heads.get(tag);
+        if (!previous || older(previous, event) < 0)
+            heads.set(tag, event);
+    }
+    if (!heads.size || heads.size > MAX_VAULT_HEADS)
+        return { state: 'unusable', reason: 'checkpoint' };
+    const snapshots = [];
+    for (const [tag, event] of heads) {
+        let raw;
+        try {
+            raw = await reader.open(event.content, expected.author);
+        }
+        catch {
+            return { state: 'unusable', reason: 'checkpoint' };
+        }
+        const checkpoint = raw === null ? null : parseVaultCheckpoint(raw, expected);
+        if (!checkpoint || tag !== vaultCheckpointTag(expected.author, checkpoint.publisher))
+            return { state: 'unusable', reason: 'checkpoint' };
+        const result = await readVaultSnapshot({ ...reader, checkpoints: async () => [event],
+            open: (content, author) => content === event.content ? Promise.resolve(raw) : reader.open(content, author),
+        }, { author: expected.author, purpose: expected.purpose, rotation: expected.rotation, now,
+            publisher: checkpoint.publisher, minSequence: expected.sequenceFloors?.[checkpoint.publisher ?? 'legacy'] });
+        if (result.state !== 'ready')
+            return result;
+        snapshots.push(result);
+    }
+    for (const [publisher, floor] of Object.entries(expected.sequenceFloors ?? {})) {
+        if (floor > 0 && !snapshots.some(s => (s.checkpoint.publisher ?? 'legacy') === publisher))
+            return { state: 'unusable', reason: 'rollback' };
+    }
+    snapshots.sort((a, b) => older(a.event, b.event));
+    return { state: 'ready', snapshots };
+}
+/** 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 async function readVaultHeadRotations(resolve, purpose, now = nowSeconds(), minRotation = 0) {
+    checkNow(now);
+    checkMinRotation(minRotation);
+    const found = await newestRotation(resolve, now);
+    if (!('context' in found))
+        return found;
+    const { rotation, context } = found;
+    if (rotation < minRotation)
+        return { state: 'unusable', reason: 'rollback' };
+    const result = await readVaultHeads(context.reader, { ...context, purpose, rotation, now });
+    if (result.state === 'absent')
+        return rotation > 0 ? { state: 'unusable', reason: 'checkpoint' } : result;
+    if (result.state === 'ready' && result.snapshots.some(s => s.checkpoint.nextRotation !== undefined)) {
+        return { state: 'unusable', reason: 'checkpoint' };
+    }
+    return result;
+}
+//# sourceMappingURL=vault-recovery.js.map

package/dist/vault-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-recovery.js","sourceRoot":"","sources":["../src/vault-recovery.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,gBAAgB,EAClE,iBAAiB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAGxI;4EAC4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAA;AAChD,MAAM,eAAe,GAAG,EAAE,CAAA;AAC1B;qEACqE;AACrE,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAC5B,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AACjC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;AAItD;mDACmD;AACnD,SAAS,WAAW,CAAC,KAAe;IAClC,MAAM,MAAM,GAAI,KAAgD,EAAE,YAAY,CAAA;IAC9E,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QACtE,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA;AACpF,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;IAC/G,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAA;IAC5E,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC;AAED;;2EAE2E;AAC3E,SAAS,oBAAoB,CAAC,MAAwC;IACpE,IAAI,OAAO,GAAG,CAAC,CAAC,CAAA;IAChB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;QAC5B,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,GAAG,OAAO;YAAE,OAAO,GAAG,QAAQ,CAAA;IAC3F,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;mDAEmD;AACnD,MAAM,KAAK,GAAG,CAAC,CAAa,EAAE,CAAa,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEvH,8EAA8E;AAC9E,KAAK,UAAU,wBAAwB,CAAC,KAAiB,EAAE,MAAc,EAAE,GAAW;IACpF,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;WACnG,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,uBAAuB;WACnG,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC;WAC/D,KAAK,CAAC,UAAU,GAAG,GAAG,GAAG,6BAA6B;QAAE,OAAO,IAAI,CAAA;IACxE,MAAM,GAAG,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAA;IAC3C,OAAO,GAAG,KAAK,IAAI,IAAI,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9D,CAAC;AAmBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAmB,EACnB,QAAuH;IAEvH,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC,CAAA;IAClD,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;IACnE,IAAI,UAAwB,CAAA;IAC5B,IAAI,CAAC;QAAC,UAAU,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;IAAC,CAAC;IACvG,IAAI,CAAC,UAAU,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;IAClD,IAAI,UAAU,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAC/E,+EAA+E;IAC/E,iFAAiF;IACjF,MAAM,KAAK,GAAiB,EAAE,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,IAAI,MAAM,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5F,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACjC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACtB,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAC9D,IAAI,GAAkB,CAAA;IACtB,IAAI,CAAC;QAAC,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAAC,CAAC;IAC5H,MAAM,UAAU,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC5E,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAClH,IAAI,UAAU,CAAC,QAAQ,GAAG,CAAC,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IACvG,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,KAAwB,CAAA;QAC5B,IAAI,CAAC;YAAC,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;QAAC,CAAC;QACnF,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QAC/C,CAAC;QACD,IAAI,IAAmB,CAAA;QACvB,IAAI,CAAC;YAAC,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QAAC,CAAC;QACxH,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QAChE,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAA;QACzC,IAAI,UAAU,GAAG,gBAAgB,GAAG,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QACxF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClB,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChC,IAAI,gBAAgB,CAAC,SAAS,CAAC,KAAK,UAAU,CAAC,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IACzG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAA;AACzD,CAAC;AAED;;qDAEqD;AACrD,KAAK,UAAU,eAAe,CAAC,MAAmB,EAAE,MAAc,EAAE,GAAW,EAAE,GAAY;IAE3F,IAAI,MAAoB,CAAA;IACxB,IAAI,CAAC;QAAC,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;IAAC,CAAC;IAC1F,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;QAChE,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,KAAK,GAAG,CAAC;YAAE,OAAO,SAAS,CAAA;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;;;iBAciB;AACjB,KAAK,UAAU,cAAc,CAC3B,OAAyC,EAAE,GAAW,EAAE,MAAmC;IAE3F,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,IAAI,OAAU,CAAA;IACd,IAAI,CAAC;QAAC,OAAO,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;IAAC,CAAC;IACtE,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,iBAAiB,EAAE,GAAG,EAAE,EAAE,CAAC;QACjD,IAAI,IAAO,CAAA;QACX,IAAI,CAAC;YAAC,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAA;QAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;QAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;QACzF,IAAI,KAAK,KAAK,QAAQ;YAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;QACpD,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACrC,QAAQ,EAAE,CAAA;QACV,OAAO,GAAG,IAAI,CAAA;IAChB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;AACpD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAA+E,EAC/E,OAAe,EACf,SAA2C,EAAE,EAC7C,MAAc,UAAU,EAAE;IAE1B,QAAQ,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAA;IACtF,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACvC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,CAAA;IACnC,IAAI,QAAQ,GAAG,oBAAoB,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAC7F,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE;QACrD,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG;KAC9E,CAAC,CAAA;IACF,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACzG,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAChI,OAAO,MAAM,CAAA;AACf,CAAC;AASD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAmB,EAAE,QAAuB;IAC/E,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC,CAAA;IAClD,IAAI,MAAoB,CAAA;IACxB,IAAI,CAAC;QAAC,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAA;IAAC,CAAC;IAC9F,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB;WAC/F,wBAAwB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;IAC1C,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC9C,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IAC3E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,MAAM,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QACvE,IAAI,GAAG,KAAK,IAAI;YAAE,SAAQ;QAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,GAAG,eAAe;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IACnG,MAAM,SAAS,GAAY,EAAE,CAAA;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACjC,IAAI,GAAkB,CAAA;QACtB,IAAI,CAAC;YAAC,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QAAC,CAAC;QAC5H,MAAM,UAAU,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;QAC5E,IAAI,CAAC,UAAU,IAAI,GAAG,KAAK,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QACxI,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC;YAClF,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;SAC3G,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,GAAG;YACvF,SAAS,EAAE,UAAU,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,SAAS,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAA;QAC9G,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO;YAAE,OAAO,MAAM,CAAA;QAC3C,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxB,CAAC;IACD,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/E,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,QAAQ,CAAC,KAAK,SAAS,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAC7I,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IACjD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAE3C,EAAE,OAAe,EAAE,MAAc,UAAU,EAAE,EAAE,WAAW,GAAG,CAAC;IAC9D,QAAQ,CAAC,GAAG,CAAC,CAAA;IACb,gBAAgB,CAAC,WAAW,CAAC,CAAA;IAC7B,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAChD,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACvC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,CAAA;IACnC,IAAI,QAAQ,GAAG,WAAW;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAC5E,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAA;IAC3F,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACzG,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,KAAK,SAAS,CAAC,EAAE,CAAC;QACpG,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IACpD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/vault-relay.d.ts

@@ -0,0 +1,29 @@
+import { RelayClient, type NostrFilter } from './relay.js';
+import type { NostrEvent } from './types.js';
+import type { VaultReader } from './vault-recovery.js';
+/** Matching events one relay may contribute to one query. More fails that relay. */
+export declare const MAX_VAULT_EVENTS_PER_RELAY = 128;
+/** A relay query that did not complete on every relay. `failedRelays` names the
+ * relays that errored, timed out or exceeded the cap. */
+export declare class VaultRelayError extends Error {
+    readonly failedRelays: string[];
+    constructor(message: string, failedRelays: string[]);
+}
+/** EOSE is required: a timed-out empty query is not evidence of absence.
+ * Events are filtered against `filter` (and `accept`, when given) and
+ * de-duplicated before the per-relay cap applies, so unrelated events cannot
+ * crowd out the requested ones. */
+export declare function fetchVaultEvents(relay: Pick<RelayClient, 'subscribe' | 'closeSubscription'>, filter: NostrFilter, timeoutMs?: number, accept?: (event: NostrEvent) => boolean): Promise<NostrEvent[]>;
+/** Relay-backed reader. At most eight valid relay URLs are queried.
+ *
+ * A checkpoint query, empty or not, completes only when EVERY queried relay
+ * answered with EOSE: one relay's "nothing" is not evidence of absence, and one
+ * relay's heads may omit a device head another relay holds. Otherwise it throws
+ * a `VaultRelayError` naming the failed relays, and recovery reports
+ * `unavailable` with `failedRelays`. A permanently dead configured relay keeps
+ * reads unavailable until it is removed from the set. A chunk fetch by exact
+ * ID succeeds as soon as any relay returns it (its hash is pinned); "not found"
+ * again needs every relay. Checkpoint queries drop events without a
+ * checkpoint-shaped d-tag before the per-relay cap. */
+export declare function createVaultRelayReader(relays: readonly string[], open: VaultReader['open']): VaultReader;
+//# sourceMappingURL=vault-relay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vault-relay.d.ts","sourceRoot":"","sources":["../src/vault-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAGtD,oFAAoF;AACpF,eAAO,MAAM,0BAA0B,MAAM,CAAA;AA2B7C;yDACyD;AACzD,qBAAa,eAAgB,SAAQ,KAAK;IACX,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE;gBAAhD,OAAO,EAAE,MAAM,EAAW,YAAY,EAAE,MAAM,EAAE;CAI7D;AAED;;;mCAGmC;AACnC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB,CAAC,EAC1F,MAAM,EAAE,WAAW,EAAE,SAAS,SAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsBxG;AAED;;;;;;;;;;uDAUuD;AACvD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CA6BxG"}

package/dist/vault-relay.js

@@ -0,0 +1,131 @@
+import { RelayClient } from './relay.js';
+import { VAULT_EVENT_KIND, vaultCheckpointShapedTag } from './vault-checkpoint.js';
+/** Matching events one relay may contribute to one query. More fails that relay. */
+export const MAX_VAULT_EVENTS_PER_RELAY = 128;
+const MAX_VAULT_RELAYS = 8;
+/** Must agree with the RelayClient constructor: a URL accepted here but rejected
+ * there would be skipped silently. Plain ws:// is loopback-only (localhost and
+ * 127.0.0.1; RelayClient does not accept [::1]). */
+function validRelay(raw) {
+    try {
+        const url = new URL(raw);
+        return !url.username && !url.password && !url.hash && (url.protocol === 'wss:'
+            || (url.protocol === 'ws:' && ['localhost', '127.0.0.1'].includes(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Client-side re-check of the relay filter. Relays are untrusted, so an event
+ * outside the requested author/kind/id/d-tag is dropped before it counts
+ * towards any limit. */
+function matchesFilter(filter, event) {
+    if (!event || typeof event.id !== 'string' || typeof event.pubkey !== 'string' || !Array.isArray(event.tags))
+        return false;
+    if (filter.ids && !filter.ids.includes(event.id))
+        return false;
+    if (filter.authors && !filter.authors.includes(event.pubkey))
+        return false;
+    if (filter.kinds && !filter.kinds.includes(event.kind))
+        return false;
+    const dTags = filter['#d'];
+    if (dTags && !event.tags.some(t => Array.isArray(t) && t[0] === 'd' && dTags.includes(t[1])))
+        return false;
+    return true;
+}
+/** A relay query that did not complete on every relay. `failedRelays` names the
+ * relays that errored, timed out or exceeded the cap. */
+export class VaultRelayError extends Error {
+    failedRelays;
+    constructor(message, failedRelays) {
+        super(message);
+        this.failedRelays = failedRelays;
+        this.name = 'VaultRelayError';
+    }
+}
+/** EOSE is required: a timed-out empty query is not evidence of absence.
+ * Events are filtered against `filter` (and `accept`, when given) and
+ * de-duplicated before the per-relay cap applies, so unrelated events cannot
+ * crowd out the requested ones. */
+export function fetchVaultEvents(relay, filter, timeoutMs = 10000, accept) {
+    return new Promise((resolve, reject) => {
+        const events = new Map();
+        let subId;
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (subId)
+                relay.closeSubscription(subId);
+            if (error)
+                reject(error);
+            else
+                resolve([...events.values()]);
+        };
+        const timer = setTimeout(() => finish(new Error('Vault query did not complete')), timeoutMs);
+        try {
+            subId = relay.subscribe([filter], event => {
+                if (finished || !matchesFilter(filter, event) || (accept && !accept(event)) || events.has(event.id))
+                    return;
+                if (events.size >= MAX_VAULT_EVENTS_PER_RELAY)
+                    finish(new Error('Vault query exceeds event limit'));
+                else
+                    events.set(event.id, event);
+            }, () => finish());
+            if (finished)
+                relay.closeSubscription(subId);
+        }
+        catch {
+            finish(new Error('Vault query failed'));
+        }
+    });
+}
+/** Relay-backed reader. At most eight valid relay URLs are queried.
+ *
+ * A checkpoint query, empty or not, completes only when EVERY queried relay
+ * answered with EOSE: one relay's "nothing" is not evidence of absence, and one
+ * relay's heads may omit a device head another relay holds. Otherwise it throws
+ * a `VaultRelayError` naming the failed relays, and recovery reports
+ * `unavailable` with `failedRelays`. A permanently dead configured relay keeps
+ * reads unavailable until it is removed from the set. A chunk fetch by exact
+ * ID succeeds as soon as any relay returns it (its hash is pinned); "not found"
+ * again needs every relay. Checkpoint queries drop events without a
+ * checkpoint-shaped d-tag before the per-relay cap. */
+export function createVaultRelayReader(relays, open) {
+    const urls = [...new Set(relays.filter(validRelay))].slice(0, MAX_VAULT_RELAYS);
+    const query = async (filter, accept, enough) => {
+        if (!urls.length)
+            throw new VaultRelayError('No valid vault relays', []);
+        const events = new Map();
+        const failed = [];
+        await Promise.all(urls.map(async (url) => {
+            let relay;
+            try {
+                relay = new RelayClient(url);
+                await relay.connect();
+                const found = await fetchVaultEvents(relay, filter, undefined, accept);
+                for (const e of found)
+                    events.set(e.id, e);
+            }
+            catch {
+                failed.push(url);
+            }
+            finally {
+                relay?.disconnect();
+            }
+        }));
+        const result = [...events.values()];
+        if (failed.length && !(enough && enough(result))) {
+            throw new VaultRelayError(`Vault relays did not all answer: ${failed.length} of ${urls.length} failed`, failed.sort());
+        }
+        return result;
+    };
+    return {
+        checkpoints: (author, dTag) => query({ kinds: [VAULT_EVENT_KIND], authors: [author], ...(dTag ? { '#d': [dTag] } : {}), limit: MAX_VAULT_EVENTS_PER_RELAY }, event => vaultCheckpointShapedTag(event) !== null),
+        chunk: async (id) => (await query({ ids: [id], limit: 1 }, undefined, found => found.some(e => e.id === id))).find(e => e.id === id) ?? null,
+        open,
+    };
+}
+//# sourceMappingURL=vault-relay.js.map

package/dist/vault-relay.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signet-protocol",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Decentralised identity verification protocol for Nostr",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./experimental": {
+      "import": "./dist/experimental.js",
+      "types": "./dist/experimental.d.ts"
     }
   },
   "files": [
@@ -24,7 +28,8 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "keywords": [
     "nostr",
@@ -54,20 +59,20 @@
   "dependencies": {
     "@forgesworn/range-proof": "^2.0.0",
     "@forgesworn/ring-sig": "^3.0.0",
-    "@forgesworn/shamir-words": "^1.0.0",
+    "@forgesworn/shamir-words": "^1.2.0-alpha.1",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
     "@scure/bip39": "^2.0.1",
     "jurisdiction-kit": "^1.0.0",
     "nostr-attestations": "^2.3.1",
-    "nsec-tree": "^1.4.1",
+    "nsec-tree": "^1.6.0-alpha.1",
     "spoken-token": "^2.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "vitest": "^5.0.0"
   },
   "funding": {
     "type": "lightning",

package/src/bonds.ts

@@ -1,5 +1,5 @@
-// Proof-of-Reserve Bond Attestation
-// Non-custodial bond system: verifiers prove Bitcoin address control via BIP-322
+// Bond declaration with BIP-322 address-control proof.
+// This does not prove funds, lock value, or make a bond slashable.
 
 import { BOND_DOMAIN_SEPARATOR, DEFAULT_BOND_MAX_AGE_SECS, VALID_BOND_ADDRESS_TYPES } from './constants.js';
 import { getTagValue } from './validation.js';
@@ -44,7 +44,7 @@ export interface VerifyBondProofOptions {
   verifier?: BIP322Verifier;
   /** Maximum age in seconds (default: DEFAULT_BOND_MAX_AGE_SECS) */
   maxAgeSecs?: number;
-  /** Minimum required amount in satoshis */
+  /** Minimum declared amount in satoshis. This does not verify funds. */
   requiredSats?: number;
   /** Override current time (unix seconds, for testing) */
   now?: number;
@@ -84,7 +84,7 @@ export async function verifyBondProof(
   const fresh = ageSecs <= maxAgeSecs;
 
   // Check threshold
-  const meetsThreshold = opts.requiredSats != null
+  const declaredAmountMeetsThreshold = opts.requiredSats != null
     ? proof.amountSats >= opts.requiredSats
     : null;
 
@@ -126,7 +126,9 @@ export async function verifyBondProof(
     signatureValid,
     fresh,
     ageSecs,
-    meetsThreshold,
+    declaredAmountMeetsThreshold,
+    fundsVerified: false,
+    meetsThreshold: declaredAmountMeetsThreshold,
     errors,
   };
 }
@@ -185,10 +187,14 @@ export function parseBondProof(event: NostrEvent | { tags: string[][] }): BondPr
   };
 }
 
-/** Check whether a bond proof meets a required amount threshold */
+/**
+ * Check policy compliance using independently verified funds evidence.
+ * Safe by default: BIP-322 plus a declared amount is never enough on its own.
+ */
 export function checkBondCompliance(
   proof: BondProof | null,
   requiredSats: number,
+  opts: { fundsVerified?: boolean } = {},
 ): { meets: boolean; reason?: string } {
   if (!proof) {
     return { meets: false, reason: 'No bond proof provided' };
@@ -199,5 +205,11 @@ export function checkBondCompliance(
       reason: `Bond amount ${proof.amountSats} sats is below required ${requiredSats} sats`,
     };
   }
+  if (opts.fundsVerified !== true) {
+    return {
+      meets: false,
+      reason: 'BIP-322 proves address control only; independent locked-funds verification is required',
+    };
+  }
   return { meets: true };
 }