@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/fullstack/apps/api/src/config/provider-selection.ts

@@ -0,0 +1,79 @@
+import {
+  CACHE,
+  EVENTS,
+  JOBS,
+  OBJECT_STORAGE,
+  PROVIDER_CAPABILITIES,
+  PROVIDER_NAMES,
+  type ProviderCapability,
+  type ProviderSelections,
+  type ServiceKey,
+} from "@podosoft/podokit-runtime";
+
+/** The variable that replaces each capability's generated provider at startup. */
+export const PROVIDER_VARIABLES: Readonly<Record<ProviderCapability, string>> = {
+  database: "DATABASE_PROVIDER",
+  cache: "CACHE_PROVIDER",
+  "object-storage": "OBJECT_STORAGE_PROVIDER",
+  events: "EVENTS_PROVIDER",
+  jobs: "JOBS_PROVIDER",
+};
+
+export type ProviderEnvironment = Readonly<Record<string, string | undefined>>;
+
+/** The capabilities whose provider a variable selects, for example in a desktop build. */
+export function selectedFromEnvironment(env: ProviderEnvironment = process.env): ProviderCapability[] {
+  return PROVIDER_CAPABILITIES.filter((capability) => Boolean(env[PROVIDER_VARIABLES[capability]]?.trim()));
+}
+
+/**
+ * The generated selection, with a capability replaced when its variable is set,
+ * so one build can run, say, PostgreSQL on a server and SQLite in a desktop
+ * shell. The selected provider's module must be installed; an unknown name
+ * fails at startup.
+ */
+export function providersFromEnvironment(
+  generated: ProviderSelections,
+  env: ProviderEnvironment = process.env,
+): ProviderSelections {
+  const selections: Record<string, string> = { ...generated };
+  for (const capability of selectedFromEnvironment(env)) {
+    const variable = PROVIDER_VARIABLES[capability];
+    const value = env[variable]?.trim().toLowerCase() ?? "";
+    const allowed: readonly string[] = PROVIDER_NAMES[capability];
+    if (!allowed.includes(value)) {
+      throw new Error(`Invalid environment: ${variable} must be one of ${allowed.join(", ")}`);
+    }
+    selections[capability] = value;
+  }
+  return selections as unknown as ProviderSelections;
+}
+
+// The service each provider module registers when its provider is selected.
+// The database has no module: the core service serves PostgreSQL and SQLite.
+const PROVIDER_SERVICES: Partial<Record<ProviderCapability, ServiceKey<unknown>>> = {
+  cache: CACHE,
+  "object-storage": OBJECT_STORAGE,
+  events: EVENTS,
+  jobs: JOBS,
+};
+
+/**
+ * Fails startup when a variable selects a provider whose module is not
+ * installed, which would otherwise fail the first request that needs it.
+ */
+export function assertSelectedProvidersInstalled(
+  services: { tryResolve<T>(key: ServiceKey<T>): T | undefined },
+  providers: ProviderSelections,
+  env: ProviderEnvironment = process.env,
+): void {
+  const missing = selectedFromEnvironment(env).flatMap((capability) => {
+    const key = PROVIDER_SERVICES[capability];
+    return key && services.tryResolve(key) === undefined
+      ? [`${PROVIDER_VARIABLES[capability]}=${providers[capability]}`]
+      : [];
+  });
+  if (missing.length > 0) {
+    throw new Error(`Invalid environment: no installed module provides ${missing.join(", ")}`);
+  }
+}

package/dist/templates/fullstack/apps/api/src/config/providers.ts

@@ -1,9 +1,15 @@
 import type { ProviderSelections } from "@podosoft/podokit-runtime";
+import { providersFromEnvironment } from "./provider-selection";
 
-export const PROVIDERS = {
+// The providers selected when the project was generated or by `podo provider
+// set`. Typed with every provider name, not the selected ones: the module of a
+// provider that stays installed after a switch compares against its own name.
+// A <CAPABILITY>_PROVIDER variable replaces one at startup; see
+// provider-selection.ts.
+export const PROVIDERS: Readonly<ProviderSelections> = providersFromEnvironment({
   database: "{{databaseProvider}}",
   cache: "{{cacheProvider}}",
   "object-storage": "{{objectStorageProvider}}",
   events: "{{eventsProvider}}",
   jobs: "{{jobsProvider}}",
-} as const satisfies ProviderSelections;
+});

