@totemsdk/wots-lease 1.0.1 → 1.0.2

package/dist/cjs/local.js

@@ -0,0 +1,440 @@
+"use strict";
+/**
+ * LocalLeaseProvider — Layer 1: local durable ledger.
+ *
+ * Single-device, no network coordination.
+ * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalLeaseProvider = void 0;
+const core_1 = require("@totemsdk/core");
+const core_2 = require("@totemsdk/core");
+const watermark_js_1 = require("./watermark.js");
+const journal_js_1 = require("./journal.js");
+const errors_js_1 = require("./errors.js");
+function randomId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+class LocalLeaseProvider {
+    constructor(storage, logger = new core_1.NoopLogger(), deviceId = 'local') {
+        this.logger = logger;
+        this._initialized = false;
+        this.initializePromise = null;
+        this.mutationTail = Promise.resolve();
+        this.watermark = new watermark_js_1.WotsWatermarkStore(storage, logger);
+        this.leaseStore = new core_2.LeaseStore(storage, logger);
+        this.journal = new journal_js_1.LeaseJournal(storage, logger);
+        this.deviceId = deviceId;
+        this.cas = LocalLeaseProvider.detectCas(storage);
+    }
+    static detectCas(storage) {
+        const candidate = storage;
+        return typeof candidate.conditionalUpdate === 'function' ? candidate : undefined;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        if (!this.initializePromise) {
+            this.initializePromise = this.initializeOnce().catch((error) => {
+                this.initializePromise = null;
+                throw error;
+            });
+        }
+        await this.initializePromise;
+    }
+    async initializeOnce() {
+        await this.journal.initialize();
+        await this.watermark.initialize();
+        await this.leaseStore.initialize();
+        await this.reconcileDurableSafetyState();
+        await this.recoverExpiredReservations();
+        await this.burnUnresolvedReservations();
+        this._initialized = true;
+    }
+    /**
+     * Rebuild the no-reuse watermark from immutable journal history and leases.
+     * The journal is audit authority; the watermark remains allocation authority.
+     */
+    async reconcileDurableSafetyState() {
+        const entries = this.journal.getAll();
+        const latestBySlot = new Map();
+        const latestByReservation = new Map();
+        for (const entry of entries) {
+            latestBySlot.set(`${entry.treeId}:${entry.wotsIndex}`, entry);
+            if (entry.reservationId)
+                latestByReservation.set(entry.reservationId, entry);
+        }
+        for (const entry of latestBySlot.values()) {
+            await this.watermark.markUnavailable(entry.treeId, entry.indices, entry.status);
+        }
+        const leases = this.leaseStore.getAll();
+        const leaseIds = new Set(leases.map((lease) => lease.leaseId));
+        for (const entry of latestByReservation.values()) {
+            if (entry.status !== 'reserved' || leaseIds.has(entry.reservationId))
+                continue;
+            await this.journal.append({
+                ...entry,
+                status: 'burned',
+                timestamp: Date.now(),
+            });
+            await this.watermark.markUnavailable(entry.treeId, entry.indices, 'burned');
+        }
+        for (const lease of leases) {
+            const treeId = lease.treeId ?? 'default';
+            const latest = this.journal.getByReservation(lease.leaseId);
+            if (!latest) {
+                const status = lease.status === 'finalized'
+                    ? 'committed'
+                    : lease.status === 'cancelled'
+                        ? 'burned'
+                        : lease.status === 'expired'
+                            ? 'reserved-expired'
+                            : 'reserved';
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
+                    indices: lease.indices,
+                    status,
+                    reservationId: lease.leaseId,
+                    ...(lease.txId !== undefined ? { txId: lease.txId } : {}),
+                    timestamp: lease.createdAt,
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, status);
+                continue;
+            }
+            if (latest.status === 'committed' && lease.status !== 'finalized') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'finalized');
+            }
+            else if (latest.status === 'burned' && lease.status !== 'cancelled') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
+            }
+            else if (latest.status === 'reserved-expired' && lease.status !== 'expired') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'expired');
+            }
+            else if (latest.status === 'reserved' && lease.status === 'finalized') {
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
+                    indices: lease.indices,
+                    status: 'committed',
+                    reservationId: lease.leaseId,
+                    ...(lease.txId !== undefined ? { txId: lease.txId } : {}),
+                    timestamp: Date.now(),
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, 'committed');
+            }
+            else if (latest.status === 'reserved' && lease.status === 'cancelled') {
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
+                    indices: lease.indices,
+                    status: 'burned',
+                    reservationId: lease.leaseId,
+                    timestamp: Date.now(),
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, 'burned');
+            }
+        }
+    }
+    /** Burn all active (non-expired) leases that have no matching treeId.
+     *  On restart, leases with missing treeId (from before the treeId field was added)
+     *  must be burned to prevent index reuse. */
+    async burnUnresolvedReservations() {
+        const now = Date.now();
+        for (const lease of this.leaseStore.getAll()) {
+            if (lease.status === 'active' && lease.expiresAt >= now && !lease.treeId) {
+                this.logger.warn(`[LocalLeaseProvider] Burning unresolved lease ${lease.leaseId} (no treeId)`);
+                if (this.journal.getByReservation(lease.leaseId)?.status !== 'burned') {
+                    await this.journal.append({
+                        treeId: 'default',
+                        branchId: 'default',
+                        wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
+                        indices: lease.indices,
+                        status: 'burned',
+                        reservationId: lease.leaseId,
+                        timestamp: now,
+                        deviceId: this.deviceId,
+                    });
+                }
+                await this.watermark.markUnavailable('default', lease.indices, 'burned');
+                await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
+            }
+        }
+    }
+    async recoverExpiredReservations() {
+        const now = Date.now();
+        for (const lease of this.leaseStore.getAll()) {
+            if (lease.status === 'expired' || (lease.status === 'active' && lease.expiresAt < now)) {
+                const treeId = lease.treeId ?? 'default';
+                if (this.journal.getByReservation(lease.leaseId)?.status !== 'reserved-expired') {
+                    await this.journal.append({
+                        treeId,
+                        branchId: 'default',
+                        wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
+                        indices: lease.indices,
+                        status: 'reserved-expired',
+                        reservationId: lease.leaseId,
+                        timestamp: now,
+                        deviceId: this.deviceId,
+                    });
+                }
+                await this.watermark.markUnavailable(treeId, lease.indices, 'reserved-expired');
+                if (lease.status !== 'expired')
+                    await this.leaseStore.updateStatus(lease.leaseId, 'expired');
+            }
+        }
+    }
+    async reserveKeyUse(params) {
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            // Pick up any allocation made by another provider over the same storage
+            // before choosing a slot (AUD-004).
+            await this.watermark.refresh();
+            const indices = this.watermark.getNextIndices(params.treeId);
+            return this.reserveSpecificKeyUseUnlocked(params, indices);
+        });
+    }
+    /**
+     * Reserve a specific set of indices (used by quorum coordination so every
+     * peer attests to the same slot). Throws IndicesUnavailableError when the
+     * slot is already taken.
+     */
+    async reserveSpecificKeyUse(params, indices) {
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            await this.watermark.refresh();
+            return this.reserveSpecificKeyUseUnlocked(params, indices);
+        });
+    }
+    async reserveSpecificKeyUseUnlocked(params, indices) {
+        if (!this._initialized)
+            await this.initialize();
+        const treeId = params.treeId;
+        const ttlMs = params.ttlMs ?? 120000;
+        if (this.watermark.isUnavailable(treeId, indices)) {
+            throw new errors_js_1.IndicesUnavailableError(treeId, indices);
+        }
+        // Validate device range BEFORE marking unavailable — prevents permanent index loss
+        if (params.deviceId) {
+            const range = this.getDeviceRange(params.deviceId);
+            if (range && (indices.addressIndex < range.start || indices.addressIndex > range.end)) {
+                throw new errors_js_1.DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
+            }
+        }
+        const reservationId = randomId();
+        const expiresAt = Date.now() + ttlMs;
+        // Cross-instance CAS claim (AUD-004): on a durable medium shared by two
+        // provider instances over distinct adapter objects, refresh() above can
+        // race and both pick the same slot. Claim it atomically first; a lost race
+        // means another instance owns it, so the slot is not re-allocated.
+        if (this.cas) {
+            const claimKey = `totem_wots_claim:${treeId}:${(0, watermark_js_1.flatIndex)(indices)}`;
+            const claim = await this.cas.conditionalUpdate(claimKey, (current) => current
+                ? { abort: 'slot already claimed' }
+                : {
+                    next: {
+                        reservationId,
+                        ...(params.deviceId !== undefined ? { deviceId: params.deviceId } : {}),
+                        claimedAt: Date.now(),
+                    },
+                });
+            if (!claim.applied) {
+                throw new errors_js_1.IndicesUnavailableError(treeId, indices);
+            }
+        }
+        // Write-ahead safety record: once this succeeds, recovery will never
+        // re-expose the index even if a later snapshot write fails.
+        await this.journal.append({
+            treeId,
+            branchId: params.branchId ?? 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'reserved',
+            reservationId,
+            payloadHash: params.payloadHash,
+            timestamp: Date.now(),
+            deviceId: params.deviceId ?? this.deviceId,
+        });
+        await this.watermark.markUnavailable(treeId, indices, 'reserved');
+        const lease = {
+            leaseId: reservationId,
+            leaseToken: reservationId,
+            treeId,
+            indices,
+            expiresAt,
+            status: 'active',
+            createdAt: Date.now(),
+            leaseTTL: ttlMs,
+        };
+        await this.leaseStore.save(lease);
+        return { reservationId, indices, expiresAt };
+    }
+    withMutationLock(operation) {
+        const run = this.mutationTail.then(operation, operation);
+        this.mutationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async commitKeyUse(reservationId, txId) {
+        return this.withMutationLock(() => this.commitKeyUseUnlocked(reservationId, txId));
+    }
+    async commitKeyUseUnlocked(reservationId, txId) {
+        if (!this._initialized)
+            await this.initialize();
+        await this.watermark.refresh();
+        const lease = this.leaseStore.get(reservationId);
+        if (!lease)
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
+        const treeId = lease.treeId ?? 'default';
+        const indices = lease.indices;
+        const latest = this.journal.getByReservation(reservationId);
+        if (latest?.status === 'committed') {
+            if (latest.txId !== txId) {
+                throw new errors_js_1.InvalidLeaseTransitionError(reservationId, 'committed', 'committed');
+            }
+            await this.watermark.markUnavailable(treeId, indices, 'committed');
+            if (lease.status !== 'finalized')
+                await this.leaseStore.updateStatus(reservationId, 'finalized');
+            return;
+        }
+        if (latest?.status === 'burned' || latest?.status === 'reserved-expired'
+            || lease.status === 'cancelled' || lease.status === 'expired') {
+            throw new errors_js_1.InvalidLeaseTransitionError(reservationId, latest?.status ?? lease.status, 'committed');
+        }
+        await this.journal.append({
+            treeId,
+            branchId: 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'committed',
+            reservationId,
+            txId,
+            timestamp: Date.now(),
+            deviceId: this.deviceId,
+        });
+        await this.watermark.markUnavailable(treeId, indices, 'committed');
+        await this.leaseStore.updateStatus(reservationId, 'finalized');
+    }
+    async burnReservation(reservationId, reason) {
+        return this.withMutationLock(() => this.burnReservationUnlocked(reservationId, reason));
+    }
+    async burnReservationUnlocked(reservationId, reason) {
+        if (!this._initialized)
+            await this.initialize();
+        await this.watermark.refresh();
+        const lease = this.leaseStore.get(reservationId);
+        if (!lease)
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
+        const treeId = lease.treeId ?? 'default';
+        const indices = lease.indices;
+        const latest = this.journal.getByReservation(reservationId);
+        if (latest?.status === 'burned') {
+            await this.watermark.markUnavailable(treeId, indices, 'burned');
+            if (lease.status !== 'cancelled')
+                await this.leaseStore.updateStatus(reservationId, 'cancelled');
+            return;
+        }
+        if (latest?.status === 'committed' || latest?.status === 'reserved-expired'
+            || lease.status === 'finalized' || lease.status === 'expired') {
+            throw new errors_js_1.InvalidLeaseTransitionError(reservationId, latest?.status ?? lease.status, 'burned');
+        }
+        await this.journal.append({
+            treeId,
+            branchId: 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'burned',
+            reservationId,
+            timestamp: Date.now(),
+            deviceId: this.deviceId,
+        });
+        await this.watermark.markUnavailable(treeId, indices, 'burned');
+        await this.leaseStore.updateStatus(reservationId, 'cancelled');
+        this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
+    }
+    async getLocalWatermark(treeId) {
+        if (!this._initialized)
+            await this.initialize();
+        return this.watermark.getLocalWatermark(treeId);
+    }
+    /**
+     * Export a portable watermark seed for restore (RFC-013 §9).
+     */
+    async exportWatermark(treeId) {
+        if (!this._initialized)
+            await this.initialize();
+        return this.watermark.exportSeed(treeId);
+    }
+    /**
+     * Seed the local watermark from an exported/operator/on-chain snapshot.
+     * Forward-only by default; refuses to start below the true high-water mark.
+     */
+    async seedWatermark(seed, options) {
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            await this.watermark.refresh();
+            await this.watermark.seed(seed, options);
+        });
+    }
+    /** List all tree IDs known to the local watermark store. */
+    listTrees() {
+        return Object.keys(this.watermark.getRawState().trees);
+    }
+    /** Expose the journal for quorum/on-chain providers to merge remote entries. */
+    getJournal() {
+        return this.journal;
+    }
+    /**
+     * Advance the local watermark to a remote cursor (monotonic merge).
+     * Used by quorum sync and the lookup-node LeaseCoordinator when a peer
+     * publishes a watermark ahead of ours. Returns false when the remote
+     * cursor is behind (no-op).
+     */
+    async advanceToRemoteWatermark(treeId, remote) {
+        if (!this._initialized)
+            await this.initialize();
+        const local = this.watermark.getLocalWatermark(treeId);
+        const localFlat = (0, watermark_js_1.flatIndex)({ addressIndex: local.addressCursor, l1: local.l1Cursor, l2: local.l2Cursor });
+        const remoteFlat = (0, watermark_js_1.flatIndex)({ addressIndex: remote.addressCursor, l1: remote.l1Cursor, l2: remote.l2Cursor });
+        if (remoteFlat <= localFlat)
+            return false;
+        await this.watermark.save(treeId, {
+            addressCursor: remote.addressCursor,
+            l1Cursor: remote.l1Cursor,
+            l2Cursor: remote.l2Cursor,
+            lastSyncTimestamp: Date.now(),
+        });
+        return true;
+    }
+    async publishWatermark(_treeId) {
+        // Layer 1: no-op
+    }
+    async syncLeaseJournal() {
+        // Layer 1: no-op
+        return { synced: true, conflicts: [] };
+    }
+    async verifyLeaseCertificate(cert) {
+        if (cert === undefined)
+            return true;
+        return false;
+    }
+    getDeviceRange(deviceId) {
+        const match = deviceId.match(/^device-?(\d+)$/i);
+        if (!match)
+            return null;
+        const slot = parseInt(match[1], 10);
+        return { start: slot * 8, end: slot * 8 + 7 };
+    }
+}
+exports.LocalLeaseProvider = LocalLeaseProvider;

