@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/org/client.ts

@@ -0,0 +1,404 @@
+// The organisation client: a fetch-based HTTP client for the brain org server (`OrgClient`), and `openRemoteMemory`, which makes the
+// server look like the local `Memory` so the rest of the brain (prepare, sync, the MCP server) needs no changes.
+//
+// Trust model of this file: the server is trusted with the distilled items it is sent, and NOT trusted to be well-formed (a hostile or
+// old server must not crash the client: every response is validated). The client-side policy check is a courtesy that keeps denied
+// items on the machine; the server re-checks everything. The bearer token is only ever put in the Authorization header: never in a
+// URL, an error message, a log line or a redirect (redirects are refused, so the header cannot be forwarded to another host).
+// Nothing is queued on disk when the server is down: items either reach the server or stay in the local session files they came from.
+import { readFileSync } from "node:fs"
+import type { BrainMemory, MemoryCounts } from "../memory/store.ts"
+import type { MemoryItem, MemoryKind, MemoryStatus, ProjectKey, Recalled } from "../memory/types.ts"
+import { SCOPES, scopeRank, type AuditEvent, type ForgetRequest, type IngestResponse, type OrgConfig, type OrgRecalled, type OrgUser, type Policy, type ProjectsResponse, type Role, type Scope, type WhoAmI } from "./types.ts"
+
+export class OrgHttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+    this.name = "OrgHttpError"
+  }
+}
+
+const KINDS: MemoryKind[] = ["decision", "constraint", "preference", "failed", "file", "command", "summary", "state"]
+const ROLES: Role[] = ["viewer", "editor", "admin"]
+const MAX_RESPONSE_CHARS = 8_000_000
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isStr = (v: unknown): v is string => typeof v === "string"
+const isScope = (v: unknown): v is Scope => isStr(v) && (SCOPES as string[]).includes(v)
+const bad = (what: string): never => {
+  throw new OrgHttpError(502, "bad_response", `the server sent an unexpected ${what}; is it a brain org server of the same version?`)
+}
+
+// ---- response validators --------------------------------------------------------------------------------------------
+
+function parsePolicy(v: unknown): Policy {
+  if (!isObj(v) || !isScope(v.maxScope) || !isScope(v.defaultScope) || !Array.isArray(v.denyPaths) || !Array.isArray(v.denyTerms)) return bad("policy")
+  const p: Policy = { maxScope: v.maxScope as Scope, defaultScope: v.defaultScope as Scope, denyPaths: (v.denyPaths as unknown[]).filter(isStr), denyTerms: (v.denyTerms as unknown[]).filter(isStr) }
+  if (Array.isArray(v.allowedKinds)) p.allowedKinds = (v.allowedKinds as unknown[]).filter((k): k is MemoryKind => KINDS.includes(k as MemoryKind))
+  if (typeof v.retentionDays === "number" && Number.isFinite(v.retentionDays) && v.retentionDays > 0) p.retentionDays = v.retentionDays
+  return p
+}
+
+function parseUser(v: unknown): OrgUser {
+  if (!isObj(v) || !isStr(v.id) || !isStr(v.name) || !ROLES.includes(v.role as Role)) return bad("user")
+  return { id: v.id as string, name: v.name as string, role: v.role as Role, teams: Array.isArray(v.teams) ? (v.teams as unknown[]).filter(isStr) : [], ...(v.disabled === true ? { disabled: true } : {}) }
+}
+
+export function parseWhoAmI(v: unknown): WhoAmI {
+  if (!isObj(v) || !isObj(v.org) || !isStr(v.org.id) || !isStr(v.org.name)) return bad("whoami answer")
+  return { user: parseUser(v.user), org: { id: v.org.id as string, name: v.org.name as string }, policy: parsePolicy(v.policy), api: 1 }
+}
+
+function parseRecalled(v: unknown): OrgRecalled {
+  if (!isObj(v) || !isStr(v.text) || !isScope(v.scope) || !isStr(v.owner)) return bad("recalled item")
+  const out: OrgRecalled = { text: v.text as string, score: typeof v.score === "number" && Number.isFinite(v.score) ? v.score : 0, scope: v.scope as Scope, owner: v.owner as string }
+  if (KINDS.includes(v.kind as MemoryKind)) out.kind = v.kind as MemoryKind
+  if (isStr(v.name)) out.name = v.name
+  if (isStr(v.source)) out.source = v.source
+  if (isStr(v.id)) out.id = v.id
+  if (isStr(v.project)) out.project = v.project
+  if (isStr(v.team)) out.team = v.team
+  return out
+}
+
+const count = (v: unknown, what: string): number => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : (bad(what) as never))
+
+function parseIngest(v: unknown): IngestResponse {
+  if (!isObj(v) || !isScope(v.scope)) return bad("ingest answer")
+  const dropped = Array.isArray(v.dropped) ? (v.dropped as unknown[]).filter(isObj).map((d) => ({ id: String(d.id ?? ""), reason: String(d.reason ?? "") })) : []
+  return { stored: count(v.stored, "ingest answer"), dropped, scope: v.scope as Scope }
+}
+
+function parseProjects(v: unknown): ProjectsResponse {
+  if (!isObj(v) || !Array.isArray(v.projects)) return bad("projects answer")
+  return { projects: (v.projects as unknown[]).filter(isObj).filter((p) => isStr(p.id)).map((p) => ({ id: p.id as string, label: isStr(p.label) ? p.label : (p.id as string), items: typeof p.items === "number" ? p.items : 0 })) }
+}
+
+/** Admin answers: the server sends a bare array; the wrapped form ({users: [...]}) is tolerated too, anything else is a bad response. */
+const listOf = (v: unknown, key: string): unknown[] => (Array.isArray(v) ? v : isObj(v) && Array.isArray(v[key]) ? (v[key] as unknown[]) : (bad(`${key} list`) as never))
+
+// ---- transport check ------------------------------------------------------------------------------------------------
+
+export function isLoopbackHost(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase()
+  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h)
+}
+
+/** Parses the server URL and refuses plain http to anything but loopback (unless BRAIN_ORG_INSECURE=1). Returns the base URL, no trailing slash. */
+export function checkServerUrl(server: string, env = process.env): string {
+  let u: URL
+  try {
+    u = new URL(server)
+  } catch {
+    throw new OrgHttpError(0, "bad_url", `"${server}" is not a URL; use e.g. https://brain.example.com`)
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") throw new OrgHttpError(0, "bad_url", `unsupported scheme ${u.protocol}; use https://`)
+  if (u.username || u.password) throw new OrgHttpError(0, "bad_url", "put the token in --token, not in the URL")
+  if (u.protocol === "http:" && !isLoopbackHost(u.hostname) && env.BRAIN_ORG_INSECURE !== "1")
+    throw new OrgHttpError(0, "insecure_transport", `refusing http:// to ${u.hostname}: the token would cross the network in clear text. Use https://, or set BRAIN_ORG_INSECURE=1 if you accept that`)
+  return `${u.origin}${u.pathname.replace(/\/+$/, "")}`
+}
+
+/** fetch that trusts the certificate authority in the PEM file `ca` (a private or internal CA) for https servers. The https-only rule and
+ *  the redirect refusal live in OrgClient and are unchanged; this only says whom to trust for the handshake. */
+function fetchTrusting(ca: string): (input: string, init?: RequestInit) => Promise<Response> {
+  let pem: string
+  try {
+    pem = readFileSync(ca, "utf8")
+  } catch {
+    throw new OrgHttpError(0, "bad_ca", `cannot read the certificate authority file ${ca}`)
+  }
+  if (!pem.includes("BEGIN CERTIFICATE")) throw new OrgHttpError(0, "bad_ca", `${ca} does not hold a PEM certificate`)
+  return (input, init) => fetch(input, { ...init, tls: { ca: pem } } as RequestInit)
+}
+
+// ---- the client -----------------------------------------------------------------------------------------------------
+
+export interface OrgClientOptions {
+  /** For tests. */
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>
+  timeoutMs?: number
+}
+
+export class OrgClient {
+  private base: string
+  private token: string
+  private fetchImpl: (input: string, init?: RequestInit) => Promise<Response>
+  private timeoutMs: number
+
+  constructor(cfg: Pick<OrgConfig, "server" | "token"> & { ca?: string }, opts: OrgClientOptions = {}) {
+    this.base = checkServerUrl(cfg.server)
+    this.token = cfg.token
+    this.fetchImpl = opts.fetch ?? (cfg.ca ? fetchTrusting(cfg.ca) : fetch)
+    this.timeoutMs = opts.timeoutMs ?? 10_000
+  }
+
+  /** One request. `idempotent` calls are retried once on a network error (never on an HTTP answer). */
+  private async call(method: string, path: string, body: unknown, idempotent: boolean, auth = true): Promise<unknown> {
+    for (let attempt = 0; ; attempt++) {
+      const ctl = new AbortController()
+      const timer = setTimeout(() => ctl.abort(), this.timeoutMs)
+      let res: Response
+      let text: string
+      try {
+        res = await this.fetchImpl(`${this.base}${path}`, {
+          method,
+          redirect: "error",
+          signal: ctl.signal,
+          headers: { accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}), ...(auth ? { authorization: `Bearer ${this.token}` } : {}) },
+          ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        })
+        text = await res.text()
+      } catch (e) {
+        clearTimeout(timer)
+        if (attempt === 0 && idempotent) continue
+        const timedOut = ctl.signal.aborted
+        throw new OrgHttpError(0, timedOut ? "timeout" : "unreachable", timedOut ? `the server did not answer within ${this.timeoutMs / 1000}s` : `cannot reach the server (${String((e as Error)?.message ?? e).split("\n")[0]!.replaceAll(this.token, "***")})`)
+      }
+      clearTimeout(timer)
+      if (text.length > MAX_RESPONSE_CHARS) throw new OrgHttpError(502, "bad_response", "the server's answer is too large")
+      let json: unknown
+      try {
+        json = text ? JSON.parse(text) : undefined
+      } catch {
+        if (res.ok) return bad("answer (not JSON)")
+      }
+      if (!res.ok) {
+        const code = isObj(json) && isStr(json.code) ? json.code : `http_${res.status}`
+        const msg = isObj(json) && isStr(json.error) ? json.error : `the server answered ${res.status}`
+        throw new OrgHttpError(res.status, code.slice(0, 64), msg.slice(0, 500).replaceAll(this.token, "***"))
+      }
+      return json
+    }
+  }
+
+  health = async (): Promise<boolean> => isObj(await this.call("GET", "/v1/health", undefined, true, false))
+  whoami = async (): Promise<WhoAmI> => parseWhoAmI(await this.call("GET", "/v1/whoami", undefined, true))
+  async ingest(project: ProjectKey, items: MemoryItem[], opts: { scope?: Scope; team?: string } = {}): Promise<IngestResponse> {
+    return parseIngest(await this.call("POST", "/v1/ingest", { project, items, ...(opts.scope ? { scope: opts.scope } : {}), ...(opts.team ? { team: opts.team } : {}) }, true))
+  }
+  async recall(project: ProjectKey, query: string, opts: { limit?: number; maxTokens?: number } = {}): Promise<OrgRecalled[]> {
+    const r = await this.call("POST", "/v1/recall", { project, query, ...(opts.limit ? { limit: opts.limit } : {}), ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}) }, true)
+    return listOf(r, "items").map(parseRecalled)
+  }
+  async promote(req: { ids?: string[]; source?: string; project?: ProjectKey; to: Scope; team?: string }): Promise<number> {
+    const r = await this.call("POST", "/v1/promote", { ...(req.ids ? { ids: req.ids } : {}), ...(req.source ? { source: req.source } : {}), ...(req.project ? { project: req.project } : {}), to: req.to, ...(req.team ? { team: req.team } : {}) }, true)
+    return count(isObj(r) ? r.changed : undefined, "promote answer")
+  }
+  async forget(req: ForgetRequest): Promise<number> {
+    const r = await this.call("POST", "/v1/forget", req, true)
+    return count(isObj(r) ? r.removed : undefined, "forget answer")
+  }
+  async projects(): Promise<ProjectsResponse["projects"]> {
+    return parseProjects(await this.call("GET", "/v1/projects", undefined, true)).projects
+  }
+
+  // ---- admin (role admin; the server enforces it) ----
+  async addUser(u: { id: string; name: string; role: Role; teams?: string[] }): Promise<OrgUser> {
+    return parseUser(await this.call("POST", "/v1/admin/users", u, false))
+  }
+  async listUsers(): Promise<OrgUser[]> {
+    return listOf(await this.call("GET", "/v1/admin/users", undefined, true), "users").map(parseUser)
+  }
+  async disableUser(id: string): Promise<void> {
+    await this.call("POST", "/v1/admin/users/disable", { id }, true)
+  }
+  /** The token is in the answer exactly once: the caller must show it and drop it. */
+  async createToken(user: string, expiresInDays?: number): Promise<{ id: string; token: string }> {
+    const r = await this.call("POST", "/v1/admin/tokens", { user, ...(expiresInDays ? { expiresInDays } : {}) }, false)
+    if (!isObj(r) || !isStr(r.id) || !isStr(r.token)) return bad("token answer")
+    return { id: r.id as string, token: r.token as string }
+  }
+  async listTokens(): Promise<Array<Record<string, unknown>>> {
+    // Whatever the server lists, a field named `token` is dropped here: a listing must never be able to put a secret on screen.
+    return listOf(await this.call("GET", "/v1/admin/tokens", undefined, true), "tokens").filter(isObj).map(({ token: _t, ...rest }) => rest)
+  }
+  async revokeToken(id: string): Promise<void> {
+    await this.call("POST", "/v1/admin/tokens/revoke", { id }, true)
+  }
+  async addTeam(t: { id: string; name: string; members: string[] }): Promise<void> {
+    await this.call("POST", "/v1/admin/teams", t, true)
+  }
+  async projectMembers(project: string, change: { add?: { users?: string[]; teams?: string[] }; remove?: { users?: string[]; teams?: string[] } }): Promise<void> {
+    await this.call("POST", "/v1/admin/projects/members", { project, ...change }, true)
+  }
+  async getPolicy(): Promise<Policy> {
+    return parsePolicy(await this.call("GET", "/v1/admin/policy", undefined, true))
+  }
+  async setPolicy(p: unknown): Promise<void> {
+    await this.call("PUT", "/v1/admin/policy", p, true)
+  }
+  async audit(q: { since?: string; limit?: number } = {}): Promise<AuditEvent[]> {
+    const qs = new URLSearchParams()
+    if (q.since) qs.set("since", q.since)
+    if (q.limit) qs.set("limit", String(q.limit))
+    const r = listOf(await this.call("GET", `/v1/admin/audit${qs.size ? `?${qs}` : ""}`, undefined, true), "events")
+    return r.filter(isObj).map((e) => ({ at: String(e.at ?? ""), actor: String(e.actor ?? "-"), action: String(e.action ?? ""), ...(isStr(e.project) ? { project: e.project } : {}), ...(isScope(e.scope) ? { scope: e.scope } : {}), ...(typeof e.count === "number" ? { count: e.count } : {}), ...(isStr(e.detail) ? { detail: e.detail } : {}) }))
+  }
+  async runRetention(): Promise<unknown> {
+    return this.call("POST", "/v1/admin/retention/run", {}, true)
+  }
+
+  // ---- single sign-on (see sso.ts; the first two need no token) ----
+  async ssoConfig(): Promise<{ enabled: boolean; issuer?: string; authorizationEndpoint?: string; clientId?: string; scopes?: string }> {
+    const r = await this.call("GET", "/v1/auth/sso/config", undefined, true, false)
+    if (!isObj(r) || typeof r.enabled !== "boolean") return bad("sign-in configuration")
+    return { enabled: r.enabled, ...(isStr(r.issuer) ? { issuer: r.issuer } : {}), ...(isStr(r.authorizationEndpoint) ? { authorizationEndpoint: r.authorizationEndpoint } : {}), ...(isStr(r.clientId) ? { clientId: r.clientId } : {}), ...(isStr(r.scopes) ? { scopes: r.scopes } : {}) }
+  }
+  /** Not retried: an authorization code works once. The token in the answer is for the caller to store, never to print. */
+  async ssoExchange(req: { code: string; codeVerifier: string; redirectUri: string; nonce: string }): Promise<{ token: string; user: OrgUser; expiresAt: string }> {
+    const r = await this.call("POST", "/v1/auth/sso/exchange", req, false, false)
+    if (!isObj(r) || !isStr(r.token) || !isStr(r.expiresAt)) return bad("sign-in answer")
+    return { token: r.token as string, user: parseUser(r.user), expiresAt: r.expiresAt as string }
+  }
+  async getSso(): Promise<Record<string, unknown>> {
+    const r = await this.call("GET", "/v1/admin/sso", undefined, true)
+    return isObj(r) ? r : (bad("sso configuration") as never)
+  }
+  async setSso(cfg: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const r = await this.call("PUT", "/v1/admin/sso", cfg, true)
+    return isObj(r) ? r : (bad("sso configuration") as never)
+  }
+}
+
+// ---- remote memory --------------------------------------------------------------------------------------------------
+
+interface PolicyFns {
+  checkItem(item: MemoryItem, policy: Policy): { ok: true } | { ok: false; reason: string }
+  effectiveScope(requested: Scope | undefined, policy: Policy): { ok: true; scope: Scope } | { ok: false; code: string; reason: string }
+}
+
+/** policy.ts is loaded lazily (and by a computed specifier) so this file does not depend on it being present to compile or to load. */
+async function loadPolicy(): Promise<PolicyFns> {
+  const file = "./policy.ts"
+  return (await import(file)) as PolicyFns
+}
+
+export interface RemoteMemoryOptions extends OrgClientOptions {
+  /** For tests: replaces the policy functions. */
+  policy?: PolicyFns
+  now?: () => number
+  /** How long the whoami answer (and the policy in it) is reused. Default 5 minutes. */
+  policyTtlMs?: number
+}
+
+export type RemoteIngestResult = { stored: number; dropped?: Array<{ id: string; reason: string }>; reason?: string }
+
+export function openRemoteMemory(cfg: OrgConfig, opts: RemoteMemoryOptions = {}): Omit<BrainMemory, "ingest"> & { ingest(project: ProjectKey, items: MemoryItem[], o?: { scope?: Scope; team?: string }): Promise<RemoteIngestResult>; client: OrgClient | undefined } {
+  let client: OrgClient | undefined
+  let clientErr: string | undefined
+  try {
+    client = new OrgClient(cfg, opts)
+  } catch (e) {
+    clientErr = (e as Error).message
+  }
+  const now = opts.now ?? Date.now
+  const ttl = opts.policyTtlMs ?? 5 * 60_000
+  let cached: { at: number; who: WhoAmI } | undefined
+  let policyFns: PolicyFns | undefined
+
+  const reasonOf = (e: unknown): string => {
+    if (e instanceof OrgHttpError) return e.status === 401 ? "the organisation server rejected the token (revoked, expired or disabled): run `brain org login` again" : e.message
+    return String((e as Error)?.message ?? e).split("\n")[0]!
+  }
+  const who = async (): Promise<WhoAmI> => {
+    if (!client) throw new Error(clientErr)
+    if (cached && now() - cached.at < ttl) return cached.who
+    const w = await client.whoami()
+    cached = { at: now(), who: w }
+    return w
+  }
+
+  return {
+    client,
+    async status(): Promise<MemoryStatus> {
+      try {
+        const w = await who()
+        const projects = await client!.projects().catch(() => [])
+        return { available: true, store: `${cfg.server} (organisation ${w.org.name}, you are ${w.user.id}, ${w.user.role})`, items: projects.reduce((n, p) => n + p.items, 0) }
+      } catch (e) {
+        cached = undefined
+        return { available: false, why: reasonOf(e) }
+      }
+    },
+
+    async ingest(project, items, o = {}): Promise<RemoteIngestResult> {
+      let w: WhoAmI
+      try {
+        w = await who()
+      } catch (e) {
+        return { stored: 0, reason: reasonOf(e) }
+      }
+      policyFns ??= opts.policy ?? (await loadPolicy().catch(() => undefined))
+      const requested = o.scope ?? cfg.defaultScope
+      let scope: Scope | undefined = requested
+      if (policyFns) {
+        const eff = policyFns.effectiveScope(requested, w.policy)
+        if (!eff.ok) return { stored: 0, reason: eff.reason }
+        scope = eff.scope
+      } else if (requested && scopeRank(requested) > scopeRank(w.policy.maxScope)) return { stored: 0, reason: `scope ${requested} is above the organisation's limit (${w.policy.maxScope})` }
+      // Denied items never leave the machine.
+      const keep: MemoryItem[] = []
+      const dropped: Array<{ id: string; reason: string }> = []
+      for (const item of items) {
+        const r = policyFns ? policyFns.checkItem(item, w.policy) : { ok: true as const }
+        if (r.ok) keep.push(item)
+        else dropped.push({ id: item.id, reason: r.reason })
+      }
+      if (!keep.length) return { stored: 0, dropped }
+      try {
+        const out: IngestResponse = { stored: 0, dropped: [], scope: scope ?? w.policy.defaultScope }
+        for (let i = 0; i < keep.length; i += 200) {
+          const r = await client!.ingest(project, keep.slice(i, i + 200), { ...(scope ? { scope } : {}), ...(o.team ? { team: o.team } : {}) })
+          out.stored += r.stored
+          out.dropped.push(...r.dropped)
+        }
+        return { stored: out.stored, dropped: [...dropped, ...out.dropped] }
+      } catch (e) {
+        if (e instanceof OrgHttpError && e.status === 401) cached = undefined
+        return { stored: 0, dropped, reason: reasonOf(e) }
+      }
+    },
+
+    async recall(project, query, o = {}): Promise<Recalled[]> {
+      if (!client || !query.trim()) return []
+      try {
+        return (await client.recall(project, query, o)).map((r) => ({ text: r.text, ...(r.kind ? { kind: r.kind } : {}), ...(r.name ? { name: r.name } : {}), score: r.score, ...(r.source ? { source: r.source } : {}), scope: r.scope, owner: r.owner }))
+      } catch {
+        return []
+      }
+    },
+
+    async forget(project, o = {}): Promise<number> {
+      if (!client) return 0
+      try {
+        return await client.forget({ project, mine: true, ...(o.source ? { source: o.source } : {}) })
+      } catch {
+        return 0
+      }
+    },
+
+    async counts(project?: ProjectKey): Promise<MemoryCounts> {
+      try {
+        const ps = (await client!.projects()).filter((p) => !project || p.id === project.id)
+        return { total: ps.reduce((n, p) => n + p.items, 0), byKind: {} }
+      } catch {
+        return { total: 0, byKind: {} }
+      }
+    },
+
+    async projects() {
+      try {
+        return await client!.projects()
+      } catch {
+        return []
+      }
+    },
+
+    close() {},
+  }
+}

