@totemsdk/wots-lease 0.1.1 → 0.1.3

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

package/src/stubs.ts

@@ -1,106 +0,0 @@
-/**
- * Stub implementations for Layers 3–5.
- * These throw descriptive errors until the full implementations land.
- */
-
-import type {
-  WotsLeaseProvider,
-  ReserveParams,
-  LeaseReservation,
-  LeaseCertificate,
-  LocalWatermark,
-  SyncResult,
-  PersonalLeaseNodeConfig,
-} from './types.js';
-import {
-  PersonalLeaseNodeNotConfiguredError,
-  P2PQuorumNotImplementedError,
-  OnchainWatermarkNotImplementedError,
-} from './errors.js';
-
-/**
- * Layer 3 — personal p2p lease node.
- *
- * Verifies ed25519 certs issued by a configured node public key.
- * Reserve/commit throws until the node is reachable — callers should
- * wrap with HybridLeaseProvider using a LocalLeaseProvider as the local layer.
- */
-export class PersonalLeaseNodeProvider implements WotsLeaseProvider {
-  constructor(private readonly config: PersonalLeaseNodeConfig) {}
-
-  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-  burnReservation(_reservationId: string, _reason: string): Promise<void> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-  publishWatermark(_treeId: string): Promise<void> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-  syncLeaseJournal(): Promise<SyncResult> {
-    throw new PersonalLeaseNodeNotConfiguredError();
-  }
-
-  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
-    if (!cert) return false;
-    if (cert.issuedBy !== this.config.nodePubkey) return false;
-    if (cert.expiresAt <= Date.now()) return false;
-    return true;
-  }
-}
-
-/** Layer 4 — p2p replicated lease witnesses. */
-export class P2PQuorumLeaseProvider implements WotsLeaseProvider {
-  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  burnReservation(_reservationId: string, _reason: string): Promise<void> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  publishWatermark(_treeId: string): Promise<void> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  syncLeaseJournal(): Promise<SyncResult> {
-    throw new P2PQuorumNotImplementedError();
-  }
-  verifyLeaseCertificate(_cert?: LeaseCertificate): Promise<boolean> {
-    throw new P2PQuorumNotImplementedError();
-  }
-}
-
-/** Layer 5 — on-chain watermark coin. */
-export class OnchainWatermarkProvider implements WotsLeaseProvider {
-  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  burnReservation(_reservationId: string, _reason: string): Promise<void> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  publishWatermark(_treeId: string): Promise<void> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  syncLeaseJournal(): Promise<SyncResult> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-  verifyLeaseCertificate(_cert?: LeaseCertificate): Promise<boolean> {
-    throw new OnchainWatermarkNotImplementedError();
-  }
-}

package/src/types.ts

@@ -1,119 +0,0 @@
-/**
- * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
- */
-
-export type UnavailableReason = '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 LeaseCertificate {
-  reservationId: string;
-  treeId: string;
-  branchId?: string;
-  deviceId?: string;
-  indices: SigningIndices;
-  purpose?: string;
-  payloadHash?: string;
-  issuedBy: string;
-  issuedAt: number;
-  expiresAt: number;
-  signature: 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;
-}
-
-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';
-  payloadHash?: string;
-  txId?: string;
-  timestamp: number;
-  deviceId: string;
-}
-
-export interface DeviceKeyRange {
-  deviceId: string;
-  startAddressIndex: number;
-  endAddressIndex: number;
-  addressCount: number;
-}
-
-export interface PersonalLeaseNodeConfig {
-  nodeUrl: string;
-  nodePubkey: string;
-  authToken?: string;
-}