@totemsdk/wots-lease 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -92,6 +92,6 @@ entries.forEach(e => console.log(e.flatIndex, e.allocatedAt, e.committedAt));
 
 ## See also
 
-- [`@totemsdk/core`](../core) — WOTS primitives this package protects
-- [`@totemsdk/lookup-node`](../lookup-node) — `LeaseCoordinator` for multi-client setups
-- [`@totemsdk/omnia`](../omnia) — integrates wots-lease to protect channel signing slots
+- [`@totemsdk/core`](https://www.npmjs.com/package/@totemsdk/core) — WOTS primitives this package protects
+- [`@totemsdk/lookup-node`](https://www.npmjs.com/package/@totemsdk/lookup-node) — `LeaseCoordinator` for multi-client setups
+- [`@totemsdk/omnia`](https://www.npmjs.com/package/@totemsdk/omnia) — integrates wots-lease to protect channel signing slots

package/dist/axia.js

@@ -1,23 +1,26 @@
+"use strict";
 /**
  * AxiaLeaseProvider — wraps the Axia API's /v1/wots-hardened endpoints.
  *
  * Callers do NOT need to call /finalize separately — commitKeyUse() does it.
  */
-import { NoopLogger, LeaseStore } from '@totemsdk/core';
-import { prepareLease, finalizeLease } from '@totemsdk/core';
-import { WotsWatermarkStore, flatIndex } from './watermark.js';
-import { LeaseJournal } from './journal.js';
-import { LeaseNotFoundError } from './errors.js';
-export class AxiaLeaseProvider {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AxiaLeaseProvider = 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");
+class AxiaLeaseProvider {
     constructor(config) {
         this._initialized = false;
         this.apiUrl = config.apiUrl;
         this.apiKey = config.apiKey;
         this.rootPublicKey = config.rootPublicKey;
-        this.logger = config.logger ?? new NoopLogger();
-        this.watermark = new WotsWatermarkStore(config.storage, this.logger);
-        this.leaseStore = new LeaseStore(config.storage, this.logger);
-        this.journal = new LeaseJournal(config.storage, this.logger);
+        this.logger = config.logger ?? new core_1.NoopLogger();
+        this.watermark = new watermark_js_1.WotsWatermarkStore(config.storage, this.logger);
+        this.leaseStore = new core_1.LeaseStore(config.storage, this.logger);
+        this.journal = new journal_js_1.LeaseJournal(config.storage, this.logger);
     }
     async initialize() {
         if (this._initialized)
@@ -31,7 +34,7 @@ export class AxiaLeaseProvider {
         if (!this._initialized)
             await this.initialize();
         const txId = params.payloadHash ?? `tx-${Date.now()}`;
-        const resp = await prepareLease(this.apiUrl, this.apiKey, {
+        const resp = await (0, core_2.prepareLease)(this.apiUrl, this.apiKey, {
             txId,
             rootPublicKey: this.rootPublicKey,
             to: params.treeId,
@@ -44,6 +47,7 @@ export class AxiaLeaseProvider {
         const lease = {
             leaseId: reservationId,
             leaseToken: resp.leaseToken,
+            treeId: params.treeId,
             indices,
             expiresAt,
             status: 'active',
@@ -54,7 +58,7 @@ export class AxiaLeaseProvider {
         await this.journal.append({
             treeId: params.treeId,
             branchId: params.branchId ?? 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'reserved',
             payloadHash: params.payloadHash,
@@ -68,15 +72,15 @@ export class AxiaLeaseProvider {
             await this.initialize();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new LeaseNotFoundError(reservationId);
-        await finalizeLease(this.apiUrl, this.apiKey, lease.leaseToken, txId);
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
+        await (0, core_2.finalizeLease)(this.apiUrl, this.apiKey, lease.leaseToken, txId);
         const indices = lease.indices;
         await this.watermark.markUnavailable(lease.indices.addressIndex.toString(), indices, 'committed');
         await this.leaseStore.updateStatus(reservationId, 'finalized');
         await this.journal.append({
             treeId: reservationId,
             branchId: 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'committed',
             txId,
@@ -89,7 +93,7 @@ export class AxiaLeaseProvider {
             await this.initialize();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new LeaseNotFoundError(reservationId);
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
         const indices = lease.indices;
         await this.watermark.markUnavailable(lease.indices.addressIndex.toString(), indices, 'burned');
         await this.leaseStore.updateStatus(reservationId, 'cancelled');
@@ -97,7 +101,7 @@ export class AxiaLeaseProvider {
         await this.journal.append({
             treeId: reservationId,
             branchId: 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'burned',
             timestamp: Date.now(),
@@ -121,3 +125,4 @@ export class AxiaLeaseProvider {
         return false;
     }
 }
+exports.AxiaLeaseProvider = AxiaLeaseProvider;

package/dist/device.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Device keyspace partitioning — Layer 2.
  *
@@ -10,9 +11,12 @@
  *   device 2 → addressIndex 16–23
  *   ...
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allocateDeviceRange = allocateDeviceRange;
+exports.deviceSlotForAddressIndex = deviceSlotForAddressIndex;
 const ADDRESSES_PER_DEVICE = 8;
 const MAX_DEVICE_SLOTS = 8;
-export function allocateDeviceRange(params) {
+function allocateDeviceRange(params) {
     if (params.deviceSlot < 0 || params.deviceSlot >= MAX_DEVICE_SLOTS) {
         throw new RangeError(`Device slot must be 0–${MAX_DEVICE_SLOTS - 1}, got ${params.deviceSlot}`);
     }
@@ -25,6 +29,6 @@ export function allocateDeviceRange(params) {
         addressCount: ADDRESSES_PER_DEVICE,
     };
 }
-export function deviceSlotForAddressIndex(addressIndex) {
+function deviceSlotForAddressIndex(addressIndex) {
     return Math.floor(addressIndex / ADDRESSES_PER_DEVICE);
 }

package/dist/errors.js

@@ -1,43 +1,52 @@
-export class WatermarkMonotonicityError extends Error {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceRangeViolationError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = void 0;
+class WatermarkMonotonicityError extends Error {
     constructor(message) {
         super(message);
         this.name = 'WatermarkMonotonicityError';
     }
 }
-export class WatermarkExhaustedError extends Error {
+exports.WatermarkMonotonicityError = WatermarkMonotonicityError;
+class WatermarkExhaustedError extends Error {
     constructor(treeId) {
         super(`WOTS keyspace exhausted for tree: ${treeId}`);
         this.treeId = treeId;
         this.name = 'WatermarkExhaustedError';
     }
 }
-export class LeaseNotFoundError extends Error {
+exports.WatermarkExhaustedError = WatermarkExhaustedError;
+class LeaseNotFoundError extends Error {
     constructor(reservationId) {
         super(`Lease reservation not found: ${reservationId}`);
         this.reservationId = reservationId;
         this.name = 'LeaseNotFoundError';
     }
 }
-export class PersonalLeaseNodeNotConfiguredError extends Error {
+exports.LeaseNotFoundError = LeaseNotFoundError;
+class PersonalLeaseNodeNotConfiguredError extends Error {
     constructor() {
         super('PersonalLeaseNodeProvider requires a running lookup node. ' +
             'Deploy @totemsdk/lookup-node and configure { nodeUrl, nodePubkey }.');
         this.name = 'PersonalLeaseNodeNotConfiguredError';
     }
 }
-export class P2PQuorumNotImplementedError extends Error {
+exports.PersonalLeaseNodeNotConfiguredError = PersonalLeaseNodeNotConfiguredError;
+class P2PQuorumNotImplementedError extends Error {
     constructor() {
         super('P2PQuorumLeaseProvider is not yet implemented.');
         this.name = 'P2PQuorumNotImplementedError';
     }
 }
-export class OnchainWatermarkNotImplementedError extends Error {
+exports.P2PQuorumNotImplementedError = P2PQuorumNotImplementedError;
+class OnchainWatermarkNotImplementedError extends Error {
     constructor() {
         super('OnchainWatermarkProvider is not yet implemented.');
         this.name = 'OnchainWatermarkNotImplementedError';
     }
 }
-export class DeviceRangeViolationError extends Error {
+exports.OnchainWatermarkNotImplementedError = OnchainWatermarkNotImplementedError;
+class DeviceRangeViolationError extends Error {
     constructor(addressIndex, allowedStart, allowedEnd) {
         super(`Address index ${addressIndex} is outside device range [${allowedStart}, ${allowedEnd}]`);
         this.addressIndex = addressIndex;
@@ -46,3 +55,4 @@ export class DeviceRangeViolationError extends Error {
         this.name = 'DeviceRangeViolationError';
     }
 }
+exports.DeviceRangeViolationError = DeviceRangeViolationError;

package/dist/hybrid.js

@@ -1,10 +1,13 @@
+"use strict";
 /**
  * HybridLeaseProvider — recommended production default.
  *
  * Always uses local first, then gates on node cert and/or quorum attestation
  * for transactions above a configurable value threshold.
  */
-export class HybridLeaseProvider {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridLeaseProvider = void 0;
+class HybridLeaseProvider {
     constructor(config) {
         this.local = config.local;
         this.node = config.node;
@@ -62,3 +65,4 @@ export class HybridLeaseProvider {
         return false;
     }
 }
+exports.HybridLeaseProvider = HybridLeaseProvider;

package/dist/index.js

@@ -1,8 +1,30 @@
-export { WotsWatermarkStore, flatIndex, fromFlatIndex, } from './watermark.js';
-export { LeaseJournal } from './journal.js';
-export { LocalLeaseProvider } from './local.js';
-export { AxiaLeaseProvider } from './axia.js';
-export { HybridLeaseProvider } from './hybrid.js';
-export { PersonalLeaseNodeProvider, P2PQuorumLeaseProvider, OnchainWatermarkProvider, } from './stubs.js';
-export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
-export { WatermarkMonotonicityError, WatermarkExhaustedError, LeaseNotFoundError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, DeviceRangeViolationError, } from './errors.js';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceRangeViolationError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = exports.HybridLeaseProvider = exports.AxiaLeaseProvider = exports.LocalLeaseProvider = exports.LeaseJournal = exports.fromFlatIndex = exports.flatIndex = exports.WotsWatermarkStore = void 0;
+var watermark_js_1 = require("./watermark.js");
+Object.defineProperty(exports, "WotsWatermarkStore", { enumerable: true, get: function () { return watermark_js_1.WotsWatermarkStore; } });
+Object.defineProperty(exports, "flatIndex", { enumerable: true, get: function () { return watermark_js_1.flatIndex; } });
+Object.defineProperty(exports, "fromFlatIndex", { enumerable: true, get: function () { return watermark_js_1.fromFlatIndex; } });
+var journal_js_1 = require("./journal.js");
+Object.defineProperty(exports, "LeaseJournal", { enumerable: true, get: function () { return journal_js_1.LeaseJournal; } });
+var local_js_1 = require("./local.js");
+Object.defineProperty(exports, "LocalLeaseProvider", { enumerable: true, get: function () { return local_js_1.LocalLeaseProvider; } });
+var axia_js_1 = require("./axia.js");
+Object.defineProperty(exports, "AxiaLeaseProvider", { enumerable: true, get: function () { return axia_js_1.AxiaLeaseProvider; } });
+var hybrid_js_1 = require("./hybrid.js");
+Object.defineProperty(exports, "HybridLeaseProvider", { enumerable: true, get: function () { return hybrid_js_1.HybridLeaseProvider; } });
+var stubs_js_1 = require("./stubs.js");
+Object.defineProperty(exports, "PersonalLeaseNodeProvider", { enumerable: true, get: function () { return stubs_js_1.PersonalLeaseNodeProvider; } });
+Object.defineProperty(exports, "P2PQuorumLeaseProvider", { enumerable: true, get: function () { return stubs_js_1.P2PQuorumLeaseProvider; } });
+Object.defineProperty(exports, "OnchainWatermarkProvider", { enumerable: true, get: function () { return stubs_js_1.OnchainWatermarkProvider; } });
+var device_js_1 = require("./device.js");
+Object.defineProperty(exports, "allocateDeviceRange", { enumerable: true, get: function () { return device_js_1.allocateDeviceRange; } });
+Object.defineProperty(exports, "deviceSlotForAddressIndex", { enumerable: true, get: function () { return device_js_1.deviceSlotForAddressIndex; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "WatermarkMonotonicityError", { enumerable: true, get: function () { return errors_js_1.WatermarkMonotonicityError; } });
+Object.defineProperty(exports, "WatermarkExhaustedError", { enumerable: true, get: function () { return errors_js_1.WatermarkExhaustedError; } });
+Object.defineProperty(exports, "LeaseNotFoundError", { enumerable: true, get: function () { return errors_js_1.LeaseNotFoundError; } });
+Object.defineProperty(exports, "PersonalLeaseNodeNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PersonalLeaseNodeNotConfiguredError; } });
+Object.defineProperty(exports, "P2PQuorumNotImplementedError", { enumerable: true, get: function () { return errors_js_1.P2PQuorumNotImplementedError; } });
+Object.defineProperty(exports, "OnchainWatermarkNotImplementedError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkNotImplementedError; } });
+Object.defineProperty(exports, "DeviceRangeViolationError", { enumerable: true, get: function () { return errors_js_1.DeviceRangeViolationError; } });

package/dist/journal.d.ts

@@ -12,6 +12,7 @@ export declare class LeaseJournal {
     constructor(storage: StorageAdapter, logger?: LoggerAdapter);
     initialize(): Promise<void>;
     append(entry: JournalEntry): Promise<void>;
+    private _verifyChain;
     getAll(): JournalEntry[];
     getByTree(treeId: string): JournalEntry[];
     getByReservation(reservationId: string): JournalEntry | undefined;

package/dist/journal.js

@@ -1,11 +1,30 @@
+"use strict";
 /**
  * LeaseJournal — append-only audit log for WOTS key-use events.
  * Preserves the full history: reserved → committed | burned | reserved-expired.
  */
-import { NoopLogger } from '@totemsdk/core';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaseJournal = void 0;
+const crypto_1 = require("crypto");
+const core_1 = require("@totemsdk/core");
 const STORAGE_KEY = 'totem_wots_journal';
-export class LeaseJournal {
-    constructor(storage, logger = new NoopLogger()) {
+function hashEntry(entry) {
+    const encoder = new TextEncoder();
+    const data = {
+        t: entry.treeId,
+        b: entry.branchId,
+        i: entry.wotsIndex,
+        s: entry.status,
+        r: entry.reservationId,
+        p: entry.previousHash,
+        ts: entry.timestamp,
+        d: entry.deviceId,
+    };
+    const bytes = encoder.encode(JSON.stringify(data));
+    return (0, crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+class LeaseJournal {
+    constructor(storage, logger = new core_1.NoopLogger()) {
         this.storage = storage;
         this.logger = logger;
         this.entries = [];
@@ -16,12 +35,40 @@ export class LeaseJournal {
             return;
         const stored = await this.storage.get(STORAGE_KEY);
         this.entries = stored ?? [];
+        if (this.entries.length > 0) {
+            const ok = this._verifyChain();
+            if (!ok) {
+                this.logger.error('[LeaseJournal] hash chain integrity check FAILED — journal may be tampered');
+                throw new Error('Journal hash chain integrity check failed');
+            }
+        }
         this._initialized = true;
     }
     async append(entry) {
+        const prev = this.entries[this.entries.length - 1];
+        entry.previousHash = prev?.hash;
+        entry.hash = hashEntry(entry);
         this.entries.push(entry);
         await this.storage.set(STORAGE_KEY, this.entries);
-        this.logger.debug(`[LeaseJournal] ${entry.status} treeId=${entry.treeId} idx=${entry.wotsIndex} txId=${entry.txId ?? '-'}`);
+        this.logger.debug(`[LeaseJournal] ${entry.status} treeId=${entry.treeId} idx=${entry.wotsIndex} txId=${entry.txId ?? '-'} hash=${entry.hash.slice(0, 8)}`);
+    }
+    _verifyChain() {
+        for (let i = 0; i < this.entries.length; i++) {
+            const e = this.entries[i];
+            const expectedHash = hashEntry(e);
+            if (e.hash !== expectedHash) {
+                this.logger.error(`[LeaseJournal] hash mismatch at entry ${i}: expected ${expectedHash}, stored ${e.hash}`);
+                return false;
+            }
+            if (i > 0) {
+                const prevHash = this.entries[i - 1].hash;
+                if (e.previousHash !== prevHash) {
+                    this.logger.error(`[LeaseJournal] previousHash mismatch at entry ${i}: expected ${prevHash}, stored ${e.previousHash}`);
+                    return false;
+                }
+            }
+        }
+        return true;
     }
     getAll() {
         return [...this.entries];
@@ -37,3 +84,4 @@ export class LeaseJournal {
         await this.storage.remove(STORAGE_KEY);
     }
 }
+exports.LeaseJournal = LeaseJournal;

package/dist/local.d.ts

@@ -13,10 +13,12 @@ export declare class LocalLeaseProvider implements WotsLeaseProvider {
     private readonly journal;
     private _initialized;
     private readonly deviceId;
-    /** In-memory map: reservationId → treeId (lost on restart; watermark survives). */
-    private readonly _treeIdByReservation;
     constructor(storage: StorageAdapter, logger?: LoggerAdapter, deviceId?: string);
     initialize(): Promise<void>;
+    /** 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. */
+    private burnUnresolvedReservations;
     private recoverExpiredReservations;
     reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
     commitKeyUse(reservationId: string, txId: string): Promise<void>;

package/dist/local.js

@@ -1,29 +1,30 @@
+"use strict";
 /**
  * LocalLeaseProvider — Layer 1: local durable ledger.
  *
  * Single-device, no network coordination.
  * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
  */
-import { NoopLogger } from '@totemsdk/core';
-import { LeaseStore } from '@totemsdk/core';
-import { WotsWatermarkStore, flatIndex } from './watermark.js';
-import { LeaseJournal } from './journal.js';
-import { LeaseNotFoundError, DeviceRangeViolationError } from './errors.js';
+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);
 }
-export class LocalLeaseProvider {
-    constructor(storage, logger = new NoopLogger(), deviceId = 'local') {
+class LocalLeaseProvider {
+    constructor(storage, logger = new core_1.NoopLogger(), deviceId = 'local') {
         this.logger = logger;
         this._initialized = false;
-        /** In-memory map: reservationId → treeId (lost on restart; watermark survives). */
-        this._treeIdByReservation = new Map();
-        this.watermark = new WotsWatermarkStore(storage, logger);
-        this.leaseStore = new LeaseStore(storage, logger);
-        this.journal = new LeaseJournal(storage, logger);
+        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;
     }
     async initialize() {
@@ -33,21 +34,46 @@ export class LocalLeaseProvider {
         await this.leaseStore.initialize();
         await this.journal.initialize();
         await this.recoverExpiredReservations();
+        await this.burnUnresolvedReservations();
         this._initialized = true;
     }
+    /** 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)`);
+                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) {
-                const treeId = this._treeIdByReservation.get(lease.leaseId) ?? 'default';
+                const treeId = lease.treeId ?? 'default';
                 await this.watermark.markUnavailable(treeId, lease.indices, 'reserved-expired');
                 await this.leaseStore.updateStatus(lease.leaseId, 'expired');
                 await this.journal.append({
                     treeId,
                     branchId: 'default',
-                    wotsIndex: flatIndex(lease.indices),
+                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
                     indices: lease.indices,
                     status: 'reserved-expired',
+                    reservationId: lease.leaseId,
                     timestamp: now,
                     deviceId: this.deviceId,
                 });
@@ -59,11 +85,13 @@ export class LocalLeaseProvider {
             await this.initialize();
         const treeId = params.treeId;
         const ttlMs = params.ttlMs ?? 120000;
+        // Atomically get the next available index AND mark it reserved in the watermark
         const indices = this.watermark.getNextIndices(treeId);
+        await this.watermark.markUnavailable(treeId, indices, 'reserved');
         if (params.deviceId) {
             const range = this.getDeviceRange(params.deviceId);
             if (range && (indices.addressIndex < range.start || indices.addressIndex > range.end)) {
-                throw new DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
+                throw new errors_js_1.DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
             }
         }
         const reservationId = randomId();
@@ -71,6 +99,7 @@ export class LocalLeaseProvider {
         const lease = {
             leaseId: reservationId,
             leaseToken: reservationId,
+            treeId,
             indices,
             expiresAt,
             status: 'active',
@@ -78,14 +107,13 @@ export class LocalLeaseProvider {
             leaseTTL: ttlMs,
         };
         await this.leaseStore.save(lease);
-        // Track treeId in memory so commit/burn can reference the right watermark tree
-        this._treeIdByReservation.set(reservationId, treeId);
         await this.journal.append({
             treeId,
             branchId: params.branchId ?? 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'reserved',
+            reservationId,
             payloadHash: params.payloadHash,
             timestamp: Date.now(),
             deviceId: params.deviceId ?? this.deviceId,
@@ -97,18 +125,20 @@ export class LocalLeaseProvider {
             await this.initialize();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new LeaseNotFoundError(reservationId);
-        const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
+            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');
-        this._treeIdByReservation.delete(reservationId);
         await this.journal.append({
             treeId,
             branchId: 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'committed',
+            reservationId,
             txId,
             timestamp: Date.now(),
             deviceId: this.deviceId,
@@ -119,19 +149,19 @@ export class LocalLeaseProvider {
             await this.initialize();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new LeaseNotFoundError(reservationId);
-        const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
+            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._treeIdByReservation.delete(reservationId);
         this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
         await this.journal.append({
             treeId,
             branchId: 'default',
-            wotsIndex: flatIndex(indices),
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
             indices,
             status: 'burned',
+            reservationId,
             timestamp: Date.now(),
             deviceId: this.deviceId,
         });
@@ -161,3 +191,4 @@ export class LocalLeaseProvider {
         return { start: slot * 8, end: slot * 8 + 7 };
     }
 }
+exports.LocalLeaseProvider = LocalLeaseProvider;

package/dist/stubs.d.ts

@@ -1,23 +1,46 @@
 /**
- * Stub implementations for Layers 3–5.
- * These throw descriptive errors until the full implementations land.
+ * 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) — require
+ *   distributed infrastructure not yet available; they throw descriptive errors.
  */
 import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, PersonalLeaseNodeConfig } from './types.js';
 /**
- * Layer 3 — personal p2p lease node.
+ * 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.
  *
- * Verifies ed25519 certs issued by a configured node public key.
- * Reserve/commit throws until the node is reachable — callers should
- * wrap with HybridLeaseProvider using a LocalLeaseProvider as the local layer.
+ * 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 config;
+    private readonly baseUrl;
+    private readonly nodePubkey;
+    private readonly authToken?;
     constructor(config: PersonalLeaseNodeConfig);
-    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>;
+    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>;
 }