@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/cjs/quorum.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * P2PQuorumLeaseProvider — Layer 4: multi-device quorum lease coordination.
+ *
+ * Safety model
+ * ────────────
+ * The local provider remains the authoritative watermark (it can only move
+ * forward). The quorum adds a second, independent check: before a reservation
+ * is handed to the caller, at least `minAttestations` peers must confirm that
+ * the same (treeId, indices) slot is free in *their* view of the world. This
+ * catches the failure mode where two devices share a seed and both believe
+ * they own the next slot — the peers see the double-reservation and refuse
+ * to attest.
+ *
+ * Wire protocol
+ * ─────────────
+ * Peers speak the same LEASE_RESERVE / LEASE_COMMIT / LEASE_BURN /
+ * LEASE_WATERMARK message shapes as the lookup protocol, so any peer that
+ * implements that protocol can participate: a personal lookup node, another
+ * device running this provider, or an in-memory test peer.
+ *
+ * Failure semantics
+ * ─────────────────
+ * - If quorum cannot be reached, the local reservation is burned and
+ *   QuorumUnavailableError is thrown. The slot is NOT reusable (burned),
+ *   which is the safe direction: a slot that might have been attested by
+ *   some peers must never be handed out again.
+ * - If a peer reports the slot as taken, the local reservation is burned
+ *   and QuorumConflictError is thrown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.P2PQuorumLeaseProvider = void 0;
+const errors_js_1 = require("./errors.js");
+const certificate_js_1 = require("./certificate.js");
+function sameIndices(a, b) {
+    return a.addressIndex === b.addressIndex && a.l1 === b.l1 && a.l2 === b.l2;
+}
+class P2PQuorumLeaseProvider {
+    constructor(config) {
+        /**
+         * localReservationId -> (peerId -> the reservation id that peer issued).
+         * Commit/burn must reference each peer's own id, because a peer only knows
+         * the reservation it issued, not the local provider's id (AUD-044).
+         */
+        this.peerReservationIds = new Map();
+        this._initialized = false;
+        this.peers = config.peers;
+        this.minAttestations = config.minAttestations ?? 1;
+        this.local = config.local;
+        this.requestTimeoutMs = config.requestTimeoutMs ?? 5000;
+        this.requireQuorumOnCommit = config.requireQuorumOnCommit ?? false;
+        this.certificateSigner = config.certificateSigner;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        await this.local.initialize();
+        this._initialized = true;
+    }
+    async ensureInit() {
+        if (!this._initialized)
+            await this.initialize();
+    }
+    // -------------------------------------------------------------------------
+    // Reserve — local first, then quorum attestation
+    // -------------------------------------------------------------------------
+    async reserveKeyUse(params) {
+        await this.ensureInit();
+        // 1. Local reservation (authoritative, monotonic watermark).
+        const reservation = await this.local.reserveKeyUse(params);
+        // 2. Collect attestations from peers for the SAME indices.
+        //    On failure the local reservation is burned — the slot is never reused.
+        let attestations;
+        try {
+            attestations = await this.attestKeyUse(params, reservation.indices);
+        }
+        catch (err) {
+            const reason = err instanceof errors_js_1.QuorumConflictError
+                ? `quorum conflict: ${err.message}`
+                : 'quorum not reached';
+            await this.local.burnReservation(reservation.reservationId, reason);
+            throw err;
+        }
+        this.recordPeerReservationIds(reservation.reservationId, attestations);
+        const certificate = {
+            reservationId: reservation.reservationId,
+            treeId: params.treeId,
+            branchId: params.branchId,
+            deviceId: params.deviceId,
+            indices: reservation.indices,
+            purpose: params.purpose,
+            payloadHash: params.payloadHash,
+            issuedBy: this.certificateSigner?.name ?? 'p2p-quorum',
+            issuedAt: Date.now(),
+            expiresAt: reservation.expiresAt,
+            signature: '',
+            attestations,
+        };
+        certificate.signature = this.certificateSigner ? await (0, certificate_js_1.signCertificate)(this.certificateSigner, certificate) : '';
+        return { ...reservation, certificate };
+    }
+    /**
+     * Collect quorum attestations for a reservation that was already made
+     * locally (used by HybridLeaseProvider so the local slot and the attested
+     * slot are the same). Throws QuorumUnavailableError / QuorumConflictError
+     * on failure — the caller owns the local reservation and must burn it.
+     */
+    async attestKeyUse(params, indices) {
+        await this.ensureInit();
+        const attestations = [];
+        const conflicts = [];
+        await Promise.all(this.peers.map(async (peer) => {
+            try {
+                const resp = await peer.request({
+                    type: 'LEASE_RESERVE',
+                    payload: {
+                        treeId: params.treeId,
+                        branchId: params.branchId,
+                        deviceId: params.deviceId,
+                        ttlMs: params.ttlMs,
+                        payloadHash: params.payloadHash,
+                        purpose: params.purpose,
+                        indices,
+                    },
+                }, this.requestTimeoutMs);
+                if (resp.type === 'ERROR') {
+                    conflicts.push(String(resp.payload.message ?? 'peer error'));
+                    return;
+                }
+                const body = resp.payload;
+                const peerIndices = body.reservation?.indices;
+                if (!peerIndices || !sameIndices(peerIndices, indices)) {
+                    conflicts.push('peer returned mismatched indices');
+                    return;
+                }
+                const peerReservationId = body.reservation?.reservationId;
+                attestations.push({
+                    peerId: peer.peerId,
+                    indices,
+                    expiresAt: body.reservation?.expiresAt ?? Date.now() + (params.ttlMs ?? 120000),
+                    ...(typeof peerReservationId === 'string' && peerReservationId.length > 0
+                        ? { peerReservationId }
+                        : {}),
+                });
+            }
+            catch {
+                // Peer unreachable — counted as no attestation.
+            }
+        }));
+        if (conflicts.length > 0) {
+            throw new errors_js_1.QuorumConflictError(params.treeId, indices);
+        }
+        if (attestations.length < this.minAttestations) {
+            throw new errors_js_1.QuorumUnavailableError(this.minAttestations, attestations.length);
+        }
+        return attestations;
+    }
+    // -------------------------------------------------------------------------
+    // Commit / burn — local authoritative, broadcast to peers
+    // -------------------------------------------------------------------------
+    async commitKeyUse(reservationId, txId) {
+        await this.ensureInit();
+        await this.local.commitKeyUse(reservationId, txId);
+        const acks = await this.broadcastAck('LEASE_COMMIT', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            txId,
+        }));
+        if (this.requireQuorumOnCommit && acks < this.minAttestations) {
+            throw new errors_js_1.QuorumUnavailableError(this.minAttestations, acks);
+        }
+    }
+    async burnReservation(reservationId, reason) {
+        await this.ensureInit();
+        await this.local.burnReservation(reservationId, reason);
+        await this.broadcastAck('LEASE_BURN', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            reason,
+        }));
+    }
+    /** Record which peer issued which reservation id for a local reservation. */
+    recordPeerReservationIds(localReservationId, attestations) {
+        const byPeer = new Map();
+        for (const attestation of attestations) {
+            if (attestation.peerReservationId) {
+                byPeer.set(attestation.peerId, attestation.peerReservationId);
+            }
+        }
+        if (byPeer.size > 0)
+            this.peerReservationIds.set(localReservationId, byPeer);
+    }
+    /**
+     * The id to send a peer for a local reservation. Peers only know the id they
+     * issued; fall back to the local id only when no peer id was recorded (e.g.
+     * attestations gathered outside `reserveKeyUse`).
+     */
+    peerReservationIdFor(localReservationId, peerId) {
+        return this.peerReservationIds.get(localReservationId)?.get(peerId) ?? localReservationId;
+    }
+    async broadcastAck(type, payloadFor) {
+        let acks = 0;
+        await Promise.all(this.peers.map(async (peer) => {
+            try {
+                const resp = await peer.request({ type, payload: payloadFor(peer.peerId) }, this.requestTimeoutMs);
+                if (resp.type !== 'ERROR')
+                    acks++;
+            }
+            catch {
+                // Peer unreachable — no ack.
+            }
+        }));
+        return acks;
+    }
+    // -------------------------------------------------------------------------
+    // Watermark / journal
+    // -------------------------------------------------------------------------
+    async getLocalWatermark(treeId) {
+        await this.ensureInit();
+        return this.local.getLocalWatermark(treeId);
+    }
+    async publishWatermark(treeId) {
+        await this.ensureInit();
+        const wm = await this.local.getLocalWatermark(treeId);
+        await Promise.all(this.peers.map(async (peer) => {
+            try {
+                await peer.request({
+                    type: 'LEASE_WATERMARK',
+                    payload: {
+                        treeId,
+                        addressCursor: wm.addressCursor,
+                        l1Cursor: wm.l1Cursor,
+                        l2Cursor: wm.l2Cursor,
+                        unavailableCount: wm.unavailableCount,
+                        lastSyncTimestamp: wm.lastSyncTimestamp ?? Date.now(),
+                    },
+                }, this.requestTimeoutMs);
+            }
+            catch {
+                // Peer unreachable — watermark publish is best-effort.
+            }
+        }));
+    }
+    async syncLeaseJournal() {
+        await this.ensureInit();
+        const conflicts = [];
+        let advancedTo;
+        for (const treeId of this.local.listTrees()) {
+            const localWm = await this.local.getLocalWatermark(treeId);
+            for (const peer of this.peers) {
+                try {
+                    const resp = await peer.request({
+                        type: 'LEASE_WATERMARK',
+                        payload: { treeId, query: true },
+                    }, this.requestTimeoutMs);
+                    if (resp.type === 'ERROR')
+                        continue;
+                    const p = resp.payload;
+                    if (typeof p.addressCursor !== 'number')
+                        continue;
+                    const remoteFlat = p.addressCursor * 64 * 64 + p.l1Cursor * 64 + p.l2Cursor;
+                    const localFlat = localWm.addressCursor * 64 * 64 + localWm.l1Cursor * 64 + localWm.l2Cursor;
+                    if (remoteFlat > localFlat) {
+                        const advanced = await this.local.advanceToRemoteWatermark(treeId, {
+                            addressCursor: p.addressCursor,
+                            l1Cursor: p.l1Cursor,
+                            l2Cursor: p.l2Cursor,
+                        });
+                        if (advanced) {
+                            advancedTo = {
+                                addressIndex: p.addressCursor,
+                                l1: p.l1Cursor,
+                                l2: p.l2Cursor,
+                            };
+                        }
+                    }
+                    else if (remoteFlat < localFlat) {
+                        conflicts.push({
+                            treeId,
+                            localIndex: localFlat,
+                            remoteIndex: remoteFlat,
+                            timestamp: Date.now(),
+                        });
+                    }
+                }
+                catch {
+                    // Peer unreachable — skip.
+                }
+            }
+        }
+        return { synced: conflicts.length === 0, conflicts, advancedTo };
+    }
+    async verifyLeaseCertificate(cert) {
+        if (!cert)
+            return false;
+        if (cert.expiresAt <= Date.now())
+            return false;
+        // An unsigned certificate carries no authenticity evidence.
+        if (!(await (0, certificate_js_1.certificateSignatureVerified)(cert, this.certificateSigner))) {
+            return false;
+        }
+        const attestations = cert.attestations ?? [];
+        if (attestations.length < this.minAttestations)
+            return false;
+        return attestations.every((a) => sameIndices(a.indices, cert.indices) &&
+            a.expiresAt > Date.now());
+    }
+}
+exports.P2PQuorumLeaseProvider = P2PQuorumLeaseProvider;