package/src/org/config.ts

@@ -0,0 +1,44 @@
+// The user-side organisation config: <home>/.brain/org.json (file mode 0600, folder 0700). It holds the server URL and the bearer
+// token, so it is the one file here that must never be world-readable. Absent file = no organisation = the local store, as before.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { SCOPES, type OrgConfig, type Scope } from "./types.ts"
+
+export const orgConfigPath = (home: string): string => join(home, ".brain", "org.json")
+
+/** The config, or undefined when there is none or it is unusable (wrong shape: a hand-edited file must not crash the brain). */
+export function readOrgConfig(home: string): OrgConfig | undefined {
+  const p = orgConfigPath(home)
+  if (!existsSync(p)) return undefined
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>
+    if (typeof raw?.server !== "string" || !raw.server || typeof raw.token !== "string" || !raw.token) return undefined
+    const cfg: OrgConfig = { server: raw.server, token: raw.token }
+    if (typeof raw.defaultScope === "string" && (SCOPES as string[]).includes(raw.defaultScope)) cfg.defaultScope = raw.defaultScope as Scope
+    if (typeof raw.ca === "string" && raw.ca) cfg.ca = raw.ca
+    return cfg
+  } catch {
+    return undefined
+  }
+}
+
+/** Writes the config atomically with mode 0600 (the temp file is created 0600 too, so the token is never readable by others). */
+export function writeOrgConfig(home: string, cfg: OrgConfig): void {
+  const p = orgConfigPath(home)
+  mkdirSync(dirname(p), { recursive: true, mode: 0o700 })
+  try {
+    chmodSync(dirname(p), 0o700)
+  } catch {}
+  const tmp = `${p}.${process.pid}.tmp`
+  writeFileSync(tmp, `${JSON.stringify({ server: cfg.server, token: cfg.token, ...(cfg.ca ? { ca: cfg.ca } : {}), ...(cfg.defaultScope ? { defaultScope: cfg.defaultScope } : {}) }, null, 2)}\n`, { mode: 0o600 })
+  chmodSync(tmp, 0o600)
+  renameSync(tmp, p)
+}
+
+/** Removes the config (logout). Returns whether there was one. */
+export function clearOrgConfig(home: string): boolean {
+  const p = orgConfigPath(home)
+  if (!existsSync(p)) return false
+  rmSync(p, { force: true })
+  return true
+}