@cliwant/mcp-sam-gov 1.3.0 → 1.5.0

package/src/nist-controls.ts

@@ -0,0 +1,219 @@
+/**
+ * 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, type MetaBundle, type ResponseMeta } 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.";
+
+// ─── Parsed shapes ────────────────────────────────────────────────
+export type NistControl = {
+  id: string; // display form, e.g. "AC-2"
+  family: string; // e.g. "AC — Access Control"
+  title: string;
+  statement: string; // assembled requirement prose (labelled, multi-line)
+  guidance: string | null; // discussion prose
+  enhancements: { id: string; title: string }[]; // e.g. AC-2(1)
+};
+
+type OscalPart = {
+  name?: string;
+  prose?: string;
+  props?: { name?: string; value?: string }[];
+  parts?: OscalPart[];
+};
+type OscalControl = {
+  id?: string;
+  title?: string;
+  parts?: OscalPart[];
+  controls?: OscalControl[];
+};
+type OscalGroup = { id?: string; title?: string; controls?: OscalControl[] };
+
+/** OSCAL control id ("ac-2", "ac-2.1") → display id ("AC-2", "AC-2(1)"). */
+function displayId(rawId: string): string {
+  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: OscalPart, depth: number, out: string[]): void {
+  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: OscalControl, name: string): string | null {
+  const part = (control.parts ?? []).find((p) => p.name === name);
+  if (!part) return null;
+  const out: string[] = [];
+  collectProse(part, 0, out);
+  const text = out.join("\n").trim();
+  return text.length > 0 ? text : null;
+}
+
+function mapControl(control: OscalControl, family: string): NistControl {
+  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(): Promise<NistControl[]> {
+  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,
+      })) as { catalog?: { groups?: unknown } };
+      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: NistControl[] = [];
+      for (const g of groups as OscalGroup[]) {
+        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: {
+  controlId?: string;
+  family?: string;
+  keyword?: string;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  const limit = args.limit ?? 25;
+  const offset = args.offset ?? 0;
+  const all = await loadControls();
+
+  const filtersApplied: string[] = [];
+  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],
+    } satisfies Partial<ResponseMeta>,
+  );
+}

package/src/nonprofit.ts

