@totemsdk/wots-lease 1.0.1 → 1.0.2

package/dist/cjs/journal.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaseJournal = void 0;
+const sha256_js_1 = require("@noble/hashes/sha256.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const core_1 = require("@totemsdk/core");
+const errors_1 = require("@totemsdk/storage/errors");
+const LEGACY_STORAGE_KEY = 'totem_wots_journal';
+const ENTRY_PREFIX = 'totem_wots_journal:v1:entry:';
+const RECORD_VERSION = 1;
+const SEQUENCE_WIDTH = 16;
+const MAX_INDEX_COMPONENT = 63;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const KEY_PATTERN = /^(\d{16}):([0-9a-f]{64})$/;
+const STATUSES = new Set([
+    'reserved',
+    'committed',
+    'burned',
+    'reserved-expired',
+]);
+const storageTails = new WeakMap();
+function withStorageLock(storage, fn) {
+    const prior = storageTails.get(storage) ?? Promise.resolve();
+    const run = prior.then(fn, fn);
+    storageTails.set(storage, run.then(() => undefined, () => undefined));
+    return run;
+}
+/** Existing commitment format; property names/order and SHA-256 stay unchanged. */
+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, utils_js_1.bytesToHex)((0, sha256_js_1.sha256)(bytes));
+}
+function cloneEntry(entry) {
+    return {
+        treeId: entry.treeId,
+        branchId: entry.branchId,
+        wotsIndex: entry.wotsIndex,
+        indices: { ...entry.indices },
+        status: entry.status,
+        ...(entry.reservationId !== undefined ? { reservationId: entry.reservationId } : {}),
+        ...(entry.payloadHash !== undefined ? { payloadHash: entry.payloadHash } : {}),
+        ...(entry.txId !== undefined ? { txId: entry.txId } : {}),
+        timestamp: entry.timestamp,
+        deviceId: entry.deviceId,
+        ...(entry.previousHash !== undefined ? { previousHash: entry.previousHash } : {}),
+        ...(entry.hash !== undefined ? { hash: entry.hash } : {}),
+    };
+}
+function asObject(value, key) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid object at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function requiredString(object, field, key) {
+    const value = object[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function optionalString(object, field, key) {
+    const value = object[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function requiredInteger(object, field, key) {
+    const value = object[field];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function validateEntry(value, key) {
+    const object = asObject(value, key);
+    const indices = asObject(object.indices, `${key}.indices`);
+    const status = requiredString(object, 'status', key);
+    if (!STATUSES.has(status)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid status at ${key}`, 'corrupt', { key });
+    }
+    const timestamp = object.timestamp;
+    if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp < 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid timestamp at ${key}`, 'corrupt', { key });
+    }
+    const validated = cloneEntry({
+        treeId: requiredString(object, 'treeId', key),
+        branchId: requiredString(object, 'branchId', key),
+        wotsIndex: requiredInteger(object, 'wotsIndex', key),
+        indices: {
+            addressIndex: requiredInteger(indices, 'addressIndex', `${key}.indices`),
+            l1: requiredInteger(indices, 'l1', `${key}.indices`),
+            l2: requiredInteger(indices, 'l2', `${key}.indices`),
+        },
+        status,
+        reservationId: optionalString(object, 'reservationId', key),
+        payloadHash: optionalString(object, 'payloadHash', key),
+        txId: optionalString(object, 'txId', key),
+        timestamp,
+        deviceId: requiredString(object, 'deviceId', key),
+        previousHash: optionalString(object, 'previousHash', key),
+        hash: optionalString(object, 'hash', key),
+    });
+    const { addressIndex, l1, l2 } = validated.indices;
+    if (addressIndex > MAX_INDEX_COMPONENT || l1 > MAX_INDEX_COMPONENT || l2 > MAX_INDEX_COMPONENT) {
+        throw new errors_1.StorageError(`LeaseJournal: indices out of range at ${key}`, 'corrupt', { key });
+    }
+    const expectedIndex = addressIndex * 64 * 64 + l1 * 64 + l2;
+    if (validated.wotsIndex !== expectedIndex) {
+        throw new errors_1.StorageError(`LeaseJournal: wotsIndex/indices mismatch at ${key}`, 'corrupt', { key });
+    }
+    return validated;
+}
+function verifyChain(entries, source) {
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (entry.hash === undefined || !HASH_PATTERN.test(entry.hash)) {
+            throw new errors_1.StorageError(`LeaseJournal: invalid hash at ${source}[${i}]`, 'corrupt');
+        }
+        const expectedHash = hashEntry(entry);
+        if (entry.hash !== expectedHash) {
+            throw new errors_1.StorageError(`LeaseJournal: hash mismatch at ${source}[${i}]`, 'corrupt');
+        }
+        if (i === 0) {
+            if (entry.previousHash !== undefined) {
+                throw new errors_1.StorageError(`LeaseJournal: first entry has previousHash at ${source}[0]`, 'corrupt');
+            }
+        }
+        else if (entry.previousHash !== entries[i - 1].hash) {
+            throw new errors_1.StorageError(`LeaseJournal: previousHash mismatch at ${source}[${i}]`, 'corrupt');
+        }
+    }
+}
+function entriesEqual(a, b) {
+    return a.treeId === b.treeId
+        && a.branchId === b.branchId
+        && a.wotsIndex === b.wotsIndex
+        && a.indices.addressIndex === b.indices.addressIndex
+        && a.indices.l1 === b.indices.l1
+        && a.indices.l2 === b.indices.l2
+        && a.status === b.status
+        && a.reservationId === b.reservationId
+        && a.payloadHash === b.payloadHash
+        && a.txId === b.txId
+        && a.timestamp === b.timestamp
+        && a.deviceId === b.deviceId
+        && a.previousHash === b.previousHash
+        && a.hash === b.hash;
+}
+function sequenceText(sequence) {
+    return sequence.toString(10).padStart(SEQUENCE_WIDTH, '0');
+}
+function recordKey(sequence, hash) {
+    return `${ENTRY_PREFIX}${sequenceText(sequence)}:${hash}`;
+}
+function parseRecordKey(key) {
+    const relative = key.slice(ENTRY_PREFIX.length);
+    const match = KEY_PATTERN.exec(relative);
+    if (!match) {
+        throw new errors_1.StorageError(`LeaseJournal: malformed record key ${key}`, 'corrupt', { key });
+    }
+    const sequence = Number(match[1]);
+    if (!Number.isSafeInteger(sequence)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid sequence in ${key}`, 'corrupt', { key });
+    }
+    return { key, sequence, hash: match[2] };
+}
+class LeaseJournal {
+    constructor(storage, logger = new core_1.NoopLogger()) {
+        this.storage = storage;
+        this.logger = logger;
+        this.entries = [];
+        this.initialized = false;
+        this.initializePromise = null;
+        this.appendTail = Promise.resolve();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.initializePromise) {
+            this.initializePromise = withStorageLock(this.storage, () => this.initializeOnce()).catch((error) => {
+                this.initializePromise = null;
+                throw error;
+            });
+        }
+        await this.initializePromise;
+    }
+    async initializeOnce() {
+        const physical = await this.readPhysicalRecords();
+        const legacy = await this.readLegacyEntries();
+        if (legacy !== null) {
+            const commonLength = Math.min(physical.length, legacy.length);
+            for (let i = 0; i < commonLength; i += 1) {
+                if (!entriesEqual(physical[i], legacy[i])) {
+                    throw new errors_1.StorageError(`LeaseJournal: legacy/v1 divergence at sequence ${i}`, 'corrupt');
+                }
+            }
+            for (let i = physical.length; i < legacy.length; i += 1) {
+                await this.writeRecord(i, legacy[i]);
+            }
+        }
+        const replayed = legacy !== null && legacy.length > physical.length
+            ? await this.readPhysicalRecords()
+            : physical;
+        this.entries = replayed.map(cloneEntry);
+        this.initialized = true;
+    }
+    async readLegacyEntries() {
+        const raw = await this.storage.get(LEGACY_STORAGE_KEY);
+        if (raw === null)
+            return null;
+        if (!Array.isArray(raw)) {
+            throw new errors_1.StorageError('LeaseJournal: legacy journal is not an array', 'corrupt', { key: LEGACY_STORAGE_KEY });
+        }
+        const entries = raw.map((entry, index) => validateEntry(entry, `${LEGACY_STORAGE_KEY}[${index}]`));
+        verifyChain(entries, LEGACY_STORAGE_KEY);
+        return entries;
+    }
+    async readPhysicalRecords() {
+        const parsed = (await this.storage.keys())
+            .filter((key) => key.startsWith(ENTRY_PREFIX))
+            .map(parseRecordKey)
+            .sort((a, b) => a.sequence - b.sequence || a.key.localeCompare(b.key));
+        for (let i = 0; i < parsed.length; i += 1) {
+            if (i > 0 && parsed[i - 1].sequence === parsed[i].sequence) {
+                throw new errors_1.StorageError(`LeaseJournal: fork at sequence ${parsed[i].sequence}`, 'corrupt');
+            }
+            if (parsed[i].sequence !== i) {
+                throw new errors_1.StorageError(`LeaseJournal: sequence gap at ${i}`, 'corrupt');
+            }
+        }
+        const entries = [];
+        for (const descriptor of parsed) {
+            const raw = await this.storage.get(descriptor.key);
+            if (raw === null) {
+                throw new errors_1.StorageError(`LeaseJournal: listed record is missing`, 'corrupt', { key: descriptor.key });
+            }
+            const record = asObject(raw, descriptor.key);
+            const formatVersion = record.formatVersion;
+            if (formatVersion !== RECORD_VERSION) {
+                throw new errors_1.StorageError('LeaseJournal: unsupported record version', 'corrupt', {
+                    key: descriptor.key,
+                    detectedVersion: typeof formatVersion === 'number' ? formatVersion : undefined,
+                    unsupportedVersion: typeof formatVersion === 'number' ? formatVersion : undefined,
+                });
+            }
+            if (record.sequence !== descriptor.sequence) {
+                throw new errors_1.StorageError('LeaseJournal: sequence/key mismatch', 'corrupt', { key: descriptor.key });
+            }
+            const entry = validateEntry(record.entry, `${descriptor.key}.entry`);
+            if (entry.hash !== descriptor.hash) {
+                throw new errors_1.StorageError('LeaseJournal: hash/key mismatch', 'corrupt', { key: descriptor.key });
+            }
+            entries.push(entry);
+        }
+        verifyChain(entries, ENTRY_PREFIX);
+        return entries;
+    }
+    async writeRecord(sequence, entry) {
+        if (entry.hash === undefined) {
+            throw new errors_1.StorageError(`LeaseJournal: entry ${sequence} has no hash`, 'corrupt');
+        }
+        const key = recordKey(sequence, entry.hash);
+        const record = {
+            formatVersion: RECORD_VERSION,
+            sequence,
+            entry: cloneEntry(entry),
+        };
+        await this.storage.set(key, record);
+    }
+    append(entry) {
+        const run = this.appendTail.then(async () => this.appendOne(entry));
+        this.appendTail = run.catch(() => undefined);
+        return run;
+    }
+    async appendOne(input) {
+        await this.initialize();
+        await withStorageLock(this.storage, async () => {
+            // Refresh under the shared lock so multiple journal instances that share
+            // the same adapter object cannot allocate the same sequence or slot.
+            this.entries = (await this.readPhysicalRecords()).map(cloneEntry);
+            const entry = validateEntry(cloneEntry(input), 'append');
+            if (entry.status === 'reserved' && this.entries.some((existing) => existing.treeId === entry.treeId && existing.wotsIndex === entry.wotsIndex)) {
+                throw new errors_1.StorageError(`LeaseJournal: WOTS slot ${entry.treeId}/${entry.wotsIndex} is already recorded`, 'write-failed');
+            }
+            if (entry.status !== 'reserved' && entry.reservationId) {
+                const latest = [...this.entries].reverse().find((existing) => existing.reservationId === entry.reservationId);
+                if (latest?.status === entry.status) {
+                    if (latest.treeId !== entry.treeId || latest.wotsIndex !== entry.wotsIndex
+                        || (entry.status === 'committed' && latest.txId !== entry.txId)) {
+                        throw new errors_1.StorageError(`LeaseJournal: reservation ${entry.reservationId} is already ${latest.status} for a different use`, 'write-failed');
+                    }
+                    if (latest.previousHash === undefined)
+                        delete input.previousHash;
+                    else
+                        input.previousHash = latest.previousHash;
+                    input.hash = latest.hash;
+                    return;
+                }
+                if (latest && latest.status !== 'reserved') {
+                    throw new errors_1.StorageError(`LeaseJournal: reservation ${entry.reservationId} is already ${latest.status}`, 'write-failed');
+                }
+            }
+            const previous = this.entries[this.entries.length - 1];
+            if (previous?.hash !== undefined)
+                entry.previousHash = previous.hash;
+            else
+                delete entry.previousHash;
+            entry.hash = hashEntry(entry);
+            const sequence = this.entries.length;
+            const sequencePrefix = `${ENTRY_PREFIX}${sequenceText(sequence)}:`;
+            if ((await this.storage.keys()).some((key) => key.startsWith(sequencePrefix))) {
+                throw new errors_1.StorageError(`LeaseJournal: sequence ${sequence} already exists`, 'write-failed');
+            }
+            await this.writeRecord(sequence, entry);
+            this.entries.push(entry);
+            if (entry.previousHash === undefined)
+                delete input.previousHash;
+            else
+                input.previousHash = entry.previousHash;
+            input.hash = entry.hash;
+            this.logger.debug(`[LeaseJournal] ${entry.status} treeId=${entry.treeId} idx=${entry.wotsIndex} `
+                + `txId=${entry.txId ?? '-'} hash=${entry.hash.slice(0, 8)}`);
+        });
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('LeaseJournal not initialized — call initialize() first');
+        }
+    }
+    getAll() {
+        this.ensureInitialized();
+        return this.entries.map(cloneEntry);
+    }
+    getByTree(treeId) {
+        this.ensureInitialized();
+        return this.entries.filter((entry) => entry.treeId === treeId).map(cloneEntry);
+    }
+    getByReservation(reservationId) {
+        this.ensureInitialized();
+        const entry = [...this.entries].reverse().find((candidate) => candidate.reservationId === reservationId);
+        return entry ? cloneEntry(entry) : undefined;
+    }
+    async clear() {
+        throw new errors_1.StorageError('LeaseJournal is append-only and cannot be cleared', 'write-failed');
+    }
+}
+exports.LeaseJournal = LeaseJournal;

package/dist/cjs/local.d.ts

@@ -0,0 +1,83 @@
+/**
+ * LocalLeaseProvider — Layer 1: local durable ledger.
+ *
+ * Single-device, no network coordination.
+ * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
+ */
+import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, SigningIndices, WatermarkSeed, SeedWatermarkOptions } from './types.js';
+import { LeaseJournal } from './journal.js';
+export declare class LocalLeaseProvider implements WotsLeaseProvider {
+    private readonly logger;
+    private readonly watermark;
+    private readonly leaseStore;
+    private readonly journal;
+    private _initialized;
+    private initializePromise;
+    private mutationTail;
+    private readonly deviceId;
+    /**
+     * Optional CAS primitive (AUD-004). When the adapter exposes
+     * `conditionalUpdate`, a per-slot claim key is written atomically before the
+     * reservation so two providers over distinct adapter objects on the same
+     * durable medium cannot both claim one slot. Adapters without CAS fall back
+     * to the existing refresh() + check behavior.
+     */
+    private readonly cas?;
+    constructor(storage: StorageAdapter, logger?: LoggerAdapter, deviceId?: string);
+    private static detectCas;
+    initialize(): Promise<void>;
+    private initializeOnce;
+    /**
+     * Rebuild the no-reuse watermark from immutable journal history and leases.
+     * The journal is audit authority; the watermark remains allocation authority.
+     */
+    private reconcileDurableSafetyState;
+    /** 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>;
+    /**
+     * Reserve a specific set of indices (used by quorum coordination so every
+     * peer attests to the same slot). Throws IndicesUnavailableError when the
+     * slot is already taken.
+     */
+    reserveSpecificKeyUse(params: ReserveParams, indices: SigningIndices): Promise<LeaseReservation>;
+    private reserveSpecificKeyUseUnlocked;
+    private withMutationLock;
+    commitKeyUse(reservationId: string, txId: string): Promise<void>;
+    private commitKeyUseUnlocked;
+    burnReservation(reservationId: string, reason: string): Promise<void>;
+    private burnReservationUnlocked;
+    getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    /**
+     * Export a portable watermark seed for restore (RFC-013 §9).
+     */
+    exportWatermark(treeId: string): Promise<WatermarkSeed>;
+    /**
+     * Seed the local watermark from an exported/operator/on-chain snapshot.
+     * Forward-only by default; refuses to start below the true high-water mark.
+     */
+    seedWatermark(seed: WatermarkSeed, options?: SeedWatermarkOptions): Promise<void>;
+    /** List all tree IDs known to the local watermark store. */
+    listTrees(): string[];
+    /** Expose the journal for quorum/on-chain providers to merge remote entries. */
+    getJournal(): LeaseJournal;
+    /**
+     * Advance the local watermark to a remote cursor (monotonic merge).
+     * Used by quorum sync and the lookup-node LeaseCoordinator when a peer
+     * publishes a watermark ahead of ours. Returns false when the remote
+     * cursor is behind (no-op).
+     */
+    advanceToRemoteWatermark(treeId: string, remote: {
+        addressCursor: number;
+        l1Cursor: number;
+        l2Cursor: number;
+    }): Promise<boolean>;
+    publishWatermark(_treeId: string): Promise<void>;
+    syncLeaseJournal(): Promise<SyncResult>;
+    verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+    private getDeviceRange;
+}