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 brain attest <keygen|sign|list|verify>` (delivery trust, card
* t_3bdb82b0): the operator surface over the attestation kernel.
*
* The split is the `brain_secrets` split applied to signatures: everything
* that holds or mints a key is CLI-only, because a key lifecycle is an
* operator decision and never an agent's. The MCP face
* (`brain_attestations`) is read-only list/verify; no keygen or sign
* surface exists anywhere but here.
*
* The passphrase never rides argv. It is ingested exactly the way the
* secret verb ingests a value: `--passphrase-from-env NAME` (the
* kernel-resolved route, `$secret:` references included) or stdin, with
* ONE blankness rule - a value that is empty after trim is not a
* passphrase. A wrap is optional at keygen; an operator who pipes nothing
* gets the raw 0600 seed.
*
* Exit codes (the `brain log verify` contract): 0 on success and on a
* verification where every shard is intact or merely appended, 1 on an
* operational failure, a diverged or missing shard, a store-digest
* drift no appended shard explains, or an invalid signature, 2 on
* usage errors.
*/
import {
buildAttestationRecord,
listAttestationRecordFiles,
readAttestationEntry,
writeAttestationRecord,
type AttestationEntry,
type AttestationRecord,
} from "../../../core/brain/attestation/record.ts";
import {
attestationStoreDigest,
collectAttestationManifest,
} from "../../../core/brain/attestation/digest.ts";
import {
ATTESTATION_KEY_MISSING,
AttestationKeyExistsError,
AttestationKeyMissingError,
AttestationPassphraseError,
generateAttestationKeypair,
signAttestationRecord,
} from "../../../core/brain/attestation/signing.ts";
import { verifyAttestation } from "../../../core/brain/attestation/verify.ts";
import {
ATTESTATION_STORE_DAMAGED_CODE,
ATTESTATIONS_ABSENT_CODE,
} from "../../../core/brain/diagnostics.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { brainVerbContext, fail, info, parse, writeJson, ok, okJson } from "../helpers.ts";
import { readStdinText } from "../../stdin.ts";
const ATTEST_VERBS = Object.freeze({
keygen: "keygen",
sign: "sign",
list: "list",
verify: "verify",
} as const);
/** Printed for `o2b brain attest` with no verb, and for `--help`. */
const ATTEST_USAGE =
"usage: o2b brain attest <verb> [args...]\n" +
"Verbs:\n" +
" keygen [--passphrase-from-env NAME] [--json]\n" +
" Generate the operator's Ed25519 attestation keypair under\n" +
" .open-second-brain/keys/attestation/ (private half 0600, never\n" +
" synced). The optional passphrase - an env var NAME or stdin,\n" +
" never argv - wraps the private half. Key loss means every past\n" +
" attestation stays unverifiable; there is no recovery.\n" +
" sign [--passphrase-from-env NAME] [--json]\n" +
" Measure the store (log heads, ledger inventories, index\n" +
" stamp), seal and sign one attestation record, and write it as\n" +
" one JSON file. Signing never creates a key.\n" +
" list [--json] Every attestation, newest first: id, created-at, device.\n" +
" A record that cannot be read is named on its own row.\n" +
" verify [--json] [--public-key PATH]\n" +
" Re-measure the store against the newest attestation: per-shard\n" +
" intact / appended / diverged / missing, the signature, and the\n" +
" store digest. --public-key verifies against exactly that exported\n" +
" half (a copy kept outside the vault). Reports only - nothing here\n" +
" repairs a store.\n";
/**
* The CLI-internal env bridge for a passphrase that arrived on stdin: the
* kernel's contract takes an env var NAME (so `$secret:` resolution and
* the named refusals stay in one place), so the value read from stdin is
* parked here for the duration of the one kernel call and deleted after -
* the consumed-once shape the secrets env bridge uses.
*/
const ATTEST_PASSPHRASE_STDIN_ENV = "OPEN_SECOND_BRAIN_ATTEST_PASSPHRASE_STDIN";
type IngestedPassphrase = { readonly name: string } | { readonly exitCode: number };
/**
* Ingest the passphrase the secret verb's way: `--passphrase-from-env NAME`
* or stdin, never argv. Returns the env var NAME for the kernel (its own
* for the flag route; the CLI bridge's for the stdin route), or an exit
* code when the route is broken. A blank stdin yields `null` - no
* passphrase - which keygen reads as "store the raw seed" and sign reads
* as "holder, env bridge, or the named locked refusal".
*/
async function ingestPassphrase(
op: string,
flags: Record<string, string | boolean | string[] | undefined>,
): Promise<IngestedPassphrase | null> {
const fromEnv = flags["passphrase-from-env"] as string | undefined;
if (fromEnv !== undefined) {
const value = process.env[fromEnv];
if (value === undefined || value.trim().length === 0) {
process.stderr.write(
`brain attest ${op}: env var ${fromEnv} is unset, empty, or blank; set it to a ` +
"passphrase (or a $secret: reference), or pipe the passphrase via stdin\n",
);
return { exitCode: 2 };
}
return { name: fromEnv };
}
if (process.stdin.isTTY) return null;
// A stream that cannot be read (the in-process test runner's already
// consumed body) is an EMPTY pipe, not a passphrase: same answer an
// empty pipe gives, so no second reading of "no input" exists.
let text: string;
try {
text = await readStdinText();
} catch {
return null;
}
const passphrase = text.replace(/\r?\n$/, "");
if (passphrase.trim().length === 0) return null;
process.env[ATTEST_PASSPHRASE_STDIN_ENV] = passphrase;
return { name: ATTEST_PASSPHRASE_STDIN_ENV };
}
/** Run `body` with the bridge env var cleaned up whichever way it ends. */
async function withPassphraseBridge(
ingested: IngestedPassphrase | null,
body: () => Promise<number>,
): Promise<number> {
try {
return await body();
} finally {
if (ingested !== null && "name" in ingested && ingested.name === ATTEST_PASSPHRASE_STDIN_ENV) {
delete process.env[ATTEST_PASSPHRASE_STDIN_ENV];
}
}
}
/** The named refusal every key-bearing operation maps to exit 1 through. */
function failAttestation(op: string, exc: unknown): number {
if (exc instanceof AttestationKeyMissingError) {
return fail(`${ATTESTATION_KEY_MISSING}: ${(exc as Error).message}`);
}
if (exc instanceof AttestationPassphraseError || exc instanceof AttestationKeyExistsError) {
return fail(
`${(exc as { code?: string }).code ?? "attestation_error"}: ${(exc as Error).message}`,
);
}
return fail(`brain attest ${op} failed: ${(exc as Error).message ?? exc}`);
}
export async function cmdBrainAttest(argv: ReadonlyArray<string>): Promise<number> {
if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
process.stdout.write(ATTEST_USAGE);
return argv.length === 0 ? 2 : 0;
}
const sub = argv[0]!;
const rest = argv.slice(1);
switch (sub) {
case ATTEST_VERBS.keygen:
return await cmdBrainAttestKeygen([...rest]);
case ATTEST_VERBS.sign:
return await cmdBrainAttestSign([...rest]);
case ATTEST_VERBS.list:
return await cmdBrainAttestList([...rest]);
case ATTEST_VERBS.verify:
return await cmdBrainAttestVerify([...rest]);
default:
process.stderr.write(
`unknown brain attest verb: ${sub}; supported: ${Object.values(ATTEST_VERBS).join(", ")}\n`,
);
return 2;
}
}
async function cmdBrainAttestKeygen(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
json: { type: "boolean" },
"passphrase-from-env": { type: "string" },
});
const { vault } = brainVerbContext(flags);
const ingested = await ingestPassphrase("keygen", flags);
if (ingested !== null && "exitCode" in ingested) return ingested.exitCode;
return await withPassphraseBridge(ingested, async () => {
let paths;
try {
paths = generateAttestationKeypair(
vault,
ingested === null ? {} : { passphraseFromEnv: ingested.name },
);
} catch (exc) {
return failAttestation("keygen", exc);
}
if (flags["json"]) {
okJson({ private_path: paths.privatePath, public_path: paths.publicPath });
return 0;
}
ok("attestation keypair generated (a lost key leaves every past attestation unverifiable):");
ok(` private: ${paths.privatePath}`);
ok(` public: ${paths.publicPath}`);
return 0;
});
}
async function cmdBrainAttestSign(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
json: { type: "boolean" },
"passphrase-from-env": { type: "string" },
});
const { vault } = brainVerbContext(flags);
const ingested = await ingestPassphrase("sign", flags);
if (ingested !== null && "exitCode" in ingested) return ingested.exitCode;
return await withPassphraseBridge(ingested, async () => {
let record: AttestationRecord;
try {
const manifest = collectAttestationManifest(vault);
const sealed = buildAttestationRecord(vault, manifest);
record = signAttestationRecord(
sealed,
vault,
ingested === null ? {} : { passphraseFromEnv: ingested.name },
);
const { path } = writeAttestationRecord(vault, record);
if (flags["json"]) {
okJson({
id: record.id,
created_at: record.createdAt,
device_id: record.deviceId,
store_digest: attestationStoreDigest(record.manifest),
path,
});
return 0;
}
ok(`attestation written: ${path}`);
ok(` id: ${record.id} device: ${record.deviceId}`);
return 0;
} catch (exc) {
return failAttestation("sign", exc);
}
});
}
async function cmdBrainAttestList(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
json: { type: "boolean" },
});
// Captured before any narrowing: the advisory stream needs the parsed
// flag after the point where the truthiness check above the JSON
// branch has narrowed the record access away from `true`.
const asJson = flags["json"] === true;
const { vault } = brainVerbContext(flags);
// Name order is time order (the id is the compact UTC instant), so
// newest-first is a reverse of the oldest-first listing. A record that
// cannot be read is damage to name, never an empty answer: it gets
// its own row with the reader's reason while the readable records
// still list - one corrupted file hides nothing but itself.
let entries: ReadonlyArray<AttestationEntry>;
try {
entries = listAttestationRecordFiles(vault).toReversed();
} catch (exc) {
// A directory that cannot be listed (permissions, a file where the
// directory should be) is an operational failure with a name, never
// a crash and never an empty inventory.
return failAttestation("list", exc);
}
const records: { path: string; record: AttestationRecord }[] = [];
const unreadable: { path: string; reason: string }[] = [];
for (const entry of entries) {
try {
records.push({ path: entry.path, record: readAttestationEntry(entry) });
} catch (exc) {
unreadable.push({ path: entry.path, reason: (exc as Error).message ?? String(exc) });
}
}
if (flags["json"]) {
writeJson({
attestations: records.map(({ path, record }) => ({
id: record.id,
created_at: record.createdAt,
device_id: record.deviceId,
store_digest: record.storeDigest,
path,
})),
...(unreadable.length > 0 ? { unreadable } : {}),
});
return 0;
}
if (records.length === 0 && unreadable.length === 0) {
info("no attestation on record");
// The forward pointer rides the advisory rail (no-dead-ends phase 3):
// the empty-list state is a registered signal, not a hand-written
// invocation literal inside an info() argument.
emitNextStep(ATTESTATIONS_ABSENT_CODE, {
command: "brain",
argv,
jsonRequested: asJson,
});
return 0;
}
info(`attestations: ${records.length} (newest first)`);
for (const { path, record } of records) {
info(` ${record.id} created: ${record.createdAt} device: ${record.deviceId}`);
info(` ${path}`);
}
for (const { path, reason } of unreadable) {
info(` UNREADABLE ${path}`);
info(` ${reason}`);
}
return 0;
}
/**
* Re-measure the store against the newest attestation and print the
* per-shard verdict.
*
* Exit 1 when anything reports damage - a diverged or missing shard, a
* store-digest drift no appended shard explains (an inventoried ledger,
* the vault identity, the index), or a signature that does not verify.
* `appended` shards and the digest drift they explain are a store that
* MOVED, not a store that broke, and they exit 0: a cron entry keyed on
* this verb reports breakage, not progress.
*
* `--public-key <path>` verifies against exactly that exported half -
* a copy kept outside the vault defeats a key that was replaced in
* place - and a missing or unreadable file reads as an invalid
* signature, never as a fall back to the private seed.
*/
async function cmdBrainAttestVerify(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
json: { type: "boolean" },
"public-key": { type: "string" },
});
// Captured before any narrowing, same as the list verb above.
const asJson = flags["json"] === true;
const { vault } = brainVerbContext(flags);
const publicKeyPath = flags["public-key"] as string | undefined;
let record: AttestationRecord;
try {
const files = listAttestationRecordFiles(vault);
const newest = files.at(-1);
if (newest === undefined) {
if (flags["json"]) {
writeJson({ verified: null });
return 0;
}
info("no attestation on record: nothing to verify");
return 0;
}
record = readAttestationEntry(newest);
} catch (exc) {
return failAttestation("verify", exc);
}
const result =
publicKeyPath !== undefined
? verifyAttestation(vault, record, { publicPath: publicKeyPath })
: verifyAttestation(vault, record);
const damaged = result.shards.some(
(shard) => shard.state === "diverged" || shard.state === "missing",
);
// The kernel classifies the manifest diff surface by surface: normal
// growth - appended attested shards, shards created after signing, and
// the append-only ledgers' own grammar-valid new shards - is
// explained, everything else (ledger damage, a strict directory, the
// vault identity, the search index) is drift no shard names, and a
// manifest that could not be recomputed at all is its own fact. One
// rule here and in the doctor, computed once in the kernel.
const unexplainedDrift = result.unexplainedDrift;
const healthy = !damaged && !unexplainedDrift && result.storeMeasured && result.signatureValid;
if (flags["json"]) {
// The K4 AttestationVerification shape, field for field.
writeJson(result);
return healthy ? 0 : 1;
}
info(
`attestation ${result.recordId} (${result.createdAt}): ` +
`${result.shards.length} ${result.shards.length === 1 ? "shard" : "shards"}, ` +
`signature ${result.signatureValid ? "valid" : "INVALID"}`,
);
for (const shard of result.shards) info(` ${shard.shardId}: ${shard.state}`);
// The digest verdict prints on every MEASURED run, healthy or not:
// growth and match are both facts an operator or a cron log reads. An
// unmeasured run prints no digest reading at all - it has none to
// give.
if (result.storeMeasured) {
info(
result.storeDigestMatches
? "store digest matches the attested one"
: "store digest differs from the attested one" +
(unexplainedDrift ? "" : " (growth since signing explains it)"),
);
}
if (healthy) return 0;
// An unmeasured manifest is reported as its own fact - and only when
// nothing else is wrong: the shard walk and the signature check ran,
// so real damage names itself first and the unmeasured prose must not
// cover it. No advisory rail here either: the state is not store
// damage, and the prose names the remedy (re-run) directly.
if (!result.storeMeasured && !damaged && result.signatureValid && !unexplainedDrift) {
info(
"the store could not be measured this run - a log lock was held or a surface could " +
"not be read - so whether it still matches the attestation is unknown; re-run",
);
return 1;
}
if (damaged) {
info(
"the store diverged from the point this attestation vouches for: the shards named " +
"above were edited, removed, or rewritten after it was signed. Nothing here repairs " +
"a store; whether the log chain itself still links up is the adjacent question.",
);
} else if (unexplainedDrift) {
info(
"the store no longer matches the attested manifest beyond the log shards: an " +
"inventoried ledger directory, the vault identity or the search index changed since " +
"signing, and no shard above explains it. Nothing here repairs a store.",
);
} else {
info(
"the attestation's signature does not verify against the key this run checked: the " +
"record may not be the one this vault's operator signed, or the exported public " +
"half is missing or was replaced. Nothing here repairs a store.",
);
}
// The forward pointer rides the advisory rail (no-dead-ends phase 3):
// the diverged-store state is a registered signal whose exit is the
// log chain's verifier, not a hand-written invocation literal inside
// an info() argument.
emitNextStep(ATTESTATION_STORE_DAMAGED_CODE, {
command: "brain",
argv,
jsonRequested: asJson,
});
return 1;
}