package/dist/templates/fullstack/apps/api/src/config/server-options.spec.ts

@@ -4,26 +4,37 @@ import { validateEnv } from "./env.validation";
 import { apiServerOptions, DEFAULT_MAX_REQUEST_BODY_SIZE } from "./server-options";
 
 describe("apiServerOptions", () => {
-  it("defaults to Bun's request body limit and leaves the idle timeout to Elysia", () => {
+  it("defaults to Bun's request body limit and an idle timeout that outlasts the web proxy", () => {
     const env = validateEnv({});
     expect(env.API_MAX_REQUEST_BODY_SIZE).toBe(DEFAULT_MAX_REQUEST_BODY_SIZE);
-    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE });
+    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE, idleTimeout: 35 });
+  });
+
+  it("reads API_IDLE_TIMEOUT from 0 to 255 seconds and treats an empty value as unset", () => {
+    expect(validateEnv({ API_IDLE_TIMEOUT: "125" }).API_IDLE_TIMEOUT).toBe(125);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "0" }).API_IDLE_TIMEOUT).toBe(0);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "255" }).API_IDLE_TIMEOUT).toBe(255);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "" }).API_IDLE_TIMEOUT).toBe(35);
+    for (const value of ["256", "-1", "1.5", "soon"]) {
+      expect(() => validateEnv({ API_IDLE_TIMEOUT: value })).toThrow("API_IDLE_TIMEOUT");
+    }
+    expect(apiServerOptions(validateEnv({ API_IDLE_TIMEOUT: "0" }), {}).idleTimeout).toBe(0);
   });
 
   it("reads API_MAX_REQUEST_BODY_SIZE and rejects values that are not byte counts", () => {
-    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}))
-      .toEqual({ maxRequestBodySize: 1_073_741_824 });
+    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}).maxRequestBodySize)
+      .toBe(1_073_741_824);
     for (const value of ["0", "-1", "1.5", "lots"]) {
       expect(() => validateEnv({ API_MAX_REQUEST_BODY_SIZE: value })).toThrow("API_MAX_REQUEST_BODY_SIZE");
     }
   });
 
   it("lets the application's options win over the environment", () => {
-    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024" });
+    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024", API_IDLE_TIMEOUT: "60" });
     expect(apiServerOptions(env, { maxRequestBodySize: 4096, idleTimeout: 120 }))
       .toEqual({ maxRequestBodySize: 4096, idleTimeout: 120 });
     expect(apiServerOptions(env, (current) => ({ maxRequestBodySize: current.API_MAX_REQUEST_BODY_SIZE * 2 })))
-      .toEqual({ maxRequestBodySize: 2048 });
+      .toEqual({ maxRequestBodySize: 2048, idleTimeout: 60 });
     expect(() => apiServerOptions(env, { maxRequestBodySize: 0 })).toThrow("maxRequestBodySize");
     expect(() => apiServerOptions(env, { idleTimeout: 256 })).toThrow("idleTimeout");
     expect(() => apiServerOptions(env, { idleTimeout: -1 })).toThrow("idleTimeout");

package/dist/templates/fullstack/apps/api/src/config/server-options.ts

@@ -11,7 +11,7 @@ export interface ApiServerOptions {
   maxRequestBodySize?: number;
   /**
    * Seconds a connection may stay idle before it is closed, from 0 (never) to
-   * 255. Defaults to Elysia's 30 seconds.
+   * 255. Defaults to `API_IDLE_TIMEOUT`.
    */
   idleTimeout?: number;
 }
@@ -31,18 +31,15 @@ const owned: { readonly [name: string]: unknown; readonly apiServerOptions?: Api
 export function apiServerOptions(
   env: AppEnv,
   source: ApiServerOptionsSource | undefined = owned.apiServerOptions,
-): ApiServerOptions & { maxRequestBodySize: number } {
+): Required<ApiServerOptions> {
   const options = typeof source === "function" ? source(env) : source ?? {};
   const maxRequestBodySize = options.maxRequestBodySize ?? env.API_MAX_REQUEST_BODY_SIZE;
   if (!Number.isSafeInteger(maxRequestBodySize) || maxRequestBodySize < 1) {
     throw new Error("apiServerOptions.maxRequestBodySize must be a positive integer of bytes");
   }
-  const { idleTimeout } = options;
-  if (
-    idleTimeout !== undefined &&
-    (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS)
-  ) {
+  const idleTimeout = options.idleTimeout ?? env.API_IDLE_TIMEOUT;
+  if (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS) {
     throw new Error(`apiServerOptions.idleTimeout must be an integer from 0 to ${MAX_IDLE_TIMEOUT_SECONDS} seconds`);
   }
-  return { maxRequestBodySize, ...(idleTimeout === undefined ? {} : { idleTimeout }) };
+  return { maxRequestBodySize, idleTimeout };
 }

package/dist/templates/fullstack/apps/api/src/core/api-contract.extensions.ts

@@ -0,0 +1,6 @@
+// This owned file is never overwritten by `podo update`. List the operations
+// the application's own API must serve, as "METHOD /path". `bun run contract`
+// fails when one is not registered or missing from the OpenAPI document, for
+// example after a route was renamed or hidden by mistake. Parameters may use
+// either syntax: "GET /reports/{id}" or "GET /reports/:id".
+export const APP_DOCUMENTED_ROUTES: readonly string[] = [];

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -1,10 +1,13 @@
 import { describe, expect, it } from "bun:test";
 import {
   assertApiContract,
+  assertApplicationRoutes,
   assertConsistentRouteParameters,
   documentedApiRoutes,
   expectedApiRoutes,
   missingApiRoutes,
+  normalizeApiRoute,
+  registeredApiRoutes,
 } from "./api-contract";
 
 describe("API contract inventory", () => {
@@ -57,4 +60,30 @@ describe("API contract inventory", () => {
       { method: "DELETE", path: "/hosts/:hostId/services/:serviceId" },
     ])).not.toThrow();
   });
+
+  it("normalizes runtime and OpenAPI parameter syntax", () => {
+    expect(normalizeApiRoute("get /reports/:id/rows/:rowId")).toBe("GET /reports/{id}/rows/{rowId}");
+    expect(normalizeApiRoute("GET /reports/{id}")).toBe("GET /reports/{id}");
+    expect(registeredApiRoutes([
+      { method: "GET", path: "/reports/:id" },
+      { method: "POST", path: "/reports" },
+      { path: "/no-method" },
+    ])).toEqual(new Set(["GET /reports/{id}", "POST /reports"]));
+  });
+
+  it("requires every application route to be registered and documented", () => {
+    const document = { paths: { "/reports/{id}": { get: {} }, "/hidden": {} } };
+    const routes = [{ method: "GET", path: "/reports/:id" }, { method: "DELETE", path: "/hidden" }];
+
+    expect(() => assertApplicationRoutes(document, routes, ["GET /reports/:id", "GET /reports/{id}"])).not.toThrow();
+    expect(() => assertApplicationRoutes(document, routes, [])).not.toThrow();
+    expect(() => assertApplicationRoutes(document, routes, ["DELETE /hidden", "POST /reports"])).toThrow(
+      [
+        "Application API contract failed:",
+        "DELETE /hidden is missing from the OpenAPI document",
+        "POST /reports is not registered",
+        "POST /reports is missing from the OpenAPI document",
+      ].join("\n"),
+    );
+  });
 });

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -97,6 +97,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
 };
 
 interface RuntimeRoute {
+  method?: string;
   path: string;
 }
 
