@knotpad/app 0.1.4 → 0.1.6

package/lib/mcp-auth.ts

@@ -0,0 +1,65 @@
+import { SignJWT, jwtVerify } from "jose";
+import { prisma } from "@/lib/prisma";
+
+// Throttle lastUsed updates to reduce DB row contention (heartbeat calls ~120/min)
+const THROTTLE_MS = 60_000;
+const lastUsedCache = new Map<string, number>();
+
+const MCP_SECRET = new TextEncoder().encode(
+  process.env.MCP_SECRET ?? "dev-mcp-secret-change-in-production"
+);
+
+export type McpTokenPayload = {
+  userId: string;
+  workspaceId: string;
+  tokenId: string;
+};
+
+export async function signMcpToken(payload: McpTokenPayload): Promise<string> {
+  return new SignJWT({ ...payload })
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuedAt()
+    .setExpirationTime("1y")
+    .sign(MCP_SECRET);
+}
+
+export async function verifyMcpToken(
+  token: string
+): Promise<(McpTokenPayload & { alias: string | null }) | null> {
+  try {
+    const { payload } = await jwtVerify(token, MCP_SECRET);
+    const { userId, workspaceId, tokenId } = payload as McpTokenPayload;
+
+    // Check DB: not revoked, correct IDs
+    const record = await prisma.mcpToken.findUnique({ where: { id: tokenId } });
+    if (
+      !record ||
+      record.revokedAt ||
+      record.userId !== userId ||
+      record.workspaceId !== workspaceId
+    ) {
+      return null;
+    }
+
+    // Touch lastUsed (throttled to reduce DB row contention)
+    const now = Date.now();
+    const lastUpdate = lastUsedCache.get(tokenId) ?? 0;
+    if (now - lastUpdate > THROTTLE_MS) {
+      lastUsedCache.set(tokenId, now);
+      // Fire-and-forget: don't await so it never blocks auth
+      prisma.mcpToken.update({
+        where: { id: tokenId },
+        data: { lastUsed: new Date() },
+      }).catch(() => {});
+    }
+
+    return { userId, workspaceId, tokenId, alias: record.alias };
+  } catch {
+    return null;
+  }
+}
+
+export function extractBearerToken(authHeader: string | null): string | null {
+  if (!authHeader?.startsWith("Bearer ")) return null;
+  return authHeader.slice(7);
+}

package/lib/mcp-contract.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { SERVER_INSTRUCTIONS, TOOLS } from "@/lib/mcp-contract";
+
+describe("MCP contract", () => {
+  it("documents markdown equivalents for editor shortcuts", () => {
+    expect(SERVER_INSTRUCTIONS).toContain("/todo");
+    expect(SERVER_INSTRUCTIONS).toContain("[[Note Title]]");
+    expect(SERVER_INSTRUCTIONS).toContain("((Task Title))");
+    expect(SERVER_INSTRUCTIONS).toContain("!high");
+  });
+
+  it("teaches create_note how to write agent-friendly markdown", () => {
+    const createNote = TOOLS.find((tool) => tool.name === "create_note");
+
+    expect(createNote?.description).toContain("editor shortcuts");
+    expect(JSON.stringify(createNote?.inputSchema)).toContain("- [ ]");
+  });
+
+  it("teaches append_to_note how to append task-aware markdown", () => {
+    const appendToNote = TOOLS.find((tool) => tool.name === "append_to_note");
+
+    expect(appendToNote?.description).toContain("append markdown");
+    expect(JSON.stringify(appendToNote?.inputSchema)).toContain("!high");
+  });
+});

package/lib/mcp-contract.ts

