create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/services/usage-credits.ts

@@ -1,340 +0,0 @@
-/**
- * @file usage-credits.ts
- * @description Credit consumption waterfall (FEAT-047 P3.S1 — buckets 1-2).
- * Spec: docs/specs/3730-credit-waterfall-atomicity-spec.md (hardening pass over
- * the original docs/specs/3706-s1-credit-waterfall-service-spec.md).
- *
- * Charges a billed cost across the two non-overage buckets, in order:
- *   1. included plan credits
- *   2. carry-forward credit balance
- * Bucket 3 (on-demand overage, pre-charge, spend limit) is P4 — this service
- * leaves `onDemandPortionCents = 0` and returns any remainder as
- * `uncoveredCents` rather than throwing. The caller (P2.S1's
- * `recordUsageEvent`) stamps the returned split back onto the UsageEvent row —
- * this service owns balances only.
- *
- * ─── The four invariants this file must hold (#3730) ────────────────────────
- * The original implementation shipped unreviewed and violated all four. Each
- * carries a test that fails without its fix (usage-credits.test.ts).
- *
- *  1. THE DEBIT IS ATOMIC (H1). The balance write is a conditional
- *     `updateMany` COMPARE-AND-SWAP whose `where` carries every column value
- *     the read observed; a concurrent writer that moved any of them makes the
- *     predicate miss, the update match 0 rows, and this service re-read,
- *     recompute, and retry (bounded — then `conflict`).
- *
- *     ⚠️ NOT a `$transaction`. The sibling `usage-metering.ts` uses one, which
- *     makes it the locally-obvious reach — but wrapping the same
- *     read-then-write in a Read-Committed transaction does NOT fix the TOCTOU.
- *     Atomicity is not isolation. A single conditional UPDATE *is* the atomic
- *     compare-and-swap and needs no transaction: Postgres re-evaluates the
- *     `where` against the newly-committed row after the row lock releases
- *     (EvalPlanQual) — exactly the semantics required (spec D1).
- *
- *     The `where` guards the WHOLE read-set — the ALLOWANCE
- *     (`includedCreditsCents`) as well as the two counters. The debit math
- *     reads the allowance, so a concurrent plan change that moves it while the
- *     counters sit still would otherwise slip a STALE allowance past a
- *     counters-only predicate. Read-set ≡ CAS-set (spec AC-2b).
- *
- *  2. AVAILABILITY IS ZERO-CLAMPED (H3). A plan DOWNGRADE legitimately leaves
- *     `used > included`, so `included − used` goes negative — and an unclamped
- *     `Math.min(negative, cost)` INVERTS the debit: it refunds consumed
- *     allowance and drains real credits (a verified 41× overcharge). Both
- *     derived availabilities are `Math.max(0, …)`.
- *
- *  3. THE BOUNDARY IS VALIDATED (H2/H4/M1/M2). `costCents` and
- *     `organizationId` are zod-parsed BEFORE any read or math. `NaN <= 0` is
- *     `false`, so the old guard let `NaN` through; `Infinity <= 0` is `false`
- *     too, and `Infinity` yields VALID finite integers (`min(800, Infinity) =
- *     800`) that silently zero a customer's entire credit position.
- *     `z.number().int()` rejects `NaN`, `±Infinity`, and `10.5` — and `.min(0)`
- *     is a SEPARATE, REQUIRED clause, because `.int()` alone ACCEPTS `-50`.
- *
- *  4. NOTHING THROWS, NOTHING LEAKS (L1/L2). Every failure is a discriminated
- *     result. Raw DB error text is logged server-side and NEVER returned
- *     (Prisma embeds the full `data` argument — org ids, amounts), and
- *     `org_not_found` carries no org id: the house route pattern
- *     (`routes/leads/index.ts`) returns `error.message` verbatim to the client,
- *     which would make an echoed id an org-existence oracle.
- *
- * PII boundary: this service touches no PII — only organization ids and cent
- * amounts. No Stripe call (P4).
- */
-
-import { zOrganizationId, type Id } from "@working-theory/ids";
-import { z } from "zod";
-
-import { prisma } from "../lib/prisma.js";
-
-// ─── Boundary validation (H2/H4/M1/M2) ────────────────────────────────────────
-
-/**
- * An ABSURDITY ceiling, not a business limit — so a corrupt caller cannot drive
- * the debit to an absurd magnitude. $1,000,000 in cents. Mirrors
- * `MAX_TOKENS_PER_EVENT` (usage-metering.ts).
- */
-export const MAX_COST_CENTS = 100_000_000;
-
-/**
- * A cent cost: finite, integral, non-negative, bounded.
- * `.int()` rejects `NaN` and `±Infinity` (neither is an integer) and `10.5`.
- * `.min(0)` is REQUIRED SEPARATELY — `.int()` alone accepts `-50`.
- */
-const zCostCents = z
-  .number()
-  .int("costCents must be an integer")
-  .min(0, "costCents cannot be negative")
-  .max(MAX_COST_CENTS, "costCents exceeds the per-call maximum");
-
-const zConsumeInput = z.object({
-  organizationId: zOrganizationId,
-  costCents: zCostCents,
-});
-
-/** The bounded CAS retry budget (spec OQ-1). */
-const MAX_ATTEMPTS = 3;
-
-const CREDIT_SELECT = {
-  includedCreditsCents: true,
-  includedCreditsUsedCents: true,
-  onDemandCreditBalanceCents: true,
-} as const;
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-type OrganizationCreditRow = {
-  includedCreditsCents: number;
-  includedCreditsUsedCents: number;
-  onDemandCreditBalanceCents: number;
-};
-
-type CreditSplit = {
-  includedPortionCents: number;
-  creditBalancePortionCents: number;
-  onDemandPortionCents: 0;
-  uncoveredCents: number;
-};
-
-/** Every failure this service can produce — no path throws. */
-type CreditErrorKind =
-  | "invalid_input"
-  | "org_not_found"
-  | "conflict"
-  | "db_error";
-
-type CreditError = { kind: CreditErrorKind; message: string };
-
-export type ConsumeResult =
-  | ({ ok: true } & CreditSplit)
-  | { ok: false; error: CreditError };
-
-export type CreditStatusResult =
-  | {
-      ok: true;
-      includedRemaining: number;
-      creditBalance: number;
-      effectiveRemaining: number;
-    }
-  | { ok: false; error: CreditError };
-
-const ALL_ZERO: { ok: true } & CreditSplit = {
-  ok: true,
-  includedPortionCents: 0,
-  creditBalancePortionCents: 0,
-  onDemandPortionCents: 0,
-  uncoveredCents: 0,
-};
-
-// ─── Internals ────────────────────────────────────────────────────────────────
-
-function invalidInput(error: z.ZodError): { ok: false; error: CreditError } {
-  // Field names + our own messages only — never the received value.
-  const message = error.issues
-    .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
-    .join("; ");
-  return { ok: false, error: { kind: "invalid_input", message } };
-}
-
-/** L1 — no org id in the message; the route returns it verbatim to the client. */
-const ORG_NOT_FOUND: { ok: false; error: CreditError } = {
-  ok: false,
-  error: { kind: "org_not_found", message: "organization not found" },
-};
-
-/** L2 — log the detail server-side; NEVER return it (Prisma embeds `data`). */
-function dbError(
-  operation: string,
-  organizationId: Id<"organization">,
-  error: unknown,
-): { ok: false; error: CreditError } {
-  const detail = error instanceof Error ? error.message : String(error);
-  console.error("usage-credits: %s failed", operation, {
-    organizationId,
-    detail,
-  });
-  return {
-    ok: false,
-    error: { kind: "db_error", message: "credit operation failed" },
-  };
-}
-
-/**
- * The waterfall, with BOTH availabilities zero-clamped (H3). The clamp is the
- * correct expression of the invariant: a downgraded org has zero included
- * availability, so the call spills straight to carry-forward — the right
- * billing behaviour — instead of inverting the debit.
- */
-function computeSplit(
-  org: OrganizationCreditRow,
-  costCents: number,
-): CreditSplit {
-  const includedAvailable = Math.max(
-    0,
-    org.includedCreditsCents - org.includedCreditsUsedCents,
-  );
-  const includedPortionCents = Math.min(includedAvailable, costCents);
-  const remainingAfterIncluded = costCents - includedPortionCents;
-
-  const balanceAvailable = Math.max(0, org.onDemandCreditBalanceCents);
-  const creditBalancePortionCents = Math.min(
-    balanceAvailable,
-    remainingAfterIncluded,
-  );
-
-  return {
-    includedPortionCents,
-    creditBalancePortionCents,
-    onDemandPortionCents: 0,
-    uncoveredCents: remainingAfterIncluded - creditBalancePortionCents,
-  };
-}
-
-// ─── Main exports ─────────────────────────────────────────────────────────────
-
-/**
- * Charges `costCents` against `organizationId`'s included plan credits, then
- * its carry-forward credit balance (buckets 1-2). Returns the attribution
- * split; the caller stamps it onto the UsageEvent row.
- */
-export async function consumeCredits(
-  organizationId: Id<"organization">,
-  costCents: number,
-): Promise<ConsumeResult> {
-  const parsed = zConsumeInput.safeParse({ organizationId, costCents });
-  if (!parsed.success) {
-    return invalidInput(parsed.error);
-  }
-
-  // A genuinely free call — no read, no write. (A NEGATIVE cost is a caller
-  // bug and is rejected above as `invalid_input`, not treated as free.)
-  if (parsed.data.costCents === 0) {
-    return ALL_ZERO;
-  }
-
-  const { organizationId: orgId, costCents: cost } = parsed.data;
-
-  try {
-    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-      const org = await prisma.organization.findUnique({
-        where: { id: orgId },
-        select: CREDIT_SELECT,
-      });
-
-      if (!org) {
-        return ORG_NOT_FOUND;
-      }
-
-      const split = computeSplit(org, cost);
-
-      // Nothing to debit (exhausted, or a clamped-to-zero availability): the
-      // remainder is reported as uncovered and no write is needed, so there is
-      // no CAS to lose and no spurious `conflict`.
-      if (
-        split.includedPortionCents === 0 &&
-        split.creditBalancePortionCents === 0
-      ) {
-        return { ok: true, ...split };
-      }
-
-      // H1 — COMPARE-AND-SWAP. The `where` restates every value the read
-      // observed (allowance INCLUDED — spec AC-2b), so any concurrent writer
-      // makes this match 0 rows rather than committing stale amounts.
-      const { count } = await prisma.organization.updateMany({
-        where: {
-          id: orgId,
-          includedCreditsCents: org.includedCreditsCents,
-          includedCreditsUsedCents: org.includedCreditsUsedCents,
-          onDemandCreditBalanceCents: org.onDemandCreditBalanceCents,
-        },
-        data: {
-          includedCreditsUsedCents: { increment: split.includedPortionCents },
-          onDemandCreditBalanceCents: {
-            decrement: split.creditBalancePortionCents,
-          },
-        },
-      });
-
-      if (count > 0) {
-        return { ok: true, ...split };
-      }
-      // count === 0 — someone moved the row under us. Re-read and recompute.
-    }
-
-    // An honest `conflict` the caller can retry beats an unbounded spin on
-    // money code (spec OQ-1).
-    return {
-      ok: false,
-      error: {
-        kind: "conflict",
-        message: "credit balance changed concurrently; retry the request",
-      },
-    };
-  } catch (error) {
-    return dbError("debit", orgId, error);
-  }
-}
-
-/**
- * Returns the current credit standing for `organizationId` across the two P3
- * buckets. On-demand overage remaining is P4 — not surfaced here.
- *
- * Both availabilities are zero-clamped, so a downgraded org reads `0`
- * remaining rather than a negative number — consistent with what the debit
- * will actually charge.
- */
-export async function getCreditStatus(
-  organizationId: Id<"organization">,
-): Promise<CreditStatusResult> {
-  const parsed = zOrganizationId.safeParse(organizationId);
-  if (!parsed.success) {
-    return invalidInput(parsed.error);
-  }
-  const orgId = parsed.data;
-
-  try {
-    const org = await prisma.organization.findUnique({
-      where: { id: orgId },
-      select: CREDIT_SELECT,
-    });
-
-    if (!org) {
-      return ORG_NOT_FOUND;
-    }
-
-    const includedRemaining = Math.max(
-      0,
-      org.includedCreditsCents - org.includedCreditsUsedCents,
-    );
-    const creditBalance = Math.max(0, org.onDemandCreditBalanceCents);
-
-    return {
-      ok: true,
-      includedRemaining,
-      creditBalance,
-      effectiveRemaining: includedRemaining + creditBalance,
-    };
-  } catch (error) {
-    return dbError("status read", orgId, error);
-  }
-}