@@ -109,11 +110,47 @@ function record(value: unknown): Record<string, unknown> {
 function runtimeRoutes(value: unknown): RuntimeRoute[] {
   if (!Array.isArray(value)) return [];
   return value.flatMap((route) => {
-    const path = record(route).path;
-    return typeof path === "string" ? [{ path }] : [];
+    const { path, method } = record(route);
+    if (typeof path !== "string") return [];
+    return [typeof method === "string" ? { method, path } : { path }];
   });
 }
 
+/** "METHOD /path" with OpenAPI parameters, so ":id" and "{id}" compare equal. */
+export function normalizeApiRoute(route: string): string {
+  const [method = "", path = ""] = route.trim().split(/\s+/, 2);
+  const openApiPath = path
+    .split("/")
+    .map((segment) => segment.startsWith(":") ? `{${segment.slice(1).replace(/[?*]$/, "")}}` : segment)
+    .join("/");
+  return `${method.toUpperCase()} ${openApiPath}`;
+}
+
+/** The operations an Elysia app registers, as normalized "METHOD /path" entries. */
+export function registeredApiRoutes(routes: unknown): Set<string> {
+  const registered = new Set<string>();
+  for (const route of runtimeRoutes(routes)) {
+    if (route.method) registered.add(normalizeApiRoute(`${route.method} ${route.path}`));
+  }
+  return registered;
+}
+
+/**
+ * Fails unless every application route is both registered and documented.
+ * `expected` comes from APP_DOCUMENTED_ROUTES in api-contract.extensions.ts.
+ */
+export function assertApplicationRoutes(document: unknown, routes: unknown, expected: readonly string[]): void {
+  const documented = documentedApiRoutes(document);
+  const registered = registeredApiRoutes(routes);
+  const problems = [...new Set(expected.map(normalizeApiRoute))].sort().flatMap((route) => [
+    ...(registered.has(route) ? [] : [`${route} is not registered`]),
+    ...(documented.has(route) ? [] : [`${route} is missing from the OpenAPI document`]),
+  ]);
+  if (problems.length > 0) {
+    throw new Error(`Application API contract failed:\n${problems.join("\n")}`);
+  }
+}
+
 /**
  * Memoirist stores one parameter name at each structural radix-tree position.
  * Routes such as `/hosts/:id` and `/hosts/:hostId/files` therefore cannot share

package/dist/templates/fullstack/apps/api/src/core/client-address.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import {
+  CLIENT_ADDRESS_HEADER,
+  clientAddressOf,
+  resolveClientAddress,
+  stampClientAddress,
+} from "./client-address";
+
+const forwarded = (value: string): Headers => new Headers({ "x-forwarded-for": value });
+const config = (trustedProxyHops: number) => ({ trustedProxyHops, header: "x-forwarded-for" });
+
+describe("resolveClientAddress", () => {
+  it("uses the socket peer and ignores a caller's header without trusted proxies", () => {
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "::ffff:10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(new Headers(), undefined, config(0))).toBeUndefined();
+  });
+
+  it("takes the entry the trusted proxies appended, never one further left", () => {
+    // A caller sent "198.51.100.66"; the one trusted proxy appended the real client.
+    const chain = forwarded("198.51.100.66, 203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(2))).toBe("198.51.100.66");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(
+      resolveClientAddress(new Headers({ "x-real-ip": "203.0.113.8" }), "10.0.0.9", {
+        trustedProxyHops: 1,
+        header: "x-real-ip",
+      }),
+    ).toBe("203.0.113.8");
+  });
+
+  it("falls back to the peer for a short or malformed chain", () => {
+    expect(resolveClientAddress(new Headers(), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(2))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("attacker-controlled"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7, not-an-ip"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+  });
+
+  it("reads the address the API set", () => {
+    expect(clientAddressOf(new Headers({ [CLIENT_ADDRESS_HEADER]: "203.0.113.7" }))).toBe("203.0.113.7");
+    expect(clientAddressOf(new Headers())).toBeUndefined();
+    expect(clientAddressOf(undefined)).toBeUndefined();
+  });
+});
+
+describe("client address settings", () => {
+  it("validates the trusted proxy settings and refuses the rate limiter's former names", () => {
+    expect(validateEnv({})).toMatchObject({ TRUSTED_PROXY_HOPS: 0, TRUSTED_PROXY_HEADER: "x-forwarded-for" });
+    expect(validateEnv({ TRUSTED_PROXY_HOPS: "1", TRUSTED_PROXY_HEADER: "X-Real-IP" }))
+      .toMatchObject({ TRUSTED_PROXY_HOPS: 1, TRUSTED_PROXY_HEADER: "x-real-ip" });
+    expect(() => validateEnv({ TRUSTED_PROXY_HOPS: "-1" })).toThrow("TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ TRUSTED_PROXY_HEADER: "bad header" })).toThrow("TRUSTED_PROXY_HEADER");
+    expect(() => validateEnv({ RATE_LIMIT_TRUSTED_PROXY_HOPS: "1" }))
+      .toThrow("RATE_LIMIT_TRUSTED_PROXY_HOPS was renamed to TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ RATE_LIMIT_PROXY_HEADER: "x-forwarded-for" }))
+      .toThrow("RATE_LIMIT_PROXY_HEADER was renamed to TRUSTED_PROXY_HEADER");
+  });
+});
+
+describe("stampClientAddress", () => {
+  const request = (headers: Record<string, string>): Request => new Request("http://localhost/x", { headers });
+
+  it("replaces a caller's own address header and ignores its forwarded header without trusted proxies", () => {
+    const spoofed = request({ "x-forwarded-for": "198.51.100.66", [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(spoofed, "::ffff:127.0.0.1", config(0))).toBe("127.0.0.1");
+    expect(clientAddressOf(spoofed.headers)).toBe("127.0.0.1");
+  });
+
+  it("records the rightmost forwarded entry behind one trusted proxy", () => {
+    const proxied = request({ "x-forwarded-for": "198.51.100.66, 203.0.113.7" });
+    expect(stampClientAddress(proxied, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(clientAddressOf(proxied.headers)).toBe("203.0.113.7");
+  });
+
+  it("removes a caller's value when no address can be resolved", () => {
+    const unknown = request({ [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(unknown, undefined, config(0))).toBeUndefined();
+    expect(clientAddressOf(unknown.headers)).toBeUndefined();
+  });
+});

package/dist/templates/fullstack/apps/api/src/core/client-address.ts

@@ -0,0 +1,68 @@
+import { isIP } from "node:net";
+
+/**
+ * The request header that carries the client address the API resolved. The API
+ * sets it on every request before any handler runs, replacing whatever a caller
+ * sent, so Better Auth, audit entries, and application code read one address
+ * that a caller cannot choose.
+ */
+export const CLIENT_ADDRESS_HEADER = "x-podokit-client-address";
+
+export interface ClientAddressConfig {
+  /** Reverse proxies in front of the API whose forwarded header is trusted; 0 trusts none. */
+  trustedProxyHops: number;
+  /** The lowercase header those proxies append the client address to. */
+  header: string;
+}
+
+/** An IP address without its IPv4-mapped IPv6 prefix, or undefined when the value is not one. */
+export function normalizeIp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const normalized = trimmed.startsWith("::ffff:") ? trimmed.slice("::ffff:".length) : trimmed;
+  return isIP(normalized) === 0 ? undefined : normalized;
+}
+
+/**
+ * The caller's address. With no trusted proxy it is the socket peer. Otherwise
+ * each trusted proxy appended one entry to the header, so the client is the
+ * entry that many places left of the peer; entries further left were written
+ * by the caller and are ignored. A chain shorter than the trusted hops, or a
+ * malformed entry, falls back to the peer instead of trusting caller input.
+ */
+export function resolveClientAddress(
+  headers: Headers,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const direct = normalizeIp(remoteAddress);
+  if (config.trustedProxyHops === 0) return direct;
+  const forwarded = headers.get(config.header)
+    ?.split(",")
+    .map((value) => value.trim())
+    .filter(Boolean) ?? [];
+  const chain = [...forwarded, direct ?? ""];
+  if (chain.length <= config.trustedProxyHops) return direct;
+  return normalizeIp(chain[chain.length - config.trustedProxyHops - 1]) ?? direct;
+}
+
+/**
+ * Resolves a request's client address and records it in CLIENT_ADDRESS_HEADER,
+ * replacing any value the caller sent. The API does this for every request
+ * before a guard, Better Auth, or a handler reads the request.
+ */
+export function stampClientAddress(
+  request: Request,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const address = resolveClientAddress(request.headers, remoteAddress, config);
+  if (address) request.headers.set(CLIENT_ADDRESS_HEADER, address);
+  else request.headers.delete(CLIENT_ADDRESS_HEADER);
+  return address;
+}
+
+/** The address the API resolved for a request, as set in CLIENT_ADDRESS_HEADER. */
+export function clientAddressOf(headers: Headers | undefined): string | undefined {
+  return headers?.get(CLIENT_ADDRESS_HEADER) ?? undefined;
+}

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -6,6 +6,8 @@ import {
 } from "@podosoft/podokit-runtime";
 import type { AppEnv } from "../config/env.validation";
 import { Database } from "../database/database";
