@everystack/cli 0.2.37 → 0.3.0

package/src/cli/security-audit.ts

@@ -0,0 +1,405 @@
+/**
+ * security:audit — the gate behind the two-surface security model.
+ *
+ * everystack's automatic authorization floor is RLS, but RLS only self-enforces on
+ * the table/REST surface. A `SECURITY DEFINER` function runs as its owner, *above*
+ * RLS, gated only by its EXECUTE grant and whatever its body hand-writes — that is
+ * where the `get_user`-returns-someone-else's-email class of leak lives. This module
+ * is the pure classifier that makes the dangerous shape impossible to mis-author by
+ * accident: it goes RED on any data-returning definer function (and on a public view
+ * that exposes a non-public column), so CI fails before the leak ships.
+ *
+ * See docs/plans/nothing-skips-rls.md and docs/security.md ("Auditing the surface").
+ *
+ * Pure and side-effect-free. Two inputs feed the same classifier:
+ *   - static: parsed from migration SQL (pre-merge, no database)
+ *   - catalog: introspected from pg_proc / pg_views / pg_auth_members (post-deploy)
+ */
+
+export type Severity = 'red' | 'warn' | 'ok';
+
+/** How a function's return type maps onto the leak model. */
+export type ReturnClass = 'void' | 'scalar' | 'rows';
+
+export interface FunctionDescriptor {
+  schema: string;
+  name: string;
+  /** Raw return type text, for display (e.g. "jsonb", "SETOF users", "void"). */
+  returnType: string;
+  /**
+   * Precise return class when the source knows it (the catalog distinguishes a
+   * composite rowtype return from a scalar; static parsing cannot). When absent the
+   * class is derived from `returnType`.
+   */
+  returnClassHint?: ReturnClass;
+  /** True for SECURITY DEFINER; false for INVOKER (the default). */
+  securityDefiner: boolean;
+  /** True when the function pins `SET search_path`. */
+  hasSearchPath: boolean;
+  /** Owning role (catalog path only — static SQL parsing can't know it). */
+  owner?: string;
+  /**
+   * True when the owner runs above RLS (superuser, BYPASSRLS, or rds_superuser member).
+   * A SECURITY DEFINER function owned by such a role is the maximum blast radius.
+   */
+  ownerBypassesRls?: boolean;
+}
+
+export interface FunctionFinding {
+  /** `schema.name` — the waiver-match key. */
+  key: string;
+  schema: string;
+  name: string;
+  returnType: string;
+  returnClass: ReturnClass;
+  severity: Severity;
+  reasons: string[];
+  waived: boolean;
+  waiverReason?: string;
+}
+
+export interface ViewDescriptor {
+  schema: string;
+  name: string;
+  /** Relation kind. Tables are only checked when declared; views are nudged to declare. */
+  kind: 'view' | 'table';
+  /** Selected columns, or null when they can't be determined (e.g. `SELECT *`). */
+  columns: string[] | null;
+  /**
+   * True when SELECT is granted (directly or through role inheritance) to a broadly
+   * reachable role: anon, authenticated, or PUBLIC. The catalog path resolves
+   * inheritance via pg_auth_members; the static path sees only direct grants.
+   */
+  broadlyExposed: boolean;
+}
+
+export interface ViewFinding {
+  key: string;
+  schema: string;
+  name: string;
+  severity: Severity;
+  reasons: string[];
+}
+
+export interface Waivers {
+  /** `schema.name` -> justification. Empty/missing justification is invalid. */
+  secdef?: Record<string, string>;
+  /** `schema.view` -> declared public column allowlist. */
+  publicColumns?: Record<string, string[]>;
+}
+
+export interface AuditReport {
+  functions: FunctionFinding[];
+  views: ViewFinding[];
+  /** Counts across both invariants, excluding waived. */
+  red: number;
+  warn: number;
+}
+
+const RETURN_TERMINATORS = [
+  'language',
+  'security',
+  'set',
+  'stable',
+  'immutable',
+  'volatile',
+  'as',
+  'cost',
+  'rows',
+  'parallel',
+  'strict',
+  'leakproof',
+  'called',
+  'window',
+  'support',
+];
+
+const BROAD_ROLES = new Set(['anon', 'authenticated', 'public']);
+
+/**
+ * Map a raw SQL return type onto the leak model.
+ * - `void` / `trigger`            -> 'void' (writes; nothing returned to a caller)
+ * - `SETOF …` / `RETURNS TABLE…` / `record` -> 'rows'
+ * - everything else (text, jsonb, uuid, boolean, a composite type) -> 'scalar'
+ *
+ * Scalar is deliberately treated as data-returning: a `jsonb` or `text` return can
+ * carry another user's email. That is the exact incident this gate exists for.
+ */
+export function classifyReturnType(returnType: string): ReturnClass {
+  const t = returnType.trim().toLowerCase().replace(/\s+/g, ' ');
+  if (t === 'void' || t === 'trigger' || t === '') return 'void';
+  if (t.startsWith('setof ')) return 'rows';
+  if (t.startsWith('table(') || t.startsWith('table (')) return 'rows';
+  if (t === 'record' || t.startsWith('record')) return 'rows';
+  return 'scalar';
+}
+
+/** Apply Invariant A to a single function. INVOKER functions are never flagged. */
+export function classifyFunction(
+  fn: FunctionDescriptor,
+  waivers: Waivers = {},
+): FunctionFinding {
+  const key = `${fn.schema}.${fn.name}`;
+  const returnClass = fn.returnClassHint ?? classifyReturnType(fn.returnType);
+  const reasons: string[] = [];
+  let severity: Severity = 'ok';
+
+  // INVOKER functions run under RLS — not part of Invariant A.
+  if (!fn.securityDefiner) {
+    return { key, schema: fn.schema, name: fn.name, returnType: fn.returnType, returnClass, severity: 'ok', reasons, waived: false };
+  }
+
+  if (returnClass === 'rows') {
+    reasons.push('SECURITY DEFINER returns rows (table/SETOF/composite/record) above RLS — convert to SECURITY INVOKER over RLS policies');
+    severity = 'red';
+  } else if (returnClass === 'scalar') {
+    reasons.push(`SECURITY DEFINER returns a value (${fn.returnType}) above RLS — a scalar can leak another user's data (e.g. email); convert to SECURITY INVOKER`);
+    severity = 'red';
+  } else {
+    // void / trigger — a write that runs above RLS. The audit can't prove the body's
+    // authorization check is current, so it warns rather than passing silently.
+    reasons.push('SECURITY DEFINER write runs above RLS — its body authorization check is not verifiable by this audit');
+    severity = raise(severity, 'warn');
+  }
+
+  if (!fn.hasSearchPath) {
+    reasons.push('missing SET search_path — an unpinned definer function is a schema-shadowing escalation vector');
+    severity = raise(severity, 'red');
+  }
+
+  // Waivers downgrade a reviewed-and-justified function to OK. A waiver with no
+  // justification is itself a finding — opt-out must always carry a reason.
+  const waiverReason = waivers.secdef?.[key];
+  if (waiverReason !== undefined) {
+    if (typeof waiverReason === 'string' && waiverReason.trim().length > 0) {
+      return { key, schema: fn.schema, name: fn.name, returnType: fn.returnType, returnClass, severity: 'ok', reasons, waived: true, waiverReason };
+    }
+    reasons.push('waiver present but missing a justification string — a waiver must explain why the function is safe');
+    severity = raise(severity, 'red');
+  }
+
+  return { key, schema: fn.schema, name: fn.name, returnType: fn.returnType, returnClass, severity, reasons, waived: false };
+}
+
+/** Apply Invariant B to a single view/projection. */
+export function classifyView(view: ViewDescriptor, waivers: Waivers = {}): ViewFinding {
+  const key = `${view.schema}.${view.name}`;
+  const reasons: string[] = [];
+  let severity: Severity = 'ok';
+
+  if (!view.broadlyExposed) {
+    return { key, schema: view.schema, name: view.name, severity, reasons };
+  }
+
+  const allowlist = waivers.publicColumns?.[key];
+
+  if (!allowlist) {
+    // A broadly-exposed *view* is a deliberate public projection — nudge it to declare
+    // its public column set so drift can be caught. Base tables are the normal REST
+    // surface (governed by RLS + hiddenColumns); don't warn on every one.
+    if (view.kind === 'view') {
+      reasons.push('broadly-granted view with no declared public column set — declare its public columns so drift can be caught');
+      severity = 'warn';
+    }
+    return { key, schema: view.schema, name: view.name, severity, reasons };
+  }
+
+  if (view.columns === null) {
+    reasons.push('cannot determine projected columns (e.g. SELECT *) — a public projection must select an explicit column list');
+    severity = 'red';
+    return { key, schema: view.schema, name: view.name, severity, reasons };
+  }
+
+  const allowed = new Set(allowlist);
+  const leaked = view.columns.filter((c) => !allowed.has(c));
+  if (leaked.length > 0) {
+    reasons.push(`exposes non-public column(s) beyond the declared public set: ${leaked.join(', ')}`);
+    severity = 'red';
+  }
+
+  return { key, schema: view.schema, name: view.name, severity, reasons };
+}
+
+/** Run both invariants over a set of descriptors and tally the result. */
+export function audit(
+  functions: FunctionDescriptor[],
+  views: ViewDescriptor[],
+  waivers: Waivers = {},
+): AuditReport {
+  const fnFindings = functions.map((f) => classifyFunction(f, waivers));
+  const viewFindings = views.map((v) => classifyView(v, waivers));
+  const all: { severity: Severity }[] = [...fnFindings, ...viewFindings];
+  return {
+    functions: fnFindings,
+    views: viewFindings,
+    red: all.filter((f) => f.severity === 'red').length,
+    warn: all.filter((f) => f.severity === 'warn').length,
+  };
+}
+
+function raise(current: Severity, next: Severity): Severity {
+  const rank: Record<Severity, number> = { ok: 0, warn: 1, red: 2 };
+  return rank[next] > rank[current] ? next : current;
+}
+
+// ---------------------------------------------------------------------------
+// Static parsing — extract descriptors from migration SQL (pre-merge, no DB).
+// ---------------------------------------------------------------------------
+
+/** Strip `--` line comments and `/* *\/` block comments so they don't confuse parsing. */
+function stripComments(sql: string): string {
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/--[^\n]*/g, ' ');
+}
+
+function unquoteIdent(raw: string): string {
+  return raw.replace(/"/g, '').trim();
+}
+
+/** Split a qualified identifier `schema.name` (defaulting schema to `public`). */
+function splitQualified(qualified: string): { schema: string; name: string } {
+  const parts = unquoteIdent(qualified).split('.');
+  if (parts.length >= 2) return { schema: parts[parts.length - 2], name: parts[parts.length - 1] };
+  return { schema: 'public', name: parts[0] };
+}
+
+/**
+ * Parse every `CREATE FUNCTION` in a SQL string into descriptors. Paren-aware over
+ * the parameter list, so default expressions with commas/quotes don't break it.
+ */
+export function parseFunctionsFromSql(sql: string): FunctionDescriptor[] {
+  const src = stripComments(sql);
+  const out: FunctionDescriptor[] = [];
+  const headerRe = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+([a-zA-Z0-9_."]+)\s*\(/gi;
+  let m: RegExpExecArray | null;
+
+  while ((m = headerRe.exec(src)) !== null) {
+    const { schema, name } = splitQualified(m[1]);
+
+    // Walk the parameter list to its matching close paren.
+    let depth = 1;
+    let i = headerRe.lastIndex;
+    for (; i < src.length && depth > 0; i++) {
+      if (src[i] === '(') depth++;
+      else if (src[i] === ')') depth--;
+    }
+
+    // Options span from after the params to the body delimiter `AS $tag$`
+    // (or the statement terminator for a declaration without a body).
+    const rest = src.slice(i);
+    const bodyMatch = /\bAS\s+\$[A-Za-z0-9_]*\$/i.exec(rest);
+    const optionsEnd = bodyMatch ? bodyMatch.index : (rest.indexOf(';') === -1 ? rest.length : rest.indexOf(';'));
+    const options = rest.slice(0, optionsEnd);
+
+    out.push({
+      schema,
+      name,
+      returnType: extractReturnType(options),
+      securityDefiner: /\bSECURITY\s+DEFINER\b/i.test(options),
+      hasSearchPath: /\bSET\s+search_path\b/i.test(options),
+    });
+
+    headerRe.lastIndex = i;
+  }
+
+  return out;
+}
+
+/** Pull the return type out of a function's options block. */
+function extractReturnType(options: string): string {
+  const m = /\bRETURNS\s+([\s\S]+)/i.exec(options);
+  if (!m) return 'void';
+  const after = m[1].trim();
+  const lower = after.toLowerCase();
+
+  // SETOF / TABLE(...) / record are recognized as row-returning verbatim.
+  // Otherwise capture up to the next function-option keyword.
+  let end = after.length;
+  for (const kw of RETURN_TERMINATORS) {
+    const re = new RegExp(`\\b${kw}\\b`, 'i');
+    const idx = lower.search(re);
+    if (idx !== -1 && idx < end) end = idx;
+  }
+  return after.slice(0, end).trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * Parse views and their broad grants from SQL. Static analysis sees only direct
+ * grants to anon/authenticated/PUBLIC (no role-inheritance graph).
+ */
+export function parseViewsAndGrantsFromSql(sql: string): ViewDescriptor[] {
+  const src = stripComments(sql);
+
+  // Collect objects granted SELECT/ALL to a broad role.
+  const broad = new Set<string>();
+  const grantRe = /GRANT\s+([\s\S]+?)\s+ON\s+(?:TABLE\s+)?([a-zA-Z0-9_."]+)\s+TO\s+([a-zA-Z0-9_,"\s]+?)\s*;/gi;
+  let g: RegExpExecArray | null;
+  while ((g = grantRe.exec(src)) !== null) {
+    const privs = g[1].toLowerCase();
+    const grantsRead = /\bselect\b/.test(privs) || /\ball\b/.test(privs);
+    if (!grantsRead) continue;
+    const { schema, name } = splitQualified(g[2]);
+    const roles = g[3].split(',').map((r) => unquoteIdent(r).toLowerCase());
+    if (roles.some((r) => BROAD_ROLES.has(r))) broad.add(`${schema}.${name}`);
+  }
+
+  const out: ViewDescriptor[] = [];
+  const viewRe = /CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\s+([a-zA-Z0-9_."]+)\s+AS\s+([\s\S]*?);/gi;
+  let v: RegExpExecArray | null;
+  while ((v = viewRe.exec(src)) !== null) {
+    const { schema, name } = splitQualified(v[1]);
+    out.push({
+      schema,
+      name,
+      kind: 'view',
+      columns: extractSelectColumns(v[2]),
+      broadlyExposed: broad.has(`${schema}.${name}`),
+    });
+  }
+
+  return out;
+}
+
+/** Extract an explicit top-level column list from a SELECT, or null if not determinable. */
+function extractSelectColumns(selectBody: string): string[] | null {
+  const m = /SELECT\s+([\s\S]+?)\s+FROM\b/i.exec(selectBody);
+  if (!m) return null;
+  const list = m[1].trim();
+  if (list === '*' || list.includes('*')) return null;
+
+  // Split on top-level commas (ignore commas inside parens, e.g. coalesce(a, b)).
+  const cols: string[] = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of list) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      cols.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) cols.push(cur);
+
+  // Resolve each item to its output column name: prefer `AS alias`, else a bare column,
+  // else null (an unaliased expression has no stable public name → unverifiable).
+  const names: string[] = [];
+  for (const raw of cols) {
+    const item = raw.trim();
+    const asMatch = /\bAS\s+([a-zA-Z0-9_"]+)\s*$/i.exec(item);
+    if (asMatch) {
+      names.push(unquoteIdent(asMatch[1]));
+      continue;
+    }
+    if (/^[a-zA-Z0-9_"]+(\.[a-zA-Z0-9_"]+)?$/.test(item)) {
+      const parts = item.split('.');
+      names.push(unquoteIdent(parts[parts.length - 1]));
+      continue;
+    }
+    return null; // bare expression without alias — can't name the public column
+  }
+  return names;
+}

package/src/cli/security-catalog.ts

@@ -0,0 +1,170 @@
+/**
+ * Catalog instrument for security:audit — the post-deploy half.
+ *
+ * Static parsing gates the PR from the migration SQL; this introspects the *live*
+ * database (pg_proc / pg_class / pg_attribute, with role inheritance resolved by
+ * `has_table_privilege`) to catch deployed-state drift and anything created
+ * out-of-band that the migration files never described.
+ *
+ * The SQL runs through the ops Lambda (`db:query`); the mappers here are pure and
+ * unit-tested without a database.
+ */
+
+import type {
+  FunctionDescriptor,
+  ViewDescriptor,
+  ReturnClass,
+} from './security-audit.js';
+
+/**
+ * Enumerate every function with its security context. Excludes system schemas and
+ * extension-owned functions (pgcrypto, PostGIS) via pg_depend, so vendor functions
+ * never need a manual waiver.
+ */
+export const FUNCTIONS_SQL = `
+SELECT
+  n.nspname AS schema,
+  p.proname AS name,
+  pg_get_function_result(p.oid) AS return_type,
+  p.prosecdef AS security_definer,
+  p.proretset AS returns_set,
+  t.typtype AS return_typtype,
+  EXISTS (
+    SELECT 1 FROM unnest(coalesce(p.proconfig, '{}'::text[])) cfg
+    WHERE lower(cfg) LIKE 'search_path=%'
+  ) AS has_search_path,
+  pg_get_userbyid(p.proowner) AS owner,
+  -- Does the owner run above RLS? A SECURITY DEFINER function owned by such a role is
+  -- the maximum blast radius — search_path pinning is necessary but not sufficient.
+  -- RDS has no true superuser (rolsuper=false), so also check rds_superuser membership.
+  (
+    SELECT r.rolsuper OR r.rolbypassrls OR EXISTS (
+      SELECT 1 FROM pg_auth_members m JOIN pg_roles g ON g.oid = m.roleid
+      WHERE m.member = p.proowner AND g.rolname = 'rds_superuser'
+    )
+    FROM pg_roles r WHERE r.oid = p.proowner
+  ) AS owner_bypasses_rls
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+JOIN pg_type t ON t.oid = p.prorettype
+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 = p.oid AND d.deptype = 'e'
+  )
+ORDER BY n.nspname, p.proname;
+`.trim();
+
+/**
+ * Enumerate relations (tables, views, matviews) with their columns and whether
+ * SELECT is reachable from a broad role. `has_table_privilege` resolves role
+ * inheritance and PUBLIC grants, so a view granted to an intermediate role that
+ * `authenticated` inherits is correctly flagged broadly-exposed.
+ */
+export const RELATIONS_SQL = `
+WITH targets AS (
+  SELECT rolname FROM pg_roles WHERE rolname IN ('anon', 'authenticated')
+)
+SELECT
+  n.nspname AS schema,
+  c.relname AS name,
+  c.relkind AS relkind,
+  (
+    SELECT array_agg(a.attname ORDER BY a.attnum)
+    FROM pg_attribute a
+    WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+  ) AS columns,
+  EXISTS (
+    SELECT 1 FROM targets tg
+    WHERE has_table_privilege(tg.rolname, c.oid, 'SELECT')
+  ) AS broadly_exposed
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('r', 'v', 'm')
+  AND 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'
+  )
+ORDER BY n.nspname, c.relname;
+`.trim();
+
+/** Coerce a Postgres boolean (true | 't' | 'true' | 1) into a JS boolean. */
+function truthy(v: unknown): boolean {
+  return v === true || v === 't' || v === 'true' || v === 1 || v === '1';
+}
+
+/** Parse a text[] that may arrive as a JS array or a `{a,b,c}` literal string. */
+export function parsePgArray(v: unknown): string[] | null {
+  if (v == null) return null;
+  if (Array.isArray(v)) return v.map(String);
+  if (typeof v === 'string') {
+    const trimmed = v.trim();
+    if (trimmed === '{}' || trimmed === '') return [];
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+      return trimmed
+        .slice(1, -1)
+        .split(',')
+        .map((s) => s.replace(/^"|"$/g, '').trim())
+        .filter((s) => s.length > 0);
+    }
+  }
+  return null;
+}
+
+interface FunctionRow {
+  schema: string;
+  name: string;
+  return_type: string;
+  security_definer: unknown;
+  returns_set: unknown;
+  return_typtype: unknown;
+  has_search_path: unknown;
+  owner?: unknown;
+  owner_bypasses_rls?: unknown;
+}
+
+/** Map a pg_proc row to a descriptor, computing a precise return class. */
+export function catalogFunctionToDescriptor(row: FunctionRow): FunctionDescriptor {
+  const text = String(row.return_type ?? '').trim().toLowerCase();
+  let returnClassHint: ReturnClass;
+  if (text === 'void' || text === 'trigger' || text === '') {
+    returnClassHint = 'void';
+  } else if (truthy(row.returns_set) || row.return_typtype === 'c' || text === 'record' || text.startsWith('setof') || text.startsWith('table(')) {
+    returnClassHint = 'rows';
+  } else {
+    returnClassHint = 'scalar';
+  }
+
+  return {
+    schema: row.schema,
+    name: row.name,
+    returnType: row.return_type,
+    returnClassHint,
+    securityDefiner: truthy(row.security_definer),
+    hasSearchPath: truthy(row.has_search_path),
+    owner: row.owner != null ? String(row.owner) : undefined,
+    ownerBypassesRls: row.owner_bypasses_rls != null ? truthy(row.owner_bypasses_rls) : undefined,
+  };
+}
+
+interface RelationRow {
+  schema: string;
+  name: string;
+  relkind: string;
+  columns: unknown;
+  broadly_exposed: unknown;
+}
+
+/** Map a pg_class row to a view/table descriptor. */
+export function catalogRelationToDescriptor(row: RelationRow): ViewDescriptor {
+  return {
+    schema: row.schema,
+    name: row.name,
+    kind: row.relkind === 'r' ? 'table' : 'view',
+    columns: parsePgArray(row.columns),
+    broadlyExposed: truthy(row.broadly_exposed),
+  };
+}