@everystack/cli 0.4.35 → 0.4.38

package/bin/everystack.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * The `everystack` entry point.
+ *
+ * This package ships TypeScript source deliberately — every `exports` target is a
+ * `./src/*.ts` file — so the CLI needs a TypeScript loader at runtime. It used to get one
+ * from `#!/usr/bin/env tsx` on `src/cli/index.ts`, which cannot work once the package is
+ * installed: `env` searches the CONSUMER's PATH, and tsx is a dependency of
+ * @everystack/cli, so under pnpm's isolated layout it lives in this package's own
+ * node_modules and is never on that PATH. `everystack --help` died with
+ * "env: tsx: No such file or directory"; only `pnpm exec everystack` worked, because that
+ * puts the local .bin on PATH first.
+ *
+ * So: boot under plain `node` — always present, it is what runs npm — and find tsx by
+ * MODULE RESOLUTION from this file rather than by PATH lookup.
+ *
+ * The loader is installed by re-executing node with `--import`, not by calling tsx's
+ * register() in-process. register() followed by `import()` of the TypeScript entry makes
+ * the entry load through a require(esm) path and Node rejects it with
+ * ERR_REQUIRE_CYCLE_MODULE. `--import` installs the hooks before any module graph exists,
+ * which is the only ordering that works. The extra process is the price of shipping
+ * source, and it is paid once per invocation.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+let tsx;
+try {
+  tsx = pathToFileURL(require.resolve('tsx')).href;
+} catch {
+  console.error('everystack: could not resolve the "tsx" TypeScript loader from this package.');
+  console.error('This usually means a partial install — try reinstalling @everystack/cli.');
+  process.exit(1);
+}
+
+const entry = fileURLToPath(new URL('../src/cli/index.ts', import.meta.url));
+
+const result = spawnSync(process.execPath, ['--import', tsx, entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+// Re-raise a signal death as a signal death so `everystack … &` + Ctrl-C behaves, and
+// otherwise pass the child's exit code through unchanged — the CLI's non-zero exits are
+// load-bearing (db:check, db:authz:diff and friends are CI gates).
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(result.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.35",
+  "version": "0.4.38",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "files": [
+    "bin",
     "src",
     "README.md"
   ],
@@ -91,7 +92,7 @@
     }
   },
   "bin": {
-    "everystack": "./src/cli/index.ts"
+    "everystack": "./bin/everystack.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-cloudfront": "3.1053.0",
@@ -111,7 +112,7 @@
     "@everystack/model": "0.4.5"
   },
   "peerDependencies": {
-    "@everystack/server": ">=0.1.0",
+    "@everystack/server": ">=0.4.0",
     "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",

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

@@ -9,9 +9,20 @@
  * 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.
+ * Two venues, one verdict. The core (introspect/assemble/diff/evaluate) is backend-agnostic
+ * and pure — only the VENUE differs, and both satisfy the same `AuthzVenue` contract, so
+ * every command below runs identical evaluation code either way:
+ *
+ * - **Deployed** (`--stage`, the default): the ops Lambda's `db:query` + `db:authz:probe`
+ *   actions. Credentials never leave AWS.
+ * - **Direct** (`--database-url`, or an inherited ADMIN_DATABASE_URL / DATABASE_URL): a
+ *   postgres.js connection from this process.
+ *
+ * The direct venue is what makes a brownfield authz migration rehearsable. Translating
+ * hand-written RLS into Model abilities is the hardest part of an adoption, and until the
+ * local venue existed it was the ONLY part that required a deployed stage to iterate
+ * against. Every run names its venue, because a security verdict against an unintended
+ * database is worse than no verdict.
  */
 
 import path from 'node:path';
@@ -43,6 +54,7 @@ import { renderContractMarkdown } from '../authz-render.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { resolveModelsPath } from '../models-path.js';
+import { resolveDbSource, connectingVia, createUrlProbeRunner } from '../db-source.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
@@ -59,20 +71,65 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
   };
 }
 
