@huynle/hub 0.0.0-stage → 0.6.1

package/bin/hub.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+// Hub server entry point (`hub-server`, aliases `opencode-hub` and `opencode-voice-hub`): `bun bin/hub.ts [--help | --version]`,
+// configured by HUB_* env vars over ~/.config/hub/hub.json ($HUB_CONFIG); see src/central/config.ts. Serves the
+// built web app (web/dist, `npm run build:web`) from disk. The standalone binaries embed it instead
+// (scripts/build-binaries.sh).
+import { readFileSync } from "node:fs"
+import path from "node:path"
+import { diskAssets } from "../src/central/assets"
+import { runHub } from "../src/central/main"
+
+const root = path.join(import.meta.dir, "..")
+const version = (() => {
+  try {
+    return String(JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version ?? "0.0.0")
+  } catch {
+    return "0.0.0"
+  }
+})()
+
+runHub({ web: diskAssets(path.join(root, "web", "dist")), version })

package/docker/hub-deps.ts

@@ -0,0 +1,42 @@
+// Docker build helper: copies the hub's runtime packages (and everything they depend on, as resolved by the
+// lockfile install in ./node_modules) into <out>/node_modules. The plugin-only @opencode/* packages are left out.
+//   bun docker/hub-deps.ts /deps web-push
+import { cpSync, existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+const [out, ...roots] = process.argv.slice(2)
+if (!out || roots.length === 0) throw new Error("usage: hub-deps.ts <out-dir> <package>...")
+const top = path.resolve("node_modules")
+
+/** Node resolution: nearest node_modules/<name> walking up from `from`, stopping at the project root. */
+function resolve(from: string, name: string): string {
+  for (let dir = from; dir.startsWith(top); dir = path.dirname(dir)) {
+    const candidate = path.join(dir, "node_modules", name)
+    if (existsSync(path.join(candidate, "package.json"))) return candidate
+  }
+  const candidate = path.join(top, name)
+  if (existsSync(path.join(candidate, "package.json"))) return candidate
+  throw new Error(`cannot resolve ${name} from ${from}`)
+}
+
+const seen = new Set<string>()
+const queue = roots.map((name) => resolve(top, name))
+while (queue.length) {
+  const dir = queue.pop()!
+  if (seen.has(dir)) continue
+  seen.add(dir)
+  const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"))
+  for (const name of Object.keys({ ...pkg.dependencies, ...pkg.optionalDependencies })) {
+    try {
+      queue.push(resolve(dir, name))
+    } catch (cause) {
+      if (!pkg.optionalDependencies?.[name]) throw cause
+    }
+  }
+}
+
+// Copy outermost package directories only; nested node_modules come along with their parent.
+const dirs = [...seen].sort()
+const outer = dirs.filter((dir) => !dirs.some((other) => other !== dir && dir.startsWith(other + path.sep)))
+for (const dir of outer) cpSync(dir, path.join(out, "node_modules", path.relative(top, dir)), { recursive: true })
+console.log(`hub deps: ${outer.length} packages → ${out}/node_modules`)

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@huynle/hub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huynle/hub.git"
+  },
+  "homepage": "https://github.com/huynle/hub#readme",
+  "bugs": {
+    "url": "https://github.com/huynle/hub/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "hub",
+    "remote",
+    "console",
+    "voice",
+    "speech",
+    "tts",
+    "stt",
+    "pwa",
+    "agent",
+    "harness"
+  ],
+  "type": "module",
+  "main": "./server.ts",
+  "exports": {
+    ".": "./server.ts",
+    "./server": "./server.ts",
+    "./tui": "./tui.ts",
+    "./rpc": "./rpc.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "hub-server": "bin/hub.ts",
+    "opencode-hub": "bin/hub.ts",
+    "opencode-voice-hub": "bin/hub.ts"
+  },
+  "files": [
+    "server.ts",
+    "tui.ts",
+    "rpc.ts",
+    "src",
+    "bin",
+    "web/dist",
+    "docker",
+    "Dockerfile",
+    "scripts/hub-local.sh",
+    "scripts/io.github.huynle.hub.plist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p web",
+    "build:web": "vite build --config web/vite.config.ts",
+    "dev:web": "vite --config web/vite.config.ts",
+    "test:e2e": "bun web/e2e/smoke.ts",
+    "prepack": "npm run build:web",
+    "hub": "bun bin/hub.ts"
+  },
+  "dependencies": {
+    "@opencode/client": "^2.0.26",
+    "@opencode/plugin": "^2.0.26",
+    "web-push": "^3.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/web-push": "^3.6.4",
+    "playwright-core": "^1.64.1",
+    "solid-js": "^1.9.17",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.4",
+    "vite-plugin-solid": "^2.11.14"
+  }
+}

