@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/onchain.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * OnchainWatermarkProvider — Layer 5: on-chain watermark anchoring.
  *
@@ -21,13 +20,13 @@
  * - syncLeaseJournal merges the on-chain cursor into the local watermark
  *   monotonically (remote ahead → advance; remote behind → conflict record).
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnchainWatermarkProvider = void 0;
-const watermark_js_1 = require("./watermark.js");
-const errors_js_1 = require("./errors.js");
-const core_1 = require("@totemsdk/core");
-const txpow_1 = require("@totemsdk/txpow");
+import { flatIndex } from './watermark.js';
+import { OnchainWatermarkError } from './errors.js';
+import { sha3_256, bytesToHex, hexToBytes, parseMxAddress, serializeTransaction, computeTransactionDigest, rollCoinId, writeMiniNumber, } from '@totemsdk/core';
+import { serializeTxPoW } from '@totemsdk/txpow';
+import { signCertificate, certificateSignatureVerified } from './certificate.js';
 const MAX_L = 64;
+const WATERMARK_COIN_STORAGE_KEY = 'wots-lease:onchain:watermark-coin';
 function multiConcat(parts) {
     if (parts.length === 0)
         return new Uint8Array(0);
@@ -46,7 +45,7 @@ function concatBytes(a, b) {
 function addressToHex(address) {
     const upper = address.startsWith('0x') || address.startsWith('0X') ? address.slice(2) : address;
     return upper.toUpperCase().startsWith('MX')
-        ? (0, core_1.bytesToHex)((0, core_1.parseMxAddress)(address))
+        ? bytesToHex(parseMxAddress(address))
         : address.replace(/^0x/i, '');
 }
 function flatToHex(flat) {
@@ -77,19 +76,20 @@ function stateVarJson(port, hexValue) {
     return { port, svtype: 'hex', data: hexValue };
 }
 function buildWitnessBytes(sigs) {
-    const parts = [(0, core_1.writeMiniNumber)(BigInt(sigs.length), 0)];
+    const parts = [writeMiniNumber(BigInt(sigs.length), 0)];
     for (const sig of sigs)
         parts.push(sig);
-    parts.push((0, core_1.writeMiniNumber)(0n, 0));
-    parts.push((0, core_1.writeMiniNumber)(0n, 0));
+    parts.push(writeMiniNumber(0n, 0));
+    parts.push(writeMiniNumber(0n, 0));
     return multiConcat(parts);
 }
-class OnchainWatermarkProvider {
+export class OnchainWatermarkProvider {
     constructor(config) {
         this._initialized = false;
         this._lastPublishBlock = -1;
         this.chain = config.chain;
-        this.watermarkCoinId = config.watermarkCoinId;
+        this.initialWatermarkCoinId = config.watermarkCoinId;
+        this.currentCoinId = config.watermarkCoinId;
         this.watermarkAddress = config.watermarkAddress;
         this.tokenId = config.tokenId ?? '0x00';
         this.amount = config.amount ?? '1';
@@ -97,10 +97,25 @@ class OnchainWatermarkProvider {
         this.signer = config.signer;
         this.statePort = config.statePort ?? 0;
         this.minBlocksBetweenPublishes = config.minBlocksBetweenPublishes ?? 1;
+        this.storage = config.storage;
     }
     async initialize() {
         if (this._initialized)
             return;
+        // Recover the advanced watermark coin identity across restarts.
+        if (this.storage) {
+            try {
+                const saved = await this.storage.get(WATERMARK_COIN_STORAGE_KEY);
+                if (saved?.coinId)
+                    this.currentCoinId = saved.coinId;
+                if (typeof saved?.lastPublishBlock === 'number') {
+                    this._lastPublishBlock = saved.lastPublishBlock;
+                }
+            }
+            catch {
+                // Storage unavailable — fall back to the configured coin.
+            }
+        }
         await this.local.initialize();
         this._initialized = true;
     }
@@ -127,6 +142,7 @@ class OnchainWatermarkProvider {
             expiresAt: reservation.expiresAt,
             signature: '',
         };
+        certificate.signature = await signCertificate(this.signer, certificate);
         return { ...reservation, certificate };
     }
     async commitKeyUse(reservationId, txId) {
@@ -153,7 +169,7 @@ class OnchainWatermarkProvider {
     async publishWatermark(treeId) {
         await this.ensureInit();
         const wm = await this.local.getLocalWatermark(treeId);
-        const newFlat = (0, watermark_js_1.flatIndex)({
+        const newFlat = flatIndex({
             addressIndex: wm.addressCursor,
             l1: wm.l1Cursor,
             l2: wm.l2Cursor,
@@ -170,10 +186,11 @@ class OnchainWatermarkProvider {
         catch {
             // Tip unavailable — proceed without rate limiting.
         }
-        // Read the current on-chain cursor so the input state matches the coin.
-        const coin = await this.chain.getCoin(this.watermarkCoinId);
+        // Read the current on-chain cursor so the input state matches the coin
+        // anchored by the CURRENT watermark coin (which advances on every spend).
+        const coin = await this.chain.getCoin(this.currentCoinId);
         if (!coin) {
-            throw new errors_js_1.OnchainWatermarkError(`Watermark coin not found: ${this.watermarkCoinId}`);
+            throw new OnchainWatermarkError(`Watermark coin not found: ${this.currentCoinId}`);
         }
         const currentState = coin.state ?? [];
         const currentFlat = readStateCursor(currentState, this.statePort);
@@ -182,7 +199,7 @@ class OnchainWatermarkProvider {
             return;
         }
         const inputCoin = {
-            coinid: this.watermarkCoinId,
+            coinid: this.currentCoinId,
             address: addressToHex(this.watermarkAddress),
             amount: this.amount,
             tokenid: this.tokenId,
@@ -196,22 +213,39 @@ class OnchainWatermarkProvider {
             storestate: true,
             state: [stateVarJson(this.statePort, flatToHex(newFlat))],
         };
+        const rolledCoinId = rollCoinId(hexToBytes(this.currentCoinId), 0);
         const tx = {
             linkhash: '0x00',
             inputs: [inputCoin],
-            outputs: [outputCoin],
+            outputs: [{ ...outputCoin, coinid: '0x' + bytesToHex(rolledCoinId) }],
             state: [],
         };
-        const txBytes = (0, core_1.serializeTransaction)(JSON.stringify(tx));
-        (0, core_1.precomputeTransactionCoinID)(txBytes, 0);
-        const digest = (0, core_1.computeTransactionDigest)(txBytes);
+        const txBytes = serializeTransaction(JSON.stringify(tx));
+        const digest = computeTransactionDigest(txBytes);
         const sig = await this.signer.sign(digest);
         const witnessBytes = buildWitnessBytes([sig]);
-        const prng = (0, core_1.sha3_256)(new TextEncoder().encode(`watermark:${treeId}:${this.watermarkCoinId}:${newFlat}`));
-        const txHex = Buffer.from((0, txpow_1.serializeTxPoW)(txBytes, witnessBytes, { prng })).toString('hex');
+        const prng = sha3_256(new TextEncoder().encode(`watermark:${treeId}:${this.currentCoinId}:${newFlat}`));
+        const txHex = Buffer.from(serializeTxPoW(txBytes, witnessBytes, { prng })).toString('hex');
         const result = await this.chain.broadcastTxPoW(txHex);
         if (!result.success) {
-            throw new errors_js_1.OnchainWatermarkError(`Watermark publish rejected: ${result.message ?? 'unknown error'}`);
+            throw new OnchainWatermarkError(`Watermark publish rejected: ${result.message ?? 'unknown error'}`);
+        }
+        // Rollover: the spent watermark coin is destroyed and replaced by a fresh
+        // coin with a new coin ID (output 0 of this spend). Track and persist the
+        // ADVANCED identity so the next publish spends the live coin, not the
+        // consumed one.
+        const newCoinId = '0x' + bytesToHex(rolledCoinId);
+        this.currentCoinId = newCoinId;
+        if (this.storage) {
+            try {
+                await this.storage.set(WATERMARK_COIN_STORAGE_KEY, {
+                    coinId: newCoinId,
+                    lastPublishBlock: this._lastPublishBlock,
+                });
+            }
+            catch {
+                // Storage unavailable — in-memory rollover still applies this session.
+            }
         }
     }
     // -------------------------------------------------------------------------
@@ -223,14 +257,14 @@ class OnchainWatermarkProvider {
         let advancedTo;
         for (const treeId of this.local.listTrees()) {
             const localWm = await this.local.getLocalWatermark(treeId);
-            const localFlat = (0, watermark_js_1.flatIndex)({
+            const localFlat = flatIndex({
                 addressIndex: localWm.addressCursor,
                 l1: localWm.l1Cursor,
                 l2: localWm.l2Cursor,
             });
             let onchainFlat = null;
             try {
-                const coin = await this.chain.getCoin(this.watermarkCoinId);
+                const coin = await this.chain.getCoin(this.currentCoinId);
                 if (coin)
                     onchainFlat = readStateCursor(coin.state ?? [], this.statePort);
             }
@@ -269,7 +303,8 @@ class OnchainWatermarkProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
+        if (!(await certificateSignatureVerified(cert, this.signer)))
+            return false;
         return cert.issuedBy === 'onchain-watermark';
     }
 }
-exports.OnchainWatermarkProvider = OnchainWatermarkProvider;

package/dist/quorum.d.ts

@@ -34,6 +34,13 @@ export declare class P2PQuorumLeaseProvider implements WotsLeaseProvider {
     private readonly local;
     private readonly requestTimeoutMs;
     private readonly requireQuorumOnCommit;
+    private readonly certificateSigner?;
+    /**
+     * localReservationId -> (peerId -> the reservation id that peer issued).
+     * Commit/burn must reference each peer's own id, because a peer only knows
+     * the reservation it issued, not the local provider's id (AUD-044).
+     */
+    private readonly peerReservationIds;
     private _initialized;
     constructor(config: P2PQuorumLeaseProviderConfig);
     initialize(): Promise<void>;
@@ -52,6 +59,14 @@ export declare class P2PQuorumLeaseProvider implements WotsLeaseProvider {
     }): Promise<QuorumAttestation[]>;
     commitKeyUse(reservationId: string, txId: string): Promise<void>;
     burnReservation(reservationId: string, reason: string): Promise<void>;
+    /** Record which peer issued which reservation id for a local reservation. */
+    private recordPeerReservationIds;
+    /**
+     * The id to send a peer for a local reservation. Peers only know the id they
+     * issued; fall back to the local id only when no peer id was recorded (e.g.
+     * attestations gathered outside `reserveKeyUse`).
+     */
+    private peerReservationIdFor;
     private broadcastAck;
     getLocalWatermark(treeId: string): Promise<LocalWatermark>;
     publishWatermark(treeId: string): Promise<void>;

package/dist/quorum.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * P2PQuorumLeaseProvider — Layer 4: multi-device quorum lease coordination.
  *
@@ -28,20 +27,26 @@
  * - If a peer reports the slot as taken, the local reservation is burned
  *   and QuorumConflictError is thrown.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.P2PQuorumLeaseProvider = void 0;
-const errors_js_1 = require("./errors.js");
+import { QuorumUnavailableError, QuorumConflictError, } from './errors.js';
+import { signCertificate, certificateSignatureVerified, } from './certificate.js';
 function sameIndices(a, b) {
     return a.addressIndex === b.addressIndex && a.l1 === b.l1 && a.l2 === b.l2;
 }
-class P2PQuorumLeaseProvider {
+export class P2PQuorumLeaseProvider {
     constructor(config) {
+        /**
+         * localReservationId -> (peerId -> the reservation id that peer issued).
+         * Commit/burn must reference each peer's own id, because a peer only knows
+         * the reservation it issued, not the local provider's id (AUD-044).
+         */
+        this.peerReservationIds = new Map();
         this._initialized = false;
         this.peers = config.peers;
         this.minAttestations = config.minAttestations ?? 1;
         this.local = config.local;
         this.requestTimeoutMs = config.requestTimeoutMs ?? 5000;
         this.requireQuorumOnCommit = config.requireQuorumOnCommit ?? false;
+        this.certificateSigner = config.certificateSigner;
     }
     async initialize() {
         if (this._initialized)
@@ -67,12 +72,13 @@ class P2PQuorumLeaseProvider {
             attestations = await this.attestKeyUse(params, reservation.indices);
         }
         catch (err) {
-            const reason = err instanceof errors_js_1.QuorumConflictError
+            const reason = err instanceof QuorumConflictError
                 ? `quorum conflict: ${err.message}`
                 : 'quorum not reached';
             await this.local.burnReservation(reservation.reservationId, reason);
             throw err;
         }
+        this.recordPeerReservationIds(reservation.reservationId, attestations);
         const certificate = {
             reservationId: reservation.reservationId,
             treeId: params.treeId,
@@ -81,12 +87,13 @@ class P2PQuorumLeaseProvider {
             indices: reservation.indices,
             purpose: params.purpose,
             payloadHash: params.payloadHash,
-            issuedBy: 'p2p-quorum',
+            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 };
     }
     /**
@@ -123,10 +130,14 @@ class P2PQuorumLeaseProvider {
                     conflicts.push('peer returned mismatched indices');
                     return;
                 }
+                const peerReservationId = body.reservation?.reservationId;
                 attestations.push({
                     peerId: peer.peerId,
                     indices,
                     expiresAt: body.reservation?.expiresAt ?? Date.now() + (params.ttlMs ?? 120000),
+                    ...(typeof peerReservationId === 'string' && peerReservationId.length > 0
+                        ? { peerReservationId }
+                        : {}),
                 });
             }
             catch {
@@ -134,10 +145,10 @@ class P2PQuorumLeaseProvider {
             }
         }));
         if (conflicts.length > 0) {
-            throw new errors_js_1.QuorumConflictError(params.treeId, indices);
+            throw new QuorumConflictError(params.treeId, indices);
         }
         if (attestations.length < this.minAttestations) {
-            throw new errors_js_1.QuorumUnavailableError(this.minAttestations, attestations.length);
+            throw new QuorumUnavailableError(this.minAttestations, attestations.length);
         }
         return attestations;
     }
@@ -147,21 +158,46 @@ class P2PQuorumLeaseProvider {
     async commitKeyUse(reservationId, txId) {
         await this.ensureInit();
         await this.local.commitKeyUse(reservationId, txId);
-        const acks = await this.broadcastAck('LEASE_COMMIT', { reservationId, txId });
+        const acks = await this.broadcastAck('LEASE_COMMIT', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            txId,
+        }));
         if (this.requireQuorumOnCommit && acks < this.minAttestations) {
-            throw new errors_js_1.QuorumUnavailableError(this.minAttestations, acks);
+            throw new QuorumUnavailableError(this.minAttestations, acks);
         }
     }
     async burnReservation(reservationId, reason) {
         await this.ensureInit();
         await this.local.burnReservation(reservationId, reason);
-        await this.broadcastAck('LEASE_BURN', { reservationId, reason });
+        await this.broadcastAck('LEASE_BURN', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            reason,
+        }));
+    }
+    /** Record which peer issued which reservation id for a local reservation. */
+    recordPeerReservationIds(localReservationId, attestations) {
+        const byPeer = new Map();
+        for (const attestation of attestations) {
+            if (attestation.peerReservationId) {
+                byPeer.set(attestation.peerId, attestation.peerReservationId);
+            }
+        }
+        if (byPeer.size > 0)
+            this.peerReservationIds.set(localReservationId, byPeer);
     }
-    async broadcastAck(type, payload) {
+    /**
+     * The id to send a peer for a local reservation. Peers only know the id they
+     * issued; fall back to the local id only when no peer id was recorded (e.g.
+     * attestations gathered outside `reserveKeyUse`).
+     */
+    peerReservationIdFor(localReservationId, peerId) {
+        return this.peerReservationIds.get(localReservationId)?.get(peerId) ?? localReservationId;
+    }
+    async broadcastAck(type, payloadFor) {
         let acks = 0;
         await Promise.all(this.peers.map(async (peer) => {
             try {
-                const resp = await peer.request({ type, payload }, this.requestTimeoutMs);
+                const resp = await peer.request({ type, payload: payloadFor(peer.peerId) }, this.requestTimeoutMs);
                 if (resp.type !== 'ERROR')
                     acks++;
             }
@@ -254,6 +290,10 @@ class P2PQuorumLeaseProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
+        // An unsigned certificate carries no authenticity evidence.
+        if (!(await certificateSignatureVerified(cert, this.certificateSigner))) {
+            return false;
+        }
         const attestations = cert.attestations ?? [];
         if (attestations.length < this.minAttestations)
             return false;
@@ -261,4 +301,3 @@ class P2PQuorumLeaseProvider {
             a.expiresAt > Date.now());
     }
 }
-exports.P2PQuorumLeaseProvider = P2PQuorumLeaseProvider;

package/dist/replicated-backup.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RFC-057 — replicated WOTS lease-journal backup.
+ *
+ * The local `LeaseJournal` remains authoritative for allocation. This adapter
+ * mirrors the physically append-only journal into a replicated log for audit
+ * and disaster recovery, and restores entries into a local journal in order.
+ * It never allocates or advances a signing slot.
+ */
+import type { ReplicatedLog } from '@totemsdk/replication';
+import type { JournalEntry } from './types.js';
+export interface LeaseJournalRestoreTarget {
+    append(entry: JournalEntry): Promise<void>;
+}
+export declare class ReplicatedLeaseJournalBackup {
+    private readonly log;
+    constructor(log: ReplicatedLog<JournalEntry>);
+    /** Mirror one local journal entry. */
+    append(entry: JournalEntry): Promise<{
+        length: number;
+        head: string;
+    }>;
+    /** Read all mirrored entries, verifying the local hash-chain links in order. */
+    readAll(): Promise<JournalEntry[]>;
+    /**
+     * Restore into a local journal. The local journal's own duplicate-slot and
+     * reservation checks remain the final guard; this method only preserves the
+     * replicated order and links.
+     */
+    restoreInto(target: LeaseJournalRestoreTarget): Promise<number>;
+}

package/dist/replicated-backup.js

@@ -0,0 +1,48 @@
+/**
+ * RFC-057 — replicated WOTS lease-journal backup.
+ *
+ * The local `LeaseJournal` remains authoritative for allocation. This adapter
+ * mirrors the physically append-only journal into a replicated log for audit
+ * and disaster recovery, and restores entries into a local journal in order.
+ * It never allocates or advances a signing slot.
+ */
+import { StorageError } from '@totemsdk/storage/errors';
+export class ReplicatedLeaseJournalBackup {
+    constructor(log) {
+        this.log = log;
+    }
+    /** Mirror one local journal entry. */
+    async append(entry) {
+        return this.log.append(entry);
+    }
+    /** Read all mirrored entries, verifying the local hash-chain links in order. */
+    async readAll() {
+        const entries = [];
+        for await (const entry of this.log.readSince())
+            entries.push(entry.record);
+        let previous;
+        for (const [index, entry] of entries.entries()) {
+            if (index === 0) {
+                if (entry.previousHash !== undefined) {
+                    throw new StorageError('replicated lease journal first entry has previousHash', 'corrupt');
+                }
+            }
+            else if (entry.previousHash !== previous?.hash) {
+                throw new StorageError(`replicated lease journal chain mismatch at ${index}`, 'corrupt');
+            }
+            previous = entry;
+        }
+        return entries;
+    }
+    /**
+     * Restore into a local journal. The local journal's own duplicate-slot and
+     * reservation checks remain the final guard; this method only preserves the
+     * replicated order and links.
+     */
+    async restoreInto(target) {
+        const entries = await this.readAll();
+        for (const entry of entries)
+            await target.append(entry);
+        return entries.length;
+    }
+}

package/dist/seed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+import type { LocalLeaseProvider } from './local.js';
+import type { OnchainWatermarkProvider } from './onchain.js';
+import type { LocalWatermark, WatermarkSeed } from './types.js';
+export interface SeedLeaseWatermarkParams {
+    readonly local: LocalLeaseProvider;
+    readonly treeId: string;
+    /** Layer 5 — the on-chain cursor is authoritative when reachable. */
+    readonly onchain?: OnchainWatermarkProvider;
+    /** Exported watermark blob. */
+    readonly exported?: WatermarkSeed;
+    /** Operator-provided flat high-water mark. */
+    readonly operatorHighWaterMark?: number;
+    /** Declares the keyspace fresh/unspent, so cursor 0 is safe. */
+    readonly fresh?: boolean;
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+export declare function seedLeaseWatermark(params: SeedLeaseWatermarkParams): Promise<LocalWatermark>;
+/** Export a portable watermark blob for backup/restore. */
+export declare function exportLeaseWatermark(local: LocalLeaseProvider, treeId: string): Promise<WatermarkSeed>;

package/dist/seed.js

@@ -0,0 +1,80 @@
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+import { flatIndex, fromFlatIndex } from './watermark.js';
+import { WatermarkSeedRequiredError } from './errors.js';
+function flatOf(w) {
+    return flatIndex({ addressIndex: w.addressCursor, l1: w.l1Cursor, l2: w.l2Cursor });
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+export async function seedLeaseWatermark(params) {
+    const { local, treeId } = params;
+    // 1. On-chain cursor — advances the same local watermark (monotonic).
+    if (params.onchain) {
+        try {
+            await params.onchain.syncLeaseJournal();
+        }
+        catch {
+            // Chain unreachable — fall through to exported/operator sources below.
+        }
+    }
+    const current = await local.getLocalWatermark(treeId);
+    let bestFlat = flatOf({ addressCursor: current.addressCursor, l1Cursor: current.l1Cursor, l2Cursor: current.l2Cursor });
+    let best;
+    // 2. Exported blob.
+    if (params.exported) {
+        if (flatOf(params.exported) > bestFlat) {
+            best = params.exported;
+            bestFlat = flatOf(params.exported);
+        }
+    }
+    // 3. Operator high-water mark.
+    if (params.operatorHighWaterMark !== undefined) {
+        const indices = fromFlatIndex(params.operatorHighWaterMark);
+        const candidate = {
+            version: 1,
+            treeId,
+            addressCursor: indices.addressIndex,
+            l1Cursor: indices.l1,
+            l2Cursor: indices.l2,
+            unavailable: [],
+        };
+        if (flatOf(candidate) > bestFlat) {
+            best = candidate;
+            bestFlat = flatOf(candidate);
+        }
+    }
+    if (best) {
+        await local.seedWatermark(best);
+    }
+    if (!params.onchain &&
+        !params.exported &&
+        params.operatorHighWaterMark === undefined &&
+        !params.fresh) {
+        throw new WatermarkSeedRequiredError(treeId);
+    }
+    return local.getLocalWatermark(treeId);
+}
+/** Export a portable watermark blob for backup/restore. */
+export function exportLeaseWatermark(local, treeId) {
+    return local.exportWatermark(treeId);
+}

package/dist/stubs.d.ts

@@ -34,6 +34,8 @@ export declare class PersonalLeaseNodeProvider implements WotsLeaseProvider {
     private readonly baseUrl;
     private readonly nodePubkey;
     private readonly authToken?;
+    private readonly certificateSigner?;
+    private readonly verify?;
     constructor(config: PersonalLeaseNodeConfig);
     private headers;
     private post;

package/dist/stubs.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Implementations for Layers 3–5 of the WotsLeaseProvider hierarchy.
  *
@@ -9,12 +8,9 @@
  * Layers 4–5 (P2PQuorumLeaseProvider, OnchainWatermarkProvider) — implemented in
  *   quorum.ts and onchain.ts; re-exported here for backward compatibility.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PersonalLeaseNodeProvider = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = void 0;
-var quorum_js_1 = require("./quorum.js");
-Object.defineProperty(exports, "P2PQuorumLeaseProvider", { enumerable: true, get: function () { return quorum_js_1.P2PQuorumLeaseProvider; } });
-var onchain_js_1 = require("./onchain.js");
-Object.defineProperty(exports, "OnchainWatermarkProvider", { enumerable: true, get: function () { return onchain_js_1.OnchainWatermarkProvider; } });
+import { certificateSignatureVerified } from './certificate.js';
+export { P2PQuorumLeaseProvider } from './quorum.js';
+export { OnchainWatermarkProvider } from './onchain.js';
 /**
  * Layer 3 — personal lookup-node lease coordinator.
  *
@@ -34,11 +30,13 @@ Object.defineProperty(exports, "OnchainWatermarkProvider", { enumerable: true, g
  * });
  * ```
  */
-class PersonalLeaseNodeProvider {
+export class PersonalLeaseNodeProvider {
     constructor(config) {
         this.baseUrl = config.nodeUrl.replace(/\/$/, '');
         this.nodePubkey = config.nodePubkey;
         this.authToken = config.authToken;
+        this.certificateSigner = config.certificateSigner;
+        this.verify = config.verify;
     }
     headers() {
         const h = { 'Content-Type': 'application/json' };
@@ -103,7 +101,19 @@ class PersonalLeaseNodeProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
-        return true;
+        // AUD-016: fail closed. The provider can only verify a certificate when it
+        // holds a verifier; an `issuedBy` match is not authenticity evidence.
+        const signer = this.certificateSigner?.verify
+            ? this.certificateSigner
+            : this.verify
+                ? {
+                    publicKeyDigest: this.nodePubkey,
+                    sign: async () => {
+                        throw new Error('PersonalLeaseNodeProvider holds a verify-only signer and cannot sign');
+                    },
+                    verify: this.verify,
+                }
+                : undefined;
+        return certificateSignatureVerified(cert, signer);
     }
 }
-exports.PersonalLeaseNodeProvider = PersonalLeaseNodeProvider;