Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

feat(tokens): read/write scopes + write provenance; fix silent git-sync failure

Ronalds Palacise34a4647cbf9
diff --git a/app/api/mcp/route.ts b/app/api/mcp/route.ts
index ed61ddf..fd5b1c9 100644
--- a/app/api/mcp/route.ts
+++ b/app/api/mcp/route.ts
@@ -1,7 +1,8 @@
import { MCP_TOKEN } from "@/lib/config";
import { harnessEnabled } from "@/lib/settings";
-import { hasAnyToken, verifyToken } from "@/lib/tokens";
+import { hasAnyToken, resolveToken, type TokenScope } from "@/lib/tokens";
import { oauthEnabled, verifyAccessToken, wwwAuthenticate } from "@/lib/oauth";
+import { withActor } from "@/lib/actor";
import { TOOLS, TOOL_MAP } from "@/lib/mcp/tools";
export const dynamic = "force-dynamic";
@@ -11,6 +12,12 @@ const PROTOCOL = "2025-06-18";
// eslint-disable-next-line @typescript-eslint/no-explicit-any
type Json = any;
+/** The authenticated caller: a name for the audit trail, and what it may do. */
+interface Caller {
+ name: string;
+ scope: TokenScope;
+}
+
function rpc(id: Json, result?: Json, error?: Json) {
const msg: Json = { jsonrpc: "2.0", id: id ?? null };
if (error) msg.error = error;
@@ -18,7 +25,7 @@ function rpc(id: Json, result?: Json, error?: Json) {
return msg;
}
-async function handleMessage(msg: Json): Promise<Json | null> {
+async function handleMessage(msg: Json, caller: Caller): Promise<Json | null> {
const method: string | undefined = msg?.method;
const id = msg?.id;
const params = msg?.params;
@@ -35,8 +42,14 @@ async function handleMessage(msg: Json): Promise<Json | null> {
case "ping":
return rpc(id, {});
case "tools/list": {
- // Hide the auto-filing harness unless it's turned on (agents file notes themselves).
- const tools = TOOLS.filter((t) => t.name !== "brain_capture" || harnessEnabled());
+ // A read-only token never sees the write tools — it cannot be tempted to call them,
+ // and the model never wastes a turn discovering it is forbidden.
+ // The auto-filing harness stays hidden unless it's turned on (agents file notes themselves).
+ const tools = TOOLS.filter((t) => {
+ if (t.name === "brain_capture" && !harnessEnabled()) return false;
+ if (t.write && caller.scope !== "write") return false;
+ return true;
+ });
return rpc(id, {
tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
});
@@ -44,8 +57,18 @@ async function handleMessage(msg: Json): Promise<Json | null> {
case "tools/call": {
const tool = TOOL_MAP.get(params?.name);
if (!tool) return rpc(id, undefined, { code: -32602, message: `unknown tool: ${params?.name}` });
+ if (tool.write && caller.scope !== "write") {
+ return rpc(id, undefined, {
+ code: -32001,
+ message: `${tool.name} mutates the vault, and this token is read-only. Ask the operator for a write token.`,
+ });
+ }
+ if (tool.name === "brain_capture" && !harnessEnabled()) {
+ return rpc(id, undefined, { code: -32601, message: "brain_capture is off — the operator has not enabled it." });
+ }
try {
- const out = await tool.handler(params?.arguments ?? {});
+ // Stamp every write this call causes with the caller's name, for the git audit trail.
+ const out = await withActor(caller.name, () => tool.handler(params?.arguments ?? {}));
const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);
return rpc(id, { content: [{ type: "text", text }] });
} catch (e) {
@@ -61,13 +84,19 @@ function jsonResponse(body: Json, status = 200) {
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
}
-/** A credential is valid if it matches the shared token, a per-teammate token, or a live OAuth access token. */
-async function authOk(token: string): Promise<boolean> {
- if (!token) return false;
- if (MCP_TOKEN !== "" && token === MCP_TOKEN) return true;
- if (verifyToken(token)) return true;
- if (oauthEnabled() && (await verifyAccessToken(token))) return true;
- return false;
+/**
+ * Resolve a credential to a caller, or null when it is not valid. A named per-teammate token
+ * carries its own scope; the shared env token and OAuth sessions are full-access, and an
+ * unauthenticated local instance (no auth configured at all) is treated as the operator.
+ */
+async function authenticate(token: string, authRequired: boolean): Promise<Caller | null> {
+ if (!authRequired) return { name: "local", scope: "write" };
+ if (!token) return null;
+ if (MCP_TOKEN !== "" && token === MCP_TOKEN) return { name: "shared-token", scope: "write" };
+ const named = resolveToken(token);
+ if (named) return { name: named.name, scope: named.scope };
+ if (oauthEnabled() && (await verifyAccessToken(token))) return { name: "oauth", scope: "write" };
+ return null;
}
/** 401 that also advertises the OAuth flow (WWW-Authenticate) so connectors can discover it. */
@@ -82,7 +111,8 @@ export async function POST(req: Request) {
// locally when nothing is set. On failure, advertise OAuth so Claude.ai can connect.
const token = (req.headers.get("authorization") || "").replace(/^Bearer\s+/i, "").trim();
const authRequired = MCP_TOKEN !== "" || hasAnyToken() || oauthEnabled();
- if (authRequired && !(await authOk(token))) return unauthorized();
+ const caller = await authenticate(token, authRequired);
+ if (!caller) return unauthorized();
let body: Json;
try {
@@ -92,10 +122,10 @@ export async function POST(req: Request) {
}
if (Array.isArray(body)) {
- const out = (await Promise.all(body.map(handleMessage))).filter(Boolean);
+ const out = (await Promise.all(body.map((m) => handleMessage(m, caller)))).filter(Boolean);
return out.length === 0 ? new Response(null, { status: 202 }) : jsonResponse(out);
}
- const res = await handleMessage(body);
+ const res = await handleMessage(body, caller);
return res ? jsonResponse(res) : new Response(null, { status: 202 });
}
diff --git a/app/api/notes/[...path]/route.ts b/app/api/notes/[...path]/route.ts
index a1ec8ad..0f99f78 100644
--- a/app/api/notes/[...path]/route.ts
+++ b/app/api/notes/[...path]/route.ts
@@ -1,9 +1,21 @@
+import { SESSION_COOKIE } from "@/lib/config";
+import { verifySessionToken } from "@/lib/auth";
+import { withActor } from "@/lib/actor";
import { getBacklinks, getNote, getOutlinks } from "@/lib/vault/store";
import { checkFrontmatter } from "@/lib/vault/validate";
import { deleteNote, writeNoteRaw } from "@/lib/vault/write";
export const dynamic = "force-dynamic";
+/** Attribute dashboard writes to the signed-in human, so the git log is not anonymous. */
+async function actorFor(req: Request): Promise<string> {
+ const cookie = req.headers.get("cookie") ?? "";
+ const raw = cookie.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${SESSION_COOKIE}=`));
+ if (!raw) return "dashboard";
+ const session = await verifySessionToken(raw.slice(SESSION_COOKIE.length + 1));
+ return session?.email ? `dashboard (${session.email})` : "dashboard";
+}
+
export async function GET(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {
const { path } = await params;
const rel = path.map(decodeURIComponent).join("/");
@@ -19,7 +31,8 @@ export async function PUT(req: Request, { params }: { params: Promise<{ path: st
if (typeof content !== "string") return Response.json({ error: "content (string) required" }, { status: 400 });
// Non-strict: a human may autosave half-typed frontmatter. Save it, but tell them it is broken —
// otherwise the note silently loses its status and tags. (Agents are refused; see lib/mcp/tools.ts.)
- const saved = await writeNoteRaw(rel, content);
+ const actor = await actorFor(req);
+ const saved = await withActor(actor, () => writeNoteRaw(rel, content));
const check = checkFrontmatter(content);
return Response.json({
ok: true,
@@ -32,9 +45,10 @@ export async function PUT(req: Request, { params }: { params: Promise<{ path: st
});
}
-export async function DELETE(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {
+export async function DELETE(req: Request, { params }: { params: Promise<{ path: string[] }> }) {
const { path } = await params;
const rel = path.map(decodeURIComponent).join("/");
- await deleteNote(rel);
+ const actor = await actorFor(req);
+ await withActor(actor, () => deleteNote(rel));
return Response.json({ ok: true });
}
diff --git a/app/api/tokens/route.ts b/app/api/tokens/route.ts
index 4b7fc2a..a1dc61a 100644
--- a/app/api/tokens/route.ts
+++ b/app/api/tokens/route.ts
@@ -7,7 +7,8 @@ export function GET() {
}
export async function POST(req: Request) {
- const { name } = await req.json().catch(() => ({}));
+ const { name, scope } = await req.json().catch(() => ({}));
// Returns the plaintext token ONCE — only its hash is stored.
- return Response.json(createToken(typeof name === "string" ? name : "token"));
+ // Scope decides whether the holder may mutate the vault; anything but "read" means full access.
+ return Response.json(createToken(typeof name === "string" ? name : "token", scope === "read" ? "read" : "write"));
}
diff --git a/lib/actor.ts b/lib/actor.ts
new file mode 100644
index 0000000..4588ac1
--- /dev/null
+++ b/lib/actor.ts
@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Who caused the write currently in flight.
+ *
+ * Agents already write to the vault autonomously, so an anonymous "edit foo.md" in the git
+ * log is not an audit trail. Every write funnels through lib/vault/write.ts, which stamps
+ * the current actor into the commit message — so the Activity page answers "who did this"
+ * without threading an `actor` argument through every tool handler.
+ *
+ * Set it at the request boundary (the MCP route, the dashboard API), read it in write.ts.
+ */
+const storage = new AsyncLocalStorage<string>();
+
+export function withActor<T>(actor: string, fn: () => T): T {
+ return storage.run(actor, fn);
+}
+
+/** The actor for the in-flight request, or "unknown" outside any request (e.g. a git pull). */
+export function currentActor(): string {
+ return storage.getStore() ?? "unknown";
+}
diff --git a/lib/git.ts b/lib/git.ts
index 2b4349e..ec1e4f7 100644
--- a/lib/git.ts
+++ b/lib/git.ts
@@ -21,6 +21,34 @@ export function gitVaultDir(): string | null {
return fs.existsSync(path.join(dir, ".git")) ? dir : null;
}
+/**
+ * The environment for a git child process.
+ *
+ * simple-git refuses to run when an editor variable is inherited from the host
+ * ("Use of GIT_EDITOR is not permitted without enabling allowUnsafeEditor"), because a
+ * hostile value would execute arbitrary code. Plenty of shells and CI images export one, and
+ * the only symptom was a console.error while the vault quietly stopped syncing — so strip
+ * them rather than re-permitting them. `-m` commits need no editor anyway.
+ *
+ * GIT_TERMINAL_PROMPT=0 stops a missing credential from hanging the push forever.
+ */
+function commitEnv(name: string, email: string): Record<string, string> {
+ const env: Record<string, string> = {};
+ for (const [k, v] of Object.entries(process.env)) {
+ if (v === undefined) continue;
+ if (k === "GIT_EDITOR" || k === "GIT_SEQUENCE_EDITOR") continue;
+ env[k] = v;
+ }
+ return {
+ ...env,
+ GIT_AUTHOR_NAME: name,
+ GIT_AUTHOR_EMAIL: email,
+ GIT_COMMITTER_NAME: name,
+ GIT_COMMITTER_EMAIL: email,
+ GIT_TERMINAL_PROMPT: "0",
+ };
+}
+
/**
* Debounced commit + pull --rebase + push of the active vault. No-op unless git-sync is on
* AND the vault is its own git repo (see gitVaultDir).
@@ -52,15 +80,7 @@ async function runSync(): Promise<void> {
return;
}
const { name, email } = gitAuthor();
- await g
- .env({
- ...process.env,
- GIT_AUTHOR_NAME: name,
- GIT_AUTHOR_EMAIL: email,
- GIT_COMMITTER_NAME: name,
- GIT_COMMITTER_EMAIL: email,
- })
- .commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);
+ await g.env(commitEnv(name, email)).commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);
try {
await g.pull(["--rebase", "--autostash"]);
} catch (e) {
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index 67d578f..ebb1a32 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -28,6 +28,8 @@ export interface Tool {
name: string;
description: string;
inputSchema: Record<string, unknown>;
+ /** True when the tool mutates the vault. Read-only tokens may not call these. */
+ write?: boolean;
handler: (args: Args) => Promise<unknown> | unknown;
}
@@ -208,6 +210,7 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_write",
+ write: true,
description:
"Create or overwrite a note. PREFER `body` (markdown, no frontmatter) + `frontmatter` (an object): the YAML is serialised for you and always parses. Hand-writing frontmatter into `content` risks invalid YAML — a note whose frontmatter fails to parse loses its status, tags and title on every read, so a note claiming `status: locked` would rank as an ordinary one. Such a write is REJECTED. Follow SCHEMA.md: kebab-case path, dated names for daily/decisions, frontmatter with title/type/tags/status. Path vault-relative (e.g. decisions/foo-2026-07-09.md).",
inputSchema: {
@@ -224,6 +227,7 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_edit",
+ write: true,
description:
"Overwrite a note. Pass `content` (full raw markdown incl. frontmatter) — read first with brain_read, then write the whole file back. Also accepts `body` (+ optional `frontmatter`) like brain_write.",
inputSchema: {
@@ -240,6 +244,7 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_append",
+ write: true,
description: "Append text to a note (creates it if missing).",
inputSchema: {
type: "object",
@@ -254,6 +259,7 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_move",
+ write: true,
description:
"Move or rename a note. This is how you retire something: when a note stops being true, move it to an archive folder (see brain_schema → conventions.ranking.archiveFolders) rather than deleting it. Archived notes are demoted in search and excluded by default, so they stop misleading agents while the reasoning trail survives. Leave a pointer in the replacement note saying what superseded what.",
inputSchema: { type: "object", properties: { from: s("current path"), to: s("new path") }, required: ["from", "to"] },
@@ -261,12 +267,14 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_create_folder",
+ write: true,
description: "Create a new folder in the vault (with a .gitkeep).",
inputSchema: { type: "object", properties: { path: s("folder path") }, required: ["path"] },
handler: async ({ path }) => ({ ok: true, path: await createFolder(String(path)) }),
},
{
name: "brain_capture",
+ write: true,
description:
"Capture a ROUGH note / brain-dump and let the vault file it automatically: it reads SCHEMA.md + the current folders, picks the right folder + filename, writes clean frontmatter, and structures the body. Use when you have unstructured input and don't want to decide the path yourself.",
inputSchema: { type: "object", properties: { text: s("the rough note / brain dump to file") }, required: ["text"] },
@@ -274,6 +282,7 @@ export const TOOLS: Tool[] = [
},
{
name: "brain_delete",
+ write: true,
description:
"Delete a note (recoverable via git history). Prefer brain_move into an archive folder — deleting destroys the reasoning trail, archiving only removes it from search. Delete when the note is wrong or duplicated, archive when it is merely no longer true.",
inputSchema: { type: "object", properties: { path: s("vault-relative path") }, required: ["path"] },
diff --git a/lib/tokens.ts b/lib/tokens.ts
index 4f3d00a..b7a0dc4 100644
--- a/lib/tokens.ts
+++ b/lib/tokens.ts
@@ -7,17 +7,31 @@ import { DATA_ROOT } from "@/lib/config";
const STATE_DIR = process.env.ENGRAM_STATE_DIR || DATA_ROOT;
const TOKENS_FILE = path.join(STATE_DIR, "tokens.json");
+/**
+ * What a token is allowed to do.
+ *
+ * `read` — search, read, list, tree, backlinks, graph, recent, schema.
+ * `write` — everything, including move and delete.
+ *
+ * This, not the Curator, is the lever that decides whether an agent can mutate the vault.
+ * A read-only token is the guarantee that a connected agent cannot change your notes.
+ */
+export type TokenScope = "read" | "write";
+
interface StoredToken {
id: string;
name: string;
hash: string;
created: string;
+ /** Absent on tokens created before scopes existed — those are grandfathered as `write`. */
+ scope?: TokenScope;
}
export interface TokenMeta {
id: string;
name: string;
created: string;
+ scope: TokenScope;
}
const hash = (t: string) => crypto.createHash("sha256").update(t).digest("hex");
@@ -39,33 +53,39 @@ function save(tokens: StoredToken[]) {
fs.writeFileSync(TOKENS_FILE, JSON.stringify(tokens, null, 2));
}
+/** Tokens minted before scopes existed keep the behaviour they had: full access. */
+const scopeOf = (t: StoredToken): TokenScope => t.scope ?? "write";
+
export function listTokens(): TokenMeta[] {
- return load().map(({ id, name, created }) => ({ id, name, created }));
+ return load().map((t) => ({ id: t.id, name: t.name, created: t.created, scope: scopeOf(t) }));
}
/** Create a token. Returns the plaintext value ONCE — only the hash is stored. */
-export function createToken(name: string): { id: string; name: string; token: string } {
+export function createToken(name: string, scope: TokenScope = "write"): { id: string; name: string; scope: TokenScope; token: string } {
const token = crypto.randomBytes(32).toString("hex");
const rec: StoredToken = {
id: crypto.randomUUID(),
name: name?.trim() || "token",
hash: hash(token),
created: new Date().toISOString(),
+ scope: scope === "read" ? "read" : "write",
};
const all = load();
all.push(rec);
save(all);
- return { id: rec.id, name: rec.name, token };
+ return { id: rec.id, name: rec.name, scope: rec.scope!, token };
}
export function revokeToken(id: string): void {
save(load().filter((t) => t.id !== id));
}
-export function verifyToken(bearer: string): boolean {
- if (!bearer) return false;
+/** Resolve a bearer token to its identity + scope, or null when unknown. */
+export function resolveToken(bearer: string): TokenMeta | null {
+ if (!bearer) return null;
const h = hash(bearer);
- return load().some((t) => t.hash === h);
+ const t = load().find((x) => x.hash === h);
+ return t ? { id: t.id, name: t.name, created: t.created, scope: scopeOf(t) } : null;
}
export function hasAnyToken(): boolean {
diff --git a/lib/vault/write.ts b/lib/vault/write.ts
index 1b9d982..138bdc6 100644
--- a/lib/vault/write.ts
+++ b/lib/vault/write.ts
@@ -5,6 +5,7 @@ import { activeVaultDir } from "@/lib/repos";
import { refreshPaths } from "./store";
import { checkFrontmatter, frontmatterErrorMessage } from "./validate";
import { requestSync } from "@/lib/git";
+import { currentActor } from "@/lib/actor";
/** Resolve a vault-relative path to an absolute path in the active vault, refusing escapes. */
function safeAbs(relPath: string): string {
@@ -19,10 +20,14 @@ export function normalizeNotePath(relPath: string): string {
return /\.md$/i.test(p) ? p : `${p}.md`;
}
-/** Re-index only what changed, then queue a git commit. `touched` are vault-relative paths. */
+/**
+ * Re-index only what changed, then queue a git commit stamped with who caused it.
+ * The actor prefix is what turns the Activity feed into an audit trail rather than a
+ * list of anonymous edits. `touched` are vault-relative paths.
+ */
function after(message: string, touched: string[]) {
refreshPaths(touched);
- requestSync(message);
+ requestSync(`${currentActor()}: ${message}`);
}
export interface WriteOpts {
@@ -95,6 +100,6 @@ export async function createFolder(relPath: string): Promise<string> {
const abs = safeAbs(p);
await fsp.mkdir(abs, { recursive: true });
await fsp.writeFile(path.join(abs, ".gitkeep"), "", "utf8");
- requestSync(`mkdir ${p}`);
+ requestSync(`${currentActor()}: mkdir ${p}`);
return p;
}