@everystack/server 0.2.26 → 0.3.1

package/README.md

@@ -125,6 +125,47 @@ Returns PostgreSQL connection URL from SST Resources.
 
 Returns JWT secret as `Uint8Array` from `Resource.JwtSecret.value`.
 
+## Database operations (`dbPlugin`)
+
+`dbPlugin` registers the operator actions the CLI invokes over IAM-authed Lambda invoke (no HTTP, no shared secret). Add it to the ops Lambda's plugin list; it runs on the privileged operator connection (`ctx.adminDb`).
+
+```typescript
+import { dbPlugin } from '@everystack/server/plugin';
+
+dbPlugin({
+  migrationsFolder: join(__dirname, 'drizzle'),
+  seed: runSeed,                              // optional — registers `seed` (dev only)
+  schemas: ['auth', 'public', 'drizzle'],     // db:reset drop set (dev only)
+  backupBucket: Resource.Backups.name,        // private bucket for logical backups
+  forceRlsCarveouts: ['ops.runs'],            // ENABLE-not-FORCE tables db:doctor shouldn't flag
+});
+```
+
+Actions contributed (each is an `everystack db:*` command):
+
+| Action | Does |
+|---|---|
+| `migrate` / `seed` / `db:reset` | run migrations, seed (dev), drop+remigrate (dev) |
+| `db:psql` / `db:query` | connection info / read-only SQL via Lambda |
+| `db:doctor` | audit: is the API connection least-privilege + RLS-subject? Flags BYPASSRLS, un-FORCEd RLS, and **app-reachable tables without RLS** |
+| `db:provision` | create the least-privilege role chain on an existing DB (idempotent; roles only) |
+| `db:backup:probe` | verify the `pg_dump` layer is attached and `pg_dump` major ≥ the server major |
+| `db:backup` | `pg_dump -Fc` → gzip → S3 (streamed); awaits the child exit code, deletes the partial on failure |
+| `db:backups` | list a stage's backups |
+| `db:restore` | S3 → gunzip → `pg_restore --clean --if-exists` (requires `confirm:true`) |
+| `db:authz:probe` | run the CLI-built authorization red-team SQL in a rolled-back transaction |
+| `console` / `console:meta` | the operator REPL (db, schema, models, auth in scope) |
+
+### Backup options
+
+| Option | Type | Description |
+|---|---|---|
+| `backupBucket` | `string` | Private S3 bucket for logical backups. Pass `Resource.Backups.name`. Unset → `db:backup`/`db:backups`/`db:restore` return "backup storage not configured"; the rest of the plugin is unaffected. |
+| `backupRegion` | `string` | Region for the backups bucket. Defaults to the Lambda's `AWS_REGION`. |
+| `forceRlsCarveouts` | `string[]` | App-owned tables intentionally ENABLE-not-FORCE RLS (owner must write them), so `db:doctor` doesn't flag them. `auth.users` is always carved out. |
+
+Logical backups need the `pg_dump` Lambda layer — see [docs/backups.md](../../docs/backups.md). Credentials reach `pg_dump`/`pg_restore` as `PG*` env vars, never on argv.
+
 ## Web SSR (`@everystack/server/ssr`)
 
 Serves Expo web builds deployed via `@everystack/cli`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.26",
+  "version": "0.3.1",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -78,6 +78,7 @@
     "esbuild": ">=0.20.0",
     "@aws-sdk/client-cloudfront-keyvaluestore": ">=3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
+    "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "@aws-sdk/signature-v4a": ">=3.1048.0",
     "@everystack/auth": ">=0.1.0",