package/templates/apps/api/src/services/verified-email.ts

@@ -1,71 +0,0 @@
-/**
- * @file verified-email.ts
- * @description The one `User {id, email, emailVerified}` read every
- * email-keyed authorization path in `apps/api` goes through (#5701 D4).
- *
- * `emailVerified` is load-bearing wherever this codebase joins an identity to
- * data by email. An unverified address is an unproven CLAIM to the identity it
- * names: the operator pin it might match (`services/default-tenant.ts`), the
- * anonymous Lead rows it would promote (`services/lead-promotion.ts`,
- * `services/listing-promotion.ts`), the respondent rows it would read back
- * (`services/waitlist-signups.ts`, `services/flow-checkouts.ts`). Each of
- * those five sites wrote the same read and the same refusal by hand, and
- * "the same read, written six times" is exactly the shape that let #3631
- * ship a sixth one without the check.
- *
- * So the read lives here once, the refusal is inside it rather than at the
- * call site — a service-level invariant, not a caller obligation, which is
- * what makes it unbypassable by a wrong call site — and callers receive the
- * email ONLY when `emailVerified === true`. The two refusals stay distinct
- * (`user_not_found` vs `email_unverified`) because the callers map them to
- * different outcomes on the wire.
- *
- * `select` names exactly the three fields, so nothing else about the User row
- * is read on an authorization path; `tools/lint-email-authz.ts` is the
- * mechanical backstop that fails any NEW `prisma.user` read which selects
- * `email` for a decision and omits `emailVerified`.
- *
- * ONE KNOWN IMPRECISION IN THE CALLERS, deliberate and unchanged by this
- * helper. `User.email` is `@unique` in Postgres, which is byte-exact, while
- * every caller that compares the address lowercases both sides — so two
- * distinct rows (`Operator@x.com` and `operator@x.com`) could both satisfy one
- * comparison. It is not reachable today: `apps/web/auth.ts` configures social
- * providers only, so the address is provider-asserted and normalized rather
- * than caller-chosen. It becomes reachable the moment a credential provider is
- * enabled, and the durable fix is case-insensitive email uniqueness in the
- * schema (citext, or lowercase-at-write) so "matches" and "is unique" agree.
- * Matching case-sensitively instead would be worse: it would lock out an
- * operator who typed their own address with different capitalisation.
- */
-
-import { prisma } from "../lib/prisma.js";
-
-/** Why a verified-email read refused. Callers map these to their own outcomes. */
-export type VerifiedEmailRefusal = "user_not_found" | "email_unverified";
-
-export type VerifiedEmailResult =
-  | { ok: true; value: { id: string; email: string } }
-  | { ok: false; reason: VerifiedEmailRefusal };
-
-/**
- * Read the `User` row for `userId` and return its email ONLY when the address
- * is verified.
- *
- * @param userId the authenticated caller's id — never a request-supplied email.
- * @returns `{ok: true}` with the verified address, or the refusal reason.
- */
-export async function findVerifiedEmail(
-  userId: string,
-): Promise<VerifiedEmailResult> {
-  const user = await prisma.user.findUnique({
-    where: { id: userId },
-    select: { id: true, email: true, emailVerified: true },
-  });
-  if (!user) {
-    return { ok: false, reason: "user_not_found" };
-  }
-  if (user.emailVerified !== true) {
-    return { ok: false, reason: "email_unverified" };
-  }
-  return { ok: true, value: { id: user.id, email: user.email } };
-}