@@ -0,0 +1,210 @@
+type McpToolSchema = {
+  type: "object";
+  properties: Record<string, unknown>;
+  required: string[];
+};
+
+export type McpTool = {
+  name: string;
+  description: string;
+  inputSchema: McpToolSchema;
+};
+
+export const TOOLS: McpTool[] = [
+  {
+    name: "get_notes",
+    description:
+      "List all notes in the workspace. Returns note IDs, titles, and task counts. " +
+      "Use this first to discover what work is tracked. Note IDs are needed for get_note and append_to_note.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_tasks",
+    description:
+      "List unclaimed agent tasks (assigned to @agent, status OPEN, not yet claimed). " +
+      "Returns task IDs, titles, source notes, and age. " +
+      "Use this to find work items you can pick up. Always claim a task before starting work on it.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_task_detail",
+    description:
+      "Get full details of a specific task including its audit log history. " +
+      "Use this to understand a task's context, past status changes, and who interacted with it.",
+    inputSchema: {
+      type: "object",
+      properties: { taskId: { type: "string", description: "The task ID (from get_tasks or get_notes)" } },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "get_linked_files",
+    description:
+      "Get file path references linked to a task (e.g. source files the task relates to). " +
+      "Use this to know which files to look at when working on a task.",
+    inputSchema: {
+      type: "object",
+      properties: { taskId: { type: "string", description: "The task ID" } },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "claim_tasks",
+    description:
+      "Claim one or more agent tasks to reserve them for yourself. " +
+      "You MUST claim a task before working on it — this prevents other agents from picking it up. " +
+      "After claiming, send periodic heartbeats and update the status as you make progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: { type: "array", items: { type: "string" }, description: "Task IDs to claim (from get_tasks)" },
+      },
+      required: ["ids"],
+    },
+  },
+  {
+    name: "release_task",
+    description:
+      "Release a task you previously claimed back to the open queue. " +
+      "Use this if you cannot complete the task, it's blocked, or it's no longer relevant. " +
+      "Provide a reason so the workspace owner understands why it was released. " +
+      "This notifies the workspace owner.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The task ID to release" },
+        reason: { type: "string", description: "Why you are releasing it (optional but recommended)" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "update_task",
+    description:
+      "Update the status of a task you have claimed. Status flow: in_progress → review → done. " +
+      "Use 'in_progress' when you start working, 'review' when work is complete and awaiting approval, " +
+      "'done' when fully finished (this also auto-checks the task off in the source note). " +
+      "Each update resets the heartbeat timer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The task ID" },
+        status: {
+          type: "string",
+          enum: ["in_progress", "review", "done"],
+          description: "New status: in_progress (working), review (awaiting approval), done (completed)",
+        },
+      },
+      required: ["id", "status"],
+    },
+  },
+  {
+    name: "heartbeat",
+    description:
+      "Send a heartbeat to signal you are still actively working on a claimed task. " +
+      "Send heartbeats regularly (e.g. every few minutes) while working on long tasks " +
+      "so the system knows the task hasn't been abandoned.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "The task ID" } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "create_note",
+    description:
+      "Create a new note in the workspace with markdown content. Use markdown, not literal editor shortcuts: " +
+      "/todo becomes '- [ ] Task title', + note becomes '[[Note Title]]', + task becomes '((Task Title))', " +
+      "+ mention becomes '@agent' or '@human(name)', and + priority becomes '!high' or another !priority tag. " +
+      "Checkbox task lines automatically create tasks and parse priority and ISO date metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Note title (e.g. 'Sprint 24 Tasks')" },
+        content: {
+          type: "string",
+          description:
+            "Markdown content using the parser's real syntax. Example task: '- [ ] Ship MCP docs @agent !high " +
+            "2026-06-14..2026-06-20 <app/mcp/route.tsx>'. Use '- [x]' for completed tasks, '[[Note Title]]' " +
+            "for note links, '((Task Title))' for task references, and @human(name) for human-assigned tasks.",
+        },
+      },
+      required: ["title"],
+    },
+  },
+  {
+    name: "get_note",
+    description:
+      "Get a note's full decrypted markdown content along with all its tasks. " +
+      "Use this to read the complete context of a task or to see all work tracked in a note.",
+    inputSchema: {
+      type: "object",
+      properties: { noteId: { type: "string", description: "The note ID (from get_notes)" } },
+      required: ["noteId"],
+    },
+  },
+  {
+    name: "append_to_note",
+    description:
+      "Append markdown content to an existing note. Use append markdown with the same note-writing syntax as create_note: " +
+      "checkbox tasks, note links, task references, mentions, !priority tags, and ISO dates are all supported. " +
+      "New task lines automatically create tasks without overwriting existing content. Cannot be used on locked notes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        noteId: { type: "string", description: "The note ID (from get_notes)" },
+        content: {
+          type: "string",
+          description:
+            "Markdown to append, such as '- [ ] Review release notes @agent !high 2026-06-14 <docs/release.md>' " +
+            "or 'Linked note [[Release Plan]] with task ref ((Review release notes))'.",
+        },
+      },
+      required: ["noteId", "content"],
+    },
+  },
+];
+
+export const SERVER_INSTRUCTIONS = [
+  "You are connected to Knotpad, a task and note management workspace for dev teams.",
+  "",
+  "## Core Concepts",
+  "- **Notes** contain markdown with embedded task checkboxes.",
+  "- **Tasks** are parsed from notes and can be assigned to @agent (AI) or @human.",
+  "- Agent tasks must be **claimed** before working on them to avoid conflicts.",
+  "- Tasks have a lifecycle: OPEN → CLAIMED → IN_PROGRESS → REVIEW → DONE.",
+  "",
+  "## Recommended Agent Workflow",
+  "1. Call `get_notes` to see all notes and identify work areas.",
+  "2. Call `get_tasks` to see unclaimed agent tasks available to you.",
+  "3. Call `get_task_detail` and `get_linked_files` to understand a task's context and related files.",
+  "4. Call `claim_tasks` to reserve the tasks you want to work on.",
+  "5. Call `update_task` with status 'in_progress' when you start.",
+  "6. Send `heartbeat` periodically while working on long tasks.",
+  "7. When work is done, call `update_task` with status 'review' or 'done'.",
+  "8. Use `create_note` or `append_to_note` to document your work or create new task plans.",
+  "",
+  "## Writing Notes Correctly",
+  "- Prefer valid markdown content over UI-specific wording like 'press /todo'.",
+  "- `/todo` in the editor becomes `- [ ] Task title` in note content.",
+  "- `/bullet` in the editor becomes `- item` in note content.",
+  "- `+ note` becomes `[[Note Title]]`.",
+  "- `+ task` becomes `((Task Title))` for referencing an existing task.",
+  "- `+ mention` becomes `@agent` or `@human(name)`.",
+  "- `+ priority` becomes `!critical`, `!high`, `!medium`, or `!low`.",
+  "- Supported date syntax is `YYYY-MM-DD` or `YYYY-MM-DD..YYYY-MM-DD`.",
+  "",
+  "## Task Syntax in Notes",
+  "- Agent task: `- [ ] Fix login bug @agent <src/auth/login.ts> !high 2026-06-14`",
+  "- Completed task: `- [x] Ship MCP docs @agent !high 2026-06-14..2026-06-20 <app/mcp/route.tsx>`",
+  "- Human task: `- [ ] Review design @human(alice)`",
+  "- Note link: `[[Sprint Plan]]`",
+  "- Task reference: `((Fix login bug))` anywhere in note text.",
+  "",
+  "## Important Rules",
+  "- Always claim a task before starting work on it.",
+  "- Send heartbeats every few minutes for long-running tasks.",
+  "- Release tasks you cannot complete, with a reason.",
+  "- Only update status on tasks you have claimed.",
+  "- When marking a task 'done', the source note checkbox is automatically checked.",
+].join("\n");

