@everystack/cli 0.3.0 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -29,6 +29,10 @@
       "types": "./src/cli/model-api.ts",
       "default": "./src/cli/model-api.ts"
     },
+    "./audit": {
+      "types": "./src/cli/audit-api.ts",
+      "default": "./src/cli/audit-api.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
@@ -65,7 +69,7 @@
     "node-forge": "1.4.0",
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
-    "@everystack/model": "0.3.0"
+    "@everystack/model": "0.3.3"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/audit-api.ts

@@ -0,0 +1,54 @@
+/**
+ * Public audit surface — `@everystack/cli/audit`.
+ *
+ * The governance MCP imports these pure scanners directly to gate authoring and
+ * pre-deploy: the secret-leak checks (bundle-audit) and the weight/size checks
+ * (bundle-weight), plus the bundle composition helpers they build on. Pure,
+ * filesystem-free, no CLI/IO coupling — feed them text or {path, size} lists.
+ */
+
+export {
+  // types
+  type AuditFinding,
+  type SecretPattern,
+  // leak scanners
+  SECRET_PATTERNS,
+  redact,
+  isPublicEnvKey,
+  scanSecretShapes,
+  extractBundleUrls,
+  extractExtraEnvKeys,
+  classifyPrivateEnvKeys,
+  scanSecretValue,
+  summarize,
+} from './bundle-audit.js';
+
+export {
+  // types
+  type AssetFile,
+  type AssetKind,
+  type WeightBudget,
+  // weight scanners
+  DEFAULT_WEIGHT_BUDGET,
+  classifyAsset,
+  formatBytes,
+  scanAssetWeights,
+  scanTotalWeight,
+  scanJsWeight,
+  scanSourceMapsPresent,
+  scanDependencyWeight,
+  resolveWeightBudget,
+} from './bundle-weight.js';
+
+export {
+  // composition (input to scanDependencyWeight)
+  type Composition,
+  type ChunkInput,
+  type ChunkSize,
+  type SourceMap,
+  measureChunk,
+  measureChunks,
+  totalSizes,
+  bucketSource,
+  composeSourceMap,
+} from './bundle.js';

package/src/cli/authz-compile.ts

@@ -75,6 +75,22 @@ 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.
 // ---------------------------------------------------------------------------
@@ -96,10 +112,18 @@ interface OwnerRef {
 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';
+  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);
@@ -112,11 +136,79 @@ function resolveOwner(model: ModelDescriptor): OwnerRef | null {
   };
 }
 
+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.
 // ---------------------------------------------------------------------------
@@ -127,20 +219,34 @@ function softDeleteColumn(model: ModelDescriptor): string | null {
  * output is byte-comparable with an introspected contract.
  */
 export function compileTableContract(model: ModelDescriptor, opts: CompileOptions = {}): TableContract {
-  const schema = opts.schema ?? 'public';
+  const schema = resolveSchema(model, opts);
   const table = `${schema}.${model.table}`;
   const owner = resolveOwner(model);
+  const via = resolveVia(model);
   const sdCol = softDeleteColumn(model);
-  const ownerPred = owner ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim) : null;
+  // 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 && !a.condition.owner);
-  const hasOwnerRead = abilities.some((a) => a.action === 'read' && a.condition.owner);
+  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' && a.condition.owner);
-  const hasDeleteOwner = abilities.some((a) => a.action === 'delete' && a.condition.owner);
+  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[] = [];
@@ -161,51 +267,97 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
 
     let authedUsing = anonUsing;
-    if (sdGuard && ownerPred) authedUsing = `(${sdGuard} OR ${ownerPred})`;
-    else if (ownerPred && !sdGuard) authedUsing = ownerPred;
+    if (sdGuard && rowPred) authedUsing = `(${sdGuard} OR ${rowPred})`;
+    else if (rowPred && !sdGuard) authedUsing = rowPred;
     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);
+  } 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.
-  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);
+  // 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,
-    rls: { enabled: true, forced: true },
-    grants: compileGrants(hasAdminManage),
+    // 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]];
+}
+
 /**
- * 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).
+ * 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
  *
- * 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.
+ * 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(hasAdminManage: boolean): Record<string, string[]> {
-  const crud = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
-  return {
-    anon: ['SELECT'],
-    authenticated: [...crud],
-    ...(hasAdminManage ? { admin: [...crud] } : {}),
+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.

package/src/cli/authz-owner-probe.ts

@@ -34,6 +34,13 @@ export interface OwnerProbe {
   claim?: string;
   /** App role to assume. Default `authenticated`. */
   role?: string;