package/templates/apps/mcp/__tests__/abuse/daily-cap.test.ts

@@ -1,52 +0,0 @@
-/**
- * Unit tests for abuse/daily-cap.ts
- *
- * Verifies per-IP daily cap counter with configurable limit and daily reset.
- */
-
-import { DailyCapTracker } from "../../src/abuse/daily-cap.js";
-
-describe("DailyCapTracker", () => {
-  it("allows requests below the cap", () => {
-    const tracker = new DailyCapTracker(3);
-    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
-    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
-    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
-  });
-
-  it("blocks requests at and above the cap", () => {
-    const tracker = new DailyCapTracker(2);
-    tracker.isAllowed("1.2.3.4");
-    tracker.isAllowed("1.2.3.4");
-    // Third call should be blocked
-    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
-  });
-
-  it("tracks IPs independently", () => {
-    const tracker = new DailyCapTracker(1);
-    tracker.isAllowed("1.2.3.4");
-    // Exhausted for .4 but .5 is fresh
-    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
-    expect(tracker.isAllowed("1.2.3.5")).toBe(true);
-  });
-
-  it("resets counters after the daily window expires", () => {
-    jest.useFakeTimers();
-    const tracker = new DailyCapTracker(1);
-    tracker.isAllowed("1.2.3.4");
-    expect(tracker.isAllowed("1.2.3.4")).toBe(false);
-
-    // Advance 24 hours + 1ms
-    jest.advanceTimersByTime(24 * 60 * 60 * 1000 + 1);
-    expect(tracker.isAllowed("1.2.3.4")).toBe(true);
-    jest.useRealTimers();
-  });
-
-  it("uses cap=50 when none supplied", () => {
-    const tracker = new DailyCapTracker();
-    for (let i = 0; i < 50; i++) {
-      expect(tracker.isAllowed("9.9.9.9")).toBe(true);
-    }
-    expect(tracker.isAllowed("9.9.9.9")).toBe(false);
-  });
-});

