@cliwant/mcp-sam-gov 1.3.0 → 1.4.0

package/dist/epa-envirofacts.js

@@ -0,0 +1,292 @@
+/**
+ * epa-envirofacts.ts — EPA Envirofacts RESTful data service (`data.epa.gov`,
+ * `/efservice`), the `tri_facility` table (ADR-0059). KEYLESS.
+ *
+ * WHAT IT ADDS: `epa_tri_facilities` — a location/compliance lane: look up EPA
+ * Toxics Release Inventory (TRI) reporting facilities by state / facility-name /
+ * county. This is the demand-side environmental-footprint complement to the
+ * market-sizing (Census CBP) and macro (FRED) sources — a place-of-performance
+ * environmental screen for a given geography.
+ *
+ * ★THE TWO-REQUEST PATTERN (the load-bearing P1 honesty): the efservice REST API
+ *   embeds filters as PATH SEGMENTS and reports NO total in the data slice. So the
+ *   EXACT total comes from a SEPARATE count sub-query — the identical filter path
+ *   with a `/count/JSON` tail returns `[{"TOTALQUERYRESULTS": 1247}]`. This tool
+ *   runs the count FIRST (best-effort) then the data slice: totalAvailable =
+ *   TOTALQUERYRESULTS (P1, EXACT), NEVER the returned rows' length. If the count
+ *   sub-query fails or is absent, totalAvailable falls to null + a disclosing note
+ *   (never a length-faked total) and the data slice still returns.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error") / `driftError` (datasource.ts), `str`/`num` (coerce.ts,
+ * null-never-empty-string / null-never-0), and `withMeta`·`buildMeta` (meta.ts,
+ * offset pagination + totalAvailable). It MIRRORS census-economic.ts's
+ * fixed-host SSRF idiom (a single host const + a post-construction hostname/
+ * protocol assertion + redirect:"error") and datagov-catalog.ts's schema_drift
+ * catch-ladder (ToolErrorCarrier rethrow FIRST so a 5xx keeps its taxonomy →
+ * SyntaxError→driftError → bare rethrow).
+ *
+ *   GET https://data.epa.gov/efservice/tri_facility/state_abbr/{ST}
+ *       [/facility_name/CONTAINING/{NAME}] [/county_name/CONTAINING/{COUNTY}]
+ *       /count/JSON               → [{ "TOTALQUERYRESULTS": <int> }]  (the total)
+ *   GET …same filter path… /rows/{offset}:{offset+limit-1}/JSON
+ *       → [{ tri_facility_id, facility_name, street_address, city_name,
+ *            county_name, state_abbr, zip_code, region, fac_closed_ind, … }, …]
+ *
+ * ★ SSRF (the load-bearing guard — values ride as PATH SEGMENTS, not query params):
+ *   the host is a compile-time literal (`EPA_HOST`); the table + column names + the
+ *   `CONTAINING` operator + `rows`/`count`/`JSON` are all MODULE literals. Every
+ *   USER value is BOTH charclass-validated (state `^[A-Za-z]{2}$`; facilityName/
+ *   county letters/digits/space/&/-/. only, rejecting `/` and `..` path-traversal)
+ *   AND `encodeURIComponent`-encoded before it joins the path. `offset`/`limit` are
+ *   coerced to non-negative integers. A post-construction hostname/protocol
+ *   assertion + `redirect:"error"` fail closed on any off-host 3xx.
+ *
+ * ★ HONESTY (ADR-0059 P1–P5, live-verified 2026-07-15 on data.epa.gov):
+ *   [input] require at least `state` OR `facilityName` — an all-empty query is
+ *           REFUSED with invalid_input (0 fetch) so the whole national table is
+ *           never scanned.
+ *   [P1]    totalAvailable = the count sub-query's TOTALQUERYRESULTS (EXACT — e.g.
+ *           VA = 1247), NOT the slice length. hasMore = offset+returned < total.
+ *           Count fails/absent ⇒ totalAvailable:null + a disclosing note.
+ *   [P2]    an empty array ⇒ honest empty (returned:0, complete:true). getJson maps
+ *           a 4xx/5xx via errorFromResponse and THROWS (503 ⇒ upstream_unavailable,
+ *           400 ⇒ invalid_input, 404 ⇒ not_found); a 200 non-array/non-JSON body ⇒
+ *           schema_drift (NEVER a fabricated empty).
+ *   [P3]    fac_closed_ind ("0"/"1" live; "N"/"Y" per the schema) ⇒ a normalized
+ *           boolean `closed` — an UNRECOGNIZED value ⇒ null (never a fabricated
+ *           false). Addresses/names are strings via `str` (null-never-empty-string).
+ *   [P4]    a data body that is not an array ⇒ driftError; a count body missing
+ *           TOTALQUERYRESULTS ⇒ totalAvailable:null (handled, not a crash).
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str, num } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercions (single audited copy in ./coerce.js) so a
+// regression fails together across sources. NO local num/str.
+export { num, str };
+// ─── SSRF core: the single fixed host + module-literal path pieces ──
+const EPA_HOST = "data.epa.gov";
+const EPA_TABLE = "tri_facility";
+// HOST+path label — surfaces in ToolError.upstreamEndpoint; keyless, so no token
+// can ever appear here.
+const EPA_LABEL = "epa-envirofacts:/efservice/tri_facility";
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+// state rides as a PATH SEGMENT → strictly 2 ASCII letters (the efservice filter is
+// case-insensitive; live-verified `va` === `VA`).
+const STATE_RE = /^[A-Za-z]{2}$/;
+// facilityName / county ride as PATH SEGMENTS after `.../CONTAINING/`. Allow only
+// letters / digits / space / & / - / . (a superset of real facility names); this
+// REJECTS `/` (path injection) and any other separator. `..` path-traversal is
+// rejected explicitly below (the charclass permits a lone `.`, so `..` must be
+// caught separately).
+const NAME_RE = /^[A-Za-z0-9 &.\-]+$/;
+const NAME_MAX = 100;
+const LIMIT_MIN = 1;
+const LIMIT_MAX = 100;
+const LIMIT_DEFAULT = 25;
+// ─── Honesty notes (ADR-0059 required set) ────────────────────────
+const CLOSED_NOTE = "`closed` is the normalized EPA fac_closed_ind ('0'/'N' → false = active, '1'/'Y' → true = closed); an unrecognized value is null (unknown), NEVER a fabricated false. A closed facility no longer actively reports to TRI.";
+const NOMINAL_NOTE = "These are EPA TRI (Toxics Release Inventory) REPORTING facilities for the geography — a nominal environmental-footprint screen, NOT a compliance, enforcement, or violation determination. Use ECHO / enforcement sources for compliance status.";
+const COUNT_FALLBACK_NOTE = "The count sub-query (…/count/JSON) failed or did not report TOTALQUERYRESULTS, so totalAvailable is null (unknown) — it was NOT faked from the returned row count. hasMore is a heuristic (a full page ⇒ likely more); re-page with offset to confirm.";
+/**
+ * Normalize EPA's fac_closed_ind to a boolean. Live values are "0" (active) / "1"
+ * (closed); the schema also documents "N"/"Y". Anything else ⇒ null (unknown) —
+ * NEVER a fabricated false (P3).
+ */
+export function normalizeClosed(v) {
+    const s = str(v);
+    if (s === null)
+        return null;
+    const t = s.toUpperCase();
+    if (t === "1" || t === "Y" || t === "YES" || t === "TRUE")
+        return true;
+    if (t === "0" || t === "N" || t === "NO" || t === "FALSE")
+        return false;
+    return null;
+}
+/** Map ONE efservice row → the curated facility shape (every scalar via `str`). */
+function mapFacility(row) {
+    const r = (row ?? {});
+    return {
+        triFacilityId: str(r.tri_facility_id),
+        facilityName: str(r.facility_name),
+        streetAddress: str(r.street_address),
+        city: str(r.city_name),
+        county: str(r.county_name),
+        state: str(r.state_abbr),
+        zip: str(r.zip_code),
+        region: str(r.region),
+        closed: normalizeClosed(r.fac_closed_ind),
+    };
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect:"error") ──
+/**
+ * GET one efservice JSON resource at a MODULE-BUILT path (all user values already
+ * charclass-validated + encodeURIComponent-encoded by the caller). Builds
+ * `https://${EPA_HOST}${path}` on the FIXED host, asserts the CONSTRUCTED URL's
+ * hostname === the host over https (belt-and-suspenders), and sets
+ * `redirect:"error"` (an off-host 3xx must NOT be followed). Keyless — no headers.
+ */
+async function getEpa(path) {
+    const url = `https://${EPA_HOST}${path}`;
+    const built = new URL(url);
+    if (built.hostname !== EPA_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed EPA Envirofacts URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(EPA_HOST)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: EPA_LABEL,
+        });
+    }
+    return getJson(built.toString(), { label: EPA_LABEL, redirect: "error" });
+}
+/** Validate + encode ONE user path-segment value (facilityName / county). */
+function validateName(value, field) {
+    if (value.length > NAME_MAX || !NAME_RE.test(value) || value.includes("..")) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid ${field} ${JSON.stringify(value)} — allowed: letters, digits, space, & - . (≤${NAME_MAX} chars); '/' and '..' are rejected (it rides in the request PATH as a segment; it is strictly validated to prevent path injection).`,
+            upstreamEndpoint: EPA_LABEL,
+        });
+    }
+    return encodeURIComponent(value);
+}
+/**
+ * Look up EPA TRI reporting facilities by state / facilityName / county →
+ * normalized facility rows + honest `_meta`. Requires at least `state` OR
+ * `facilityName` (an all-empty query is refused). Runs a count sub-query FIRST for
+ * the EXACT total (P1), then the data slice; a count failure degrades to
+ * totalAvailable:null + a note (never a length-faked total).
+ */
+export async function triFacilities(args) {
+    // ── [input guard] require at least state OR facilityName (never scan the whole
+    //    national table). ──
+    const hasState = args.state !== undefined && args.state !== "";
+    const hasName = args.facilityName !== undefined && args.facilityName !== "";
+    if (!hasState && !hasName) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "epa_tri_facilities requires at least `state` (2-letter, e.g. 'VA') OR `facilityName` — an all-empty query would scan the entire national TRI table and is refused. Add a filter and retry.",
+            upstreamEndpoint: EPA_LABEL,
+        });
+    }
+    // ── Validate + build the filter path segments (SSRF: charclass + encode each). ──
+    const segments = ["efservice", EPA_TABLE];
+    const filtersApplied = [];
+    if (hasState) {
+        const state = args.state;
+        if (!STATE_RE.test(state)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid state ${JSON.stringify(state)} — expected a 2-letter state code (^[A-Za-z]{2}$), e.g. "VA" (it rides in the request PATH; it is strictly validated).`,
+                upstreamEndpoint: EPA_LABEL,
+            });
+        }
+        segments.push("state_abbr", encodeURIComponent(state));
+        filtersApplied.push(`state:${state}`);
+    }
+    if (hasName) {
+        const enc = validateName(args.facilityName, "facilityName");
+        segments.push("facility_name", "CONTAINING", enc);
+        filtersApplied.push(`facilityName~${args.facilityName}`);
+    }
+    if (args.county !== undefined && args.county !== "") {
+        const enc = validateName(args.county, "county");
+        segments.push("county_name", "CONTAINING", enc);
+        filtersApplied.push(`county~${args.county}`);
+    }
+    // ── Coerce limit / offset to non-negative integers (belt-and-suspenders behind
+    //    the server Zod; a DIRECT handler call bypasses Zod). ──
+    let limit = LIMIT_DEFAULT;
+    if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
+        limit = Math.trunc(args.limit);
+        if (limit < LIMIT_MIN)
+            limit = LIMIT_MIN;
+        if (limit > LIMIT_MAX)
+            limit = LIMIT_MAX;
+    }
+    let offset = 0;
+    if (typeof args.offset === "number" && Number.isFinite(args.offset) && args.offset > 0) {
+        offset = Math.trunc(args.offset);
+    }
+    const filterPath = "/" + segments.join("/");
+    // ── (1) The COUNT sub-query FIRST (best-effort — the EXACT total, P1). Any
+    //    failure (network/5xx/drift/missing field) degrades to totalAvailable:null +
+    //    a disclosing note; it NEVER throws and NEVER fakes the total from the slice
+    //    length. ──
+    let totalAvailable = null;
+    let countFailed = false;
+    try {
+        const countBody = await getEpa(`${filterPath}/count/JSON`);
+        if (Array.isArray(countBody) &&
+            countBody.length > 0 &&
+            countBody[0] !== null &&
+            typeof countBody[0] === "object") {
+            const t = num(countBody[0].TOTALQUERYRESULTS);
+            if (t !== null && t >= 0) {
+                totalAvailable = t;
+            }
+            else {
+                countFailed = true; // present body but no usable TOTALQUERYRESULTS (P4)
+            }
+        }
+        else {
+            countFailed = true; // count body not the expected [{...}] shape
+        }
+    }
+    catch {
+        countFailed = true; // any count error ⇒ degrade, never propagate (P1)
+    }
+    // ── (2) The DATA slice — the authoritative request. efservice rows are INCLUSIVE
+    //    on both ends: rows/{offset}:{offset+limit-1}. Its errors follow P2. ──
+    const end = offset + limit - 1;
+    const dataPath = `${filterPath}/rows/${offset}:${end}/JSON`;
+    // Catch-ladder (datagov-catalog shape, VERBATIM): preserve the 4xx/5xx/timeout
+    // ToolErrorCarrier taxonomy FIRST; reclassify a 200 non-JSON SyntaxError to
+    // schema_drift SECOND; bare-rethrow LAST.
+    let body;
+    try {
+        body = await getEpa(dataPath);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(EPA_LABEL, "EPA Envirofacts returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        throw e;
+    }
+    // [P4] the data body MUST be an array (a non-array 200 is drift, never a
+    // fabricated empty).
+    if (!Array.isArray(body)) {
+        throw driftError(EPA_LABEL, "EPA Envirofacts shape drift — the /rows/…/JSON response must be a JSON array of facilities.");
+    }
+    const facilities = body.map(mapFacility);
+    const returned = facilities.length;
+    // ── [P1] pagination. total known ⇒ hasMore = offset+returned < total; total
+    //    unknown (count degraded) ⇒ a full page is the honest heuristic for "more". ──
+    const hasMore = totalAvailable !== null
+        ? offset + returned < totalAvailable
+        : returned === limit;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [CLOSED_NOTE, NOMINAL_NOTE];
+    if (countFailed)
+        notes.push(COUNT_FALLBACK_NOTE);
+    const meta = {
+        source: `${EPA_HOST} EPA Envirofacts /efservice/${EPA_TABLE} (TRI facilities; keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes,
+    };
+    return withMeta({ facilities }, meta);
+}
+//# sourceMappingURL=epa-envirofacts.js.map

package/dist/epa-envirofacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epa-envirofacts.js","sourceRoot":"","sources":["../src/epa-envirofacts.ts"],"names":[],"mappings":"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"}

package/dist/fred.d.ts

@@ -8,7 +8,7 @@
  *   FRED has NO keyless tier: every request needs `&api_key=`, and a missing/bad
  *   key returns HTTP 400 `{error_code, error_message}`. So, honestly: with NO
  *   `FRED_API_KEY` these two tools THROW an `invalid_input` config error BEFORE any
- *   fetch (never a fake-empty, never a keyless-pretend). The other 112 tools stay
+ *   fetch (never a fake-empty, never a keyless-pretend). The other tools stay
  *   keyless — this key is scoped to this one source. (Contrast the OPTIONAL keys of
  *   datagov/bls/nvd, which lift a tier but are not required.)
  *

package/dist/fred.js

@@ -8,7 +8,7 @@
  *   FRED has NO keyless tier: every request needs `&api_key=`, and a missing/bad
  *   key returns HTTP 400 `{error_code, error_message}`. So, honestly: with NO
  *   `FRED_API_KEY` these two tools THROW an `invalid_input` config error BEFORE any
- *   fetch (never a fake-empty, never a keyless-pretend). The other 112 tools stay
+ *   fetch (never a fake-empty, never a keyless-pretend). The other tools stay
  *   keyless — this key is scoped to this one source. (Contrast the OPTIONAL keys of
  *   datagov/bls/nvd, which lift a tier but are not required.)
  *

package/dist/keys.d.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.
  */
 /** One registry entry describing a single API key the server can use. */
 export type KeyRegistryEntry = {
@@ -39,11 +40,11 @@ export type KeyRegistryEntry = {
     note: string;
 };
 /**
- * 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 declare const KEY_REGISTRY: readonly KeyRegistryEntry[];

package/dist/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EA8F1C,CAAC;AAQX,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAErE,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,sFAAsF;IACtF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAYjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4C/C"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EAkH1C,CAAC;AAQX,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAErE,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,sFAAsF;IACtF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAYjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4C/C"}

package/dist/keys.js

@@ -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,17 +20,18 @@
  * `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";
 import { join } from "node:path";
 /**
- * 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 = [
@@ -106,7 +107,7 @@ export const KEY_REGISTRY = [
             "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.",
     },
@@ -118,6 +119,24 @@ export const KEY_REGISTRY = [
         unlocks: "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.",
+    },
 ];
 /** true iff the env var is set to a non-empty (after-trim) string. */
 function isSet(envVar) {

package/dist/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/dist/nhtsa.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { type MetaBundle } from "./meta.js";
+export declare const NHTSA_HOST = "api.nhtsa.gov";
+export declare const NHTSA_MODEL_YEAR_RE: RegExp;
+export declare const NHTSA_MAKE_MODEL_RE: RegExp;
+export type NhtsaVehicleArgs = {
+    make: string;
+    model: string;
+    modelYear: string;
+};
+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;
+};
+/**
+ * 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 declare function recalls(args: NhtsaVehicleArgs): Promise<MetaBundle>;
+/**
+ * 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 declare function complaints(args: NhtsaVehicleArgs): Promise<MetaBundle>;
+//# sourceMappingURL=nhtsa.d.ts.map

package/dist/nhtsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nhtsa.d.ts","sourceRoot":"","sources":["../src/nhtsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAGzE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAY1C,eAAO,MAAM,mBAAmB,QAAY,CAAC;AAC7C,eAAO,MAAM,mBAAmB,QAAqB,CAAC;AActD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAiHF,MAAM,MAAM,WAAW,GAAG;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,CAAC;AA4CF;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCzE;AAGD;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAuC5E"}