@podosoft/podokit 1.0.2 → 1.1.4

package/dist/templates/modules/auth/files/apps/api/src/auth/account-issuer-migration.ts

@@ -0,0 +1,123 @@
+import type { Database as SqliteDatabase } from "bun:sqlite";
+import type { Pool } from "pg";
+
+type MigrationRow = Record<string, unknown>;
+
+export interface AccountIssuerMigrationClient {
+  query<Row extends MigrationRow>(sql: string, values?: readonly unknown[]): Promise<readonly Row[]>;
+  release(): void;
+}
+
+export interface AccountIssuerMigrationDatabase {
+  connect(): Promise<AccountIssuerMigrationClient>;
+}
+
+export type AccountIssuerMigrationResult = "absent" | "current" | "migrated";
+
+function readCount(rows: readonly MigrationRow[]): number {
+  const value = rows[0]?.count;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  throw new Error("Cannot read account identity collision count");
+}
+
+function assertNoCollisions(count: number): void {
+  if (count > 0) {
+    throw new Error("Cannot upgrade Better Auth: duplicate providerId and accountId identities require manual resolution");
+  }
+}
+
+export function postgresAccountIssuerMigrationDatabase(pool: Pool): AccountIssuerMigrationDatabase {
+  return {
+    connect: async (): Promise<AccountIssuerMigrationClient> => {
+      const client = await pool.connect();
+      return {
+        query: async <Row extends MigrationRow>(sql: string, values?: readonly unknown[]): Promise<readonly Row[]> => {
+          const result = await client.query<Row>(sql, values === undefined ? undefined : [...values]);
+          return result.rows;
+        },
+        release: (): void => client.release(),
+      };
+    },
+  };
+}
+
+/** Relax the obsolete 1.7.0-1.7.2 issuer schema for Better Auth 1.7.3 and later. */
+export async function migrateLegacyAccountIssuers(
+  database: AccountIssuerMigrationDatabase,
+): Promise<AccountIssuerMigrationResult> {
+  const client = await database.connect();
+  let transactionOpen = false;
+  try {
+    await client.query("BEGIN");
+    transactionOpen = true;
+    await client.query("SELECT pg_advisory_xact_lock(1886350955, 1)");
+    const tableRows = await client.query<{ exists: boolean }>(`
+      SELECT to_regclass('"account"') IS NOT NULL AS "exists"
+    `);
+    if (tableRows[0]?.exists !== true) {
+      await client.query("COMMIT");
+      transactionOpen = false;
+      return "absent";
+    }
+    await client.query('LOCK TABLE "account" IN SHARE ROW EXCLUSIVE MODE');
+    const collisions = await client.query<MigrationRow>(`
+      SELECT COUNT(*)::int AS "count" FROM (
+        SELECT "providerId", "accountId" FROM "account"
+        GROUP BY "providerId", "accountId" HAVING COUNT(*) > 1
+      ) AS collisions
+    `);
+    assertNoCollisions(readCount(collisions));
+    const columns = await client.query<{ exists: boolean }>(`
+      SELECT EXISTS (
+        SELECT 1 FROM pg_attribute
+        WHERE attrelid = '"account"'::regclass AND attname = 'issuer' AND NOT attisdropped
+      ) AS "exists"
+    `);
+    await client.query('DROP TRIGGER IF EXISTS podokit_fill_legacy_account_issuer ON "account"');
+    await client.query('DROP INDEX IF EXISTS "account_issuer_accountId_uidx"');
+    if (columns[0]?.exists === true) {
+      await client.query('ALTER TABLE "account" ALTER COLUMN "issuer" DROP NOT NULL');
+    }
+    await client.query('CREATE UNIQUE INDEX IF NOT EXISTS "account_providerId_accountId_uidx" ON "account" ("providerId", "accountId")');
+    await client.query("COMMIT");
+    transactionOpen = false;
+    return columns[0]?.exists === true ? "migrated" : "current";
+  } catch (error: unknown) {
+    if (transactionOpen) await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+/** SQLite follows the upstream cleanup: remove the unused issuer column. */
+export function migrateSqliteLegacyAccountIssuers(database: SqliteDatabase): AccountIssuerMigrationResult {
+  database.run("BEGIN IMMEDIATE");
+  try {
+    const table = database.query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'account'",
+    ).get();
+    if (!table) {
+      database.run("COMMIT");
+      return "absent";
+    }
+    const collision = database.query<{ count: number }, []>(`
+      SELECT COUNT(*) AS count FROM (
+        SELECT "providerId", "accountId" FROM "account"
+        GROUP BY "providerId", "accountId" HAVING COUNT(*) > 1
+      )
+    `).get();
+    assertNoCollisions(readCount(collision ? [collision] : []));
+    const hasIssuer = database.query<{ name: string }, []>('PRAGMA table_info("account")').all()
+      .some((column) => column.name === "issuer");
+    database.run('DROP INDEX IF EXISTS "account_issuer_accountId_uidx"');
+    if (hasIssuer) database.run('ALTER TABLE "account" DROP COLUMN "issuer"');
+    database.run('CREATE UNIQUE INDEX IF NOT EXISTS "account_providerId_accountId_uidx" ON "account" ("providerId", "accountId")');
+    database.run("COMMIT");
+    return hasIssuer ? "migrated" : "current";
+  } catch (error: unknown) {
+    database.run("ROLLBACK");
+    throw error;
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-config-store.ts

@@ -1,6 +1,6 @@
 import { createConfigStore } from "@podosoft/podokit-auth";
-import { pool } from "./db";
+import { readAuthConfig } from "./db";
 
 // One process-wide store keeps the auth runtime and capabilities endpoint on the
 // same cache snapshot. Admin writes invalidate this store before rebuilding auth.
-export const authConfigStore = createConfigStore(pool);
+export const authConfigStore = createConfigStore({ list: readAuthConfig });

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.module.ts

@@ -20,6 +20,8 @@ import { getAuth, authRuntime, primeAuth } from "./auth-provider";
 import { generateAuthOpenApiDocument } from "./auth.openapi";
 import { ROLE_NAMES } from "./permissions";
 import { AuthService } from "./auth.service";
+import { configureAuthQueryDatabase } from "./db";
+import { setMailConfigStore } from "../mail/mailer";
 
 export const AUTH = Symbol("auth") as ServiceKey<AuthService>;
 export const SETTINGS = Symbol("settings") as ServiceKey<SettingsService>;
@@ -146,6 +148,8 @@ export const authModule: PodokitModule = {
   name: "auth",
   configure: (_env, services): void => {
     const database = services.resolve(DATABASE);
+    configureAuthQueryDatabase(database.sql);
+    setMailConfigStore(authConfigStore);
     const accessPolicy = services.resolve(ACCESS_POLICY);
     const settings = new SettingsService(database.sql);
     const authService = new AuthService(settings, accessPolicy);

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.service.ts

@@ -2,7 +2,7 @@ import { AppException } from "@podosoft/podokit-contracts";
 import type { AccessPolicy } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
 import { getAuth, refreshIfStale } from "./auth-provider";
-import { pool } from "./db";
+import { closeAuthDatabase } from "./db";
 
 export interface AuthUser extends Record<string, unknown> {
   id: string;
@@ -73,6 +73,6 @@ export class AuthService {
   }
 
   async close(): Promise<void> {
-    await pool.end();
+    await closeAuthDatabase();
   }
 }

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -5,7 +5,7 @@ import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
 import { assertUserCreationAllowed, createFeatureGate, createSignupOpenCheck } from "./feature-gate";
 import { orgAc, orgRoles } from "./org-permissions";
-import { pool } from "./db";
+import { authDatabase, readAppSettings } from "./db";
 import { type AuthConfig, envAuthConfig, sessionIdleOptions, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
 import { apiKey } from "@better-auth/api-key";
 import { passkey } from "@better-auth/passkey";
@@ -46,7 +46,7 @@ function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialP
 // server-enforced toggles) apply without a restart. Everything below the injection
 // markers is contributed by other PodoKit modules (admin-dashboard, audit-log).
 export function buildAuth(config: AuthConfig) {
-  const isSignupOpen = createSignupOpenCheck(pool);
+  const isSignupOpen = createSignupOpenCheck(readAppSettings);
   const plugins: BetterAuthPlugin[] = [
     twoFactor(),
     magicLink({
@@ -176,7 +176,7 @@ export function buildAuth(config: AuthConfig) {
   // real server boundary (disabled features 404). Other PodoKit modules add their
   // own hooks below the marker.
   const hooks: NonNullable<BetterAuthOptions["hooks"]> = {
-    before: createFeatureGate(pool, isSignupOpen),
+    before: createFeatureGate(readAppSettings, isSignupOpen),
   };
   // podokit:begin:auth-hooks
   // podokit:end:auth-hooks
@@ -184,7 +184,7 @@ export function buildAuth(config: AuthConfig) {
   const session = sessionIdleOptions(config.sessionIdleTimeoutMinutes);
 
   return betterAuth({
-    database: pool,
+    database: authDatabase,
     emailAndPassword: {
       enabled: true,
       // Pending email/password registrations should complete without creating a

package/dist/templates/modules/auth/files/apps/api/src/auth/db.ts

@@ -1,12 +1,57 @@
+import { Database as SqliteDatabase } from "bun:sqlite";
+import type { SQL } from "bun";
 import { Pool } from "pg";
+import type { AuthConfigRow } from "@podosoft/podokit-auth";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { validateEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
+import { databaseUrl, sqliteDatabasePath } from "../database/database";
 
-// One shared pg connection pool, in its own module so it can be imported by
-// auth.ts, the mailer, and the config store without an import cycle (auth.ts
-// imports the mailer, which needs the pool for runtime SMTP config).
-export const pool = new Pool({
-  host: process.env.POSTGRES_HOST ?? "localhost",
-  port: Number(process.env.POSTGRES_PORT ?? 5432),
-  user: process.env.POSTGRES_USER ?? "podokit",
-  password: process.env.POSTGRES_PASSWORD ?? "podokit",
-  database: process.env.POSTGRES_DB ?? "podokit",
-});
+const env = validateEnv(process.env);
+const url = databaseUrl(env);
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+const provider = databaseProvider();
+
+export const postgresPool = provider === "postgres"
+  ? new Pool({ connectionString: url })
+  : null;
+
+export const sqliteDatabase = provider === "sqlite"
+  ? new SqliteDatabase(sqliteDatabasePath(url), { create: true, strict: true })
+  : null;
+
+export const authDatabase = postgresPool ?? sqliteDatabase;
+if (!authDatabase) throw new Error("No authentication database is configured");
+
+let queryDatabase: SQL | undefined;
+
+export function configureAuthQueryDatabase(sql: SQL): void {
+  queryDatabase = sql;
+}
+
+function queries(): SQL {
+  if (!queryDatabase) throw new Error("Authentication query database is not configured");
+  return queryDatabase;
+}
+
+export async function readAppSettings(): Promise<Array<{ key: string; value: string }>> {
+  const sql = queries();
+  return sql<Array<{ key: string; value: string }>>`
+    SELECT "key", "value" FROM "app_setting"
+  `;
+}
+
+export async function readAuthConfig(): Promise<AuthConfigRow[]> {
+  const sql = queries();
+  const rows = await sql<Array<Omit<AuthConfigRow, "enabled"> & { enabled: boolean | number }>>`
+    SELECT "key", "enabled", "config", "secret", "updatedAt" FROM "auth_config"
+  `;
+  return rows.map((row) => ({ ...row, enabled: row.enabled === true || row.enabled === 1 }));
+}
+
+export async function closeAuthDatabase(): Promise<void> {
+  if (postgresPool) await postgresPool.end();
+  sqliteDatabase?.close();
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.ts

@@ -1,5 +1,4 @@
 import { APIError, createAuthMiddleware } from "better-auth/api";
-import type { Pool } from "pg";
 import { FLAG_DEFAULTS, type FeatureFlag } from "../settings/flag-defaults";
 
 export const PUBLIC_SIGNUP_DISABLED = "PUBLIC_SIGNUP_DISABLED" as const;
@@ -22,22 +21,20 @@ const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
 const CACHE_TTL_MS = 3_000;
 
 export type SignupOpenCheck = () => Promise<boolean>;
+export type AppSettingsReader = () => Promise<Array<{ key: string; value: string }>>;
 
 /** Public registration is the default until an administrator explicitly closes
  *  it. The short cache keeps every auth flow on the same live site-setting
  *  policy without rebuilding the Better Auth instance. */
-export function createSignupOpenCheck(pool: Pool): SignupOpenCheck {
+export function createSignupOpenCheck(readSettings: AppSettingsReader): SignupOpenCheck {
   let signupOpen = true;
   let fetchedAt = 0;
 
   return async (): Promise<boolean> => {
     if (Date.now() - fetchedAt < CACHE_TTL_MS) return signupOpen;
     try {
-      const res = await pool.query<{ value: string }>(
-        'SELECT "value" FROM "app_setting" WHERE "key" = $1',
-        ["site.allowSignup"],
-      );
-      signupOpen = res.rows[0]?.value !== "false";
+      const rows = await readSettings();
+      signupOpen = rows.find((row) => row.key === "site.allowSignup")?.value !== "false";
     } catch {
       signupOpen = true;
     }
@@ -67,8 +64,8 @@ export function assertUserCreationAllowed(signupOpen: boolean, requestPath?: str
  *  (a toggle takes effect within ~CACHE_TTL_MS); before the migration has run,
  *  the shipped defaults apply. */
 export function createFeatureGate(
-  pool: Pool,
-  isSignupOpen: SignupOpenCheck = createSignupOpenCheck(pool),
+  readSettings: AppSettingsReader,
+  isSignupOpen: SignupOpenCheck = createSignupOpenCheck(readSettings),
 ) {
   let cache: Record<FeatureFlag, boolean> = { ...FLAG_DEFAULTS };
   let fetchedAt = 0;
@@ -76,12 +73,11 @@ export function createFeatureGate(
   async function flags(): Promise<Record<FeatureFlag, boolean>> {
     if (Date.now() - fetchedAt < CACHE_TTL_MS) return cache;
     try {
-      const res = await pool.query<{ key: string; value: string }>(
-        'SELECT "key", "value" FROM "app_setting" WHERE "key" = ANY($1)',
-        [Object.keys(FLAG_DEFAULTS)],
-      );
+      const rows = await readSettings();
       const next = { ...FLAG_DEFAULTS };
-      for (const row of res.rows) next[row.key as FeatureFlag] = row.value === "true";
+      for (const row of rows) {
+        if (row.key in FLAG_DEFAULTS) next[row.key as FeatureFlag] = row.value === "true";
+      }
       cache = next;
     } catch {
       cache = { ...FLAG_DEFAULTS };

package/dist/templates/modules/auth/files/apps/api/src/migrate.ts

@@ -1,14 +1,33 @@
 import { getMigrations } from "better-auth/db/migration";
 import { auth } from "./auth/auth";
-import { pool } from "./auth/db";
-import dataSource from "./database/data-source";
+import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";
+import {
+  migrateLegacyAccountIssuers,
+  migrateSqliteLegacyAccountIssuers,
+  postgresAccountIssuerMigrationDatabase,
+} from "./auth/account-issuer-migration";
+import { runSqliteMigrations } from "./database/sqlite-migrator";
 
 async function runMigrations(): Promise<void> {
+  if (postgresPool) {
+    await migrateLegacyAccountIssuers(postgresAccountIssuerMigrationDatabase(postgresPool));
+  }
+  if (sqliteDatabase) migrateSqliteLegacyAccountIssuers(sqliteDatabase);
+
   const authMigrations = await getMigrations(auth.options);
   await authMigrations.runMigrations();
 
-  await dataSource.initialize();
-  await dataSource.runMigrations();
+  if (sqliteDatabase) {
+    await runSqliteMigrations(sqliteDatabase);
+  } else {
+    const { appDataSource: dataSource } = await import("./database/data-source.js");
+    await dataSource.initialize();
+    try {
+      await dataSource.runMigrations();
+    } finally {
+      await dataSource.destroy();
+    }
+  }
 }
 
 runMigrations()
@@ -17,6 +36,5 @@ runMigrations()
     process.exitCode = 1;
   })
   .finally(async (): Promise<void> => {
-    if (dataSource.isInitialized) await dataSource.destroy();
-    await pool.end();
+    await closeAuthDatabase();
   });

package/dist/templates/modules/auth/files/apps/api/src/migrations/1720400000000-InitAppSettings.ts

@@ -4,11 +4,12 @@ export class InitAppSettings1720400000000 implements MigrationInterface {
   name = "InitAppSettings1720400000000";
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    const sqlite = queryRunner.connection.options.type === "better-sqlite3";
     await queryRunner.query(`
       CREATE TABLE "app_setting" (
         "key" text NOT NULL,
         "value" text NOT NULL,
-        "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        "updatedAt" ${sqlite ? "datetime" : "TIMESTAMP WITH TIME ZONE"} NOT NULL DEFAULT ${sqlite ? "CURRENT_TIMESTAMP" : "now()"},
         CONSTRAINT "PK_app_setting_key" PRIMARY KEY ("key")
       )
     `);

package/dist/templates/modules/auth/files/apps/api/src/migrations/1720500000000-InitAuthConfig.ts

@@ -4,6 +4,7 @@ export class InitAuthConfig1720500000000 implements MigrationInterface {
   name = "InitAuthConfig1720500000000";
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    const sqlite = queryRunner.connection.options.type === "better-sqlite3";
     // Admin-managed auth configuration (OAuth providers, SMTP, server-enforced
     // toggles). Secrets (OAuth client secret, SMTP password) are stored encrypted
     // in "secret" (AES-256-GCM envelope; key derived from BETTER_AUTH_SECRET —
@@ -12,10 +13,10 @@ export class InitAuthConfig1720500000000 implements MigrationInterface {
     await queryRunner.query(`
       CREATE TABLE "auth_config" (
         "key" text NOT NULL,
-        "enabled" boolean NOT NULL DEFAULT false,
-        "config" jsonb NOT NULL DEFAULT '{}',
+        "enabled" ${sqlite ? "integer" : "boolean"} NOT NULL DEFAULT ${sqlite ? "0" : "false"},
+        "config" ${sqlite ? "text" : "jsonb"} NOT NULL DEFAULT '{}',
         "secret" text,
-        "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        "updatedAt" ${sqlite ? "datetime" : "TIMESTAMP WITH TIME ZONE"} NOT NULL DEFAULT ${sqlite ? "CURRENT_TIMESTAMP" : "now()"},
         CONSTRAINT "PK_auth_config_key" PRIMARY KEY ("key")
       )
     `);

package/dist/templates/modules/auth/files/apps/api/src/settings/app-settings.migration.spec.ts

@@ -3,16 +3,19 @@ import type { QueryRunner } from "typeorm";
 import { InitAppSettings1720400000000 } from "../migrations/1720400000000-InitAppSettings";
 
 describe("app setting migration", () => {
-  it("seeds every authentication feature and policy default", async () => {
-    const queries: string[] = [];
-    const runner = {
+  function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRunner {
+    return {
+      connection: { options: { type } },
       query: (sql: string): Promise<unknown[]> => {
         queries.push(sql);
         return Promise.resolve([]);
       },
     } as unknown as QueryRunner;
+  }
 
-    await new InitAppSettings1720400000000().up(runner);
+  it("seeds every authentication feature and policy default", async () => {
+    const queries: string[] = [];
+    await new InitAppSettings1720400000000().up(runner("postgres", queries));
 
     const seed = queries.join("\n");
     for (const key of [
@@ -31,4 +34,12 @@ describe("app setting migration", () => {
       expect(seed).toContain(`('${key}',`);
     }
   });
+
+  it("uses SQLite-compatible timestamp syntax", async () => {
+    const queries: string[] = [];
+    await new InitAppSettings1720400000000().up(runner("better-sqlite3", queries));
+    expect(queries[0]).toContain("datetime");
+    expect(queries[0]).toContain("CURRENT_TIMESTAMP");
+    expect(queries[0]).not.toContain("TIMESTAMP WITH TIME ZONE");
+  });
 });

package/dist/templates/modules/auth/files/apps/api/src/settings/auth-config.migration.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "bun:test";
+import type { QueryRunner } from "typeorm";
+import { InitAuthConfig1720500000000 } from "../migrations/1720500000000-InitAuthConfig";
+
+function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRunner {
+  return {
+    connection: { options: { type } },
+    query: (sql: string): Promise<unknown[]> => {
+      queries.push(sql);
+      return Promise.resolve([]);
+    },
+  } as unknown as QueryRunner;
+}
+
+describe("auth config migration", () => {
+  it("retains PostgreSQL boolean and JSONB columns", async () => {
+    const queries: string[] = [];
+    await new InitAuthConfig1720500000000().up(runner("postgres", queries));
+    expect(queries[0]).toContain("boolean NOT NULL DEFAULT false");
+    expect(queries[0]).toContain("jsonb NOT NULL");
+  });
+
+  it("uses SQLite integer booleans and JSON text", async () => {
+    const queries: string[] = [];
+    await new InitAuthConfig1720500000000().up(runner("better-sqlite3", queries));
+    expect(queries[0]).toContain("integer NOT NULL DEFAULT 0");
+    expect(queries[0]).toContain("text NOT NULL DEFAULT '{}'");
+    expect(queries[0]).toContain("DEFAULT CURRENT_TIMESTAMP");
+  });
+});

package/dist/templates/modules/auth/module.manifest.json

@@ -7,13 +7,13 @@
     ".claude/skills/podokit-configure-auth/**"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.3.0",
+    "@podosoft/podokit-auth": "^0.4.0",
     "@podosoft/podokit-contracts": "^0.4.0",
-    "better-auth": "^1.7.1",
+    "better-auth": "^1.7.7",
     "pg": "^8.12.0",
-    "@better-auth/api-key": "^1.7.1",
-    "@better-auth/passkey": "^1.7.1",
-    "@better-auth/oauth-provider": "^1.7.1"
+    "@better-auth/api-key": "^1.7.7",
+    "@better-auth/passkey": "^1.7.7",
+    "@better-auth/oauth-provider": "^1.7.7"
   },
   "devDependencies": {
     "@types/pg": "^8.11.10"
@@ -58,7 +58,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### auth (Better Auth + Elysia)\n- The API is secure by default: every application route needs a session except health, OpenAPI, `/api/auth/*`, and routes explicitly registered in `ACCESS_POLICY`.\n- Register a public route during module configuration with `services.resolve(ACCESS_POLICY).register(\"GET\", \"/path\", \"public\")`; use `AUTH` and `AuthService.requireSession()` or `requireAdmin()` when a handler needs the current user.\n- Configure OAuth providers, SMTP, sign-up approval, automatic logout, and server toggles on the admin Settings page. Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required environment variables.\n- Use `{{apiRun}} auth:configure{{apiWorkspaceArg}} -- ...` and `.claude/skills/podokit-configure-auth` to apply OAuth/SMTP credentials without committing secrets.\n- Run `bun run --cwd apps/api migrate:all` in development and production so Better Auth and application migrations use the versions installed by the app.\n"
+      "text": "### auth (Better Auth + Elysia)\n- The API is secure by default: every application route needs a session except health, OpenAPI, `/api/auth/*`, and routes explicitly registered in `ACCESS_POLICY`.\n- Register a public route during module configuration with `services.resolve(ACCESS_POLICY).register(\"GET\", \"/path\", \"public\")`; use `AUTH` and `AuthService.requireSession()` or `requireAdmin()` when a handler needs the current user.\n- Configure OAuth providers, SMTP, sign-up approval, automatic logout, and server toggles on the admin Settings page. Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required environment variables.\n- Use `{{apiRun}} auth:configure{{apiWorkspaceArg}} -- ...` and `.claude/skills/podokit-configure-auth` to apply OAuth/SMTP credentials without committing secrets.\n- Run `bun run --cwd apps/api migrate:all` in development and production so Better Auth and application migrations use the versions installed by the app.\n- Back up existing databases before upgrading authentication. Migrations check duplicate `(providerId, accountId)` identities and clean up obsolete issuer constraints; resolve reported collisions manually rather than guessing account ownership.\n"
     }
   ],
   "instructions": [

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/bullmq-job.queue.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "bun:test";
+import { externalJobId, parseExternalJobId } from "./bullmq-job.queue";
+
+describe("BullMQ job identifiers", () => {
+  it("round-trips queue names without exposing an ambiguous id", () => {
+    const id = externalJobId("email/delivery", "42");
+    expect(parseExternalJobId(id)).toEqual({ name: "email/delivery", id: "42" });
+    expect(parseExternalJobId("invalid")).toBeNull();
+  });
+});

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/bullmq-job.queue.ts

@@ -0,0 +1,107 @@
+import { Queue, Worker } from "bullmq";
+import type {
+  EnqueueOptions,
+  JobHandler,
+  JobQueue,
+  JobReference,
+  JobSnapshot,
+  JobStatus,
+  Unsubscribe,
+} from "@podosoft/podokit-runtime";
+import { redisConnection } from "./queue";
+
+const ID_SEPARATOR = "~";
+
+export function externalJobId(name: string, id: string): string {
+  return `${encodeURIComponent(name)}${ID_SEPARATOR}${id}`;
+}
+
+export function parseExternalJobId(id: string): { name: string; id: string } | null {
+  const separator = id.indexOf(ID_SEPARATOR);
+  if (separator < 1 || separator === id.length - 1) return null;
+  try {
+    return { name: decodeURIComponent(id.slice(0, separator)), id: id.slice(separator + 1) };
+  } catch {
+    return null;
+  }
+}
+
+function statusOf(state: string): JobStatus {
+  if (state === "active" || state === "completed" || state === "failed") return state;
+  return "waiting";
+}
+
+export class BullMqJobQueue implements JobQueue {
+  private readonly queues = new Map<string, Queue>();
+  private readonly workers = new Map<string, Worker>();
+
+  async enqueue(
+    name: string,
+    payload: unknown,
+    options: EnqueueOptions = {},
+  ): Promise<JobReference> {
+    const queue = this.queue(name);
+    const job = await queue.add(name, payload, {
+      ...(options.delayMs === undefined ? {} : { delay: options.delayMs }),
+      ...(options.attempts === undefined ? {} : { attempts: options.attempts }),
+      ...(options.deduplicationKey === undefined
+        ? {}
+        : { deduplication: { id: options.deduplicationKey } }),
+    });
+    if (job.id === undefined) throw new Error("BullMQ did not assign a job id");
+    return { id: externalJobId(name, job.id), name };
+  }
+
+  async get(externalId: string): Promise<JobSnapshot | null> {
+    const parsed = parseExternalJobId(externalId);
+    if (!parsed) return null;
+    const job = await this.queue(parsed.name).getJob(parsed.id);
+    if (!job) return null;
+    return {
+      id: externalId,
+      name: parsed.name,
+      status: statusOf(await job.getState()),
+      attempts: job.attemptsMade,
+      createdAt: job.timestamp,
+      updatedAt: job.finishedOn ?? job.processedOn ?? job.timestamp,
+      ...(job.returnvalue === undefined ? {} : { result: job.returnvalue as unknown }),
+      ...(job.failedReason ? { error: job.failedReason } : {}),
+    };
+  }
+
+  process(name: string, handler: JobHandler): Promise<Unsubscribe> {
+    if (this.workers.has(name)) throw new Error(`A handler is already registered for job ${name}`);
+    const worker = new Worker(
+      name,
+      async (job): Promise<void> => {
+        await handler(job.data as unknown, {
+          id: externalJobId(name, String(job.id)),
+          name,
+        });
+      },
+      { connection: redisConnection() },
+    );
+    this.workers.set(name, worker);
+    return Promise.resolve(async () => {
+      this.workers.delete(name);
+      await worker.close();
+    });
+  }
+
+  async close(): Promise<void> {
+    await Promise.all([
+      ...[...this.workers.values()].map((worker) => worker.close()),
+      ...[...this.queues.values()].map((queue) => queue.close()),
+    ]);
+    this.workers.clear();
+    this.queues.clear();
+  }
+
+  private queue(name: string): Queue {
+    const current = this.queues.get(name);
+    if (current) return current;
+    const queue = new Queue(name, { connection: redisConnection() });
+    this.queues.set(name, queue);
+    return queue;
+  }
+}