@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/org/sso.ts

@@ -0,0 +1,316 @@
+// brain org: single sign-on (OpenID Connect, authorization code + PKCE). The server routes every /v1/auth/* request here, before
+// authentication, because these endpoints are how a person obtains a bearer token.
+//
+//   GET  /v1/auth/sso/config    (no auth) -> {enabled, issuer?, authorizationEndpoint?, clientId?, scopes?}
+//   POST /v1/auth/sso/exchange  (no auth) {code, codeVerifier, redirectUri, nonce} -> {token, user, expiresAt}
+//   GET/PUT /v1/admin/sso       (admin; routed from server.ts to getSsoAdmin / putSsoAdmin) <-> SsoConfig
+//
+// The CLIENT only ever talks to the identity provider through the browser. The SERVER trades the code for tokens, VERIFIES the ID
+// token itself (oidc.ts: signature, iss, aud, exp, iat, nonce), then applies the organisation's rules (verified email, allowed
+// domain, role, disabled user) and issues an ordinary brain bearer token. The ID token and the access token are used in memory
+// for one request and never stored, logged, audited or returned. The caller gets one generic answer for every rejection; the real
+// reason goes to the audit log as a short fixed code, with only a keyed hash of the email's domain (never the email, never a token).
+//
+// Decisions: roles from `roleMap`/`defaultRole` apply when a user is CREATED by sign-in; an existing user's role is never changed
+// by a sign-in (admins own roles; an IdP group change cannot silently promote someone). `defaultRole: none` = only existing
+// users may sign in. A user id is the lower-cased email and must already be a valid id (so emails with `+`, non-ASCII, or over 64
+// characters are refused rather than mapped to something ambiguous). The redirect URI must be an http loopback address (the CLI's
+// own listener), so the exchange cannot be pointed at anyone else's page.
+import { createHash, createHmac } from "node:crypto"
+import type { OrgDb } from "./db.ts"
+import { isId } from "./db.ts"
+import { KeyCache, MAX_ID_TOKEN_CHARS, OidcError, basicAuth, emailVerified, endpointOk, fetchJson, isLoopbackHostname, tokenAuthFor, verifyIdToken, type Discovery, type IdClaims } from "./oidc.ts"
+import type { Role, SsoConfig } from "./types.ts"
+
+export interface SsoContext {
+  db: OrgDb
+  now: () => number
+  /** The caller's address (already rate limited by the server). */
+  ip: string
+}
+
+/** A bad admin input: the server turns it into a 400. */
+export class SsoInputError extends Error {}
+
+const ROLES: Role[] = ["viewer", "editor", "admin"]
+const roleRank = (r: Role): number => ROLES.indexOf(r)
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/
+const DEFAULT_SCOPES = "openid email profile"
+
+// ---- stored configuration ---------------------------------------------------------------------------------------------------
+
+export type StoredSso = Omit<SsoConfig, "clientSecret"> & { enabled: boolean }
+
+function load(db: OrgDb): StoredSso | undefined {
+  const raw = db.ssoRaw()
+  if (!raw) return undefined
+  try {
+    const v = JSON.parse(raw) as StoredSso
+    return isObj(v) && typeof v.issuer === "string" ? v : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const str = (b: Record<string, unknown>, k: string, max: number): string => {
+  const v = b[k]
+  if (typeof v !== "string" || !v.trim() || v.length > max || /[\u0000-\u001f\u007f\s]/.test(v)) throw new SsoInputError(`${k} must be a string of 1-${max} characters without spaces or control characters`)
+  return v
+}
+
+/** Validates an admin's SsoConfig; returns what is stored plus the secret (undefined = keep the old one, "" = remove it). */
+export function validateSsoConfig(body: unknown): { cfg: StoredSso; secret?: string } {
+  if (!isObj(body)) throw new SsoInputError("the body must be a JSON object")
+  const enabled = body.enabled === undefined ? true : body.enabled
+  if (typeof enabled !== "boolean") throw new SsoInputError("enabled must be true or false")
+  const issuer = str(body, "issuer", 500)
+  const u = endpointOk(issuer)
+  if (!u || u.search) throw new SsoInputError("issuer must be an https:// URL (http:// only for a loopback identity provider), without a query or fragment")
+  const clientId = str(body, "clientId", 256)
+  let secret: string | undefined
+  if (body.clientSecret !== undefined) {
+    if (typeof body.clientSecret !== "string" || body.clientSecret.length > 2048 || /[\u0000-\u001f\u007f]/.test(body.clientSecret)) throw new SsoInputError("clientSecret must be a string of at most 2048 characters")
+    secret = body.clientSecret
+  }
+  let scopes = DEFAULT_SCOPES
+  if (body.scopes !== undefined) {
+    const s = typeof body.scopes === "string" ? body.scopes.trim().replace(/\s+/g, " ") : ""
+    if (!s || s.length > 500 || !/^[\x21-\x7e]+( [\x21-\x7e]+)*$/.test(s) || !s.split(" ").includes("openid")) throw new SsoInputError("scopes must be space separated and include openid")
+    scopes = s
+  }
+  if (!Array.isArray(body.allowedDomains) || !body.allowedDomains.length || body.allowedDomains.length > 50) throw new SsoInputError("allowedDomains must list 1-50 domains (an empty list would let nobody in)")
+  const allowedDomains = [...new Set(body.allowedDomains.map((d) => (typeof d === "string" ? d.trim().toLowerCase() : "")))]
+  for (const d of allowedDomains) if (!DOMAIN_RE.test(d) || d.length > 253) throw new SsoInputError(`"${String(d).slice(0, 60)}" is not a domain name (no wildcards, no '@'; e.g. example.com)`)
+  const defaultRole = body.defaultRole === undefined ? "viewer" : body.defaultRole
+  if (defaultRole !== "none" && !ROLES.includes(defaultRole as Role)) throw new SsoInputError("defaultRole must be viewer, editor, admin or none")
+  let roleMap: SsoConfig["roleMap"]
+  if (body.roleMap !== undefined) {
+    const rm = body.roleMap
+    if (!isObj(rm) || typeof rm.claim !== "string" || !/^[A-Za-z0-9_:./-]{1,100}$/.test(rm.claim) || !isObj(rm.map)) throw new SsoInputError("roleMap must be {claim: string, map: {value: role}}")
+    const entries = Object.entries(rm.map)
+    if (!entries.length || entries.length > 200) throw new SsoInputError("roleMap.map must hold 1-200 entries")
+    const map: Record<string, Role> = Object.create(null)
+    for (const [k, r] of entries) {
+      if (k.length > 256 || !ROLES.includes(r as Role)) throw new SsoInputError("roleMap.map values must be viewer, editor or admin")
+      map[k] = r as Role
+    }
+    roleMap = { claim: rm.claim, map: { ...map } }
+  }
+  let tokenDays = 30
+  if (body.tokenDays !== undefined) {
+    if (typeof body.tokenDays !== "number" || !Number.isInteger(body.tokenDays) || body.tokenDays < 1 || body.tokenDays > 365) throw new SsoInputError("tokenDays must be a whole number from 1 to 365")
+    tokenDays = body.tokenDays
+  }
+  if (body.tokenAuth !== undefined && body.tokenAuth !== "client_secret_basic" && body.tokenAuth !== "client_secret_post") throw new SsoInputError("tokenAuth must be client_secret_basic or client_secret_post")
+  const tokenAuth = body.tokenAuth as SsoConfig["tokenAuth"]
+  return { cfg: { issuer, clientId, scopes, allowedDomains, defaultRole: defaultRole as Role | "none", ...(roleMap ? { roleMap } : {}), tokenDays, ...(tokenAuth ? { tokenAuth } : {}), enabled }, ...(secret !== undefined ? { secret } : {}) }
+}
+
+/** GET /v1/admin/sso: the configuration, without the secret (only whether one is set). */
+export function getSsoAdmin(db: OrgDb): Record<string, unknown> {
+  const c = load(db)
+  if (!c) return { enabled: false, configured: false }
+  return { ...c, configured: true, clientSecretSet: !!db.ssoSecret() }
+}
+
+/** PUT /v1/admin/sso: validates, stores, audits. A missing clientSecret keeps the old one; "" removes it. */
+export function putSsoAdmin(db: OrgDb, actor: string, body: unknown): Record<string, unknown> {
+  const { cfg, secret } = validateSsoConfig(body)
+  db.tx(() => {
+    db.setSsoRaw(JSON.stringify(cfg))
+    if (secret !== undefined) db.setSsoSecret(secret)
+  })
+  db.audit({ actor, action: cfg.enabled ? "admin.sso.set" : "admin.sso.disable", detail: `issuer=${cfg.issuer} domains=${cfg.allowedDomains.length} defaultRole=${cfg.defaultRole}${secret !== undefined ? " secret=updated" : ""}` })
+  return getSsoAdmin(db)
+}
+
+// ---- per-database runtime state ---------------------------------------------------------------------------------------------
+
+interface Runtime {
+  keys: KeyCache
+  usedCodes: Map<string, number>
+}
+const runtimes = new WeakMap<OrgDb, Runtime>()
+const CODE_TTL_MS = 10 * 60_000
+function runtime(ctx: SsoContext): Runtime {
+  let r = runtimes.get(ctx.db)
+  if (!r) runtimes.set(ctx.db, (r = { keys: new KeyCache(ctx.now), usedCodes: new Map() }))
+  return r
+}
+
+// ---- responses -------------------------------------------------------------------------------------------------------------
+
+const headers = { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" }
+const reply = (status: number, body: unknown): Response => new Response(JSON.stringify(body), { status, headers })
+const generic = (): Response => reply(401, { error: "sign-in failed", code: "sso_failed" })
+
+// ---- endpoints -------------------------------------------------------------------------------------------------------------
+
+export async function handleSso(req: Request, ctx: SsoContext): Promise<Response | undefined> {
+  const path = new URL(req.url).pathname
+  if (path === "/v1/auth/sso/config") {
+    if (req.method !== "GET") return reply(405, { error: "use GET", code: "method_not_allowed" })
+    return await config(ctx)
+  }
+  if (path === "/v1/auth/sso/exchange") {
+    if (req.method !== "POST") return reply(405, { error: "use POST", code: "method_not_allowed" })
+    return await exchange(req, ctx)
+  }
+  return undefined
+}
+
+async function config(ctx: SsoContext): Promise<Response> {
+  const c = load(ctx.db)
+  if (!c || !c.enabled) return reply(200, { enabled: false })
+  try {
+    const d = await runtime(ctx).keys.discovery(c.issuer)
+    return reply(200, { enabled: true, issuer: c.issuer, authorizationEndpoint: d.authorization_endpoint, clientId: c.clientId, scopes: c.scopes ?? DEFAULT_SCOPES })
+  } catch {
+    return reply(502, { error: "the identity provider is not reachable", code: "sso_unavailable" })
+  }
+}
+
+const readBody = async (req: Request): Promise<Record<string, unknown> | undefined> => {
+  const declared = Number(req.headers.get("content-length") ?? "0")
+  if (Number.isFinite(declared) && declared > 16_384) return undefined
+  const text = await req.text()
+  if (text.length > 16_384) return undefined
+  try {
+    const v = JSON.parse(text)
+    return isObj(v) ? v : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Highest role any value of the configured claim maps to. */
+function mappedRole(c: StoredSso, claims: Record<string, unknown>): Role | undefined {
+  if (!c.roleMap) return undefined
+  const v = claims[c.roleMap.claim]
+  const vals = typeof v === "string" ? [v] : Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []
+  let best: Role | undefined
+  for (const x of vals) {
+    const r = Object.hasOwn(c.roleMap.map, x) ? c.roleMap.map[x] : undefined
+    if (r && (!best || roleRank(r) > roleRank(best))) best = r
+  }
+  return best
+}
+
+/** The user id for an email, or undefined when the email cannot be mapped to a valid, unambiguous id. */
+export function emailToId(email: string): string | undefined {
+  const e = email.toLowerCase() // no trimming: whitespace in an email is a refusal, not something to clean up
+  const m = /^([a-z0-9]([a-z0-9._-]*[a-z0-9])?)@([a-z0-9.-]+)$/.exec(e)
+  if (!m || e.length > 64 || m[1]!.includes("..") || !DOMAIN_RE.test(m[3]!)) return undefined
+  return isId(e) ? e : undefined
+}
+
+const cleanName = (v: unknown, fallback: string): string => {
+  if (typeof v !== "string") return fallback
+  const s = v.replace(/[\p{Cc}\p{Zl}\p{Zp}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 200)
+  return s || fallback
+}
+
+async function exchange(req: Request, ctx: SsoContext): Promise<Response> {
+  const { db } = ctx
+  const hmac = (s: string): string => createHmac("sha256", db.auditKey()).update(s).digest("hex").slice(0, 12)
+  const fail = (reason: string, domain?: string): Response => {
+    db.audit({ actor: "-", action: "auth.sso.fail", detail: `reason=${reason}${domain ? ` domain=${hmac(domain)}` : ""}` })
+    return generic()
+  }
+  const c = load(db)
+  if (!c || !c.enabled) return fail("disabled")
+  const b = await readBody(req)
+  if (!b) return reply(400, { error: "the body must be a JSON object of at most 16 KB", code: "invalid_request" })
+  const { code, codeVerifier, redirectUri, nonce } = b
+  if (typeof code !== "string" || !code || code.length > 2048) return reply(400, { error: "code must be a string", code: "invalid_request" })
+  if (typeof codeVerifier !== "string" || !/^[A-Za-z0-9._~-]{43,128}$/.test(codeVerifier)) return reply(400, { error: "codeVerifier must be 43-128 URL-safe characters", code: "invalid_request" })
+  if (typeof nonce !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)) return reply(400, { error: "nonce must be 16-128 URL-safe characters", code: "invalid_request" })
+  let ru: URL | undefined
+  try {
+    ru = typeof redirectUri === "string" && redirectUri.length <= 200 ? new URL(redirectUri) : undefined
+  } catch {}
+  if (!ru || ru.protocol !== "http:" || !isLoopbackHostname(ru.hostname) || ru.username || ru.password || ru.hash || ru.search) return reply(400, { error: "redirectUri must be an http loopback address (http://127.0.0.1:<port>/callback)", code: "invalid_request" })
+
+  const rt = runtime(ctx)
+  const t = ctx.now()
+  const codeKey = createHash("sha256").update(code).digest("hex")
+  for (const [k, at] of rt.usedCodes) if (t - at > CODE_TTL_MS) rt.usedCodes.delete(k)
+  if (rt.usedCodes.has(codeKey)) return fail("replayed_code")
+  if (rt.usedCodes.size > 5_000) rt.usedCodes.clear()
+  rt.usedCodes.set(codeKey, t) // a code is spent the moment it is presented, whatever happens next
+
+  let disc: Discovery
+  try {
+    disc = await rt.keys.discovery(c.issuer)
+  } catch (e) {
+    return fail(e instanceof OidcError ? e.reason : "discovery")
+  }
+
+  let idToken: string
+  let accessToken: string | undefined
+  try {
+    const form = new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri as string, code_verifier: codeVerifier })
+    const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded" }
+    const secret = db.ssoSecret()
+    if (!secret) form.set("client_id", c.clientId) // a public client identifies itself; PKCE is its proof
+    else if (tokenAuthFor(disc, c.tokenAuth) === "client_secret_post") {
+      form.set("client_id", c.clientId)
+      form.set("client_secret", secret)
+    } else headers.authorization = basicAuth(c.clientId, secret)
+    const r = await fetchJson(disc.token_endpoint, { method: "POST", headers, body: form.toString() }, "token")
+    if (!isObj(r) || typeof r.id_token !== "string" || !r.id_token || r.id_token.length > MAX_ID_TOKEN_CHARS) return fail("token_response")
+    idToken = r.id_token
+    if (typeof r.access_token === "string" && r.access_token && r.access_token.length <= 8192) accessToken = r.access_token
+  } catch (e) {
+    return fail(e instanceof OidcError ? e.reason : "token_endpoint")
+  }
+
+  let claims: IdClaims
+  try {
+    claims = await verifyIdToken({ token: idToken, issuer: disc.issuer, clientId: c.clientId, nonce, nowMs: t, keys: (force) => rt.keys.keys(disc.jwks_uri, force) })
+  } catch (e) {
+    return fail(e instanceof OidcError ? e.reason : "verify")
+  }
+
+  // The code flow lets a provider keep profile claims out of the ID token and serve them from userinfo (OIDC Core 5.4; the
+  // certified oidc-provider does by default). Ask userinfo only for what the verified ID token lacks, and only about the same
+  // subject (5.3.2: its sub MUST match). The ID token's own claims always win; userinfo never overrides them.
+  const wanted = ["email", "email_verified", "name", ...(c.roleMap ? [c.roleMap.claim] : [])]
+  if (wanted.some((k) => claims[k] === undefined) && disc.userinfo_endpoint && accessToken) {
+    let info: unknown
+    try {
+      info = await fetchJson(disc.userinfo_endpoint, { method: "GET", headers: { authorization: `Bearer ${accessToken}` } }, "userinfo")
+    } catch (e) {
+      return fail(e instanceof OidcError ? e.reason : "userinfo")
+    }
+    if (!isObj(info) || typeof info.sub !== "string" || info.sub !== claims.sub) return fail("userinfo_sub_mismatch")
+    for (const k of wanted) if (claims[k] === undefined && info[k] !== undefined) (claims as Record<string, unknown>)[k] = info[k]
+  }
+
+  const email = typeof claims.email === "string" ? claims.email.toLowerCase() : ""
+  const domain = email.includes("@") ? email.slice(email.lastIndexOf("@") + 1) : ""
+  if (!email) return fail("no_email")
+  if (!emailVerified(claims)) return fail("email_not_verified", domain)
+  if (!c.allowedDomains.map((d) => d.toLowerCase()).includes(domain)) return fail("domain_not_allowed", domain)
+  const id = emailToId(email)
+  if (!id) return fail("email_not_mappable", domain)
+
+  const outcome = db.tx(() => {
+    const existing = db.user(id)
+    if (existing) return existing.disabled ? ("disabled" as const) : ("existing" as const)
+    if (c.defaultRole === "none") return "unknown" as const
+    const role = mappedRole(c, claims) ?? (c.defaultRole as Role)
+    db.addUser(id, cleanName(claims.name, id), role)
+    db.audit({ actor: "-", action: "auth.sso.user.create", detail: `role=${role} domain=${hmac(domain)}` })
+    return "created" as const
+  })
+  if (outcome === "disabled") return fail("user_disabled", domain)
+  if (outcome === "unknown") return fail("user_unknown", domain)
+
+  const days = c.tokenDays ?? 30
+  const tok = db.createToken(id, days, "sso")
+  db.audit({ actor: id, action: "auth.sso.ok", detail: `domain=${hmac(domain)} token=${tok.id}` })
+  const user = db.orgUser(db.user(id)!)
+  return reply(200, { token: tok.token, user, expiresAt: new Date(t + days * 86_400_000).toISOString() })
+}

package/src/org/tls.ts

@@ -0,0 +1,66 @@
+// brain org: TLS for the server itself. `admin serve --tls-cert <pem> --tls-key <pem>` makes Bun.serve terminate TLS, so the bearer
+// tokens never cross the network in clear text even without a proxy in front.
+//
+// This file only LOADS and CHECKS the certificate and key; Bun does the handshake. The check exists so a wrong pair or an
+// expired certificate stops the server at startup with a sentence, instead of every client failing later with a handshake error.
+// Refused: a missing or unreadable file; a file that is not a PEM certificate / private key; a private key protected by a
+// passphrase (not supported: use a key file the service account alone can read, or terminate TLS in a proxy); a key that does
+// not belong to the certificate; a certificate that has expired or is not valid yet.
+// NOT checked: that the certificate names the host clients use, or that it chains to a root clients trust (a client says so itself:
+// `brain org login --ca <pem>` for a private CA). `cert` may be a chain (the server's certificate first, then intermediates).
+import { X509Certificate, createPrivateKey } from "node:crypto"
+import { readFileSync } from "node:fs"
+
+export interface TlsFiles {
+  certFile: string
+  keyFile: string
+}
+export interface LoadedTls {
+  cert: string
+  key: string
+  /** When the certificate stops being valid. */
+  notAfter: Date
+  /** A non-fatal note for the operator (the certificate expires soon). */
+  warning?: string
+}
+
+export class TlsError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "TlsError"
+  }
+}
+
+function read(path: string, what: string): string {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    throw new TlsError(`cannot read the TLS ${what} file ${path}`)
+  }
+}
+
+export function loadTls(f: TlsFiles, now: () => number = Date.now): LoadedTls {
+  const cert = read(f.certFile, "certificate")
+  const key = read(f.keyFile, "private key")
+  let x: X509Certificate
+  try {
+    x = new X509Certificate(cert)
+  } catch {
+    throw new TlsError(`${f.certFile} does not hold a PEM certificate`)
+  }
+  let priv: ReturnType<typeof createPrivateKey>
+  try {
+    priv = createPrivateKey(key)
+  } catch (e) {
+    const msg = String((e as Error)?.message ?? e)
+    if (/passphrase|encrypted/i.test(msg)) throw new TlsError(`the private key in ${f.keyFile} is protected by a passphrase, which is not supported: use an unencrypted key file only the service account can read`)
+    throw new TlsError(`${f.keyFile} does not hold a PEM private key`)
+  }
+  if (!x.checkPrivateKey(priv)) throw new TlsError(`the private key in ${f.keyFile} does not belong to the certificate in ${f.certFile}`)
+  const t = now()
+  const notAfter = new Date(x.validTo)
+  if (Date.parse(x.validFrom) > t) throw new TlsError(`the certificate in ${f.certFile} is not valid until ${new Date(x.validFrom).toISOString()}`)
+  if (notAfter.getTime() <= t) throw new TlsError(`the certificate in ${f.certFile} expired on ${notAfter.toISOString()}`)
+  const days = Math.floor((notAfter.getTime() - t) / 86_400_000)
+  return { cert, key, notAfter, ...(days < 14 ? { warning: `the TLS certificate expires in ${days} day${days === 1 ? "" : "s"} (${notAfter.toISOString().slice(0, 10)}): renew it, then restart the server` } : {}) }
+}

