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
13.1 KB
Raw Blame
/**
 * The named-secret resolver (trust-surface-hardening, t_e5807974).
 *
 * A `$secret:NAME` reference in a consumer's config resolves through the
 * vault's custody store ahead of the process environment. Resolution is
 * READ-ONLY: it composes `parseSecretReference` with the custody store's
 * read-only resolve export, so a config read never stamps
 * `last_used_at` and never appends an exec audit record - resolution
 * must not take the write path.
 *
 * Precedence is store first, env fallback - EXCEPT a name the store
 * holds under a locked envelope, which surfaces the named locked-store
 * error rather than silently answering from the environment (a silent
 * fallback would hide the locked state). A vault with no custody store
 * gains no state from resolution: the metadata read creates nothing.
 *
 * Resolution happens at use sites, not at config load, keeping
 * plaintext spread no wider than the exec path's one-variable
 * discipline. The probe re-reads store metadata per lookup
 * (correctness first); caching stays deferred until measured.
 */

import { existsSync } from "node:fs";

import { installNamedSecretResolver } from "./config.ts";
import {
  isSecretReferenceValue,
  parseSecretReference,
  resolveSecretReference,
  storeSecretName,
  type SecretProvider,
  type SecretReferenceStatus,
  invalidSecretReferenceBody,
} from "./secret-ref.ts";

/**
 * The `$secret:` syntax check lives in the leaf `secret-ref.ts` beside the
 * rest of the reference grammar; re-exported here so this module's
 * consumers keep one import path.
 */
export { isSecretReferenceValue } from "./secret-ref.ts";

/**
 * The custody store, joined at CALL time rather than at module load.
 *
 * The store's own import neighbourhood reaches back into `config.ts`
 * (store → audit → ledger-shards → config), and `config.ts` resolves
 * credentials through THIS module, so a static import here closed the
 * six-module cycle whose initialisation order is undefined - it aborted
 * `audit.ts` at module scope with a TDZ error whenever the shard-grammar
 * module was entered first. The lazy require is the sanctioned cure (see
 * `tests/core/architecture/import-cycles.test.ts`); the store is needed
 * only when a reference or a probe actually resolves, and `require`
 * caches the module after the first call.
 */
type CustodyStore = typeof import("./brain/secrets/store.ts");

let custodyStoreModule: CustodyStore | undefined;

function custodyStore(): CustodyStore {
  if (custodyStoreModule === undefined) {
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    custodyStoreModule = require("./brain/secrets/store.ts") as CustodyStore;
  }
  return custodyStoreModule;
}

/**
 * The device config, joined at CALL time rather than at module load - the
 * same sanctioned lazy require as the custody store above (`config.ts`
 * resolves credentials through THIS module, so a static import here would
 * close the same cycle). Needed only when the env legs of the config's
 * `$secret:` references feed the egress literal set.
 */
type ConfigModule = typeof import("./config.ts");

let configModule: ConfigModule | undefined;

function discoverDeviceConfig(): ReturnType<ConfigModule["discoverConfig"]> {
  if (configModule === undefined) {
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    configModule = require("./config.ts") as ConfigModule;
  }
  return configModule.discoverConfig();
}

/**
 * The store leg of the merged provider: one name's custody answer, or
 * undefined when the store does not hold it (the caller falls back to the
 * environment). Probing is on demand - a name the store does not hold costs
 * one metadata read and never decrypts; the store's plaintext is handed to
 * the caller exactly where the value is used. A name the store holds under
 * a locked envelope raises the named locked-store refusal, never a silent
 * env fallback.
 */
function storeValue(vault: string | null, name: string): string | undefined {
  // The custody store is the vault's; with no vault only the environment answers.
  if (vault === null) return undefined;
  const held = custodyStore()
    .listSecrets(vault)
    .some((meta) => meta.name === name);
  if (!held) return undefined;
  return custodyStore().resolveSecretReadOnly(vault, name).value;
}

