@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

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>,
+  );
+}