Add spam protection, moderation and repo verification

.env.example

@@ -4,3 +4,13 @@ BIGQUERY_DATASET=
 
 # Public canonical site URL, used for metadata and sitemap generation.
 NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# Secret used to sign the voter cookie for ratings. Required in production.
+# Generate one with: openssl rand -base64 32
+VOTER_SECRET=
+
+# Bearer token for /api/admin/tools (approve or reject submissions). Leave empty to disable the admin API.
+ADMIN_TOKEN=
+
+# Optional GitHub token (no scopes needed). Raises the API limit used to verify submitted repositories.
+GITHUB_TOKEN=

.gitignore

@@ -83,6 +83,7 @@ web_modules/
 # Next.js build output
 .next
 out
+next-env.d.ts
 
 # Nuxt.js build / generate output
 .nuxt

README.md

@@ -47,7 +47,30 @@ gcloud run deploy chainkit \
   --region us-central1 \
   --allow-unauthenticated \
   --service-account chainkit-runtime@YOUR_PROJECT_ID.iam.gserviceaccount.com \
-  --set-env-vars BIGQUERY_PROJECT_ID=YOUR_PROJECT_ID,BIGQUERY_DATASET=YOUR_DATASET
+  --set-env-vars BIGQUERY_PROJECT_ID=YOUR_PROJECT_ID,BIGQUERY_DATASET=YOUR_DATASET \
+  --set-secrets VOTER_SECRET=chainkit-voter-secret:latest,ADMIN_TOKEN=chainkit-admin-token:latest,GITHUB_TOKEN=chainkit-github-token:latest
+```
+
+Create the three secrets in Secret Manager first and grant the runtime service
+account `roles/secretmanager.secretAccessor`. If you are upgrading an existing
+deployment, run the migration at the bottom of `infra/bigquery_schema.sql` before
+deploying.
+
+### Upgrading an existing BigQuery table
+
+Run the three statements at the bottom of `infra/bigquery_schema.sql` once, either
+in the BigQuery console or with `bq query --use_legacy_sql=false`. They add the
+`status` and `repo_key` columns and mark existing rows as `approved`. Use an account
+with `roles/bigquery.dataEditor` on the dataset and `roles/bigquery.jobUser` on the project.
+
+### Moderation
+
+New submissions are stored as `pending` and are not listed until approved:
+
+```sh
+curl -H "Authorization: Bearer $ADMIN_TOKEN" "$URL/api/admin/tools?status=pending"
+curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"action":"approve"}' "$URL/api/admin/tools/TOOL_ID"
 ```
 
 After deployment, set `NEXT_PUBLIC_SITE_URL` to the Cloud Run URL or your
@@ -65,8 +88,10 @@ runtime service account.
 
 ## Important production considerations
 
-- Submissions are immediately public in this starter. Add moderation or an approval workflow before opening submissions to an untrusted audience.
-- Ratings use a random browser-local identifier, not an authenticated user identity. It supports repeat edits from the same browser but is not abuse-resistant; add sign-in and rate limiting before treating ratings as verified.
+- Submissions are held as `pending` until approved through `/api/admin/tools`. The GitHub API is used to confirm the repository exists and is public; a repository that cannot be verified because GitHub is unavailable stays pending. Whether a project is actually about supply chains is a moderator decision.
+- Duplicate repositories are rejected (case-insensitive, ignoring `.git` and a trailing slash). BigQuery cannot enforce uniqueness, so the check runs inside the insert; two exactly simultaneous submissions could still both succeed.
+- `/api/tools` (3 per hour) and `/api/ratings` (30 per hour) are rate limited per client IP in application memory. On Cloud Run this is per instance and resets on cold start, so it is best-effort. Put Cloud Armor in front of the service for a hard limit.
+- Ratings use a server-signed cookie (`VOTER_SECRET`), so voter IDs cannot be made up. Clearing cookies still gives a new identity; the IP rate limit is the second layer. Add sign-in before treating ratings as verified.
 - The repository URL is validated and stored as a link. Chainkit does not clone, fetch, or execute submitted code.
 - BigQuery is optimized for analytics rather than high-volume transactional writes. For substantial rating or submission traffic, consider a transactional store and retain BigQuery for analytics.
 

infra/bigquery_schema.sql

@@ -5,8 +5,12 @@ CREATE TABLE IF NOT EXISTS `YOUR_PROJECT_ID.YOUR_DATASET.tools` (
   summary STRING NOT NULL,
   category STRING NOT NULL,
   repo_url STRING NOT NULL,
+  -- Lowercase owner/repo, used to reject duplicate submissions (not enforced by BigQuery).
+  repo_key STRING,
   website_url STRING,
   submitted_by STRING NOT NULL,
+  -- pending | approved | rejected. New submissions are pending until a moderator approves them.
+  status STRING,
   created_at TIMESTAMP NOT NULL
 )
 PARTITION BY DATE(created_at)
@@ -21,3 +25,16 @@ CREATE TABLE IF NOT EXISTS `YOUR_PROJECT_ID.YOUR_DATASET.tool_ratings` (
 )
 PARTITION BY DATE(created_at)
 CLUSTER BY tool_id, voter_id;
+
+-- ---------------------------------------------------------------------------
+-- Migration for an existing deployment (run once, BEFORE deploying this version).
+-- BigQuery cannot add NOT NULL columns, so both are nullable; the app treats a
+-- NULL status as 'approved' until the backfill has run.
+-- ---------------------------------------------------------------------------
+-- ALTER TABLE `YOUR_PROJECT_ID.YOUR_DATASET.tools` ADD COLUMN IF NOT EXISTS repo_key STRING;
+-- ALTER TABLE `YOUR_PROJECT_ID.YOUR_DATASET.tools` ADD COLUMN IF NOT EXISTS status STRING;
+-- UPDATE `YOUR_PROJECT_ID.YOUR_DATASET.tools`
+-- SET
+--   status = COALESCE(status, 'approved'),
+--   repo_key = LOWER(REGEXP_EXTRACT(repo_url, r'^https://github\.com/([^/]+/[^/]+?)(?:\.git)?/?$'))
+-- WHERE TRUE;

next-env.d.ts

@@ -1,7 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-import "./.next/types/root-params.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package.json

@@ -8,7 +8,8 @@
     "prestart": "node scripts/prepare-standalone.mjs",
     "start": "node .next/standalone/server.js",
     "lint": "eslint",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "next typegen && tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "@google-cloud/bigquery": "^9.6.0",
@@ -26,6 +27,7 @@
     "eslint": "^9",
     "eslint-config-next": "16.4.5",
     "tailwindcss": "^4",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^3.2.7"
   }
 }

src/app/api/admin/tools/[id]/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { adminDenied, checkAdmin } from "@/lib/admin-auth";
+import { setToolStatus } from "@/lib/tools";
+
+const bodySchema = z.object({ action: z.enum(["approve", "reject"]) });
+
+export async function POST(request: Request, context: { params: Promise<{ id: string }> }) {
+  const auth = checkAdmin(request);
+  if (auth !== "ok") return adminDenied(auth);
+
+  const parsed = bodySchema.safeParse(await request.json().catch(() => undefined));
+  if (!parsed.success) {
+    return NextResponse.json({ error: "action must be 'approve' or 'reject'." }, { status: 400 });
+  }
+
+  const { id } = await context.params;
+  const found = await setToolStatus(id, parsed.data.action === "approve" ? "approved" : "rejected");
+  if (!found) return NextResponse.json({ error: "Tool not found." }, { status: 404 });
+  return NextResponse.json({ id, status: parsed.data.action === "approve" ? "approved" : "rejected" });
+}

src/app/api/admin/tools/route.ts

@@ -0,0 +1,17 @@
+import { NextResponse } from "next/server";
+import { adminDenied, checkAdmin } from "@/lib/admin-auth";
+import { toolStatuses } from "@/lib/tool-types";
+import type { ToolStatus } from "@/lib/tool-types";
+import { listToolsByStatus } from "@/lib/tools";
+
+export async function GET(request: Request) {
+  const auth = checkAdmin(request);
+  if (auth !== "ok") return adminDenied(auth);
+
+  const status = new URL(request.url).searchParams.get("status") ?? "pending";
+  if (!toolStatuses.includes(status as ToolStatus)) {
+    return NextResponse.json({ error: "Unknown status." }, { status: 400 });
+  }
+  const tools = await listToolsByStatus(status as ToolStatus);
+  return NextResponse.json({ tools });
+}

src/app/api/ratings/route.ts

@@ -1,14 +1,27 @@
 import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
 import { z } from "zod";
+import { checkRateLimit, getClientIp, rateLimitResponse } from "@/lib/rate-limit";
 import { rateTool } from "@/lib/tools";
+import {
+  VOTER_COOKIE,
+  VOTER_COOKIE_MAX_AGE,
+  createVoterToken,
+  verifyVoterToken,
+} from "@/lib/voter";
 
+const RATINGS_PER_HOUR = 30;
+
+// The voter identity comes from a signed cookie, never from the request body.
 const ratingSchema = z.object({
   toolId: z.string().min(1).max(80),
-  voterId: z.string().uuid(),
   rating: z.number().int().min(1).max(5),
 });
 
 export async function POST(request: Request) {
+  const limit = checkRateLimit(`ratings:${getClientIp(request)}`, RATINGS_PER_HOUR, 60 * 60 * 1000);
+  if (!limit.allowed) return rateLimitResponse(limit);
+
   let body: unknown;
   try {
     body = await request.json();
@@ -22,11 +35,21 @@ export async function POST(request: Request) {
   }
 
   try {
-    const tool = await rateTool(
-      parsed.data.toolId,
-      parsed.data.voterId,
-      parsed.data.rating,
-    );
+    const cookieStore = await cookies();
+    let voterId = verifyVoterToken(cookieStore.get(VOTER_COOKIE)?.value);
+    if (!voterId) {
+      const issued = createVoterToken();
+      voterId = issued.voterId;
+      cookieStore.set(VOTER_COOKIE, issued.token, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: process.env.NODE_ENV === "production",
+        path: "/",
+        maxAge: VOTER_COOKIE_MAX_AGE,
+      });
+    }
+
+    const tool = await rateTool(parsed.data.toolId, voterId, parsed.data.rating);
     if (!tool) {
       return NextResponse.json({ error: "Tool not found." }, { status: 404 });
     }

src/app/api/tools/route.ts

@@ -1,27 +1,16 @@
 import { NextResponse } from "next/server";
 import { z } from "zod";
 import { categories } from "@/lib/tool-types";
-import { submitTool } from "@/lib/tools";
+import { parseGithubRepoUrl, verifyRepo } from "@/lib/github";
+import { checkRateLimit, getClientIp, rateLimitResponse } from "@/lib/rate-limit";
+import { DuplicateRepoError, submitTool } from "@/lib/tools";
+
+const SUBMISSIONS_PER_HOUR = 3;
 
 const githubRepoUrl = z
   .string()
   .url()
-  .refine((value) => {
-    try {
-      const url = new URL(value);
-      return (
-        url.protocol === "https:" &&
-        url.hostname === "github.com" &&
-        !url.username &&
-        !url.password &&
-        !url.search &&
-        !url.hash &&
-        /^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?\/?$/.test(url.pathname)
-      );
-    } catch {
-      return false;
-    }
-  }, "Enter a public GitHub repository URL.");
+  .refine((value) => parseGithubRepoUrl(value) !== undefined, "Enter a public GitHub repository URL.");
 
 const optionalWebsiteUrl = z
   .union([z.literal(""), z.string().url()])
@@ -41,6 +30,9 @@ const submissionSchema = z.object({
 });
 
 export async function POST(request: Request) {
+  const limit = checkRateLimit(`tools:${getClientIp(request)}`, SUBMISSIONS_PER_HOUR, 60 * 60 * 1000);
+  if (!limit.allowed) return rateLimitResponse(limit);
+
   let body: unknown;
   try {
     body = await request.json();
@@ -56,10 +48,40 @@ export async function POST(request: Request) {
     );
   }
 
+  const repo = parseGithubRepoUrl(parsed.data.repoUrl);
+  if (!repo) {
+    return NextResponse.json({ error: "Enter a public GitHub repository URL." }, { status: 400 });
+  }
+
+  // A failed lookup (rate limit, timeout) must not block the submission: it stays
+  // pending and a moderator checks it. Only a definite "not found" is rejected.
+  const verification = await verifyRepo(repo);
+  if (verification.status === "not_found") {
+    return NextResponse.json(
+      {
+        error: "That GitHub repository could not be found. Make sure it exists and is public.",
+        fields: { repoUrl: ["That GitHub repository could not be found. Make sure it exists and is public."] },
+      },
+      { status: 422 },
+    );
+  }
+
   try {
-    const tool = await submitTool(parsed.data);
-    return NextResponse.json({ tool }, { status: 201 });
+    await submitTool(parsed.data);
+    return NextResponse.json(
+      { status: "pending", message: "Thanks! Your submission is awaiting review." },
+      { status: 201 },
+    );
   } catch (error) {
+    if (error instanceof DuplicateRepoError) {
+      return NextResponse.json(
+        {
+          error: error.message,
+          fields: { repoUrl: [error.message] },
+        },
+        { status: 409 },
+      );
+    }
     console.error("Tool submission failed", error);
     return NextResponse.json(
       { error: "The tool could not be saved. Please try again later." },

src/app/directory.tsx

@@ -65,7 +65,7 @@ const emptyForm: FormFields = {
 };
 
 export function Directory({ initialTools }: Props) {
-  const [tools, setTools] = useState(initialTools);
+  const [tools] = useState(initialTools);
   const [search, setSearch] = useState("");
   const searchRef = useRef<HTMLInputElement>(null);
   const [category, setCategory] = useState("All tools");
@@ -126,7 +126,6 @@ export function Directory({ initialTools }: Props) {
         body: JSON.stringify(form),
       });
       const data = (await response.json()) as {
-        tool?: SupplyChainTool;
         error?: string;
         fields?: Record<string, string[] | undefined>;
       };
@@ -134,13 +133,7 @@ export function Directory({ initialTools }: Props) {
         const detail = Object.values(data.fields ?? {}).flat().find(Boolean);
         throw new Error(detail || data.error || "Your submission could not be saved.");
       }
-      const newTool = data.tool;
-      if (newTool) {
-        setTools((current) => [newTool, ...current]);
-        setSearch("");
-        setCategory("All tools");
-        setSort("Recently added");
-      }
+      // New submissions are held for review, so they are not added to the list here.
       setSubmitted(true);
       setForm(emptyForm);
     } catch (error) {
@@ -354,9 +347,9 @@ export function Directory({ initialTools }: Props) {
             {submitted ? (
               <div className="success-panel">
                 <div className="success-icon"><Check size={23} /></div>
-                <div className="section-kicker">YOU’RE IN THE INDEX</div>
+                <div className="section-kicker">SUBMISSION RECEIVED</div>
                 <h2 id="modal-heading">Thanks for sharing.</h2>
-                <p>Your project has been added to the community directory.</p>
+                <p>Your project is awaiting review and will appear in the directory once it is approved.</p>
                 <button className="button button-primary" onClick={() => setShowForm(false)}>Back to exploring</button>
               </div>
             ) : (

src/app/tool-rating.tsx

@@ -10,16 +10,6 @@ type Props = {
   size?: "small" | "large";
 };
 
-function getVoterId() {
-  const storageKey = "chainkit-voter-id";
-  let voterId = window.localStorage.getItem(storageKey);
-  if (!voterId) {
-    voterId = window.crypto.randomUUID();
-    window.localStorage.setItem(storageKey, voterId);
-  }
-  return voterId;
-}
-
 export function ToolRating({
   toolId,
   initialRating,
@@ -39,7 +29,7 @@ export function ToolRating({
       const response = await fetch("/api/ratings", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ toolId, rating: value, voterId: getVoterId() }),
+        body: JSON.stringify({ toolId, rating: value }),
       });
       const data = (await response.json()) as {
         averageRating?: number;

src/lib/admin-auth.ts

@@ -0,0 +1,22 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * Checks `Authorization: Bearer $ADMIN_TOKEN`. Returns "disabled" when no token is
+ * configured so the admin routes can answer 404 and stay invisible.
+ */
+export function checkAdmin(request: Request): "ok" | "denied" | "disabled" {
+  const expected = process.env.ADMIN_TOKEN;
+  if (!expected) return "disabled";
+  const header = request.headers.get("authorization") ?? "";
+  const provided = header.startsWith("Bearer ") ? header.slice(7) : "";
+  // Hash both sides so the comparison has equal length and does not leak it.
+  const a = createHash("sha256").update(provided).digest();
+  const b = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(a, b) ? "ok" : "denied";
+}
+
+export function adminDenied(result: "denied" | "disabled") {
+  return result === "disabled"
+    ? Response.json({ error: "Not found." }, { status: 404 })
+    : Response.json({ error: "Unauthorized." }, { status: 401 });
+}

src/lib/github.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseGithubRepoUrl, verifyRepo } from "@/lib/github";
+
+describe("parseGithubRepoUrl", () => {
+  it("normalizes case, .git and trailing slash", () => {
+    const a = parseGithubRepoUrl("https://github.com/Foo/Bar.git");
+    const b = parseGithubRepoUrl("https://github.com/foo/bar/");
+    expect(a?.repoKey).toBe("foo/bar");
+    expect(b?.repoKey).toBe("foo/bar");
+    expect(a?.canonicalUrl).toBe("https://github.com/Foo/Bar");
+  });
+
+  it.each([
+    "http://github.com/a/b",
+    "https://gitlab.com/a/b",
+    "https://github.com/a",
+    "https://github.com/a/b/tree/main",
+    "https://github.com/a/b?x=1",
+    "https://user@github.com/a/b",
+    "https://github.com/../b",
+  ])("rejects %s", (value) => {
+    expect(parseGithubRepoUrl(value)).toBeUndefined();
+  });
+});
+
+describe("verifyRepo", () => {
+  const ref = { owner: "a", repo: "b" };
+  const reply = (status: number, body: unknown = {}) =>
+    vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status }));
+
+  it("accepts a public repo", async () => {
+    expect(await verifyRepo(ref, reply(200, { private: false }))).toEqual({ status: "ok" });
+  });
+  it("rejects missing and private repos", async () => {
+    expect(await verifyRepo(ref, reply(404))).toEqual({ status: "not_found" });
+    expect(await verifyRepo(ref, reply(200, { private: true }))).toEqual({ status: "not_found" });
+  });
+  it("treats rate limits, 5xx and network errors as unavailable", async () => {
+    expect(await verifyRepo(ref, reply(403))).toEqual({ status: "unavailable" });
+    expect(await verifyRepo(ref, reply(502))).toEqual({ status: "unavailable" });
+    expect(await verifyRepo(ref, vi.fn().mockRejectedValue(new Error("timeout")))).toEqual({
+      status: "unavailable",
+    });
+  });
+});

src/lib/github.ts

@@ -0,0 +1,75 @@
+const REPO_PATH = /^\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/;
+
+export type GithubRepoRef = {
+  owner: string;
+  repo: string;
+  /** Lowercase `owner/repo`, used to detect duplicate submissions. */
+  repoKey: string;
+  /** Canonical URL stored in the database. */
+  canonicalUrl: string;
+};
+
+/** Returns undefined unless the value is a plain https://github.com/owner/repo URL. */
+export function parseGithubRepoUrl(value: string): GithubRepoRef | undefined {
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol !== "https:" ||
+      url.hostname !== "github.com" ||
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash
+    ) {
+      return undefined;
+    }
+    const match = REPO_PATH.exec(url.pathname);
+    if (!match) return undefined;
+    const [, owner, repo] = match;
+    if (repo === "." || repo === ".." || owner === "." || owner === "..") return undefined;
+    return {
+      owner,
+      repo,
+      repoKey: `${owner}/${repo}`.toLowerCase(),
+      canonicalUrl: `https://github.com/${owner}/${repo}`,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export type RepoVerification =
+  | { status: "ok" }
+  | { status: "not_found" }
+  | { status: "unavailable" };
+
+/**
+ * Confirms that a public repository exists. `unavailable` means GitHub could not
+ * answer (rate limit, timeout, 5xx), so the caller should not reject the submission.
+ */
+export async function verifyRepo(
+  ref: Pick<GithubRepoRef, "owner" | "repo">,
+  fetchImpl: typeof fetch = fetch,
+): Promise<RepoVerification> {
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "chainkit-directory",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+
+  try {
+    const response = await fetchImpl(
+      `https://api.github.com/repos/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.repo)}`,
+      { headers, signal: AbortSignal.timeout(5000), cache: "no-store" },
+    );
+    // Private repos return 404 to unauthenticated callers, which is what we want.
+    if (response.status === 404 || response.status === 451) return { status: "not_found" };
+    if (!response.ok) return { status: "unavailable" };
+    const data = (await response.json()) as { private?: boolean; disabled?: boolean };
+    if (data.private || data.disabled) return { status: "not_found" };
+    return { status: "ok" };
+  } catch {
+    return { status: "unavailable" };
+  }
+}