/**
 * The merged provider: custody store ahead of the process environment. The
 * STORE leg normalizes the requested name the way the store normalizes names
 * at set time ({@link storeSecretName}: trim, lowercase - so
 * `$secret:BRAVE` answers store entry `brave` and `$secret:openai-key`
 * answers the dashed entry `set openai-key` wrote); the ENVIRONMENT leg
 * answers the name verbatim, case-sensitively. Probing is on demand - a
 * name the store does not hold costs one metadata read and never decrypts;
 * the store's plaintext is handed to the caller exactly where the value is
 * used.
 */
export function secretProvider(vault: string | null): SecretProvider {
  const env = process.env;
  return new Proxy(env as SecretProvider, {
    get(_target, prop) {
      if (typeof prop !== "string") return undefined;
      return storeValue(vault, storeSecretName(prop)) ?? env[prop];
    },
    has(_target, prop) {
      if (typeof prop !== "string") return Reflect.has(env, prop);
      return storeValue(vault, storeSecretName(prop)) !== undefined || Reflect.has(env, prop);
    },
  });
}

/**
 * Resolve one config value for the vault. A plain value passes through
 * untouched; a reference resolves store-first with env fallback, and a
 * reference that resolves nowhere keeps the existing
 * `SecretReferenceError` behavior.
 */
export function resolveNamedSecret(vault: string | null, value: string): string {
  if (!isSecretReferenceValue(value)) return value;
  return resolveSecretReference(value.trim(), secretProvider(vault));
}

/**
 * Probe one config key through the merged provider. A reference-shaped
 * key resolves as a reference; any other key is a store-held name ahead
 * of `env`. This is the seam the registry's env probing expands through.
 */
export function resolveMergedValue(
  vault: string,
  env: Readonly<Record<string, string | undefined>>,
  key: string,
): string | undefined {
  if (isSecretReferenceValue(key)) return resolveNamedSecret(vault, key.trim());
  return storeValue(vault, key) ?? env[key];
}

/**
 * Whether one named secret is usable by this process: the store holds the
 * name (metadata only - a locked envelope still counts, no decrypt; the
 * name is normalized for the store leg the way the store normalizes at set
 * time), or the environment carries it verbatim, case-sensitively. Backs
 * `o2b secrets status`.
 */
export function namedSecretAvailable(vault: string, name: string): boolean {
  return (
    custodyStore()
      .listSecrets(vault)
      .some((meta) => meta.name === storeSecretName(name)) || Boolean(process.env[name])
  );
}

/**
 * Metadata-only availability for a config object's references: the
 * store's name set joined with the environment, never a decrypt. The
 * same `SecretReferenceStatus` rows `listSecretReferences` reports, so
 * `o2b secrets list` keeps its output shape with the store joined in.
 */
export function listNamedSecretAvailability(
  vault: string,
  data: Readonly<Record<string, unknown>>,
): ReadonlyArray<SecretReferenceStatus> {
  const held = new Set(
    custodyStore()
      .listSecrets(vault)
      .map((meta) => meta.name),
  );
  const out: SecretReferenceStatus[] = [];
  for (const [configKey, value] of Object.entries(data)) {
    const ref = parseSecretReference(value);
    if (!ref) {
      // A reference-SHAPED value the grammar cannot spell (a spaced body,
      // say) resolves to a `SecretReferenceError` at use time and can never
      // be answered by the store or the env - report it instead of silently
      // dropping it while `secrets status` answers the same name from
      // metadata alone.
      const body = invalidSecretReferenceBody(value);
      if (body !== null) {
        out.push({ configKey, name: body, available: false, invalid: true });
      }
      continue;
    }
    out.push({
      configKey,
      name: ref.name,
      available: held.has(storeSecretName(ref.name)) || Boolean(process.env[ref.name]),
    });
  }
  out.sort((a, b) => a.configKey.localeCompare(b.configKey));
  return Object.freeze(out);
}

