@orbinum/sdk 0.25.0 → 1.0.0

package/dist/adapters/indexeddb/index.d.ts

@@ -0,0 +1,152 @@
+import { V as VaultStorage, a as VaultConfigRecord, E as EncryptedNoteRecord, b as EncryptedTxRecord, C as CachedNullifier, N as NullifierSyncMeta, S as SpendDetails, D as DeviceKeyStore, c as SecretStore } from '../../secretStore-CF6Nse__.js';
+
+/**
+ * `VaultStorage` over IndexedDB — the browser's copy of a wallet's notes.
+ *
+ * The DOM lib reference above is scoped to this file: the package's tsconfig
+ * ships `lib: ["esnext"]`, so nothing outside this entry point can reach for a
+ * browser API by accident.
+ *
+ * Ships in its own subpath so a consumer on Node, React Native or a worker
+ * implements their own backend and never loads this module — the interface it
+ * satisfies lives in the root entry.
+ *
+ * ## Object stores
+ *
+ *   vault_config      one record, id "main": schema version, scan cursor, the
+ *                     ephemeral-index counters
+ *   vault_notes       one record per note, keyed by its BLINDED commitment tag.
+ *                     The note itself is encrypted and its identifiers are
+ *                     blinded, so a database dump reveals nothing linkable to
+ *                     chain activity while equality lookups still work.
+ *   vault_tx_history  encrypted outgoing-transfer records
+ *   nullifier_set     the spent-nullifier mirror. Public chain data, stored in
+ *                     the clear on purpose: it is the same set every wallet
+ *                     downloads, so encrypting it would protect nothing and
+ *                     make membership checks cost a decrypt each.
+ *   nullifier_sync    sync progress for the above
+ *
+ * The database NAME is supplied by the caller rather than fixed here. One vault
+ * per (chain, account) is what keeps a wallet from reading notes that belong to
+ * a different chain or a different key, and only the host knows those.
+ */
+
+interface IndexedDbVaultStorageOptions {
+    /**
+     * Database name. Use one per (chain, account): a vault opened against the
+     * wrong chain holds notes whose commitments no longer exist, and one opened
+     * under another account cannot decrypt anything it finds.
+     */
+    name: string;
+    /**
+     * IndexedDB factory. Defaults to the global one; pass a fake to test without
+     * a browser.
+     */
+    indexedDB?: IDBFactory | undefined;
+}
+/** Browser-backed `VaultStorage`. One instance per database. */
+declare class IndexedDbVaultStorage implements VaultStorage {
+    private readonly name;
+    private readonly idb;
+    private db;
+    constructor(options: IndexedDbVaultStorageOptions);
+    private openDB;
+    /**
+     * Runs one transaction, reopening once if the cached connection was already
+     * dead.
+     *
+     * `onclose` does not fire in every closing path — notably a connection
+     * killed between `openDB()` and the transaction call — so this retry is what
+     * actually makes the adapter self-healing. `InvalidStateError` means "this
+     * handle is finished", and a fresh one is the only fix. Once is enough: a
+     * second failure is a real problem, not a stale handle.
+     *
+     * `run` must build its requests synchronously (no await before the last
+     * one), or the transaction auto-commits underneath it.
+     */
+    private withDB;
+    getConfig(): Promise<VaultConfigRecord | null>;
+    putConfig(config: VaultConfigRecord): Promise<void>;
+    /**
+     * Read-modify-write in ONE transaction.
+     *
+     * Doing this as getConfig() then putConfig() spans two transactions, so two
+     * concurrent callers both read the old record and the second write wins. For
+     * `selfEphCounter` that lost increment means two notes derive the SAME
+     * ephemeral index and publish one ephPk twice, linking them as
+     * same-creator — a privacy leak, not a lost UI update. A single readwrite
+     * transaction serialises them, since IndexedDB scopes those per store.
+     */
+    updateConfig(mutate: (config: VaultConfigRecord) => VaultConfigRecord): Promise<VaultConfigRecord | null>;
+    hasVault(): Promise<boolean>;
+    getAllNoteRecords(): Promise<EncryptedNoteRecord[]>;
+    putNote(record: EncryptedNoteRecord): Promise<void>;
+    putNotes(records: EncryptedNoteRecord[]): Promise<void>;
+    deleteNote(commitmentTag: string): Promise<void>;
+    deleteNotes(commitmentTags: string[]): Promise<void>;
+    clearNotes(): Promise<void>;
+    addTxRecord(record: EncryptedTxRecord): Promise<void>;
+    getAllTxRecords(): Promise<EncryptedTxRecord[]>;
+    /**
+     * Persists one sealed chunk AND the sync progress it produced in a single
+     * transaction. Both must land together: progress ahead of the data would
+     * make the next sync resume past chunks that were never stored, leaving
+     * spent notes looking unspent.
+     */
+    putNullifierChunk(entries: CachedNullifier[], meta: NullifierSyncMeta): Promise<void>;
+    getNullifierSyncMeta(): Promise<NullifierSyncMeta | null>;
+    /**
+     * Which of `hexes` the cache holds, as batch point-gets.
+     *
+     * Local lookups are the whole point: asking a server whether one specific
+     * nullifier is spent would tell it which notes this wallet owns.
+     */
+    getSpentNullifiers(hexes: string[]): Promise<Map<string, SpendDetails>>;
+    countNullifiers(): Promise<number>;
+    clearNullifierCache(): Promise<void>;
+    /** Closes the cached connection. The next call reopens it. */
+    close(): void;
+}
+
+/**
+ * A `DeviceKeyStore` backed by a tiny dedicated IndexedDB.
+ *
+ * IndexedDB rather than localStorage because it stores a `CryptoKey` HANDLE via
+ * structured clone. The key is generated non-extractable, so its material never
+ * becomes visible to JavaScript — a storage dump yields an opaque handle, not
+ * bytes. localStorage can only hold strings, which would mean exporting the key.
+ *
+ * Its own database, separate from the vault: the device key outlives any single
+ * vault and must survive one being dropped.
+ */
+declare function createIndexedDbDeviceKeyStore(indexedDBFactory?: IDBFactory): DeviceKeyStore;
+/**
+ * The browser device key, generated and persisted on first use.
+ *
+ * The store is built on the FIRST CALL, not at import time: an extension's
+ * service worker and a test environment can both import this module before
+ * IndexedDB is reachable, and failing there would take down everything that
+ * merely imports the entry point.
+ */
+declare const getOrCreateIndexedDbDeviceKey: () => Promise<CryptoKey>;
+
+/**
+ * A `SecretStore` over Web Storage.
+ *
+ * No IndexedDB involved — it ships from this entry point because a consumer
+ * reaching for browser persistence wants both adapters together, and splitting
+ * them across two subpaths would buy nothing.
+ */
+
+/**
+ * A `SecretStore` over Web Storage.
+ *
+ * Reads fall back to `sessionStorage` so a value written by an older build, or
+ * by a deliberately session-scoped flow, is still found. Writes always go to the
+ * durable store and clear the session copy, so one key never lives in both.
+ *
+ * Values are encrypted before they arrive here — see `sessionCache`.
+ */
+declare function createWebStorageSecretStore(storage?: Storage, sessionStorageArea?: Storage | null): SecretStore;
+
+export { IndexedDbVaultStorage, type IndexedDbVaultStorageOptions, createIndexedDbDeviceKeyStore, createWebStorageSecretStore, getOrCreateIndexedDbDeviceKey };

