@auxiora/vault 1.0.0

package/dist/storage.js

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getVaultPath, isWindows } from '@auxiora/core';
+export { getVaultPath };
+export async function readVaultFile(customPath) {
+    const vaultPath = customPath || getVaultPath();
+    try {
+        const content = await fs.readFile(vaultPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeVaultFile(vaultFile, customPath) {
+    const vaultPath = customPath || getVaultPath();
+    const vaultDir = path.dirname(vaultPath);
+    // Create parent directories if needed
+    await fs.mkdir(vaultDir, { recursive: true });
+    // Write the file
+    await fs.writeFile(vaultPath, JSON.stringify(vaultFile, null, 2), 'utf-8');
+    // Set permissions to 0600 on Unix
+    if (!isWindows()) {
+        await fs.chmod(vaultPath, 0o600);
+    }
+}
+export async function deleteVaultFile(customPath) {
+    const vaultPath = customPath || getVaultPath();
+    try {
+        await fs.unlink(vaultPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+export async function vaultExists(customPath) {
+    const vaultPath = customPath || getVaultPath();
+    try {
+        await fs.access(vaultPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAUxD,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAmB;IACrD,MAAM,SAAS,GAAG,UAAU,IAAI,YAAY,EAAE,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAc,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAoB,EAAE,UAAmB;IAC5E,MAAM,SAAS,GAAG,UAAU,IAAI,YAAY,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEzC,sCAAsC;IACtC,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,iBAAiB;IACjB,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE3E,kCAAkC;IAClC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACjB,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAmB;IACvD,MAAM,SAAS,GAAG,UAAU,IAAI,YAAY,EAAE,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAAmB;IACnD,MAAM,SAAS,GAAG,UAAU,IAAI,YAAY,EAAE,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/vault.d.ts

@@ -0,0 +1,25 @@
+export declare class VaultError extends Error {
+    constructor(message: string);
+}
+export interface VaultOptions {
+    path?: string;
+}
+export declare class Vault {
+    private key;
+    private salt;
+    private credentials;
+    private isUnlocked;
+    private vaultPath?;
+    constructor(options?: VaultOptions);
+    unlock(password: string): Promise<void>;
+    lock(): void;
+    private ensureUnlocked;
+    private save;
+    add(name: string, value: string): Promise<void>;
+    list(): string[];
+    remove(name: string): Promise<boolean>;
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    changePassword(newPassword: string): Promise<void>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAcA,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,OAAO,CAAC,EAAE,YAAY;IAI5B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkC7C,IAAI,IAAI,IAAI;IAUZ,OAAO,CAAC,cAAc;YAMR,IAAI;IAkBZ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,IAAI,IAAI,MAAM,EAAE;IAKV,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKpB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAezD"}

package/dist/vault.js

@@ -0,0 +1,115 @@
+import { deriveKey, generateSalt, encrypt, decrypt, zeroBuffer, } from './crypto.js';
+import { readVaultFile, writeVaultFile } from './storage.js';
+export class VaultError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VaultError';
+    }
+}
+export class Vault {
+    key = null;
+    salt = null;
+    credentials = {};
+    isUnlocked = false;
+    vaultPath;
+    constructor(options) {
+        this.vaultPath = options?.path;
+    }
+    async unlock(password) {
+        const vaultFile = await readVaultFile(this.vaultPath);
+        if (vaultFile === null) {
+            // New vault - create with this password
+            this.salt = generateSalt();
+            this.key = await deriveKey(password, this.salt);
+            this.credentials = {};
+            this.isUnlocked = true;
+            await this.save();
+            return;
+        }
+        // Existing vault - decrypt
+        this.salt = Buffer.from(vaultFile.salt, 'base64');
+        this.key = await deriveKey(password, this.salt);
+        const encryptedData = {
+            iv: Buffer.from(vaultFile.iv, 'base64'),
+            ciphertext: Buffer.from(vaultFile.data, 'base64'),
+            tag: Buffer.from(vaultFile.tag, 'base64'),
+        };
+        try {
+            const plaintext = decrypt(encryptedData, this.key);
+            const data = JSON.parse(plaintext.toString('utf-8'));
+            this.credentials = data.credentials;
+            this.isUnlocked = true;
+        }
+        catch {
+            this.lock();
+            throw new VaultError('Wrong password or corrupted vault');
+        }
+    }
+    lock() {
+        if (this.key) {
+            zeroBuffer(this.key);
+            this.key = null;
+        }
+        this.salt = null;
+        this.credentials = {};
+        this.isUnlocked = false;
+    }
+    ensureUnlocked() {
+        if (!this.isUnlocked || !this.key || !this.salt) {
+            throw new VaultError('Vault is locked');
+        }
+    }
+    async save() {
+        this.ensureUnlocked();
+        const data = { credentials: this.credentials };
+        const plaintext = Buffer.from(JSON.stringify(data), 'utf-8');
+        const encrypted = encrypt(plaintext, this.key);
+        const vaultFile = {
+            version: 1,
+            salt: this.salt.toString('base64'),
+            iv: encrypted.iv.toString('base64'),
+            data: encrypted.ciphertext.toString('base64'),
+            tag: encrypted.tag.toString('base64'),
+        };
+        await writeVaultFile(vaultFile, this.vaultPath);
+    }
+    async add(name, value) {
+        this.ensureUnlocked();
+        this.credentials[name] = value;
+        await this.save();
+    }
+    list() {
+        this.ensureUnlocked();
+        return Object.keys(this.credentials);
+    }
+    async remove(name) {
+        this.ensureUnlocked();
+        if (!(name in this.credentials)) {
+            return false;
+        }
+        delete this.credentials[name];
+        await this.save();
+        return true;
+    }
+    get(name) {
+        this.ensureUnlocked();
+        return this.credentials[name];
+    }
+    has(name) {
+        this.ensureUnlocked();
+        return name in this.credentials;
+    }
+    async changePassword(newPassword) {
+        this.ensureUnlocked();
+        // Zero the old key
+        if (this.key) {
+            zeroBuffer(this.key);
+        }
+        // Generate new salt and derive new key
+        this.salt = generateSalt();
+        this.key = await deriveKey(newPassword, this.salt);
+        // Re-save with new encryption
+        await this.save();
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,OAAO,EACP,UAAU,GAEX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAkB,MAAM,cAAc,CAAC;AAM7E,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAMD,MAAM,OAAO,KAAK;IACR,GAAG,GAAkB,IAAI,CAAC;IAC1B,IAAI,GAAkB,IAAI,CAAC;IAC3B,WAAW,GAA2B,EAAE,CAAC;IACzC,UAAU,GAAG,KAAK,CAAC;IACnB,SAAS,CAAU;IAE3B,YAAY,OAAsB;QAChC,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEtD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,wCAAwC;YACxC,IAAI,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,2BAA2B;QAC3B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,GAAG,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhD,MAAM,aAAa,GAAkB;YACnC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,QAAQ,CAAC;YACvC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC;YACjD,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC;SAC1C,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YACnD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAc,CAAC;YAClE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;YACpC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,mCAAmC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,UAAU,CAAC,iBAAiB,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,MAAM,IAAI,GAAc,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,GAAI,CAAC,CAAC;QAEhD,MAAM,SAAS,GAAc;YAC3B,OAAO,EAAE,CAAC;YACV,IAAI,EAAE,IAAI,CAAC,IAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACnC,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACnC,IAAI,EAAE,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC7C,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;SACtC,CAAC;QAEF,MAAM,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,KAAa;QACnC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC/B,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,WAAmB;QACtC,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,mBAAmB;QACnB,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,uCAAuC;QACvC,IAAI,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAEnD,8BAA8B;QAC9B,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@auxiora/vault",
+  "version": "1.0.0",
+  "description": "Encrypted credential vault with AES-256-GCM and Argon2id",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "argon2": "^0.44.0",
+    "@auxiora/core": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cloud-vault.ts

@@ -0,0 +1,129 @@
+import * as crypto from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+
+/**
+ * Encrypted envelope containing a data key encrypted by the master key,
+ * and the data encrypted by the data key.
+ */
+export interface EncryptedEnvelope {
+  version: number;
+  /** Encrypted data key (base64) */
+  encryptedDataKey: string;
+  /** IV for data key encryption (base64) */
+  dataKeyIv: string;
+  /** Auth tag for data key encryption (base64) */
+  dataKeyTag: string;
+  /** Encrypted payload (base64) */
+  encryptedPayload: string;
+  /** IV for payload encryption (base64) */
+  payloadIv: string;
+  /** Auth tag for payload encryption (base64) */
+  payloadTag: string;
+}
+
+function encryptAes256Gcm(plaintext: Buffer, key: Buffer): { ciphertext: Buffer; iv: Buffer; tag: Buffer } {
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { ciphertext, iv, tag };
+}
+
+function decryptAes256Gcm(ciphertext: Buffer, key: Buffer, iv: Buffer, tag: Buffer): Buffer {
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+/**
+ * CloudVault provides client-side AES-256-GCM encryption with envelope encryption.
+ * All data is encrypted before leaving the client, so the server never sees plaintext.
+ */
+export class CloudVault {
+  /**
+   * Encrypt data using envelope encryption.
+   * Generates a random data key, encrypts the payload with it,
+   * then encrypts the data key with the master key.
+   */
+  static encrypt(plaintext: Buffer, masterKey: Buffer): EncryptedEnvelope {
+    // Generate a random data key
+    const dataKey = crypto.randomBytes(KEY_LENGTH);
+
+    // Encrypt the payload with the data key
+    const payload = encryptAes256Gcm(plaintext, dataKey);
+
+    // Encrypt the data key with the master key
+    const wrappedKey = encryptAes256Gcm(dataKey, masterKey);
+
+    // Zero the data key
+    dataKey.fill(0);
+
+    return {
+      version: 1,
+      encryptedDataKey: wrappedKey.ciphertext.toString('base64'),
+      dataKeyIv: wrappedKey.iv.toString('base64'),
+      dataKeyTag: wrappedKey.tag.toString('base64'),
+      encryptedPayload: payload.ciphertext.toString('base64'),
+      payloadIv: payload.iv.toString('base64'),
+      payloadTag: payload.tag.toString('base64'),
+    };
+  }
+
+  /**
+   * Decrypt an envelope-encrypted payload.
+   */
+  static decrypt(envelope: EncryptedEnvelope, masterKey: Buffer): Buffer {
+    // Unwrap the data key
+    const dataKey = decryptAes256Gcm(
+      Buffer.from(envelope.encryptedDataKey, 'base64'),
+      masterKey,
+      Buffer.from(envelope.dataKeyIv, 'base64'),
+      Buffer.from(envelope.dataKeyTag, 'base64'),
+    );
+
+    // Decrypt the payload
+    const plaintext = decryptAes256Gcm(
+      Buffer.from(envelope.encryptedPayload, 'base64'),
+      dataKey,
+      Buffer.from(envelope.payloadIv, 'base64'),
+      Buffer.from(envelope.payloadTag, 'base64'),
+    );
+
+    // Zero the data key
+    dataKey.fill(0);
+
+    return plaintext;
+  }
+
+  /**
+   * Re-encrypt an envelope with a new master key (for key rotation).
+   * The data key is unwrapped with the old key and re-wrapped with the new key.
+   * The payload itself is not re-encrypted (only the key envelope changes).
+   */
+  static reEncrypt(envelope: EncryptedEnvelope, oldMasterKey: Buffer, newMasterKey: Buffer): EncryptedEnvelope {
+    // Unwrap data key with old master key
+    const dataKey = decryptAes256Gcm(
+      Buffer.from(envelope.encryptedDataKey, 'base64'),
+      oldMasterKey,
+      Buffer.from(envelope.dataKeyIv, 'base64'),
+      Buffer.from(envelope.dataKeyTag, 'base64'),
+    );
+
+    // Re-wrap data key with new master key
+    const wrappedKey = encryptAes256Gcm(dataKey, newMasterKey);
+
+    // Zero the data key
+    dataKey.fill(0);
+
+    return {
+      ...envelope,
+      encryptedDataKey: wrappedKey.ciphertext.toString('base64'),
+      dataKeyIv: wrappedKey.iv.toString('base64'),
+      dataKeyTag: wrappedKey.tag.toString('base64'),
+    };
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,63 @@
+import * as crypto from 'node:crypto';
+import * as argon2 from 'argon2';
+import { zeroBuffer } from '@auxiora/core';
+
+const ARGON2_MEMORY_COST = 65536; // 64MB
+const ARGON2_TIME_COST = 3;
+const ARGON2_PARALLELISM = 1;
+const KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+
+export async function deriveKey(password: string, salt: Buffer): Promise<Buffer> {
+  const key = await argon2.hash(password, {
+    type: argon2.argon2id,
+    salt,
+    memoryCost: ARGON2_MEMORY_COST,
+    timeCost: ARGON2_TIME_COST,
+    parallelism: ARGON2_PARALLELISM,
+    hashLength: KEY_LENGTH,
+    raw: true,
+  });
+  return key;
+}
+
+export function generateSalt(): Buffer {
+  return crypto.randomBytes(32);
+}
+
+export function generateIv(): Buffer {
+  return crypto.randomBytes(IV_LENGTH);
+}
+
+export interface EncryptedData {
+  iv: Buffer;
+  ciphertext: Buffer;
+  tag: Buffer;
+}
+
+export function encrypt(plaintext: Buffer, key: Buffer): EncryptedData {
+  const iv = generateIv();
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv, {
+    authTagLength: AUTH_TAG_LENGTH,
+  });
+
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return { iv, ciphertext, tag };
+}
+
+export function decrypt(encryptedData: EncryptedData, key: Buffer): Buffer {
+  const { iv, ciphertext, tag } = encryptedData;
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv, {
+    authTagLength: AUTH_TAG_LENGTH,
+  });
+  decipher.setAuthTag(tag);
+
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return plaintext;
+}
+
+export { zeroBuffer };

package/src/eject.ts

@@ -0,0 +1,55 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+export interface EjectableData {
+  version: number;
+  exportedAt: string;
+  credentials: Record<string, string>;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * EjectManager provides data portability — export all tenant data
+ * in a portable, decrypted format that can be imported elsewhere.
+ */
+export class EjectManager {
+  /**
+   * Export all credentials to a portable JSON format.
+   */
+  static exportData(credentials: Record<string, string>, metadata?: Record<string, unknown>): EjectableData {
+    return {
+      version: 1,
+      exportedAt: new Date().toISOString(),
+      credentials: { ...credentials },
+      metadata,
+    };
+  }
+
+  /**
+   * Save exported data to a file.
+   */
+  static async saveToFile(data: EjectableData, filePath: string): Promise<void> {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  /**
+   * Load exported data from a file.
+   */
+  static async loadFromFile(filePath: string): Promise<EjectableData> {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const data = JSON.parse(content) as EjectableData;
+    if (!data.version || !data.credentials) {
+      throw new Error('Invalid eject file format');
+    }
+    return data;
+  }
+
+  /**
+   * Import credentials from ejected data into a vault-compatible format.
+   */
+  static getCredentials(data: EjectableData): Record<string, string> {
+    return { ...data.credentials };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { Vault, VaultError, type VaultOptions } from './vault.js';
+export {
+  deriveKey,
+  encrypt,
+  decrypt,
+  generateSalt,
+  generateIv,
+  zeroBuffer,
+} from './crypto.js';
+export { readVaultFile, writeVaultFile, deleteVaultFile, getVaultPath, vaultExists } from './storage.js';
+export { CloudVault, type EncryptedEnvelope } from './cloud-vault.js';
+export { KeyManager, type ExportedKey } from './key-management.js';
+export { EjectManager, type EjectableData } from './eject.js';

package/src/key-management.ts

@@ -0,0 +1,86 @@
+import * as crypto from 'node:crypto';
+
+const PBKDF2_ITERATIONS = 600000;
+const KEY_LENGTH = 32;
+const SALT_LENGTH = 32;
+
+export interface ExportedKey {
+  version: number;
+  salt: string;
+  iterations: number;
+  keyHash: string;
+}
+
+/**
+ * KeyManager handles key derivation, rotation, and import/export
+ * for client-side cloud vault encryption.
+ */
+export class KeyManager {
+  /**
+   * Derive a 256-bit key from a password using PBKDF2.
+   */
+  static async deriveKey(password: string, salt?: Buffer): Promise<{ key: Buffer; salt: Buffer }> {
+    const keySalt = salt ?? crypto.randomBytes(SALT_LENGTH);
+
+    const key = await new Promise<Buffer>((resolve, reject) => {
+      crypto.pbkdf2(password, keySalt, PBKDF2_ITERATIONS, KEY_LENGTH, 'sha512', (err, derivedKey) => {
+        if (err) reject(err);
+        else resolve(derivedKey);
+      });
+    });
+
+    return { key, salt: keySalt };
+  }
+
+  /**
+   * Generate a random 256-bit master key.
+   */
+  static generateKey(): Buffer {
+    return crypto.randomBytes(KEY_LENGTH);
+  }
+
+  /**
+   * Rotate a key: derive a new key from a new password.
+   * Returns both old and new keys for re-encryption.
+   */
+  static async rotateKey(
+    oldPassword: string,
+    oldSalt: Buffer,
+    newPassword: string,
+  ): Promise<{ oldKey: Buffer; newKey: Buffer; newSalt: Buffer }> {
+    const { key: oldKey } = await KeyManager.deriveKey(oldPassword, oldSalt);
+    const { key: newKey, salt: newSalt } = await KeyManager.deriveKey(newPassword);
+
+    return { oldKey, newKey, newSalt };
+  }
+
+  /**
+   * Export a key's metadata for storage (does NOT export the key itself).
+   * Stores the salt and a hash of the derived key for verification.
+   */
+  static exportKeyMetadata(salt: Buffer, key: Buffer): ExportedKey {
+    const keyHash = crypto.createHash('sha256').update(key).digest('hex');
+    return {
+      version: 1,
+      salt: salt.toString('base64'),
+      iterations: PBKDF2_ITERATIONS,
+      keyHash,
+    };
+  }
+
+  /**
+   * Import key metadata and verify a password against it.
+   */
+  static async verifyPassword(password: string, exported: ExportedKey): Promise<{ valid: boolean; key: Buffer }> {
+    const salt = Buffer.from(exported.salt, 'base64');
+    const { key } = await KeyManager.deriveKey(password, salt);
+    const keyHash = crypto.createHash('sha256').update(key).digest('hex');
+
+    if (keyHash === exported.keyHash) {
+      return { valid: true, key };
+    }
+
+    key.fill(0);
+    return { valid: false, key: Buffer.alloc(0) };
+  }
+}

package/src/storage.ts

@@ -0,0 +1,66 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getVaultPath, isWindows } from '@auxiora/core';
+
+export interface VaultFile {
+  version: number;
+  salt: string;
+  iv: string;
+  data: string;
+  tag: string;
+}
+
+export { getVaultPath };
+
+export async function readVaultFile(customPath?: string): Promise<VaultFile | null> {
+  const vaultPath = customPath || getVaultPath();
+
+  try {
+    const content = await fs.readFile(vaultPath, 'utf-8');
+    return JSON.parse(content) as VaultFile;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function writeVaultFile(vaultFile: VaultFile, customPath?: string): Promise<void> {
+  const vaultPath = customPath || getVaultPath();
+  const vaultDir = path.dirname(vaultPath);
+
+  // Create parent directories if needed
+  await fs.mkdir(vaultDir, { recursive: true });
+
+  // Write the file
+  await fs.writeFile(vaultPath, JSON.stringify(vaultFile, null, 2), 'utf-8');
+
+  // Set permissions to 0600 on Unix
+  if (!isWindows()) {
+    await fs.chmod(vaultPath, 0o600);
+  }
+}
+
+export async function deleteVaultFile(customPath?: string): Promise<void> {
+  const vaultPath = customPath || getVaultPath();
+
+  try {
+    await fs.unlink(vaultPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+export async function vaultExists(customPath?: string): Promise<boolean> {
+  const vaultPath = customPath || getVaultPath();
+
+  try {
+    await fs.access(vaultPath);
+    return true;
+  } catch {
+    return false;
+  }
+}