package/lib/mcp-handler.ts

@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from "next/server";
+import { verifyMcpToken, extractBearerToken, McpTokenPayload } from "@/lib/mcp-auth";
+import { rateLimit, getClientIp } from "@/lib/rate-limit";
+
+export type McpContext = McpTokenPayload & { alias: string | null };
+
+// 120 requests per minute per IP — generous for agent polling, tight enough to block abuse
+const MCP_RATE_LIMIT_MAX = 120;
+const MCP_RATE_LIMIT_WINDOW_MS = 60_000;
+
+export async function withMcpAuth(
+  req: NextRequest,
+  handler: (ctx: McpContext) => Promise<NextResponse>
+): Promise<NextResponse> {
+  const ip = getClientIp(req);
+  const rl = rateLimit(`mcp:${ip}`, MCP_RATE_LIMIT_MAX, MCP_RATE_LIMIT_WINDOW_MS);
+  if (rl.limited) {
+    return NextResponse.json(
+      { error: "Too many requests" },
+      { status: 429, headers: { "Retry-After": String(rl.retryAfter) } }
+    );
+  }
+
+  const token = extractBearerToken(req.headers.get("authorization"));
+  if (!token) return NextResponse.json({ error: "Missing token" }, { status: 401 });
+
+  const ctx = await verifyMcpToken(token);
+  if (!ctx) return NextResponse.json({ error: "Invalid or revoked token" }, { status: 401 });
+
+  return handler(ctx);
+}

