@qubic.ts/sdk 0.1.0

package/src/vault-browser.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  createLocalStorageVaultStore,
+  createMemoryVaultStore,
+  openSeedVaultBrowser,
+} from "./vault-browser.js";
+import type { SeedVault } from "./vault/types.js";
+
+const SEED = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+
+let vaults: SeedVault[] = [];
+
+afterEach(async () => {
+  for (const vault of vaults) {
+    await vault.close();
+  }
+  vaults = [];
+});
+
+describe("seed vault browser", () => {
+  it("stores and reloads encrypted seeds using memory store", async () => {
+    const store = createMemoryVaultStore("vault-browser");
+
+    const vault = await openSeedVaultBrowser({
+      store,
+      passphrase: "secret",
+      create: true,
+    });
+    vaults.push(vault);
+
+    await vault.addSeed({ name: "main", seed: SEED });
+    expect(await vault.getSeed("main")).toBe(SEED);
+
+    const reopened = await openSeedVaultBrowser({
+      store,
+      passphrase: "secret",
+    });
+    vaults.push(reopened);
+
+    expect(await reopened.getSeed("main")).toBe(SEED);
+  });
+
+  it("creates a localStorage-backed store from an injected storage object", async () => {
+    const backing = new Map<string, string>();
+    const storage = {
+      getItem(key: string): string | null {
+        return backing.has(key) ? backing.get(key) ?? null : null;
+      },
+      setItem(key: string, value: string): void {
+        backing.set(key, value);
+      },
+      removeItem(key: string): void {
+        backing.delete(key);
+      },
+      clear(): void {
+        backing.clear();
+      },
+      key(index: number): string | null {
+        return Array.from(backing.keys())[index] ?? null;
+      },
+      get length(): number {
+        return backing.size;
+      },
+    } as Storage;
+
+    const store = createLocalStorageVaultStore("vault-browser-ls", storage);
+    const vault = await openSeedVaultBrowser({
+      store,
+      passphrase: "secret",
+      create: true,
+    });
+    vaults.push(vault);
+
+    await vault.addSeed({ name: "main", seed: SEED });
+    expect(vault.list().length).toBe(1);
+  });
+});

package/src/vault-browser.ts

