@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/cjs/stubs.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Implementations for Layers 3–5 of the WotsLeaseProvider hierarchy.
+ *
+ * Layer 3 (PersonalLeaseNodeProvider) — HTTP client for a personal @totemsdk/lookup-node
+ *   that has lease coordination enabled ({ lease: { enabled: true } }).
+ *   The node exposes REST endpoints under /v1/lease/*.
+ *
+ * Layers 4–5 (P2PQuorumLeaseProvider, OnchainWatermarkProvider) — 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;
+const certificate_js_1 = require("./certificate.js");
+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; } });
+/**
+ * Layer 3 — personal lookup-node lease coordinator.
+ *
+ * Calls the HTTP REST API exposed by a running @totemsdk/lookup-node that has
+ * lease coordination enabled. All write operations are forwarded to the node's
+ * LeaseCoordinator so the node acts as the source-of-truth watermark journal
+ * for high-value transactions.
+ *
+ * Wrap with HybridLeaseProvider so local reservations always succeed even when
+ * the personal node is temporarily unreachable:
+ *
+ * ```ts
+ * const provider = new HybridLeaseProvider({
+ *   local: new LocalLeaseProvider(storage),
+ *   node:  new PersonalLeaseNodeProvider({ nodeUrl, nodePubkey }),
+ *   threshold: 10, // escalate to node for txns >= 10 MIN
+ * });
+ * ```
+ */
+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' };
+        if (this.authToken)
+            h['Authorization'] = `Bearer ${this.authToken}`;
+        return h;
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`PersonalLeaseNodeProvider: ${path} HTTP ${res.status} — ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    async get(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, { headers: this.headers() });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`PersonalLeaseNodeProvider: GET ${path} HTTP ${res.status} — ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    async reserveKeyUse(params) {
+        const data = await this.post('/v1/lease/reserve', {
+            treeId: params.treeId,
+            branchId: params.branchId,
+            deviceId: params.deviceId,
+            ttlMs: params.ttlMs,
+            payloadHash: params.payloadHash,
+            purpose: params.purpose,
+        });
+        return { ...data.reservation, certificate: data.certificate };
+    }
+    async commitKeyUse(reservationId, txId) {
+        const data = await this.post('/v1/lease/commit', { reservationId, txId });
+        if (!data.ok)
+            throw new Error(`PersonalLeaseNodeProvider: commit failed — ${data.error ?? 'unknown'}`);
+    }
+    async burnReservation(reservationId, reason) {
+        const data = await this.post('/v1/lease/burn', { reservationId, reason });
+        if (!data.ok)
+            throw new Error(`PersonalLeaseNodeProvider: burn failed — ${data.error ?? 'unknown'}`);
+    }
+    async getLocalWatermark(treeId) {
+        return this.get(`/v1/lease/watermark/${encodeURIComponent(treeId)}`);
+    }
+    async publishWatermark(treeId) {
+        await this.post(`/v1/lease/watermark/${encodeURIComponent(treeId)}/publish`, {});
+    }
+    async syncLeaseJournal() {
+        return this.get('/v1/lease/journal/sync');
+    }
+    async verifyLeaseCertificate(cert) {
+        if (!cert)
+            return false;
+        if (cert.issuedBy !== this.nodePubkey)
+            return false;
+        if (cert.expiresAt <= Date.now())
+            return false;
+        // 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 (0, certificate_js_1.certificateSignatureVerified)(cert, signer);
+    }
+}
+exports.PersonalLeaseNodeProvider = PersonalLeaseNodeProvider;

