@cliwant/mcp-sam-gov 1.4.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/nws-weather.ts

@@ -0,0 +1,167 @@
+/**
+ * nws-weather.ts — National Weather Service active alerts (api.weather.gov, KEYLESS)
+ * — the DISASTER / CLIMATE-READINESS lane. Current watches, warnings, and advisories
+ * (event, severity, urgency, area, effective/expires window, instructions). Pairs
+ * directly with the FEMA tools (disaster declarations → public assistance → hazard
+ * mitigation → LIVE active weather) to complete a disaster-response-readiness view:
+ * where severe-weather events are active NOW, ahead of the declarations/contracts
+ * that follow.
+ *
+ * SOURCE: NWS api.weather.gov (a .gov host), keyless. Requires a descriptive
+ * User-Agent (NWS policy) — sent from a fixed constant; no token. Returns a GeoJSON
+ * FeatureCollection. This is REAL-TIME data (currently-active alerts) — freshness is
+ * disclosed and never implied to be a historical series.
+ *
+ * HONESTY: fixed host + redirect:"error" (SSRF); `state` is a 2-letter charclass (the
+ * server-side ?area= filter); event/severity are applied CLIENT-SIDE over the returned
+ * set; a non-FeatureCollection / non-array body ⇒ driftError; an outage/4xx/timeout
+ * THROWS. A genuine no-active-alerts result ⇒ an HONEST EMPTY (returned:0), never an
+ * error. totalAvailable = the EXACT count of matched active alerts. Every scalar via
+ * `str` (null-never-empty-string); dates preserved as ISO strings.
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export const NWS_HOST = "api.weather.gov";
+const NWS_ACTIVE_URL = "https://api.weather.gov/alerts/active";
+const NWS_LABEL = "nws:/alerts/active";
+const NWS_TIMEOUT_MS = 15_000;
+// NWS asks every client to send a descriptive User-Agent (with contact). No token.
+const NWS_USER_AGENT = "cliwant-mcp-sam-gov (https://github.com/cliwant/mcp-sam-gov)";
+const STATE_RE = /^[A-Za-z]{2}$/;
+
+const PROVENANCE_NOTE =
+  "Source: NWS api.weather.gov active-alerts feed (keyless; a descriptive User-Agent is sent per NWS policy).";
+const FRESHNESS_NOTE =
+  "REAL-TIME: these are the alerts ACTIVE at request time (a live snapshot, not a historical archive). Read effective/onset/expires/ends for each alert's window; an expired alert is not returned. A no-active-alerts result is an HONEST empty (returned:0), never an error.";
+
+export type NwsAlert = {
+  id: string | null;
+  event: string | null; // e.g. "Wind Advisory", "Flood Warning"
+  headline: string | null;
+  severity: string | null; // Extreme | Severe | Moderate | Minor | Unknown
+  urgency: string | null; // Immediate | Expected | Future | Past | Unknown
+  certainty: string | null;
+  category: string | null;
+  status: string | null; // Actual | Exercise | Test | …
+  messageType: string | null; // Alert | Update | Cancel
+  areaDesc: string | null;
+  effective: string | null;
+  onset: string | null;
+  expires: string | null;
+  ends: string | null;
+  senderName: string | null;
+  description: string | null;
+  instruction: string | null;
+  response: string | null;
+};
+
+function mapAlert(feature: unknown): NwsAlert {
+  const p = ((feature ?? {}) as { properties?: Record<string, unknown> }).properties ?? {};
+  return {
+    id: str(p.id),
+    event: str(p.event),
+    headline: str(p.headline),
+    severity: str(p.severity),
+    urgency: str(p.urgency),
+    certainty: str(p.certainty),
+    category: str(p.category),
+    status: str(p.status),
+    messageType: str(p.messageType),
+    areaDesc: str(p.areaDesc),
+    effective: str(p.effective),
+    onset: str(p.onset),
+    expires: str(p.expires),
+    ends: str(p.ends),
+    senderName: str(p.senderName),
+    description: str(p.description),
+    instruction: str(p.instruction),
+    response: str(p.response),
+  };
+}
+
+async function loadActiveAlerts(state: string | undefined): Promise<NwsAlert[]> {
+  const params = new URLSearchParams();
+  if (state !== undefined) params.set("area", state.toUpperCase());
+  const url = params.toString() ? `${NWS_ACTIVE_URL}?${params.toString()}` : NWS_ACTIVE_URL;
+  const built = new URL(url);
+  if (built.hostname !== NWS_HOST || built.protocol !== "https:") {
+    throw driftError(NWS_LABEL, `Constructed NWS URL host ${JSON.stringify(built.hostname)} is not ${NWS_HOST} over https — refusing to fetch (SSRF safety).`);
+  }
+  const body = (await getJson(url, {
+    label: NWS_LABEL,
+    redirect: "error",
+    timeoutMs: NWS_TIMEOUT_MS,
+    headers: { "User-Agent": NWS_USER_AGENT, Accept: "application/geo+json" },
+  })) as { type?: unknown; features?: unknown };
+  if (body.type !== "FeatureCollection" || !Array.isArray(body.features)) {
+    throw driftError(NWS_LABEL, "NWS active-alerts body is not a GeoJSON FeatureCollection with a features[] array — schema drift, never a fake-empty result.");
+  }
+  return (body.features as unknown[]).map(mapAlert);
+}
+
+// ─── Tool: nws_active_alerts ──────────────────────────────────────
+/**
+ * List CURRENTLY-ACTIVE NWS weather alerts, optionally scoped by `state` (server-side
+ * ?area=) and filtered client-side by `event` (substring) and/or `severity` (exact).
+ * Honest `_meta` (exact match total + real-time freshness; a no-alerts result is an
+ * honest empty).
+ */
+export async function activeAlerts(args: {
+  state?: string;
+  event?: string;
+  severity?: string;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  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. "CA".`,
+      upstreamEndpoint: NWS_LABEL,
+    });
+  }
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  const all = await loadActiveAlerts(args.state);
+
+  const filtersApplied: string[] = [];
+  if (args.state !== undefined) filtersApplied.push("state");
+  const eventQ = args.event?.trim().toLowerCase();
+  const sevQ = args.severity?.trim().toLowerCase();
+  if (args.event !== undefined) filtersApplied.push("event");
+  if (args.severity !== undefined) filtersApplied.push("severity");
+
+  const matched = all.filter((a) => {
+    if (eventQ && !(a.event ?? "").toLowerCase().includes(eventQ)) return false;
+    if (sevQ && (a.severity ?? "").toLowerCase() !== sevQ) 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(
+    { alerts: page },
+    {
+      source: "api.weather.gov active alerts (NWS, keyless)",
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      truncated: hasMore,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes: [PROVENANCE_NOTE, FRESHNESS_NOTE],
+    } satisfies Partial<ResponseMeta>,
+  );
+}