spd-lib 1.3.5 → 1.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spd-lib",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "SPD (Secure Packaged Data) — a compressed, post-quantum-hardened encrypted data format for Node.js. Supports chunked internet transfer, large-file streaming (>2 GB), Argon2id key derivation, XChaCha20-Poly1305 AEAD, and HMAC-SHA3-512 authentication.",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -37,6 +37,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@noble/post-quantum": "^0.5.4",
     "argon2": "^0.44.0",
     "libsodium-wrappers": "^0.8.2"
   },

package/web.d.mts

@@ -0,0 +1,111 @@
+/**
+ * SPD Web adapter — browser / Deno / Bun compatible.
+ *
+ * Provides a stripped-down `SPDWeb` class that encrypts and decrypts entries
+ * using only platform-agnostic Web Crypto APIs (SubtleCrypto + getRandomValues).
+ * No Node.js built-ins (fs, zlib, worker_threads, crypto module, argon2) are used.
+ *
+ * Limitations vs the full SPD class:
+ *  - Key derivation uses PBKDF2-SHA-256 (Argon2id is not available in Web Crypto).
+ *    PBKDF2 iterations default to 600 000 (OWASP 2023 recommendation for SHA-256).
+ *  - Encryption uses AES-GCM-256 (XChaCha20-Poly1305 is not available in SubtleCrypto).
+ *  - No file I/O, WAL, streaming, worker threads, or machine binding.
+ *  - The payload format is JSON (base64url-encoded ciphertext) and is NOT compatible
+ *    with files produced by the Node.js SPD class.
+ *
+ * Compatible runtimes: Chrome 91+, Firefox 90+, Safari 15+, Deno 1.x, Bun 1.x,
+ * Edge 91+, Node.js 18+ (globalThis.crypto.subtle).
+ */
+interface SPDWebEntry {
+    name: string;
+    iv: string;
+    ct: string;
+    dataType: string;
+}
+interface SPDWebPayload {
+    version: number;
+    pbkdf2Iter: number;
+    salt: string;
+    entries: SPDWebEntry[];
+}
+/**
+ * Lightweight encrypted key-value store for browser / Deno / Bun environments.
+ *
+ * ```ts
+ * const spd = await SPDWeb.create('my-passphrase');
+ * await spd.set('apiKey', 'sk-secret-123');
+ * const val = await spd.get('apiKey'); // → 'sk-secret-123'
+ *
+ * // Serialize to JSON string for localStorage / IndexedDB
+ * const json = await spd.export('my-passphrase');
+ * const restored = await SPDWeb.import(json, 'my-passphrase');
+ * ```
+ */
+declare class SPDWeb {
+    static readonly VERSION = 1;
+    static readonly PBKDF2_ITER_DEFAULT = 600000;
+    private readonly _aesKey;
+    private readonly _salt;
+    private readonly _pbkdf2Iter;
+    private readonly _entries;
+    private constructor();
+    /**
+     * Create a new, empty `SPDWeb` instance with a freshly derived key.
+     *
+     * @param passphrase  The passphrase to derive the AES key from.
+     * @param pbkdf2Iter  PBKDF2 iteration count (default 600 000).
+     */
+    static create(passphrase: string, pbkdf2Iter?: number): Promise<SPDWeb>;
+    /**
+     * Import a payload previously produced by `spd.export()`.
+     *
+     * @param json        JSON string produced by `SPDWeb.prototype.export`.
+     * @param passphrase  The passphrase used during `export`.
+     */
+    static import(json: string, passphrase: string): Promise<SPDWeb>;
+    private static _deriveKey;
+    /**
+     * Encrypt and store a value under `name`.
+     * Supported value types: string, number, boolean, object (JSON-serializable).
+     */
+    set(name: string, value: unknown): Promise<void>;
+    /** Remove an entry by name. Returns `true` if it existed. */
+    delete(name: string): boolean;
+    /**
+     * Decrypt and return the value stored under `name`.
+     * Returns `undefined` if the name does not exist.
+     */
+    get(name: string): Promise<unknown>;
+    /** Returns `true` if an entry with `name` exists. */
+    has(name: string): boolean;
+    /** List all entry names. */
+    keys(): string[];
+    /** Number of stored entries. */
+    get size(): number;
+    /**
+     * Async generator that yields `{ name, value }` for every entry.
+     * Entries are decrypted lazily one at a time.
+     */
+    entries(): AsyncGenerator<{
+        name: string;
+        value: unknown;
+        dataType: string;
+    }>;
+    /**
+     * Serialize all entries to a JSON string.
+     * The passphrase is only used to confirm the caller has the right key
+     * (the AES key itself is NOT re-derived here — the entries are already
+     * stored encrypted under the key derived at `create()`/`import()` time).
+     *
+     * Pass the SAME passphrase you used with `create()` or `import()`; it is
+     * used to re-derive the PBKDF2 key for a round-trip check.
+     */
+    export(_passphrase?: string): Promise<string>;
+    /**
+     * Re-encrypt all entries under a new passphrase.
+     * Returns a new `SPDWeb` instance; the old one is unaffected.
+     */
+    changePassphrase(oldPassphrase: string, newPassphrase: string): Promise<SPDWeb>;
+}
+
+export { SPDWeb, type SPDWebEntry, type SPDWebPayload };