src/lib/rate-limit.test.ts

@@ -0,0 +1,29 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { checkRateLimit, getClientIp } from "@/lib/rate-limit";
+
+beforeEach(() => {
+  globalThis.__chainkitRateLimits = undefined;
+});
+
+describe("checkRateLimit", () => {
+  it("blocks after the limit and recovers after the window", () => {
+    expect(checkRateLimit("k", 2, 1000, 0).allowed).toBe(true);
+    expect(checkRateLimit("k", 2, 1000, 1).allowed).toBe(true);
+    const blocked = checkRateLimit("k", 2, 1000, 2);
+    expect(blocked.allowed).toBe(false);
+    expect(blocked.retryAfterSeconds).toBeGreaterThan(0);
+    expect(checkRateLimit("k", 2, 1000, 1001).allowed).toBe(true);
+  });
+
+  it("tracks keys independently", () => {
+    checkRateLimit("a", 1, 1000, 0);
+    expect(checkRateLimit("b", 1, 1000, 0).allowed).toBe(true);
+  });
+});
+
+describe("getClientIp", () => {
+  it("uses the last x-forwarded-for entry", () => {
+    const request = new Request("http://x", { headers: { "x-forwarded-for": "6.6.6.6, 1.2.3.4" } });
+    expect(getClientIp(request)).toBe("1.2.3.4");
+  });
+});

