@everystack/cli 0.4.98 → 0.4.99

package/src/cli/select-grant-advisory.ts

@@ -0,0 +1,132 @@
+/**
+ * A role that can write a table but holds no SELECT grant on it.
+ *
+ * `can('update', { role: 'moderator' })` alone compiles `GRANT UPDATE` and an UPDATE policy for
+ * moderator, but no SELECT grant. PostgreSQL needs SELECT to read the columns a WHERE or RETURNING
+ * names, so every `UPDATE t ... WHERE id = $1` by moderator fails with "permission denied for
+ * table t". The ability reads as working and is dead. The same holds for DELETE ... WHERE and
+ * INSERT ... RETURNING (measured: __tests__/integration/select-grant-advisory.test.ts).
+ *
+ * The rule reads the COMPILED grants (compileTableContract), not the abilities, so it judges what
+ * the database will hold: `manage` carries its SELECT, a bare `can('read')` covers anon and
+ * authenticated only, an owner read is authenticated's table SELECT, and a column-scoped SELECT
+ * counts. Two exceptions: a role with any ability carrying a raw `sql:` condition is skipped (a
+ * hand-written predicate is outside what this rule judges), and a write granted only through the
+ * model's `privileges:` is left to findNakedGrants, which owns that case.
+ *
+ * The rule cannot see role membership: a role that inherits SELECT from another role it is a
+ * member of is still reported, since no model declares memberships.
+ *
+ * The advice is a read SCOPED to the rows the write touches, never broader than the write: for an
+ * owner write a role-wide `can('read', { role })` would be a USING (true) policy for every
+ * signed-in user. A role-wide read is offered only for a role-wide write.
+ *
+ * Known limits: a table with `rls: false` whose `privileges:` grant a write but no SELECT is
+ * skipped here (findNakedGrants owns `privileges:` grants and does not name the missing SELECT);
+ * and a write scoped by `where:` alone gets the generic advice, which can be wider than the write.
+ *
+ * Advisory only — db:check reports it as a warning and never fails on it.
+ */
+
+import type { Ability, ModelDescriptor } from '@everystack/model';
+import { compileTableContract } from './authz-compile';
+import type { TableContract } from './authz-contract';
+
+export type WriteVerb = 'create' | 'delete' | 'update';
+
+export interface SelectGrantGap {
+  /** `schema.table`. */
+  table: string;
+  role: string;
+  /** The ability verb whose grant is unusable without SELECT. */
+  verb: WriteVerb;
+  message: string;
+}
+
+/** Ability verb -> the privilege it compiles to, in report order. */
+const WRITE_PRIVILEGES: ReadonlyArray<[WriteVerb, string]> = [
+  ['create', 'INSERT'],
+  ['delete', 'DELETE'],
+  ['update', 'UPDATE'],
+];
+
+/** The statement shape that needs SELECT, per privilege. INSERT has no WHERE. */
+const NEEDS_SELECT: Record<string, string> = {
+  INSERT: 'INSERT ... RETURNING',
+  DELETE: 'DELETE ... WHERE/RETURNING',
+  UPDATE: 'UPDATE ... WHERE/RETURNING',
+};
+
+/** Does the role hold this privilege on the table, table-wide or on any column? */
+function holds(contract: TableContract, role: string, privilege: string): boolean {
+  return (contract.grants[role] ?? []).includes(privilege)
+    || Boolean(contract.columnGrants?.[role]?.[privilege]?.length);
+}
+
+/** The grantee an ability lands on — what compileGrants keys it under. */
+function granteeOf(role: string | undefined): string {
+  if (!role) return 'authenticated';
+  return role.toLowerCase() === 'public' ? 'PUBLIC' : role;
+}
+
+/** The table privileges an ability compiles to (`manage` is all four). */
+function privilegesOf(action: Ability['action']): string[] {
+  switch (action) {
+    case 'manage': return ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+    case 'read': return ['SELECT'];
+    case 'create': return ['INSERT'];
+    case 'update': return ['UPDATE'];
+    case 'delete': return ['DELETE'];
+    default: return [];
+  }
+}
+
+/** The abilities whose grant puts `privilege` on `role` — none means it came from `privileges:`. */
+function sources(model: ModelDescriptor, role: string, privilege: string): Ability[] {
+  return model.abilities.filter((a) => granteeOf(a.condition.role) === role && privilegesOf(a.action).includes(privilege));
+}
+
+/** The read to suggest: scoped like the write when the write is owner/via-scoped, else generic. */
+function remedy(role: string, from: readonly Ability[]): string {
+  const scoped = from.find((a) => a.condition.owner || a.condition.via);
+  const lead = `Add a read ability for ${role} scoped to the rows it may touch`;
+  if (!scoped) {
+    return `${lead} (for example can('read', { owner: '<column>' }) for an owner write, `
+      + `or can('read', { role: '${role}' }) for a role-wide one).`;
+  }
+  const keys = [
+    ...(scoped.condition.role ? [`role: '${scoped.condition.role}'`] : []),
+    scoped.condition.owner ? `owner: '${scoped.condition.owner}'` : `via: '${scoped.condition.via}'`,
+  ];
+  return `${lead}, for example can('read', { ${keys.join(', ')} }).`;
+}
+
+export function findSelectGrantGaps(models: readonly ModelDescriptor[]): SelectGrantGap[] {
+  const out: SelectGrantGap[] = [];
+  for (const model of models) {
+    const contract = compileTableContract(model);
+    const suppressed = new Set(
+      model.abilities.filter((a) => a.condition.sql != null).map((a) => granteeOf(a.condition.role)),
+    );
+    const roles = new Set([...Object.keys(contract.grants), ...Object.keys(contract.columnGrants ?? {})]);
+    for (const role of [...roles].sort()) {
+      if (suppressed.has(role)) continue;
+      // A PUBLIC SELECT reaches every role, so it satisfies any of them.
+      if (holds(contract, role, 'SELECT') || holds(contract, 'PUBLIC', 'SELECT')) continue;
+      for (const [verb, privilege] of WRITE_PRIVILEGES) {
+        if (!holds(contract, role, privilege)) continue;
+        const from = sources(model, role, privilege);
+        if (from.length === 0) continue;
+        out.push({
+          table: contract.table,
+          role,
+          verb,
+          message: `${contract.table}: ${role} can ${privilege} but has no SELECT grant; `
+            + `${NEEDS_SELECT[privilege]} by ${role} fails with "permission denied for table ${model.table}". `
+            + remedy(role, from),
+        });
+      }
+    }
+  }
+  return out;
+}

