hullproof 0.0.0-stage → 0.5.0

package/src/types/check.ts

@@ -0,0 +1,52 @@
+// Executable checks: the definition format (checks/*.json) and the result format (checks.json).
+// JSON schemas: schemas/check.schema.json, schemas/check-results.schema.json. Documented in docs/INTERFACES.md.
+import type { StackCategory } from './stack.ts';
+import type { ResultWord } from './results.ts';
+
+export type CheckOp =
+  | 'file_exists' | 'file_exists_for_each' | 'file_absent'
+  | 'regex_present' | 'regex_absent' | 'json_value'
+  | 'sql_every_table_has' | 'workflow_uses_pinned_sha' | 'workflow_permissions' | 'version_in_table'
+  | 'code';                                     // a check written as TypeScript, see CodeCheckDefinition
+
+// One declarative check definition (checks/*.json). Data only, no code. The interpreter in src/checks/ runs it.
+export interface CheckDefinition {
+  id: string;                                   // "check.<area>.<name>", for example "check.supply.lockfile-committed"
+  sec_ids: string[];
+  // Runs only when every named stack category has an item whose id is listed, or any item when the value is "*".
+  applies_when: Partial<Record<StackCategory, string[] | '*'>>;
+  op: CheckOp;
+  params: Record<string, unknown>;              // op specific, documented per op in docs/INTERFACES.md by the checks author
+  on_true: ResultWord;
+  on_false: ResultWord;
+  fixtures: { pass: string; fail: string };     // folders under test/fixtures/checks/
+}
+
+// A check written as TypeScript when no declarative op can say it: op "code", no params, and module names the file in
+// src/checks/code/ that exports it. The five code checks keep this metadata in their module (src/checks/types.ts CodeCheck).
+export interface CodeCheckDefinition extends Omit<CheckDefinition, 'op' | 'params'> {
+  op: 'code';
+  module: string;                               // for example "src/checks/code/webhook-verify.ts"
+}
+
+export interface CheckEvidence { file: string; line?: number; key?: string; note: string }
+
+// The search that supports an absence result (same idea as absence_search in the findings record).
+export interface AbsenceSearch { pattern: string; files_searched: number; file_globs: string[]; matches: number }
+
+export interface CheckResult {
+  check_id: string;
+  sec_ids: string[];
+  result: ResultWord;
+  evidence: CheckEvidence[];                    // sorted by file, then line
+  absence_search: AbsenceSearch | null;
+  message_key: string;                          // key into the engine's plain English text, normally the check id
+}
+
+// checks.json
+export interface CheckResultsFile {
+  schema_version: '1.0.0';
+  commit: string | null;
+  results: CheckResult[];                       // sorted by check_id
+  not_run: { check_id: string; reason: string }[]; // sorted by check_id
+}

package/src/types/codemap.ts