src/lib/rate-limit.ts

@@ -0,0 +1,69 @@
+type Bucket = { count: number; resetAt: number };
+
+declare global {
+  var __chainkitRateLimits: Map<string, Bucket> | undefined;
+}
+
+const MAX_KEYS = 10_000;
+
+function getBuckets() {
+  globalThis.__chainkitRateLimits ??= new Map();
+  return globalThis.__chainkitRateLimits;
+}
+
+export type RateLimitResult = { allowed: boolean; retryAfterSeconds: number };
+
+/**
+ * Fixed-window limiter held in process memory. On Cloud Run it is per instance
+ * and resets on cold start, so treat it as best-effort; put Cloud Armor in front
+ * for a hard limit.
+ */
+export function checkRateLimit(
+  key: string,
+  limit: number,
+  windowMs: number,
+  now = Date.now(),
+): RateLimitResult {
+  const buckets = getBuckets();
+  if (buckets.size > MAX_KEYS) {
+    for (const [bucketKey, bucket] of buckets) {
+      if (bucket.resetAt <= now) buckets.delete(bucketKey);
+    }
+    // Still full of live buckets: drop the oldest ones rather than grow unbounded.
+    if (buckets.size > MAX_KEYS) {
+      for (const bucketKey of buckets.keys()) {
+        buckets.delete(bucketKey);
+        if (buckets.size <= MAX_KEYS / 2) break;
+      }
+    }
+  }
+
+  const existing = buckets.get(key);
+  if (!existing || existing.resetAt <= now) {
+    buckets.set(key, { count: 1, resetAt: now + windowMs });
+    return { allowed: true, retryAfterSeconds: 0 };
+  }
+  existing.count += 1;
+  if (existing.count > limit) {
+    return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil((existing.resetAt - now) / 1000)) };
+  }
+  return { allowed: true, retryAfterSeconds: 0 };
+}
+
+/** Client IP as set by Cloud Run / a proxy. Falls back to "unknown". */
+export function getClientIp(request: Request) {
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded) {
+    // Cloud Run appends the real client address; the last entry is the one we trust.
+    const parts = forwarded.split(",").map((part) => part.trim()).filter(Boolean);
+    if (parts.length) return parts[parts.length - 1];
+  }
+  return request.headers.get("x-real-ip") ?? "unknown";
+}
+
+export function rateLimitResponse(result: RateLimitResult) {
+  return Response.json(
+    { error: "Too many requests. Please try again later." },
+    { status: 429, headers: { "Retry-After": String(result.retryAfterSeconds) } },
+  );
+}

