create-ailk 0.1.0

package/templates/apps/api/src/middleware/__tests__/rate-limit.test.ts

@@ -0,0 +1,292 @@
+/**
+ * @file rate-limit.test.ts
+ * Unit tests for the per-IP rate limit middleware (B5).
+ *
+ * Test runner: Jest (repo convention — jest.config.cjs uses ts-jest).
+ * Time control: jest.spyOn(Date, 'now') for the window-rolls case. We
+ * intentionally avoid jest.useFakeTimers() because it intercepts setImmediate,
+ * which Fastify's avvio plugin system uses during app.ready() — causing all
+ * tests to hang. Controlling Date.now() directly is sufficient since the
+ * middleware's window logic only calls Date.now().
+ * IP mocking: x-forwarded-for header on a trustProxy:true test server.
+ *
+ * Spec: docs/internal/specs/draft/ailk-mcp-mvp-pb-b5-rate-limit-spec.md
+ */
+
+import Fastify from "fastify";
+import { rateLimitMiddleware, __resetBuckets } from "../rate-limit.js";
+
+function buildApp(opts: { perIpPerMinute?: number; windowMs?: number } = {}) {
+  const app = Fastify({ trustProxy: true });
+  app.register(rateLimitMiddleware, opts);
+  app.get("/test", async () => ({ ok: true }));
+  return app;
+}
+
+describe("per-IP rate limit middleware", () => {
+  let app: ReturnType<typeof buildApp>;
+
+  beforeEach(async () => {
+    __resetBuckets();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("allows requests within the per-minute budget (5 under default)", async () => {
+    app = buildApp({ perIpPerMinute: 10 });
+    await app.ready();
+
+    for (let i = 0; i < 5; i++) {
+      const res = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "1.2.3.4" },
+      });
+      expect(res.statusCode).toBe(200);
+    }
+  });
+
+  it("returns 429 on the 11th request within the window", async () => {
+    app = buildApp({ perIpPerMinute: 10 });
+    await app.ready();
+
+    for (let i = 0; i < 10; i++) {
+      const res = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "1.2.3.4" },
+      });
+      expect(res.statusCode).toBe(200);
+    }
+
+    const overLimit = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "1.2.3.4" },
+    });
+    expect(overLimit.statusCode).toBe(429);
+    const body = JSON.parse(overLimit.body);
+    expect(body).toMatchObject({ error: "rate_limited" });
+    expect(typeof body.retryAfterSeconds).toBe("number");
+  });
+
+  it("resets the budget after the window expires", async () => {
+    // windowMs is passed explicitly so the spy's return value uses the same window the middleware sees.
+    const windowMs = 60_000;
+    app = buildApp({ perIpPerMinute: 2, windowMs });
+    await app.ready();
+
+    const origin = Date.now();
+    const dateSpy = jest.spyOn(Date, "now").mockReturnValue(origin);
+
+    try {
+      // Exhaust the budget.
+      for (let i = 0; i < 2; i++) {
+        await app.inject({
+          method: "GET",
+          url: "/test",
+          headers: { "x-forwarded-for": "1.2.3.4" },
+        });
+      }
+
+      // Advance virtual time past the window.
+      dateSpy.mockReturnValue(origin + windowMs + 1);
+
+      // First request in the new window should succeed.
+      const afterRoll = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "1.2.3.4" },
+      });
+      expect(afterRoll.statusCode).toBe(200);
+    } finally {
+      dateSpy.mockRestore();
+    }
+  });
+
+  it("includes Retry-After header <= 60 on 429 responses", async () => {
+    app = buildApp({ perIpPerMinute: 1 });
+    await app.ready();
+
+    // Use the budget.
+    await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "10.0.0.1" },
+    });
+
+    // Trigger 429.
+    const over = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "10.0.0.1" },
+    });
+
+    expect(over.statusCode).toBe(429);
+    const retryAfter = Number(over.headers["retry-after"]);
+    expect(Number.isInteger(retryAfter)).toBe(true);
+    expect(retryAfter).toBeGreaterThanOrEqual(1);
+    expect(retryAfter).toBeLessThanOrEqual(60);
+  });
+
+  it("tracks independent buckets per IP", async () => {
+    app = buildApp({ perIpPerMinute: 2 });
+    await app.ready();
+
+    // Exhaust IP A.
+    for (let i = 0; i < 2; i++) {
+      await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "192.168.1.1" },
+      });
+    }
+    const ipA429 = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "192.168.1.1" },
+    });
+    expect(ipA429.statusCode).toBe(429);
+
+    // IP B should still have a fresh budget.
+    const ipB = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "192.168.1.2" },
+    });
+    expect(ipB.statusCode).toBe(200);
+  });
+
+  it("respects custom perIpPerMinute option over env/default", async () => {
+    app = buildApp({ perIpPerMinute: 3 });
+    await app.ready();
+
+    // 3 requests should succeed.
+    for (let i = 0; i < 3; i++) {
+      const res = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "5.5.5.5" },
+      });
+      expect(res.statusCode).toBe(200);
+    }
+
+    // 4th exceeds the custom limit of 3.
+    const fourth = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "5.5.5.5" },
+    });
+    expect(fourth.statusCode).toBe(429);
+  });
+
+  it("reads perIpPerMinute from AILK_RATE_LIMIT_PER_IP_PER_MINUTE env var when option is absent", async () => {
+    // Cover `Number(process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE) || 10` left-side truthy arm
+    // Build the app without a perIpPerMinute option so the env var path is taken
+    const prev = process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE;
+    process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE = "2";
+    try {
+      app = buildApp({}); // no perIpPerMinute — env var drives the limit
+      await app.ready();
+
+      // 2 requests should succeed (env-configured limit).
+      for (let i = 0; i < 2; i++) {
+        const res = await app.inject({
+          method: "GET",
+          url: "/test",
+          headers: { "x-forwarded-for": "7.7.7.7" },
+        });
+        expect(res.statusCode).toBe(200);
+      }
+
+      // 3rd request exceeds the env-configured limit of 2.
+      const third = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "7.7.7.7" },
+      });
+      expect(third.statusCode).toBe(429);
+    } finally {
+      if (prev === undefined) {
+        delete process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE;
+      } else {
+        process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE = prev;
+      }
+    }
+  });
+
+  it("evicts stale buckets when cleanup is triggered on 429 with a stale IP in store", async () => {
+    // Cover the stale-bucket delete arm inside evictStaleBuckets (line 54)
+    // Scenario: IP A exhausts budget at t=0, time advances past window, IP B hits 429 — cleanup evicts A's stale bucket
+    const windowMs = 60_000;
+    app = buildApp({ perIpPerMinute: 1, windowMs });
+    await app.ready();
+
+    const origin = Date.now();
+    const dateSpy = jest.spyOn(Date, "now").mockReturnValue(origin);
+
+    try {
+      // Exhaust IP A's budget at t=0.
+      await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "11.0.0.1" },
+      });
+
+      // Advance virtual time past the window so IP A's bucket is now stale.
+      dateSpy.mockReturnValue(origin + windowMs + 1);
+
+      // Exhaust IP B's budget (fresh window).
+      await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "11.0.0.2" },
+      });
+
+      // IP B's 2nd request triggers 429 → calls evictStaleBuckets → deletes IP A's stale bucket.
+      const res = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "11.0.0.2" },
+      });
+
+      expect(res.statusCode).toBe(429);
+      // Cleanup ran — IP A's stale bucket was deleted. IP A can now make fresh requests.
+      const resA = await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": "11.0.0.1" },
+      });
+      expect(resA.statusCode).toBe(200);
+    } finally {
+      dateSpy.mockRestore();
+    }
+  });
+
+  it("triggers periodic cleanup after 100 requests in a single window", async () => {
+    // Cover `requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS` true arm (line 93)
+    // 100 requests from distinct IPs fill the bucket store; the 101st triggers eviction
+    app = buildApp({ perIpPerMinute: 200 }); // high limit so no 429 for first 100 requests
+    await app.ready();
+
+    // Send 100 requests from distinct IPs to advance requestsSinceLastClean to 100.
+    for (let i = 0; i < 100; i++) {
+      await app.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": `10.${Math.floor(i / 255)}.${i % 255}.1` },
+      });
+    }
+
+    // The 101st request (any IP) crosses the CLEAN_INTERVAL_REQUESTS threshold.
+    const res = await app.inject({
+      method: "GET",
+      url: "/test",
+      headers: { "x-forwarded-for": "10.1.0.99" },
+    });
+    // Cleanup fired — the route still responds normally.
+    expect(res.statusCode).toBe(200);
+  });
+});

