hullproof 0.0.0-stage → 0.5.0

package/src/checks/context.ts

@@ -0,0 +1,72 @@
+// The read only view of a repository that every check runs against: the file list, file text, stack.json and scan hits.
+import { closeSync, openSync, readSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { LIMITS } from '../discover/discover.ts';
+import { walk } from '../discover/walk.ts';
+import { cmp, globToRegExp } from '../util.ts';
+import { readTracked } from '../scanners/common.ts';
+import type { CheckEvidence, Hit, Stack } from '../types/index.ts';
+
+// Folders no check searches: engine output, the kit's own files and the project's security records. The kit folders hold
+// text that names almost every term a check looks for (STANDARD.md, "What the searches leave out").
+export const LEFT_OUT = ['.hullproof/', 'docs/hullproof/', 'tools/hullproof/', '.claude/', 'editors/', 'prompts/', 'docs/security/'];
+
+export interface CheckContext {
+  repo: string;                 // absolute path
+  files: string[];              // repository relative POSIX paths, sorted, LEFT_OUT removed
+  stack: Stack;
+  hits: Hit[];
+  kitDir: string | null;        // absolute path of the kit (docs/hullproof and tools/hullproof under it), when known
+  text(file: string): string;   // '' when unreadable; at most LIMITS.maxBytesPerFile bytes
+  select(globs: string[], exclude?: string[]): string[];
+  // Every file in the git index, sorted, including files inside folders discovery skips (.vercel, .netlify, dist ...),
+  // so a check can see a committed link or build file. null outside a git repository. Read once, on first use.
+  tracked(): string[] | null;
+}
+
+function readHead(abs: string, max: number): string {
+  const fd = openSync(abs, 'r');
+  try {
+    const buf = Buffer.alloc(max);
+    const n = readSync(fd, buf, 0, max, 0);
+    return buf.subarray(0, n).toString('utf8');
+  } finally { closeSync(fd); }
+}
+
+export function makeContext(repo: string, stack: Stack, hits: Hit[] = [], kitDir: string | null = null): CheckContext {
+  const root = resolve(repo);
+  const files = walk(root, LIMITS.maxFiles).files.filter((f) => !LEFT_OUT.some((p) => f.startsWith(p)));
+  const cache = new Map<string, string>();
+  const text = (f: string): string => {
+    let t = cache.get(f);
+    if (t === undefined) {
+      try { t = readHead(join(root, f), LIMITS.maxBytesPerFile); } catch { t = ''; }
+      cache.set(f, t);
+    }
+    return t;
+  };
+  const select = (globs: string[], exclude: string[] = []): string[] => {
+    const inc = globs.map(globToRegExp);
+    const exc = exclude.map(globToRegExp);
+    return files.filter((f) => inc.some((r) => r.test(f)) && !exc.some((r) => r.test(f)));
+  };
+  let trackedList: string[] | null | undefined;
+  const tracked = (): string[] | null => {
+    if (trackedList === undefined) { const t = readTracked(root); trackedList = t ? [...t].sort(cmp) : null; }
+    return trackedList;
+  };
+  return { repo: root, files, stack, hits, kitDir, text, select, tracked };
+}
+
+// 1 based line of a character index.
+export function lineOf(text: string, index: number): number {
+  let n = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+export const byFileLine = (a: CheckEvidence, b: CheckEvidence): number =>
+  a.file < b.file ? -1 : a.file > b.file ? 1 : (a.line ?? 0) - (b.line ?? 0) || (a.note < b.note ? -1 : a.note > b.note ? 1 : 0);
+
+// The most evidence entries one check result keeps. The count of all matches is kept in absence_search.
+export const MAX_EVIDENCE = 25;

package/src/checks/map/config-checks.ts

@@ -0,0 +1,79 @@
+// Checks that read the configuration maps: Supabase tables (grants and policies) and Firebase rules. Start as leads.
+import { fileURLToPath } from 'node:url';
+import type { CheckEvidence, SupabaseTable } from '../../types/index.ts';
+import { PRIVILEGED } from '../../map/vocab.ts';
+import type { CodeCheck } from '../types.ts';
+import { mapCheck } from './shared.ts';
+
+const source = fileURLToPath(import.meta.url);
+const NATIVE_FIXTURES = { pass: 'test/fixtures/map-native/pass', fail: 'test/fixtures/map-native/fail' };
+const CLIENT_ROLES = new Set(['anon', 'authenticated', 'public']);
+const tables = (m: { config: { supabase: { tables: SupabaseTable[] } | null } }): SupabaseTable[] => m.config.supabase?.tables ?? [];
+const alwaysTrue = (e: string | null): boolean => e !== null && /^\(?\s*true\s*\)?$/i.test(e.trim());
+const WRITE_PRIVS = new Set(['insert', 'update', 'delete', 'all', 'truncate']);
+
+export const supabaseOpenTable = mapCheck({
+  id: 'check.map.supabase-open-table', sec_ids: ['SEC-DB-001', 'SEC-DB-003'], name: 'supabase-open-table', source,
+  pattern: 'a table granted to anon without row level security, or with a policy for anon or public that is always true',
+  none: 'the code map has no Supabase table',
+  candidates: (m) => tables(m).length,
+  fails: (m) => tables(m).flatMap((t): CheckEvidence[] => {
+    const out: CheckEvidence[] = [];
+    const anon = t.grants.filter((g) => g.role === 'anon' || g.role === 'public');
+    if (t.rls_enabled !== true && anon.length) out.push({ file: t.file, line: anon[0].line, note: `${t.name} has no row level security and ${anon[0].role} holds ${[...new Set(anon.flatMap((g) => g.privileges))].join(', ')}` });
+    for (const p of t.policies) {
+      if (p.roles.some((r) => r === 'anon' || r === 'public') && (alwaysTrue(p.using) || (p.using === null && alwaysTrue(p.check)) || alwaysTrue(p.check))) out.push({ file: t.file, line: p.line, note: `${t.name} policy ${p.name} lets ${p.roles.join(', ')} ${p.op} with an expression that is always true` });
+    }
+    return out;
+  }),
+});
+
+export const supabasePrivilegedColumnGrant = mapCheck({
+  id: 'check.map.supabase-privileged-column-grant', sec_ids: ['SEC-DB-033'], name: 'supabase-privileged-column-grant', source,
+  pattern: 'a client role holding insert or update on a table that has a role, plan, admin or similar column, without a column list that leaves it out',
+  none: 'the code map has no Supabase table with a role, plan or admin column',
+  candidates: (m) => tables(m).filter((t) => t.columns.some((c) => PRIVILEGED.test(c))).length,
+  fails: (m) => tables(m).flatMap((t): CheckEvidence[] => {
+    const priv = t.columns.filter((c) => PRIVILEGED.test(c) && !/^(?:owner_?id|org_?id|tenant_?id)$/i.test(c));
+    if (!priv.length) return [];
+    const lines = new Map<string, { role: string; privileges: Set<string>; columns: string[] | null; line: number }>();
+    for (const g of t.grants.filter((x) => CLIENT_ROLES.has(x.role) && x.privileges.some((p) => p === 'update' || p === 'insert' || p === 'all'))) {
+      const k = `${g.role}|${g.line}|${(g.columns ?? ['*']).join(',')}`;
+      const cur = lines.get(k) ?? { role: g.role, privileges: new Set<string>(), columns: g.columns, line: g.line };
+      for (const p of g.privileges) cur.privileges.add(p);
+      lines.set(k, cur);
+    }
+    return [...lines.values()].flatMap((g) => {
+      const reach = g.columns === null ? priv : priv.filter((c) => g.columns!.includes(c));
+      return reach.length ? [{ file: t.file, line: g.line, note: `${t.name}: ${g.role} can ${[...g.privileges].sort().join(', ')} ${g.columns === null ? 'every column' : 'the listed columns'} including ${reach.join(', ')}` }] : [];
+    });
+  }),
+});
+
+export const supabasePolicyTrustsClaims = mapCheck({
+  id: 'check.map.supabase-policy-trusts-claims', sec_ids: ['SEC-DB-006'], name: 'supabase-policy-trusts-claims', source,
+  pattern: 'a policy expression that reads user_metadata or raw_user_meta_data',
+  none: 'the code map has no Supabase policy',
+  candidates: (m) => tables(m).reduce((n, t) => n + t.policies.length, 0),
+  fails: (m) => tables(m).flatMap((t): CheckEvidence[] => t.policies.filter((p) => /user_metadata|raw_user_meta_data/i.test(`${p.using ?? ''} ${p.check ?? ''}`)).map((p) => ({ file: t.file, line: p.line, note: `${t.name} policy ${p.name} trusts user_metadata, which the signed in user can edit` }))),
+});
+
+export const firebaseAuthOnlyRule = mapCheck({
+  id: 'check.map.firebase-auth-only-rule', sec_ids: ['SEC-AUTHZ-010'], name: 'firebase-auth-only-rule', source,
+  pattern: 'a rule on a path with an owner wildcard whose only condition is that the caller is signed in',
+  none: 'the code map has no Firebase rule on a path with an owner wildcard',
+  candidates: (m) => (m.config.firebase?.rules ?? []).filter((r) => r.owner_wildcard).length,
+  fails: (m) => (m.config.firebase?.rules ?? []).filter((r) => r.owner_wildcard && r.uses_auth && !r.owner_bound && !r.always_true).map((r) => ({
+    file: r.file, line: r.line, note: `${r.service} ${r.path} allows ${r.ops.join(', ')} to any signed in user, not to the owner named in the path`,
+  })),
+});
+
+export const mobileSecretInConfig = mapCheck({
+  id: 'check.map.mobile-secret-in-config', sec_ids: ['SEC-MOBILE-001'], name: 'mobile-secret-in-config', source, fixtures: NATIVE_FIXTURES,
+  pattern: 'a value written in AndroidManifest.xml, an Android strings file or an iOS Info.plist under a name that says secret, password or private key',
+  none: 'the code map has no Android or iOS configuration file',
+  candidates: (m) => (m.config.android?.manifests.length ?? 0) + (m.config.ios?.plists.length ?? 0),
+  fails: (m) => m.config.secrets.map((x): CheckEvidence => ({ file: x.file, line: x.line, note: `${x.where}: the name ${x.key} holds a value written into the file, and this file ships inside the app` })),
+});
+
+export const CONFIG_CHECKS: CodeCheck[] = [supabaseOpenTable, supabasePrivilegedColumnGrant, supabasePolicyTrustsClaims, firebaseAuthOnlyRule, mobileSecretInConfig];

package/src/checks/map/entry-checks.ts

@@ -0,0 +1,116 @@
+// Checks that read entry points from the code map: what protects each one and what it touches. All start as leads
+// (src/report/tiers.ts) until a measurement raises them. Each is a pattern over map facts, so a FAIL is a place to look.
+import { fileURLToPath } from 'node:url';
+import type { EntryPoint } from '../../types/index.ts';
+import type { CodeCheck } from '../types.ts';
+import { ev, evAt, has, hasAuth, judged, mapCheck, stateChanging, weakAuth, where } from './shared.ts';
+
+const source = fileURLToPath(import.meta.url);
+const exempt = (ep: EntryPoint): boolean => ep.tags.includes('auth_endpoint') || ep.tags.includes('public') || ep.tags.includes('webhook');
+const SENSITIVE = /user|account|profile|customer|member|order|payment|invoice|billing|card|address|email|message|note|file|upload|document|ticket|booking|patient|wallet|session|token|credential|subscription|contact|secret|key|transaction|history|log|basket|cart|chat|conversation|appointment|photo|prescription/i;
+
+export const mutatingRouteWithoutAuth = mapCheck({
+  id: 'check.map.mutating-route-without-auth', sec_ids: ['SEC-API-001'], name: 'mutating-route-without-auth', source,
+  pattern: 'a state changing entry point with no session read on the handler, a wrapper, the router or a gate',
+  none: 'the code map has no state changing entry point',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && stateChanging(e)).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && stateChanging(e) && !exempt(e) && !hasAuth(e)).map((e) => {
+    const weak = weakAuth(e);
+    return ev(e, `${where(e)} changes state and no session read is reachable on it${weak ? ` (only a weak sign: ${weak.via} at ${weak.file}:${weak.line})` : ''}`);
+  }),
+});
+
+export const dataReadWithoutAuth = mapCheck({
+  id: 'check.map.data-read-without-auth', sec_ids: ['SEC-API-001', 'SEC-DATA-024'], name: 'data-read-without-auth', source,
+  pattern: 'a GET entry point that reads a table with a personal data name and has no session read',
+  none: 'the code map has no GET entry point that reads a data store',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.kind === 'http_route' && e.method !== 'POST' && e.data.some((d) => d.op === 'read')).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind === 'http_route' && (e.method === 'GET' || e.method === 'HEAD' || e.method === 'ANY' || e.method === null) && !exempt(e) && !hasAuth(e)).flatMap((e) => {
+    const d = e.data.find((x) => x.op === 'read' && x.target && SENSITIVE.test(x.target) && x.store !== 'filesystem');
+    return d ? [evAt(e, `${where(e)} reads ${d.target} and no session read is reachable on it`, d.line)] : [];
+  }),
+});
+
+export const writeByIdWithoutOwner = mapCheck({
+  id: 'check.map.write-by-id-without-owner', sec_ids: ['SEC-AUTHZ-003'], name: 'write-by-id-without-owner', source,
+  pattern: 'an update or delete filtered by an id from the request with no owner, user or tenant value from the session',
+  none: 'the code map has no update or delete by id',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.data.some((d) => (d.op === 'write' || d.op === 'delete') && d.by_id)).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !has(e, 'role_check')).flatMap((e) =>
+    e.data.filter((d) => (d.op === 'write' || d.op === 'delete') && d.by_id && !d.owner_scoped).map((d) => evAt(e, `${where(e)} ${d.op === 'delete' ? 'deletes from' : 'updates'} ${d.target ?? 'a record'} by an id from the request and no owner value from the session is in the query`, d.line))),
+});
+
+export const readByIdWithoutOwner = mapCheck({
+  id: 'check.map.read-by-id-without-owner', sec_ids: ['SEC-AUTHZ-003'], name: 'read-by-id-without-owner', source,
+  fixtures: { pass: 'test/fixtures/map-idor/pass', fail: 'test/fixtures/map-idor/fail' },
+  pattern: 'a signed in entry point that reads a record with a personal data name by an id from the request, with no owner, user or tenant value from the session in the query and no role check',
+  none: 'the code map has no signed in entry point that reads a record by an id from the request',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !exempt(e) && has(e, 'session_read') && e.data.some((d) => d.op === 'read' && d.by_id && d.store !== 'filesystem' && d.target && SENSITIVE.test(d.target))).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !exempt(e) && has(e, 'session_read') && !has(e, 'role_check') && !has(e, 'owner_filter')).flatMap((e) =>
+    e.data.filter((d) => d.op === 'read' && d.by_id && !d.owner_scoped && d.store !== 'filesystem' && d.target && SENSITIVE.test(d.target)).slice(0, 1).map((d) => evAt(e, `${where(e)} reads ${d.target ?? 'a record'} by an id from the request and no owner value from the session is in the query`, d.line))),
+});
+
+export const adminRouteWithoutRole = mapCheck({
+  id: 'check.map.admin-route-without-role', sec_ids: ['SEC-AUTHZ-020', 'SEC-AUTHZ-002'], name: 'admin-route-without-role', source,
+  pattern: 'an entry point in an admin area with no role check on the handler, a wrapper, the router or a gate',
+  none: 'the code map has no entry point in an admin area',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin')).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && !has(e, 'role_check')).map((e) =>
+    ev(e, `${where(e)} is in an admin area and no server side role check is reachable on it${has(e, 'session_read') ? ' (a session read is not a role check)' : ''}`)),
+});
+
+export const webhookVerifyBeforeUse = mapCheck({
+  id: 'check.map.webhook-verify-before-use', sec_ids: ['SEC-API-101'], name: 'webhook-verify-before-use', source,
+  pattern: 'a webhook entry point with no signature check, a check that does not stop the request, or a body parsed first',
+  none: 'the code map has no webhook entry point',
+  candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.kind === 'webhook').length,
+  fails: (m) => m.entry_points.filter((e) => !e.test_code && e.kind === 'webhook').flatMap((e) => {
+    const sigs = e.protections.filter((p) => p.kind === 'signature_verify');
+    if (!sigs.length) return [ev(e, `${where(e)} is a webhook and no signature check was found on it`)];
+    if (sigs.every((p) => p.enforced === false)) return [{ file: sigs[0].file, line: sigs[0].line, note: `${where(e)} checks the signature but carries on when it fails` }];
+    if (sigs.some((p) => p.after_parse) && !sigs.some((p) => !p.after_parse)) return [{ file: sigs[0].file, line: sigs[0].line, note: `${where(e)} parses the request body before it checks the signature` }];
+    return [];
+  }),
+});
+
+export const requestUrlFetched = mapCheck({
+  id: 'check.map.request-url-fetched', sec_ids: ['SEC-API-035'], name: 'request-url-fetched', source,
+  pattern: 'an outbound HTTP call whose target comes from the request, with no allowlist in the same function',
+  none: 'the code map has no outbound HTTP call in an entry point',
+  candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.outbound.some((o) => o.kind === 'http')).length,
+  fails: (m) => m.entry_points.filter((e) => !e.test_code).flatMap((e) => e.outbound.filter((o) => o.kind === 'http' && o.request_derived && !o.guarded).map((o) =>
+    evAt(e, `${where(e)} fetches ${o.target}, which comes from the request, and no allowlist of hosts is checked`, o.line))),
+});
+
+export const privilegedFieldFromRequest = mapCheck({
+  id: 'check.map.privileged-field-from-request', sec_ids: ['SEC-AUTHZ-004'], name: 'privileged-field-from-request', source,
+  pattern: 'a write that sets role, plan, admin or similar columns from request data, or passes the whole request object to a create or update',
+  none: 'the code map has no write in an entry point',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.data.some((d) => d.op === 'write')).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !has(e, 'role_check')).flatMap((e) =>
+    e.data.filter((d) => d.op === 'write' && (d.sets.length > 0 || d.mass_assign)).map((d) =>
+      evAt(e, d.sets.length ? `${where(e)} sets ${d.sets.join(', ')} on ${d.target ?? 'a record'} from request data` : `${where(e)} passes the whole request object into a write on ${d.target ?? 'a record'}`, d.line))),
+});
+
+export const privilegedActionWithoutAudit = mapCheck({
+  id: 'check.map.privileged-action-without-audit', sec_ids: ['SEC-LOG-003'], name: 'privileged-action-without-audit', source,
+  pattern: 'a write or delete in an admin area with no audit record call',
+  none: 'the code map has no write or delete in an admin area',
+  candidates: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && e.data.some((d) => d.op === 'write' || d.op === 'delete')).length,
+  fails: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && e.data.some((d) => d.op === 'write' || d.op === 'delete') && !e.protections.some((p) => p.kind === 'audit_log')).map((e) =>
+    ev(e, `${where(e)} changes data in an admin area and writes no audit record`)),
+});
+
+export const redirectFromRequest = mapCheck({
+  id: 'check.map.redirect-from-request', sec_ids: ['SEC-AUTH-030'], name: 'redirect-from-request', source,
+  pattern: 'a redirect target taken from the request with no allowlist comparison in the same function',
+  none: 'the code map has no redirect in an entry point',
+  candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.outbound.some((o) => o.kind === 'redirect')).length,
+  fails: (m) => m.entry_points.filter((e) => !e.test_code).flatMap((e) => e.outbound.filter((o) => o.kind === 'redirect' && o.request_derived && !o.guarded).map((o) =>
+    evAt(e, `${where(e)} sends the user to ${o.target}, which comes from the request, and no allowlist is checked`, o.line))),
+});
+
+export const ENTRY_CHECKS: CodeCheck[] = [
+  mutatingRouteWithoutAuth, dataReadWithoutAuth, writeByIdWithoutOwner, readByIdWithoutOwner, adminRouteWithoutRole, webhookVerifyBeforeUse,
+  requestUrlFetched, privilegedFieldFromRequest, privilegedActionWithoutAudit, redirectFromRequest,
+];