package/dist/cjs/types.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
+ */
+import type { LocalLeaseProvider } from './local.js';
+import type { StorageAdapter } from '@totemsdk/core';
+export type UnavailableReason = 'reserved' | 'committed' | 'burned' | 'reserved-expired';
+export interface SigningIndices {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+}
+export type LeaseStatus = 'pending' | 'active' | 'expired' | 'finalized' | 'cancelled';
+export interface TreeWatermark {
+    treeId: string;
+    deviceId?: string;
+    branchId?: string;
+    addressCursor: number;
+    l1Cursor: number;
+    l2Cursor: number;
+    unavailable: Record<number, UnavailableReason>;
+    lastSyncTimestamp?: number;
+}
+export interface WotsWatermarkState {
+    version: 3;
+    trees: Record<string, TreeWatermark>;
+}
+export interface QuorumAttestation {
+    peerId: string;
+    indices: SigningIndices;
+    expiresAt: number;
+    signature?: string;
+    /**
+     * The reservation id the peer issued for these indices in its own journal.
+     * Commit/burn broadcasts must reference the peer's id, not the local one
+     * (AUD-044) — each peer only knows the reservation it issued.
+     */
+    peerReservationId?: string;
+}
+/**
+ * Identity used to authenticate lease certificates (Layer 4/5).
+ *
+ * A certificate's `signature` is a signature over the canonical certificate
+ * payload (see certificate.ts). Verifiers reject unsigned certificates.
+ */
+export interface CertificateSigner {
+    /** Hex (0x-prefixed or bare) public key digest of the issuing identity. */
+    publicKeyDigest: string;
+    /** Identity label stored on issued certificates via `issuedBy`. */
+    name?: string;
+    /** Sign the canonical certificate message. */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /** Verify a signature over the canonical certificate message. */
+    verify?(message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+}
+export interface LeaseCertificate {
+    reservationId: string;
+    treeId: string;
+    branchId?: string;
+    deviceId?: string;
+    indices: SigningIndices;
+    purpose?: string;
+    payloadHash?: string;
+    issuedBy: string;
+    issuedAt: number;
+    expiresAt: number;
+    signature: string;
+    /** Layer 4 — quorum attestations collected from P2P peers. */
+    attestations?: QuorumAttestation[];
+    /** Layer 5 — content hash of the on-chain watermark TX (sha3-256 of TxPoW bytes). */
+    txpowid?: string;
+}
+export interface LeaseReservation {
+    reservationId: string;
+    indices: SigningIndices;
+    expiresAt: number;
+    certificate?: LeaseCertificate;
+    leaseToken?: string;
+}
+export interface ReserveParams {
+    treeId: string;
+    branchId?: string;
+    purpose?: string;
+    deviceId?: string;
+    ttlMs?: number;
+    payloadHash?: string;
+    valueHint?: string;
+}
+export interface LocalWatermark {
+    treeId: string;
+    addressCursor: number;
+    l1Cursor: number;
+    l2Cursor: number;
+    unavailableCount: number;
+    capacity: number;
+    lastSyncTimestamp?: number;
+}
+/**
+ * A portable, self-describing watermark snapshot (RFC-013 §9). Used to seed a
+ * freshly-provisioned local watermark from an exported blob, an operator-supplied
+ * high-water mark, or the on-chain cursor, so a restored wallet never starts
+ * below the true high-water mark and reissues a spent leaf.
+ */
+export interface WatermarkSeed {
+    readonly version: 1;
+    readonly treeId: string;
+    readonly addressCursor: number;
+    readonly l1Cursor: number;
+    readonly l2Cursor: number;
+    /** Flat indices already consumed (reserved/committed/burned). */
+    readonly unavailable?: readonly number[];
+}
+export interface SeedWatermarkOptions {
+    /**
+     * Permit a seed whose cursor is behind the current local cursor. Defaults to
+     * `false` — regression re-exposes used leaves, so seeding fails closed.
+     */
+    readonly allowRegression?: boolean;
+}
+export interface ConflictRecord {
+    treeId: string;
+    localIndex: number;
+    remoteIndex: number;
+    timestamp: number;
+}
+export interface SyncResult {
+    synced: boolean;
+    conflicts: ConflictRecord[];
+    advancedTo?: SigningIndices;
+}
+export interface WotsLeaseProvider {
+    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>;
+}
+export interface JournalEntry {
+    treeId: string;
+    branchId: string;
+    wotsIndex: number;
+    indices: SigningIndices;
+    status: 'reserved' | 'committed' | 'burned' | 'reserved-expired';
+    reservationId?: string;
+    payloadHash?: string;
+    txId?: string;
+    timestamp: number;
+    deviceId: string;
+    previousHash?: string;
+    hash?: string;
+}
+export interface DeviceKeyRange {
+    deviceId: string;
+    startAddressIndex: number;
+    endAddressIndex: number;
+    addressCount: number;
+}
+export interface PersonalLeaseNodeConfig {
+    nodeUrl: string;
+    nodePubkey: string;
+    authToken?: string;
+    /**
+     * Identity that authenticates certificates issued by this node. When it
+     * carries a `verify()` function, `verifyLeaseCertificate` uses it. Without
+     * any verifier the provider FAILS CLOSED (AUD-016) — an identity match on
+     * `issuedBy` alone is never enough.
+     */
+    certificateSigner?: CertificateSigner;
+    /**
+     * Verify-only cryptographic verifier for certificates issued by the node.
+     * The provider holds no signing key, so this is the recommended way to make
+     * `verifyLeaseCertificate` functional. When neither this nor a
+     * `certificateSigner.verify` is supplied, the provider rejects every
+     * certificate (fail closed).
+     */
+    verify?: (message: Uint8Array, signature: Uint8Array) => Promise<boolean>;
+}
+/**
+ * Layer 4 — P2P quorum lease coordination.
+ *
+ * `peers` is the set of quorum members this device coordinates with. Each
+ * entry is a transport-agnostic RPC handle: the provider sends the same
+ * LEASE_RESERVE / LEASE_COMMIT / LEASE_BURN wire messages used by the
+ * lookup protocol, so any peer that speaks that protocol can participate
+ * (lookup nodes, other devices, or in-memory test peers).
+ */
+export interface QuorumPeer {
+    peerId: string;
+    request(message: {
+        type: 'LEASE_RESERVE' | 'LEASE_COMMIT' | 'LEASE_BURN' | 'LEASE_WATERMARK';
+        payload: Record<string, unknown>;
+    }, timeoutMs?: number): Promise<{
+        type: string;
+        payload: Record<string, unknown>;
+    }>;
+}
+export interface P2PQuorumLeaseProviderConfig {
+    /** Quorum members to coordinate with (excluding self). */
+    peers: QuorumPeer[];
+    /** Minimum attestations required for a reservation to be considered quorum-approved. Default: 1. */
+    minAttestations?: number;
+    /** Local provider used for the authoritative local watermark + journal. */
+    local: LocalLeaseProvider;
+    /** Timeout per peer request. Default: 5_000. */
+    requestTimeoutMs?: number;
+    /** Require quorum approval on commit as well as reserve. Default: false. */
+    requireQuorumOnCommit?: boolean;
+    /**
+     * Identity that authenticates issued certificates. When set, reserved
+     * certificates carry a real signature; without it, certificates are
+     * issued unsigned and will FAIL verification.
+     */
+    certificateSigner?: CertificateSigner;
+}
+/**
+ * Layer 5 — on-chain watermark anchoring.
+ *
+ * `chain` is any ChainStateProvider (hosted, Minima RPC, or lookup node).
+ * The provider spends a dedicated watermark coin whose STATE(0) holds the
+ * flat watermark cursor; every publish advances it on-chain so the watermark
+ * is verifiable by third parties without trusting this device.
+ */
+export interface OnchainWatermarkProviderConfig {
+    /** Chain access for coin queries, proofs, and broadcasting. */
+    chain: {
+        getCoin(coinId: string): Promise<{
+            coinid: string;
+            address: string;
+            amount: string;
+            tokenid: string;
+            state?: unknown[];
+        } | null>;
+        getProof(coinId: string): Promise<{
+            data: unknown;
+        }>;
+        broadcastTxPoW(txpowHex: string): Promise<{
+            success: boolean;
+            txpowid?: string;
+            message?: string;
+        }>;
+        getTip?(): Promise<{
+            block: number;
+        }>;
+    };
+    /** Coin ID of the dedicated watermark coin. */
+    watermarkCoinId: string;
+    /** Address the watermark coin currently sits at (spending address). */
+    watermarkAddress: string;
+    /** Token ID of the watermark coin. Default: '0x00'. */
+    tokenId?: string;
+    /** Amount of the watermark coin in MIN base units. Default: '1'. */
+    amount?: string;
+    /** Local provider used for the authoritative local watermark + journal. */
+    local: LocalLeaseProvider;
+    /** Signer for the watermark coin's script (SIGNEDBY digest). Also authenticates issued certificates. */
+    signer: {
+        publicKeyDigest: string;
+        sign(message: Uint8Array): Promise<Uint8Array>;
+        verify?(message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+    };
+    /** Port holding the flat watermark cursor in the coin state. Default: 0. */
+    statePort?: number;
+    /** Minimum blocks between on-chain publishes (rate limit). Default: 1. */
+    minBlocksBetweenPublishes?: number;
+    /**
+     * Optional durable storage for the watermark coin's identity. When set, the
+     * provider persists the advanced watermark coin ID after each publish so the
+     * rollover survives restarts. Default: in-memory only.
+     */
+    storage?: StorageAdapter;
+}

package/dist/cjs/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/watermark.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WotsWatermarkStore — canonical v3 implementation
+ *
+ * - Reads v1 (flat usedIndices) and v2 (per-address usedIndices) automatically on load.
+ * - Writes only v3.
+ * - Enforces monotonicity: unavailable map can only grow, cursors can only advance.
+ * - Storage key unchanged ('totem_wots_watermark') to avoid storage churn.
+ */
+import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
+import type { WotsWatermarkState, TreeWatermark, SigningIndices, UnavailableReason, LocalWatermark, WatermarkSeed, SeedWatermarkOptions } from './types.js';
+export declare function flatIndex(idx: SigningIndices): number;
+export declare function fromFlatIndex(flat: number): SigningIndices;
+export declare function assertValidSigningIndices(indices: SigningIndices): void;
+export declare class WotsWatermarkStore {
+    private readonly storage;
+    private state;
+    private _initialized;
+    private readonly logger;
+    constructor(storage: StorageAdapter, logger?: LoggerAdapter);
+    initialize(): Promise<void>;
+    private ensureInit;
+    private persist;
+    /**
+     * Reload the persisted watermark and merge it monotonically into the local
+     * state. A provider that shares its storage with another provider (AUD-004)
+     * must call this inside its mutation critical section before allocating or
+     * marking, so it observes writes it did not make and never re-issues a slot
+     * another instance already took.
+     */
+    refresh(): Promise<void>;
+    private getOrCreateTree;
+    getNextIndices(treeId: string): SigningIndices;
+    markUnavailable(treeId: string, indices: SigningIndices, reason: UnavailableReason): Promise<void>;
+    isUnavailable(treeId: string, indices: SigningIndices): boolean;
+    save(treeId: string, patch: Partial<TreeWatermark>): Promise<void>;
+    getLocalWatermark(treeId: string): LocalWatermark;
+    /**
+     * Export a portable seed for a tree (RFC-013 §9). Includes the cursor and the
+     * flat indices already consumed, so it can rebuild the no-reuse state exactly.
+     */
+    exportSeed(treeId: string): WatermarkSeed;
+    /**
+     * Seed the watermark from an exported/operator/on-chain snapshot. Forward-only
+     * by default: a seed behind the current cursor raises
+     * {@link WatermarkSeedRegressionError} so a restore can never re-expose used
+     * leaves. The unavailable set is unioned, never shrunk.
+     */
+    seed(seed: WatermarkSeed, options?: SeedWatermarkOptions): Promise<void>;
+    getRawState(): WotsWatermarkState;
+    clear(): Promise<void>;
+}