@@ -116,12 +117,17 @@
     "@aws-sdk/client-s3": {
       "optional": true
     },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
     }
   },
   "devDependencies": {
     "@aws-sdk/client-cloudfront-keyvaluestore": "3.1053.0",
+    "@aws-sdk/client-s3": "3.1053.0",
+    "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1063.0",
     "@types/aws-lambda": "8.10.161",
     "@types/jest": "29.5.14",
@@ -133,8 +139,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.2.6",
-    "@everystack/cli": "0.2.39"
+    "@everystack/auth": "0.3.0",
+    "@everystack/cli": "0.3.3"
   },
   "scripts": {
     "test": "jest",

package/src/backup-run.ts

@@ -0,0 +1,161 @@
+/**
+ * db:backup execution — spawn pg_dump/pg_restore in the ops Lambda and stream to/from S3.
+ *
+ * The streaming is the whole point: pg_dump stdout → gzip → S3 multipart upload (never buffer the
+ * dump), and the reverse for restore. The load-bearing correctness rule (see docs/plans/
+ * db-backup-restore.md): the S3 Upload resolving does NOT mean pg_dump succeeded — pg_dump can exit
+ * non-zero mid-stream while the multipart "completes". So we await the child exit code SEPARATELY
+ * and, on failure, delete the partial object. A backup tool that ships a truncated dump is worse
+ * than none.
+ *
+ * The pure helpers (key scheme, PG* env, arg builders) live in ./backup and are unit-tested; this
+ * module is the IO and is proven by a deployed smoke test.
+ */
+
+import { spawn } from 'node:child_process';
+import { createGzip, createGunzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { randomBytes } from 'node:crypto';
+import type { Readable } from 'node:stream';
+import {
+  backupPrefix, backupKey, metaKey, backupId, idForKey, keyForId, utcStamp,
+  pgEnvFromUrl, dbNameFromUrl, pgDumpArgs, pgRestoreArgs,
+} from './backup';
+
+/** Where backups live + the operator connection pg_dump/pg_restore use. */
+export interface BackupRunDeps {
+  bucket: string;
+  region?: string;
+  /** The resolved operator (privileged) connection URL — never logged, never on argv. */
+  adminUrl: string;
+}
+
+export interface BackupSummary {
+  id: string;
+  key: string;
+  bytes?: number;
+  lastModified?: string;
+}
+
+async function getS3(region?: string): Promise<any> {
+  const { S3Client } = await import('@aws-sdk/client-s3');
+  return new S3Client(region ? { region } : {});
+}
+
+/**
+ * pg_dump -Fc → gzip → S3 (multipart, streamed). Writes a `.meta.json` sidecar on success.
+ * Throws (after deleting the partial object) if pg_dump exits non-zero — the dump is never trusted
+ * on a successful upload alone.
+ */
+export async function runBackup(deps: BackupRunDeps, stage: string): Promise<BackupSummary> {
+  const { bucket, region, adminUrl } = deps;
+  const env = { ...process.env, ...pgEnvFromUrl(adminUrl) };
+  const stamp = utcStamp(new Date());
+  const shortId = randomBytes(3).toString('hex');
+  const key = backupKey(stage, stamp, shortId);
+  const mkey = metaKey(key);
+  const id = backupId(stage, stamp, shortId);
+
+  const s3 = await getS3(region);
+  const { Upload } = await import('@aws-sdk/lib-storage');
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+
+  const child = spawn('pg_dump', pgDumpArgs(), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+  });
+
+  const gzip = createGzip();
+  const upload = new Upload({
+    client: s3,
+    params: {
+      Bucket: bucket, Key: key, Body: gzip,
+      ContentType: 'application/gzip', ServerSideEncryption: 'AES256',
+    },
+  });
+
+  try {
+    await Promise.all([
+      pipeline(child.stdout!, gzip), // pg_dump → gzip; errors propagate, streams destroyed
+      upload.done(),                 // gzip → S3 multipart
+      childExit,                     // the guard: non-zero pg_dump rejects the whole thing
+    ]);
+  } catch (err) {
+    try { await upload.abort(); } catch { /* may already have completed */ }
+    await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key })).catch(() => {});
+    throw err;
+  }
+
+  let bytes: number | undefined;
+  try {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+    bytes = head.ContentLength;
+  } catch { /* size is best-effort */ }
+
+  const meta = { id, stage, createdAt: new Date().toISOString(), bytes, key };
+  await s3.send(new PutObjectCommand({
+    Bucket: bucket, Key: mkey, Body: JSON.stringify(meta),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+
+  return { id, key, bytes };
+}
+
+/** List a stage's backups (newest first) from S3 object metadata — one list call, no per-item gets. */
+export async function listBackups(deps: BackupRunDeps, stage: string): Promise<BackupSummary[]> {
+  const s3 = await getS3(deps.region);
+  const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
+  const prefix = `${backupPrefix(stage)}/`;
+  const out: BackupSummary[] = [];
+  let token: string | undefined;
+  do {
+    const res: any = await s3.send(new ListObjectsV2Command({
+      Bucket: deps.bucket, Prefix: prefix, ContinuationToken: token,
+    }));
+    for (const o of res.Contents ?? []) {
+      if (!o.Key?.endsWith('.dump.gz')) continue;
+      const id = idForKey(o.Key);
+      if (id) out.push({ id, key: o.Key, bytes: o.Size, lastModified: o.LastModified?.toISOString() });
+    }
+    token = res.IsTruncated ? res.NextContinuationToken : undefined;
+  } while (token);
+  out.sort((a, b) => (b.lastModified ?? '').localeCompare(a.lastModified ?? ''));
+  return out;
+}
+
+/**
+ * S3 → gunzip → pg_restore (--clean --if-exists) into the operator connection. Strict: a non-zero
+ * pg_restore throws with its stderr. (We start strict and observe benign-error behavior on the
+ * deploy smoke test; the flags --no-owner/--no-privileges/--no-comments remove the usual offenders.)
+ */
+export async function runRestore(deps: BackupRunDeps, id: string): Promise<{ id: string; restored: true }> {
+  const key = keyForId(id);
+  if (!key) throw new Error(`Malformed backup id: ${id}`);
+  const env = { ...process.env, ...pgEnvFromUrl(deps.adminUrl) };
+  const dbName = dbNameFromUrl(deps.adminUrl);
+
+  const s3 = await getS3(deps.region);
+  const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+  const obj: any = await s3.send(new GetObjectCommand({ Bucket: deps.bucket, Key: key }));
+  if (!obj.Body) throw new Error(`Backup not found: ${id}`);
+  const body = obj.Body as Readable;
+
+  const child = spawn('pg_restore', pgRestoreArgs(dbName), { env, stdio: ['pipe', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`pg_restore exited ${code}: ${stderr.trim()}`)));
+  });
+
+  await Promise.all([
+    pipeline(body, createGunzip(), child.stdin!), // S3 → gunzip → pg_restore stdin
+    childExit,
+  ]);
+  return { id, restored: true };
+}