package/src/org/types.ts

@@ -0,0 +1,193 @@
+// brain org: shared memory for an organisation, with who-may-see-what enforced by a server.
+//
+// What crosses the wire is only distilled, redacted MemoryItems (src/memory/types.ts): never blobs (full tool outputs), never raw
+// turns, never attachments. Those stay on the person's machine. Every item has a SCOPE; the default is private.
+//
+//   private  only its owner
+//   project  members of the item's project (explicit membership)
+//   team     members of a named team
+//   org      every member of the organisation
+//
+// ROLES (one per user, per organisation; one organisation per server database):
+//   viewer   recalls what its scopes allow; cannot add, promote or forget
+//   editor   viewer + adds items, promotes/demotes/forgets its OWN items (never above policy.maxScope)
+//   admin    editor + manages users, tokens, teams, project membership, policy, audit and retention; may forget any item by id;
+//            an admin does NOT see other people's private items (private means private)
+//
+// Identity is a bearer token (an admin creates it for a user; it is shown once, stored hashed, revocable, may expire).
+// Transport: the client refuses http:// to a non-loopback host unless BRAIN_ORG_INSECURE=1; run the server behind TLS.
+
+import type { MemoryItem, MemoryKind, ProjectKey, Recalled } from "../memory/types.ts"
+
+export type Scope = "private" | "project" | "team" | "org"
+export type Role = "viewer" | "editor" | "admin"
+
+/** Scopes from narrowest to widest. */
+export const SCOPES: Scope[] = ["private", "project", "team", "org"]
+export const scopeRank = (s: Scope): number => SCOPES.indexOf(s)
+
+export interface Policy {
+  /** The widest scope an item may be given. Default "team". */
+  maxScope: Scope
+  /** The scope of an item whose sender does not say. Default "private". */
+  defaultScope: Scope
+  /** Items that mention a path matching any of these globs (`**`, `*`) are dropped before they leave the machine and refused by the server. */
+  denyPaths: string[]
+  /** Items whose text contains any of these (case-insensitive substrings, or `/regex/i`) are dropped the same way. */
+  denyTerms: string[]
+  /** When set, only these kinds are accepted. */
+  allowedKinds?: MemoryKind[]
+  /** Items older than this many days (by when they were stored) are deleted by the retention run. Unset: kept. */
+  retentionDays?: number
+}
+
+export const DEFAULT_POLICY: Policy = { maxScope: "team", defaultScope: "private", denyPaths: [], denyTerms: [] }
+
+export interface OrgUser {
+  id: string
+  name: string
+  role: Role
+  /** Team ids the user belongs to. */
+  teams: string[]
+  disabled?: boolean
+}
+
+export interface WhoAmI {
+  user: OrgUser
+  org: { id: string; name: string }
+  policy: Policy
+  /** The server's API version. */
+  api: 1
+}
+
+/** An item as the server returns it: the recalled text plus who it belongs to and who may see it. */
+export interface OrgRecalled extends Recalled {
+  id?: string
+  scope: Scope
+  /** The owner's user id. */
+  owner: string
+  project?: string
+  team?: string
+}
+
+// ---- requests and responses (JSON over HTTP, `Authorization: Bearer <token>`) ----
+
+export interface IngestRequest {
+  project: ProjectKey
+  items: MemoryItem[]
+  /** Default: the policy's defaultScope. Not above the policy's maxScope, or the call is refused. */
+  scope?: Scope
+  /** Required for scope "team". */
+  team?: string
+}
+export interface IngestResponse {
+  stored: number
+  dropped: Array<{ id: string; reason: string }>
+  scope: Scope
+}
+
+export interface RecallRequest {
+  project: ProjectKey
+  query: string
+  limit?: number
+  maxTokens?: number
+}
+export interface RecallResponse {
+  items: OrgRecalled[]
+}
+
+export interface PromoteRequest {
+  /** Item ids (as stored by ingest), all owned by the caller. Either `ids`, or `source` (with `project`), is required. */
+  ids?: string[]
+  /** All the caller's items from one source session in `project` (the portable session id). */
+  source?: string
+  project?: ProjectKey
+  to: Scope
+  team?: string
+}
+export interface PromoteResponse {
+  changed: number
+}
+
+export interface ForgetRequest {
+  /** Which items: those of a project, or of one source session; `mine` limits it to the caller's own (the default for non-admins). */
+  project?: ProjectKey
+  source?: string
+  ids?: string[]
+  mine?: boolean
+}
+export interface ForgetResponse {
+  removed: number
+}
+
+export interface ProjectsResponse {
+  projects: Array<{ id: string; label: string; items: number }>
+}
+
+export interface AuditEvent {
+  at: string
+  /** The acting user id, or "-" when no one was identified. */
+  actor: string
+  action: string
+  project?: string
+  scope?: Scope
+  count?: number
+  /** Never the text of an item; for a recall, only a hash of the query. */
+  detail?: string
+}
+
+/** How a failed call comes back: HTTP status 400/401/403/404/413/429 and this body. */
+export interface OrgError {
+  error: string
+  /** A short stable code: "unauthorized", "forbidden", "scope_above_policy", "denied_by_policy", "rate_limited", ... */
+  code: string
+}
+
+/** The user-side configuration, <home>/.brain/org.json (mode 0600). */
+export interface OrgConfig {
+  server: string
+  token: string
+  /** Path to a PEM file with the certificate authority that signed the server's certificate (a private or internal CA). */
+  ca?: string
+  /** Applied when a command does not say: usually "private". */
+  defaultScope?: Scope
+}
+
+// ---- admin API shapes (role admin only) ----
+// POST /v1/admin/users            {id, name, role, teams?}        -> OrgUser
+// GET  /v1/admin/users                                            -> OrgUser[]  (or {users})
+// POST /v1/admin/users/disable    {id}                            -> {ok: true}
+// POST /v1/admin/tokens           {user, expiresInDays?}          -> {id, token}   (the token is returned ONCE)
+// GET  /v1/admin/tokens                                           -> [{id, user, created, expires?, lastUsed?, revoked}]  (never the token)
+// POST /v1/admin/tokens/revoke    {id}                            -> {ok: true}
+// POST /v1/admin/teams            {id, name, members: string[]}   -> {ok: true}
+// POST /v1/admin/projects/members {project: string, add?: {users?: string[], teams?: string[]}, remove?: {users?: string[], teams?: string[]}} -> {ok: true}
+// GET  /v1/admin/policy                                           -> Policy
+// PUT  /v1/admin/policy           Policy                          -> Policy
+// GET  /v1/admin/audit?since=<iso>&limit=<n>                      -> AuditEvent[]  (or {events})
+// POST /v1/admin/retention/run    {}                              -> {removed: number}
+
+// ---- single sign-on (OIDC authorization code + PKCE; the server turns a verified identity into a brain bearer token) ----
+export interface SsoConfig {
+  /** The identity provider's issuer URL (its `/.well-known/openid-configuration` is fetched from it): Google, Okta, Azure AD, Auth0, ... */
+  issuer: string
+  clientId: string
+  /** Optional: public clients using PKCE need none. Never returned by the API after it is set. */
+  clientSecret?: string
+  /** Default "openid email profile". */
+  scopes?: string
+  /** Only identities with a verified email in one of these domains may sign in. Required: an empty list means nobody can. */
+  allowedDomains: string[]
+  /** Create the user on first sign-in with this role; "none" means the user must already exist. Default "viewer". */
+  defaultRole: Role | "none"
+  /** Optional: a claim (e.g. "groups") whose values map to roles; the highest matching role wins. */
+  roleMap?: { claim: string; map: Record<string, Role> }
+  /** How long an issued token lasts, in days. Default 30. */
+  tokenDays?: number
+  /** How the server authenticates with the client secret at the token endpoint. Default client_secret_basic (the OAuth default),
+   *  or client_secret_post when the provider supports only that. */
+  tokenAuth?: "client_secret_basic" | "client_secret_post"
+}
+// GET  /v1/auth/sso/config   (no auth) -> {enabled: boolean, issuer?, authorizationEndpoint?, clientId?, scopes?}
+// POST /v1/auth/sso/exchange (no auth) {code, codeVerifier, redirectUri, nonce} -> {token, user: OrgUser, expiresAt}
+// GET/PUT /v1/admin/sso (admin) <-> SsoConfig (the secret is write-only)

