whisper-id 0.6.1 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # whisper-id
 
-Three things for any Node agent, in one dependency-free package: query the **Whisper security graph** (3.6B nodes / 30B relationships, Cypher), give the agent a routable **IPv6 identity** with safe **egress**, and drive the full **control plane**.
+Three things for any Node agent, in one dependency-free package: query the **Whisper security graph** (7.48B nodes and 39.5B edges joining the physical, network, naming, ownership and threat layers; live totals at nic.whisper.online/stats, Cypher), give the agent a routable **IPv6 identity** with safe **egress**, and drive the full **control plane**.
 
 ```sh
 npm i whisper-id
@@ -8,7 +8,7 @@ npm i whisper-id
 
 ## The security graph (keyless, zero setup)
 
-The Whisper graph knows who operates a host, its threat posture, its look-alikes, the real origins behind a CDN, WHOIS history, and 20+ named investigations. The **direct read verbs run with no key at all** (rate-limited taste, ~100/window). One import, real answers:
+The Whisper graph knows who operates a host, its threat posture, its look-alikes, the real origins behind a CDN, WHOIS history, and 15 named investigations. The **direct read verbs run with no key at all** (rate-limited taste, ~100/window). One import, real answers:
 
 ```js
 import { graph } from "whisper-id";                // no key needed for the read verbs
@@ -19,7 +19,7 @@ await graph.origins("cloudflare.com");             // the real origin IPs behind
 await graph.explain("paypal.com");                 // threat-feed score + why
 ```
 
-Set `WHISPER_API_KEY` (or pass `{ apiKey }`) to lift the rate limit and unlock **raw Cypher** and the **multi-step flows**:
+Set `WHISPER_API_KEY` (or pass `{ apiKey }`) to lift the keyless rate limit. Every verb is sent either way; the graph decides what to answer:
 
 ```js
 // raw Cypher, your own query, parameters bound as $-params (never string-built):
