create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/lib/rate-limit-store.ts

@@ -1,142 +0,0 @@
-/**
- * The rate limiter's database store (#5040 D1/D3/D4). Counts a bucket in
- * `rate_limit_counters` so one visitor's limit holds across every concurrent
- * isolate on a deployment with a database — see
- * `apps/api/src/middleware/rate-limit.ts`'s `SHARED STORE` header for the
- * full picture (what this protects against, and what it does not).
- *
- * The only file naming `rate_limit_counters` outside `database/`. All SQL is
- * `db.$queryRaw` / `db.$executeRaw` tagged templates — never `…Unsafe` — so
- * every value is a bound parameter, never string-interpolated.
- */
-import { createHash } from "node:crypto";
-
-import type { Prisma } from "@working-theory/database";
-
-/** One bucket's state, as both the memory and database stores report it. */
-export type RateLimitBucket = {
-  count: number;
-  windowStartMs: number;
-};
-
-/** What a store call reports when it ran against a backing database. */
-export type RateLimitStore = {
-  /** Count one request against `key`'s visitor bucket. */
-  hit(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
-  /** Count one request against `key`'s forwarding-key bucket (#7394 DD-8). */
-  hitKey(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
-  /** True when `key` has a bucket whose window has not yet ended. */
-  hasOpenWindow(key: string, now: number, windowMs: number): Promise<boolean>;
-  /** Evict expired buckets. `reason` is why the sweep fired (D6). */
-  sweep(now: number, windowMs: number, reason: "interval" | "limited"): Promise<void>;
-};
-
-/** What `createDatabaseRateLimitStore` needs of a Prisma client (D3). */
-export type RateLimitSqlClient = Pick<
-  Prisma.TransactionClient,
-  "$queryRaw" | "$executeRaw"
->;
-
-function sha256Hex(value: string): string {
-  return createHash("sha256").update(value).digest("hex");
-}
-
-/**
- * The database store (D1/D3): one atomic upsert per hit, same window rules as
- * the memory store. `bucketKey` is the exact string the memory store uses as
- * its Map key; this store hashes it before it ever reaches SQL (FR-5) — the
- * table never holds a plaintext IP or bucket key.
- */
-export function createDatabaseRateLimitStore(
-  db: RateLimitSqlClient,
-): RateLimitStore {
-  async function countHit(
-    bucketKey: string,
-    now: number,
-    windowMs: number,
-  ): Promise<RateLimitBucket> {
-    const hash = sha256Hex(bucketKey);
-    const rows = await db.$queryRaw<
-      Array<{ count: number; window_start_ms: bigint | string }>
-    >`
-      INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count")
-      VALUES (${hash}, ${now}::bigint, ${windowMs}::integer, 1)
-      ON CONFLICT ("key_hash") DO UPDATE SET
-        "count" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
-                       THEN 1 ELSE "rate_limit_counters"."count" + 1 END,
-        "window_start_ms" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
-                       THEN ${now}::bigint ELSE "rate_limit_counters"."window_start_ms" END,
-        "window_ms" = ${windowMs}::integer
-      RETURNING "count", "window_start_ms"
-    `;
-    const row = rows[0];
-    if (!row) {
-      throw new Error("rate_limit_counters upsert returned no row");
-    }
-    return {
-      count: Number(row.count),
-      windowStartMs: Number(row.window_start_ms),
-    };
-  }
-
-  async function hasOpenWindow(
-    bucketKey: string,
-    now: number,
-    windowMs: number,
-  ): Promise<boolean> {
-    const hash = sha256Hex(bucketKey);
-    const rows = await db.$queryRaw<Array<{ one: number }>>`
-      SELECT 1 AS "one" FROM "rate_limit_counters"
-      WHERE "key_hash" = ${hash}
-        AND ${now}::bigint - "window_start_ms" < ${windowMs}::integer
-      LIMIT 1
-    `;
-    return rows.length > 0;
-  }
-
-  return {
-    hit: (key, now, windowMs) => countHit(key, now, windowMs),
-    hitKey: (key, now, windowMs) => countHit(key, now, windowMs),
-    hasOpenWindow,
-    async sweep(now, _windowMs, reason) {
-      // D6 — the database store sweeps on the interval trigger only. Sweeping
-      // on every 429 would let an attacker buy a table scan per refused
-      // request.
-      if (reason !== "interval") return;
-      await db.$executeRaw`
-        DELETE FROM "rate_limit_counters"
-        WHERE "window_start_ms" + "window_ms" <= ${now}::bigint
-      `;
-    },
-  };
-}
-
-/**
- * Which store a registration with no explicit `store` option uses (D4),
- * resolved once per process and memoized by the middleware. `warn` is called
- * exactly once for each of the two misconfiguration rows below.
- */
-export type RateLimitStoreEnv = {
-  DATABASE_URL?: string | undefined;
-  AILK_RATE_LIMIT_STORE?: string | undefined;
-};
-
-export function resolveRateLimitStoreKind(
-  env: RateLimitStoreEnv,
-  warn: (msg: string) => void,
-): "memory" | "database" {
-  const hasDatabase = !!env.DATABASE_URL;
-  const raw = env.AILK_RATE_LIMIT_STORE;
-
-  if (raw === undefined || raw === "") {
-    return hasDatabase ? "database" : "memory";
-  }
-  if (raw === "memory") return "memory";
-  if (raw === "database") {
-    if (hasDatabase) return "database";
-    warn("AILK_RATE_LIMIT_STORE=database needs DATABASE_URL; using memory");
-    return "memory";
-  }
-  warn("AILK_RATE_LIMIT_STORE is not memory or database and is ignored");
-  return hasDatabase ? "database" : "memory";
-}

package/templates/apps/api/src/lib/require-commerce-claim.ts

@@ -1,250 +0,0 @@
-/**
- * Commerce license-claim guard for the commerce PRIMITIVES that live in the
- * base tree (DECISION-LOG D-64, epic #5770, #5796).
- *
- * The checkout launcher, the Stripe webhook receiver, customer mapping and
- * `lib/stripe.ts` ship unconditionally now — they are no longer registered
- * behind `isModuleEnabled("commerce")`. What decides whether they SERVE is the
- * JWT `features[]` claim `commerce`, read at CALL time through `checkLicense()`
- * from `@working-theory/license`.
- *
- * This is the same shape as `./require-paid-tier.ts` — that file is the
- * PATTERN, not the code (D-64): this gate reads
- * `result.features.includes("commerce")` and never looks at `result.tier` as
- * the claim test. A `commerce` claim can ride any paid level, so a tier test
- * would be the wrong question.
- *
- * Response without the claim: the SAME module-disabled response the
- * module-conditional path produced — a 404. `server.ts`'s root-endpoint
- * comment (§ `deriveRootEndpoints`) documents that a build with commerce off
- * simply does not advertise these routes and answers 404 on them, and
- * `src/__tests__/module-exclusion.test.ts` measures exactly that status. The
- * body is `notFoundError()` from `./errors.ts` — this repo's one reusable 404
- * body — rather than a newly invented `module_disabled` code, which exists
- * nowhere in the tree. The message deliberately does not mention commerce: a
- * site without the claim is indistinguishable from a site built without the
- * module, which is the point.
- *
- * ── TRI-STATE, not a boolean ────────────────────────────────────────────────
- *
- * Security review 2026-09-16, High; widened by the operator in round 2. A
- * single `false` for "no claim" and "could not tell" is a data-loss bug on the
- * webhook: a signed `checkout.session.completed` on a live commerce site whose
- * licence read merely FAILED would be acked 200 and dropped, Stripe would
- * record success and never retry, and the charge would never be mapped.
- *
- * So `resolveCommerceClaim()` answers `claimed | unclaimed | undetermined`:
- *
- *   claimed      — read successfully; `features[]` carries `commerce`.
- *   unclaimed    — a positively-established "no": either a licence that reads
- *                  successfully and simply lacks the claim, or a KEYLESS
- *                  deployment that configures no licence at all.
- *   undetermined — the read established no "no". These states reach it:
- *                    1. `checkLicense()` threw.
- *                    2. `revoked === true` — a revoked licence is still a
- *                       PAYING site inside its JWT window (ADR 0014).
- *                    3. a licence IS configured yet resolves free — the JWT
- *                       expired, or no longer verifies.
- *                    4. (3) also absorbs a configured-but-unparseable key.
- *                    5. the licence STORAGE FILE could not be read — EACCES,
- *                       EIO, EMFILE, a directory at its path (#5820).
- *
- * Why (3) needs the env read. `checkLicense()` returns the SAME `FREE_RESULT`
- * for expired, invalid and keyless alike (`check-license.ts` — `expiresAt` is
- * `null` and `revoked` is `false` in all three), so nothing on `LicenseResult`
- * separates "this deployment's licence stopped verifying" from "this
- * deployment never had one". The one signal that does is whether a licence is
- * CONFIGURED at all, which is an env read this app already makes elsewhere
- * (`services/enrichment-shim.ts`). No JWT is parsed here and no verification
- * is re-implemented — presence is the entire test.
- *
- * ── The storage file, read for what it actually says (#5820) ────────────────
- *
- * A licence sourced from the refresh STORAGE FILE is covered on both axes.
- * `readStoredJwtState()` — added to `@working-theory/license` for this gate —
- * answers `absent | unreadable | present` where `readStoredJwt()` answered one
- * `null` for the first two. Only `absent` (no file, or a file holding nothing
- * but whitespace) is evidence that a deployment is unlicensed; a file that
- * merely could not be READ is evidence of nothing, so it holds. An EXPIRED
- * storage licence (`present`, resolving free) holds too.
- *
- * Before that distinction existed, a transient EACCES on a storage-licensed
- * site read as keyless: a signed `checkout.session.completed` arriving in that
- * window was acked 200, Stripe never redelivered it, and the charge was never
- * mapped. `readStoredJwt()`'s own contract is untouched — `checkLicense()` and
- * every other caller still see `null` for both states.
- *
- * ── Why the two routes answer differently ───────────────────────────────────
- *
- * The checkout launcher answers the module-disabled 404 on BOTH non-serving
- * states: a checkout that cannot be started loses nothing, so there is no call
- * to leak a "configured but unreadable" shape on it. The webhook receiver
- * holds an `undetermined` event with a retryable 503 + `Retry-After`, because
- * by the time it arrives the buyer's money has already moved.
- *
- * Usage as a Fastify preHandler (the checkout launcher):
- *
- *   fastify.post("/path", { preHandler: requireCommerceClaim }, handler);
- *
- * The Stripe webhook receiver does NOT use the preHandler: D3 puts signature
- * verification BEFORE the claim check, so it consults `resolveCommerceClaim()`
- * from inside its handler. See `routes/webhooks/README.md` § Commerce claim.
- */
-
-import {
-  checkLicense,
-  readStoredJwtState,
-  type ProFeature,
-} from "@working-theory/license";
-import type { FastifyReply, FastifyRequest } from "fastify";
-
-import { notFoundError } from "./errors.js";
-
-/** The claim the commerce primitives serve behind (`ProFeature`, verify-jwt.ts). */
-export const COMMERCE_FEATURE: ProFeature = "commerce";
-
-const MODULE_DISABLED_MESSAGE = "Not found";
-
-/**
- * What the licence read actually established. See the header for the four
- * states that reach `undetermined`.
- */
-export type CommerceClaimState = "claimed" | "unclaimed" | "undetermined";
-
-/** The module-disabled response — a 404, the canonical `not_found` body. */
-export function commerceDisabledResponse() {
-  return notFoundError(MODULE_DISABLED_MESSAGE);
-}
-
-/**
- * The retryable answer for `undetermined` on the webhook. A local error
- * vocabulary (`{ error: "..." }`), matching what `routes/webhooks/stripe.ts`
- * already emits for its own failure modes, rather than `errors.ts`'s closed
- * `ErrorCode` set, which has no service-unavailable member and whose MCP twin
- * would have to grow one too.
- *
- * `Retry-After` is in SECONDS and is read by Stripe: five minutes is long
- * enough for a transient licence-read failure or a refresh round-trip to
- * clear, and short enough that a queued `checkout.session.completed` is mapped
- * well inside Stripe's three-day redelivery window.
- */
-export const LICENSE_UNDETERMINED_STATUS = 503;
-export const LICENSE_UNDETERMINED_BODY = { error: "license-undetermined" };
-export const LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS = 300;
-
-/**
- * What this deployment's licence CONFIGURATION says — three answers, not two.
- *
- *   configured — an env key is set, or the storage file holds a token.
- *   absent     — no env key, and the storage file is genuinely not there (or
- *                holds nothing but whitespace). The only state that is
- *                evidence of an unlicensed site.
- *   unreadable — no env key, and the storage file could not be read at all.
- *
- * Presence only — the token is never parsed, verified or logged. This is the
- * one signal that separates an EXPIRED/unverifiable licence from a keyless
- * site, because `checkLicense()` collapses both into the same free result.
- *
- * It asks the question the SAME WAY `check-license.ts#resolveToken` does —
- * `AILK_LICENSE_KEY`, else the refresh storage file — because that is where
- * `checkLicense()` itself just looked. An env-only test would miss a
- * deployment licensed purely from storage, so an EXPIRED storage licence would
- * read as keyless and its already-charged events would be dropped.
- *
- * `unreadable` is kept separate from `absent` rather than folded into
- * `configured` so the caller can LOG why it is holding (#5820): "this site has
- * no licence" and "this site's licence could not be read" are different
- * operator problems, and only the first is a fact.
- */
-type LicenseConfigurationState = "configured" | "absent" | "unreadable";
-
-async function resolveLicenseConfiguration(): Promise<LicenseConfigurationState> {
-  const key = process.env["AILK_LICENSE_KEY"];
-  if (typeof key === "string" && key.length > 0) return "configured";
-
-  const stored = await readStoredJwtState();
-  if (stored.state === "present") return "configured";
-  if (stored.state === "absent") return "absent";
-
-  // `console.warn` rather than a request logger: `resolveCommerceClaim()` is
-  // called from the webhook handler with no logger threaded through, and the
-  // routes are out of scope for this change. The cause's `code` is the whole
-  // point of the line — EACCES and EISDIR are different operator fixes. The
-  // token is never in scope here, so nothing secret can reach the log.
-  const code =
-    (stored.cause as NodeJS.ErrnoException | undefined)?.code ?? "UNKNOWN";
-  console.warn(
-    "commerce-claim: licence storage file unreadable — holding rather than dropping",
-    { outcome: "license_storage_unreadable", code },
-  );
-  return "unreadable";
-}
-
-/**
- * Resolve what this deployment's licence says about `commerce`.
- *
- * Never throws: a failed read is a state, not an exception, because both
- * callers must be able to tell "no" from "could not tell".
- */
-export async function resolveCommerceClaim(): Promise<CommerceClaimState> {
-  let result;
-  try {
-    result = await checkLicense();
-  } catch {
-    // The read FAILED. Not a "no" — callers hold rather than drop.
-    return "undetermined";
-  }
-
-  // A revoked licence keeps verifying locally until JWT `exp` (ADR 0014), so
-  // this is a PAYING commerce site mid-window whose events are still real.
-  // Closing the gate is right; DROPPING them is the security review's High
-  // under a different label.
-  if (result.revoked === true) return "undetermined";
-
-  if (result.features.includes(COMMERCE_FEATURE)) return "claimed";
-
-  if (result.tier === "free") {
-    const configuration = await resolveLicenseConfiguration();
-    // A licence is configured yet resolved free: expired, or no longer
-    // verifying. `checkLicense()` cannot say which, and neither is a "no".
-    if (configuration === "configured") return "undetermined";
-    // The storage file could not be read (#5820). An unreadable file is not
-    // evidence of a keyless site, and dropping a signed Stripe event needs
-    // evidence — so this holds and Stripe retries.
-    if (configuration === "unreadable") return "undetermined";
-    // `absent` — no env key and no storage file. A positively-established
-    // "no", and the only state on this path that may drop an event.
-  }
-
-  return "unclaimed";
-}
-
-/**
- * Fastify preHandler for the checkout launcher: serve only with the claim.
- *
- * Both non-serving states answer the module-disabled 404 — see the header:
- * an unstartable checkout loses nothing, so the route stays indistinguishable
- * from a build without the module rather than advertising that a licence
- * exists but could not be read. The `undetermined` case is still logged, so
- * an operator can tell a lapsed licence from a deliberate free build.
- *
- * Returns void (proceed) with the claim and short-circuits with `reply.send`
- * otherwise, matching Fastify's preHandler contract.
- */
-export async function requireCommerceClaim(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const state = await resolveCommerceClaim();
-  if (state === "claimed") return;
-
-  if (state === "undetermined") {
-    request.log.warn(
-      { outcome: "license_undetermined" },
-      "commerce licence could not be read — checkout answering the module-disabled response",
-    );
-  }
-
-  const err = commerceDisabledResponse();
-  return reply.status(err.status).send(err.body);
-}

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

@@ -1,53 +0,0 @@
-/**
- * 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);
-  }
-}