package/dist/adapters/indexeddb/index.js

@@ -0,0 +1,381 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/indexeddb/index.ts
+var indexeddb_exports = {};
+__export(indexeddb_exports, {
+  IndexedDbVaultStorage: () => IndexedDbVaultStorage,
+  createIndexedDbDeviceKeyStore: () => createIndexedDbDeviceKeyStore,
+  createWebStorageSecretStore: () => createWebStorageSecretStore,
+  getOrCreateIndexedDbDeviceKey: () => getOrCreateIndexedDbDeviceKey
+});
+module.exports = __toCommonJS(indexeddb_exports);
+
+// src/adapters/indexeddb/idb.ts
+function idbRequest(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+// src/adapters/indexeddb/VaultStorage.ts
+var DB_VERSION = 1;
+var STORE_CONFIG = "vault_config";
+var STORE_NOTES = "vault_notes";
+var STORE_TX_HISTORY = "vault_tx_history";
+var STORE_NULLIFIERS = "nullifier_set";
+var STORE_NULLIFIER_SYNC = "nullifier_sync";
+var IndexedDbVaultStorage = class {
+  name;
+  idb;
+  db = null;
+  constructor(options) {
+    this.name = options.name;
+    const factory = options.indexedDB ?? globalThis.indexedDB;
+    if (!factory) {
+      throw new Error(
+        "IndexedDB is unavailable. Pass `indexedDB`, or use a different VaultStorage."
+      );
+    }
+    this.idb = factory;
+  }
+  openDB() {
+    if (this.db) return Promise.resolve(this.db);
+    return new Promise((resolve, reject) => {
+      const req = this.idb.open(this.name, DB_VERSION);
+      req.onupgradeneeded = (e) => {
+        const db = e.target.result;
+        for (const [store, keyPath] of [
+          [STORE_CONFIG, "id"],
+          [STORE_NOTES, "commitmentTag"],
+          [STORE_TX_HISTORY, "id"],
+          [STORE_NULLIFIERS, "h"],
+          [STORE_NULLIFIER_SYNC, "id"]
+        ]) {
+          if (!db.objectStoreNames.contains(store)) {
+            db.createObjectStore(store, { keyPath });
+          }
+        }
+      };
+      req.onsuccess = (e) => {
+        const db = e.target.result;
+        db.onclose = () => {
+          if (this.db === db) this.db = null;
+        };
+        db.onversionchange = () => {
+          db.close();
+          if (this.db === db) this.db = null;
+        };
+        this.db = db;
+        resolve(db);
+      };
+      req.onerror = () => reject(new Error(`Failed to open IndexedDB: ${String(req.error?.message)}`));
+    });
+  }
+  /**
+   * Runs one transaction, reopening once if the cached connection was already
+   * dead.
+   *
+   * `onclose` does not fire in every closing path — notably a connection
+   * killed between `openDB()` and the transaction call — so this retry is what
+   * actually makes the adapter self-healing. `InvalidStateError` means "this
+   * handle is finished", and a fresh one is the only fix. Once is enough: a
+   * second failure is a real problem, not a stale handle.
+   *
+   * `run` must build its requests synchronously (no await before the last
+   * one), or the transaction auto-commits underneath it.
+   */
+  async withDB(run) {
+    try {
+      return await run(await this.openDB());
+    } catch (err) {
+      if (err?.name !== "InvalidStateError") throw err;
+      this.db = null;
+      return run(await this.openDB());
+    }
+  }
+  // ── Config ───────────────────────────────────────────────────────────────
+  async getConfig() {
+    return this.withDB(async (db) => {
+      const tx = db.transaction(STORE_CONFIG, "readonly");
+      const result = await idbRequest(
+        tx.objectStore(STORE_CONFIG).get("main")
+      );
+      return result ?? null;
+    });
+  }
+  async putConfig(config) {
+    await this.withDB(async (db) => {
+      const tx = db.transaction(STORE_CONFIG, "readwrite");
+      await idbRequest(tx.objectStore(STORE_CONFIG).put(config));
+    });
+  }
+  /**
+   * Read-modify-write in ONE transaction.
+   *
+   * Doing this as getConfig() then putConfig() spans two transactions, so two
+   * concurrent callers both read the old record and the second write wins. For
+   * `selfEphCounter` that lost increment means two notes derive the SAME
+   * ephemeral index and publish one ephPk twice, linking them as
+   * same-creator — a privacy leak, not a lost UI update. A single readwrite
+   * transaction serialises them, since IndexedDB scopes those per store.
+   */
+  async updateConfig(mutate) {
+    return this.withDB(async (db) => {
+      const tx = db.transaction(STORE_CONFIG, "readwrite");
+      const store = tx.objectStore(STORE_CONFIG);
+      const current = await idbRequest(store.get("main"));
+      if (!current) return null;
+      const updated = mutate(current);
+      await idbRequest(store.put(updated));
+      return updated;
+    });
+  }
+  async hasVault() {
+    return await this.getConfig() !== null;
+  }
+  // ── Notes ────────────────────────────────────────────────────────────────
+  async getAllNoteRecords() {
+    return this.withDB((db) => {
+      const tx = db.transaction(STORE_NOTES, "readonly");
+      return idbRequest(tx.objectStore(STORE_NOTES).getAll());
+    });
+  }
+  async putNote(record) {
+    await this.putNotes([record]);
+  }
+  async putNotes(records) {
+    if (records.length === 0) return;
+    await this.withDB(async (db) => {
+      const tx = db.transaction(STORE_NOTES, "readwrite");
+      const store = tx.objectStore(STORE_NOTES);
+      await Promise.all(records.map((r) => idbRequest(store.put(r))));
+    });
+  }
+  async deleteNote(commitmentTag) {
+    await this.deleteNotes([commitmentTag]);
+  }
+  async deleteNotes(commitmentTags) {
+    if (commitmentTags.length === 0) return;
+    await this.withDB(async (db) => {
+      const tx = db.transaction(STORE_NOTES, "readwrite");
+      const store = tx.objectStore(STORE_NOTES);
+      await Promise.all(commitmentTags.map((tag) => idbRequest(store.delete(tag))));
+    });
+  }
+  async clearNotes() {
+    await this.withDB(async (db) => {
+      const tx = db.transaction(STORE_NOTES, "readwrite");
+      await idbRequest(tx.objectStore(STORE_NOTES).clear());
+    });
+  }
+  // ── Transaction history ──────────────────────────────────────────────────
+  // Storage-dumb: rows are written and read as-is. Encryption lives in
+  // VaultStore, which is what a caller should use.
+  async addTxRecord(record) {
+    await this.withDB(async (db) => {
+      const tx = db.transaction(STORE_TX_HISTORY, "readwrite");
+      await idbRequest(tx.objectStore(STORE_TX_HISTORY).put(record));
+    });
+  }
+  async getAllTxRecords() {
+    return this.withDB((db) => {
+      const tx = db.transaction(STORE_TX_HISTORY, "readonly");
+      return idbRequest(tx.objectStore(STORE_TX_HISTORY).getAll());
+    });
+  }
+  // ── Nullifier cache ──────────────────────────────────────────────────────
+  /**
+   * Persists one sealed chunk AND the sync progress it produced in a single
+   * transaction. Both must land together: progress ahead of the data would
+   * make the next sync resume past chunks that were never stored, leaving
+   * spent notes looking unspent.
+   */
+  async putNullifierChunk(entries, meta) {
+    await this.withDB(async (db) => {
+      const tx = db.transaction([STORE_NULLIFIERS, STORE_NULLIFIER_SYNC], "readwrite");
+      const store = tx.objectStore(STORE_NULLIFIERS);
+      await Promise.all([
+        ...entries.map((e) => idbRequest(store.put(e))),
+        idbRequest(tx.objectStore(STORE_NULLIFIER_SYNC).put(meta))
+      ]);
+    });
+  }
+  async getNullifierSyncMeta() {
+    return this.withDB(async (db) => {
+      const tx = db.transaction(STORE_NULLIFIER_SYNC, "readonly");
+      const result = await idbRequest(
+        tx.objectStore(STORE_NULLIFIER_SYNC).get("main")
+      );
+      return result ?? null;
+    });
+  }
+  /**
+   * Which of `hexes` the cache holds, as batch point-gets.
+   *
+   * Local lookups are the whole point: asking a server whether one specific
+   * nullifier is spent would tell it which notes this wallet owns.
+   */
+  async getSpentNullifiers(hexes) {
+    if (hexes.length === 0) return /* @__PURE__ */ new Map();
+    return this.withDB(async (db) => {
+      const tx = db.transaction(STORE_NULLIFIERS, "readonly");
+      const store = tx.objectStore(STORE_NULLIFIERS);
+      const results = await Promise.all(
+        hexes.map((h) => idbRequest(store.get(h)))
+      );
+      return new Map(
+        results.filter((r) => r !== void 0).map((r) => [r.h, { spentAt: r.ts ?? null, txHash: r.tx ?? null }])
+      );
+    });
+  }
+  async countNullifiers() {
+    return this.withDB((db) => {
+      const tx = db.transaction(STORE_NULLIFIERS, "readonly");
+      return idbRequest(tx.objectStore(STORE_NULLIFIERS).count());
+    });
+  }
+  async clearNullifierCache() {
+    await this.withDB(async (db) => {
+      const tx = db.transaction([STORE_NULLIFIERS, STORE_NULLIFIER_SYNC], "readwrite");
+      await Promise.all([
+        idbRequest(tx.objectStore(STORE_NULLIFIERS).clear()),
+        idbRequest(tx.objectStore(STORE_NULLIFIER_SYNC).clear())
+      ]);
+    });
+  }
+  /** Closes the cached connection. The next call reopens it. */
+  close() {
+    this.db?.close();
+    this.db = null;
+  }
+};
+
+// src/wallet/identity/deviceKey.ts
+async function generateDeviceKey(extractable = false) {
+  return crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, extractable, [
+    "encrypt",
+    "decrypt"
+  ]);
+}
+function createDeviceKeyProvider(store) {
+  let cached = null;
+  let inFlight = null;
+  return async function getOrCreateDeviceKey() {
+    if (cached) return cached;
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+      const existing = await store.load();
+      if (existing) return existing;
+      const key = await generateDeviceKey();
+      await store.save(key);
+      return key;
+    })();
+    try {
+      cached = await inFlight;
+      return cached;
+    } finally {
+      inFlight = null;
+    }
+  };
+}
+
+// src/adapters/indexeddb/deviceKeyStore.ts
+var KEYSTORE_DB = "orbinum-keystore";
+var KEYSTORE_STORE = "keys";
+var DEVICE_KEY_ID = "device";
+function createIndexedDbDeviceKeyStore(indexedDBFactory) {
+  const idb = indexedDBFactory ?? globalThis.indexedDB;
+  if (!idb) throw new Error("IndexedDB is unavailable; supply a different DeviceKeyStore.");
+  const open = () => new Promise((resolve, reject) => {
+    const req = idb.open(KEYSTORE_DB, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(KEYSTORE_STORE)) {
+        db.createObjectStore(KEYSTORE_STORE, { keyPath: "id" });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(new Error(`Failed to open keystore: ${String(req.error?.message)}`));
+  });
+  return {
+    async load() {
+      const db = await open();
+      try {
+        const row = await idbRequest(
+          db.transaction(KEYSTORE_STORE, "readonly").objectStore(KEYSTORE_STORE).get(DEVICE_KEY_ID)
+        );
+        return row?.key ?? null;
+      } finally {
+        db.close();
+      }
+    },
+    async save(key) {
+      const db = await open();
+      try {
+        await idbRequest(
+          db.transaction(KEYSTORE_STORE, "readwrite").objectStore(KEYSTORE_STORE).put({ id: DEVICE_KEY_ID, key })
+        );
+      } finally {
+        db.close();
+      }
+    }
+  };
+}
+var getOrCreateIndexedDbDeviceKey = createDeviceKeyProvider({
+  load: () => createIndexedDbDeviceKeyStore().load(),
+  save: (key) => createIndexedDbDeviceKeyStore().save(key)
+});
+
+// src/adapters/indexeddb/secretStore.ts
+function createWebStorageSecretStore(storage, sessionStorageArea) {
+  const durable = () => {
+    const area = storage ?? globalThis.localStorage;
+    if (!area) throw new Error("Web Storage is unavailable; supply a different SecretStore.");
+    return area;
+  };
+  const session = () => sessionStorageArea === void 0 ? globalThis.sessionStorage ?? null : sessionStorageArea;
+  return {
+    async get(key) {
+      return durable().getItem(key) ?? session()?.getItem(key) ?? null;
+    },
+    async set(key, value) {
+      durable().setItem(key, value);
+      session()?.removeItem(key);
+    },
+    async remove(key) {
+      durable().removeItem(key);
+      session()?.removeItem(key);
+    },
+    async keys() {
+      const all = new Set(Object.keys(durable()));
+      const area = session();
+      if (area) for (const k of Object.keys(area)) all.add(k);
+      return [...all];
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IndexedDbVaultStorage,
+  createIndexedDbDeviceKeyStore,
+  createWebStorageSecretStore,
+  getOrCreateIndexedDbDeviceKey
+});