feat(web/api): wire write+delete scopes for REST and MCP

Add the four daily-write REST endpoints and five matching MCP tools
backed by PAT bearer auth, plus two new scopes (submission:delete,
comment:delete) for author-only deletes. Cores extracted into lib/
so the web action, REST route, and MCP tool share one implementation
per noun.

Endpoints:
  POST   /api/v1/comments           comment:write
  POST   /api/v1/votes              vote:write
  POST   /api/v1/saves              save:write
  DELETE /api/v1/submissions/{id}   submission:delete  (author-only)
  DELETE /api/v1/comments/{id}      comment:delete     (author-only)

MCP tools: post_comment, vote, save, delete_submission, delete_comment.

Cores:
  lib/comments.ts  createComment, deleteCommentAsAuthor
  lib/votes.ts     castVote, setSave
  lib/submissions.ts adds deleteSubmissionAsAuthor

Audit-driven correctness fixes folded into the comment core:
- deleteCommentAsAuthor wraps the reply-check + delete in a tx with
  FOR UPDATE on the target. createComment locks the parent FOR SHARE
  before insert. parent_id has no FK; without serialization a hard
  delete + concurrent reply could leave an orphaned parent_id.
- Locked accounts now return reason=locked instead of silently routing
  to the moderation queue, matching lib/submissions.ts and lib/votes.ts.
- Replies must target an approved, non-deleted parent. The web UI hid
  reply links for non-visible parents; PAT/MCP could bypass that.
- Notifications gate on initialState=approved so a "reply" alert
  cannot point at a tombstone the recipient cannot read yet.
- CommentThread renders id="comment-<id>" so the #comment-<id>
  fragment that REST/MCP and the notifications page emit resolves.

MCP duplication trimmed: formatZodIssues + enforceRateLimit helpers
keep wording stable via a singular RATE_LIMIT_NOUN map.

Author: xiaolai

web/src/app/api/v1/comments/[id]/route.ts

