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
10.4 KB
Raw Blame
/**
 * Does a Syncthing folder carry the secrets directory to its peers?
 *
 * The `.gitignore` marker `crypto.ts` drops into the secrets directory
 * keeps the keyfile and the ciphertext out of a git commit. Syncthing
 * does not read `.gitignore` files: its only exclusion list is the
 * `.stignore` at the root of the synced folder (plus the files that one
 * `#include`s). A vault inside a Syncthing folder therefore ships the
 * keyfile AND the ciphertext it decrypts to every peer unless that
 * `.stignore` names the directory.
 *
 * This module only DETECTS the gap. It never edits `.stignore`: that file
 * belongs to the operator's sync setup, and a peer-shared ignore list
 * changed behind their back is a sync-topology decision this project does
 * not get to make. The finding names the exact line to add.
 *
 * The matcher is a deliberately small subset of Syncthing's pattern
 * language - `(?i)` / `(?d)` prefixes, `!` negation with first-match-wins,
 * a leading `/` anchoring to the folder root, `*`, `**`, `?`, and one level
 * of `#include` - so an unusual spelling can read as uncovered. That is the
 * safe direction for a warning: a false alarm costs one line in `.stignore`,
 * a false all-clear costs the key.
 */

import { existsSync, readFileSync, realpathSync } from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";

import { attestationKeyPaths, attestationKeysDir } from "../attestation/signing.ts";
import { secretsDir } from "./store.ts";

/** The marker Syncthing keeps at the root of every synced folder. */
const STFOLDER_MARKER = ".stfolder";
/** The folder-root ignore list, the only one Syncthing reads. */
const STIGNORE_FILE = ".stignore";

export interface SecretsSyncExposure {
  /** Root of the Syncthing folder the vault sits in. */
  readonly folderRoot: string;
  /** The `.stignore` that should cover the secrets directory (may not exist). */
  readonly stignorePath: string;
  /** The line to add to it, anchored at the folder root. */
  readonly suggestedPattern: string;
}

/**
 * The Syncthing folder root at or above `vault`, or null. Walks up
 * because a vault is often one subdirectory of a larger synced folder.
 */