src/lib/tool-types.ts

@@ -8,6 +8,10 @@ export const categories = [
 
 export type ToolCategory = (typeof categories)[number];
 
+export const toolStatuses = ["pending", "approved", "rejected"] as const;
+
+export type ToolStatus = (typeof toolStatuses)[number];
+
 export type SupplyChainTool = {
   id: string;
   slug: string;
@@ -17,6 +21,7 @@ export type SupplyChainTool = {
   repoUrl: string;
   websiteUrl: string;
   submittedBy: string;
+  status: ToolStatus;
   createdAt: string;
   averageRating: number;
   ratingCount: number;

src/lib/tools.test.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { DuplicateRepoError, getTools, listToolsByStatus, rateTool, setToolStatus, submitTool } from "@/lib/tools";
+
+const input = {
+  name: "Demo Tool",
+  summary: "A summary that is long enough to pass.",
+  category: "Planning" as const,
+  repoUrl: "https://github.com/Acme/Widget.git",
+  websiteUrl: "",
+  submittedBy: "Tester",
+};
+
+beforeEach(() => {
+  globalThis.__chainkitDemoState = undefined;
+});
+
+describe("demo store moderation", () => {
+  it("keeps new submissions hidden until approved", async () => {
+    const tool = await submitTool(input);
+    expect(tool.status).toBe("pending");
+    expect((await getTools()).some((t) => t.id === tool.id)).toBe(false);
+    expect(await rateTool(tool.id, crypto.randomUUID(), 5)).toBeUndefined();
+
+    await setToolStatus(tool.id, "approved");
+    expect((await getTools()).some((t) => t.id === tool.id)).toBe(true);
+    expect(await rateTool(tool.id, crypto.randomUUID(), 5)).toBeDefined();
+  });
+
+  it("rejects duplicates regardless of case, .git and trailing slash", async () => {
+    await submitTool(input);
+    await expect(submitTool({ ...input, repoUrl: "https://github.com/acme/widget/" })).rejects.toBeInstanceOf(
+      DuplicateRepoError,
+    );
+  });
+
+  it("allows resubmitting a repo after it was rejected", async () => {
+    const tool = await submitTool(input);
+    await setToolStatus(tool.id, "rejected");
+    await expect(submitTool(input)).resolves.toBeDefined();
+    expect(await listToolsByStatus("rejected")).toHaveLength(1);
+  });
+});

src/lib/tools.ts

@@ -1,13 +1,21 @@
 import { randomUUID } from "node:crypto";
 import { BigQuery } from "@google-cloud/bigquery";
-import type { SupplyChainTool, ToolCategory } from "@/lib/tool-types";
-import { categories } from "@/lib/tool-types";
+import type { SupplyChainTool, ToolCategory, ToolStatus } from "@/lib/tool-types";
+import { categories, toolStatuses } from "@/lib/tool-types";
+import { parseGithubRepoUrl } from "@/lib/github";
 
 type NewTool = Omit<
   SupplyChainTool,
-  "id" | "slug" | "createdAt" | "averageRating" | "ratingCount"
+  "id" | "slug" | "createdAt" | "averageRating" | "ratingCount" | "status"
 >;
 
+export class DuplicateRepoError extends Error {
+  constructor() {
+    super("This repository has already been submitted.");
+    this.name = "DuplicateRepoError";
+  }
+}
+
 type DemoState = {
   tools: SupplyChainTool[];
   ratings: Map<string, number>;
@@ -28,6 +36,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/MSUSAzureAccelerators/Intelligent-Supply-Chain-Management",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -42,6 +51,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/frenkowski/SCIMAI-Gym",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -56,6 +66,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/trydoff/Product-Demand-Forecasting-Using-ML",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -70,6 +81,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/TimefoldAI/timefold-solver",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -84,6 +96,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/workkrishnpatel/supply-chain-late-delivery-prediction",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -98,6 +111,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/ArwaElsayed5/Graduation-Project",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -112,6 +126,7 @@ const demoTools: SupplyChainTool[] = [
     repoUrl: "https://github.com/thenishantraj/fraudlens-ai",
     websiteUrl: "",
     submittedBy: "Chainkit demo",
+    status: "approved",
     createdAt: "2026-11-06T10:00:00.000Z",
     averageRating: 0,
     ratingCount: 0,
@@ -161,6 +176,10 @@ function ratingTable(projectId: string, dataset: string) {
   return `\`${projectId}.${dataset}.tool_ratings\``;
 }
 
+function isToolStatus(value: string): value is ToolStatus {
+  return toolStatuses.some((item) => item === value);
+}
+
 function isToolCategory(value: string): value is ToolCategory {
   return categories.some((item) => item === value);
 }
@@ -170,6 +189,10 @@ function mapBigQueryRow(row: Record<string, unknown>): SupplyChainTool {
   if (!isToolCategory(category)) {
     throw new Error(`BigQuery returned an unsupported category: ${category}`);
   }
+  const status = String(row.status ?? "approved");
+  if (!isToolStatus(status)) {
+    throw new Error(`BigQuery returned an unsupported status: ${status}`);
+  }
   return {
     id: String(row.id),
     slug: String(row.slug),
@@ -179,12 +202,15 @@ function mapBigQueryRow(row: Record<string, unknown>): SupplyChainTool {
     repoUrl: String(row.repoUrl),
     websiteUrl: String(row.websiteUrl ?? ""),
     submittedBy: String(row.submittedBy),
+    status,
     createdAt: new Date(String(row.createdAt)).toISOString(),
     averageRating: Number(row.averageRating ?? 0),
     ratingCount: Number(row.ratingCount ?? 0),
   };
 }
 
+const APPROVED_ONLY = "WHERE COALESCE(t.status, 'approved') = 'approved'";
+
 function buildToolQuery(
   projectId: string,
   dataset: string,
@@ -201,6 +227,7 @@ function buildToolQuery(
       t.repo_url AS repoUrl,
       t.website_url AS websiteUrl,
       t.submitted_by AS submittedBy,
+      COALESCE(t.status, 'approved') AS status,
       t.created_at AS createdAt,
       COALESCE(AVG(r.rating), 0) AS averageRating,
       COUNT(r.rating) AS ratingCount
@@ -210,36 +237,75 @@ function buildToolQuery(
     ${where}
     GROUP BY
       t.tool_id, t.slug, t.name, t.summary, t.category, t.repo_url,
-      t.website_url, t.submitted_by, t.created_at
+      t.website_url, t.submitted_by, t.status, t.created_at
     ${order}
   `;
 }
 
 export async function getTools(): Promise<SupplyChainTool[]> {
   const bigQuery = getBigQuery();
-  if (!bigQuery) return getDemoState().tools;
+  if (!bigQuery) return getDemoState().tools.filter((tool) => tool.status === "approved");
+
+  const [rows] = await bigQuery.client.query({
+    query: buildToolQuery(
+      bigQuery.projectId,
+      bigQuery.dataset,
+      APPROVED_ONLY,
+      "ORDER BY t.created_at DESC",
+    ),
+  });
+  return rows.map(mapBigQueryRow);
+}
+
+/** Moderation view: tools in a given status, newest first. */
+export async function listToolsByStatus(status: ToolStatus): Promise<SupplyChainTool[]> {
+  const bigQuery = getBigQuery();
+  if (!bigQuery) return getDemoState().tools.filter((tool) => tool.status === status);
 
   const [rows] = await bigQuery.client.query({
     query: buildToolQuery(
       bigQuery.projectId,
       bigQuery.dataset,
-      "",
+      "WHERE COALESCE(t.status, 'approved') = @status",
       "ORDER BY t.created_at DESC",
     ),
+    params: { status },
   });
   return rows.map(mapBigQueryRow);
 }
 
+export async function setToolStatus(toolId: string, status: ToolStatus) {
+  const bigQuery = getBigQuery();
+  if (!bigQuery) {
+    const tool = getDemoState().tools.find((candidate) => candidate.id === toolId);
+    if (!tool) return false;
+    tool.status = status;
+    return true;
+  }
+  const [job] = await bigQuery.client.createQueryJob({
+    query: `
+      UPDATE ${toolTable(bigQuery.projectId, bigQuery.dataset)}
+      SET status = @status
+      WHERE tool_id = @toolId
+    `,
+    params: { toolId, status },
+  });
+  await job.getQueryResults();
+  return (await affectedRows(job)) > 0;
+}
+
 export async function getToolBySlug(slug: string) {
   const bigQuery = getBigQuery();
   if (!bigQuery) {
-    return getDemoState().tools.find((tool) => tool.slug === slug);
+    return getDemoState().tools.find(
+      (tool) => tool.slug === slug && tool.status === "approved",
+    );
   }
   const [rows] = await bigQuery.client.query({
     query: `${buildToolQuery(
       bigQuery.projectId,
       bigQuery.dataset,
-      "WHERE t.slug = @slug",
+      `${APPROVED_ONLY} AND t.slug = @slug`,
     )} LIMIT 1`,
     params: { slug },
   });
@@ -249,20 +315,41 @@ export async function getToolBySlug(slug: string) {
 async function getToolById(toolId: string) {
   const bigQuery = getBigQuery();
   if (!bigQuery) {
-    return getDemoState().tools.find((tool) => tool.id === toolId);
+    return getDemoState().tools.find(
+      (tool) => tool.id === toolId && tool.status === "approved",
+    );
   }
   const [rows] = await bigQuery.client.query({
     query: `${buildToolQuery(
       bigQuery.projectId,
       bigQuery.dataset,
-      "WHERE t.tool_id = @toolId",
+      `${APPROVED_ONLY} AND t.tool_id = @toolId`,
     )} LIMIT 1`,
     params: { toolId },
   });
   return rows[0] ? mapBigQueryRow(rows[0]) : undefined;
 }
 
+async function affectedRows(job: { getMetadata: () => Promise<unknown[]> }) {
+  const [metadata] = (await job.getMetadata()) as [
+    { statistics?: { query?: { numDmlAffectedRows?: string } } },
+  ];
+  return Number(metadata.statistics?.query?.numDmlAffectedRows ?? 0);
+}
+
+/**
+ * Stores a new submission as `pending`. Throws DuplicateRepoError when the same
+ * repository (case-insensitive, ignoring `.git` and trailing slash) is already
+ * listed or awaiting review.
+ *
+ * BigQuery cannot enforce uniqueness, so the check is part of the INSERT
+ * statement. Two exactly simultaneous submissions can still race; the per-IP
+ * rate limit makes that impractical to exploit.
+ */
 export async function submitTool(input: NewTool) {
+  const repo = parseGithubRepoUrl(input.repoUrl);
+  if (!repo) throw new Error("repoUrl must be a GitHub repository URL.");
+
   const createdAt = new Date().toISOString();
   const id = randomUUID();
   const slugBase =
@@ -275,8 +362,10 @@ export async function submitTool(input: NewTool) {
       .slice(0, 48) || "supply-chain-tool";
   const tool: SupplyChainTool = {
     ...input,
+    repoUrl: repo.canonicalUrl,
     id,
     slug: `${slugBase}-${id.slice(0, 8)}`,
+    status: "pending",
     createdAt,
     averageRating: 0,
     ratingCount: 0,
@@ -284,16 +373,33 @@ export async function submitTool(input: NewTool) {
   const bigQuery = getBigQuery();
 
   if (!bigQuery) {
-    getDemoState().tools.unshift(tool);
+    const state = getDemoState();
+    const duplicate = state.tools.some(
+      (existing) =>
+        existing.status !== "rejected" &&
+        parseGithubRepoUrl(existing.repoUrl)?.repoKey === repo.repoKey,
+    );
+    if (duplicate) throw new DuplicateRepoError();
+    state.tools.unshift(tool);
     return tool;
   }
 
-  await bigQuery.client.query({
+  // The REGEXP_REPLACE branch also catches rows written before repo_key existed.
+  const [job] = await bigQuery.client.createQueryJob({
     query: `
       INSERT INTO ${toolTable(bigQuery.projectId, bigQuery.dataset)}
-        (tool_id, slug, name, summary, category, repo_url, website_url, submitted_by, created_at)
-      VALUES
-        (@id, @slug, @name, @summary, @category, @repoUrl, @websiteUrl, @submittedBy, TIMESTAMP(@createdAt))
+        (tool_id, slug, name, summary, category, repo_url, repo_key, website_url, submitted_by, status, created_at)
+      SELECT
+        @id, @slug, @name, @summary, @category, @repoUrl, @repoKey, @websiteUrl, @submittedBy, 'pending', TIMESTAMP(@createdAt)
+      FROM (SELECT 1)
+      WHERE NOT EXISTS (
+        SELECT 1 FROM ${toolTable(bigQuery.projectId, bigQuery.dataset)} AS existing
+        WHERE COALESCE(existing.status, 'approved') != 'rejected'
+          AND (
+            existing.repo_key = @repoKey
+            OR LOWER(REGEXP_REPLACE(existing.repo_url, r'(\.git)?/?$', '')) = CONCAT('https://github.com/', @repoKey)
+          )
+      )
     `,
     params: {
       id: tool.id,
@@ -302,11 +408,14 @@ export async function submitTool(input: NewTool) {
       summary: tool.summary,
       category: tool.category,
       repoUrl: tool.repoUrl,
+      repoKey: repo.repoKey,
       websiteUrl: tool.websiteUrl,
       submittedBy: tool.submittedBy,
       createdAt: tool.createdAt,
     },
   });
+  await job.getQueryResults();
+  if ((await affectedRows(job)) === 0) throw new DuplicateRepoError();
   return tool;
 }
 
@@ -314,7 +423,9 @@ export async function rateTool(toolId: string, voterId: string, rating: number)
   const bigQuery = getBigQuery();
   if (!bigQuery) {
     const state = getDemoState();
-    const tool = state.tools.find((candidate) => candidate.id === toolId);
+    const tool = state.tools.find(
+      (candidate) => candidate.id === toolId && candidate.status === "approved",
+    );
     if (!tool) return undefined;
 
     const key = `${toolId}:${voterId}`;

src/lib/voter.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { createVoterToken, verifyVoterToken } from "@/lib/voter";
+
+describe("voter token", () => {
+  it("round-trips a signed token", () => {
+    const { voterId, token } = createVoterToken();
+    expect(verifyVoterToken(token)).toBe(voterId);
+  });
+  it("rejects forged, tampered and missing tokens", () => {
+    const { token } = createVoterToken();
+    expect(verifyVoterToken(`${crypto.randomUUID()}.${token.split(".")[1]}`)).toBeUndefined();
+    expect(verifyVoterToken(`${token}x`)).toBeUndefined();
+    expect(verifyVoterToken(crypto.randomUUID())).toBeUndefined();
+    expect(verifyVoterToken(undefined)).toBeUndefined();
+  });
+});

src/lib/voter.ts

@@ -0,0 +1,38 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+export const VOTER_COOKIE = "chainkit-voter";
+export const VOTER_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+let devSecret: string | undefined;
+
+function getSecret() {
+  const secret = process.env.VOTER_SECRET;
+  if (secret) return secret;
+  if (process.env.NODE_ENV === "production") {
+    throw new Error("VOTER_SECRET must be set in production.");
+  }
+  devSecret ??= randomUUID();
+  return devSecret;
+}
+
+function sign(voterId: string) {
+  return createHmac("sha256", getSecret()).update(voterId).digest("base64url");
+}
+
+export function createVoterToken(voterId = randomUUID()) {
+  return { voterId, token: `${voterId}.${sign(voterId)}` };
+}
+
+/** Returns the voter UUID when the token carries a valid signature. */
+export function verifyVoterToken(token: string | undefined) {
+  if (!token) return undefined;
+  const separator = token.indexOf(".");
+  if (separator < 1) return undefined;
+  const voterId = token.slice(0, separator);
+  const signature = Buffer.from(token.slice(separator + 1));
+  const expected = Buffer.from(sign(voterId));
+  if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {
+    return undefined;
+  }
+  return voterId;
+}

vitest.config.ts

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+  test: { include: ["src/**/*.test.ts"] },
+});