@totemsdk/wots-lease 0.1.2 → 0.1.4

package/src/axia.ts

@@ -1,169 +0,0 @@
-/**
- * AxiaLeaseProvider — wraps the Axia API's /v1/wots-hardened endpoints.
- *
- * Callers do NOT need to call /finalize separately — commitKeyUse() does it.
- */
-
-import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
-import { NoopLogger, LeaseStore, type StoredLease } from '@totemsdk/core';
-import { prepareLease, finalizeLease } from '@totemsdk/core';
-import type {
-  WotsLeaseProvider,
-  ReserveParams,
-  LeaseReservation,
-  LeaseCertificate,
-  LocalWatermark,
-  SyncResult,
-  SigningIndices,
-} from './types.js';
-import { WotsWatermarkStore, flatIndex } from './watermark.js';
-import { LeaseJournal } from './journal.js';
-import { LeaseNotFoundError } from './errors.js';
-
-export interface AxiaLeaseProviderConfig {
-  apiUrl: string;
-  apiKey: string;
-  rootPublicKey: string;
-  storage: StorageAdapter;
-  logger?: LoggerAdapter;
-}
-
-export class AxiaLeaseProvider implements WotsLeaseProvider {
-  private readonly watermark: WotsWatermarkStore;
-  private readonly leaseStore: LeaseStore;
-  private readonly journal: LeaseJournal;
-  private readonly apiUrl: string;
-  private readonly apiKey: string;
-  private readonly rootPublicKey: string;
-  private readonly logger: LoggerAdapter;
-  private _initialized = false;
-
-  constructor(config: AxiaLeaseProviderConfig) {
-    this.apiUrl = config.apiUrl;
-    this.apiKey = config.apiKey;
-    this.rootPublicKey = config.rootPublicKey;
-    this.logger = config.logger ?? new NoopLogger();
-    this.watermark = new WotsWatermarkStore(config.storage, this.logger);
-    this.leaseStore = new LeaseStore(config.storage, this.logger);
-    this.journal = new LeaseJournal(config.storage, this.logger);
-  }
-
-  async initialize(): Promise<void> {
-    if (this._initialized) return;
-    await this.watermark.initialize();
-    await this.leaseStore.initialize();
-    await this.journal.initialize();
-    this._initialized = true;
-  }
-
-  async reserveKeyUse(params: ReserveParams): Promise<LeaseReservation> {
-    if (!this._initialized) await this.initialize();
-
-    const txId = params.payloadHash ?? `tx-${Date.now()}`;
-    const resp = await prepareLease(this.apiUrl, this.apiKey, {
-      txId,
-      rootPublicKey: this.rootPublicKey,
-      to: params.treeId,
-      amount: params.valueHint ?? '0',
-      ttlMs: params.ttlMs ?? 120_000,
-    });
-
-    const indices: SigningIndices = resp.lease;
-    const expiresAt = Date.now() + (params.ttlMs ?? 120_000);
-    const reservationId = resp.txId;
-
-    const lease: StoredLease = {
-      leaseId: reservationId,
-      leaseToken: resp.leaseToken,
-      indices,
-      expiresAt,
-      status: 'active',
-      createdAt: Date.now(),
-      leaseTTL: params.ttlMs ?? 120_000,
-    };
-    await this.leaseStore.save(lease);
-
-    await this.journal.append({
-      treeId: params.treeId,
-      branchId: params.branchId ?? 'default',
-      wotsIndex: 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: string, txId: string): Promise<void> {
-    if (!this._initialized) await this.initialize();
-    const lease = this.leaseStore.get(reservationId);
-    if (!lease) throw new LeaseNotFoundError(reservationId);
-
-    await finalizeLease(this.apiUrl, this.apiKey, lease.leaseToken, txId);
-
-    const indices: SigningIndices = lease.indices;
-    await this.watermark.markUnavailable(
-      lease.indices.addressIndex.toString(),
-      indices,
-      'committed',
-    );
-    await this.leaseStore.updateStatus(reservationId, 'finalized');
-
-    await this.journal.append({
-      treeId: reservationId,
-      branchId: 'default',
-      wotsIndex: flatIndex(indices),
-      indices,
-      status: 'committed',
-      txId,
-      timestamp: Date.now(),
-      deviceId: 'axia',
-    });
-  }
-
-  async burnReservation(reservationId: string, reason: string): Promise<void> {
-    if (!this._initialized) await this.initialize();
-    const lease = this.leaseStore.get(reservationId);
-    if (!lease) throw new LeaseNotFoundError(reservationId);
-
-    const indices: SigningIndices = lease.indices;
-    await this.watermark.markUnavailable(
-      lease.indices.addressIndex.toString(),
-      indices,
-      'burned',
-    );
-    await this.leaseStore.updateStatus(reservationId, 'cancelled');
-
-    this.logger.warn(`[AxiaLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
-    await this.journal.append({
-      treeId: reservationId,
-      branchId: 'default',
-      wotsIndex: flatIndex(indices),
-      indices,
-      status: 'burned',
-      timestamp: Date.now(),
-      deviceId: 'axia',
-    });
-  }
-
-  async getLocalWatermark(treeId: string): Promise<LocalWatermark> {
-    if (!this._initialized) await this.initialize();
-    return this.watermark.getLocalWatermark(treeId);
-  }
-
-  async publishWatermark(_treeId: string): Promise<void> {
-    // Server maintains its own watermark via the lease API
-  }
-
-  async syncLeaseJournal(): Promise<SyncResult> {
-    return { synced: true, conflicts: [] };
-  }
-
-  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
-    if (cert === undefined) return true;
-    return false;
-  }
-}

package/src/device.ts

@@ -1,40 +0,0 @@
-/**
- * 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';
-
-const ADDRESSES_PER_DEVICE = 8;
-const MAX_DEVICE_SLOTS = 8;
-
-export function allocateDeviceRange(params: {
-  deviceSlot: number;
-  deviceId: string;
-}): DeviceKeyRange {
-  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,
-  };
-}
-
-export function deviceSlotForAddressIndex(addressIndex: number): number {
-  return Math.floor(addressIndex / ADDRESSES_PER_DEVICE);
-}

package/src/errors.ts

@@ -1,57 +0,0 @@
-export class WatermarkMonotonicityError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'WatermarkMonotonicityError';
-  }
-}
-
-export class WatermarkExhaustedError extends Error {
-  constructor(public readonly treeId: string) {
-    super(`WOTS keyspace exhausted for tree: ${treeId}`);
-    this.name = 'WatermarkExhaustedError';
-  }
-}
-
-export class LeaseNotFoundError extends Error {
-  constructor(public readonly reservationId: string) {
-    super(`Lease reservation not found: ${reservationId}`);
-    this.name = 'LeaseNotFoundError';
-  }
-}
-
-export class PersonalLeaseNodeNotConfiguredError extends Error {
-  constructor() {
-    super(
-      'PersonalLeaseNodeProvider requires a running lookup node. ' +
-        'Deploy @totemsdk/lookup-node and configure { nodeUrl, nodePubkey }.',
-    );
-    this.name = 'PersonalLeaseNodeNotConfiguredError';
-  }
-}
-
-export class P2PQuorumNotImplementedError extends Error {
-  constructor() {
-    super('P2PQuorumLeaseProvider is not yet implemented.');
-    this.name = 'P2PQuorumNotImplementedError';
-  }
-}
-
-export class OnchainWatermarkNotImplementedError extends Error {
-  constructor() {
-    super('OnchainWatermarkProvider is not yet implemented.');
-    this.name = 'OnchainWatermarkNotImplementedError';
-  }
-}
-
-export class DeviceRangeViolationError extends Error {
-  constructor(
-    public readonly addressIndex: number,
-    public readonly allowedStart: number,
-    public readonly allowedEnd: number,
-  ) {
-    super(
-      `Address index ${addressIndex} is outside device range [${allowedStart}, ${allowedEnd}]`,
-    );
-    this.name = 'DeviceRangeViolationError';
-  }
-}

package/src/hybrid.ts

@@ -1,98 +0,0 @@
-/**
- * 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,
-} 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;
-}
-
-export class HybridLeaseProvider implements WotsLeaseProvider {
-  private readonly local: LocalLeaseProvider;
-  private readonly node?: PersonalLeaseNodeProvider;
-  private readonly quorum?: P2PQuorumLeaseProvider;
-  private readonly onchain?: OnchainWatermarkProvider;
-  private readonly threshold: number;
-
-  constructor(config: HybridLeaseProviderConfig) {
-    this.local = config.local;
-    this.node = config.node;
-    this.quorum = config.quorum;
-    this.onchain = config.onchain;
-    this.threshold = config.threshold ?? Infinity;
-  }
-
-  private isHighValue(params: ReserveParams): boolean {
-    if (!params.valueHint) return false;
-    const val = parseFloat(params.valueHint);
-    return !isNaN(val) && val >= this.threshold;
-  }
-
-  async reserveKeyUse(params: ReserveParams): Promise<LeaseReservation> {
-    const reservation = await this.local.reserveKeyUse(params);
-
-    if (this.isHighValue(params)) {
-      if (this.node) {
-        try {
-          const nodeReservation = await this.node.reserveKeyUse(params);
-          return { ...reservation, certificate: nodeReservation.certificate };
-        } catch {
-          // Node unavailable — continue with local only
-        }
-      }
-    }
-
-    return reservation;
-  }
-
-  commitKeyUse(reservationId: string, txId: string): Promise<void> {
-    return this.local.commitKeyUse(reservationId, txId);
-  }
-
-  burnReservation(reservationId: string, reason: string): Promise<void> {
-    return this.local.burnReservation(reservationId, reason);
-  }
-
-  getLocalWatermark(treeId: string): Promise<LocalWatermark> {
-    return this.local.getLocalWatermark(treeId);
-  }
-
-  publishWatermark(treeId: string): Promise<void> {
-    if (this.node) {
-      return this.node.publishWatermark(treeId).catch(() => this.local.publishWatermark(treeId));
-    }
-    return this.local.publishWatermark(treeId);
-  }
-
-  syncLeaseJournal(): Promise<SyncResult> {
-    if (this.node) {
-      return this.node.syncLeaseJournal().catch(() => this.local.syncLeaseJournal());
-    }
-    return this.local.syncLeaseJournal();
-  }
-
-  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
-    if (!cert) return this.local.verifyLeaseCertificate(cert);
-    if (this.node) return this.node.verifyLeaseCertificate(cert);
-    return false;
-  }
-}

package/src/index.ts

@@ -1,51 +0,0 @@
-export type {
-  UnavailableReason,
-  SigningIndices,
-  LeaseStatus,
-  TreeWatermark,
-  WotsWatermarkState,
-  LeaseCertificate,
-  LeaseReservation,
-  ReserveParams,
-  LocalWatermark,
-  ConflictRecord,
-  SyncResult,
-  WotsLeaseProvider,
-  JournalEntry,
-  DeviceKeyRange,
-  PersonalLeaseNodeConfig,
-} from './types.js';
-
-export {
-  WotsWatermarkStore,
-  flatIndex,
-  fromFlatIndex,
-} from './watermark.js';
-
-export { LeaseJournal } from './journal.js';
-
-export { LocalLeaseProvider } from './local.js';
-
-export { AxiaLeaseProvider } from './axia.js';
-export type { AxiaLeaseProviderConfig } from './axia.js';
-
-export { HybridLeaseProvider } from './hybrid.js';
-export type { HybridLeaseProviderConfig } from './hybrid.js';
-
-export {
-  PersonalLeaseNodeProvider,
-  P2PQuorumLeaseProvider,
-  OnchainWatermarkProvider,
-} from './stubs.js';
-
-export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
-
-export {
-  WatermarkMonotonicityError,
-  WatermarkExhaustedError,
-  LeaseNotFoundError,
-  PersonalLeaseNodeNotConfiguredError,
-  P2PQuorumNotImplementedError,
-  OnchainWatermarkNotImplementedError,
-  DeviceRangeViolationError,
-} from './errors.js';

package/src/journal.ts

@@ -1,52 +0,0 @@
-/**
- * LeaseJournal — append-only audit log for WOTS key-use events.
- * Preserves the full history: reserved → committed | burned | reserved-expired.
- */
-
-import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
-import { NoopLogger } from '@totemsdk/core';
-import type { JournalEntry } from './types.js';
-
-const STORAGE_KEY = 'totem_wots_journal';
-
-export class LeaseJournal {
-  private entries: JournalEntry[] = [];
-  private _initialized = false;
-
-  constructor(
-    private readonly storage: StorageAdapter,
-    private readonly logger: LoggerAdapter = new NoopLogger(),
-  ) {}
-
-  async initialize(): Promise<void> {
-    if (this._initialized) return;
-    const stored = await this.storage.get<JournalEntry[]>(STORAGE_KEY);
-    this.entries = stored ?? [];
-    this._initialized = true;
-  }
-
-  async append(entry: JournalEntry): Promise<void> {
-    this.entries.push(entry);
-    await this.storage.set(STORAGE_KEY, this.entries);
-    this.logger.debug(`[LeaseJournal] ${entry.status} treeId=${entry.treeId} idx=${entry.wotsIndex} txId=${entry.txId ?? '-'}`);
-  }
-
-  getAll(): JournalEntry[] {
-    return [...this.entries];
-  }
-
-  getByTree(treeId: string): JournalEntry[] {
-    return this.entries.filter((e) => e.treeId === treeId);
-  }
-
-  getByReservation(reservationId: string): JournalEntry | undefined {
-    return [...this.entries].reverse().find(
-      (e) => (e as JournalEntry & { reservationId?: string }).reservationId === reservationId,
-    );
-  }
-
-  async clear(): Promise<void> {
-    this.entries = [];
-    await this.storage.remove(STORAGE_KEY);
-  }
-}

package/src/local.ts

@@ -1,196 +0,0 @@
-/**
- * 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 { NoopLogger } from '@totemsdk/core';
-import { LeaseStore, type StoredLease } from '@totemsdk/core';
-import type {
-  WotsLeaseProvider,
-  ReserveParams,
-  LeaseReservation,
-  LeaseCertificate,
-  LocalWatermark,
-  SyncResult,
-  SigningIndices,
-} from './types.js';
-import { WotsWatermarkStore, flatIndex } from './watermark.js';
-import { LeaseJournal } from './journal.js';
-import { LeaseNotFoundError, DeviceRangeViolationError } from './errors.js';
-
-function randomId(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  return Math.random().toString(36).slice(2) + Date.now().toString(36);
-}
-
-export class LocalLeaseProvider implements WotsLeaseProvider {
-  private readonly watermark: WotsWatermarkStore;
-  private readonly leaseStore: LeaseStore;
-  private readonly journal: LeaseJournal;
-  private _initialized = false;
-  private readonly deviceId: string;
-  /** In-memory map: reservationId → treeId (lost on restart; watermark survives). */
-  private readonly _treeIdByReservation = new Map<string, string>();
-
-  constructor(
-    storage: StorageAdapter,
-    private readonly logger: LoggerAdapter = new NoopLogger(),
-    deviceId = 'local',
-  ) {
-    this.watermark = new WotsWatermarkStore(storage, logger);
-    this.leaseStore = new LeaseStore(storage, logger);
-    this.journal = new LeaseJournal(storage, logger);
-    this.deviceId = deviceId;
-  }
-
-  async initialize(): Promise<void> {
-    if (this._initialized) return;
-    await this.watermark.initialize();
-    await this.leaseStore.initialize();
-    await this.journal.initialize();
-    await this.recoverExpiredReservations();
-    this._initialized = true;
-  }
-
-  private async recoverExpiredReservations(): Promise<void> {
-    const now = Date.now();
-    for (const lease of this.leaseStore.getAll()) {
-      if (lease.status === 'active' && lease.expiresAt < now) {
-        const treeId = this._treeIdByReservation.get(lease.leaseId) ?? 'default';
-        await this.watermark.markUnavailable(treeId, lease.indices, 'reserved-expired');
-        await this.leaseStore.updateStatus(lease.leaseId, 'expired');
-        await this.journal.append({
-          treeId,
-          branchId: 'default',
-          wotsIndex: flatIndex(lease.indices),
-          indices: lease.indices,
-          status: 'reserved-expired',
-          timestamp: now,
-          deviceId: this.deviceId,
-        });
-      }
-    }
-  }
-
-  async reserveKeyUse(params: ReserveParams): Promise<LeaseReservation> {
-    if (!this._initialized) await this.initialize();
-    const treeId = params.treeId;
-    const ttlMs = params.ttlMs ?? 120_000;
-
-    const indices = this.watermark.getNextIndices(treeId);
-
-    if (params.deviceId) {
-      const range = this.getDeviceRange(params.deviceId);
-      if (range && (indices.addressIndex < range.start || indices.addressIndex > range.end)) {
-        throw new DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
-      }
-    }
-
-    const reservationId = randomId();
-    const expiresAt = Date.now() + ttlMs;
-
-    const lease: StoredLease = {
-      leaseId: reservationId,
-      leaseToken: reservationId,
-      indices,
-      expiresAt,
-      status: 'active',
-      createdAt: Date.now(),
-      leaseTTL: ttlMs,
-    };
-    await this.leaseStore.save(lease);
-
-    // Track treeId in memory so commit/burn can reference the right watermark tree
-    this._treeIdByReservation.set(reservationId, treeId);
-
-    await this.journal.append({
-      treeId,
-      branchId: params.branchId ?? 'default',
-      wotsIndex: flatIndex(indices),
-      indices,
-      status: 'reserved',
-      payloadHash: params.payloadHash,
-      timestamp: Date.now(),
-      deviceId: params.deviceId ?? this.deviceId,
-    });
-
-    return { reservationId, indices, expiresAt };
-  }
-
-  async commitKeyUse(reservationId: string, txId: string): Promise<void> {
-    if (!this._initialized) await this.initialize();
-    const lease = this.leaseStore.get(reservationId);
-    if (!lease) throw new LeaseNotFoundError(reservationId);
-
-    const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
-    const indices: SigningIndices = lease.indices;
-    await this.watermark.markUnavailable(treeId, indices, 'committed');
-    await this.leaseStore.updateStatus(reservationId, 'finalized');
-    this._treeIdByReservation.delete(reservationId);
-
-    await this.journal.append({
-      treeId,
-      branchId: 'default',
-      wotsIndex: flatIndex(indices),
-      indices,
-      status: 'committed',
-      txId,
-      timestamp: Date.now(),
-      deviceId: this.deviceId,
-    });
-  }
-
-  async burnReservation(reservationId: string, reason: string): Promise<void> {
-    if (!this._initialized) await this.initialize();
-    const lease = this.leaseStore.get(reservationId);
-    if (!lease) throw new LeaseNotFoundError(reservationId);
-
-    const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
-    const indices: SigningIndices = lease.indices;
-    await this.watermark.markUnavailable(treeId, indices, 'burned');
-    await this.leaseStore.updateStatus(reservationId, 'cancelled');
-    this._treeIdByReservation.delete(reservationId);
-
-    this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
-    await this.journal.append({
-      treeId,
-      branchId: 'default',
-      wotsIndex: flatIndex(indices),
-      indices,
-      status: 'burned',
-      timestamp: Date.now(),
-      deviceId: this.deviceId,
-    });
-  }
-
-  async getLocalWatermark(treeId: string): Promise<LocalWatermark> {
-    if (!this._initialized) await this.initialize();
-    return this.watermark.getLocalWatermark(treeId);
-  }
-
-  async publishWatermark(_treeId: string): Promise<void> {
-    // Layer 1: no-op
-  }
-
-  async syncLeaseJournal(): Promise<SyncResult> {
-    // Layer 1: no-op
-    return { synced: true, conflicts: [] };
-  }
-
-  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
-    if (cert === undefined) return true;
-    return false;
-  }
-
-  private getDeviceRange(deviceId: string): { start: number; end: number } | null {
-    const match = deviceId.match(/^device-?(\d+)$/i);
-    if (!match) return null;
-    const slot = parseInt(match[1], 10);
-    return { start: slot * 8, end: slot * 8 + 7 };
-  }
-}