@everystack/cli 0.2.37 → 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/commands/db.ts

@@ -9,6 +9,34 @@ import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+/** Secret-store keys that may hold the privileged (operator) connection URL,
+ *  in precedence order. Names vary by deployment; --secret-name overrides. */
+const ADMIN_URL_KEYS = ['ADMIN_DATABASE_URL', 'AdminDatabaseUrl', 'ADMIN_URL'];
+
+/**
+ * Parse a postgres connection URL into psql's PG* environment variables.
+ *
+ * Passing the credential via env (not argv) keeps the password out of the
+ * process table and shell history. Pure and side-effect free — it never logs;
+ * callers must never log the result either (it contains PGPASSWORD).
+ */
+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;
+}
+
 export async function dbMigrateCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -115,6 +143,130 @@ export async function dbResetCommand(flags: Record<string, string>): Promise<voi
   }
 }
 
+export async function dbProvisionCommand(flags: Record<string, string>): Promise<void> {
+  if (!flags.stage) {
+    fail('--stage is required for db:provision (it writes the DATABASE_URL secret for that stage)');
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  info('Creating the least-privilege role chain on your EXISTING database (no database is created).');
+  step('Provisioning roles...');
+
+  // Generate the login password and keep it in memory only — it is written straight into
+  // the secret store and is NEVER printed, logged, or returned to a human.
+  const { randomBytes } = await import('node:crypto');
+  const authPassword = randomBytes(24).toString('hex');
+
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword });
+  } catch (err: any) {
+    fail(`db:provision failed: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`db:provision failed: ${result.error}`);
+    process.exit(1);
+  }
+  success(`Role chain ready: ${result.loginRole} (LOGIN, NOINHERIT, no BYPASSRLS) → can SET ROLE to ${result.appRoles.join(', ')}`);
+
+  // Resolve host/port/db (not secret) to build the connection string in memory.
+  let conn: any;
+  try {
+    conn = await invokeAction(config.region, opsFunction(config), 'db:psql', {});
+  } catch {
+    /* handled below */
+  }
+  if (!conn?.host) {
+    fail('Could not resolve the database host to build DATABASE_URL.');
+    info('Provide a db:psql connectionInfo callback, or set the DATABASE_URL secret yourself.');
+    process.exit(1);
+  }
+  const url = `postgresql://${result.loginRole}:${authPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`;
+
+  // Write the secret directly to the SST secret store — never display it.
+  step('Writing the DATABASE_URL secret (not displayed)...');
+  try {
+    const { loadSstSecrets, putSstSecrets } = await import('../utils/secrets.js');
+    const { parseAppName } = await import('../discover.js');
+    const ctx = { appName: await parseAppName(), stage: flags.stage, region: config.region };
+    const secrets = await loadSstSecrets(ctx);
+    secrets.DATABASE_URL = url;
+    await putSstSecrets(ctx, secrets);
+  } catch (err: any) {
+    fail(`Failed to write the DATABASE_URL secret: ${err.message}`);
+    info('Ensure your IAM role can write the SST secret store (s3:PutObject, kms:Encrypt).');
+    process.exit(1);
+  }
+
+  success(`DATABASE_URL secret set for stage "${flags.stage}" → role ${result.loginRole}. No credential was displayed.`);
+  console.log('');
+  info('Finish the wiring in sst.config.ts (one-time): declare `new sst.Secret("DatabaseUrl")`,');
+  info('link it to the Api function, and remove the raw Postgres component from the Api link');
+  info('(keep it on the ops/worker functions). Then redeploy.');
+  info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
+}
+
+export async function dbDoctorCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Probing database connections (api + operator)...');
+
+  let report: any;
+  try {
+    report = await invokeAction(config.region, opsFunction(config), 'db:doctor', {});
+  } catch (err: any) {
+    fail(`db:doctor failed: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+
+  if (report?.error) {
+    fail(`db:doctor failed: ${report.error}`);
+    process.exit(1);
+  }
+
+  console.log('');
+  info(`api connection (DATABASE_URL):    role=${report.api.role}  superuser=${report.api.isSuperuser}  bypassrls=${report.api.bypassRls}`);
+  info(`operator connection (ADMIN_URL):  role=${report.admin.role}  superuser=${report.admin.isSuperuser}  bypassrls=${report.admin.bypassRls}`);
+  console.log('');
+
+  for (const c of report.checks as Array<{ name: string; status: string; detail: string; remediation?: string }>) {
+    if (c.status === 'pass') success(`${c.name} — ${c.detail}`);
+    else if (c.status === 'warn') warn(`${c.name} — ${c.detail}`);
+    else fail(`${c.name} — ${c.detail}`);
+    if (c.status === 'fail' && c.remediation) info(`    fix: ${c.remediation}`);
+  }
+
+  console.log('');
+  if (report.ok) {
+    success('db:doctor — database is least-privilege and RLS-subject');
+    process.exit(0);
+  } else {
+    fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+    process.exit(1);
+  }
+}
+
 export async function dbPsqlCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -180,9 +332,67 @@ export async function dbPsqlCommand(flags: Record<string, string>): Promise<void
     }
   }
 
-  // Interactive mode: not supported for private RDS
-  fail('Interactive psql mode not supported for private RDS instances.');
-  info('Use -c flag to execute SQL queries via Lambda: everystack db:psql -c "SELECT * FROM users;"');
-  info('The Lambda function executes queries from within the VPC where it can reach the database.');
-  process.exit(1);
+  // Interactive mode — break-glass admin psql.
+  //
+  // Authorization IS your AWS identity: resolving the admin URL requires reading
+  // the SST secret store (SSM passphrase + S3 blob + KMS decrypt). If your
+  // profile can't, you don't get a session — the permission is the policy, no
+  // confirmation prompt. CloudTrail records the decrypt, so the access is
+  // audited for free. The URL is resolved in-process and handed to psql via PG*
+  // env vars: it never touches your terminal, argv, clipboard, or psql history.
+  if (!flags.stage) {
+    fail('--stage is required for an interactive session. Example: everystack db:psql --stage production');
+    info('Or run a one-off query via Lambda: everystack db:psql -c "SELECT 1" --stage production');
+    process.exit(1);
+  }
+
+  step('Resolving the admin connection from the secret store...');
+  let secrets: Record<string, string>;
+  try {
+    const { loadSstSecrets } = await import('../utils/secrets.js');
+    const { parseAppName } = await import('../discover.js');
+    const appName = await parseAppName();
+    secrets = await loadSstSecrets({ appName, stage: flags.stage, region: config.region });
+  } catch (err: any) {
+    fail('Could not read the secret store — your AWS profile lacks secrets access.');
+    info('db:psql opens an ADMIN session; it requires SSM + S3 + KMS access to the SST state.');
+    info('If you should have it, check your IAM permissions; otherwise you should not be in psql.');
+    process.exit(1);
+  }
+
+  const keyName = flags['secret-name'] || ADMIN_URL_KEYS.find((k) => secrets[k]);
+  const adminUrl = keyName ? secrets[keyName] : undefined;
+  if (!adminUrl) {
+    fail(`No admin database URL found for stage "${flags.stage}".`);
+    // Names only — never values.
+    info(`Looked for: ${ADMIN_URL_KEYS.join(', ')}. Available secret names: ${Object.keys(secrets).join(', ') || '(none)'}.`);
+    info('Provision one with `everystack db:provision`, or point at an existing key with --secret-name <KEY>.');
+    process.exit(1);
+  }
+
+  let pgEnv: Record<string, string>;
+  try {
+    pgEnv = pgEnvFromUrl(adminUrl);
+  } catch {
+    fail(`The resolved ${keyName} is not a valid postgres connection URL.`);
+    process.exit(1);
+  }
+
+  // Confirm the target (host/user/db are infra identifiers, not the credential);
+  // the password is in PGPASSWORD and is never displayed.
+  success(
+    `Admin psql → ${flags.stage} as ${pgEnv.PGUSER ?? '?'}@${pgEnv.PGHOST ?? '?'}/${pgEnv.PGDATABASE ?? ''} (credential not displayed)`,
+  );
+
+  const { spawn } = await import('node:child_process');
+  const child = spawn('psql', [], { stdio: 'inherit', env: { ...process.env, ...pgEnv } });
+  child.on('error', (err: any) => {
+    if (err.code === 'ENOENT') {
+      fail('psql not found on PATH. Install the PostgreSQL client to use interactive mode.');
+    } else {
+      fail(`Failed to launch psql: ${err.message}`);
+    }
+    process.exit(1);
+  });
+  child.on('close', (code) => process.exit(code ?? 0));
 }

package/src/cli/commands/logs.ts

@@ -133,6 +133,62 @@ function resolveFunctionForOrigin(
   }
 }
 
+/** One FilterLogEvents page (the subset of the AWS shape this command reads). */
+interface FilterLogEventsPage {
+  events?: Array<{ eventId?: string; timestamp?: number; message?: string }>;
+  nextToken?: string;
+}
+
+/** Carries the tail window across polls so a re-query can't reprint events. */
+export interface TailState {
+  /** Highest event timestamp printed so far. Only moves forward. */
+  lastTimestamp: number;
+  /** eventId → timestamp for events at the boundary millisecond — the only ones
+   *  an inclusive-startTime re-query can return again. Pruned each drain so it
+   *  never grows past one millisecond's worth of events. */
+  seen: Map<string, number>;
+}
+
+/**
+ * Drain one poll's worth of pages, printing only events not seen before and
+ * advancing the window forward.
+ *
+ * The loop bug this fixes: FilterLogEvents `startTime` is INCLUSIVE, so a poll
+ * with `startTime = lastTimestamp` re-returns every event sharing that newest
+ * millisecond. The old code advanced `lastTimestamp` only on a strictly-greater
+ * comparison and never deduped, so the boundary batch reprinted on every 2s poll
+ * forever. Here we dedup by `eventId` and advance to the max timestamp, then
+ * prune `seen` to just the boundary millisecond (the only ids that can recur).
+ *
+ * Exported for unit testing without the AWS SDK or the setTimeout poll loop.
+ */
+export async function drainLogEvents(
+  send: (params: { startTime: number; nextToken?: string }) => Promise<FilterLogEventsPage>,
+  state: TailState,
+  emit: (line: string) => void,
+): Promise<void> {
+  let nextToken: string | undefined;
+  do {
+    const page = await send({ startTime: state.lastTimestamp, nextToken });
+    for (const event of page.events ?? []) {
+      const id = event.eventId;
+      const ts = event.timestamp ?? state.lastTimestamp;
+      if (id && state.seen.has(id)) continue; // already printed this one
+      const timestamp = event.timestamp ? new Date(event.timestamp).toISOString() : '';
+      emit(`[${timestamp}] ${(event.message || '').trimEnd()}`);
+      if (id) state.seen.set(id, ts);
+      if (ts > state.lastTimestamp) state.lastTimestamp = ts;
+    }
+    nextToken = page.nextToken;
+  } while (nextToken);
+
+  // Only events at exactly lastTimestamp can be returned again (startTime is
+  // inclusive); drop everything older so `seen` stays bounded.
+  for (const [id, ts] of state.seen) {
+    if (ts < state.lastTimestamp) state.seen.delete(id);
+  }
+}
+
 export async function logsTailCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -174,42 +230,20 @@ export async function logsTailCommand(flags: Record<string, string>): Promise<vo
 
     success(`Streaming logs from ${logGroupName}...\n`);
 
-    // Poll for new logs every 2 seconds
-    let nextToken: string | undefined;
-    let lastTimestamp = startTime;
+    // Poll for new logs every 2 seconds. State carries the window + dedup set
+    // across polls — see drainLogEvents for why both are required.
+    const state: TailState = { lastTimestamp: startTime, seen: new Map() };
+    const send = (params: { startTime: number; nextToken?: string }) =>
+      client.send(new FilterLogEventsCommand({
+        logGroupName,
+        startTime: params.startTime,
+        filterPattern,
+        ...(params.nextToken ? { nextToken: params.nextToken } : {}),
+      }));
 
     const poll = async () => {
       try {
-        const params: any = {
-          logGroupName,
-          startTime: lastTimestamp,
-          filterPattern,
-        };
-
-        if (nextToken) {
-          params.nextToken = nextToken;
-        }
-
-        const response = await client.send(new FilterLogEventsCommand(params));
-
-        if (response.events && response.events.length > 0) {
-          for (const event of response.events) {
-            if (event.timestamp && event.timestamp > lastTimestamp) {
-              lastTimestamp = event.timestamp;
-            }
-
-            const timestamp = event.timestamp
-              ? new Date(event.timestamp).toISOString()
-              : '';
-            const message = event.message || '';
-
-            console.log(`[${timestamp}] ${message.trimEnd()}`);
-          }
-        }
-
-        nextToken = response.nextToken;
-
-        // Continue polling
+        await drainLogEvents(send, state, (line) => console.log(line));
         setTimeout(poll, 2000);
       } catch (err: any) {
         if (err.name === 'ResourceNotFoundException') {