package/lib/mcp-url.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { getMcpUrl } from "@/lib/mcp-url";
+
+describe("getMcpUrl", () => {
+  it("prefers the explicit MCP URL", () => {
+    expect(getMcpUrl("https://app.example.com", "https://mcp.example.com")).toBe("https://mcp.example.com");
+  });
+
+  it("derives the MCP URL from the app URL when no explicit value is set", () => {
+    expect(getMcpUrl("http://localhost:3000", undefined)).toBe("http://localhost:3000/mcp");
+  });
+});

package/lib/mcp-url.ts

@@ -0,0 +1,7 @@
+export function getMcpUrl(appUrl: string, explicitMcpUrl?: string): string {
+  if (explicitMcpUrl) {
+    return explicitMcpUrl;
+  }
+
+  return `${appUrl.replace(/\/$/, "")}/mcp`;
+}

package/lib/mentions.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { resolveAssignee, normalizeHandle } from "@/lib/mentions";
+
+// Minimal fake tx exposing only what resolveAssignee touches.
+function fakeTx(members: Array<{ userId: string; user: { name: string | null; email: string | null } }>) {
+  return { workspaceMember: { findMany: async () => members } } as never;
+}
+
+const members = [
+  { userId: "u1", user: { name: "John Doe", email: "john@acme.com" } },
+  { userId: "u2", user: { name: null, email: "alice@acme.com" } },
+];
+
+describe("resolveAssignee", () => {
+  it("matches a name handle even though the editor strips spaces", async () => {
+    // editor builds "@johndoe" from "John Doe"
+    const r = await resolveAssignee(fakeTx(members), "ws", "@johndoe");
+    expect(r).toEqual({ assigneeId: "u1", assigneeType: "HUMAN" });
+  });
+
+  it("matches a bare email local-part", async () => {
+    const r = await resolveAssignee(fakeTx(members), "ws", "@alice");
+    expect(r.assigneeId).toBe("u2");
+  });
+
+  it("does not ambiguously prefix-match emails", async () => {
+    // "@al" must NOT resolve to alice@ (old startsWith bug)
+    const r = await resolveAssignee(fakeTx(members), "ws", "@al");
+    expect(r.assigneeId).toBeNull();
+  });
+
+  it("treats @agent as an agent, not a human", async () => {
+    const r = await resolveAssignee(fakeTx(members), "ws", "@agent");
+    expect(r).toEqual({ assigneeId: null, assigneeType: "AGENT" });
+  });
+
+  it("returns no assignee for a null handle", async () => {
+    const r = await resolveAssignee(fakeTx(members), "ws", null);
+    expect(r).toEqual({ assigneeId: null, assigneeType: "HUMAN" });
+  });
+
+  it("normalizeHandle strips @, case, and whitespace", () => {
+    expect(normalizeHandle("@John Doe")).toBe("johndoe");
+  });
+});