package/templates/apps/api/src/middleware/auth.ts

@@ -0,0 +1,246 @@
+/**
+ * Dual-mode authentication preHandler for apps/api (#587).
+ *
+ * Decorates `request.userId` on authenticated requests, or returns 401.
+ * Two modes, evaluated in order:
+ *
+ *   1. Cookie path — Better Auth session cookie present and valid.
+ *      Looked up directly against the `Session` table (the row Better Auth's
+ *      database adapter creates on sign-in). Cookie wins when both modes are
+ *      present (locked by brief decision OQ-D / spec §3 "Both present").
+ *      Non-GET requests with a cookie are required to carry a same-origin
+ *      Origin header — the lightweight CSRF mechanism agreed in OQ-D. Bearer-
+ *      authenticated callers skip the origin check (non-browser flow).
+ *
+ *   2. Bearer path — Authorization: Bearer <token>. The token is sha256-hashed
+ *      and matched against `ApiToken.token` (stored as hash). Revoked / expired
+ *      tokens fail closed; lastUsedAt is bumped on a successful hit.
+ *
+ * Decision matrix (per spec §3):
+ *   - Cookie valid                    → cookie path wins. Bearer ignored.
+ *   - Cookie absent, bearer valid     → bearer path; CSRF skipped.
+ *   - Both modes invalid              → 401 unauthorized.
+ *   - Cookie expired + bearer valid   → 401 (no silent fallback).
+ *   - Cookie absent, bearer malformed → 401 (no silent fallback).
+ *
+ * Public routes (health, content, leads, webhooks, openapi) are NOT registered
+ * with this preHandler — server.ts narrows scope via a sub-plugin.
+ */
+import { createHash } from "node:crypto";
+
+import { getClock } from "@working-theory/common";
+import type {
+  FastifyPluginCallback,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+
+import { prisma } from "../lib/prisma.js";
+
+/**
+ * Better Auth's default cookie names. Both are tried in order so a deployment
+ * running over HTTP locally and HTTPS in production reads the same code path.
+ */
+const COOKIE_NAMES = [
+  "better-auth.session_token",
+  "__Secure-better-auth.session_token",
+] as const;
+
+const UNAUTHORIZED = { error: "unauthorized" } as const;
+
+declare module "fastify" {
+  interface FastifyRequest {
+    userId?: string;
+  }
+}
+
+/**
+ * Hash an opaque bearer-token string the same way `tokens.ts` does at create
+ * time. Centralised here so the lookup contract stays identical.
+ */
+function hashBearer(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/**
+ * Parse the request's Cookie header for the first Better Auth session-token
+ * variant present. Returns the cookie value (decoded) or undefined.
+ *
+ * Cookie parsing intentionally avoids decoding `+` as space — session tokens
+ * are URL-safe and don't contain `+`. Use decodeURIComponent only on the value
+ * to handle the rare case Better Auth percent-encodes the token.
+ */
+function readSessionCookie(request: FastifyRequest): string | undefined {
+  const raw = request.headers.cookie;
+  if (!raw) return undefined;
+  for (const part of raw.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (!COOKIE_NAMES.includes(name as (typeof COOKIE_NAMES)[number])) continue;
+    const value = part.slice(eq + 1).trim();
+    if (!value) continue;
+    try {
+      // Better Auth signs the cookie as <token>.<signature>; the dual-mode
+      // preHandler only needs the token portion to look up the Session row.
+      // Strip the signature if present.
+      const decoded = decodeURIComponent(value);
+      const dot = decoded.indexOf(".");
+      return dot > 0 ? decoded.slice(0, dot) : decoded;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function readBearer(request: FastifyRequest): string | undefined {
+  const auth = request.headers.authorization;
+  if (!auth) return undefined;
+  const match = /^Bearer\s+(\S+)$/i.exec(auth);
+  return match ? match[1] : undefined;
+}
+
+/**
+ * Same-origin CSRF check for cookie-authenticated mutating requests.
+ * Returns true if the request is safe (GET/HEAD/OPTIONS) or the Origin header
+ * matches the configured frontend origin. False otherwise.
+ */
+function isOriginAllowed(
+  request: FastifyRequest,
+  frontendOrigin: string | undefined,
+): boolean {
+  const method = request.method.toUpperCase();
+  if (method === "GET" || method === "HEAD" || method === "OPTIONS")
+    return true;
+  if (!frontendOrigin) {
+    // No FRONTEND_URL configured → accept any origin. The single-tenant OSS
+    // default trusts the deployment to set FRONTEND_URL; mis-configuration
+    // is a deploy-time concern, not a runtime auth failure.
+    return true;
+  }
+  const origin = request.headers.origin;
+  if (!origin) return false;
+  return origin === frontendOrigin;
+}
+
+type SessionRow = {
+  userId: string;
+  expiresAt: Date;
+};
+
+async function resolveCookieSession(
+  cookieToken: string,
+): Promise<SessionRow | undefined> {
+  const row = await prisma.session.findUnique({
+    where: { token: cookieToken },
+    select: { userId: true, expiresAt: true },
+  });
+  if (!row) return undefined;
+  return row;
+}
+
+type BearerRow = {
+  userId: string;
+  expiresAt: Date | null;
+  revokedAt: Date | null;
+  id: string;
+};
+
+async function resolveBearerToken(
+  bearer: string,
+): Promise<BearerRow | undefined> {
+  const hash = hashBearer(bearer);
+  const row = await prisma.apiToken.findUnique({
+    where: { token: hash },
+    select: { id: true, userId: true, expiresAt: true, revokedAt: true },
+  });
+  return row ?? undefined;
+}
+
+export type AuthPreHandlerOptions = {
+  /** Configured frontend origin used for the CSRF same-origin check. */
+  frontendOrigin?: string | undefined;
+};
+
+/**
+ * Fastify preHandler implementing the dual-mode contract.
+ *
+ * Exported standalone so route-test suites can register it directly without
+ * spinning up the full server module.
+ */
+export function makeAuthPreHandler(opts: AuthPreHandlerOptions = {}) {
+  const { frontendOrigin } = opts;
+  return async function authPreHandler(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const now = getClock().now();
+    const cookieToken = readSessionCookie(request);
+
+    if (cookieToken) {
+      const session = await resolveCookieSession(cookieToken).catch(
+        () => undefined,
+      );
+      if (session && session.expiresAt.getTime() > now) {
+        if (!isOriginAllowed(request, frontendOrigin)) {
+          reply.code(401).send(UNAUTHORIZED);
+          return;
+        }
+        request.userId = session.userId;
+        return;
+      }
+      // Cookie present but invalid / expired → 401 (no silent bearer fallback).
+      reply.code(401).send(UNAUTHORIZED);
+      return;
+    }
+
+    const bearer = readBearer(request);
+    if (bearer) {
+      const row = await resolveBearerToken(bearer).catch(() => undefined);
+      if (!row) {
+        reply.code(401).send(UNAUTHORIZED);
+        return;
+      }
+      if (row.revokedAt) {
+        reply.code(401).send(UNAUTHORIZED);
+        return;
+      }
+      if (row.expiresAt && row.expiresAt.getTime() <= now) {
+        reply.code(401).send(UNAUTHORIZED);
+        return;
+      }
+      request.userId = row.userId;
+      // Best-effort: bump lastUsedAt. Failure here MUST NOT 401 — the caller
+      // is already authenticated. Swallow the error and continue.
+      prisma.apiToken
+        .update({ where: { id: row.id }, data: { lastUsedAt: new Date(now) } })
+        .catch(() => undefined);
+      return;
+    }
+
+    // Neither present.
+    reply.code(401).send(UNAUTHORIZED);
+  };
+}
+
+/**
+ * Plugin form — exposes the preHandler via Fastify's `addHook`. The
+ * encapsulation override (Symbol.for("skip-override")) lets the hook
+ * propagate to sibling routes registered in the SAME parent scope after the
+ * plugin — matching the rate-limit.ts pattern. Without it, the hook would
+ * only fire for routes registered INSIDE the plugin, which is not the calling
+ * convention (server.ts registers the plugin first, then sibling routes).
+ */
+export const authPreHandlerPlugin: FastifyPluginCallback<
+  AuthPreHandlerOptions
+> = (fastify, opts, done) => {
+  const handler = makeAuthPreHandler(opts);
+  fastify.decorateRequest("userId", undefined);
+  fastify.addHook("preHandler", handler);
+  done();
+};
+
+(authPreHandlerPlugin as FastifyPluginCallback & { [key: symbol]: boolean })[
+  Symbol.for("skip-override")
+] = true;

package/templates/apps/api/src/middleware/rate-limit.ts

@@ -0,0 +1,132 @@
+/**
+ * Per-IP rate limit middleware for anonymous write routes.
+ *
+ * SINGLE-REPLICA CAVEAT: This module uses an in-process Map to store request
+ * counts. Each Fastify instance maintains its own bucket state. In a
+ * multi-replica deployment (e.g. 3 Vercel functions), an attacker can issue
+ * up to N × perIpPerMinute requests per minute per IP, where N is the replica
+ * count. For OSS v1 (single-replica), this is acceptable. A Redis-backed swap
+ * is tracked in the follow-up issue "Phase 6+ — Redis-backed rate limit for
+ * multi-replica deploys."
+ *
+ * Cleanup strategy: evict stale buckets on every 429 emission and every 100
+ * allowed requests (bounded, O(n) over bucket count — negligible for typical
+ * IP cardinality). No setInterval is started until the middleware is registered,
+ * keeping the module import-side-effect-free.
+ *
+ * Trust-proxy boundary: this middleware reads req.ip, which Fastify populates
+ * from the socket address and any trusted proxy headers (X-Forwarded-For) per
+ * the server's own trustProxy config. This middleware does NOT parse
+ * X-Forwarded-For itself.
+ */
+
+import { getClock } from "@working-theory/common";
+import type {
+  FastifyRequest,
+  FastifyReply,
+  FastifyPluginCallback,
+} from "fastify";
+
+export type RateLimitOptions = {
+  /** Requests allowed per IP per window. Default: AILK_RATE_LIMIT_PER_IP_PER_MINUTE env var ?? 10 */
+  perIpPerMinute?: number;
+  /** Window duration in milliseconds. Default: 60_000 */
+  windowMs?: number;
+  /** Extract the IP key from a request. Default: req.ip */
+  ipFromRequest?: (req: FastifyRequest) => string;
+};
+
+type Bucket = {
+  count: number;
+  windowStartMs: number;
+};
+
+const RATE_LIMITED = "rate_limited" as const;
+
+// Module-scoped bucket store. One entry per unique IP.
+const buckets = new Map<string, Bucket>();
+
+// Request counter used to trigger periodic cleanup.
+let requestsSinceLastClean = 0;
+const CLEAN_INTERVAL_REQUESTS = 100;
+
+function evictStaleBuckets(now: number, windowMs: number): void {
+  for (const [ip, bucket] of buckets) {
+    if (now - bucket.windowStartMs >= windowMs) {
+      buckets.delete(ip);
+    }
+  }
+  requestsSinceLastClean = 0;
+}
+
+/**
+ * Test-only reset. Clears all bucket state between test cases so they do not
+ * interfere with each other. Not intended for production use.
+ */
+export function __resetBuckets(): void {
+  buckets.clear();
+  requestsSinceLastClean = 0;
+}
+
+// Break Fastify's plugin encapsulation so the onRequest hook propagates to
+// parent and sibling scopes. This is the manual equivalent of fastify-plugin's
+// `skip-override` mechanism — documented in Fastify's plugin guide.
+// Without this, routes registered outside this plugin's scope do not see the hook.
+export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
+  fastify,
+  opts,
+  done,
+) => {
+  const {
+    perIpPerMinute = Number(process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE) ||
+      10,
+    windowMs = 60_000,
+    ipFromRequest = (req: FastifyRequest) => req.ip,
+  } = opts;
+
+  fastify.addHook(
+    "onRequest",
+    async (req: FastifyRequest, reply: FastifyReply) => {
+      const now = getClock().now();
+      const ip = ipFromRequest(req);
+
+      requestsSinceLastClean += 1;
+      if (requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS) {
+        evictStaleBuckets(now, windowMs);
+      }
+
+      let bucket = buckets.get(ip);
+
+      if (!bucket || now - bucket.windowStartMs >= windowMs) {
+        bucket = { count: 0, windowStartMs: now };
+        buckets.set(ip, bucket);
+      }
+
+      bucket.count += 1;
+
+      if (bucket.count > perIpPerMinute) {
+        const retryAfterSeconds = Math.ceil(
+          (bucket.windowStartMs + windowMs - now) / 1_000,
+        );
+
+        // Evict stale buckets on every 429 to cap memory under abuse.
+        evictStaleBuckets(now, windowMs);
+
+        req.log.warn({ ip, path: req.url, count: bucket.count }, RATE_LIMITED);
+
+        return reply
+          .status(429)
+          .header("Retry-After", String(retryAfterSeconds))
+          .send({ error: RATE_LIMITED, retryAfterSeconds });
+      }
+    },
+  );
+
+  done();
+};
+
+// Skip Fastify's plugin encapsulation — hooks registered inside propagate to
+// all scopes (parent + siblings), not just descendants of this plugin.
+(rateLimitMiddleware as FastifyPluginCallback & { [key: symbol]: boolean })[
+  Symbol.for("skip-override")
+] = true;