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
17.7 KB
Raw Blame
/**
 * `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;
}