@@ -0,0 +1,449 @@
+import { identityFromSeed } from "@qubic.ts/core";
+import type {
+  Pbkdf2Hash,
+  Pbkdf2KdfParams,
+  SeedVault,
+  VaultEntry,
+  VaultEntryEncrypted,
+  VaultExport,
+  VaultHeader,
+  VaultSummary,
+} from "./vault/types.js";
+import {
+  VaultEntryExistsError,
+  VaultEntryNotFoundError,
+  VaultError,
+  VaultInvalidPassphraseError,
+  VaultNotFoundError,
+} from "./vault/types.js";
+
+const DEFAULT_PBKDF2_PARAMS = Object.freeze({
+  iterations: 200_000,
+  hash: "SHA-256" as Pbkdf2Hash,
+  dkLen: 32,
+});
+
+const AES_GCM_NONCE_BYTES = 12;
+const AES_GCM_TAG_BYTES = 16;
+const VAULT_VERSION = 1;
+
+type VaultFile = Omit<VaultHeader, "kdf"> &
+  Readonly<{
+    kdf: Readonly<{
+      name: "pbkdf2";
+      params: Pbkdf2KdfParams;
+    }>;
+    entries: readonly VaultEntry[];
+  }>;
+
+export type VaultStore = Readonly<{
+  read(): Promise<string | null>;
+  write(value: string): Promise<void>;
+  remove?(): Promise<void>;
+  label?: string;
+}>;
+
+export type OpenSeedVaultBrowserInput = Readonly<{
+  passphrase: string;
+  create?: boolean;
+  autoSave?: boolean;
+  kdfParams?: Readonly<{
+    iterations?: number;
+    hash?: Pbkdf2Hash;
+    dkLen?: number;
+  }>;
+  store: VaultStore;
+  path?: string;
+}>;
+
+export async function openSeedVaultBrowser(input: OpenSeedVaultBrowserInput): Promise<SeedVault> {
+  const { store, passphrase } = input;
+  const autoSave = input.autoSave ?? true;
+  const path = input.path ?? store.label ?? "vault";
+
+  let file: VaultFile | undefined;
+  const raw = await store.read();
+  if (raw) file = parseVaultFile(raw);
+
+  if (!file) {
+    if (!input.create) {
+      throw new VaultNotFoundError(path);
+    }
+    const params = createKdfParams(input.kdfParams);
+    file = createEmptyVault(params);
+    await store.write(JSON.stringify(file, null, 2));
+  }
+
+  if (file.vaultVersion !== VAULT_VERSION) {
+    throw new VaultError(`Unsupported vault version: ${file.vaultVersion}`);
+  }
+
+  let key = await deriveKey(passphrase, file.kdf.params);
+  const entries = new Map(file.entries.map((entry) => [entry.name, entry]));
+
+  const findEntry = (ref: string): VaultEntry => {
+    const direct = entries.get(ref);
+    if (direct) return direct;
+    for (const entry of entries.values()) {
+      if (entry.identity === ref) return entry;
+    }
+    throw new VaultEntryNotFoundError(ref);
+  };
+
+  const list = (): readonly VaultSummary[] => {
+    return Array.from(entries.values()).map((entry) => ({
+      name: entry.name,
+      identity: entry.identity,
+      seedIndex: entry.seedIndex,
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+    }));
+  };
+
+  const save = async (): Promise<void> => {
+    if (!file) {
+      throw new VaultError("Vault not initialized");
+    }
+    const updated: VaultFile = { ...file, entries: Array.from(entries.values()) };
+    await store.write(JSON.stringify(updated, null, 2));
+    file = updated;
+  };
+
+  const addSeed = async ({
+    name,
+    seed,
+    seedIndex = 0,
+    overwrite = false,
+  }: Readonly<{
+    name: string;
+    seed: string;
+    seedIndex?: number;
+    overwrite?: boolean;
+  }>): Promise<VaultSummary> => {
+    if (!overwrite && entries.has(name)) {
+      throw new VaultEntryExistsError(name);
+    }
+
+    const identity = await identityFromSeed(seed, seedIndex);
+    const encrypted = await encryptSeed(seed, key);
+    const now = new Date().toISOString();
+
+    const entry: VaultEntry = {
+      name,
+      identity,
+      seedIndex,
+      createdAt: entries.get(name)?.createdAt ?? now,
+      updatedAt: now,
+      encrypted,
+    };
+
+    entries.set(name, entry);
+    if (autoSave) await save();
+    return {
+      name: entry.name,
+      identity: entry.identity,
+      seedIndex: entry.seedIndex,
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+    };
+  };
+
+  const getSeed = async (ref: string): Promise<string> => {
+    const entry = findEntry(ref);
+    try {
+      return await decryptSeed(entry.encrypted, key);
+    } catch {
+      throw new VaultInvalidPassphraseError();
+    }
+  };
+
+  const getIdentity = (ref: string): string => {
+    return findEntry(ref).identity;
+  };
+
+  const signer = (ref: string): Readonly<{ fromVault: string }> => {
+    findEntry(ref);
+    return { fromVault: ref };
+  };
+
+  const remove = async (ref: string): Promise<void> => {
+    const entry = findEntry(ref);
+    entries.delete(entry.name);
+    if (autoSave) await save();
+  };
+
+  const rotatePassphrase = async (newPassphrase: string): Promise<void> => {
+    const params = createKdfParams(input.kdfParams);
+    const nextKey = await deriveKey(newPassphrase, params);
+    const now = new Date().toISOString();
+
+    for (const entry of entries.values()) {
+      const seed = await decryptSeed(entry.encrypted, key);
+      entries.set(entry.name, {
+        ...entry,
+        encrypted: await encryptSeed(seed, nextKey),
+        updatedAt: now,
+      });
+    }
+
+    file = {
+      vaultVersion: VAULT_VERSION,
+      kdf: { name: "pbkdf2", params },
+      entries: Array.from(entries.values()),
+    };
+    key = nextKey;
+    await save();
+  };
+
+  const exportEncrypted = (): VaultExport => {
+    if (!file) throw new VaultError("Vault not initialized");
+    return { ...file, entries: Array.from(entries.values()) };
+  };
+
+  const exportJson = (): string => {
+    return JSON.stringify(exportEncrypted(), null, 2);
+  };
+
+  const importEncrypted = async (
+    inputExport: VaultExport | string,
+    options?: Readonly<{ mode?: "merge" | "replace"; sourcePassphrase?: string }>,
+  ): Promise<void> => {
+    const source = typeof inputExport === "string" ? parseVaultFile(inputExport) : inputExport;
+    if (source.kdf.name !== "pbkdf2") {
+      throw new VaultError("Unsupported KDF");
+    }
+    const sourceKey = await deriveKey(options?.sourcePassphrase ?? passphrase, source.kdf.params);
+    const mode = options?.mode ?? "merge";
+    const now = new Date().toISOString();
+
+    const nextEntries = mode === "replace" ? new Map<string, VaultEntry>() : new Map(entries);
+
+    for (const entry of source.entries) {
+      const seed = await decryptSeed(entry.encrypted, sourceKey);
+      const encrypted = await encryptSeed(seed, key);
+      nextEntries.set(entry.name, {
+        name: entry.name,
+        identity: entry.identity,
+        seedIndex: entry.seedIndex,
+        createdAt: entry.createdAt,
+        updatedAt: now,
+        encrypted,
+      });
+    }
+
+    entries.clear();
+    for (const [name, entry] of nextEntries.entries()) {
+      entries.set(name, entry);
+    }
+    if (autoSave) await save();
+  };
+
+  const getSeedSource = async (ref: string): Promise<Readonly<{ fromSeed: string }>> => {
+    const fromSeed = await getSeed(ref);
+    return { fromSeed };
+  };
+
+  const close = async (): Promise<void> => {
+    return;
+  };
+
+  return {
+    path,
+    list,
+    getEntry: findEntry,
+    getIdentity,
+    signer,
+    getSeed,
+    addSeed,
+    remove,
+    rotatePassphrase,
+    exportEncrypted,
+    exportJson,
+    importEncrypted,
+    getSeedSource,
+    save,
+    close,
+  };
+}
+
+export function createMemoryVaultStore(label = "memory-vault"): VaultStore {
+  let value: string | null = null;
+  return {
+    label,
+    async read() {
+      return value;
+    },
+    async write(next: string) {
+      value = next;
+    },
+    async remove() {
+      value = null;
+    },
+  };
+}
+
+export function createLocalStorageVaultStore(key: string, storage?: Storage): VaultStore {
+  const store = storage ?? getDefaultStorage();
+  if (!store) {
+    throw new VaultError("localStorage is not available in this environment");
+  }
+  return {
+    label: key,
+    async read() {
+      return store.getItem(key);
+    },
+    async write(next) {
+      store.setItem(key, next);
+    },
+    async remove() {
+      store.removeItem(key);
+    },
+  };
+}
+
+function getDefaultStorage(): Storage | undefined {
+  const anyGlobal = globalThis as typeof globalThis & { localStorage?: Storage };
+  return anyGlobal.localStorage;
+}
+
+function createKdfParams(
+  overrides?: Readonly<{ iterations?: number; hash?: Pbkdf2Hash; dkLen?: number }>,
+): Pbkdf2KdfParams {
+  const params = {
+    iterations: overrides?.iterations ?? DEFAULT_PBKDF2_PARAMS.iterations,
+    hash: overrides?.hash ?? DEFAULT_PBKDF2_PARAMS.hash,
+    dkLen: overrides?.dkLen ?? DEFAULT_PBKDF2_PARAMS.dkLen,
+  };
+  const salt = getRandomBytes(16);
+  return {
+    ...params,
+    saltBase64: bytesToBase64(salt),
+  };
+}
+
+function createEmptyVault(params: Pbkdf2KdfParams): VaultFile {
+  return {
+    vaultVersion: VAULT_VERSION,
+    kdf: {
+      name: "pbkdf2",
+      params,
+    },
+    entries: [],
+  };
+}
+
+async function deriveKey(passphrase: string, params: Pbkdf2KdfParams): Promise<CryptoKey> {
+  const crypto = await getCrypto();
+  const salt = base64ToBytes(params.saltBase64);
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    toArrayBuffer(utf8ToBytes(passphrase)),
+    "PBKDF2",
+    false,
+    ["deriveKey"],
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt: toArrayBuffer(salt),
+      iterations: params.iterations,
+      hash: params.hash,
+    },
+    baseKey,
+    { name: "AES-GCM", length: params.dkLen * 8 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+async function encryptSeed(seed: string, key: CryptoKey): Promise<VaultEntryEncrypted> {
+  const crypto = await getCrypto();
+  const nonce = getRandomBytes(AES_GCM_NONCE_BYTES);
+  const ciphertextAndTag = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(nonce), tagLength: 128 },
+    key,
+    toArrayBuffer(utf8ToBytes(seed)),
+  );
+  const bytes = new Uint8Array(ciphertextAndTag);
+  const ciphertext = bytes.slice(0, bytes.length - AES_GCM_TAG_BYTES);
+  const tag = bytes.slice(bytes.length - AES_GCM_TAG_BYTES);
+  return {
+    nonceBase64: bytesToBase64(nonce),
+    ciphertextBase64: bytesToBase64(ciphertext),
+    tagBase64: bytesToBase64(tag),
+  };
+}
+
+async function decryptSeed(encrypted: VaultEntryEncrypted, key: CryptoKey): Promise<string> {
+  const crypto = await getCrypto();
+  const nonce = base64ToBytes(encrypted.nonceBase64);
+  const ciphertext = base64ToBytes(encrypted.ciphertextBase64);
+  const tag = base64ToBytes(encrypted.tagBase64);
+  const combined = new Uint8Array(ciphertext.length + tag.length);
+  combined.set(ciphertext, 0);
+  combined.set(tag, ciphertext.length);
+  const clear = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(nonce), tagLength: 128 },
+    key,
+    toArrayBuffer(combined),
+  );
+  return bytesToUtf8(new Uint8Array(clear));
+}
+
+function parseVaultFile(raw: string): VaultFile {
+  const parsed = JSON.parse(raw) as VaultFile;
+  if (!parsed || typeof parsed !== "object") {
+    throw new VaultError("Invalid vault file");
+  }
+  if (!parsed.kdf || parsed.kdf.name !== "pbkdf2") {
+    throw new VaultError("Unsupported KDF");
+  }
+  return parsed;
+}
+
+async function getCrypto(): Promise<Crypto> {
+  if (globalThis.crypto?.subtle) return globalThis.crypto;
+  throw new VaultError("WebCrypto is not available in this environment");
+}
+
+function getRandomBytes(length: number): Uint8Array<ArrayBuffer> {
+  const crypto = globalThis.crypto;
+  if (!crypto?.getRandomValues) {
+    throw new VaultError("crypto.getRandomValues is not available");
+  }
+  const bytes = new Uint8Array(new ArrayBuffer(length));
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+function base64ToBytes(base64: string): Uint8Array<ArrayBuffer> {
+  if (typeof Buffer !== "undefined") {
+    const buf = Buffer.from(base64, "base64");
+    return new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function bytesToUtf8(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function utf8ToBytes(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const out = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+  out.set(bytes);
+  return out.buffer;
+}

package/src/vault-cli.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SEED = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+
+let currentDir: string | undefined;
+
+afterEach(async () => {
+  if (currentDir) {
+    await rm(currentDir, { recursive: true, force: true });
+    currentDir = undefined;
+  }
+});
+
+describe("vault cli", () => {
+  it("supports init/add/list flow", async () => {
+    currentDir = await mkdtemp(join(tmpdir(), "sdk-vault-cli-"));
+    const vaultPath = join(currentDir, "vault.json");
+
+    await runCli(["init", "--path", vaultPath, "--passphrase", "secret"]);
+    await runCli([
+      "add",
+      "--path",
+      vaultPath,
+      "--passphrase",
+      "secret",
+      "--name",
+      "main",
+      "--seed",
+      SEED,
+    ]);
+    const listed = await runCli(["list", "--path", vaultPath, "--passphrase", "secret"]);
+
+    const entries = JSON.parse(listed.stdout) as Array<{ name: string; identity: string }>;
+    expect(entries.length).toBe(1);
+    expect(entries[0]?.name).toBe("main");
+    expect(entries[0]?.identity.length).toBe(60);
+  });
+});
+
+async function runCli(args: readonly string[]): Promise<{ stdout: string; stderr: string }> {
+  const scriptPath = new URL("./vault-cli.ts", import.meta.url).pathname;
+  const proc = Bun.spawn({
+    cmd: [process.execPath, scriptPath, ...args],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new Error(`CLI failed with code ${exitCode}\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`);
+  }
+
+  return { stdout: stdout.trim(), stderr: stderr.trim() };
+}

package/src/vault-cli.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { openSeedVault } from "./vault.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+const path = getArg(args, "--path") ?? "./vault.json";
+const passphrase = getArg(args, "--passphrase");
+
+if (!passphrase) {
+  console.error("Missing --passphrase");
+  process.exit(1);
+}
+
+const vault = await openSeedVault({ path, passphrase, create: command === "init" });
+
+try {
+  switch (command) {
+    case "init":
+      console.log(`Vault ready at ${path}`);
+      break;
+    case "list":
+      console.log(JSON.stringify(vault.list(), null, 2));
+      break;
+    case "add": {
+      const name = requiredArg(args, "--name");
+      const seed = requiredArg(args, "--seed");
+      const seedIndex = parseNumberArg(args, "--index");
+      const overwrite = hasFlag(args, "--overwrite");
+      const entry = await vault.addSeed({ name, seed, seedIndex, overwrite });
+      console.log(JSON.stringify(entry, null, 2));
+      break;
+    }
+    case "remove": {
+      const name = requiredArg(args, "--name");
+      await vault.remove(name);
+      console.log(`Removed ${name}`);
+      break;
+    }
+    case "rotate": {
+      const newPassphrase = requiredArg(args, "--new-passphrase");
+      await vault.rotatePassphrase(newPassphrase);
+      console.log("Passphrase rotated");
+      break;
+    }
+    case "export": {
+      const outPath = getArg(args, "--out");
+      const json = vault.exportJson();
+      if (outPath) {
+        await writeFile(outPath, json, "utf8");
+        console.log(`Exported to ${outPath}`);
+      } else {
+        console.log(json);
+      }
+      break;
+    }
+    case "import": {
+      const importPath = requiredArg(args, "--file");
+      const mode = (getArg(args, "--mode") as "merge" | "replace" | undefined) ?? "merge";
+      const sourcePassphrase = getArg(args, "--source-passphrase") ?? passphrase;
+      const json = await readFile(importPath, "utf8");
+      await vault.importEncrypted(json, { mode, sourcePassphrase });
+      console.log(`Imported ${importPath}`);
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+} finally {
+  await vault.close();
+}
+
+function getArg(argsList: readonly string[], name: string): string | undefined {
+  const index = argsList.indexOf(name);
+  if (index === -1) return undefined;
+  return argsList[index + 1];
+}
+
+function requiredArg(argsList: readonly string[], name: string): string {
+  const value = getArg(argsList, name);
+  if (!value) {
+    console.error(`Missing ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function parseNumberArg(argsList: readonly string[], name: string): number | undefined {
+  const value = getArg(argsList, name);
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    console.error(`${name} must be an integer`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+function hasFlag(argsList: readonly string[], name: string): boolean {
+  return argsList.includes(name);
+}
+
+function printHelp() {
+  console.log(`Seed vault CLI
+
+Usage:
+  qubic-vault init --path ./vault.json --passphrase "secret"
+  qubic-vault list --path ./vault.json --passphrase "secret"
+  qubic-vault add --path ./vault.json --passphrase "secret" --name main --seed "..." [--index 0] [--overwrite]
+  qubic-vault remove --path ./vault.json --passphrase "secret" --name main
+  qubic-vault rotate --path ./vault.json --passphrase "secret" --new-passphrase "next"
+  qubic-vault export --path ./vault.json --passphrase "secret" [--out backup.json]
+  qubic-vault import --path ./vault.json --passphrase "secret" --file backup.json [--mode merge|replace] [--source-passphrase "secret"]
+`);
+}