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
16.0 KB
Raw Blame
/**
 * The attestation signing kernel (delivery trust, card t_3bdb82b0).
 *
 * Ed25519 from `node:crypto` - the tree's first asymmetric crypto, kept
 * to three small pure operations here so the census-visible crypto
 * surface stays auditable: generate, sign, verify. There is no new
 * dependency.
 *
 * The key lifecycle follows the secrets family's posture exactly:
 *
 *   - Keys are OPERATOR-MANAGED. `sign` refuses by name
 *     (`attestation_key_missing`) when no key exists and never mints
 *     one: a key the operator did not create would be a false sense of
 *     attestation, the same reasoning that keeps the custody store from
 *     minting a key over surviving ciphertext.
 *   - The private half is the raw 32-byte Ed25519 seed, born 0600 in a
 *     0700 directory with `restrictToOwner` applied and the secrets
 *     sync-exclusion marker dropped beside it, under
 *     `<vault>/.open-second-brain/keys/attestation/`. Not inside
 *     `secrets/` itself - the custody store has its own lock/unlock
 *     semantics and a signing key must not gate on the store's locked
 *     state - and never under `Brain/`, which syncs across peers. Git
 *     exclusion is seeded here; file-syncer exclusion is the operator's
 *     `.stignore`, which the doctor names.
 *   - The passphrase wrap reuses the envelope module's `wrapKeyfile` /
 *     `unlockKeyfile` unchanged, so the wrapped form is byte-compatible
 *     with the custody keyfile's envelope and every refusal code it
 *     already names. The passphrase is ingested as an ENV VAR NAME
 *     (`passphraseFromEnv`), never a value in argv, and the value may be
 *     a `$secret:` reference resolved through the named-secret resolver.
 *   - Key loss means no recovery, stated like `envelope.ts` and
 *     `bundle.ts` state it: a lost key leaves every past attestation
 *     unverifiable, and rotation is keygen plus re-sign, never
 *     re-signing of old records.
 *   - Key material is never printed. Nothing here writes stdout at all;
 *     error prose is path-free where it travels into model context.
 */

import {
  createPrivateKey,
  createPublicKey,
  generateKeyPairSync,
  sign as cryptoSign,
  verify as cryptoVerify,
} from "node:crypto";
import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { join } from "node:path";

import {
  atomicCreateFileSyncExclusive,
  atomicWriteFileSync,
  FileAlreadyExistsError,
} from "../../fs-atomic.ts";
import {
  isEnvelopeBytes,
  unlockKeyfile,
  wrapKeyfile,
  heldKeyOrRefusal,
} from "../../brain/secrets/envelope.ts";
import { restrictToOwner } from "../secrets/owner-acl.ts";
import { resolveNamedSecret } from "../../secret-resolver.ts";
import { WRITE_LANE } from "../freeze-marker.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import {
  attestationSealVerifies,
  attestationSigningPayload,
  type AttestationRecord,
} from "./record.ts";
import { machineStatePath } from "../../state/machine-state.ts";
import { DERIVED_STORE_DIR } from "../path-constants.ts";

/** The stable code every missing-key refusal carries. */
export const ATTESTATION_KEY_MISSING = "attestation_key_missing";

/**
 * A signing operation met a vault with no generated attestation key.
 * The remedy is `o2b brain attest keygen` - and the refusal NEVER
 * generates one, because a key an operator did not create would attest
 * nothing they can vouch for.
 */
export class AttestationKeyMissingError extends Error {
  readonly code = ATTESTATION_KEY_MISSING;

  constructor() {
    super(
      "no attestation key exists: generate one with `o2b brain attest keygen` - " +
        "signing never creates a key, because a key the operator did not generate " +
        "would be a false sense of attestation",
    );
    this.name = "AttestationKeyMissingError";
  }
}

/** Refusal for keygen over an existing key: regenerating would orphan past attestations. */
export class AttestationKeyExistsError extends Error {
  readonly code = "attestation_key_exists";