package/src/backup.ts

@@ -0,0 +1,149 @@
+/**
+ * db:backup — logical pg_dump/pg_restore helpers (server side).
+ *
+ * The version gate is load-bearing: pg_dump must be >= the server's MAJOR version, and there is no
+ * bypass flag (a newer server refuses an older client; a custom-format archive won't restore under
+ * an older pg_restore). So before any dump we compare the layer's pg_dump major against the live
+ * server's `server_version_num`. The parsing/compat logic is pure and unit-tested here; the actual
+ * spawn (which needs the pg_dump layer at runtime) is exercised by the deployed db:backup:probe.
+ * See docs/plans/db-backup-restore.md.
+ */
+
+/**
+ * Parse the major version from `pg_dump --version` output, e.g.
+ * "pg_dump (PostgreSQL) 16.9" → 16. Returns null when no version can be found.
+ */
+export function parsePgDumpMajor(versionOutput: string): number | null {
+  const m = versionOutput.match(/\b(\d+)(?:\.\d+)?\s*$/) ?? versionOutput.match(/\b(\d+)\.\d+\b/);
+  return m ? Number(m[1]) : null;
+}
+
+/** The server major from libpq's `server_version_num` (e.g. 160009 → 16). */
+export function serverMajorFromNum(serverVersionNum: number): number {
+  return Math.floor(serverVersionNum / 10000);
+}
+
+/**
+ * Whether a pg_dump of `clientMajor` can safely dump/restore a server at `serverVersionNum`.
+ * The rule is simply clientMajor >= serverMajor — a newer client can read an older server, never
+ * the reverse.
+ */
+export function isDumpCompatible(clientMajor: number, serverVersionNum: number): boolean {
+  return clientMajor >= serverMajorFromNum(serverVersionNum);
+}
+
+// --- S3 key scheme (canonical; the CLI's cli/backup.ts mirrors these for display/guards) --------
+
+/** The S3 prefix all of a stage's logical backups live under (admin-only, encrypted). */
+export function backupPrefix(stage: string): string {
+  return `backups/${stage}`;
+}
+
+/** The object key for a new backup dump. `stamp` is a UTC `YYYYMMDDTHHMMSSZ` string. */
+export function backupKey(stage: string, stamp: string, shortId: string): string {
+  return `${backupPrefix(stage)}/${stamp}-${shortId}.dump.gz`;
+}
+
+/** The metadata sidecar key for a backup dump key. */
+export function metaKey(dumpKey: string): string {
+  return dumpKey.replace(/\.dump\.gz$/, '.meta.json');
+}
+
+/** A stage-qualified backup id — what `list` returns and `restore` consumes: `dev/20260628T120000Z-ab12cd`. */
+export function backupId(stage: string, stamp: string, shortId: string): string {
+  return `${stage}/${stamp}-${shortId}`;
+}
+
+/** Parse a backup id into its stage and name, or null when malformed. */
+export function parseBackupRef(id: string): { stage: string; name: string } | null {
+  const m = id.match(/^([A-Za-z0-9_-]+)\/([A-Za-z0-9_.:-]+)$/);
+  return m ? { stage: m[1], name: m[2] } : null;
+}
+
+/** The S3 dump key for a backup id (inverse of backupId), or null when malformed. */
+export function keyForId(id: string): string | null {
+  const ref = parseBackupRef(id);
+  return ref ? `${backupPrefix(ref.stage)}/${ref.name}.dump.gz` : null;
+}
+
+/** Derive the backup id from a dump key (inverse of backupKey), or null when it isn't a dump key. */
+export function idForKey(dumpKey: string): string | null {
+  const m = dumpKey.match(/^backups\/([A-Za-z0-9_-]+)\/(.+)\.dump\.gz$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Format a Date as the UTC `YYYYMMDDTHHMMSSZ` stamp (caller's clock; pure). */
+export function utcStamp(date: Date): string {
+  const p = (n: number): string => String(n).padStart(2, '0');
+  return (
+    `${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}` +
+    `T${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}Z`
+  );
+}
+
+// --- pg_dump / pg_restore invocation (PG* env from the admin URL, never argv) -------------------
+
+/**
+ * Parse a postgres connection URL into libpq's PG* environment variables. Passing the credential
+ * via env (not argv) keeps the password out of the process table. Pure; callers must never log the
+ * result (it contains PGPASSWORD). Mirrors the CLI's pgEnvFromUrl.
+ */
+export function pgEnvFromUrl(url: string): Record<string, string> {
+  const u = new URL(url);
+  if (!/^postgres(ql)?:$/.test(u.protocol)) {
+    throw new Error(`Not a postgres connection URL (protocol: ${u.protocol})`);
+  }
+  const env: Record<string, string> = {};
+  if (u.hostname) env.PGHOST = decodeURIComponent(u.hostname);
+  if (u.port) env.PGPORT = u.port;
+  if (u.username) env.PGUSER = decodeURIComponent(u.username);
+  if (u.password) env.PGPASSWORD = decodeURIComponent(u.password);
+  const database = u.pathname.replace(/^\//, '');
+  if (database) env.PGDATABASE = decodeURIComponent(database);
+  const sslmode = u.searchParams.get('sslmode');
+  if (sslmode) env.PGSSLMODE = sslmode;
+  return env;
+}
+
+/** The database name from a postgres connection URL (for pg_restore -d). */
+export function dbNameFromUrl(url: string): string {
+  return decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+}
+
+/**
+ * Args for `pg_dump` — custom format (portable, restorable under a different role/stage). The
+ * connection comes from PG* env, so no host/db on argv. --no-owner/--no-privileges/--no-comments
+ * make the dump restore cleanly into a different stage (and dodge the RDS plpgsql-comment error).
+ */
+export function pgDumpArgs(): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments'];
+}
+
+/**
+ * Args for `pg_restore` into `dbName` — drop-then-restore (--clean --if-exists), ownership-neutral.
+ * With no archive-file argument pg_restore reads the dump from stdin.
+ */
+export function pgRestoreArgs(dbName: string): string[] {
+  return ['--clean', '--if-exists', '--no-owner', '--no-privileges', '--no-comments', '-d', dbName];
+}
+
+/**
+ * Spawn `<bin> --version` and return its trimmed stdout (e.g. "pg_dump (PostgreSQL) 16.9").
+ * Rejects when the binary is missing — which, in the ops Lambda, means the pg_dump layer is not
+ * attached. `bin` defaults to `pg_dump`, resolved on PATH (the layer lands at /opt/bin, on PATH).
+ */
+export async function pgClientVersion(bin = 'pg_dump'): Promise<string> {
+  const { spawn } = await import('node:child_process');
+  return await new Promise<string>((resolve, reject) => {
+    let out = '';
+    let err = '';
+    const child = spawn(bin, ['--version']);
+    child.stdout.on('data', (d) => { out += d.toString(); });
+    child.stderr.on('data', (d) => { err += d.toString(); });
+    child.on('error', (e) => reject(e));
+    child.on('close', (code) => {
+      if (code === 0) resolve(out.trim());
+      else reject(new Error(`${bin} --version exited ${code}: ${err.trim()}`));
+    });
+  });
+}

package/src/db-doctor.ts

@@ -30,6 +30,18 @@ export interface ForceRlsRow {
   forced: boolean;
 }
 
+/** A base table an app role can reach (table- or column-level grant), with its RLS posture. */
+export interface AppGrantedRow {
+  schema: string;
+  table: string;
+  /** RLS enabled on the table. */
+  enabled: boolean;
+  /** FORCE ROW LEVEL SECURITY. */
+  forced: boolean;
+  /** The app roles holding a privilege on it (sorted). */
+  grantedTo: string[];
+}
+
 export interface DoctorProbe {
   /** The api credential's connection facts (createDb / DATABASE_URL). */
   api: ConnInfo;
@@ -37,6 +49,12 @@ export interface DoctorProbe {
   admin: ConnInfo;
   /** Tables with RLS enabled, and whether it's FORCEd. Gathered as admin. */
   forceRls: ForceRlsRow[];
+  /**
+   * Every base table reachable by an app role (anon/authenticated/admin), with its RLS
+   * posture. Drives the "we require RLS" check — a table granted to a request role with RLS
+   * OFF is the PostgREST fail-open shape. Absent on an older probe (the check is then skipped).
+   */
+  appGrantedRls?: AppGrantedRow[];
   /**
    * Result of a bare `SELECT` on an RLS table as the api connection, WITHOUT setting a
    * role. A least-privilege role (NOINHERIT, no grants of its own) must fail closed here;
@@ -44,6 +62,20 @@ export interface DoctorProbe {
    * `USING(true)` role like the master). Absent when there is no RLS table to probe.
    */
   apiAmbientRead?: { table: string; accessible: boolean };
+  /**
+   * Every SECURITY DEFINER function (schema, name, whether search_path is pinned). The
+   * `functions` teeth read this: for each schema that owns a `writtenBy: 'functions'` table
+   * (passed as `functionSchemas`), the package's SECDEF functions must exist and each must
+   * pin its search_path. Absent on an older probe (the check is then skipped).
+   */
+  secdefFunctions?: SecdefFn[];
+}
+
+/** A SECURITY DEFINER function and whether its `search_path` is pinned. */
+export interface SecdefFn {
+  schema: string;
+  name: string;
+  hasSearchPath: boolean;
 }
 
 export type CheckStatus = 'pass' | 'fail' | 'warn';
@@ -88,20 +120,107 @@ WHERE c.relkind = 'r'
 ORDER BY n.nspname, c.relname
 `.trim();
 
+/**
+ * Every SECURITY DEFINER function with whether its `search_path` is pinned. A SECDEF
+ * function runs as its owner (above RLS), so an unpinned `search_path` is a hijack vector:
+ * a caller can shadow an unqualified name the body calls and run code as the owner. This is
+ * the exact bug class that bit dev (migration 0022 went unapplied via a journal gap, leaving
+ * the auth SECDEF functions mutable) — the `functions` teeth read this to catch it on the
+ * deployed database, not just in the migration SQL (which `security:audit` already covers).
+ */
+export const SECDEF_FUNCTIONS_SQL = `
+SELECT
+  n.nspname AS schema,
+  p.proname AS name,
+  EXISTS (
+    SELECT 1 FROM unnest(COALESCE(p.proconfig, '{}'::text[]) ) cfg WHERE cfg LIKE 'search_path=%'
+  ) AS has_search_path
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+WHERE p.prosecdef
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY n.nspname, p.proname
+`.trim();
+
 /** Coerce a Postgres boolean (true | 't' | 'true' | 1) to a JS boolean. */
 export function pgBool(v: unknown): boolean {
   return v === true || v === 't' || v === 'true' || v === 1 || v === '1';
 }
 
+/** Coerce a Postgres text[] (a JS array, or the `{a,b}` text form some drivers return) to string[]. */
+function pgTextArray(v: unknown): string[] {
+  if (Array.isArray(v)) return v.map(String);
+  if (typeof v === 'string') {
+    return v.replace(/^\{|\}$/g, '').split(',').map((s) => s.replace(/^"|"$/g, '').trim()).filter(Boolean);
+  }
+  return [];
+}
+
+const ROLE_IDENT = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * Every base table an app role can reach — a table-level grant (`relacl`) OR a column-level
+ * grant (`attacl`, the "revoke the table, grant safe columns" shape) — with its RLS flags.
+ * The "we require RLS" check reads these: a table granted to a request role with RLS disabled
+ * exposes every row to that role, the PostgREST fail-open shape the FORCE check can't see
+ * (it only inspects tables that already have RLS on). App-role names are validated idents
+ * (they're interpolated); they default to the role-chain set. Extension tables are excluded.
+ */
+export function appGrantsRlsSql(appRoles: string[] = ['anon', 'authenticated', 'admin']): string {
+  for (const r of appRoles) {
+    if (!ROLE_IDENT.test(r)) throw new Error(`Invalid app role: ${JSON.stringify(r)}`);
+  }
+  const roleList = appRoles.map((r) => `'${r}'`).join(', ');
+  return `
+WITH app_granted AS (
+  SELECT c.oid, r.rolname
+  FROM pg_class c
+  CROSS JOIN LATERAL aclexplode(c.relacl) a
+  JOIN pg_roles r ON r.oid = a.grantee
+  WHERE c.relkind = 'r' AND r.rolname IN (${roleList})
+  UNION
+  SELECT c.oid, r.rolname
+  FROM pg_class c
+  JOIN pg_attribute att ON att.attrelid = c.oid AND att.attnum > 0 AND NOT att.attisdropped
+  CROSS JOIN LATERAL aclexplode(att.attacl) a
+  JOIN pg_roles r ON r.oid = a.grantee
+  WHERE c.relkind = 'r' AND r.rolname IN (${roleList})
+)
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  c.relrowsecurity AS enabled,
+  c.relforcerowsecurity AS forced,
+  array_agg(DISTINCT g.rolname ORDER BY g.rolname) AS granted_to
+FROM app_granted g
+JOIN pg_class c ON c.oid = g.oid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype = 'e')
+GROUP BY n.nspname, c.relname, c.relrowsecurity, c.relforcerowsecurity
+ORDER BY n.nspname, c.relname;
+`.trim();
+}
+
 /** Options for the report builder. */
 export interface DoctorReportOptions {
   /**
-   * App-owned tables that are intentionally ENABLE-not-FORCE: an operational table whose
-   * owner (e.g. the worker, or a SECURITY DEFINER function) must read/write it, where FORCE
-   * would block the owner. These are added to the framework default (`auth.users`) and not
-   * flagged by the FORCE check. Example: `['ops.runs']` (the jobs queue the worker writes).
+   * Tables that are intentionally ENABLE-not-FORCE: a table whose owner (the worker, or a
+   * SECURITY DEFINER function) must read/write it, where FORCE would block the owner. These
+   * are not flagged by the FORCE check. Read from each model's `writtenBy` declaration via
+   * `deriveForceRlsCarveouts(models)` — including `auth.users` and the six other `auth.*`
+   * tables (all `writtenBy: 'functions'`), `ops.runs`, `dist.blobs`, and the notification
+   * tables — so the list can't drift from the contract.
    */
   forceRlsCarveouts?: string[];
+  /**
+   * Schemas that own a `writtenBy: 'functions'` table (e.g. `['auth']`), via
+   * `deriveFunctionSchemas(models)`. The `functions` teeth assert each such schema has
+   * SECDEF functions and that every one pins its `search_path`. Omitted/empty skips the check.
+   */
+  functionSchemas?: string[];
 }
 
 /** Build the green/red report from a gathered probe. Pure. */
@@ -162,6 +281,33 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     });
   }
 
+  // The "we require RLS" invariant — the line that separates everystack from PostgREST,
+  // which serves a granted table with no RLS. A table reachable by an app role
+  // (anon/authenticated/admin) with RLS DISABLED exposes every row to that role. The FORCE
+  // check below can't catch it (it only sees tables that already have RLS on), so this is the
+  // check that actually enforces "every app-reachable table is row-secured." A consumer who
+  // hand-writes a migration and grants a table without RLS is caught here, not in production.
+  if (probe.appGrantedRls) {
+    const exposed = probe.appGrantedRls.filter((t) => !t.enabled);
+    if (exposed.length > 0) {
+      checks.push({
+        name: 'App-reachable tables require RLS',
+        status: 'fail',
+        detail: `granted to an app role but RLS is NOT enabled — every row is exposed to that role: ${exposed.map((t) => `${t.schema}.${t.table} [${t.grantedTo.join('/')}]`).join(', ')}`,
+        remediation: exposed
+          .map((t) => `ALTER TABLE ${t.schema}.${t.table} ENABLE ROW LEVEL SECURITY; ALTER TABLE ${t.schema}.${t.table} FORCE ROW LEVEL SECURITY;`)
+          .join('  ')
+          + '  Then declare a policy — or model the table with the v3 Model so `db:generate` emits RLS + policies + grants together.',
+      });
+    } else {
+      checks.push({
+        name: 'App-reachable tables require RLS',
+        status: 'pass',
+        detail: `all ${probe.appGrantedRls.length} app-reachable table(s) have RLS enabled`,
+      });
+    }
+  }
+
   // FORCE coverage — RLS enabled but not FORCEd means the owner silently bypasses it.
   //
   // Carve-out: a credential table whose SECURITY DEFINER auth functions (verify the
@@ -171,9 +317,11 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
   // ENABLE-but-not-FORCE: the API/SSR roles are non-owners and are still gated by its
   // policies regardless of FORCE. `auth.users` (the @everystack/auth credential table) is
   // the framework's one such table.
-  // auth.users is the framework's own credential carve-out (always); apps add operational
-  // tables whose owner must write them (e.g. ops.runs, the worker-written jobs queue).
-  const FORCE_RLS_CARVEOUTS = new Set(['auth.users', ...(options.forceRlsCarveouts ?? [])]);
+  // The carveouts come entirely from the models' `writtenBy` declarations
+  // (deriveForceRlsCarveouts): auth.users and the six other auth.* tables (functions),
+  // ops.runs and dist.blobs (worker), the notification tables. No hand-list, no framework
+  // default that could drift from — or fall short of — the modeled set.
+  const FORCE_RLS_CARVEOUTS = new Set(options.forceRlsCarveouts ?? []);
   const allUnforced = probe.forceRls.filter((r) => r.enabled && !r.forced);
   const carved = allUnforced.filter((r) => FORCE_RLS_CARVEOUTS.has(`${r.schema}.${r.table}`));
   const unforced = allUnforced.filter((r) => !FORCE_RLS_CARVEOUTS.has(`${r.schema}.${r.table}`));
@@ -201,6 +349,42 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     });
   }
 
+  // The `functions` teeth — the other half of `writtenBy: 'functions'`. A table written only
+  // by SECURITY DEFINER functions is ENABLE-not-FORCE (carved out above) precisely BECAUSE the
+  // package's functions run as the owner. That bargain is only safe if those functions exist
+  // and each pins its search_path; an unpinned one is an owner-privilege hijack vector. This
+  // asserts it on the deployed database — the gate that was missing when 0022 silently went
+  // unapplied and left the auth SECDEF functions mutable.
+  if (probe.secdefFunctions && (options.functionSchemas?.length ?? 0) > 0) {
+    const schemas = new Set(options.functionSchemas);
+    const relevant = probe.secdefFunctions.filter((f) => schemas.has(f.schema));
+    const unpinned = relevant.filter((f) => !f.hasSearchPath);
+    const present = new Set(relevant.map((f) => f.schema));
+    const missing = [...schemas].filter((s) => !present.has(s)).sort();
+    if (unpinned.length > 0) {
+      checks.push({
+        name: 'SECURITY DEFINER functions pin search_path',
+        status: 'fail',
+        detail: `SECDEF function(s) in a functions-written schema have a mutable search_path (owner-privilege hijack vector): ${unpinned.map((f) => `${f.schema}.${f.name}`).join(', ')}`,
+        remediation: unpinned.map((f) => `ALTER FUNCTION ${f.schema}.${f.name} SET search_path = ${f.schema}, public, pg_temp;`).join('  ')
+          + '  (Then redeploy so the migration that defines them carries the pin.)',
+      });
+    } else if (missing.length > 0) {
+      checks.push({
+        name: 'SECURITY DEFINER functions exist for functions-written tables',
+        status: 'fail',
+        detail: `no SECDEF functions found in schema(s) that own a writtenBy:'functions' table: ${missing.join(', ')} — the package SQL that writes those tables was not applied`,
+        remediation: `Apply the package's functions migration (e.g. everystack db:migrate). A functions-written table with no SECDEF functions cannot be written at all.`,
+      });
+    } else {
+      checks.push({
+        name: 'SECURITY DEFINER functions pin search_path',
+        status: 'pass',
+        detail: `all ${relevant.length} SECDEF function(s) in ${[...present].sort().join(', ')} pin their search_path`,
+      });
+    }
+  }
+
   return {
     api,
     admin,
@@ -209,6 +393,15 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
   };
 }
 
