@everystack/cli 0.2.39 → 0.3.3

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.3",
   "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.3"
   },
   "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,364 @@
+/**
+ * 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)`;
+}
+
+/**
+ * The transitive-owner (`via:`) predicate, in deparser normal form — a parent
+ * subquery that scopes the child to rows whose FK points at a parent the caller
+ * owns. The exact whitespace (3 spaces before FROM, 2 before WHERE, the newlines)
+ * is what `pg_get_expr` emits and the contract stores, so it is reproduced byte
+ * for byte; the inner owner predicate reuses {@link ownerPredicate} (table-qualified):
+ *
+ *   (upload_id IN ( SELECT uploads.id
+ *      FROM uploads
+ *     WHERE (uploads.user_id = ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))))
+ */
+function viaPredicate(v: ViaRef): string {
+  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim);
+  return `(${v.fkColumn} IN ( SELECT ${v.parentTable}.${v.parentPk}\n   FROM ${v.parentTable}\n  WHERE ${parentOwner}))`;
+}
+
+// ---------------------------------------------------------------------------
+// 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 = resolveSchema(model, opts);
+  return { table: `${schema}.${model.table}`, ownerColumn: owner.sqlColumn, claim: owner.claim };
+}
+
+/**
+ * The schema a model's table lives in. The model's own `schema` wins (a 'dist'
+ * model is dist in any run), then the generate call's default, then 'public'.
+ */
+function resolveSchema(model: ModelDescriptor, opts: CompileOptions): string {
+  return model.schema ?? opts.schema ?? 'public';
+}
+
+/** 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',
+  };
+}
+
+interface ViaRef {
+  /** The child's FK column, snake_cased (e.g. `upload_id`). */
+  fkColumn: string;
+  /** The referenced parent table (e.g. `uploads`). */
+  parentTable: string;
+  /** The parent's primary-key column, snake_cased (e.g. `id`). */
+  parentPk: string;
+  /** The parent's resolved owner — the predicate scopes the subquery on this. */
+  parentOwner: OwnerRef;
+}
+
+/**
+ * Resolve the transitive-owner spec from the first `via:` ability. The named field
+ * must carry `.references()`; the compiler follows that thunk to the parent
+ * descriptor and resolves the parent's own `owner` ability. Throws a clear error
+ * when the field has no FK or the parent declares no owner — a `via:` that cannot
+ * reach an owner is a model bug, not a silently-empty policy.
+ */
+function resolveVia(model: ModelDescriptor): ViaRef | null {
+  const viaAbility = model.abilities.find((a) => a.condition.via);
+  if (!viaAbility) return null;
+  const fieldKey = viaAbility.condition.via!;
+  const ref = model.fields[fieldKey]?.spec.references;
+  if (!ref) {
+    throw new Error(`via: '${fieldKey}' on '${model.table}' must name a field declared with .references()`);
+  }
+  const parent = ref() as ModelDescriptor;
+  const parentOwner = resolveOwner(parent);
+  if (!parentOwner) {
+    throw new Error(`via: parent model '${parent.table}' (from '${model.table}.${fieldKey}') declares no owner ability`);
+  }
+  return {
+    fkColumn: toSnakeCase(fieldKey),
+    parentTable: parent.table,
+    parentPk: toSnakeCase(parent.primaryKey[0] ?? 'id'),
+    parentOwner,
+  };
+}
+
+/** 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;
+}
+
+/**
+ * A column-scoped self read — `can('read', { owner, columns })`. It compiles to a COLUMN
+ * grant (`GRANT SELECT (cols)`) plus a `<table>_select_self` policy, NOT a table grant and
+ * NOT a `_select_own` policy: the row is scoped by the owner predicate, the fields by the
+ * column list (`auth.users` → id/email/role to the owner, never the password hash). It is
+ * excluded from the table-grant and owner-read paths so the two never double-emit.
+ */
+function isColumnRead(a: Ability): boolean {
+  return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
+}
+
+/**
+ * Column grants from the column-scoped read abilities: the read role (`authenticated`, since
+ * the ability is owner-scoped, not role-gated) gets `SELECT (cols)`. Field keys are snake_cased
+ * to SQL columns and sorted, matching the introspected contract. Returns undefined when no
+ * ability declares columns — an introspected contract omits the key rather than carry an empty
+ * object, so the compiled one must too (or the round-trip diff would false-fire).
+ */
+function compileColumnGrants(abilities: readonly Ability[]): Record<string, Record<string, string[]>> | undefined {
+  const out: Record<string, Record<string, string[]>> = {};
+  for (const a of abilities) {
+    if (!isColumnRead(a)) continue;
+    const role = a.condition.role ?? 'authenticated';
+    const cols = [...a.condition.columns!].map(toSnakeCase).sort();
+    (out[role] ??= {}).SELECT = cols;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 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 = resolveSchema(model, opts);
+  const table = `${schema}.${model.table}`;
+  const owner = resolveOwner(model);
+  const via = resolveVia(model);
+  const sdCol = softDeleteColumn(model);
+  // The row-scoping predicate: a direct owner column, else a transitive `via:`
+  // parent subquery. Both drive the same owner-gated policies (select/insert/
+  // update/delete_own); only the predicate text differs.
+  const rowPred = owner
+    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim)
+    : via
+      ? viaPredicate(via)
+      : null;
+  const sdGuard = sdCol ? softDeleteGuard(sdCol) : null;
+
+  // A "row-scoped" condition is either a direct owner or a transitive via.
+  const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
+
+  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 && !rowScoped(a));
+  // A column-scoped read is row-scoped but emits a self policy + column grant, not the
+  // full-row owner read — so it is excluded here and handled by its own branch.
+  const hasOwnerRead = abilities.some((a) => a.action === 'read' && rowScoped(a) && !isColumnRead(a));
+  const hasColumnRead = abilities.some(isColumnRead);
+  const canCreate = abilities.some((a) => a.action === 'create');
+  const hasUpdateOwner = abilities.some((a) => a.action === 'update' && rowScoped(a));
+  const hasDeleteOwner = abilities.some((a) => a.action === 'delete' && rowScoped(a));
+
+  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 && rowPred) authedUsing = `(${sdGuard} OR ${rowPred})`;
+    else if (rowPred && !sdGuard) authedUsing = rowPred;
+    policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
+  } else if (hasOwnerRead && rowPred) {
+    // owner-scoped read — no anon visibility; you see only the rows you own
+    // (directly, or transitively through a `via:` parent).
+    policy(`${t}_select_own`, 'SELECT', ['authenticated'], rowPred, null);
+  } else if (hasColumnRead && rowPred) {
+    // column-scoped self read — `authenticated` reads only its OWN row, and only the
+    // granted columns (the GRANT scopes fields; this policy scopes rows). Named
+    // `_select_self`, distinct from the full-row `_select_own`.
+    policy(`${t}_select_self`, 'SELECT', ['authenticated'], rowPred, null);
+  }
+
+  // owner-gated writes. INSERT checks ownership (you can only create rows you own);
+  // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
+  if (rowPred) {
+    if (canCreate) policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, rowPred);
+    if (hasUpdateOwner) policy(`${t}_update_own`, 'UPDATE', ['authenticated'], rowPred, rowPred);
+    if (hasDeleteOwner) policy(`${t}_delete_own`, 'DELETE', ['authenticated'], rowPred, null);
+  }
+
+  policies.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    table,
+    // The FORCE axiom: FORCE iff the write principal is subject to its own RLS
+    // policies. 'app' writes through its policies -> FORCE; 'worker'/'functions'
+    // write on the owner connection and bypass RLS -> ENABLE-not-FORCE (on RDS the
+    // owner is not a superuser, so a FORCEd table would block the owner's own writes).
+    rls: { enabled: true, forced: model.writtenBy === 'app' },
+    grants: compileGrants(abilities),
+    ...(compileColumnGrants(abilities) ? { columnGrants: compileColumnGrants(abilities) } : {}),
+    policies,
+  };
+}
+
+/** The four DML privileges, sorted — the expansion of a `manage` ability. */
+const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/** The SQL privilege a single CRUD verb grants. `manage` expands to all of CRUD. */
+const VERB: Record<Exclude<Ability['action'], 'manage'>, string> = {
+  read: 'SELECT',
+  create: 'INSERT',
+  update: 'UPDATE',
+  delete: 'DELETE',
+};
+
+/** The privileges an ability's action grants (a single verb, or all of CRUD for `manage`). */
+function verbsFor(action: Ability['action']): string[] {
+  return action === 'manage' ? [...CRUD] : [VERB[action]];
+}
+
+/**
+ * Precise grants — derive each role's privilege set from the abilities, not a
+ * uniform tier. everystack's model is coarse grants + fine-grained RLS: the grant
+ * is the gate (which roles may touch the table at all), RLS restricts which rows.
+ * A role gets a privilege iff some ability grants that verb to it:
+ *
+ *   - `can(action, { role })`            -> that role gets the verb(s)
+ *   - public/owner/via ability (no role) -> `authenticated` gets the verb(s)
+ *   - a *public* read (no role, no owner/via) -> `anon` also gets SELECT
+ *
+ * No ability for a role means no grant for that role: an ability-less (internal)
+ * table grants nothing, an owner-only table grants no anon SELECT, an admin-managed
+ * table grants admin CRUD only. Deterministic: roles and privilege lists sorted,
+ * so the output is byte-comparable with an introspected contract.
+ */
+function compileGrants(abilities: readonly Ability[]): Record<string, string[]> {
+  const grants: Record<string, Set<string>> = {};
+  const add = (role: string, verbs: string[]): void => {
+    const set = (grants[role] ??= new Set<string>());
+    for (const v of verbs) set.add(v);
+  };
+  for (const a of abilities) {
+    // A column-scoped read grants `SELECT (cols)` (a column grant), not a table-level
+    // privilege — emitted by compileColumnGrants, skipped here so it never leaks a
+    // whole-table grant that would defeat the column scoping.
+    if (isColumnRead(a)) continue;
+    const verbs = verbsFor(a.action);
+    if (a.condition.role) {
+      add(a.condition.role, verbs);
+    } else {
+      add('authenticated', verbs);
+      // A public read (no role, not owner/via-scoped) is anon-visible.
+      if (a.action === 'read' && !a.condition.owner && !a.condition.via) add('anon', ['SELECT']);
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
+  return out;
+}
+
+// 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'));
+}