@everystack/cli 0.2.39 → 0.3.0

package/src/cli/authz-render.ts

@@ -0,0 +1,248 @@
+/**
+ * The human-readable view of the Authorization Contract.
+ *
+ * The JSON contract is machine-grade — correct for diff/test/probe, but a CTO cannot
+ * scan `(author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->>
+ * 'sub'::text))::uuid)` and confirm it means "owns the row". This renders the same
+ * contract as a role x action matrix with the predicates translated to plain English,
+ * so a human can read it and confirm or deny the rules match intent.
+ *
+ * `humanizePredicate` recognises the handful of shapes that make up ~all real policies
+ * (owner check, soft-delete guard, boolean, simple comparisons) — the same
+ * classification the v3 reverse-compiler (db:pull -> can()) needs, so it is not
+ * throwaway. Anything it does not recognise is shown verbatim, never hidden.
+ */
+
+import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { hasPrivilege } from './authz-redteam.js';
+
+/** True when the expression resolves to the signed-in user's id (any of the forms). */
+function isCurrentUserExpr(s: string): boolean {
+  return /current_setting\([^)]*jwt\.claims/i.test(s)
+    || /auth\.uid\(\)/i.test(s)
+    || /auth\.jwt\(\)\s*->>\s*'sub'/i.test(s);
+}
+
+/** Strip one layer of redundant outer parentheses, repeatedly. */
+function unwrap(s: string): string {
+  let t = s.trim();
+  while (t.startsWith('(') && t.endsWith(')') && balanced(t.slice(1, -1))) {
+    t = t.slice(1, -1).trim();
+  }
+  return t;
+}
+
+/** True when every '(' in s closes before the end — i.e. the outer parens were redundant. */
+function balanced(s: string): boolean {
+  let depth = 0;
+  for (const ch of s) {
+    if (ch === '(') depth++;
+    else if (ch === ')') { if (--depth < 0) return false; }
+  }
+  return depth === 0;
+}
+
+/** Split on a top-level keyword (OR / AND), respecting parentheses. */
+function splitTop(s: string, keyword: 'OR' | 'AND'): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let last = 0;
+  const re = new RegExp(`\\b${keyword}\\b`, 'gi');
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') depth--;
+    else if (depth === 0) {
+      re.lastIndex = i;
+      const m = re.exec(s);
+      if (m && m.index === i) {
+        parts.push(s.slice(last, i));
+        i += m[0].length - 1;
+        last = i + 1;
+      }
+    }
+  }
+  parts.push(s.slice(last));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** One comparison/atom -> a phrase. Falls back to the raw SQL in backticks. */
+function ownerOf(col: string): string {
+  return `owner (\`${col.replace(/"/g, '')}\`)`;
+}
+
+function humanizeAtom(atom: string): string {
+  const a = unwrap(atom);
+  if (/^true$/i.test(a)) return 'any row';
+  if (/^false$/i.test(a)) return 'no row';
+
+  // <col> IN ( SELECT ... FROM <parent> WHERE ... <current user> ... ) — parent-visibility
+  // inheritance: you may touch this row when you own the parent it links to.
+  let m = a.match(/^([\w".]+)\s+IN\s*\(\s*SELECT[\s\S]*?\bFROM\s+([\w".]+)/i);
+  if (m && isCurrentUserExpr(a)) {
+    return `owner of linked \`${m[2].replace(/"/g, '')}\` (via \`${m[1].replace(/"/g, '')}\`)`;
+  }
+
+  // <col> = <current-user-id-expr>  (in either order) -> ownership. Anchored on the
+  // column and the start of the identity expression, so the trailing cast/paren noise
+  // (`::uuid`, `))`) never matters.
+  if (isCurrentUserExpr(a)) {
+    m = a.match(/^\(*\s*([\w".]+)\s*=\s*\(*\s*(?:current_setting|auth\.)/i);
+    if (m) return ownerOf(m[1]);
+    m = a.match(/=\s*([\w".]+)\s*\)*$/);
+    if (m) return ownerOf(m[1]);
+    // A subquery / EXISTS keyed on the current user that we can't reduce cleanly — be
+    // honest that it depends on the user via related data, and point at the JSON.
+    if (/\bselect\b|\bexists\b/i.test(a)) return 'depends on the signed-in user (via a subquery — see JSON)';
+    return 'the current user';
+  }
+
+  // a bare boolean column used as a predicate (e.g. `active`) means "<col> is true"
+  if (/^[\w".]+$/.test(a)) return `\`${a.replace(/"/g, '')}\` is true`;
+
+  // soft-delete / null guards
+  m = a.match(/^([\w".]+)\s+IS\s+NULL$/i);
+  if (m) return /delet/i.test(m[1]) ? 'not deleted' : `\`${m[1].replace(/"/g, '')}\` is empty`;
+  m = a.match(/^([\w".]+)\s+IS\s+NOT\s+NULL$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` is set`;
+
+  // simple equality / membership against a literal
+  m = a.match(/^([\w".]+)\s*=\s*('[^']*'|\w+)$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` = ${m[2]}`;
+  m = a.match(/^([\w".]+)\s+IN\s+(\(.+\))$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` in ${m[2]}`;
+
+  return `\`${a}\``;
+}
+
+/**
+ * Translate an RLS predicate to a plain-English phrase. null/empty -> "any row".
+ * Handles OR / AND combinations of the recognised atoms; unknown atoms are shown raw.
+ */
+export function humanizePredicate(sql: string | null): string {
+  if (!sql || !sql.trim()) return 'any row';
+  const expr = unwrap(sql);
+
+  const ors = splitTop(expr, 'OR');
+  if (ors.length > 1) return ors.map(renderConj).join(' OR ');
+  return renderConj(expr);
+}
+
+function renderConj(s: string): string {
+  const ands = splitTop(s, 'AND');
+  if (ands.length > 1) return ands.map(humanizeAtom).join(' AND ');
+  return humanizeAtom(s);
+}
+
+// ---------------------------------------------------------------------------
+// The matrix renderer.
+// ---------------------------------------------------------------------------
+
+const ACTIONS: { label: string; command: string; clause: 'using' | 'check' }[] = [
+  { label: 'Read', command: 'SELECT', clause: 'using' },
+  { label: 'Create', command: 'INSERT', clause: 'check' },
+  { label: 'Update', command: 'UPDATE', clause: 'using' },
+  { label: 'Delete', command: 'DELETE', clause: 'using' },
+];
+const COMMAND_PRIVILEGE: Record<string, string> = { SELECT: 'SELECT', INSERT: 'INSERT', UPDATE: 'UPDATE', DELETE: 'DELETE' };
+
+/** Roles to show as rows: the table's grantees (and column-grantees), minus PUBLIC. */
+function tableRoles(t: TableContract): string[] {
+  const roles = new Set<string>();
+  Object.keys(t.grants).forEach((g) => g.toUpperCase() !== 'PUBLIC' && roles.add(g));
+  Object.keys(t.columnGrants ?? {}).forEach((g) => g.toUpperCase() !== 'PUBLIC' && roles.add(g));
+  return [...roles].sort();
+}
+
+function policiesFor(t: TableContract, role: string, command: string): { permissive: PolicyContract[]; restrictive: PolicyContract[] } {
+  const applies = (p: PolicyContract) =>
+    (p.command === command || p.command === 'ALL') &&
+    (p.roles.includes(role) || p.roles.includes('public'));
+  return {
+    permissive: t.policies.filter((p) => applies(p) && p.permissive),
+    restrictive: t.policies.filter((p) => applies(p) && !p.permissive),
+  };
+}
+
+/** One matrix cell for (table, role, action). */
+export function renderCell(t: TableContract, role: string, action: typeof ACTIONS[number]): string {
+  const priv = COMMAND_PRIVILEGE[action.command];
+  if (!hasPrivilege(t, role, priv)) return '—';
+  if (!t.rls.enabled) return '✓ all';
+
+  const { permissive, restrictive } = policiesFor(t, role, action.command);
+  if (permissive.length === 0) return '⚠ no policy';
+
+  const conds = permissive.map((p) => humanizePredicate(p[action.clause]));
+  let cell = conds.some((c) => c === 'any row') ? '✓ all' : `✓ ${[...new Set(conds)].join(' OR ')}`;
+  if (restrictive.length) {
+    cell += ` (only if ${restrictive.map((p) => humanizePredicate(p[action.clause])).join(' AND ')})`;
+  }
+  // Column-restricted read/write: note the columns when access is column-scoped only.
+  const cols = t.columnGrants?.[role]?.[priv];
+  if (cols?.length && !(t.grants[role] ?? []).includes(priv)) {
+    cell += ` — cols: ${cols.join(', ')}`;
+  }
+  return cell;
+}
+
+/** Render the whole contract as a human-readable Markdown review document. */
+export function renderContractMarkdown(contract: AuthzContract): string {
+  const policyCount = contract.tables.reduce((n, t) => n + t.policies.length, 0);
+  const lines: string[] = [];
+
+  lines.push('# Authorization Review');
+  lines.push('');
+  lines.push('> The human-readable view of `authz/*.contract.json`. Read it to confirm the rules');
+  lines.push('> match intent — the JSON is the machine-checked source, this is generated from it.');
+  lines.push('> Regenerate with `everystack db:authz:report`; never hand-edit.');
+  lines.push('');
+  lines.push(`_${contract.tables.length} tables · ${policyCount} policies · ${contract.functions.length} SECURITY DEFINER functions._`);
+  lines.push('');
+  lines.push('**Legend:**');
+  lines.push('');
+  lines.push('- **✓** — allowed, followed by the condition a row must satisfy');
+  lines.push('- **—** — not granted');
+  lines.push('- **⚠ no policy** — the privilege is granted but no RLS policy matches, so no rows are returned (usually a mistake)');
+  lines.push('- **owner (`col`)** — the row\'s `col` equals the signed-in user');
+  lines.push('- **owner of linked `t` (via `col`)** — you may act when you own the `t` row that `col` points to');
+  lines.push('');
+
+  for (const t of contract.tables) {
+    const posture = t.rls.enabled ? (t.rls.forced ? 'enforced (forced)' : 'enabled (not forced)') : '**OFF — no row security**';
+    lines.push(`## ${t.table}`);
+    lines.push(`RLS: ${posture}`);
+    lines.push('');
+    const roles = tableRoles(t);
+    if (roles.length === 0) {
+      lines.push('_No roles granted any access._');
+      lines.push('');
+      continue;
+    }
+    lines.push(`| Role | ${ACTIONS.map((a) => a.label).join(' | ')} |`);
+    lines.push(`|---|${ACTIONS.map(() => '---').join('|')}|`);
+    for (const role of roles) {
+      lines.push(`| \`${role}\` | ${ACTIONS.map((a) => renderCell(t, role, a)).join(' | ')} |`);
+    }
+    lines.push('');
+  }
+
+  if (contract.functions.length) {
+    lines.push('## SECURITY DEFINER functions');
+    lines.push('');
+    lines.push('These run with their owner\'s privileges, **above row security** — their own bodies enforce access. Review each one deliberately. A missing `search_path` is a hijack vector; an owner that bypasses RLS (superuser / BYPASSRLS) makes the function run above RLS as that role — the maximum blast radius. `db:migrate` often leaves functions superuser-owned; normalize ownership to a non-superuser operator.');
+    lines.push('');
+    const elevated = contract.functions.filter((f) => f.ownerBypassesRls);
+    if (elevated.length) {
+      lines.push(`> **⚠ ${elevated.length} function(s) are owned by a role that bypasses RLS** — they run above row security regardless of \`search_path\`. Normalize their ownership.`);
+      lines.push('');
+    }
+    for (const f of contract.functions) {
+      const sp = f.hasSearchPath ? 'search_path pinned ✓' : '**search_path NOT pinned ⚠**';
+      const own = f.ownerBypassesRls ? ' · **owner bypasses RLS ⚠**' : '';
+      lines.push(`- \`${f.name}\` — ${sp}${own}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/cli/aws.ts

@@ -8,6 +8,7 @@
 let s3Client: InstanceType<typeof import('@aws-sdk/client-s3').S3Client> | null = null;
 let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaClient> | null = null;
 let kvsClient: InstanceType<typeof import('@aws-sdk/client-cloudfront-keyvaluestore').CloudFrontKeyValueStoreClient> | null = null;
+let rdsClient: InstanceType<typeof import('@aws-sdk/client-rds').RDSClient> | null = null;
 
 async function getS3(region: string) {
   if (!s3Client) {
@@ -25,6 +26,14 @@ async function getLambda(region: string) {
   return lambdaClient;
 }
 
+async function getRds(region: string) {
+  if (!rdsClient) {
+    const { RDSClient } = await import('@aws-sdk/client-rds');
+    rdsClient = new RDSClient({ region });
+  }
+  return rdsClient;
+}
+
 export async function uploadToS3(
   region: string,
   bucket: string,
@@ -373,3 +382,94 @@ export async function putKvsKey(
     })
   );
 }
+
+/** Presign a GET URL for an S3 object (operator IAM). Used by db:backup:download. */
+export async function presignGet(
+  region: string,
+  bucket: string,
+  key: string,
+  expiresIn = 3600,
+): Promise<string> {
+  const client = await getS3(region);
+  const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+  const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
+  return await getSignedUrl(client as any, new GetObjectCommand({ Bucket: bucket, Key: key }), { expiresIn });
+}
+
+/** A flattened RDS DB snapshot summary, the fields the CLI prints. */
+export interface RdsSnapshotSummary {
+  identifier: string;
+  status: string;
+  /** When the snapshot was first created (stable across copies). */
+  created?: Date;
+  /** Allocated storage in GiB. */
+  sizeGiB?: number;
+  engineVersion?: string;
+  encrypted?: boolean;
+  /** manual | automated | awsbackup | shared | public. */
+  type?: string;
+}
+
+/**
+ * Create a manual RDS DB snapshot of `dbInstanceId` (a physical, instance-level point-in-time image).
+ * Control-plane call — authorized purely by the operator's IAM, no VPC. Returns the new snapshot's
+ * identifier + initial status (`creating`); the snapshot becomes usable once it reaches `available`.
+ */
+export async function createRdsSnapshot(
+  region: string,
+  dbInstanceId: string,
+  snapshotId: string,
+): Promise<RdsSnapshotSummary> {
+  const client = await getRds(region);
+  const { CreateDBSnapshotCommand } = await import('@aws-sdk/client-rds');
+  const res = await client.send(new CreateDBSnapshotCommand({
+    DBInstanceIdentifier: dbInstanceId,
+    DBSnapshotIdentifier: snapshotId,
+  }));
+  const s = res.DBSnapshot ?? {};
+  return {
+    identifier: s.DBSnapshotIdentifier ?? snapshotId,
+    status: s.Status ?? 'creating',
+    created: s.SnapshotCreateTime,
+    sizeGiB: s.AllocatedStorage,
+    engineVersion: s.EngineVersion,
+    encrypted: s.Encrypted,
+    type: s.SnapshotType,
+  };
+}
+
+/**
+ * List the manual RDS DB snapshots for `dbInstanceId`, newest first. Manual-only by default — the
+ * automated/PITR backups RDS takes on its own are noise for this command.
+ */
+export async function describeRdsSnapshots(
+  region: string,
+  dbInstanceId: string,
+): Promise<RdsSnapshotSummary[]> {
+  const client = await getRds(region);
+  const { DescribeDBSnapshotsCommand } = await import('@aws-sdk/client-rds');
+  const summaries: RdsSnapshotSummary[] = [];
+  let marker: string | undefined;
+  do {
+    const res = await client.send(new DescribeDBSnapshotsCommand({
+      DBInstanceIdentifier: dbInstanceId,
+      SnapshotType: 'manual',
+      Marker: marker,
+    }));
+    for (const s of res.DBSnapshots ?? []) {
+      summaries.push({
+        identifier: s.DBSnapshotIdentifier ?? '',
+        status: s.Status ?? '',
+        created: s.SnapshotCreateTime,
+        sizeGiB: s.AllocatedStorage,
+        engineVersion: s.EngineVersion,
+        encrypted: s.Encrypted,
+        type: s.SnapshotType,
+      });
+    }
+    marker = res.Marker;
+  } while (marker);
+  // Newest first; undated (still-creating) snapshots sort to the top.
+  summaries.sort((a, b) => (b.created?.getTime() ?? Infinity) - (a.created?.getTime() ?? Infinity));
+  return summaries;
+}

package/src/cli/backup.ts

@@ -0,0 +1,99 @@
+/**
+ * db:backup / db:restore — the pure core: the S3 key scheme and the cross-stage safety
+ * guards for LOGICAL backups (pg_dump custom format, gzipped). The ops actions (pg_dump → S3)
+ * and the CLI commands share these, so naming and the confirm policy live in one tested place.
+ * See docs/plans/db-backup-restore.md.
+ *
+ * No IO here — the clock (timestamp) and the short id are passed in, so the mapping is
+ * deterministic and unit-tested. Backups are LOGICAL (pg_dump custom format, gzipped),
+ * Postgres-native and portable across stages (and across any Postgres, RDS or not).
+ */
+
+/** Production-tier stage names whose data must not flow downward without explicit intent. */
+const PRODUCTION_TIERS = new Set(['prod', 'production']);
+
+/** Is this stage a production tier (its data is sensitive; restores into/from it are gated)? */
+export function isProductionTier(stage: string): boolean {
+  return PRODUCTION_TIERS.has(stage.toLowerCase());
+}
+
+/** The S3 prefix all of a stage's backups live under (admin-only, encrypted). */
+export function backupPrefix(stage: string): string {
+  return `backups/${stage}`;
+}
+
+/** The object key for a new backup dump. `stamp` is a UTC `YYYYMMDDTHHMMSSZ` string (caller's clock). */
+export function backupKey(stage: string, stamp: string, shortId: string): string {
+  return `${backupPrefix(stage)}/${stamp}-${shortId}.dump.gz`;
+}
+
+/** The metadata sidecar key for a backup dump key. */
+export function metaKey(dumpKey: string): string {
+  return dumpKey.replace(/\.dump\.gz$/, '.meta.json');
+}
+
+/** A stage-qualified backup id — what `list` returns and `restore` consumes: `dev/20260628T120000Z-ab12cd`. */
+export function backupId(stage: string, stamp: string, shortId: string): string {
+  return `${stage}/${stamp}-${shortId}`;
+}
+
+/** Parse a backup id back into its stage and name, or null when malformed. */
+export function parseBackupRef(id: string): { stage: string; name: string } | null {
+  const m = id.match(/^([A-Za-z0-9_-]+)\/([A-Za-z0-9_.:-]+)$/);
+  return m ? { stage: m[1], name: m[2] } : null;
+}
+
+/** The S3 dump key for a backup id (inverse of backupId), or null when the id is malformed. */
+export function keyForId(id: string): string | null {
+  const ref = parseBackupRef(id);
+  return ref ? `${backupPrefix(ref.stage)}/${ref.name}.dump.gz` : null;
+}
+
+/**
+ * Format a Date as the UTC `YYYYMMDDTHHMMSSZ` stamp used in backup keys/ids. The clock is the
+ * caller's — pass `new Date()` at the call site so this stays pure and unit-testable.
+ */
+export function utcStamp(date: Date): string {
+  const p = (n: number): string => String(n).padStart(2, '0');
+  return (
+    `${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}` +
+    `T${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}Z`
+  );
+}
+
+export interface Guard {
+  /** True when the operation needs an explicit confirmation token/flag, not just a default run. */
+  requiresConfirm: boolean;
+  /** The warning to show when confirmation is required. */
+  warning?: string;
+}
+
+/**
+ * Whether restoring `fromStage` → `toStage` needs explicit confirmation. A production-tier source
+ * into a different (non-prod) target drags production data — PII, credentials — downward; that is
+ * a data-governance decision the operator must make on purpose, never by accident.
+ */
+export function crossStageGuard(fromStage: string, toStage: string): Guard {
+  if (fromStage === toStage) return { requiresConfirm: false };
+  if (isProductionTier(fromStage) && !isProductionTier(toStage)) {
+    return {
+      requiresConfirm: true,
+      warning: `Restoring from production-tier "${fromStage}" into "${toStage}" copies ALL production data — including PII and credentials — into ${toStage}. This is a data-governance decision; pass --confirm to proceed.`,
+    };
+  }
+  return { requiresConfirm: false };
+}
+
+/**
+ * Whether a restore INTO `toStage` needs explicit confirmation regardless of source. A restore
+ * OVERWRITES the target's database; into a production tier that is always intent-only.
+ */
+export function restoreTargetGuard(toStage: string): Guard {
+  if (isProductionTier(toStage)) {
+    return {
+      requiresConfirm: true,
+      warning: `Restore OVERWRITES the database of production-tier stage "${toStage}" — every current row is replaced. Pass --confirm to proceed.`,
+    };
+  }
+  return { requiresConfirm: false };
+}