@everystack/cli 0.2.39 → 0.3.0

package/README.md

@@ -168,17 +168,40 @@ everystack channels create --name staging
 everystack channels create --name production
 ```
 
+### Deploy
+
+```bash
+everystack deploy --stage dev           # provision infrastructure (wraps `sst deploy`)
+```
+
+A thin wrapper over SST so you never type `sst` directly. Infrastructure only — migrations and bundle publishing stay explicit (`db:migrate`, `update`).
+
 ### Database Management
 
-These commands invoke your Lambda function directly via IAM (no database credentials exposed):
+These commands invoke your Lambda directly via IAM (no database credentials ever leave AWS):
 
 ```bash
-everystack db:migrate                   # Run Drizzle migrations
-everystack db:seed                      # Seed database (dev only)
-everystack db:psql --stage dev          # Open a psql session via Lambda
+# Migrations
+everystack db:migrate                   # apply Drizzle migrations
+everystack db:seed                      # seed (dev only)
+everystack db:psql --stage dev [-c SQL] # interactive psql / one-off query via Lambda
+
+# Model-driven schema (@everystack/model)
+everystack db:generate                  # diff Models vs the live DB → next migration
+everystack db:pull                      # introspect a live DB → field() Models (brownfield on-ramp)
+
+# Security
+everystack db:doctor                    # is the DB least-privilege + RLS-subject?
+everystack db:provision                 # create the least-privilege role chain (idempotent)
+everystack db:authz:pull|diff|test|owner|report   # the authorization contract + red-team
+
+# Backups (see docs/backups.md)
+everystack db:backup | db:backups | db:restore --from <id> --confirm   # logical pg_dump → S3
+everystack db:backup:download <id>      # presigned URL to a dump (1h)
+everystack db:snapshot | db:snapshots   # physical RDS snapshots
 ```
 
-`db:migrate` and `db:seed` dispatch to your Lambda's `onAction` handler. `db:psql` proxies a PostgreSQL session through the Lambda, so your database credentials never leave AWS.
+The full command reference — including `secrets`, `logs:*`, `status`, `cache:purge`, `branches`, and every flag — is in [docs/cli.md](../../docs/cli.md).
 
 ### Interactive Console
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.2.39",
+  "version": "0.3.0",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -25,6 +25,10 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./model": {
+      "types": "./src/cli/model-api.ts",
+      "default": "./src/cli/model-api.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
@@ -60,13 +64,15 @@
     "glob": "13.0.6",
     "node-forge": "1.4.0",
     "structured-headers": "1.0.1",
-    "tsx": "4.21.0"
+    "tsx": "4.21.0",
+    "@everystack/model": "0.3.0"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",
     "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
     "@aws-sdk/client-lambda": "3.1053.0",
+    "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",
@@ -91,6 +97,9 @@
     "@aws-sdk/client-lambda": {
       "optional": true
     },
+    "@aws-sdk/client-rds": {
+      "optional": true
+    },
     "@aws-sdk/client-ssm": {
       "optional": true
     },
@@ -111,6 +120,7 @@
     "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
     "@aws-sdk/client-lambda": "3.1053.0",
+    "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",

package/src/cli/authz-compile.ts

@@ -0,0 +1,212 @@
+/**
+ * The Model -> Authorization Contract compiler (the second producer).
+ *
+ * Introspection (authz-contract.ts) reads the live database INTO a contract. This
+ * compiles a `defineModel` declaration the other way: `abilities` OUT to the same
+ * contract shape, so the two meet at `diffContracts` — declared (Model) vs live
+ * (DB). That is the whole leverage of the v3 Model: it is mostly a new producer of
+ * an existing format, and `db:authz:reconcile` is the diff turned back into SQL.
+ *
+ * The make-or-break constraint (proven against apps/example/authz): `diffContracts`
+ * compares predicate text VERBATIM, and the contract stores the Postgres deparser
+ * (`pg_get_expr`) normal form — which differs from hand-written source SQL (it adds
+ * outer parens, an explicit `::text` cast on the claims key, spaces around `->>`,
+ * and a `'sub'::text` cast). So the compiler emits that exact normal form, by
+ * template, for the shapes that make up ~96% of a real app: owner (uuid or text),
+ * soft-delete guard, admin-bypass, the soft-delete-OR-owner read, and the
+ * owner-only read. The cross-table `via:` parent subquery and `rawPolicy` escape
+ * hatch are the tail — emitted verbatim, round-trip only after a live deparse.
+ *
+ * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
+ */
+
+import type { ModelDescriptor, Ability } from '@everystack/model';
+import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
+
+export interface CompileOptions {
+  /** Schema the table lives in. Default: `public`. */
+  schema?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Predicate templates — the deparser normal form, parameterized.
+// ---------------------------------------------------------------------------
+
+/** `authorId` -> `author_id`. The contract predicates use SQL column names. */
+function toSnakeCase(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+/**
+ * The Postgres cast a JWT-claim string is coerced to for a non-text owner column.
+ * The claim arrives as text (`->> 'sub'`); a uuid/bigint owner needs the cast, a
+ * text owner does not (see ownerPredicate). Mapped for completeness; only uuid and
+ * text are exercised by the example.
+ */
+function castForType(type: string): string {
+  switch (type) {
+    case 'uuid': return 'uuid';
+    case 'bigint':
+    case 'bigserial': return 'bigint';
+    case 'integer': return 'integer';
+    default: return type;
+  }
+}
+
+/** The signed-in user's id from the JWT claims, in deparser normal form. */
+function claimExpr(claim: string): string {
+  return `((current_setting('request.jwt.claims'::text, true))::jsonb ->> '${claim}'::text)`;
+}
+
+/**
+ * The owner predicate, in deparser normal form. The shape depends on the owner
+ * column's type, because the deparser drops a redundant cast:
+ *   uuid: (author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))::uuid)
+ *   text: (user_id   =  ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))
+ */
+function ownerPredicate(sqlColumn: string, type: string, claim: string): string {
+  const ce = claimExpr(claim);
+  if (type === 'text') return `(${sqlColumn} = ${ce})`;
+  return `(${sqlColumn} = (${ce})::${castForType(type)})`;
+}
+
+/** The soft-delete guard, in deparser normal form: `(deleted_at IS NULL)`. */
+function softDeleteGuard(sqlColumn: string): string {
+  return `(${sqlColumn} IS NULL)`;
+}
+
+// ---------------------------------------------------------------------------
+// Ability classification.
+// ---------------------------------------------------------------------------
+
+interface OwnerRef {
+  sqlColumn: string;
+  /** The field's Postgres type — drives the cast in ownerPredicate. */
+  type: string;
+  /** JWT claim holding the owner id. */
+  claim: string;
+}
+
+/**
+ * The owner-scoped probe spec a model declares — its schema-qualified table, owner SQL column,
+ * and JWT claim — or null when the model has no owner ability. This is what drives the
+ * owner-aware red-team (`db:authz:owner`): the Model already names the owner via `can({ owner })`,
+ * so isolation testing needs no extra declaration.
+ */
+export function modelOwner(model: ModelDescriptor, opts: CompileOptions = {}): { table: string; ownerColumn: string; claim: string } | null {
+  const owner = resolveOwner(model);
+  if (!owner) return null;
+  const schema = opts.schema ?? 'public';
+  return { table: `${schema}.${model.table}`, ownerColumn: owner.sqlColumn, claim: owner.claim };
+}
+
+/** Resolve the owner column (SQL name + type + claim) from the first owner ability. */
+function resolveOwner(model: ModelDescriptor): OwnerRef | null {
+  const ownerAbility = model.abilities.find((a) => a.condition.owner);
+  if (!ownerAbility) return null;
+  const fieldKey = ownerAbility.condition.owner!;
+  return {
+    sqlColumn: toSnakeCase(fieldKey),
+    type: model.fields[fieldKey]?.spec.type ?? 'uuid',
+    claim: ownerAbility.condition.userField ?? 'sub',
+  };
+}
+
+/** The conventional soft-delete column SQL name, when the model has one. */
+function softDeleteColumn(model: ModelDescriptor): string | null {
+  return 'deletedAt' in model.fields ? 'deleted_at' : null;
+}
+
+// ---------------------------------------------------------------------------
+// Compile.
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile one model's `abilities` into its TableContract (rls + grants + policies).
+ * Deterministic: policies sorted by name, grant privilege lists sorted — so the
+ * output is byte-comparable with an introspected contract.
+ */
+export function compileTableContract(model: ModelDescriptor, opts: CompileOptions = {}): TableContract {
+  const schema = opts.schema ?? 'public';
+  const table = `${schema}.${model.table}`;
+  const owner = resolveOwner(model);
+  const sdCol = softDeleteColumn(model);
+  const ownerPred = owner ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim) : null;
+  const sdGuard = sdCol ? softDeleteGuard(sdCol) : null;
+
+  const abilities = model.abilities;
+  const hasAdminManage = abilities.some((a) => a.action === 'manage' && a.condition.role === 'admin');
+  const hasPublicRead = abilities.some((a) => a.action === 'read' && !a.condition.role && !a.condition.owner);
+  const hasOwnerRead = abilities.some((a) => a.action === 'read' && a.condition.owner);
+  const canCreate = abilities.some((a) => a.action === 'create');
+  const hasUpdateOwner = abilities.some((a) => a.action === 'update' && a.condition.owner);
+  const hasDeleteOwner = abilities.some((a) => a.action === 'delete' && a.condition.owner);
+
+  const t = model.table;
+  const policies: PolicyContract[] = [];
+  const policy = (
+    name: string, command: PolicyCommand, roles: string[],
+    using: string | null, check: string | null,
+  ): void => {
+    policies.push({ name, command, roles, permissive: true, using, check });
+  };
+
+  // admin-bypass — one ALL policy, true/true.
+  if (hasAdminManage) policy(`${t}_admin`, 'ALL', ['admin'], 'true', 'true');
+
+  if (hasPublicRead) {
+    // public read on a soft-delete table — split per role; authenticated owners
+    // also see their own (soft-deleted) rows, hence the OR'd owner check.
+    const anonUsing = sdGuard ?? 'true';
+    policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
+
+    let authedUsing = anonUsing;
+    if (sdGuard && ownerPred) authedUsing = `(${sdGuard} OR ${ownerPred})`;
+    else if (ownerPred && !sdGuard) authedUsing = ownerPred;
+    policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
+  } else if (hasOwnerRead && ownerPred) {
+    // owner-only read — no anon visibility; you see only your own rows.
+    policy(`${t}_select_own`, 'SELECT', ['authenticated'], ownerPred, null);
+  }
+
+  // owner-gated writes. INSERT checks ownership (you can only create rows you own);
+  // UPDATE gates + checks; DELETE gates.
+  if (ownerPred) {
+    if (canCreate) policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, ownerPred);
+    if (hasUpdateOwner) policy(`${t}_update_own`, 'UPDATE', ['authenticated'], ownerPred, ownerPred);
+    if (hasDeleteOwner) policy(`${t}_delete_own`, 'DELETE', ['authenticated'], ownerPred, null);
+  }
+
+  policies.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    table,
+    rls: { enabled: true, forced: true },
+    grants: compileGrants(hasAdminManage),
+    policies,
+  };
+}
+
+/**
+ * The grant tier for a public app table. everystack's model is coarse grants +
+ * fine-grained RLS: anon may read, authenticated may CRUD, admin may CRUD — and
+ * RLS (the policies above) is what actually restricts which rows. So the grants
+ * are uniform across app tables, not derived per-ability (profiles has no create
+ * ability yet is granted INSERT; uploads is owner-only yet grants anon SELECT).
+ *
+ * A precise, least-exposure grant set (drop the anon SELECT on an owner-only
+ * table) is a deliberate future refinement — it would tighten the live DB, which
+ * the diff would surface and reconcile would apply. Today this reproduces the
+ * deployed grants so the contract round-trips.
+ */
+function compileGrants(hasAdminManage: boolean): Record<string, string[]> {
+  const crud = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+  return {
+    anon: ['SELECT'],
+    authenticated: [...crud],
+    ...(hasAdminManage ? { admin: [...crud] } : {}),
+  };
+}
+
+// Kept exported for callers that want just the privilege set for a role tier.
+export type { Ability };

package/src/cli/authz-contract-io.ts

@@ -0,0 +1,92 @@
+/**
+ * Filesystem IO for the Authorization Contract — write/load the per-table files.
+ *
+ * Kept out of authz-contract.ts so the core (introspect/assemble/diff) stays pure and
+ * fs-free. The serialized form is deterministic and byte-stable: a re-pull of an
+ * unchanged database produces identical files, so a contract change is always a real,
+ * reviewable git diff and never reformatting noise.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AuthzContract, TableContract, FunctionContract } from './authz-contract.js';
+import { renderContractMarkdown } from './authz-render.js';
+
+/** The human-readable review doc written alongside the JSON. */
+export const REVIEW_FILE = 'AUTHORIZATION.md';
+
+/** Stable JSON: object keys sorted recursively, 2-space indent, trailing newline. */
+export function stableStringify(value: unknown): string {
+  const sortKeys = (v: any): any => {
+    if (Array.isArray(v)) return v.map(sortKeys);
+    if (v && typeof v === 'object') {
+      return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]));
+    }
+    return v;
+  };
+  return JSON.stringify(sortKeys(value), null, 2) + '\n';
+}
+
+/** `public.posts` -> `public.posts.contract.json`. */
+export function tableFileName(table: string): string {
+  return `${table}.contract.json`;
+}
+
+export const FUNCTIONS_FILE = '_functions.contract.json';
+
+/**
+ * Write the contract as one file per table plus `_functions.contract.json`. Prunes any
+ * stale `*.contract.json` for a table no longer in the contract, so a dropped table
+ * leaves no orphan file. The directory is created if absent.
+ */
+export async function writeContract(dir: string, contract: AuthzContract): Promise<string[]> {
+  await fs.mkdir(dir, { recursive: true });
+
+  const written = new Set<string>();
+  for (const table of contract.tables) {
+    const file = tableFileName(table.table);
+    await fs.writeFile(path.join(dir, file), stableStringify(table), 'utf8');
+    written.add(file);
+  }
+  await fs.writeFile(path.join(dir, FUNCTIONS_FILE), stableStringify({ functions: contract.functions }), 'utf8');
+  written.add(FUNCTIONS_FILE);
+
+  for (const existing of await listContractFiles(dir)) {
+    if (!written.has(existing)) await fs.rm(path.join(dir, existing));
+  }
+
+  // The human-readable review doc, regenerated from the same contract so it can't drift.
+  await fs.writeFile(path.join(dir, REVIEW_FILE), renderContractMarkdown(contract), 'utf8');
+  written.add(REVIEW_FILE);
+  return [...written].sort();
+}
+
+/** Load the per-table files back into a contract. Missing dir -> empty contract. */
+export async function loadContract(dir: string): Promise<AuthzContract> {
+  let files: string[];
+  try {
+    files = await listContractFiles(dir);
+  } catch {
+    return { tables: [], functions: [] };
+  }
+
+  const tables: TableContract[] = [];
+  let functions: FunctionContract[] = [];
+  for (const file of files) {
+    const raw = await fs.readFile(path.join(dir, file), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (file === FUNCTIONS_FILE) {
+      functions = parsed.functions ?? [];
+    } else {
+      tables.push(parsed as TableContract);
+    }
+  }
+  tables.sort((a, b) => a.table.localeCompare(b.table));
+  functions.sort((a, b) => a.name.localeCompare(b.name));
+  return { tables, functions };
+}
+
+async function listContractFiles(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir);
+  return entries.filter((f) => f.endsWith('.contract.json'));
+}