+  /**
+   * The table has an intended PUBLIC read (a `can('read')` with no owner/role/via — anon /
+   * authenticated may SELECT every row). Reader isolation is then NOT expected (a Twitter-clone's
+   * posts/profiles/likes/follows are public), so a visible other-owner row is by design, not an
+   * IDOR. Writer isolation is still enforced — the rows are owner-WRITE even when public-read.
+   */
+  publicRead?: boolean;
 }
 
 export type OwnerCheck = 'discover' | 'read-own' | 'read-other' | 'write-other';
@@ -49,7 +56,7 @@ export interface OwnerProbeResult {
 }
 
 export interface OwnerFinding {
-  severity: 'read-leak' | 'write-leak' | 'vacuous' | 'unprobed';
+  severity: 'read-leak' | 'write-leak' | 'vacuous' | 'unprobed' | 'public-read';
   table: string;
   detail: string;
 }
@@ -164,8 +171,12 @@ export function toOwnerProbeResult(row: any): OwnerProbeResult {
  *   - unprobed   — fewer than two distinct owners in the table; isolation can't be tested (a
  *                  warning, not a verdict — seed a second owner's row, or accept the gap).
  * A correctly-isolated table with two owners produces zero findings.
+ *
+ * `publicReadTables` names tables with an intended public read: their reader-isolation check is
+ * informational (`public-read`), not a leak — but writer isolation is still enforced, so a
+ * write-leak on a public-read table is still a failure.
  */
-export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[] {
+export function evaluateOwnerProbe(results: OwnerProbeResult[], publicReadTables: Set<string> = new Set()): OwnerFinding[] {
   const findings: OwnerFinding[] = [];
   const byTable = new Map<string, Map<OwnerCheck, OwnerProbeResult>>();
   for (const r of results) {
@@ -181,6 +192,7 @@ export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[]
     const own = checks.get('read-own');
     const other = checks.get('read-other');
     const write = checks.get('write-other');
+    const publicRead = publicReadTables.has(table);
 
     if (own && own.outcome !== 'visible') {
       findings.push({ severity: 'vacuous', table,
@@ -188,8 +200,14 @@ export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[]
       continue; // the other checks are meaningless while the owner can't see own rows
     }
     if (other && other.outcome === 'visible') {
-      findings.push({ severity: 'read-leak', table,
-        detail: `as the owner, ${other.rows} of another user's row(s) in ${table} were visible — RLS does not isolate readers (IDOR read)` });
+      // A public-read table is SUPPOSED to expose every row — that is not an IDOR. Report it as
+      // informational so the operator sees it was recognized, not a leak. Owner-private tables
+      // (no public read) still fail here.
+      findings.push(publicRead
+        ? { severity: 'public-read', table,
+            detail: `${table} has an intended public read — reader isolation not applicable (the ${other.rows} other-owner row(s) are public by design); writer isolation still enforced` }
+        : { severity: 'read-leak', table,
+            detail: `as the owner, ${other.rows} of another user's row(s) in ${table} were visible — RLS does not isolate readers (IDOR read)` });
     }
     if (write && write.outcome === 'visible') {
       findings.push({ severity: 'write-leak', table,

package/src/cli/authz-reconcile.ts

@@ -84,6 +84,7 @@ export function emitReconcileSql(declared: AuthzContract, live: AuthzContract):
     reconcileRls(table, d, l, sql);
     reconcilePolicies(table, d, l, sql);
     reconcileGrants(table, d, l, sql);
+    reconcileColumnGrants(table, d, l, sql);
   }
 
   return sql;
@@ -125,3 +126,27 @@ function reconcileGrants(table: string, d: TableContract, l: TableContract | und
     if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON ${table} TO ${target};`);
   }
 }
+
+/**
+ * Reconcile column-scoped grants — `GRANT SELECT (cols) ON t TO role`. The grantee/privilege
+ * grid is reconciled per (grantee, privilege): add the columns declared-but-not-live, revoke
+ * those live-but-not-declared. This is how `auth.users` exposes id/email/role (and only those)
+ * to `authenticated` without a whole-table grant. Columns are sorted, so a re-pull is a no-op.
+ */
+function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+  const dcg = d.columnGrants ?? {};
+  const lcg = l?.columnGrants ?? {};
+  for (const grantee of [...new Set([...Object.keys(dcg), ...Object.keys(lcg)])].sort()) {
+    const target = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
+    const dPriv = dcg[grantee] ?? {};
+    const lPriv = lcg[grantee] ?? {};
+    for (const priv of [...new Set([...Object.keys(dPriv), ...Object.keys(lPriv)])].sort()) {
+      const declared = new Set(dPriv[priv] ?? []);
+      const live = new Set(lPriv[priv] ?? []);
+      const toRevoke = [...live].filter((c) => !declared.has(c)).sort();
+      const toGrant = [...declared].filter((c) => !live.has(c)).sort();
+      if (toRevoke.length) out.push(`REVOKE ${priv} (${toRevoke.join(', ')}) ON ${table} FROM ${target};`);
+      if (toGrant.length) out.push(`GRANT ${priv} (${toGrant.join(', ')}) ON ${table} TO ${target};`);
+    }
+  }
+}

package/src/cli/bundle-audit.ts

@@ -0,0 +1,185 @@
+/**
+ * Bundle secret-leak audit — pure scanners for `everystack bundle:audit`.
+ *
+ * Scans the *served* client bundle for leaked secrets. Config-free by leaning on
+ * universal truths instead of a hand-maintained deny-list:
+ *
+ *   1. Generic secret SHAPES (Postgres/Mongo/Redis URLs, sk_live_, AKIA…, PEM
+ *      blocks) — these match a secret's *value* regardless of its key name.
+ *   2. The Expo convention: Metro only inlines `EXPO_PUBLIC_*` env vars into the
+ *      client bundle. Any *other* env key serialized into the bundle is, by
+ *      definition, a private value that leaked.
+ *   3. (Operator-run) value canary: grep the bundle for the literal values of the
+ *      deployed secrets — the only way to catch a Metro-inlined value whose key
+ *      name never appears. Values are redacted in output; never printed.
+ *
+ * Nothing here reads secret values; the canary matcher receives them from the
+ * command's operator-run path.
+ */
+
+export interface AuditFinding {
+  severity: 'fail' | 'warn';
+  check:
+    // leak checks (this file)
+    | 'secret-shape'
+    | 'source-map'
+    | 'private-env-key'
+    | 'secret-value'
+    // weight/size checks (bundle-weight.ts)
+    | 'asset-weight'
+    | 'total-weight'
+    | 'data-in-bundle'
+    | 'js-weight'
+    | 'dep-weight';
+  source: string;
+  detail: string;
+}
+
+export interface SecretPattern {
+  name: string;
+  re: RegExp;
+}
+
+/** Generic, app-agnostic secret shapes. A value matching any of these in a
+ *  client bundle is a leak no matter what env key carried it. */
+export const SECRET_PATTERNS: SecretPattern[] = [
+  { name: 'postgres-url-with-credentials', re: /postgres(?:ql)?:\/\/[^:\s'"`]+:[^@\s'"`]+@/ },
+  { name: 'mongodb-url-with-credentials', re: /mongodb(?:\+srv)?:\/\/[^:\s'"`]+:[^@\s'"`]+@/ },
+  { name: 'redis-url-with-credentials', re: /redis:\/\/[^:\s'"`]*:[^@\s'"`]+@/ },
+  { name: 'stripe-secret-key', re: /sk_(?:live|test)_[A-Za-z0-9]{10,}/ },
+  { name: 'mapbox-secret-token', re: /sk\.[A-Za-z0-9_-]{60,}/ },
+  { name: 'sendgrid-key', re: /SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/ },
+  { name: 'google-api-key', re: /AIza[0-9A-Za-z_-]{35}/ },
+  { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+  { name: 'slack-token', re: /xox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { name: 'aws-access-key-id', re: /AKIA[0-9A-Z]{16}/ },
+  { name: 'pem-private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+  { name: 'generic-credentials-in-url', re: /\b[a-z][a-z0-9+.-]*:\/\/[A-Za-z0-9._%-]+:[^@\s'"`/]{6,}@/ },
+];
+
+/** Mask a matched secret so the output never prints it in full. */
+export function redact(s: string): string {
+  if (s.length <= 6) return '******';
+  return `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`;
+}
+
+/** True if an env key is client-public by Expo convention (Metro-inlined). */
+export function isPublicEnvKey(key: string): boolean {
+  return key.startsWith('EXPO_PUBLIC_');
+}
+
+/** Scan one artifact's text for generic secret shapes. Matches are redacted. */
+export function scanSecretShapes(text: string, source: string): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  const seen = new Set<string>(); // dedupe overlapping patterns on the same span
+  for (const { name, re } of SECRET_PATTERNS) {
+    const m = re.exec(text);
+    if (m && !seen.has(m[0])) {
+      seen.add(m[0]);
+      findings.push({
+        severity: 'fail',
+        check: 'secret-shape',
+        source,
+        detail: `${name}: ${redact(m[0])}`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Extract client JS bundle URLs from served HTML (Expo web export convention). */
+export function extractBundleUrls(html: string): string[] {
+  const urls = new Set<string>();
+  const re = /["'(]([^"'()]*_expo\/static\/js\/web\/[^"'()?]+\.js)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) !== null) {
+    urls.add(m[1].replace(/^\.?\//, ''));
+  }
+  return [...urls];
+}
+
+/**
+ * Extract served *static asset* references (images, data files, fonts, css)
+ * from a bundle/HTML — anything under `assets/` or `_expo/static/` that is not
+ * JS or a source map (those are crawled / gated separately). Used by the remote
+ * weight scan to discover what to HEAD for its size without downloading it.
+ */
+export function extractAssetUrls(text: string): string[] {
+  const urls = new Set<string>();
+  const re = /["'(]((?:\.?\/)?(?:assets|_expo\/static)\/[^"'()\s]+?\.[A-Za-z0-9]+)(?:\?[^"'()\s]*)?["')]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const rel = m[1].replace(/^\.?\//, '');
+    if (/\.(?:js|mjs|cjs|map)$/i.test(rel)) continue;
+    urls.add(rel);
+  }
+  return [...urls];
+}
+
+const EXTRA_KEY_SKIP = new Set([
+  'JSON', 'URL', 'GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS', 'PATCH',
+  'API', 'HTTP', 'HTTPS', 'UTF', 'UUID', 'ID', 'OK', 'EAS',
+]);
+
+/**
+ * Best-effort extraction of ALL-CAPS env-looking keys serialized near an
+ * `"extra"` region of the bundle (where Expo embeds app.config `extra`). No EAS
+ * projectId anchor needed — we scan a window around each `"extra"` occurrence.
+ */
+export function extractExtraEnvKeys(text: string, window = 600): string[] {
+  const keys = new Set<string>();
+  const keyRe = /["']([A-Z][A-Z0-9_]{2,})["']\s*:/g;
+  let idx = text.indexOf('"extra"');
+  while (idx !== -1) {
+    const region = text.slice(idx, idx + window);
+    let m: RegExpExecArray | null;
+    keyRe.lastIndex = 0;
+    while ((m = keyRe.exec(region)) !== null) {
+      if (!EXTRA_KEY_SKIP.has(m[1])) keys.add(m[1]);
+    }
+    idx = text.indexOf('"extra"', idx + 1);
+  }
+  return [...keys];
+}
+
+/** Flag any non-EXPO_PUBLIC env key found embedded in the bundle's extra. */
+export function classifyPrivateEnvKeys(keys: string[], source: string): AuditFinding[] {
+  return keys
+    .filter((k) => !isPublicEnvKey(k))
+    .map((k) => ({
+      severity: 'fail' as const,
+      check: 'private-env-key' as const,
+      source,
+      detail: `${k} is embedded in the bundle but is not EXPO_PUBLIC_* — a private value leaked`,
+    }));
+}
+
+/**
+ * Operator-run value canary: does the bundle contain the literal secret value?
+ * Returns a finding with the value REDACTED (replaced by a [KEY] marker) — the
+ * raw value is never placed in the output.
+ */
+export function scanSecretValue(
+  text: string,
+  key: string,
+  value: string,
+  source: string,
+): AuditFinding | null {
+  if (isPublicEnvKey(key)) return null; // public by design
+  if (value.length < 8) return null; // too short to be a meaningful secret
+  const at = text.indexOf(value);
+  if (at === -1) return null;
+  return {
+    severity: 'fail',
+    check: 'secret-value',
+    source,
+    detail: `value of ${key} appears verbatim in the bundle (Metro-inlined leak) [${redact(value)}]`,
+  };
+}
+
+export function summarize(findings: AuditFinding[]): { fail: number; warn: number } {
+  return {
+    fail: findings.filter((f) => f.severity === 'fail').length,
+    warn: findings.filter((f) => f.severity === 'warn').length,
+  };
+}