package/lib/mentions.ts

@@ -0,0 +1,73 @@
+/**
+ * Mention handle resolution — shared by every note→task sync path so the
+ * matching rules can't drift between call sites.
+ *
+ * The editor builds handles from a member's name (preferred) or email:
+ *   @${(name ?? email).toLowerCase().replace(/\s+/g, "")}
+ * so resolution must normalise both sides identically. We also accept a bare
+ * email local-part (e.g. "@alice" for alice@acme.com) since people type that.
+ */
+
+import { prisma } from "@/lib/prisma";
+import { isAgentHandle } from "@/lib/task-parser";
+
+type Tx = Parameters<Parameters<typeof prisma.$transaction>[0]>[0];
+
+export type ResolvedAssignee = {
+  assigneeId: string | null;
+  assigneeType: "HUMAN" | "AGENT";
+};
+
+export type WorkspaceMemberWithUser = {
+  userId: string;
+  user: { id: string; name: string | null; email: string | null };
+};
+
+/** Strip a leading "@", lower-case, and remove whitespace. */
+export function normalizeHandle(handle: string): string {
+  return handle.replace(/^@/, "").toLowerCase().replace(/\s+/g, "");
+}
+
+/**
+ * Fetch all workspace members once so callers in a loop can pass the list in
+ * and avoid an N+1 per-task query.
+ */
+export async function fetchWorkspaceMembers(
+  tx: Tx,
+  workspaceId: string
+): Promise<WorkspaceMemberWithUser[]> {
+  return tx.workspaceMember.findMany({
+    where: { workspaceId },
+    include: { user: { select: { id: true, name: true, email: true } } },
+  });
+}
+
+/**
+ * Resolve an @mention handle to a workspace user.
+ * Pass `prefetchedMembers` (from `fetchWorkspaceMembers`) to avoid a DB query
+ * per call when resolving multiple tasks in a loop.
+ */
+export async function resolveAssignee(
+  tx: Tx,
+  workspaceId: string,
+  handle: string | null,
+  prefetchedMembers?: WorkspaceMemberWithUser[]
+): Promise<ResolvedAssignee> {
+  if (!handle) return { assigneeId: null, assigneeType: "HUMAN" };
+  if (isAgentHandle(handle)) return { assigneeId: null, assigneeType: "AGENT" };
+
+  const slug = normalizeHandle(handle);
+  const members = prefetchedMembers ?? await tx.workspaceMember.findMany({
+    where: { workspaceId },
+    include: { user: { select: { id: true, name: true, email: true } } },
+  });
+
+  const match = members.find((m) => {
+    const email = (m.user.email ?? "").toLowerCase().replace(/\s+/g, "");
+    const nameSlug = (m.user.name ?? "").toLowerCase().replace(/\s+/g, "");
+    const emailLocal = email.split("@")[0];
+    return slug === nameSlug || slug === email || slug === emailLocal;
+  });
+
+  return { assigneeId: match?.userId ?? null, assigneeType: "HUMAN" };
+}

package/lib/note-crypto.ts

