@everystack/cli 0.2.37 → 0.2.40

package/src/cli/commands/security.ts

@@ -0,0 +1,185 @@
+/**
+ * `everystack security:audit` — the gate behind the two-surface security model.
+ *
+ * Goes RED (non-zero exit) on any data-returning SECURITY DEFINER function or any
+ * public view that exposes a non-public column, so CI fails before the leak ships.
+ * Two instruments over one classifier:
+ *
+ *   everystack security:audit                 static scan of migration SQL (pre-merge)
+ *   everystack security:audit --stage <name>  live catalog scan of a deployed stage
+ *
+ * See docs/security.md ("Auditing the surface") and docs/plans/nothing-skips-rls.md.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  audit,
+  parseFunctionsFromSql,
+  parseViewsAndGrantsFromSql,
+  type Waivers,
+  type AuditReport,
+  type FunctionDescriptor,
+  type ViewDescriptor,
+} from '../security-audit.js';
+import {
+  FUNCTIONS_SQL,
+  RELATIONS_SQL,
+  catalogFunctionToDescriptor,
+  catalogRelationToDescriptor,
+} from '../security-catalog.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const MIGRATION_DIRS = ['drizzle', 'db/migrations', 'migrations', 'db/drizzle'];
+const WAIVER_FILES = ['security-audit.json', '.security-audit.json'];
+
+export async function securityAuditCommand(flags: Record<string, string>): Promise<void> {
+  const waivers = await loadWaivers(flags.config);
+
+  const useCatalog = flags.catalog === 'true' || typeof flags.stage === 'string';
+
+  let report: AuditReport;
+  try {
+    report = useCatalog
+      ? await runCatalogAudit(flags, waivers)
+      : await runStaticAudit(flags, waivers);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  printReport(report, useCatalog ? 'catalog' : 'static');
+  process.exit(report.red > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Static instrument — parse migration SQL, no database.
+// ---------------------------------------------------------------------------
+
+async function runStaticAudit(flags: Record<string, string>, waivers: Waivers): Promise<AuditReport> {
+  const dir = await resolveMigrationDir(flags.dir);
+  step(`Scanning migration SQL in ${dir} ...`);
+
+  const entries = (await fs.readdir(dir)).filter((f) => f.endsWith('.sql')).sort();
+  if (entries.length === 0) {
+    throw new Error(`No .sql files found in ${dir}. Pass --dir <path> to point at your migrations.`);
+  }
+
+  let sql = '';
+  for (const entry of entries) {
+    sql += '\n' + (await fs.readFile(path.join(dir, entry), 'utf8'));
+  }
+
+  const functions = parseFunctionsFromSql(sql);
+  const views = parseViewsAndGrantsFromSql(sql);
+  info(`Found ${functions.length} function(s), ${views.length} view(s) across ${entries.length} migration file(s).`);
+  return audit(functions, views, waivers);
+}
+
+async function resolveMigrationDir(flag?: string): Promise<string> {
+  if (flag) {
+    const abs = path.resolve(flag);
+    await fs.access(abs);
+    return abs;
+  }
+  for (const candidate of MIGRATION_DIRS) {
+    const abs = path.resolve(candidate);
+    try {
+      const stat = await fs.stat(abs);
+      if (stat.isDirectory()) return abs;
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(`No migration directory found (looked for ${MIGRATION_DIRS.join(', ')}). Pass --dir <path>.`);
+}
+
+// ---------------------------------------------------------------------------
+// Catalog instrument — introspect the live database via the ops Lambda.
+// ---------------------------------------------------------------------------
+
+async function runCatalogAudit(flags: Record<string, string>, waivers: Waivers): Promise<AuditReport> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+
+  step('Introspecting database catalog (functions + relations)...');
+  const fnRows = await catalogQuery(config.region, opsFunction(config), FUNCTIONS_SQL);
+  const relRows = await catalogQuery(config.region, opsFunction(config), RELATIONS_SQL);
+
+  const functions: FunctionDescriptor[] = fnRows.map(catalogFunctionToDescriptor);
+  const views: ViewDescriptor[] = relRows.map(catalogRelationToDescriptor);
+  info(`Catalog: ${functions.length} function(s), ${views.length} relation(s).`);
+  return audit(functions, views, waivers);
+}
+
+async function catalogQuery(region: string, fn: string, sql: string): Promise<any[]> {
+  const result: any = await invokeAction(region, fn, 'db:query', { sql });
+  if (result?.error) throw new Error(`Catalog query failed: ${result.error}`);
+  return result?.rows ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Waivers + reporting.
+// ---------------------------------------------------------------------------
+
+async function loadWaivers(flag?: string): Promise<Waivers> {
+  const candidates = flag ? [flag] : WAIVER_FILES;
+  for (const candidate of candidates) {
+    const abs = path.resolve(candidate);
+    try {
+      const raw = await fs.readFile(abs, 'utf8');
+      const parsed = JSON.parse(raw);
+      info(`Loaded waivers from ${candidate}.`);
+      return { secdef: parsed.secdef ?? {}, publicColumns: parsed.publicColumns ?? {} };
+    } catch (err: any) {
+      if (err.code !== 'ENOENT') throw new Error(`Could not read waiver config ${candidate}: ${err.message}`);
+    }
+  }
+  return {};
+}
+
+function printReport(report: AuditReport, instrument: 'static' | 'catalog'): void {
+  const reds = [
+    ...report.functions.filter((f) => f.severity === 'red'),
+    ...report.views.filter((v) => v.severity === 'red'),
+  ];
+  const warns = [
+    ...report.functions.filter((f) => f.severity === 'warn'),
+    ...report.views.filter((v) => v.severity === 'warn'),
+  ];
+  const waived = report.functions.filter((f) => f.waived);
+
+  if (reds.length > 0) {
+    console.log('');
+    info('RED — must fix or waive with justification:');
+    for (const f of reds) {
+      fail(`${f.key}`);
+      for (const r of f.reasons) info(`    ${r}`);
+    }
+  }
+
+  if (warns.length > 0) {
+    console.log('');
+    info('WARN — review (does not fail the build):');
+    for (const f of warns) {
+      warn(`${f.key}`);
+      for (const r of f.reasons) info(`    ${r}`);
+    }
+  }
+
+  if (waived.length > 0) {
+    console.log('');
+    info(`Waived (${waived.length}): ${waived.map((f) => f.key).join(', ')}`);
+  }
+
+  console.log('');
+  const summary = `security:audit (${instrument}) — ${report.red} red, ${report.warn} warn`;
+  if (report.red > 0) {
+    fail(summary);
+  } else {
+    success(summary);
+  }
+}

package/src/cli/index.ts

@@ -6,7 +6,8 @@ import { updateCommand } from './commands/update.js';
 import { certsCommand } from './commands/certs.js';
 import { channelsCommand } from './commands/channels.js';
 import { branchesCommand } from './commands/branches.js';
-import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand } from './commands/db.js';
+import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand, dbDoctorCommand, dbProvisionCommand } from './commands/db.js';
+import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzReportCommand } from './commands/db-authz.js';
 import { consoleCommand } from './commands/console.js';
 import { cachePurgeCommand } from './commands/cache.js';
 import { statusCommand } from './commands/status.js';
@@ -14,6 +15,7 @@ import { diagCommand } from './commands/diag.js';
 import { analyzeSSRCommand } from './commands/analyze.js';
 import { logsErrorsCommand, logsTailCommand, logsQueryCommand } from './commands/logs.js';
 import { secretsCommand } from './commands/secrets.js';
+import { securityAuditCommand } from './commands/security.js';
 import { fail } from './output.js';
 
 const args = process.argv.slice(2);
@@ -114,6 +116,24 @@ async function main() {
     case 'db:psql':
       await dbPsqlCommand(flags);
       break;
+    case 'db:doctor':
+      await dbDoctorCommand(flags);
+      break;
+    case 'db:provision':
+      await dbProvisionCommand(flags);
+      break;
+    case 'db:authz:pull':
+      await dbAuthzPullCommand(flags);
+      break;
+    case 'db:authz:diff':
+      await dbAuthzDiffCommand(flags);
+      break;
+    case 'db:authz:test':
+      await dbAuthzTestCommand(flags);
+      break;
+    case 'db:authz:report':
+      await dbAuthzReportCommand(flags);
+      break;
     case 'console':
       await consoleCommand(flags);
       break;
@@ -143,6 +163,9 @@ async function main() {
     case 'logs:query':
       await logsQueryCommand(flags);
       break;
+    case 'security:audit':
+      await securityAuditCommand(flags);
+      break;
     case 'secrets': {
       // secrets <subcommand> [positional...] [--flags]
       // Extract positional args: everything after subcommand that isn't a flag or flag value
@@ -176,9 +199,18 @@ Usage:
   everystack db:migrate        [--stage <name>]  Run database migrations on deployed Lambda
   everystack db:seed           [--stage <name>]  Seed database on deployed Lambda (dev only)
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
-  everystack db:psql           [--stage <name>] -c <command>  Execute SQL query via Lambda (private RDS)
+  everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
+  everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
+  everystack db:doctor         [--stage <name>]  Check the DB is least-privilege + RLS-subject (api vs operator connection)
+  everystack db:provision      [--stage <name>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB)
+  everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
+  everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
+  everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
+  everystack db:authz:report   [--dir authz]  Render the committed contract as a human-readable authorization review (no DB)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary
+  everystack security:audit    [--dir <path>] [--config <file>]  Static scan of migration SQL (pre-merge gate)
+  everystack security:audit    --stage <name> [--config <file>]  Live catalog scan of a deployed stage (post-deploy)
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

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;
+}