@huynle/hub 0.6.0 → 0.7.1

package/packages/runtime-openshell/src/policy.ts

@@ -0,0 +1,155 @@
+// Compiles a hub profile into an OpenShell sandbox policy (decision lk6gn3u7 §7; OpenShell 0.1.x policy schema
+// version 1). Deny by default: the policy holds only these network rules, each for the harness binary alone
+// (OpenShell matches a connection's ancestors too, so the agent's shells and git inherit the harness's egress):
+//
+//   hub            the hub, protocol tcp: the supervisor proxy relays it without terminating TLS. A loopback hub is
+//                  reached through host.openshell.internal (OpenShell never authorizes loopback destinations).
+//   git_remote     the launch's git remote, only when the profile sets allowGitRemote (https inspected; ssh tcp).
+//   profile_egress the profile's extra endpoints, minus any host:port an earlier rule already has.
+//
+// Model provider endpoints are not listed: attached OpenShell providers contribute their own `_provider_*` rules,
+// and the keys stay in OpenShell's proxy. The filesystem section is OpenShell's documented baseline plus the
+// sandbox working directory and /sandbox.
+//
+// Every value is validated before it gets here and every string is emitted double-quoted (JSON strings are YAML
+// scalars), so no input can add keys to the document.
+import { isGitRemote } from "../../protocol/src/index.ts"
+import { RuntimeError } from "../../runtime-sdk/src/index.ts"
+import { egressHost, type EgressEndpoint, type OpenShellProfile } from "./profiles.ts"
+
+/** The only binary the policy lets out: the harness baked into the sandbox image. */
+export const HARNESS_BINARY = "/usr/local/bin/opencode"
+/** How a sandbox reaches the gateway host (and so a loopback-bound hub). */
+export const SANDBOX_HOST_ALIAS = "host.openshell.internal"
+
+const READ_ONLY = ["/usr", "/lib", "/bin", "/etc", "/app", "/var/log", "/proc", "/dev/urandom"]
+const READ_WRITE = ["/sandbox", "/tmp", "/dev/null"]
+const DEFAULT_PORTS: Record<string, number> = { "http:": 80, "ws:": 80, "https:": 443, "wss:": 443 }
+
+/** A destination in a network rule; `tcp` relays the raw connection (no TLS termination, no request checks). */
+export interface PolicyEndpoint extends EgressEndpoint {
+  readonly protocol?: "tcp"
+}
+
+/** The hub as the sandbox sees it: the policy endpoint and the URL the harness inside connects to. */
+export interface HubEndpoint {
+  readonly host: string
+  readonly port: number
+  readonly url: string
+}
+
+export interface PolicyInput {
+  /** The hub URL as the node knows it (config.json `server`). */
+  readonly hubURL: string
+  readonly profile: OpenShellProfile
+  /** The launch's workspace remote; allowed only when the profile sets allowGitRemote. */
+  readonly gitRemote?: string
+}
+
+export interface CompiledPolicy {
+  /** The policy document for `openshell sandbox create --policy`. */
+  readonly yaml: string
+  /** OpenShell providers to attach (`--provider`), whose rules and credentials OpenShell adds itself. */
+  readonly providers: readonly string[]
+  /** The hub URL to hand the harness inside the sandbox. */
+  readonly hubURL: string
+}
+
+const isLoopback = (host: string): boolean =>
+  host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+
+/** Where the sandbox reaches the hub; RuntimeError when the URL is not one a policy can allow. */
+export function sandboxHubEndpoint(hubURL: string): HubEndpoint {
+  let url: URL
+  try {
+    url = new URL(hubURL)
+  } catch {
+    throw new RuntimeError("the hub URL is not an http(s) or ws(s) URL")
+  }
+  const defaultPort = DEFAULT_PORTS[url.protocol]
+  if (defaultPort === undefined || !url.hostname) throw new RuntimeError("the hub URL is not an http(s) or ws(s) URL")
+  const port = url.port ? Number(url.port) : defaultPort
+  if (isLoopback(url.hostname)) {
+    url.hostname = SANDBOX_HOST_ALIAS
+    return { host: SANDBOX_HOST_ALIAS, port, url: url.href }
+  }
+  const host = url.hostname.includes("*") ? undefined : egressHost(url.hostname)
+  if (!host) throw new RuntimeError(`the hub's host ${url.hostname.replace(/^\[|\]$/g, "")} cannot be allowed in a sandbox policy`)
+  return { host, port, url: url.href }
+}
+
+/** The endpoint a git remote needs: https (443) inspected, ssh or scp-style (22) tcp; undefined when unusable. */
+export function gitRemoteEndpoint(remote: string): PolicyEndpoint | undefined {
+  if (!isGitRemote(remote)) return undefined
+  let host: string | undefined
+  let port: number
+  let tcp: boolean
+  const scp = /^[^@/]+@([^:/]+):/.exec(remote)
+  if (scp?.[1]) {
+    host = scp[1]
+    port = 22
+    tcp = true
+  } else {
+    const url = new URL(remote)
+    host = url.hostname
+    tcp = url.protocol === "ssh:"
+    port = url.port ? Number(url.port) : tcp ? 22 : 443
+  }
+  const clean = egressHost(host)
+  if (!clean || clean.includes("*") || isLoopback(clean)) return undefined
+  return tcp ? { host: clean, port, protocol: "tcp" } : { host: clean, port }
+}
+
+interface Rule {
+  readonly key: string
+  readonly name: string
+  readonly endpoints: readonly PolicyEndpoint[]
+}
+
+const q = (s: string) => JSON.stringify(s)
+
+function emit(profile: string, rules: readonly Rule[]): string {
+  const lines = [
+    `# hub sandbox policy for profile ${profile}: deny by default; only the rules below allow egress.`,
+    "version: 1",
+    "",
+    "filesystem_policy:",
+    "  include_workdir: true",
+    "  read_only:",
+    ...READ_ONLY.map((p) => `    - ${q(p)}`),
+    "  read_write:",
+    ...READ_WRITE.map((p) => `    - ${q(p)}`),
+    "",
+    "landlock:",
+    "  compatibility: best_effort",
+    "",
+    "network_policies:",
+  ]
+  for (const rule of rules) {
+    lines.push(`  ${rule.key}:`, `    name: ${q(rule.name)}`, "    endpoints:")
+    for (const e of rule.endpoints) {
+      lines.push(`      - host: ${q(e.host)}`, `        port: ${e.port}`)
+      if (e.protocol) lines.push(`        protocol: ${e.protocol}`)
+    }
+    lines.push("    binaries:", `      - path: ${q(HARNESS_BINARY)}`)
+  }
+  return lines.join("\n") + "\n"
+}
+
+/** The OpenShell policy, providers and in-sandbox hub URL for a launch with this profile. */
+export function compilePolicy(input: PolicyInput): CompiledPolicy {
+  const hub = sandboxHubEndpoint(input.hubURL)
+  const rules: Rule[] = [{ key: "hub", name: "hub", endpoints: [{ host: hub.host, port: hub.port, protocol: "tcp" }] }]
+
+  if (input.profile.allowGitRemote && input.gitRemote !== undefined) {
+    const git = gitRemoteEndpoint(input.gitRemote)
+    if (!git) throw new RuntimeError("the launch's git remote has no host the sandbox can reach")
+    rules.push({ key: "git_remote", name: "git-remote", endpoints: [git] })
+  }
+
+  const taken = new Set(rules.flatMap((r) => r.endpoints.map((e) => `${e.host}:${e.port}`)))
+  const extras = input.profile.endpoints.filter((e) => !taken.has(`${e.host}:${e.port}`))
+  if (extras.length > 0) rules.push({ key: "profile_egress", name: "profile-egress", endpoints: extras.map((e) => ({ host: e.host, port: e.port })) })
+
+  return { yaml: emit(input.profile.name, rules), providers: [...input.profile.providers], hubURL: hub.url }
+}

