VaultStore
katanakit-js / VaultStore
Class: VaultStore
Section titled “Class: VaultStore”Defined in: infrastructure/vault/vault.store.ts:40
Encrypted vault persistence: scrypt key derivation + AES-256-GCM, versioned envelope, atomic writes.
This module owns all crypto and filesystem I/O for the key manager. Node
built-ins load through dynamic import() (the same idiom
storage.service.ts uses for node:async_hooks), so merely importing this
module stays browser- and SSR-safe and no key material exists outside the
two functions below.
The vault file never leaves the machine: keys export re-encrypts the same
payload for backups, so a stolen backup is useless without the passphrase.
Example
Section titled “Example”import { useSaveVaultFile, useLoadVaultFile } from "katanakit-js/infrastructure";
await useSaveVaultFile(path, vault, passphrase);const loaded = await useLoadVaultFile(path, passphrase);Methods
Section titled “Methods”useDecryptVault()
Section titled “useDecryptVault()”useDecryptVault(payload, passphrase): Promise<SafeResult<{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;}>>;Defined in: infrastructure/vault/vault.store.ts:147
Opens an envelope with a passphrase. A wrong passphrase and a tampered file both fail GCM authentication and are reported the same way — never say which one it was.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
payload |
string |
The serialized envelope. |
passphrase |
string |
The passphrase to open it with. |
Returns
Section titled “Returns”Promise<SafeResult<{
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
}>>
{ data, error, ok } with the decrypted payload.
useEncryptVault()
Section titled “useEncryptVault()”useEncryptVault(data, passphrase): Promise<SafeResult<string>>;Defined in: infrastructure/vault/vault.store.ts:77
Encrypts a vault payload into the on-disk envelope format.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The decrypted payload (validated before sealing). |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
passphrase |
string |
The passphrase the vault is sealed with. |
Returns
Section titled “Returns”Promise<SafeResult<string>>
{ data, error, ok } with the serialized envelope.
useLoadVaultFile()
Section titled “useLoadVaultFile()”useLoadVaultFile(path, passphrase): Promise<SafeResult<{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;}>>;Defined in: infrastructure/vault/vault.store.ts:265
Reads and opens a vault file. A missing file resolves with
error.status = 404 so callers can decide between “start fresh” and
“fail loudly” without parsing error strings.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
path |
string |
The vault file path. |
passphrase |
string |
The passphrase to open it with. |
Returns
Section titled “Returns”Promise<SafeResult<{
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
}>>
{ data, error, ok } with the decrypted payload.
useSaveVaultFile()
Section titled “useSaveVaultFile()”useSaveVaultFile( path, data, passphrase): Promise<SafeResult<string>>;Defined in: infrastructure/vault/vault.store.ts:227
Encrypts and writes the vault atomically (temp file + rename) with owner-only permissions, creating the parent directory when needed.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
path |
string |
Target file path. |
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The payload to persist. |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
passphrase |
string |
The passphrase to seal it with. |
Returns
Section titled “Returns”Promise<SafeResult<string>>
{ data, error, ok } with the written path.
useVaultPath()
Section titled “useVaultPath()”useVaultPath(): Promise<string>;Defined in: infrastructure/vault/vault.store.ts:61
Resolves the vault file location: KATANAKITAI_VAULT when set,
otherwise $XDG_CONFIG_HOME/katanakitai/vault.enc.json (defaulting to
~/.config).
Returns
Section titled “Returns”Promise<string>
The absolute vault file path.
getInstance()
Section titled “getInstance()”static getInstance(): VaultStore;Defined in: infrastructure/vault/vault.store.ts:47
Returns the shared instance (Singleton).
Returns
Section titled “Returns”VaultStore