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
/**
* Transport authentication and request-scoped identity (write-side-trust,
* Task 7).
*
* The token map is the first credential source, the shared key the
* second (it keeps the process config identity), and a presented
* credential that matches neither is refused with the same generic 401
* body the shared key has always answered with - no oracle distinguishes
* a revoked token from an unknown one. With no tokens configured every
* existing posture is byte-identical: the suites that predate this one
* pass unmodified.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { startHttp, type HttpServerHandle } from "../../src/mcp/index.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";
import {
MCP_TOKENS_REQUIRED_CONFIG_KEY,
authenticateRequest,
resolveMcpTokensRequired,
type RequestIdentity,
} from "../../src/mcp/http.ts";
import type { IncomingMessage } from "node:http";
import { JSONRPC_VERSION } from "../../src/mcp/protocol.ts";
import { brainConfigPath } from "../../src/core/brain/paths.ts";
import { GATE_MODE } from "../../src/core/integrity/stamp.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";
import {
mintAgentToken,
revokeAgentToken,
rotateAgentToken,
} from "../../src/core/brain/secrets/token-store.ts";
let vault: string;
let handle: HttpServerHandle | null = null;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-http-token-"));
// These tests pin an unswitched machine: tokens minted the per-vault way
// next to a legacy tree. A vault with no `Brain/` is a store-only fresh
// install (design D14 item 1), whose writes need a device id and a store.
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(async () => {
if (handle !== null) await handle.close();
handle = null;
rmSync(vault, { recursive: true, force: true });
});
function rpc(method: string, id: number, params: Record<string, unknown> = {}) {
return { jsonrpc: JSONRPC_VERSION, id, method, params };
}
async function post(
body: unknown,
opts: { key?: string; header?: "authorization" | "x-api-key" } = {},
): Promise<Response> {
const headers: Record<string, string> = {
"content-type": "application/json",
accept: "application/json",
};
if (opts.key !== undefined) {
if (opts.header === "x-api-key") headers["x-api-key"] = opts.key;
else headers.authorization = `Bearer ${opts.key}`;
}
return fetch(handle!.url, { method: "POST", headers, body: JSON.stringify(body) });
}
async function postJson(body: unknown, opts: { key?: string } = {}): Promise<Record<string, any>> {
const res = await post(body, opts);
expect(res.status).toBe(200);
return (await res.json()) as Record<string, any>;
}
async function start(opts: Parameters<typeof startHttp>[1] = {}): Promise<void> {
handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0, ...opts });
}
/** The identity a token caller named, via a foreign-scope probe under the fail gate. */
async function resolvedIdentityInRefusal(
tokenMaterial: string,
requestedScope: string,
): Promise<string | null> {
const body = await postJson(
rpc("tools/call", 1, {
name: "brain_context_pack",
arguments: { max_tokens: 4000, agent_scope: requestedScope },
}),
{ key: tokenMaterial },
);
const message = body.error?.message as string | undefined;
if (message === undefined) return null;
const match = /resolved for the caller, "([^"]+)"/.exec(message);
return match?.[1] ?? null;
}
function setGate(mode: string): void {
mkdirSync(join(vault, "Brain"), { recursive: true });
writeFileSync(
brainConfigPath(vault),
`schema_version: 1\nintegrity:\n owner_scope_delivery: ${mode}\n`,
);
}
function makePref(slug: string, owner?: string): void {
mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
writePreference(vault, {
slug,
topic: slug,
principle: `principle for ${slug}`,
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: BRAIN_PREFERENCE_STATUS.confirmed,
evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
confirmed_at: "2026-05-02T00:00:00Z",
applied_count: 1,
violated_count: 0,
last_evidence_at: "2026-05-02T00:00:00Z",
confidence: BRAIN_CONFIDENCE.high,
confidence_value: 0.8,
...(owner !== undefined ? { owner } : {}),
});
}
/** Replace the token store's bytes with something that cannot parse. */
function corruptTokenStore(): void {
const dir = join(vault, ".open-second-brain", "secrets");
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "mcp-tokens.json"), "{not json", "utf8");
}
describe("HTTP token authentication", () => {
test("a valid token authenticates with per-caller identity", async () => {
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
// Preferences land before any gate exists, so their owners are the
// ones this fixture states rather than ones a write-time gate stamped.
makePref("shared-pref");
makePref("edge-owned", "edge-agent");
makePref("other-owned", "someone-else");
setGate(GATE_MODE.fail);
await start({});
// Own scope: answered, and isolated to what this caller may read.
const own = await postJson(
rpc("tools/call", 1, {
name: "brain_context_pack",
arguments: { max_tokens: 4000, agent_scope: "edge-agent" },
}),
{ key: tokenMaterial },
);
const payload = JSON.stringify(own.result);
expect(payload).toContain("shared-pref");
expect(payload).toContain("edge-owned");
expect(payload).not.toContain("other-owned");
});
test("a foreign scope under the fail gate is refused, naming the token's agent", async () => {
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
setGate(GATE_MODE.fail);
await start({});
const body = await postJson(
rpc("tools/call", 1, {
name: "brain_context_pack",
arguments: { max_tokens: 4000, agent_scope: "someone-else" },
}),
{ key: tokenMaterial },
);
const message = body.error?.message as string;
expect(message).toContain("foreign-owner");
expect(message).toContain("edge-agent");
expect(message).toContain("someone-else");
});
test("concurrent requests with different tokens never observe each other's identity", async () => {
const a = mintAgentToken(vault, "mcp_token_caller_a", "caller-a").tokenMaterial;
const b = mintAgentToken(vault, "mcp_token_caller_b", "caller-b").tokenMaterial;
setGate(GATE_MODE.fail);
await start({});
// Eight rounds of two in-flight requests whose refusal messages would
// name the WRONG token's agent if either request observed the other's
// identity - the failure an instance field would produce.
const rounds = await Promise.all(
Array.from({ length: 8 }, () =>
Promise.all([
resolvedIdentityInRefusal(a, "owner-x"),
resolvedIdentityInRefusal(b, "owner-y"),
]),
),
);
for (const [identityA, identityB] of rounds) {
expect(identityA).toBe("caller-a");
expect(identityB).toBe("caller-b");
}
});
test("the shared key still authenticates, carrying the process identity", async () => {
const sharedKey = fakeCredential("shared", "-master-", "77f1");
const savedAgent = process.env["VAULT_AGENT_NAME"];
process.env["VAULT_AGENT_NAME"] = "operator";
try {
setGate(GATE_MODE.fail);
await start({ apiKey: sharedKey });
const own = await postJson(
rpc("tools/call", 1, {
name: "brain_context_pack",
arguments: { max_tokens: 4000, agent_scope: "operator" },
}),
{ key: sharedKey },
);
expect(own.error).toBeUndefined();
} finally {
if (savedAgent === undefined) delete process.env["VAULT_AGENT_NAME"];
else process.env["VAULT_AGENT_NAME"] = savedAgent;
}
});
test("the token map is consulted before the shared key", async () => {
const sharedKey = fakeCredential("shared", "-master-", "77f1");
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
setGate(GATE_MODE.fail);
await start({ apiKey: sharedKey });
const identity = await resolvedIdentityInRefusal(tokenMaterial, "someone-else");
// The refusal names the TOKEN's agent, so the map answered first.
expect(identity).toBe("edge-agent");
});
test("a revoked token answers the same generic 401 as an unknown one", async () => {
const sharedKey = fakeCredential("shared", "-master-", "77f1");
const minted = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
await start({ apiKey: sharedKey });
// Revocation, not rotation: the rotation grace window does not apply
// here - a withdrawn credential dies immediately.
revokeAgentToken(vault, "mcp_token_edge");
const revoked = await post(rpc("ping", 1), { key: minted.tokenMaterial });
const unknown = await post(rpc("ping", 2), {
key: fakeCredential("osbt_", "never-minted"),
});
expect(revoked.status).toBe(401);
expect(await revoked.text()).toBe("Unauthorized\n");
expect(await unknown.text()).toBe("Unauthorized\n");
});
test("mcp_tokens_required with a non-empty map refuses credential-less and invalid calls", async () => {
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
await start({ tokensRequired: true });
const missing = await post(rpc("ping", 1));
const invalid = await post(rpc("ping", 2), { key: fakeCredential("osbt_", "garbage") });
const valid = await post(rpc("ping", 3), { key: tokenMaterial });
expect(missing.status).toBe(401);
expect(await missing.text()).toBe("Unauthorized\n");
expect(invalid.status).toBe(401);
expect(await invalid.text()).toBe("Unauthorized\n");
expect(valid.status).toBe(200);
});
test("mcp_tokens_required with an empty map does not refuse (warn only)", async () => {
await start({ tokensRequired: true });
const res = await post(rpc("ping", 1));
expect(res.status).toBe(200);
});
test("mcp_tokens_required with a corrupt map still refuses credential-less calls", async () => {
// Enforcement was REQUESTED by config; an unreadable store is not "no
// tokens, come on in" - the probe fails closed, so the anonymous
// request is refused with the same generic 401, and the loss is named
// on stderr.
mintAgentToken(vault, "mcp_token_edge", "edge-agent");
corruptTokenStore();
const warnings: string[] = [];
const original = process.stderr.write.bind(process.stderr);
process.stderr.write = ((chunk: string | Uint8Array): boolean => {
warnings.push(String(chunk));
return true;
}) as typeof process.stderr.write;
try {
await start({ tokensRequired: true });
const missing = await post(rpc("ping", 1));
expect(missing.status).toBe(401);
expect(await missing.text()).toBe("Unauthorized\n");
} finally {
process.stderr.write = original;
}
expect(warnings.join("")).toContain("the MCP token store could not be read");
});
test("a non-loopback bind accepts a token map without an api key", async () => {
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
handle = await startHttp({ vault }, { host: "0.0.0.0", port: 0 });
const keyless = await post(rpc("ping", 1));
expect(keyless.status).toBe(401);
const withToken = await post(rpc("ping", 2), { key: tokenMaterial });
expect(withToken.status).toBe(200);
});
test("a rotation takes effect on the next request with no server restart", async () => {
const first = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
await start({ tokensRequired: true });
expect((await post(rpc("ping", 1), { key: first.tokenMaterial })).status).toBe(200);
const second = rotateAgentToken(vault, "mcp_token_edge");
// Inside the rotation grace window the PREVIOUS material keeps
// authenticating beside the new one, so the caller holding it does
// not fail while the new material is being placed.
expect((await post(rpc("ping", 2), { key: first.tokenMaterial })).status).toBe(200);
expect((await post(rpc("ping", 3), { key: second.tokenMaterial })).status).toBe(200);
});
test("a token is accepted through the x-api-key header too", async () => {
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
await start({ tokensRequired: true });
const res = await post(rpc("ping", 1), { key: tokenMaterial, header: "x-api-key" });
expect(res.status).toBe(200);
});
test("a corrupt token store never widens the gate: the token fails closed, the key still answers", async () => {
const sharedKey = fakeCredential("shared", "-master-", "77f1");
const { tokenMaterial } = mintAgentToken(vault, "mcp_token_edge", "edge-agent");
corruptTokenStore();
const warnings: string[] = [];
const original = process.stderr.write.bind(process.stderr);
process.stderr.write = ((chunk: string | Uint8Array): boolean => {
warnings.push(String(chunk));
return true;
}) as typeof process.stderr.write;
try {
await start({ apiKey: sharedKey });
// The presented token can no longer be matched (the store cannot be
// read), so it fails the way any unmatched credential does: the
// generic 401, no oracle.
const presented = await post(rpc("ping", 1), { key: tokenMaterial });
expect(presented.status).toBe(401);
// The operator's master credential is not locked out with it.
const keyed = await post(rpc("ping", 2), { key: sharedKey });
expect(keyed.status).toBe(200);
} finally {
process.stderr.write = original;
}
// The loss is named, never silent: token matching is off and the
// reason is on stderr.
expect(warnings.join("")).toContain("the MCP token store could not be read");
});
test("a corrupt map never opens a key-less exposed bind: the bind refuses to start", async () => {
mintAgentToken(vault, "mcp_token_edge", "edge-agent");
corruptTokenStore();
const warnings: string[] = [];
const original = process.stderr.write.bind(process.stderr);
process.stderr.write = ((chunk: string | Uint8Array): boolean => {
warnings.push(String(chunk));
return true;
}) as typeof process.stderr.write;
try {
// A non-loopback bind requires a credential source by itself; an
// unreadable map is not "no tokens, come on in" - the bind fails
// closed at startup instead of exposing an unauthenticated endpoint.
await expect(startHttp({ vault }, { host: "0.0.0.0", port: 0 })).rejects.toThrow();
} finally {
process.stderr.write = original;
}
});
test("a map that turns unreadable after the bind never re-opens anonymous access", async () => {
// The bind-time probe passes on a healthy map; the store then corrupts
// under the running server. The exposed bind's requirement is the bind
// itself, not the map's current readability, so credential-less calls
// stay refused.
mintAgentToken(vault, "mcp_token_edge", "edge-agent");
handle = await startHttp({ vault }, { host: "0.0.0.0", port: 0 });
corruptTokenStore();
const anonymous = await post(rpc("ping", 1));
expect(anonymous.status).toBe(401);
expect(await anonymous.text()).toBe("Unauthorized\n");
});
});
/** A minimal request double: authenticateRequest reads only `headers`. */
const reqWith = (headers: Record<string, string>) => ({ headers }) as unknown as IncomingMessage;
const RESOLVED_TOKEN = fakeCredential("token-material", "-1");
const resolveToken = (presented: string) =>
presented === RESOLVED_TOKEN ? { agent: "edge-agent" } : null;
describe("authenticateRequest", () => {
test("the token map answers first, then the shared key, then null", () => {
const base = {
apiKey: fakeCredential("key-material-", "2"),
resolveToken,
};
expect(
authenticateRequest(reqWith({ authorization: `Bearer ${RESOLVED_TOKEN}` }), base),
).toEqual({
agent: "edge-agent",
via: "token",
});
expect(
authenticateRequest(
reqWith({ authorization: `Bearer ${fakeCredential("key-material-", "2")}` }),
{
...base,
sharedKeyAgent: "operator",
},
),
).toEqual({ agent: "operator", via: "shared-key" });
expect(authenticateRequest(reqWith({ authorization: "Bearer neither" }), base)).toBeNull();
expect(authenticateRequest(reqWith({}), base)).toBeNull();
// A credential matching BOTH the token map and the shared key resolves
// through the token map: the minted agent wins and the shared key never
// overrides it - the consultation order itself is pinned here.
expect(
authenticateRequest(reqWith({ authorization: `Bearer ${RESOLVED_TOKEN}` }), {
...base,
apiKey: RESOLVED_TOKEN,
sharedKeyAgent: "operator",
}),
).toEqual({ agent: "edge-agent", via: "token" });
});
test("an empty shared key never matches; x-api-key carries a token too", () => {
const base = { apiKey: "", resolveToken };
expect(authenticateRequest(reqWith({ "x-api-key": RESOLVED_TOKEN }), base)).toEqual({
agent: "edge-agent",
via: "token",
});
expect(authenticateRequest(reqWith({ "x-api-key": "" }), base)).toBeNull();
});
test("resolveToken sees exactly the presented credential", () => {
const seen: string[] = [];
authenticateRequest(reqWith({ authorization: `Bearer ${RESOLVED_TOKEN}` }), {
apiKey: null,
resolveToken: (presented) => {
seen.push(presented);
return null;
},
});
expect(seen).toEqual([RESOLVED_TOKEN]);
});
});
describe("resolveMcpTokensRequired", () => {
test("the config key and its env twin resolve, env winning", () => {
const configHome = mkdtempSync(join(tmpdir(), "o2b-http-token-cfg-"));
const configPath = join(configHome, "config.yaml");
writeFileSync(configPath, `${MCP_TOKENS_REQUIRED_CONFIG_KEY}: "true"\n`);
const savedEnv = process.env["OPEN_SECOND_BRAIN_CONFIG"];
const savedTwin = process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
try {
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
delete process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
expect(resolveMcpTokensRequired(undefined)).toBe(true);
process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"] = "false";
expect(resolveMcpTokensRequired(undefined)).toBe(false);
process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"] = "true";
expect(resolveMcpTokensRequired(undefined)).toBe(true);
} finally {
if (savedEnv === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
else process.env["OPEN_SECOND_BRAIN_CONFIG"] = savedEnv;
if (savedTwin === undefined) delete process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
else process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"] = savedTwin;
rmSync(configHome, { recursive: true, force: true });
}
});
test("default off with nothing configured", () => {
const savedEnv = process.env["OPEN_SECOND_BRAIN_CONFIG"];
const savedTwin = process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
try {
process.env["OPEN_SECOND_BRAIN_CONFIG"] = join(vault, "absent-config.yaml");
delete process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
expect(resolveMcpTokensRequired(undefined)).toBe(false);
} finally {
if (savedEnv === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
else process.env["OPEN_SECOND_BRAIN_CONFIG"] = savedEnv;
if (savedTwin === undefined) delete process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"];
else process.env["OPEN_SECOND_BRAIN_MCP_TOKENS_REQUIRED"] = savedTwin;
}
});
});
// The identity type is part of the pinned surface; a shape check keeps
// the import honest even where the tests above only build one inline.
// The compared value is deliberately outside the `via` vocabulary, so
// the check reads through `string`: a member named here would make the
// comparison look intentional to the compiler and vacuous at runtime.
const SAMPLE_IDENTITY: RequestIdentity = { agent: "edge-agent", via: "token" };
if ((SAMPLE_IDENTITY.via as string) === "never") throw new Error("unreachable");