create-ailk 0.1.0

package/templates/apps/api/src/lib/locales.ts

@@ -0,0 +1,201 @@
+/**
+ * readLocales — read and validate the `product.locales` field from project.yaml.
+ *
+ * Mirrors `apps/web/lib/locales.ts`. Duplicated because architecture.yaml does
+ * not permit cross-app imports (apps/api may not import apps/web), and the
+ * shared package boundary would require either a new package or extending
+ * packages/common's architectural surface (which neither apps/api nor apps/web
+ * declares as a may-import-from for filesystem helpers today).
+ *
+ * Validation rules:
+ * - `locales` field absent → defaults to `["en"]` (backward-compat with OSS
+ *   forks that pre-date the field)
+ * - `locales` present → must be a non-empty array of BCP-47 locale tags
+ *   matching `/^[a-z]{2}(-[A-Z]{2})?$/` (MVP subset)
+ * - `product.default_locale` must be included in the `locales` list; parse
+ *   error if not
+ * - `locales: []` → parse error (empty array is invalid)
+ *
+ * Used by the content read routes to validate the `?locale=` query parameter
+ * against the configured allowlist before passing to the adapter (defense-in-
+ * depth per AC-i18n-07).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse } from "yaml";
+
+/** BCP-47 MVP subset: `xx` or `xx-XX` (language + optional region). */
+const BCP47_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+/**
+ * Reads, validates, and returns the sorted locale list from project.yaml.
+ *
+ * Walks up from cwd to locate the file:
+ *   - When apps/api runs from its own dir, project.yaml lives at `../..`
+ *   - When invoked from repo root, project.yaml lives at `./`
+ *
+ * @param cwd - Directory to search from. Defaults to `process.cwd()`.
+ * @returns Sorted `string[]` of enabled locale tags.
+ * @throws Error with a descriptive message (file + cause) when validation fails.
+ */
+export function readLocales(cwd = process.cwd()): string[] {
+  const filePath = resolveProjectYamlPath(cwd);
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    throw new Error(
+      `[locales] Cannot read ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+
+  let doc: unknown;
+  try {
+    doc = parse(raw);
+  } catch (err) {
+    throw new Error(
+      `[locales] YAML parse error in ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+
+  if (!doc || typeof doc !== "object") {
+    throw new Error(
+      `[locales] ${filePath}: expected a YAML mapping at the top level`,
+    );
+  }
+
+  const top = doc as Record<string, unknown>;
+  const product = top["product"];
+
+  const p =
+    product && typeof product === "object"
+      ? (product as Record<string, unknown>)
+      : {};
+
+  const defaultLocale =
+    typeof p["default_locale"] === "string" ? p["default_locale"] : "en";
+
+  const rawLocales = p["locales"];
+
+  if (rawLocales === undefined || rawLocales === null) {
+    return ["en"];
+  }
+
+  if (!Array.isArray(rawLocales)) {
+    throw new Error(
+      `[locales] ${filePath}: product.locales must be an array, got ${typeof rawLocales}`,
+    );
+  }
+
+  if (rawLocales.length === 0) {
+    throw new Error(
+      `[locales] ${filePath}: product.locales must be a non-empty array (got empty array)`,
+    );
+  }
+
+  for (const entry of rawLocales) {
+    if (typeof entry !== "string") {
+      throw new Error(
+        `[locales] ${filePath}: product.locales entries must be strings, got ${typeof entry}`,
+      );
+    }
+    if (!BCP47_RE.test(entry)) {
+      throw new Error(
+        `[locales] ${filePath}: product.locales entry "${entry}" is not a valid BCP-47 locale tag (expected format: xx or xx-XX)`,
+      );
+    }
+  }
+
+  const locales = rawLocales as string[];
+
+  if (!locales.includes(defaultLocale)) {
+    throw new Error(
+      `[locales] ${filePath}: product.default_locale "${defaultLocale}" is not in product.locales [${locales.join(", ")}]`,
+    );
+  }
+
+  return [...locales].sort();
+}
+
+/**
+ * Read the project's default locale from project.yaml. Mirrors `readLocales`
+ * resolution and fallback semantics. Returns `"en"` when project.yaml is
+ * absent or `product.default_locale` is unset — same default as the adapter.
+ */
+export function readDefaultLocale(cwd = process.cwd()): string {
+  const filePath = resolveProjectYamlPath(cwd);
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch {
+    return "en";
+  }
+
+  let doc: unknown;
+  try {
+    doc = parse(raw);
+  } catch {
+    return "en";
+  }
+
+  if (!doc || typeof doc !== "object") return "en";
+  const product = (doc as Record<string, unknown>)["product"];
+  if (!product || typeof product !== "object") return "en";
+  const defaultLocale = (product as Record<string, unknown>)["default_locale"];
+  return typeof defaultLocale === "string" ? defaultLocale : "en";
+}
+
+/**
+ * Resolve the validated locale to pass to the adapter.
+ *
+ * Allowlist enforcement at the API boundary (AC-i18n-07): if `requested` is
+ * not in `readLocales()`, silently fall back to the project's `default_locale`.
+ * The adapter still applies its own regex check as defense-in-depth.
+ *
+ * `readLocales` failures (project.yaml absent / malformed) degrade gracefully
+ * to a default-locale-only allowlist.
+ */
+export function resolveLocale(requested: string | undefined): string {
+  const defaultLocale = readDefaultLocale();
+  if (requested === undefined) return defaultLocale;
+
+  let allow: string[];
+  try {
+    allow = readLocales();
+  } catch {
+    allow = [defaultLocale];
+  }
+
+  return allow.includes(requested) ? requested : defaultLocale;
+}
+
+/**
+ * Probe likely locations for project.yaml. Apps run from their own dirs in
+ * dev/build (`apps/api/`, `apps/mcp/`) but from repo root in some test setups.
+ */
+function resolveProjectYamlPath(cwd: string): string {
+  // Most common case — cwd is repo root, or cwd is an app dir (./../../project.yaml).
+  // Probe in order: cwd, ../, ../../.
+  const candidates = [
+    join(cwd, "project.yaml"),
+    join(cwd, "..", "project.yaml"),
+    join(cwd, "..", "..", "project.yaml"),
+  ];
+  for (const candidate of candidates) {
+    try {
+      readFileSync(candidate, "utf8");
+      return candidate;
+    } catch {
+      // continue
+    }
+  }
+  // Fall back to the cwd-relative path so the caller's error references the
+  // expected location.
+  return candidates[0] ?? join(cwd, "project.yaml");
+}

package/templates/apps/api/src/lib/outbound-http.ts

@@ -0,0 +1,122 @@
+/**
+ * Outbound HTTP wrapper — fetch with default timeout + SSRF allow-list.
+ *
+ * Every outbound HTTP call originating from `apps/api/src/lib/**` SHOULD route
+ * through this wrapper. Two guarantees:
+ *
+ *   1. Default 10s timeout via `AbortSignal.timeout(timeoutMs)`. Overridable
+ *      per call. Without this, a hung peer can pin a Fastify worker
+ *      indefinitely.
+ *
+ *   2. SSRF allow-list — RFC 1918 / loopback / link-local / metadata-service
+ *      addresses are rejected before the fetch is issued. Without this, a
+ *      user-influenced URL (webhook config, license-refresh endpoint, etc.)
+ *      can probe cloud-provider metadata endpoints (169.254.169.254 →
+ *      cloud IAM credentials) or pivot into the cluster network.
+ *
+ * The wrapper is forward-looking — `apps/api/src/lib` has no outbound fetch
+ * callsites in this PR. Subsequent issues that introduce them MUST use this
+ * wrapper. Direct `globalThis.fetch` in `apps/api/src/lib/**` is a recon
+ * finding waiting to happen.
+ *
+ * Test-mode escape hatch — `allowPrivate: true` suppresses the SSRF gate.
+ * Use only for explicit, internal-by-design traffic (typically tests).
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export type OutboundFetchOptions = RequestInit & {
+  /** Override the default 10s timeout. */
+  timeoutMs?: number;
+  /**
+   * Suppress the SSRF allow-list — test-mode escape hatch only.
+   * NEVER pass true for user-controlled URLs.
+   */
+  allowPrivate?: boolean;
+};
+
+/**
+ * Returns true if the URL should be blocked by the SSRF allow-list.
+ * Pure — no side effects, no fetch issued.
+ *
+ * Blocked:
+ *   - Non-HTTP(S) schemes (file:, javascript:, gopher:, ftp:, …)
+ *   - Unparseable URLs
+ *   - Hostnames that resolve syntactically to RFC 1918 / loopback / link-local
+ *     IPv4 ranges, IPv6 loopback (::1), or the wildcard 0.0.0.0
+ *   - The literal hostname "localhost"
+ *
+ * NOT covered (out of scope for syntactic check):
+ *   - DNS rebinding (host resolves to a public IP at check time, then to a
+ *     private IP at fetch time). A defense for this would resolve the
+ *     hostname here and bind the fetch to the resolved IP — significant
+ *     extra complexity, deferred.
+ */
+export function ssrfBlocked(rawUrl: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return true;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return true;
+  }
+
+  // Node's URL.hostname for IPv6 keeps the brackets (e.g. "[::1]"). Strip
+  // them so the literal-loopback comparison works.
+  const rawHost = parsed.hostname.toLowerCase();
+  const host =
+    rawHost.startsWith("[") && rawHost.endsWith("]")
+      ? rawHost.slice(1, -1)
+      : rawHost;
+
+  if (host === "localhost") return true;
+  if (host === "0.0.0.0") return true;
+
+  // IPv6 loopback (bracketed in URL form)
+  if (host === "::1") return true;
+
+  // IPv4 dotted-quad check
+  const ipv4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4) {
+    const [a, b] = [Number(ipv4[1]), Number(ipv4[2])];
+    if (a === 127) return true; // 127.0.0.0/8 — loopback
+    if (a === 10) return true; // 10.0.0.0/8 — RFC 1918
+    if (a === 169 && b === 254) return true; // 169.254.0.0/16 — link-local (incl. AWS metadata)
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 — RFC 1918
+    if (a === 192 && b === 168) return true; // 192.168.0.0/16 — RFC 1918
+  }
+
+  return false;
+}
+
+/**
+ * Performs an outbound fetch with timeout + SSRF allow-list enforcement.
+ *
+ * Throws synchronously (well, rejects) before any network call when:
+ *   - The URL fails the SSRF check (and `allowPrivate` is not true)
+ *
+ * Rejects with an AbortError when the per-call timeout fires.
+ */
+export async function outboundFetch(
+  url: string,
+  init: OutboundFetchOptions = {},
+): Promise<Response> {
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    allowPrivate = false,
+    ...rest
+  } = init;
+
+  if (!allowPrivate && ssrfBlocked(url)) {
+    throw new Error(
+      `outbound-http: SSRF allow-list blocked URL (disallowed: private/loopback/link-local/non-HTTP)`,
+    );
+  }
+
+  const signal = rest.signal ?? AbortSignal.timeout(timeoutMs);
+
+  return globalThis.fetch(url, { ...rest, signal });
+}