  constructor(privatePath: string) {
    super(
      "an attestation key already exists: refusing to regenerate - every attestation " +
        "signed with the existing key would become unverifiable. Rotation is a " +
        "deliberate act: move the old key aside, then generate",
    );
    this.name = "AttestationKeyExistsError";
    void privatePath;
  }
}

/** Refusal when the passphrase source names no usable value. */
export class AttestationPassphraseError extends Error {
  readonly code = "attestation_passphrase_missing";

  constructor(source: string) {
    super(
      `passphrase source ${JSON.stringify(source)} is unset, empty, or blank; ` +
        "set the environment variable to the passphrase (or to a $secret: reference), " +
        "or pipe it via stdin on the CLI - the passphrase is never taken from argv",
    );
    this.name = "AttestationPassphraseError";
  }
}

const KEY_DIR_SEGMENTS = ["keys", "attestation"] as const;
const PRIVATE_KEY_FILE = "attestation.key";
const PUBLIC_KEY_FILE = "attestation.pub";

/**
 * The fixed PKCS#8 DER prefix of an Ed25519 private key: the ASN.1
 * wrapper around the 32-byte seed. The seed stored on disk plus this
 * prefix is a valid PKCS#8 `PrivateKeyInfo`, which `createPrivateKey`
 * reads directly.
 */
const ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");

const SYNC_EXCLUSION_CONTENT = "*\n!.gitignore\n";

/** `<vault>/.open-second-brain/keys/attestation/`. */
export function attestationKeysDir(vault: string): string {
  return machineStatePath(vault, DERIVED_STORE_DIR, ...KEY_DIR_SEGMENTS);
}

/** Both halves of the operator's attestation key, without reading either. */
export function attestationKeyPaths(vault: string): {
  readonly privatePath: string;
  readonly publicPath: string;
} {
  const dir = attestationKeysDir(vault);
  return { privatePath: join(dir, PRIVATE_KEY_FILE), publicPath: join(dir, PUBLIC_KEY_FILE) };
}

/**
 * Best-effort owner-only hardening, applied on creation AND on every
 * load (a keyfile that arrived with a copied or restored vault carries
 * whatever ACL it inherited). Idempotent per path per process, like the
 * custody store's use.
 */
function hardenKeyPaths(dir: string, privatePath: string): void {
  restrictToOwner(dir, "directory");
  restrictToOwner(privatePath, "file");
  // POSIX mirror: mode bits are set at creation only, so a keyfile that
  // arrived with a copy keeps whatever mode the copy gave it. The
  // custody store re-chmods on load; this module cannot - a re-chmod is
  // a direct write-site the census would have to carry an exclusion for,
  // and silently rewriting permissions the operator's restore set is not
  // obviously the right act anyway - so a loose mode is NAMED on stderr
  // and left for the operator to fix deliberately.
  if (process.platform !== "win32" && existsSync(privatePath)) {
    const mode = statSync(privatePath).mode & 0o777;
    if ((mode & 0o077) !== 0) {
      process.stderr.write(
        `warning: the attestation private key is readable beyond its owner ` +
          `(${mode.toString(8)}); tighten it with chmod 600 ${privatePath}\n`,
      );
    }
  }
}

/** Resolve the passphrase from an env-var NAME; `$secret:` references included. */
function ingestPassphrase(vault: string, passphraseFromEnv: string): string {
  const offered = process.env[passphraseFromEnv];
  if (offered === undefined || offered.trim().length === 0) {
    throw new AttestationPassphraseError(passphraseFromEnv);
  }
  return resolveNamedSecret(vault, offered);
}

/** Seed bytes -> signing KeyObject, via the fixed PKCS#8 wrapper. */
function seedToPrivateKey(seed: Buffer): ReturnType<typeof createPrivateKey> {
  return createPrivateKey({
    key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
    format: "der",
    type: "pkcs8",
  });
}

export interface GenerateAttestationKeypairOptions {
  /**
   * NAME of the environment variable holding the wrap passphrase (never
   * the passphrase itself, and never argv). When set, the private
   * keyfile is stored as a passphrase-wrapped envelope at the same
   * path; the value may be a `$secret:` reference.
   */
  readonly passphraseFromEnv?: string;
}