@@ -0,0 +1,142 @@
+// codemap.json, written by `hullproof map` and by `scan`. JSON schema: schemas/codemap.schema.json. Design: docs/PHASE-2-DESIGN.md.
+import type { Confidence } from './stack.ts';
+
+export type EntryKind =
+  | 'http_route' | 'webhook' | 'server_action' | 'page' | 'ai_tool' | 'job' | 'graphql_resolver' | 'rpc'
+  | 'message_consumer' | 'websocket' | 'deep_link' | 'ipc';
+
+export type ProtectionKind = 'session_read' | 'role_check' | 'owner_filter' | 'signature_verify' | 'rate_limit' | 'input_validation' | 'audit_log';
+export type Scope = 'handler' | 'wrapper' | 'router' | 'middleware' | 'global';
+
+export interface Protection {
+  kind: ProtectionKind;
+  scope: Scope;
+  file: string;
+  line: number;
+  via: string;                    // the call, decorator or name that matched
+  enforced: boolean | null;       // true: a failed check stops the request; false: it carries on; null: cannot tell
+  after_parse?: boolean;          // signature_verify only: the body is parsed before the signature is checked
+  confidence: Confidence;
+}
+
+export type InputSource = 'body' | 'query' | 'params' | 'headers' | 'cookies' | 'form' | 'file';
+export interface InputRead { source: InputSource; line: number }
+
+export type StoreKind = 'sql' | 'prisma' | 'drizzle' | 'mongo' | 'supabase' | 'firebase' | 'redis' | 'orm' | 'filesystem' | 'object_storage';
+export interface DataTouch {
+  store: StoreKind;
+  op: 'read' | 'write' | 'delete' | 'unknown';
+  target: string | null;          // table or model name when known
+  line: number;
+  by_id: boolean;                 // filters on an id column with a value from the request
+  limit_from_request: boolean;    // a limit or page size comes from the request
+  request_derived: boolean;       // the query text or its arguments contain a request derived value
+  owner_scoped: boolean;          // the where clause names an owner, user, tenant or account column and the value comes from the session
+  raw_sql: boolean;
+  sets: string[];                 // privileged columns (role, plan, is_admin ...) a write sets from a request value, sorted
+  mass_assign: boolean;           // a whole request object goes into a create or update
+  confidence: Confidence;
+}
+
+export type OutboundKind = 'http' | 'ai_model' | 'email' | 'sms' | 'payment' | 'process' | 'redirect' | 'queue';
+export interface Outbound {
+  kind: OutboundKind;
+  line: number;
+  target: string;                 // the target expression, clipped to 120 characters
+  request_derived: boolean;
+  guarded: boolean;               // an allowlist or host check in the same function
+  confidence: Confidence;
+}
+
+export interface EntryPoint {
+  id: string;
+  kind: EntryKind;
+  framework: string;
+  file: string;
+  line: number;
+  end_line: number;
+  method: string | null;
+  path: string | null;
+  name: string | null;
+  handler: { file: string; line: number } | null;   // where the handler body is, when it is registered by reference
+  confidence: Confidence;
+  test_code: boolean;
+  tags: string[];                 // sorted: admin, auth_endpoint, public, state_changing, upload, webhook
+  protections: Protection[];
+  reads: InputRead[];
+  data: DataTouch[];
+  outbound: Outbound[];
+}
+
+export interface Gate {
+  id: string;
+  kind: 'middleware' | 'guard' | 'router_dependency' | 'global_pipe' | 'mount';
+  framework: string;
+  file: string;
+  line: number;
+  paths: string[];                // path prefixes covered; ['*'] for everything
+  methods: string[];              // [] for all
+  protections: Protection[];
+  confidence: Confidence;
+}
+
+export type CoverageStatus = 'mapped' | 'partial' | 'not_mapped';
+export interface Coverage {
+  language: string;
+  files: number;
+  extractor: string | null;
+  status: CoverageStatus;
+  entry_points: number;
+  note: string;
+}
+
+export interface SupabasePolicy { name: string; op: string; roles: string[]; using: string | null; check: string | null; line: number; permissive: boolean }
+export interface SupabaseGrant { role: string; privileges: string[]; columns: string[] | null; line: number }
+export interface SupabaseTable {
+  name: string; file: string; line: number; rls_enabled: boolean | null; columns: string[];
+  policies: SupabasePolicy[]; grants: SupabaseGrant[];
+}
+export interface FirebaseRule {
+  service: 'firestore' | 'storage' | 'realtime';
+  file: string; line: number; path: string; ops: string[]; condition: string;
+  uses_auth: boolean; owner_bound: boolean; always_true: boolean; owner_wildcard: boolean;
+}
+
+// ---- native mobile and Rust configuration (Phase 6f)
+export interface ConfigSecret { file: string; line: number; key: string; where: 'android manifest' | 'android strings' | 'ios plist' }
+export interface AndroidFilter { actions: string[]; categories: string[]; schemes: string[]; hosts: string[]; paths: string[] }
+export interface AndroidComponent {
+  kind: 'activity' | 'service' | 'receiver' | 'provider'; name: string; line: number;
+  exported: boolean; exported_explicit: boolean; permission: string | null; launcher: boolean; filters: AndroidFilter[];
+}
+export interface AndroidManifest {
+  file: string; package: string | null; line: number; debuggable: boolean | null; allow_backup: boolean | null; uses_cleartext_traffic: boolean | null;
+  network_security_config: string | null; target_sdk: number | null; permissions: string[]; components: AndroidComponent[];
+}
+export interface NetworkSecurity { file: string; line: number; cleartext_base: boolean | null; cleartext_domains: string[]; trusts_user_certs: boolean; pinned_domains: number }
+export interface AndroidConfig { manifests: AndroidManifest[]; network_security: NetworkSecurity[] }
+export interface IosPlist { file: string; ats_arbitrary_loads: boolean | null; ats_line: number | null; url_schemes: string[]; associated_domains: string[]; usage_descriptions: string[] }
+export interface IosConfig { plists: IosPlist[] }
+export interface CargoDependency { name: string; source: 'registry' | 'git' | 'path'; version: string | null; line: number }
+export interface CargoManifest {
+  file: string; line: number; name: string | null; edition: string | null; dependencies: CargoDependency[];
+  release_debug: boolean | null; release_overflow_checks: boolean | null; unsafe_code_lint: string | null; has_lock: boolean; binary: boolean;
+}
+export interface CargoConfig { manifests: CargoManifest[] }
+
+export interface AuthHelperCandidate { name: string; entry_points: number; file: string; line: number }
+export interface LocalVocabRecord { auth_helpers: string[]; role_helpers: string[] }
+
+export interface CodeMap {
+  schema_version: '1.0.0';
+  engine_version: string;
+  commit: string | null;
+  coverage: Coverage[];
+  entry_points: EntryPoint[];
+  gates: Gate[];
+  config: {
+    supabase: { tables: SupabaseTable[] } | null; firebase: { rules: FirebaseRule[] } | null; android: AndroidConfig | null; ios: IosConfig | null; cargo: CargoConfig | null;
+    secrets: ConfigSecret[]; local_vocab: LocalVocabRecord; auth_helper_candidates: AuthHelperCandidate[];
+  };
+  counts: { entry_points: number; by_kind: Record<string, number>; by_framework: Record<string, number> };
+}

