Skip to content

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
20.5 KB
Raw Blame
/**
 * 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,
  );
}