@everystack/cli 0.2.39 → 0.2.40

package/src/cli/commands/db-authz.ts

@@ -0,0 +1,206 @@
+/**
+ * `everystack db:authz:pull` / `db:authz:diff` — the Authorization Contract commands.
+ *
+ *   db:authz:pull --stage <name>   introspect the live authz → write authz/*.contract.json
+ *   db:authz:diff --stage <name>   validate the live DB against the committed contract
+ *
+ * The contract is the brownfield slice of the Model (docs/plans/v3-authz-contract.md):
+ * authorization that lived only in scattered migrations becomes a reviewable file you
+ * can diff a deployed database against. `pull` is the export + on-ramp; `diff` is the
+ * audit and the CI gate (non-zero exit on any drift).
+ *
+ * Both introspect through the ops Lambda `db:query` action (read-only SQL), the same
+ * path security:audit uses. The core (introspect/assemble/diff) is backend-agnostic and
+ * pure; only the runner here is AWS-bound.
+ */
+
+import path from 'node:path';
+import {
+  introspectContract,
+  diffContracts,
+  type QueryRunner,
+  type AuthzContract,
+} from '../authz-contract.js';
+import {
+  buildProbeSql,
+  PROBE_SELECT_SQL,
+  probeRoles,
+  toProbeResult,
+  evaluateRedTeam,
+  GRANT_COMPLETENESS_SQL,
+  toGrantGap,
+} from '../authz-redteam.js';
+import { writeContract, loadContract } from '../authz-contract-io.js';
+import { renderContractMarkdown } from '../authz-render.js';
+import { FUNCTIONS_SQL, catalogFunctionToDescriptor } 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 DEFAULT_DIR = 'authz';
+
+/** Map a FUNCTIONS_SQL row to the minimal shape the contract records. */
+const mapFunctionRow = (row: any) => {
+  const d = catalogFunctionToDescriptor(row);
+  return {
+    schema: d.schema, name: d.name, securityDefiner: d.securityDefiner, hasSearchPath: d.hasSearchPath,
+    owner: d.owner, ownerBypassesRls: d.ownerBypassesRls,
+  };
+};
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Introspection query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+async function introspectStage(flags: Record<string, string>): Promise<AuthzContract> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Introspecting authorization (rls + grants + policies + secdef)...');
+  const runner = lambdaRunner(config.region, opsFunction(config));
+  return introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
+}
+
+export async function dbAuthzPullCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+  let contract: AuthzContract;
+  try {
+    contract = await introspectStage(flags);
+  } catch (err: any) {
+    fail(err.message);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+
+  const files = await writeContract(dir, contract);
+  const policies = contract.tables.reduce((n, t) => n + t.policies.length, 0);
+  console.log('');
+  success(`Wrote ${files.length} file(s) to ${dir}`);
+  info(`${contract.tables.length} table(s), ${policies} policy(ies), ${contract.functions.length} SECDEF function(s).`);
+  console.log('');
+  warn('pull OVERWROTE the committed contract with the live state — `git diff` IS your drift report.');
+  warn('Do not run `db:authz:diff` to find drift right after a pull: it compares the live DB to what');
+  warn('you just wrote, so it is always clean. Review `git diff`, then commit only if the change is intended.');
+  info('Note: column exposure (hidden/protected) is handler-layer and not part of the DB pull.');
+  process.exit(0);
+}
+
+export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+
+  let declared: AuthzContract;
+  let live: AuthzContract;
+  try {
+    declared = await loadContract(dir);
+    live = await introspectStage(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  if (declared.tables.length === 0 && declared.functions.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+
+  const findings = diffContracts(declared, live);
+  console.log('');
+  if (findings.length === 0) {
+    success(`db:authz:diff — live database matches the declared contract (${declared.tables.length} tables)`);
+    process.exit(0);
+  }
+
+  fail(`db:authz:diff — ${findings.length} drift finding(s): the live database does NOT match the declared contract`);
+  console.log('');
+  for (const f of findings) {
+    warn(`[${f.kind}] ${f.subject} — ${f.detail}`);
+  }
+  console.log('');
+  info('Either the live DB drifted (reconcile it) or the change is intended (re-pull + commit the contract delta).');
+  process.exit(1);
+}
+
+export async function dbAuthzReportCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+  let contract: AuthzContract;
+  try {
+    contract = await loadContract(dir);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (contract.tables.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+  // Render from the committed contract — no database needed. Print to stdout so it can
+  // be piped or redirected; `pull` writes the same content to authz/AUTHORIZATION.md.
+  console.log(renderContractMarkdown(contract));
+  process.exit(0);
+}
+
+export async function dbAuthzTestCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+
+  let contract: AuthzContract;
+  try {
+    contract = await loadContract(dir);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (contract.tables.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+
+  let rows: any[];
+  let gapRows: any[];
+  try {
+    step('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    const fn = opsFunction(config);
+    info(`Region: ${config.region}, Function: ${fn}`);
+    step('Red-teaming enforcement (SET ROLE + attempt per role/table/command, rolled back)...');
+    const setup = buildProbeSql(probeRoles(contract), contract.tables.map((t) => t.table));
+    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', { setup, read: PROBE_SELECT_SQL });
+    if (result?.error) throw new Error(result.error);
+    rows = result?.rows ?? [];
+    step('Checking SECDEF grant-completeness (owner can EXECUTE every helper it calls)...');
+    const gc: any = await invokeAction(config.region, fn, 'db:query', { sql: GRANT_COMPLETENESS_SQL });
+    if (gc?.error) throw new Error(gc.error);
+    gapRows = gc?.rows ?? [];
+  } catch (err: any) {
+    fail(`db:authz:test failed: ${err.message}`);
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    process.exit(1);
+  }
+
+  const findings = evaluateRedTeam(contract, rows.map(toProbeResult));
+  const holes = findings.filter((f) => f.severity === 'hole');
+  const broken = findings.filter((f) => f.severity === 'broken');
+  const unprobed = findings.filter((f) => f.severity === 'unprobed');
+  const gaps = gapRows.map(toGrantGap);
+
+  console.log('');
+  for (const f of holes) fail(`[HOLE]   ${f.detail}`);
+  for (const f of broken) warn(`[BROKEN] ${f.detail}`);
+  for (const g of gaps) fail(`[GRANT-GAP] ${g.secdef} calls ${g.helper} but its owner cannot EXECUTE it (42501 in prod once ownership is normalized)`);
+  if (unprobed.length) {
+    const roles = [...new Set(unprobed.map((f) => f.role))].join(', ');
+    info(`[unprobed] could not SET ROLE into: ${roles} — grant the operator membership to cover them.`);
+  }
+  console.log('');
+
+  if (holes.length === 0 && broken.length === 0 && gaps.length === 0) {
+    success(`db:authz:test — enforcement matches the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
+    process.exit(0);
+  }
+  fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). The database does not enforce the contract.`);
+  process.exit(1);
+}

package/src/cli/index.ts

@@ -7,6 +7,7 @@ import { certsCommand } from './commands/certs.js';
 import { channelsCommand } from './commands/channels.js';
 import { branchesCommand } from './commands/branches.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';
@@ -121,6 +122,18 @@ async function main() {
     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;
@@ -190,6 +203,10 @@ Usage:
   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)

package/src/cli/security-audit.ts

@@ -36,6 +36,13 @@ export interface FunctionDescriptor {
   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 {

package/src/cli/security-catalog.ts

@@ -32,7 +32,18 @@ SELECT
   EXISTS (
     SELECT 1 FROM unnest(coalesce(p.proconfig, '{}'::text[])) cfg
     WHERE lower(cfg) LIKE 'search_path=%'
-  ) AS has_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
@@ -111,6 +122,8 @@ interface FunctionRow {
   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. */
@@ -132,6 +145,8 @@ export function catalogFunctionToDescriptor(row: FunctionRow): FunctionDescripto
     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,
   };
 }
 

package/src/storage/index.ts

@@ -1,3 +1,5 @@
+import type { S3StorageOptions } from './s3';
+
 export interface StorageAdapter {
   put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void>;
   get(key: string): Promise<{ data: Buffer; contentType: string } | null>;
@@ -32,7 +34,18 @@ export interface StorageAdapter {
 
 export type StorageOptions =
   | { type: 'filesystem'; directory: string }
-  | { type: 's3'; bucket: string; region?: string; endpoint?: string };
+  | {
+      type: 's3';
+      bucket: string;
+      region?: string;
+      endpoint?: string;
+      /**
+       * Bound the S3 client's failure modes (connect/request timeouts, retries,
+       * list caps). Every field defaults to a safe bound; env vars override too.
+       * See {@link S3StorageOptions}.
+       */
+      options?: S3StorageOptions;
+    };
 
 export async function createStorage(options: StorageOptions): Promise<StorageAdapter> {
   if (options.type === 'filesystem') {
@@ -40,8 +53,8 @@ export async function createStorage(options: StorageOptions): Promise<StorageAda
     return new FilesystemStorageAdapter(options.directory);
   }
   const { S3StorageAdapter } = await import('./s3');
-  return new S3StorageAdapter(options.bucket, options.region, options.endpoint);
+  return new S3StorageAdapter(options.bucket, options.region, options.endpoint, options.options);
 }
 
 export { FilesystemStorageAdapter } from './filesystem';
-export { S3StorageAdapter } from './s3';
+export { S3StorageAdapter, type S3StorageOptions } from './s3';

package/src/storage/s3.ts

@@ -1,15 +1,58 @@
 import type { StorageAdapter } from './index';
 
+/**
+ * Tuning for the S3 client's failure modes. Every value is bounded by default so
+ * a single call can never hang: under an S3 503 SlowDown storm an unbounded
+ * client blocks until the Lambda's own timeout (60s), and because each hung
+ * invocation pins a concurrency slot, the observability rollup can drain the
+ * whole account pool and starve the app it observes. Bounded here, a stuck call
+ * fails fast instead. Overridable per-field, then by env (so ops can tighten a
+ * live Lambda without a code redeploy), then these defaults.
+ */
+export interface S3StorageOptions {
+  /** TCP connect timeout, ms. Env: EVERYSTACK_S3_CONNECT_TIMEOUT_MS. */
+  connectionTimeoutMs?: number;
+  /** Socket-idle timeout for a single request, ms. Env: EVERYSTACK_S3_REQUEST_TIMEOUT_MS. */
+  requestTimeoutMs?: number;
+  /** Total attempts per call (1 + retries). Env: EVERYSTACK_S3_MAX_ATTEMPTS. */
+  maxAttempts?: number;
+  /** Keys per ListObjectsV2 page (S3 caps this at 1000). */
+  listMaxKeys?: number;
+  /** Hard backstop on pages a single list() will walk before truncating (warns). */
+  listMaxPages?: number;
+}
+
+function envInt(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
 export class S3StorageAdapter implements StorageAdapter {
   private bucket: string;
   private region: string;
   private endpoint?: string;
   private client: any;
 
-  constructor(bucket: string, region?: string, endpoint?: string) {
+  private readonly connectionTimeoutMs: number;
+  private readonly requestTimeoutMs: number;
+  private readonly maxAttempts: number;
+  private readonly listMaxKeys: number;
+  private readonly listMaxPages: number;
+
+  constructor(bucket: string, region?: string, endpoint?: string, options: S3StorageOptions = {}) {
     this.bucket = bucket;
     this.region = region || 'us-east-1';
     this.endpoint = endpoint;
+
+    this.connectionTimeoutMs =
+      options.connectionTimeoutMs ?? envInt('EVERYSTACK_S3_CONNECT_TIMEOUT_MS') ?? 3000;
+    this.requestTimeoutMs =
+      options.requestTimeoutMs ?? envInt('EVERYSTACK_S3_REQUEST_TIMEOUT_MS') ?? 10000;
+    this.maxAttempts = options.maxAttempts ?? envInt('EVERYSTACK_S3_MAX_ATTEMPTS') ?? 3;
+    this.listMaxKeys = options.listMaxKeys ?? 1000;
+    this.listMaxPages = options.listMaxPages ?? 1000;
   }
 
   private async getClient(): Promise<any> {
@@ -17,6 +60,15 @@ export class S3StorageAdapter implements StorageAdapter {
       const { S3Client } = await import('@aws-sdk/client-s3');
       this.client = new S3Client({
         region: this.region,
+        // Bounded retries — the SDK default (3) is fine, but pin it so a config
+        // drift can't reintroduce unbounded blocking under throttling.
+        maxAttempts: this.maxAttempts,
+        // Connect + per-request timeouts. Without these a call can block forever
+        // on a stalled socket (the 60s-hang class the rollup outage rode in on).
+        requestHandler: {
+          connectionTimeout: this.connectionTimeoutMs,
+          requestTimeout: this.requestTimeoutMs,
+        },
         ...(this.endpoint ? { endpoint: this.endpoint, forcePathStyle: true } : {}),
       });
     }
@@ -136,11 +188,13 @@ export class S3StorageAdapter implements StorageAdapter {
     const client = await this.getClient();
     const keys: string[] = [];
     let continuationToken: string | undefined;
+    let pages = 0;
 
     do {
       const response = await client.send(new ListObjectsV2Command({
         Bucket: this.bucket,
         Prefix: prefix,
+        MaxKeys: this.listMaxKeys,
         ContinuationToken: continuationToken,
       }));
       if (response.Contents) {
@@ -149,6 +203,17 @@ export class S3StorageAdapter implements StorageAdapter {
         }
       }
       continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+      pages += 1;
+      // Backstop: a prefix that walks past the page cap is almost always a sign
+      // the rollup's per-hour debounce isn't engaged (one object → one invoke).
+      // Truncate loudly rather than let a single list() run unbounded.
+      if (continuationToken && pages >= this.listMaxPages) {
+        console.warn(
+          `[s3] list('${prefix}') hit the ${this.listMaxPages}-page cap at ${keys.length} keys; truncating. ` +
+            `A prefix this large usually means the observability rollup is being invoked per-object instead of per-hour.`,
+        );
+        break;
+      }
     } while (continuationToken);
 
     return keys;