@totemsdk/wots-lease 1.0.0 → 1.0.1

package/dist/local.js

@@ -22,21 +22,129 @@ 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.journal.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. */
@@ -45,46 +153,56 @@ class LocalLeaseProvider {
         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');
-                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,
-                });
             }
         }
     }
     async recoverExpiredReservations() {
         const now = Date.now();
         for (const lease of this.leaseStore.getAll()) {
-            if (lease.status === 'active' && lease.expiresAt < now) {
+            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');
-                await this.leaseStore.updateStatus(lease.leaseId, '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,
-                });
+                if (lease.status !== 'expired')
+                    await this.leaseStore.updateStatus(lease.leaseId, 'expired');
             }
         }
     }
     async reserveKeyUse(params) {
-        if (!this._initialized)
-            await this.initialize();
-        const indices = this.watermark.getNextIndices(params.treeId);
-        return this.reserveSpecificKeyUse(params, indices);
+        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
@@ -92,6 +210,14 @@ class LocalLeaseProvider {
      * 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;
@@ -106,20 +232,29 @@ class LocalLeaseProvider {
                 throw new errors_js_1.DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
             }
         }
-        await this.watermark.markUnavailable(treeId, indices, 'reserved');
         const reservationId = randomId();
         const expiresAt = Date.now() + ttlMs;
-        const lease = {
-            leaseId: reservationId,
-            leaseToken: reservationId,
-            treeId,
-            indices,
-            expiresAt,
-            status: 'active',
-            createdAt: Date.now(),
-            leaseTTL: ttlMs,
-        };
-        await this.leaseStore.save(lease);
+        // 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',
@@ -131,20 +266,51 @@ class LocalLeaseProvider {
             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);
-        if (lease.status === 'finalized')
-            return;
         const treeId = lease.treeId ?? 'default';
         const indices = lease.indices;
-        await this.watermark.markUnavailable(treeId, indices, 'committed');
-        await this.leaseStore.updateStatus(reservationId, 'finalized');
+        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',
@@ -156,18 +322,32 @@ class LocalLeaseProvider {
             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;
-        await this.watermark.markUnavailable(treeId, indices, 'burned');
-        await this.leaseStore.updateStatus(reservationId, 'cancelled');
-        this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
+        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',
@@ -178,12 +358,35 @@ class LocalLeaseProvider {
             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);

package/dist/onchain.d.ts

@@ -23,7 +23,8 @@
 import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, OnchainWatermarkProviderConfig } from './types.js';
 export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
     private readonly chain;
-    private readonly watermarkCoinId;
+    private readonly initialWatermarkCoinId;
+    private currentCoinId;
     private readonly watermarkAddress;
     private readonly tokenId;
     private readonly amount;
@@ -31,6 +32,7 @@ export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
     private readonly signer;
     private readonly statePort;
     private readonly minBlocksBetweenPublishes;
+    private readonly storage?;
     private _initialized;
     private _lastPublishBlock;
     constructor(config: OnchainWatermarkProviderConfig);

package/dist/onchain.js

@@ -27,7 +27,9 @@ const watermark_js_1 = require("./watermark.js");
 const errors_js_1 = require("./errors.js");
 const core_1 = require("@totemsdk/core");
 const txpow_1 = require("@totemsdk/txpow");
+const certificate_js_1 = require("./certificate.js");
 const MAX_L = 64;
+const WATERMARK_COIN_STORAGE_KEY = 'wots-lease:onchain:watermark-coin';
 function multiConcat(parts) {
     if (parts.length === 0)
         return new Uint8Array(0);
@@ -89,7 +91,8 @@ class OnchainWatermarkProvider {
         this._initialized = false;
         this._lastPublishBlock = -1;
         this.chain = config.chain;
-        this.watermarkCoinId = config.watermarkCoinId;
+        this.initialWatermarkCoinId = config.watermarkCoinId;
+        this.currentCoinId = config.watermarkCoinId;
         this.watermarkAddress = config.watermarkAddress;
         this.tokenId = config.tokenId ?? '0x00';
         this.amount = config.amount ?? '1';
@@ -97,10 +100,25 @@ class OnchainWatermarkProvider {
         this.signer = config.signer;
         this.statePort = config.statePort ?? 0;
         this.minBlocksBetweenPublishes = config.minBlocksBetweenPublishes ?? 1;
+        this.storage = config.storage;
     }
     async initialize() {
         if (this._initialized)
             return;
+        // Recover the advanced watermark coin identity across restarts.
+        if (this.storage) {
+            try {
+                const saved = await this.storage.get(WATERMARK_COIN_STORAGE_KEY);
+                if (saved?.coinId)
+                    this.currentCoinId = saved.coinId;
+                if (typeof saved?.lastPublishBlock === 'number') {
+                    this._lastPublishBlock = saved.lastPublishBlock;
+                }
+            }
+            catch {
+                // Storage unavailable — fall back to the configured coin.
+            }
+        }
         await this.local.initialize();
         this._initialized = true;
     }
@@ -127,6 +145,7 @@ class OnchainWatermarkProvider {
             expiresAt: reservation.expiresAt,
             signature: '',
         };
+        certificate.signature = await (0, certificate_js_1.signCertificate)(this.signer, certificate);
         return { ...reservation, certificate };
     }
     async commitKeyUse(reservationId, txId) {
@@ -170,10 +189,11 @@ class OnchainWatermarkProvider {
         catch {
             // Tip unavailable — proceed without rate limiting.
         }
-        // Read the current on-chain cursor so the input state matches the coin.
-        const coin = await this.chain.getCoin(this.watermarkCoinId);
+        // Read the current on-chain cursor so the input state matches the coin
+        // anchored by the CURRENT watermark coin (which advances on every spend).
+        const coin = await this.chain.getCoin(this.currentCoinId);
         if (!coin) {
-            throw new errors_js_1.OnchainWatermarkError(`Watermark coin not found: ${this.watermarkCoinId}`);
+            throw new errors_js_1.OnchainWatermarkError(`Watermark coin not found: ${this.currentCoinId}`);
         }
         const currentState = coin.state ?? [];
         const currentFlat = readStateCursor(currentState, this.statePort);
@@ -182,7 +202,7 @@ class OnchainWatermarkProvider {
             return;
         }
         const inputCoin = {
-            coinid: this.watermarkCoinId,
+            coinid: this.currentCoinId,
             address: addressToHex(this.watermarkAddress),
             amount: this.amount,
             tokenid: this.tokenId,
@@ -207,12 +227,29 @@ class OnchainWatermarkProvider {
         const digest = (0, core_1.computeTransactionDigest)(txBytes);
         const sig = await this.signer.sign(digest);
         const witnessBytes = buildWitnessBytes([sig]);
-        const prng = (0, core_1.sha3_256)(new TextEncoder().encode(`watermark:${treeId}:${this.watermarkCoinId}:${newFlat}`));
+        const prng = (0, core_1.sha3_256)(new TextEncoder().encode(`watermark:${treeId}:${this.currentCoinId}:${newFlat}`));
         const txHex = Buffer.from((0, txpow_1.serializeTxPoW)(txBytes, witnessBytes, { prng })).toString('hex');
         const result = await this.chain.broadcastTxPoW(txHex);
         if (!result.success) {
             throw new errors_js_1.OnchainWatermarkError(`Watermark publish rejected: ${result.message ?? 'unknown error'}`);
         }
+        // Rollover: the spent watermark coin is destroyed and replaced by a fresh
+        // coin with a new coin ID (output 0 of this spend). Track and persist the
+        // ADVANCED identity so the next publish spends the live coin, not the
+        // consumed one.
+        const newCoinId = '0x' + (0, core_1.bytesToHex)((0, core_1.precomputeTransactionCoinID)((0, core_1.hexToBytes)(this.currentCoinId), 0));
+        this.currentCoinId = newCoinId;
+        if (this.storage) {
+            try {
+                await this.storage.set(WATERMARK_COIN_STORAGE_KEY, {
+                    coinId: newCoinId,
+                    lastPublishBlock: this._lastPublishBlock,
+                });
+            }
+            catch {
+                // Storage unavailable — in-memory rollover still applies this session.
+            }
+        }
     }
     // -------------------------------------------------------------------------
     // Sync — merge on-chain cursor into local watermark
@@ -230,7 +267,7 @@ class OnchainWatermarkProvider {
             });
             let onchainFlat = null;
             try {
-                const coin = await this.chain.getCoin(this.watermarkCoinId);
+                const coin = await this.chain.getCoin(this.currentCoinId);
                 if (coin)
                     onchainFlat = readStateCursor(coin.state ?? [], this.statePort);
             }
@@ -269,6 +306,8 @@ class OnchainWatermarkProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
+        if (!(await (0, certificate_js_1.certificateSignatureVerified)(cert, this.signer)))
+            return false;
         return cert.issuedBy === 'onchain-watermark';
     }
 }

package/dist/quorum.d.ts

@@ -34,6 +34,13 @@ export declare class P2PQuorumLeaseProvider implements WotsLeaseProvider {
     private readonly local;
     private readonly requestTimeoutMs;
     private readonly requireQuorumOnCommit;
+    private readonly certificateSigner?;
+    /**
+     * 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).
+     */
+    private readonly peerReservationIds;
     private _initialized;
     constructor(config: P2PQuorumLeaseProviderConfig);
     initialize(): Promise<void>;
@@ -52,6 +59,14 @@ export declare class P2PQuorumLeaseProvider implements WotsLeaseProvider {
     }): Promise<QuorumAttestation[]>;
     commitKeyUse(reservationId: string, txId: string): Promise<void>;
     burnReservation(reservationId: string, reason: string): Promise<void>;
+    /** Record which peer issued which reservation id for a local reservation. */
+    private recordPeerReservationIds;
+    /**
+     * 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`).
+     */
+    private peerReservationIdFor;
     private broadcastAck;
     getLocalWatermark(treeId: string): Promise<LocalWatermark>;
     publishWatermark(treeId: string): Promise<void>;