@totemsdk/wots-lease 1.0.1 → 1.0.2

package/dist/cjs/certificate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared helpers for authenticating lease certificates.
+ *
+ * A certificate is authenticated by a real signature over a canonical,
+ * deterministic byte encoding of its content. Providers that hold an issuing
+ * identity (`certificateSigner`, or the watermark coin owner on Layer 5) sign
+ * the payload before returning the certificate. Verification FAILS CLOSED:
+ * a certificate is rejected unless the caller supplies a `verify()` function
+ * and the signature cryptographically verifies against it. An empty signature,
+ * an absent verifier, or an identity without a verifier are all rejections —
+ * `issuedBy` alone is never treated as authenticity evidence.
+ */
+import type { CertificateSigner, LeaseCertificate } from './types.js';
+/**
+ * Canonical byte encoding of a certificate's bindable content.
+ *
+ * Any change to a bound field changes the message, so a certificate cannot
+ * be re-targeted at a different reservation, device, purpose, or expiry.
+ */
+export declare function canonicalCertificateMessage(cert: Pick<LeaseCertificate, 'treeId' | 'branchId' | 'deviceId' | 'indices' | 'purpose' | 'payloadHash' | 'reservationId' | 'issuedBy' | 'issuedAt' | 'expiresAt'>): Uint8Array;
+/** Sign a certificate via the issuer identity, returning hex of the signature. */
+export declare function signCertificate(signer: {
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}, cert: Parameters<typeof canonicalCertificateMessage>[0]): Promise<string>;
+/**
+ * Verify a certificate's signature.
+ *
+ * Fails closed (AUD-016):
+ * - Empty/malformed signature -> false (an unsigned certificate is not
+ *   authenticity evidence regardless of what issuedBy claims).
+ * - No `signer`, or a `signer` without a `verify()` function -> false. Knowing
+ *   only an identity (e.g. a public key digest) cannot authenticate a
+ *   signature; a verifier is required.
+ * - Otherwise the signature must cryptographically verify against the
+ *   supplied verifier.
+ */
+export declare function certificateSignatureVerified(cert: LeaseCertificate, signer?: CertificateSigner): Promise<boolean>;

package/dist/cjs/certificate.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Shared helpers for authenticating lease certificates.
+ *
+ * A certificate is authenticated by a real signature over a canonical,
+ * deterministic byte encoding of its content. Providers that hold an issuing
+ * identity (`certificateSigner`, or the watermark coin owner on Layer 5) sign
+ * the payload before returning the certificate. Verification FAILS CLOSED:
+ * a certificate is rejected unless the caller supplies a `verify()` function
+ * and the signature cryptographically verifies against it. An empty signature,
+ * an absent verifier, or an identity without a verifier are all rejections —
+ * `issuedBy` alone is never treated as authenticity evidence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalCertificateMessage = canonicalCertificateMessage;
+exports.signCertificate = signCertificate;
+exports.certificateSignatureVerified = certificateSignatureVerified;
+const core_1 = require("@totemsdk/core");
+/**
+ * Canonical byte encoding of a certificate's bindable content.
+ *
+ * Any change to a bound field changes the message, so a certificate cannot
+ * be re-targeted at a different reservation, device, purpose, or expiry.
+ */
+function canonicalCertificateMessage(cert) {
+    const encoded = new TextEncoder().encode([
+        'TOTEM-LEASECERT',
+        'v1',
+        cert.issuedBy ?? '',
+        cert.treeId ?? '',
+        cert.branchId ?? '',
+        cert.deviceId ?? '',
+        cert.reservationId ?? '',
+        String(cert.indices?.addressIndex ?? 0),
+        String(cert.indices?.l1 ?? 0),
+        String(cert.indices?.l2 ?? 0),
+        cert.purpose ?? '',
+        cert.payloadHash ?? '',
+        String(cert.issuedAt ?? 0),
+        String(cert.expiresAt ?? 0),
+    ].join('\x1f'));
+    return (0, core_1.sha3_256)(encoded);
+}
+/** Sign a certificate via the issuer identity, returning hex of the signature. */
+async function signCertificate(signer, cert) {
+    return (0, core_1.bytesToHex)(await signer.sign(canonicalCertificateMessage(cert)));
+}
+/**
+ * Verify a certificate's signature.
+ *
+ * Fails closed (AUD-016):
+ * - Empty/malformed signature -> false (an unsigned certificate is not
+ *   authenticity evidence regardless of what issuedBy claims).
+ * - No `signer`, or a `signer` without a `verify()` function -> false. Knowing
+ *   only an identity (e.g. a public key digest) cannot authenticate a
+ *   signature; a verifier is required.
+ * - Otherwise the signature must cryptographically verify against the
+ *   supplied verifier.
+ */
+async function certificateSignatureVerified(cert, signer) {
+    if (typeof cert.signature !== 'string' || cert.signature.length === 0) {
+        return false;
+    }
+    if (!signer?.verify)
+        return false;
+    let sig;
+    try {
+        sig = (0, core_1.hexToBytes)(cert.signature);
+    }
+    catch {
+        return false;
+    }
+    return signer.verify(canonicalCertificateMessage(cert), sig);
+}