package/src/types/findings.ts

@@ -0,0 +1,107 @@
+// The findings record (the JSON inside the hullproof-findings block of report.findings.md), schema 1.1.0.
+// The schema file is schemas/findings.schema.json, a copy of the kit's docs/hullproof/findings.schema.json; the kit file is the
+// source of truth and the copy is checked by test/schemas.test.ts. Field limits (lengths, counts, patterns) live in the schema;
+// cross field rules live in the kit's validate-findings.mjs. The engine writes schema_version "1.1.0".
+
+export type Severity = 'BLOCKER' | 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+export type FailClass = 'finding' | 'missing_control' | 'hardening_note';
+export type RouteStateWord = 'NEEDS DASHBOARD' | 'NEEDS BUILD' | 'NEEDS DYNAMIC TEST' | 'ASK OWNER' | 'ATTESTATION' | 'UNKNOWN';
+
+export interface FileLineNote { file: string; line: number; note: string }
+
+export interface Boundary { principal: string; input: string; intended_control: string; crossed: string; affected: string; result: string }
+export interface TraceStep extends FileLineNote { kind: 'entrypoint' | 'handoff' | 'sink' }
+
+// New in 1.1.0. A fail record carrying this may be class "finding" without a trace: the rule hit is the evidence.
+export interface MachineEvidence {
+  tool: string;                    // "semgrep", "gitleaks", "trivy", "hullproof-check" and so on
+  rule_id: string;                 // scanner rule id or engine check id
+  tool_version: string;
+  config_sha256: string | null;
+}
+
+export interface FailRecord {
+  fingerprint: string;             // "<SEC id|GAP|OBS>:<file or ->:<slug>"
+  kind: 'fail';
+  sec_ids: string[];
+  title: string;
+  class: FailClass;
+  gap_in_standard: boolean;
+  severity: Severity;
+  confidence: 'VERIFIED' | 'SUSPECTED';
+  demonstrated: boolean;
+  root_cause: string;
+  raised_by: string[];
+  impact_statement: string;
+  remediation: { strategy: string; confirm: string };
+  evidence: FileLineNote[];
+  boundary?: Boundary;
+  trace?: TraceStep[];
+  absence_search?: { command: string; files_searched: number; count: number; practice: 'absent' | 'present_unsafe' };
+  preventing_layer?: FileLineNote[];
+  paths_enumerated?: { count: number; method: string };
+  expiry_condition?: string;
+  owner_evidence?: { file: string; hash: string; hash_kind: 'git_blob' | 'sha256'; date: string; commit: string; note: string }[];
+  lowering?: { from: Severity; to: Severity; evidence: FileLineNote[] };
+  verified_by?: { agent: 'hullproof-finding-verifier'; mode: 'finding'; outcome: 'UPHELD' | 'ADJUSTED' | 'INSUFFICIENT'; own_severity?: Severity; own_class?: FailClass; call: number };
+  machine_evidence?: MachineEvidence;
+}
+
+export interface RoutedRecord {
+  fingerprint: string;
+  kind: 'routed';
+  sec_ids: string[];
+  title: string;
+  state: RouteStateWord;
+  reason: string;
+  owner_action: string;
+  check_card: string | null;
+  raised_by: string[];
+  boundary: Boundary;
+  trace?: TraceStep[];
+  verified_by?: { agent: 'hullproof-finding-verifier'; mode: 'handoff'; outcome: 'UPHELD' | 'ADJUSTED' | 'INSUFFICIENT'; call: number };
+}
+
+export interface RefutedRecord {
+  fingerprint: string;
+  kind: 'refuted';
+  sec_ids: string[];
+  title: string;
+  claim: string;
+  reason: string;
+  preventing_layer: FileLineNote[];
+  raised_by: string[];
+  verified_by: { agent: 'hullproof-finding-verifier'; mode: 'finding' | 'handoff'; outcome: 'REFUTED'; call: number };
+}
+
+export interface ObservationRecord {
+  fingerprint: string;
+  kind: 'observation';
+  sec_ids: string[];
+  title: string;
+  where: FileLineNote[];
+  note: string;
+  raised_by: string[];
+}
+
+export type FindingRecord = FailRecord | RoutedRecord | RefutedRecord | ObservationRecord;
+
+export interface FindingsReport {
+  commit: string;
+  tree: string;
+  tree_clean: boolean;
+  stage: 'LAUNCH' | 'GROWTH' | 'SCALE';
+  profile: 'quick' | 'standard' | 'deep';
+  scope: 'full' | 'partial';
+  scope_note?: string;
+  run_status: 'complete' | 'incomplete';
+  incomplete_reason?: 'budget_exhausted' | 'agent_failure' | 'owner_stopped' | 'deterministic_only'; // deterministic_only: schema 1.1.0, engine run, no verifier by design
+  agent_calls: number;
+  budget: number | null;
+}
+
+export interface FindingsFile {
+  schema_version: '1.0.0' | '1.1.0';
+  report: FindingsReport;
+  records: FindingRecord[];        // sorted by fingerprint
+}

