Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Passphrase-encrypted credential bundles (t_592d9e91): export the
* store's entries as a single schema-versioned envelope whose values are
* re-encrypted under a key the passphrase derives through the keyfile
* envelope's KDF, and import one back - into this vault or a fresh one -
* with exactness on name collisions and nothing written on a refusal.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
BUNDLE_REFUSAL_CODES,
bundleEgressScanTree,
bundleFromEgressScan,
exportSecretBundle,
importSecretBundle,
resealBundleMetadata,
SECRET_BUNDLE_SCHEMA_VERSION,
SecretBundleError,
} from "../../../../src/core/brain/secrets/bundle.ts";
import {
listSecrets,
resolveSecretReadOnly,
secretsDir,
setSecret,
} from "../../../../src/core/brain/secrets/store.ts";
import { fakeCredential } from "../../../helpers/fake-credentials.ts";
const NOW = new Date("2026-06-05T10:00:00Z");
const LATER = new Date("2026-06-05T11:00:00Z");
const CTX = { agent: "tester", now: NOW };
const PASSPHRASE = fakeCredential("bundle-pass", "-phrase-", "42");
const WRONG_PASSPHRASE = fakeCredential("bundle-wrong", "-phrase-", "42");
const VALUE_A = fakeCredential("sk-bundle-", "alpha-9f8e7d6c");
const VALUE_B = fakeCredential("tok-bundle-", "beta-5a5a5a5a");
let vault: string;
let other: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-bundle-"));
other = mkdtempSync(join(tmpdir(), "o2b-bundle-other-"));
for (const root of [vault, other]) mkdirSync(join(root, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(other, { recursive: true, force: true });
});
function seed(root: string): void {
setSecret(root, {
name: "alpha-key",
value: VALUE_A,
envVar: "ALPHA_KEY",
allow: ["curl *"],
agent: "tester",
now: NOW,
});
setSecret(root, {
name: "beta-key",
value: VALUE_B,
envVar: "BETA_KEY",
allow: [],
agent: "tester",
now: NOW,
});
}
describe("the credential bundle", () => {
test("export then import into a fresh vault restores names, env vars and allowlists", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const result = importSecretBundle(other, bundle, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
expect(result.imported.toSorted()).toEqual(["alpha-key", "beta-key"]);
expect(result.replaced).toEqual([]);
const restored = listSecrets(other);
expect(restored).toHaveLength(2);
expect(restored.find((s) => s.name === "alpha-key")).toMatchObject({
env_var: "ALPHA_KEY",
allow: ["curl *"],
});
expect(restored.find((s) => s.name === "beta-key")).toMatchObject({
env_var: "BETA_KEY",
allow: [],
});
expect(resolveSecretReadOnly(other, "alpha-key").value).toBe(VALUE_A);
expect(resolveSecretReadOnly(other, "beta-key").value).toBe(VALUE_B);
});
test("a wrong passphrase refuses by name and writes nothing to the target store", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
try {
importSecretBundle(other, bundle, {
passphrase: WRONG_PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the passphrase refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.passphrase);
}
expect(listSecrets(other)).toHaveLength(0);
expect(existsSync(join(secretsDir(other), "secrets.json"))).toBe(false);
});
test("import refuses an existing name without --replace; --replace overwrites exactly", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const older = fakeCredential("older", "-value-", "1");
setSecret(other, {
name: "alpha-key",
value: older,
envVar: "OLD_KEY",
allow: [],
agent: "tester",
now: NOW,
});
try {
importSecretBundle(other, bundle, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the collision refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.nameExists);
expect((err as SecretBundleError).message).toContain("alpha-key");
}
// Exactness: the refused import changed nothing.
expect(resolveSecretReadOnly(other, "alpha-key").value).toBe(older);
expect(listSecrets(other)).toHaveLength(1);
const result = importSecretBundle(other, bundle, {
passphrase: PASSPHRASE,
replace: true,
agent: "tester",
now: LATER,
});
expect(result.replaced).toEqual(["alpha-key"]);
expect(result.imported.toSorted()).toEqual(["alpha-key", "beta-key"]);
expect(resolveSecretReadOnly(other, "alpha-key").value).toBe(VALUE_A);
expect(listSecrets(other)).toHaveLength(2);
});
test("import validates allow patterns exactly as `set` refuses them", () => {
// The allow list rides in the clear, so a bundle rewritten in transit
// cannot land entries the store's own writer would refuse - and a
// non-string pattern cannot reach the exec allowlist matcher.
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX) as unknown as {
entries: Record<string, { allow: unknown[] }>;
};
for (const bad of [[""], [" "]]) {
const tampered = structuredClone(bundle);
tampered.entries["beta-key"]!.allow = bad;
try {
importSecretBundle(other, tampered, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error(`expected the allow-pattern refusal for ${JSON.stringify(bad)}`);
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.entry);
}
expect(listSecrets(other)).toHaveLength(0);
}
const typed = structuredClone(bundle);
typed.entries["beta-key"]!.allow = [42];
expect(() =>
importSecretBundle(other, typed, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
}),
).toThrow(SecretBundleError);
expect(listSecrets(other)).toHaveLength(0);
// A whitespace edit to an allow pattern no longer lands (the value is
// authenticated against the metadata exactly as exported); the store's
// trim rule stays as the post-decrypt invariant for values that DO
// verify.
const padded = structuredClone(bundle);
padded.entries["beta-key"]!.allow = [" curl * "];
try {
importSecretBundle(other, padded, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the edited-metadata refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.passphrase);
}
expect(listSecrets(other)).toHaveLength(0);
});
test("a bundle edited after export refuses before any write", () => {
// Every value is sealed under GCM associated data covering its name,
// env-var mapping, allowlist, the bundle version and the KDF block, so
// the two edits below - a widened allowlist and two ciphertexts swapped
// between entries - fail the authentication tag instead of landing.
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const widened = structuredClone(bundle) as unknown as {
entries: Record<string, { allow: string[] }>;
};
widened.entries["beta-key"]!.allow = ["curl *", "bun -e *"];
try {
importSecretBundle(other, widened, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the widened-allow refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.passphrase);
expect((err as SecretBundleError).message).toContain("edited after it was exported");
}
expect(listSecrets(other)).toHaveLength(0);
expect(existsSync(join(secretsDir(other), "secrets.json"))).toBe(false);
const swapped = structuredClone(bundle) as unknown as {
entries: Record<string, { value: { ciphertext: string; iv: string; tag: string } }>;
};
const alphaValue = swapped.entries["alpha-key"]!.value;
swapped.entries["alpha-key"]!.value = swapped.entries["beta-key"]!.value;
swapped.entries["beta-key"]!.value = alphaValue;
try {
importSecretBundle(other, swapped, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the swapped-ciphertext refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.passphrase);
}
expect(listSecrets(other)).toHaveLength(0);
expect(existsSync(join(secretsDir(other), "secrets.json"))).toBe(false);
});
test("a merged (egress-redacted) bundle re-seals under the shipped metadata and imports", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const scanTree = bundleEgressScanTree(bundle) as {
entries: Array<Record<string, unknown>>;
};
const alpha = scanTree.entries.find((e) => e["name"] === "alpha-key")!;
alpha["allow"] = ["curl * (redacted)"];
const merged = bundleFromEgressScan(bundle, scanTree);
// The merged bundle alone refuses its own import: alpha's value is
// sealed under the pre-merge metadata.
expect(() =>
importSecretBundle(other, merged, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
}),
).toThrow(SecretBundleError);
// The re-seal binds the values to the metadata that actually ships.
const resealed = resealBundleMetadata(merged, PASSPHRASE, bundle);
expect(resealed.entries["alpha-key"]!.allow).toEqual(["curl * (redacted)"]);
const result = importSecretBundle(other, resealed, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
expect(result.imported.toSorted()).toEqual(["alpha-key", "beta-key"]);
expect(listSecrets(other).find((s) => s.name === "alpha-key")?.allow).toEqual([
"curl * (redacted)",
]);
expect(resolveSecretReadOnly(other, "alpha-key").value).toBe(VALUE_A);
expect(resolveSecretReadOnly(other, "beta-key").value).toBe(VALUE_B);
});
test("the exported bytes carry none of the values or the passphrase; KDF rides inside", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const serialized = JSON.stringify(bundle);
expect(serialized).not.toContain(VALUE_A);
expect(serialized).not.toContain(VALUE_B);
expect(serialized).not.toContain(PASSPHRASE);
// Schema version and wall clock top the envelope; the KDF parameters
// travel inside it so old exports stay readable as the cost curve moves.
expect(bundle.version).toBe(SECRET_BUNDLE_SCHEMA_VERSION);
expect(typeof bundle.generated_at).toBe("string");
expect(bundle.kdf.algo).toBe("scrypt");
expect(bundle.kdf.n).toBe(2 ** 15);
// The egress scan tree is exactly the non-ciphertext inventory: names
// and mappings visible to the guard as an ARRAY (never credential-
// shaped mapping keys), the kdf salt excluded, values absent.
const scanTree = bundleEgressScanTree(bundle);
const scanned = JSON.stringify(scanTree);
expect(scanned).toContain("alpha-key");
expect(scanned).toContain("ALPHA_KEY");
expect(scanned).not.toContain("ciphertext");
expect(scanned).not.toContain("salt");
const scannedEntries = scanTree.entries as Array<{ name: string }>;
expect(scannedEntries.map((e) => e.name).toSorted()).toEqual(["alpha-key", "beta-key"]);
// The merge re-attaches the sealed values; a clean scan round-trips.
const merged = bundleFromEgressScan(bundle, scanTree);
expect(merged.entries["alpha-key"]!.value).toEqual(bundle.entries["alpha-key"]!.value);
});
test("the merge refuses when the guard rewrote an entry identifier", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
const scanTree = bundleEgressScanTree(bundle) as {
entries: Array<Record<string, unknown>>;
};
scanTree.entries[0]!["name"] = fakeCredential("rewritten", "-name-", "9");
try {
bundleFromEgressScan(bundle, scanTree);
throw new Error("expected the identifier-rewrite refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.entry);
}
});
test("audit records the export and the import with no values", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
importSecretBundle(other, bundle, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
for (const [root, action] of [
[vault, "secret_bundle_exported"],
[other, "secret_bundle_imported"],
] as const) {
const auditDir = join(root, "Brain", "log", "secret-custody");
const raw = readdirSync(auditDir)
.map((f) => readFileSync(join(auditDir, f), "utf8"))
.join("");
const lines = raw
.split("\n")
.filter((l) => l.trim().length > 0)
.map((l) => JSON.parse(l) as { action: string });
expect(lines.map((l) => l.action)).toContain(action);
expect(raw).not.toContain(VALUE_A);
expect(raw).not.toContain(PASSPHRASE);
}
});
test("an unknown bundle version or kdf algo refuses by name", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
for (const [field, mutate, code] of [
[
"version",
(b: Record<string, unknown>) => void (b["version"] = (b["version"] as number) + 1),
BUNDLE_REFUSAL_CODES.version,
],
[
"algo",
(b: Record<string, unknown>) =>
void ((b["kdf"] as Record<string, unknown>)["algo"] = "argon2id"),
BUNDLE_REFUSAL_CODES.kdfAlgo,
],
] as const) {
const tampered = JSON.parse(JSON.stringify(bundle)) as Record<string, unknown>;
mutate(tampered);
try {
importSecretBundle(other, tampered, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error(`expected the ${field} refusal`);
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(code);
}
}
expect(listSecrets(other)).toHaveLength(0);
// The AAD binding moved the schema to v2: a bundle from a build before
// it refuses by name with the re-export remedy, not with a cipher
// error a wrong passphrase would also produce.
const older = JSON.parse(JSON.stringify(bundle)) as Record<string, unknown>;
older["version"] = SECRET_BUNDLE_SCHEMA_VERSION - 1;
try {
importSecretBundle(other, older, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the version refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.version);
expect((err as SecretBundleError).message).toContain("re-export the bundle");
}
expect(listSecrets(other)).toHaveLength(0);
});
test("a crafted kdf cost block refuses by name before scrypt allocates", () => {
seed(vault);
const bundle = exportSecretBundle(vault, PASSPHRASE, CTX);
// The bundle's kdf block rides in the clear, so a rewritten one is
// the same unbounded-cost knob a hand-edited keyfile envelope is;
// the same build curve bounds it.
const absurd = JSON.parse(JSON.stringify(bundle)) as Record<string, unknown>;
(absurd["kdf"] as Record<string, unknown>)["n"] = 2 ** 31;
(absurd["kdf"] as Record<string, unknown>)["maxmem"] = 10 ** 12;
try {
importSecretBundle(other, absurd, {
passphrase: PASSPHRASE,
replace: false,
agent: "tester",
now: LATER,
});
throw new Error("expected the kdf-cost refusal");
} catch (err) {
expect(err).toBeInstanceOf(SecretBundleError);
expect((err as SecretBundleError).code).toBe(BUNDLE_REFUSAL_CODES.kdfCost);
}
expect(listSecrets(other)).toHaveLength(0);
});
});