-async function introspectStage(flags: Record<string, string>): Promise<AuthzContract> {
+/**
+ * Where an authz command runs. Both venues expose the same two capabilities, so the
+ * commands never branch on venue after this point — that is what keeps the local
+ * rehearsal honest: same SQL, same evaluation, same verdict.
+ */
+interface AuthzVenue {
+  /** Read-only introspection. */
+  runner: QueryRunner;
+  /** Self-reverting red-team probe (writes, always rolled back). */
+  probe: (setup: string, read: string) => Promise<any[]>;
+  /** Human-readable venue, printed with every verdict. */
+  label: string;
+  /** Release any connection this venue holds. */
+  end: () => Promise<void>;
+}
+
+/**
+ * Precedence is `resolveDbSource`'s, shared with db:pull / db:generate / db:check:
+ * `--database-url` > explicit `--stage` > ADMIN_DATABASE_URL > DATABASE_URL > default stage.
+ */
+async function resolveVenue(flags: Record<string, string>): Promise<AuthzVenue> {
+  const source = resolveDbSource(flags);
+  if (source.kind === 'url') {
+    step(connectingVia(source));
+    const { runner, probe, end } = await createUrlProbeRunner(source.url);
+    return { runner, probe, end, label: 'direct connection' };
+  }
   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, contractFunctionRow, FUNCTIONS_SQL);
+  const fn = opsFunction(config);
+  info(`Region: ${config.region}, Function: ${fn}`);
+  return {
+    runner: lambdaRunner(config.region, fn),
+    probe: async (setup: string, read: string) => {
+      const result: any = await invokeAction(config.region, fn, 'db:authz:probe', { setup, read });
+      if (result?.error) throw new Error(result.error);
+      return result?.rows ?? [];
+    },
+    label: flags.stage ? `stage ${flags.stage}` : 'deployed stage (.sst/outputs.json)',
+    end: async () => {},
+  };
+}
+
+async function introspectVenue(flags: Record<string, string>): Promise<{ contract: AuthzContract; label: string }> {
+  const venue = await resolveVenue(flags);
+  try {
+    step('Introspecting authorization (rls + grants + policies + secdef)...');
+    return { contract: await introspectContract(venue.runner, contractFunctionRow, FUNCTIONS_SQL), label: venue.label };
+  } finally {
+    await venue.end();
+  }
 }
 
 export async function dbAuthzPullCommand(flags: Record<string, string>): Promise<void> {
   const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
   let contract: AuthzContract;
+  let venueLabel: string;
   try {
-    contract = await introspectStage(flags);
+    ({ contract, label: venueLabel } = await introspectVenue(flags));
   } catch (err: any) {
     fail(err.message);
     for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
@@ -82,7 +139,7 @@ export async function dbAuthzPullCommand(flags: Record<string, string>): Promise
   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}`);
+  success(`Wrote ${files.length} file(s) to ${dir} (from ${venueLabel})`);
   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.');
@@ -97,9 +154,10 @@ export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise
 
   let declared: AuthzContract;
   let live: AuthzContract;
+  let venueLabel: string;
   try {
     declared = await loadContract(dir);
-    live = await introspectStage(flags);
+    ({ contract: live, label: venueLabel } = await introspectVenue(flags));
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
@@ -113,11 +171,11 @@ export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise
   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)`);
+    success(`db:authz:diff — ${venueLabel} 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`);
+  fail(`db:authz:diff — ${findings.length} drift finding(s): ${venueLabel} does NOT match the declared contract`);
   console.log('');
   for (const f of findings) {
     warn(`[${f.kind}] ${f.subject} — ${f.detail}`);
@@ -163,24 +221,23 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
 
   let rows: any[];
   let gapRows: any[];
+  let venueLabel: string;
+  let venue: AuthzVenue | undefined;
   try {
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    const fn = opsFunction(config);
-    info(`Region: ${config.region}, Function: ${fn}`);
+    venue = await resolveVenue(flags);
+    venueLabel = venue.label;
     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 ?? [];
+    rows = await venue.probe(setup, PROBE_SELECT_SQL);
     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 ?? [];
+    gapRows = await venue.runner(GRANT_COMPLETENESS_SQL);
   } 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.');
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe,');
+    info('or rehearse locally: db:authz:test --database-url <url>.');
     process.exit(1);
+  } finally {
+    await venue?.end();
   }
 
   const findings = evaluateRedTeam(contract, rows.map(toProbeResult));
@@ -200,10 +257,10 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   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)`);
+    success(`db:authz:test — ${venueLabel} enforces 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.`);
+  fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). ${venueLabel} does not enforce the contract.`);
   process.exit(1);
 }
 
@@ -223,6 +280,8 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
   let probes: OwnerProbe[];
   let publicReadTables = new Set<string>();
   let rows: any[];
+  let venueLabel = '';
+  let venue: AuthzVenue | undefined;
   try {
     step(`Loading models from ${modelsPath}...`);
     const models = await loadModels(modelsPath);
@@ -240,20 +299,17 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
       success('db:authz:owner — no owner-scoped models (no `can({ owner })`); nothing to probe.');
       process.exit(0);
     }
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    const fn = opsFunction(config);
-    info(`Region: ${config.region}, Function: ${fn}`);
+    venue = await resolveVenue(flags);
+    venueLabel = venue.label;
     step('Red-teaming owner isolation (two JWT identities per table, rolled back)...');
-    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', {
-      setup: buildOwnerProbeSql(probes), read: OWNER_PROBE_SELECT_SQL,
-    });
-    if (result?.error) throw new Error(result.error);
-    rows = result?.rows ?? [];
+    rows = await venue.probe(buildOwnerProbeSql(probes), OWNER_PROBE_SELECT_SQL);
   } catch (err: any) {
     fail(`db:authz:owner failed: ${err.message}`);
-    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe,');
+    info('or rehearse locally: db:authz:owner --database-url <url>.');
     process.exit(1);
+  } finally {
+    await venue?.end();
   }
 
   const findings = evaluateOwnerProbe(rows.map(toOwnerProbeResult), publicReadTables);
@@ -270,9 +326,9 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
   console.log('');
 
   if (leaks.length === 0 && vacuous.length === 0) {
-    success(`db:authz:owner — owner isolation holds (${probes.length} table(s) probed${unprobed.length ? `, ${unprobed.length} unprobed` : ''}).`);
+    success(`db:authz:owner — owner isolation holds on ${venueLabel} (${probes.length} table(s) probed${unprobed.length ? `, ${unprobed.length} unprobed` : ''}).`);
     process.exit(0);
   }
-  fail(`db:authz:owner — ${leaks.length} IDOR leak(s), ${vacuous.length} vacuous policy(ies). One user can reach another's rows.`);
+  fail(`db:authz:owner — ${leaks.length} IDOR leak(s), ${vacuous.length} vacuous policy(ies) on ${venueLabel}. One user can reach another's rows.`);
   process.exit(1);
 }