whisper-id 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viaGraph B.V. (Whisper Security)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# whisper-id
+
+A real, routable **IPv6 identity** and **safe egress** for any Node agent — in two calls.
+
+```sh
+npm i whisper-id
+```
+
+```js
+import { register, withEgress } from "whisper-id";
+
+const agent = await register("my-bot");          // a routable Whisper /128 identity
+await withEgress(async (e) => {
+  // proxy env (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY) now points at your local Whisper proxy
+  // → curl, axios, got, and other env-aware clients leave from your /128.
+  console.log("egress on", e.proxyUrl);
+});
+```
+
+## API
+
+| Call | Does |
+|------|------|
+| `register(name, { newKey })` | Create a named agent — 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. |
+| `verify(address)` | Keyless — is `address` a real Whisper agent? (DANE + DNSSEC + reverse-DNS + JWS) → `boolean` |
+| `ip()` | Your current egress IP, proving it's your `/128`. → `string` |
+
+### Using it with `fetch`
+
+Node's global `fetch` (undici) does **not** read proxy env vars, so pass a dispatcher:
+
+```js
+import { egress } from "whisper-id";
+import { ProxyAgent } from "undici";          // npm i undici
+
+const e = await egress();
+const res = await fetch("https://api64.ipify.org", { dispatcher: new ProxyAgent(e.proxyUrl) });
+console.log(await res.text());                 // ← your /128
+```
+
+`axios` / `got` can take `e.proxyUrl` directly; CLI tools and env-aware libraries work
+transparently inside `withEgress`.
+
+## Requirements
+
+The `whisper` CLI on your `PATH` (this package is a thin, dependency-free wrapper over it):
+
+```sh
+curl get.whisper.online | sh
+```
+
+For authenticated calls (`register`, `egress`, `ip`), set `WHISPER_API_KEY` or run
+`whisper login`. `verify` is keyless. (`$WHISPER_BIN` overrides the CLI path.)
+
+## Links
+
+- Site — https://whisper.online
+- CLI — https://github.com/whisper-sec/whisper-cli
+
+MIT licensed.

package/index.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 viaGraph B.V. (Whisper Security)
+export declare class WhisperError extends Error {}
+
+export interface Agent {
+  /** The routable IPv6 /128 — both the identity and the auth. */
+  address: string;
+  id: string | null;
+  name: string;
+}
+
+export interface Egress {
+  port: number;
+  address: string | null;
+  proxyUrl: string;
+  socksUrl: string;
+  proxies: { http: string; https: string };
+  /** Restore the proxy environment variables to their prior values. */
+  close(): void;
+}
+
+export interface RegisterOptions { newKey?: boolean; timeout?: number; }
+export interface EgressOptions { agent?: string; tier?: string; setEnv?: boolean; timeout?: number; }
+
+export function register(name: string, opts?: RegisterOptions): Promise<Agent>;
+export function egress(opts?: EgressOptions): Promise<Egress>;
+export function withEgress<T>(fn: (e: Egress) => Promise<T> | T): Promise<T>;
+export function withEgress<T>(opts: EgressOptions, fn: (e: Egress) => Promise<T> | T): Promise<T>;
+export function verify(address: string, opts?: { timeout?: number }): Promise<boolean>;
+export function ip(opts?: { timeout?: number }): Promise<string>;
+export function firstAddr(obj: unknown): string | null;

package/index.js