@@ -0,0 +1,460 @@
+/**
+ * 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 { 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";
+
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so a `num` regression fails together across sources.
+export { num };
+
+// ─── SSRF core: the single fixed host + base path ─────────────────
+export const NONPROFIT_HOST = "projects.propublica.org";
+const NONPROFIT_BASE = "/nonprofits/api/v2";
+// HOST+path labels — surface in ToolError.upstreamEndpoint. No token exists for
+// this keyless source, so no secret can ever appear here.
+const NONPROFIT_SEARCH_LABEL = "propublica-nonprofit:/nonprofits/api/v2/search";
+const NONPROFIT_ORG_LABEL = "propublica-nonprofit:/nonprofits/api/v2/organizations";
+
+// ─── Validation (SSRF + "verify the input" honesty) ───────────────
+const STATE_RE = /^[A-Za-z]{2}$/; // a 2-letter US state/territory code
+const EIN_RE = /^\d{1,9}$/; // a numeric EIN (1..9 digits), rides the PATH
+// ★ProPublica's not-found SENTINEL (live-verified, NOT in the ADR): an EIN with no
+// matching IRS record does NOT always 404 — an in-range unknown EIN (e.g. 999999999)
+// returns HTTP 200 carrying a SYNTHETIC placeholder org `{ name:"Unknown Organization",
+// …all-null }` with ZERO filings_with_data. Surfacing that verbatim would present a
+// FABRICATED empty org as a real hit (a P2 honesty violation). We detect the exact
+// sentinel name + empty structured filings and map it to not_found, EXACTLY like a 404.
+const PROPUBLICA_NOT_FOUND_NAME = "Unknown Organization";
+const NTEE_MIN = 1;
+const NTEE_MAX = 10; // the NTEE major-category filter, 1..10
+const DEFAULT_PAGE = 0; // the API's page is 0-BASED
+const FALLBACK_PER_PAGE = 25; // the API's fixed page size (~25); a defensive fallback
+
+// ─── Honesty notes (ADR-0060 required set) ────────────────────────
+const PROVENANCE_NOTE =
+  "Data = IRS Form 990 filings (federal tax-exempt public records), served by ProPublica Nonprofit Explorer (ProPublica, a non-profit newsroom, which republishes them keyless) — NOT a .gov API. The IRS itself has no clean query API (only bulk downloads / a web UI). Treat figures as of ProPublica's last IRS ingest.";
+const SEARCH_TOTAL_NOTE =
+  "totalAvailable is the API's real total_results — the total match count for the query (NOT the organizations on this page). Pagination is page-based and 0-INDEXED (pass page=cur_page+1 for the next page while hasMore).";
+const FINANCIALS_TOTAL_NOTE =
+  "totalAvailable is filings.length — the COMPLETE set of Form 990 filings-with-data carried by this organization's detail document (there is no pagination; this is the whole set, not a page).";
+const FINANCIALS_MONEY_NOTE =
+  "revenueUsd / expensesUsd / assetsUsd / liabilitiesUsd are parsed from the Form 990 totrevenue / totfuncexpns / totassetsend / totliabend. A genuine reported 0 is preserved as 0; an absent figure maps to null — NEVER 0.";
+
+// ─── Curated search shape ─────────────────────────────────────────
+export type NonprofitOrgSummary = {
+  ein: string | null;
+  name: string | null;
+  city: string | null;
+  state: string | null;
+  nteeCode: string | null; // ntee_code (the NTEE classification, e.g. "E21")
+  subsectionCode: string | null; // subseccd (the 501(c) subsection code)
+};
+
+/** Map ONE search `organizations[]` row → the curated summary shape. */
+function mapOrgSummary(raw: unknown): NonprofitOrgSummary {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  return {
+    // EIN + codes are IDENTIFIERS ⇒ strings (never num-coerced).
+    ein: str(o.ein),
+    name: str(o.name),
+    city: str(o.city),
+    state: str(o.state),
+    nteeCode: str(o.ntee_code),
+    subsectionCode: str(o.subseccd),
+  };
+}
+
+// ─── Curated financials shapes ────────────────────────────────────
+export type NonprofitOrganization = {
+  ein: string | null;
+  name: string | null;
+  address: string | null;
+  city: string | null;
+  state: string | null;
+  zip: string | null; // zipcode
+  nteeCode: string | null; // ntee_code
+  subsectionCode: string | null; // subsection_code
+  rulingDate: string | null; // ruling_date (a date STRING — never coerced)
+  statusCode: string | null; // exempt_organization_status_code
+};
+
+export type NonprofitFiling = {
+  taxYear: number | null; // tax_prd_yr (a filing year)
+  formType: string | null; // formtype
+  revenueUsd: number | null; // totrevenue — null-never-0
+  expensesUsd: number | null; // totfuncexpns — null-never-0
+  assetsUsd: number | null; // totassetsend — null-never-0
+  liabilitiesUsd: number | null; // totliabend — null-never-0
+  pdfUrl: string | null; // pdf_url (the scanned Form 990 PDF)
+};
+
+/** Map the detail `organization` object → the curated organization shape. */
+function mapOrganization(raw: unknown): NonprofitOrganization {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  return {
+    ein: str(o.ein),
+    name: str(o.name),
+    address: str(o.address),
+    city: str(o.city),
+    state: str(o.state),
+    zip: str(o.zipcode),
+    nteeCode: str(o.ntee_code),
+    subsectionCode: str(o.subsection_code),
+    rulingDate: str(o.ruling_date),
+    statusCode: str(o.exempt_organization_status_code),
+  };
+}
+
+/** Map ONE `filings_with_data[]` row → the curated filing shape (money via num). */
+function mapFiling(raw: unknown): NonprofitFiling {
+  const f = (raw ?? {}) as Record<string, unknown>;
+  return {
+    taxYear: num(f.tax_prd_yr),
+    formType: str(f.formtype),
+    // [P3] a genuine 0 STAYS 0; absent ⇒ null (NEVER 0-faked).
+    revenueUsd: num(f.totrevenue),
+    expensesUsd: num(f.totfuncexpns),
+    assetsUsd: num(f.totassetsend),
+    liabilitiesUsd: num(f.totliabend),
+    pdfUrl: str(f.pdf_url),
+  };
+}
+
+// ─── Tool: nonprofit_search ───────────────────────────────────────
+export type NonprofitSearchArgs = {
+  query?: string; // → q
+  state?: string; // 2-letter → state[id]
+  ntee?: number; // 1..10 → ntee[id]
+  page?: number; // ≥0, default 0 (the API's page is 0-based)
+};
+
+/**
+ * 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 async function search(args: NonprofitSearchArgs): Promise<MetaBundle> {
+  const label = NONPROFIT_SEARCH_LABEL;
+
+  // ── Validate + default (belt-and-suspenders behind the server Zod; a DIRECT
+  //    handler call bypasses Zod). state/ntee/page are charclass/range-guarded;
+  //    the free-text query rides URLSearchParams (encoded). ──
+  if (args.state !== undefined && !STATE_RE.test(args.state)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid state ${JSON.stringify(args.state)} — expected a 2-letter US state/territory code (^[A-Za-z]{2}$), e.g. "VA".`,
+      upstreamEndpoint: label,
+    });
+  }
+  if (
+    args.ntee !== undefined &&
+    (!Number.isInteger(args.ntee) || args.ntee < NTEE_MIN || args.ntee > NTEE_MAX)
+  ) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid ntee ${JSON.stringify(args.ntee)} — expected an integer NTEE major category 1..10.`,
+      upstreamEndpoint: label,
+    });
+  }
+  const page = clampPage(args.page);
+
+  // ── Build the query from VALIDATED typed args, key-by-key (SSRF: no raw
+  //    passthrough; every VALUE is URLSearchParams-encoded, incl. the bracket keys
+  //    `state[id]`/`ntee[id]`). ──
+  const params = new URLSearchParams();
+  const filtersApplied: string[] = [];
+  if (args.query !== undefined && args.query !== "") {
+    params.set("q", args.query);
+    filtersApplied.push("query");
+  }
+  if (args.state !== undefined) {
+    params.set("state[id]", args.state.toUpperCase());
+    filtersApplied.push("state");
+  }
+  if (args.ntee !== undefined) {
+    params.set("ntee[id]", String(args.ntee));
+    filtersApplied.push("ntee");
+  }
+  params.set("page", String(page));
+
+  const url = `https://${NONPROFIT_HOST}${NONPROFIT_BASE}/search.json?${params.toString()}`;
+  assertOnHost(url, label);
+
+  // ── Fetch through the shared envelope. redirect:"error" fails closed on any
+  //    off-host 3xx. A 4xx ⇒ invalid_input; a 5xx/timeout ⇒ upstream_unavailable
+  //    THROW; a 429 ⇒ rate_limited THROW; a 200 non-JSON ⇒ getJson's r.json()
+  //    throws a SyntaxError ⇒ schema_drift. ──
+  let body: unknown;
+  try {
+    body = await getJson<unknown>(url, { label, redirect: "error" });
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw driftError(
+        label,
+        "ProPublica Nonprofit search returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).",
+      );
+    }
+    throw e; // 5xx → upstream_unavailable, 4xx → invalid_input, 429 → rate_limited …
+  }
+
+  // ── [P4] `organizations` MUST be an array and `total_results` MUST be a number
+  //    (a missing/wrong-typed either is drift, never a fabricated empty/total). ──
+  const b = (body ?? {}) as {
+    organizations?: unknown;
+    total_results?: unknown;
+    num_pages?: unknown;
+    cur_page?: unknown;
+    per_page?: unknown;
+    page_offset?: unknown;
+  };
+  if (!Array.isArray(b.organizations)) {
+    throw driftError(
+      label,
+      "ProPublica Nonprofit search shape drift — `organizations` must be an array.",
+    );
+  }
+  if (typeof b.total_results !== "number" || !Number.isFinite(b.total_results)) {
+    throw driftError(
+      label,
+      "ProPublica Nonprofit search shape drift — `total_results` (the total match count) must be a number.",
+    );
+  }
+
+  const organizations = (b.organizations as unknown[]).map(mapOrgSummary);
+  const returned = organizations.length;
+
+  // ── [P1] totalAvailable is the API's REAL total_results, NEVER organizations.length.
+  //    Page-based + 0-INDEXED: hasMore = (cur_page+1) < num_pages; surface the next
+  //    page. cur_page/num_pages/per_page/page_offset via num() (defensive fallbacks). ──
+  const totalAvailable = b.total_results;
+  const curPage = num(b.cur_page) ?? page;
+  const numPages = num(b.num_pages);
+  const perPage = num(b.per_page) ?? (returned > 0 ? returned : FALLBACK_PER_PAGE);
+  const hasMore = numPages !== null ? curPage + 1 < numPages : false;
+  const offset = num(b.page_offset) ?? curPage * perPage;
+  const nextOffset = hasMore ? (curPage + 1) * perPage : null;
+
+  const notes: string[] = [PROVENANCE_NOTE, SEARCH_TOTAL_NOTE];
+  if (hasMore && numPages !== null) {
+    notes.push(
+      `This is page ${curPage} (0-indexed) of ${numPages} — pass page=${curPage + 1} for the next page.`,
+    );
+  }
+
+  return withMeta(
+    { organizations },
+    {
+      source: `${NONPROFIT_HOST} /nonprofits/api/v2/search (IRS Form 990 data via ProPublica Nonprofit Explorer — not a .gov API; keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit: perPage, hasMore, nextOffset },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
+// ─── Tool: nonprofit_financials ───────────────────────────────────
+export type NonprofitFinancialsArgs = {
+  ein: string; // required; ^\d{1,9}$ (rides the PATH)
+};
+
+/**
+ * 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 async function financials(
+  args: NonprofitFinancialsArgs,
+): Promise<MetaBundle> {
+  const label = NONPROFIT_ORG_LABEL;
+
+  // ── Validate (belt-and-suspenders behind the server Zod). ein is charclass-
+  //    guarded PRE-fetch — it rides the URL PATH, so it MUST be digits-only. ──
+  if (typeof args.ein !== "string" || !EIN_RE.test(args.ein)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid ein ${JSON.stringify(args.ein)} — expected a numeric EIN of 1..9 digits (^\\d{1,9}$), e.g. "530196605".`,
+      upstreamEndpoint: label,
+    });
+  }
+
+  // ein is digits-only (EIN_RE) ⇒ safe as a path segment; no separators can steer
+  // the authority. Build + re-assert the host (SSRF belt-and-suspenders).
+  const url = `https://${NONPROFIT_HOST}${NONPROFIT_BASE}/organizations/${args.ein}.json`;
+  assertOnHost(url, label);
+
+  // ── Fetch through the shared envelope. A 404 (unknown EIN) ⇒ not_found (the
+  //    shared taxonomy — never a fabricated empty org); a 4xx ⇒ invalid_input; a
+  //    5xx/timeout ⇒ upstream_unavailable THROW; a 200 non-JSON ⇒ schema_drift. ──
+  let body: unknown;
+  try {
+    body = await getJson<unknown>(url, { label, redirect: "error" });
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw driftError(
+        label,
+        "ProPublica Nonprofit organization detail returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).",
+      );
+    }
+    throw e; // 404 → not_found, 5xx → upstream_unavailable, 4xx → invalid_input …
+  }
+
+  // ── [P4] `organization` MUST be an object and `filings_with_data` MUST be an
+  //    array (a missing/wrong-typed either is drift, never a fabricated empty). ──
+  const b = (body ?? {}) as {
+    organization?: unknown;
+    filings_with_data?: unknown;
+  };
+  if (
+    b.organization === null ||
+    typeof b.organization !== "object" ||
+    Array.isArray(b.organization)
+  ) {
+    throw driftError(
+      label,
+      "ProPublica Nonprofit organization detail shape drift — `organization` must be an object.",
+    );
+  }
+  if (!Array.isArray(b.filings_with_data)) {
+    throw driftError(
+      label,
+      "ProPublica Nonprofit organization detail shape drift — `filings_with_data` must be an array.",
+    );
+  }
+
+  const organization = mapOrganization(b.organization);
+  const filings = (b.filings_with_data as unknown[]).map(mapFiling);
+  const returned = filings.length;
+
+  // ── [P2] ★not-found SENTINEL: ProPublica returns HTTP 200 + a synthetic
+  //    `{ name:"Unknown Organization", …all-null }` placeholder (zero
+  //    filings_with_data) for an in-range EIN with no IRS record. That is a
+  //    FABRICATED empty org — surface it as not_found (identical to a 404), NEVER
+  //    as a real hit. Gated on BOTH the exact sentinel name AND empty structured
+  //    filings, so a real org (which would carry its true name / filings) is safe. ──
+  if (organization.name === PROPUBLICA_NOT_FOUND_NAME && returned === 0) {
+    throw new ToolErrorCarrier({
+      kind: "not_found",
+      retryable: false,
+      message: `No IRS Form 990 record for EIN ${args.ein} — ProPublica returned its "${PROPUBLICA_NOT_FOUND_NAME}" placeholder (no matching tax-exempt organization). Verify the EIN.`,
+      upstreamEndpoint: label,
+    });
+  }
+
+  // ── [P1] totalAvailable = filings.length — the COMPLETE filing set from the one
+  //    detail document (no pagination). ──
+  const notes: string[] = [
+    PROVENANCE_NOTE,
+    FINANCIALS_TOTAL_NOTE,
+    FINANCIALS_MONEY_NOTE,
+  ];
+
+  return withMeta(
+    { organization, filings },
+    {
+      source: `${NONPROFIT_HOST} /nonprofits/api/v2/organizations (IRS Form 990 data via ProPublica Nonprofit Explorer — not a .gov API; keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable: returned,
+      filtersApplied: [],
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      // The complete set is in one document — no pagination, hasMore:false.
+      pagination: { offset: 0, limit: returned, hasMore: false, nextOffset: null },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
+// ─── SSRF host assert (shared by both tools) ──────────────────────
+/**
+ * Belt-and-suspenders: the fixed host + strictly-built URL leave nothing to steer
+ * the authority; assert the built URL cannot have been moved off-host / downgraded.
+ */
+function assertOnHost(url: string, label: string): void {
+  const built = new URL(url);
+  if (built.hostname !== NONPROFIT_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Constructed ProPublica Nonprofit URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${NONPROFIT_HOST} over https — refusing to fetch (SSRF safety).`,
+      upstreamEndpoint: label,
+    });
+  }
+}
+
+// ─── Small clamp (defensive, behind the server Zod bounds) ─────────
+function clampPage(v: unknown): number {
+  if (typeof v !== "number" || !Number.isFinite(v)) return DEFAULT_PAGE;
+  const n = Math.floor(v);
+  return n < 0 ? 0 : n;
+}