package/rpc.ts

@@ -0,0 +1,2 @@
+// RPC definitions for clients, resolved by OpenCode as <dir>/rpc. VoiceRpc is the deprecated opencode-voice id.
+export { HubRpc, VoiceRpc } from "./src/rpc.ts"

package/scripts/hub-local.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Run Hub on this machine in the foreground (Ctrl-C stops it).
+# Configured by ~/.config/hub/hub.json (or $HUB_CONFIG); HUB_* env vars win over it. The legacy names
+# ($VOICE_HUB_CONFIG, VOICE_*) still work, and on first start the hub copies a legacy hub.json and state
+# directory from ~/.config/opencode-hub and ~/.local/state/opencode-hub (else the opencode-voice ones).
+# Default address http://127.0.0.1:4097, state in ~/.local/state/hub. See README → Local only.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+BASE="${XDG_CONFIG_HOME:-$HOME/.config}"
+CONFIG="${HUB_CONFIG:-${VOICE_HUB_CONFIG:-$BASE/hub/hub.json}}"
+LEGACY=""
+for dir in opencode-hub opencode-voice; do
+  if [[ -f "$BASE/$dir/hub.json" ]]; then LEGACY="$BASE/$dir/hub.json"; break; fi
+done
+if [[ -f "$CONFIG" ]]; then
+  perms=$(stat -f %Lp "$CONFIG" 2>/dev/null || stat -c %a "$CONFIG")
+  if [[ "$perms" != "600" && "$perms" != "400" ]]; then
+    echo "warning: $CONFIG has mode $perms; API keys in it are ignored until you run: chmod 600 $CONFIG" >&2
+  fi
+elif [[ -z "${HUB_CONFIG:-}${VOICE_HUB_CONFIG:-}" && -n "$LEGACY" ]]; then
+  echo "note: $CONFIG not found; the hub copies $LEGACY there on start" >&2
+else
+  echo "note: $CONFIG not found; using env vars and defaults" >&2
+fi
+BUN="${BUN:-$(command -v bun || true)}"
+[[ -n "$BUN" ]] || BUN="$HOME/.bun/bin/bun"
+cd "$ROOT"
+exec "$BUN" bin/hub.ts "$@"

package/scripts/io.github.huynle.hub.plist

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Template: keep a local Hub running on macOS (launchd). Not installed by anything.
+  Install (replace __REPO__ and __HOME__ first):
+    sed -e "s|__REPO__|$PWD|g" -e "s|__HOME__|$HOME|g" scripts/io.github.huynle.hub.plist \
+      > ~/Library/LaunchAgents/io.github.huynle.hub.plist
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.huynle.hub.plist
+  Remove:
+    launchctl bootout gui/$(id -u)/io.github.huynle.hub && rm ~/Library/LaunchAgents/io.github.huynle.hub.plist
+  The hub reads ~/.config/hub/hub.json (mode 0600). Only one hub per machine at a time:
+  with this agent loaded, the plugin's auto-start finds it running and does nothing.
+
+  Upgrading: this replaces com.opencode-hub.hub (opencode-hub) and com.opencode-voice.hub (opencode-voice).
+  Remove the old agent first, e.g.:
+    launchctl bootout gui/$(id -u)/com.opencode-hub.hub && rm ~/Library/LaunchAgents/com.opencode-hub.hub.plist
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>io.github.huynle.hub</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__REPO__/scripts/hub-local.sh</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>__HOME__/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>__HOME__/.local/state/hub/hub.log</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.local/state/hub/hub.log</string>
+</dict>
+</plist>

package/server.ts

@@ -0,0 +1,3 @@
+// OpenCode resolves a local plugin directory's server entry as <dir>/server or <dir>/index;
+// package.json "main" is not consulted.
+export { default } from "./src/index.ts"

package/src/central/assets.ts

