@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/gateway/signin.ts

@@ -0,0 +1,323 @@
+// `brain gateway login`: sign in to 100xprompt in the browser, the same way the 100xprompt CLI does (`100xprompt auth login`).
+//
+//   1. A one-use server listens on 127.0.0.1 on a free port, for /auth/callback only.
+//   2. The browser opens https://100xprompt.com/auth/cli?port=<port>&state=<random>&challenge=<PKCE S256>. The person signs in
+//      there; the site sends the browser back to http://127.0.0.1:<port>/auth/callback?token=...&state=...&email=...
+//   3. The state must be the one sent (so no other page can hand this machine a key); the token is the gateway key.
+//   4. No browser here (SSH), or the callback cannot get through: the person pastes the one-time code or API key the
+//      site shows instead (input hidden). It is checked the way the CLI checks it.
+//
+// HUNDREDXPROMPT_AUTH_URL points the sign-in at another site (the CLI reads the same variable). The key is never printed.
+//
+// The state is the only thing that tells the real sign-in apart from a key planted by someone else on this machine, so
+// it is kept out of other processes' view where the system allows: on macOS the address goes to the browser through
+// AppleScript's `open location` on stdin, not on a command line that `ps` shows every user. (Linux and Windows browsers
+// take the address on their command line; there, another user who watches `ps` during the sign-in could plant a key. The
+// 100xprompt CLI has the same limit everywhere.)
+import { timingSafeEqual } from "node:crypto"
+
+export const AUTH_URL = "https://100xprompt.com"
+export const TIMEOUT_MS = 5 * 60_000
+
+/** PKCE (RFC 7636): a 43-character verifier and its S256 challenge, as the CLI makes them. */
+export async function pkce(): Promise<{ verifier: string; challenge: string }> {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+  const verifier = Array.from(crypto.getRandomValues(new Uint8Array(43)), (b) => chars[b % chars.length]).join("")
+  const challenge = Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))).toString("base64url")
+  return { verifier, challenge }
+}
+
+/**
+ * Whether a pasted credential looks like a 100xprompt one, as the CLI decides it (Auth.validate): a 100x_live_ / 100x_test_ /
+ * sk- key, a sign-in token (JWT, not expired), or a 100x_auth_ one-time code wrapping either. Returns the key to store.
+ */
+export function checkCredential(raw: string, now = Date.now()): { ok: true; key: string; email?: string } | { ok: false; why: string } {
+  const t = raw.trim()
+  if (!t || t.length < 16) return { ok: false, why: "that is too short to be a key or code" }
+  if (/\s/.test(t)) return { ok: false, why: "a key or code has no spaces in it" }
+  // The sign-in page shows the key shortened ("100x_live_AbCdEfGhIjKl...12345678"); only its Copy key button gives all of it.
+  if (/\.\.\.|…/.test(t)) return { ok: false, why: "that is the shortened key the page shows: use its Copy key button, then paste again" }
+  if (/^(?:100x_live_|100x_test_|sk-)/.test(t)) {
+    if (!/^(?:100x_live_|100x_test_|sk-)[A-Za-z0-9_-]+$/.test(t)) return { ok: false, why: "that key has characters a 100xprompt key never has" }
+    return t.length >= 24 ? { ok: true, key: t } : { ok: false, why: "that key is too short" }
+  }
+  const parts = t.split(".")
+  if (parts.length === 3) {
+    try {
+      const head = JSON.parse(Buffer.from(parts[0]!, "base64url").toString("utf8"))
+      const body = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"))
+      if (!head?.alg || !body?.sub) return { ok: false, why: "that sign-in token is malformed" }
+      if (typeof body.exp === "number" && body.exp < Math.floor(now / 1000)) return { ok: false, why: "that sign-in token has expired: sign in again" }
+      return { ok: true, key: t, ...(typeof body.email === "string" ? { email: body.email } : {}) }
+    } catch {
+      return { ok: false, why: "that sign-in token is malformed" }
+    }
+  }
+  if (t.startsWith("100x_auth_")) {
+    try {
+      const inner = JSON.parse(Buffer.from(t.slice("100x_auth_".length), "base64url").toString("utf8"))
+      if (typeof inner?.t === "string" && !inner.t.startsWith("100x_auth_")) {
+        const r = checkCredential(inner.t, now)
+        return r.ok && typeof inner.e === "string" && !r.email ? { ...r, email: inner.e } : r
+      }
+    } catch {}
+    return { ok: false, why: "that one-time code is malformed" }
+  }
+  return { ok: false, why: `that is not a 100xprompt key or one-time code (copy the code from ${AUTH_URL}/auth/cli, or a 100x_live_ key)` }
+}
+
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
+const page = (title: string, body: string, status = 200) =>
+  new Response(
+    `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title>` +
+      `<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#050505;color:#f1ecec}` +
+      `main{text-align:center;max-width:32rem;padding:1rem}h1{font-size:1.4rem}p{color:#a8a3a3}</style></head>` +
+      `<body><main><h1>${esc(title)}</h1><p>${esc(body)}</p></main></body></html>`,
+    // The callback URL carries the key: nothing on this page may cache it or pass it on.
+    { status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-frame-options": "DENY" } },
+  )
+
+/** Constant-time state check. Byte lengths are compared (a non-ASCII state of the right length in characters must not throw). */
+const sameState = (got: string, want: string) => {
+  const a = Buffer.from(got)
+  const b = Buffer.from(want)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+/** The key in a callback's token: the CLI takes it as it is; brain also unwraps a one-time code and refuses junk. */
+const callbackKey = (token: string): { ok: true; key: string; email?: string } | { ok: false; why: string } =>
+  token.startsWith("100x_auth_") ? checkCredential(token) : token.length >= 16 && !/\s/.test(token) ? { ok: true, key: token } : { ok: false, why: "no key came back from the sign-in page" }
+
+/** The sign-in site from --auth-url / $HUNDREDXPROMPT_AUTH_URL (empty means unset, as for the CLI); undefined if not http(s). */
+export function signInBase(given?: string): string | undefined {
+  const raw = given?.trim() || process.env.HUNDREDXPROMPT_AUTH_URL?.trim() || AUTH_URL
+  try {
+    const u = new URL(raw)
+    if (u.protocol !== "https:" && u.protocol !== "http:") return undefined
+    return `${u.origin}${u.pathname.replace(/\/+$/, "")}`
+  } catch {
+    return undefined
+  }
+}
+
+export interface SignInDeps {
+  /** Opens the sign-in page; default: the system browser. */
+  open?: (url: string) => void
+  /** false: print the address only (a machine with no browser, or one the person opens elsewhere). */
+  browser?: boolean
+  /** The sign-in site; default $HUNDREDXPROMPT_AUTH_URL or https://100xprompt.com. */
+  authUrl?: string
+  timeoutMs?: number
+  /**
+   * Asks for a pasted code, input hidden; resolves undefined when the person gives up or `signal` aborts. Absent when
+   * there is no terminal to ask in (then the browser is the only way).
+   */
+  ask?: (message: string, signal: AbortSignal) => Promise<string | undefined>
+  say: (line: string) => void
+}
+
+export type SignIn = { ok: true; key: string; email?: string; via: "browser" | "code" } | { ok: false; why: string }
+
+/** Signs in through the browser (or a pasted code). Does not store anything: the caller does. */
+export async function browserSignIn(d: SignInDeps): Promise<SignIn> {
+  const base = signInBase(d.authUrl)
+  if (!base) return { ok: false, why: "HUNDREDXPROMPT_AUTH_URL must be an http:// or https:// address" }
+  const { challenge } = await pkce()
+  const state = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex")
+  let finish!: (r: SignIn) => void
+  const done = new Promise<SignIn>((r) => (finish = r))
+  let settled = false
+  const settle = (r: SignIn) => {
+    if (settled) return
+    settled = true
+    finish(r)
+  }
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    development: false,
+    // Anything the handler did not expect: a plain refusal, never a stack trace on the page or in the terminal.
+    error: () => new Response("Bad request", { status: 400 }),
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname !== "/auth/callback" || req.method !== "GET") return new Response("Not found", { status: 404 })
+      if (settled) return page("Already signed in", "This sign-in has finished. You can close this tab.", 410)
+      const got = url.searchParams.get("state") ?? ""
+      const error = url.searchParams.get("error")
+      // Only the page this command opened knows the state: anything else is refused and the wait goes on.
+      if (!/^[0-9a-f]{64}$/.test(got) || !sameState(got, state)) return page("Sign-in refused", "This link was not started by this brain gateway login. Start again from your terminal.", 400)
+      if (error) {
+        settle({ ok: false, why: `the sign-in page said: ${error.slice(0, 200)}` })
+        return page("Sign-in failed", `${error.slice(0, 200)}. Go back to your terminal.`, 400)
+      }
+      const c = callbackKey(url.searchParams.get("token") ?? "")
+      if (!c.ok) {
+        settle({ ok: false, why: c.why })
+        return page("Sign-in failed", "No usable key came back. Go back to your terminal.", 400)
+      }
+      const email = url.searchParams.get("email") || c.email || undefined
+      settle({ ok: true, key: c.key, ...(email ? { email } : {}), via: "browser" })
+      return page("Signed in", `brain is now signed in to the 100xprompt gateway${email ? ` as ${email}` : ""}. You can close this tab and go back to your terminal.`)
+    },
+  })
+  const url = `${base}/auth/cli?port=${server.port}&state=${state}&challenge=${challenge}`
+  const stopAsking = new AbortController()
+  const timer = setTimeout(() => settle({ ok: false, why: `no sign-in came back within ${Math.round((d.timeoutMs ?? TIMEOUT_MS) / 60_000) || 1} minutes` }), d.timeoutMs ?? TIMEOUT_MS)
+  try {
+    if (d.browser === false) d.say(`Open this address in a browser to sign in to 100xprompt:\n  ${url}`)
+    else {
+      d.say(`Opening your browser to sign in to 100xprompt:\n  ${url}`)
+      try {
+        ;(d.open ?? openInBrowser)(url)
+      } catch {}
+    }
+    if (d.ask) {
+      d.say(
+        "Waiting for the browser. Signing in on another machine (SSH)? Paste the key from the page's Copy key button, or the address the browser could not open, then press Enter (Escape cancels).",
+      )
+      // The paste runs alongside the browser: whichever comes first wins. A bad paste asks again; Escape ends the sign-in
+      // (an abandoned hidden prompt would leave the terminal echoing whatever is pasted next, and the shell reading it).
+      void (async () => {
+        for (;;) {
+          const pasted = await d.ask!("key or address: ", stopAsking.signal)
+          if (settled) return
+          if (pasted === undefined) return settle({ ok: false, why: "sign-in cancelled" })
+          if (!pasted.trim()) continue
+          const c = fromPaste(pasted.trim(), state)
+          if (c.ok) return settle({ ok: true, key: c.key, ...(c.email ? { email: c.email } : {}), via: "code" })
+          if ("fatal" in c) return settle({ ok: false, why: c.why })
+          d.say(`  ${c.why}`)
+        }
+      })()
+    } else d.say("Waiting for the browser…")
+    return await done
+  } finally {
+    clearTimeout(timer)
+    stopAsking.abort()
+    // The page that just answered must reach the browser before this returns: `brain` exits right after, and an exit
+    // with the answer still unsent leaves the person looking at a browser error after a sign-in that worked. A graceful
+    // stop waits for that answer; a browser holding the connection open gets cut off after 1.5 s.
+    await Promise.race([server.stop(), Bun.sleep(1_500)])
+    void server.stop(true)
+  }
+}
+
+/**
+ * A pasted key, one-time code or sign-in token; or the callback address itself (on SSH the browser is sent to
+ * 127.0.0.1 on the wrong machine, and the address it could not open holds the key). An address must carry this sign-in's
+ * state, so one from another sign-in, or one made up, is refused.
+ */
+export function fromPaste(pasted: string, state: string): { ok: true; key: string; email?: string } | { ok: false; why: string } | { ok: false; why: string; fatal: true } {
+  if (/^https?:\/\//i.test(pasted)) {
+    let u: URL
+    try {
+      u = new URL(pasted)
+    } catch {
+      return { ok: false, why: "that address could not be read" }
+    }
+    if (!u.pathname.endsWith("/auth/callback")) return { ok: false, why: "that is not the sign-in's return address (it ends in /auth/callback?token=...)" }
+    const got = u.searchParams.get("state") ?? ""
+    if (!/^[0-9a-f]{64}$/.test(got) || !sameState(got, state)) return { ok: false, why: "that address is from another sign-in: paste the one from this sign-in" }
+    const error = u.searchParams.get("error")
+    if (error) return { ok: false, why: `the sign-in page said: ${error.slice(0, 200)}`, fatal: true }
+    const c = callbackKey(u.searchParams.get("token") ?? "")
+    if (!c.ok) return c
+    const email = u.searchParams.get("email") || c.email
+    return { ok: true, key: c.key, ...(email ? { email } : {}) }
+  }
+  return checkCredential(pasted)
+}
+
+/**
+ * How to open the sign-in page on this platform: the command, and what to write to its stdin. On macOS the address goes
+ * to AppleScript's `open location` on stdin, so it (and its state) is on no command line.
+ */
+export function browserCommand(url: string, platform: string = process.platform): { argv: string[]; stdin?: string } {
+  if (platform === "darwin") return { argv: ["osascript", "-"], stdin: `open location "${url.replace(/[\\"]/g, (c) => `\\${c}`)}"\n` }
+  if (platform === "win32") return { argv: ["cmd", "/c", "start", "", url.replace(/&/g, "^&")] }
+  return { argv: ["xdg-open", url] }
+}
+
+/** Opens the sign-in page in the default browser (browserCommand). */
+export function openInBrowser(url: string): void {
+  const c = browserCommand(url)
+  try {
+    const p = Bun.spawn(c.argv, { stdin: c.stdin === undefined ? "ignore" : "pipe", stdout: "ignore", stderr: "ignore" })
+    if (c.stdin !== undefined && p.stdin && typeof p.stdin !== "number") {
+      p.stdin.write(c.stdin)
+      void p.stdin.end()
+    }
+    p.unref()
+  } catch {}
+}
+
+/**
+ * Applies typed or pasted terminal input to `buf`. Enter ends the line; Escape on its own, or Ctrl-D on an empty line,
+ * cancels; Ctrl-C interrupts. Arrow, Delete and Home keys, Alt+key and bracketed-paste markers arrive as escape sequences
+ * and are skipped, so they neither end the prompt nor land in the key.
+ */
+export function applyKeys(buf: string, chunk: string): { buf: string; end?: "enter" | "cancel" | "interrupt" } {
+  for (let i = 0; i < chunk.length; i++) {
+    const ch = chunk[i]!
+    if (ch === "\r" || ch === "\n") return { buf, end: "enter" }
+    if (ch === "\u0003") return { buf, end: "interrupt" }
+    if (ch === "\u0004") {
+      if (!buf) return { buf, end: "cancel" }
+      continue
+    }
+    if (ch === "\u001b") {
+      const next = chunk[i + 1]
+      if (next === undefined) return { buf, end: "cancel" }
+      if (next === "[") {
+        // CSI: parameter bytes, then one final byte in 0x40-0x7E.
+        let j = i + 2
+        while (j < chunk.length && !(chunk.charCodeAt(j) >= 0x40 && chunk.charCodeAt(j) <= 0x7e)) j++
+        i = j
+      } else i += next === "O" ? 2 : 1 // SS3 (ESC O x) or Alt+key (ESC x)
+      continue
+    }
+    if (ch === "\u007f" || ch === "\b") buf = buf.slice(0, -1)
+    else if (ch >= " ") buf += ch
+  }
+  return { buf }
+}
+
+/**
+ * Reads one line from the terminal without showing it (the key must not land in the scrollback). undefined: no terminal,
+ * cancelled (Escape, Ctrl-D), or `signal` aborted. Ctrl-C ends the command, as it would anywhere else.
+ */
+export function askHidden(message: string, signal: AbortSignal): Promise<string | undefined> {
+  const stdin = process.stdin
+  if (!stdin.isTTY || signal.aborted) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    let buf = ""
+    let over = false
+    process.stderr.write(message)
+    stdin.setRawMode(true)
+    stdin.setEncoding("utf8")
+    stdin.resume()
+    const end = (v: string | undefined) => {
+      if (over) return
+      over = true
+      stdin.off("data", onData)
+      signal.removeEventListener("abort", onAbort)
+      stdin.setRawMode(false)
+      stdin.pause()
+      process.stderr.write("\n")
+      resolve(v)
+    }
+    const onAbort = () => end(undefined)
+    const onData = (chunk: string) => {
+      const r = applyKeys(buf, chunk)
+      buf = r.buf
+      if (r.end === "enter") end(buf)
+      else if (r.end === "cancel") end(undefined)
+      else if (r.end === "interrupt") {
+        end(undefined)
+        process.exit(130)
+      }
+    }
+    stdin.on("data", onData)
+    signal.addEventListener("abort", onAbort)
+  })
+}

