@elizaos/vault 2.0.0-alpha.537

package/dist/master-key.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Where the encryption master key lives.
+ *
+ * Resolvers, ordered by preference for `defaultMasterKey()`:
+ *
+ *   1. **OS keychain** — cross-platform via @napi-rs/keyring (macOS
+ *      Keychain, Windows Credential Manager, Linux Secret Service /
+ *      libsecret). The default on machines with a desktop session.
+ *   2. **Passphrase** — scrypt-derived 32-byte key from `ELIZA_VAULT_PASSPHRASE`
+ *      with a per-service salt. Use this on headless Linux servers, in
+ *      Docker containers, or in CI where the OS keychain isn't reachable.
+ *      Operator opts in by setting the env var; we never derive from a
+ *      hard-coded fallback.
+ *   3. **In-memory** — `inMemoryMasterKey(buffer)`. Tests only.
+ *
+ * `defaultMasterKey()` walks 1 → 2 and throws a single
+ * `MasterKeyUnavailableError` with both paths' diagnostic messages when
+ * neither is available. Operators see a single line that names every
+ * remediation option.
+ */
+export interface MasterKeyResolver {
+    load(): Promise<Buffer>;
+    describe(): string;
+}
+export declare class MasterKeyUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare function inMemoryMasterKey(key: Buffer): MasterKeyResolver;
+export interface OsKeychainOptions {
+    /** Service name shown in the OS keychain UI. Default: "eliza". */
+    readonly service?: string;
+    /** Account/account name within the service. Default: "vault.masterKey". */
+    readonly account?: string;
+}
+export interface PassphraseOptions {
+    /**
+     * Passphrase string. Typically read from `process.env.ELIZA_VAULT_PASSPHRASE`.
+     * Must be at least 12 characters; shorter passphrases are rejected to
+     * push operators away from trivially-brute-forceable keys.
+     */
+    readonly passphrase: string;
+    /**
+     * Salt for the scrypt KDF. Default: derived from the service identifier
+     * so two distinct services on the same host with the same passphrase
+     * still produce different keys. Override only if you know what you're
+     * doing — changing the salt invalidates every value already in the
+     * vault.
+     */
+    readonly salt?: string;
+    /**
+     * scrypt cost. Default 2^15 = 32_768 — same order of magnitude as 1Password's
+     * recommendation for a master password derivation, comfortably below the
+     * default 64MB memory cap on Node's scrypt. Override for tests if needed.
+     */
+    readonly cost?: number;
+    /** Service identifier used as the default salt prefix. Default `"eliza"`. */
+    readonly service?: string;
+}
+/**
+ * Master key derived from a passphrase via scrypt. Use this when no OS
+ * keychain is available — typically headless Linux servers or containers.
+ *
+ * The same passphrase + salt + cost always produces the same key, so
+ * operators MUST keep their passphrase stable across restarts (otherwise
+ * existing ciphertext can no longer be decrypted).
+ */
+export declare function passphraseMasterKey(opts: PassphraseOptions): MasterKeyResolver;
+/**
+ * Construct a passphrase resolver from `ELIZA_VAULT_PASSPHRASE` env. Returns
+ * `null` when the env var is absent or empty so callers can fall through
+ * to the next strategy without a try/catch dance.
+ */
+export declare function passphraseMasterKeyFromEnv(service?: string): MasterKeyResolver | null;
+/**
+ * Default resolver: try the OS keychain first, then a passphrase-derived
+ * key from `ELIZA_VAULT_PASSPHRASE`. If both fail, throws a single
+ * `MasterKeyUnavailableError` whose message lists every remediation
+ * option so operators on a fresh headless box see one actionable line.
+ *
+ * Tests should NOT use this — pass `inMemoryMasterKey(...)` to
+ * `createVault()` directly. Production paths that already inject a
+ * resolver are unaffected.
+ */
+export declare function defaultMasterKey(opts?: OsKeychainOptions): MasterKeyResolver;
+export declare function osKeychainMasterKey(opts?: OsKeychainOptions): MasterKeyResolver;
+//# sourceMappingURL=master-key.d.ts.map

package/dist/master-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-key.d.ts","sourceRoot":"","sources":["../src/master-key.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAchE;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,GACtB,iBAAiB,CAgDnB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,GAAG,IAAI,CAO1B;AAyCD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,GAAE,iBAAsB,GAC3B,iBAAiB,CA0DnB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,iBAAsB,GAC3B,iBAAiB,CAqEnB"}

package/dist/master-key.js