package/src/types/hunt.ts

@@ -0,0 +1,97 @@
+// Types of the hunt files under <out>/<commit>/hunt/. Documented in docs/INTERFACES.md. The confirmation engine that reads them is
+// open; the step that calls a model and writes the answers is not part of this repository.
+export type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+export interface LeadStep { file: string; line: number; note: string }
+
+// A condition of the map query language (src/confirm/query.ts).
+export type Cond =
+  | { all: Cond[] } | { any: Cond[] } | { not: Cond }
+  | { field: string; op: 'eq' | 'ne' | 'in' | 'contains' | 'startsWith' | 'exists' | 'gt' | 'lt'; value?: Json }
+  | { some: string; where?: Cond } | { none: string; where?: Cond };
+export interface Query { where: Cond }
+
+export type EvidenceProposal =
+  | { kind: 'map_query'; query: Query }
+  | { kind: 'semgrep_rule'; rule_yaml: string; control_code: string; control_extension: string }
+  | { kind: 'generated_test' }
+  | { kind: 'none'; rejected?: string };
+
+export interface Lead {
+  lead_id: string;
+  entry_point: string;
+  requirement_ids: string[];      // sorted, unique
+  claim: string;
+  path: LeadStep[];               // entry point first, sink last
+  quoted_code: string;            // the code at the sink, as it stands in the file
+  evidence_proposal: EvidenceProposal;
+  claim_truncated?: true;         // the model's claim was longer than the limit and was shortened
+}
+
+// One saved answer: one call for one entry point in one run. Written as soon as it arrives.
+export interface HuntAnswer {
+  schema_version: '1.0.0';
+  run: number;
+  entry_id: string;
+  status: 'complete' | 'incomplete';
+  stop: string | null;            // why an incomplete call stopped: refusal, safety, rate_limit, timeout, length, ...
+  detail: string | null;
+  provider: string;
+  model: string;
+  context_sha256: string;
+  truncated: boolean;
+  usage: { input_tokens: number; output_tokens: number };
+  output: Json;                   // the model's JSON as received; null for an incomplete call
+}
+
+export interface HuntPlan {
+  schema_version: '1.0.0';
+  commit: string | null;
+  runs: number;
+  entries: string[];              // entry point ids in hunting order
+}
+
+export type Confirmation =
+  | { status: 'confirmed'; method: 'map_query' | 'semgrep_rule' | 'sandbox_test'; run: number; detail: string; tool: string; rule_id: string; tool_version: string; config_sha256: string }
+  | { status: 'not_confirmed'; method: 'map_query' | 'semgrep_rule' | 'generated_test' | 'none'; detail: string; reason?: 'unknown_protection'; helpers?: string[] }
+  | { status: 'not_run'; method: 'semgrep_rule'; detail: string };
+
+export interface LeadOut {
+  key: string;
+  claim_truncated?: true;
+  entry_point: string;
+  requirement_ids: string[];
+  claim: string;
+  path: LeadStep[];
+  sink: { file: string; line: number };
+  runs_raised: number;
+  runs: number[];
+  confirmation: Confirmation;
+}
+
+export interface HuntResult {
+  schema_version: '1.0.0';
+  engine_version: string;
+  commit: string | null;
+  runs: number;
+  entries_hunted: number;
+  calls: { complete: number; incomplete: number; missing: number };
+  incomplete: { entry_id: string; run: number; stop: string; detail: string }[];
+  malformed: { count: number; items: { run: number; entry_id: string; lead_id: string; reason: string }[] };
+  hallucinations: { count: number; items: { run: number; entry_id: string; lead_id: string; reason: string }[] };
+  confirmed: LeadOut[];
+  leads: LeadOut[];               // everything not confirmed, most runs first
+  usage: { calls: number; input_tokens: number; output_tokens: number };
+}
+
+export interface HuntSynthesis {
+  schema_version: '1.0.0';
+  status: 'complete' | 'incomplete';
+  stop: string | null;
+  detail: string | null;
+  provider: string;
+  model: string;
+  summary: string;
+  explanations: { key: string; text: string }[];
+  usage: { input_tokens: number; output_tokens: number };
+}