+import { migrationSet } from "../database/migration-files";
+import { MIGRATIONS_READINESS_CHECK, pendingMigrationsCheck } from "../database/migration-readiness";
 import { DATABASE_READINESS_CHECK, ReadinessService } from "../health/readiness.service";
 
 export type { ServiceKey } from "@podosoft/podokit-runtime";
@@ -280,7 +282,10 @@ export class AccessPolicy {
 
 export interface RequestGuardContext {
   request: Request;
+  /** The socket peer. */
   remoteAddress?: string;
+  /** The caller's address behind the trusted proxies; see core/client-address.ts. */
+  clientAddress?: string;
   setHeader: (name: string, value: string) => void;
 }
 
@@ -305,6 +310,31 @@ export interface RequestIdentity {
   activeOrganizationId(request: Request): Promise<string | undefined>;
 }
 
+/** A session the API resolved while handling a request. */
+export interface ResolvedSession {
+  /** The session token without its cookie signature. */
+  token: string;
+  userId: string;
+  expiresAt: Date;
+}
+
+/**
+ * Passes each session the API resolves for a request to the modules that listen,
+ * so they can use it without a session lookup of their own. The auth module
+ * reports; the rate limiter listens to count a signed-in caller per user.
+ */
+export class ResolvedSessions {
+  private readonly listeners: Array<(session: ResolvedSession) => void> = [];
+
+  listen(listener: (session: ResolvedSession) => void): void {
+    this.listeners.push(listener);
+  }
+
+  report(session: ResolvedSession): void {
+    for (const listener of this.listeners) listener(session);
+  }
+}
+
 export interface OpenApiContribution {
   document: Record<string, unknown>;
   pathPrefix?: string;
@@ -331,6 +361,7 @@ export const LOGGER = Symbol("logger") as ServiceKey<Logger>;
 export const ACCESS_POLICY = Symbol("access-policy") as ServiceKey<AccessPolicy>;
 export const REQUEST_GUARDS = Symbol("request-guards") as ServiceKey<RequestGuardRegistry>;
 export const REQUEST_IDENTITY = Symbol("request-identity") as ServiceKey<RequestIdentity>;
+export const RESOLVED_SESSIONS = Symbol("resolved-sessions") as ServiceKey<ResolvedSessions>;
 export const OPENAPI = Symbol("openapi") as ServiceKey<OpenApiRegistry>;
 
 export interface AppContext {
@@ -381,6 +412,17 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
   });
   services.register(READINESS, readiness);
   readiness.register(DATABASE_READINESS_CHECK, () => services.resolve(DATABASE).ping());
+  if (env.NODE_ENV === "production") {
+    // Throws when the build output lacks its migration list, so the API does not
+    // start without knowing which migrations its schema needs.
+    const migrations = migrationSet({ production: true });
+    if (migrations.compiled) {
+      readiness.register(
+        MIGRATIONS_READINESS_CHECK,
+        pendingMigrationsCheck(() => services.resolve(DATABASE).sql, migrations),
+      );
+    }
+  }
   services.register(LOGGER, logger);
   services.register(ACCESS_POLICY, accessPolicy);
   services.register(REQUEST_GUARDS, requestGuards);
@@ -390,6 +432,7 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
     roles: async () => [],
     activeOrganizationId: async () => undefined,
   });
