@huynle/hub 0.0.0-stage → 0.6.0

package/src/central/main.ts

@@ -0,0 +1,136 @@
+// The hub process: command line, config, startup log and shutdown. Shared by bin/hub.ts (web/ from
+// disk) and the compiled binaries (web/ embedded, see scripts/gen-web-entry.ts).
+import type { WebAssets } from "./assets"
+import { PAIR_TTL_MS } from "./auth"
+import { isLoopbackURL } from "../loopback"
+import { loadCentralConfig, type CentralConfig } from "./config"
+import { startCentral } from "./http"
+
+export type HubArgs = { readonly action: "run" | "version" | "help" } | { readonly action: "error"; readonly message: string }
+
+export function parseHubArgs(argv: readonly string[]): HubArgs {
+  if (argv.length === 0) return { action: "run" }
+  const [first] = argv
+  if (argv.length === 1 && (first === "--version" || first === "-v")) return { action: "version" }
+  if (argv.length === 1 && (first === "--help" || first === "-h")) return { action: "help" }
+  return { action: "error", message: `Unknown argument: ${argv.join(" ")}. The hub is configured with env vars and hub.json; see --help.` }
+}
+
+export function hubHelp(version: string): string {
+  return `hub-server ${version}
+
+Hub: the central hub your AI agent harnesses connect to (OpenCode first). Serves the web console,
+pairs phones and browsers, enrolls machines, and does push notifications and (optional) Voice speech.
+
+Usage: hub-server [--help | --version]   (also installed as opencode-hub and opencode-voice-hub)
+
+Configuration: environment variables over ~/.config/hub/hub.json ($HUB_CONFIG).
+  HUB_HOST / HUB_PORT       listen address (default 127.0.0.1 / 4097)
+  HUB_PUBLIC_URL            origin used in links and cookies (default http://<host>:<port>)
+  HUB_STATE_DIR             machines, devices, keys (default ~/.local/state/hub)
+  OPENROUTER_API_KEY        default speech key; or set speech providers in the web app (Settings → Speech)
+  HUB_CONFIG                path of hub.json
+
+Multi-user (sign in with Google or another OpenID Connect provider):
+  HUB_AUTH=oidc             default "pairing" (one owner)
+  HUB_OIDC_ISSUER           default https://accounts.google.com
+  HUB_OIDC_CLIENT_ID        OAuth client ID (required)
+  HUB_OIDC_CLIENT_SECRET    OAuth client secret (required; never logged)
+  HUB_OIDC_ALLOWED          who may sign in: emails and/or @domain entries, comma separated (required)
+  HUB_ADMIN_EMAILS          admin emails, comma separated (at least one)
+  Register <public URL>/auth/callback as the redirect URI.
+
+The former VOICE_* names (opencode-voice) still work, with a deprecation warning; so do the
+opencode-hub and opencode-voice config and state directories (copied once on first start).
+While no device is paired, the log shows a pairing code for the first one (open <public URL>/pair).
+Docs: https://github.com/huynle/hub#running-the-hub
+`
+}
+
+/** Startup log lines about sign-in (never the client secret). Pairing mode has none. */
+export function authStartupLines(config: CentralConfig): { info: string[]; warnings: string[] } {
+  const auth = config.auth
+  if (auth.mode !== "oidc") return { info: [], warnings: [] }
+  const entries = auth.allowed.length
+  const admins = auth.admins.length
+  const info = [
+    `multi-user: sign-in with ${auth.issuer} (client ${auth.clientId}); redirect URI ${config.publicURL}/auth/callback`,
+    `multi-user: ${entries} allow-list ${entries === 1 ? "entry" : "entries"}, ${admins} admin${admins === 1 ? "" : "s"}`,
+  ]
+  const warnings: string[] = []
+  if (!config.publicURL.startsWith("https://") && !isLoopbackURL(config.publicURL)) {
+    warnings.push(`HUB_PUBLIC_URL ${config.publicURL} is not https: sign-in cookies travel unencrypted and most providers refuse the redirect URI`)
+  }
+  if (auth.insecureIssuer) warnings.push(`HUB_OIDC_INSECURE_ISSUER is set: plain-http issuer ${auth.issuer} allowed (development only)`)
+  return { info, warnings }
+}
+
+export interface RunHubOptions {
+  readonly web: WebAssets
+  readonly version: string
+  readonly argv?: readonly string[]
+}
+
+/** Runs the hub until SIGINT/SIGTERM (or answers --help / --version). */
+export function runHub(options: RunHubOptions): void {
+  const args = parseHubArgs(options.argv ?? process.argv.slice(2))
+  if (args.action === "version") {
+    console.log(options.version)
+    return
+  }
+  if (args.action === "help") {
+    console.log(hubHelp(options.version))
+    return
+  }
+  if (args.action === "error") {
+    console.error(`[hub] ${args.message}`)
+    process.exit(2)
+  }
+
+  let loaded: ReturnType<typeof loadCentralConfig>
+  try {
+    loaded = loadCentralConfig()
+  } catch (cause) {
+    console.error(`[hub] ${cause instanceof Error ? cause.message : cause}`)
+    process.exit(1)
+  }
+  for (const warning of loaded.warnings) console.warn(`[hub] warning: ${warning}`)
+  const config = loaded.config
+  const central = startCentral({ config, web: options.web, version: options.version })
+
+  console.log(`[hub] Hub ${options.version} listening on ${central.url} (public URL ${central.publicURL})`)
+  console.log(`[hub] state: ${config.stateDir}`)
+  console.log(`[hub] config: ${loaded.loaded ? loaded.path : `${loaded.path} (not found; using env and defaults)`}`)
+  const authLines = authStartupLines(config)
+  for (const line of authLines.info) console.log(`[hub] ${line}`)
+  for (const line of authLines.warnings) console.warn(`[hub] warning: ${line}`)
+  const speech = central.speechSettings.view()
+  if (speech.ready.reason) {
+    console.log(`[hub] speech is not set up yet: ${speech.ready.reason} (or OPENROUTER_API_KEY, or speech.stt/tts in hub.json)`)
+  }
+
+  // While no device is paired, keep a fresh bootstrap pairing code in the log.
+  const bootstrap = () => {
+    const code = central.auth.bootstrapCode()
+    if (code) console.log(`[hub] Pair your first device at ${central.publicURL}/pair with code ${code.code}`)
+    return code !== undefined
+  }
+  let timer: ReturnType<typeof setInterval> | undefined
+  if (bootstrap()) {
+    timer = setInterval(() => {
+      if (!bootstrap()) clearInterval(timer)
+    }, PAIR_TTL_MS - 5_000)
+  }
+
+  let stopping = false
+  const shutdown = async (signal: string) => {
+    if (stopping) return
+    stopping = true
+    console.log(`[hub] ${signal}: shutting down`)
+    clearInterval(timer)
+    await central.stop()
+    process.exit(0)
+  }
+  process.on("SIGTERM", () => void shutdown("SIGTERM"))
+  process.on("SIGINT", () => void shutdown("SIGINT"))
+}