package/src/self.ts

@@ -0,0 +1,68 @@
+// How brain refers to itself in what it writes for other programs: AI tools' MCP entries and session hooks run brain
+// later, long after this process is gone.
+//
+// From a checkout or a global install (`bun add -g @100xprompt/brain`), that is `<bun> <absolute path to cli.ts>`: the
+// file stays where it is. Run through `bunx @100xprompt/brain` (or `bun x`), this cli.ts is a temporary copy that a reboot
+// or a cache clean removes, so the entry would break; then it is `<bun> x @100xprompt/brain@<this version>` instead, pinned
+// so a later release does not change what an installed hook runs. The absolute bun stays either way: a tool started from
+// a desktop launcher often has no ~/.bun/bin on its PATH.
+import { chmodSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+export const CLI_PATH = join(import.meta.dir, "cli.ts")
+
+function readPackage(): { name: string; version: string } {
+  try {
+    const p = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8"))
+    if (typeof p?.name === "string" && typeof p?.version === "string") return { name: p.name, version: p.version }
+  } catch {}
+  return { name: "@100xprompt/brain", version: "0.0.0" }
+}
+const pkg = readPackage()
+export const PACKAGE = pkg.name
+export const VERSION = pkg.version
+
+/** A copy that will not be there later: bunx's temporary install, Bun's or npm's package-runner cache. */
+export function isEphemeral(path: string = CLI_PATH): boolean {
+  return /[\\/](?:bunx-[^\\/]*|_npx|\.bun[\\/]install[\\/]cache|dlx-[^\\/]*)[\\/]/.test(path)
+}
+
+/** The package spec an ephemeral copy is started with later. */
+export const pinnedSpec = (): string => `${PACKAGE}@${VERSION}`
+
+/** What follows the bun executable to start this brain later: [cli.ts] or ["x", "@100xprompt/brain@<version>"]. */
+export function selfArgs(path: string = CLI_PATH): string[] {
+  return isEphemeral(path) ? ["x", pinnedSpec()] : [path]
+}
+
+/**
+ * The bun that installed entries start brain with: absolute, because a tool started from a desktop launcher often has no
+ * ~/.bun/bin on its PATH. Where the bun on PATH is this same executable through a symlink (Homebrew's
+ * /opt/homebrew/bin/bun pointing into Cellar/<version>/, proto's shims), the symlink is used: it survives an upgrade and
+ * the versioned path does not. BRAIN_BUN overrides it (tests pin "bun").
+ */
+export function stableBun(execPath: string = process.execPath, onPath: string | null = Bun.which("bun")): string {
+  if (process.env.BRAIN_BUN) return process.env.BRAIN_BUN
+  const exec = /(?:^|[\\/])bun(?:\.exe)?$/.test(execPath) ? execPath : undefined
+  if (onPath && exec) {
+    try {
+      if (realpathSync(onPath) === realpathSync(exec)) return onPath
+    } catch {}
+  }
+  return exec ?? onPath ?? "bun"
+}
+
+/**
+ * A global install can leave cli.ts writable by everyone (a package's bin is made executable with mode 0777), and the
+ * hooks and MCP entries brain installs run this file on their own. Brain takes the write bits for others off its own
+ * files when it starts; only files the running user owns, and never an error.
+ */
+export function secureSelf(files: string[] = [CLI_PATH]): void {
+  if (typeof process.getuid !== "function") return
+  for (const f of files) {
+    try {
+      const st = statSync(f)
+      if (st.uid === process.getuid() && st.mode & 0o022) chmodSync(f, st.mode & 0o7755)
+    } catch {}
+  }
+}