package/src/types/index.ts

@@ -0,0 +1,10 @@
+// Shared types for every engine module. Import with `import type { ... } from '../types/index.ts'`.
+export type * from './stack.ts';
+export type * from './scan.ts';
+export type * from './check.ts';
+export type * from './results.ts';
+export type * from './findings.ts';
+export { STACK_CATEGORIES } from './stack.ts';
+export type * from './codemap.ts';
+export type * from './hunt.ts';
+export type * from './prove.ts';

package/src/types/prove.ts

@@ -0,0 +1,83 @@
+// Types of the proof sandbox (Phase 4): the test spec language, the recipe that starts an app, and the files under <out>/<commit>/prove/.
+// Documented in docs/INTERFACES.md and docs/PHASE-4-DESIGN.md.
+import type { Json } from './hunt.ts';
+
+export type Method = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type Phase = 'setup' | 'control' | 'attack';
+
+export type Assertion =
+  | { kind: 'status'; op: 'eq' | 'ne' | 'in'; value: number | number[] }
+  | { kind: 'json'; path: string; op: 'eq' | 'ne' | 'contains' | 'exists' | 'absent'; value?: string | number | boolean | null }
+  | { kind: 'text'; op: 'contains' | 'absent'; value: string }
+  | { kind: 'header'; name: string; op: 'eq' | 'contains' | 'exists' | 'absent'; value?: string };
+
+export interface Capture { name: string; from: 'json' | 'header' | 'status'; path?: string }
+
+export interface SpecStep {
+  id: string; phase: Phase; actor: string; method: Method; path: string;
+  headers?: Record<string, string>; body?: { [k: string]: Json } | null; captures?: Capture[]; assert: Assertion[];
+}
+
+export interface Spec {
+  schema_version: '1.0.0';
+  spec_id: string; title: string; claim: string;
+  lead_key: string | null;                         // the hunt lead this spec tests, when it came from one
+  target: { entry_point: string; file: string; line: number };
+  requirement_ids: string[];
+  actors: Record<string, { headers?: Record<string, string> }>;
+  steps: SpecStep[];
+  expect: { outcome: 'flaw_present' };             // the attack steps' assertions describe the flaw; they all hold when it is there
+}
+
+export interface StepRecord {
+  id: string; phase: Phase; actor: string;
+  error: string | null;                            // the request could not be made (connection, timeout, bad variable)
+  request: { method: Method; path: string; headers: Record<string, string>; body: Json };
+  response: { status: number; headers: Record<string, string>; json: Json | undefined; text: string | undefined; truncated: boolean } | null;
+  captures: Record<string, Json>;
+  assertions: { ok: boolean; desc: string }[];
+}
+
+export type RunOutcome = 'proven' | 'not_proven' | 'invalid' | 'error';
+export type SpecOutcome = RunOutcome | 'unstable' | 'not_provable';
+
+// One run of one spec, as stored under prove/runs/<spec_id>/run-N.json. The hash covers everything but itself.
+export interface RunRecord {
+  schema_version: '1.0.0'; spec_id: string; spec_sha256: string; run: number;
+  outcome: RunOutcome; detail: string; steps: StepRecord[]; transcript_sha256: string;
+}
+
+export interface ProveRunSummary { run: number; outcome: RunOutcome; transcript_sha256: string; detail: string }
+export interface ProveSpecResult {
+  spec_id: string; spec_sha256: string; lead_key: string | null; title: string; claim: string;
+  entry_point: string; requirement_ids: string[]; sink: { file: string; line: number };
+  outcome: SpecOutcome; reason: string; runs: ProveRunSummary[];
+}
+
+export type NotProvableCode =
+  | 'no_package_json' | 'unsupported_stack' | 'hosted_service' | 'unsupported_datastore' | 'no_lockfile' | 'needs_install_scripts'
+  | 'no_start_command' | 'port_unknown' | 'db_path_hardcoded' | 'no_seed' | 'no_runtime' | 'refused_unsafe_backend' | 'build_failed' | 'start_failed' | 'health_failed' | 'time_limit' | 'too_large';
+export interface NotProvable { code: NotProvableCode; reason: string }
+
+export interface ProveMeta { schema_version: '1.0.0'; commit: string | null; runner: string; runs_required: number; recipe_sha256: string | null; not_provable: NotProvable | null; left_behind: number; copy_excluded: string[] }
+export interface ProveResult {
+  schema_version: '1.0.0'; engine_version: string; commit: string | null; runner: string; runs_required: number;
+  recipe_sha256: string | null; not_provable: NotProvable | null;
+  specs: ProveSpecResult[];
+  dropped: { file: string; reason: string }[];       // spec files that failed validation and were not run
+  left_behind: number;                               // containers, images or networks still there after teardown (0 when clean)
+  copy_excluded: string[];                           // what was left out of the copy that went into the sandbox
+  counts: { specs: number; proven: number; not_proven: number; invalid: number; unstable: number; error: number; not_provable: number; dropped: number };
+}
+
+export interface Recipe {
+  schema_version: '1.0.0'; stack: 'node-express' | 'python-flask'; base_image: string;
+  install_scripts?: boolean;                       // true only when the owner passed --allow-install-scripts: install scripts run (a Python package may build from source) in the build container
+  install: string[] | null;                        // argv of the build phase install, null when nothing is installed
+  vendored_modules: boolean;                       // node_modules of the repository is part of the copy (no install, no registry); always false for Python
+  seed: string | null; start: string; port: number; port_from_env: boolean; health_path: string;
+  data_store: { kind: 'none' } | { kind: 'sqlite'; env: string[] } | { kind: 'postgres'; migrations: string[]; seed_sql: string | null };
+  env: Record<string, string>;                     // dummy values only; {DATA} stands for the writable data folder
+  notes: string[];
+}
+export type RecipeResult = { ok: true; recipe: Recipe } | ({ ok: false } & NotProvable);