package/dist/cjs/device.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Device keyspace partitioning — Layer 2.
+ *
+ * Deterministic address-index range assignment per device slot.
+ * Does NOT accept a raw seed; the caller derives the TreeKey in @totemsdk/core.
+ *
+ * Layout (8 device slots × 8 addresses each = 64 total):
+ *   device 0 → addressIndex 0–7
+ *   device 1 → addressIndex 8–15
+ *   device 2 → addressIndex 16–23
+ *   ...
+ */
+import type { DeviceKeyRange } from './types.js';
+export declare function allocateDeviceRange(params: {
+    deviceSlot: number;
+    deviceId: string;
+}): DeviceKeyRange;
+export declare function deviceSlotForAddressIndex(addressIndex: number): number;

package/dist/cjs/device.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Device keyspace partitioning — Layer 2.
+ *
+ * Deterministic address-index range assignment per device slot.
+ * Does NOT accept a raw seed; the caller derives the TreeKey in @totemsdk/core.
+ *
+ * Layout (8 device slots × 8 addresses each = 64 total):
+ *   device 0 → addressIndex 0–7
+ *   device 1 → addressIndex 8–15
+ *   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;
+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}`);
+    }
+    const startAddressIndex = params.deviceSlot * ADDRESSES_PER_DEVICE;
+    const endAddressIndex = startAddressIndex + ADDRESSES_PER_DEVICE - 1;
+    return {
+        deviceId: params.deviceId,
+        startAddressIndex,
+        endAddressIndex,
+        addressCount: ADDRESSES_PER_DEVICE,
+    };
+}
+function deviceSlotForAddressIndex(addressIndex) {
+    return Math.floor(addressIndex / ADDRESSES_PER_DEVICE);
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,71 @@
+import type { SigningIndices } from './types.js';
+export declare class WatermarkMonotonicityError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when seeding would move the local watermark cursor backwards. This is
+ * the fail-closed guard against restoring a wallet below its true high-water
+ * mark and reusing a WOTS leaf (RFC-013 §9).
+ */
+export declare class WatermarkSeedRegressionError extends Error {
+    readonly treeId: string;
+    readonly currentCursor: number;
+    readonly seedCursor: number;
+    constructor(treeId: string, currentCursor: number, seedCursor: number);
+}
+/**
+ * Raised when a restore/import has no usable watermark source and the caller has
+ * not declared the keyspace fresh. Failing closed is required: starting at 0
+ * would reissue spent leaves (RFC-013 §9).
+ */
+export declare class WatermarkSeedRequiredError extends Error {
+    readonly treeId: string;
+    constructor(treeId: string);
+}
+export declare class WatermarkExhaustedError extends Error {
+    readonly treeId: string;
+    constructor(treeId: string);
+}
+export declare class LeaseNotFoundError extends Error {
+    readonly reservationId: string;
+    constructor(reservationId: string);
+}
+export declare class InvalidLeaseTransitionError extends Error {
+    readonly reservationId: string;
+    readonly currentStatus: string;
+    readonly requestedStatus: string;
+    constructor(reservationId: string, currentStatus: string, requestedStatus: string);
+}
+export declare class IndicesUnavailableError extends Error {
+    readonly treeId: string;
+    readonly indices: SigningIndices;
+    constructor(treeId: string, indices: SigningIndices);
+}
+export declare class PersonalLeaseNodeNotConfiguredError extends Error {
+    constructor();
+}
+export declare class P2PQuorumNotImplementedError extends Error {
+    constructor();
+}
+export declare class OnchainWatermarkNotImplementedError extends Error {
+    constructor();
+}
+export declare class QuorumUnavailableError extends Error {
+    readonly required: number;
+    readonly available: number;
+    constructor(required: number, available: number);
+}
+export declare class QuorumConflictError extends Error {
+    readonly treeId: string;
+    readonly indices: SigningIndices;
+    constructor(treeId: string, indices: SigningIndices);
+}
+export declare class OnchainWatermarkError extends Error {
+    constructor(message: string);
+}
+export declare class DeviceRangeViolationError extends Error {
+    readonly addressIndex: number;
+    readonly allowedStart: number;
+    readonly allowedEnd: number;
+    constructor(addressIndex: number, allowedStart: number, allowedEnd: number);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,135 @@
+"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.InvalidLeaseTransitionError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkSeedRequiredError = exports.WatermarkSeedRegressionError = exports.WatermarkMonotonicityError = void 0;
+class WatermarkMonotonicityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WatermarkMonotonicityError';
+    }
+}
+exports.WatermarkMonotonicityError = WatermarkMonotonicityError;
+/**
+ * Raised when seeding would move the local watermark cursor backwards. This is
+ * the fail-closed guard against restoring a wallet below its true high-water
+ * mark and reusing a WOTS leaf (RFC-013 §9).
+ */
+class WatermarkSeedRegressionError extends Error {
+    constructor(treeId, currentCursor, seedCursor) {
+        super(`Refusing to seed watermark for ${treeId} below the current cursor ` +
+            `(${seedCursor} < ${currentCursor}); this would re-expose used WOTS leaves.`);
+        this.treeId = treeId;
+        this.currentCursor = currentCursor;
+        this.seedCursor = seedCursor;
+        this.name = 'WatermarkSeedRegressionError';
+    }
+}
+exports.WatermarkSeedRegressionError = WatermarkSeedRegressionError;
+/**
+ * Raised when a restore/import has no usable watermark source and the caller has
+ * not declared the keyspace fresh. Failing closed is required: starting at 0
+ * would reissue spent leaves (RFC-013 §9).
+ */
+class WatermarkSeedRequiredError extends Error {
+    constructor(treeId) {
+        super(`No watermark source available for ${treeId}. Provide an on-chain cursor, an ` +
+            'exported watermark, or an operator high-water mark — or declare the keyspace fresh. ' +
+            'Refusing to start at 0.');
+        this.treeId = treeId;
+        this.name = 'WatermarkSeedRequiredError';
+    }
+}
+exports.WatermarkSeedRequiredError = WatermarkSeedRequiredError;
+class WatermarkExhaustedError extends Error {
+    constructor(treeId) {
+        super(`WOTS keyspace exhausted for tree: ${treeId}`);
+        this.treeId = treeId;
+        this.name = 'WatermarkExhaustedError';
+    }
+}
+exports.WatermarkExhaustedError = WatermarkExhaustedError;
+class LeaseNotFoundError extends Error {
+    constructor(reservationId) {
+        super(`Lease reservation not found: ${reservationId}`);
+        this.reservationId = reservationId;
+        this.name = 'LeaseNotFoundError';
+    }
+}
+exports.LeaseNotFoundError = LeaseNotFoundError;
+class InvalidLeaseTransitionError extends Error {
+    constructor(reservationId, currentStatus, requestedStatus) {
+        super(`Cannot transition lease ${reservationId} from ${currentStatus} to ${requestedStatus}`);
+        this.reservationId = reservationId;
+        this.currentStatus = currentStatus;
+        this.requestedStatus = requestedStatus;
+        this.name = 'InvalidLeaseTransitionError';
+    }
+}
+exports.InvalidLeaseTransitionError = InvalidLeaseTransitionError;
+class IndicesUnavailableError extends Error {
+    constructor(treeId, indices) {
+        super(`Indices (${indices.addressIndex}, ${indices.l1}, ${indices.l2}) are already unavailable for tree: ${treeId}`);
+        this.treeId = treeId;
+        this.indices = indices;
+        this.name = 'IndicesUnavailableError';
+    }
+}
+exports.IndicesUnavailableError = IndicesUnavailableError;
+class PersonalLeaseNodeNotConfiguredError extends Error {
+    constructor() {
+        super('PersonalLeaseNodeProvider requires a running lookup node. ' +
+            'Deploy @totemsdk/lookup-node and configure { nodeUrl, nodePubkey }.');
+        this.name = 'PersonalLeaseNodeNotConfiguredError';
+    }
+}
+exports.PersonalLeaseNodeNotConfiguredError = PersonalLeaseNodeNotConfiguredError;
+class P2PQuorumNotImplementedError extends Error {
+    constructor() {
+        super('P2PQuorumLeaseProvider is not yet implemented.');
+        this.name = 'P2PQuorumNotImplementedError';
+    }
+}
+exports.P2PQuorumNotImplementedError = P2PQuorumNotImplementedError;
+class OnchainWatermarkNotImplementedError extends Error {
+    constructor() {
+        super('OnchainWatermarkProvider is not yet implemented.');
+        this.name = 'OnchainWatermarkNotImplementedError';
+    }
+}
+exports.OnchainWatermarkNotImplementedError = OnchainWatermarkNotImplementedError;
+class QuorumUnavailableError extends Error {
+    constructor(required, available) {
+        super(`Quorum not reached: ${available}/${required} peers attested. ` +
+            'The reservation was burned locally — retry when more peers are reachable.');
+        this.required = required;
+        this.available = available;
+        this.name = 'QuorumUnavailableError';
+    }
+}
+exports.QuorumUnavailableError = QuorumUnavailableError;
+class QuorumConflictError extends Error {
+    constructor(treeId, indices) {
+        super(`Quorum conflict for tree ${treeId} at (${indices.addressIndex}, ${indices.l1}, ${indices.l2}): ` +
+            'a peer already holds a reservation for these indices.');
+        this.treeId = treeId;
+        this.indices = indices;
+        this.name = 'QuorumConflictError';
+    }
+}
+exports.QuorumConflictError = QuorumConflictError;
+class OnchainWatermarkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OnchainWatermarkError';
+    }
+}
+exports.OnchainWatermarkError = OnchainWatermarkError;
+class DeviceRangeViolationError extends Error {
+    constructor(addressIndex, allowedStart, allowedEnd) {
+        super(`Address index ${addressIndex} is outside device range [${allowedStart}, ${allowedEnd}]`);
+        this.addressIndex = addressIndex;
+        this.allowedStart = allowedStart;
+        this.allowedEnd = allowedEnd;
+        this.name = 'DeviceRangeViolationError';
+    }
+}
+exports.DeviceRangeViolationError = DeviceRangeViolationError;

package/dist/cjs/hybrid.d.ts

@@ -0,0 +1,37 @@
+/**
+ * HybridLeaseProvider — recommended production default.
+ *
+ * Always uses local first, then gates on node cert and/or quorum attestation
+ * for transactions above a configurable value threshold.
+ */
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, CertificateSigner } from './types.js';
+import type { LocalLeaseProvider } from './local.js';
+import type { PersonalLeaseNodeProvider } from './stubs.js';
+import type { P2PQuorumLeaseProvider } from './stubs.js';
+import type { OnchainWatermarkProvider } from './stubs.js';
+export interface HybridLeaseProviderConfig {
+    local: LocalLeaseProvider;
+    node?: PersonalLeaseNodeProvider;
+    quorum?: P2PQuorumLeaseProvider;
+    onchain?: OnchainWatermarkProvider;
+    threshold?: number;
+    /** Identity that authenticates locally-assembled quorum certificates. */
+    certificateSigner?: CertificateSigner;
+}
+export declare class HybridLeaseProvider implements WotsLeaseProvider {
+    private readonly local;
+    private readonly node?;
+    private readonly quorum?;
+    private readonly onchain?;
+    private readonly threshold;
+    private readonly certificateSigner?;
+    constructor(config: HybridLeaseProviderConfig);
+    private isHighValue;
+    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>;
+}

package/dist/cjs/hybrid.js

@@ -0,0 +1,145 @@
+"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;
+const certificate_js_1 = require("./certificate.js");
+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)
+            return false;
+        const val = parseFloat(params.valueHint);
+        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);
+                    const certificate = {
+                        reservationId: reservation.reservationId,
+                        treeId: params.treeId,
+                        branchId: params.branchId,
+                        deviceId: params.deviceId,
+                        indices: reservation.indices,
+                        purpose: params.purpose,
+                        payloadHash: params.payloadHash,
+                        issuedBy: this.certificateSigner?.name ?? 'p2p-quorum',
+                        issuedAt: Date.now(),
+                        expiresAt: reservation.expiresAt,
+                        signature: '',
+                        attestations,
+                    };
+                    certificate.signature = this.certificateSigner
+                        ? await (0, certificate_js_1.signCertificate)(this.certificateSigner, certificate)
+                        : '';
+                    return { ...reservation, certificate };
+                }
+                catch {
+                    // Quorum unavailable — fall through to node / local only.
+                }
+            }
+            // Layer 3 — personal lookup node certificate.
+            if (this.node) {
+                try {
+                    const nodeReservation = await this.node.reserveKeyUse(params);
+                    return { ...reservation, certificate: nodeReservation.certificate };
+                }
+                catch {
+                    // Node unavailable — continue with local only
+                }
+            }
+        }
+        return reservation;
+    }
+    commitKeyUse(reservationId, txId) {
+        return this.local.commitKeyUse(reservationId, txId);
+    }
+    burnReservation(reservationId, reason) {
+        return this.local.burnReservation(reservationId, reason);
+    }
+    getLocalWatermark(treeId) {
+        return this.local.getLocalWatermark(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) {
+            try {
+                await this.node.publishWatermark(treeId);
+                return;
+            }
+            catch {
+                // fall through
+            }
+        }
+        await this.local.publishWatermark(treeId);
+    }
+    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) {
+            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 (0, certificate_js_1.certificateSignatureVerified)(cert, this.certificateSigner);
+        }
+        if (this.node)
+            return this.node.verifyLeaseCertificate(cert);
+        return false;
+    }
+}
+exports.HybridLeaseProvider = HybridLeaseProvider;

package/dist/cjs/index.d.ts

@@ -0,0 +1,17 @@
+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';
+export type { HybridLeaseProviderConfig } 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';
+export type { LeaseJournalRestoreTarget } from './replicated-backup.js';

package/dist/cjs/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplicatedLeaseJournalBackup = exports.DeviceRangeViolationError = exports.OnchainWatermarkError = exports.QuorumConflictError = exports.QuorumUnavailableError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.IndicesUnavailableError = exports.LeaseNotFoundError = exports.WatermarkSeedRequiredError = exports.WatermarkSeedRegressionError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.ChainWatermarkProvider = exports.QuorumLeaseProvider = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = exports.HybridLeaseProvider = exports.AxiaLeaseProvider = exports.exportLeaseWatermark = exports.seedLeaseWatermark = 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 seed_js_1 = require("./seed.js");
+Object.defineProperty(exports, "seedLeaseWatermark", { enumerable: true, get: function () { return seed_js_1.seedLeaseWatermark; } });
+Object.defineProperty(exports, "exportLeaseWatermark", { enumerable: true, get: function () { return seed_js_1.exportLeaseWatermark; } });
+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, "WatermarkSeedRegressionError", { enumerable: true, get: function () { return errors_js_1.WatermarkSeedRegressionError; } });
+Object.defineProperty(exports, "WatermarkSeedRequiredError", { enumerable: true, get: function () { return errors_js_1.WatermarkSeedRequiredError; } });
+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; } });
+var replicated_backup_js_1 = require("./replicated-backup.js");
+Object.defineProperty(exports, "ReplicatedLeaseJournalBackup", { enumerable: true, get: function () { return replicated_backup_js_1.ReplicatedLeaseJournalBackup; } });

package/dist/cjs/journal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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';
+export declare class LeaseJournal {
+    private readonly storage;
+    private readonly logger;
+    private entries;
+    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 appendOne;
+    private ensureInitialized;
+    getAll(): JournalEntry[];
+    getByTree(treeId: string): JournalEntry[];
+    getByReservation(reservationId: string): JournalEntry | undefined;
+    clear(): Promise<void>;
+}