package/packages/runtime-openshell/src/profiles.ts

@@ -0,0 +1,181 @@
+// Hub profiles for OpenShell sandboxes (decision lk6gn3u7 §2, §4, §9): node.json `openshell.profiles`, a map of
+// profile name to { image?, providers?, endpoints?, allowGitRemote? }. Phase 5 keeps them on the node; a hub-side
+// profile store comes later. They are not OpenShell's own (credential) profiles: `providers` names OpenShell
+// providers the node operator created, and the sandbox only ever sees their placeholders.
+//
+// Normalized field by field like the rest of node.json: a bad field is dropped with one problem line. A profile
+// that asks for what the vm backend cannot honour (host mounts, cpu, memory) is never used in a weaker form: it is
+// listed as unsupported and a launch naming it fails `unsupported`.
+//
+// node.json: { "openshell": { "profiles": { "untrusted-code": { "image": "hub-sandbox:0.1",
+//   "providers": ["anthropic"], "endpoints": ["registry.npmjs.org:443"], "allowGitRemote": false } } } }
+import { token } from "../../protocol/src/wire.ts"
+import { RuntimeError } from "../../runtime-sdk/src/index.ts"
+
+/** The profile a launch without `runtime.profile` gets; built in (deny all but the hub) unless node.json sets it. */
+export const DEFAULT_PROFILE = "default"
+export const PROFILES_MAX = 32
+export const ENDPOINTS_MAX = 64
+const NAME_MAX = 64
+const IMAGE = /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,254}$/
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
+const KNOWN_FIELDS = new Set(["image", "providers", "endpoints", "allowGitRemote"])
+/** Fields the vm backend cannot honour (decision 9), in the order the reason lists them. */
+const UNSUPPORTED_FIELDS = ["mounts", "cpu", "memoryMB", "memory"] as const
+
+/** An egress destination a profile adds to the policy. */
+export interface EgressEndpoint {
+  readonly host: string
+  readonly port: number
+}
+
+export interface OpenShellProfile {
+  readonly name: string
+  /** The sandbox image; unset: the runtime's default image. */
+  readonly image?: string
+  /** OpenShell provider names attached to the sandbox (model keys, injected by OpenShell's proxy). */
+  readonly providers: readonly string[]
+  /** Extra egress beyond the hub (and the providers' own endpoints). */
+  readonly endpoints: readonly EgressEndpoint[]
+  /** Allow egress to the launch's git remote (pushing from inside is a later opt-in; off by default). */
+  readonly allowGitRemote: boolean
+}
+
+export interface OpenShellProfiles {
+  readonly profiles: Readonly<Record<string, OpenShellProfile>>
+  /** Profile name → why it cannot be used on this node. */
+  readonly unsupported: Readonly<Record<string, string>>
+  readonly problems: readonly string[]
+}
+
+/** A launch named a profile this node does not have (`not_found`) or cannot honour (`unsupported`). */
+export class ProfileError extends RuntimeError {
+  constructor(
+    readonly code: "unsupported" | "not_found",
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const show = (v: unknown) => JSON.stringify(v)?.slice(0, 80) ?? String(v)
+const builtinDefault = (): OpenShellProfile => ({ name: DEFAULT_PROFILE, providers: [], endpoints: [], allowGitRemote: false })
+
+/** A hostname (lowercase), or a wildcard host OpenShell accepts: `*` or `**` as the first of at least three labels. */
+export function egressHost(v: string): string | undefined {
+  const host = v.toLowerCase()
+  if (host.length > 253) return undefined
+  const labels = host.split(".")
+  const [first, ...rest] = labels
+  const wildcard = first === "*" || first === "**"
+  if (wildcard && labels.length < 3) return undefined
+  return (wildcard ? rest : labels).every((label) => LABEL.test(label)) ? host : undefined
+}
+
+const isPort = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 65535
+
+/** "host:port" or { host, port }. */
+function egressEndpoint(v: unknown): EgressEndpoint | undefined {
+  let host: unknown
+  let port: unknown
+  if (typeof v === "string") {
+    const colon = v.lastIndexOf(":")
+    if (colon < 0 || !/^\d{1,5}$/.test(v.slice(colon + 1))) return undefined
+    host = v.slice(0, colon)
+    port = Number(v.slice(colon + 1))
+  } else if (isObject(v)) {
+    host = v.host
+    port = v.port
+  }
+  if (typeof host !== "string" || !isPort(port)) return undefined
+  const clean = egressHost(host)
+  return clean ? { host: clean, port } : undefined
+}
+
+function normalizeProfile(name: string, r: Record<string, unknown>, problems: string[]): OpenShellProfile {
+  const at = `openshell.profiles.${name}`
+  for (const key of Object.keys(r)) if (!KNOWN_FIELDS.has(key)) problems.push(`${at}: unknown field ${show(key)} ignored`)
+
+  let image: string | undefined
+  if (r.image !== undefined) {
+    if (typeof r.image === "string" && IMAGE.test(r.image)) image = r.image
+    else problems.push(`${at}.image: ${show(r.image)} is not an image reference`)
+  }
+
+  const providers: string[] = []
+  if (r.providers !== undefined && !Array.isArray(r.providers)) problems.push(`${at}.providers must be a list of provider names`)
+  for (const provider of Array.isArray(r.providers) ? r.providers : []) {
+    if (!token(provider, NAME_MAX)) problems.push(`${at}.providers: ${show(provider)} is not a provider name`)
+    else if (!providers.includes(provider)) providers.push(provider)
+  }
+
+  const endpoints: EgressEndpoint[] = []
+  if (r.endpoints !== undefined && !Array.isArray(r.endpoints)) problems.push(`${at}.endpoints must be a list of host:port`)
+  for (const raw of Array.isArray(r.endpoints) ? r.endpoints : []) {
+    const endpoint = egressEndpoint(raw)
+    if (!endpoint) problems.push(`${at}.endpoints: ${show(raw)} is not host:port`)
+    else if (!endpoints.some((e) => e.host === endpoint.host && e.port === endpoint.port)) endpoints.push(endpoint)
+  }
+  if (endpoints.length > ENDPOINTS_MAX) {
+    problems.push(`${at}.endpoints: at most ${ENDPOINTS_MAX} endpoints; the rest are ignored`)
+    endpoints.length = ENDPOINTS_MAX
+  }
+
+  let allowGitRemote = false
+  if (r.allowGitRemote !== undefined) {
+    if (typeof r.allowGitRemote === "boolean") allowGitRemote = r.allowGitRemote
+    else problems.push(`${at}.allowGitRemote must be true or false`)
+  }
+
+  return { name, ...(image !== undefined ? { image } : {}), providers, endpoints, allowGitRemote }
+}
+
+/** Normalizes untrusted node.json `openshell.profiles`; the default profile is always there unless unsupported. */
+export function normalizeOpenShellProfiles(raw: unknown): OpenShellProfiles {
+  const problems: string[] = []
+  const profiles: Record<string, OpenShellProfile> = { [DEFAULT_PROFILE]: builtinDefault() }
+  const unsupported: Record<string, string> = {}
+  if (raw !== undefined && !isObject(raw)) problems.push("openshell.profiles must be an object of profile name to profile")
+
+  let entries = Object.entries(isObject(raw) ? raw : {})
+  if (entries.length > PROFILES_MAX) {
+    problems.push(`openshell.profiles: at most ${PROFILES_MAX} profiles; the rest are ignored`)
+    entries = entries.slice(0, PROFILES_MAX)
+  }
+  for (const [name, value] of entries) {
+    if (!token(name, NAME_MAX)) {
+      problems.push(`openshell.profiles: ${show(name)} is not a profile name (lowercase letters, digits, . _ -; at most ${NAME_MAX})`)
+      continue
+    }
+    if (!isObject(value)) {
+      problems.push(`openshell.profiles.${name} must be an object`)
+      continue
+    }
+    const asked = UNSUPPORTED_FIELDS.filter((field) => value[field] !== undefined)
+    if (asked.length > 0) {
+      const reason = `profile ${name} sets ${asked.join(", ")}, which the OpenShell vm backend does not support`
+      unsupported[name] = reason
+      delete profiles[name]
+      problems.push(`openshell.profiles.${name}: unsupported (${reason})`)
+      continue
+    }
+    profiles[name] = normalizeProfile(name, value, problems)
+  }
+  return { profiles, unsupported, problems }
+}
+
+/** The profile a launch asked for (or the default); ProfileError when it is unknown or unsupported here. */
+export function selectProfile(set: OpenShellProfiles, name: string | undefined): OpenShellProfile {
+  const wanted = name ?? DEFAULT_PROFILE
+  const reason = set.unsupported[wanted]
+  if (reason !== undefined) throw new ProfileError("unsupported", reason)
+  const profile = set.profiles[wanted]
+  if (!profile) throw new ProfileError("not_found", `this node has no OpenShell profile ${wanted}`)
+  return profile
+}
+
+/** Usable profile names, sorted: what the node's hello reports for the openshell runtime. */
+export function profileNames(set: OpenShellProfiles): string[] {
+  return Object.keys(set.profiles).sort()
+}