whisper-id 0.3.0 → 0.5.0

package/README.md

@@ -2,10 +2,11 @@
 
 A real, routable **IPv6 identity** and **safe egress** for any Node agent.
 
-**Two-tier, by design** (Postel's Law): **with no key** the keyless half works everywhere —
-`verify`, `verifyDetails`, `rdap` — so anyone can prove an address is a Whisper agent. **With
-your key** (`opts.apiKey` or `WHISPER_API_KEY`) the whole control plane unlocks — list, policy,
-logs, revoke, identity, agent — plus **egress** that sources your traffic from your `/128`.
+**Two-tier, by design** (Postel's Law): **with no key** the keyless half works everywhere.
+`verify`, `verifyDetails`, and `rdap` let anyone prove an address is a Whisper agent. **With
+your key** (`opts.apiKey` or `WHISPER_API_KEY`) the whole control plane unlocks (list, policy,
+logs, revoke, identity, agent), plus the keyed **`graph`** namespace (Cypher intelligence over
+the Whisper Security graph) and **egress** that sources your traffic from your `/128`.
 
 ```sh
 npm i whisper-id
@@ -13,7 +14,7 @@ npm i whisper-id
 
 ```js
 import { verify } from "whisper-id";
-await verify("2a04:2a01:…");                       // keyless: true if it's a real Whisper agent
+await verify("2a04:2a01:...");                     // keyless: true if it's a real Whisper agent
 ```
 
 ```js
@@ -28,14 +29,14 @@ await withEgress(async (e) => {
 
 ## API
 
-### Keyless — no key, no CLI (pure HTTPS)
+### Keyless: no key, no CLI (pure HTTPS)
 
 Run anywhere `fetch` runs (Cloudflare Workers, Vercel, Deno, Lambda, the browser).
 
 | Call | Does |
 |------|------|
 | `verify(address)` | Is `address` a real Whisper agent? (server-side DANE + DNSSEC + reverse-DNS + JWS) → `boolean` |
-| `verifyDetails(address)` | The full verdict (`is_whisper_agent`, `fqdn`, `operator`, `dane_ok`, `jws_ok`, …) or `null` |
+| `verifyDetails(address)` | The full verdict (`is_whisper_agent`, `fqdn`, `operator`, `dane_ok`, `jws_ok`, and more) or `null` |
 | `rdap(address)` | The public RDAP record for a `/128`, or `null` |
 | `egressIp()` | The IP this process leaves from (a `/128` when routed, else the platform's) → `string` |
 
@@ -44,21 +45,21 @@ import { verify, rdap } from "whisper-id";
 if (await verify(addr)) console.log((await rdap(addr)).name);
 ```
 
-### Control plane — with a key (pure HTTP, no CLI)
+### Control plane: with a key (pure HTTP, no CLI)
 
-Pure `fetch` to the control endpoint — no `whisper` CLI, no child process. The key comes from
+Pure `fetch` to the control endpoint, with no `whisper` CLI and no child process. The key comes from
 `opts.apiKey` or `WHISPER_API_KEY` and is sent only in the `X-API-Key` header (never on argv,
 never logged). Each also takes `{ apiKey, timeout }`. On failure they throw a `WhisperError`
 carrying the server's `detail` (plus `.status` / `.retryAfter`).
 
 | Call | Does |
 |------|------|
-| `list({ kind })` | List your fleet — `kind`: `"agents"` (default) \| `"identities"` \| `"records"`. → items `{ label, fqdn, address, agent, created, state }` |
+| `list({ kind })` | List your fleet. `kind`: `"agents"` (default) \| `"identities"` \| `"records"`. → items `{ label, fqdn, address, agent, created, state }` |
 | `identity({ label, contact_email })` | Allocate your own `/128`. Release with `{ release: true, address }`. → `{ agent, address, fqdn, ptr, state }` |
 | `agent(idOrAddress)` | One agent's detail + live counters. → the record, or `null` |
 | `policy({ default, allow, block })` | Read (no fields) or set your per-tenant DNS policy. → `{ key, value }` rows |
 | `logs({ agent, kind, from, to, limit })` | Recent DNS/conn/alloc activity from warm storage. → event records |
-| `revoke(idOrAddress)` | Fully revoke an agent — **irreversible** (needs `admin:dns`). → `{ status }` |
+| `revoke(idOrAddress)` | Fully revoke an agent, **irreversible** (needs `admin:dns`). → `{ status }` |
 
 ```js
 import { list, policy, logs } from "whisper-id"; // WHISPER_API_KEY in the env
@@ -68,11 +69,67 @@ for (const a of await list()) console.log(a.address, a.label);
 const recent = await logs({ kind: "dns", limit: 100 });
 ```
 
+### Graph (keyed Cypher, pure HTTP)
+
+The intelligence half of the keyed surface. `import { graph } from "whisper-id"` and you get one
+typed method per catalog entry over the Whisper Security graph, plus a raw `graph.query` escape
+hatch. Same auth as the control plane: the key comes from `opts.apiKey` or `WHISPER_API_KEY` and
+is sent only in `X-API-Key`. If it is Cypher, it needs a key: this whole namespace is keyed (the
+keyless `verify` / `verifyDetails` / `rdap` above touch no Cypher and stay key-free). Every method
+resolves to `{ columns, rows, statistics }` where `rows` are objects keyed by column name.
+
+```js
+import { graph } from "whisper-id";                // WHISPER_API_KEY in the env, or pass { apiKey }
+
+const r = await graph.identify("api.openai.com", { apiKey: "whisper-..." });
+console.log(r.rows[0].vendor_id, r.rows[0].canonical_name);   // → openai OpenAI
+
+await graph.assess("185.220.101.33");              // threat posture: malicious / benign / unknown
+await graph.variants("paypal.com");                // registered look-alike domains
+await graph.origins("cloudflare.com");             // real origin IPs behind a CDN
+await graph.query("MATCH (n) RETURN n LIMIT $lim", { lim: 5 });  // raw Cypher escape hatch
+```
+
+| Call | Does |
+|------|------|
+| `graph.identify(value)` | Name the vendor and operator role behind a host or IP |
+| `graph.assess(value)` | Labelled threat posture for a host or IP (malicious / benign / unknown) |
+| `graph.variants(value)` | Look-alike domain variants of a brand, and which are registered |
+| `graph.walk(value)` | Walk to the nearest known vendors behind a host, with channel + confidence |
+| `graph.explain(value)` | Score an indicator against the threat feeds and explain why |
+| `graph.pslTldplusone(value)` | Reduce any hostname to its registrable apex (eTLD+1) |
+| `graph.pslAffiliation(value)` | Is a domain a PSL private-section suffix, and who submitted it |
+| `graph.origins(value)` | Real origin IPs behind a CDN-fronted domain, ranked by confidence |
+| `graph.history(value)` | Full historical WHOIS timeline for a domain |
+| `graph.historyWhois(value)` | WHOIS-only historical timeline for a domain |
+| `graph.asset(value)` | Member ASNs of an AS-SET macro |
+| `graph.lookupTorRelay(value)` | Is an IP a known Tor exit relay |
+| `graph.dbSchema()` | Every node + relationship type in the graph, with counts and examples |
+| `graph.submit({ kind, ...fields })` | Contribute an indicator observation or feedback (keyed write) |
+| `graph.query(cypher, params)` | Raw Cypher escape hatch. → the full `{ columns, rows, statistics }` |
+
+Fifteen multi-step **workflow** methods (`attackPath`, `attackSurface`, `blastRadius`, `typosquat`,
+`indicator`, `routeHealth`, and 9 more) execute on the Whisper workflow runner and stream
+Server-Sent Events; one call collects the whole run into `{ slug, steps, complete, events }`:
+
+```js
+const run = await graph.typosquat("paypal.com");   // bare value → the flow's primary input
+console.log(run.steps.length, "steps");            // each step: its bound Cypher, columns, rows
+console.log(run.complete.totalLatencyMs, "ms");    // the terminal aggregate context
+
+await graph.attackSurface({ domain: "github.com", level: "deep" });  // named inputs + knobs
+```
+
+Every `graph` method is generated from the Whisper query catalog (never hand-copied, so it
+cannot drift) and links its canonical docs: `graph.identify.docs` →
+`https://www.whisper.security/docs/whisper-graph/procedures/identify`, and the same URL is on
+each method's `@see` tag in your editor.
+
 ### Egress + CLI-backed
 
 | Call | Does |
 |------|------|
-| `register(name, { newKey })` | Create a named agent via the CLI — a routable `/128`. `newKey: true` mints a new agent **and** its own API key. → `Agent { address, id, name }` |
+| `register(name, { newKey })` | Create a named agent via the CLI: a routable `/128`. `newKey: true` mints a new agent **and** its own API key. → `Agent { address, id, name }` |
 | `egress({ agent, tier, setEnv })` | Bring up egress bound to your `/128`. → `Egress { port, proxyUrl, socksUrl, proxies, close() }`. `tier: "wireguard"` for a routed `/128`. Sets proxy env unless `setEnv:false`; call `close()` to restore. |
 | `withEgress([opts], fn)` | Run `fn(egress)` with egress up, restoring the environment afterwards. |
 | `ip()` | Your current egress IP via the CLI, proving it's your `/128`. → `string` |
@@ -99,7 +156,7 @@ transparently inside `withEgress`.
 ## Requirements
 
 Zero dependencies. The **keyless** checks and the **control plane** are pure HTTP (Node ≥ 18's
-global `fetch`) — no CLI, nothing to install. For the control plane, set `WHISPER_API_KEY` (or
+global `fetch`), with no CLI and nothing to install. For the control plane, set `WHISPER_API_KEY` (or
 pass `{ apiKey }`).
 
 Only **egress** and the CLI-backed calls (`register`, `egress`, `withEgress`, `ip`) need the
@@ -109,12 +166,12 @@ Only **egress** and the CLI-backed calls (`register`, `egress`, `withEgress`, `i
 curl get.whisper.online | sh
 ```
 
-(`$WHISPER_BIN` overrides the CLI path; `$WHISPER_CONTROL_URL` / `$WHISPER_RDAP_URL` override the
-endpoints.)
+(`$WHISPER_BIN` overrides the CLI path; `$WHISPER_CONTROL_URL` / `$WHISPER_GRAPH_URL` /
+`$WHISPER_RDAP_URL` override the endpoints.)
 
 ## Links
 
-- Site — https://whisper.online
-- CLI — https://github.com/whisper-sec/whisper-cli
+- Site: https://whisper.online
+- CLI: https://github.com/whisper-sec/whisper-cli
 
 MIT licensed.

package/index.d.ts

@@ -3,7 +3,7 @@
 export declare class WhisperError extends Error {}
 
 export interface Agent {
-  /** The routable IPv6 /128 — both the identity and the auth. */
+  /** The routable IPv6 /128 - both the identity and the auth. */
   address: string;
   id: string | null;
   name: string;
@@ -51,7 +51,7 @@ export function egressIp(opts?: { timeout?: number }): Promise<string>;
 export function ip(opts?: { timeout?: number }): Promise<string>;
 export function firstAddr(obj: unknown): string | null;
 
-// ── Control plane (pure HTTP, keyed — no CLI) ───────────────────────────────────────
+// ── Control plane (pure HTTP, keyed - no CLI) ───────────────────────────────────────
 // The governance half of the two-tier surface: pure `fetch` to the control endpoint, so
 // it runs anywhere (serverless, edge, a plain server). The key is read from `opts.apiKey`
 // or `WHISPER_API_KEY` and sent only in the `X-API-Key` header. On failure these throw a
@@ -59,7 +59,7 @@ export function firstAddr(obj: unknown): string | null;
 
 /** Common options for every keyed control call. */
 export interface ControlOptions {
-  /** The Whisper owner key (`whisper_live_…`). Falls back to `process.env.WHISPER_API_KEY`. */
+  /** The Whisper owner key (`whisper_live_...`). Falls back to `process.env.WHISPER_API_KEY`. */
   apiKey?: string;
   /** Per-call timeout in ms (default 60000). */
   timeout?: number;
@@ -142,7 +142,7 @@ export function list(opts?: ListOptions): Promise<AgentItem[]>;
 export function policy(opts?: PolicyOptions): Promise<PolicyEntry[]>;
 /** Query recent DNS/conn/alloc activity from warm storage. → event records. */
 export function logs(opts?: LogsOptions): Promise<LogEvent[]>;
-/** Fully revoke an agent — IRREVERSIBLE (admin:dns). → `{ status, … }`. */
+/** Fully revoke an agent - IRREVERSIBLE (admin:dns). → `{ status, ... }`. */
 export function revoke(agent: string, opts?: ControlOptions): Promise<{ status: string; [k: string]: unknown }>;
 export function revoke(opts: RevokeOptions): Promise<{ status: string; [k: string]: unknown }>;
 /** Allocate your own /128 (or release with `{release:true,address}`). → `{agent,address,fqdn,ptr,state}`. */
@@ -150,3 +150,460 @@ export function identity(opts?: IdentityOptions): Promise<AgentItem | null>;
 /** One agent's detail + live counters. Accepts an id, a /128, or `{agent}`/`{address}`. */
 export function agent(sel: string, opts?: ControlOptions): Promise<AgentItem | null>;
 export function agent(opts?: AgentSelectOptions): Promise<AgentItem | null>;
+
+// ── Graph (keyed: Cypher + flows over the Whisper Security graph) ────────────────────
+// The intelligence half of the keyed surface. Postel two-tier: the keyless identity calls
+// above (verify/verifyDetails/rdap) run with no key and no Cypher; this whole `graph`
+// namespace is KEYED (Kaveh's rule: if it is Cypher, it needs a key). The 14 `direct`
+// methods POST their catalog Cypher to /api/query; the 15 `flow` methods execute on the
+// workflow runner (POST gallery/run, Server-Sent Events) and resolve to the collected
+// stream. The key rides only in `X-API-Key`. The method surface below is GENERATED from
+// the Whisper query catalog by scripts/gen-graph.mjs; every method's docs live at the
+// `@see` URL and are also on the function itself as `.docs`.
+
+/** Per-call options for the keyed graph namespace (same shape as the control plane). */
+export interface GraphOptions extends ControlOptions {}
+
+/** Result of a keyed graph query. `rows` are objects keyed by column name. */
+export interface GraphResult {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  statistics?: { rowCount?: number; executionTimeMs?: number; [k: string]: unknown } | null;
+}
+
+/** A `graph.submit` payload: an indicator observation or a piece of feedback. */
+export interface GraphSubmission {
+  kind: "indicator" | "feedback" | string;
+  identifier_kind?: string;
+  identifierKind?: string;
+  value?: string;
+  observation_id?: string;
+  observationId?: string;
+  confidence?: number;
+  first_seen?: string;
+  firstSeen?: string;
+  provenance?: string;
+  query?: string;
+  results?: unknown;
+  comment?: string;
+  severity?: string;
+  v?: number;
+  [k: string]: unknown;
+}
+
+/**
+ * Input for a flow method: a bare value for the flow's primary input, a plain object of
+ * named inputs (a known knob name routes to params), or an explicit `{ inputs, params }`.
+ */
+export type GraphFlowInput =
+  | string
+  | number
+  | Record<string, unknown>
+  | { inputs?: Record<string, unknown>; params?: Record<string, unknown> };
+
+/** One Server-Sent Event from a flow run; `data` is JSON-decoded when possible. */
+export interface GraphFlowEvent {
+  event: string;
+  data: unknown;
+}
+
+/**
+ * Result of a flow run: every `step` event's payload (each carries the step's bound
+ * Cypher, columns, and rows), the terminal `complete` payload (the aggregate context;
+ * `null` if the stream ended early), and the full raw event list.
+ */
+export interface GraphFlowResult {
+  slug: string;
+  steps: Record<string, unknown>[];
+  complete: Record<string, unknown> | null;
+  events: GraphFlowEvent[];
+}
+
+/**
+ * The keyed graph namespace: one typed method per catalog entry (14 direct Cypher reads +
+ * 15 workflow-runner flows), plus a raw `query` escape hatch. Every method needs a key
+ * (`{ apiKey }` or `WHISPER_API_KEY`) and carries its canonical docs URL as `.docs`.
+ */
+export interface GraphNamespace {
+  /**
+   * Raw Cypher escape hatch: run arbitrary Cypher with `params` bound server-side as
+   * $-parameters. Returns the full `{columns,rows,statistics}`.
+   * @see https://www.whisper.security/docs/cypher-api
+   */
+  query(cypher: string, params?: Record<string, unknown>, opts?: GraphOptions): Promise<GraphResult>;
+
+  // BEGIN GENERATED: graph catalog (scripts/gen-graph.mjs) - do not edit by hand
+  /**
+   * Assess how resilient a country's core DNS is if it were cut off from the world.
+   *
+   * Could a country still resolve names if it were isolated? Counts how many of the 13 root
+   * letters have in-country DNS_ROOT_INSTANCE anycast nodes, the Global-vs-Local split, the BGP
+   * origin ASNs hosting them, and a resilience grade.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "anycast-dns-root-sovereignty")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: country. Params: instanceType.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  anycastDnsRootSovereignty(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find the choke points an attacker would target - and how any two things connect.
+   *
+   * From a starting foothold, finds shared dependencies whose compromise reaches furthest; for
+   * any two indicators, traces how they are actually connected.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "attack-path")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value, other. Params: level.
+   * @see https://www.whisper.security/docs/recipes/attack-path
+   */
+  attackPath(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Map everything about a domain that's exposed to the outside world, scored for risk.
+   *
+   * Maps the full external footprint - subdomains, name/mail servers, registrant, third-party
+   * services, connected web - and scores the exposure.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "attack-surface")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain. Params: level.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  attackSurface(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Grade a network's routing security and trace conflicts to the domains they'd expose.
+   *
+   * Grades a network on the conflicts/gaps that make route hijacking possible, then traces any
+   * conflict to the specific domains and organisations exposed on the affected blocks.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "bgp-hijack-exposure")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/bgp-routing
+   */
+  bgpHijackExposure(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Pick one asset and see what would break if it failed - and what it depends on in turn.
+   *
+   * Maps dependencies in both directions: everything that breaks if the asset fails (SPOFs) and
+   * everything it relies on (its own DNS/mail/hosting/network supply chain).
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "blast-radius")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: indicator. Params: depth.
+   * @see https://www.whisper.security/docs/recipes/soc
+   */
+  blastRadius(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Assemble a ready-to-submit dossier for taking down a scam or phishing domain.
+   *
+   * One-pass takedown package: reputation verdict, owner (WHOIS), abuse-list listings, and
+   * surrounding infrastructure, laid out ready to hand to a registrar/host.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "build-takedown-evidence-package")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/threat-intel
+   */
+  buildTakedownEvidencePackage(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Map an organisation's externally visible AI and agent endpoints from the outside.
+   *
+   * Maps externally visible AI/agent hosts (API, model, agent) from the outside via heuristic
+   * hostname patterns (api./mcp./ai./vector./llm./agent./chat./copilot.). Best-effort leads.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "discover-ai-agent-infrastructure")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  discoverAiAgentInfrastructure(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Investigate one suspicious domain, IP, or network in depth and get a clear picture of the threat and everything connected to it.
+   *
+   * Deep-dive: works outward across the whole footprint (related domains, real origins behind
+   * CDN, neighbouring infra), threat-checks each node, never inherits maliciousness from shared
+   * infra; labelled posture, no score.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "indicator")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: indicator.
+   * @see https://www.whisper.security/docs/recipes/soc
+   */
+  indicator(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Turn one domain or IP into a full context card - owner, hosting, mail, location, reputation at a glance.
+   *
+   * Fills the picture for one indicator: registrant (WHOIS), hosting + country, mail/name
+   * servers, network behind it, reputation read.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "indicator-enrichment")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/dns-email
+   */
+  indicatorEnrichment(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Trace one indicator to its true owner and full estate, even behind privacy screens and CDNs.
+   *
+   * Works out the true operator (even behind privacy WHOIS), de-cloaks CDN-fronted sites to real
+   * servers, pivots to the rest of that owner's estate across every layer.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "infrastructure-mapping")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value. Params: level.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  infrastructureMapping(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Grade an organisation for over-reliance on single providers, regions, or facilities.
+   *
+   * Grades how concentrated infra is - too much riding on one provider/region/data-centre/cable
+   * landing - surfacing SPOFs for resilience and DORA/NIS2 fourth-party risk.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "map-supply-chain-concentration")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  mapSupplyChainConcentration(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Check a domain's name servers for the misconfigurations that enable DNS hijacking.
+   *
+   * Audits delegation, flags stale/mismatched/lame nameservers, sizes each provider's share,
+   * surfaces registry facts - catches delegation weakness before exploit.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "nameserver-hijack-dns-consistency")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/dns-email
+   */
+  nameserverHijackDnsConsistency(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Profile a network or address block into a full routing and reachability health card.
+   *
+   * Health card for a network/block: what it announces, peers/transit, single-upstream lean,
+   * RPKI protection - the one-look reach & resilience report.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "route-health")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: target.
+   * @see https://www.whisper.security/docs/recipes/bgp-routing
+   */
+  routeHealth(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find subdomains that point at abandoned services an attacker could claim.
+   *
+   * Walks subdomains and flags ones aiming at deprovisioned targets (dangling CNAME whose target
+   * no longer resolves) so you can reclaim/remove before someone else does. CNAME layer is
+   * prod-ahead.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "subdomain-takeover")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  subdomainTakeover(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find registered look-alikes of your brand and check which ones are dangerous.
+   *
+   * Finds registered impersonations across misspellings/risky TLDs, separates your own defensive
+   * domains from strangers', flags fresh/privacy/abuse-listed ones into a prioritised list.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "typosquat")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/brand-protection
+   */
+  typosquat(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Name the vendor and operator role behind a host or IP in one call.
+   *
+   * Resolves a host/IP to its canonical vendor, category and operator roles (DNS_OPERATOR / CDN
+   * / ORIGIN_AS / MAIL_RECEIVER) with a confidence band.
+   *
+   * KEYED. Cypher: CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band
+   * Returns columns: host, vendor_id, canonical_name, category, roles, host_class, band.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/identify
+   */
+  identify(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Get a labelled threat posture for a host or IP - malicious, benign, or unknown.
+   *
+   * Returns a posture label + severity band + sub-labels + coverage + evidence for an indicator;
+   * benign-allowlisted vs malicious-evidenced, never a bare score.
+   *
+   * KEYED. Cypher: CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence
+   * Returns columns: host, label, band, sub_labels, coverage, evidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
+  assess(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Generate look-alike domain variants of a brand and see which are registered.
+   *
+   * Enumerates permutations (omission, bitsquatting, ...) of a domain, flags which exist, with a
+   * per-variant confidence.
+   *
+   * KEYED. Cypher: CALL whisper.variants($v) YIELD variant, method, exists, confidence
+   * Returns columns: variant, method, exists, confidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/variants
+   */
+  variants(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Walk the graph to the nearest known vendors behind a host, with the channel and confidence.
+   *
+   * Structural attribution: returns nearest_known_vendors with the channel (DELEGATED_TO /
+   * ORIGIN_AS) and confidence, plus siblings and coverage - explains WHY a host maps to a
+   * vendor.
+   *
+   * KEYED. Cypher: CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings
+   * Returns columns: coverage, host, nearest_known_vendors, no_atlas_match, siblings.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
+  walk(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Score an indicator against the threat feeds and explain exactly why.
+   *
+   * Threat-intel scorer: score + level + human explanation + the feeds it is listed in (feedId,
+   * weight, firstSeen/lastSeen). Two live forms: bare CALL explain($v) (full columns) and CALL
+   * whisper.explain($v) (restricted YIELD).
+   *
+   * KEYED. Cypher: CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources
+   * Returns columns: indicator, score, level, explanation, sources.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/explain
+   */
+  explain(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Reduce any hostname to its registrable apex (eTLD+1) via the Public Suffix List.
+   *
+   * PSL-correct eTLD+1: www.foo.co.uk -> foo.co.uk. The right way to group hosts by the thing
+   * someone actually registered.
+   *
+   * KEYED. Cypher: CALL whisper.psl.tldPlusOne($v) YIELD apex
+   * Returns columns: apex.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
+  pslTldplusone(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Check whether a domain is a PSL private-section suffix and who submitted it.
+   *
+   * For a PSL private-section suffix, returns the submitting org/login and evidence kind +
+   * confidence; found=false for ordinary registrable domains.
+   *
+   * KEYED. Cypher: CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence
+   * Returns columns: found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
+  pslAffiliation(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Find the real origin IPs behind a CDN-fronted domain, ranked by confidence.
+   *
+   * Candidate origin IPs behind a CDN with confidence, the methods that found them (e.g.
+   * links_to), and the hosting ASN/name - de-cloaks to the real server.
+   *
+   * KEYED. Cypher: CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind
+   * Returns columns: ip, confidence, methods, asn, asnName, kind.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/origins
+   */
+  origins(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Get the full historical WHOIS timeline for a domain.
+   *
+   * Every observed WHOIS snapshot over time: create/update/expiry, registrar, registrant,
+   * country, nameservers - the ownership/registration story.
+   *
+   * KEYED. Cypher: CALL whisper.history($v)
+   * Returns columns: indicator, type, queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers, cached.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/history
+   */
+  history(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Get the WHOIS-only historical timeline for a domain.
+   *
+   * The registration-record projection of the history timeline: create/update/expiry, registrar,
+   * registrant, country, nameservers per snapshot.
+   *
+   * KEYED. Cypher: CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers
+   * Returns columns: queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/history
+   */
+  historyWhois(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * List the member ASNs of an AS-SET macro.
+   *
+   * Expands an AS-SET name (e.g. AS-CLOUDFLARE) to its member ASNs and source RIR. Arg is a
+   * STRING as-set name, not an integer ASN. (Membership is sparsely populated in the current
+   * graph.)
+   *
+   * KEYED. Cypher: CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir
+   * Returns columns: asSetName, memberAsn, sourceRir.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
+  asset(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Check whether an IP is a known Tor exit relay.
+   *
+   * Live Tor exit-node check: found + fingerprint + exit-address count + source + ingest time
+   * for an IPv4.
+   *
+   * KEYED. Cypher: CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt
+   * Returns columns: indicator, found, fingerprint, exitAddressCount, source, ingestedAt.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
+  lookupTorRelay(value: string, opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * List every node and relationship type in the graph with counts and examples.
+   *
+   * The self-describing schema: node/relationship types with counts, descriptions, examples,
+   * source/target labels and query best-practices - the map of what the graph holds.
+   *
+   * KEYED. Cypher: CALL db.schema()
+   * Returns columns: type, name, count, description, example, sourceLabels, targetLabels, fastPatterns, slowPatterns, bestPractices.
+   * @see https://www.whisper.security/docs/whisper-graph/schema
+   */
+  dbSchema(opts?: GraphOptions): Promise<GraphResult>;
+
+  /**
+   * Contribute an indicator observation or feedback back into the graph (requires an API key).
+   *
+   * The write channel: submit an indicator/feedback with an attributable API key (anonymous
+   * submits are refused to preserve K-anonymity). Keyed-only by design.
+   *
+   * KEYED write: CALL whisper.submit({...}) with the payload fields bound as $-parameters.
+   * Fields: kind, identifier_kind, value, observation_id, confidence, first_seen, provenance, query, results, comment, severity, v (kind required).
+   * Returns columns: observation_id, kind, accepted, idempotent, promotion_state, k_bucket, advisory, v.
+   * @see https://www.whisper.security/docs/cypher-api
+   */
+  submit(payload: GraphSubmission, opts?: GraphOptions): Promise<GraphResult>;
+  // END GENERATED: graph catalog
+}
+
+/** The keyed graph namespace. `import { graph } from "whisper-id"`. */
+export const graph: GraphNamespace;

package/index.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2026 viaGraph B.V. (Whisper Security)
-// whisper-id — a routable IPv6 identity and safe egress for any Node agent.
+// whisper-id - a routable IPv6 identity and safe egress for any Node agent.
 // A thin, dependency-free wrapper over the `whisper` CLI (https://whisper.online): the CLI
 // holds the auth, control plane, and egress tunnel; this gives you register/egress/verify/ip.
 import { execFile } from "node:child_process";
@@ -72,7 +72,7 @@ function getKey(obj, ...keys) {
   return null;
 }
 
-/** Create a named agent identity — a routable Whisper IPv6 /128. */
+/** Create a named agent identity - a routable Whisper IPv6 /128. */
 export async function register(name, { newKey = false, timeout = 120000 } = {}) {
   if (!name || !name.trim()) throw new WhisperError("register() needs a non-empty agent name");
   const args = ["create", "--name", name];
@@ -129,7 +129,7 @@ export async function withEgress(optsOrFn, maybeFn) {
 }
 
 // Keyless public endpoint base (the same surface the CLI uses, server-side). No key, no `whisper`
-// CLI — these work in any runtime that can fetch() (serverless, edge, browser). Override via env.
+// CLI - these work in any runtime that can fetch() (serverless, edge, browser). Override via env.
 function rdapBase() {
   return (process.env.WHISPER_RDAP_URL || "https://rdap.whisper.online").replace(/\/+$/, "");
 }
@@ -155,7 +155,7 @@ async function httpGetJson(url, { timeout = 60000 } = {}) {
 }
 
 /**
- * Return true iff `address` is a real Whisper agent. **Keyless and CLI-free** — one HTTPS GET to
+ * Return true iff `address` is a real Whisper agent. **Keyless and CLI-free** - one HTTPS GET to
  * the public /verify-identity endpoint (server-side DANE+DNSSEC+reverse-DNS+JWS chain). Works in
  * any runtime. 200 ⇒ agent, 404 ⇒ not. Throws only if the endpoint is unreachable.
  */
@@ -163,7 +163,7 @@ export async function verify(address, { timeout = 60000 } = {}) {
   return (await verifyDetails(address, { timeout })) !== null;
 }
 
-/** Full verify verdict for a real agent (is_whisper_agent, fqdn, operator, tenant, dane_ok, jws_ok, …), else null. Keyless, CLI-free. */
+/** Full verify verdict for a real agent (is_whisper_agent, fqdn, operator, tenant, dane_ok, jws_ok, ...), else null. Keyless, CLI-free. */
 export async function verifyDetails(address, { timeout = 60000 } = {}) {
   if (!address || !address.trim()) throw new WhisperError("verify() needs an address");
   const url = `${rdapBase()}/verify-identity?ip=${encodeURIComponent(address.trim())}`;
@@ -172,10 +172,10 @@ export async function verifyDetails(address, { timeout = 60000 } = {}) {
   return body;
 }
 
-/** Public RDAP record for a Whisper /128 (handle, name, status, entities, …), or null. Keyless, CLI-free. */
+/** Public RDAP record for a Whisper /128 (handle, name, status, entities, ...), or null. Keyless, CLI-free. */
 export async function rdap(address, { timeout = 60000 } = {}) {
   if (!address || !address.trim()) throw new WhisperError("rdap() needs an address");
-  const url = `${rdapBase()}/ip/${encodeURI(address.trim())}`; // path segment — keep the literal colons
+  const url = `${rdapBase()}/ip/${encodeURI(address.trim())}`; // path segment - keep the literal colons
   const { status, body } = await httpGetJson(url, { timeout });
   return status === 200 ? body : null;
 }
@@ -193,10 +193,10 @@ export async function ip({ timeout = 60000 } = {}) {
   return getKey(env, "ip", "agent") || firstAddr(env) || "";
 }
 
-// ── Control plane (pure HTTP — no CLI) ──────────────────────────────────────────────
+// ── Control plane (pure HTTP - no CLI) ──────────────────────────────────────────────
 // The governance half of the two-tier surface (Postel: keyless verify above works with no
-// key; these unlock with the caller's key). One control verb — `whisper.agents({op,args})`
-// — POSTed straight to the control endpoint. No `whisper` CLI, no child process, no key on
+// key; these unlock with the caller's key). One control verb - `whisper.agents({op,args})`
+// - POSTed straight to the control endpoint. No `whisper` CLI, no child process, no key on
 // argv: works in any runtime with fetch() (serverless, edge, a plain server). The key is
 // read from opts.apiKey or $WHISPER_API_KEY and sent ONLY in the X-API-Key header.
 
@@ -204,8 +204,8 @@ function controlUrl() {
   return process.env.WHISPER_CONTROL_URL || "https://graph.whisper.security/api/query";
 }
 
-// Conservative-emit (RFC 761): render a value as a Cypher literal so no input — however
-// hostile — can break out of the map. A ' is doubled and a \ is doubled (order matters:
+// Conservative-emit (RFC 761): render a value as a Cypher literal so no input - however
+// hostile - can break out of the map. A ' is doubled and a \ is doubled (order matters:
 // backslashes first). Mirrors the reference client's cypher builder byte-for-byte.
 function escapeCypher(s) {
   return String(s).replace(/\\/g, "\\\\").replace(/'/g, "''");
@@ -235,8 +235,8 @@ function buildAgentsQuery(op, args) {
 }
 
 // Liberal-accept (RFC 761): decode BOTH documented envelope shapes into one normalised
-// { ok, status, result, error, retryAfter } — the flat {ok,status,result,error} dev shape
-// AND the live procedure-row table whose single row carries the per-op envelope — plus a
+// { ok, status, result, error, retryAfter } - the flat {ok,status,result,error} dev shape
+// AND the live procedure-row table whose single row carries the per-op envelope - plus a
 // bare RFC-7807 problem object. Never throws on shape; a fault becomes error, not a crash.
 function decodeEnvelope(body, httpStatus) {
   const out = { ok: false, status: httpStatus, result: null, error: null, retryAfter: null };
@@ -254,9 +254,9 @@ function decodeEnvelope(body, httpStatus) {
     if (out.error && !out.error.status) out.error.status = out.status;
     return out;
   };
-  // Shape B — an explicit ok flag at the top level.
+  // Shape B - an explicit ok flag at the top level.
   if (typeof body.ok === "boolean") return applyRow(body);
-  // Shape A — the procedure-row table: rows[0] carries {op,ok,status,result,error,…}. The
+  // Shape A - the procedure-row table: rows[0] carries {op,ok,status,result,error,...}. The
   // row may be an object already, or a positional array aligned to top-level columns.
   if (Array.isArray(body.rows) && body.rows.length > 0) {
     let row0 = body.rows[0];
@@ -287,7 +287,7 @@ function decodeEnvelope(body, httpStatus) {
 }
 
 // Turn a {columns,rows} result into column-keyed records. Rows may be positional arrays
-// (aligned to columns) or already-keyed objects — both are accepted.
+// (aligned to columns) or already-keyed objects - both are accepted.
 function recordsFrom(result) {
   if (!result || !Array.isArray(result.rows)) return [];
   const cols = Array.isArray(result.columns) ? result.columns : [];
@@ -312,7 +312,7 @@ async function callControl(op, args, opts = {}) {
   const key = resolveKey(opts);
   if (!key) {
     throw new WhisperError(
-      `\`${op}\` needs a Whisper API key — pass { apiKey } or set WHISPER_API_KEY. ` +
+      `\`${op}\` needs a Whisper API key - pass { apiKey } or set WHISPER_API_KEY. ` +
         "(verify/verifyDetails/rdap are keyless and need no key.)"
     );
   }
@@ -383,7 +383,7 @@ export async function policy(opts = {}) {
 }
 
 /**
- * Query recent activity from warm storage (op:logs) — the poll counterpart of the live
+ * Query recent activity from warm storage (op:logs) - the poll counterpart of the live
  * monitor. All filters optional: `{ agent, kind:"dns"|"conn"|"alloc", from, to, limit }`
  * (from/to accept epoch-ms, RFC-3339, or relative like "-1h"). → an array of event records.
  */
@@ -399,9 +399,9 @@ export async function logs(opts = {}) {
 }
 
 /**
- * Fully revoke an agent — IRREVERSIBLE (op:revoke; needs admin:dns). Liberal input:
- * `revoke("agent-id")`, `revoke("2a04:2a01:…")`, or `revoke({ agent, apiKey })`.
- * → `{ status, … }`.
+ * Fully revoke an agent - IRREVERSIBLE (op:revoke; needs admin:dns). Liberal input:
+ * `revoke("agent-id")`, `revoke("2a04:2a01:...")`, or `revoke({ agent, apiKey })`.
+ * → `{ status, ... }`.
  */
 export async function revoke(target, maybeOpts) {
   const o = typeof target === "string" ? maybeOpts || {} : target || {};
@@ -414,7 +414,7 @@ export async function revoke(target, maybeOpts) {
 
 /**
  * Allocate your own /128 identity (op:identity): `identity({ label, contact_email })`.
- * Release form: `identity({ release:true, address:"2a04:2a01:…" })`.
+ * Release form: `identity({ release:true, address:"2a04:2a01:..." })`.
  * → `{ agent, address, fqdn, ptr, state }`.
  */
 export async function identity(opts = {}) {
@@ -434,7 +434,7 @@ export async function identity(opts = {}) {
 }
 
 /**
- * One agent's detail + live counters (op:agent). Liberal input: `agent("2a04:2a01:…")`,
+ * One agent's detail + live counters (op:agent). Liberal input: `agent("2a04:2a01:...")`,
  * `agent("agent-id")`, or `agent({ agent })` / `agent({ address })`. A value with a colon
  * is treated as a /128 address. → the detail record, or null if not in your account.
  */
@@ -454,3 +454,380 @@ export async function agent(sel = {}, maybeOpts) {
   const recs = await callControl("agent", args, o);
   return recs.length ? recs[0] : null;
 }
+
+// ── Graph (keyed Cypher over the Whisper Security graph) ─────────────────────────────
+// The intelligence half of the keyed surface. Postel two-tier holds cleanly: the keyless
+// identity calls above (verify/verifyDetails/rdap) run with NO key and touch NO Cypher;
+// this whole `graph` namespace is KEYED (Kaveh's absolute rule: if it is Cypher, it needs
+// a key). It POSTs raw Cypher to the SAME endpoint the control plane uses
+// (https://graph.whisper.security/api/query, X-API-Key), reusing resolveKey() so there is
+// one auth path, not two. It does NOT go through the whisper.agents() control wrapper: the
+// graph contract is different (body {query,parameters}; reply {columns,rows,statistics}
+// where rows are already column-keyed objects), so it has its own choke point, callGraph().
+//
+// Source of truth for the 29 methods is the Whisper query catalog (catalog.json +
+// sdk-methods.json): the GRAPH_METHODS table below is GENERATED from it by
+// scripts/gen-graph.mjs (`npm run gen`), so this SDK cannot drift from the catalog. The
+// 14 `direct` entries run their catalog Cypher against /api/query; the 15 `flow` entries
+// EXECUTE on the workflow runner (POST gallery/run, Server-Sent Events) via callFlow().
+// Every method carries its canonical docs URL as `.docs`. graph.query() is the raw
+// escape hatch.
+
+function graphUrl() {
+  // Defaults to the control endpoint, which already IS the graph endpoint. Override for tests
+  // or a private deployment. WHISPER_GRAPH_URL wins, then the shared control URL.
+  return process.env.WHISPER_GRAPH_URL || controlUrl();
+}
+
+// Normalise the /api/query reply into { columns, rows, statistics }. Per the contract rows
+// are OBJECTS keyed by column name; we also accept a positional-array row (aligned to
+// columns) so a liberal server shape still decodes. Never throws on shape.
+function normalizeGraph(body) {
+  if (!body || typeof body !== "object") return { columns: [], rows: [], statistics: null };
+  const columns = Array.isArray(body.columns) ? body.columns : [];
+  const rawRows = Array.isArray(body.rows) ? body.rows : [];
+  const rows = rawRows.map((row) => {
+    if (Array.isArray(row)) {
+      const m = {};
+      columns.forEach((c, i) => { if (i < row.length) m[c] = row[i]; });
+      return m;
+    }
+    return row && typeof row === "object" ? row : { value: row };
+  });
+  return { columns, rows, statistics: body.statistics || null };
+}
+
+// The one place that talks to the graph. Requires a key (via the shared resolveKey), POSTs
+// {query,parameters}, and on an HTTP>=400 or an RFC-7807 problem body throws a WhisperError
+// carrying the server's helpful detail (plus .status/.retryAfter). The key is only ever sent
+// in X-API-Key: never logged, never on argv, never returned.
+async function callGraph(cypher, params, opts = {}, methodName = "query") {
+  const key = resolveKey(opts);
+  if (!key) {
+    throw new WhisperError(
+      `\`graph.${methodName}\` needs a Whisper API key: pass { apiKey } or set WHISPER_API_KEY. ` +
+        "(verify/verifyDetails/rdap are keyless and need no key; graph queries are Cypher, so they do.)"
+    );
+  }
+  const url = graphUrl();
+  const timeout = opts.timeout || 60000;
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-API-Key": key,
+        "User-Agent": UA,
+      },
+      body: JSON.stringify({ query: cypher, parameters: params || {} }),
+      signal: ctrl.signal,
+    });
+  } catch (err) {
+    throw new WhisperError(`could not reach the Whisper graph at ${url}: ${err && err.message ? err.message : err}`);
+  } finally {
+    clearTimeout(t);
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  // A fault is either an HTTP error status or a problem body (has error/detail/title but no
+  // result table). A valid table always carries columns/rows, so those are never a fault.
+  const hasTable = body && typeof body === "object" && (Array.isArray(body.columns) || Array.isArray(body.rows));
+  const problem = body && typeof body === "object" && (body.error || (!hasTable && (body.detail || body.title || body.type)));
+  if (res.status >= 400 || problem) {
+    const e = (body && (body.error || body)) || {};
+    const werr = new WhisperError(e.detail || e.title || e.message || e.type || `graph query returned HTTP ${res.status}`);
+    werr.status = e.status || res.status;
+    if (e.retry_after != null) werr.retryAfter = e.retry_after;
+    throw werr;
+  }
+  return normalizeGraph(body);
+}
+
+// BEGIN GENERATED: graph catalog (scripts/gen-graph.mjs) - do not edit by hand
+// The Whisper query catalog, one row per entry (14 direct + 15 flow), in catalog order.
+// A direct row carries its catalog Cypher (input bound as a $-parameter); a flow row
+// carries its gallery/run slug plus the input/param names the workflow runner accepts;
+// the map-call row (submit) enumerates its fields. `docs` is the canonical docs URL.
+const GRAPH_DOCS_BASE = "https://www.whisper.security";
+const GRAPH_FLOW_RUN_URL = "https://console.whisper.security/api/gallery/run";
+const GRAPH_METHODS = [
+  { name: "anycastDnsRootSovereignty", mode: "flow", slug: "anycast-dns-root-sovereignty", primary: "country", inputs: ["country"], params: ["instanceType"], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "attackPath", mode: "flow", slug: "attack-path", primary: "value", inputs: ["value", "other"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/attack-path" },
+  { name: "attackSurface", mode: "flow", slug: "attack-surface", primary: "domain", inputs: ["domain"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "bgpHijackExposure", mode: "flow", slug: "bgp-hijack-exposure", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/bgp-routing" },
+  { name: "blastRadius", mode: "flow", slug: "blast-radius", primary: "indicator", inputs: ["indicator"], params: ["depth"], docs: GRAPH_DOCS_BASE + "/docs/recipes/soc" },
+  { name: "buildTakedownEvidencePackage", mode: "flow", slug: "build-takedown-evidence-package", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/threat-intel" },
+  { name: "discoverAiAgentInfrastructure", mode: "flow", slug: "discover-ai-agent-infrastructure", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "indicator", mode: "flow", slug: "indicator", primary: "indicator", inputs: ["indicator"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/soc" },
+  { name: "indicatorEnrichment", mode: "flow", slug: "indicator-enrichment", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/dns-email" },
+  { name: "infrastructureMapping", mode: "flow", slug: "infrastructure-mapping", primary: "value", inputs: ["value"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "mapSupplyChainConcentration", mode: "flow", slug: "map-supply-chain-concentration", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "nameserverHijackDnsConsistency", mode: "flow", slug: "nameserver-hijack-dns-consistency", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/dns-email" },
+  { name: "routeHealth", mode: "flow", slug: "route-health", primary: "target", inputs: ["target"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/bgp-routing" },
+  { name: "subdomainTakeover", mode: "flow", slug: "subdomain-takeover", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "typosquat", mode: "flow", slug: "typosquat", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/brand-protection" },
+  { name: "identify", mode: "direct", input: "v", cypher: "CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/identify" },
+  { name: "assess", mode: "direct", input: "v", cypher: "CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "variants", mode: "direct", input: "v", cypher: "CALL whisper.variants($v) YIELD variant, method, exists, confidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/variants" },
+  { name: "walk", mode: "direct", input: "v", cypher: "CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "explain", mode: "direct", input: "v", cypher: "CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/explain" },
+  { name: "pslTldplusone", mode: "direct", input: "v", cypher: "CALL whisper.psl.tldPlusOne($v) YIELD apex", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "pslAffiliation", mode: "direct", input: "v", cypher: "CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "origins", mode: "direct", input: "v", cypher: "CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/origins" },
+  { name: "history", mode: "direct", input: "v", cypher: "CALL whisper.history($v)", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/history" },
+  { name: "historyWhois", mode: "direct", input: "v", cypher: "CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/history" },
+  { name: "asset", mode: "direct", input: "v", cypher: "CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "lookupTorRelay", mode: "direct", input: "v", cypher: "CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "dbSchema", mode: "direct", input: null, cypher: "CALL db.schema()", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/schema" },
+  { name: "submit", mode: "direct", proc: "whisper.submit", fields: [["kind", "kind"], ["identifierKind", "identifier_kind"], ["value", "value"], ["observationId", "observation_id"], ["confidence", "confidence"], ["firstSeen", "first_seen"], ["provenance", "provenance"], ["query", "query"], ["results", "results"], ["comment", "comment"], ["severity", "severity"], ["v", "v"]], requires: ["kind"], docs: GRAPH_DOCS_BASE + "/docs/cypher-api" },
+];
+// END GENERATED: graph catalog
+
+// Coerce a liberal first arg into the string value bound as $v. Accepts a bare value or a
+// { value } / { v } wrapper; empty is rejected with a clear error, never an opaque failure.
+function graphValue(name, value) {
+  let v = value;
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    if (v.value !== undefined) v = v.value;
+    else if (v.v !== undefined) v = v.v;
+  }
+  if (v === null || v === undefined || String(v).trim() === "") {
+    throw new WhisperError(`graph.${name}() needs a value (a host, IP, domain, or ASN)`);
+  }
+  return String(v).trim();
+}
+
+/**
+ * Run raw Cypher against the Whisper Security graph (keyed). The escape hatch under every
+ * typed method: `graph.query("MATCH (n) RETURN n LIMIT 1", {}, { apiKey })`. Returns the
+ * full `{ columns, rows, statistics }` (rows are objects keyed by column name).
+ * @see https://www.whisper.security/docs/cypher-api
+ */
+async function graphQuery(cypher, params, opts = {}) {
+  if (!cypher || !String(cypher).trim()) throw new WhisperError("graph.query() needs a Cypher string");
+  return callGraph(String(cypher), params || {}, opts, "query");
+}
+
+// ── Flow runner (gallery/run, Server-Sent Events) ───────────────────────────────────
+// A flow entry is a multi-step read workflow orchestrated by the Whisper workflow runner:
+// POST {slug, inputs, params} to the gallery/run endpoint (keyed, X-API-Key) and consume
+// the SSE stream. Each `step` event carries a step's bound Cypher + rows; the terminal
+// `complete` event carries the aggregate context. callFlow() collects the whole stream and
+// resolves to { slug, steps, complete, events } - one call, the full flow.
+
+function flowRunUrl() {
+  return process.env.WHISPER_FLOW_URL || GRAPH_FLOW_RUN_URL;
+}
+
+// Liberal-accept (RFC 761): coerce the caller's input into the runner's {inputs, params}.
+// A bare value binds to the flow's primary input; a plain object routes each key by name
+// (a known knob name goes to params, everything else to inputs); an explicit
+// { inputs, params } wrapper passes through untouched.
+function flowBody(m, input) {
+  const inputs = {};
+  const params = {};
+  if (input === null || input === undefined) return { inputs, params };
+  if (typeof input !== "object" || Array.isArray(input)) {
+    const v = String(input).trim();
+    if (v === "") throw new WhisperError(`graph.${m.name}() needs a value for its \`${m.primary}\` input (a host, IP, domain, ASN, or prefix)`);
+    inputs[m.primary] = v;
+    return { inputs, params };
+  }
+  if ((input.inputs && typeof input.inputs === "object") || (input.params && typeof input.params === "object")) {
+    return { inputs: { ...(input.inputs || {}) }, params: { ...(input.params || {}) } };
+  }
+  for (const [k, v] of Object.entries(input)) {
+    if (v === undefined) continue;
+    if (m.params.includes(k)) params[k] = v;
+    else inputs[k] = v;
+  }
+  return { inputs, params };
+}
+
+// Parse one SSE record ("event: x\ndata: {...}") into { event, data }; data is JSON-decoded
+// when possible, else kept as the raw string. Never throws on shape.
+function parseSseRecord(record) {
+  let event = "message";
+  const dataLines = [];
+  for (const line of record.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  let data = dataLines.join("\n");
+  try {
+    data = JSON.parse(data);
+  } catch {
+    // not JSON - keep the raw string
+  }
+  return { event, data };
+}
+
+// The one place that talks to the workflow runner. Requires a key (shared resolveKey),
+// POSTs {slug, inputs, params}, consumes the SSE stream, and resolves to the collected
+// { slug, steps, complete, events }. Flows are multi-step, so the default timeout is 5
+// minutes (override with opts.timeout). On an HTTP error, an `error` event, or a stream
+// that ends with no result at all, throws a WhisperError with the server's clear detail.
+async function callFlow(m, input, opts = {}) {
+  const key = resolveKey(opts);
+  if (!key) {
+    throw new WhisperError(
+      `\`graph.${m.name}\` needs a Whisper API key: pass { apiKey } or set WHISPER_API_KEY. ` +
+        "(verify/verifyDetails/rdap are keyless and need no key; flows run keyed on the workflow runner.)"
+    );
+  }
+  const { inputs, params } = flowBody(m, input);
+  const url = flowRunUrl();
+  const timeout = opts.timeout || 300000;
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+          "X-API-Key": key,
+          "User-Agent": UA,
+        },
+        body: JSON.stringify({ slug: m.slug, inputs, params }),
+        signal: ctrl.signal,
+      });
+    } catch (err) {
+      throw new WhisperError(`could not reach the Whisper workflow runner at ${url}: ${err && err.message ? err.message : err}`);
+    }
+    if (res.status >= 400) {
+      let body = null;
+      try {
+        body = await res.json();
+      } catch {
+        body = null;
+      }
+      const e = body && typeof body === "object" ? body : {};
+      const werr = new WhisperError(
+        e.message || e.detail || (typeof e.error === "string" ? e.error : null) || `the workflow runner returned HTTP ${res.status}`
+      );
+      werr.status = res.status;
+      throw werr;
+    }
+    // Liberal accept: a plain-JSON reply (no stream) is decoded as the complete result.
+    const ct = res.headers && typeof res.headers.get === "function" ? res.headers.get("content-type") || "" : "";
+    if (ct.includes("json")) {
+      let body = null;
+      try {
+        body = await res.json();
+      } catch {
+        body = null;
+      }
+      return { slug: m.slug, steps: [], complete: body && typeof body === "object" ? body : null, events: [] };
+    }
+    // The SSE stream: split records on blank lines (CRLF-safe), decode each.
+    const events = [];
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    const drain = () => {
+      buf = buf.replace(/\r\n/g, "\n");
+      let i;
+      while ((i = buf.indexOf("\n\n")) !== -1) {
+        const rec = buf.slice(0, i);
+        buf = buf.slice(i + 2);
+        if (rec.trim() !== "") events.push(parseSseRecord(rec));
+      }
+    };
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      drain();
+    }
+    buf += decoder.decode();
+    drain();
+    if (buf.trim() !== "") events.push(parseSseRecord(buf));
+    const steps = events.filter((ev) => ev.event === "step").map((ev) => ev.data);
+    const completeEv = events.findLast((ev) => ev.event === "complete");
+    const complete = completeEv && completeEv.data && typeof completeEv.data === "object" ? completeEv.data : null;
+    const errEv = events.find((ev) => ev.event === "error");
+    if (errEv && !complete) {
+      const d = errEv.data && typeof errEv.data === "object" ? errEv.data : { detail: String(errEv.data || "") };
+      const werr = new WhisperError(d.message || d.detail || (typeof d.error === "string" ? d.error : null) || `graph.${m.name} failed on the workflow runner`);
+      werr.events = events;
+      throw werr;
+    }
+    if (!complete && steps.length === 0) {
+      const werr = new WhisperError(`graph.${m.name}: the flow stream ended without a step or complete event`);
+      werr.events = events;
+      throw werr;
+    }
+    return { slug: m.slug, steps, complete, events };
+  } catch (err) {
+    if (err instanceof WhisperError) throw err;
+    if ((err && err.name === "AbortError") || ctrl.signal.aborted) {
+      throw new WhisperError(`graph.${m.name} timed out after ${timeout}ms (flows are multi-step; raise { timeout } if you need longer)`);
+    }
+    throw new WhisperError(`graph.${m.name} failed while streaming from the workflow runner: ${err && err.message ? err.message : err}`);
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// The map-call write (whisper.submit): each payload field becomes one entry of a Cypher
+// map with its value bound as its own $-parameter (injection-safe), keys in SORTED order
+// so the query is byte-stable. Field names are accepted in both catalog spellings
+// (camelCase id or snake_case paramName) and normalised to the wire form; any extra key
+// must be a plain identifier, and the server validates the full set per kind.
+function makeMapCall(m) {
+  const canon = new Map();
+  for (const [id, param] of m.fields) {
+    canon.set(id, param);
+    canon.set(param, param);
+  }
+  return async (payload, opts = {}) => {
+    const p = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+    const bound = {};
+    for (const [k, v] of Object.entries(p)) {
+      if (v === undefined) continue;
+      const name = canon.get(k) || k;
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new WhisperError(`graph.${m.name}() field ${JSON.stringify(k)} is not a valid field name (letters, digits, _)`);
+      }
+      bound[name] = v;
+    }
+    for (const req of m.requires) {
+      if (bound[req] === null || bound[req] === undefined || String(bound[req]).trim() === "") {
+        throw new WhisperError(`graph.${m.name}() needs a { ${req} } of 'indicator' or 'feedback' (plus its fields)`);
+      }
+    }
+    const keys = Object.keys(bound).sort();
+    const cypher = `CALL ${m.proc}({` + keys.map((k) => `${k}:$${k}`).join(", ") + "})";
+    return callGraph(cypher, bound, opts, m.name);
+  };
+}
+
+// Build the namespace from the generated catalog table: query + one method per entry.
+// Direct methods run their catalog Cypher; the map-call write builds its parameter map;
+// flow methods execute on the workflow runner. Every method carries its canonical docs
+// URL as `.docs` (docsBase + the entry's docPath).
+const graph = { query: graphQuery };
+graph.query.docs = GRAPH_DOCS_BASE + "/docs/cypher-api";
+
+for (const m of GRAPH_METHODS) {
+  if (m.mode === "flow") {
+    graph[m.name] = async (input, opts = {}) => callFlow(m, input, opts);
+  } else if (m.fields) {
+    graph[m.name] = makeMapCall(m);
+  } else if (m.input) {
+    graph[m.name] = async (value, opts = {}) => callGraph(m.cypher, { [m.input]: graphValue(m.name, value) }, opts, m.name);
+  } else {
+    graph[m.name] = async (opts = {}) => callGraph(m.cypher, {}, opts, m.name);
+  }
+  graph[m.name].docs = m.docs;
+}
+
+export { graph };

package/package.json

@@ -1,16 +1,42 @@
 {
   "name": "whisper-id",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A routable Whisper IPv6 identity and safe egress for any Node agent.",
   "type": "module",
-  "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
   "types": "./index.d.ts",
-  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node --test" },
-  "keywords": ["whisper", "agent", "identity", "ipv6", "egress", "proxy", "dns"],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "gen": "node scripts/gen-graph.mjs"
+  },
+  "keywords": [
+    "whisper",
+    "agent",
+    "identity",
+    "ipv6",
+    "egress",
+    "proxy",
+    "dns"
+  ],
   "homepage": "https://whisper.online",
-  "repository": { "type": "git", "url": "https://github.com/whisper-sec/whisper-node.git" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/whisper-sec/whisper-node.git"
+  },
   "license": "MIT",
   "author": "Whisper Security"
 }