@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/org/cli.ts

@@ -0,0 +1,438 @@
+// `brain org ...`: log in to an organisation's brain server, see who you are, move your own memories between scopes, and (for admins)
+// run and manage the server. Plain output; errors say what to do next. A token is printed only right after it is created.
+import { existsSync, readFileSync, realpathSync } from "node:fs"
+import { randomUUID } from "node:crypto"
+import { resolve as resolvePath } from "node:path"
+import { gitInfo } from "../fsutil.ts"
+import { projectKey } from "../memory/project.ts"
+import type { ProjectKey } from "../memory/types.ts"
+import { OrgClient, OrgHttpError, checkServerUrl, isLoopbackHost } from "./client.ts"
+import { openInBrowser, ssoLoginFlow } from "./oidc.ts"
+import { adminOps, keyForNewDatabase } from "./admin-ops.ts"
+import { dbState, resolveKey } from "./crypto.ts"
+import { clearOrgConfig, orgConfigPath, readOrgConfig, writeOrgConfig } from "./config.ts"
+import { SCOPES, type OrgConfig, type Role, type Scope } from "./types.ts"
+
+const USAGE = `usage: brain org <command>
+  login --server <url> --token <t> [--ca <pem of a private certificate authority>] [--default-scope private|project|team|org]   (or BRAIN_ORG_TOKEN=<t>)   | logout | whoami | status
+  promote (--ids a,b | --source <session id>) --to project|team|org [--team id] [--project p]
+  demote  (--ids a,b | --source <session id>) --to private|project|team [--team id] [--project p]
+  forget (--mine | --ids a,b) [--source id] [--project p]
+  admin init --db <path> --org-id <id> --org-name <name> --admin-id <id> --admin-name <name> [--encrypt [--key-file <path>]]
+  admin serve --db <path> [--port 4500 (or $PORT)] [--host 127.0.0.1] [--allow-remote] [--trust-proxy] [--key-file <path>] [--tls-cert <pem> --tls-key <pem>]   (key: BRAIN_ORG_KEY or --key-file)
+  admin encrypt --db <path> [--key-file <path>] [--remove-backup]   |   admin rekey --db <path> --key-file <current> --new-key-file <new>
+  admin backup --db <path> --out <file> [--key-file <path>]   |   admin restore --from <backup> --db <path> [--key-file <path>] [--force]
+  admin user add --id <id> --name <name> [--role viewer|editor|admin] [--teams a,b] | list | disable <id>
+  admin token create --user <id> [--expires-days n] | list | revoke <id>
+  admin team add --id <id> --name <name> --members a,b
+  admin project members --project <id> [--add users] [--add-teams t] [--remove users] [--remove-teams t]
+  admin policy get | set --file policy.json
+  login --server <url> --sso [--no-open]      sign in through the organisation's identity provider (browser)
+  admin sso set --issuer <url> --client-id <id> [--client-secret-env VAR] --domains a.com,b.com --default-role viewer|editor|admin|none
+               [--role-claim groups --role-map "eng=editor,platform=admin"] [--token-days 30] [--token-auth basic|post] | get | disable
+  admin audit [--since <iso date>] [--limit n]   |   admin retention`
+
+const BOOLEAN = new Set(["mine", "allow-remote", "trust-proxy", "sso", "no-open", "encrypt", "remove-backup", "force"])
+
+interface Parsed {
+  flags: Record<string, string>
+  bools: Set<string>
+  pos: string[]
+}
+
+function parse(args: string[]): Parsed {
+  const flags: Record<string, string> = {}
+  const bools = new Set<string>()
+  const pos: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (!a.startsWith("--")) pos.push(a)
+    else if (BOOLEAN.has(a.slice(2))) bools.add(a.slice(2))
+    else if (i + 1 < args.length) flags[a.slice(2)] = args[++i]!
+    else flags[a.slice(2)] = ""
+  }
+  return { flags, bools, pos }
+}
+
+const list = (s: string | undefined): string[] => (s ?? "").split(",").map((x) => x.trim()).filter(Boolean)
+
+export interface OrgIo {
+  out(line: string): void
+  /** For tests: replaces the server functions (otherwise loaded from src/org/db.ts, auth.ts, server.ts). */
+  deps?: {
+    initOrg?: (dbPath: string, org: { id: string; name: string }, admin: { id: string; name: string }, opts?: { key?: string }) => { token: string }
+    startOrgServer?: (o: { dbPath: string; port?: number; host?: string; trustProxy?: boolean; key?: string; tlsCertFile?: string; tlsKeyFile?: string }) => Promise<{ url: string; port: number; stop(): Promise<void> }>
+    /** For tests: replaces the browser launch of `login --sso`. */
+    openBrowser?: (url: string) => void
+  }
+  /** For tests: `admin serve` returns (after stopping the server) when this resolves, instead of waiting for Ctrl-C. */
+  stopWhen?: Promise<void>
+}
+
+async function serverFn<T>(name: "initOrg" | "startOrgServer"): Promise<T> {
+  for (const f of ["./db.ts", "./auth.ts", "./server.ts"]) {
+    try {
+      const mod = (await import(f)) as Record<string, unknown>
+      if (typeof mod[name] === "function") return mod[name] as T
+    } catch {}
+  }
+  throw new Error(`the organisation server code (${name}) is not available in this build`)
+}
+
+function hint(e: OrgHttpError): string {
+  if (e.status === 401) return "your token was rejected (wrong, revoked, expired or the user is disabled): ask an admin for a new one and run `brain org login`"
+  if (e.status === 403) return "your role does not allow this"
+  if (e.status === 429) return "too many requests: wait a minute and try again"
+  if (e.code === "unreachable" || e.code === "timeout") return "check the server address (`brain org status`) and your network"
+  if (e.code === "insecure_transport") return ""
+  return ""
+}
+
+function currentProject(): ProjectKey {
+  const cwd = (() => {
+    try {
+      return realpathSync(process.cwd())
+    } catch {
+      return process.cwd()
+    }
+  })()
+  return projectKey({ cwd, ...gitInfo(cwd) })
+}
+
+export async function orgCommand(args: string[], home: string, io: OrgIo = { out: console.log }): Promise<number> {
+  const out = io.out
+  const [sub, ...rest] = args
+  const p = parse(rest)
+  const fail = (msg: string, code = 1): number => (out(msg), code)
+
+  try {
+    if (!sub || sub === "help" || sub === "--help") return fail(USAGE, sub ? 0 : 2)
+
+    if (sub === "login") {
+      const server = p.flags.server
+      if (p.bools.has("sso")) {
+        if (!server) return fail("usage: brain org login --server <url> --sso [--no-open] [--default-scope private|project|team|org]", 2)
+        const ds = p.flags["default-scope"]
+        if (ds !== undefined && !(SCOPES as string[]).includes(ds)) return fail(`--default-scope must be one of ${SCOPES.join(", ")}`, 2)
+        const base = checkServerUrl(server)
+        const probe = { server: base, token: randomUUID(), ...(p.flags.ca ? { ca: resolvePath(p.flags.ca) } : {}) } as OrgConfig // never sent: the sign-in calls carry no token
+        const anon = new OrgClient(probe)
+        const got = await ssoLoginFlow({ config: () => anon.ssoConfig(), exchange: (r) => anon.ssoExchange(r), open: p.bools.has("no-open") ? undefined : (io.deps?.openBrowser ?? openInBrowser), print: out })
+        const cfg: OrgConfig = { server: base, token: got.token, ...(p.flags.ca ? { ca: resolvePath(p.flags.ca) } : {}), ...(ds ? { defaultScope: ds as Scope } : {}) }
+        const who = await new OrgClient(cfg).whoami()
+        writeOrgConfig(home, cfg)
+        out(`logged in to ${cfg.server} with single sign-on`)
+        out(`organisation: ${who.org.name} (${who.org.id})`)
+        out(`you are ${who.user.id} (${who.user.name}), role ${who.user.role}${who.user.teams.length ? `, teams ${who.user.teams.join(", ")}` : ""}`)
+        out(`this sign-in is valid until ${got.expiresAt}; run \`brain org login --sso\` again then`)
+        out(`saved to ${orgConfigPath(home)} (readable only by you)`)
+        return 0
+      }
+      const token = p.flags.token ?? process.env.BRAIN_ORG_TOKEN
+      if (!server || !token) return fail("usage: brain org login --server <url> --token <token> [--default-scope private|project|team|org]\n(or pass the token in BRAIN_ORG_TOKEN to keep it out of your shell history)", 2)
+      const ds = p.flags["default-scope"]
+      if (ds !== undefined && !(SCOPES as string[]).includes(ds)) return fail(`--default-scope must be one of ${SCOPES.join(", ")}`, 2)
+      const cfg: OrgConfig = { server: checkServerUrl(server), token, ...(p.flags.ca ? { ca: resolvePath(p.flags.ca) } : {}), ...(ds ? { defaultScope: ds as Scope } : {}) }
+      const who = await new OrgClient(cfg).whoami()
+      writeOrgConfig(home, cfg)
+      out(`logged in to ${cfg.server}`)
+      out(`organisation: ${who.org.name} (${who.org.id})`)
+      out(`you are ${who.user.id} (${who.user.name}), role ${who.user.role}${who.user.teams.length ? `, teams ${who.user.teams.join(", ")}` : ""}`)
+      out(`new memories default to scope ${cfg.defaultScope ?? who.policy.defaultScope}; nothing is shared wider unless you promote it`)
+      out(`saved to ${orgConfigPath(home)} (readable only by you)`)
+      return 0
+    }
+
+    if (sub === "logout") {
+      out(clearOrgConfig(home) ? "logged out: this machine uses its local memory again (the token is still valid on the server; ask an admin to revoke it if the machine is lost)" : "not logged in")
+      return 0
+    }
+
+    if (sub === "admin") {
+      const local = await orgAdminLocal(args, io)
+      if (local !== undefined) return local
+    }
+    const cfg = readOrgConfig(home)
+    if (sub === "status" && !cfg) return out("organisation: not configured (memory is local to this machine). Join one with `brain org login`."), 0
+    if (!cfg) return fail("not logged in: run `brain org login --server <url> --token <token>` first", 1)
+    const client = new OrgClient(cfg)
+
+    if (sub === "whoami" || sub === "status") {
+      const who = await client.whoami()
+      out(`server: ${cfg.server}`)
+      out(`organisation: ${who.org.name} (${who.org.id})`)
+      out(`user: ${who.user.id} (${who.user.name}), role ${who.user.role}${who.user.teams.length ? `, teams ${who.user.teams.join(", ")}` : ""}`)
+      const pol = who.policy
+      out(`policy: widest scope ${pol.maxScope}, default scope ${cfg.defaultScope ?? pol.defaultScope}${pol.retentionDays ? `, kept ${pol.retentionDays} days` : ""}${pol.allowedKinds ? `, kinds ${pol.allowedKinds.join("/")}` : ""}, ${pol.denyPaths.length} denied paths, ${pol.denyTerms.length} denied terms`)
+      if (sub === "status") {
+        const projects = await client.projects()
+        out(`you can see ${projects.reduce((n, x) => n + x.items, 0)} items in ${projects.length} projects`)
+        for (const x of projects) out(`  ${x.label}  ${x.items} items  (${x.id})`)
+      }
+      return 0
+    }
+
+    if (sub === "promote" || sub === "demote") {
+      const to = p.flags.to
+      const allowed = sub === "promote" ? ["project", "team", "org"] : ["private", "project", "team"]
+      if (!to || !allowed.includes(to) || (!p.flags.ids && !p.flags.source)) return fail(`usage: brain org ${sub} (--ids a,b | --source <session id>) --to ${allowed.join("|")} [--team id] [--project p]`, 2)
+      if (to === "team" && !p.flags.team) return fail("scope team needs --team <team id>", 2)
+      const project = p.flags.project ? { id: p.flags.project, label: p.flags.project } : currentProject()
+      const ids = list(p.flags.ids)
+      const req = ids.length ? { ids } : { source: p.flags.source!, project }
+      const changed = await client.promote({ ...req, to: to as Scope, ...(p.flags.team ? { team: p.flags.team } : {}) })
+      out(`${sub === "promote" ? "promoted" : "demoted"} ${changed} items${ids.length ? "" : ` from ${p.flags.source} in ${project.label}`} to ${to}${p.flags.team ? ` (team ${p.flags.team})` : ""}`)
+      return 0
+    }
+    if (sub === "forget") {
+      if (!p.bools.has("mine") && !p.flags.ids) return fail("usage: brain org forget (--mine | --ids a,b) [--source id] [--project p]\n--mine removes your own memories (of the current project, or --project); --ids removes those items (admins: any item)", 2)
+      const project = p.flags.project ? { id: p.flags.project, label: p.flags.project } : p.flags.ids ? undefined : currentProject()
+      const removed = await client.forget({ ...(project ? { project } : {}), ...(p.flags.source ? { source: p.flags.source } : {}), ...(p.flags.ids ? { ids: list(p.flags.ids) } : {}), mine: p.bools.has("mine") })
+      out(`forgot ${removed} items`)
+      return 0
+    }
+
+    if (sub === "admin") return await admin(rest, home, io, cfg, client)
+
+    return fail(USAGE, 2)
+  } catch (e) {
+    if (e instanceof OrgHttpError) {
+      out(`error: ${e.message}${e.code && e.status ? ` (${e.code})` : ""}`)
+      const h = hint(e)
+      if (h) out(h)
+      return 1
+    }
+    out(`error: ${(e as Error).message}`)
+    return 1
+  }
+}
+
+async function admin(args: string[], home: string, io: OrgIo, cfg: OrgConfig, client: OrgClient): Promise<number> {
+  const out = io.out
+  const [what, verb, ...rest] = args
+  const p = parse(rest)
+  const id = (): string | undefined => p.flags.id ?? p.pos[0]
+  const usage = (s: string): number => (out(`usage: brain org admin ${s}`), 2)
+
+  if (what === "user") {
+    if (verb === "add") {
+      const role = (p.flags.role ?? "editor") as Role
+      if (!p.flags.id || !p.flags.name) return usage("user add --id <id> --name <name> [--role viewer|editor|admin] [--teams a,b]")
+      if (!["viewer", "editor", "admin"].includes(role)) return usage("user add: --role must be viewer, editor or admin")
+      const u = await client.addUser({ id: p.flags.id, name: p.flags.name, role, ...(p.flags.teams ? { teams: list(p.flags.teams) } : {}) })
+      out(`added ${u.id} (${u.name}) as ${u.role}; create a token with: brain org admin token create --user ${u.id}`)
+      return 0
+    }
+    if (verb === "list") {
+      const users = await client.listUsers()
+      out(`${users.length} users`)
+      for (const u of users) out(`  ${u.id}  ${u.name}  ${u.role}${u.teams.length ? `  teams ${u.teams.join(",")}` : ""}${u.disabled ? "  DISABLED" : ""}`)
+      return 0
+    }
+    if (verb === "disable") {
+      if (!id()) return usage("user disable <id>")
+      await client.disableUser(id()!)
+      out(`disabled ${id()}: every token of that user is rejected from now on`)
+      return 0
+    }
+    return usage("user add|list|disable")
+  }
+
+  if (what === "token") {
+    if (verb === "create") {
+      const user = p.flags.user ?? p.pos[0]
+      if (!user) return usage("token create --user <id> [--expires-days n]")
+      const days = p.flags["expires-days"] ? Number(p.flags["expires-days"]) : undefined
+      if (days !== undefined && !(Number.isInteger(days) && days > 0)) return usage("token create: --expires-days must be a whole number above 0")
+      const t = await client.createToken(user, days)
+      out(`token ${t.id} for ${user}${days ? ` (expires in ${days} days)` : " (does not expire)"}:`)
+      out(t.token)
+      out("This is the ONLY time the token is shown: the server keeps just a hash. Give it to the user over a private channel; they run `brain org login --server <url> --token <it>`.")
+      return 0
+    }
+    if (verb === "list") {
+      const toks = await client.listTokens()
+      out(`${toks.length} tokens`)
+      for (const t of toks) out(`  ${Object.entries(t).map(([k, v]) => `${k}=${v === null || v === undefined || v === "" ? "-" : String(v)}`).join("  ")}`)
+      return 0
+    }
+    if (verb === "revoke") {
+      if (!id()) return usage("token revoke <id>")
+      await client.revokeToken(id()!)
+      out(`revoked ${id()}: it is rejected from now on`)
+      return 0
+    }
+    return usage("token create|list|revoke")
+  }
+
+  if (what === "team" && verb === "add") {
+    if (!p.flags.id || !p.flags.name) return usage("team add --id <id> --name <name> --members a,b")
+    await client.addTeam({ id: p.flags.id, name: p.flags.name, members: list(p.flags.members) })
+    out(`team ${p.flags.id} saved with ${list(p.flags.members).length} members`)
+    return 0
+  }
+
+  if (what === "project" && verb === "members") {
+    const q = p
+    const project = q.flags.project ?? q.pos[0]
+    const grp = (users?: string, teams?: string) => (users || teams ? { ...(users ? { users: list(users) } : {}), ...(teams ? { teams: list(teams) } : {}) } : undefined)
+    const add = grp(q.flags.add ?? q.flags["add-users"], q.flags["add-teams"])
+    const remove = grp(q.flags.remove ?? q.flags["remove-users"], q.flags["remove-teams"])
+    if (!project || (!add && !remove)) return usage("project members --project <id> [--add users | --add-users u1,u2 | --add-teams t1] [--remove ... likewise]")
+    await client.projectMembers(project, { ...(add ? { add } : {}), ...(remove ? { remove } : {}) })
+    const show = (g?: { users?: string[]; teams?: string[] }) => [...(g?.users ?? []), ...(g?.teams ?? []).map((t) => `team ${t}`)].join(", ")
+    out(`updated members of ${project}${add ? `; added ${show(add)}` : ""}${remove ? `; removed ${show(remove)}` : ""}`)
+    return 0
+  }
+
+  if (what === "policy") {
+    if (verb === "get") {
+      out(JSON.stringify(await client.getPolicy(), null, 2))
+      return 0
+    }
+    if (verb === "set") {
+      if (!p.flags.file) return usage("policy set --file policy.json")
+      const file = resolvePath(p.flags.file)
+      if (!existsSync(file)) return (out(`no such file: ${file}`), 1)
+      let raw: unknown
+      try {
+        raw = JSON.parse(readFileSync(file, "utf8"))
+      } catch (e) {
+        return (out(`${file} is not valid JSON: ${(e as Error).message}`), 1)
+      }
+      try {
+        const mod = (await import("./policy.ts")) as { normalizePolicy?: (r: unknown) => unknown }
+        raw = mod.normalizePolicy ? mod.normalizePolicy(raw) : raw
+      } catch (e) {
+        if (!/Cannot find module|not found/i.test((e as Error).message)) return (out(`policy rejected: ${(e as Error).message}`), 1)
+      }
+      await client.setPolicy(raw)
+      out("policy saved; it applies from the next request of every user")
+      return 0
+    }
+    return usage("policy get | set --file policy.json")
+  }
+
+  if (what === "sso") {
+    if (verb === "get") {
+      const c = await client.getSso()
+      if (!c.configured) return (out("single sign-on is not configured; set it up with `brain org admin sso set --issuer ... --client-id ... --domains a.com`"), 0)
+      out(JSON.stringify(c, null, 2))
+      return 0
+    }
+    if (verb === "disable") {
+      const c = await client.getSso()
+      if (!c.configured) return (out("single sign-on is not configured"), 0)
+      await client.setSso({ ...c, configured: undefined, clientSecretSet: undefined, enabled: false })
+      out("single sign-on disabled: no new sign-ins; tokens already issued keep working until they expire (revoke them with `admin token revoke`)")
+      return 0
+    }
+    if (verb === "set") {
+      const f = p.flags
+      const bad = (m: string): number => (out(`admin sso set: ${m}`), 2)
+      if (!f.issuer || !f["client-id"] || !f.domains) return usage("sso set --issuer <url> --client-id <id> [--client-secret-env VAR] --domains a.com,b.com --default-role viewer|editor|admin|none [--role-claim groups --role-map \"eng=editor,platform=admin\"] [--token-days 30] [--scopes \"openid email profile\"]")
+      const body: Record<string, unknown> = { issuer: f.issuer, clientId: f["client-id"], allowedDomains: list(f.domains), defaultRole: f["default-role"] ?? "viewer" }
+      if (f["client-secret-env"]) {
+        const v = process.env[f["client-secret-env"]]
+        if (!v) return bad(`the environment variable ${f["client-secret-env"]} is empty or not set (the secret is read from the environment so it stays out of your shell history)`)
+        body.clientSecret = v
+      }
+      if (f["role-claim"] || f["role-map"]) {
+        if (!f["role-claim"] || !f["role-map"]) return bad("--role-claim and --role-map go together")
+        const map: Record<string, string> = {}
+        for (const pair of list(f["role-map"])) {
+          const i = pair.lastIndexOf("=")
+          if (i < 1) return bad(`--role-map entries look like group=role, got "${pair}"`)
+          map[pair.slice(0, i)] = pair.slice(i + 1)
+        }
+        body.roleMap = { claim: f["role-claim"], map }
+      }
+      if (f["token-days"]) body.tokenDays = Number(f["token-days"])
+      if (f["token-auth"]) {
+        const m = f["token-auth"] === "basic" ? "client_secret_basic" : f["token-auth"] === "post" ? "client_secret_post" : undefined
+        if (!m) return bad("--token-auth must be basic (the OAuth default) or post")
+        body.tokenAuth = m
+      }
+      if (f.scopes) body.scopes = f.scopes
+      const r = await client.setSso(body)
+      out(`single sign-on ${r.enabled ? "enabled" : "saved (disabled)"} for ${String(r.issuer)}; people sign in with: brain org login --server <url> --sso`)
+      return 0
+    }
+    return usage("sso set|get|disable")
+  }
+
+  if (what === "audit") {
+    const q = parse(args.slice(1))
+    const limit = q.flags.limit ? Number(q.flags.limit) : 100
+    const events = await client.audit({ ...(q.flags.since ? { since: q.flags.since } : {}), limit })
+    out(`${events.length} events`)
+    for (const e of events) out(`${e.at}  ${e.actor}  ${e.action}${e.project ? `  ${e.project}` : ""}${e.scope ? `  ${e.scope}` : ""}${e.count !== undefined ? `  x${e.count}` : ""}${e.detail ? `  ${e.detail}` : ""}`)
+    return 0
+  }
+
+  if (what === "retention") {
+    const r = await client.runRetention()
+    out(`retention run done${r && typeof r === "object" ? `: ${JSON.stringify(r)}` : ""}`)
+    return 0
+  }
+
+  // init and serve are local: they need no login (the server and its database are on this machine).
+  return usage("user|token|team|project|policy|audit|retention ...")
+}
+
+/** `brain org admin init|serve`: run on the server's machine, no login needed. Called by orgCommand before it asks for a login. */
+export async function orgAdminLocal(args: string[], io: OrgIo): Promise<number | undefined> {
+  const [admin, verb, ...rest] = args
+  if (admin !== "admin" || !verb || !["init", "serve", "encrypt", "rekey", "backup", "restore"].includes(verb)) return undefined
+  const out = io.out
+  const p = parse(rest)
+  if (verb === "encrypt" || verb === "rekey" || verb === "backup" || verb === "restore") return await adminOps(verb, p, out)
+  if (verb === "init") {
+    const f = p.flags
+    if (!f.db || !f["org-id"] || !f["org-name"] || !f["admin-id"] || !f["admin-name"]) return (out("usage: brain org admin init --db <path> --org-id <id> --org-name <name> --admin-id <id> --admin-name <name>"), 2)
+    const db = resolvePath(f.db)
+    if (existsSync(db)) return (out(`${db} already exists; refusing to overwrite an organisation database. Pick a new --db path, or delete it if you really want a fresh start.`), 1)
+    try {
+      const initOrg = io.deps?.initOrg ?? (await serverFn<NonNullable<NonNullable<OrgIo["deps"]>["initOrg"]>>("initOrg"))
+      const key = p.bools.has("encrypt") ? keyForNewDatabase(db, f["key-file"], out) : undefined // says where the key file is, never the key
+      const { token } = key ? initOrg(db, { id: f["org-id"], name: f["org-name"] }, { id: f["admin-id"], name: f["admin-name"] }, { key }) : initOrg(db, { id: f["org-id"], name: f["org-name"] }, { id: f["admin-id"], name: f["admin-name"] })
+      out(`organisation ${f["org-name"]} created in ${db}${key ? " (encrypted at rest)" : ""}; first admin: ${f["admin-id"]}`)
+      out("admin token (shown ONCE, the database keeps only a hash; store it in a password manager):")
+      out(token)
+      // An encrypted database needs its key file again to start: say so (the path is the one printed above, not the key).
+      const keyHint = key ? ` --key-file ${resolvePath(f["key-file"] ?? `${db}.key`)}` : ""
+      out(`next: brain org admin serve --db ${db}${keyHint}   then   brain org login --server http://127.0.0.1:4500 --token <the token above>`)
+      return 0
+    } catch (e) {
+      return (out(`error: ${(e as Error).message}`), 1)
+    }
+  }
+  // serve
+  if (!p.flags.db) return (out("usage: brain org admin serve --db <path> [--port 4500 (or $PORT)] [--host 127.0.0.1] [--allow-remote] [--trust-proxy]"), 2)
+  const host = p.flags.host ?? "127.0.0.1"
+  // A cloud host tells the process its port in $PORT.
+  const port = p.flags.port !== undefined ? Number(p.flags.port) : process.env.PORT ? Number(process.env.PORT) : 4500
+  if (!Number.isInteger(port) || port < 0 || port > 65535) return (out("--port must be a number from 0 to 65535"), 2)
+  const tlsCert = p.flags["tls-cert"]
+  const tlsKey = p.flags["tls-key"]
+  if (!tlsCert !== !tlsKey) return (out("TLS needs both --tls-cert <pem> and --tls-key <pem>"), 2)
+  if (!isLoopbackHost(host) && !p.bools.has("allow-remote")) return (out(tlsCert ? `refusing to listen on ${host} without --allow-remote (you asked for a non-loopback address: pass --allow-remote to confirm).` : `refusing to listen on ${host}: the server speaks plain HTTP and tokens would cross the network in clear text.\nUse --tls-cert/--tls-key so the server terminates TLS itself, or keep the default 127.0.0.1 and put a TLS-terminating proxy (nginx, Caddy, a cloud load balancer) in front, or pass --allow-remote if you already are behind one.`), 1)
+  const db = resolvePath(p.flags.db)
+  if (!existsSync(db)) return (out(`no database at ${db}; create it with: brain org admin init --db ${db} ...`), 1)
+  try {
+    const start = io.deps?.startOrgServer ?? (await serverFn<NonNullable<NonNullable<OrgIo["deps"]>["startOrgServer"]>>("startOrgServer"))
+    // the key comes from --key-file or BRAIN_ORG_KEY (never a command-line value); an unusable one is an error here, not a silent plain start
+    const k = resolveKey({ keyFile: p.flags["key-file"] ? resolvePath(p.flags["key-file"]) : undefined })
+    if (k.warning) out(`warning: ${k.warning}`)
+    if (!k.key && dbState(db) === "plain") out(`warning: the database is not encrypted at rest: anyone who can read ${db} can read every item. Convert it with: brain org admin encrypt --db ${db}`)
+    const srv = await start({ dbPath: db, port, host, ...(p.bools.has("trust-proxy") ? { trustProxy: true } : {}), ...(k.key ? { key: k.key } : {}), ...(tlsCert && tlsKey ? { tlsCertFile: resolvePath(tlsCert), tlsKeyFile: resolvePath(tlsKey) } : {}) })
+    out(`brain org server listening on ${srv.url} (database ${db}${k.key ? ", encrypted" : ""}); Ctrl-C to stop`)
+    if (!isLoopbackHost(host) && !tlsCert) out("warning: not loopback and plain HTTP: make sure TLS is terminated in front of this port")
+    await (io.stopWhen ?? new Promise<void>((res) => { process.once("SIGINT", () => res()); process.once("SIGTERM", () => res()) }))
+    await srv.stop()
+    out("stopped")
+    return 0
+  } catch (e) {
+    return (out(`error: ${(e as Error).message}`), 1)
+  }
+}