package/src/handoff.ts

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+// Pending handoffs: a brief waiting for the next session of a target tool in a project. `brain session
+// continue --in <tool>` writes one; the tool's session-start hook (hooks.ts) finds it, hands the brief to
+// the model once, and marks it used for that tool. Kept as plain files under ~/.brain/handoffs.
+
+export const HANDOFF_HOURS = 12
+
+export interface Handoff {
+  id: string
+  createdAt: string
+  expiresAt: string
+  /** The tool and portable id of the session being continued. */
+  fromTool: string
+  sessionId: string
+  title?: string
+  /** The project folder the brief is for. */
+  cwd: string
+  gitRemote?: string
+  /** The tool the person is moving to, or "any". */
+  target: string
+  brief: string
+  /** The brief as a Markdown file, for pasting by hand. */
+  briefPath: string
+  /** Tools whose sessions have already received it. */
+  consumedBy: string[]
+}
+
+export const handoffDir = (home: string) => join(home, ".brain", "handoffs")
+
+export function saveHandoff(home: string, h: Omit<Handoff, "briefPath" | "consumedBy" | "expiresAt" | "createdAt"> & { now?: number }): Handoff {
+  const now = h.now ?? Date.now()
+  const dir = handoffDir(home)
+  mkdirSync(dir, { recursive: true })
+  const briefPath = join(dir, `${h.id}.md`)
+  const { now: _, ...rest } = h
+  const full: Handoff = { ...rest, createdAt: new Date(now).toISOString(), expiresAt: new Date(now + HANDOFF_HOURS * 3_600_000).toISOString(), briefPath, consumedBy: [] }
+  writeFileSync(briefPath, `${h.brief}\n`)
+  writeFileSync(join(dir, `${h.id}.json`), `${JSON.stringify(full, null, 1)}\n`)
+  return full
+}
+
+export function listHandoffs(home: string): Handoff[] {
+  const dir = handoffDir(home)
+  let names: string[] = []
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".json"))
+  } catch {
+    return []
+  }
+  const out: Handoff[] = []
+  for (const n of names) {
+    try {
+      out.push(JSON.parse(readFileSync(join(dir, n), "utf8")) as Handoff)
+    } catch {
+      // A half-written or foreign file is not a handoff.
+    }
+  }
+  return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+const norm = (p: string) => p.replace(/\/+$/, "")
+/** The same project: the same folder, one inside the other, or the same git remote. */
+function sameProject(h: Handoff, cwd: string, gitRemote?: string): boolean {
+  const a = norm(h.cwd)
+  const b = norm(cwd)
+  return a === b || b.startsWith(`${a}/`) || a.startsWith(`${b}/`) || (!!gitRemote && !!h.gitRemote && h.gitRemote === gitRemote)
+}
+
+/** A tool's claim on a handoff: created exclusively, so two sessions starting at once cannot both take it. */
+const claimPath = (home: string, id: string, tool: string) => join(handoffDir(home), `${id}.${tool}.claimed`)
+
+/** The newest unexpired handoff for this project that `tool` has not received yet. */
+export function findHandoff(home: string, q: { cwd: string; tool: string; gitRemote?: string; now?: number }): Handoff | undefined {
+  const now = q.now ?? Date.now()
+  return listHandoffs(home).find(
+    (h) =>
+      Date.parse(h.expiresAt) > now &&
+      (h.target === q.tool || h.target === "any") &&
+      !h.consumedBy.includes(q.tool) &&
+      !existsSync(claimPath(home, h.id, q.tool)) &&
+      sameProject(h, q.cwd, q.gitRemote),
+  )
+}
+
+/** Claims the handoff for `tool`; false when another session of that tool already has it (deliver nothing then). */
+export function markConsumed(home: string, id: string, tool: string): boolean {
+  try {
+    writeFileSync(claimPath(home, id, tool), new Date().toISOString(), { flag: "wx" })
+  } catch {
+    return false
+  }
+  // Also recorded in the handoff itself, for listing; the claim file is what decides.
+  const path = join(handoffDir(home), `${id}.json`)
+  try {
+    const h = JSON.parse(readFileSync(path, "utf8")) as Handoff
+    if (!h.consumedBy.includes(tool)) h.consumedBy.push(tool)
+    writeFileSync(path, `${JSON.stringify(h, null, 1)}\n`)
+  } catch {
+    // Gone or unreadable: the claim file still stands.
+  }
+  return true
+}