create-ailk 0.23.0 → 0.25.1

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

@@ -1,318 +0,0 @@
-/**
- * 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.
- */
-import { logger } from "@working-theory/observability";
-import {
-  admitLiveRestrictedKey,
-  assertSandboxKey,
-  createStripeClientForKey,
-  getStripeClient,
-  StripeConfigError,
-  type StripeConnectionMode,
-} from "@working-theory/stripe-client";
-
-export {
-  // PRECONDITION (#6113): do not narrow or bypass this sandbox-only guard for a
-  // production key class until #6113's no-overwrite guard in
-  // routes/webhooks/stripe.ts upsertBillingIdentity is on main — an unverified
-  // Checkout email must never re-point an already-bound User.billingCustomerId.
-  // Widened by #6852 (the #6113 follow-up): the same function must bind only
-  // on a server-stamped metadata.ailk_user_id — an unverified Checkout email
-  // never makes a FIRST binding either.
-  // Both are on main (#6850, #6862); #8450 is the narrowing this guarded —
-  // `assertAdmittedStripeKey` below. This export itself stays sandbox-only.
-  assertSandboxKey,
-  // The plan checkout's mode assertion and terms-box failure (#9067 D3 step 9).
-  CheckoutModeMismatchError,
-  // The Organization connection's key classifier (#8906, #8907 D4).
-  classifyStripeKey,
-  createAdHocPrice,
-  createBillingPortalSession,
-  createCheckoutSession,
-  // The Offerings checkout's per-client calls (#8931 D6), on the connection's client.
-  createCheckoutSessionForPrice,
-  createPaymentLink,
-  createQuotedCheckoutSession,
-  expireCheckoutSessionWith,
-  findActivePriceByLookupKey,
-  getStripeClient,
-  // Working Theory's own absolute policies for the plan checkout's terms box (#9067 D3 step 9).
-  PLATFORM_TERMS_OF_SERVICE,
-  // Checkout session read (#6084 D9) — re-exported through this sole
-  // Stripe-touching chokepoint, same as every other Stripe call here.
-  retrieveCheckoutSession,
-  STRIPE_API_VERSION,
-  StripeConfigError,
-  StripeWebhookSignatureError,
-  TermsOfServiceUrlMissingError,
-  toSubscriptionLifecycleStatus,
-  // Signed-in Checkout (#6866 D8) — a pinned customer Stripe rejects.
-  UnknownCustomerError,
-  UnknownProductCodeError,
-  UnknownSessionError,
-  verifyWebhookSignature,
-  // The per-Organization webhook's verify (#8932 D3): the row's secret, no env key.
-  verifyWebhookSignatureKeyless,
-  WEBHOOK_TOLERANCE_SECONDS,
-} from "@working-theory/stripe-client";
-
-export type {
-  CheckoutSessionLineItem,
-  CreateAdHocPriceInput,
-  CreateAdHocPriceOutput,
-  CreateBillingPortalSessionInput,
-  CreateBillingPortalSessionOutput,
-  CreatePaymentLinkInput,
-  CreatePaymentLinkOutput,
-  CreateCheckoutSessionForPriceInput,
-  CreateCheckoutSessionInput,
-  CreateCheckoutSessionOutput,
-  CreateCheckoutSessionParams,
-  CreateQuotedCheckoutSessionInput,
-  CreateQuotedCheckoutSessionOutput,
-  RetrieveCheckoutSessionInput,
-  RetrieveCheckoutSessionOutput,
-  Stripe,
-  StripeCheckoutSession,
-  StripeConnectionMode,
-  StripeKeyClass,
-  StripeWebhookEvent,
-} from "@working-theory/stripe-client";
-
-/**
- * apps/api's live-key admission (#8450 D2 — D-68's apps/api leg, the half
- * #6881 left unbuilt). Composed at runtime so this file's own text never
- * trips the repo-wide live-key lint.
- */
-const LIVE_RESTRICTED_KEY_PREFIX = ["rk", "live", ""].join("_");
-
-let liveKeyAdmitted = false;
-
-/**
- * `VERCEL_ENV` when set, else `NODE_ENV` — packages/spoke-checkout's own
- * rule, with one fail-closed delta (PR #8470 security review R-1): on Vercel
- * (`VERCEL` set) a missing `VERCEL_ENV` is not production, because
- * `vercel.json` sets `NODE_ENV=production` in every environment, Preview
- * included. Exported for the Organization connection's go-live check and
- * its live-row guard (#8907 D3, D8 step 6); the body is unchanged.
- */
-export function isProductionBuild(): boolean {
-  if (process.env.VERCEL_ENV !== undefined) {
-    return process.env.VERCEL_ENV === "production";
-  }
-  if (process.env.VERCEL !== undefined) return false;
-  return process.env.NODE_ENV === "production";
-}
-
-/**
- * Admit this process's Stripe key at server build, or throw
- * `StripeConfigError` (#8450 D2). Called once, by `server.ts`'s `build()`,
- * and nowhere else.
- *
- * Only a restricted live key, beside `STRIPE_MODE=live`, on a production
- * build is admitted: the package's one-way flag is set and `"live"` comes
- * back. `STRIPE_MODE` unset or `test` is today's boot — `assertSandboxKey`,
- * its message unchanged — and returns `"test"`. Every other combination
- * throws. It takes no parameter and reads `process.env` only, so it vouches
- * for the same key `getStripeClient()` later reads. No message names any
- * part of the key.
- */
-export function admitApiStripeKey(): "test" | "live" {
-  const mode = process.env.STRIPE_MODE;
-  const key = process.env.STRIPE_SECRET_KEY ?? "";
-
-  if (mode !== undefined && mode !== "test" && mode !== "live") {
-    throw new StripeConfigError('STRIPE_MODE must be "test" or "live".');
-  }
-  if (mode === "live") {
-    if (!key.startsWith(LIVE_RESTRICTED_KEY_PREFIX)) {
-      throw new StripeConfigError(
-        "STRIPE_MODE=live needs a restricted live Stripe key. " +
-          "Unrestricted, publishable and test-mode keys are refused.",
-      );
-    }
-    if (!isProductionBuild()) {
-      throw new StripeConfigError(
-        "A restricted live Stripe key is admitted only with STRIPE_MODE=live on a production build " +
-          "(VERCEL_ENV=production, or NODE_ENV=production off Vercel).",
-      );
-    }
-    admitLiveRestrictedKey();
-    liveKeyAdmitted = true;
-    return "live";
-  }
-  assertSandboxKey(key);
-  return "test";
-}
-
-/**
- * The request-time key check for the routes that may run live (#8450 D3):
- * the member portal session and the checkout start and read. It returns
- * before the sandbox-only guard for the restricted live class alone, and
- * only once `admitApiStripeKey()` admitted it; every other key meets
- * `assertSandboxKey`'s allow-list, so an unrestricted or publishable live
- * key is refused whether or not the process admitted.
- */
-export function assertAdmittedStripeKey(key: string): void {
-  if (liveKeyAdmitted && key.startsWith(LIVE_RESTRICTED_KEY_PREFIX)) return;
-  assertSandboxKey(key);
-}
-
-/**
- * A fresh Stripe client from ONE Organization's own key (#8907 D12, #8906
- * F-T1 to F-T3), or `null` when the factory refuses it: the factory's only
- * caller, so `productionBuild` is always the strict predicate above and never
- * a caller's boolean. It reads and sets no process flag — `stripeKeyMode()`
- * is untouched — so one process holds a live Organization and a test one
- * (contract K6, K7). A refusal logs `{ organizationId, reason }` only.
- * `architecture.yaml` confines its callers to exact paths.
- */
-export function stripeClientForConnection(input: {
-  organizationId: string;
-  key: string;
-  mode: StripeConnectionMode;
-  liveAt: Date | null;
-}): ReturnType<typeof createStripeClientForKey> {
-  return createStripeClientForKey({
-    organizationId: input.organizationId,
-    key: input.key,
-    mode: input.mode,
-    liveAt: input.liveAt,
-    productionBuild: isProductionBuild(),
-    log: (refusal) =>
-      logger.warn(
-        { organizationId: refusal.organizationId, reason: refusal.reason },
-        "[stripe] connection key refused for its mode",
-      ),
-  });
-}
-
-/** The key class this process admitted at boot: `"live"` only after `admitApiStripeKey()` did. */
-export function stripeKeyMode(): "test" | "live" {
-  return liveKeyAdmitted ? "live" : "test";
-}
-
-/**
- * Expire a Checkout Session (#4912 FR7/D7).
- *
- * The compensation the recommender's attach-miss branch owes: the Stripe
- * session already exists, its id never reached the `FlowCheckout` row, and
- * nothing will ever join the two — so the session is closed rather than left
- * live and payable (#4863). Built on the already-re-exported
- * `getStripeClient`, whose construction asserts its key allow-list, so this
- * call inherits the same gate as every other Stripe call here (test-mode, or
- * the restricted live key once `admitApiStripeKey()` admitted it, #8450).
- */
-export async function expireCheckoutSession(stripeSessionId: string): Promise<void> {
-  await getStripeClient().checkout.sessions.expire(stripeSessionId);
-}
-
-/**
- * #8171 D7 — what the Billing page shows: the plan's name and the card on
- * file. #9067 D6 adds the renewal date and the site count, read from the
- * same subscription.
- */
-export type CustomerBillingSummary = {
-  planName: string | null;
-  paymentMethod: { brand: string; last4: string; expMonth: number; expYear: number } | null;
-  renewsAt: string | null;
-  sites: number | null;
-};
-
-/** A subscription status that still names the customer's plan (#8171 C10). */
-const CURRENT_SUBSCRIPTION_STATUSES = new Set(["active", "trialing", "past_due", "unpaid"]);
-/** A subscription status that renews at its period end (#9067 C3). */
-const RENEWING_SUBSCRIPTION_STATUSES = new Set(["active", "trialing", "past_due"]);
-const PLAN_NAME_MAX = 200;
-
-/**
- * Read one customer's plan name and card summary (#8171 D7, C10): the newest
- * subscription that is `active`, `trialing`, `past_due` or `unpaid`; its
- * first item's product name (else the price nickname); and its default
- * payment method (else the customer's invoice default). At most three reads,
- * no expand path deeper than three levels (SEC-8171-3). Built on
- * `getStripeClient`, so it inherits its allow-list: a missing key, or a live
- * key this process did not admit (#8450), throws `StripeConfigError`. It logs
- * nothing and returns no id.
- */
-export async function readCustomerBillingSummary(
-  customerId: string,
-): Promise<CustomerBillingSummary> {
-  const stripe = getStripeClient();
-  const subscriptions = await stripe.subscriptions.list({
-    customer: customerId,
-    status: "all",
-    limit: 10,
-    expand: ["data.default_payment_method"],
-  });
-  const current = subscriptions.data
-    .filter((sub) => CURRENT_SUBSCRIPTION_STATUSES.has(sub.status))
-    .sort((a, b) => b.created - a.created)[0];
-
-  let planName: string | null = null;
-  const price = current?.items.data[0]?.price;
-  if (price) {
-    let name: string | null = null;
-    if (typeof price.product === "string") {
-      const product = await stripe.products.retrieve(price.product);
-      name = product.name;
-    } else if (price.product && !("deleted" in price.product && price.product.deleted)) {
-      name = (price.product as { name?: string }).name ?? null;
-    }
-    const trimmed = (name ?? price.nickname ?? "").trim().slice(0, PLAN_NAME_MAX);
-    planName = trimmed === "" ? null : trimmed;
-  }
-
-  let method: unknown = current?.default_payment_method ?? null;
-  if (cardOf(method) === null) {
-    const customer = await stripe.customers.retrieve(customerId, {
-      expand: ["invoice_settings.default_payment_method"],
-    });
-    method = "deleted" in customer && customer.deleted
-      ? null
-      : (customer as { invoice_settings?: { default_payment_method?: unknown } }).invoice_settings
-          ?.default_payment_method ?? null;
-  }
-
-  // #9067 C3, D6 — under `dahlia` the period end lives on the item, and a
-  // subscription set to cancel names no renewal.
-  const item = current?.items.data[0];
-  const renews =
-    current !== undefined &&
-    RENEWING_SUBSCRIPTION_STATUSES.has(current.status) &&
-    current.cancel_at_period_end !== true &&
-    current.cancel_at == null &&
-    typeof item?.current_period_end === "number";
-  const renewsAt = renews ? new Date(item.current_period_end * 1000).toISOString() : null;
-  const quantity = item?.quantity;
-  const sites = typeof quantity === "number" && Number.isInteger(quantity) && quantity >= 1 ? quantity : null;
-
-  return { planName, paymentMethod: cardOf(method), renewsAt, sites };
-}
-
-/** A `card` payment method's presentation fields, or `null` for anything else. */
-function cardOf(method: unknown): CustomerBillingSummary["paymentMethod"] {
-  if (typeof method !== "object" || method === null) return null;
-  const { type, card } = method as {
-    type?: unknown;
-    card?: { brand?: unknown; last4?: unknown; exp_month?: unknown; exp_year?: unknown };
-  };
-  if (type !== "card" || !card) return null;
-  const { brand, last4, exp_month: expMonth, exp_year: expYear } = card;
-  if (
-    typeof brand !== "string" ||
-    typeof last4 !== "string" ||
-    typeof expMonth !== "number" ||
-    typeof expYear !== "number"
-  ) {
-    return null;
-  }
-  return { brand, last4, expMonth, expYear };
-}

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