package/src/checks/map/shared.ts

@@ -0,0 +1,63 @@
+// Helpers for the checks that read the code map (docs/PHASE-2-DESIGN.md section 4). The map is built once per context.
+import type { CheckEvidence, CodeMap, EntryPoint, Protection, ProtectionKind } from '../../types/index.ts';
+import { buildCodeMap } from '../../map/build.ts';
+import type { CheckContext } from '../context.ts';
+import type { OpOutcome } from '../ops.ts';
+import type { CodeCheck } from '../types.ts';
+
+const cache = new WeakMap<CheckContext, CodeMap>();
+export function getMap(ctx: CheckContext): CodeMap {
+  let m = cache.get(ctx);
+  if (!m) { m = buildCodeMap(ctx); cache.set(ctx, m); }
+  return m;
+}
+
+// A protection that counts: not a weak guess, and not one the code is known to ignore.
+export const counts = (p: Protection): boolean => p.confidence !== 'low' && p.enforced !== false;
+export const has = (ep: EntryPoint, kind: ProtectionKind): boolean => ep.protections.some((p) => p.kind === kind && counts(p));
+export const hasAuth = (ep: EntryPoint): boolean => has(ep, 'session_read') || has(ep, 'signature_verify');
+export const weakAuth = (ep: EntryPoint): Protection | undefined => ep.protections.find((p) => p.kind === 'session_read' && !counts(p));
+
+export const HANDLER_KINDS = new Set(['http_route', 'server_action', 'graphql_resolver', 'rpc']);
+// Entry points the checks judge: shipped code, a kind that handles requests.
+export const judged = (ep: EntryPoint): boolean => !ep.test_code && HANDLER_KINDS.has(ep.kind) && ep.framework !== 'django-admin';
+export const stateChanging = (ep: EntryPoint): boolean => ep.tags.includes('state_changing') || (ep.kind === 'graphql_resolver' && ep.method === 'MUTATION') || (ep.kind === 'rpc' && ep.method === 'MUTATION');
+
+// Evidence in the entry point's own file at the registration line, or, for a line inside the handler body (a data touch, an outbound
+// call), in the file that holds the handler: a route registered in one file can have its handler in another.
+export const ev = (ep: EntryPoint, note: string): CheckEvidence => ({ file: ep.file, line: ep.line, note });
+export const evAt = (ep: EntryPoint, note: string, line: number): CheckEvidence => ({ file: ep.handler?.file ?? ep.file, line, note });
+
+export const where = (ep: EntryPoint): string => `${ep.method && ep.method !== 'ANY' ? ep.method + ' ' : ''}${ep.path ?? ep.name ?? ep.file}`.trim();
+
+export interface MapCheckSpec {
+  id: string; sec_ids: string[]; name: string; source: string;
+  // The entry points or records the check looks at. Zero candidates makes the check not applicable.
+  candidates(map: CodeMap): number;
+  // Evidence for everything that fails.
+  fails(map: CodeMap, ctx: CheckContext): CheckEvidence[];
+  none: string;                    // reason when there is nothing to judge
+  pattern: string;                 // what was searched, for the absence record
+  fixtures?: { pass: string; fail: string }; // when the check reads facts the shared map fixtures do not hold
+}
+
+export function mapCheck(s: MapCheckSpec): CodeCheck {
+  return {
+    id: s.id, sec_ids: s.sec_ids, applies_when: {}, op: 'code', on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST', on_false: 'FAIL',
+    fixtures: s.fixtures ?? { pass: 'test/fixtures/map/pass', fail: 'test/fixtures/map/fail' }, source: s.source,
+    run: (ctx): OpOutcome => {
+      const map = getMap(ctx);
+      const n = s.candidates(map);
+      if (n === 0) return { value: 'not_applicable', reason: s.none, evidence: [], absence: null };
+      const bad = s.fails(map, ctx).sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) || (a.line ?? 0) - (b.line ?? 0) || (a.note < b.note ? -1 : a.note > b.note ? 1 : 0));
+      return { value: bad.length === 0, evidence: bad, absence: { pattern: s.pattern, files_searched: n, file_globs: ['codemap.json'], matches: bad.length } };
+    },
+  };
+}
+
+// The text of an entry point's handler, with `above` lines before it (decorators and route options sit above).
+export function handlerText(ctx: CheckContext, ep: EntryPoint, above = 0): string {
+  const file = ep.handler?.file ?? ep.file;
+  const start = ep.handler?.line ?? ep.line;
+  return ctx.text(file).split('\n').slice(Math.max(0, start - 1 - above), Math.max(start, ep.end_line)).join('\n');
+}

