whisper-id 0.7.0 → 0.7.2

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** (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**.
+Three things for any Node agent, in one dependency-free package: query the **Whisper security graph** (billions of nodes and tens of billions of edges joining the physical, network, naming, ownership and threat layers, queried with Cypher; live totals at nic.whisper.online/stats), give the agent a routable **IPv6 identity** with safe **egress**, and drive the full **control plane**.
 
 ```sh
 npm i whisper-id
@@ -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 |
 |------|------|

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}`. */

package/index.js

@@ -16,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);
@@ -24,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";
 }
@@ -309,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);
@@ -350,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;
@@ -403,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 };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whisper-id",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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": {