/**
 * The VALUES the vault's custody store can currently answer with, plus the
 * environment legs of the device config's `$secret:` references - the input
 * the egress boundaries need to scrub resolved credentials (the
 * `resolvedLiterals` option on `EgressPolicy` and the MCP error redactor's
 * fourth parameter). This is the one production join between the store and
 * the redactor plane; without it the literal passes were plumbed but never
 * fed, and a resolved credential under a quiet key name stayed as invisible
 * to the boundary as before the wave.
 *
 * The env legs: a reference the store does not hold resolves, at use time,
 * from the environment under the reference body verbatim - that value is
 * exactly as egress-relevant as a store value and was invisible here before.
 * A name the store DOES hold never falls back to the environment (store
 * first; a locked envelope refuses rather than falling back), so its env
 * entry, if any, is not a resolved credential and is excluded. The config is
 * discovered the way every default-path consumer discovers it
 * (`discoverConfig()`, honoring `OPEN_SECOND_BRAIN_CONFIG`); a boundary
 * handed an explicit config path that differs is a wiring decision this
 * docblock hands to the next change. Candidates shorter than
 * `MIN_REDACTED_LITERAL_LENGTH` are dropped downstream by
 * {@link sortedDistinctLiterals} - the over-redaction guard, with its
 * trade-off stated there.
 *
 * Wired boundaries, and only these: the MCP error redaction (both the
 * tools/call catch and the one builder every JSON-RPC error answer
 * passes through), the config-mapping status surfaces, and the
 * decision-model adapters that hold the key they are about to send. A
 * boundary that cannot know the vault (the CLI export verbs run
 * vault-scoped already but scan vault-authored content the structural
 * passes cover) must not pretend - the absent option stays byte-
 * identical there.
 *
 * Degradation is the point: a store that is absent, empty, unreadable,
 * LOCKED (the named locked refusal), or missing its keyfile contributes
 * nothing - the boundary then answers exactly as the pre-literal
 * redactor did. Redaction never blocks, never surfaces a refusal, and
 * never mints: a lost keyfile is skipped rather than regenerated, so a
 * scan leaves no custody state behind.
 */
export function resolvedSecretLiterals(vault: string): string[] {
  const store = custodyStore();
  let held: ReadonlyArray<{ readonly name: string }>;
  try {
    held = store.listSecrets(vault);
  } catch {
    // An unreadable store is not a redactable store: contribute nothing.
    return [];
  }
  const heldNames = new Set(held.map((meta) => meta.name));
  const out: string[] = [];
  if (held.length > 0 && existsSync(store.keyPath(vault))) {
    for (const meta of held) {
      try {
        out.push(store.resolveSecretReadOnly(vault, meta.name).value);
      } catch {
        // The locked envelope lands here (the named refusal), as does an
        // entry that cannot be decrypted; each contributes nothing.
      }
    }
  }
  out.push(...envReferenceLiterals(vault, heldNames));
  return out;
}

/**
 * The environment legs of the device config's `$secret:` references: for a
 * reference-shaped config value whose name the store does not hold, the
 * environment value the use-site resolution would answer with. An unreadable
 * or absent config contributes nothing - degradation, not refusal - exactly
 * like the store legs above.
 */
function envReferenceLiterals(vault: string, heldNames: ReadonlySet<string>): string[] {
  let data: Readonly<Record<string, unknown>>;
  try {
    const discovery = discoverDeviceConfig();
    if (!discovery.exists) return [];
    data = discovery.data;
  } catch {
    return [];
  }
  const out: string[] = [];
  for (const value of Object.values(data)) {
    const ref = parseSecretReference(value);
    if (!ref) continue;
    // Store first: a store-held name never resolves from the environment,
    // so the env entry under that name is not a resolved credential.
    if (heldNames.has(storeSecretName(ref.name))) continue;
    const envValue = process.env[ref.name];
    if (envValue !== undefined) out.push(envValue);
  }
  return out;
}

/**
 * Install THIS module as the adapter behind config's resolver port (see
 * {@link installNamedSecretResolver}). Config values carrying a
 * `$secret:` reference resolve through the custody store from here, and
 * the dependency points resolver -> config - the direction that keeps
 * the six-module cycle (config -> resolver -> custody store -> audit ->
 * ledger-shards -> config) cut. Every production entry (the CLI's
 * `main.ts`, the MCP server, the OpenClaw bridge) imports this module
 * statically at startup, which is what wires the port before any command
 * dispatch; a test exercising the reference branch of a config resolver
 * imports this module for the same side effect.
 */
installNamedSecretResolver({ resolveNamedSecret });