feat(db)!: SnapOtter 2.0 phase 1 foundation: postgres, migrator, compose stack (#216)

* feat(infra): add dev compose stack with postgres and redis

* fix(infra): comment dev env defaults until wired; harden dev compose restart and start_period

* chore(deps): add pg driver and testcontainers for postgres migration

* feat(db): translate schema to drizzle pg-core (timestamptz, boolean, pgEnum, jsonb)

Schema translation (apps/api/src/db/schema.ts):
- sqlite-core -> pg-core, all 10 tables preserved 1:1
- integer(mode:'timestamp') -> timestamp({ withTimezone: true })
- integer(mode:'boolean') -> boolean
- jobs.status text enum -> pgEnum('job_status') with same 4 values
- 7 columns changed from text to jsonb: jobs.inputFiles, jobs.settings,
  pipelines.steps, apiKeys.permissions, roles.permissions,
  auditLog.details, userFiles.toolChain
- settings.value stays text, jobs.error stays text, jobs.progress stays real

jsonb call-site sweep (removed JSON.stringify on writes, JSON.parse on reads):
- apps/api/src/routes/roles.ts: permissions read/write (3 sites)
- apps/api/src/routes/api-keys.ts: permissions write + read (2 sites)
- apps/api/src/routes/audit-log.ts: details read (1 site)
- apps/api/src/routes/pipeline.ts: steps write + read (2 sites)
- apps/api/src/routes/progress.ts: inputFiles write (2 sites)
- apps/api/src/routes/tool-factory.ts: toolChain read + write (2 sites)
- apps/api/src/routes/user-files.ts: toolChain read + write (4 sites)
- apps/api/src/permissions.ts: roles.permissions read (1 site)
- apps/api/src/lib/audit.ts: details write (1 site)
- apps/api/src/plugins/auth.ts: apiKeys.permissions read (1 site)

* refactor(db): type jsonb columns via $type and note raw CTE conversion requirements

* feat(db): archive sqlite migrations and generate postgres baseline

* chore(db): dockerignore legacy migrations, add archive breadcrumb, fix trailing newline

* feat(db): pg pool connection, advisory-locked boot migrations, DATABASE_URL config

* fix(db): friendly fatal on unreachable postgres, idempotent closeDb, lock-key convention note

* refactor(db): async drizzle calls in plugins, lib, permissions

* fix(api): analytics never throws, typed permission guard, single-query session invalidation

* refactor(db): async drizzle calls across all routes and bootstrap

Convert every route file and index.ts from sync SQLite drizzle
patterns to async node-postgres drizzle:

- .all() removed (bare await on select)
- .get() converted to destructured [row] = await ...
- .run() removed (bare await on insert/update/delete)
- .changes replaced with .rowCount (null-guarded) in progress.ts
- sqlite import removed from user-files.ts; raw CTEs converted to
  await db.execute(sql`...`) with postgres-dialect recursive CTEs
- ChainRow types updated: tool_chain is parsed jsonb (string[] | null),
  created_at is Date (timestamptz) with no * 1000 conversion
- All requirePermission() guard calls awaited (security: unawaited
  async guard returns truthy Promise, bypassing permission check)
- All hasEffectivePermission() and getPermissions() calls awaited
- All auditLog() calls awaited (preserves write-before-response order)
- trackEvent() and captureException() left un-awaited (fire-and-forget
  by design, guaranteed never-throw)
- ensureAnonymousUser(), startCleanupCron(), recoverStaleJobs() awaited
  in bootstrap sequence
- ensureInstanceId() and ensureDefaultSettings() made async

Files converted: 14 (index.ts + 12 route files + tools/index.ts)

* fix(db): await async checkStorageQuota in user-files upload/save routes

* fix(db): await checkStorageQuota in save-result route (missed second call site)

* feat(db): sqlite-to-postgres migrator with CLI and first-boot import

* fix(db): migrator error context, honest force semantics, boot-hook fatal, null-variance tests

* test: run suite against per-file postgres databases via testcontainers

- Add tests/global-setup.ts: spins up a Postgres testcontainer,
  creates a migrated template database once per vitest run.
- Rewrite tests/setup/per-fork-env.ts: each test file (forks pool)
  clones the template into its own database via CREATE DATABASE ...
  TEMPLATE, preserving the same per-file isolation granularity.
- Update vitest.config.ts: add globalSetup, pg alias, update comment.
- Fix tests/integration/test-server.ts: remove DB_PATH mkdir, async
  runMigrations, async db operations, remove SQLite WAL checkpoint.
- Fix 21 unit test db/index mocks: add pool and closeDb exports.
- Fix 8 unit test files: add async/await for now-async permission,
  audit, and analytics functions.
- Fix 18 integration test files: convert sync .run()/.all()/.get()
  to async drizzle patterns, add async to callbacks.
- Production change: apps/api/src/routes/teams.ts: cast COUNT(*)
  to ::int so Postgres returns a number instead of bigint string.

* fix(db): seed built-in roles, reject NUL bytes, cast COUNT, serialize job persists

- Seed built-in roles (admin, editor, user) at boot via ensureBuiltinRoles()
  with onConflictDoNothing, restoring data that legacy SQLite migration 0007
  provided via INSERT statements (the pg baseline is DDL-only).
- Reject NUL bytes in login credentials with 401 (postgres rejects \x00 in
  text columns; valid usernames never contain NUL, matching 1.x behavior).
- Cast COUNT(*)::int in user-files, audit-log, and roles listing queries so
  postgres returns a JS number instead of bigint-as-string.
- Serialize fire-and-forget job progress DB writes per jobId so the final
  "completed" status is never overwritten by a late-arriving "processing"
  write (race condition exposed by async postgres round-trips).

* test: fix teams race, seed roles in test server, poll for job status

- Add missing await to resetTeams() in teams PUT beforeEach (the async
  delete raced with the subsequent insert under postgres).
- Call ensureBuiltinRoles() in test server bootstrap so integration tests
  have the same built-in roles as production.
- Replace fixed 100ms flushPersist delay with a polling helper that waits
  for terminal job status, eliminating timing-dependent failures caused by
  postgres network round-trip latency.

* test: make heic temp-file cleanup assertion resilient to concurrent workers

Use a set-based diff instead of raw file count when checking that
decodeHeic cleans up temp files. Other concurrent test workers can
create heic-in-*/heic-out-* files in the shared tmpdir, inflating the
"after" count and causing spurious failures under full-suite load.

* fix(db): align builtin-role seed to post-0010 legacy state; test polish

* feat(docker): three-container compose (app, postgres, redis) with boot wait and migrations

* fix(docker): set TEST_DATABASE_URL so containerized tests skip testcontainers

* chore(docker): test compose project name, clearer 1.x upgrade comment, unref probe timer

* feat(enterprise): enforce D15 license boundary; move s3 storage into packages/enterprise

* fix(enterprise): restore lazy aws-sdk loading; community installs load no s3 code at boot

* fix(enterprise): boundary check catches dynamic imports; document getS3 concurrency

* feat(db)!: SnapOtter 2.0 phase 1 foundation: postgres, migrator, compose stack

BREAKING CHANGE: SQLite is no longer the runtime database. Deployments now
require Postgres (and Redis, used from phase 2). Existing installs migrate
with SQLITE_MIGRATE_PATH or 'pnpm --filter @snapotter/api migrate:sqlite'.

* fix(ci): postgres service + fresh e2e database per run; ignore unfixable torch CVE-2025-3000

tests/integration/oidc-auth.test.ts

@@ -35,38 +35,36 @@ afterAll(async () => {
  * Insert an OIDC-only user directly into the DB (no passwordHash).
  * Returns a session token for the user.
  */
-function createOidcUser(opts: { username?: string; email?: string; role?: string } = {}): {
+async function createOidcUser(
+  opts: { username?: string; email?: string; role?: string } = {},
+): Promise<{
   userId: string;
   username: string;
   sessionToken: string;
-} {
+}> {
   const userId = randomUUID();
   const username = opts.username || `oidc_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
 
-  db.insert(schema.users)
-    .values({
-      id: userId,
-      username,
-      passwordHash: null,
-      role: opts.role || "user",
-      team: "default-team-00000000",
-      mustChangePassword: false,
-      authProvider: "oidc",
-      externalId: `sub-${userId}`,
-      email: opts.email || `${username}@example.com`,
-    })
-    .run();
+  await db.insert(schema.users).values({
+    id: userId,
+    username,
+    passwordHash: null,
+    role: opts.role || "user",
+    team: "default-team-00000000",
+    mustChangePassword: false,
+    authProvider: "oidc",
+    externalId: `sub-${userId}`,
+    email: opts.email || `${username}@example.com`,
+  });
 
   // Create a session (simulates what the OIDC callback would do)
   const sessionToken = randomUUID();
-  db.insert(schema.sessions)
-    .values({
-      id: sessionToken,
-      userId,
-      expiresAt: new Date(Date.now() + 3_600_000),
-      idToken: "mock-id-token-jwt",
-    })
-    .run();
+  await db.insert(schema.sessions).values({
+    id: sessionToken,
+    userId,
+    expiresAt: new Date(Date.now() + 3_600_000),
+    idToken: "mock-id-token-jwt",
+  });
 
   return { userId, username, sessionToken };
 }
@@ -74,26 +72,24 @@ function createOidcUser(opts: { username?: string; email?: string; role?: string
 /**
  * Insert a session for an existing user with custom options.
  */
-function createOidcSession(
+async function createOidcSession(
   userId: string,
   opts: { expiresAt?: Date; idToken?: string | null } = {},
-): string {
+): Promise<string> {
   const sessionToken = randomUUID();
-  db.insert(schema.sessions)
-    .values({
-      id: sessionToken,
-      userId,
-      expiresAt: opts.expiresAt ?? new Date(Date.now() + 3_600_000),
-      idToken: opts.idToken ?? null,
-    })
-    .run();
+  await db.insert(schema.sessions).values({
+    id: sessionToken,
+    userId,
+    expiresAt: opts.expiresAt ?? new Date(Date.now() + 3_600_000),
+    idToken: opts.idToken ?? null,
+  });
   return sessionToken;
 }
 
 /**
  * Insert a "hybrid" user -- has both a local password AND an OIDC link.
  */
-function _createHybridUser(
+async function _createHybridUser(
   passwordHash: string,
   opts: { username?: string; email?: string } = {},
 ): { userId: string; username: string; sessionToken: string } {
@@ -101,28 +97,24 @@ function _createHybridUser(
   const username =
     opts.username || `hybrid_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
 
-  db.insert(schema.users)
-    .values({
-      id: userId,
-      username,
-      passwordHash,
-      role: "user",
-      team: "default-team-00000000",
-      mustChangePassword: false,
-      authProvider: "oidc",
-      externalId: `sub-${userId}`,
-      email: opts.email || `${username}@example.com`,
-    })
-    .run();
+  await db.insert(schema.users).values({
+    id: userId,
+    username,
+    passwordHash,
+    role: "user",
+    team: "default-team-00000000",
+    mustChangePassword: false,
+    authProvider: "oidc",
+    externalId: `sub-${userId}`,
+    email: opts.email || `${username}@example.com`,
+  });
 
   const sessionToken = randomUUID();
-  db.insert(schema.sessions)
-    .values({
-      id: sessionToken,
-      userId,
-      expiresAt: new Date(Date.now() + 3_600_000),
-    })
-    .run();
+  await db.insert(schema.sessions).values({
+    id: sessionToken,
+    userId,
+    expiresAt: new Date(Date.now() + 3_600_000),
+  });
 
   return { userId, username, sessionToken };
 }
@@ -132,7 +124,7 @@ function _createHybridUser(
 // =====================================================================
 describe("Session response fields", () => {
   it("returns OIDC fields for an OIDC user session", async () => {
-    const { sessionToken, username } = createOidcUser();
+    const { sessionToken, username } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "GET",
@@ -185,7 +177,7 @@ describe("Session response fields", () => {
 // =====================================================================
 describe("Password guards for OIDC users", () => {
   it("OIDC user (no passwordHash) cannot change password", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -203,7 +195,7 @@ describe("Password guards for OIDC users", () => {
   });
 
   it("admin cannot reset password for OIDC user", async () => {
-    const { userId } = createOidcUser();
+    const { userId } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -223,7 +215,7 @@ describe("Password guards for OIDC users", () => {
 // =====================================================================
 describe("Users list includes OIDC fields", () => {
   it("GET /api/auth/users includes authProvider, hasLocalPassword, hasOidcLink", async () => {
-    const { username: oidcUsername } = createOidcUser();
+    const { username: oidcUsername } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "GET",
@@ -251,7 +243,7 @@ describe("Users list includes OIDC fields", () => {
   });
 
   it("users list does not expose passwordHash or externalId directly", async () => {
-    createOidcUser();
+    await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "GET",
@@ -275,7 +267,7 @@ describe("Users list includes OIDC fields", () => {
 describe("Backward compatibility", () => {
   it("local login still works when OIDC users exist in the DB", async () => {
     // Create an OIDC user (just to prove it doesn't break local login)
-    createOidcUser();
+    await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -290,7 +282,7 @@ describe("Backward compatibility", () => {
   });
 
   it("OIDC user cannot log in via local login (no passwordHash)", async () => {
-    const { username } = createOidcUser();
+    const { username } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -641,7 +633,7 @@ describe("OIDC callback edge cases", () => {
 // =====================================================================
 describe("Admin operations on OIDC users", () => {
   it("admin can delete an OIDC user", async () => {
-    const { userId } = createOidcUser();
+    const { userId } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "DELETE",
@@ -652,12 +644,12 @@ describe("Admin operations on OIDC users", () => {
     expect(res.statusCode).toBe(200);
 
     // Verify user is gone
-    const user = db.select().from(schema.users).where(eq(schema.users.id, userId)).get();
+    const [user] = await db.select().from(schema.users).where(eq(schema.users.id, userId));
     expect(user).toBeUndefined();
   });
 
   it("admin can update role of an OIDC user", async () => {
-    const { userId } = createOidcUser();
+    const { userId } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "PUT",
@@ -668,7 +660,7 @@ describe("Admin operations on OIDC users", () => {
 
     expect(res.statusCode).toBe(200);
 
-    const user = db.select().from(schema.users).where(eq(schema.users.id, userId)).get();
+    const [user] = await db.select().from(schema.users).where(eq(schema.users.id, userId));
     expect(user?.role).toBe("editor");
   });
 });
@@ -678,7 +670,7 @@ describe("Admin operations on OIDC users", () => {
 // =====================================================================
 describe("Cookie-based session auth", () => {
   it("OIDC session cookie works for authenticated requests", async () => {
-    const { sessionToken, username } = createOidcUser();
+    const { sessionToken, username } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "GET",
@@ -693,7 +685,7 @@ describe("Cookie-based session auth", () => {
   });
 
   it("Both cookie and Bearer work simultaneously", async () => {
-    const { sessionToken: oidcToken, username: oidcUsername } = createOidcUser();
+    const { sessionToken: oidcToken, username: oidcUsername } = await createOidcUser();
 
     // Bearer token for local user (admin)
     const bearerRes = await testApp.app.inject({
@@ -735,10 +727,10 @@ describe("Cookie-based session auth", () => {
 // =====================================================================
 describe("Session expiry", () => {
   it("expired OIDC session returns 401", async () => {
-    const { userId } = createOidcUser();
+    const { userId } = await createOidcUser();
 
     // Create a session that expired 10 minutes ago
-    const expiredToken = createOidcSession(userId, {
+    const expiredToken = await createOidcSession(userId, {
       expiresAt: new Date(Date.now() - 600_000),
     });
 
@@ -751,11 +743,10 @@ describe("Session expiry", () => {
     expect(res.statusCode).toBe(401);
 
     // Verify the expired session was cleaned up from DB
-    const session = db
+    const [session] = await db
       .select()
       .from(schema.sessions)
-      .where(eq(schema.sessions.id, expiredToken))
-      .get();
+      .where(eq(schema.sessions.id, expiredToken));
     expect(session).toBeUndefined();
   });
 });
@@ -765,7 +756,7 @@ describe("Session expiry", () => {
 // =====================================================================
 describe("API keys for OIDC users", () => {
   it("OIDC user can create an API key", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -781,7 +772,7 @@ describe("API keys for OIDC users", () => {
   });
 
   it("API key works for auth after creation", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     // Create the API key via cookie auth
     const createRes = await testApp.app.inject({
@@ -824,7 +815,7 @@ describe("API keys for OIDC users", () => {
 // =====================================================================
 describe("Logout", () => {
   it("logout clears the snapotter-session cookie", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     const res = await testApp.app.inject({
       method: "POST",
@@ -850,14 +841,13 @@ describe("Logout", () => {
   });
 
   it("session is deleted from DB after logout", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     // Verify session exists before logout
-    const before = db
+    const [before] = await db
       .select()
       .from(schema.sessions)
-      .where(eq(schema.sessions.id, sessionToken))
-      .get();
+      .where(eq(schema.sessions.id, sessionToken));
     expect(before).toBeDefined();
 
     await testApp.app.inject({
@@ -867,16 +857,15 @@ describe("Logout", () => {
     });
 
     // Verify session is gone
-    const after = db
+    const [after] = await db
       .select()
       .from(schema.sessions)
-      .where(eq(schema.sessions.id, sessionToken))
-      .get();
+      .where(eq(schema.sessions.id, sessionToken));
     expect(after).toBeUndefined();
   });
 
   it("logout returns logoutUrl when session has idToken and OIDC discovery is cached", async () => {
-    const { sessionToken } = createOidcUser();
+    const { sessionToken } = await createOidcUser();
 
     // The default createOidcUser sets idToken to "mock-id-token-jwt".
     // Without a running OIDC provider and cached discovery, the logout