package/src/types/results.ts

@@ -0,0 +1,15 @@
+// results.json: the per requirement result list the kit gate (hullproof-gate.mjs, loadResults) already reads.
+
+export type RouteState = 'NEEDS DASHBOARD' | 'NEEDS BUILD' | 'NEEDS DYNAMIC TEST' | 'ASK OWNER' | 'ATTESTATION' | 'UNKNOWN';
+
+// The result words of STANDARD.md. "PASS (static)" settles only repo authority controls; the gate enforces that.
+export type ResultWord = 'FAIL' | 'PASS (static)' | 'NOT APPLICABLE' | `NOT ASSESSED: ${RouteState}`;
+
+export interface ResultRow {
+  id: string;        // SEC-XXX-000
+  result: ResultWord;
+  notes: string;     // NOT APPLICABLE needs a reason here; plain text, no secret values
+}
+
+// results.json is a JSON array of ResultRow sorted by id.
+export type ResultsFile = ResultRow[];

package/src/types/scan.ts

@@ -0,0 +1,63 @@
+// Scanner adapters and their normalised output. JSON schemas: schemas/scan-hits.schema.json, schemas/scan-meta.schema.json.
+// Written by the adapters in src/scanners/. Documented in docs/INTERFACES.md.
+import type { Stack } from './stack.ts';
+
+export type ScannerId = 'semgrep' | 'osv-scanner' | 'gitleaks' | 'trivy' | 'checkov';
+
+// One normalised scanner hit. No secret value, no tool message text, no absolute path, no timing.
+export interface Hit {
+  tool: ScannerId;
+  rule_id: string;              // the tool's own rule or check id, as the tool prints it
+  file: string;                 // repository relative POSIX path
+  line: number;                 // 1 based; 0 only when the tool gives no line (for example a lockfile level advisory)
+  sec_ids: string[];            // requirement IDs from the rule metadata or engine/maps/<tool>.json; [] means unmapped
+  severity_hint: string | null; // the tool's own severity word, kept for the report; never used by the gate
+  message_key: string;          // key into the engine's plain English text, normally `${tool}:${rule_id}`
+  noise?: string;               // secret hits only: why the value is an example, not a live secret (src/scanners/secret-noise.ts); absent when it must hold
+}
+
+// scan/<tool>.json
+export interface HitsFile {
+  schema_version: '1.0.0';
+  tool: ScannerId;
+  hits: Hit[];                  // sorted by file, line, tool, rule_id
+}
+
+// scan/<tool>.meta.json. The reproducibility record.
+export interface ToolMeta {
+  schema_version: '1.0.0';
+  tool: ScannerId;
+  status: 'ran' | 'skipped: not installed' | 'skipped: not applicable' | 'skipped: network not allowed' | 'failed';
+  version: string | null;
+  tested_version_range: string;
+  version_tested: boolean;      // false when the installed version is outside tested_version_range
+  argv: string[];               // exact command, no shell; [] when skipped
+  config_sha256: string | null;
+  commit: string | null;
+  files_scanned: number | null;
+  files_tracked: number | null;
+  exit_code: number | null;
+  db_date: string | null;       // OSV Scanner advisory data date, else null
+  not_assessed_sec_ids: string[]; // IDs that stay NOT ASSESSED because this tool did not run
+}
+
+export interface RunContext {
+  repo: string;                 // absolute path of the repository being scanned
+  out: string;                  // absolute path of the output folder
+  stack: Stack;
+  allowNetwork: boolean;
+  edition: 'free' | 'pro';
+  kit?: string | null;          // the kit folder the scan resolved; absent or null: the path order in src/mapping/controls.ts
+  history?: boolean;            // set by the scan step after its git configuration check; lets `gitleaks git` run
+}
+
+export interface ScannerAdapter {
+  id: ScannerId;
+  versionCommand: string[];
+  testedVersions: string;
+  needsNetwork: boolean;
+  applies(stack: Stack): boolean;
+  command(ctx: RunContext): string[];
+  configFiles(ctx: RunContext): string[];
+  parse(stdout: string, ctx: RunContext): Hit[];
+}

