create-ailk 0.6.1 → 0.8.0

package/templates/apps/api/src/config/__tests__/index.test.ts

@@ -5,10 +5,11 @@ jest.mock('dotenv', () => ({
 
 // Mock the observability logger so assertions don't depend on pino's stdout serialization.
 const mockLoggerError = jest.fn();
+const mockLoggerWarn = jest.fn();
 jest.mock('@working-theory/observability', () => ({
   logger: {
     error: (...args: unknown[]) => mockLoggerError(...args),
-    warn: jest.fn(),
+    warn: (...args: unknown[]) => mockLoggerWarn(...args),
     info: jest.fn(),
     debug: jest.fn(),
   },
@@ -41,22 +42,74 @@ describe('Config', () => {
     expect(dotenv.config).toHaveBeenCalled();
   });
 
-  it('should exit on missing DATABASE_URL', () => {
-    // ARRANGE
+  // #6730 security review (M1): a production build whose enabled modules keep
+  // their state in the database still refuses to boot without DATABASE_URL —
+  // a missing database there is a broken deploy (e.g. a commerce licence read
+  // as absent would ack-and-drop signed Stripe events), not a Free site.
+  it.each(['commerce', 'content-write', 'multi-tenant', 'scheduling', 'signal-collectors', 'workspace'])(
+    'should exit on missing DATABASE_URL in production when the %s module is enabled',
+    (moduleName) => {
+      process.env.NODE_ENV = 'production';
+      process.env.AILK_ENABLED_MODULES = `marketing,${moduleName}`;
+      delete process.env.DATABASE_URL;
+      const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('Process exit called');
+      });
+
+      expect(() => require('../index')).toThrow('Process exit called');
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(mockLoggerError).toHaveBeenCalled();
+
+      exitSpy.mockRestore();
+    },
+  );
+
+  it('should start database-less in production with only non-database modules enabled', () => {
+    process.env.NODE_ENV = 'production';
+    process.env.AILK_ENABLED_MODULES = 'marketing,docs-blog';
     delete process.env.DATABASE_URL;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+
+    const { config } = require('../index');
+
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(config.DATABASE_URL).toBeUndefined();
+    exitSpy.mockRestore();
+  });
 
+  // #6482 — a missing DATABASE_URL starts the API database-less (one
+  // warning) instead of exiting, so a fresh scaffold's `pnpm dev` keeps its
+  // "no database needed" promise. #6730 (operator decision (a)) extends that
+  // to production: a Free site delivers leads by email with no Postgres.
+  it.each([
+    ['production', 'production'],
+    ['development', 'development'],
+    ['unset', undefined],
+    ['test', 'test'],
+  ])('should start database-less with DATABASE_URL unset when NODE_ENV is %s', (_label, nodeEnv) => {
+    // ARRANGE
+    if (nodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = nodeEnv;
+    }
+    delete process.env.DATABASE_URL;
     const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('Process exit called');
     });
-    mockLoggerError.mockClear();
 
-    // ACT & ASSERT
-    expect(() => {
-      require('../index');
-    }).toThrow('Process exit called');
+    // ACT
+    const { config } = require('../index');
 
-    expect(exitSpy).toHaveBeenCalledWith(1);
-    expect(mockLoggerError).toHaveBeenCalled();
+    // ASSERT
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(config.DATABASE_URL).toBeUndefined();
+    expect(config.NODE_ENV).toBe(nodeEnv ?? 'development');
+    expect(mockLoggerError).not.toHaveBeenCalled();
+    expect(mockLoggerWarn).toHaveBeenCalledTimes(1);
+    expect(mockLoggerWarn.mock.calls[0]?.[1]).toContain('database_not_configured');
 
     exitSpy.mockRestore();
   });
@@ -95,3 +148,86 @@ describe('Config', () => {
     expect(config.FRONTEND_URL).toBe('http://localhost:3000');
   });
 });
+
+// #6730 (operator decision (a)) — the REAL server boots in production with
+// no database: an email-only Free site must be able to run its API, answer
+// `GET /v1/leads/capture`, and refuse authenticated routes with a 503 rather
+// than exit at startup.
+describe('production boot without a database (#6730)', () => {
+  const originalEnv = process.env;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the Fastify instance comes from an isolated require; its generics add nothing here
+  let app: any;
+
+  const EMAIL_ENV = {
+    RESEND_API_KEY: 're_test',
+    AILK_LEAD_NOTIFICATION_TO: 'owner@example.com',
+    AILK_LEAD_NOTIFICATION_FROM: 'noreply@example.com',
+  };
+
+  // External boundaries only, as src/__tests__/server.test.ts mocks them.
+  beforeAll(() => {
+    jest.doMock('@fastify/cors', () => jest.fn().mockResolvedValue(undefined));
+    jest.doMock('@fastify/rate-limit', () => jest.fn().mockResolvedValue(undefined));
+    jest.doMock('@working-theory/email', () => ({
+      sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: 'm' }),
+      sendRequestConfirmEmail: jest.fn(),
+      sendRequestPaidLinkEmail: jest.fn(),
+    }));
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+    process.env = originalEnv;
+  });
+
+  async function bootProduction(extra: Record<string, string> = {}) {
+    jest.resetModules();
+    const env: NodeJS.ProcessEnv = { ...originalEnv, NODE_ENV: 'production', ...extra };
+    delete env.DATABASE_URL;
+    delete env.DATABASE_URL_NON_POOLED;
+    delete env.RESEND_API_KEY;
+    delete env.AILK_LEAD_NOTIFICATION_TO;
+    delete env.AILK_LEAD_NOTIFICATION_FROM;
+    Object.assign(env, extra);
+    process.env = env;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+    try {
+      const { build } = require('../../server');
+      app = await build();
+    } finally {
+      expect(exitSpy).not.toHaveBeenCalled();
+      exitSpy.mockRestore();
+    }
+    return app;
+  }
+
+  it('with only the email vars, starts and reports contact accepted, newsletter not', async () => {
+    const server = await bootProduction(EMAIL_ENV);
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads/capture' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { contact: true, newsletter: false } });
+  });
+
+  it('with nothing configured, starts and reports nothing accepted', async () => {
+    const server = await bootProduction();
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads/capture' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { contact: false, newsletter: false } });
+  });
+
+  it('refuses an authenticated route with 503 database_not_configured', async () => {
+    const server = await bootProduction(EMAIL_ENV);
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads' });
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ error: 'database_not_configured' });
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -7,6 +7,8 @@
 import { logger } from '@working-theory/observability';
 import * as dotenv from 'dotenv';
 
+import { isModuleEnabled } from './modules.js';
+
 dotenv.config();
 
 export interface Config {
@@ -15,8 +17,9 @@ export interface Config {
   PORT: number;
   FRONTEND_URL: string;
 
-  // Local Database (for auth: User, Session, ApiToken, etc.)
-  DATABASE_URL: string;
+  // Local Database (for auth: User, Session, ApiToken, etc.). Required in
+  // production; unset elsewhere starts the API database-less (#6482).
+  DATABASE_URL?: string;
 
   // Stripe — consumed by apps/api/src/lib/stripe.ts via @working-theory/stripe-client wrapper
   STRIPE_SECRET_KEY?: string;
@@ -91,26 +94,55 @@ export interface Config {
   CAL_WEBHOOK_SECRET?: string;
 }
 
-function validateConfig(): Config {
-  const errors: string[] = [];
+/** Enabled modules whose state lives in the database (see validateConfig). */
+const DATABASE_MODULES = [
+  'commerce',
+  'content-write',
+  'multi-tenant',
+  'scheduling',
+  'signal-collectors',
+  'workspace',
+] as const;
 
-  // Required: Local database for auth
+function validateConfig(): Config {
+  const nodeEnv = (process.env.NODE_ENV || 'development') as Config['NODE_ENV'];
+
+  // No database is a supported shape in every environment, production
+  // included (#6730 operator decision (a)): a Free site delivers leads by
+  // email and needs no Postgres. Start database-less and let the auth
+  // preHandler answer 503 database_not_configured (#6482) — it reads
+  // DATABASE_URL per request, whatever NODE_ENV says, so no authenticated
+  // route runs without a database.
+  //
+  // Except a production build whose ENABLED modules keep their state in the
+  // database. There a missing DATABASE_URL is a broken deploy, not a Free
+  // site: e.g. a commerce site's licence lives in the database-backed store,
+  // so booting without it would read the site as unlicensed and ack-and-drop
+  // every signed Stripe event (#6730 security review, M1). Those builds keep
+  // the loud startup failure.
   if (!process.env.DATABASE_URL) {
-    errors.push('DATABASE_URL is required for authentication');
-  }
-
-  // Exit on errors
-  if (errors.length > 0) {
-    logger.error({ errors }, '❌ Configuration validation failed');
-    process.exit(1);
+    const needsDatabase = DATABASE_MODULES.filter((m) => isModuleEnabled(m));
+    if (nodeEnv === 'production' && needsDatabase.length > 0) {
+      logger.error(
+        { modules: needsDatabase },
+        '❌ DATABASE_URL is required in production when these modules are enabled',
+      );
+      process.exit(1);
+    }
+    logger.warn(
+      { nodeEnv },
+      '⚠️ DATABASE_URL not set — starting database-less; authenticated routes answer 503 database_not_configured',
+    );
   }
 
   return {
-    NODE_ENV: (process.env.NODE_ENV || 'development') as Config['NODE_ENV'],
+    NODE_ENV: nodeEnv,
     PORT: parseInt(process.env.PORT || '3002', 10),
     FRONTEND_URL: process.env.FRONTEND_URL || 'http://localhost:3000',
 
-    DATABASE_URL: process.env.DATABASE_URL!,
+    ...(process.env.DATABASE_URL !== undefined && {
+      DATABASE_URL: process.env.DATABASE_URL,
+    }),
 
     ...(process.env.STRIPE_SECRET_KEY !== undefined && {
       STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,

package/templates/apps/api/src/lib/__tests__/lead-capture-store.test.ts

@@ -96,6 +96,36 @@ describe("appendLeadRecord", () => {
     expect(filePath).toMatch(/leads\.jsonl$/);
   });
 
+  // #6730 D3 — the default file is local-only: in production it does not
+  // outlive a serverless instance, so it is skipped unless explicitly pointed
+  // at a durable path.
+  describe("in production (#6730 D3)", () => {
+    const savedNodeEnv = process.env.NODE_ENV;
+    afterEach(() => {
+      process.env.NODE_ENV = savedNodeEnv;
+    });
+
+    it("skips the write when LEAD_CAPTURE_FILE is unset", async () => {
+      process.env.NODE_ENV = "production";
+
+      const result = await appendLeadRecord(record);
+
+      expect(result).toEqual({ ok: true, skipped: true });
+      expect(mockAppendFile).not.toHaveBeenCalled();
+    });
+
+    it("writes when LEAD_CAPTURE_FILE is set explicitly", async () => {
+      process.env.NODE_ENV = "production";
+      process.env.LEAD_CAPTURE_FILE = "/data/leads.jsonl";
+
+      const result = await appendLeadRecord(record);
+
+      expect(result).toEqual({ ok: true });
+      expect(mockAppendFile).toHaveBeenCalledTimes(1);
+      expect(mockAppendFile.mock.calls[0][0]).toBe("/data/leads.jsonl");
+    });
+  });
+
   // AC4 — LEAD_CAPTURE_FILE_DISABLED=true skips the write
   it("short-circuits write when LEAD_CAPTURE_FILE_DISABLED=true", async () => {
     process.env.LEAD_CAPTURE_FILE_DISABLED = "true";

package/templates/apps/api/src/lib/__tests__/lead-delivery.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @file lead-delivery.test.ts
+ * @description The #6730 D1 delivery table, row by row.
+ */
+
+import { acceptsKind, resolveLeadDelivery } from "../lead-delivery";
+
+const EMAIL = {
+  RESEND_API_KEY: "re_test",
+  AILK_LEAD_NOTIFICATION_TO: "owner@example.com",
+  AILK_LEAD_NOTIFICATION_FROM: "noreply@example.com",
+};
+
+describe("resolveLeadDelivery", () => {
+  it("DATABASE_URL alone → inbox", () => {
+    expect(resolveLeadDelivery({ DATABASE_URL: "postgres://x", NODE_ENV: "production" })).toBe(
+      "inbox",
+    );
+  });
+
+  it("DATABASE_URL wins over the email vars", () => {
+    expect(resolveLeadDelivery({ DATABASE_URL: "postgres://x", ...EMAIL })).toBe("inbox");
+  });
+
+  it("the three email vars, no database → email", () => {
+    expect(resolveLeadDelivery({ ...EMAIL, NODE_ENV: "production" })).toBe("email");
+    expect(resolveLeadDelivery({ ...EMAIL, NODE_ENV: "development" })).toBe("email");
+  });
+
+  it("a bare RESEND_API_KEY is not email delivery — local in dev, none in production", () => {
+    expect(resolveLeadDelivery({ RESEND_API_KEY: "re_test", NODE_ENV: "development" })).toBe(
+      "local",
+    );
+    expect(resolveLeadDelivery({ RESEND_API_KEY: "re_test", NODE_ENV: "production" })).toBe(
+      "none",
+    );
+  });
+
+  it("the key and one address only → not email", () => {
+    expect(
+      resolveLeadDelivery({
+        RESEND_API_KEY: "re_test",
+        AILK_LEAD_NOTIFICATION_TO: "owner@example.com",
+        NODE_ENV: "production",
+      }),
+    ).toBe("none");
+  });
+
+  it("nothing configured in production → none", () => {
+    expect(resolveLeadDelivery({ NODE_ENV: "production" })).toBe("none");
+  });
+
+  it("nothing configured outside production → local", () => {
+    expect(resolveLeadDelivery({ NODE_ENV: "test" })).toBe("local");
+    expect(resolveLeadDelivery({})).toBe("local");
+  });
+
+  it("LEAD_CAPTURE_FILE_DISABLED=true removes the local path → none", () => {
+    expect(
+      resolveLeadDelivery({ NODE_ENV: "development", LEAD_CAPTURE_FILE_DISABLED: "true" }),
+    ).toBe("none");
+  });
+
+  it("reads process.env by default", () => {
+    const saved = process.env.DATABASE_URL;
+    process.env.DATABASE_URL = "postgres://x";
+    try {
+      expect(resolveLeadDelivery()).toBe("inbox");
+    } finally {
+      if (saved === undefined) delete process.env.DATABASE_URL;
+      else process.env.DATABASE_URL = saved;
+    }
+  });
+});
+
+describe("acceptsKind", () => {
+  it("none accepts nothing", () => {
+    expect(acceptsKind("none", "submit")).toBe(false);
+    expect(acceptsKind("none", "subscribe")).toBe(false);
+    expect(acceptsKind("none", "callback")).toBe(false);
+  });
+
+  it("email accepts submit and callback, never subscribe", () => {
+    expect(acceptsKind("email", "submit")).toBe(true);
+    expect(acceptsKind("email", "callback")).toBe(true);
+    expect(acceptsKind("email", "subscribe")).toBe(false);
+  });
+
+  it("inbox and local accept every kind", () => {
+    for (const d of ["inbox", "local"] as const) {
+      expect(acceptsKind(d, "submit")).toBe(true);
+      expect(acceptsKind(d, "subscribe")).toBe(true);
+      expect(acceptsKind(d, "callback")).toBe(true);
+    }
+  });
+});

package/templates/apps/api/src/lib/lead-capture-store.ts

@@ -12,6 +12,15 @@
  *
  * Env vars (all read inside function bodies — module is import-side-effect-free):
  *   LEAD_CAPTURE_FILE            — output path (default: apps/api/leads.jsonl relative to cwd)
+ *
+ * The default path is LOCAL-ONLY (#6730 D3). In production
+ * (`NODE_ENV=production`) with `LEAD_CAPTURE_FILE` unset, the write is skipped:
+ * on serverless hosting a file under the process cwd does not outlive the
+ * instance, so it is not a record of anything. An operator with a durable
+ * volume can keep a side copy by setting `LEAD_CAPTURE_FILE` explicitly —
+ * a copy only: in production it never makes a lead count as delivered
+ * (`lib/lead-delivery.ts` needs a database or the email vars).
+ *
  *   LEAD_CAPTURE_FILE_DISABLED   — set to "true" to skip writes (opt-out)
  *   LEAD_CAPTURE_INCLUDE_IP      — set to "true" to include metadata.ip in the record
  *
@@ -47,6 +56,9 @@ export async function appendLeadRecord(
   if (disabled) {
     return { ok: true, skipped: true };
   }
+  if (process.env.NODE_ENV === "production" && !process.env.LEAD_CAPTURE_FILE) {
+    return { ok: true, skipped: true };
+  }
 
   const includeIp = process.env.LEAD_CAPTURE_INCLUDE_IP === "true";
   const outputPath = resolveOutputPath();

package/templates/apps/api/src/lib/lead-delivery.ts

@@ -0,0 +1,52 @@
+/**
+ * @file lead-delivery.ts
+ * @description Where a captured lead goes, resolved from the environment (#6730 D1).
+ *
+ *   inbox — `DATABASE_URL` is set: the database is the destination (the lead
+ *           inbox at `/leads`); the owner email is still sent best-effort.
+ *   email — no database, but `RESEND_API_KEY` plus both notification
+ *           addresses are set: the owner email IS the delivery.
+ *   local — neither, outside production (`pnpm dev`, tests): the local file
+ *           fallback + `leads.jsonl`, so local work needs nothing configured.
+ *   none  — neither, in production: nothing is accepted, so no visitor is
+ *           ever told a message was sent when it reached nobody.
+ *
+ * A key alone delivers nothing (`sendEmail()` also needs both addresses), so
+ * it is not counted as configured. `LEAD_CAPTURE_FILE_DISABLED=true` removes
+ * the local file path, so outside production it resolves to `none` too.
+ *
+ * Import-side-effect-free; the environment is read at call time.
+ */
+
+export type LeadDelivery = "inbox" | "email" | "local" | "none";
+
+export type LeadDeliveryKind = "submit" | "subscribe" | "callback";
+
+export function resolveLeadDelivery(
+  env: NodeJS.ProcessEnv = process.env,
+): LeadDelivery {
+  if (env.DATABASE_URL) return "inbox";
+  if (
+    env.RESEND_API_KEY &&
+    env.AILK_LEAD_NOTIFICATION_TO &&
+    env.AILK_LEAD_NOTIFICATION_FROM
+  ) {
+    return "email";
+  }
+  if (env.NODE_ENV !== "production" && env.LEAD_CAPTURE_FILE_DISABLED !== "true") {
+    return "local";
+  }
+  return "none";
+}
+
+/**
+ * Whether a delivery mode accepts a lead of this kind. A newsletter
+ * subscription is a list entry, not a message — emailing the owner one
+ * address per signup is not a list — so `subscribe` needs somewhere to keep
+ * it (the database, or the local file in development).
+ */
+export function acceptsKind(d: LeadDelivery, kind: LeadDeliveryKind): boolean {
+  if (d === "none") return false;
+  if (kind === "subscribe") return d === "inbox" || d === "local";
+  return true;
+}

package/templates/apps/api/src/lib/license-key-store.ts

@@ -0,0 +1,45 @@
+/**
+ * Registers the durable home of a renewed licence key (#6677 DD-6).
+ *
+ * `@working-theory/license` renews the deployment's key before it lapses and
+ * keeps the renewed key in a `LicenseKeyStore`. Its default store is a file,
+ * which a Vercel redeploy wipes — so a redeployed site would fall back to the
+ * older `AILK_LICENSE_KEY` and, past the renewal grace, to free. With a
+ * database configured, this registers the store backed by ONE deployment-wide
+ * `SiteSetting` row, `(DEFAULT_WORKSPACE_ID, "license.renewed_key")`, shared
+ * by this app, apps/mcp and apps/web.
+ *
+ * The row is deployment-wide, not tenant data: the licence is the
+ * deployment's, so it sits under the seeded default workspace in single- and
+ * multi-tenant builds alike (the named tenant-scope exclusion in
+ * architecture.yaml). A DB-less scaffold keeps the file store.
+ */
+
+import { DEFAULT_WORKSPACE_ID } from "@working-theory/database/tenancy";
+import {
+  createSiteSettingLicenseKeyStore,
+  setLicenseKeyStore,
+} from "@working-theory/license";
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "./prisma.js";
+
+/**
+ * Register the SiteSetting-backed store when `DATABASE_URL` is set. An
+ * explicitly set `AILK_LICENSE_STORAGE_PATH` is the operator choosing the
+ * file store, and is honoured. Never throws: a failure logs and leaves the
+ * file store in place.
+ */
+export async function registerLicenseKeyStore(): Promise<void> {
+  if (!process.env.DATABASE_URL || process.env.AILK_LICENSE_STORAGE_PATH) return;
+  try {
+    setLicenseKeyStore(
+      createSiteSettingLicenseKeyStore(prisma.siteSetting, DEFAULT_WORKSPACE_ID),
+    );
+  } catch (err) {
+    logger.warn(
+      { errName: err instanceof Error ? err.name : "UnknownError" },
+      "[license] could not register the SiteSetting licence-key store — the file store stays in place",
+    );
+  }
+}

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

@@ -144,9 +144,11 @@ export async function resolveWorkspaceIdForAlias(
  *  1. **No `DATABASE_URL` configured** — the literal `requireDb()` guard
  *     `apps/api/src/services/flow-engine.ts` uses for the flow services:
  *     presence, not reachability. (`apps/api/src/config/index.ts`'s own
- *     eager `validateConfig()` already refuses a real `apps/api` boot with
- *     `DATABASE_URL` unset before `build()` is ever reached, so this arm is
- *     for any OTHER caller of `build()`.)
+ *     eager `validateConfig()` refuses a **production** `apps/api` boot with
+ *     `DATABASE_URL` unset before `build()` is ever reached; outside
+ *     production a real boot starts database-less (#6482), so this arm is
+ *     reachable from a real dev boot as well as from any other caller of
+ *     `build()`.)
  *  2. **`prisma.workspace.findUnique` is not even a function** — the case
  *     that surfaced this arm: `apps/api`'s shared/global prisma mocks
  *     (`lib/__mocks__/prisma-client.js`, the module-map-level double every

package/templates/apps/api/src/middleware/__tests__/auth.database-not-configured.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @file auth.database-not-configured.test.ts
+ *
+ * DATABASE_URL unset → 503 database_not_configured (#6482).
+ *
+ * Outside production apps/api boots database-less. The preHandler must say
+ * so before it reads any credential: placed after the lookups, the existing
+ * `.catch(() => undefined)` would turn the connection failure into a
+ * misleading 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";
+
+const echoHandler = jest.fn(async () => ({ ok: true }));
+
+function buildApp(): FastifyInstance {
+  const app = Fastify();
+  app.register(authPreHandlerPlugin, {
+    frontendOrigin: "https://app.example.com",
+  });
+  app.get("/echo", echoHandler);
+  app.post("/echo", echoHandler);
+  return app;
+}
+
+describe("auth preHandler — DATABASE_URL not configured", () => {
+  const originalDatabaseUrl = process.env.DATABASE_URL;
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    delete process.env.DATABASE_URL;
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    if (originalDatabaseUrl === undefined) {
+      delete process.env.DATABASE_URL;
+    } else {
+      process.env.DATABASE_URL = originalDatabaseUrl;
+    }
+  });
+
+  it.each([
+    ["no credentials", "GET", {}],
+    ["a bearer token", "GET", { authorization: "Bearer ailk_abc123" }],
+    ["a session cookie", "GET", { cookie: "better-auth.session_token=tok" }],
+    [
+      "a non-GET with a session cookie",
+      "POST",
+      {
+        cookie: "better-auth.session_token=tok",
+        origin: "https://app.example.com",
+      },
+    ],
+  ] as const)(
+    'returns 503 { error: "database_not_configured" } for %s without any lookup',
+    async (_label, method, headers) => {
+      const res = await app.inject({ method, url: "/echo", headers });
+
+      expect(res.statusCode).toBe(503);
+      expect(JSON.parse(res.body)).toEqual({
+        error: "database_not_configured",
+      });
+      expect(prisma.session.findUnique).not.toHaveBeenCalled();
+      expect(prisma.apiToken.findUnique).not.toHaveBeenCalled();
+      expect(echoHandler).not.toHaveBeenCalled();
+    },
+  );
+
+  it("control: with DATABASE_URL set and no credentials, answers 401 unauthorized", async () => {
+    process.env.DATABASE_URL = "postgresql://test:test@localhost/test";
+
+    const res = await app.inject({ method: "GET", url: "/echo" });
+
+    expect(res.statusCode).toBe(401);
+    expect(JSON.parse(res.body)).toEqual({ error: "unauthorized" });
+    expect(echoHandler).not.toHaveBeenCalled();
+  });
+});

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

@@ -22,6 +22,7 @@
  *   - Both modes invalid              → 401 unauthorized.
  *   - Cookie expired + bearer valid   → 401 (no silent fallback).
  *   - Cookie absent, bearer malformed → 401 (no silent fallback).
+ *   - DATABASE_URL unset              → 503 database_not_configured (#6482).
  *
  * Public routes (health, content, leads, webhooks, openapi) are NOT registered
  * with this preHandler — server.ts narrows scope via a sub-plugin.
@@ -48,6 +49,7 @@ const COOKIE_NAMES = [
 ] as const;
 
 const UNAUTHORIZED = { error: "unauthorized" } as const;
+const DATABASE_NOT_CONFIGURED = { error: "database_not_configured" } as const;
 
 declare module "fastify" {
   interface FastifyRequest {
@@ -201,6 +203,13 @@ export function makeAuthPreHandler(opts: AuthPreHandlerOptions = {}) {
     request: FastifyRequest,
     reply: FastifyReply,
   ): Promise<void> {
+    // A database-less dev boot (#6482). First, and read per request: after
+    // the lookups below, their `.catch` would already have answered 401.
+    if (!process.env.DATABASE_URL) {
+      reply.code(503).send(DATABASE_NOT_CONFIGURED);
+      return;
+    }
+
     const now = getClock().now();
     const cookieToken = readSessionCookie(request);