@@ -0,0 +1,141 @@
+// 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.
+// 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";
+import { promisify } from "node:util";
+
+const pexec = promisify(execFile);
+
+const ADDR_RE = /2a04:2a01:[0-9a-fA-F:]{2,}/; // the public Whisper agent prefix (AS219419)
+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"];
+
+/** Error thrown when a `whisper` invocation fails, or the CLI is not installed. */
+export class WhisperError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WhisperError";
+  }
+}
+
+function bin() {
+  return process.env.WHISPER_BIN || "whisper";
+}
+
+async function run(args, { timeout = 120000, check = true } = {}) {
+  try {
+    const { stdout, stderr } = await pexec(bin(), args, { timeout, encoding: "utf8" });
+    return { stdout: stdout || "", stderr: stderr || "", code: 0 };
+  } catch (err) {
+    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)."
+      );
+    }
+    const out = { stdout: err.stdout || "", stderr: err.stderr || "", code: typeof err.code === "number" ? err.code : 1 };
+    if (check) {
+      const detail = (out.stderr || out.stdout || err.message || `exit ${out.code}`).toString().trim();
+      throw new WhisperError(`\`whisper ${args.join(" ")}\` failed: ${detail.slice(0, 300)}`);
+    }
+    return out;
+  }
+}
+
+async function runJson(args, opts) {
+  const { stdout } = await run(["--json", ...args], opts);
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    throw new WhisperError(`could not parse JSON from \`whisper ${args.join(" ")}\`: ${stdout.trim().slice(0, 200)}`);
+  }
+}
+
+export function firstAddr(obj) {
+  const m = ADDR_RE.exec(JSON.stringify(obj));
+  return m ? m[0] : null;
+}
+
+function getKey(obj, ...keys) {
+  if (obj && typeof obj === "object") {
+    for (const k of keys) if (obj[k]) return obj[k];
+    for (const v of Object.values(obj)) {
+      if (v && typeof v === "object") {
+        const got = getKey(v, ...keys);
+        if (got) return got;
+      }
+    }
+  }
+  return null;
+}
+
+/** 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];
+  if (newKey) args.push("--register");
+  const env = await runJson(args, { timeout });
+  const address = firstAddr(env);
+  if (!address) throw new WhisperError(`no /128 returned by \`whisper create\`: ${JSON.stringify(env).slice(0, 200)}`);
+  return { address, id: getKey(env, "id", "agent_id", "agentId"), name };
+}
+
+function makeEgress(port, address) {
+  const proxyUrl = `http://127.0.0.1:${port}`;
+  const socksUrl = `socks5h://127.0.0.1:${port}`;
+  return { port, address: address || null, proxyUrl, socksUrl, proxies: { http: proxyUrl, https: proxyUrl }, close() {} };
+}
+
+/**
+ * Bring egress up bound to your /128 (idempotent detached proxy). By default sets the standard
+ * proxy env vars; call the returned `.close()` to restore them. Prefer `withEgress` for scoping.
+ */
+export async function egress({ agent, tier = "socks5", setEnv = true, timeout = 90000 } = {}) {
+  const args = ["connect", "--ensure", "--tier", tier];
+  if (agent) args.push("--agent", agent);
+  const { stdout, stderr } = await run(args, { timeout });
+  const m = HOSTPORT_RE.exec(`${stdout}\n${stderr}`);
+  if (!m) throw new WhisperError(`could not determine the local proxy port from \`whisper connect\`: ${`${stdout}${stderr}`.trim().slice(0, 200)}`);
+  const e = makeEgress(Number(m[1]), agent);
+  const saved = {};
+  if (setEnv) {
+    for (const k of PROXY_VARS) saved[k] = process.env[k];
+    process.env.HTTP_PROXY = process.env.http_proxy = e.proxyUrl;
+    process.env.HTTPS_PROXY = process.env.https_proxy = e.proxyUrl;
+    process.env.ALL_PROXY = process.env.all_proxy = e.socksUrl;
+  }
+  e.close = () => {
+    for (const k of PROXY_VARS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  };
+  return e;
+}
+
+/** Run `fn(egress)` with egress up, restoring the environment afterwards. */
+export async function withEgress(optsOrFn, maybeFn) {
+  const fn = typeof optsOrFn === "function" ? optsOrFn : maybeFn;
+  const opts = typeof optsOrFn === "function" ? {} : optsOrFn || {};
+  const e = await egress(opts);
+  try {
+    return await fn(e);
+  } finally {
+    e.close();
+  }
+}
+
+/** Return true iff `address` is a real Whisper agent (DANE+DNSSEC+reverse-DNS+JWS). Keyless. */
+export async function verify(address, { timeout = 60000 } = {}) {
+  if (!address || !address.trim()) throw new WhisperError("verify() needs an address");
+  const { code } = await run(["verify", address], { timeout, check: false });
+  return code === 0;
+}
+
+/** Return the current egress IP, proving it is your Whisper /128. */
+export async function ip({ timeout = 60000 } = {}) {
+  const env = await runJson(["ip"], { timeout });
+  return getKey(env, "ip", "agent") || firstAddr(env) || "";
+}

package/package.json

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