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
/**
* 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}`
);
}