@@ -0,0 +1,108 @@
+/**
+ * Transparent note encryption-at-rest layer — server-side AES-256-GCM.
+ *
+ * Encryption policy:
+ *   - Local-only mode (IS_CLOUD=false, no CLOUD_DATABASE_URL):
+ *     Notes are stored as plaintext in PGlite. The data never leaves the
+ *     user's device, so encryption is unnecessary and would only create
+ *     a footgun (lose ENCRYPTION_PEPPER → lose all notes).
+ *
+ *   - Cloud mode (IS_CLOUD=true) or local with cloud sync (CLOUD_DATABASE_URL):
+ *     Notes are always encrypted before storage. This protects data at rest
+ *     in the cloud DB (Neon). The server holds the key (ENCRYPTION_PEPPER).
+ *
+ * Two sets of helpers, kept for call-site clarity:
+ *   encryptContent / decryptContent   → API routes / MCP (primary `prisma`)
+ *   encryptForSync / decryptFromSync  → sync-worker talking to either DB
+ * Both behave identically. Decryption is safe to call on plaintext (returns
+ * it unchanged) so legacy rows and local-only data don't throw.
+ *
+ * Only note.content is encrypted. Titles, ids, timestamps, and task data stay
+ * plaintext so they remain queryable.
+ */
+
+import { prisma, getCloudPrisma } from "@/lib/prisma";
+import { encryptNote, decryptNote, generateSalt, isEncrypted } from "@/lib/encryption";
+
+// ── Cloud check ─────────────────────────────────────────────────────────────
+// Encryption is only needed when data may reach the cloud DB. In local-only
+// mode (no cloud sync), notes stay plaintext on the user's own device.
+function isCloudEnabled(): boolean {
+  return process.env.IS_CLOUD === "true" || !!process.env.CLOUD_DATABASE_URL;
+}
+
+// ── Salt cache ────────────────────────────────────────────────────────────────
+// Per-workspace salt persisted in the workspace row. Cached in-process to avoid
+// an extra round-trip on every note read/write.
+
+const saltCache = new Map<string, string>();
+
+async function getWorkspaceSalt(workspaceId: string): Promise<string> {
+  const cached = saltCache.get(workspaceId);
+  if (cached) return cached;
+
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: workspaceId },
+    select: { encryptionSalt: true },
+  });
+
+  if (workspace?.encryptionSalt) {
+    saltCache.set(workspaceId, workspace.encryptionSalt);
+    return workspace.encryptionSalt;
+  }
+
+  // First time for this workspace: generate and persist the salt.
+  const salt = generateSalt();
+  await prisma.workspace.update({
+    where: { id: workspaceId },
+    data: { encryptionSalt: salt },
+  });
+  // Mirror to Neon so the migration step can find the salt alongside the workspace record.
+  // Non-fatal: if the cloud write fails, the migration endpoint will copy the workspace row.
+  const cloud = getCloudPrisma();
+  if (cloud) {
+    cloud.workspace.update({ where: { id: workspaceId }, data: { encryptionSalt: salt } }).catch(() => {});
+  }
+  saltCache.set(workspaceId, salt);
+  return salt;
+}
+
+function getPepper(): string {
+  const pepper = process.env.ENCRYPTION_PEPPER;
+  if (!pepper) {
+    throw new Error(
+      "[Brief] ENCRYPTION_PEPPER env var is required to encrypt notes at rest. " +
+      "Generate one with: openssl rand -base64 32"
+    );
+  }
+  return pepper;
+}
+
+// ── Public helpers ──────────────────────────────────────────────────────────
+
+export async function encryptContent(
+  content: string,
+  workspaceId: string
+): Promise<string> {
+  if (!isCloudEnabled()) return content; // local-only: store plaintext
+  if (isEncrypted(content)) return content; // never double-encrypt
+  const salt = await getWorkspaceSalt(workspaceId);
+  return encryptNote(content, getPepper(), salt);
+}
+
+export async function decryptContent(
+  content: string,
+  workspaceId: string
+): Promise<string> {
+  if (!isEncrypted(content)) return content; // plaintext or local-only safety
+  const salt = await getWorkspaceSalt(workspaceId);
+  return decryptNote(content, getPepper(), salt);
+}
+
+// Sync-worker aliases — identical behaviour, named for call-site intent.
+export const encryptForSync = encryptContent;
+export const decryptFromSync = decryptContent;
+
+export function invalidateSaltCache(workspaceId: string): void {
+  saltCache.delete(workspaceId);
+}