@cliwant/mcp-sam-gov 1.3.0 → 1.5.0

package/dist/nhtsa.js

@@ -0,0 +1,263 @@
+/**
+ * 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 } 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) {
+    return typeof x === "boolean" ? x : null;
+}
+/**
+ * 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, label) {
+    const checks = [
+        ["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, label, params) {
+    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) {
+    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, label, args) {
+    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, returned, label) {
+    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 };
+}
+/** Map ONE /recallsByVehicle row → the curated recall shape. Booleans via `bool`. */
+function mapRecall(row) {
+    const r = (row ?? {});
+    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) {
+    const r = (row ?? {});
+    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) {
+    validateVehicleArgs(args, RECALLS_LABEL);
+    const body = await fetchNhtsa(RECALLS_PATH, RECALLS_LABEL, args);
+    const b = (body ?? {});
+    // 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.map(mapRecall);
+    const returned = recalls.length;
+    const { total, fellBack } = resolveTotal(b.Count, returned, RECALLS_LABEL);
+    const notes = [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,
+    });
+}
+// ─── 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) {
+    validateVehicleArgs(args, COMPLAINTS_LABEL);
+    const body = await fetchNhtsa(COMPLAINTS_PATH, COMPLAINTS_LABEL, args);
+    const b = (body ?? {});
+    // 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.map(mapComplaint);
+    const returned = complaints.length;
+    const { total, fellBack } = resolveTotal(b.count, returned, COMPLAINTS_LABEL);
+    const notes = [
+        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,
+    });
+}
+//# sourceMappingURL=nhtsa.js.map

package/dist/nhtsa.js.map

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

package/dist/nist-controls.d.ts