@@ -0,0 +1,247 @@
+import { scryptSync } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { generateMasterKey, KEY_BYTES } from "./crypto.js";
+export class MasterKeyUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MasterKeyUnavailableError";
+    }
+}
+export function inMemoryMasterKey(key) {
+    if (key.length !== KEY_BYTES) {
+        throw new MasterKeyUnavailableError(`inMemoryMasterKey: expected ${KEY_BYTES} bytes, got ${key.length}`);
+    }
+    return {
+        async load() {
+            return key;
+        },
+        describe() {
+            return "inMemory";
+        },
+    };
+}
+const PASSPHRASE_MIN_LENGTH = 12;
+const DEFAULT_SCRYPT_COST = 1 << 15;
+const DEFAULT_SCRYPT_BLOCK_SIZE = 8;
+const DEFAULT_SCRYPT_PARALLELIZATION = 1;
+/**
+ * Master key derived from a passphrase via scrypt. Use this when no OS
+ * keychain is available — typically headless Linux servers or containers.
+ *
+ * The same passphrase + salt + cost always produces the same key, so
+ * operators MUST keep their passphrase stable across restarts (otherwise
+ * existing ciphertext can no longer be decrypted).
+ */
+export function passphraseMasterKey(opts) {
+    if (typeof opts.passphrase !== "string") {
+        throw new MasterKeyUnavailableError("passphraseMasterKey: passphrase must be a string");
+    }
+    if (opts.passphrase.length < PASSPHRASE_MIN_LENGTH) {
+        throw new MasterKeyUnavailableError(`passphraseMasterKey: passphrase must be at least ${PASSPHRASE_MIN_LENGTH} characters`);
+    }
+    const service = opts.service ?? "eliza";
+    const salt = opts.salt ?? `${service}.vault.masterKey.v1`;
+    const cost = opts.cost ?? DEFAULT_SCRYPT_COST;
+    return {
+        async load() {
+            // scryptSync is intentional: this runs once per process at vault
+            // construction. Using the async variant adds noise without
+            // measurable benefit on a one-shot derivation.
+            try {
+                // N=32_768 r=8 needs ~32MB, exactly Node's default `maxmem` cap, which
+                // OpenSSL rejects with MEMORY_LIMIT_EXCEEDED. Raise the cap to 64MB so
+                // the default cost works on every platform.
+                const derived = scryptSync(opts.passphrase, salt, KEY_BYTES, {
+                    N: cost,
+                    r: DEFAULT_SCRYPT_BLOCK_SIZE,
+                    p: DEFAULT_SCRYPT_PARALLELIZATION,
+                    maxmem: 64 * 1024 * 1024,
+                });
+                if (derived.length !== KEY_BYTES) {
+                    throw new MasterKeyUnavailableError(`passphraseMasterKey: scrypt returned ${derived.length} bytes, expected ${KEY_BYTES}`);
+                }
+                return derived;
+            }
+            catch (err) {
+                if (err instanceof MasterKeyUnavailableError)
+                    throw err;
+                throw new MasterKeyUnavailableError(`passphraseMasterKey: scrypt derivation failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+        describe() {
+            return `passphrase://${service}`;
+        },
+    };
+}
+/**
+ * Construct a passphrase resolver from `ELIZA_VAULT_PASSPHRASE` env. Returns
+ * `null` when the env var is absent or empty so callers can fall through
+ * to the next strategy without a try/catch dance.
+ */
+export function passphraseMasterKeyFromEnv(service) {
+    const raw = process.env.ELIZA_VAULT_PASSPHRASE;
+    if (!raw || raw.length === 0)
+        return null;
+    return passphraseMasterKey({
+        passphrase: raw,
+        ...(service ? { service } : {}),
+    });
+}
+/**
+ * Detects hosts where invoking `@napi-rs/keyring` is known to crash the
+ * process at the native level instead of throwing a catchable JS error:
+ *
+ *   - explicit opt-out via `ELIZA_VAULT_DISABLE_KEYCHAIN=1`
+ *   - headless Linux with no reachable D-Bus session (the libsecret
+ *     backend aborts at the C level when it can't reach the Secret
+ *     Service)
+ *
+ * D-Bus reachability on Linux is checked two ways:
+ *
+ *   1. `DBUS_SESSION_BUS_ADDRESS` env var — the classical signal,
+ *      reliably set by desktop session startup and `dbus-launch`.
+ *   2. `$XDG_RUNTIME_DIR/bus` socket — modern systemd user sessions
+ *      socket-activate D-Bus and don't always export the env var
+ *      (notably SSH sessions without env forwarding, and Fedora /
+ *      Arch / Ubuntu 22+ desktops). Treat the socket file's presence
+ *      as equivalent to the env var.
+ *
+ * This is intentionally a heuristic: it never returns `false` (safe)
+ * for a host that would actually crash, and may return `false` (safe)
+ * for a host where the keychain ultimately fails with a regular JS
+ * error. That's the desired direction — we'd rather attempt the
+ * keychain and let the existing try/catch handle a JS-level failure
+ * than refuse on a host where it would have worked.
+ */
+function isKeychainUnsafe() {
+    if (process.env.ELIZA_VAULT_DISABLE_KEYCHAIN === "1")
+        return true;
+    if (process.platform !== "linux")
+        return false;
+    if (process.env.DBUS_SESSION_BUS_ADDRESS)
+        return false;
+    const xdgRuntime = process.env.XDG_RUNTIME_DIR;
+    if (xdgRuntime && existsSync(join(xdgRuntime, "bus")))
+        return false;
+    return true;
+}
+function keychainUnsafeMessage(prefix) {
+    return `${prefix}OS keychain is unsafe on this host (headless Linux with no reachable D-Bus session, or ELIZA_VAULT_DISABLE_KEYCHAIN=1). Set ELIZA_VAULT_PASSPHRASE (≥${PASSPHRASE_MIN_LENGTH} chars) to enable a passphrase-derived master key, or pass an inMemoryMasterKey.`;
+}
+/**
+ * Default resolver: try the OS keychain first, then a passphrase-derived
+ * key from `ELIZA_VAULT_PASSPHRASE`. If both fail, throws a single
+ * `MasterKeyUnavailableError` whose message lists every remediation
+ * option so operators on a fresh headless box see one actionable line.
+ *
+ * Tests should NOT use this — pass `inMemoryMasterKey(...)` to
+ * `createVault()` directly. Production paths that already inject a
+ * resolver are unaffected.
+ */
+export function defaultMasterKey(opts = {}) {
+    const keychain = osKeychainMasterKey(opts);
+    return {
+        async load() {
+            // Skip the OS keychain on hosts where @napi-rs/keyring is known to
+            // segfault the process instead of throwing a catchable JS error.
+            // The defensive try/catch around keychain.load() can't help once
+            // the native crash fires.
+            if (isKeychainUnsafe()) {
+                const passphrase = passphraseMasterKeyFromEnv(opts.service);
+                if (passphrase)
+                    return passphrase.load();
+                throw new MasterKeyUnavailableError(keychainUnsafeMessage("vault: "));
+            }
+            try {
+                return await keychain.load();
+            }
+            catch (keychainErr) {
+                const passphrase = passphraseMasterKeyFromEnv(opts.service);
+                if (passphrase) {
+                    try {
+                        return await passphrase.load();
+                    }
+                    catch (passphraseErr) {
+                        throw new MasterKeyUnavailableError(`vault master key unavailable. Keychain: ${keychainErr instanceof Error
+                            ? keychainErr.message
+                            : String(keychainErr)}. Passphrase: ${passphraseErr instanceof Error
+                            ? passphraseErr.message
+                            : String(passphraseErr)}.`);
+                    }
+                }
+                throw new MasterKeyUnavailableError(`vault master key unavailable. ${keychainErr instanceof Error
+                    ? keychainErr.message
+                    : String(keychainErr)} To use a passphrase-derived key on a headless host, set ELIZA_VAULT_PASSPHRASE (≥${PASSPHRASE_MIN_LENGTH} chars) and restart.`);
+            }
+        },
+        describe() {
+            // describe() reflects the runtime-selected path. On hosts where
+            // the keychain is bypassed, surfacing `keychain://...` would
+            // misrepresent which resolver actually ran.
+            const passphrase = passphraseMasterKeyFromEnv(opts.service);
+            if (isKeychainUnsafe()) {
+                return passphrase
+                    ? `${passphrase.describe()} (keychain bypassed: host unsafe)`
+                    : `unavailable (keychain bypassed: host unsafe; no ELIZA_VAULT_PASSPHRASE set)`;
+            }
+            return passphrase
+                ? `${keychain.describe()} (fallback: ${passphrase.describe()})`
+                : keychain.describe();
+        },
+    };
+}
+export function osKeychainMasterKey(opts = {}) {
+    const service = opts.service ?? "eliza";
+    const account = opts.account ?? "vault.masterKey";
+    return {
+        async load() {
+            // Refuse to invoke the native binding on hosts where it crashes
+            // the process. Direct callers of `osKeychainMasterKey` (plugins,
+            // integrations) get the same protection as `defaultMasterKey`.
+            if (isKeychainUnsafe()) {
+                throw new MasterKeyUnavailableError(keychainUnsafeMessage(`OS keychain (${service}/${account}): `));
+            }
+            let Entry;
+            try {
+                ({ Entry } = await import("@napi-rs/keyring"));
+            }
+            catch (err) {
+                throw new MasterKeyUnavailableError(`OS keychain binding unavailable (${service}/${account}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            let entry;
+            try {
+                entry = new Entry(service, account);
+            }
+            catch (err) {
+                throw new MasterKeyUnavailableError(`OS keychain entry construction failed (${service}/${account}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            let existing = null;
+            try {
+                existing = entry.getPassword();
+            }
+            catch (err) {
+                throw new MasterKeyUnavailableError(`OS keychain read failed (${service}/${account}): ${err instanceof Error ? err.message : String(err)}. On Linux, ensure libsecret + a Secret Service agent (gnome-keyring / kwallet) is running, or pass an inMemoryMasterKey.`);
+            }
+            if (existing && existing.length > 0) {
+                const buf = Buffer.from(existing, "base64");
+                if (buf.length !== KEY_BYTES) {
+                    throw new MasterKeyUnavailableError(`OS keychain entry ${service}/${account} is not a ${KEY_BYTES}-byte key`);
+                }
+                return buf;
+            }
+            const created = generateMasterKey();
+            try {
+                entry.setPassword(created.toString("base64"));
+            }
+            catch (err) {
+                throw new MasterKeyUnavailableError(`OS keychain write failed (${service}/${account}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return created;
+        },
+        describe() {
+            return `keychain://${service}/${account}`;
+        },
+    };
+}
+//# sourceMappingURL=master-key.js.map

package/dist/master-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-key.js","sourceRoot":"","sources":["../src/master-key.ts"],"names":[],"mappings":"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"}

package/dist/password-managers.d.ts

@@ -0,0 +1,17 @@
+import type { PasswordManagerReference } from "./types.js";
+/**
+ * Resolve a password-manager reference at use time.
+ *
+ * 1Password: shells out to `op read op://<vault>/<item>/<field>`.
+ * Proton Pass: scaffolded; the vendor's CLI/SDK isn't stable enough
+ * to wire in v1.
+ *
+ * The reference contents are never copied to disk by the vault; only
+ * the reference itself (`{ source, path }`) is stored.
+ */
+export declare class PasswordManagerError extends Error {
+    readonly source: PasswordManagerReference["source"];
+    constructor(source: PasswordManagerReference["source"], message: string);
+}
+export declare function resolveReference(ref: PasswordManagerReference): Promise<string>;
+//# sourceMappingURL=password-managers.d.ts.map

package/dist/password-managers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-managers.d.ts","sourceRoot":"","sources":["../src/password-managers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAI3D;;;;;;;;;GASG;AAEH,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC;gBAA1C,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACnD,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/password-managers.js

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+/**
+ * Resolve a password-manager reference at use time.
+ *
+ * 1Password: shells out to `op read op://<vault>/<item>/<field>`.
+ * Proton Pass: scaffolded; the vendor's CLI/SDK isn't stable enough
+ * to wire in v1.
+ *
+ * The reference contents are never copied to disk by the vault; only
+ * the reference itself (`{ source, path }`) is stored.
+ */
+export class PasswordManagerError extends Error {
+    source;
+    constructor(source, message) {
+        super(`[${source}] ${message}`);
+        this.source = source;
+        this.name = "PasswordManagerError";
+    }
+}
+export async function resolveReference(ref) {
+    if (ref.source === "1password")
+        return resolve1Password(ref.path);
+    if (ref.source === "protonpass")
+        return resolveProtonPass(ref.path);
+    throw new PasswordManagerError(ref.source, "unsupported source");
+}
+async function resolve1Password(path) {
+    const uri = path.startsWith("op://") ? path : `op://${path}`;
+    try {
+        const { stdout } = await exec("op", ["read", uri], {
+            encoding: "utf8",
+            timeout: 5000,
+        });
+        const value = stdout.trim();
+        if (value.length === 0) {
+            throw new PasswordManagerError("1password", `${uri} is empty`);
+        }
+        return value;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            throw new PasswordManagerError("1password", "`op` CLI not found. Install from https://developer.1password.com/docs/cli, then sign in (`eval $(op signin)`).");
+        }
+        if (err instanceof PasswordManagerError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/not signed in|not authenticated/i.test(msg)) {
+            throw new PasswordManagerError("1password", "`op` is not signed in. Unlock the 1Password desktop app or run `eval $(op signin)`.");
+        }
+        throw new PasswordManagerError("1password", msg);
+    }
+}
+async function resolveProtonPass(_path) {
+    throw new PasswordManagerError("protonpass", "Proton Pass integration is scaffolded; vendor CLI / SDK is not yet stable. File a request to prioritize.");
+}
+//# sourceMappingURL=password-managers.js.map

package/dist/password-managers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-managers.js","sourceRoot":"","sources":["../src/password-managers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEjC;;;;;;;;;GASG;AAEH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IADX,YACW,MAA0C,EACnD,OAAe;QAEf,KAAK,CAAC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;QAHvB,WAAM,GAAN,MAAM,CAAoC;QAInD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAA6B;IAE7B,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpE,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AACnE,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;YACjD,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,GAAG,GAAG,WAAW,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAA4B,CAAC;QACvC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,gHAAgH,CACjH,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,YAAY,oBAAoB;YAAE,MAAM,GAAG,CAAC;QACnD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,IAAI,kCAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,qFAAqF,CACtF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,KAAa;IAC5C,MAAM,IAAI,oBAAoB,CAC5B,YAAY,EACZ,0GAA0G,CAC3G,CAAC;AACJ,CAAC"}

package/dist/profiles.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Profile resolution + per-context routing on top of `Vault`.
+ *
+ * Two layers:
+ *
+ * 1. Per-key active profile.
+ *    A key K can have multiple named profiles (e.g. work, personal,
+ *    throwaway). Each profile's value lives at `K.profile.<profileId>`;
+ *    the meta blob (`_meta.K`) tracks the profile list and which one
+ *    is currently active for bare reads. When no meta is present the
+ *    legacy storage path is used (the value lives at K itself).
+ *
+ * 2. Per-context routing rules.
+ *    A user can declare "for OPENROUTER_API_KEY, when agentId=X use the
+ *    work profile". Rules are walked in order; the first match wins.
+ *    Falls back to the key's `activeProfile`, then to the global
+ *    `defaultProfile`, then to the legacy bare-key value.
+ *
+ * The vault stays dumb: every read goes through `Vault.get/has`. The
+ * only routing logic lives here so the vault contract is unchanged.
+ */
+import type { Vault } from "./vault.js";
+export type RoutingScopeKind = "agent" | "app" | "skill";
+export interface RoutingScope {
+    readonly kind: RoutingScopeKind;
+    readonly agentId?: string;
+    readonly appName?: string;
+    readonly skillId?: string;
+}
+export interface RoutingRule {
+    /** Exact-match against the vault key (e.g. "OPENROUTER_API_KEY"). */
+    readonly keyPattern: string;
+    readonly scope: RoutingScope;
+    readonly profileId: string;
+}
+export interface RoutingConfig {
+    readonly rules: ReadonlyArray<RoutingRule>;
+    /**
+     * Profile id used when no rule matches and the key's own
+     * `activeProfile` is unset. Acts as the global default for keys
+     * that have profiles enabled.
+     */
+    readonly defaultProfile?: string;
+}
+export interface ResolutionContext {
+    readonly agentId?: string;
+    readonly appName?: string;
+    readonly skillId?: string;
+}
+/**
+ * Resolve `key` against (a) per-context routing rules, (b) the key's
+ * `activeProfile`, (c) the global `defaultProfile`, then (d) the bare
+ * key value.
+ *
+ * Throws when none of the above resolves to a stored value — callers
+ * decide how to surface the miss (e.g. inventory routes return 404,
+ * runtime callers fall back to env var).
+ */
+export declare function resolveActiveValue(vault: Vault, key: string, ctx?: ResolutionContext): Promise<string>;
+/**
+ * Read the routing config blob from the vault. Missing or malformed
+ * entries return `EMPTY_ROUTING` — routing is best-effort overlay,
+ * not a load-bearing contract.
+ */
+export declare function readRoutingConfig(vault: Vault): Promise<RoutingConfig>;
+/** Persist the routing config blob. Caller-validated input. */
+export declare function writeRoutingConfig(vault: Vault, config: RoutingConfig): Promise<void>;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,iBAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,CAI5E;AAED,+DAA+D;AAC/D,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC,CAGf"}