@@ -35,7 +35,7 @@ for (const r of graph.recipes()) {
 }
 ```
 
-Every verb maps to a catalog entry with its own docs page under [whisper.security/docs](https://www.whisper.security/docs) (e.g. [`assess`](https://www.whisper.security/docs/whisper-graph/procedures), [`identify`](https://www.whisper.security/docs/whisper-graph/procedures/identify)); `recipes()` carries the exact `docsUrl` for each, and the same URL sits on every method as `graph.identify.docs` and on its `@see` tag in your editor. The 13 direct reads are keyless; the 15 multi-step flows and the `submit` write channel are keyed. Full query reference: [whisper-catalog](https://github.com/whisper-sec/whisper-catalog).
+Every verb maps to a catalog entry with its own docs page under [whisper.security/docs](https://www.whisper.security/docs) (e.g. [`assess`](https://www.whisper.security/docs/whisper-graph/procedures), [`identify`](https://www.whisper.security/docs/whisper-graph/procedures/identify)); `recipes()` carries the exact `docsUrl` for each, and the same URL sits on every method as `graph.identify.docs` and on its `@see` tag in your editor. The 13 direct reads answer keyless; the 15 multi-step flows and the `submit` write channel are proxied up the same way and the graph decides. Full query reference: [whisper-catalog](https://github.com/whisper-sec/whisper-catalog).
 
 ## Identity + egress
 
@@ -78,12 +78,12 @@ if (await verify(addr)) console.log((await rdap(addr)).name);   // keyless, pure
 | `graph.asset(value)` | yes | Member ASNs of an AS-SET macro |
 | `graph.lookupTorRelay(value)` | yes | Is an IP a known Tor exit relay |
 | `graph.dbSchema()` | yes | Every node + relationship type in the graph, with counts and examples |
-| `graph.query(cypher, params)` | key | Raw Cypher escape hatch. -> the full `{ columns, rows, statistics }` |
+| `graph.query(cypher, params)` | yes | Raw Cypher escape hatch. -> the full `{ columns, rows, statistics }` |
 | `graph.submit({ kind, ...fields })` | key | Contribute an indicator observation or feedback (the write channel) |
 | `graph.recipes()` | yes (offline) | The whole catalog: `{ method, keyless, mode, summary, params, docsUrl }` per verb |
 
 Fifteen multi-step **workflow** methods (`attackPath`, `attackSurface`, `blastRadius`, `typosquat`,
-`indicator`, `routeHealth`, and 9 more) execute keyed on the Whisper workflow runner and stream
+`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
@@ -114,7 +114,10 @@ Run anywhere `fetch` runs (Cloudflare Workers, Vercel, Deno, Lambda, the browser
 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`).
+carrying the server's message (plus `.code` / `.status` / `.retryable` / `.retryAfter`). A
+`revoke` that matches nothing of yours (revoked already, or not in your account) throws
+`NotFoundError` (`.code` `NOT_FOUND`, `.status` 404, not retryable): nothing was revoked, so
+do not retry it.
 
 | Call | Does |
 |------|------|
@@ -165,14 +168,15 @@ transparently inside `withEgress`.
 
 Zero dependencies. The **graph read verbs**, the **keyless** checks, and the **control plane** are
 pure HTTP (Node ≥ 18's global `fetch`), with no CLI and nothing to install. Set `WHISPER_API_KEY`
-(or pass `{ apiKey }`) for the control plane and the keyed graph (raw Cypher + flows + `submit`);
-the graph read verbs, `verify`, and `rdap` need no key.
+(or pass `{ apiKey }`) for the control plane (`whisper.agents`), which always needs it. Graph calls
+never require a key from this SDK: they go up with one or without, and the graph decides what to
+answer. A key lifts the keyless rate limit. `verify` and `rdap` need no key either.
 
 Only **egress** and the CLI-backed calls (`register`, `egress`, `withEgress`, `ip`) need the
 `whisper` CLI on your `PATH`:
 
 ```sh
-curl get.whisper.online | sh
+curl -fsSL https://get.whisper.online | sh
 ```
 
 (`$WHISPER_BIN` overrides the CLI path; `$WHISPER_CONTROL_URL` / `$WHISPER_GRAPH_URL` /

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately to **security@whisper.security**. Do not
+open a public issue for a suspected vulnerability.
+
+Include what you found, how to reproduce it, and the impact you expect. We aim to
+acknowledge within a few business days and will keep you updated as we work on a
+fix. Coordinated disclosure is appreciated.
+
+## Scope
+
+This repository is the **Node client** for Whisper: the control plane
+(`whisper.agents`), the keyless public checks, and the Whisper security graph. It
+talks only to Whisper's public endpoints and holds no server-side secrets.
+
+Your API key travels in one place and one place only: the `X-API-Key` request
+header. It is never written to a URL, a request body, a log line, or argv. A call
+made without a key sends no auth header at all rather than an empty one. Any
+deviation from that is a security bug and is in scope, as are the input validation
+and the redaction of keys from error text.
+
+## Supported versions
+
+The latest published release receives security fixes. Older versions may not.

package/index.d.ts

@@ -1,6 +1,30 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2026 viaGraph B.V. (Whisper Security)
-export declare class WhisperError extends Error {}
+/**
+ * Thrown when a `whisper` invocation fails, the CLI is missing, or the control plane refuses
+ * a call. A control-plane refusal carries the server's `code`, `status` and `retryable`.
+ */
+export declare class WhisperError extends Error {
+  /** The server's error code, e.g. "NOT_FOUND" or "FORBIDDEN", when it gave one. */
+  code?: string;
+  /** The effective HTTP/envelope status of a control-plane refusal. */
+  status?: number;
+  /** Whether the server says retrying could succeed. */
+  retryable?: boolean;
+  /** Seconds the server asked the caller to wait (rate limits). */
+  retryAfter?: number;
+  suggestions?: string[];
+}
+
+/**
+ * Nothing of yours matched: from `revoke()`, nothing was revoked (revoked already, or not in
+ * your account). An answer, not a fault: never retry it.
+ */
+export declare class NotFoundError extends WhisperError {
+  code: "NOT_FOUND";
+  status: 404;
+  retryable: false;
+}
 
 export interface Agent {
   /** The routable IPv6 /128 - both the identity and the auth. */
@@ -55,7 +79,8 @@ export function firstAddr(obj: unknown): string | null;
 // 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
-// `WhisperError` carrying the server's `detail` (and `.status` / `.retryAfter`).
+// `WhisperError` carrying the server's message (and `.code` / `.status` / `.retryable` /
+// `.retryAfter`); a `NotFoundError` when the server's code is NOT_FOUND.
 
 /** Common options for every keyed control call. */
 export interface ControlOptions {
@@ -142,7 +167,10 @@ 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, ... }`. Throws
+ * `NotFoundError` when nothing was revoked (revoked already, or not in your account).
+ */
 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}`. */
@@ -157,7 +185,7 @@ export function agent(opts?: AgentSelectOptions): Promise<AgentItem | null>;
 // KEYLESS - no key at all, a rate-limited taste with real answers; a key ({ apiKey } or
 // WHISPER_API_KEY) lifts the limit. Raw Cypher (`graph.query`), the 15 multi-step `flow`
 // methods (workflow runner: POST gallery/run, Server-Sent Events), and the `submit`
-// write stay KEYED. A present key rides only in `X-API-Key`; an absent one sends no auth
+// write are proxied up the same way. A present key rides only in `X-API-Key`; an absent one sends no auth
 // header at all. 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`, and `graph.recipes()` lists the whole catalog.