@@ -0,0 +1,48 @@
+/**
+ * nist-controls.ts — NIST SP 800-53 Rev 5 security & privacy CONTROLS catalog
+ * (OSCAL, keyless). The cyber-compliance controls backbone for FedRAMP / CMMC / RMF
+ * work: look up a control (AC-2, SC-7, …) or a family (Access Control, System &
+ * Communications Protection, …) and get its title, requirement STATEMENT, discussion
+ * guidance, and control enhancements. No other tool here exposes the controls catalog
+ * (we have NVD CVEs + CISA KEV, but not the requirement side).
+ *
+ * SOURCE: NIST's OFFICIAL OSCAL content, published at github.com/usnistgov/oscal-content
+ * (the canonical machine-readable release; the .gov PDF is the human copy). NOT a
+ * .gov API host, so provenance is disclosed on every response (the ProPublica /
+ * CourtListener / get.gov republisher idiom — here NIST is the first-party author).
+ *
+ * PATTERN: the CISA-KEV static-file idiom (nvd.ts) — a fixed-host const URL fetched
+ * via getJson (redirect:"error" + 30s timeout), memoized 6h, with a plausibility
+ * FLOOR (a truncated catalog must NEVER read as "control not found"), then
+ * client-side filter/lookup. An outage/4xx/timeout THROWS (never a fake empty).
+ *
+ * SSRF: fixed host `raw.githubusercontent.com` + a fixed, pinned path (no free
+ * host/path). Filtering is CLIENT-SIDE over the parsed catalog.
+ */
+import { type MetaBundle } from "./meta.js";
+export declare const OSCAL_HOST = "raw.githubusercontent.com";
+export type NistControl = {
+    id: string;
+    family: string;
+    title: string;
+    statement: string;
+    guidance: string | null;
+    enhancements: {
+        id: string;
+        title: string;
+    }[];
+};
+/**
+ * Look up NIST SP 800-53 Rev 5 controls by controlId (exact, e.g. "AC-2"), family
+ * (exact family letter or name, e.g. "AC" / "Access Control"), and/or keyword
+ * (case-insensitive substring over title + statement). Client-side filters over the
+ * cached OSCAL catalog; honest `_meta` (exact match total; provenance disclosed).
+ */
+export declare function searchControls(args: {
+    controlId?: string;
+    family?: string;
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<MetaBundle>;
+//# sourceMappingURL=nist-controls.d.ts.map

package/dist/nist-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nist-controls.d.ts","sourceRoot":"","sources":["../src/nist-controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAEzE,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAkBtD,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C,CAAC;AAsGF;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqDtB"}

package/dist/nist-controls.js

@@ -0,0 +1,174 @@
+/**
+ * nist-controls.ts — NIST SP 800-53 Rev 5 security & privacy CONTROLS catalog
+ * (OSCAL, keyless). The cyber-compliance controls backbone for FedRAMP / CMMC / RMF
+ * work: look up a control (AC-2, SC-7, …) or a family (Access Control, System &
+ * Communications Protection, …) and get its title, requirement STATEMENT, discussion
+ * guidance, and control enhancements. No other tool here exposes the controls catalog
+ * (we have NVD CVEs + CISA KEV, but not the requirement side).
+ *
+ * SOURCE: NIST's OFFICIAL OSCAL content, published at github.com/usnistgov/oscal-content
+ * (the canonical machine-readable release; the .gov PDF is the human copy). NOT a
+ * .gov API host, so provenance is disclosed on every response (the ProPublica /
+ * CourtListener / get.gov republisher idiom — here NIST is the first-party author).
+ *
+ * PATTERN: the CISA-KEV static-file idiom (nvd.ts) — a fixed-host const URL fetched
+ * via getJson (redirect:"error" + 30s timeout), memoized 6h, with a plausibility
+ * FLOOR (a truncated catalog must NEVER read as "control not found"), then
+ * client-side filter/lookup. An outage/4xx/timeout THROWS (never a fake empty).
+ *
+ * SSRF: fixed host `raw.githubusercontent.com` + a fixed, pinned path (no free
+ * host/path). Filtering is CLIENT-SIDE over the parsed catalog.
+ */
+import { getJson, driftError } from "./datasource.js";
+import { memoize } from "./cache.js";
+import { withMeta } from "./meta.js";
+export const OSCAL_HOST = "raw.githubusercontent.com";
+const OSCAL_URL = "https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json";
+const OSCAL_LABEL = "nist-oscal:sp800-53r5";
+const OSCAL_TIMEOUT_MS = 30_000;
+const OSCAL_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+// Plausibility floor: 800-53 Rev5 has 20 control families and ~1000 controls. A
+// truncated catalog with far fewer must THROW, never read as "control not found".
+const FAMILY_FLOOR = 15;
+const PROVENANCE_NOTE = "Source: NIST SP 800-53 Rev 5 OSCAL catalog, published at github.com/usnistgov/oscal-content (NIST's canonical machine-readable release; authoritative first-party data served from GitHub, not a .gov API host).";
+const CLIENT_FILTER_NOTE = "The catalog has no query API — the full published OSCAL JSON is fetched (cached 6h) and filtered CLIENT-SIDE (controlId exact, family exact, keyword = case-insensitive substring over title+statement). totalAvailable is the EXACT match count.";
+const REFERENCE_NOTE = "This is the REQUIREMENT catalog (control text), NOT an assessment or an authorization. A control's applicability depends on the system's FIPS-199 impact baseline (Low/Moderate/High) and overlay — which this catalog does not encode.";
+/** OSCAL control id ("ac-2", "ac-2.1") → display id ("AC-2", "AC-2(1)"). */
+function displayId(rawId) {
+    const m = /^([a-z]+)-(\d+)(?:\.(\d+))?$/i.exec(rawId.trim());
+    if (!m)
+        return rawId.toUpperCase();
+    const fam = (m[1] ?? "").toUpperCase();
+    // Strip leading zeros so a zero-padded input ('AC-02') normalizes to the catalog's
+    // canonical unpadded form ('AC-2') — else an exact controlId lookup would miss.
+    const num = String(Number(m[2] ?? "0"));
+    const enh = m[3] !== undefined ? String(Number(m[3])) : undefined;
+    return enh !== undefined ? `${fam}-${num}(${enh})` : `${fam}-${num}`;
+}
+/** Recursively collect a statement part's prose as labelled, indented lines. */
+function collectProse(part, depth, out) {
+    const label = part.props?.find((p) => p.name === "label")?.value;
+    const indent = "  ".repeat(depth);
+    const prefix = label ? `${label} ` : "";
+    if (part.prose && part.prose.trim().length > 0) {
+        out.push(`${indent}${prefix}${part.prose.trim()}`);
+    }
+    else if (label) {
+        out.push(`${indent}${prefix}`.trimEnd());
+    }
+    for (const sub of part.parts ?? [])
+        collectProse(sub, depth + 1, out);
+}
+function partProse(control, name) {
+    const part = (control.parts ?? []).find((p) => p.name === name);
+    if (!part)
+        return null;
+    const out = [];
+    collectProse(part, 0, out);
+    const text = out.join("\n").trim();
+    return text.length > 0 ? text : null;
+}
+function mapControl(control, family) {
+    return {
+        id: displayId(control.id ?? ""),
+        family,
+        title: (control.title ?? "").trim(),
+        statement: partProse(control, "statement") ?? "",
+        guidance: partProse(control, "guidance"),
+        enhancements: (control.controls ?? []).map((e) => ({
+            id: displayId(e.id ?? ""),
+            title: (e.title ?? "").trim(),
+        })),
+    };
+}
+/**
+ * Fetch + parse the OSCAL catalog into a flat list of TOP-LEVEL controls, memoized
+ * 6h. Header/shape guarded: `catalog.groups` MUST be an array with ≥ FAMILY_FLOOR
+ * families (else driftError — a truncated catalog is NEVER a fake empty). Enhancements
+ * are carried on each control (not indexed as top-level entries).
+ */
+async function loadControls() {
+    return memoize("nist:sp800-53r5", async () => {
+        const built = new URL(OSCAL_URL);
+        if (built.hostname !== OSCAL_HOST || built.protocol !== "https:") {
+            throw driftError(OSCAL_LABEL, `Constructed OSCAL URL host ${JSON.stringify(built.hostname)} is not ${OSCAL_HOST} over https — refusing to fetch (SSRF safety).`);
+        }
+        const body = (await getJson(OSCAL_URL, {
+            label: OSCAL_LABEL,
+            redirect: "error",
+            timeoutMs: OSCAL_TIMEOUT_MS,
+        }));
+        const groups = body.catalog?.groups;
+        if (!Array.isArray(groups) || groups.length < FAMILY_FLOOR) {
+            throw driftError(OSCAL_LABEL, `OSCAL catalog.groups missing or implausibly small (${Array.isArray(groups) ? groups.length : "not-an-array"} < ${FAMILY_FLOOR} families) — treating as schema drift / truncation, never a fake-empty catalog.`);
+        }
+        const controls = [];
+        for (const g of groups) {
+            const family = `${(g.id ?? "").toUpperCase()} — ${(g.title ?? "").trim()}`;
+            for (const c of g.controls ?? [])
+                controls.push(mapControl(c, family));
+        }
+        return controls;
+    }, OSCAL_CACHE_TTL_MS);
+}
+// ─── Tool: nist_800_53_controls ───────────────────────────────────
+/**
+ * Look up NIST SP 800-53 Rev 5 controls by controlId (exact, e.g. "AC-2"), family
+ * (exact family letter or name, e.g. "AC" / "Access Control"), and/or keyword
+ * (case-insensitive substring over title + statement). Client-side filters over the
+ * cached OSCAL catalog; honest `_meta` (exact match total; provenance disclosed).
+ */
+export async function searchControls(args) {
+    const limit = args.limit ?? 25;
+    const offset = args.offset ?? 0;
+    const all = await loadControls();
+    const filtersApplied = [];
+    const idQ = args.controlId !== undefined ? displayId(args.controlId) : undefined;
+    const famQ = args.family?.trim().toLowerCase();
+    const kwQ = args.keyword?.trim().toLowerCase();
+    if (args.controlId !== undefined)
+        filtersApplied.push("controlId");
+    if (args.family !== undefined)
+        filtersApplied.push("family");
+    if (args.keyword !== undefined)
+        filtersApplied.push("keyword");
+    const matched = all.filter((c) => {
+        if (idQ && c.id.toUpperCase() !== idQ.toUpperCase())
+            return false;
+        if (famQ) {
+            // family field is "AC — Access Control"; match either the letter code or a
+            // substring of the title (both case-insensitive).
+            const fam = c.family.toLowerCase();
+            const code = (fam.split("—")[0] ?? "").trim();
+            if (code !== famQ && !fam.includes(famQ))
+                return false;
+        }
+        if (kwQ) {
+            // Search the title + requirement statement AND each enhancement's title, so a
+            // term that lives only in an enhancement (e.g. "multi-factor" → IA-2(1)) still
+            // surfaces the parent control. filtersApplied still lists 'keyword'.
+            const hay = `${c.title}\n${c.statement}\n${c.enhancements.map((e) => e.title).join("\n")}`.toLowerCase();
+            if (!hay.includes(kwQ))
+                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({ controls: page }, {
+        source: "NIST SP 800-53 Rev 5 (OSCAL catalog, keyless)",
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        truncated: hasMore,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes: [PROVENANCE_NOTE, CLIENT_FILTER_NOTE, REFERENCE_NOTE],
+    });
+}
+//# sourceMappingURL=nist-controls.js.map

package/dist/nist-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nist-controls.js","sourceRoot":"","sources":["../src/nist-controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,MAAM,CAAC,MAAM,UAAU,GAAG,2BAA2B,CAAC;AACtD,MAAM,SAAS,GACb,6HAA6H,CAAC;AAChI,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAC5C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC9C,gFAAgF;AAChF,kFAAkF;AAClF,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,MAAM,eAAe,GACnB,kNAAkN,CAAC;AACrN,MAAM,kBAAkB,GACtB,mPAAmP,CAAC;AACtP,MAAM,cAAc,GAClB,yOAAyO,CAAC;AA0B5O,4EAA4E;AAC5E,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,CAAC,GAAG,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,mFAAmF;IACnF,gFAAgF;IAChF,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;AACvE,CAAC;AAED,gFAAgF;AAChF,SAAS,YAAY,CAAC,IAAe,EAAE,KAAa,EAAE,GAAa;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,KAAK,CAAC;IACjE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;SAAM,IAAI,KAAK,EAAE,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE;QAAE,YAAY,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,SAAS,CAAC,OAAqB,EAAE,IAAY;IACpD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED,SAAS,UAAU,CAAC,OAAqB,EAAE,MAAc;IACvD,OAAO;QACL,EAAE,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;QAC/B,MAAM;QACN,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACnC,SAAS,EAAE,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE;QAChD,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC;QACxC,YAAY,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjD,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACzB,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;SAC9B,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,YAAY;IACzB,OAAO,OAAO,CACZ,iBAAiB,EACjB,KAAK,IAAI,EAAE;QACT,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,KAAK,CAAC,QAAQ,KAAK,UAAU,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjE,MAAM,UAAU,CAAC,WAAW,EAAE,8BAA8B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,UAAU,gDAAgD,CAAC,CAAC;QACnK,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,SAAS,EAAE;YACrC,KAAK,EAAE,WAAW;YAClB,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,gBAAgB;SAC5B,CAAC,CAAuC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YAC3D,MAAM,UAAU,CACd,WAAW,EACX,sDAAsD,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,MAAM,YAAY,iFAAiF,CAChN,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAkB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,MAAsB,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3E,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE;gBAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,EACD,kBAAkB,CACnB,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAMpC;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,MAAM,YAAY,EAAE,CAAC;IAEjC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAC/B,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,WAAW,EAAE;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,IAAI,EAAE,CAAC;YACT,2EAA2E;YAC3E,kDAAkD;YAClD,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,CAAC;QACzD,CAAC;QACD,IAAI,GAAG,EAAE,CAAC;YACR,8EAA8E;YAC9E,+EAA+E;YAC/E,qEAAqE;YACrE,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;YACzG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC;IACnD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,OAAO,QAAQ,CACb,EAAE,QAAQ,EAAE,IAAI,EAAE,EAClB;QACE,MAAM,EAAE,+CAA+C;QACvD,WAAW,EAAE,IAAI;QACjB,QAAQ;QACR,cAAc;QACd,SAAS,EAAE,OAAO;QAClB,cAAc;QACd,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;QAClD,KAAK,EAAE,CAAC,eAAe,EAAE,kBAAkB,EAAE,cAAc,CAAC;KAC7B,CAClC,CAAC;AACJ,CAAC"}

package/dist/nonprofit.d.ts

@@ -0,0 +1,116 @@
+/**
+ * nonprofit.ts — US TAX-EXEMPT NONPROFITS (IRS Form 990) — the nonprofit /
+ * grantee / subcontractor vetting lane (ADR-0060). Who a tax-exempt organization
+ * IS (EIN, NTEE code, subsection, ruling date, status) and what its Form 990
+ * FINANCIALS look like (revenue, expenses, assets, liabilities by tax year) —
+ * the 501(c) signal no contract/spending/grant/lobbying source carries.
+ *
+ * ★ PROVENANCE — THIS IS NOT A .gov API (must be disclosed). The DATA is IRS Form
+ *   990 filings — FEDERAL tax-exempt PUBLIC RECORDS — but the API is **ProPublica
+ *   Nonprofit Explorer**, operated by **ProPublica** (a non-profit newsroom) which
+ *   republishes those records KEYLESS. The IRS itself offers NO clean query API
+ *   (only bulk downloads / a web UI). So every response's `_meta.source` AND a note
+ *   name "IRS Form 990 data via ProPublica Nonprofit Explorer" — the tool NEVER
+ *   presents itself as a government API.
+ *
+ * ★ KEYLESS — no key of any kind. Anonymous GETs return HTTP 200. There is NO
+ *   KEY_REGISTRY / keys.ts / API_KEYS.md entry for this source.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code of its own: it REUSES
+ * `getJson` (the shared fetch envelope, redirect:"error") / `driftError` /
+ * `num`·`str` (coerce.ts, null-never-0/empty) / `withMeta`·`buildMeta`.
+ *
+ *   SEARCH  GET https://projects.propublica.org/nonprofits/api/v2/search.json
+ *       ?q=&state[id]=&ntee[id]=&page=
+ *     → { total_results, organizations:[{ ein, name, sub_name, city, state,
+ *          ntee_code, subseccd, score }], num_pages, cur_page, per_page,
+ *          page_offset }
+ *   DETAIL  GET https://projects.propublica.org/nonprofits/api/v2/organizations/{ein}.json
+ *     → { organization:{ ein, name, address, city, state, zipcode, ntee_code,
+ *          subsection_code, ruling_date, exempt_organization_status_code,
+ *          foundation_code }, filings_with_data:[{ tax_prd_yr, formtype, pdf_url,
+ *          totrevenue, totfuncexpns, totassetsend, totliabend }] }
+ *
+ * ★ HONESTY (ADR-0060 P1–P5):
+ *   [P1]   SEARCH totalAvailable = `total_results` (the API's REAL total for the
+ *          query) — NEVER organizations.length. Page pagination (page is 0-based):
+ *          hasMore = (cur_page+1) < num_pages; the next page number is surfaced in
+ *          a note. DETAIL totalAvailable = filings.length (the COMPLETE filing set
+ *          from the one detail doc — no pagination). Reverting the search total to
+ *          organizations.length must go RED.
+ *   [P2]   SEARCH a genuine no-match (organizations:[]) ⇒ honest empty (returned:0,
+ *          complete:true). DETAIL an unknown EIN (HTTP 404) ⇒ not_found (NEVER a
+ *          fabricated empty org). A 4xx ⇒ invalid_input; a 5xx/timeout ⇒
+ *          upstream_unavailable THROW; a 200 non-JSON ⇒ schema_drift.
+ *   [P3]   The four Form 990 figures (totrevenue/totfuncexpns/totassetsend/
+ *          totliabend) ride `num()` — a genuine 0 STAYS 0, an absent figure ⇒ null
+ *          (NEVER 0-faked). EIN + the codes are strings; ruling_date is a string.
+ *   [P4]   SEARCH `organizations` non-array OR `total_results` non-number ⇒
+ *          driftError. DETAIL `organization` non-object OR `filings_with_data`
+ *          non-array ⇒ driftError (never a fabricated empty/total).
+ *   [SSRF] fixed host `projects.propublica.org`; a post-construction hostname/
+ *          protocol assert + `redirect:"error"`; the query VALUES ride
+ *          URLSearchParams (incl. the `state[id]`/`ntee[id]` bracket keys);
+ *          `ein` charclass `^\d{1,9}$` (path segment); `state` `^[A-Za-z]{2}$`;
+ *          `ntee` an integer 1..10.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const NONPROFIT_HOST = "projects.propublica.org";
+export type NonprofitOrgSummary = {
+    ein: string | null;
+    name: string | null;
+    city: string | null;
+    state: string | null;
+    nteeCode: string | null;
+    subsectionCode: string | null;
+};
+export type NonprofitOrganization = {
+    ein: string | null;
+    name: string | null;
+    address: string | null;
+    city: string | null;
+    state: string | null;
+    zip: string | null;
+    nteeCode: string | null;
+    subsectionCode: string | null;
+    rulingDate: string | null;
+    statusCode: string | null;
+};
+export type NonprofitFiling = {
+    taxYear: number | null;
+    formType: string | null;
+    revenueUsd: number | null;
+    expensesUsd: number | null;
+    assetsUsd: number | null;
+    liabilitiesUsd: number | null;
+    pdfUrl: string | null;
+};
+export type NonprofitSearchArgs = {
+    query?: string;
+    state?: string;
+    ntee?: number;
+    page?: number;
+};
+/**
+ * Search US tax-exempt nonprofits (IRS Form 990) via ProPublica Nonprofit Explorer
+ * (`/nonprofits/api/v2/search.json`) → curated org summaries + honest `_meta`.
+ * KEYLESS. ★PROVENANCE: this is ProPublica (a non-profit newsroom) republishing
+ * IRS Form 990 public records — NOT a .gov API. ★totalAvailable is the API's REAL
+ * `total_results` — never organizations.length; page-based (0-indexed) pagination.
+ */
+export declare function search(args: NonprofitSearchArgs): Promise<MetaBundle>;
+export type NonprofitFinancialsArgs = {
+    ein: string;
+};
+/**
+ * Fetch ONE nonprofit's IRS Form 990 profile + financials via ProPublica Nonprofit
+ * Explorer (`/nonprofits/api/v2/organizations/{ein}.json`) → curated organization +
+ * filings + honest `_meta`. KEYLESS. ★PROVENANCE: ProPublica (a non-profit newsroom)
+ * republishing IRS Form 990 public records — NOT a .gov API. An unknown EIN (HTTP
+ * 404) ⇒ not_found (never a fabricated empty org). The four Form 990 figures ride
+ * num() (null-never-0). totalAvailable = filings.length (the COMPLETE set).
+ */
+export declare function financials(args: NonprofitFinancialsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=nonprofit.d.ts.map

package/dist/nonprofit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonprofit.d.ts","sourceRoot":"","sources":["../src/nonprofit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAiCxD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAiBF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAmCF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4H3E;AAGD,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAoGrB"}