package/src/central/oidc.ts

@@ -0,0 +1,295 @@
+// OpenID Connect sign-in (authorization code flow with PKCE S256, state and nonce) for multi-user hubs.
+// The ID token comes straight from the token endpoint over TLS (confidential client, client_secret_post),
+// so its signature is not checked (OIDC Core 3.1.3.7, item 6); its claims are. Pending sign-ins live in
+// memory only (a restart invalidates them) and are single use.
+import { createHash, randomBytes } from "node:crypto"
+import type { OidcConfig } from "./config"
+
+export const OIDC_COOKIE = "voice_oidc"
+export const OIDC_PENDING_TTL_MS = 10 * 60_000
+/** Discovery documents are re-fetched after this long. */
+export const DISCOVERY_CACHE_MS = 60 * 60_000
+/** Clock skew tolerated on `exp`. */
+const SKEW_SECONDS = 60
+/** Most pending sign-ins kept (the oldest are dropped): /auth/login is public. */
+const MAX_PENDING = 1000
+const FETCH_TIMEOUT_MS = 10_000
+const MAX_NEXT_CHARS = 1024
+
+/** A failed sign-in step; `message` is safe to show, `reason` goes to the audit log. */
+export class OidcError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly reason: string,
+    /** The state was valid: the attempt is worth an audit entry. */
+    readonly audited = false,
+  ) {
+    super(message)
+    this.name = "OidcError"
+  }
+}
+
+export interface OidcIdentity {
+  readonly sub: string
+  /** Lowercased, verified. */
+  readonly email: string
+  readonly name?: string
+}
+
+interface Discovery {
+  readonly issuer: string
+  readonly authorization_endpoint: string
+  readonly token_endpoint: string
+}
+
+interface Pending {
+  readonly nonce: string
+  readonly verifier: string
+  readonly next: string
+  readonly expiresAt: number
+}
+
+export interface OidcClientOptions {
+  readonly config: OidcConfig
+  /** Hub origin: the redirect URI is <publicURL>/auth/callback. */
+  readonly publicURL: string
+  readonly fetch?: typeof globalThis.fetch
+  readonly now?: () => number
+}
+
+const random = () => randomBytes(32).toString("base64url")
+
+/** A same-origin path (with query and fragment) to land on after sign-in; anything else becomes "/". */
+export function safeNext(raw: string | null | undefined): string {
+  if (!raw || raw.length > MAX_NEXT_CHARS) return "/"
+  if (!raw.startsWith("/") || raw.startsWith("//") || /[\\\x00-\x20\x7f]/.test(raw)) return "/"
+  const base = "http://hub.invalid"
+  try {
+    const url = new URL(raw, base)
+    if (url.origin !== base) return "/"
+    const path = `${url.pathname}${url.search}${url.hash}`
+    return path.startsWith("//") ? "/" : path
+  } catch {
+    return "/"
+  }
+}
+
+/** A short device name from a user agent, e.g. "Safari on iPhone". */
+export function deviceName(userAgent: string | null | undefined): string {
+  const ua = userAgent ?? ""
+  if (!ua) return "Browser"
+  const os = /iPhone/.test(ua)
+    ? "iPhone"
+    : /iPad/.test(ua)
+      ? "iPad"
+      : /Android/.test(ua)
+        ? "Android"
+        : /Macintosh|Mac OS X/.test(ua)
+          ? "Mac"
+          : /Windows/.test(ua)
+            ? "Windows"
+            : /Linux|X11/.test(ua)
+              ? "Linux"
+              : undefined
+  const browser = /Edg\//.test(ua)
+    ? "Edge"
+    : /Firefox\/|FxiOS/.test(ua)
+      ? "Firefox"
+      : /Chrome\/|CriOS/.test(ua)
+        ? "Chrome"
+        : /Safari\//.test(ua)
+          ? "Safari"
+          : "Browser"
+  return os ? `${browser} on ${os}` : browser
+}
+
+/** The value of one cookie in a Cookie header. */
+export function cookieValue(header: string | null, name: string): string | undefined {
+  for (const part of (header ?? "").split(";")) {
+    const [key, ...rest] = part.trim().split("=")
+    if (key === name) return rest.join("=")
+  }
+  return undefined
+}
+
+function decodePayload(idToken: unknown): Record<string, unknown> {
+  const parts = typeof idToken === "string" ? idToken.split(".") : []
+  if (parts.length !== 3 || !parts[1]) throw new OidcError(401, "The sign-in provider sent an invalid ID token.", "id_token malformed", true)
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as unknown
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new Error("not an object")
+    return payload as Record<string, unknown>
+  } catch {
+    throw new OidcError(401, "The sign-in provider sent an invalid ID token.", "id_token malformed", true)
+  }
+}
+
+export class OidcClient {
+  private readonly config: OidcConfig
+  private readonly fetch: typeof globalThis.fetch
+  private readonly now: () => number
+  private readonly pending = new Map<string, Pending>()
+  private discovery?: { at: number; doc: Discovery }
+  readonly redirectURI: string
+
+  constructor(options: OidcClientOptions) {
+    this.config = options.config
+    this.fetch = options.fetch ?? globalThis.fetch
+    this.now = options.now ?? Date.now
+    this.redirectURI = `${options.publicURL}/auth/callback`
+  }
+
+  /** Starts a sign-in: the provider URL to redirect to and the state for the voice_oidc cookie. */
+  async login(next: string | null): Promise<{ location: string; state: string }> {
+    const doc = await this.discover()
+    this.sweep()
+    const state = random()
+    const nonce = random()
+    const verifier = random()
+    while (this.pending.size >= MAX_PENDING) this.pending.delete(this.pending.keys().next().value!)
+    this.pending.set(state, { nonce, verifier, next: safeNext(next), expiresAt: this.now() + OIDC_PENDING_TTL_MS })
+    const url = new URL(doc.authorization_endpoint)
+    url.searchParams.set("response_type", "code")
+    url.searchParams.set("client_id", this.config.clientId)
+    url.searchParams.set("redirect_uri", this.redirectURI)
+    url.searchParams.set("scope", "openid email profile")
+    url.searchParams.set("state", state)
+    url.searchParams.set("nonce", nonce)
+    url.searchParams.set("code_challenge", createHash("sha256").update(verifier).digest("base64url"))
+    url.searchParams.set("code_challenge_method", "S256")
+    return { location: url.toString(), state }
+  }
+
+  /**
+   * Finishes a sign-in from the callback's query and the voice_oidc cookie. Throws OidcError. The
+   * pending entry is consumed whatever the outcome once the state matches the cookie.
+   */
+  async callback(params: URLSearchParams, cookieState: string | undefined): Promise<{ identity: OidcIdentity; next: string }> {
+    this.sweep()
+    const state = params.get("state") ?? ""
+    const pending = state && cookieState === state ? this.pending.get(state) : undefined
+    if (!pending) {
+      throw new OidcError(400, "This sign-in has expired or was already used. Please sign in again.", "state invalid")
+    }
+    this.pending.delete(state)
+    const providerError = params.get("error")
+    if (providerError) {
+      const description = params.get("error_description")
+      throw new OidcError(400, `The sign-in provider reported: ${providerError}${description ? ` (${description})` : ""}`, `provider error ${providerError.slice(0, 64)}`, true)
+    }
+    const code = params.get("code")
+    if (!code) throw new OidcError(400, "The sign-in provider sent no authorization code.", "no code", true)
+
+    const doc = await this.discover()
+    let tokens: Record<string, unknown>
+    try {
+      const response = await this.fetch(doc.token_endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: this.redirectURI,
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret,
+          code_verifier: pending.verifier,
+        }),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      })
+      if (!response.ok) throw new Error(`token endpoint answered ${response.status}`)
+      tokens = (await response.json()) as Record<string, unknown>
+    } catch (cause) {
+      throw new OidcError(502, "Could not complete sign-in with the provider. Please try again.", `token exchange failed: ${cause instanceof Error ? cause.message : cause}`, true)
+    }
+    const identity = this.validate(decodePayload(tokens?.id_token), doc, pending.nonce)
+    return { identity, next: pending.next }
+  }
+
+  private validate(claims: Record<string, unknown>, doc: Discovery, nonce: string): OidcIdentity {
+    const reject = (reason: string, status = 401, message = "The sign-in could not be verified. Please sign in again."): never => {
+      throw new OidcError(status, message, reason, true)
+    }
+    const issuers = new Set([doc.issuer])
+    // Google documents both forms for `iss`.
+    if (doc.issuer === "https://accounts.google.com") issuers.add("accounts.google.com")
+    if (typeof claims.iss !== "string" || !issuers.has(claims.iss)) reject("iss mismatch")
+    const aud = claims.aud
+    const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : []
+    if (!audiences.includes(this.config.clientId)) reject("aud mismatch")
+    if ((audiences.length > 1 || claims.azp !== undefined) && claims.azp !== this.config.clientId) reject("azp mismatch")
+    if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp) || claims.exp + SKEW_SECONDS <= this.now() / 1000) reject("token expired")
+    if (typeof claims.nonce !== "string" || claims.nonce !== nonce) reject("nonce mismatch")
+    if (typeof claims.sub !== "string" || !claims.sub) reject("no sub")
+    const email = typeof claims.email === "string" ? claims.email.trim().toLowerCase() : ""
+    if (!email) reject("no email", 403, "Your account did not share an email address.")
+    if (claims.email_verified !== true && claims.email_verified !== "true") reject("email not verified", 403, "Your email address is not verified with the sign-in provider.")
+    const name = typeof claims.name === "string" && claims.name.trim() ? claims.name.trim().slice(0, 100) : undefined
+    return { sub: claims.sub as string, email, ...(name ? { name } : {}) }
+  }
+
+  private async discover(): Promise<Discovery> {
+    if (this.discovery && this.now() - this.discovery.at < DISCOVERY_CACHE_MS) return this.discovery.doc
+    const issuer = this.config.issuer
+    let raw: Record<string, unknown>
+    try {
+      const response = await this.fetch(`${issuer}/.well-known/openid-configuration`, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      })
+      if (!response.ok) throw new Error(`answered ${response.status}`)
+      raw = (await response.json()) as Record<string, unknown>
+    } catch (cause) {
+      throw new OidcError(502, "The sign-in provider is not reachable right now. Please try again later.", `discovery failed: ${cause instanceof Error ? cause.message : cause}`)
+    }
+    const fail = (what: string): never => {
+      throw new OidcError(502, "The sign-in provider is misconfigured.", `discovery: ${what}`)
+    }
+    if (typeof raw.issuer !== "string" || raw.issuer.replace(/\/+$/, "") !== issuer) fail("issuer mismatch")
+    for (const key of ["authorization_endpoint", "token_endpoint"] as const) {
+      if (!this.endpointOK(raw[key])) fail(`${key} invalid`)
+    }
+    const doc: Discovery = {
+      issuer: raw.issuer as string,
+      authorization_endpoint: raw.authorization_endpoint as string,
+      token_endpoint: raw.token_endpoint as string,
+    }
+    this.discovery = { at: this.now(), doc }
+    return doc
+  }
+
+  /** https, or http on the (dev-only) insecure loopback issuer's host. */
+  private endpointOK(value: unknown): boolean {
+    if (typeof value !== "string") return false
+    try {
+      const url = new URL(value)
+      if (url.protocol === "https:") return true
+      return url.protocol === "http:" && this.config.insecureIssuer === true && url.origin === new URL(this.config.issuer).origin
+    } catch {
+      return false
+    }
+  }
+
+  private sweep(): void {
+    const t = this.now()
+    for (const [state, entry] of this.pending) if (entry.expiresAt <= t) this.pending.delete(state)
+  }
+}
+
+const ESCAPES: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }
+export const escapeHTML = (text: string) => text.replace(/[&<>"']/g, (c) => ESCAPES[c]!)
+
+/** A small standalone HTML page for sign-in results (no scripts, nothing external). */
+export function authPage(status: number, title: string, message: string, headers: HeadersInit = {}): Response {
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHTML(title)} · Hub</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1rem;color:#222}a{color:#0a58ca}</style>
+</head><body><h1>${escapeHTML(title)}</h1><p>${escapeHTML(message)}</p><p><a href="/">Back to Hub</a></p></body></html>
+`
+  const h = new Headers(headers)
+  h.set("content-type", "text/html; charset=utf-8")
+  h.set("cache-control", "no-store")
+  h.set("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'")
+  return new Response(html, { status, headers: h })
+}

package/src/central/push-target.ts

@@ -0,0 +1,97 @@
+// Push endpoints come from browsers, and the hub POSTs to them: without checks a subscription could make the
+// hub send requests into its own network (SSRF). An endpoint must be https on a public hostname; hosts are
+// resolved at subscribe time and rejected when any address is loopback, private, link-local, CGNAT, ULA,
+// unspecified or multicast. Real push services (FCM, Mozilla, Apple, WNS) are public names on public addresses.
+import { lookup } from "node:dns/promises"
+import { isIPv4, isIPv6 } from "node:net"
+
+export type ResolveHost = (host: string) => Promise<readonly string[]>
+
+/** Every address the system resolver returns for a host. */
+export const resolveHost: ResolveHost = async (host) => (await lookup(host, { all: true, verbatim: true })).map((a) => a.address)
+
+/** IPv4 [network, prefix length] blocks that never reach a public push service. */
+const V4_BLOCKED: ReadonlyArray<readonly [string, number]> = [
+  ["0.0.0.0", 8], // "this network", unspecified
+  ["10.0.0.0", 8], // private
+  ["100.64.0.0", 10], // CGNAT
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local (cloud metadata)
+  ["172.16.0.0", 12], // private
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.168.0.0", 16], // private
+  ["198.18.0.0", 15], // benchmarking
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved, broadcast
+]
+
+const v4Number = (ip: string): number => ip.split(".").reduce((n, part) => n * 256 + Number(part), 0)
+
+function privateV4(ip: string): boolean {
+  const n = v4Number(ip)
+  return V4_BLOCKED.some(([net, bits]) => Math.floor(n / 2 ** (32 - bits)) === Math.floor(v4Number(net) / 2 ** (32 - bits)))
+}
+
+/** The eight 16-bit groups of an IPv6 address (with any embedded IPv4 tail converted). */
+function v6Groups(ip: string): number[] {
+  let text = ip.toLowerCase().replace(/%.*$/, "")
+  const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text)
+  if (tail) {
+    const n = v4Number(tail[1]!)
+    text = `${text.slice(0, -tail[1]!.length)}${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`
+  }
+  const [head, rest] = text.split("::") as [string, string | undefined]
+  const left = head ? head.split(":") : []
+  const right = rest === undefined ? [] : rest ? rest.split(":") : []
+  const fill = rest === undefined ? [] : Array(8 - left.length - right.length).fill("0")
+  return [...left, ...fill, ...right].map((g) => parseInt(g, 16))
+}
+
+/** True for addresses a push endpoint must not resolve to. Anything that is not an IP counts as private. */
+export function isPrivateAddress(address: string): boolean {
+  const ip = address.trim().replace(/^\[(.*)\]$/, "$1")
+  if (isIPv4(ip)) return privateV4(ip)
+  if (!isIPv6(ip)) return true
+  const g = v6Groups(ip)
+  const first = g[0]!
+  if (g.slice(0, 5).every((x) => x === 0) && (g[5] === 0xffff || g[5] === 0)) {
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d, which includes :: and ::1).
+    if (g[5] === 0 && g[6] === 0 && (g[7] === 0 || g[7] === 1)) return true
+    return privateV4(`${g[6]! >> 8}.${g[6]! & 0xff}.${g[7]! >> 8}.${g[7]! & 0xff}`)
+  }
+  if (first === 0x64 && g[1] === 0xff9b) return privateV4(`${g[6]! >> 8}.${g[6]! & 0xff}.${g[7]! >> 8}.${g[7]! & 0xff}`) // NAT64
+  return (
+    (first & 0xfe00) === 0xfc00 || // ULA fc00::/7
+    (first & 0xffc0) === 0xfe80 || // link-local fe80::/10
+    (first & 0xffc0) === 0xfec0 || // site-local fec0::/10 (deprecated)
+    (first & 0xff00) === 0xff00 // multicast
+  )
+}
+
+const LOCAL_SUFFIXES = [".localhost", ".local", ".internal", ".localdomain", ".home.arpa", ".lan"]
+
+/** Why an endpoint is not acceptable for Web Push, or undefined when it is. */
+export async function pushEndpointProblem(endpoint: string, resolve: ResolveHost): Promise<string | undefined> {
+  let url: URL
+  try {
+    url = new URL(endpoint)
+  } catch {
+    return "Push endpoint is not a URL"
+  }
+  if (url.protocol !== "https:") return "Push endpoint must be https"
+  if (url.username || url.password) return "Push endpoint must not carry credentials"
+  const host = url.hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.$/, "")
+  if (isIPv4(host) || isIPv6(host)) return isPrivateAddress(host) ? "Push endpoint is a private or local address" : undefined
+  if (host === "localhost" || !host.includes(".") || LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix))) {
+    return "Push endpoint is a local hostname"
+  }
+  let addresses: readonly string[]
+  try {
+    addresses = await resolve(host)
+  } catch {
+    return `Push endpoint host ${host} does not resolve`
+  }
+  if (addresses.length === 0) return `Push endpoint host ${host} does not resolve`
+  if (addresses.some(isPrivateAddress)) return "Push endpoint resolves to a private or local address"
+  return undefined
+}