/**
 * Generate the operator's Ed25519 attestation keypair.
 *
 * The seed is written through the exclusive-create shared writer at
 * 0600 so two concurrent keygens cannot truncate each other: the loser
 * refuses with {@link AttestationKeyExistsError} rather than replacing
 * the winner. A keypair that survives in ANY half refuses too - a
 * surviving public half still verifies every past attestation, and
 * regenerating over it would orphan them - and the exclusive-create
 * race loser's own error is translated onto the same named refusal. The
 * public half is written beside the private one (safe to copy to every
 * peer), and the sync-exclusion marker keeps git from ever carrying the
 * directory.
 */
export function generateAttestationKeypair(
  vault: string,
  opts: GenerateAttestationKeypairOptions = {},
): { readonly privatePath: string; readonly publicPath: string } {
  // The passphrase is resolved BEFORE anything is created: a refused
  // wrap leaves no half-built key directory behind.
  const passphrase =
    opts.passphraseFromEnv === undefined ? null : ingestPassphrase(vault, opts.passphraseFromEnv);
  assertVaultIdentityForWrite(vault, undefined, WRITE_LANE.audit);
  const { privatePath, publicPath } = attestationKeyPaths(vault);
  if (existsSync(privatePath) || existsSync(publicPath)) {
    // Name the half that actually survives: a refusal pointing at a file
    // that does not exist sends the operator looking in the wrong place.
    throw new AttestationKeyExistsError(existsSync(privatePath) ? privatePath : publicPath);
  }
  const dir = attestationKeysDir(vault);
  // The 0700 mode takes effect on POSIX for directories this call
  // creates; `restrictToOwner` sets the equivalent ACL on Windows.
  mkdirSync(dir, { recursive: true, mode: 0o700 });
  restrictToOwner(dir, "directory");
  atomicWriteFileSync(join(dir, ".gitignore"), SYNC_EXCLUSION_CONTENT);

  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
  const pkcs8 = privateKey.export({ type: "pkcs8", format: "der" }) as Buffer;
  const seed = pkcs8.subarray(ED25519_PKCS8_PREFIX.length);
  // Exclusive create at 0600: the seed never exists at a wider mode,
  // even for an instant. It is stored as hex TEXT - the shared writers
  // encode UTF-8, and 64 hex characters survive any text round trip
  // byte-identically, which raw binary through a text writer does not.
  // A concurrent keygen that passes the pre-check above loses here, and
  // its refusal carries the same named code the pre-check gives.
  try {
    atomicCreateFileSyncExclusive(privatePath, seed.toString("hex"), { mode: 0o600 });
  } catch (err) {
    if (err instanceof FileAlreadyExistsError) throw new AttestationKeyExistsError(privatePath);
    throw err;
  }
  restrictToOwner(privatePath, "file");
  const written = Buffer.from(readFileSync(privatePath, "utf8").trim(), "hex");
  if (!seed.equals(written)) {
    throw new Error("attestation keygen: the private seed did not survive its write");
  }
  atomicWriteFileSync(publicPath, publicKey.export({ type: "spki", format: "pem" }) + "\n");

  if (passphrase !== null) {
    // Replaces the raw seed with the envelope at the SAME path, 0600,
    // round-trip verified by the envelope module before any byte lands.
    wrapKeyfile(privatePath, passphrase, seed);
  }
  return { privatePath, publicPath };
}

export interface SignAttestationRecordOptions {
  /** NAME of the environment variable holding the wrap passphrase. */
  readonly passphraseFromEnv?: string;
}

/**
 * Sign one sealed record with the vault's attestation key.
 *
 * Refuses by name with {@link ATTESTATION_KEY_MISSING} when no key
 * exists - never generates. The signature covers
 * `attestationSigningPayload(record)`: the sealed body's canonical JSON
 * without the signature field, so the signed bytes are derivable from
 * the record alone on every build.
 */