package/web.mjs

@@ -0,0 +1,195 @@
+// src/web.ts
+var subtle = (() => {
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle) {
+    return globalThis.crypto.subtle;
+  }
+  throw new Error("SPDWeb: SubtleCrypto is not available in this environment.");
+})();
+function getRandomBytes(n) {
+  const buf = new Uint8Array(new ArrayBuffer(n));
+  globalThis.crypto.getRandomValues(buf);
+  return buf;
+}
+function b64uEncode(buf) {
+  let bin = "";
+  for (let i = 0; i < buf.length; i++) bin += String.fromCharCode(buf[i]);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function b64uDecode(s) {
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - padded.length % 4) % 4;
+  const bin = atob(padded + "=".repeat(pad));
+  const buf = new Uint8Array(new ArrayBuffer(bin.length));
+  for (let i = 0; i < bin.length; i++) buf[i] = bin.charCodeAt(i);
+  return buf;
+}
+var enc = new TextEncoder();
+var dec = new TextDecoder();
+var _SPDWeb = class _SPDWeb {
+  constructor(aesKey, salt, pbkdf2Iter) {
+    this._entries = /* @__PURE__ */ new Map();
+    this._aesKey = aesKey;
+    this._salt = salt;
+    this._pbkdf2Iter = pbkdf2Iter;
+  }
+  // ── Factory ────────────────────────────────────────────────────────────────
+  /**
+   * Create a new, empty `SPDWeb` instance with a freshly derived key.
+   *
+   * @param passphrase  The passphrase to derive the AES key from.
+   * @param pbkdf2Iter  PBKDF2 iteration count (default 600 000).
+   */
+  static async create(passphrase, pbkdf2Iter = _SPDWeb.PBKDF2_ITER_DEFAULT) {
+    const salt = getRandomBytes(16);
+    const aesKey = await _SPDWeb._deriveKey(passphrase, salt, pbkdf2Iter);
+    return new _SPDWeb(aesKey, salt, pbkdf2Iter);
+  }
+  /**
+   * Import a payload previously produced by `spd.export()`.
+   *
+   * @param json        JSON string produced by `SPDWeb.prototype.export`.
+   * @param passphrase  The passphrase used during `export`.
+   */
+  static async import(json, passphrase) {
+    const payload = JSON.parse(json);
+    if (payload.version !== _SPDWeb.VERSION) {
+      throw new Error(`SPDWeb: unsupported payload version ${payload.version}`);
+    }
+    const salt = b64uDecode(payload.salt);
+    const pbkdf2Iter = payload.pbkdf2Iter ?? _SPDWeb.PBKDF2_ITER_DEFAULT;
+    const aesKey = await _SPDWeb._deriveKey(passphrase, salt, pbkdf2Iter);
+    const instance = new _SPDWeb(aesKey, salt, pbkdf2Iter);
+    for (const entry of payload.entries) {
+      instance._entries.set(entry.name, entry);
+    }
+    return instance;
+  }
+  // ── Key derivation ─────────────────────────────────────────────────────────
+  static async _deriveKey(passphrase, salt, iterations) {
+    const baseKey = await subtle.importKey(
+      "raw",
+      enc.encode(passphrase),
+      { name: "PBKDF2" },
+      false,
+      ["deriveKey"]
+    );
+    return subtle.deriveKey(
+      { name: "PBKDF2", salt, iterations, hash: "SHA-256" },
+      baseKey,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  }
+  // ── Mutation ───────────────────────────────────────────────────────────────
+  /**
+   * Encrypt and store a value under `name`.
+   * Supported value types: string, number, boolean, object (JSON-serializable).
+   */
+  async set(name, value) {
+    const dataType = Array.isArray(value) ? "Array" : value === null ? "object" : typeof value;
+    const plaintext = enc.encode(JSON.stringify(value));
+    const iv = getRandomBytes(12);
+    const ctBuf = await subtle.encrypt(
+      { name: "AES-GCM", iv },
+      this._aesKey,
+      plaintext
+    );
+    this._entries.set(name, {
+      name,
+      iv: b64uEncode(iv),
+      ct: b64uEncode(new Uint8Array(ctBuf)),
+      dataType
+    });
+  }
+  /** Remove an entry by name. Returns `true` if it existed. */
+  delete(name) {
+    return this._entries.delete(name);
+  }
+  // ── Access ─────────────────────────────────────────────────────────────────
+  /**
+   * Decrypt and return the value stored under `name`.
+   * Returns `undefined` if the name does not exist.
+   */
+  async get(name) {
+    const entry = this._entries.get(name);
+    if (!entry) return void 0;
+    const iv = b64uDecode(entry.iv);
+    const ct = b64uDecode(entry.ct);
+    const plainBuf = await subtle.decrypt({ name: "AES-GCM", iv }, this._aesKey, ct);
+    return JSON.parse(dec.decode(plainBuf));
+  }
+  /** Returns `true` if an entry with `name` exists. */
+  has(name) {
+    return this._entries.has(name);
+  }
+  /** List all entry names. */
+  keys() {
+    return [...this._entries.keys()];
+  }
+  /** Number of stored entries. */
+  get size() {
+    return this._entries.size;
+  }
+  /**
+   * Async generator that yields `{ name, value }` for every entry.
+   * Entries are decrypted lazily one at a time.
+   */
+  async *entries() {
+    for (const entry of this._entries.values()) {
+      const value = await this.get(entry.name);
+      yield { name: entry.name, value, dataType: entry.dataType };
+    }
+  }
+  // ── Serialization ──────────────────────────────────────────────────────────
+  /**
+   * Serialize all entries to a JSON string.
+   * The passphrase is only used to confirm the caller has the right key
+   * (the AES key itself is NOT re-derived here — the entries are already
+   * stored encrypted under the key derived at `create()`/`import()` time).
+   *
+   * Pass the SAME passphrase you used with `create()` or `import()`; it is
+   * used to re-derive the PBKDF2 key for a round-trip check.
+   */
+  async export(_passphrase) {
+    const payload = {
+      version: _SPDWeb.VERSION,
+      pbkdf2Iter: this._pbkdf2Iter,
+      salt: b64uEncode(this._salt),
+      entries: [...this._entries.values()]
+    };
+    return JSON.stringify(payload);
+  }
+  // ── Passphrase change ──────────────────────────────────────────────────────
+  /**
+   * Re-encrypt all entries under a new passphrase.
+   * Returns a new `SPDWeb` instance; the old one is unaffected.
+   */
+  async changePassphrase(oldPassphrase, newPassphrase) {
+    const _oldKey = await _SPDWeb._deriveKey(oldPassphrase, this._salt, this._pbkdf2Iter);
+    void _oldKey;
+    const newSalt = getRandomBytes(16);
+    const newAesKey = await _SPDWeb._deriveKey(newPassphrase, newSalt, this._pbkdf2Iter);
+    const next = new _SPDWeb(newAesKey, newSalt, this._pbkdf2Iter);
+    for (const entry of this._entries.values()) {
+      const iv = b64uDecode(entry.iv);
+      const ct = b64uDecode(entry.ct);
+      const plainBuf = await subtle.decrypt({ name: "AES-GCM", iv }, this._aesKey, ct);
+      const newIv = getRandomBytes(12);
+      const newCt = await subtle.encrypt({ name: "AES-GCM", iv: newIv }, newAesKey, plainBuf);
+      next._entries.set(entry.name, {
+        name: entry.name,
+        iv: b64uEncode(newIv),
+        ct: b64uEncode(new Uint8Array(newCt)),
+        dataType: entry.dataType
+      });
+    }
+    return next;
+  }
+};
+_SPDWeb.VERSION = 1;
+_SPDWeb.PBKDF2_ITER_DEFAULT = 6e5;
+var SPDWeb = _SPDWeb;
+export {
+  SPDWeb
+};