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
/**
* `o2b mcp token` (write-side-trust, Task 14).
*
* The management sub-dispatcher riding the `mcp` command: mint, rotate,
* revoke, and list the named per-agent MCP tokens. This is the store's
* operator surface - the transport reads the same store per request, so
* a rotation or revocation here lands on a running server's NEXT
* request with no restart.
*
* o2b mcp token mint --agent codex [--name mcp_token_codex]
* o2b mcp token rotate --name mcp_token_codex
* o2b mcp token revoke --name mcp_token_codex
* o2b mcp token list
*
* The material of a mint or rotation is printed exactly once with a
* shown-once notice; `list` prints metadata only, because the store
* holds only hashes and prefixes. Exit codes follow the same table
* style as the install verbs: 0 ok, 1 runtime (unknown name, refused
* mint), 2 usage (bad verb, missing flag, no vault).
*/
import { defaultConfigPath, resolveVault } from "../../core/config.ts";
import { VAULT_NOT_CONFIGURED_REASON } from "../../core/install/env.ts";
import {
isValidMcpTokenName,
listAgentTokens,
McpTokenStoreError,
mintAgentToken,
revokeAgentToken,
ROTATION_GRACE_MS,
rotateAgentToken,
} from "../../core/brain/secrets/token-store.ts";
import { CliError, parseFlags } from "../argparse.ts";
/** Every code this dispatcher can return, named once. */
export const TOKEN_EXIT = Object.freeze({
ok: 0,
runtimeError: 1,
usage: 2,
} as const);
export const MCP_TOKEN_VERBS: ReadonlyArray<string> = Object.freeze([
"mint",
"rotate",
"revoke",
"list",
]);
/**
* The sentence printed beside every piece of token material this CLI ever
* shows - `mcp token` here and `bootstrap` in `run.ts` alike. One constant
* because the custody rule is a property of the material, not of the verb
* that happens to be minting it.
*/
export const SHOWN_ONCE_NOTICE =
"Copy it now; reference it from the agent's environment or a $secret:NAME store entry. " +
"Never a harness config file.";
/**
* The identity boundary printed beside every piece of minted material,
* here and in `bootstrap` alike: the token authenticates HTTP MCP
* clients an operator configures BY HAND, while a stdio registration -
* what bootstrap writes - presents no credential and keeps its
* config-derived identity (`buildPayload` registers `o2b mcp --vault
* ...`), so minting a token changes nothing for the bootstrapped harness.
* One constant because the boundary is a property of the credential, not
* of the verb that happens to be minting it.
*/
export const HTTP_BOUNDARY_NOTICE =
"This token authenticates HTTP MCP clients you configure by hand (Authorization: Bearer or X-API-Key). " +
"A stdio server keeps its config-derived identity and presents no token - minting changes nothing for it.";
function usage(message: string): number {
process.stderr.write(`error: ${message}\n`);
return TOKEN_EXIT.usage;
}
function storeFailure(e: unknown): number {
if (e instanceof McpTokenStoreError) {
process.stderr.write(`error: ${e.message}\n`);
return TOKEN_EXIT.runtimeError;
}
throw e;
}
/** One parsed verb's flags, exactly the value shapes `parseFlags` produces. */
type TokenFlags = Map<string, string | boolean | string[] | undefined>;
/** The vault the verb acts on: `--vault`, else the canonical resolver. */
function vaultFromFlags(flags: TokenFlags): string {
const config = (flags.get("config") as string | undefined) ?? defaultConfigPath();
return (flags.get("vault") as string | undefined) ?? resolveVault(config) ?? "";
}
/**
* The verb's own flag parser: one pass over argv with the verb's whole
* schema (its flags plus the vault-addressing pair), so an unknown flag
* is a named refusal and the vault is read from the SAME parse - a
* second narrow parse would re-see the verb's flags and reject them.
*/
function parseVerbFlags(
argv: string[],
schema: Record<string, { type: "string" | "boolean" }>,
): TokenFlags {
const { flags, positional } = parseFlags(argv, {
...schema,
vault: { type: "string" },
config: { type: "string" },
});
if (positional.length > 0) {
throw new CliError(`does not accept positional arguments: ${positional.join(" ")}`);
}
return new Map(Object.entries(flags));
}
export async function handleMcpTokenCommand(argv: ReadonlyArray<string>): Promise<number> {
if (argv.length === 0) {
return usage(`o2b mcp token requires a verb: ${MCP_TOKEN_VERBS.join(", ")}`);
}
const verb = argv[0]!;
const rest = argv.slice(1);
switch (verb) {
case "mint":
return tokenMint(rest);
case "rotate":
return tokenRotate(rest);
case "revoke":
return tokenRevoke(rest);
case "list":
return tokenList(rest);
default:
return usage(
`unknown mcp token verb: ${verb}. Expected one of: ${MCP_TOKEN_VERBS.join(", ")}`,
);
}
}
function tokenMint(argv: string[]): number {
let flags: TokenFlags;
try {
flags = parseVerbFlags(argv, {
agent: { type: "string" },
name: { type: "string" },
vault: { type: "string" },
config: { type: "string" },
});
} catch (e) {
if (e instanceof CliError) return usage(e.message);
throw e;
}
const vault = vaultFromFlags(flags);
if (vault === "") return usage(`o2b mcp token mint: ${VAULT_NOT_CONFIGURED_REASON}`);
const agent = (flags.get("agent") as string | undefined)?.trim() ?? "";
if (agent === "") return usage("o2b mcp token mint requires --agent <name>");
const explicitName = (flags.get("name") as string | undefined)?.trim() ?? "";
const name = explicitName !== "" ? explicitName : deriveTokenName(agent);
if (!isValidMcpTokenName(name)) {
return usage(
`token name must be mcp_token_<slug> (lowercase [a-z0-9_]), got: ${JSON.stringify(name)}`,
);
}
let tokenMaterial: string;
let record: ReturnType<typeof mintAgentToken>["record"];
try {
({ tokenMaterial, record } = mintAgentToken(vault, name, agent, configFlag(flags)));
} catch (e) {
return storeFailure(e);
}
process.stdout.write(
`token: ${record.name} minted for agent ${JSON.stringify(record.agent)} - ` +
"shown exactly once, stored only as a hash\n" +
` ${tokenMaterial}\n` +
` ${SHOWN_ONCE_NOTICE}\n` +
` ${HTTP_BOUNDARY_NOTICE}\n`,
);
return TOKEN_EXIT.ok;
}
function tokenRotate(argv: string[]): number {
let flags: TokenFlags;
try {
flags = parseVerbFlags(argv, {
name: { type: "string" },
vault: { type: "string" },
config: { type: "string" },
});
} catch (e) {
if (e instanceof CliError) return usage(e.message);
throw e;
}
const vault = vaultFromFlags(flags);
if (vault === "") return usage(`o2b mcp token rotate: ${VAULT_NOT_CONFIGURED_REASON}`);
const name = (flags.get("name") as string | undefined)?.trim() ?? "";
if (name === "") return usage("o2b mcp token rotate requires --name <mcp_token_...>");
let tokenMaterial: string;
let record: ReturnType<typeof rotateAgentToken>["record"];
try {
({ tokenMaterial, record } = rotateAgentToken(vault, name, configFlag(flags)));
} catch (e) {
return storeFailure(e);
}
process.stdout.write(
`token: ${record.name} rotated for agent ${JSON.stringify(record.agent)} - the previous ` +
`material keeps authenticating for ${ROTATION_GRACE_MS / 60_000} minutes while you place ` +
"the new one, then stops on its own; the new material is shown exactly once, stored only " +
"as a hash\n" +
` ${tokenMaterial}\n` +
` ${SHOWN_ONCE_NOTICE}\n` +
` ${HTTP_BOUNDARY_NOTICE}\n`,
);
return TOKEN_EXIT.ok;
}
function tokenRevoke(argv: string[]): number {
let flags: TokenFlags;
try {
flags = parseVerbFlags(argv, {
name: { type: "string" },
vault: { type: "string" },
config: { type: "string" },
});
} catch (e) {
if (e instanceof CliError) return usage(e.message);
throw e;
}
const vault = vaultFromFlags(flags);
if (vault === "") return usage(`o2b mcp token revoke: ${VAULT_NOT_CONFIGURED_REASON}`);
const name = (flags.get("name") as string | undefined)?.trim() ?? "";
if (name === "") return usage("o2b mcp token revoke requires --name <mcp_token_...>");
let revoked: boolean;
try {
revoked = revokeAgentToken(vault, name, configFlag(flags));
} catch (e) {
return storeFailure(e);
}
if (!revoked) {
process.stderr.write(`error: token ${JSON.stringify(name)} not found or already revoked\n`);
return TOKEN_EXIT.runtimeError;
}
process.stdout.write(
`token: ${name} revoked; the material stops authenticating on the next request\n`,
);
return TOKEN_EXIT.ok;
}
function tokenList(argv: string[]): number {
let flags: TokenFlags;
try {
flags = parseVerbFlags(argv, {
vault: { type: "string" },
config: { type: "string" },
});
} catch (e) {
if (e instanceof CliError) return usage(e.message);
throw e;
}
const vault = vaultFromFlags(flags);
if (vault === "") return usage(`o2b mcp token list: ${VAULT_NOT_CONFIGURED_REASON}`);
const records = listAgentTokens(vault, configFlag(flags));
if (records.length === 0) {
process.stdout.write("tokens: no tokens minted\n");
return TOKEN_EXIT.ok;
}
const width = Math.max(...records.map((r) => r.name.length));
const lines = records.map((r) => {
const rotated = r.rotated_at !== undefined ? ` rotated ${r.rotated_at}` : "";
return (
` ${r.name.padEnd(width)} ${r.status.padEnd(7)} ${r.agent} ${r.token_prefix} ` +
`created ${r.created_at}${rotated}`
);
});
process.stdout.write(`tokens (${records.length})\n${lines.join("\n")}\n`);
return TOKEN_EXIT.ok;
}
/** `mcp_token_<slug>`: the agent name lowercased, non-grammar runs dashed to underscores. */
function deriveTokenName(agent: string): string {
return `mcp_token_${agent.toLowerCase().replaceAll(/[^a-z0-9_]+/g, "_")}`;
}
/** The `--config` the operator named: the machine whose token map is written. */
function configFlag(flags: TokenFlags): string | undefined {
const config = flags.get("config");
return typeof config === "string" && config.trim() !== "" ? config : undefined;
}