@cliwant/mcp-sam-gov 1.3.0 → 1.5.0

package/src/gov-domains.ts

@@ -0,0 +1,237 @@
+/**
+ * get.gov — the authoritative US .gov domain registry (CISA). KEYLESS.
+ *
+ * The .gov program (run by CISA) publishes the COMPLETE registry as CSVs in its
+ * official repo github.com/cisagov/dotgov-data — the canonical published location
+ * (get.gov links there; there is no query API for the full set). It is NOT a .gov
+ * API host, so provenance is disclosed on every response (the ProPublica /
+ * CourtListener republisher pattern — except here CISA is the first-party registrar).
+ *
+ * B2G value: resolve WHICH organization owns a .gov domain, enumerate federal
+ * agencies, and MAP SLED entities (state / county / city / school-district /
+ * special-district / tribal) for market targeting — a distinct authoritative
+ * gov-org registry no other tool here exposes.
+ *
+ * SSRF: fixed host `raw.githubusercontent.com` + fixed path prefix
+ * `/cisagov/dotgov-data/main/` + a scope-selected FIXED filename (federal | full) —
+ * no free host, path, or filename. `redirect:"error"` on the fetch.
+ *
+ * PII: the CSV carries a "Security contact email" column (an ORG security mailbox,
+ * e.g. security@agency.gov). We DROP it — this tool resolves ORGANIZATIONS, not
+ * contacts, and excluding it keeps the output free of contact info.
+ *
+ * Filtering is CLIENT-SIDE over the full published CSV (the registry has no query
+ * API) — disclosed in `_meta.notes`. `totalAvailable` is the EXACT match count.
+ */
+
+import { getText } from "./datasource.js";
+import { driftError } from "./datasource.js";
+import { memoize } from "./cache.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export const DOTGOV_HOST = "raw.githubusercontent.com";
+const DOTGOV_PATH_PREFIX = "https://raw.githubusercontent.com/cisagov/dotgov-data/main/";
+
+// scope → the pinned filename (no free path). "all" = federal + SLED (~16k rows),
+// "federal" = federal only (~1.3k rows).
+const DOTGOV_FILES = {
+  all: "current-full.csv",
+  federal: "current-federal.csv",
+} as const;
+export type GovDomainScope = keyof typeof DOTGOV_FILES;
+
+const SOURCE_LABEL = "getgov:cisagov/dotgov-data";
+const PROVENANCE_NOTE =
+  "Source: the CISA get.gov OFFICIAL .gov domain registry, published as CSV at github.com/cisagov/dotgov-data (the canonical location; get.gov links there). CISA is the first-party .gov registrar; this is authoritative public data served from GitHub, not a .gov API host.";
+const CLIENT_FILTER_NOTE =
+  "The registry has no query API — the full published CSV is fetched and filtered CLIENT-SIDE (organization/domain/city are case-insensitive SUBSTRING matches; state/domainType are case-insensitive). totalAvailable is the EXACT count of matching rows.";
+const FRESHNESS_NOTE =
+  "The CISA dotgov-data CSV is refreshed ~daily; this response reflects the currently-published snapshot (served from a 6-hour cache).";
+const EMAIL_DROP_NOTE =
+  "The registry's 'Security contact email' column (an organization security mailbox) is intentionally EXCLUDED — this tool resolves organizations, not contacts.";
+
+export type GovDomainRow = {
+  domain: string;
+  domainType: string;
+  organization: string;
+  suborganization: string | null;
+  city: string | null;
+  state: string | null;
+};
+
+// ─── Minimal RFC-4180 CSV parser (quoted fields + embedded commas/newlines) ──
+/**
+ * Parse a full CSV document into rows of string fields. Handles double-quoted
+ * fields, escaped `""` quotes, and commas/newlines INSIDE quotes. Self-contained
+ * (no external dep) — the get.gov CSV is small (~1.4 MB) so a whole-string parse is
+ * fine. Returns every record's raw field array (including the header row).
+ */
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let field = "";
+  let row: string[] = [];
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++; // consume the escaped quote
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      inQuotes = true;
+    } else if (c === ",") {
+      row.push(field);
+      field = "";
+    } else if (c === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else if (c === "\r") {
+      // CRLF: the \n case pushes the record; ignore the stray CR.
+    } else {
+      field += c;
+    }
+  }
+  // Flush a trailing field/row if the file did not end with a newline.
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** Coerce a CSV field to a trimmed non-empty string, else null (never ""). */
+function s(v: string | undefined): string | null {
+  if (v === undefined) return null;
+  const t = v.trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * Fetch + parse ONE scope's registry CSV into rows, memoized ~6h. Header-mapped by
+ * COLUMN NAME (not fixed index) so an upstream column reorder does not silently
+ * mis-map; a missing required header ⇒ schema_drift (never a fake-empty). The
+ * "Security contact email" column is dropped at the map step.
+ */
+async function loadRegistry(scope: GovDomainScope): Promise<GovDomainRow[]> {
+  return memoize(`getgov:${scope}`, async () => {
+    const url = `${DOTGOV_PATH_PREFIX}${DOTGOV_FILES[scope]}`;
+    // Belt-and-suspenders SSRF: the URL is built only from the pinned prefix +
+    // pinned filename, but assert it before the fetch.
+    const built = new URL(url);
+    if (built.hostname !== DOTGOV_HOST || built.protocol !== "https:") {
+      throw driftError(
+        SOURCE_LABEL,
+        `Constructed get.gov URL host ${JSON.stringify(built.hostname)} is not ${DOTGOV_HOST} over https — refusing to fetch (SSRF safety).`,
+      );
+    }
+    const text = await getText(url, { label: SOURCE_LABEL, redirect: "error", timeoutMs: 20_000 });
+    const rows = parseCsv(text);
+    const headerRow = rows[0];
+    if (!headerRow) {
+      throw driftError(SOURCE_LABEL, "get.gov registry CSV was empty — treating as schema drift, never a fake-empty result.");
+    }
+    const header = headerRow.map((h) => h.trim());
+    const idx = (name: string) => header.indexOf(name);
+    const iDomain = idx("Domain name");
+    const iType = idx("Domain type");
+    const iOrg = idx("Organization name");
+    const iSub = idx("Suborganization name");
+    const iCity = idx("City");
+    const iState = idx("State");
+    // The four load-bearing columns MUST be present (a rename ⇒ schema drift, not a
+    // silently mis-mapped/empty result).
+    if (iDomain < 0 || iType < 0 || iOrg < 0) {
+      throw driftError(
+        SOURCE_LABEL,
+        `get.gov registry CSV header is missing a required column (Domain name / Domain type / Organization name) — schema drift. Got: ${header.join(", ")}.`,
+      );
+    }
+    return rows.slice(1).map((r) => ({
+      domain: (r[iDomain] ?? "").trim(),
+      domainType: (r[iType] ?? "").trim(),
+      organization: (r[iOrg] ?? "").trim(),
+      suborganization: iSub >= 0 ? s(r[iSub]) : null,
+      city: iCity >= 0 ? s(r[iCity]) : null,
+      state: iState >= 0 ? s(r[iState]) : null,
+      // NOTE: "Security contact email" is deliberately NOT read/emitted.
+    }));
+  });
+}
+
+// ─── Tool: search_gov_domains ─────────────────────────────────────
+/**
+ * Search the CISA get.gov .gov domain registry. Client-side filters over the
+ * published CSV: organization/domain/city are case-insensitive SUBSTRING matches;
+ * state (2-letter) and domainType are case-insensitive. scope 'all' (federal + SLED,
+ * default) | 'federal'. Honest `_meta` (exact match total; provenance + client-side
+ * disclosure).
+ */
+export async function searchGovDomains(args: {
+  scope?: GovDomainScope;
+  organization?: string;
+  domain?: string;
+  domainType?: string;
+  state?: string;
+  city?: string;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  const scope: GovDomainScope = args.scope ?? "all";
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  const all = await loadRegistry(scope);
+
+  const filtersApplied: string[] = [];
+  const ci = (v: string | undefined) => (v ?? "").toLowerCase();
+  const orgQ = ci(args.organization);
+  const domQ = ci(args.domain);
+  const typeQ = ci(args.domainType);
+  const stateQ = ci(args.state);
+  const cityQ = ci(args.city);
+  if (args.organization !== undefined) filtersApplied.push("organization");
+  if (args.domain !== undefined) filtersApplied.push("domain");
+  if (args.domainType !== undefined) filtersApplied.push("domainType");
+  if (args.state !== undefined) filtersApplied.push("state");
+  if (args.city !== undefined) filtersApplied.push("city");
+
+  const matched = all.filter((row) => {
+    if (orgQ && !row.organization.toLowerCase().includes(orgQ)) return false;
+    if (domQ && !row.domain.toLowerCase().includes(domQ)) return false;
+    if (typeQ && !row.domainType.toLowerCase().includes(typeQ)) return false;
+    if (stateQ && (row.state ?? "").toLowerCase() !== stateQ) return false;
+    if (cityQ && !(row.city ?? "").toLowerCase().includes(cityQ)) return false;
+    return true;
+  });
+
+  const totalAvailable = matched.length;
+  const page = matched.slice(offset, offset + limit);
+  const returned = page.length;
+  const hasMore = offset + returned < totalAvailable;
+  const nextOffset = hasMore ? offset + returned : null;
+
+  return withMeta(
+    { scope, domains: page },
+    {
+      source: `getgov ${DOTGOV_FILES[scope]} (CISA .gov registry, keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      truncated: hasMore,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: ["securityContactEmail (org mailbox — intentionally excluded)"],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes: [PROVENANCE_NOTE, CLIENT_FILTER_NOTE, FRESHNESS_NOTE, EMAIL_DROP_NOTE],
+    } satisfies Partial<ResponseMeta>,
+  );
+}

package/src/keys.ts

@@ -3,7 +3,7 @@
  *
  * Why this exists
  * ----------------
- * The server rides 31 federal sources. MOST are fully keyless. But the set of
+ * The server rides dozens of federal data sources. MOST are fully keyless. But the set of
  * *optional* keys (raise a rate limit, unlock one filter) plus the four *required*
  * keys (Census business-patterns, FRED, BEA Regional, DOL data) has grown to the point where a user — or
  * the AI driving the server — cannot tell, without reading source code:
@@ -20,8 +20,9 @@
  * `process.env.<NAME>` — DATA_GOV_API_KEY (datagovKey.ts), SAM_GOV_API_KEY
  * (server.ts), BLS_API_KEY (bls.ts), NVD_API_KEY (nvd.ts), SOCRATA_APP_TOKEN
  * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts),
- * BEA_API_KEY (bea.ts), DOL_API_KEY (dol.ts), LDA_API_KEY (lda.ts). No invented
- * keys, sources, or signup URLs.
+ * BEA_API_KEY (bea.ts), DOL_API_KEY (dol.ts), LDA_API_KEY (lda.ts),
+ * OPENFDA_API_KEY (openfda.ts), COURTLISTENER_API_TOKEN (courtlistener.ts).
+ * No invented keys, sources, or signup URLs.
  */
 
 import { readFileSync } from "node:fs";
@@ -44,11 +45,11 @@ export type KeyRegistryEntry = {
 };
 
 /**
- * The 10 keys the server reads — code-grounded, no inventions.
+ * The 12 keys the server reads — code-grounded, no inventions.
  *
  * REQUIRED (4): CENSUS_API_KEY, FRED_API_KEY, BEA_API_KEY, DOL_API_KEY — those sources
  * have no keyless tier, so the tool throws without them (DOL_API_KEY gates ONLY
- * dol_get_dataset; the DOL catalog, dol_list_datasets, is keyless). OPTIONAL (6):
+ * dol_get_dataset; the DOL catalog, dol_list_datasets, is keyless). OPTIONAL (8):
  * everything else works keyless; a key only raises a rate limit or unlocks a single filter.
  */
 export const KEY_REGISTRY: readonly KeyRegistryEntry[] = [
@@ -131,7 +132,7 @@ export const KEY_REGISTRY: readonly KeyRegistryEntry[] = [
       "US DOL enforcement data (dol_get_dataset; dol_list_datasets is keyless)",
     ],
     required: true,
-    signupUrl: "https://dol.gov/developer",
+    signupUrl: "https://dataportal.dol.gov/registration",
     unlocks:
       "the dol_get_dataset tool (dataset records need a free key; dol_list_datasets works keyless)",
     note: "The DOL data endpoint needs a free key; the dataset CATALOG (dol_list_datasets) and agency list are keyless.",
@@ -145,6 +146,26 @@ export const KEY_REGISTRY: readonly KeyRegistryEntry[] = [
       "higher LDA API rate limits (anonymous access already works without it)",
     note: "Keyless by default (anonymous 200); a free token only raises the rate limit.",
   },
+  {
+    envVar: "OPENFDA_API_KEY",
+    sources: ["openFDA enforcement (openfda_enforcement)"],
+    required: false,
+    signupUrl: "https://open.fda.gov/apis/authentication/",
+    unlocks:
+      "higher openFDA rate limits (keyless works without it — ~1000/day)",
+    note: "Keyless by default; a free key raises the rate limit.",
+  },
+  {
+    envVar: "COURTLISTENER_API_TOKEN",
+    sources: [
+      "CourtListener federal court opinions (courtlistener_search_opinions)",
+    ],
+    required: false,
+    signupUrl: "https://www.courtlistener.com/help/api/rest/",
+    unlocks:
+      "higher CourtListener rate limits (anonymous search works without it)",
+    note: "Keyless by default (anonymous 200); a free token only raises the rate limit. Data = US federal court public records via CourtListener/Free Law Project.",
+  },
 ] as const;
 
 /** true iff the env var is set to a non-empty (after-trim) string. */

package/src/nhtsa.ts

@@ -0,0 +1,352 @@
+/**
+ * nhtsa.ts — NHTSA VEHICLE SAFETY (api.nhtsa.gov) — the vehicle / parts /
+ * fleet supplier PRODUCT-SAFETY vetting lane (ADR-0057). Two keyless tools:
+ *   • nhtsa_recalls    — /recalls/recallsByVehicle?make=&model=&modelYear=
+ *   • nhtsa_complaints — /complaints/complaintsByVehicle?make=&model=&modelYear=
+ * The cross-agency product-safety family alongside openFDA (medical) / CPSC
+ * (consumer goods): a manufacturer/component/safety-signal history for B2G
+ * supplier vetting.
+ *
+ * ★ KEYLESS — there is NO API key at all (no parameter, no header). This module
+ *   touches NO key seam (no KEY_REGISTRY / keys.ts / API_KEYS.md). It REUSES the
+ *   shared `getJson` (redirect:"error") / `driftError` fetch envelope, the `num`/
+ *   `str` coercions (null-never-empty-string; a genuine 0 stays 0), and
+ *   `withMeta`/`buildMeta` — and mirrors datagov-catalog.ts's fixed-host SSRF
+ *   idiom + schema_drift catch-ladder verbatim.
+ *
+ * ★ PII — the complaints upstream response carries a `vin` field (an individual
+ *   vehicle identifier). It is DELIBERATELY OMITTED from the curated output
+ *   entirely — never surfaced, logged, or stored. The B2G value is the
+ *   manufacturer / component / safety signal, NOT the VIN.
+ *
+ * ★ THE HONESTY PILLARS (P1-P4, live-verified 2026-07-15):
+ *   P1: totalAvailable = `Count` (recalls) / `count` (complaints) — the REAL total.
+ *       NHTSA returns the COMPLETE filtered set (no pagination), so in the normal
+ *       case Count === results.length ⇒ complete:true. totalAvailable is NEVER
+ *       fabricated: a PRESENT numeric Count is trusted verbatim; a MISSING Count
+ *       falls back to results.length WITH an honest note (never invented).
+ *   P2: results:[] (Count 0) ⇒ an HONEST EMPTY (returned:0, complete:true) — a bad
+ *       make/model that returns 200+Count 0 is an honest no-match, NOT an error. A
+ *       4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW (never a fake empty); a 200
+ *       non-JSON body ⇒ schema_drift.
+ *   P3: booleans (crash/fire/parkIt/parkOutSide/overTheAirUpdate) preserved AS
+ *       booleans (a non-boolean ⇒ null, never a fabricated false); counts
+ *       (numberOfInjuries/numberOfDeaths) via `num` (a genuine 0 stays 0, NEVER
+ *       null-for-0); dates as strings via `str`; Count/count via `num`.
+ *   P4: `results` non-array ⇒ driftError; a Count/count that is PRESENT but a
+ *       non-number ⇒ driftError (a broken total contract, never a fabricated empty).
+ *   SSRF: fixed host `api.nhtsa.gov` (compile-time literal) + post-construction
+ *       hostname/protocol assertion + redirect:"error"; make/model ride
+ *       URLSearchParams (module-built, no raw passthrough); modelYear is
+ *       ^\d{4}$; make/model are charclass-validated (letters/digits/space/hyphen,
+ *       so a `../` or `%` can never reach the fixed path).
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const NHTSA_HOST = "api.nhtsa.gov";
+const RECALLS_PATH = "/recalls/recallsByVehicle";
+const COMPLAINTS_PATH = "/complaints/complaintsByVehicle";
+// HOST+path-only labels (→ ToolError.upstreamEndpoint). Keyless ⇒ no token can
+// ever appear here regardless, but the labels stay host+path for consistency.
+const RECALLS_LABEL = "nhtsa:/recalls/recallsByVehicle";
+const COMPLAINTS_LABEL = "nhtsa:/complaints/complaintsByVehicle";
+
+// ─── Input validation grammar (SSRF + injection guard) ────────────
+// modelYear: exactly 4 digits. make/model: letters/digits/space/hyphen only —
+// rejects `../`, `%`, `/`, `.`, quotes, so a value can never break out of the
+// URLSearchParams-encoded query onto the fixed host/path.
+export const NHTSA_MODEL_YEAR_RE = /^\d{4}$/;
+export const NHTSA_MAKE_MODEL_RE = /^[A-Za-z0-9 -]+$/;
+
+const KEYLESS_NOTE =
+  "NHTSA is a keyless public API (api.nhtsa.gov) — no API key is required or accepted.";
+const COMPLETE_SET_NOTE =
+  "NHTSA returns the COMPLETE set of matching records for this make/model/modelYear (no pagination) — totalAvailable is the upstream Count, and returned should equal it.";
+
+// ─── Shared coercions ─────────────────────────────────────────────
+/** A genuine boolean preserved; anything else ⇒ null (never a fabricated false). */
+function bool(x: unknown): boolean | null {
+  return typeof x === "boolean" ? x : null;
+}
+
+// ─── Shared input validation ──────────────────────────────────────
+export type NhtsaVehicleArgs = {
+  make: string;
+  model: string;
+  modelYear: string;
+};
+
+/**
+ * Validate the shared make/model/modelYear inputs (belt-and-suspenders behind the
+ * server Zod; a DIRECT handler call bypasses Zod). Rejects a bad value PRE-fetch
+ * (0 network call) so a `../`/`%` can never reach the fixed host/path.
+ */
+function validateVehicleArgs(args: NhtsaVehicleArgs, label: string): void {
+  const checks: Array<[string, string, RegExp]> = [
+    ["make", args.make, NHTSA_MAKE_MODEL_RE],
+    ["model", args.model, NHTSA_MAKE_MODEL_RE],
+    ["modelYear", args.modelYear, NHTSA_MODEL_YEAR_RE],
+  ];
+  for (const [name, value, re] of checks) {
+    if (typeof value !== "string" || !re.test(value)) {
+      throw new ToolErrorCarrier({
+        kind: "invalid_input",
+        retryable: false,
+        message:
+          name === "modelYear"
+            ? `Invalid modelYear ${JSON.stringify(value)} — expected a 4-digit year (^\\d{4}$), e.g. "2020".`
+            : `Invalid ${name} ${JSON.stringify(value)} — expected letters/digits/space/hyphen only (^[A-Za-z0-9 -]+$), e.g. "honda".`,
+        upstreamEndpoint: label,
+      });
+    }
+  }
+}
+
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+/**
+ * GET one NHTSA JSON resource on the FIXED host. Builds
+ * `https://api.nhtsa.gov${path}?${params}`, asserts the CONSTRUCTED URL's
+ * hostname === the fixed host over https (belt-and-suspenders), and sets
+ * `redirect:"error"` (fail closed on any off-host 3xx). Keyless — no header/token.
+ */
+async function getNhtsa(
+  path: string,
+  label: string,
+  params: URLSearchParams,
+): Promise<unknown> {
+  const url = `https://${NHTSA_HOST}${path}?${params.toString()}`;
+  const built = new URL(url);
+  if (built.hostname !== NHTSA_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Constructed NHTSA URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(NHTSA_HOST)} over https — refusing to fetch (SSRF safety).`,
+      upstreamEndpoint: label,
+    });
+  }
+  return getJson(url, { label, redirect: "error" });
+}
+
+/** Build the shared make/model/modelYear query (module-built; no raw passthrough). */
+function vehicleParams(args: NhtsaVehicleArgs): URLSearchParams {
+  const params = new URLSearchParams();
+  params.set("make", args.make);
+  params.set("model", args.model);
+  params.set("modelYear", args.modelYear);
+  return params;
+}
+
+/**
+ * Fetch + parse a NHTSA resource, mirroring datagov-catalog's catch-ladder: a
+ * ToolErrorCarrier (host-assert / 4xx-5xx taxonomy) rethrows FIRST (preserving its
+ * kind); a 200 non-JSON `.json()` SyntaxError reclassifies to schema_drift; a bare
+ * error rethrows LAST.
+ */
+async function fetchNhtsa(
+  path: string,
+  label: string,
+  args: NhtsaVehicleArgs,
+): Promise<unknown> {
+  try {
+    return await getNhtsa(path, label, vehicleParams(args));
+  } catch (e) {
+    if (e instanceof ToolErrorCarrier) throw e;
+    if (e instanceof SyntaxError)
+      throw driftError(
+        label,
+        `NHTSA ${label} returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).`,
+      );
+    throw e;
+  }
+}
+
+/**
+ * Resolve the total from a Count/count field (P1/P4). A PRESENT numeric value is
+ * trusted verbatim; a MISSING (undefined/null) value falls back to results.length
+ * WITH an honest note (never fabricated); a PRESENT non-number ⇒ driftError (a
+ * broken total contract). Returns the total + the fallback flag.
+ */
+function resolveTotal(
+  rawCount: unknown,
+  returned: number,
+  label: string,
+): { total: number; fellBack: boolean } {
+  if (rawCount === undefined || rawCount === null) {
+    // P1 fallback — missing Count ⇒ results.length + an honest note.
+    return { total: returned, fellBack: true };
+  }
+  const n = num(rawCount);
+  if (n === null) {
+    // P4 — a PRESENT non-number Count is a broken contract, never a fake empty.
+    throw driftError(
+      label,
+      `NHTSA ${label} shape drift — the total count field is present but non-numeric.`,
+    );
+  }
+  return { total: n, fellBack: false };
+}
+
+// ─── Curated row shapes ───────────────────────────────────────────
+export type NhtsaRecall = {
+  campaignNumber: string | null;
+  manufacturer: string | null;
+  component: string | null;
+  summary: string | null;
+  consequence: string | null;
+  remedy: string | null;
+  reportReceivedDate: string | null;
+  parkIt: boolean | null;
+  parkOutside: boolean | null;
+  overTheAirUpdate: boolean | null;
+};
+
+export type NhtsaComplaint = {
+  odiNumber: string | null;
+  manufacturer: string | null;
+  component: string | null;
+  summary: string | null;
+  crash: boolean | null;
+  fire: boolean | null;
+  numberOfInjuries: number | null;
+  numberOfDeaths: number | null;
+  dateOfIncident: string | null;
+  dateComplaintFiled: string | null;
+};
+
+/** Map ONE /recallsByVehicle row → the curated recall shape. Booleans via `bool`. */
+function mapRecall(row: unknown): NhtsaRecall {
+  const r = (row ?? {}) as Record<string, unknown>;
+  return {
+    campaignNumber: str(r.NHTSACampaignNumber),
+    manufacturer: str(r.Manufacturer),
+    component: str(r.Component),
+    summary: str(r.Summary),
+    consequence: str(r.Consequence),
+    remedy: str(r.Remedy),
+    reportReceivedDate: str(r.ReportReceivedDate),
+    parkIt: bool(r.parkIt),
+    parkOutside: bool(r.parkOutSide),
+    overTheAirUpdate: bool(r.overTheAirUpdate),
+  };
+}
+
+/**
+ * Map ONE /complaintsByVehicle row → the curated complaint shape. ★The `vin` field
+ * is DELIBERATELY OMITTED (PII — never read into the output). Counts via `num` (a
+ * genuine 0 stays 0); booleans via `bool`.
+ */
+function mapComplaint(row: unknown): NhtsaComplaint {
+  const r = (row ?? {}) as Record<string, unknown>;
+  return {
+    odiNumber: str(r.odiNumber),
+    manufacturer: str(r.manufacturer),
+    component: str(r.components),
+    summary: str(r.summary),
+    crash: bool(r.crash),
+    fire: bool(r.fire),
+    numberOfInjuries: num(r.numberOfInjuries),
+    numberOfDeaths: num(r.numberOfDeaths),
+    dateOfIncident: str(r.dateOfIncident),
+    dateComplaintFiled: str(r.dateComplaintFiled),
+    // ★ NO vin — the PII field is never surfaced, logged, or stored.
+  };
+}
+
+const FILTERS_APPLIED = ["make", "model", "modelYear"];
+
+// ─── Tool: nhtsa_recalls ──────────────────────────────────────────
+/**
+ * Fetch NHTSA safety RECALLS for a make/model/modelYear → curated recall rows +
+ * honest `_meta`. KEYLESS. totalAvailable = the upstream `Count` (the REAL total —
+ * NHTSA returns the complete set, no pagination). A no-match (Count 0) ⇒ an honest
+ * empty; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON ⇒ drift.
+ */
+export async function recalls(args: NhtsaVehicleArgs): Promise<MetaBundle> {
+  validateVehicleArgs(args, RECALLS_LABEL);
+  const body = await fetchNhtsa(RECALLS_PATH, RECALLS_LABEL, args);
+
+  const b = (body ?? {}) as { Count?: unknown; results?: unknown };
+  // P4 — results MUST be an array (a missing/string/null results is drift).
+  if (!Array.isArray(b.results)) {
+    throw driftError(
+      RECALLS_LABEL,
+      `NHTSA ${RECALLS_LABEL} shape drift — results must be an array.`,
+    );
+  }
+  const recalls = (b.results as unknown[]).map(mapRecall);
+  const returned = recalls.length;
+  const { total, fellBack } = resolveTotal(b.Count, returned, RECALLS_LABEL);
+
+  const notes: string[] = [KEYLESS_NOTE, COMPLETE_SET_NOTE];
+  if (fellBack)
+    notes.push(
+      "NHTSA did not report a Count field — totalAvailable falls back to the number of returned rows (results.length); the true total may differ.",
+    );
+
+  return withMeta(
+    { recalls },
+    {
+      source: `${NHTSA_HOST} /recalls/recallsByVehicle (NHTSA vehicle safety recalls; keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable: total,
+      filtersApplied: FILTERS_APPLIED,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
+// ─── Tool: nhtsa_complaints ───────────────────────────────────────
+/**
+ * Fetch NHTSA consumer COMPLAINTS for a make/model/modelYear → curated complaint
+ * rows (★NO vin — PII omitted) + honest `_meta`. KEYLESS. totalAvailable = the
+ * upstream `count` (the REAL total). A no-match ⇒ honest empty; a 4xx ⇒
+ * invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON ⇒ drift.
+ */
+export async function complaints(args: NhtsaVehicleArgs): Promise<MetaBundle> {
+  validateVehicleArgs(args, COMPLAINTS_LABEL);
+  const body = await fetchNhtsa(COMPLAINTS_PATH, COMPLAINTS_LABEL, args);
+
+  const b = (body ?? {}) as { count?: unknown; results?: unknown };
+  // P4 — results MUST be an array (a missing/string/null results is drift).
+  if (!Array.isArray(b.results)) {
+    throw driftError(
+      COMPLAINTS_LABEL,
+      `NHTSA ${COMPLAINTS_LABEL} shape drift — results must be an array.`,
+    );
+  }
+  const complaints = (b.results as unknown[]).map(mapComplaint);
+  const returned = complaints.length;
+  const { total, fellBack } = resolveTotal(b.count, returned, COMPLAINTS_LABEL);
+
+  const notes: string[] = [
+    KEYLESS_NOTE,
+    COMPLETE_SET_NOTE,
+    "The NHTSA complaint VIN (an individual vehicle identifier) is intentionally EXCLUDED from this output (PII). The B2G signal is the manufacturer/component/crash/fire/injury/death safety history.",
+  ];
+  if (fellBack)
+    notes.push(
+      "NHTSA did not report a count field — totalAvailable falls back to the number of returned rows (results.length); the true total may differ.",
+    );
+
+  return withMeta(
+    { complaints },
+    {
+      source: `${NHTSA_HOST} /complaints/complaintsByVehicle (NHTSA vehicle safety complaints; keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable: total,
+      filtersApplied: FILTERS_APPLIED,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}