whisper-id 0.6.0 → 0.7.0

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
@@ -165,14 +165,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

@@ -157,7 +157,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 +181,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 +237,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 +271,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 +284,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 +297,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 +310,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 +323,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 +336,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 +349,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 +363,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 +376,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 +389,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 +402,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 +415,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 +428,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 +442,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 +455,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 +468,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 +482,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 +496,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 +511,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 +526,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 +540,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 +554,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 +568,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 +582,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 +596,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 +611,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 +625,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 +639,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 +650,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";
 
@@ -35,7 +36,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 };
@@ -203,7 +204,7 @@ export async function ip({ timeout = 60000 } = {}) {
 // read from opts.apiKey or $WHISPER_API_KEY and sent ONLY in the X-API-Key header.
 
 function controlUrl() {
-  return process.env.WHISPER_CONTROL_URL || "https://graph.whisper.security/api/query";
+  return process.env.WHISPER_CONTROL_URL || "https://graph.whisper.online/api/query";
 }
 
 // Conservative-emit (RFC 761): render a value as a Cypher literal so no input - however
@@ -463,8 +464,8 @@ 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
-// control plane uses (https://graph.whisper.security/api/query), reusing resolveKey() so
+// 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()
 // control wrapper: the graph contract is different (body {query,parameters}; reply
@@ -508,17 +509,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 +615,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 +646,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 +728,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 +745,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 +863,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 +881,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.0",
-  "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.0",
+  "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": {