@@ -0,0 +1,59 @@
+/**
+ * DELETE /api/v1/comments/[id] — author-only delete via PAT.
+ *
+ * Mirrors deleteComment (web UI server action). Soft-deletes when
+ * replies exist (tombstone preserved so the thread doesn't reshape);
+ * hard-deletes the row otherwise.
+ *
+ * Author check happens inside deleteCommentAsAuthor; PAT scope is
+ * enforced here. Charged against the `comments` daily bucket.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import { forbidden, notFound, rateLimited } from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import { deleteCommentAsAuthor } from "@/lib/comments";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function DELETE(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  const { id } = await params;
+  if (!UUID_RE.test(id)) return problemResponse(notFound("Invalid id."));
+
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "comment:delete");
+  if (denied) return problemResponse(denied.problem);
+
+  const limit = await checkAndIncrement(auth.token.id, "comments");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily comment-write limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await deleteCommentAsAuthor(auth.user.id, id);
+  if (!result.ok) {
+    if (result.reason === "forbidden") {
+      return problemResponse(
+        forbidden("You can only delete your own comments."),
+      );
+    }
+    return problemResponse(notFound("Comment not found."));
+  }
+
+  return ok({ id, deleted: true, submissionId: result.submissionId });
+}

web/src/app/api/v1/comments/route.ts

@@ -0,0 +1,93 @@
+/**
+ * POST /api/v1/comments — post a comment or reply via PAT.
+ *
+ * Mirrors submitComment (web UI server action) but takes the author
+ * identity from a Bearer token instead of a cookie session. Replies
+ * are created by passing parentId; the parent must belong to the same
+ * submissionId.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import {
+  forbidden,
+  notFound,
+  rateLimited,
+  validation,
+} from "@/lib/api/errors";
+import { created, preflight, problemResponse } from "@/lib/api/response";
+import { commentInputSchema, createComment } from "@/lib/comments";
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "comment:write");
+  if (denied) return problemResponse(denied.problem);
+
+  // Parse + validate before bumping the rate-limit bucket — see the
+  // submissions route for the rationale.
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return problemResponse(validation("Request body must be valid JSON."));
+  }
+
+  const parsed = commentInputSchema.safeParse(body);
+  if (!parsed.success) {
+    return problemResponse(
+      validation(
+        "Comment validation failed.",
+        parsed.error.issues.map((i) => ({
+          field: i.path.join("."),
+          message: i.message,
+        })),
+      ),
+    );
+  }
+
+  const limit = await checkAndIncrement(auth.token.id, "comments");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily comment limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await createComment(auth.user.id, parsed.data);
+
+  if (!result.ok) {
+    if (result.reason === "not_found") {
+      return problemResponse(
+        notFound("Submission or parent comment not found."),
+      );
+    }
+    if (result.reason === "locked") {
+      // The "locked" outcome covers both an account lock (the user's
+      // role is "locked") and a submission lock (the thread is closed
+      // to new comments). Keep the message neutral so it covers both.
+      return problemResponse(
+        forbidden(
+          "Your account is locked, or this submission is closed to new comments.",
+        ),
+      );
+    }
+    return problemResponse(validation("Comment failed."));
+  }
+
+  return created(
+    {
+      id: result.commentId,
+      pending: result.pending,
+      url: `https://claudepot.com/post/${parsed.data.submissionId}#comment-${result.commentId}`,
+    },
+    `https://claudepot.com/post/${parsed.data.submissionId}#comment-${result.commentId}`,
+  );
+}

web/src/app/api/v1/saves/route.ts

@@ -0,0 +1,69 @@
+/**
+ * POST /api/v1/saves — toggle a private bookmark via PAT.
+ *
+ * Body: { submissionId: uuid, saved: boolean }
+ *
+ *   saved = true  → insert (idempotent — duplicate inserts are absorbed)
+ *   saved = false → delete (idempotent — missing rows are absorbed)
+ *
+ * Bookmarks are private to the token's owning user; nothing in this
+ * surface is publicly observable.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import { notFound, rateLimited, validation } from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import { saveInputSchema, setSave } from "@/lib/votes";
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "save:write");
+  if (denied) return problemResponse(denied.problem);
+
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return problemResponse(validation("Request body must be valid JSON."));
+  }
+
+  const parsed = saveInputSchema.safeParse(body);
+  if (!parsed.success) {
+    return problemResponse(
+      validation(
+        "Save validation failed.",
+        parsed.error.issues.map((i) => ({
+          field: i.path.join("."),
+          message: i.message,
+        })),
+      ),
+    );
+  }
+
+  const limit = await checkAndIncrement(auth.token.id, "saves");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily save limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await setSave(auth.user.id, parsed.data);
+
+  if (!result.ok) {
+    return problemResponse(
+      notFound("Submission not found, or not in a saveable state."),
+    );
+  }
+
+  return ok({ submissionId: parsed.data.submissionId, saved: result.saved });
+}

web/src/app/api/v1/submissions/[id]/route.ts

@@ -0,0 +1,60 @@
+/**
+ * DELETE /api/v1/submissions/[id] — author-only soft delete via PAT.
+ *
+ * Mirrors deleteSubmission (web UI server action). The row stays in
+ * the DB with `deleted_at` set; reads filter it out everywhere except
+ * the staff queue.
+ *
+ * Author check happens inside deleteSubmissionAsAuthor; PAT scope is
+ * enforced here. We charge against the `submissions` daily bucket so
+ * a leaked token can't mass-delete past the daily limit.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import { forbidden, notFound, rateLimited } from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import { deleteSubmissionAsAuthor } from "@/lib/submissions";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function DELETE(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  const { id } = await params;
+  if (!UUID_RE.test(id)) return problemResponse(notFound("Invalid id."));
+
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "submission:delete");
+  if (denied) return problemResponse(denied.problem);
+
+  const limit = await checkAndIncrement(auth.token.id, "submissions");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily submission-write limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await deleteSubmissionAsAuthor(auth.user.id, id);
+  if (!result.ok) {
+    if (result.reason === "forbidden") {
+      return problemResponse(
+        forbidden("You can only delete your own submissions."),
+      );
+    }
+    return problemResponse(notFound("Submission not found."));
+  }
+
+  return ok({ id, deleted: true });
+}

web/src/app/api/v1/votes/route.ts

@@ -0,0 +1,96 @@
+/**
+ * POST /api/v1/votes — cast / change / clear a vote via PAT.
+ *
+ * Body: { submissionId: uuid, value: 1 | -1 | 0 }
+ *
+ *   value =  1 → upvote
+ *   value = -1 → downvote (gated on karma >= 100, like the web UI)
+ *   value =  0 → clear the existing vote
+ *
+ * The DB trigger handles score deltas; the action upserts on
+ * (user_id, submission_id) so flipping is one row, not two.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import {
+  forbidden,
+  notFound,
+  rateLimited,
+  validation,
+} from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import { castVote, voteInputSchema } from "@/lib/votes";
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "vote:write");
+  if (denied) return problemResponse(denied.problem);
+
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return problemResponse(validation("Request body must be valid JSON."));
+  }
+
+  const parsed = voteInputSchema.safeParse(body);
+  if (!parsed.success) {
+    return problemResponse(
+      validation(
+        "Vote validation failed.",
+        parsed.error.issues.map((i) => ({
+          field: i.path.join("."),
+          message: i.message,
+        })),
+      ),
+    );
+  }
+
+  const limit = await checkAndIncrement(auth.token.id, "votes");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily vote limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await castVote(auth.user.id, parsed.data);
+
+  if (!result.ok) {
+    if (result.reason === "missing_user") {
+      // Token references a deleted user — already handled in
+      // authenticate(), but the core may still detect this if the user
+      // was deleted between auth and the vote. Surface as 401.
+      return problemResponse({
+        type: "https://claudepot.com/api/errors/unauthorized",
+        title: "Unauthorized",
+        status: 401,
+        detail: "Token references a deleted user.",
+      });
+    }
+    if (result.reason === "locked") {
+      return problemResponse(forbidden("Account is locked."));
+    }
+    if (result.reason === "karma_gate") {
+      return problemResponse(
+        forbidden(
+          "Downvotes require at least 100 karma. Your account is below the threshold.",
+        ),
+      );
+    }
+    return problemResponse(
+      notFound("Submission not found, or not in a votable state."),
+    );
+  }
+
+  return ok({ submissionId: parsed.data.submissionId, value: result.value });
+}