package/templates/apps/api/src/lib/prisma.ts

@@ -0,0 +1,21 @@
+/**
+ * PrismaClient singleton for the local auth database.
+ * Business data (leads, orders, analytics) lives on the Platform, not here.
+ */
+import { PrismaClient } from '@working-theory/database';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+declare global {
+  var prisma: PrismaClient | undefined;
+}
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
+
+export const prisma = globalThis.prisma || new PrismaClient({
+  adapter,
+  log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.prisma = prisma;
+}

package/templates/apps/api/src/lib/require-paid-tier.ts

@@ -0,0 +1,53 @@
+/**
+ * Paid-tier license guard for apps/api content-write routes (D14a Stage 0).
+ *
+ * Calls `checkLicense()` from @working-theory/license; on free tier emits a 402 with the
+ * canonical `payment_required` shape from `./errors.ts`. Paid tier proceeds.
+ * Network/refresh failures inside checkLicense() degrade gracefully to free
+ * (per ADR 0014 — local-verify, no remote-validate path).
+ *
+ * Usage as Fastify preHandler:
+ *
+ *   fastify.post("/path", { preHandler: requirePaidTier }, handler);
+ *
+ * Or composed with other preHandlers:
+ *
+ *   fastify.post("/path", {
+ *     preHandler: [requirePaidTier, ...others],
+ *   }, handler);
+ *
+ * The handler returns nothing (void) on pro and short-circuits with reply.send
+ * on free, matching Fastify's preHandler contract.
+ */
+
+import { checkLicense } from "@working-theory/license";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { paymentRequiredError } from "./errors.js";
+
+const FREE_TIER_MESSAGE =
+  "This endpoint requires a paid license. Visit https://ailaunchkit.ai to upgrade.";
+
+export async function requirePaidTier(
+  _request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  let result;
+  try {
+    result = await checkLicense();
+  } catch {
+    // Per ADR 0014 — license verification is local; an exception here means a
+    // bug, not a network failure. Treat as free for safe-by-default gating.
+    const err = paymentRequiredError(FREE_TIER_MESSAGE);
+    return reply.status(err.status).send(err.body);
+  }
+
+  // Revoked paid licenses keep verifying until JWT exp (up to 24h after the
+  // server reports `revoked`). Closing the gate when `revoked === true`
+  // shrinks that window to "next request" without waiting for exp. See
+  // packages/license/src/types.ts § LicenseResult and ADR 0014.
+  if (result.revoked === true || result.tier === "free") {
+    const err = paymentRequiredError(FREE_TIER_MESSAGE);
+    return reply.status(err.status).send(err.body);
+  }
+}

package/templates/apps/api/src/lib/stripe.ts

@@ -0,0 +1,30 @@
+/**
+ * apps/api Stripe shim.
+ *
+ * Re-exports @working-theory/stripe-client's public surface for use by routes and
+ * services under apps/api. This is the SOLE Stripe-touching file in apps/api.
+ *
+ * Future routes import from here (`from '../lib/stripe'`), not directly from
+ * '@working-theory/stripe-client' — single chokepoint for AILK-internal ergonomics
+ * (logger context, request-id propagation) without touching every consumer.
+ */
+export {
+  assertSandboxKey,
+  createCheckoutSession,
+  getStripeClient,
+  STRIPE_API_VERSION,
+  StripeConfigError,
+  StripeWebhookSignatureError,
+  UnknownProductCodeError,
+  verifyWebhookSignature,
+  WEBHOOK_TOLERANCE_SECONDS,
+} from "@working-theory/stripe-client";
+
+export type {
+  CreateCheckoutSessionInput,
+  CreateCheckoutSessionOutput,
+  CreateCheckoutSessionParams,
+  Stripe,
+  StripeCheckoutSession,
+  StripeWebhookEvent,
+} from "@working-theory/stripe-client";

package/templates/apps/api/src/lib/webhook-idempotency.ts

@@ -0,0 +1,92 @@
+/**
+ * Webhook idempotency store — in-memory dedup of Stripe `event.id` values.
+ *
+ * Stripe guarantees at-least-once delivery; the same `event.id` can arrive
+ * multiple times (network retries, manual dashboard replay, webhook URL
+ * reconfiguration). We persist seen event IDs for a bounded window so the
+ * second arrival short-circuits before any side effect fires.
+ *
+ * IMPLEMENTATION CHOICE — module-scoped Map, NOT a database table:
+ *
+ *   The S14 spec mentioned a `StripeEventLog` table for durability across
+ *   restarts. We chose an in-process Map for the OSS v1 release because:
+ *
+ *   1. AILK ships as a single-replica template (see middleware/rate-limit.ts
+ *      § "SINGLE-REPLICA CAVEAT" for the same reasoning applied to per-IP
+ *      rate limits — both modules share the deployment-shape assumption).
+ *   2. Stripe retries within a bounded window (~3 days). A TTL-bounded Map
+ *      covers practical replay traffic; the worst-case loss after a process
+ *      restart is "an event we already successfully processed re-fires
+ *      telemetry once," which is itself idempotent (analytics is dedup-safe).
+ *   3. Avoiding a schema migration here keeps S14 isolated from the recent
+ *      #587 Better Auth schema work and the prisma-client test mocks.
+ *
+ *   A durable swap (Redis or DB-backed) is the right answer for multi-replica
+ *   deployments. Tracked as a follow-up; the consumer-facing contract
+ *   (`hasSeen` / `markSeen`) is unchanged, so the swap is a drop-in.
+ *
+ * Eviction strategy: lazy — every insert past the soft cap (10k entries)
+ * triggers a sweep that drops entries older than `IDEMPOTENCY_TTL_MS`.
+ */
+
+export const IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1_000; // 24h — well above Stripe's retry horizon
+const SOFT_CAP = 10_000;
+
+type Entry = {
+  insertedAtMs: number;
+};
+
+const store = new Map<string, Entry>();
+let insertsSinceLastSweep = 0;
+const SWEEP_INTERVAL_INSERTS = 1_000;
+
+function sweepExpired(nowMs: number): void {
+  for (const [eventId, entry] of store) {
+    if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
+      store.delete(eventId);
+    }
+  }
+  insertsSinceLastSweep = 0;
+}
+
+/**
+ * Returns true if this `eventId` was already marked seen within the TTL window.
+ * Lazily evicts the entry if its TTL has expired (so callers see fresh state).
+ */
+export function hasSeen(eventId: string, nowMs: number = Date.now()): boolean {
+  const entry = store.get(eventId);
+  if (!entry) return false;
+  if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
+    store.delete(eventId);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Records `eventId` as seen at the given timestamp. Idempotent — re-marking
+ * a known event leaves the original insertedAtMs (so TTL is anchored to first
+ * sighting, not most-recent retry).
+ */
+export function markSeen(eventId: string, nowMs: number = Date.now()): void {
+  if (!store.has(eventId)) {
+    store.set(eventId, { insertedAtMs: nowMs });
+  }
+
+  insertsSinceLastSweep += 1;
+  if (
+    store.size > SOFT_CAP ||
+    insertsSinceLastSweep >= SWEEP_INTERVAL_INSERTS
+  ) {
+    sweepExpired(nowMs);
+  }
+}
+
+/**
+ * Test-only reset. Clears all dedup state between test cases so they do not
+ * interfere with each other.
+ */
+export function __resetIdempotencyStore(): void {
+  store.clear();
+  insertsSinceLastSweep = 0;
+}

package/templates/apps/api/src/middleware/__tests__/adversarial/bearer-token-format.test.ts

@@ -0,0 +1,111 @@
+/**
+ * @file bearer-token-format.test.ts (S13 adversarial)
+ *
+ * Adversarial Authorization-header parsing coverage on the bearer path.
+ * The baseline `auth.bearer-path.test.ts` asserts that `NotBearer x` rejects.
+ * This file extends with the malformed-input matrix from S13 §3:
+ *
+ *   - Wrong scheme (`Token foo`, `Basic xyz`).
+ *   - Missing token after `Bearer ` → 401.
+ *   - Leading or trailing whitespace inside the header.
+ *   - Bearer with embedded control characters → 401.
+ *   - Lowercase `bearer` is treated as valid (RFC 7235 — schemes are
+ *     case-insensitive), but still requires a non-empty token.
+ *   - Two `Bearer ` prefixes (`Bearer Bearer xyz`) — the second word is
+ *     taken as the token (well-formed per the regex), but adversarial code
+ *     trying to smuggle "Bearer" inside the token should still produce a
+ *     DB miss → 401.
+ */
+
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    apiToken: {
+      findUnique: jest.fn(),
+      update: jest.fn().mockResolvedValue(undefined),
+    },
+  },
+}));
+
+import { prisma } from "../../../lib/prisma.js";
+import { authPreHandlerPlugin } from "../../auth.js";
+
+function buildApp(): FastifyInstance {
+  const app = Fastify();
+  app.register(authPreHandlerPlugin, {
+    frontendOrigin: "https://app.example.com",
+  });
+  app.get("/echo", async (req) => ({ userId: req.userId ?? null }));
+  return app;
+}
+
+describe("S13 adversarial — bearer token format", () => {
+  let app: FastifyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it.each([
+    ["wrong scheme — Token", "Token abc123"],
+    ["wrong scheme — Basic", "Basic dXNlcjpwYXNz"],
+    ["empty token after Bearer", "Bearer "],
+    ["only the scheme word", "Bearer"],
+  ])("rejects %s and never queries the token table", async (_label, header) => {
+    app = buildApp();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/echo",
+      headers: { authorization: header },
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(JSON.parse(res.body)).toEqual({ error: "unauthorized" });
+    expect(prisma.apiToken.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("accepts the case-insensitive scheme but still rejects an unknown token", async () => {
+    (prisma.apiToken.findUnique as jest.Mock).mockResolvedValue(null);
+
+    app = buildApp();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/echo",
+      headers: { authorization: "bearer abc" },
+    });
+
+    expect(res.statusCode).toBe(401);
+    // Lowercase scheme matched; lookup happened; token unknown → 401.
+    expect(prisma.apiToken.findUnique).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats `Bearer Bearer x` as a normal token value and rejects on miss", async () => {
+    (prisma.apiToken.findUnique as jest.Mock).mockResolvedValue(null);
+
+    app = buildApp();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/echo",
+      headers: { authorization: "Bearer Bearer x" },
+    });
+
+    // The regex anchors `^Bearer\s+(\S+)$`; "Bearer x" is two tokens, so the
+    // header does NOT match the single-token shape → 401 before any DB hit.
+    expect(res.statusCode).toBe(401);
+    expect(prisma.apiToken.findUnique).not.toHaveBeenCalled();
+  });
+});