@huynle/hub 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.9.2
+
+Webhooks can reach a named receiver on your own network without opening the hub to every private address. No
+migration is needed.
+
+### For operators
+- **`agents.webhooks.allowPrivateHosts`** in `hub.json`: a list of exact hostnames whose `https://` webhook URLs may
+  resolve to private addresses (a LAN-hosted app behind split DNS, such as a Brain on the same cluster). Everything
+  else keeps the public-host rule: no `http://`, no IPs, no other hosts or subdomains, and the check still runs before
+  every send, and webhooks to a listed host must use port 443. Use it instead of `allowPrivate`, which opens private
+  targets for every webhook on the hub. In Kubernetes, also allow egress to the receiver's private address.
+  [docs/launches.md → Where webhooks may go](docs/launches.md#where-webhooks-may-go)
+
 ## 0.9.1
 
 **+ launch node on Windows.** `hubctl` installs `hub node` as a per-user logon task (Task Scheduler: no admin, no

package/README.md

@@ -1995,6 +1995,7 @@ in the file).
 | `agents.never` | permission patterns (`action[:glob]`) no agent may ever approve, for every user, checked before any grant; see [Agent actions and grants](#agent-actions-and-grants) |
 | `agents.launches` | per-user launch caps `{maxQueued?, maxActive?, perHour?}` (defaults 50, 4, 60) and `lostAfterMinutes?` (0–1440 or false, default 5: a running launch the same node instance stops reporting, with its session gone, ends lost; 0/false: never); see [docs/launches.md](docs/launches.md#placement-and-caps) |
 | `agents.webhooks.allowPrivate` | `true` lets webhooks target `http://`, loopback and private hosts (self-hosted receivers); see [docs/launches.md](docs/launches.md#where-webhooks-may-go) |
+| `agents.webhooks.allowPrivateHosts` | exact hostnames (at most 50) whose `https://` webhook URLs may resolve to private addresses, e.g. a LAN-hosted app behind split DNS; nothing else is opened; see [docs/launches.md](docs/launches.md#where-webhooks-may-go) |
 
 Server fields: env vars (`HUB_HOST`, `HUB_PORT`, `HUB_PUBLIC_URL`, `HUB_STATE_DIR`) > hub.json >
 defaults. Speech: phone settings > hub.json > env vars. Values are checked like the phone's speech

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Hub: a harness-agnostic central hub your AI agent harnesses connect to (OpenCode first). Follow, steer and stop sessions from your phone or browser, with notifications, optional hands-free Voice and a self-hostable server.",
   "license": "MIT",
   "author": "Huy Le",

package/packages/claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-claude-code",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/dist/hub-cli.js

@@ -7,7 +7,7 @@ import { createInterface } from "readline";
 // packages/cli/package.json
 var package_default = {
   name: "@huynle/hub-cli",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   license: "MIT",
@@ -9227,7 +9227,7 @@ import { arch as osArch, platform as osPlatform } from "node:os";
 // packages/node/package.json
 var package_default2 = {
   name: "@huynle/hub-node",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -10682,7 +10682,7 @@ import path14 from "node:path";
 // packages/runtime-openshell/package.json
 var package_default3 = {
   name: "@huynle/hub-runtime-openshell",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -14640,7 +14640,7 @@ import path23 from "node:path";
 // packages/claude-code/package.json
 var package_default4 = {
   name: "@huynle/hub-claude-code",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -14929,7 +14929,7 @@ import path26 from "node:path";
 // packages/preset/package.json
 var package_default5 = {
   name: "@huynle/hub-preset",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -15454,7 +15454,7 @@ import { openSync as openSync6, closeSync as closeSync6, readFileSync as readFil
 // packages/codex/package.json
 var package_default6 = {
   name: "@huynle/hub-codex",
-  version: "0.9.1",
+  version: "0.9.2",
   private: true,
   description: "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/agent/webhooks.ts

@@ -157,6 +157,8 @@ export interface WebhooksDeps {
   readonly resolve: ResolveHost
   /** hub.json agents.webhooks.allowPrivate. */
   readonly allowPrivate?: boolean
+  /** hub.json agents.webhooks.allowPrivateHosts: exact hostnames that may resolve to private addresses (https only). */
+  readonly privateHosts?: readonly string[]
   readonly fetch?: typeof globalThis.fetch
   /** Whether an app token (by its id) may still have webhooks; its registrations are dropped when not. */
   readonly appAlive?: (userID: string, tokenID: string) => boolean
@@ -283,8 +285,8 @@ export class Webhooks {
     const { url } = input
     if (typeof url !== "string" || url.length === 0) throw invalid("url must be a string")
     if (url.length > MAX_WEBHOOK_URL) throw invalid(`url must be at most ${MAX_WEBHOOK_URL} characters`)
-    const problem = await publicURLProblem(url, { resolve: this.deps.resolve, label: "Webhook URL", allowPrivate: this.deps.allowPrivate === true })
-    if (problem) throw invalid(problem, this.deps.allowPrivate ? undefined : "Webhooks need an https URL on a public host")
+    const problem = await publicURLProblem(url, { resolve: this.deps.resolve, label: "Webhook URL", allowPrivate: this.deps.allowPrivate === true, ...(this.deps.privateHosts?.length ? { privateHosts: this.deps.privateHosts } : {}) })
+    if (problem) throw invalid(problem, this.deps.allowPrivate ? undefined : "Webhooks need an https URL on a public host (or one listed in hub.json agents.webhooks.allowPrivateHosts)")
     const events = eventsOf(input.events)
     let label: string | undefined
     if (input.label !== undefined && input.label !== null) {
@@ -512,6 +514,7 @@ export class Webhooks {
           resolve: this.deps.resolve,
           label: "Webhook URL",
           allowPrivate: this.deps.allowPrivate === true,
+          ...(this.deps.privateHosts?.length ? { privateHosts: this.deps.privateHosts } : {}),
           timeoutMs,
           maxBytes: this.deps.maxResponseBytes ?? WEBHOOK_RESPONSE_MAX,
           ...(this.deps.fetch ? { fetch: this.deps.fetch } : {}),

package/src/central/config.ts

@@ -71,6 +71,8 @@ export interface CentralConfig {
   readonly launchCaps?: HubLaunches
   /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
   readonly webhooksAllowPrivate?: true
+  /** hub.json `agents.webhooks.allowPrivateHosts`: exact hostnames whose https webhook URLs may resolve privately. */
+  readonly webhooksPrivateHosts?: readonly string[]
   /**
    * HUB_RELEASE_BASE: where /install.sh and /install.ps1 tell machines to download hubctl (default: this version's
    * hub-releases GitHub release). https, or plain http on loopback or a private-network IP address.
@@ -132,6 +134,8 @@ export interface HubAgents {
 export interface HubWebhooks {
   /** Lets webhook URLs use http and private or local targets (self-hosted receivers); off by default (SSRF). */
   readonly allowPrivate?: boolean
+  /** Exact hostnames whose https webhook URLs may resolve to private addresses (a LAN-hosted receiver), nothing else. */
+  readonly allowPrivateHosts?: readonly string[]
 }
 
 /** hub.json, validated. */
@@ -151,7 +155,9 @@ type Env = Readonly<Record<string, string | undefined>>
 const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster"])
 const CLUSTER_KEYS = ["database", "valkey"] as const
 const AGENTS_KEYS = new Set(["never", "launches", "webhooks"])
-const WEBHOOK_KEYS = new Set(["allowPrivate"])
+const WEBHOOK_KEYS = new Set(["allowPrivate", "allowPrivateHosts"])
+const PRIVATE_HOSTS_MAX = 50
+const HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/
 const LAUNCH_CAP_KEYS = ["maxQueued", "maxActive", "perHour", "lostAfterMinutes"] as const
 /** The longest lostAfterMinutes (a day): far below setTimeout's 32-bit limit. */
 const LOST_AFTER_MAX = 1440
@@ -337,7 +343,22 @@ function readHubWebhooks(raw: unknown, file: string, warnings: string[], fail: (
   const input = raw as Record<string, unknown>
   for (const key of Object.keys(input)) if (!WEBHOOK_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.webhooks.${key}" ignored`)
   if (input.allowPrivate !== undefined && typeof input.allowPrivate !== "boolean") fail("agents.webhooks.allowPrivate must be true or false")
-  return input.allowPrivate === undefined ? {} : { allowPrivate: input.allowPrivate as boolean }
+  const hosts = input.allowPrivateHosts === undefined ? undefined : readPrivateHosts(input.allowPrivateHosts, fail)
+  return { ...(input.allowPrivate === undefined ? {} : { allowPrivate: input.allowPrivate as boolean }), ...(hosts ? { allowPrivateHosts: hosts } : {}) }
+}
+
+/** Plain DNS hostnames with a dot (no IPs, wildcards, schemes, ports or paths), lowercase, trailing dot dropped, deduplicated. */
+function readPrivateHosts(raw: unknown, fail: (message: string) => never): string[] {
+  if (!Array.isArray(raw)) fail("agents.webhooks.allowPrivateHosts must be a list of hostnames")
+  const list = raw as unknown[]
+  if (list.length > PRIVATE_HOSTS_MAX) fail(`agents.webhooks.allowPrivateHosts holds at most ${PRIVATE_HOSTS_MAX} hostnames`)
+  const out: string[] = []
+  for (const item of list) {
+    const host = typeof item === "string" ? item.trim().toLowerCase().replace(/\.$/, "") : ""
+    if (!HOSTNAME.test(host) || /^[0-9.]+$/.test(host)) fail(`agents.webhooks.allowPrivateHosts: ${JSON.stringify(item)} is not a hostname (no IPs, wildcards, schemes, ports or paths)`)
+    if (!out.includes(host)) out.push(host)
+  }
+  return out
 }
 
 function readHubLaunches(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubLaunches {
@@ -536,6 +557,7 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     agentsNever: [...(file.agents?.never ?? [])],
     ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
+    ...(file.agents?.webhooks?.allowPrivateHosts?.length ? { webhooksPrivateHosts: [...file.agents.webhooks.allowPrivateHosts] } : {}),
     ...(releaseBase ? { releaseBase } : {}),
     ...(cluster ? { cluster } : {}),
     ...(remoteFetch === "off" ? { remoteFetch: false } : {}),

package/src/central/http.ts

@@ -1061,6 +1061,7 @@ export function startCentral(options: CentralOptions): Central {
     users: () => store.users().map((u) => u.id),
     resolve: options.resolveHost ?? systemResolveHost,
     ...(config.webhooksAllowPrivate ? { allowPrivate: true } : {}),
+    ...(config.webhooksPrivateHosts?.length ? { privateHosts: config.webhooksPrivateHosts } : {}),
     appAlive: (userID, tokenID) => store.agentData(userID).appTokens?.some((t) => t.id === tokenID && Array.isArray(t.scopes) && WEBHOOK_APP_SCOPES.some((scope) => t.scopes!.includes(scope))) === true,
     appScopes: (userID, tokenID) => store.agentData(userID).appTokens?.find((t) => t.id === tokenID)?.scopes,
     userAgent: `hub/${options.version ?? "0.0.0"}`,

package/src/central/push-target.ts

@@ -82,6 +82,12 @@ export interface PublicURLOptions {
    * addresses and local names pass without a lookup. Other schemes and credentials still fail.
    */
   readonly allowPrivate?: boolean
+  /**
+   * The narrow admin opt-in (hub.json agents.webhooks.allowPrivateHosts): these exact hostnames, normalised (lowercase,
+   * no trailing dot), may resolve to private addresses, on port 443 only. Still https only, no credentials, and the
+   * name must resolve; a listed name also skips the local-suffix rule (.local, .lan, …).
+   */
+  readonly privateHosts?: readonly string[]
 }
 
 /** Why the hub must not send to a URL (SSRF), or undefined when it may. */
@@ -100,7 +106,10 @@ export async function publicURLProblem(raw: string, options: PublicURLOptions):
   if (options.allowPrivate) return undefined
   const host = url.hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.$/, "")
   if (isIPv4(host) || isIPv6(host)) return isPrivateAddress(host) ? `${label} is a private or local address` : undefined
-  if (host === "localhost" || !host.includes(".") || LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix))) {
+  const listed = options.privateHosts?.some((h) => h.toLowerCase().replace(/\.$/, "") === host) === true
+  // A listed host is reachable on the https port only, so the exception never opens other services on that address.
+  if (listed && url.port !== "" && url.port !== "443") return `${label} must use port 443 for a host in allowPrivateHosts`
+  if (!listed && (host === "localhost" || !host.includes(".") || LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix)))) {
     return `${label} is a local hostname`
   }
   let addresses: readonly string[]
@@ -110,7 +119,7 @@ export async function publicURLProblem(raw: string, options: PublicURLOptions):
     return `${label} host ${host} does not resolve`
   }
   if (addresses.length === 0) return `${label} host ${host} does not resolve`
-  if (addresses.some(isPrivateAddress)) return `${label} resolves to a private or local address`
+  if (!listed && addresses.some(isPrivateAddress)) return `${label} resolves to a private or local address`
   return undefined
 }