function syncthingFolderRoot(vault: string): string | null {
  let dir = resolve(vault);
  for (;;) {
    if (existsSync(join(dir, STFOLDER_MARKER))) return dir;
    const parent = dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

interface IgnorePattern {
  readonly negated: boolean;
  readonly regex: RegExp;
  readonly anchored: boolean;
}

function globToRegex(glob: string, caseInsensitive: boolean): RegExp {
  let out = "";
  for (let i = 0; i < glob.length; i++) {
    const c = glob[i]!;
    if (c === "*") {
      if (glob[i + 1] === "*") {
        out += ".*";
        i++;
      } else {
        out += "[^/]*";
      }
    } else if (c === "?") {
      out += "[^/]";
    } else {
      out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
    }
  }
  return new RegExp(`^${out}$`, caseInsensitive ? "i" : "");
}

function readPatterns(file: string, root: string, depth: number): IgnorePattern[] {
  let text: string;
  try {
    text = readFileSync(file, "utf8");
  } catch {
    return [];
  }
  const out: IgnorePattern[] = [];
  for (const raw of text.split(/\r?\n/)) {
    let line = raw.trim();
    if (line === "" || line.startsWith("//")) continue;
    if (line.startsWith("#include ")) {
      if (depth === 0) {
        out.push(...readPatterns(join(root, line.slice("#include ".length).trim()), root, 1));
      }
      continue;
    }
    if (line.startsWith("#")) continue;
    let negated = false;
    let caseInsensitive = false;
    for (;;) {
      if (line.startsWith("!")) {
        negated = true;
        line = line.slice(1);
      } else if (line.startsWith("(?i)")) {
        caseInsensitive = true;
        line = line.slice(4);
      } else if (line.startsWith("(?d)")) {
        line = line.slice(4);
      } else break;
    }
    const anchored = line.startsWith("/");
    const body = line.replace(/^\/+/, "").replace(/\/+$/, "");
    if (body === "") continue;
    out.push({ negated, anchored, regex: globToRegex(body, caseInsensitive) });
  }
  return out;
}

/** Syncthing's verdict on one folder-relative path: first match wins. */
function isIgnored(patterns: ReadonlyArray<IgnorePattern>, relPath: string): boolean {
  const segments = relPath.split("/");
  for (const p of patterns) {
    // An unanchored pattern matches at any depth, so it is tried against
    // every trailing run of segments.
    const candidates = p.anchored ? [relPath] : segments.map((_, i) => segments.slice(i).join("/"));
    if (candidates.some((c) => p.regex.test(c))) return !p.negated;
  }
  return false;
}

/**
 * The secrets store's exposure, or null when there is none to report.
 */
export function secretsSyncExposure(vault: string): SecretsSyncExposure | null {
  return dirSyncExposure(vault, secretsDir(vault));
}

/**
 * The attestation signing key's exposure, under the same matcher. The
 * private half lives beside the exported public one under the derived
 * store and gets only git exclusion from keygen, so the same question
 * the secrets family answers - does a synced folder carry it to every
 * peer - is asked of it too, by the same doctor check. The suggested
 * pattern names the PRIVATE half only: the public half is the copy that
 * lets peers verify, and a pattern covering the whole directory would
 * stop it from syncing and leave every peer with no key to verify
 * against.
 */
export function attestationKeysSyncExposure(vault: string): SecretsSyncExposure | null {
  const { privatePath } = attestationKeyPaths(vault);
  // Nothing secret, nothing to report: without the private half the
  // directory holds only the exportable public one.
  if (!existsSync(privatePath)) return null;
  return dirSyncExposure(vault, attestationKeysDir(vault), privatePath);
}

/**
 * The exposure for one directory, or null when there is none to report:
 * the directory is absent, no Syncthing folder around the vault, or a
 * `.stignore` that already ignores the directory or one of its ancestors.
 * `targetPath`, when offered, is the file the suggested pattern names -
 * the private keyfile - instead of the directory itself.
 */
function dirSyncExposure(
  vault: string,
  dir: string,
  targetPath?: string,
): SecretsSyncExposure | null {
  if (!existsSync(dir)) return null;
  // Syncthing walks real directories and does not follow symbolic links,
  // so the question is asked of the real paths: a vault reached through a
  // link (`~/vault -> ~/Sync/notes/vault`) sits in the synced folder its
  // target sits in, and a secrets directory that links out of the folder
  // is not carried by it.
  const realDir = realPathOrResolved(dir);
  const realTarget = targetPath !== undefined ? realPathOrResolved(targetPath) : realDir;
  const root = syncthingFolderRoot(realPathOrResolved(vault));
  if (root === null) return null;
  const relNative = relative(root, realTarget);
  if (relNative === "" || relNative === ".." || relNative.startsWith(`..${sep}`)) return null;
  const rel = relNative.split(sep).join("/");
  const stignorePath = join(root, STIGNORE_FILE);
  const patterns = readPatterns(stignorePath, root, 0);
  // Ignoring any ancestor inside the folder ignores the directory too.
  const parts = rel.split("/");
  for (let i = 1; i <= parts.length; i++) {
    if (isIgnored(patterns, parts.slice(0, i).join("/"))) return null;
  }
  return { folderRoot: root, stignorePath, suggestedPattern: `/${rel}` };
}

/**
 * The real path of an existing `path`, or its resolved form when the real
 * path cannot be read. Falling back keeps the check running, and the
 * lexical answer is the one this module gave before it read real paths.
 */
function realPathOrResolved(path: string): string {
  try {
    return realpathSync(path);
  } catch {
    return resolve(path);
  }
}

/** One sentence naming the gap and the operator's fix. */
export function formatSecretsSyncExposure(exposure: SecretsSyncExposure): string {
  return (
    `the secrets directory sits inside a Syncthing folder (${exposure.folderRoot}) whose ` +
    `${STIGNORE_FILE} does not ignore it, so the keyfile and the ciphertext it decrypts sync ` +
    `to every peer (Syncthing does not read .gitignore). Add this line to ` +
    `${exposure.stignorePath}: ${exposure.suggestedPattern}`
  );
}

/**
 * The same gap, stated for the ATTESTATION signing key: what would sync
 * is the private half of the operator's Ed25519 keypair, so the sentence
 * names that instead of the custody store's keyfile-and-ciphertext pair.
 */
export function formatAttestationKeysSyncExposure(exposure: SecretsSyncExposure): string {
  return (
    `the attestation signing key sits inside a Syncthing folder (${exposure.folderRoot}) ` +
    `whose ${STIGNORE_FILE} does not ignore it, so the private half would sync to every ` +
    "peer (Syncthing does not read .gitignore). Add this line to " +
    `${exposure.stignorePath}: ${exposure.suggestedPattern}`
  );
}

/**
 * The attestation gap, stated for a PASSPHRASE-WRAPPED private half: what
 * would sync is the envelope, and the passphrase is the only protection
 * left against offline guessing on a peer - the same residual the custody
 * store's wrapped wording names.
 */
export function formatAttestationWrappedKeysSyncExposure(exposure: SecretsSyncExposure): string {
  return (
    `the passphrase-wrapped attestation signing key sits inside a Syncthing folder ` +
    `(${exposure.folderRoot}) whose ${STIGNORE_FILE} does not ignore it, so the envelope ` +
    "syncs to every peer and the passphrase is the only protection left against offline " +
    `guessing there. Add this line to ${exposure.stignorePath}: ${exposure.suggestedPattern}`
  );
}

/**
 * The same gap, stated for a PASSPHRASE-WRAPPED keyfile (t_e6667a56): the
 * envelope that syncs to every peer is not the raw key material, but the
 * passphrase is now the only thing between a peer and offline guessing,
 * so the warning names that residual protection instead of implying the
 * wrap removed the exposure.
 */
export function formatWrappedKeyfileExposure(exposure: SecretsSyncExposure): string {
  return (
    `the passphrase-wrapped keyfile sits inside a Syncthing folder (${exposure.folderRoot}) ` +
    `whose ${STIGNORE_FILE} does not ignore it, so the envelope syncs to every peer and the ` +
    `passphrase is the only protection left against offline guessing there. Add this line to ` +
    `${exposure.stignorePath}: ${exposure.suggestedPattern}`
  );
}