+  services.register(RESOLVED_SESSIONS, new ResolvedSessions());
   services.register(OPENAPI, openapiRegistry);
   return services;
 }

package/dist/templates/fullstack/apps/api/src/database/data-source.spec.ts

@@ -1,6 +1,17 @@
 import { describe, expect, it } from "bun:test";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { Column, Entity, PrimaryColumn } from "typeorm";
 import { PROVIDERS } from "../config/providers";
+import { APP_ENTITIES } from "./entities";
+
+@Entity("probe_item")
+class ProbeItem {
+  @PrimaryColumn()
+  id!: string;
+
+  @Column()
+  count!: number;
+}
 
 function databaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
@@ -13,3 +24,19 @@ describe.skipIf(databaseProvider() !== "postgres")("migration data source", () =
     expect(dataSourceOptions.migrationsTransactionMode).toBe("each");
   });
 });
+
+describe("application entities", () => {
+  // The TypeORM data source serves PostgreSQL; SQLite migrates without it.
+  it.skipIf(databaseProvider() !== "postgres")("loads the entities of the owned entities.ts", async () => {
+    const { dataSourceOptions } = await import("./data-source.js");
+    expect(dataSourceOptions.entities).toBe(APP_ENTITIES);
+  });
+
+  it("compiles TypeORM entity decorators with their design types", () => {
+    // TypeORM infers a column's type from this metadata.
+    const designType = (Reflect as unknown as {
+      getMetadata(key: string, target: object, property: string): unknown;
+    }).getMetadata("design:type", ProbeItem.prototype, "count");
+    expect(designType).toBe(Number);
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/data-source.ts

@@ -1,20 +1,18 @@
 import "dotenv/config";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { DataSource, type DataSourceOptions } from "typeorm";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { PROVIDERS } from "../config/providers";
 import { validateEnv } from "../config/env.validation";
 import { databaseUrl, sqliteDatabasePath } from "./database";
+import { APP_ENTITIES } from "./entities";
+import { migrationPaths, migrationSet } from "./migration-files";
 
-const compiledMigrations = join(process.cwd(), "dist", "migrations");
-const migrations = existsSync(compiledMigrations)
-  ? [join(compiledMigrations, "[0-9]*.js")]
-  : [join(process.cwd(), "src", "migrations", "[0-9]*.ts")];
+/** The migrations the data source loads; compare them with `assertMigrationsLoaded`. */
+export const appMigrations = migrationSet();
 
 const commonOptions = {
-  entities: [],
-  migrations,
+  entities: APP_ENTITIES,
+  migrations: migrationPaths(appMigrations),
   // One transaction per migration, so a migration can set `transaction = false`
   // for statements such as CREATE INDEX CONCURRENTLY.
   migrationsTransactionMode: "each" as const,
@@ -44,6 +42,5 @@ export const dataSourceOptions: DataSourceOptions = databaseProvider() === "sqli
       ...commonOptions,
     };
 
-// Used by the TypeORM CLI for migrations (see package.json scripts).
+// The TypeORM CLI (see package.json scripts) takes the file's only DataSource export.
 export const appDataSource = new DataSource(dataSourceOptions);
-export default appDataSource;

package/dist/templates/fullstack/apps/api/src/database/database.spec.ts

@@ -86,6 +86,18 @@ describe("database provider", () => {
     expect(() => databaseUrl({ ...env, DATABASE_URL })).toThrow("DATABASE_URL must use");
   });
 
+  it("puts the default SQLite database at SQLITE_PATH", () => {
+    const root = mkdtempSync(join(tmpdir(), "podokit-sqlite-"));
+    try {
+      const path = join(root, "state", "app.sqlite");
+      expect(databaseUrl({ ...env, SQLITE_PATH: path }, "sqlite")).toBe(`sqlite://${path}`);
+      expect(existsSync(dirname(path))).toBe(true);
+      expect(databaseUrl(env, "sqlite")).toBe(`sqlite://${join(process.cwd(), "data/podokit.sqlite")}`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   it("creates the parent directory for an explicit SQLite database", () => {
     const root = mkdtempSync(join(tmpdir(), "podokit-sqlite-"));
     try {

package/dist/templates/fullstack/apps/api/src/database/database.ts

@@ -14,8 +14,7 @@ function selectedDatabaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
 }
 
-export function databaseUrl(env: AppEnv): string {
-  const provider = selectedDatabaseProvider();
+export function databaseUrl(env: AppEnv, provider: DatabaseProviderName = selectedDatabaseProvider()): string {
   if (env.DATABASE_URL) {
     if (provider === "sqlite" && !isSqliteUrl(env.DATABASE_URL)) {
       throw new Error("DATABASE_URL must use sqlite:, file:, or :memory: for the SQLite provider");
@@ -26,7 +25,7 @@ export function databaseUrl(env: AppEnv): string {
     return env.DATABASE_URL;
   }
   if (provider === "sqlite") {
-    const path = resolve("./data/podokit.sqlite");
+    const path = resolve(env.SQLITE_PATH);
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     return `sqlite://${path}`;
   }

package/dist/templates/fullstack/apps/api/src/database/entities.ts

@@ -0,0 +1,12 @@
+import type { DataSourceOptions } from "typeorm";
+
+// This owned file is never overwritten by `podo update`. List the
+// application's TypeORM entities here: the migration data source loads them,
+// so `migration:generate` compares them with the database and code that uses
+// `appDataSource` gets their repositories. For example:
+//
+//   import { Invoice } from "../invoices/invoice.entity";
+//   export const APP_ENTITIES: AppEntities = [Invoice];
+export type AppEntities = NonNullable<DataSourceOptions["entities"]>;
+
+export const APP_ENTITIES: AppEntities = [];