package/dist/cjs/replicated-backup.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RFC-057 — replicated WOTS lease-journal backup.
+ *
+ * The local `LeaseJournal` remains authoritative for allocation. This adapter
+ * mirrors the physically append-only journal into a replicated log for audit
+ * and disaster recovery, and restores entries into a local journal in order.
+ * It never allocates or advances a signing slot.
+ */
+import type { ReplicatedLog } from '@totemsdk/replication';
+import type { JournalEntry } from './types.js';
+export interface LeaseJournalRestoreTarget {
+    append(entry: JournalEntry): Promise<void>;
+}
+export declare class ReplicatedLeaseJournalBackup {
+    private readonly log;
+    constructor(log: ReplicatedLog<JournalEntry>);
+    /** Mirror one local journal entry. */
+    append(entry: JournalEntry): Promise<{
+        length: number;
+        head: string;
+    }>;
+    /** Read all mirrored entries, verifying the local hash-chain links in order. */
+    readAll(): Promise<JournalEntry[]>;
+    /**
+     * Restore into a local journal. The local journal's own duplicate-slot and
+     * reservation checks remain the final guard; this method only preserves the
+     * replicated order and links.
+     */
+    restoreInto(target: LeaseJournalRestoreTarget): Promise<number>;
+}

package/dist/cjs/replicated-backup.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * RFC-057 — replicated WOTS lease-journal backup.
+ *
+ * The local `LeaseJournal` remains authoritative for allocation. This adapter
+ * mirrors the physically append-only journal into a replicated log for audit
+ * and disaster recovery, and restores entries into a local journal in order.
+ * It never allocates or advances a signing slot.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplicatedLeaseJournalBackup = void 0;
+const errors_1 = require("@totemsdk/storage/errors");
+class ReplicatedLeaseJournalBackup {
+    constructor(log) {
+        this.log = log;
+    }
+    /** Mirror one local journal entry. */
+    async append(entry) {
+        return this.log.append(entry);
+    }
+    /** Read all mirrored entries, verifying the local hash-chain links in order. */
+    async readAll() {
+        const entries = [];
+        for await (const entry of this.log.readSince())
+            entries.push(entry.record);
+        let previous;
+        for (const [index, entry] of entries.entries()) {
+            if (index === 0) {
+                if (entry.previousHash !== undefined) {
+                    throw new errors_1.StorageError('replicated lease journal first entry has previousHash', 'corrupt');
+                }
+            }
+            else if (entry.previousHash !== previous?.hash) {
+                throw new errors_1.StorageError(`replicated lease journal chain mismatch at ${index}`, 'corrupt');
+            }
+            previous = entry;
+        }
+        return entries;
+    }
+    /**
+     * Restore into a local journal. The local journal's own duplicate-slot and
+     * reservation checks remain the final guard; this method only preserves the
+     * replicated order and links.
+     */
+    async restoreInto(target) {
+        const entries = await this.readAll();
+        for (const entry of entries)
+            await target.append(entry);
+        return entries.length;
+    }
+}
+exports.ReplicatedLeaseJournalBackup = ReplicatedLeaseJournalBackup;

