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
/**
* The named-secret resolver (trust-surface-hardening, t_e5807974 /
* Lane B1): a custody-store-backed SecretProvider with env fallback
* behind the existing `$secret:` syntax.
*
* Precedence is store first, env fallback - EXCEPT a name the store
* holds under a locked envelope, which surfaces the named locked-store
* error rather than silently answering from the environment (a silent
* fallback would hide the locked state). Resolution is read-only: no
* `last_used_at` stamp, no exec audit record, no store-file mutation -
* config reads must not take the write path. A vault with no custody
* store gains no state from resolution at all.
*
* Every credential-shaped string below is assembled at runtime via the
* fake-credentials helper.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
const IS_WINDOWS = process.platform === "win32";
import { join } from "node:path";
import { listSecrets, secretsDir, setSecret } from "../../src/core/brain/secrets/store.ts";
import { lockSecretKeyfile, unlockSecretKeyfile } from "../../src/core/brain/secrets/store.ts";
import { SecretReferenceError } from "../../src/core/secret-ref.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { redactErrorForCaller } from "../../src/mcp/error-redaction.ts";
import {
listNamedSecretAvailability,
resolveNamedSecret,
resolvedSecretLiterals,
secretProvider,
} from "../../src/core/secret-resolver.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";
const NOW = new Date("2026-06-05T10:00:00Z");
const STORE_VALUE = fakeCredential("store", "-value-", "42f1c9");
const ENV_VALUE = fakeCredential("env", "-value-", "77b3d0");
const REF = "$secret:embed_key";
let vault: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};
const ENV_KEYS = [
"embed_key",
"fallback_key",
"ENV_CASE",
"env_case",
"QUIET_ENV",
"OPEN_SECOND_BRAIN_CONFIG",
] as const;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-secret-resolver-"));
configPath = join(vault, "..", "o2b-secret-resolver-config.yaml");
mkdirSync(join(vault, "Brain"), { recursive: true });
for (const key of ENV_KEYS) {
savedEnv[key] = process.env[key];
delete process.env[key];
}
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configPath, { force: true });
for (const key of ENV_KEYS) {
if (savedEnv[key] === undefined) delete process.env[key];
else process.env[key] = savedEnv[key];
}
});
/** Point the default config discovery at a one-line config file. */
function writeDeviceConfig(body: string): void {
writeFileSync(configPath, body, "utf8");
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
}
function storeBytes(): string {
return readFileSync(join(secretsDir(vault), "secrets.json"), "utf8");
}
function custodyAuditRecords(): number {
const dir = join(vault, "Brain", "log", "secret-custody");
if (!existsSync(dir)) return 0;
return readdirSync(dir).reduce(
(n, entry) => n + readFileSync(join(dir, entry), "utf8").split("\n").filter(Boolean).length,
0,
);
}
function setStoreKey(): void {
setSecret(vault, { name: "embed_key", value: STORE_VALUE, agent: "tester", now: NOW });
}
describe("resolveNamedSecret", () => {
test("resolves a store-held reference without stamping use or emitting exec audit", () => {
setStoreKey();
const before = storeBytes();
const auditsBefore = custodyAuditRecords();
expect(resolveNamedSecret(vault, REF)).toBe(STORE_VALUE);
expect(storeBytes()).toBe(before);
expect(custodyAuditRecords()).toBe(auditsBefore);
expect(listSecrets(vault)[0]?.last_used_at).toBeNull();
});
test("falls back to the environment when the store does not hold the name", () => {
process.env["embed_key"] = ENV_VALUE;
expect(resolveNamedSecret(vault, REF)).toBe(ENV_VALUE);
});
test("a dashed store-slug reference resolves the entry `set` wrote", () => {
// Write-side trust review: the store accepts `set openai-key` while the
// old reference grammar refused `$secret:openai-key` outright - the two
// name spaces must agree.
setSecret(vault, { name: "openai-key", value: STORE_VALUE, agent: "tester", now: NOW });
expect(resolveNamedSecret(vault, "$secret:openai-key")).toBe(STORE_VALUE);
});
test("store lookup normalizes the reference body; the env fallback stays case-sensitive", () => {
setSecret(vault, { name: "brave", value: STORE_VALUE, agent: "tester", now: NOW });
// The store holds `brave`; the upper-case reference resolves through it,
// and the store shadows any same-named environment variable.
process.env["brave"] = ENV_VALUE;
expect(resolveNamedSecret(vault, "$secret:BRAVE")).toBe(STORE_VALUE);
// The environment leg keeps its case rules: an upper-case env var
// answers an upper-case reference, a lower-case env var does not.
process.env["ENV_CASE"] = ENV_VALUE;
expect(resolveNamedSecret(vault, "$secret:ENV_CASE")).toBe(ENV_VALUE);
delete process.env["ENV_CASE"];
process.env["env_case"] = ENV_VALUE;
// Windows resolves environment names case-insensitively at the OS level,
// so the lower-case variable answers the upper-case reference there; the
// case-sensitive contract is a POSIX property and is pinned only where
// the platform honours it.
if (!IS_WINDOWS) {
expect(() => resolveNamedSecret(vault, "$secret:ENV_CASE")).toThrow(SecretReferenceError);
} else {
expect(resolveNamedSecret(vault, "$secret:ENV_CASE")).toBe(ENV_VALUE);
}
});
test("a locked store surfaces the named locked error, never the env value", () => {
setStoreKey();
process.env["embed_key"] = ENV_VALUE;
lockVaultStoreForTest();
try {
expect(() => resolveNamedSecret(vault, REF)).toThrow(/locked/);
} finally {
unlockVaultStoreForTest();
}
expect(resolveNamedSecret(vault, REF)).toBe(STORE_VALUE);
});
test("malformed references keep the existing SecretReferenceError behavior", () => {
setStoreKey();
expect(() => resolveNamedSecret(vault, "$secret:has space")).toThrow(SecretReferenceError);
expect(() => resolveNamedSecret(vault, "$secret:absent_name")).toThrow(SecretReferenceError);
expect(() => resolveNamedSecret(vault, REF)).not.toThrow();
});
test("a plain value passes through untouched", () => {
const plain = fakeCredential("plain", "-inline-value");
expect(resolveNamedSecret(vault, plain)).toBe(plain);
});
});
describe("secretProvider", () => {
test("store entries answer by name and shadow the environment", () => {
setStoreKey();
process.env["embed_key"] = ENV_VALUE;
expect(secretProvider(vault)["embed_key"]).toBe(STORE_VALUE);
});
test("env names answer when the store does not hold them", () => {
process.env["embed_key"] = ENV_VALUE;
expect(secretProvider(vault)["embed_key"]).toBe(ENV_VALUE);
});
test("resolution through the provider does not mutate the store file", () => {
setStoreKey();
const before = storeBytes();
void secretProvider(vault)["embed_key"];
expect(storeBytes()).toBe(before);
});
test("an absent name reads as undefined, like any env-shaped provider", () => {
expect(secretProvider(vault)["absent_name"]).toBeUndefined();
});
test("a vault without a custody store gains no state from resolution", () => {
process.env["embed_key"] = ENV_VALUE;
expect(existsSync(secretsDir(vault))).toBe(false);
expect(resolveNamedSecret(vault, REF)).toBe(ENV_VALUE);
expect(existsSync(secretsDir(vault))).toBe(false);
});
});
describe("listNamedSecretAvailability", () => {
test("reports availability from store metadata and env without decrypting", () => {
setStoreKey();
process.env["fallback_key"] = ENV_VALUE;
const before = storeBytes();
const availability = listNamedSecretAvailability(vault, {
env_ref: "$secret:fallback_key",
missing_ref: "$secret:absent_name",
store_ref: "$secret:embed_key",
});
expect(availability).toEqual([
{ configKey: "env_ref", name: "fallback_key", available: true },
{ configKey: "missing_ref", name: "absent_name", available: false },
{ configKey: "store_ref", name: "embed_key", available: true },
]);
expect(storeBytes()).toBe(before);
expect(listSecrets(vault)[0]?.last_used_at).toBeNull();
});
test("a store-held name stays available under a locked envelope (metadata only)", () => {
setStoreKey();
lockVaultStoreForTest();
try {
const availability = listNamedSecretAvailability(vault, { ref: "$secret:embed_key" });
expect(availability).toEqual([{ configKey: "ref", name: "embed_key", available: true }]);
} finally {
unlockVaultStoreForTest();
}
});
});
describe("resolvedSecretLiterals", () => {
test("includes the env legs of the config's references so errors scrub them", () => {
// Write-side trust review: a reference the store does not hold resolves
// from the environment at use time, and that value used to be invisible
// to the egress literal set.
writeDeviceConfig(`quiet_ref: "$secret:QUIET_ENV"\n`);
process.env["QUIET_ENV"] = ENV_VALUE;
const literals = resolvedSecretLiterals(vault);
expect(literals).toContain(ENV_VALUE);
const out = redactErrorForCaller(
`upstream refused: ${ENV_VALUE}`,
vault,
TRANSPORT_REACH.remote,
literals,
);
expect(out).not.toContain(ENV_VALUE);
expect(out).toContain("***REDACTED***");
});
test("a store-held name excludes its env entry (the store never falls back)", () => {
setStoreKey();
process.env["embed_key"] = ENV_VALUE;
writeDeviceConfig(`ref: "$secret:embed_key"\n`);
// Store first: the use-site resolution can never answer this reference
// from the environment, so the env value is not a resolved credential.
expect(resolvedSecretLiterals(vault)).toEqual([STORE_VALUE]);
});
test("a 2-char stored value no longer blanks error text", () => {
// The over-redaction guard: a 1-2 char literal used to substitute every
// occurrence of those characters in the surrounding prose. The trade-off
// (short values are not scrubbed) is stated in the source.
setSecret(vault, { name: "tiny", value: "ok", agent: "tester", now: NOW });
writeDeviceConfig(`tiny_ref: "$secret:tiny"\n`);
const literals = resolvedSecretLiterals(vault);
expect(literals).toEqual(["ok"]);
// Neutral prose: no secret-shaped key name for the structural passes to
// react to, so the assertion isolates the literal mechanism.
const out = redactErrorForCaller(
"found ok and ok here",
vault,
TRANSPORT_REACH.remote,
literals,
);
expect(out).toBe("found ok and ok here");
});
});
// ----- Locked-store helpers --------------------------------------------------
//
// Lane A's lock lifecycle over the store's public surface: the first
// unlock wraps a raw keyfile under the passphrase and holds the key for
// this process; the lock op clears it, so a store-held name under a
// locked envelope answers with the named locked refusal.
const VAULT_PASSPHRASE = fakeCredential("vault-", "passphrase-9d11c2");
function lockVaultStoreForTest(): void {
unlockSecretKeyfile(vault, VAULT_PASSPHRASE, { agent: "tester", now: NOW });
lockSecretKeyfile(vault, { agent: "tester", now: NOW });
}
function unlockVaultStoreForTest(): void {
unlockSecretKeyfile(vault, VAULT_PASSPHRASE, { agent: "tester", now: NOW });
}