package/templates/apps/mcp/__tests__/abuse/email-validator.test.ts

@@ -1,46 +0,0 @@
-/**
- * Unit tests for abuse/email-validator.ts
- *
- * Verifies RFC 5322-style email format validation used by
- * capture_lead and subscribe_newsletter abuse rules.
- */
-
-import { isValidEmail } from "../../src/abuse/email-validator.js";
-
-describe("isValidEmail", () => {
-  it("accepts a well-formed email address", () => {
-    expect(isValidEmail("jane@example.com")).toBe(true);
-  });
-
-  it("accepts email with subdomain", () => {
-    expect(isValidEmail("user@mail.example.com")).toBe(true);
-  });
-
-  it("accepts email with plus addressing", () => {
-    expect(isValidEmail("user+tag@example.com")).toBe(true);
-  });
-
-  it("rejects empty string", () => {
-    expect(isValidEmail("")).toBe(false);
-  });
-
-  it("rejects missing @", () => {
-    expect(isValidEmail("notanemail")).toBe(false);
-  });
-
-  it("rejects missing domain", () => {
-    expect(isValidEmail("user@")).toBe(false);
-  });
-
-  it("rejects missing local part", () => {
-    expect(isValidEmail("@example.com")).toBe(false);
-  });
-
-  it("rejects missing TLD dot", () => {
-    expect(isValidEmail("user@localhost")).toBe(false);
-  });
-
-  it("rejects plainly malformed input", () => {
-    expect(isValidEmail("not@valid@example.com")).toBe(false);
-  });
-});