whisper-id 0.3.0 → 0.4.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,55 @@ 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) run via the Whisper workflow runner, not a single Cypher
+call, so they are not wired into this SDK yet: calling one rejects with a clear `WhisperError`
+(carrying `.runVia`) telling you which workflow to run. Use `graph.query` for raw Cypher meanwhile.
+
 ### 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 +144,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 +154,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,101 @@ 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 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). It POSTs raw Cypher to
+// the same endpoint the control plane uses, with the key only in `X-API-Key`. `direct`
+// methods run their Cypher and resolve to a `GraphResult`; the 15 `flow` methods are
+// workflow-runner reads not wired here, so calling one rejects with a clear `WhisperError`.
+
+/** 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;
+  [k: string]: unknown;
+}
+
+/**
+ * The keyed graph namespace: typed Cypher methods over the Whisper Security graph, plus a
+ * raw `query` escape hatch. Every method needs a key (`{ apiKey }` or `WHISPER_API_KEY`).
+ */
+export interface GraphNamespace {
+  /** Raw Cypher escape hatch. Returns the full `{columns,rows,statistics}`. */
+  query(cypher: string, params?: Record<string, unknown>, opts?: GraphOptions): Promise<GraphResult>;
+
+  /** Name the vendor and operator role behind a host or IP in one call. */
+  identify(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Labelled threat posture for a host or IP: malicious, benign, or unknown. */
+  assess(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Generate look-alike domain variants of a brand and see which are registered. */
+  variants(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Walk the graph to the nearest known vendors behind a host, with channel and confidence. */
+  walk(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Score an indicator against the threat feeds and explain exactly why. */
+  explain(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Reduce any hostname to its registrable apex (eTLD+1) via the Public Suffix List. */
+  pslTldplusone(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Check whether a domain is a PSL private-section suffix and who submitted it. */
+  pslAffiliation(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Find the real origin IPs behind a CDN-fronted domain, ranked by confidence. */
+  origins(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Full historical WHOIS timeline for a domain. */
+  history(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** WHOIS-only historical timeline for a domain. */
+  historyWhois(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** List the member ASNs of an AS-SET macro. */
+  asset(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** Check whether an IP is a known Tor exit relay. */
+  lookupTorRelay(value: string, opts?: GraphOptions): Promise<GraphResult>;
+  /** List every node and relationship type in the graph with counts and examples. No input. */
+  dbSchema(opts?: GraphOptions): Promise<GraphResult>;
+  /** Contribute an indicator observation or feedback back into the graph (keyed WRITE). */
+  submit(payload: GraphSubmission, opts?: GraphOptions): Promise<GraphResult>;
+
+  // The 15 `flow` workflow-runner methods. Not wired into this SDK: each rejects with a clear
+  // WhisperError (carrying `.runVia`). Run them via the console/agent workflow runner.
+  /** Workflow (run_workflow): assess a country's DNS-root sovereignty. Not wired here. */
+  anycastDnsRootSovereignty(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): find the choke points an attacker would target. Not wired here. */
+  attackPath(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): map a domain's externally exposed attack surface. Not wired here. */
+  attackSurface(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): grade a network's routing security. Not wired here. */
+  bgpHijackExposure(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): what breaks if one asset fails, and its dependencies. Not wired here. */
+  blastRadius(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): assemble a takedown evidence dossier. Not wired here. */
+  buildTakedownEvidencePackage(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): map an org's externally visible AI/agent endpoints. Not wired here. */
+  discoverAiAgentInfrastructure(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): investigate one indicator in depth. Not wired here. */
+  indicator(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): turn one domain/IP into a full context card. Not wired here. */
+  indicatorEnrichment(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): trace an indicator to its true owner and estate. Not wired here. */
+  infrastructureMapping(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): grade an org for supply-chain concentration. Not wired here. */
+  mapSupplyChainConcentration(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): check name servers for DNS-hijack misconfigurations. Not wired here. */
+  nameserverHijackDnsConsistency(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): profile a network/block into a routing health card. Not wired here. */
+  routeHealth(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): find subdomains that point at claimable services. Not wired here. */
+  subdomainTakeover(opts?: GraphOptions): Promise<never>;
+  /** Workflow (run_workflow): find registered look-alikes of your brand. Not wired here. */
+  typosquat(opts?: GraphOptions): Promise<never>;
+}
+
+/** 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,201 @@ 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 tables below are copied from it (keyed by exec.mode). A test
+// asserts the count so the two cannot silently drift. 14 `direct` entries run their catalog
+// Cypher against /api/query; 15 `flow` entries run via the workflow runner (run_workflow),
+// which is NOT a single /api/query Cypher, so they are shipped as clearly-noted stubs and
+// are not wired to an engine here. 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);
+}
+
+// The 14 `direct` catalog entries: id (camelCased) -> its catalog Cypher. Every one binds a
+// single input as $v (paramName `v` in the catalog), except dbSchema (no input) and submit
+// (a write map, handled below). Copied verbatim from whisper-catalog/catalog.json.
+const GRAPH_DIRECT = {
+  identify: "CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band",
+  assess: "CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence",
+  variants: "CALL whisper.variants($v) YIELD variant, method, exists, confidence",
+  walk: "CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings",
+  explain: "CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources",
+  pslTldplusone: "CALL whisper.psl.tldPlusOne($v) YIELD apex",
+  pslAffiliation: "CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence",
+  origins: "CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind",
+  history: "CALL whisper.history($v)",
+  historyWhois: "CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers",
+  asset: "CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir",
+  lookupTorRelay: "CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt",
+};
+
+// The 15 `flow` catalog entries: id (camelCased) -> its runVia slug. These are multi-step
+// read workflows run by the console/agent workflow runner, NOT a single /api/query Cypher,
+// so they are not wired to an engine in this SDK. Copied verbatim from the catalog.
+const GRAPH_FLOW = {
+  anycastDnsRootSovereignty: "run_workflow (anycast-dns-root-sovereignty)",
+  attackPath: "run_workflow (attack-path)",
+  attackSurface: "run_workflow (attack-surface)",
+  bgpHijackExposure: "run_workflow (bgp-hijack-exposure)",
+  blastRadius: "run_workflow (blast-radius)",
+  buildTakedownEvidencePackage: "run_workflow (build-takedown-evidence-package)",
+  discoverAiAgentInfrastructure: "run_workflow (discover-ai-agent-infrastructure)",
+  indicator: "run_workflow (indicator)",
+  indicatorEnrichment: "run_workflow (indicator-enrichment)",
+  infrastructureMapping: "run_workflow (infrastructure-mapping)",
+  mapSupplyChainConcentration: "run_workflow (map-supply-chain-concentration)",
+  nameserverHijackDnsConsistency: "run_workflow (nameserver-hijack-dns-consistency)",
+  routeHealth: "run_workflow (route-health)",
+  subdomainTakeover: "run_workflow (subdomain-takeover)",
+  typosquat: "run_workflow (typosquat)",
+};
+
+// 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).
+ */
+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");
+}
+
+// Build the namespace: query + a typed method per catalog entry. Direct methods run their
+// Cypher; flow methods throw a clear, honest "runs via the workflow runner, not wired here"
+// error (never a silent no-op) and carry .runVia for programmatic inspection.
+const graph = { query: graphQuery };
+
+for (const [name, cypher] of Object.entries(GRAPH_DIRECT)) {
+  graph[name] = async (value, opts = {}) => callGraph(cypher, { v: graphValue(name, value) }, opts, name);
+}
+
+/** List every node and relationship type in the graph with counts and examples (keyed). No input. */
+graph.dbSchema = async (opts = {}) => callGraph("CALL db.schema()", {}, opts, "dbSchema");
+
+/**
+ * Contribute an indicator observation or feedback back into the graph (keyed WRITE). Pass
+ * `{ kind: "indicator" | "feedback", ...fields }`. The payload is bound as a single Cypher
+ * parameter (injection-safe). The server enforces its own write scopes and rejects anonymous
+ * callers, so a scope/quota fault surfaces as the server's WhisperError detail.
+ */
+graph.submit = async (payload, opts = {}) => {
+  const p = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  if (!p.kind || String(p.kind).trim() === "") {
+    throw new WhisperError("graph.submit() needs a { kind } of 'indicator' or 'feedback' (plus its fields)");
+  }
+  return callGraph("CALL whisper.submit($submission)", { submission: p }, opts, "submit");
+};
+
+for (const [name, runVia] of Object.entries(GRAPH_FLOW)) {
+  graph[name] = () => {
+    const err = new WhisperError(
+      `graph.${name}() is a multi-step read workflow: it runs via the Whisper workflow runner ` +
+        `(${runVia}), not a single /api/query Cypher, and is not wired into this SDK yet. Use ` +
+        "graph.query() for a raw Cypher call, or run the workflow via the console/agent runner."
+    );
+    err.runVia = runVia;
+    return Promise.reject(err);
+  };
+}
+
+export { graph };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whisper-id",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A routable Whisper IPv6 identity and safe egress for any Node agent.",
   "type": "module",
   "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },