@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/hybrid.js

@@ -1,19 +1,18 @@
-"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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HybridLeaseProvider = void 0;
-class HybridLeaseProvider {
+import { signCertificate, certificateSignatureVerified } from './certificate.js';
+export class HybridLeaseProvider {
     constructor(config) {
         this.local = config.local;
         this.node = config.node;
         this.quorum = config.quorum;
         this.onchain = config.onchain;
         this.threshold = config.threshold ?? Infinity;
+        this.certificateSigner = config.certificateSigner;
     }
     isHighValue(params) {
         if (!params.valueHint)
@@ -22,29 +21,41 @@ class HybridLeaseProvider {
         return !isNaN(val) && val >= this.threshold;
     }
     async reserveKeyUse(params) {
+        // Cross-instance/restore safety (RFC-013 §8/§9): before a high-value
+        // reservation, anchor the local cursor to the on-chain watermark so a second
+        // instance of the same seed cannot be handed a leaf we already used.
+        if (this.isHighValue(params) && this.onchain) {
+            try {
+                await this.onchain.syncLeaseJournal();
+            }
+            catch {
+                // Chain unreachable — local monotonic watermark still guards reuse.
+            }
+        }
         const reservation = await this.local.reserveKeyUse(params);
         if (this.isHighValue(params)) {
             // Layer 4 — quorum attestation over the SAME local slot.
             if (this.quorum) {
                 try {
                     const attestations = await this.quorum.attestKeyUse(params, reservation.indices);
-                    return {
-                        ...reservation,
-                        certificate: {
-                            reservationId: reservation.reservationId,
-                            treeId: params.treeId,
-                            branchId: params.branchId,
-                            deviceId: params.deviceId,
-                            indices: reservation.indices,
-                            purpose: params.purpose,
-                            payloadHash: params.payloadHash,
-                            issuedBy: 'p2p-quorum',
-                            issuedAt: Date.now(),
-                            expiresAt: reservation.expiresAt,
-                            signature: '',
-                            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 signCertificate(this.certificateSigner, certificate)
+                        : '';
+                    return { ...reservation, certificate };
                 }
                 catch {
                     // Quorum unavailable — fall through to node / local only.
@@ -72,24 +83,59 @@ class HybridLeaseProvider {
     getLocalWatermark(treeId) {
         return this.local.getLocalWatermark(treeId);
     }
-    publishWatermark(treeId) {
+    async publishWatermark(treeId) {
+        // Anchor to the chain first (authoritative cross-instance cursor), then the
+        // personal node, then the local no-op.
+        if (this.onchain) {
+            try {
+                await this.onchain.publishWatermark(treeId);
+                return;
+            }
+            catch {
+                // fall through
+            }
+        }
         if (this.node) {
-            return this.node.publishWatermark(treeId).catch(() => this.local.publishWatermark(treeId));
+            try {
+                await this.node.publishWatermark(treeId);
+                return;
+            }
+            catch {
+                // fall through
+            }
         }
-        return this.local.publishWatermark(treeId);
+        await this.local.publishWatermark(treeId);
     }
-    syncLeaseJournal() {
+    async syncLeaseJournal() {
+        // Read the authoritative on-chain cursor first so a restore/second instance
+        // advances past every leaf published by anyone holding this seed.
+        if (this.onchain) {
+            try {
+                return await this.onchain.syncLeaseJournal();
+            }
+            catch {
+                // fall through
+            }
+        }
         if (this.node) {
-            return this.node.syncLeaseJournal().catch(() => this.local.syncLeaseJournal());
+            try {
+                return await this.node.syncLeaseJournal();
+            }
+            catch {
+                // fall through
+            }
         }
         return this.local.syncLeaseJournal();
     }
     async verifyLeaseCertificate(cert) {
         if (!cert)
             return this.local.verifyLeaseCertificate(cert);
+        // Locally-assembled quorum certificates authenticate against our issuer.
+        if (cert.issuedBy === (this.certificateSigner?.name ?? 'p2p-quorum')) {
+            return certificateSignatureVerified(cert, this.certificateSigner);
+        }
         if (this.node)
             return this.node.verifyLeaseCertificate(cert);
         return false;
     }
 }
-exports.HybridLeaseProvider = HybridLeaseProvider;

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-export type { UnavailableReason, SigningIndices, LeaseStatus, TreeWatermark, WotsWatermarkState, LeaseCertificate, LeaseReservation, ReserveParams, LocalWatermark, ConflictRecord, SyncResult, WotsLeaseProvider, JournalEntry, DeviceKeyRange, PersonalLeaseNodeConfig, QuorumAttestation, QuorumPeer, P2PQuorumLeaseProviderConfig, OnchainWatermarkProviderConfig, } from './types.js';
+export type { UnavailableReason, SigningIndices, LeaseStatus, TreeWatermark, WotsWatermarkState, LeaseCertificate, LeaseReservation, ReserveParams, LocalWatermark, WatermarkSeed, SeedWatermarkOptions, ConflictRecord, SyncResult, WotsLeaseProvider, JournalEntry, DeviceKeyRange, PersonalLeaseNodeConfig, QuorumAttestation, QuorumPeer, CertificateSigner, P2PQuorumLeaseProviderConfig, OnchainWatermarkProviderConfig, } from './types.js';
 export { WotsWatermarkStore, flatIndex, fromFlatIndex, } from './watermark.js';
 export { LeaseJournal } from './journal.js';
 export { LocalLeaseProvider } from './local.js';
+export { seedLeaseWatermark, exportLeaseWatermark } from './seed.js';
+export type { SeedLeaseWatermarkParams } from './seed.js';
 export { AxiaLeaseProvider } from './axia.js';
 export type { AxiaLeaseProviderConfig } from './axia.js';
 export { HybridLeaseProvider } from './hybrid.js';
@@ -10,4 +12,6 @@ export { PersonalLeaseNodeProvider, P2PQuorumLeaseProvider, OnchainWatermarkProv
 export { P2PQuorumLeaseProvider as QuorumLeaseProvider } from './quorum.js';
 export { OnchainWatermarkProvider as ChainWatermarkProvider } from './onchain.js';
 export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
-export { WatermarkMonotonicityError, WatermarkExhaustedError, LeaseNotFoundError, IndicesUnavailableError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, QuorumUnavailableError, QuorumConflictError, OnchainWatermarkError, DeviceRangeViolationError, } from './errors.js';
+export { WatermarkMonotonicityError, WatermarkExhaustedError, WatermarkSeedRegressionError, WatermarkSeedRequiredError, LeaseNotFoundError, IndicesUnavailableError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, QuorumUnavailableError, QuorumConflictError, OnchainWatermarkError, DeviceRangeViolationError, } from './errors.js';
+export { ReplicatedLeaseJournalBackup } from './replicated-backup.js';
+export type { LeaseJournalRestoreTarget } from './replicated-backup.js';

package/dist/index.js

@@ -1,38 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeviceRangeViolationError = exports.OnchainWatermarkError = exports.QuorumConflictError = exports.QuorumUnavailableError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.IndicesUnavailableError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.ChainWatermarkProvider = exports.QuorumLeaseProvider = 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 quorum_js_1 = require("./quorum.js");
-Object.defineProperty(exports, "QuorumLeaseProvider", { enumerable: true, get: function () { return quorum_js_1.P2PQuorumLeaseProvider; } });
-var onchain_js_1 = require("./onchain.js");
-Object.defineProperty(exports, "ChainWatermarkProvider", { enumerable: true, get: function () { return onchain_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, "IndicesUnavailableError", { enumerable: true, get: function () { return errors_js_1.IndicesUnavailableError; } });
-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, "QuorumUnavailableError", { enumerable: true, get: function () { return errors_js_1.QuorumUnavailableError; } });
-Object.defineProperty(exports, "QuorumConflictError", { enumerable: true, get: function () { return errors_js_1.QuorumConflictError; } });
-Object.defineProperty(exports, "OnchainWatermarkError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkError; } });
-Object.defineProperty(exports, "DeviceRangeViolationError", { enumerable: true, get: function () { return errors_js_1.DeviceRangeViolationError; } });
+export { WotsWatermarkStore, flatIndex, fromFlatIndex, } from './watermark.js';
+export { LeaseJournal } from './journal.js';
+export { LocalLeaseProvider } from './local.js';
+export { seedLeaseWatermark, exportLeaseWatermark } from './seed.js';
+export { AxiaLeaseProvider } from './axia.js';
+export { HybridLeaseProvider } from './hybrid.js';
+export { PersonalLeaseNodeProvider, P2PQuorumLeaseProvider, OnchainWatermarkProvider, } from './stubs.js';
+export { P2PQuorumLeaseProvider as QuorumLeaseProvider } from './quorum.js';
+export { OnchainWatermarkProvider as ChainWatermarkProvider } from './onchain.js';
+export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
+export { WatermarkMonotonicityError, WatermarkExhaustedError, WatermarkSeedRegressionError, WatermarkSeedRequiredError, LeaseNotFoundError, IndicesUnavailableError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, QuorumUnavailableError, QuorumConflictError, OnchainWatermarkError, DeviceRangeViolationError, } from './errors.js';
+export { ReplicatedLeaseJournalBackup } from './replicated-backup.js';

package/dist/journal.d.ts

@@ -1,6 +1,9 @@
 /**
- * LeaseJournal — append-only audit log for WOTS key-use events.
- * Preserves the full history: reserved → committed | burned | reserved-expired.
+ * LeaseJournal — physically append-only audit log for WOTS key-use events.
+ *
+ * Layout v1 stores one immutable record per sequence. The legacy whole-array
+ * key is retained as migration input/forensic history but is never rewritten.
+ * The SHA-256 chain format is intentionally unchanged (RFC-007 OQ3).
  */
 import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
 import type { JournalEntry } from './types.js';
@@ -8,11 +11,18 @@ export declare class LeaseJournal {
     private readonly storage;
     private readonly logger;
     private entries;
-    private _initialized;
+    private initialized;
+    private initializePromise;
+    private appendTail;
     constructor(storage: StorageAdapter, logger?: LoggerAdapter);
     initialize(): Promise<void>;
+    private initializeOnce;
+    private readLegacyEntries;
+    private readPhysicalRecords;
+    private writeRecord;
     append(entry: JournalEntry): Promise<void>;
-    private _verifyChain;
+    private appendOne;
+    private ensureInitialized;
     getAll(): JournalEntry[];
     getByTree(treeId: string): JournalEntry[];
     getByReservation(reservationId: string): JournalEntry | undefined;