@@ -181,7 +209,7 @@ export interface GraphRecipe {
   docsUrl: string;
 }
 
-/** Result of a keyed graph query. `rows` are objects keyed by column name. */
+/** Result of a graph query. `rows` are objects keyed by column name. */
 export interface GraphResult {
   columns: string[];
   rows: Record<string, unknown>[];
@@ -237,15 +265,18 @@ export interface GraphFlowResult {
 }
 
 /**
- * The graph namespace: one typed method per catalog entry (14 direct Cypher reads +
- * 15 workflow-runner flows), plus a raw `query` escape hatch and `recipes()` discovery.
- * Two-tier: the 13 direct read verbs run keyless (no key needed, rate-limited; a key
- * lifts the limit); `query`, the flows, and `submit` need a key (`{ apiKey }` or
- * `WHISPER_API_KEY`). Every method carries its canonical docs URL as `.docs`.
+ * The graph namespace: one typed method per catalog entry (13 direct Cypher reads,
+ * `submit`, and 15 workflow-runner flows), plus a raw `query` escape hatch and
+ * `recipes()` discovery. Every verb is proxied to the graph with a key if you have one
+ * and without if you do not: the graph owns the keyless policy and decides what to
+ * answer, so the SDK never refuses a call on your behalf. A key (`{ apiKey }` or
+ * `WHISPER_API_KEY`) lifts the keyless rate limit. The control plane (`whisper.agents`:
+ * agents, policy, logs, identity) is a separate surface and always requires a key.
+ * Every method carries its canonical docs URL as `.docs`.
  */
 export interface GraphNamespace {
   /**
-   * Raw Cypher escape hatch (KEYED): run arbitrary Cypher with `params` bound
+   * 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
    */
@@ -268,7 +299,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -281,7 +312,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -294,7 +325,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -307,7 +338,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -320,7 +351,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -333,7 +364,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -346,7 +377,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -360,7 +391,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -373,7 +404,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -386,7 +417,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -399,7 +430,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -412,7 +443,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -425,7 +456,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -439,7 +470,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -452,7 +483,7 @@ export interface GraphNamespace {
    * 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")
+   * 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
@@ -465,7 +496,7 @@ export interface GraphNamespace {
    * Resolves a host/IP to its canonical vendor, category and operator roles (DNS_OPERATOR / CDN
    * / ORIGIN_AS / MAIL_RECEIVER) with a confidence band.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * 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.
@@ -479,7 +510,7 @@ export interface GraphNamespace {
    * Returns a posture label + severity band + sub-labels + coverage + evidence for an indicator;
    * benign-allowlisted vs malicious-evidenced, never a bare score.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence
    * Returns columns: host, label, band, sub_labels, coverage, evidence.
@@ -493,7 +524,7 @@ export interface GraphNamespace {
    * Enumerates permutations (omission, bitsquatting, ...) of a domain, flags which exist, with a
    * per-variant confidence.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.variants($v) YIELD variant, method, exists, confidence
    * Returns columns: variant, method, exists, confidence.
@@ -508,7 +539,7 @@ export interface GraphNamespace {
    * ORIGIN_AS) and confidence, plus siblings and coverage - explains WHY a host maps to a
    * vendor.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * 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.
@@ -523,7 +554,7 @@ export interface GraphNamespace {
    * weight, firstSeen/lastSeen). Two live forms: bare CALL explain($v) (full columns) and CALL
    * whisper.explain($v) (restricted YIELD).
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources
    * Returns columns: indicator, score, level, explanation, sources.
@@ -537,7 +568,7 @@ export interface GraphNamespace {
    * PSL-correct eTLD+1: www.foo.co.uk -> foo.co.uk. The right way to group hosts by the thing
    * someone actually registered.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.psl.tldPlusOne($v) YIELD apex
    * Returns columns: apex.
@@ -551,7 +582,7 @@ export interface GraphNamespace {
    * For a PSL private-section suffix, returns the submitting org/login and evidence kind +
    * confidence; found=false for ordinary registrable domains.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence
    * Returns columns: found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence.
@@ -565,7 +596,7 @@ export interface GraphNamespace {
    * 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.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind
    * Returns columns: ip, confidence, methods, asn, asnName, kind.
@@ -579,7 +610,7 @@ export interface GraphNamespace {
    * Every observed WHOIS snapshot over time: create/update/expiry, registrar, registrant,
    * country, nameservers - the ownership/registration story.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.history($v)
    * Returns columns: indicator, type, queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers, cached.
@@ -593,7 +624,7 @@ export interface GraphNamespace {
    * The registration-record projection of the history timeline: create/update/expiry, registrar,
    * registrant, country, nameservers per snapshot.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * 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.
@@ -608,7 +639,7 @@ export interface GraphNamespace {
    * STRING as-set name, not an integer ASN. (Membership is sparsely populated in the current
    * graph.)
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir
    * Returns columns: asSetName, memberAsn, sourceRir.
@@ -622,7 +653,7 @@ export interface GraphNamespace {
    * Live Tor exit-node check: found + fingerprint + exit-address count + source + ingest time
    * for an IPv4.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt
    * Returns columns: indicator, found, fingerprint, exitAddressCount, source, ingestedAt.
@@ -636,7 +667,7 @@ export interface GraphNamespace {
    * 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.
    *
-   * KEYLESS direct read: runs with NO key at all (a rate-limited taste, real
+   * Direct read: answers with NO key at all (a rate-limited taste, real
    * answers); pass a key ({ apiKey } or WHISPER_API_KEY) to lift the limit.
    * Cypher: CALL db.schema()
    * Returns columns: type, name, count, description, example, sourceLabels, targetLabels, fastPatterns, slowPatterns, bestPractices.
@@ -647,10 +678,11 @@ export interface GraphNamespace {
   /**
    * 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.
+   * The write channel: submit an indicator/feedback with an attributable API key. The graph
+   * requires a key carrying the submit:write scope and answers anonymous callers with a clear
+   * 400, to preserve K-anonymity.
    *
-   * KEYED write: CALL whisper.submit({...}) with the payload fields bound as $-parameters.
+   * 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

package/index.js

@@ -3,8 +3,9 @@
 // whisper-id - the Whisper security graph, a routable IPv6 identity, and safe egress for
 // any Node agent. Dependency-free and two-tier (Postel): the graph's direct read verbs and
 // the identity checks run KEYLESS over plain fetch() (graph.assess("8.8.8.8") needs no key
-// at all); the control plane, raw Cypher, and the flows unlock with WHISPER_API_KEY; only
-// register/egress/ip lean on the `whisper` CLI (https://whisper.online).
+// at all); raw Cypher and the flows are sent the same way and the graph decides. Only the
+// control plane requires WHISPER_API_KEY, and only register/egress/ip lean on the
+// `whisper` CLI (https://whisper.online).
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -15,7 +16,11 @@ const HOSTPORT_RE = /127\.0\.0\.1:(\d{2,5})/;
 const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
 const UA = "whisper-id-node"; // client identifier for the keyless + control HTTP calls
 
-/** Error thrown when a `whisper` invocation fails, or the CLI is not installed. */
+/**
+ * Error thrown when a `whisper` invocation fails, the CLI is not installed, or the control
+ * plane refuses a call. A control-plane refusal carries the server's own `.code` (for example
+ * "NOT_FOUND" or "FORBIDDEN"), `.status` and `.retryable` when the server said them.
+ */
 export class WhisperError extends Error {
   constructor(message) {
     super(message);
@@ -23,6 +28,41 @@ export class WhisperError extends Error {
   }
 }
 
+/**
+ * The control plane understood the call and found nothing of yours to act on. From
+ * revoke() it means nothing was revoked: the agent was revoked already, or it is not in your
+ * account. That is an answer, not a fault, so never retry it. `.code` is "NOT_FOUND",
+ * `.status` is 404, `.retryable` is false, and the message is the server's own.
+ */
+export class NotFoundError extends WhisperError {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+    this.code = "NOT_FOUND";
+    this.status = 404;
+    this.retryable = false;
+  }
+}
+
+// NOT_FOUND is read off the code, on a 404 or with no error status; never off a bare 404,
+// which is a mistyped control URL or a proxy in the way rather than a statement about the agent.
+function isNotFound(e, status) {
+  if (!e || typeof e !== "object") return false;
+  if (String(e.code || "").trim().toUpperCase() !== "NOT_FOUND") return false;
+  return status === 404 || !status || status < 400;
+}
+
+// An older plane's ok:true revoke row whose status is not_found (directly or under item).
+// Only the first of status/state present is read.
+function revokeRowNotFound(rec) {
+  if (!rec || typeof rec !== "object") return false;
+  const row = rec.item && typeof rec.item === "object" ? rec.item : rec;
+  for (const k of ["status", "state"]) {
+    if (typeof row[k] === "string") return row[k].trim().toLowerCase() === "not_found";
+  }
+  return false;
+}
+
 function bin() {
   return process.env.WHISPER_BIN || "whisper";
 }
@@ -35,7 +75,7 @@ async function run(args, { timeout = 120000, check = true } = {}) {
     if (err && err.code === "ENOENT") {
       throw new WhisperError(
         "the `whisper` CLI was not found on PATH. Install it with " +
-          "`curl get.whisper.online | sh` (see https://whisper.online)."
+          "`curl -fsSL https://get.whisper.online | sh` (see https://whisper.online)."
       );
     }
     const out = { stdout: err.stdout || "", stderr: err.stderr || "", code: typeof err.code === "number" ? err.code : 1 };
@@ -308,7 +348,8 @@ function resolveKey(opts) {
 
 // The one place that talks to the control plane. Builds the injection-proof query, POSTs
 // it with the key in X-API-Key, decodes either envelope shape, and throws WhisperError
-// (carrying the server's helpful `detail`, plus .status/.retryAfter) on ok:false. The key
+// (carrying the server's message, plus .code/.status/.retryable/.retryAfter) on ok:false,
+// a NotFoundError when the code is NOT_FOUND. The key
 // is never logged, never placed on argv, never returned.
 async function callControl(op, args, opts = {}) {
   const key = resolveKey(opts);
@@ -349,8 +390,13 @@ async function callControl(op, args, opts = {}) {
   const env = decodeEnvelope(body, res.status);
   if (!env.ok) {
     const e = env.error || {};
-    const werr = new WhisperError(e.detail || e.title || e.type || `control plane returned HTTP ${env.status}`);
+    // The plane's own errors are {code, message, retryable}; RFC 7807 ones use detail/title.
+    const msg = e.detail || e.message || e.title || e.type || `control plane returned HTTP ${env.status}`;
+    if (isNotFound(e, env.status)) throw new NotFoundError(msg);
+    const werr = new WhisperError(msg);
     werr.status = env.status;
+    if (e.code) werr.code = String(e.code);
+    if (typeof e.retryable === "boolean") werr.retryable = e.retryable;
     if (env.retryAfter != null) werr.retryAfter = env.retryAfter;
     if (e.suggestions) werr.suggestions = e.suggestions;
     throw werr;
@@ -402,15 +448,30 @@ 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, ... }`.
+ * `revoke("agent-id")`, `revoke("2a04:2a01:...")`, `revoke("my-label")`, or
+ * `revoke({ agent, apiKey })`. → `{ status, ... }`.
+ *
+ * Throws NotFoundError when nothing was revoked: no agent of yours matches, because it was
+ * revoked already or is not in your account. Do not retry that; list() shows what is left.
+ * Both ways the plane says it throw it: the NOT_FOUND error of current servers, and the
+ * `status: not_found` row older ones answered with ok:true.
  */
 export async function revoke(target, maybeOpts) {
   const o = typeof target === "string" ? maybeOpts || {} : target || {};
   const sel = typeof target === "string" ? target : o.agent;
   if (!sel || !String(sel).trim()) throw new WhisperError("revoke() needs an agent id or /128 address");
-  const recs = await callControl("revoke", { agent: String(sel).trim() }, o);
+  const selector = String(sel).trim();
+  const recs = await callControl("revoke", { agent: selector }, o);
   const rec = recs.length ? recs[0] : {};
+  if (revokeRowNotFound(rec)) {
+    const row = rec.item && typeof rec.item === "object" ? rec.item : rec;
+    const said = [row.message, row.detail].find((v) => typeof v === "string" && v.trim());
+    throw new NotFoundError(
+      said ||
+        `nothing was revoked: no agent of yours matches ${JSON.stringify(selector)}. ` +
+          "If you revoked it before, there is nothing left to revoke; list() shows what is left"
+    );
+  }
   return { status: rec.status || rec.state || "submitted", ...rec };
 }
 
@@ -463,7 +524,7 @@ export async function agent(sel = {}, maybeOpts) {
 // origins, history, historyWhois, asset, lookupTorRelay, dbSchema) run KEYLESS - no key
 // at all, a rate-limited taste (~100/window) with real answers; a key (opts.apiKey or
 // WHISPER_API_KEY) lifts the limit. Raw Cypher (graph.query), the 15 multi-step flows,
-// and the submit write channel stay KEYED. Everything POSTs to the SAME endpoint the
+// and the submit write channel are proxied up the same way. Everything POSTs to the SAME endpoint the
 // control plane uses (https://graph.whisper.online/api/query), reusing resolveKey() so
 // there is one auth path, not two: a present key rides ONLY in the X-API-Key header, an
 // absent one sends NO auth header at all. It does NOT go through the whisper.agents()
@@ -508,17 +569,12 @@ function normalizeGraph(body) {
 // (plus .status/.retryAfter). Two-tier auth (Postel: liberal in what we accept): a keyless
 // method (`keyless: true`) NEVER throws for a missing key - with a key it runs unlimited,
 // without one the X-API-Key header is omitted entirely and the server serves the
-// rate-limited keyless taste. A keyed method with no key fails fast with a helpful error.
+// rate-limited keyless taste. No method is refused here; the graph decides what to answer.
 // 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", keyless = false) {
+async function callGraph(cypher, params, opts = {}) {
+  // Proxy up with whatever key there is, or none: the graph owns the keyless policy and
+  // decides what to answer. The SDK adds no gate the server did not ask for.
   const key = resolveKey(opts) || "";
-  if (!key && !keyless) {
-    throw new WhisperError(
-      `\`graph.${methodName}\` needs a Whisper API key: pass { apiKey } or set WHISPER_API_KEY. ` +
-        "(The direct read verbs - assess, identify, explain, origins, and friends - run keyless " +
-        "with no key at all; raw Cypher, the flows, and submit are keyed. See graph.recipes().)"
-    );
-  }
   const url = graphUrl();
   const timeout = opts.timeout || 60000;
   const ctrl = new AbortController();
@@ -619,14 +675,14 @@ function graphValue(name, value) {
 }
 
 /**
- * Run raw Cypher against the Whisper Security graph (keyed). The escape hatch under every
+ * Run raw Cypher against the Whisper Security graph. 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");
+  return callGraph(String(cypher), params || {}, opts);
 }
 
 /**
@@ -650,7 +706,7 @@ function graphRecipes() {
 
 // ── Flow runner (gallery/run, Server-Sent Events) ───────────────────────────────────
 // A flow entry is a multi-step read workflow orchestrated by the Whisper workflow runner:
-// POST {slug, value, paramValues} to the gallery/run endpoint (keyed, X-API-Key) and consume
+// POST {slug, value, paramValues} to the gallery/run endpoint (X-API-Key when set) 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.
@@ -732,19 +788,15 @@ function parseSseRecord(record) {
   return { event, data };
 }
 
-// The one place that talks to the workflow runner. Requires a key (shared resolveKey),
-// POSTs {slug, value, paramValues}, consumes the SSE stream, and resolves to the collected
+// The one place that talks to the workflow runner. Sends the key when there is one (shared
+// resolveKey) and goes without when there is not, POSTs {slug, value, paramValues},
+// 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. ` +
-        "(The graph's direct read verbs run keyless; flows run keyed on the workflow runner.)"
-    );
-  }
+  // Flows proxy up like every other graph verb; the runner decides on the key.
+  const key = resolveKey(opts) || "";
   const body = flowWireBody(m, input);
   const url = flowRunUrl();
   const timeout = opts.timeout || 300000;
@@ -753,14 +805,17 @@ async function callFlow(m, input, opts = {}) {
   try {
     let res;
     try {
+      const headers = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+        "User-Agent": UA,
+      };
+      // Present => keyed. ABSENT => keyless: an empty credential is not the same as no
+      // credential, and a server handed "" refuses instead of applying keyless policy.
+      if (key) headers["X-API-Key"] = key;
       res = await fetch(url, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Accept: "text/event-stream",
-          "X-API-Key": key,
-          "User-Agent": UA,
-        },
+        headers,
         body: JSON.stringify(body),
         signal: ctrl.signal,
       });
@@ -868,7 +923,7 @@ function makeMapCall(m) {
     }
     const keys = Object.keys(bound).sort();
     const cypher = `CALL ${m.proc}({` + keys.map((k) => `${k}:$${k}`).join(", ") + "})";
-    return callGraph(cypher, bound, opts, m.name);
+    return callGraph(cypher, bound, opts);
   };
 }
 
@@ -886,9 +941,9 @@ for (const m of GRAPH_METHODS) {
   } 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, m.keyless);
+    graph[m.name] = async (value, opts = {}) => callGraph(m.cypher, { [m.input]: graphValue(m.name, value) }, opts);
   } else {
-    graph[m.name] = async (opts = {}) => callGraph(m.cypher, {}, opts, m.name, m.keyless);
+    graph[m.name] = async (opts = {}) => callGraph(m.cypher, {}, opts);
   }
   graph[m.name].docs = m.docs;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whisper-id",
-  "version": "0.6.1",
-  "description": "Give any Node agent the Whisper security graph (keyless reads + keyed Cypher), a real routable Whisper IPv6 identity, safe egress, and the full control plane.",
+  "version": "0.7.1",
+  "description": "Give any Node agent the Whisper security graph (keyless reads, no client-side gate), a real routable Whisper IPv6 identity, safe egress, and the full control plane.",
   "type": "module",
   "exports": {
     ".": {
@@ -14,6 +14,7 @@
     "index.js",
     "index.d.ts",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "engines": {