package/src/cli/stage-backup.ts

@@ -24,6 +24,8 @@
 
 import { invokeAction, lambdaSessionRunner } from './aws';
 import { pollTaskUntilStopped } from './task-poll';
+import type { BackupLiveRead } from './apply-execute';
+import type { AuthzManifest } from './authz-manifest';
 
 /** The verdict on a completed dump's fingerprint pair. Pure — the heart of the sandwich. */
 export type SandwichVerdict = { ok: true } | { ok: false; reason: string };
@@ -46,10 +48,14 @@ export function judgeSandwich(fpBefore: string, fpAfter: string): SandwichVerdic
 }
 
 export interface StageBackupDeps {
-  /** Read the live base-schema fingerprint. Called twice, bracketing the dump. */
-  readFingerprint: () => Promise<string>;
-  /** Dispatch `db:backup` with the operator-computed fingerprint. */
-  dispatch: (fingerprint: string) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
+  /**
+   * Read the live base-schema fingerprint and the target's origin commit, in one session. Called
+   * twice, bracketing the dump; the sandwich judges the fingerprints, and the OPENING read is what
+   * the dispatch carries.
+   */
+  readLive: () => Promise<BackupLiveRead>;
+  /** Dispatch `db:backup` with the operator-computed fingerprint and origin commit. */
+  dispatch: (live: BackupLiveRead) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
   /**
    * Wait for the task to stop; resolve ok, or a human reason it did not.
    *
@@ -59,6 +65,13 @@ export interface StageBackupDeps {
   awaitTask: (ids: { runId: string; taskArn: string; id: string }) => Promise<{ ok: true; bytes?: number; stampedFingerprint?: string } | { ok: false; reason: string }>;
   /** Delete a retracted artifact (the ops Lambda's db:backup:retract). */
   retract: (key: string) => Promise<void>;
+  /**
+   * Stamp the declared-authz manifest onto the finished backup (the ops Lambda's
+   * db:backup:stamp-authz). Optional: only a caller that rendered a manifest supplies it. Runs only
+   * on a PROVEN backup, and its failure is a warning, never a failed backup — the dump is valid, the
+   * manifest is metadata layered on top, and a restore treats a missing one as "no manifest".
+   */
+  stampAuthz?: (key: string) => Promise<void>;
   /** Progress output. Optional so tests stay quiet. */
   onStep?: (message: string) => void;
 }
@@ -78,18 +91,19 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
   const step = deps.onStep ?? (() => {});
 
   step('Reading the live schema fingerprint (before the dump)...');
-  let fpBefore: string;
+  let before: BackupLiveRead;
   try {
-    fpBefore = await deps.readFingerprint();
+    before = await deps.readLive();
   } catch (err: any) {
     // Refuse BEFORE dispatching: a dump whose fingerprint cannot be proven is not a safety net, and
     // taking one anyway would burn the dump window and still leave nothing trustworthy.
     return { ok: false, reason: `the schema fingerprint could not be read, so no backup was dispatched: ${err?.message ?? String(err)}` };
   }
