API Reference

The complete IVault surface exposed by @p47h/vault-js. Every method below exists in the published package. init() must be called once before any other operation.

Badges: async returns a Promise · sync returns immediately.

Lifecycle

init()

async

Load the WASM crypto core and prepare the environment. Call once, before anything else.

init(config?: VaultConfig): Promise<void>

Throws InitializationError if the WASM module fails to load.

lock()

sync

Lock the vault: clear session keys and cached secrets from memory (zeroized). The identity stays on disk; call login() to unlock again.

lock(): void

dispose()

sync

Release all resources. After dispose(), the instance cannot be reused — create a new one.

dispose(): void

Identity

register()

async

Create a new Ed25519 identity (a DID), encrypted at rest with the password. Returns the DID and a one-time recovery code — the only way to recover the vault if the password is lost. Show it to the user once.

register(password: string): Promise<RegistrationResult>

Throws InitializationError if the vault is not initialized; CryptoError if key generation fails.

login()

async

Unlock an existing identity. With no did, the first stored identity is used.

login(password: string, did?: string): Promise<IdentityInfo>

Throws AuthenticationError if the password is wrong or the identity is not found; VaultError if the stored data is corrupted.

recoverAccount()

async

Recover access with the emergency recovery code when the password is lost. Decrypts with the recovery code, re-encrypts with the new password, and optionally issues a fresh recovery code.

recoverAccount(options: RecoveryOptions): Promise<RecoveryResult>

Throws AuthenticationError if the recovery code is invalid; VaultError if recovery is unavailable for the identity.

getDid()

sync

The DID of the currently unlocked identity.

getDid(): string

Throws NotAuthenticatedError if the vault is locked.

isAuthenticated()

sync

Whether an identity is currently unlocked.

isAuthenticated(): boolean

getStoredIdentities()

async

List the DIDs that exist in local storage. Useful to decide between Login and Register.

getStoredIdentities(): Promise<string[]>

Throws InitializationError if the vault is not initialized.

Secrets

saveSecret()

async

Encrypt and persist a value under key. The payload is encrypted before it reaches storage.

saveSecret(key: string, secret: string): Promise<void>

Throws NotAuthenticatedError if the vault is locked; VaultError if the write fails.

getSecret()

async

Retrieve and decrypt a secret. Returns null if the key does not exist.

getSecret(key: string): Promise<string | null>

Throws NotAuthenticatedError if the vault is locked.

listSecretKeys()

sync

The keys of all secrets in the unlocked vault (empty array if none). Reads the in-memory session — no decryption round-trip.

listSecretKeys(): string[]

Throws NotAuthenticatedError if the vault is locked.

Cryptography

sign()

async

Sign arbitrary bytes with the current identity’s Ed25519 private key. The key never leaves WASM memory. Returns the 64-byte signature.

sign(data: Uint8Array): Promise<Uint8Array>

Throws NotAuthenticatedError if the vault is locked.

sign() is part of @p47h/vault-js. The React bindings (@p47h/vault-react) do not expose it today — call it through the underlying vault instance if you need it.

Types

interface VaultConfig {
  wasmPath?: string;   // override the WASM path (defaults to the bundled core)
  storage?: IStorage;  // custom storage adapter (defaults to IndexedDB)
}

interface RegistrationResult {
  did: string;          // the new Decentralized Identifier
  recoveryCode: string; // one-time emergency code — store it offline
}

interface IdentityInfo {
  did: string;
  publicKey: Uint8Array; // 32-byte Ed25519 public key
}

interface RecoveryOptions {
  recoveryCode: string;
  newPassword: string;
  did?: string;
  rotateRecoveryCode?: boolean; // issue a fresh code after recovery (default false)
}

interface RecoveryResult {
  did: string;
  newRecoveryCode?: string; // present if a fresh code was issued
}