export function signAttestationRecord(
  record: AttestationRecord,
  vault: string,
  opts: SignAttestationRecordOptions = {},
): AttestationRecord {
  const { privatePath } = attestationKeyPaths(vault);
  if (!existsSync(privatePath)) throw new AttestationKeyMissingError();
  const dir = attestationKeysDir(vault);
  hardenKeyPaths(dir, privatePath);

  const seed = loadPrivateKeySeed(vault, privatePath, opts.passphraseFromEnv);
  const privateKey = seedToPrivateKey(seed);

  // A record whose seal no longer holds is not signed - signing tampered
  // evidence would launder it.
  if (!attestationSealVerifies(record)) {
    throw new Error(`refusing to sign attestation ${record.id}: its seal does not verify`);
  }

  const signature = cryptoSign(
    null,
    Buffer.from(attestationSigningPayload(record), "utf8"),
    privateKey,
  );
  return Object.freeze({ ...record, signature: signature.toString("base64") });
}

/**
 * The stored seed: raw 32 bytes, or the envelope's held/unwrapped DEK.
 * A passphrase source unlocks the envelope for this process on the way
 * (the envelope holder keeps it, exactly like the custody store).
 */
function loadPrivateKeySeed(
  vault: string,
  privatePath: string,
  passphraseFromEnv: string | undefined,
): Buffer {
  const raw = readFileSync(privatePath, "utf8");
  if (!isEnvelopeBytes(Buffer.from(raw, "utf8"))) {
    const seed = Buffer.from(raw.trim(), "hex");
    if (raw.trim().length !== 64 || seed.length !== 32) {
      throw new Error(
        `attestation keyfile is corrupt (expected a 32-byte seed as hex): ${privatePath}`,
      );
    }
    return seed;
  }
  if (passphraseFromEnv !== undefined) {
    return unlockKeyfile(privatePath, ingestPassphrase(vault, passphraseFromEnv));
  }
  // No source offered: the process holder, then the host's passphrase
  // env bridge, then the named locked refusal.
  return heldKeyOrRefusal(privatePath);
}

export interface VerifyAttestationSignatureOptions {
  /** The public half to verify against; defaults to the vault's own. */
  readonly publicPath?: string;
}

/**
 * Whether `record` carries a valid signature made by the operator's key.
 *
 * False - never a throw - for every negative: no signature, a seal that
 * no longer verifies, a missing or unreadable public half, a forged
 * signature. Verification is a report, and a boolean report cannot
 * refuse a caller that only asked.
 */
export function verifyAttestationSignature(
  record: AttestationRecord,
  vault: string,
  opts: VerifyAttestationSignatureOptions = {},
): boolean {
  if (record.signature === null) return false;
  // The seal first: a body that does not match its own digest is not
  // the body anyone signed, whatever the signature decodes against.
  if (!attestationSealVerifies(record)) return false;

  // An EXPLICIT public path is a contract: verify against exactly that
  // half, and a missing or unreadable file is false - a caller naming a
  // peer's key never means "fall back to whatever is here".
  let publicKey: ReturnType<typeof createPublicKey> | null = null;
  if (opts.publicPath !== undefined) {
    try {
      publicKey = createPublicKey(readFileSync(opts.publicPath, "utf8"));
    } catch {
      return false;
    }
  } else {
    // The default path: the vault's exported public half. Gone (or
    // unreadable) but the private seed still here, local verification
    // derives the public half rather than reporting every local record
    // invalid over a missing export file - peers verify against the
    // exported copy.
    const { publicPath, privatePath } = attestationKeyPaths(vault);
    try {
      publicKey = createPublicKey(readFileSync(publicPath, "utf8"));
    } catch {
      if (!existsSync(privatePath)) return false;
      try {
        const seed = loadPrivateKeySeed(vault, privatePath, undefined);
        publicKey = createPublicKey(seedToPrivateKey(seed));
      } catch {
        return false;
      }
    }
  }
  if (publicKey === null) return false;

  try {
    return cryptoVerify(
      null,
      Buffer.from(attestationSigningPayload(record), "utf8"),
      publicKey,
      Buffer.from(record.signature, "base64"),
    );
  } catch {
    return false;
  }
}