+  const fpBefore = before.fingerprint;
 
   let dispatched: { runId: string; taskArn: string; id: string; key: string; warning?: string };
   try {
-    dispatched = await deps.dispatch(fpBefore);
+    dispatched = await deps.dispatch(before);
   } catch (err: any) {
     return { ok: false, reason: `the backup would not dispatch: ${err?.message ?? String(err)}` };
   }
@@ -127,7 +141,7 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
   step('Re-reading the schema fingerprint (after the dump)...');
   let fpAfter: string;
   try {
-    fpAfter = await deps.readFingerprint();
+    fpAfter = (await deps.readLive()).fingerprint;
   } catch (err: any) {
     // The dump exists but is unproven. Do NOT retract — an unreadable fingerprint is not evidence
     // the schema moved, and silently destroying a good backup is the worse error.
@@ -146,7 +160,16 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
     const unverified = finished.stampedFingerprint === undefined
       ? 'the task did not report the fingerprint it stamped, so the artifact could not be verified against what the operator sent (the result-ledger write is best-effort)'
       : undefined;
-    const warning = [dispatched.warning, unverified].filter(Boolean).join('; ') || undefined;
+    let unstamped: string | undefined;
+    if (deps.stampAuthz) {
+      step('Recording the declared authz manifest on the backup...');
+      try {
+        await deps.stampAuthz(dispatched.key);
+      } catch (err: any) {
+        unstamped = `the backup is valid, but its authz manifest was NOT recorded (${err?.message ?? String(err)}) — a restore from it cannot converge authz from the manifest; take another backup if you need one`;
+      }
+    }
+    const warning = [dispatched.warning, unverified, unstamped].filter(Boolean).join('; ') || undefined;
     return { ok: true, id: dispatched.id, key: dispatched.key, bytes: finished.bytes, fingerprint: fpBefore, warning };
   }
 
@@ -178,22 +201,31 @@ export function stageBackupDeps(
   config: { region: string },
   opsFn: string,
   stage: string | undefined,
-  hooks: { onStep?: (message: string) => void; onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void } = {},
+  hooks: {
+    onStep?: (message: string) => void;
+    onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void;
+    /** The declared-authz manifest to stamp onto the finished backup (db:backup renders it). */
+    authzManifest?: AuthzManifest;
+  } = {},
 ): StageBackupDeps {
+  const { authzManifest } = hooks;
   return {
     // BOTH ends of the sandwich read over this ONE closure, so they cannot land on different lanes.
     // That matters: a before-read over a direct session and an after-read over the two-invoke
     // ops-Lambda blend could manufacture a false mismatch — or, worse, a false match. The symmetry
     // is structural here rather than asserted; if a caller ever needs to override one end, it has to
     // override both.
-    readFingerprint: async () => {
-      // The SAME helper db:apply's concurrency lock uses — that shared definition is the point.
-      const { liveBaseFingerprint } = await import('./apply-execute');
-      return (await liveBaseFingerprint(lambdaSessionRunner(config.region, opsFn))).hash;
+    readLive: async () => {
+      // The SAME one-session read db:apply's concurrency lock and descent proof use — the
+      // fingerprint and the ledger anchor come from one snapshot, one round trip.
+      const { readBackupLive } = await import('./apply-execute');
+      return readBackupLive(lambdaSessionRunner(config.region, opsFn));
     },
-    dispatch: async (fingerprint) => {
+    dispatch: async ({ fingerprint, originCommit }) => {
+      // `originCommit` is sent as read: a string, `null` (proven none), or left out when the ledger
+      // read failed (JSON drops undefined), so the artifact never claims what the read did not prove.
       const dispatched: any = await invokeAction(config.region, opsFn, 'db:backup', {
-        stage, actor: process.env.USER ?? null, fingerprint,
+        stage, actor: process.env.USER ?? null, fingerprint, originCommit,
       });
       if (dispatched?.error) throw new Error(dispatched.error);
       hooks.onDispatch?.(dispatched);
@@ -224,6 +256,15 @@ export function stageBackupDeps(
       if (res?.error) throw new Error(res.error);
       if (!res?.retracted) throw new Error(`the ops function did not confirm the retraction (returned ${JSON.stringify(res)})`);
     },
+    // Sent AFTER the dump, never in the dispatch: the task job is one ECS env override capped at
+    // 8192 chars, which a real manifest outgrows. Scoped server-side like the retraction.
+    ...(authzManifest ? {
+      stampAuthz: async (key: string) => {
+        const res: any = await invokeAction(config.region, opsFn, 'db:backup:stamp-authz', { key, stage, authzManifest });
+        if (res?.error) throw new Error(res.error);
+        if (!res?.stamped) throw new Error(`the ops function did not confirm the stamp (returned ${JSON.stringify(res)}) — deploy a server build that ships db:backup:stamp-authz`);
+      },
+    } : {}),
     onStep: hooks.onStep,
   };
 }