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
/**
* Named per-agent MCP token store (write-side-trust, Task 3).
*
* One operator-minted credential per agent, so an HTTP caller's identity
* comes from what it PRESENTS rather than from process config. The
* store is hash-at-rest by design decision (t_85059d6d), not custody
* ciphertext: `sha256(tokenMaterial)` sits beside a non-secret prefix in
* `<vault>/.open-second-brain/secrets/mcp-tokens.json` (0600, owner ACL
* on Windows through the custody targets beside `secrets.json`), and a
* plaintext-equivalent token never exists after the mint answer returns
* it exactly once. Verification therefore never needs the passphrase
* envelope - locking the custody store must not be an authentication
* outage, which is the property the ciphertext design could not give.
*
* Every mint, rotation and revocation appends a no-values record to the
* secret-custody audit, the same trail `secrets.json` writes. Names are
* `mcp_token_<slug>` - underscores only - so a `$secret:NAME` reference
* (whose grammar admits no dashes) can address them. Reads go through an
* mtime cache, so a rotation or revocation performed by another process
* (the CLI) takes effect on this one's next resolve without a restart.
*
* On a switched machine (design D14 item 15) the token map lives in
* device config (`mcp-tokens.json` beside the machine config,
* `device-token-path.ts`), which the MCP transport reads first: minting,
* rotation and revocation write there (starting from the per-vault map
* when no device copy exists yet), under a device-local lock; the
* custody audit goes where the audit writer routes it (the store), so
* nothing is written into the vault.
*/
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
import { renameWithRetry } from "../../fs-atomic.ts";
import { appendAuditRecord } from "../../reliability/audit.ts";
import { SECRET_CUSTODY_AUDIT_DIR } from "../audit-dirs.ts";
import { brainDirsForWrite } from "../paths.ts";
import { isoSecond } from "../time.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { restrictToOwner } from "./owner-acl.ts";
import { withLocalLock } from "../../store/local-lock.ts";
import { isStoreOnly } from "../../store/store-only.ts";
import { deviceTokenStorePath } from "./device-token-path.ts";
import { tokenStorePath, withSecretsLock } from "./store.ts";
/**
* Whether the token map of `vault` lives in device config on the machine
* `configPath` names (the process's default config when absent). Fails
* closed: a mode check that throws propagates, so a revocation is never
* written to the per-vault map while the server reads the device copy.
*/
function tokensInDeviceConfig(vault: string, configPath: string | undefined): boolean {
return isStoreOnly({ vault, ...(configPath !== undefined ? { configPath } : {}) });
}
/** The token file the writers write: the device-config copy once switched. */
function writePath(vault: string, configPath: string | undefined): string {
return tokensInDeviceConfig(vault, configPath)
? deviceTokenStorePath(configPath)
: tokenStorePath(vault);
}
/**
* The token file a reader of `vault` reads, or `null` when there is none:
* the device-config copy once switched (the per-vault map until a writer
* first writes the copy), the per-vault map before; with no vault, the
* device-config copy when it exists. The one rule the writers here and
* the MCP transport (`mcp/token-source.ts`) share, so they always name
* the same file for one machine config.
*/
export function tokenMapReadPath(vault: string | null, configPath?: string | null): string | null {
const config = configPath ?? undefined;
const device = deviceTokenStorePath(config);
if (vault === null) return existsSync(device) ? device : null;
if (!tokensInDeviceConfig(vault, config)) return tokenStorePath(vault);
return existsSync(device) ? device : tokenStorePath(vault);
}
function readPath(vault: string, configPath: string | undefined): string {
return tokenMapReadPath(vault, configPath)!;
}
/** The write guard and lock of a token write, by where the map lives. */
function withTokenWrite<T>(vault: string, configPath: string | undefined, fn: () => T): T {
if (!tokensInDeviceConfig(vault, configPath)) {
assertVaultIdentityForWrite(vault);
return withSecretsLock(vault, fn);
}
const path = deviceTokenStorePath(configPath);
mkdirSync(dirname(path), { recursive: true });
return withLocalLock(path, fn);
}
export const MCP_TOKENS_SCHEMA_VERSION = 1;
/** How much of the material the non-secret display prefix keeps. */
export const TOKEN_PREFIX_LENGTH = 12;
/**
* How long the PREVIOUS material keeps authenticating after a rotation.
*
* Rotation replaces the stored hash in place, and the caller that holds
* the old material learns the new one only when its operator places it -
* an environment variable, a `$secret:` entry, a hand-edited HTTP client.
* Killing the old hash at the instant of rotation turned every placement
* window into an authentication outage on the caller's side, with the
* new material printed and nowhere safe to put it yet. The hash a
* rotation replaced therefore stays resolvable for this long after
* `rotated_at`, then stops resolving on its own - no revoke needed, and
* a second rotation moves the window to the newest replaced hash.
* Revocation itself stays immediate: the window is a rotation courtesy
* for placing new material, never a reprieve for a withdrawn credential.
*/
export const ROTATION_GRACE_MS = 10 * 60 * 1000;
/** The material prefix: short, recognisable in a config, not a secret. */
const MATERIAL_PREFIX = "osbt_";
/**
* `mcp_token_<slug>` - underscores only, lowercase, so the name is a
* legal `$secret:NAME` body (no dashes) and a legal env-var tail.
*/
const TOKEN_NAME_RE = /^mcp_token_[a-z0-9_]+$/;
export type McpTokenStatus = "active" | "revoked";
/** The stored view of one token. No member ever carries the material. */
export interface McpTokenRecord {
name: string;
agent: string;
status: McpTokenStatus;
/** sha256(tokenMaterial), hex - the at-rest form, verified constant-time. */
token_hash: string;
/** A non-secret cut of the material front, for listings. */
token_prefix: string;
created_at: string;
rotated_at?: string;
/**
* The hash a rotation replaced, kept resolvable beside the current one
* for {@link ROTATION_GRACE_MS} past `rotated_at`. Optional so the file
* format stays additive and version-tolerant: a store written before
* the field existed reads unchanged, and an older build reading a store
* that carries it simply ignores the unknown member. Never a secret -
* the same sha256 at-rest form as `token_hash`.
*/
rotated_from_hash?: string;
}
interface TokenStoreFile {
readonly version: number;
readonly tokens: Record<string, McpTokenRecord>;
}
export class McpTokenStoreError extends Error {
constructor(message: string) {
super(message);
this.name = "McpTokenStoreError";
}
}
const EMPTY_STORE: TokenStoreFile = Object.freeze({
version: MCP_TOKENS_SCHEMA_VERSION,
tokens: Object.freeze({}),
});
/** The name rule mint/rotate/revoke enforce. */
export function isValidMcpTokenName(name: string): boolean {
return TOKEN_NAME_RE.test(name);
}
// ----- Writers ---------------------------------------------------------------
/**
* Mint one named token for `agent`. The material rides the RETURN VALUE
* exactly once - print it, or lose it - and only the hash is persisted.
* An existing name (active or revoked) refuses with a message naming
* rotate: a second mint over a live name would silently orphan a
* credential some agent still holds.
*/
export function mintAgentToken(
vault: string,
name: string,
agent: string,
configPath?: string,
): { tokenMaterial: string; record: McpTokenRecord } {
const cleanName = validatedName(name);
const cleanAgent = validatedAgent(agent);
const tokenMaterial = mintMaterial();
const record: McpTokenRecord = {
name: cleanName,
agent: cleanAgent,
status: "active",
token_hash: hashOf(tokenMaterial),
token_prefix: tokenMaterial.slice(0, TOKEN_PREFIX_LENGTH),
created_at: isoSecond(),
};
withTokenWrite(vault, configPath, () => {
const file = readTokenStore(vault, configPath);
if (file.tokens[cleanName] !== undefined) {
throw new McpTokenStoreError(
`token ${JSON.stringify(cleanName)} already exists; use rotate to replace its material`,
);
}
writeTokenStore(vault, configPath, {
version: MCP_TOKENS_SCHEMA_VERSION,
tokens: { ...file.tokens, [cleanName]: record },
});
});
auditToken(vault, "mcp_token_minted", cleanName, { agent: cleanAgent });
return { tokenMaterial, record };
}
/**
* Re-mint the material under an existing name: new hash, new prefix,
* `rotated_at` stamped, `created_at` kept. The PREVIOUS hash stays
* resolvable beside the new one for {@link ROTATION_GRACE_MS} (recorded
* as `rotated_from_hash`), so the caller still holding the old material
* authenticates while the new one is being placed and dies when the
* window closes - the next resolve picks all of this up with no server
* restart (the mtime cache re-reads). A revoked record refuses -
* revocation is terminal; mint a new name to start over.
*/
export function rotateAgentToken(
vault: string,
name: string,
configPath?: string,
): { tokenMaterial: string; record: McpTokenRecord } {
const cleanName = validatedName(name);
const tokenMaterial = mintMaterial();
let agent = "";
withTokenWrite(vault, configPath, () => {
const file = readTokenStore(vault, configPath);
const existing = file.tokens[cleanName];
if (existing === undefined) {
throw new McpTokenStoreError(`unknown token: ${JSON.stringify(cleanName)}`);
}
if (existing.status === "revoked") {
throw new McpTokenStoreError(
`token ${JSON.stringify(cleanName)} is revoked; mint a new name instead of rotating it`,
);
}
agent = existing.agent;
writeTokenStore(vault, configPath, {
version: MCP_TOKENS_SCHEMA_VERSION,
tokens: {
...file.tokens,
[cleanName]: {
...existing,
token_hash: hashOf(tokenMaterial),
token_prefix: tokenMaterial.slice(0, TOKEN_PREFIX_LENGTH),
rotated_at: isoSecond(),
rotated_from_hash: existing.token_hash,
},
},
});
});
auditToken(vault, "mcp_token_rotated", cleanName, { agent, replaced: true });
return {
tokenMaterial,
record: readTokenStore(vault, configPath).tokens[cleanName]!,
};
}
/** Revoke one token: the record stays (history), the material stops resolving. */
export function revokeAgentToken(vault: string, name: string, configPath?: string): boolean {
const cleanName = validatedName(name);
let revoked = false;
let agent = "";
withTokenWrite(vault, configPath, () => {
const file = readTokenStore(vault, configPath);
const existing = file.tokens[cleanName];
if (existing === undefined || existing.status === "revoked") return;
agent = existing.agent;
writeTokenStore(vault, configPath, {
version: MCP_TOKENS_SCHEMA_VERSION,
tokens: { ...file.tokens, [cleanName]: { ...existing, status: "revoked" } },
});
revoked = true;
});
if (revoked) auditToken(vault, "mcp_token_revoked", cleanName, { agent });
return revoked;
}
// ----- Readers ---------------------------------------------------------------
/** Every record, sorted by name. Metadata only - never the material. */
export function listAgentTokens(vault: string, configPath?: string): McpTokenRecord[] {
return Object.values(readTokenStore(vault, configPath).tokens).toSorted((a, b) =>
a.name.localeCompare(b.name),
);
}
/**
* Whether any token is minted at all - the non-empty-map half of the
* transport's `mcp_tokens_required` enforcement and of the non-loopback
* bind rule. Read behind the same mtime cache as
* {@link resolveAgentForToken}, so minting the first token tightens a
* running server without a restart.
*/
export function hasAnyAgentToken(vault: string, configPath?: string): boolean {
return hasAnyAgentTokenAt(readPath(vault, configPath));
}
/**
* {@link hasAnyAgentToken} for the token file at `path`: the per-vault
* file, or the device-config copy a server with no vault reads (design
* D14 item 15, `src/mcp/token-source.ts`).
*/
export function hasAnyAgentTokenAt(path: string): boolean {
return activeHashIndex(path).size > 0;
}
/**
* Resolve a presented credential to its agent, or null when nothing
* active matches. The presented material is hashed and compared against
* every stored hash with timingSafeEqual (fixed 32-byte digests), so no
* byte of a wrong answer leaks through early exit. The store is read
* behind an mtime cache, which is what lets a CLI-side rotation take
* effect here on the next request without a restart; a hash carried over
* from a rotation resolves beside the current one until its
* {@link ROTATION_GRACE_MS} window closes and is skipped once it has.
*/
export function resolveAgentForToken(
vault: string,
presented: string,
configPath?: string,
): { agent: string; name: string } | null {
return resolveAgentForTokenAt(readPath(vault, configPath), presented);
}
/** {@link resolveAgentForToken} for the token file at `path` (see {@link hasAnyAgentTokenAt}). */
export function resolveAgentForTokenAt(
path: string,
presented: string,
): { agent: string; name: string } | null {
if (typeof presented !== "string" || presented.length === 0) return null;
const index = activeHashIndex(path);
const digest = hashOf(presented);
const now = nowMs();
for (const [storedHash, entry] of index) {
// A grace-window entry past its window answers exactly like an
// unknown hash - the material is dead, not erroring.
if (entry.graceUntil !== undefined && now >= entry.graceUntil) continue;
if (timingSafeEqual(Buffer.from(storedHash, "hex"), Buffer.from(digest, "hex"))) {
return { agent: entry.agent, name: entry.name };
}
}
return null;
}
// ----- Clock seam ------------------------------------------------------------
/**
* Milliseconds since the epoch, read once per resolve. A module-level
* seam rather than a threaded argument because the readers are the
* transport's per-request path; tests walk the grace window by
* substituting the clock and restore it with `null`.
*/
let nowMs: () => number = () => Date.now();
/** Test seam: replace the store clock (pass `null` to restore the real one). */
export function setTokenStoreClock(read: (() => number) | null): void {
nowMs = read ?? (() => Date.now());
}
// ----- Store file ------------------------------------------------------------
function validatedName(name: string): string {
const trimmed = name.trim();
if (!TOKEN_NAME_RE.test(trimmed)) {
throw new McpTokenStoreError(
`token name must be mcp_token_<slug> (lowercase [a-z0-9_]): ${JSON.stringify(name)}`,
);
}
return trimmed;
}
function validatedAgent(agent: string): string {
const trimmed = agent.trim();
if (trimmed.length === 0) throw new McpTokenStoreError("token agent must not be empty");
return trimmed;
}
function mintMaterial(): string {
return `${MATERIAL_PREFIX}${randomBytes(32).toString("base64url")}`;
}
function hashOf(material: string): string {
return createHash("sha256").update(material).digest("hex");
}
function readTokenStore(vault: string, configPath: string | undefined): TokenStoreFile {
return readTokenStoreAt(readPath(vault, configPath));
}
function readTokenStoreAt(path: string): TokenStoreFile {
if (!existsSync(path)) return EMPTY_STORE;
// Same custody posture as `secrets.json`: a store that arrived by copy
// keeps whatever ACL it came with, and the read re-applies owner-only.
if (process.platform === "win32") restrictToOwner(path, "file");
const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
if (
parsed === null ||
typeof parsed !== "object" ||
(parsed as { version?: unknown }).version !== MCP_TOKENS_SCHEMA_VERSION
) {
throw new McpTokenStoreError(`MCP token store is corrupt or from a newer version: ${path}`);
}
const tokens = (parsed as { tokens?: unknown }).tokens;
if (tokens === null || typeof tokens !== "object" || Array.isArray(tokens)) {
throw new McpTokenStoreError(`MCP token store is corrupt: ${path}`);
}
const records: Record<string, McpTokenRecord> = {};
for (const [key, value] of Object.entries(tokens as Record<string, unknown>)) {
const record = value as Partial<McpTokenRecord> | null;
if (
record === null ||
typeof record !== "object" ||
typeof record.name !== "string" ||
typeof record.agent !== "string" ||
(record.status !== "active" && record.status !== "revoked") ||
typeof record.token_hash !== "string" ||
!/^[0-9a-f]{64}$/.test(record.token_hash) ||
(record.rotated_from_hash !== undefined &&
!/^[0-9a-f]{64}$/.test(record.rotated_from_hash)) ||
(record.rotated_at !== undefined &&
(typeof record.rotated_at !== "string" || Number.isNaN(Date.parse(record.rotated_at))))
) {
throw new McpTokenStoreError(
`MCP token store entry ${JSON.stringify(key)} is corrupt: ${path}`,
);
}
records[key] = record as McpTokenRecord;
}
return { version: MCP_TOKENS_SCHEMA_VERSION, tokens: records };
}
function writeTokenStore(
vault: string,
configPath: string | undefined,
file: TokenStoreFile,
): void {
const path = writePath(vault, configPath);
const tmp = `${path}.tmp`;
writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
renameWithRetry(tmp, path);
if (process.platform === "win32") restrictToOwner(path, "file");
// The writer is the one reader whose cache must not survive its own
// write: dropping the entry makes the next resolve re-stat, so an
// in-process rotation takes effect even where the filesystem's mtime
// granularity would have shown the old entry as fresh.
cacheByPath.delete(path);
}
// ----- mtime cache -----------------------------------------------------------
interface CacheEntry {
readonly mtimeMs: number;
readonly size: number;
readonly index: ReadonlyMap<string, HashIndexEntry>;
}
/** One resolvable hash: the live credential, or a rotation's grace entry. */
interface HashIndexEntry {
readonly agent: string;
readonly name: string;
/** Epoch ms when a grace-window entry dies; absent for the current hash. */
readonly graceUntil?: number;
}
/** The active-token hash index per store path, refreshed when the file changes. */
const cacheByPath = new Map<string, CacheEntry>();
const EMPTY_INDEX: ReadonlyMap<string, HashIndexEntry> = new Map();
function activeHashIndex(path: string): ReadonlyMap<string, HashIndexEntry> {
if (!existsSync(path)) {
cacheByPath.delete(path);
return EMPTY_INDEX;
}
const stats = statSync(path);
const cached = cacheByPath.get(path);
if (cached !== undefined && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
return cached.index;
}
const index = new Map<string, HashIndexEntry>();
for (const record of Object.values(readTokenStoreAt(path).tokens)) {
if (record.status !== "active") continue;
const entry: HashIndexEntry = { agent: record.agent, name: record.name };
index.set(record.token_hash, entry);
// The rotation grace: the hash this record replaced resolves beside
// the current one until its window closes. A second rotation
// overwrites the carried hash, so only the PREVIOUS material is ever
// kept; skipping a self-equal value keeps a corrupt record from
// demoting the live hash to a windowed one.
if (
record.rotated_from_hash !== undefined &&
record.rotated_from_hash !== record.token_hash &&
record.rotated_at !== undefined
) {
const rotatedAt = Date.parse(record.rotated_at);
if (Number.isFinite(rotatedAt)) {
index.set(record.rotated_from_hash, {
...entry,
graceUntil: rotatedAt + ROTATION_GRACE_MS,
});
}
}
}
cacheByPath.set(path, { mtimeMs: stats.mtimeMs, size: stats.size, index });
return index;
}
// ----- Audit -----------------------------------------------------------------
function auditToken(
vault: string,
action: "mcp_token_minted" | "mcp_token_rotated" | "mcp_token_revoked",
name: string,
details: Record<string, unknown>,
): void {
appendAuditRecord(
join(brainDirsForWrite(vault).log, SECRET_CUSTODY_AUDIT_DIR),
{
timestamp: new Date().toISOString(),
actor: "cli",
action,
target: name,
ok: true,
details,
},
vault,
);
}