package/dist/cjs/seed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+import type { LocalLeaseProvider } from './local.js';
+import type { OnchainWatermarkProvider } from './onchain.js';
+import type { LocalWatermark, WatermarkSeed } from './types.js';
+export interface SeedLeaseWatermarkParams {
+    readonly local: LocalLeaseProvider;
+    readonly treeId: string;
+    /** Layer 5 — the on-chain cursor is authoritative when reachable. */
+    readonly onchain?: OnchainWatermarkProvider;
+    /** Exported watermark blob. */
+    readonly exported?: WatermarkSeed;
+    /** Operator-provided flat high-water mark. */
+    readonly operatorHighWaterMark?: number;
+    /** Declares the keyspace fresh/unspent, so cursor 0 is safe. */
+    readonly fresh?: boolean;
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+export declare function seedLeaseWatermark(params: SeedLeaseWatermarkParams): Promise<LocalWatermark>;
+/** Export a portable watermark blob for backup/restore. */
+export declare function exportLeaseWatermark(local: LocalLeaseProvider, treeId: string): Promise<WatermarkSeed>;

package/dist/cjs/seed.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedLeaseWatermark = seedLeaseWatermark;
+exports.exportLeaseWatermark = exportLeaseWatermark;
+const watermark_js_1 = require("./watermark.js");
+const errors_js_1 = require("./errors.js");
+function flatOf(w) {
+    return (0, watermark_js_1.flatIndex)({ addressIndex: w.addressCursor, l1: w.l1Cursor, l2: w.l2Cursor });
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+async function seedLeaseWatermark(params) {
+    const { local, treeId } = params;
+    // 1. On-chain cursor — advances the same local watermark (monotonic).
+    if (params.onchain) {
+        try {
+            await params.onchain.syncLeaseJournal();
+        }
+        catch {
+            // Chain unreachable — fall through to exported/operator sources below.
+        }
+    }
+    const current = await local.getLocalWatermark(treeId);
+    let bestFlat = flatOf({ addressCursor: current.addressCursor, l1Cursor: current.l1Cursor, l2Cursor: current.l2Cursor });
+    let best;
+    // 2. Exported blob.
+    if (params.exported) {
+        if (flatOf(params.exported) > bestFlat) {
+            best = params.exported;
+            bestFlat = flatOf(params.exported);
+        }
+    }
+    // 3. Operator high-water mark.
+    if (params.operatorHighWaterMark !== undefined) {
+        const indices = (0, watermark_js_1.fromFlatIndex)(params.operatorHighWaterMark);
+        const candidate = {
+            version: 1,
+            treeId,
+            addressCursor: indices.addressIndex,
+            l1Cursor: indices.l1,
+            l2Cursor: indices.l2,
+            unavailable: [],
+        };
+        if (flatOf(candidate) > bestFlat) {
+            best = candidate;
+            bestFlat = flatOf(candidate);
+        }
+    }
+    if (best) {
+        await local.seedWatermark(best);
+    }
+    if (!params.onchain &&
+        !params.exported &&
+        params.operatorHighWaterMark === undefined &&
+        !params.fresh) {
+        throw new errors_js_1.WatermarkSeedRequiredError(treeId);
+    }
+    return local.getLocalWatermark(treeId);
+}
+/** Export a portable watermark blob for backup/restore. */
+function exportLeaseWatermark(local, treeId) {
+    return local.exportWatermark(treeId);
+}

package/dist/cjs/stubs.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Implementations for Layers 3–5 of the WotsLeaseProvider hierarchy.
+ *
+ * Layer 3 (PersonalLeaseNodeProvider) — HTTP client for a personal @totemsdk/lookup-node
+ *   that has lease coordination enabled ({ lease: { enabled: true } }).
+ *   The node exposes REST endpoints under /v1/lease/*.
+ *
+ * Layers 4–5 (P2PQuorumLeaseProvider, OnchainWatermarkProvider) — implemented in
+ *   quorum.ts and onchain.ts; re-exported here for backward compatibility.
+ */
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, PersonalLeaseNodeConfig } from './types.js';
+export { P2PQuorumLeaseProvider } from './quorum.js';
+export { OnchainWatermarkProvider } from './onchain.js';
+/**
+ * Layer 3 — personal lookup-node lease coordinator.
+ *
+ * Calls the HTTP REST API exposed by a running @totemsdk/lookup-node that has
+ * lease coordination enabled. All write operations are forwarded to the node's
+ * LeaseCoordinator so the node acts as the source-of-truth watermark journal
+ * for high-value transactions.
+ *
+ * Wrap with HybridLeaseProvider so local reservations always succeed even when
+ * the personal node is temporarily unreachable:
+ *
+ * ```ts
+ * const provider = new HybridLeaseProvider({
+ *   local: new LocalLeaseProvider(storage),
+ *   node:  new PersonalLeaseNodeProvider({ nodeUrl, nodePubkey }),
+ *   threshold: 10, // escalate to node for txns >= 10 MIN
+ * });
+ * ```
+ */
+export declare class PersonalLeaseNodeProvider implements WotsLeaseProvider {
+    private readonly baseUrl;
+    private readonly nodePubkey;
+    private readonly authToken?;
+    private readonly certificateSigner?;
+    private readonly verify?;
+    constructor(config: PersonalLeaseNodeConfig);
+    private headers;
+    private post;
+    private get;
+    reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+    commitKeyUse(reservationId: string, txId: string): Promise<void>;
+    burnReservation(reservationId: string, reason: string): Promise<void>;
+    getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    publishWatermark(treeId: string): Promise<void>;
+    syncLeaseJournal(): Promise<SyncResult>;
+    verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+}