@norionsoft/qr-vault

Core vault for encrypted wallet backup storage — types, validation, and the Vault class.

Installation

npm install @norionsoft/qr-vault

Quick Start

import { Vault, isValidDsEnvelope } from '@norionsoft/qr-vault';
import { IndexedDBAdapter } from '@norionsoft/qr-vault-local';

const vault = new Vault({ adapter: new IndexedDBAdapter() });

// Validate a ds envelope
if (isValidDsEnvelope(payload)) {
  const entry = await vault.put({
    payload,
    meta: { label: 'My Wallet', chains: ['btc'] },
  });
}

// List, get, remove, export, import
const entries = await vault.list();
const entry = await vault.get('entry-id');
await vault.remove('entry-id');
const json = await vault.export('entry-id');
await vault.import(json);

API Reference

Vault

new Vault(opts: VaultOptions)

| Option | Type | Default | Description | |--------|------|---------|-------------| | adapter | VaultAdapter | required | Storage backend | | validatePayload | boolean | true | Validate payloads as ds envelopes | | wrap | WrapStrategy | — | Optional second-layer encryption | | idGenerator | () => string | crypto.randomUUID() | Custom id generator |

Methods

• put(input) — Store an encrypted entry. Overwrites if id exists.
• get(id) — Retrieve by id. Returns null if not found.
• list() — List all entries, sorted by updatedAt desc.
• remove(id) — Remove by id. No-op if missing.
• export(id) — Export as portable JSON string.
• import(json) — Import from portable JSON string.

isValidDsEnvelope(payload: string): boolean

Structural validation of a ds envelope. Checks base64 decoding, "Salted__" magic prefix, AES-CBC block alignment, and size limits. Does not verify the password.

assertValidDsEnvelope(payload: string): void

Same validation, but throws InvalidPayloadError on failure.

Error Classes

• VaultError — Base class
• InvalidPayloadError — Payload validation failed
• EntryNotFoundError — Entry not found
• DuplicateEntryError — Duplicate entry
• AdapterError — Storage backend failure (with .cause)

Conformance Suite

import { runAdapterConformance } from '@norionsoft/qr-vault/testing';

Every adapter must pass this suite. See the testing export for details.

Security

This package handles only encrypted blobs (ds envelopes). It never sees plaintext mnemonics or raw seed bytes. No telemetry, no network calls, no global state.

Compatibility

• Node.js >= 18
• Modern browsers (Chrome 80+, Firefox 78+, Safari 14+, Edge 80+)

License

MIT — Norionsoft