+/** Map a SECDEF_FUNCTIONS_SQL row to SecdefFn. */
+export function rowToSecdefFn(row: any): SecdefFn {
+  return {
+    schema: String(row.schema),
+    name: String(row.name),
+    hasSearchPath: pgBool(row.has_search_path),
+  };
+}
+
 /** Map a CONN_SQL row to ConnInfo (tolerant of pg driver boolean encodings). */
 export function rowToConnInfo(row: any): ConnInfo {
   return {
@@ -227,3 +420,14 @@ export function rowToForceRls(row: any): ForceRlsRow {
     forced: pgBool(row.forced),
   };
 }
+
+/** Map an appGrantsRlsSql row to AppGrantedRow (tolerant of array vs text[] driver encodings). */
+export function rowToAppGranted(row: any): AppGrantedRow {
+  return {
+    schema: String(row.schema),
+    table: String(row.table),
+    enabled: pgBool(row.enabled),
+    forced: pgBool(row.forced),
+    grantedTo: pgTextArray(row.granted_to),
+  };
+}

package/src/plugin.ts

@@ -463,11 +463,18 @@ export interface DbPluginOptions {
   /** pgSettings callback for console auth context — applied via SET LOCAL when user is present */
   pgSettings?: (user: Record<string, unknown> | null) => Record<string, string>;
   /**
-   * App-owned tables that are intentionally ENABLE-not-FORCE row-level security, so db:doctor
-   * does not flag them. The framework always carves out `auth.users`; add operational tables
-   * whose owner must write them, e.g. `['ops.runs']` (the worker-written jobs queue).
+   * Tables that are intentionally ENABLE-not-FORCE row-level security, so db:doctor does not
+   * flag them. Pass `deriveForceRlsCarveouts(models)` — it reads each model's `writtenBy`
+   * declaration (auth.users + the six other auth.* tables, ops.runs, dist.blobs, the
+   * notification tables), so the list can't drift from the contract.
    */
   forceRlsCarveouts?: string[];
+  /**
+   * Schemas that own a `writtenBy: 'functions'` table (e.g. `['auth']`). Pass
+   * `deriveFunctionSchemas(models)`. db:doctor's `functions` teeth assert each such schema has
+   * SECDEF functions and that every one pins its search_path (the unpinned-search_path gate).
+   */
+  functionSchemas?: string[];
   /** Console auth helper config — column names for login/asUser (defaults to everystack conventions) */
   consoleAuth?: {
     usersTable?: string;
@@ -475,6 +482,14 @@ export interface DbPluginOptions {
     passwordColumn?: string;
     claimColumns?: string[];
   };
+  /**
+   * S3 bucket (name) for logical backups (db:backup/db:backups/db:restore). Pass the dedicated
+   * private backups bucket, e.g. `Resource.Backups.name`. When unset those actions return a
+   * "backup storage not configured" error — the rest of the plugin is unaffected.
+   */
+  backupBucket?: string;
+  /** AWS region for the backups bucket (defaults to the Lambda's AWS_REGION). */
+  backupRegion?: string;
 }
 
 /**
@@ -582,6 +597,36 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
     };
 
+    // --- db:authz:probe — the authorization red-team's execution path ---
+    // Runs the CLI-built probe SQL (SET ROLE + attempt per role/table/command, each in
+    // its own savepoint) inside ONE transaction that ALWAYS rolls back, then returns the
+    // outcome rows. Unlike db:query this permits writes — they are required to test
+    // INSERT/UPDATE/DELETE privileges — but the forced rollback guarantees nothing
+    // persists. IAM-gated like every action. The CLI owns the SQL (authz-redteam.ts);
+    // this is the thin, transactional, self-reverting runner it needs.
+    actions['db:authz:probe'] = async (payload, _ctx) => {
+      const { setup, read } = (payload ?? {}) as { setup?: string; read?: string };
+      if (!setup || !read) {
+        return { error: 'db:authz:probe requires { setup, read } SQL strings' };
+      }
+      const { sql } = await import('drizzle-orm');
+      const PROBE_ROLLBACK = Symbol('authz_probe_rollback');
+      let rows: any[] = [];
+      try {
+        await opsDb.transaction(async (tx: any) => {
+          await tx.execute(sql.raw(setup));
+          const result: any = await tx.execute(sql.raw(read));
+          rows = Array.isArray(result) ? result : result?.rows ?? [];
+          throw PROBE_ROLLBACK; // discard every probe write
+        });
+      } catch (err: unknown) {
+        if (err !== PROBE_ROLLBACK) {
+          return { error: (err as any)?.message || String(err) };
+        }
+      }
+      return { rows };
+    };
+
     // --- db:doctor — "is my database actually secure?" ---
     // Probes the api connection (createDb / DATABASE_URL) and the operator connection
     // (opsDb / ADMIN_DATABASE_URL) from inside the VPC and reports whether the api path
@@ -590,7 +635,8 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     actions['db:doctor'] = async (_payload, ctx) => {
       const { sql } = await import('drizzle-orm');
       const {
-        buildDoctorReport, rowToConnInfo, rowToForceRls, CONN_SQL, FORCE_RLS_SQL,
+        buildDoctorReport, rowToConnInfo, rowToForceRls, rowToAppGranted, rowToSecdefFn,
+        CONN_SQL, FORCE_RLS_SQL, appGrantsRlsSql, SECDEF_FUNCTIONS_SQL,
       } = await import('./db-doctor');
       const rowsOf = (result: any): any[] => (Array.isArray(result) ? result : result?.rows || []);
 
@@ -608,6 +654,12 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
 
       const admin = rowToConnInfo(rowsOf(await opsDb.execute(sql.raw(CONN_SQL)))[0]);
       const forceRls = rowsOf(await opsDb.execute(sql.raw(FORCE_RLS_SQL))).map(rowToForceRls);
+      // The "we require RLS" set — every app-reachable table + its RLS posture, so a table
+      // granted to a request role with RLS off (the PostgREST fail-open shape) is caught.
+      const appGrantedRls = rowsOf(await opsDb.execute(sql.raw(appGrantsRlsSql()))).map(rowToAppGranted);
+      // SECDEF functions (schema, name, search_path pinned?) — the `functions` teeth read these
+      // to assert every SECDEF function in a functions-written schema pins its search_path.
+      const secdefFunctions = rowsOf(await opsDb.execute(sql.raw(SECDEF_FUNCTIONS_SQL))).map(rowToSecdefFn);
 
       // Ambient-access probe: can the api connection read an RLS table WITHOUT SET ROLE?
       let apiAmbientRead: { table: string; accessible: boolean } | undefined;
@@ -623,8 +675,8 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
 
       return buildDoctorReport(
-        { api, admin, forceRls, apiAmbientRead },
-        { forceRlsCarveouts: options.forceRlsCarveouts },
+        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions },
+        { forceRlsCarveouts: options.forceRlsCarveouts, functionSchemas: options.functionSchemas },
       );
     };
 
@@ -670,6 +722,97 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       };
     };
 
+    // --- db:backup:probe — is the pg_dump layer attached, and does it match the server? ---
+    // The version gate for logical backups: pg_dump must be >= the server's MAJOR (no bypass flag
+    // exists). Returns the layer's pg_dump version + the live server_version_num so a deploy can
+    // confirm the layer is present AND version-compatible before db:backup is trusted. See backup.ts.
+    actions['db:backup:probe'] = async () => {
+      const { pgClientVersion, parsePgDumpMajor, serverMajorFromNum, isDumpCompatible } = await import('./backup');
+      const { sql } = await import('drizzle-orm');
+
+      let pgDump: string;
+      try {
+        pgDump = await pgClientVersion('pg_dump');
+      } catch (err: any) {
+        return { error: `pg_dump not available — is the pg_dump layer attached to this function? (${err?.message || String(err)})` };
+      }
+      const pgDumpMajor = parsePgDumpMajor(pgDump);
+
+      const rows: any = await opsDb.execute(sql.raw('SHOW server_version_num'));
+      const row = (Array.isArray(rows) ? rows : rows?.rows ?? [])[0];
+      const serverVersionNum = Number(row?.server_version_num);
+      const serverMajor = Number.isFinite(serverVersionNum) ? serverMajorFromNum(serverVersionNum) : null;
+
+      return {
+        pgDump,
+        pgDumpMajor,
+        serverVersionNum: Number.isFinite(serverVersionNum) ? serverVersionNum : null,
+        serverMajor,
+        compatible: pgDumpMajor != null && Number.isFinite(serverVersionNum)
+          ? isDumpCompatible(pgDumpMajor, serverVersionNum)
+          : false,
+      };
+    };
+
+    // --- db:backup / db:backups / db:restore — logical pg_dump backups streamed to S3 ---
+    // The operator (privileged) connection drives pg_dump/pg_restore; the dump streams to the
+    // dedicated private backups bucket. Restore is destructive and requires an explicit confirm in
+    // the payload (the CLI sets it after the user confirms). See backup-run.ts.
+    {
+      const resolveBackupDeps = async () => {
+        const bucket = options.backupBucket;
+        if (!bucket) {
+          return { error: 'backup storage not configured — pass backupBucket to dbPlugin (e.g. Resource.Backups.name)' as string };
+        }
+        const { getAdminDatabaseUrl, getMasterDatabaseUrl } = await import('./db');
+        const adminUrl = getAdminDatabaseUrl() ?? getMasterDatabaseUrl();
+        if (!adminUrl) {
+          return { error: 'no operator connection available (ADMIN_DATABASE_URL / Resource.Database)' as string };
+        }
+        return { deps: { bucket, region: options.backupRegion ?? process.env.AWS_REGION, adminUrl } };
+      };
+
+      actions['db:backup'] = async (payload, ctx) => {
+        const r = await resolveBackupDeps();
+        if ('error' in r) return { error: r.error };
+        const stage = ((payload ?? {}) as { stage?: string }).stage ?? ctx.environment ?? 'default';
+        const { runBackup } = await import('./backup-run');
+        try {
+          return await runBackup(r.deps, stage);
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+      };
+
+      actions['db:backups'] = async (payload, ctx) => {
+        const r = await resolveBackupDeps();
+        if ('error' in r) return { error: r.error };
+        const stage = ((payload ?? {}) as { stage?: string }).stage ?? ctx.environment ?? 'default';
+        const { listBackups } = await import('./backup-run');
+        try {
+          return { backups: await listBackups(r.deps, stage) };
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+      };
+
+      actions['db:restore'] = async (payload, _ctx) => {
+        const { id, confirm } = (payload ?? {}) as { id?: string; confirm?: boolean };
+        if (!id) return { error: 'db:restore requires { id }' };
+        if (confirm !== true) {
+          return { error: 'db:restore is destructive (drops + replaces the target DB). Pass confirm:true to proceed.' };
+        }
+        const r = await resolveBackupDeps();
+        if ('error' in r) return { error: r.error };
+        const { runRestore } = await import('./backup-run');
+        try {
+          return await runRestore(r.deps, id);
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+      };
+    }
+
     // --- console ---
     if (options.allowConsole !== false) {
       actions['console:meta'] = async (_payload, ctx) => {