package/dist/cjs/onchain.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OnchainWatermarkProvider — Layer 5: on-chain watermark anchoring.
+ *
+ * Safety model
+ * ────────────
+ * The local provider remains the authoritative watermark. This provider adds
+ * a verifiable public record: a dedicated watermark coin whose STATE(0) holds
+ * the flat watermark cursor. Every publish spends the coin back to itself
+ * with an advanced cursor, so any third party can read the on-chain state and
+ * prove that a given signing slot was consumed — without trusting this device.
+ *
+ * The watermark coin script is `RETURN SIGNEDBY(0x<digest>)` — the same
+ * single-sig pattern used by statechain reclaim addresses. The signer is the
+ * WOTS key owner; the digest is the 32-byte public key digest.
+ *
+ * Failure semantics
+ * ─────────────────
+ * - publishWatermark fails loudly (OnchainWatermarkError) when the chain
+ *   rejects the TX — the local watermark is never rolled back.
+ * - syncLeaseJournal merges the on-chain cursor into the local watermark
+ *   monotonically (remote ahead → advance; remote behind → conflict record).
+ */
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, OnchainWatermarkProviderConfig } from './types.js';
+export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
+    private readonly chain;
+    private readonly initialWatermarkCoinId;
+    private currentCoinId;
+    private readonly watermarkAddress;
+    private readonly tokenId;
+    private readonly amount;
+    private readonly local;
+    private readonly signer;
+    private readonly statePort;
+    private readonly minBlocksBetweenPublishes;
+    private readonly storage?;
+    private _initialized;
+    private _lastPublishBlock;
+    constructor(config: OnchainWatermarkProviderConfig);
+    initialize(): Promise<void>;
+    private ensureInit;
+    reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+    commitKeyUse(reservationId: string, txId: string): Promise<void>;
+    burnReservation(reservationId: string, reason: string): Promise<void>;
+    getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    /**
+     * Publish the local watermark cursor on-chain by spending the watermark
+     * coin back to itself with STATE(statePort) = flat cursor.
+     *
+     * Rate-limited by minBlocksBetweenPublishes using the chain tip.
+     */
+    publishWatermark(treeId: string): Promise<void>;
+    syncLeaseJournal(): Promise<SyncResult>;
+    verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+}