package/src/checks/ops.ts

@@ -0,0 +1,280 @@
+// The declarative check operations. Each takes the op's params and the repository view and returns an outcome.
+// Params per op are documented in src/checks/README.md. No op runs a program or uses the network.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp } from '../util.ts';
+import type { AbsenceSearch, CheckEvidence, CheckOp } from '../types/index.ts';
+import { MAX_EVIDENCE, byFileLine, lineOf, type CheckContext } from './context.ts';
+
+// value: true or false picks on_true or on_false. 'not_applicable' and 'cannot_run' put the check in not_run with reason.
+export interface OpOutcome {
+  value: boolean | 'not_applicable' | 'cannot_run';
+  reason?: string;
+  evidence: CheckEvidence[];
+  absence: AbsenceSearch | null;
+}
+
+type P = Record<string, unknown>;
+const strs = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : typeof v === 'string' ? [v] : []);
+const str = (v: unknown, d = ''): string => (typeof v === 'string' ? v : d);
+const cap = (ev: CheckEvidence[]): CheckEvidence[] => ev.sort(byFileLine).slice(0, MAX_EVIDENCE);
+const na = (reason: string): OpOutcome => ({ value: 'not_applicable', reason, evidence: [], absence: null });
+const cannot = (reason: string): OpOutcome => ({ value: 'cannot_run', reason, evidence: [], absence: null });
+
+export function compile(pattern: string, ignoreCase: boolean): RegExp {
+  return new RegExp(pattern, ignoreCase ? 'gim' : 'gm');
+}
+
+// Every match of re in text, as evidence.
+export function matchesIn(file: string, text: string, re: RegExp, note: string): CheckEvidence[] {
+  const out: CheckEvidence[] = [];
+  re.lastIndex = 0;
+  for (let m = re.exec(text); m; m = re.exec(text)) {
+    out.push({ file, line: lineOf(text, m.index), note });
+    if (m[0] === '') re.lastIndex++;
+  }
+  return out;
+}
+
+// Files the op reads: params.files minus params.exclude, kept only when they match params.only_if.
+function selected(ctx: CheckContext, p: P): string[] {
+  const files = ctx.select(strs(p.files), strs(p.exclude));
+  if (typeof p.only_if !== 'string') return files;
+  const re = compile(p.only_if, p.ignore_case === true);
+  return files.filter((f) => { re.lastIndex = 0; return re.test(ctx.text(f)); });
+}
+
+// params.precondition {files, exclude?, pattern?}: when no file meets it the check does not apply. Returns the files that do.
+function precondition(ctx: CheckContext, p: P): string[] | null {
+  const pre = p.precondition as P | undefined;
+  if (!pre) return null;
+  const files = ctx.select(strs(pre.files), strs(pre.exclude));
+  if (typeof pre.pattern !== 'string') return files;
+  const re = compile(pre.pattern, pre.ignore_case === true);
+  return files.filter((f) => { re.lastIndex = 0; return re.test(ctx.text(f)); });
+}
+
+function preEvidence(ctx: CheckContext, p: P, files: string[]): CheckEvidence[] {
+  const pre = p.precondition as P;
+  const note = str(p.precondition_note, 'searched here');
+  if (typeof pre.pattern !== 'string') return files.map((file) => ({ file, line: 1, note }));
+  const re = compile(pre.pattern, pre.ignore_case === true);
+  return files.map((file) => ({ file, line: matchesIn(file, ctx.text(file), re, note)[0]?.line ?? 1, note }));
+}
+
+function regexOp(ctx: CheckContext, p: P, present: boolean): OpOutcome {
+  const pre = precondition(ctx, p);
+  if (pre && pre.length === 0) return na(str(p.not_applicable_reason, 'no file meets the precondition'));
+  const files = selected(ctx, p);
+  const pattern = str(p.pattern);
+  if (!pattern) return cannot('params.pattern is missing');
+  const absence = (matches: number): AbsenceSearch => ({ pattern, files_searched: files.length, file_globs: strs(p.files), matches });
+  if (files.length === 0) {
+    const w = str(p.when_no_files, 'not_applicable');
+    if (w === 'not_applicable') return na(str(p.not_applicable_reason, 'no file to search'));
+    const value = w === 'true';
+    return { value, evidence: !value && pre ? cap(preEvidence(ctx, p, pre)) : [], absence: absence(0) };
+  }
+  const re = compile(pattern, p.ignore_case === true);
+  const note = str(p.note, present ? 'matches the pattern' : 'matches the pattern this check forbids');
+  const perFile = files.map((f) => ({ f, ev: matchesIn(f, ctx.text(f), re, note) }));
+  const all = perFile.flatMap((x) => x.ev);
+  if (!present) return { value: all.length === 0, evidence: cap(all), absence: absence(all.length) };
+  if (p.each_file === true) {
+    const missing = perFile.filter((x) => x.ev.length === 0).map((x) => x.f);
+    const missNote = str(p.missing_note, 'the pattern is not in this file');
+    return missing.length
+      ? { value: false, evidence: cap(missing.map((file) => ({ file, line: 1, note: missNote }))), absence: absence(all.length) }
+      : { value: true, evidence: cap(all), absence: absence(all.length) };
+  }
+  if (all.length) return { value: true, evidence: cap(all), absence: absence(all.length) };
+  // Nothing found anywhere: point at the files where the thing is normally configured, when the check names them.
+  return { value: false, evidence: pre ? cap(preEvidence(ctx, p, pre)) : [], absence: absence(0) };
+}
+
+function fileExists(ctx: CheckContext, p: P, wantPresent: boolean): OpOutcome {
+  const found = ctx.select(strs(p.files), strs(p.exclude));
+  const note = str(p.note, wantPresent ? 'file present' : 'file present that this check forbids');
+  const evidence = cap(found.map((file) => ({ file, key: '(present)', note })));
+  const absence: AbsenceSearch = { pattern: strs(p.files).join(' '), files_searched: ctx.files.length, file_globs: strs(p.files), matches: found.length };
+  return { value: wantPresent ? found.length > 0 : found.length === 0, evidence, absence };
+}
+
+// params.manifests: manifest file name to the lockfile names that pin it. A lockfile in the same folder or any parent counts.
+function fileExistsForEach(ctx: CheckContext, p: P): OpOutcome {
+  const table = (p.manifests ?? {}) as Record<string, string[]>;
+  const names = Object.keys(table);
+  const have = new Set(ctx.files);
+  const manifests = ctx.files.filter((f) => names.includes(f.slice(f.lastIndexOf('/') + 1)));
+  if (manifests.length === 0) return na('no package manifest in the repository');
+  const missing: CheckEvidence[] = [];
+  for (const m of manifests) {
+    const locks = table[m.slice(m.lastIndexOf('/') + 1)];
+    const parts = m.split('/').slice(0, -1);
+    let ok = false;
+    for (let i = parts.length; i >= 0 && !ok; i--) {
+      const dir = parts.slice(0, i).join('/');
+      ok = locks.some((l) => have.has(dir ? `${dir}/${l}` : l));
+    }
+    if (!ok) missing.push({ file: m, line: 1, note: str(p.note, `no lockfile (${locks.join(', ')}) in this folder or above`) });
+  }
+  const absence: AbsenceSearch = { pattern: [...new Set(Object.values(table).flat())].sort(cmp).join(' '), files_searched: manifests.length, file_globs: names, matches: manifests.length - missing.length };
+  return missing.length ? { value: false, evidence: cap(missing), absence } : { value: true, evidence: cap(manifests.map((file) => ({ file, line: 1, note: 'lockfile found' }))), absence };
+}
+
+// Strips SQL comments, keeping line breaks so line numbers stay right.
+const stripSqlComments = (t: string): string => t.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+const tableName = (raw: string): { schema: string | null; name: string } => {
+  const parts = raw.replace(/"/g, '').toLowerCase().split('.');
+  return parts.length > 1 ? { schema: parts[0], name: parts[1] } : { schema: null, name: parts[0] };
+};
+
+// Every table created in an exposed schema has row level security enabled after it, reading files in name order.
+function sqlEveryTableHas(ctx: CheckContext, p: P): OpOutcome {
+  const files = ctx.select(strs(p.files), strs(p.exclude));
+  if (files.length === 0) return na('no migration files');
+  const schemas = strs(p.schemas).length ? strs(p.schemas) : ['public'];
+  const ident = '((?:"[^"]+"|[\\w$]+)(?:\\.(?:"[^"]+"|[\\w$]+))?)';
+  const re = new RegExp(`\\b(create\\s+(?:unlogged\\s+)?table\\s+(?:if\\s+not\\s+exists\\s+)?${ident}|alter\\s+table\\s+(?:if\\s+exists\\s+)?(?:only\\s+)?${ident}\\s+(enable|disable|force)\\s+row\\s+level\\s+security|drop\\s+table\\s+(?:if\\s+exists\\s+)?${ident})`, 'gi');
+  const tables = new Map<string, { file: string; line: number; rls: boolean }>();
+  const key = (raw: string): string | null => {
+    const t = tableName(raw);
+    const schema = t.schema ?? schemas[0];
+    return schemas.includes(schema) ? `${schema}.${t.name}` : null;
+  };
+  for (const f of files) {
+    const text = stripSqlComments(ctx.text(f));
+    re.lastIndex = 0;
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+      if (m[2]) { const k = key(m[2]); if (k) tables.set(k, { file: f, line: lineOf(text, m.index), rls: false }); }
+      else if (m[3]) { const k = key(m[3]); const t = k ? tables.get(k) : undefined; if (t) t.rls = m[4].toLowerCase() !== 'disable'; }
+      else if (m[5]) { const k = key(m[5]); if (k) tables.delete(k); }
+    }
+  }
+  if (tables.size === 0) return na('no table created in an exposed schema');
+  const without = [...tables.entries()].filter(([, t]) => !t.rls);
+  const absence: AbsenceSearch = { pattern: 'alter table <name> enable row level security', files_searched: files.length, file_globs: strs(p.files), matches: tables.size - without.length };
+  const evidence = without.map(([name, t]) => ({ file: t.file, line: t.line, note: `table ${name} is created and row level security is never enabled on it` }));
+  return { value: without.length === 0, evidence: cap(evidence), absence };
+}
+
+function workflows(ctx: CheckContext, p: P): string[] {
+  return ctx.select(strs(p.files).length ? strs(p.files) : ['.github/workflows/*.yml', '.github/workflows/*.yaml']);
+}
+
+// Every third party action is referenced by a full 40 character commit SHA.
+function workflowUsesPinnedSha(ctx: CheckContext, p: P): OpOutcome {
+  const files = workflows(ctx, p);
+  if (files.length === 0) return na('no CI workflow files');
+  const re = /^[ \t-]*uses:\s*["']?([^\s"'#]+)/gm;
+  const bad: CheckEvidence[] = [];
+  let total = 0;
+  for (const f of files) {
+    const text = ctx.text(f);
+    re.lastIndex = 0;
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+      const ref = m[1];
+      if (ref.startsWith('./') || ref.startsWith('docker://')) continue;
+      total++;
+      const at = ref.lastIndexOf('@');
+      if (at < 0 || !/^[0-9a-f]{40}$/.test(ref.slice(at + 1))) bad.push({ file: f, line: lineOf(text, m.index), note: `${ref} is not pinned to a full commit SHA` });
+    }
+  }
+  if (total === 0) return na('no third party action is used');
+  const absence: AbsenceSearch = { pattern: 'uses: <owner>/<repo>@<40 hex>', files_searched: files.length, file_globs: strs(p.files), matches: total - bad.length };
+  return { value: bad.length === 0, evidence: cap(bad), absence };
+}
+
+// Every workflow declares token permissions (at the top or on every job) and none grants write-all.
+function workflowPermissions(ctx: CheckContext, p: P): OpOutcome {
+  const files = workflows(ctx, p);
+  if (files.length === 0) return na('no CI workflow files');
+  const bad: CheckEvidence[] = [];
+  for (const f of files) {
+    const text = ctx.text(f);
+    for (const m of text.matchAll(/^[ \t]*permissions:[ \t]*write-all\b/gm)) bad.push({ file: f, line: lineOf(text, m.index), note: 'the token is granted write access to everything' });
+    if (/^permissions:/m.test(text)) continue;
+    const jobsAt = /^jobs:\s*$/m.exec(text);
+    if (!jobsAt) continue;
+    const body = text.slice(jobsAt.index);
+    const jobs = [...body.matchAll(/^ {2}([\w-]+):\s*$/gm)];
+    const withPerms = jobs.filter((j, i) => {
+      const end = jobs[i + 1]?.index ?? body.length;
+      return /^ {4}permissions:/m.test(body.slice(j.index, end));
+    });
+    if (jobs.length === 0 || withPerms.length < jobs.length) {
+      bad.push({ file: f, line: lineOf(text, jobsAt.index), note: 'no permissions block for the workflow or for every job, so the token gets the repository default' });
+    }
+  }
+  const absence: AbsenceSearch = { pattern: 'permissions: (top level or per job), write-all', files_searched: files.length, file_globs: strs(p.files), matches: bad.length };
+  return { value: bad.length === 0, evidence: cap(bad), absence };
+}
+
+// Reads the kit's framework support table: per heading, release line to status.
+export function supportTable(markdown: string, heading: string): Map<string, string> | null {
+  const lines = markdown.split(/\r?\n/);
+  const at = lines.findIndex((l) => l.trim() === `## ${heading}`);
+  if (at < 0) return null;
+  const rows = new Map<string, string>();
+  for (let i = at + 1; i < lines.length && !lines[i].startsWith('## '); i++) {
+    const l = lines[i].trim();
+    if (!l.startsWith('|') || /^\|[\s|:-]+\|$/.test(l)) continue;
+    const cells = l.slice(1, -1).split('|').map((c) => c.trim());
+    if (cells[0] === 'Release line') continue;
+    rows.set(cells[0], cells[cells.length - 1]);
+  }
+  return rows;
+}
+
+// The release line of a declared version: "13.4.0" -> "13", "^0.85.2" -> "0.85", "~=5.2.1" -> "5.2".
+export function releaseLine(version: string, digits: number): string | null {
+  const m = /(\d+)(?:\.(\d+))?/.exec(version);
+  if (!m) return null;
+  return digits === 2 ? (m[2] === undefined ? null : `${m[1]}.${m[2]}`) : m[1];
+}
+
+// params.table: kit relative path. params.frameworks: stack id to {heading, package, digits}.
+function versionInTable(ctx: CheckContext, p: P): OpOutcome {
+  if (!ctx.kitDir) return cannot('the kit folder is not known, so the framework support table cannot be read');
+  let md: string;
+  try { md = readFileSync(join(ctx.kitDir, str(p.table)), 'utf8'); } catch { return cannot(`cannot read ${str(p.table)} in the kit`); }
+  const table = (p.frameworks ?? {}) as Record<string, { heading: string; package: string; digits?: number }>;
+  const items = [...ctx.stack.frameworks, ...ctx.stack.mobile].filter((i) => table[i.id]);
+  if (items.length === 0) return na('no framework from the support table is in stack.json');
+  const bad: CheckEvidence[] = [];
+  const good: CheckEvidence[] = [];
+  const unknown: string[] = [];
+  for (const item of items) {
+    const row = table[item.id];
+    const rows = supportTable(md, row.heading);
+    const ev = item.evidence.find((e) => e.rule.includes('.dep.')) ?? item.evidence[0];
+    const declared = (item.versions ?? []).filter((v) => v.startsWith(`${row.package}@`)).map((v) => v.slice(row.package.length + 1));
+    if (!rows || declared.length === 0) { unknown.push(item.id); continue; }
+    for (const v of declared) {
+      const line = releaseLine(v, row.digits ?? 1);
+      const status = line ? rows.get(line) : undefined;
+      const where = { file: ev?.file ?? 'package.json', ...(ev?.line ? { line: ev.line } : { key: ev?.key ?? `(present)` }) };
+      if (/canary|alpha|beta|rc|next|experimental|nightly/i.test(v)) bad.push({ ...where, note: `${row.package} ${v} is a prerelease or canary version` });
+      else if (status === 'Supported') good.push({ ...where, note: `${row.package} ${v}: release line ${line} is supported in the kit table` });
+      else if (status) bad.push({ ...where, note: `${row.package} ${v}: release line ${line} is ${status.toLowerCase()} in the kit's framework support table` });
+      else unknown.push(`${item.id} ${v}`);
+    }
+  }
+  const absence: AbsenceSearch = { pattern: `release lines in ${str(p.table)}`, files_searched: 1, file_globs: [str(p.table)], matches: good.length };
+  if (bad.length) return { value: false, evidence: cap(bad), absence };
+  if (unknown.length) return cannot(`no row in the framework support table for ${unknown.sort(cmp).join(', ')}`);
+  return { value: true, evidence: cap(good), absence };
+}
+
+export const OPS: Partial<Record<CheckOp, (ctx: CheckContext, p: P) => OpOutcome>> = {
+  file_exists: (c, p) => fileExists(c, p, true),
+  file_absent: (c, p) => fileExists(c, p, false),
+  file_exists_for_each: fileExistsForEach,
+  regex_present: (c, p) => regexOp(c, p, true),
+  regex_absent: (c, p) => regexOp(c, p, false),
+  sql_every_table_has: sqlEveryTableHas,
+  workflow_uses_pinned_sha: workflowUsesPinnedSha,
+  workflow_permissions: workflowPermissions,
+  version_in_table: versionInTable,
+  // json_value is in the op list of the design and not built: no check needs it yet.
+};

package/src/checks/pro-map.ts

@@ -0,0 +1,4 @@
+// This edition has no map checks beyond the ones in src/checks/map/, so this list is empty.
+import type { CodeCheck } from './types.ts';
+
+export const PRO_MAP_CHECKS: CodeCheck[] = [];