@@ -1,156 +0,0 @@
-/**
- * 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);
-  }
-}
-
-// ─── Per-Organization store (#8932 D8, contract W10) ─────────────────────────
-//
-// The per-Organization endpoint (`POST /v1/webhooks/stripe/:connectionToken`)
-// dedupes in its OWN map, keyed `<organizationId>:<eventId>`, so neither
-// endpoint's dedup can swallow the other's event (SEC-8879-1) and two
-// Organizations sharing one Stripe account never collide (an Organization id
-// holds no `:`). Same TTL, soft cap and sweep rules as the legacy pair above;
-// the legacy `hasSeen`/`markSeen` never read it. Correctness rests on the
-// lead's database key, not on this map.
-
-const orgStore = new Map<string, Entry>();
-let orgInsertsSinceLastSweep = 0;
-
-function orgKey(organizationId: string, eventId: string): string {
-  return `${organizationId}:${eventId}`;
-}
-
-function sweepOrgExpired(nowMs: number): void {
-  for (const [key, entry] of orgStore) {
-    if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
-      orgStore.delete(key);
-    }
-  }
-  orgInsertsSinceLastSweep = 0;
-}
-
-/** `hasSeen`'s twin for one Organization's endpoint. */
-export function hasSeenForOrganization(
-  organizationId: string,
-  eventId: string,
-  nowMs: number = Date.now(),
-): boolean {
-  const key = orgKey(organizationId, eventId);
-  const entry = orgStore.get(key);
-  if (!entry) return false;
-  if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
-    orgStore.delete(key);
-    return false;
-  }
-  return true;
-}
-
-/** `markSeen`'s twin for one Organization's endpoint. */
-export function markSeenForOrganization(
-  organizationId: string,
-  eventId: string,
-  nowMs: number = Date.now(),
-): void {
-  const key = orgKey(organizationId, eventId);
-  if (!orgStore.has(key)) {
-    orgStore.set(key, { insertedAtMs: nowMs });
-  }
-
-  orgInsertsSinceLastSweep += 1;
-  if (
-    orgStore.size > SOFT_CAP ||
-    orgInsertsSinceLastSweep >= SWEEP_INTERVAL_INSERTS
-  ) {
-    sweepOrgExpired(nowMs);
-  }
-}
-
-/**
- * Test-only reset. Clears all dedup state — both stores — between test cases
- * so they do not interfere with each other.
- */
-export function __resetIdempotencyStore(): void {
-  store.clear();
-  insertsSinceLastSweep = 0;
-  orgStore.clear();
-  orgInsertsSinceLastSweep = 0;
-}

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

@@ -1,111 +0,0 @@
-/**
- * @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, {
-    trustedOrigins: ["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();
-  });
-});