package/src/types/stack.ts

@@ -0,0 +1,61 @@
+// stack.json, written by `hullproof discover`. JSON schema: schemas/stack.schema.json. Documented in docs/INTERFACES.md.
+
+export type Confidence = 'high' | 'medium' | 'low';
+
+export const STACK_CATEGORIES = [
+  'languages', 'runtimes', 'frameworks', 'package_managers', 'data_stores', 'auth', 'payments', 'ai',
+  'hosting', 'iac', 'containers', 'ci', 'mobile',
+] as const;
+export type StackCategory = typeof STACK_CATEGORIES[number];
+
+// One proof that an item is present. Exactly one of line or key is set.
+// line: 1 based line in file. key: a JSON key path such as "dependencies.express", or "(present)" when the file itself
+// is the signal (vercel.json, Dockerfile), or "(extension)" when the file extension is the signal.
+export interface Evidence {
+  file: string;            // repository relative POSIX path
+  line?: number;
+  key?: string;
+  rule: string;            // detector rule id, for example "frameworks.express.dep.npm"
+  confidence: Confidence;
+}
+
+export interface StackItem {
+  id: string;
+  confidence: Confidence;  // the best confidence among all evidence
+  evidence: Evidence[];    // at most 5, best confidence first, then file, then line
+  evidence_count: number;  // all evidence found, including entries not listed
+  versions?: string[];     // declared versions or ranges from manifests, as written
+  file_count?: number;     // languages only: files with this language's extensions
+  kind?: string;           // hosting only: "platform" or "cloud"
+  clouds?: string[];       // iac only: providers found in those files
+  lockfiles?: string[];    // package_managers only
+  manifests?: string[];    // package_managers only
+}
+
+export interface Skipped { path: string; reason: 'gitignore' | 'dependency folder' | 'build output' | 'tool folder' | 'symlink' | 'unchanged kit files' }
+export interface Unknown { file: string; note: string }
+
+export interface Stack {
+  schema_version: '1.0.0';
+  engine_version: string;
+  detectors_sha256: string;       // sha256 over the sorted detector files
+  commit: string | null;          // HEAD commit read from .git without running git; null when not a git repository
+  confirmed_by_user: boolean;     // false until `--confirm` exists (later phase)
+  files: { listed: number; scanned_for_imports: number };
+  limits: { max_files: number; max_bytes_per_file: number; file_cap_reached: boolean; truncated_files: string[] };
+  skipped: Skipped[];
+  languages: StackItem[];
+  runtimes: StackItem[];
+  frameworks: StackItem[];
+  package_managers: StackItem[];
+  data_stores: StackItem[];
+  auth: StackItem[];
+  payments: StackItem[];
+  ai: StackItem[];
+  hosting: StackItem[];
+  iac: StackItem[];
+  containers: StackItem[];
+  ci: StackItem[];
+  mobile: StackItem[];
+  unknown: Unknown[];
+}