@@ -0,0 +1,74 @@
+// The hub's web app files (web/dist) behind one interface: read from disk (a checkout, the npm package, the Docker
+// image) or from files embedded in a compiled binary (`bun build --compile`, see scripts/gen-web-entry.ts).
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+export interface WebAssets {
+  /** The bytes of web/<name> ("app.js", "sub/x.js"), or undefined when there is no such file. */
+  read(name: string): Uint8Array<ArrayBuffer> | undefined
+}
+
+/** Files under `dir`; anything resolving outside it (or a folder) is not found. */
+export function diskAssets(dir: string): WebAssets {
+  const root = path.resolve(dir)
+  return {
+    read(name) {
+      if (!name) return undefined
+      const file = path.resolve(root, name)
+      if (!file.startsWith(root + path.sep) || !existsSync(file) || !statSync(file).isFile()) return undefined
+      return readFileSync(file)
+    },
+  }
+}
+
+/**
+ * A name → path map, as `import f from "../web/dist/index.html" with { type: "file" }` gives it: a path inside the
+ * compiled binary ($bunfs), or the file on disk when the entry runs from source.
+ */
+export function embeddedAssets(files: Readonly<Record<string, string>>): WebAssets {
+  const table = new Map(Object.entries(files))
+  return {
+    read(name) {
+      const file = table.get(name)
+      if (!file) return undefined
+      try {
+        return readFileSync(file)
+      } catch {
+        return undefined
+      }
+    },
+  }
+}
+
+/** Files that belong in the page (not type declarations, not hidden files). */
+export function isWebAsset(name: string): boolean {
+  const base = name.split("/").pop() ?? name
+  return !base.startsWith(".") && !base.endsWith(".d.ts") && !base.endsWith(".map")
+}
+
+/** Source of a module that embeds web/ files: `export default { "<name>": <embedded path>, … }`. */
+export function webAssetModule(names: readonly string[], from: string): string {
+  const files = names.filter(isWebAsset)
+  const imports = files.map((name, i) => `import f${i} from ${JSON.stringify(`${from}/${name}`)} with { type: "file" }`)
+  const entries = files.map((name, i) => `  ${JSON.stringify(name)}: f${i},`)
+  return [
+    "// Generated by scripts/gen-web-entry.ts: web/ files embedded in the compiled hub. Do not edit.",
+    ...imports,
+    "",
+    "export default {",
+    ...entries,
+    "} as Record<string, string>",
+    "",
+  ].join("\n")
+}
+
+/** Files under `dir` as "/"-separated paths relative to it ("index.html", "assets/index-x.js"), sorted. */
+export function webFiles(dir: string, prefix = ""): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(path.join(dir, prefix), { withFileTypes: true })) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name
+    if (entry.isDirectory()) out.push(...webFiles(dir, name))
+    else if (entry.isFile()) out.push(name)
+  }
+  return out.sort()
+}

package/src/central/auth.ts

