@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/cjs/axia.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * AxiaLeaseProvider — wraps the Axia API's /v1/wots-hardened endpoints.
+ *
+ * Callers do NOT need to call /finalize separately — commitKeyUse() does it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AxiaLeaseProvider = void 0;
+const core_1 = require("@totemsdk/core");
+const core_2 = require("@totemsdk/core");
+const watermark_js_1 = require("./watermark.js");
+const journal_js_1 = require("./journal.js");
+const errors_js_1 = require("./errors.js");
+const errors_1 = require("@totemsdk/storage/errors");
+class AxiaLeaseProvider {
+    constructor(config) {
+        this._initialized = false;
+        this.apiUrl = config.apiUrl;
+        this.apiKey = config.apiKey;
+        this.rootPublicKey = config.rootPublicKey;
+        this.logger = config.logger ?? new core_1.NoopLogger();
+        this.watermark = new watermark_js_1.WotsWatermarkStore(config.storage, this.logger);
+        this.leaseStore = new core_1.LeaseStore(config.storage, this.logger);
+        this.journal = new journal_js_1.LeaseJournal(config.storage, this.logger);
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        await this.watermark.initialize();
+        await this.leaseStore.initialize();
+        await this.journal.initialize();
+        this._initialized = true;
+    }
+    async reserveKeyUse(params) {
+        if (!this._initialized)
+            await this.initialize();
+        const txId = params.payloadHash ?? `tx-${Date.now()}`;
+        const resp = await (0, core_2.prepareLease)(this.apiUrl, this.apiKey, {
+            txId,
+            rootPublicKey: this.rootPublicKey,
+            to: params.treeId,
+            amount: params.valueHint ?? '0',
+            ttlMs: params.ttlMs ?? 120000,
+        });
+        const indices = resp.lease;
+        // RFC-020 C2: never accept an index this tree has already consumed, even if
+        // a replaying/hostile lease server hands the same slot out again.
+        await this.watermark.refresh();
+        if (this.watermark.isUnavailable(params.treeId, indices)) {
+            throw new errors_js_1.IndicesUnavailableError(params.treeId, indices);
+        }
+        const expiresAt = Date.now() + (params.ttlMs ?? 120000);
+        const reservationId = resp.txId;
+        const lease = {
+            leaseId: reservationId,
+            leaseToken: resp.leaseToken,
+            treeId: params.treeId,
+            indices,
+            expiresAt,
+            status: 'active',
+            createdAt: Date.now(),
+            leaseTTL: params.ttlMs ?? 120000,
+        };
+        await this.leaseStore.save(lease);
+        await this.journal.append({
+            treeId: params.treeId,
+            branchId: params.branchId ?? 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'reserved',
+            payloadHash: params.payloadHash,
+            timestamp: Date.now(),
+            deviceId: params.deviceId ?? 'axia',
+        });
+        return { reservationId, indices, expiresAt, leaseToken: resp.leaseToken };
+    }
+    async commitKeyUse(reservationId, txId) {
+        if (!this._initialized)
+            await this.initialize();
+        const lease = this.leaseStore.get(reservationId);
+        if (!lease)
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
+        await (0, core_2.finalizeLease)(this.apiUrl, this.apiKey, lease.leaseToken, txId);
+        const indices = lease.indices;
+        // RFC-020 C2: key the watermark/journal by the real treeId, never the
+        // reservation id.
+        const treeId = lease.treeId;
+        if (!treeId) {
+            throw new errors_1.StorageError(`AxiaLeaseProvider: lease ${reservationId} has no treeId`, 'corrupt');
+        }
+        await this.watermark.markUnavailable(treeId, indices, 'committed');
+        await this.leaseStore.updateStatus(reservationId, 'finalized');
+        await this.journal.append({
+            treeId,
+            branchId: 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'committed',
+            txId,
+            timestamp: Date.now(),
+            deviceId: 'axia',
+        });
+    }
+    async burnReservation(reservationId, reason) {
+        if (!this._initialized)
+            await this.initialize();
+        const lease = this.leaseStore.get(reservationId);
+        if (!lease)
+            throw new errors_js_1.LeaseNotFoundError(reservationId);
+        const indices = lease.indices;
+        const treeId = lease.treeId;
+        if (!treeId) {
+            throw new errors_1.StorageError(`AxiaLeaseProvider: lease ${reservationId} has no treeId`, 'corrupt');
+        }
+        await this.watermark.markUnavailable(treeId, indices, 'burned');
+        await this.leaseStore.updateStatus(reservationId, 'cancelled');
+        this.logger.warn(`[AxiaLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
+        await this.journal.append({
+            treeId,
+            branchId: 'default',
+            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            indices,
+            status: 'burned',
+            timestamp: Date.now(),
+            deviceId: 'axia',
+        });
+    }
+    async getLocalWatermark(treeId) {
+        if (!this._initialized)
+            await this.initialize();
+        return this.watermark.getLocalWatermark(treeId);
+    }
+    async publishWatermark(_treeId) {
+        // Server maintains its own watermark via the lease API
+    }
+    async syncLeaseJournal() {
+        return { synced: true, conflicts: [] };
+    }
+    async verifyLeaseCertificate(_cert) {
+        // RFC-020 C2: the Axia API does not return a server-signed certificate we
+        // can verify, so fail closed rather than asserting a trust we cannot prove.
+        return false;
+    }
+}
+exports.AxiaLeaseProvider = AxiaLeaseProvider;

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>;
+}