@@ -0,0 +1,271 @@
+// Credentials issued by the central server:
+// - machine enrollment (device-code flow): a spoke asks, the owner approves in the web UI, the spoke polls for its token
+// - device pairing: short single-use numeric codes, shown in the /hub dialog or logged at startup
+// - login links: long single-use codes opened from the terminal to sign a browser in
+// Pending codes live in memory only; a restart invalidates them.
+import { randomBytes, randomInt } from "node:crypto"
+import type { EnrollPoll, EnrollStart } from "../protocol"
+import { LOCAL_USER, newToken, type DeviceRecord, type Store } from "./store"
+
+export class RateLimitError extends Error {
+  constructor(message = "Too many attempts; try again in a minute") {
+    super(message)
+    this.name = "RateLimitError"
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ValidationError"
+  }
+}
+
+/** Sliding-window counter. */
+export class Limiter {
+  private hits: number[] = []
+
+  constructor(
+    private readonly max: number,
+    private readonly windowMs: number,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** True when another hit is allowed right now (does not record one). */
+  allowed(): boolean {
+    const cutoff = this.now() - this.windowMs
+    this.hits = this.hits.filter((t) => t > cutoff)
+    return this.hits.length < this.max
+  }
+
+  hit(): void {
+    this.hits.push(this.now())
+  }
+
+  /** Records a hit if allowed. */
+  tryHit(): boolean {
+    if (!this.allowed()) return false
+    this.hit()
+    return true
+  }
+}
+
+export const ENROLL_TTL_MS = 10 * 60_000
+export const ENROLL_INTERVAL_MS = 2000
+export const PAIR_TTL_MS = 5 * 60_000
+export const LOGIN_TTL_MS = 2 * 60_000
+
+/** RFC 8628 base-20 alphabet: no vowels, no look-alike characters. */
+const USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ"
+
+function userCode(): string {
+  let out = ""
+  for (let i = 0; i < 8; i++) out += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)]
+  return `${out.slice(0, 4)}-${out.slice(4)}`
+}
+
+/** Accepts "abcd-efgh", "ABCDEFGH", " abcd efgh ". */
+function normalizeUserCode(code: string): string {
+  const raw = code.toUpperCase().replace(/[^A-Z]/g, "")
+  return raw.length === 8 ? `${raw.slice(0, 4)}-${raw.slice(4)}` : raw
+}
+
+function name(value: unknown, what: string, fallback?: string): string {
+  const text = typeof value === "string" ? value.trim().replace(/\s+/g, " ") : ""
+  if (!text && fallback !== undefined) return fallback
+  if (!text || text.length > 64) throw new ValidationError(`Invalid ${what}: 1-64 characters required`)
+  return text
+}
+
+interface Enrollment {
+  userCode: string
+  deviceCode: string
+  machineName: string
+  created: number
+  expiresAt: number
+  status: "pending" | "approved" | "denied"
+  /** The approver: owner of the machine created on the next poll. */
+  ownerID?: string
+}
+
+/** A pending pairing code or login link and the user its device will belong to. */
+interface Grant {
+  readonly expiresAt: number
+  readonly ownerID: string
+}
+
+export interface PendingEnrollment {
+  readonly userCode: string
+  readonly machineName: string
+  readonly created: number
+  readonly expiresAt: number
+}
+
+export interface AuthOptions {
+  readonly store: Store
+  readonly publicURL: string
+  readonly now?: () => number
+  /** oidc: no bootstrap pairing code (devices are created by sign-in or by a machine owner). */
+  readonly mode?: "pairing" | "oidc"
+}
+
+export class Auth {
+  private readonly store: Store
+  private readonly publicURL: string
+  private readonly now: () => number
+  private readonly enrollments = new Map<string, Enrollment>() // by deviceCode
+  private readonly pairCodes = new Map<string, Grant>()
+  private readonly loginCodes = new Map<string, Grant>()
+  private readonly mode: "pairing" | "oidc"
+  private readonly enrollLimiter: Limiter
+  private readonly pairFailures: Limiter
+
+  constructor(options: AuthOptions) {
+    this.store = options.store
+    this.publicURL = options.publicURL
+    this.now = options.now ?? Date.now
+    this.mode = options.mode ?? "pairing"
+    this.enrollLimiter = new Limiter(5, 60_000, this.now)
+    this.pairFailures = new Limiter(10, 60_000, this.now)
+  }
+
+  // ---------- machine enrollment ----------
+
+  startEnrollment(machineName: unknown): EnrollStart {
+    const machine = name(machineName, "machine name")
+    if (!this.enrollLimiter.tryHit()) throw new RateLimitError("Too many enrollment requests; try again in a minute")
+    this.sweep()
+    const taken = new Set([...this.enrollments.values()].map((e) => e.userCode))
+    let code = userCode()
+    while (taken.has(code)) code = userCode()
+    const created = this.now()
+    const enrollment: Enrollment = {
+      userCode: code,
+      deviceCode: newToken(),
+      machineName: machine,
+      created,
+      expiresAt: created + ENROLL_TTL_MS,
+      status: "pending",
+    }
+    this.enrollments.set(enrollment.deviceCode, enrollment)
+    return {
+      userCode: code,
+      deviceCode: enrollment.deviceCode,
+      approveURL: `${this.publicURL}/approve?code=${code}`,
+      intervalMs: ENROLL_INTERVAL_MS,
+      expiresAt: enrollment.expiresAt,
+    }
+  }
+
+  /** Approved and denied results are delivered once; afterwards the code reads as expired. */
+  pollEnrollment(deviceCode: unknown): EnrollPoll {
+    this.sweep()
+    const enrollment = typeof deviceCode === "string" ? this.enrollments.get(deviceCode) : undefined
+    if (!enrollment) return { status: "expired" }
+    if (enrollment.status === "pending") return { status: "pending" }
+    this.enrollments.delete(enrollment.deviceCode)
+    if (enrollment.status === "denied") return { status: "denied" }
+    const { machine, token } = this.store.addMachine(enrollment.machineName, enrollment.ownerID ?? LOCAL_USER)
+    return { status: "approved", machineID: machine.id, machineToken: token }
+  }
+
+  pendingEnrollments(): PendingEnrollment[] {
+    this.sweep()
+    return [...this.enrollments.values()]
+      .filter((e) => e.status === "pending")
+      .map(({ userCode, machineName, created, expiresAt }) => ({ userCode, machineName, created, expiresAt }))
+  }
+
+  /** Approves a pending enrollment; `ownerID` (the approver) will own the machine. */
+  approveEnrollment(code: string, ownerID: string = LOCAL_USER): boolean {
+    return this.decide(code, "approved", ownerID) !== undefined
+  }
+
+  denyEnrollment(code: string): boolean {
+    return this.decide(code, "denied") !== undefined
+  }
+
+  /** Approves or denies a pending enrollment; the machine name, or undefined when no such code is pending. */
+  decide(code: string, status: "approved" | "denied", ownerID: string = LOCAL_USER): string | undefined {
+    this.sweep()
+    const wanted = normalizeUserCode(code)
+    for (const enrollment of this.enrollments.values()) {
+      if (enrollment.userCode === wanted && enrollment.status === "pending") {
+        enrollment.status = status
+        if (status === "approved") enrollment.ownerID = ownerID
+        return enrollment.machineName
+      }
+    }
+    return undefined
+  }
+
+  // ---------- device pairing ----------
+
+  /** A pairing code; the device it pairs belongs to `ownerID`. */
+  issuePairCode(ownerID: string = LOCAL_USER): { code: string; expiresAt: number } {
+    this.sweep()
+    let code = String(randomInt(1_000_000)).padStart(6, "0")
+    while (this.pairCodes.has(code)) code = String(randomInt(1_000_000)).padStart(6, "0")
+    const expiresAt = this.now() + PAIR_TTL_MS
+    this.pairCodes.set(code, { expiresAt, ownerID })
+    return { code, expiresAt }
+  }
+
+  /** A pairing code for the first device (pairing mode only), or undefined once any device exists. */
+  bootstrapCode(): { code: string; expiresAt: number } | undefined {
+    return this.mode === "pairing" && this.store.devices().length === 0 ? this.issuePairCode(LOCAL_USER) : undefined
+  }
+
+  /**
+   * Redeems a pairing code. Throws RateLimitError after too many recent failures. A code whose owner
+   * is gone or disabled counts as invalid.
+   */
+  pair(code: unknown, deviceName: unknown): { device: DeviceRecord; token: string } | undefined {
+    if (!this.pairFailures.allowed()) throw new RateLimitError()
+    this.sweep()
+    const key = typeof code === "string" ? code.trim() : ""
+    const grant = this.pairCodes.get(key)
+    if (!grant) {
+      this.pairFailures.hit()
+      return undefined
+    }
+    this.pairCodes.delete(key)
+    if (!this.active(grant.ownerID)) return undefined
+    return this.store.addDevice(name(deviceName, "device name", "Device"), grant.ownerID)
+  }
+
+  // ---------- login links ----------
+
+  /** A single-use login link code; it signs a browser in as `ownerID`. */
+  issueLoginCode(ownerID: string = LOCAL_USER): { code: string; expiresAt: number } {
+    const code = randomBytes(32).toString("base64url")
+    const expiresAt = this.now() + LOGIN_TTL_MS
+    this.loginCodes.set(code, { expiresAt, ownerID })
+    return { code, expiresAt }
+  }
+
+  /** Redeems a login code: the user to sign in as, or undefined (unknown, used, expired, or owner disabled). */
+  redeemLogin(code: unknown): string | undefined {
+    this.sweep()
+    const grant = typeof code === "string" ? this.loginCodes.get(code) : undefined
+    if (!grant) return undefined
+    this.loginCodes.delete(code as string)
+    return this.active(grant.ownerID) ? grant.ownerID : undefined
+  }
+
+  redeemLoginCode(code: unknown): boolean {
+    return this.redeemLogin(code) !== undefined
+  }
+
+  private active(userID: string): boolean {
+    const user = this.store.user(userID)
+    return user !== undefined && !user.disabled
+  }
+
+  private sweep(): void {
+    const t = this.now()
+    for (const [key, e] of this.enrollments) if (e.expiresAt < t) this.enrollments.delete(key)
+    for (const [key, grant] of this.pairCodes) if (grant.expiresAt < t) this.pairCodes.delete(key)
+    for (const [key, grant] of this.loginCodes) if (grant.expiresAt < t) this.loginCodes.delete(key)
+  }
+}