The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: Claude agent setup-token login in a sandbox (#11286)
Nicky Leache31951a17df4
diff --git a/packages/adapter-utils/src/setup-token-transport.test.ts b/packages/adapter-utils/src/setup-token-transport.test.tsnew file mode 100644index 0000000000..3644e35581--- /dev/null+++ b/packages/adapter-utils/src/setup-token-transport.test.ts@@ -0,0 +1,228 @@+import { describe, expect, it } from "vitest";+import {+ createSetupTokenPtyTransport,+ type SetupTokenPtySession,+} from "./setup-token-transport.js";++// The Enter byte the terminal login UI reads to submit the browser code. The+// login runner appends this byte to the code. The transport forwards the bytes+// unchanged, so the pseudo-terminal receives the code and then the Enter byte.+const ENTER = "\r";++/**+ * A fake pseudo-terminal session. It records each input write, drives the output+ * stream on demand, and records the stop and the close. The tests use it in+ * place of a real pseudo-terminal, so the transport runs with no sandbox.+ */+function createFakePtySession(): SetupTokenPtySession & {+ writes: string[];+ emit: (chunk: string) => void;+ finish: (exitCode: number | null) => void;+ killed: number;+ closed: number;+ // Resolves when the transport registers the output listener. The session+ // streams only after it opens, so a test waits on this before it drives the+ // output or stops the child.+ ready: Promise<void>;+} {+ const writes: string[] = [];+ let listener: ((chunk: string) => void) | null = null;+ let resolveWait: ((value: { exitCode: number | null }) => void) | null = null;+ const waitPromise = new Promise<{ exitCode: number | null }>((resolve) => {+ resolveWait = resolve;+ });+ let markReady: (() => void) | null = null;+ const ready = new Promise<void>((resolve) => {+ markReady = resolve;+ });+ let killed = 0;+ let closed = 0;+ return {+ ready,+ onData(next: (chunk: string) => void): void {+ listener = next;+ markReady?.();+ },+ write(data: string): void {+ writes.push(data);+ },+ wait(): Promise<{ exitCode: number | null }> {+ return waitPromise;+ },+ kill(): void {+ killed += 1;+ },+ async close(): Promise<void> {+ closed += 1;+ },+ // Test control below. The transport never reads these fields.+ emit(chunk: string): void {+ listener?.(chunk);+ },+ finish(exitCode: number | null): void {+ resolveWait?.({ exitCode });+ },+ get writes(): string[] {+ return writes;+ },+ get killed(): number {+ return killed;+ },+ get closed(): number {+ return closed;+ },+ };+}++describe("createSetupTokenPtyTransport", () => {+ it("delivers delayed input to the process", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", () => {});+ await session.ready;+ // The input arrives after the start and after the first output, so the+ // transport delivers it to the running process, not before it.+ session.emit("... the url below to sign in ...");+ transport.write("ABCD");+ session.finish(0);+ await started;++ expect(session.writes).toEqual(["ABCD"]);+ });++ it("returns incremental terminal output to the runner", async () => {+ const session = createFakePtySession();+ const received: string[] = [];+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", (chunk) => {+ received.push(chunk);+ });+ await session.ready;++ // Each output chunk reaches the runner as the pseudo-terminal emits it, not+ // as one final batch at the end.+ session.emit("first ");+ expect(received).toEqual(["first "]);+ session.emit("second");+ expect(received).toEqual(["first ", "second"]);++ session.finish(0);+ await started;+ });++ it("delivers the Enter byte after the browser code", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", () => {});+ await session.ready;+ // The runner writes the code plus the Enter byte in one write. The transport+ // forwards the bytes unchanged, so the code comes first and the Enter byte+ // comes last.+ transport.write("WXYZ" + ENTER);+ session.finish(0);+ await started;++ const delivered = session.writes.join("");+ expect(delivered).toBe("WXYZ" + ENTER);+ expect(delivered.endsWith(ENTER)).toBe(true);+ expect(delivered.indexOf("WXYZ")).toBeLessThan(delivered.lastIndexOf(ENTER));+ });++ it("resolves start with the child exit code", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", () => {});+ session.finish(7);++ await expect(started).resolves.toEqual({ exitCode: 7 });+ });++ it("stops the child with a direct kill", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", () => {});+ await session.ready;+ transport.stop();+ expect(session.killed).toBe(1);++ session.finish(null);+ await started;+ });++ it("disposes the session resources", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ const started = transport.start("claude setup-token", () => {});+ session.finish(0);+ await started;++ await transport.dispose();+ expect(session.closed).toBe(1);+ });++ it("stays safe when stop and dispose run before start", async () => {+ const session = createFakePtySession();+ const transport = createSetupTokenPtyTransport(async () => session);++ // The runner may stop or dispose before it starts the child. The transport+ // must not throw, and it must not open a session for a run it already stopped.+ transport.stop();+ await transport.dispose();++ expect(session.killed).toBe(0);+ expect(session.closed).toBe(0);+ });++ it("kills a session that opens after an early stop", async () => {+ const session = createFakePtySession();+ let resolveOpen!: () => void;+ const openGate = new Promise<void>((resolve) => {+ resolveOpen = resolve;+ });+ const transport = createSetupTokenPtyTransport(async () => {+ await openGate;+ return session;+ });++ const started = transport.start("claude setup-token", () => {});+ // The stop arrives while the session is still opening. The transport must+ // kill the child as soon as the session exists.+ transport.stop();+ resolveOpen();+ session.finish(null);+ await started;++ expect(session.killed).toBe(1);+ });++ it("buffers input that arrives before the session opens", async () => {+ const session = createFakePtySession();+ let resolveOpen!: () => void;+ const openGate = new Promise<void>((resolve) => {+ resolveOpen = resolve;+ });+ const transport = createSetupTokenPtyTransport(async () => {+ await openGate;+ return session;+ });++ const started = transport.start("claude setup-token", () => {});+ transport.write("EARLY" + ENTER);+ expect(session.writes).toEqual([]);++ resolveOpen();+ // Let the pending open resolve and flush the buffered input.+ await Promise.resolve();+ await Promise.resolve();+ expect(session.writes).toEqual(["EARLY" + ENTER]);++ session.finish(0);+ await started;+ });+});diff --git a/packages/adapter-utils/src/setup-token-transport.ts b/packages/adapter-utils/src/setup-token-transport.tsnew file mode 100644index 0000000000..af8b0c856c--- /dev/null+++ b/packages/adapter-utils/src/setup-token-transport.ts@@ -0,0 +1,146 @@+// The setup-token pseudo-terminal transport. It gives the Claude `setup-token`+// login runner a child that runs on a real pseudo-terminal (PTY). The command+// needs a PTY: pipe stdio emits no login prompt. The transport starts the+// command on a PTY, streams the incremental terminal output, delivers delayed+// input, and stops the child for a terminal state.+//+// This module is provider-agnostic and pure. It holds no Node built-in import,+// so the browser-safe root entry can re-export it. A sandbox provider (for+// example the Daytona plugin) opens the concrete pseudo-terminal through a+// {@link SetupTokenPtySessionOpener}. A unit test opens a fake pseudo-terminal+// through the same opener.+//+// Boundary (ANSI and OSC 8): the transport forwards the raw terminal bytes+// unchanged. It runs no ANSI or OSC 8 handling. The setup-token parser owns that+// handling, so the transport keeps every terminal byte intact for the parser.++/**+ * A live pseudo-terminal session for one setup-token login command. A sandbox+ * provider opens it. The session allocates a real pseudo-terminal, streams the+ * raw terminal output, accepts delayed input, and stops the child. The session+ * forwards the raw terminal bytes; it runs no ANSI or OSC 8 handling.+ */+export interface SetupTokenPtySession {+ /**+ * Registers the one output listener. The session streams each raw terminal+ * output chunk to `listener`, in order, as the pseudo-terminal emits it.+ */+ onData(listener: (chunk: string) => void): void;+ /**+ * Writes raw input bytes to the pseudo-terminal. The runner writes the browser+ * code plus the Enter byte here, after the command starts. The session+ * forwards the bytes unchanged, so the code reaches the pseudo-terminal first+ * and the Enter byte reaches it last.+ */+ write(data: string): void;+ /** Resolves with the child exit code when the command ends. */+ wait(): Promise<{ exitCode: number | null }>;+ /**+ * Stops the child process with a direct child stop. The characterization+ * showed that the child needs `SIGKILL`. The method must be safe to call more+ * than one time.+ */+ kill(): void;+ /** Releases the session resources. The method must be safe to call more than one time. */+ close(): Promise<void>;+}++/**+ * Opens a pseudo-terminal session for `command`. A provider binds this to its+ * sandbox. The transport calls it one time, on start.+ */+export type SetupTokenPtySessionOpener = (command: string) => Promise<SetupTokenPtySession>;++/**+ * The child side of the setup-token run, in the shape the login runner needs.+ * The transport starts the command on a pseudo-terminal, streams the terminal+ * output, delivers delayed input, and stops the child for a terminal state.+ *+ * The shape matches the runner `SetupTokenPtyDriver` interface, so the runner+ * accepts the transport with no adapter. The transport never imports the runner,+ * so the runner package keeps its one-way dependency on this package.+ */+export interface SetupTokenPtyTransport {+ /**+ * Opens the pseudo-terminal session for `command` and streams the terminal+ * output to `onData` in order. Resolves with the child exit code when the+ * command ends. The transport calls this one time.+ */+ start(command: string, onData: (chunk: string) => void): Promise<{ exitCode: number | null }>;+ /**+ * Writes `input` to the pseudo-terminal. The runner writes the browser code+ * plus the Enter byte one time, after it matches the prompt. An input that+ * arrives before the session opens waits in a small buffer, and the transport+ * flushes it in order when the session opens.+ */+ write(input: string): void;+ /**+ * Stops the child with a direct child stop. The method is safe to call before+ * start and safe to call more than one time. A stop before the session opens+ * marks the run, and the transport kills the child as soon as the session+ * opens.+ */+ stop(): void;+ /** Releases the transport resources. The method is safe to call more than one time. */+ dispose(): Promise<void>;+}++/**+ * Creates a {@link SetupTokenPtyTransport} over `open`. The transport adapts a+ * pseudo-terminal session into the runner driver shape. It buffers an early+ * input write, it honors an early stop, and it forwards the raw terminal bytes+ * with no ANSI or OSC 8 handling.+ */+export function createSetupTokenPtyTransport(+ open: SetupTokenPtySessionOpener,+): SetupTokenPtyTransport {+ let session: SetupTokenPtySession | null = null;+ let started = false;+ let stopped = false;+ // Input that the runner writes before the session opens. The transport flushes+ // it in order when the session opens. In the normal flow the runner writes+ // only after the first output, so this buffer stays empty.+ const pendingInput: string[] = [];++ const flushPendingInput = (): void => {+ if (!session) return;+ while (pendingInput.length > 0) {+ const next = pendingInput.shift();+ if (next !== undefined) session.write(next);+ }+ };++ return {+ async start(command, onData): Promise<{ exitCode: number | null }> {+ if (started) {+ throw new Error("setup-token PTY transport already started.");+ }+ started = true;+ const opened = await open(command);+ session = opened;+ // Register the output listener before any delayed input, so no output+ // chunk is missed between the open and the first write.+ opened.onData(onData);+ flushPendingInput();+ // A stop that arrived while the session was opening kills the child now.+ if (stopped) opened.kill();+ return opened.wait();+ },+ write(input): void {+ if (session) {+ session.write(input);+ return;+ }+ pendingInput.push(input);+ },+ stop(): void {+ stopped = true;+ session?.kill();+ },+ async dispose(): Promise<void> {+ // Release only a session that opened. A run that stopped before start+ // opens no session, so there is nothing to close.+ if (session) await session.close();+ },+ };+}diff --git a/packages/adapters/claude-local/src/server/__fixtures__/setup-token-success.md b/packages/adapters/claude-local/src/server/__fixtures__/setup-token-success.mdnew file mode 100644index 0000000000..fddd92f71b--- /dev/null+++ b/packages/adapters/claude-local/src/server/__fixtures__/setup-token-success.md@@ -0,0 +1,155 @@+# Claude `setup-token` success characterization fixture++- Characterized: 2026-08-12+- Claude Code: `2.1.205`+- Environment: Daytona sandbox (Ubuntu, kernel 6.8), headless, no browser.+- Intended repository path: `packages/adapters/claude-local/src/server/__fixtures__/setup-token-success.md`+- Safety: no real authorization URL, browser code, or token is recorded here. Every+ secret is replaced by a `<REDACTED_*>` placeholder. The raw PTY capture that+ produced this document was written only to a sandbox-local file and shredded+ after redaction.++This fixture resolves the "Deferred success-token assumption" in+[`setup-token.md`](./setup-token.md): it records a real, end-to-end successful+login through a PTY, with the human completing the browser authorization out of+band. It is the success counterpart to that document, which characterized the+prompt, the URL, and the invalid-code retry path only.++## Full successful PTY session++Normalized rendered text (spinner frames, cursor-movement sequences, and other+terminal control sequences omitted; word spacing restored from cursor-forward+sequences):++```text+Welcome to Claude Code v2.1.205++Opening browser to sign in…+<spinner frames>+Browser didn't open? Use the url below to sign in (c to copy)++<REDACTED_AUTHORIZATION_URL>++Paste code here if prompted > <MASKED_CODE>++✓ Long-lived authentication token created successfully!++Your OAuth token (valid for 1 year):++<REDACTED_SETUP_TOKEN>++Store this token securely. You won't be able to see it again.++Use this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=<token>+```++The command reached the success screen and then closed the PTY and exited on its+own — no host-side kill was required (unlike the invalid-code path in+`setup-token.md`, which stayed at a retry UI and had to be terminated).++## Authorization URL shape++Unchanged from `setup-token.md`; confirmed again on the success run:++- Origin: `https://claude.com`+- Path: `/cai/oauth/authorize`+- Query keys (values redacted): `client_id`, `code`, `code_challenge`,+ `code_challenge_method`, `redirect_uri`, `response_type`, `scope`, `state`+- Observed `redirect_uri` value host: `https://platform.claude.com/oauth/code/callback`.+- Observed `scope` value: `user:inference`. Observed `response_type`: `code`.+- Fragment: absent.+- The terminal emits the URL through an OSC 8 hyperlink plus wrapped display+ text; consumers must tolerate ANSI/OSC sequences and line wrapping.++## Code submission mechanics (PTY)++This is the operational detail that a driver must get right, and it is not+obvious from the prompt characterization alone.++- The browser code is the value the sign-in page shows after authorization. Its+ observed shape is `<authorization_code>#<state>` — the `#` delimiter and the+ trailing `state` match the `state` query value from the authorization URL.+- **A single PTY write of `code + "\r"` did not submit.** The Claude Code input+ is an Ink text field with paste handling: when the code and the carriage+ return arrive glued together in one write burst, the trailing `\r` is folded+ into the pasted text instead of being read as a Return (submit) key. The stream+ stalls at the prompt with the code masked but unsubmitted, and no error is+ emitted.+- **A separate, standalone `\r` written after the paste submits on the first+ Return.** The reliable sequence is: write the code bytes, let the paste buffer+ settle briefly, then write `\r` as its own write.+- Echo: input is masked as `*` characters; the code itself is never rendered by+ Claude. (The non-secret `state` suffix may remain visible at the tail of the+ masked echo, because it is public — it is the same `state` carried in the URL.)++> Implementation note for `setup-token-runner.ts`: the runner now writes the+> code and `CODE_SUBMISSION_TERMINATOR` as two separate writes — `driver.write(code)`,+> a short settle delay (`CODE_SUBMIT_SETTLE_MS`), then `driver.write(CODE_SUBMISSION_TERMINATOR)`.+> A single glued `code + "\r"` burst did not submit against this Claude Code+> build: the trailing `\r` folded into the pasted text. The separate Return,+> after the paste buffer settles, submits on the first Return. Confirm the exact+> settle delay in the live end-to-end test.++## Success token shape (resolves the deferred assumption)++The provisional assumption in `setup-token.md` — an opaque token shaped like+`sk-ant-oat01-<opaque>` on the interactive terminal output stream after+successful authorization — is **confirmed**:++- Prefix: `sk-ant-oat01-` (literal; hyphen-delimited segments `sk`, `ant`,+ `oat01`, then the opaque secret).+- The opaque tail is a long secret over the character class `[A-Za-z0-9_-]`; it+ may contain `-`, so a parser must not assume the token stops at the first+ hyphen or non-alphanumeric after the prefix.+- **Line wrapping:** like the authorization URL, the token is wrapped across+ physical terminal lines at the PTY width (an ~80-column PTY split it into two+ lines). A parser must de-wrap — join across the wrap boundary — to recover the+ full token. Capturing with a wide PTY (e.g. many hundreds of columns) avoids+ the split at the source.+- The token is introduced by the exact line `Your OAuth token (valid for 1+ year):` and followed by `Store this token securely. You won't be able to see+ it again.` — these bracket the token region and are stable anchors for a+ parser.++## Token delivery and persistence++- The success token is delivered **only on the interactive terminal (PTY)+ stream.** As with the earlier characterization, stdout/stderr are not+ independently observable once attached to one PTY.+- `claude setup-token` does **not** persist the token. After a successful run:+ - `~/.claude.json` gained no `oauthAccount` and no token-bearing field (it held+ only machine/user metadata: `userID`, `machineID`, migration flags, etc.).+ - No `~/.claude/.credentials.json` was written.+- Therefore the runner must capture the credential from the terminal stream at+ the moment it is printed; there is no on-disk artifact to read afterward, and+ the UI explicitly warns the token cannot be shown again.++## Deferred items now resolved / still open++Resolved by this capture:++- Token prefix, delimiter structure, character class, and line-wrapping behavior.+- Success-screen wording and the anchor lines around the token.+- Delivery channel (terminal-only) and the absence of any persisted credential.+- The self-initiated, no-kill exit on success.+- The PTY code-submission gotcha (glued `code + "\r"` vs. a separate Return).++Still worth confirming in the live end-to-end implementation test before locking+parser/runner assertions:++- The exact process exit code on success. The child reached EOF and exited on its+ own immediately after printing the token (a self-initiated exit consistent with+ success); the capture harness issued its normal post-run stop during cleanup,+ so an exact numeric code was not force-observed here. `setup-token-runner.ts`+ treats `exitCode === 0` as success — assert this against a live run.+- The exact opaque-tail length. It is fixed-format per account but was not pinned+ here to avoid recording token-derived specifics.++## Smallest proof++One PTY harness drove `claude setup-token` to completion: it captured the+redacted authorization URL, a human completed the browser authorization out of+band, the harness typed the returned code and submitted it with a separate+Return, and Claude Code printed a `sk-ant-oat01-…` token and exited on its own. A+literal scan of this document confirms it contains no authorization query values,+browser code, or live token.diff --git a/packages/adapters/claude-local/src/server/__fixtures__/setup-token.md b/packages/adapters/claude-local/src/server/__fixtures__/setup-token.mdnew file mode 100644index 0000000000..88d2f0020b--- /dev/null+++ b/packages/adapters/claude-local/src/server/__fixtures__/setup-token.md@@ -0,0 +1,64 @@+# Claude `setup-token` characterization fixture++- Characterized: 2026-08-11+- Claude Code: `2.1.205`+- Intended repository path: `packages/adapters/claude-local/src/server/__fixtures__/setup-token.md`+- Safety: no real authorization URL, browser code, or token is recorded here.++## Pipe stdio++Invocation: all three child streams were pipes; stdin remained open for 8 seconds, then received a syntactically shaped synthetic code followed by LF (`\+`).++- Exact emitted prompt text: none.+- stdout: 0 bytes.+- stderr: 0 bytes.+- Input echo: none (the pipe path emitted nothing).+- Result: still running after 23 seconds; controlled termination was required.+- Wrapper exit: `124` from `timeout`; direct child termination in the equivalent harness: `SIGKILL` (`-9`).+- Conclusion: `setup-token` requires a PTY to expose and drive its interactive login UI. Supplying pipe stdin alone is insufficient.++## PTY stdio++Normalized rendered text (spinner frames and terminal control sequences omitted):++```text+Welcome to Claude Code v2.1.205+Opening browser to sign in…+Browser didn’t open? Use the url below to sign in (c to copy)+<REDACTED_AUTHORIZATION_URL>+Paste code here if prompted >+```++Authorization URL shape:++- Origin: `https://claude.com`+- Path: `/cai/oauth/authorize`+- Query keys (values redacted): `client_id`, `code`, `code_challenge`, `code_challenge_method`, `redirect_uri`, `response_type`, `scope`, `state`+- Fragment: absent+- The terminal emits the same URL through an OSC 8 hyperlink plus wrapped display text; consumers must tolerate ANSI/OSC sequences and line wrapping.++Code-entry behavior:++- Observed code delimiter: `#`.+- Submission terminator: carriage return/Enter in the PTY; the synthetic pipe attempt used LF.+- Echo: input is masked as `*` characters; the synthetic code itself is not rendered by Claude.+- Prompt stream: the PTY’s terminal output stream (stdout/stderr are not independently observable once attached to one PTY).++Invalid-code result:++```text+OAuth error: Request failed with status code 400+Press Enter to retry.+```++- The invalid code does not make the command exit; it remains at the retry UI.+- Controlled PTY termination: wrapper exit `124`; direct child termination in the harness: `SIGKILL` (`-9`).++## Deferred success-token assumption++No real login or token was captured in this phase. Implementation should provisionally expect an opaque setup token shaped like `sk-ant-oat01-<opaque>` on the interactive terminal output stream after successful authorization. Both the exact prefix/length/delimiters and whether a non-PTY capture classifies the success line as stdout or stderr remain explicit assumptions. Confirm them once in the final live end-to-end implementation test before locking parser assertions.++## Smallest proof++`claude --version`; one pipe harness with a synthetic invalid code; and one PTY harness with bracketed-paste input showed the stream split, redacted URL structure, masked echo, HTTP 400 retry behavior, and controlled terminal exits. A literal scan of this document confirms it contains no authorization query values, browser code, or live token.\ No newline at end of filediff --git a/packages/adapters/claude-local/src/server/index.ts b/packages/adapters/claude-local/src/server/index.tsindex 17fea96235..801923f395 100644--- a/packages/adapters/claude-local/src/server/index.ts+++ b/packages/adapters/claude-local/src/server/index.ts@@ -28,6 +28,41 @@ export {fetchWithTimeout,claudeConfigDir,} from "./quota.js";+// The Claude `setup-token` login parser. It reads the interactive login output+// and returns the authorization URL and the browser-code prompt, or the minted+// OAuth token from the success record. Both functions fail closed and keep every+// input byte out of each log and each thrown error.+export {+ parseSetupTokenPrompt,+ parseSetupTokenCredential,+ SETUP_TOKEN_PROMPT,+ SETUP_TOKEN_URL_ORIGIN,+ SETUP_TOKEN_URL_PATH,+ SETUP_TOKEN_URL_QUERY_KEYS,+ SETUP_TOKEN_PREFIX,+ SETUP_TOKEN_BEFORE_ANCHOR,+ SETUP_TOKEN_AFTER_ANCHOR,+} from "./setup-token-parse.js";+export type { SetupTokenPrompt } from "./setup-token-parse.js";+// The Claude `setup-token` login runner. A server-side factory binds it to a+// sandbox pseudo-terminal driver to drive the two-way login round-trip and to+// deliver the minted token one time in memory.+export {+ runSetupTokenLogin,+ CLAUDE_SETUP_TOKEN_COMMAND,+ CODE_SUBMISSION_TERMINATOR,+ CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS,+ SETUP_TOKEN_CREDENTIAL_RELEASE_GATE,+} from "./setup-token-runner.js";+export type {+ SetupTokenPtyDriver,+ SetupTokenPromptSink,+ SetupTokenCodeProvider,+ SetupTokenCredentialSink,+ SetupTokenOutcome,+ SetupTokenLoginResult,+ RunSetupTokenLoginOptions,+} from "./setup-token-runner.js";import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-utils/acpx-engine/session-codec";diff --git a/packages/adapters/claude-local/src/server/setup-token-parse.test.ts b/packages/adapters/claude-local/src/server/setup-token-parse.test.tsnew file mode 100644index 0000000000..85171dc4b2--- /dev/null+++ b/packages/adapters/claude-local/src/server/setup-token-parse.test.ts@@ -0,0 +1,295 @@+import { readFileSync } from "node:fs";+import path from "node:path";+import { fileURLToPath } from "node:url";+import { describe, expect, it } from "vitest";+import {+ SETUP_TOKEN_AFTER_ANCHOR,+ SETUP_TOKEN_BEFORE_ANCHOR,+ SETUP_TOKEN_PREFIX,+ SETUP_TOKEN_PROMPT,+ SETUP_TOKEN_URL_PATH,+ SETUP_TOKEN_URL_QUERY_KEYS,+ parseSetupTokenCredential,+ parseSetupTokenPrompt,+} from "./setup-token-parse.js";++const fixturesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__");++function readFixture(name: string): string {+ return readFileSync(path.join(fixturesDir, name), "utf8");+}++// A well-formed authorization URL that carries the exact query keys of the+// contract. The values are synthetic; the fixture redacts the real values.+const VALID_URL =+ "https://claude.com/cai/oauth/authorize" ++ "?client_id=cid-000" ++ "&code=redacted" ++ "&code_challenge=chal-000" ++ "&code_challenge_method=S256" ++ "&redirect_uri=https%3A%2F%2Fclaude.com%2Fcallback" ++ "&response_type=code" ++ "&scope=user%3Ainference" ++ "&state=state-000";++// The URL preamble line and the browser-code prompt line, exactly as the+// fixture records them.+const PREAMBLE_LINE = "Browser didn’t open? Use the url below to sign in (c to copy)";+const PROMPT_LINE = "Paste code here if prompted >";++// Builds a complete, plain-text login output around a URL.+function completeOutput(url: string): string {+ return [+ "Welcome to Claude Code v2.1.205",+ "Opening browser to sign in…",+ PREAMBLE_LINE,+ url,+ PROMPT_LINE,+ ].join("\n");+}++// Wraps a URL in an OSC 8 hyperlink. The URI field carries the true URL. The+// display text is a wrapped, truncated form, so the test proves the parser reads+// the URI and not the display text.+function osc8Hyperlink(url: string, display: string): string {+ const ESC = "\x1b";+ return `${ESC}]8;;${url}${ESC}\\${display}${ESC}]8;;${ESC}\\`;+}++describe("parseSetupTokenPrompt", () => {+ it("returns the exact URL and prompt from a complete output", () => {+ const result = parseSetupTokenPrompt(completeOutput(VALID_URL));+ expect(result).not.toBeNull();+ expect(result?.url).toBe(VALID_URL);+ expect(result?.prompt).toBe(SETUP_TOKEN_PROMPT);+ });++ it("returns the URL when the output arrives split across chunks", () => {+ // The streaming caller accumulates chunks and re-parses the whole buffer.+ // The first chunk holds a partial URL, so the parser returns null. The joined+ // buffer holds the whole prompt, so the parser returns the URL.+ const chunkA = ["Opening browser to sign in…", PREAMBLE_LINE, "https://claude.com/cai/oauth/aut"].join(+ "\n",+ );+ const chunkB = ["horize?client_id=cid-000&code=redacted&code_challenge=chal-000&code_challenge_method=S256&redirect_uri=https%3A%2F%2Fclaude.com%2Fcallback&response_type=code&scope=user%3Ainference&state=state-000", PROMPT_LINE, ""].join(+ "\n",+ );+ expect(parseSetupTokenPrompt(chunkA)).toBeNull();+ const joined = parseSetupTokenPrompt(chunkA + chunkB);+ expect(joined).not.toBeNull();+ expect(joined?.url).toBe(VALID_URL);+ expect(joined?.prompt).toBe(SETUP_TOKEN_PROMPT);+ });++ it("reads the URL through ANSI and OSC 8 sequences with wrapped display text", () => {+ const cyan = "\x1b[36m";+ const reset = "\x1b[0m";+ // The display text wraps across two lines and truncates the URL. The parser+ // must ignore it and read the URI field of the hyperlink.+ const wrappedDisplay = "https://claude.com/cai/oauth/aut\nhorize?client_id=cid-000&code=…";+ const text = [+ `${cyan}Opening browser to sign in…${reset}`,+ PREAMBLE_LINE,+ `${cyan}${osc8Hyperlink(VALID_URL, wrappedDisplay)}${reset}`,+ `${cyan}${PROMPT_LINE}${reset}`,+ ].join("\n");+ const result = parseSetupTokenPrompt(text);+ expect(result).not.toBeNull();+ expect(result?.url).toBe(VALID_URL);+ expect(result?.prompt).toBe(SETUP_TOKEN_PROMPT);+ });++ it("returns null for a wrong origin", () => {+ const badOrigin = VALID_URL.replace("https://claude.com", "https://claude.example.com");+ expect(parseSetupTokenPrompt(completeOutput(badOrigin))).toBeNull();+ });++ it("returns null for a wrong path", () => {+ const badPath = VALID_URL.replace(SETUP_TOKEN_URL_PATH, "/cai/oauth/authorise");+ expect(parseSetupTokenPrompt(completeOutput(badPath))).toBeNull();+ });++ it("returns null for a missing query key", () => {+ const missingKey = VALID_URL.replace("&state=state-000", "");+ expect(parseSetupTokenPrompt(completeOutput(missingKey))).toBeNull();+ });++ it("returns null for an extra query key", () => {+ const extraKey = `${VALID_URL}&extra=1`;+ expect(parseSetupTokenPrompt(completeOutput(extraKey))).toBeNull();+ });++ it("returns null for a URL with a fragment", () => {+ const withFragment = `${VALID_URL}#section`;+ expect(parseSetupTokenPrompt(completeOutput(withFragment))).toBeNull();+ });++ it("returns null when a code-like value sits on the line after the URL", () => {+ // The line right after the URL must hold the browser-code prompt. A code-like+ // value on that line cannot bind, so the parser returns null.+ const text = [PREAMBLE_LINE, VALID_URL, "ABCD-EFGHJ", PROMPT_LINE].join("\n");+ expect(parseSetupTokenPrompt(text)).toBeNull();+ });++ it("returns null when the URL is absent from the login context", () => {+ const text = [PREAMBLE_LINE, "no url here", PROMPT_LINE].join("\n");+ expect(parseSetupTokenPrompt(text)).toBeNull();+ });++ it("returns null when the login preamble is absent", () => {+ const text = ["Some unrelated output", VALID_URL, PROMPT_LINE].join("\n");+ expect(parseSetupTokenPrompt(text)).toBeNull();+ });++ it("returns null for an API-key-shaped URL value", () => {+ const withKey = VALID_URL.replace("code=redacted", "code=sk-ant-oat01-abc123");+ expect(parseSetupTokenPrompt(completeOutput(withKey))).toBeNull();+ });++ it("returns null for a non-string input", () => {+ expect(parseSetupTokenPrompt(undefined as unknown as string)).toBeNull();+ expect(parseSetupTokenPrompt("")).toBeNull();+ });++ it("keeps its contract in sync with the characterization fixture", () => {+ // The fixture documents the prompt text, the URL path, and the query keys.+ // This test fails if the parser contract drifts from the fixture.+ const fixture = readFixture("setup-token.md");+ expect(fixture).toContain(SETUP_TOKEN_PROMPT);+ expect(fixture).toContain(SETUP_TOKEN_URL_PATH);+ for (const key of SETUP_TOKEN_URL_QUERY_KEYS) {+ expect(fixture).toContain(`\`${key}\``);+ }+ });+});++// A synthetic OAuth token. The terminal wraps a real token across two physical+// lines at the pseudo-terminal width. The two fragments join with no separator+// to form the full token. The tail carries a `-` and a `_`, so the test proves+// the parser does not stop at the first hyphen. No real token is present.+const TOKEN_FRAGMENT_A = `${SETUP_TOKEN_PREFIX}AAAABBBBCCCCDDDDEEEE1111`;+const TOKEN_FRAGMENT_B = "2222FFFFGGGG_HHHH-IIII";+const FULL_TOKEN = `${TOKEN_FRAGMENT_A}${TOKEN_FRAGMENT_B}`;++// Builds the success screen around a token body. The body holds the token+// fragment lines, already split the way the terminal wraps them.+function successScreen(body: string[]): string {+ return [+ "✓ Long-lived authentication token created successfully!",+ "",+ SETUP_TOKEN_BEFORE_ANCHOR,+ "",+ ...body,+ "",+ SETUP_TOKEN_AFTER_ANCHOR,+ "",+ "Use this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=<token>",+ ].join("\n");+}++describe("parseSetupTokenCredential", () => {+ it("returns the de-wrapped token from the exact success record once", () => {+ const text = successScreen([TOKEN_FRAGMENT_A, TOKEN_FRAGMENT_B]);+ expect(parseSetupTokenCredential(text)).toBe(FULL_TOKEN);+ });++ it("returns a single-line token from the success record", () => {+ const text = successScreen([FULL_TOKEN]);+ expect(parseSetupTokenCredential(text)).toBe(FULL_TOKEN);+ });++ it("reads the token through ANSI color sequences", () => {+ const cyan = "\x1b[36m";+ const reset = "\x1b[0m";+ const text = successScreen([`${cyan}${TOKEN_FRAGMENT_A}`, `${TOKEN_FRAGMENT_B}${reset}`]);+ expect(parseSetupTokenCredential(text)).toBe(FULL_TOKEN);+ });++ it("returns null for a token-shaped value before submit", () => {+ // The prompt screen holds a token-shaped value but no success anchors. The+ // parser fails closed, so an early value never delivers.+ const text = [+ "Browser didn’t open? Use the url below to sign in (c to copy)",+ VALID_URL,+ "Paste code here if prompted >",+ FULL_TOKEN,+ ].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a token-shaped value in retry or error text", () => {+ const text = [+ "Invalid code. Please try again.",+ `error context ${FULL_TOKEN} more context`,+ "Paste code here if prompted >",+ ].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a token-shaped value after cancellation", () => {+ const text = ["Login cancelled.", FULL_TOKEN, "Goodbye."].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null when extra text sits on the token line", () => {+ // The token line holds the token and extra prose. The parser reads only a+ // token fragment on each line, so it fails closed.+ const text = successScreen([`${FULL_TOKEN} keep this secret`]);+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null when a prose line sits between the anchors", () => {+ const text = successScreen([TOKEN_FRAGMENT_A, "a stray note", TOKEN_FRAGMENT_B]);+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a duplicate success block", () => {+ const text = `${successScreen([FULL_TOKEN])}\n${successScreen([FULL_TOKEN])}`;+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null when the after-anchor comes before the before-anchor", () => {+ const text = [+ SETUP_TOKEN_AFTER_ANCHOR,+ "",+ FULL_TOKEN,+ "",+ SETUP_TOKEN_BEFORE_ANCHOR,+ ].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null when the before-anchor is absent", () => {+ const text = [FULL_TOKEN, "", SETUP_TOKEN_AFTER_ANCHOR].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null when the after-anchor is absent", () => {+ const text = [SETUP_TOKEN_BEFORE_ANCHOR, "", FULL_TOKEN].join("\n");+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a wrong token prefix between the anchors", () => {+ const text = successScreen(["sk-ant-api03-AAAABBBBCCCCDDDDEEEE1111"]);+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a bare prefix with no opaque tail", () => {+ const text = successScreen([SETUP_TOKEN_PREFIX]);+ expect(parseSetupTokenCredential(text)).toBeNull();+ });++ it("returns null for a non-string input", () => {+ expect(parseSetupTokenCredential(undefined as unknown as string)).toBeNull();+ expect(parseSetupTokenCredential("")).toBeNull();+ });++ it("keeps its token contract in sync with the success fixture", () => {+ // The success fixture records the anchor lines and the token prefix. This+ // test fails if the token parser contract drifts from the fixture.+ const fixture = readFixture("setup-token-success.md");+ expect(fixture).toContain(SETUP_TOKEN_BEFORE_ANCHOR);+ expect(fixture).toContain(SETUP_TOKEN_AFTER_ANCHOR);+ expect(fixture).toContain(SETUP_TOKEN_PREFIX);+ });+});diff --git a/packages/adapters/claude-local/src/server/setup-token-parse.ts b/packages/adapters/claude-local/src/server/setup-token-parse.tsnew file mode 100644index 0000000000..0ad6b14bd5--- /dev/null+++ b/packages/adapters/claude-local/src/server/setup-token-parse.ts@@ -0,0 +1,330 @@+// The Claude `setup-token` parsers. They read the interactive login output of+// Claude Code. `parseSetupTokenPrompt` returns the authorization URL and the+// browser-code prompt, or null. `parseSetupTokenCredential` returns the minted+// OAuth token from the success screen, or null.+//+// Security (strict validation): the prompt parser accepts only the exact origin+// and path of the authorization URL, and only the exact set of query keys. It+// rejects any other origin, path, query, or fragment. It binds the browser-code+// prompt to a dedicated line right after the URL line, so an unrelated code-like+// value on the wrong line cannot form a prompt. It rejects an API-key-shaped+// value inside the URL.+//+// The token parser binds the token to the exact success record: it requires the+// before-anchor line and the after-anchor line, in that order, exactly one time+// each, and it reads only the lines between them. It de-wraps the token across+// the physical terminal lines. It fails closed for any other input. Both parsers+// never log any input byte, and they keep every input byte out of each thrown+// error. Both parsers are pure functions.++export interface SetupTokenPrompt {+ // The validated authorization URL, exactly as the terminal emitted it.+ url: string;+ // The canonical browser-code prompt. The parser returns the constant+ // {@link SETUP_TOKEN_PROMPT}, so the output is never a caller-controlled value.+ prompt: string;+}++// The canonical browser-code prompt text. The Claude login UI prints this line+// to ask the user to paste the code from the browser. The parser returns this+// exact constant on a match.+export const SETUP_TOKEN_PROMPT = "Paste code here if prompted";++// The one and only accepted authorization URL origin.+export const SETUP_TOKEN_URL_ORIGIN = "https://claude.com";++// The one and only accepted authorization URL path.+export const SETUP_TOKEN_URL_PATH = "/cai/oauth/authorize";++// The exact set of query keys of the authorization URL. The parser accepts the+// URL only when its query keys equal this set: no missing key, no extra key, and+// no duplicate key. The parser does not validate the query values, because the+// values are the real OAuth PKCE parameters that the user must visit.+export const SETUP_TOKEN_URL_QUERY_KEYS = [+ "client_id",+ "code",+ "code_challenge",+ "code_challenge_method",+ "redirect_uri",+ "response_type",+ "scope",+ "state",+] as const;++// An ANSI Control Sequence Introducer (CSI): the ESC control byte, a `[`, zero+// or more parameter bytes (0x30-0x3F), zero or more intermediate bytes+// (0x20-0x2F), and one final byte (0x40-0x7E). The Claude terminal wraps the+// output in CSI color sequences. The parser removes every CSI sequence first, so+// a colored prompt reads the same as a plain one.+// eslint-disable-next-line no-control-regex+const ANSI_CSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;++// An OSC 8 hyperlink. The terminal emits the URL through an OSC 8 hyperlink plus+// wrapped display text. The hyperlink carries the true, unwrapped URL in its URI+// field, while the display text may wrap across lines. The parser replaces the+// whole hyperlink (open sequence, display text, close sequence) with the URI, so+// it reads the unwrapped URL and drops the wrapped display text. The URI field+// is the first capture group. The terminator of each OSC sequence is the String+// Terminator (ESC `\`) or the BEL byte.+// eslint-disable-next-line no-control-regex+const OSC8_HYPERLINK_RE =+ /\x1b\]8;[^;\x1b\x07]*;([^\x1b\x07]*)(?:\x1b\\|\x07)[\s\S]*?\x1b\]8;[^;\x1b\x07]*;(?:\x1b\\|\x07)/g;++// Any remaining OSC sequence. A partial output chunk can hold an OSC 8 open+// sequence without its close sequence. The parser removes each leftover OSC+// sequence after it replaces the complete hyperlinks.+// eslint-disable-next-line no-control-regex+const OSC_ANY_RE = /\x1b\][^\x1b\x07]*(?:\x1b\\|\x07)/g;++// A candidate URL token: a run of non-space characters that starts with an http+// or https scheme. The parser validates each candidate with the `URL` class; the+// regular expression only splits tokens out of the text.+const URL_TOKEN_RE = /https?:\/\/\S+/g;++// Trailing punctuation that prose commonly puts right after a URL. The parser+// strips only these characters. It never strips `?` or `#`, so a URL with a+// stray query or a fragment stays malformed and the parser rejects it.+const TRAILING_PUNCTUATION_RE = /[)\].,;:!]+$/;++// The line that introduces the URL. The Claude login UI prints this phrase right+// before the URL. The parser anchors the URL search on this phrase, so a URL far+// from the login context cannot bind.+const URL_PREAMBLE_RE = /the url below to sign in/i;++// The browser-code prompt on a dedicated line. The line starts with the exact+// prompt phrase. The line can end with the input caret `>` and masked echo `*`+// characters and spaces. The pattern rejects the phrase when other prose shares+// the line.+const PROMPT_LINE_RE = /^Paste code here if prompted\b[\s>*]*$/;++// An API-key-shaped value. The Claude setup token and API key start with the+// `sk-ant-` prefix. The parser rejects a URL that embeds such a value, so a+// secret cannot ride inside the authorization URL.+const API_KEY_RE = /sk-ant-[a-z0-9-]{2,}/i;++// The maximum number of characters between the end of the URL preamble line and+// the start of the URL. The Claude UI prints the URL right after the preamble.+// The parser looks for the URL only inside this window, so a URL far from the+// preamble cannot bind.+const MAX_PREAMBLE_TO_URL_GAP = 512;++// The maximum number of characters after the end of the URL line that the parser+// reads for the browser-code prompt. The Claude UI prints the prompt one line+// after the URL. The window is large enough for the real prompt line and small+// enough to reject distant noise.+const MAX_URL_TO_PROMPT_GAP = 256;++// The result of a URL search: the validated URL and the index of the first+// character after the matched URL token in the search window.+interface SetupTokenUrlMatch {+ url: string;+ end: number;+}++/**+ * Removes the terminal control sequences from `text`. Replaces each OSC 8+ * hyperlink with its true URI, so the parser reads the unwrapped URL and drops+ * the wrapped display text. Removes each leftover OSC sequence and each ANSI CSI+ * sequence. Returns plain text. The function only normalizes the input; the URL+ * and the prompt still pass the strict validation below.+ */+function stripTerminalControls(text: string): string {+ return text+ .replace(OSC8_HYPERLINK_RE, "$1")+ .replace(OSC_ANY_RE, "")+ .replace(ANSI_CSI_RE, "");+}++/**+ * Returns the slice of `text` that starts at `start` and holds at most+ * `maxLength` characters. The parser uses this window to bound a gap between two+ * anchors, so a distant match cannot bind.+ */+function gapWindow(text: string, start: number, maxLength: number): string {+ return text.slice(start, start + maxLength);+}++/**+ * Returns true when the query keys of `parsed` equal+ * {@link SETUP_TOKEN_URL_QUERY_KEYS} exactly: no missing key, no extra key, and+ * no duplicate key.+ */+function hasExactQueryKeys(parsed: URL): boolean {+ const keys = [...parsed.searchParams.keys()];+ if (keys.length !== SETUP_TOKEN_URL_QUERY_KEYS.length) return false;+ const seen = new Set(keys);+ if (seen.size !== keys.length) return false;+ return SETUP_TOKEN_URL_QUERY_KEYS.every((key) => seen.has(key));+}++/**+ * Returns the authorization URL and its end index when `window` holds it with+ * the exact origin {@link SETUP_TOKEN_URL_ORIGIN}, the exact path+ * {@link SETUP_TOKEN_URL_PATH}, the exact query keys, no fragment, and no+ * credentials. Rejects a URL that embeds an API-key-shaped value. Returns null+ * otherwise. The `end` index is the position of the first character after the+ * matched token in `window`.+ */+function findExactUrl(window: string): SetupTokenUrlMatch | null {+ for (const match of window.matchAll(URL_TOKEN_RE)) {+ const token = match[0];+ if (API_KEY_RE.test(token)) continue;+ const cleaned = token.replace(TRAILING_PUNCTUATION_RE, "");+ let parsed: URL;+ try {+ parsed = new URL(cleaned);+ } catch {+ continue;+ }+ if (+ parsed.protocol === "https:" &&+ parsed.host === "claude.com" &&+ parsed.pathname === SETUP_TOKEN_URL_PATH &&+ parsed.hash === "" &&+ parsed.username === "" &&+ parsed.password === "" &&+ hasExactQueryKeys(parsed)+ ) {+ return { url: cleaned, end: (match.index ?? 0) + token.length };+ }+ }+ return null;+}++/**+ * Returns the canonical browser-code prompt when `text` holds it on a dedicated+ * line after the URL line. The parser advances past the URL line to the first+ * newline, then reads the first non-blank line inside a window after it. That+ * line must match the exact prompt shape. So the prompt binds to the dedicated+ * line that the UI prints right after the URL. A code-like value on that line, or+ * the prompt phrase mixed with other prose, cannot bind. Returns null when the+ * URL line has no line break after it, or when the first non-blank line is not+ * the prompt.+ */+function findBrowserCodePrompt(text: string, urlEnd: number): string | null {+ const lineBreak = text.indexOf("\n", urlEnd);+ if (lineBreak === -1) return null;+ const window = gapWindow(text, lineBreak + 1, MAX_URL_TO_PROMPT_GAP);+ for (const line of window.split("\n")) {+ const trimmed = line.trim();+ if (trimmed.length === 0) continue;+ return PROMPT_LINE_RE.test(trimmed) ? SETUP_TOKEN_PROMPT : null;+ }+ return null;+}++/**+ * Parses Claude `setup-token` login output. Removes ANSI CSI sequences and OSC 8+ * hyperlink sequences first, so colored and hyperlinked output reads the same as+ * plain output. The parser finds the URL preamble, then the exact authorization+ * URL inside a window after the preamble, then the browser-code prompt on the+ * dedicated line after the URL line. So the URL binds to the login context and+ * the prompt binds to the URL. Returns the authorization URL and the browser-code+ * prompt when both are present and valid. Returns null for any other input,+ * including a non-string input, an absent preamble, a URL with a wrong origin,+ * path, query, or fragment, an API-key-shaped URL, and a missing or misplaced+ * prompt. Never throws on input, and never puts any input byte into a log or an+ * error. This phase returns no token.+ */+export function parseSetupTokenPrompt(text: string): SetupTokenPrompt | null {+ if (typeof text !== "string" || text.length === 0) return null;+ const clean = stripTerminalControls(text);+ const preamble = URL_PREAMBLE_RE.exec(clean);+ if (!preamble) return null;+ const afterPreamble = preamble.index + preamble[0].length;+ const urlWindow = gapWindow(clean, afterPreamble, MAX_PREAMBLE_TO_URL_GAP);+ const urlMatch = findExactUrl(urlWindow);+ if (!urlMatch) return null;+ const urlEnd = afterPreamble + urlMatch.end;+ const prompt = findBrowserCodePrompt(clean, urlEnd);+ if (!prompt) return null;+ return { url: urlMatch.url, prompt };+}++// --- The success token parser ------------------------------------------------++// The literal prefix of the Claude setup-token OAuth token. The success screen+// prints a token that starts with this exact prefix. The opaque tail follows.+export const SETUP_TOKEN_PREFIX = "sk-ant-oat01-";++// The line that introduces the token. The success screen prints this exact line+// right before the token block. The token parser binds the token to this anchor.+export const SETUP_TOKEN_BEFORE_ANCHOR = "Your OAuth token (valid for 1 year):";++// The line that follows the token. The success screen prints this exact line+// right after the token block. The token parser binds the token to this anchor.+export const SETUP_TOKEN_AFTER_ANCHOR =+ "Store this token securely. You won't be able to see it again.";++// One physical line of the token. The terminal wraps the token at the+// pseudo-terminal width, so one physical line holds one fragment of the token+// character class. The token character class is `[A-Za-z0-9_-]`; the opaque tail+// can contain `-`, so a line fragment can contain `-`.+const TOKEN_FRAGMENT_RE = /^[A-Za-z0-9_-]+$/;++// The full token shape after the parser joins the wrapped fragments. The token+// starts with the exact prefix and continues over the token character class. The+// minimum tail length rejects a bare prefix and a short, noisy candidate. A real+// opaque tail is far longer than this floor.+const FULL_TOKEN_RE = /^sk-ant-oat01-[A-Za-z0-9_-]{20,}$/;++/**+ * Returns the index of the one line that equals `anchor` after a trim. Returns+ * null when no line matches. Returns null when more than one line matches, so a+ * duplicate success block fails closed.+ */+function singleAnchorIndex(lines: string[], anchor: string): number | null {+ let found: number | null = null;+ for (let i = 0; i < lines.length; i += 1) {+ if (lines[i].trim() !== anchor) continue;+ if (found !== null) return null;+ found = i;+ }+ return found;+}++/**+ * Parses the Claude `setup-token` success screen and returns the minted OAuth+ * token, or null. The parser removes the terminal control sequences first, then+ * binds the token to the exact success record. It requires the before-anchor+ * line {@link SETUP_TOKEN_BEFORE_ANCHOR} and the after-anchor line+ * {@link SETUP_TOKEN_AFTER_ANCHOR}, in that order, exactly one time each. It+ * reads only the lines between the two anchors. It de-wraps the token: it joins+ * the fragment lines with no separator, the same way the terminal split one+ * token across the physical lines. It validates the joined value against the+ * token shape.+ *+ * The parser fails closed for any other input. It returns null for a+ * token-shaped value outside the two anchors (before submit, in retry or error+ * text, or after a cancellation), a duplicate success block, an anchor out of+ * order, a missing anchor, extra text on a token line, a stray prose line+ * between the anchors, a wrong prefix, and a value that does not match the token+ * shape. It never logs any input byte and never puts any input byte into a+ * thrown error. The parser is a pure function.+ */+export function parseSetupTokenCredential(text: string): string | null {+ if (typeof text !== "string" || text.length === 0) return null;+ const clean = stripTerminalControls(text);+ const lines = clean.split("\n");++ const beforeIndex = singleAnchorIndex(lines, SETUP_TOKEN_BEFORE_ANCHOR);+ const afterIndex = singleAnchorIndex(lines, SETUP_TOKEN_AFTER_ANCHOR);+ if (beforeIndex === null || afterIndex === null) return null;+ if (afterIndex <= beforeIndex) return null;++ // Read only the non-blank lines strictly between the two anchors. Each line+ // must be one token fragment. A stray prose line, or extra text on a token+ // line, fails the fragment test and the parser returns null.+ const fragments: string[] = [];+ for (let i = beforeIndex + 1; i < afterIndex; i += 1) {+ const trimmed = lines[i].trim();+ if (trimmed.length === 0) continue;+ if (!TOKEN_FRAGMENT_RE.test(trimmed)) return null;+ fragments.push(trimmed);+ }+ if (fragments.length === 0) return null;++ const token = fragments.join("");+ if (!FULL_TOKEN_RE.test(token)) return null;+ return token;+}diff --git a/packages/adapters/claude-local/src/server/setup-token-runner.test.ts b/packages/adapters/claude-local/src/server/setup-token-runner.test.tsnew file mode 100644index 0000000000..7e4cd2db2e--- /dev/null+++ b/packages/adapters/claude-local/src/server/setup-token-runner.test.ts@@ -0,0 +1,319 @@+import { describe, expect, it, vi } from "vitest";+import { SETUP_TOKEN_PROMPT } from "./setup-token-parse.js";+import {+ CLAUDE_SETUP_TOKEN_COMMAND,+ CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS,+ CODE_SUBMISSION_TERMINATOR,+ runSetupTokenLogin,+ type SetupTokenPtyDriver,+} from "./setup-token-runner.js";++// A well-formed authorization URL. The query keys match the contract exactly.+// The values are synthetic; no real value is present.+const VALID_URL =+ "https://claude.com/cai/oauth/authorize?client_id=cid&code=abc&code_challenge=chal&code_challenge_method=S256&redirect_uri=https%3A%2F%2Fexample.test%2Fcb&response_type=code&scope=user&state=st";++// The rendered login output. The preamble line, the URL line, and the dedicated+// prompt line match the Phase 2 parser contract.+const PROMPT_OUTPUT = [+ "Welcome to Claude Code",+ "Opening browser to sign in…",+ "Browser didn't open? Use the url below to sign in (c to copy)",+ VALID_URL,+ "Paste code here if prompted >",+ "",+].join("\n");++// A synthetic browser code. No test log, result, error, or metadata field may+// contain this value.+const BROWSER_CODE = "SENTINEL-CODE-9182";++// A synthetic OAuth token, wrapped across two physical lines the way the+// terminal wraps a real token. No real token is present.+const TOKEN_FRAGMENT_A = "sk-ant-oat01-AAAABBBBCCCCDDDDEEEE1111";+const TOKEN_FRAGMENT_B = "2222FFFFGGGG_HHHH-IIII";+const FULL_TOKEN = `${TOKEN_FRAGMENT_A}${TOKEN_FRAGMENT_B}`;++// The rendered success screen. The anchor lines bracket the wrapped token, the+// same way the Phase 6a success record records them.+const SUCCESS_OUTPUT = [+ "✓ Long-lived authentication token created successfully!",+ "",+ "Your OAuth token (valid for 1 year):",+ "",+ TOKEN_FRAGMENT_A,+ TOKEN_FRAGMENT_B,+ "",+ "Store this token securely. You won't be able to see it again.",+ "",+].join("\n");++interface FakeDriverOptions {+ // The chunks the driver streams to the runner in order.+ chunks?: string[];+ // The exit code the driver returns at once. When absent, the driver waits for+ // the test to resolve the exit, or for the runner to time out or cancel.+ exitCode?: number;+ // An error the driver throws from start(), to model a stream failure.+ startError?: Error;+}++function createFakeDriver(options: FakeDriverOptions = {}) {+ const writes: string[] = [];+ const stops = { count: 0 };+ const disposes = { count: 0 };+ let resolveExit: (exit: { exitCode: number | null }) => void = () => {};+ const exitPromise = new Promise<{ exitCode: number | null }>((resolve) => {+ resolveExit = resolve;+ });+ const driver: SetupTokenPtyDriver = {+ async start(_command, onData) {+ if (options.startError) throw options.startError;+ for (const chunk of options.chunks ?? []) {+ onData(chunk);+ }+ if (options.exitCode !== undefined) {+ return { exitCode: options.exitCode };+ }+ return exitPromise;+ },+ write(input) {+ writes.push(input);+ },+ stop() {+ stops.count += 1;+ },+ async dispose() {+ disposes.count += 1;+ },+ };+ return { driver, writes, stops, disposes, resolveExit: (code: number) => resolveExit({ exitCode: code }) };+}++// Lets the pending microtasks run, so the code-input routine writes to the PTY.+async function flush(): Promise<void> {+ await new Promise((resolve) => setTimeout(resolve, 0));+}++describe("runSetupTokenLogin", () => {+ it("sends one login URL through onPrompt", async () => {+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT], exitCode: 0 });+ const onPrompt = vi.fn();+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt,+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ });+ expect(result.outcome).toBe("success");+ expect(result.promptSurfaced).toBe(true);+ expect(onPrompt).toHaveBeenCalledTimes(1);+ expect(onPrompt).toHaveBeenCalledWith({ url: VALID_URL, prompt: SETUP_TOKEN_PROMPT });+ });++ it("accepts one browser code and sends it to the prompt", async () => {+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT] });+ const onPrompt = vi.fn();+ const provideCode = vi.fn(async () => BROWSER_CODE);+ const promise = runSetupTokenLogin(fake.driver, {+ onPrompt,+ provideCode,+ timeoutMs: 1000,+ codeSubmitSettleMs: 0,+ });+ await flush();+ // The runner writes the code once, only after it matches the prompt. It writes+ // the code and the terminator as two separate writes, so the terminator reads+ // as a distinct Return key against an Ink paste field.+ expect(provideCode).toHaveBeenCalledTimes(1);+ expect(fake.writes).toEqual([BROWSER_CODE, CODE_SUBMISSION_TERMINATOR]);+ fake.resolveExit(0);+ const result = await promise;+ expect(result.outcome).toBe("success");+ expect(result.codeSubmitted).toBe(true);+ });++ it("never writes the code before it matches the prompt", async () => {+ // The driver streams noise with no prompt, then exits. The runner must never+ // send the code, because it never matched the prompt.+ const fake = createFakeDriver({ chunks: ["unrelated output\n"], exitCode: 0 });+ const provideCode = vi.fn(async () => BROWSER_CODE);+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode,+ timeoutMs: 1000,+ });+ expect(result.promptSurfaced).toBe(false);+ expect(result.codeSubmitted).toBe(false);+ expect(provideCode).not.toHaveBeenCalled();+ expect(fake.writes).toEqual([]);+ });++ it("stops the process on a timeout", async () => {+ const fake = createFakeDriver();+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 20,+ });+ expect(result.outcome).toBe("timeout");+ expect(fake.stops.count).toBe(1);+ expect(fake.disposes.count).toBe(1);+ });++ it("stops the process on a cancellation", async () => {+ const fake = createFakeDriver();+ const controller = new AbortController();+ const promise = runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 5000,+ signal: controller.signal,+ });+ controller.abort();+ const result = await promise;+ expect(result.outcome).toBe("cancelled");+ expect(fake.stops.count).toBe(1);+ expect(fake.disposes.count).toBe(1);+ });++ it("stops the process on a nonzero exit", async () => {+ const fake = createFakeDriver({ exitCode: 7 });+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ });+ expect(result.outcome).toBe("failure");+ expect(result.exitCode).toBe(7);+ expect(fake.stops.count).toBe(1);+ expect(fake.disposes.count).toBe(1);+ });++ it("keeps the code out of every log, result, and error field", async () => {+ const logs: string[] = [];+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT], exitCode: 0 });+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ log: (line) => {+ logs.push(line);+ },+ });+ const haystack = `${logs.join("\n")}\n${JSON.stringify(result)}`;+ expect(haystack).not.toContain(BROWSER_CODE);+ expect(haystack).not.toContain(VALID_URL);+ });++ it("keeps the code out of the thrown error on a stream failure", async () => {+ const fake = createFakeDriver({+ startError: new Error(`stream failure with ${VALID_URL} ${BROWSER_CODE}`),+ });+ let caught: unknown;+ try {+ await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ });+ } catch (error) {+ caught = error;+ }+ expect(caught).toBeInstanceOf(Error);+ const message = (caught as Error).message;+ expect(message).not.toContain(VALID_URL);+ expect(message).not.toContain(BROWSER_CODE);+ expect(fake.stops.count).toBe(1);+ expect(fake.disposes.count).toBe(1);+ });++ it("parses an early prompt inside one large chunk before truncation", async () => {+ // One chunk holds the prompt at its start and a large volume of output after+ // it. The chunk is larger than the retained-buffer limit. The runner parses+ // the whole chunk before it trims the retained window, so it still finds the+ // early prompt and never drops it.+ const trailingNoise = "unrelated output line\n".repeat(+ Math.ceil(CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS / 10),+ );+ const fake = createFakeDriver({ chunks: [`${PROMPT_OUTPUT}${trailingNoise}`], exitCode: 0 });+ const onPrompt = vi.fn();+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt,+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ });+ expect(result.promptSurfaced).toBe(true);+ expect(onPrompt).toHaveBeenCalledTimes(1);+ expect(onPrompt).toHaveBeenCalledWith({ url: VALID_URL, prompt: SETUP_TOKEN_PROMPT });+ });++ it("delivers no token when the success stream has no token block", async () => {+ // The stream holds only the prompt, so the token parser binds nothing. The+ // runner delivers no credential and reports credentialDelivered false.+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT], exitCode: 0 });+ const onCredential = vi.fn();+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ onCredential,+ timeoutMs: 1000,+ });+ expect(result.outcome).toBe("success");+ expect(onCredential).not.toHaveBeenCalled();+ expect(result.credentialDelivered).toBe(false);+ expect(result).not.toHaveProperty("token");+ expect(result).not.toHaveProperty("credential");+ });++ it("delivers the de-wrapped token once through onCredential on a success stream", async () => {+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT, SUCCESS_OUTPUT], exitCode: 0 });+ const onCredential = vi.fn();+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ onCredential,+ timeoutMs: 1000,+ });+ expect(result.outcome).toBe("success");+ expect(result.credentialDelivered).toBe(true);+ expect(onCredential).toHaveBeenCalledTimes(1);+ const bytes = onCredential.mock.calls[0][0] as Buffer;+ expect(Buffer.isBuffer(bytes)).toBe(true);+ expect(bytes.toString("utf8")).toBe(FULL_TOKEN);+ });++ it("keeps the token out of every log, result, and error field", async () => {+ const logs: string[] = [];+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT, SUCCESS_OUTPUT], exitCode: 0 });+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ onCredential: () => {},+ timeoutMs: 1000,+ log: (line) => {+ logs.push(line);+ },+ });+ const haystack = `${logs.join("\n")}\n${JSON.stringify(result)}`;+ expect(haystack).not.toContain(FULL_TOKEN);+ expect(haystack).not.toContain(TOKEN_FRAGMENT_A);+ expect(result.credentialDelivered).toBe(true);+ });++ it("never scans for the token when no onCredential sink is present", async () => {+ // With no sink the runner never holds the post-prompt stream and delivers+ // nothing, even when the success block is present.+ const fake = createFakeDriver({ chunks: [PROMPT_OUTPUT, SUCCESS_OUTPUT], exitCode: 0 });+ const result = await runSetupTokenLogin(fake.driver, {+ onPrompt: () => {},+ provideCode: async () => BROWSER_CODE,+ timeoutMs: 1000,+ });+ expect(result.outcome).toBe("success");+ expect(result.credentialDelivered).toBe(false);+ });++ it("exposes the fixed setup-token command", () => {+ expect(CLAUDE_SETUP_TOKEN_COMMAND).toBe("claude setup-token");+ });+});diff --git a/packages/adapters/claude-local/src/server/setup-token-runner.ts b/packages/adapters/claude-local/src/server/setup-token-runner.tsnew file mode 100644index 0000000000..1d06a46e98--- /dev/null+++ b/packages/adapters/claude-local/src/server/setup-token-runner.ts@@ -0,0 +1,416 @@+import {+ parseSetupTokenCredential,+ parseSetupTokenPrompt,+ type SetupTokenPrompt,+} from "./setup-token-parse.js";++// The Claude `setup-token` login runner. It starts `claude setup-token` through+// an injected {@link SetupTokenPtyDriver}, surfaces the sign-in prompt one time+// in memory, accepts one browser code, sends the code to the matched prompt, and+// delivers the minted OAuth token one time. It handles a timeout and a+// cancellation, and it stops the child for every terminal state.+//+// Security (secret handling): the runner treats every byte of the terminal+// stream as secret-bearing, untrusted input. It parses the stream in an in-memory+// buffer only. It drops the prompt buffer as soon as it finds the prompt, and it+// drops the token buffer as soon as it binds the token. It never forwards the raw+// text to a log or an artifact, and it never stores the raw text on the result.+// The runner reports only a fixed, non-secret status. It passes the prompt one+// time through the in-memory `onPrompt` callback. It reads the browser code one+// time through the in-memory `provideCode` callback and writes the code only to+// the child, only after it matches the prompt. It delivers the token one time+// through the in-memory `onCredential` callback. The runner keeps the URL, the+// code, and any token byte out of every log line and every thrown error.+//+// Token delivery binds to the success record. The runner scans the post-prompt+// stream with {@link parseSetupTokenCredential}, which returns the token only+// from the exact success record. The {@link SETUP_TOKEN_CREDENTIAL_RELEASE_GATE}+// stays open only while a caller provides an `onCredential` sink; without a sink+// the runner never scans for the token.++/** The fixed Claude setup-token command. The login flow needs a PTY. */+export const CLAUDE_SETUP_TOKEN_COMMAND = "claude setup-token";++/**+ * The submission terminator for the browser code. The interactive login UI reads+ * the code on a PTY and submits it on a carriage return. The runner writes this+ * terminator as its own write, after the code write and a short settle delay.+ * The live characterization showed that a single write of `code + "\r"` does not+ * submit: the input is an Ink text field with paste handling, so a glued+ * carriage return folds into the pasted text instead of a Return key, and the+ * login stalls at the prompt. Two writes with a settle gap submit on the first+ * Return.+ */+export const CODE_SUBMISSION_TERMINATOR = "\r";++/**+ * The default settle delay in milliseconds between the code write and the+ * terminator write. The delay lets the Ink paste buffer settle, so the terminator+ * arrives as a distinct Return key. A caller can override it; a test sets it to 0.+ */+export const CODE_SUBMIT_SETTLE_MS = 150;++/**+ * The maximum number of characters the runner keeps for the next chunk. The+ * login prompt is small and puts the URL and the prompt line close together. A+ * sandbox can stream a large volume of output before the prompt. So after each+ * parse the runner keeps only the most recent characters up to this limit. The+ * retained buffer cannot grow without a bound across many chunks. The limit is+ * far larger than the prompt, so the trailing window never drops a real prompt+ * that spans a chunk boundary.+ */+export const CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS = 64 * 1024;++/**+ * The release gate for the credential seam. The gate is open, so the runner+ * delivers the token that {@link parseSetupTokenCredential} binds from the+ * success record. The runner still scans for the token only when a caller+ * provides an `onCredential` sink.+ */+export const SETUP_TOKEN_CREDENTIAL_RELEASE_GATE: boolean = true;++/**+ * The child side of the setup-token run. The runner never spawns the PTY+ * directly; a caller injects a concrete driver. A production driver binds these+ * methods to a PTY child that runs {@link CLAUDE_SETUP_TOKEN_COMMAND}.+ */+export interface SetupTokenPtyDriver {+ /**+ * Starts `command` in a PTY and streams the terminal output to `onData` in+ * memory. Resolves with the child exit code when the child ends. A driver must+ * not persist the raw output to any durable log.+ */+ start(command: string, onData: (chunk: string) => void): Promise<{ exitCode: number | null }>;+ /**+ * Writes `input` to the child PTY. The runner writes the browser code plus the+ * submission terminator one time, only after it matches the prompt.+ */+ write(input: string): void;+ /**+ * Stops the child process with a direct child stop. The characterization showed+ * that the child needs `SIGKILL`. The method must be safe to call before start+ * and safe to call more than one time.+ */+ stop(): void;+ /** Releases the driver resources. */+ dispose(): Promise<void>;+}++/** Receives the parsed prompt one time in memory. The caller displays it. */+export type SetupTokenPromptSink = (prompt: SetupTokenPrompt) => void;++/**+ * Returns the one browser code the user pastes from the sign-in page. The runner+ * calls it one time, only after it surfaces the prompt. The runner passes an+ * abort signal, so the provider can stop when the runner cancels or times out.+ */+export type SetupTokenCodeProvider = (signal: AbortSignal) => Promise<string>;++/**+ * Receives the credential bytes one time in memory on success. The runner binds+ * the token from the success record, then it invokes this sink one time with the+ * token bytes. The runner never logs the bytes and never stores them on the+ * result.+ */+export type SetupTokenCredentialSink = (authBytes: Buffer) => void | Promise<void>;++export type SetupTokenOutcome = "success" | "failure" | "timeout" | "cancelled";++/** The runner result. It never carries a URL, a code, or a token byte. */+export interface SetupTokenLoginResult {+ outcome: SetupTokenOutcome;+ exitCode: number | null;+ promptSurfaced: boolean;+ codeSubmitted: boolean;+ /** True when the runner bound the token and invoked `onCredential` one time. */+ credentialDelivered: boolean;+}++export interface RunSetupTokenLoginOptions {+ /** The login command. Defaults to {@link CLAUDE_SETUP_TOKEN_COMMAND}. */+ command?: string;+ /** Receives the parsed prompt one time in memory. The caller displays it. */+ onPrompt: SetupTokenPromptSink;+ /** Returns the one browser code. The runner writes it to the matched prompt. */+ provideCode: SetupTokenCodeProvider;+ /** The credential sink. The runner invokes it one time with the token bytes. */+ onCredential?: SetupTokenCredentialSink;+ /**+ * The settle delay in milliseconds between the code write and the terminator+ * write. Defaults to {@link CODE_SUBMIT_SETTLE_MS}. A test sets it to 0.+ */+ codeSubmitSettleMs?: number;+ /** The host-side timeout in milliseconds. */+ timeoutMs: number;+ /** An optional cancellation signal. */+ signal?: AbortSignal;+ /** A non-leaking progress sink. It receives only fixed status lines. */+ log?: (line: string) => void;+}++/**+ * Waits `ms` milliseconds, or resolves at once when the signal aborts. The+ * routine lets the Ink paste buffer settle between the code write and the+ * terminator write. It never rejects; a caller checks the signal after it+ * resolves. A zero or negative delay resolves on the next microtask.+ */+function settleDelay(ms: number, signal: AbortSignal): Promise<void> {+ if (ms <= 0 || signal.aborted) return Promise.resolve();+ return new Promise<void>((resolve) => {+ const done = () => {+ clearTimeout(timer);+ signal.removeEventListener("abort", done);+ resolve();+ };+ const timer = setTimeout(done, ms);+ signal.addEventListener("abort", done, { once: true });+ });+}++type RaceResult =+ | { kind: "exit"; exitCode: number | null }+ | { kind: "timeout" }+ | { kind: "cancelled" };++/**+ * Races the streaming start against the timeout and the cancellation signal. The+ * start result resolves the race; the timeout and the signal resolve the race+ * with a terminal status. A driver error rejects the race, so the caller can+ * convert it to a fixed, non-secret error. A late start rejection after the race+ * already settled is consumed here, so it never becomes an unhandled rejection.+ */+function raceStart(+ start: Promise<{ exitCode: number | null }>,+ timeoutMs: number,+ signal: AbortSignal,+): Promise<RaceResult> {+ return new Promise<RaceResult>((resolve, reject) => {+ let settled = false;+ const cleanup = () => {+ clearTimeout(timer);+ signal.removeEventListener("abort", onAbort);+ };+ const finish = (run: () => void) => {+ if (settled) return;+ settled = true;+ cleanup();+ run();+ };+ const timer = setTimeout(() => finish(() => resolve({ kind: "timeout" })), timeoutMs);+ const onAbort = () => finish(() => resolve({ kind: "cancelled" }));+ signal.addEventListener("abort", onAbort, { once: true });+ start.then(+ (value) => finish(() => resolve({ kind: "exit", exitCode: value.exitCode })),+ (error) => finish(() => reject(error)),+ );+ });+}++/**+ * Stops the child and releases the driver for a terminal state. The runner calls+ * this on every exit path: a normal exit, a non-zero exit, a timeout, a+ * cancellation, and an error. It first runs a direct child stop, then it disposes+ * the driver. A stop error or a dispose error must not leak or mask the result,+ * so the function swallows each error and logs a fixed line.+ */+async function stopAndDispose(driver: SetupTokenPtyDriver, log: (line: string) => void): Promise<void> {+ try {+ driver.stop();+ } catch {+ log("[paperclip] Setup-token login: the process stop step errored.");+ }+ try {+ await driver.dispose();+ } catch {+ log("[paperclip] Setup-token login: the driver dispose step errored.");+ }+}++/**+ * Runs the setup-token login through `driver`. Surfaces the prompt one time+ * through `onPrompt`. Reads the browser code one time through `provideCode` and+ * writes it to the matched prompt. Binds the minted token from the success+ * record and delivers it one time through `onCredential`. Returns a fixed status.+ * Stops the child and disposes the driver for every terminal state. Never logs+ * the raw stream, and never puts a URL, a code, or a token into a log line, the+ * result, or a thrown error.+ */+export async function runSetupTokenLogin(+ driver: SetupTokenPtyDriver,+ options: RunSetupTokenLoginOptions,+): Promise<SetupTokenLoginResult> {+ const { onPrompt, provideCode, onCredential, timeoutMs, signal } = options;+ const command = options.command ?? CLAUDE_SETUP_TOKEN_COMMAND;+ const codeSubmitSettleMs = options.codeSubmitSettleMs ?? CODE_SUBMIT_SETTLE_MS;+ const log = options.log ?? (() => {});++ // A private controller that fans a timeout or a cancellation into the+ // code-input routine, so a pending `provideCode` stops when the run ends.+ const controller = new AbortController();+ const onExternalAbort = () => controller.abort();+ if (signal) {+ if (signal.aborted) controller.abort();+ else signal.addEventListener("abort", onExternalAbort, { once: true });+ }++ let promptSurfaced = false;+ let codeSubmitted = false;+ let submitStarted = false;+ let credentialDelivered = false;+ // The code-input routine runs beside the race. It is self-guarding and never+ // rejects, so an unresolved provider cannot become an unhandled rejection.+ let submitPromise: Promise<void> = Promise.resolve();+ // The credential-delivery routine runs beside the race. It is self-guarding+ // and never rejects, so an async sink cannot become an unhandled rejection.+ let credentialPromise: Promise<void> = Promise.resolve();++ // The in-memory prompt buffer. The runner drops it as soon as it finds the+ // prompt, so the secret-bearing stream never lives longer than one parse. The+ // runner parses the full buffer, and it includes the whole new chunk. So a+ // prompt at the start of one large chunk still parses. The runner bounds only+ // the buffer that it keeps for the next chunk to+ // {@link CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS}. The runner keeps the trailing+ // window and drops the oldest characters.+ let buffer = "";+ // The in-memory token buffer. The runner accumulates the post-prompt stream+ // here, parses the full buffer before any truncation, and drops it as soon as+ // it binds the token. It bounds the retained window the same way as the prompt+ // buffer, so the secret-bearing stream never grows without a bound.+ let tokenBuffer = "";++ // Reads the browser code and writes it to the matched prompt one time. The+ // routine never throws: it logs a fixed line on a provider error or a write+ // error, so the code never reaches a log or a thrown error.+ const submitCode = async (): Promise<void> => {+ let code: string;+ try {+ code = await provideCode(controller.signal);+ } catch {+ log("[paperclip] Setup-token login: the code input step errored.");+ return;+ }+ if (controller.signal.aborted) return;+ try {+ // Write the code, let the Ink paste buffer settle, then write the Return as+ // its own write. A glued `code + "\r"` burst folds the Return into the+ // pasted text and never submits (live characterization). Two writes with a+ // settle gap submit on the first Return.+ driver.write(code);+ await settleDelay(codeSubmitSettleMs, controller.signal);+ if (controller.signal.aborted) return;+ driver.write(CODE_SUBMISSION_TERMINATOR);+ codeSubmitted = true;+ log("[paperclip] Setup-token login: sent the browser code to the prompt.");+ } catch {+ log("[paperclip] Setup-token login: the code input step errored.");+ }+ };++ // Binds the token from the token buffer and delivers it one time. The runner+ // scans only when a caller provides an `onCredential` sink and the gate is+ // open. It drops the token buffer as soon as the parser binds the token. It+ // never logs the token and never puts it into a thrown error.+ const captureCredential = (): void => {+ if (!SETUP_TOKEN_CREDENTIAL_RELEASE_GATE || !onCredential || credentialDelivered) return;+ const token = parseSetupTokenCredential(tokenBuffer);+ if (!token) return;+ credentialDelivered = true;+ tokenBuffer = "";+ const authBytes = Buffer.from(token, "utf8");+ try {+ credentialPromise = Promise.resolve(onCredential(authBytes)).catch(() => {+ log("[paperclip] Setup-token login: the credential delivery step errored.");+ });+ log("[paperclip] Setup-token login: delivered the credential to the sink.");+ } catch {+ log("[paperclip] Setup-token login: the credential delivery step errored.");+ }+ };++ const onData = (chunk: string): void => {+ if (!promptSurfaced) {+ // Parse the full buffer before any truncation. This order finds an early+ // prompt inside one large chunk, so the runner never drops it.+ buffer += chunk;+ const prompt = parseSetupTokenPrompt(buffer);+ if (prompt) {+ promptSurfaced = true;+ buffer = "";+ onPrompt(prompt);+ log("[paperclip] Setup-token login: surfaced the sign-in prompt.");+ if (!submitStarted) {+ submitStarted = true;+ submitPromise = submitCode();+ }+ return;+ }+ if (buffer.length > CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS) {+ buffer = buffer.slice(buffer.length - CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS);+ }+ return;+ }+ // The prompt already surfaced. Scan the post-prompt stream for the success+ // token. The runner scans only when a caller provides an `onCredential`+ // sink, so it never holds the secret-bearing stream without a need.+ if (!SETUP_TOKEN_CREDENTIAL_RELEASE_GATE || !onCredential || credentialDelivered) return;+ tokenBuffer += chunk;+ captureCredential();+ if (!credentialDelivered && tokenBuffer.length > CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS) {+ tokenBuffer = tokenBuffer.slice(tokenBuffer.length - CLAUDE_SETUP_TOKEN_MAX_BUFFER_CHARS);+ }+ };++ const result = (outcome: SetupTokenOutcome, exitCode: number | null): SetupTokenLoginResult => ({+ outcome,+ exitCode,+ promptSurfaced,+ codeSubmitted,+ credentialDelivered,+ });++ try {+ if (signal?.aborted) {+ log("[paperclip] Setup-token login cancelled before start.");+ return result("cancelled", null);+ }++ const start = driver.start(command, onData);+ const raced = await raceStart(start, timeoutMs, controller.signal);+ // Release a pending code-input routine, then let it settle. The routine is+ // self-guarding, so this await never rejects.+ controller.abort();+ await submitPromise;++ if (raced.kind === "timeout") {+ log("[paperclip] Setup-token login timed out; stopping the process.");+ return result("timeout", null);+ }+ if (raced.kind === "cancelled") {+ log("[paperclip] Setup-token login cancelled; stopping the process.");+ return result("cancelled", null);+ }++ const exitCode = raced.exitCode;+ if (exitCode !== 0) {+ log("[paperclip] Setup-token login command ended with a non-zero exit code.");+ return result("failure", exitCode);+ }++ // The runner captured the token from the stream during `onData` and+ // delivered it through `onCredential`. Await a pending async sink, so the+ // credential fully lands before the runner reports success.+ await credentialPromise;++ log("[paperclip] Setup-token login command ended successfully.");+ return result("success", exitCode);+ } catch {+ // Convert any driver error to a fixed, non-secret error. The original error+ // may embed streamed bytes, so the runner never propagates its message.+ throw new Error("setup-token login failed: the sandbox login command errored.");+ } finally {+ if (signal) signal.removeEventListener("abort", onExternalAbort);+ // Stop a pending code-input routine, then stop the child and dispose.+ controller.abort();+ await stopAndDispose(driver, log);+ }+}diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.tsindex 9b8e160898..3114f32627 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.ts@@ -42,6 +42,25 @@ import type {} from "@paperclipai/plugin-sdk";import { performSyncIn, performSyncOut, withProviderSpan } from "./file-sync.js";+// The Claude `setup-token` login pseudo-terminal (PTY) session for this provider.+// The session runs the login command on a real pseudo-terminal, streams the+// terminal output, and delivers the delayed browser code plus the Enter byte. A+// later phase binds the opener to `sandbox.process` and wraps it with the+// `createSetupTokenPtyTransport` factory from `@paperclipai/adapter-utils` to+// build the transport the login runner drives.+export {+ createDaytonaSetupTokenPtySessionOpener,+ openDaytonaSetupTokenPtySession,+} from "./setup-token-pty.js";+export type {+ SetupTokenPtySession,+ SetupTokenPtySessionOpener,+ DaytonaPtyHandle,+ DaytonaPtyProcess,+ DaytonaPtyCreateOptions,+ DaytonaSetupTokenPtyOptions,+} from "./setup-token-pty.js";+// Injectable monotonic clock for provider-boundary timing (Open Q1). Defaults// to the real wall clock; `plugin.test.ts` overrides it via// `setDaytonaTimingClockForTest` so the measured `durationMs`/`getDurationMs`diff --git a/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.test.ts b/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.test.tsnew file mode 100644index 0000000000..63ca4bb114--- /dev/null+++ b/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.test.ts@@ -0,0 +1,222 @@+import { describe, expect, it } from "vitest";+import {+ createDaytonaSetupTokenPtySessionOpener,+ openDaytonaSetupTokenPtySession,+ type DaytonaPtyCreateOptions,+ type DaytonaPtyHandle,+ type DaytonaPtyProcess,+} from "./setup-token-pty.js";++// The Enter byte the terminal login UI reads to submit the browser code.+const ENTER = "\r";++/**+ * A fake Daytona PTY handle. It records each input write, drives the output+ * stream on demand, and records the kill and the disconnect. The tests use it in+ * place of the real SDK `PtyHandle`, so the session runs with no sandbox.+ */+function createFakePtyHandle(onData: (data: Uint8Array) => void | Promise<void>): DaytonaPtyHandle & {+ inputs: string[];+ emitText: (text: string) => void;+ emitBytes: (bytes: Uint8Array) => void;+ finish: (exitCode: number | undefined) => void;+ killed: number;+ disconnected: number;+} {+ const encoder = new TextEncoder();+ const inputs: string[] = [];+ let resolveWait: ((value: { exitCode?: number; error?: string }) => void) | null = null;+ const waitPromise = new Promise<{ exitCode?: number; error?: string }>((resolve) => {+ resolveWait = resolve;+ });+ let killed = 0;+ let disconnected = 0;+ return {+ async waitForConnection(): Promise<void> {},+ async sendInput(data: string | Uint8Array): Promise<void> {+ inputs.push(typeof data === "string" ? data : new TextDecoder().decode(data));+ },+ wait(): Promise<{ exitCode?: number; error?: string }> {+ return waitPromise;+ },+ async kill(): Promise<void> {+ killed += 1;+ },+ async disconnect(): Promise<void> {+ disconnected += 1;+ },+ // Test control below. The session never reads these fields.+ emitText(text: string): void {+ onData(encoder.encode(text));+ },+ emitBytes(bytes: Uint8Array): void {+ onData(bytes);+ },+ finish(exitCode: number | undefined): void {+ resolveWait?.({ exitCode });+ },+ get inputs(): string[] {+ return inputs;+ },+ get killed(): number {+ return killed;+ },+ get disconnected(): number {+ return disconnected;+ },+ };+}++/**+ * A fake Daytona process. It opens one fake PTY handle and records the create+ * options, so a test asserts the terminal size and the command start.+ */+function createFakeProcess(): DaytonaPtyProcess & {+ handle: ReturnType<typeof createFakePtyHandle> | null;+ createOptions: DaytonaPtyCreateOptions | null;+} {+ const state: {+ handle: ReturnType<typeof createFakePtyHandle> | null;+ createOptions: DaytonaPtyCreateOptions | null;+ } = { handle: null, createOptions: null };+ return {+ get handle() {+ return state.handle;+ },+ get createOptions() {+ return state.createOptions;+ },+ async createPty(options: DaytonaPtyCreateOptions): Promise<DaytonaPtyHandle> {+ state.createOptions = options;+ const handle = createFakePtyHandle(options.onData);+ state.handle = handle;+ return handle;+ },+ };+}++describe("openDaytonaSetupTokenPtySession", () => {+ it("starts the login command on a pseudo-terminal with a fixed size", async () => {+ const process = createFakeProcess();++ await openDaytonaSetupTokenPtySession(process, "claude setup-token");++ expect(process.createOptions?.cols).toBe(120);+ expect(process.createOptions?.rows).toBe(30);+ // The session replaces the shell with the command through `exec`, so the+ // pseudo-terminal runs the command directly and its exit code is the PTY+ // exit code.+ expect(process.handle?.inputs[0]).toBe("exec claude setup-token" + ENTER);+ });++ it("returns incremental terminal output to the listener", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ session.onData((chunk) => received.push(chunk));++ process.handle?.emitText("the url below to sign in\n");+ process.handle?.emitText("Paste code here if prompted\n");++ expect(received).toEqual(["the url below to sign in\n", "Paste code here if prompted\n"]);+ });++ it("buffers early output until the listener registers", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ // Output arrives before the transport registers the listener.+ process.handle?.emitText("early output ");+ process.handle?.emitText("more output");+ expect(received).toEqual([]);++ session.onData((chunk) => received.push(chunk));+ // The session flushes the buffered output in order on registration.+ expect(received).toEqual(["early output more output"]);+ });++ it("delivers the browser code plus the Enter byte to the command", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ session.write("BROWSERCODE" + ENTER);++ // The first input is the command start; the second input is the delayed+ // browser code plus the Enter byte.+ expect(process.handle?.inputs[1]).toBe("BROWSERCODE" + ENTER);+ expect(process.handle?.inputs[1]?.endsWith(ENTER)).toBe(true);+ });++ it("keeps a multibyte character whole across two output chunks", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ session.onData((chunk) => received.push(chunk));++ // The euro sign is three UTF-8 bytes. Split it across two chunks, so the+ // stream decoder must join the bytes.+ const euro = new TextEncoder().encode("€");+ process.handle?.emitBytes(euro.subarray(0, 2));+ process.handle?.emitBytes(euro.subarray(2));++ expect(received.join("")).toBe("€");+ });++ it("resolves wait with the command exit code", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ process.handle?.finish(9);++ await expect(session.wait()).resolves.toEqual({ exitCode: 9 });+ });++ it("maps an absent exit code to null", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ process.handle?.finish(undefined);++ await expect(session.wait()).resolves.toEqual({ exitCode: null });+ });++ it("kills the child and closes the session", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaSetupTokenPtySession(process, "claude setup-token");+ session.kill();+ expect(process.handle?.killed).toBe(1);++ await session.close();+ expect(process.handle?.disconnected).toBe(1);+ });++ it("passes the working directory to the pseudo-terminal", async () => {+ const process = createFakeProcess();++ await openDaytonaSetupTokenPtySession(process, "claude setup-token", { cwd: "/workspace" });++ expect(process.createOptions?.cwd).toBe("/workspace");+ });+});++describe("createDaytonaSetupTokenPtySessionOpener", () => {+ it("opens a session for the command on each call", async () => {+ const process = createFakeProcess();+ const opener = createDaytonaSetupTokenPtySessionOpener(process, { cwd: "/workspace" });++ const session = await opener("claude setup-token");++ expect(process.createOptions?.cwd).toBe("/workspace");+ expect(process.handle?.inputs[0]).toBe("exec claude setup-token" + ENTER);+ // The opener returns a session the transport can drive.+ expect(typeof session.onData).toBe("function");+ expect(typeof session.write).toBe("function");+ expect(typeof session.wait).toBe("function");+ expect(typeof session.kill).toBe("function");+ expect(typeof session.close).toBe("function");+ });+});diff --git a/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.ts b/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.tsnew file mode 100644index 0000000000..89bace5b5c--- /dev/null+++ b/packages/plugins/sandbox-providers/daytona/src/setup-token-pty.ts@@ -0,0 +1,194 @@+// The Daytona pseudo-terminal (PTY) session for the Claude `setup-token` login.+// The login command needs a real pseudo-terminal: pipe stdio emits no login+// prompt. The Daytona SDK opens a PTY through `process.createPty`. This module+// binds that PTY to a small session that the setup-token transport consumes, so+// the login runner runs the command on a real terminal, streams the terminal+// output, and delivers the delayed browser code plus the Enter byte.+//+// Dependency boundary: this provider plugin ships standalone (the workspace+// excludes `packages/plugins/sandbox-providers/**`). So the module imports no+// workspace package. It declares the small session shape locally through+// {@link SetupTokenPtySession}. The shape matches the `SetupTokenPtySession`+// interface in `@paperclipai/adapter-utils`, so the transport factory+// `createSetupTokenPtyTransport` accepts the session opener from this module with+// no adapter. The runner drives the transport; the transport drives this session.+//+// SDK boundary: the module holds no Daytona SDK type import. It declares the+// small subset of the SDK PTY surface that it uses through+// {@link DaytonaPtyProcess} and {@link DaytonaPtyHandle}. The SDK `Process` and+// `PtyHandle` satisfy that subset, so a caller passes `sandbox.process` with no+// adapter. The narrow surface keeps the module unit-testable with a fake PTY.+//+// Security (secret handling): the login runner delivers the browser code and the+// Enter byte through {@link DaytonaPtyHandle.sendInput}. The SDK sends the input+// over the PTY socket, so the code never rides a command line and never reaches a+// process argument list. The session forwards the raw terminal bytes with no+// ANSI or OSC 8 handling; the setup-token parser owns that handling.++import { randomUUID } from "node:crypto";++/**+ * A live pseudo-terminal session for one setup-token login command. The session+ * allocates a real pseudo-terminal, streams the raw terminal output, accepts+ * delayed input, and stops the child. The shape matches the+ * `SetupTokenPtySession` interface in `@paperclipai/adapter-utils`, so the+ * transport factory there accepts a session opener that returns this session.+ */+export interface SetupTokenPtySession {+ /** Registers the one output listener. The session streams each raw chunk in order. */+ onData(listener: (chunk: string) => void): void;+ /** Writes raw input bytes to the pseudo-terminal. */+ write(data: string): void;+ /** Resolves with the child exit code when the command ends. */+ wait(): Promise<{ exitCode: number | null }>;+ /** Stops the child process. Safe to call more than one time. */+ kill(): void;+ /** Releases the session resources. Safe to call more than one time. */+ close(): Promise<void>;+}++/** Opens a {@link SetupTokenPtySession} for `command`. The transport calls it one time. */+export type SetupTokenPtySessionOpener = (command: string) => Promise<SetupTokenPtySession>;++/**+ * The subset of the Daytona SDK `PtyHandle` that the session uses. The SDK+ * `PtyHandle` satisfies this interface, so a caller passes the real handle with+ * no adapter.+ */+export interface DaytonaPtyHandle {+ /** Resolves when the PTY socket connection is ready for input and output. */+ waitForConnection(): Promise<void>;+ /** Sends raw input bytes to the pseudo-terminal. */+ sendInput(data: string | Uint8Array): Promise<void>;+ /** Resolves with the exit result when the pseudo-terminal process ends. */+ wait(): Promise<{ exitCode?: number; error?: string }>;+ /** Kills the pseudo-terminal process. */+ kill(): Promise<void>;+ /** Closes the PTY socket and releases the resources. */+ disconnect(): Promise<void>;+}++/**+ * The options the session passes to `createPty`. The session sets a fixed+ * terminal size and one output callback. It sets the working directory when the+ * caller provides one.+ */+export interface DaytonaPtyCreateOptions {+ id: string;+ cwd?: string;+ cols: number;+ rows: number;+ onData: (data: Uint8Array) => void | Promise<void>;+}++/**+ * The subset of the Daytona SDK `Process` that the session uses. The SDK+ * `Process` satisfies this interface, so a caller passes `sandbox.process`.+ */+export interface DaytonaPtyProcess {+ createPty(options: DaytonaPtyCreateOptions): Promise<DaytonaPtyHandle>;+}++/** The options for the Daytona setup-token PTY session. */+export interface DaytonaSetupTokenPtyOptions {+ /** The working directory for the login PTY. Defaults to the sandbox default. */+ cwd?: string;+}++// The terminal size for the login PTY. The login UI prints a short prompt, so a+// standard terminal size is enough. A fixed size keeps the output stable.+const SETUP_TOKEN_PTY_COLS = 120;+const SETUP_TOKEN_PTY_ROWS = 30;++/**+ * The input terminator that replaces the interactive shell with the login+ * command. The `exec` builtin replaces the shell process image with the command,+ * so the PTY runs the command directly. When the command ends, the PTY ends with+ * the command exit code, and the delayed input reaches the command, not a shell.+ * The terminal reads the carriage return as the Enter key.+ */+const PTY_COMMAND_TERMINATOR = "\r";++/**+ * Opens a Daytona PTY session for `command` and returns it as a+ * {@link SetupTokenPtySession}. The session allocates a real pseudo-terminal,+ * streams the raw terminal output, delivers delayed input, and stops the child.+ *+ * The function starts the login command with `exec`, so the pseudo-terminal runs+ * the command directly and the command exit code becomes the PTY exit code. The+ * function decodes the terminal bytes as a UTF-8 stream, so a multibyte+ * character that splits across two output chunks stays whole. It buffers the+ * output until the transport registers the listener, so no early chunk is lost.+ */+export async function openDaytonaSetupTokenPtySession(+ process: DaytonaPtyProcess,+ command: string,+ options?: DaytonaSetupTokenPtyOptions,+): Promise<SetupTokenPtySession> {+ const decoder = new TextDecoder("utf-8");+ let listener: ((chunk: string) => void) | null = null;+ let buffered = "";++ const handle = await process.createPty({+ id: `paperclip-setup-token-${randomUUID()}`,+ ...(options?.cwd ? { cwd: options.cwd } : {}),+ cols: SETUP_TOKEN_PTY_COLS,+ rows: SETUP_TOKEN_PTY_ROWS,+ onData: (data: Uint8Array): void => {+ // Decode the terminal bytes as a stream, so a split multibyte character+ // stays whole across two chunks. Forward the raw text; the parser owns the+ // ANSI and OSC 8 handling.+ const text = decoder.decode(data, { stream: true });+ if (text.length === 0) return;+ if (listener) listener(text);+ else buffered += text;+ },+ });++ await handle.waitForConnection();+ // Replace the interactive shell with the login command, so the pseudo-terminal+ // runs the command directly. The runner then writes the delayed browser code+ // to the command, not to a shell.+ await handle.sendInput(`exec ${command}${PTY_COMMAND_TERMINATOR}`);++ return {+ onData(next: (chunk: string) => void): void {+ listener = next;+ if (buffered.length > 0) {+ const pending = buffered;+ buffered = "";+ next(pending);+ }+ },+ write(data: string): void {+ // Fire the input write. A write error must not throw into the runner, so+ // the runner's fixed status stays the single result path.+ void handle.sendInput(data).catch(() => undefined);+ },+ async wait(): Promise<{ exitCode: number | null }> {+ const result = await handle.wait();+ return { exitCode: typeof result.exitCode === "number" ? result.exitCode : null };+ },+ kill(): void {+ void handle.kill().catch(() => undefined);+ },+ async close(): Promise<void> {+ await handle.disconnect().catch(() => undefined);+ },+ };+}++/**+ * Creates a {@link SetupTokenPtySessionOpener} bound to a Daytona `process`. Pass+ * `sandbox.process` from the Daytona SDK. A later phase wraps the opener with the+ * `createSetupTokenPtyTransport` factory from `@paperclipai/adapter-utils` and+ * hands the transport to the login runner. The opener runs the login command on+ * a real pseudo-terminal, streams the terminal output, delivers the delayed+ * browser code plus the Enter byte, and stops the child for a terminal state.+ */+export function createDaytonaSetupTokenPtySessionOpener(+ process: DaytonaPtyProcess,+ options?: DaytonaSetupTokenPtyOptions,+): SetupTokenPtySessionOpener {+ return (command: string) => openDaytonaSetupTokenPtySession(process, command, options);+}diff --git a/server/src/app.ts b/server/src/app.tsindex 51f49a1ca3..83ba9f791f 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -29,6 +29,7 @@ import { summarySlotRoutes } from "./routes/summary-slots.js";import { statusCardRoutes } from "./routes/status-cards.js";import { teamsCatalogRoutes } from "./routes/teams-catalog.js";import { agentRoutes } from "./routes/agents.js";+import type { SetupTokenSessionService } from "./services/setup-token-session.js";import { projectRoutes } from "./routes/projects.js";import { issueRoutes } from "./routes/issues.js";import { issueTreeControlRoutes } from "./routes/issue-tree-control.js";@@ -384,7 +385,41 @@ export async function createApp(api.use(summarySlotRoutes(db));api.use(statusCardRoutes(db));api.use(teamsCatalogRoutes(db));- api.use(agentRoutes(db, { pluginWorkerManager: workerManager }));+ // The setup-token login session service. The router builds it and hands it+ // back through the callback below, so the shutdown hook can cancel every live+ // session (SR-4).+ let setupTokenLoginService: SetupTokenSessionService | null = null;+ // The dedicated proxy IP or CIDR allowlist for the confidential setup-token+ // login responses (SR-7). The global `TRUST_PROXY` setting does not satisfy+ // the guard; an operator sets this allowlist to the real TLS-terminating+ // proxy addresses. An empty value keeps the confidential responses on direct+ // TLS (or a `local_trusted` loopback peer) only.+ const setupTokenLoginProxyAllowlist = (process.env.CLAUDE_LOGIN_TRUSTED_PROXIES ?? "")+ .split(",")+ .map((entry) => entry.trim())+ .filter((entry) => entry.length > 0);+ // The production server does not bind `setupTokenLogin` yet, so the start route+ // fails closed with a fixed no-secret 503 and the login never spawns a process+ // or holds a lease. This is a deliberate staged rollout: the live transport+ // needs a real sandbox-lease manager, a live pseudo-terminal factory over the+ // sandbox provider, and a durable cleanup store (the in-router default store is+ // in-memory only). Each of those is a separate follow-up that goes through its+ // own security review before the production server binds `setupTokenLogin`.+ api.use(+ agentRoutes(db, {+ pluginWorkerManager: workerManager,+ deploymentMode: opts.deploymentMode,+ confidentialProxyAllowlist: setupTokenLoginProxyAllowlist,+ onSetupTokenLoginService: (service) => {+ setupTokenLoginService = service;+ // Startup reaper (SR-4): release any lease whose login session is+ // terminal or past its deadline after a restart. The DB is ready here.+ void service.reap().catch((err) => {+ logger.error({ err }, "Setup-token login startup reaper failed");+ });+ },+ }),+ );api.use(assetRoutes(db, opts.storageService));api.use(projectRoutes(db));api.use(caseRoutes(db, opts.storageService));@@ -792,6 +827,9 @@ export async function createApp(viteHtmlRenderer?.dispose();hostServiceCleanup.disposeAll();hostServiceCleanup.teardown();+ // Cancel every live setup-token login session, so each direct child stops+ // before the server releases each lease (SR-4).+ void setupTokenLoginService?.shutdown();};app.locals.paperclipShutdown = shutdownAppServices;diff --git a/server/src/middleware/redact-sensitive.ts b/server/src/middleware/redact-sensitive.tsindex e5a5e9ade1..3197e459f3 100644--- a/server/src/middleware/redact-sensitive.ts+++ b/server/src/middleware/redact-sensitive.ts@@ -39,6 +39,12 @@ const SENSITIVE_KEYS = new Set<string>(["sessiontoken","private_key","privatekey",+ // The Claude setup-token login fields. `browserCode` carries the one-time+ // sign-in code and `authorization_code` carries the OAuth code; neither may+ // reach a log line.+ "browsercode",+ "authorization_code",+ "authorizationcode",]);const MAX_DEPTH = 6;@@ -53,6 +59,11 @@ const URLISH_KEYS = new Set<string>(["sourceurl","uri","url",+ // The Claude setup-token login URL. A structured `loginUrl` that reaches a log+ // sink keeps its origin and path only; the OAuth query, fragment, and any+ // credentials are stripped (SR-5 backstop).+ "loginurl",+ "login_url",]);function isSensitiveKey(key: string): boolean {diff --git a/server/src/redaction.ts b/server/src/redaction.tsindex 64cd96966c..eea53edc67 100644--- a/server/src/redaction.ts+++ b/server/src/redaction.ts@@ -1,7 +1,7 @@import { redactCommandText } from "@paperclipai/adapter-utils";const SECRET_FIELD_NAME_PATTERN =- String.raw`[A-Za-z0-9_-]*(?:api[-_]?key|access[-_]?token|auth(?:_?token)?|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)[A-Za-z0-9_-]*`;+ String.raw`[A-Za-z0-9_-]*(?:api[-_]?key|access[-_]?token|auth(?:_?token)?|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring|browser[-_]?code|login[-_]?url)[A-Za-z0-9_-]*`;const SECRET_PAYLOAD_KEY_RE = new RegExp(SECRET_FIELD_NAME_PATTERN, "i");// Authorization reasons are policy decision codes, not credentials. They mustdiff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex 08a458b5b4..3dbdc4a7ed 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -94,6 +94,23 @@ import {resolveWorktreeRunExecutionActivationState,} from "../services/instance-settings.js";import { runClaudeLogin } from "@paperclipai/adapter-claude-local/server";+import { createInviteRateLimiter } from "../services/invite-rate-limit.js";+import {+ SetupTokenSessionService,+ SetupTokenSessionError,+ assessConfidentialStartup,+ evaluateConfidentialTransport,+ SETUP_TOKEN_START_FAILED,+ SETUP_TOKEN_TRANSPORT_INSECURE,+ type ConfidentialTransportConfig,+ type SetupTokenCleanupRecord,+ type SetupTokenCleanupStore,+ type SetupTokenLease,+ type SetupTokenLeaseManager,+ type SetupTokenLoginProcessFactory,+ type SetupTokenSessionScope,+} from "../services/setup-token-session.js";+import type { DeploymentMode } from "@paperclipai/shared";import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX } from "@paperclipai/adapter-codex-local";import {checkStagedCredentialReadiness,@@ -185,7 +202,37 @@ function readRunIssueId(context: Record<string, unknown> | null) {export function agentRoutes(db: Db,- options: { pluginWorkerManager?: PluginWorkerManager } = {},+ options: {+ pluginWorkerManager?: PluginWorkerManager;+ /** The active deployment mode. The confidential transport guard reads it. */+ deploymentMode?: DeploymentMode;+ /**+ * The dedicated proxy IP or CIDR allowlist for the confidential setup-token+ * responses (SR-7). The global `TRUST_PROXY` setting does not satisfy the+ * guard; only a peer on this explicit allowlist may forward a TLS protocol.+ */+ confidentialProxyAllowlist?: string[];+ /**+ * Receives the setup-token login session service once the router builds it.+ * The caller registers the startup reaper and the graceful-shutdown cleanup.+ */+ onSetupTokenLoginService?: (service: SetupTokenSessionService) => void;+ /**+ * Binds the live setup-token login transport. When the caller provides it,+ * the session route is the live login path: the start route acquires a real+ * sandbox lease through `leases` and drives one live login process through+ * `factory`. When the caller omits it, the start route fails closed with the+ * fixed no-secret error, because the sandbox pseudo-terminal transport is not+ * bound yet. A test injects a fake factory and a fake lease manager to drive+ * the full route path.+ */+ setupTokenLogin?: {+ factory: SetupTokenLoginProcessFactory;+ leases: SetupTokenLeaseManager;+ /** The durable cleanup store. Defaults to the in-memory record store. */+ store?: SetupTokenCleanupStore;+ };+ } = {},) {// Legacy hardcoded maps — used as fallback when adapter module does not// declare capability flags explicitly.@@ -234,6 +281,102 @@ export function agentRoutes(const environmentRuntime = environmentRuntimeService(db, {pluginWorkerManager: options.pluginWorkerManager,});++ // --- Setup-token login session (Claude in-product login) -------------------+ //+ // The service owns a company-scoped, owner-bound login session, the+ // confidential transport guard (SR-6, SR-7), the session caps, and the start+ // rate limit. The `options.setupTokenLogin` transport binds the live sandbox+ // pseudo-terminal login process and the real sandbox-lease acquisition. When a+ // caller provides the transport, the session route is the live login path and+ // `SETUP_TOKEN_LOGIN_TRANSPORT_READY` is true. When a caller omits it, the+ // start route returns the fixed no-secret error and the login never spawns a+ // process or holds a lease. The full session state machine, the cleanup order,+ // and the reaper are covered by setup-token-session.test.ts.+ const SETUP_TOKEN_LOGIN_TRANSPORT_READY = options.setupTokenLogin != null;++ const setupTokenConfidentialConfig: ConfidentialTransportConfig = {+ deploymentMode: options.deploymentMode ?? "local_trusted",+ trustedProxies: options.confidentialProxyAllowlist ?? [],+ };++ // Rate-limit the start route: a small window per company and owner (SR-4).+ const setupTokenRateLimiter = createInviteRateLimiter({ windowMs: 60_000, maxRequests: 5 });++ // The deferred lease manager. It fails closed on acquire until a caller binds+ // the live transport. It still releases a lease by handle or by id, so a+ // reaper or a shutdown can free a lease that an injected transport acquired.+ const deferredSetupTokenLeaseManager: SetupTokenLeaseManager = {+ async acquire(): Promise<SetupTokenLease> {+ // The real sandbox-lease acquisition binds through `options.setupTokenLogin`.+ // Until then the start route fails closed before it reaches here.+ throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);+ },+ async release(lease): Promise<void> {+ await environmentsSvc.releaseLease(lease.id, "released").catch(() => {});+ },+ async releaseById(leaseId): Promise<void> {+ await environmentsSvc.releaseLease(leaseId, "released").catch(() => {});+ },+ };++ // The in-memory non-secret cleanup record store. It is the default store when a+ // caller does not inject a durable database-backed store.+ const setupTokenCleanupRows = new Map<string, SetupTokenCleanupRecord>();+ const inMemorySetupTokenCleanupStore: SetupTokenCleanupStore = {+ async record(record): Promise<void> {+ setupTokenCleanupRows.set(record.sessionId, { ...record });+ },+ async markState(sessionId, state): Promise<void> {+ const row = setupTokenCleanupRows.get(sessionId);+ if (row) row.state = state;+ },+ async remove(sessionId): Promise<void> {+ setupTokenCleanupRows.delete(sessionId);+ },+ async listReapable(): Promise<SetupTokenCleanupRecord[]> {+ return [];+ },+ };++ const deferredSetupTokenLoginFactory: SetupTokenLoginProcessFactory = () => {+ // The runner-over-pseudo-terminal binding arrives through+ // `options.setupTokenLogin`. Until then the start route fails closed.+ throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);+ };++ // Resolve the transport: use the injected factory, lease manager, and store+ // when a caller binds them; otherwise use the deferred, fail-closed defaults.+ const setupTokenLoginFactory =+ options.setupTokenLogin?.factory ?? deferredSetupTokenLoginFactory;+ const setupTokenLeaseManager =+ options.setupTokenLogin?.leases ?? deferredSetupTokenLeaseManager;+ const setupTokenCleanupStore =+ options.setupTokenLogin?.store ?? inMemorySetupTokenCleanupStore;++ const setupTokenLoginService = new SetupTokenSessionService({+ factory: setupTokenLoginFactory,+ leases: setupTokenLeaseManager,+ store: setupTokenCleanupStore,+ rateLimiter: setupTokenRateLimiter,+ });++ {+ // Log the startup transport assessment, so an operator can see whether a+ // forwarded proxy protocol is trusted for the confidential routes (SR-7).+ const startupAssessment = assessConfidentialStartup(setupTokenConfidentialConfig);+ logger.info(+ {+ proxyForwardingEnabled: startupAssessment.proxyForwardingEnabled,+ reason: startupAssessment.reason,+ deploymentMode: setupTokenConfidentialConfig.deploymentMode,+ },+ "Setup-token login confidential transport startup assessment",+ );+ }++ options.onSetupTokenLoginService?.(setupTokenLoginService);+const runRedactions = createRunSecretRedactionRegistry(db);const heartbeat = heartbeatService(db, {pluginWorkerManager: options.pluginWorkerManager,@@ -4044,6 +4187,192 @@ export function agentRoutes(res.json(result);});+ // --- Setup-token login session routes --------------------------------------+ //+ // The routes give the harness the operations against one live login session.+ // Every operation verifies the company, the owner user, and the target agent+ // through the session scope. A missing session and a cross-scope session both+ // return the same 404. The confidential responses (read-prompt and+ // receive-token) pass through the fail-closed transport guard and set+ // `Cache-Control: no-store`. The routes write no prompt, code, token, or raw+ // process chunk to a log or an activity detail, and they return fixed error+ // text only.+ //+ // Operator requirement (SR-7): to serve the confidential responses behind a+ // TLS-terminating reverse proxy, set `CLAUDE_LOGIN_TRUSTED_PROXIES` to the+ // explicit proxy IP or CIDR allowlist. The global `TRUST_PROXY` setting,+ // including `TRUST_PROXY=true` and a hop-count value, does not satisfy the+ // guard. A direct TLS request is always valid; a non-TLS request is valid only+ // on a loopback peer in the `local_trusted` deployment mode.+ //+ // Each route below writes its full path as a plain string literal. The static+ // OpenAPI coverage test reads the route paths from the source text; it does+ // not evaluate a template variable. A shared base constant would leave the+ // test with an unresolved path, so the routes repeat the base path instead.++ /**+ * Builds the immutable session scope from the authenticated owner user and the+ * target agent (SR-3, FU-1). Only a user actor owns a login session; the route+ * uses this dedicated login scope, not the broad agent-manage permission.+ */+ const buildSetupTokenScope = (+ req: Request,+ agent: { id: string; companyId: string },+ ): SetupTokenSessionScope => {+ const actor = getActorInfo(req);+ if (actor.actorType !== "user") {+ throw forbidden("A user must own a setup-token login session.");+ }+ return { companyId: agent.companyId, ownerUserId: actor.actorId, targetAgentId: agent.id };+ };++ /**+ * Applies the fail-closed confidential transport guard (SR-6, SR-7). It reads+ * the raw socket TLS bit and the immediate peer address, so the global+ * `trust proxy` setting cannot influence the decision. It returns false and+ * sends the fixed no-secret error when the transport is not confidential.+ */+ const enforceSetupTokenTransport = (req: Request, res: Response): boolean => {+ const socket = req.socket as { encrypted?: boolean; remoteAddress?: string };+ const forwardedProto = req.headers["x-forwarded-proto"];+ const decision = evaluateConfidentialTransport(setupTokenConfidentialConfig, {+ socketEncrypted: socket?.encrypted === true,+ remoteAddress: socket?.remoteAddress,+ forwardedProto: Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto,+ });+ if (!decision.allowed) {+ res.setHeader("Cache-Control", "no-store");+ res.status(403).json({ error: SETUP_TOKEN_TRANSPORT_INSECURE });+ return false;+ }+ return true;+ };++ const sendSetupTokenError = (res: Response, err: unknown): void => {+ if (err instanceof SetupTokenSessionError) {+ res.status(err.status).json({ error: err.message });+ return;+ }+ throw err;+ };++ /**+ * Resolves the target agent for a login-session route and verifies it is a+ * `claude_local` agent. Returns null and sends the response when the agent is+ * missing, inaccessible, or the wrong adapter type.+ */+ const resolveSetupTokenAgent = async (req: Request, res: Response) => {+ const id = req.params.id as string;+ const agent = await getAccessibleResource(req, res, svc.getById(id), "Agent not found");+ if (!agent) return null;+ if (agent.adapterType !== "claude_local") {+ res.status(400).json({ error: "Login is only supported for claude_local agents" });+ return null;+ }+ return agent;+ };++ router.post("/agents/:id/setup-token-login-sessions", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ res.setHeader("Cache-Control", "no-store");+ if (!SETUP_TOKEN_LOGIN_TRANSPORT_READY) {+ // The live login transport binds at a later call site. Fail closed with the+ // fixed no-secret error until then.+ res.status(503).json({ error: SETUP_TOKEN_START_FAILED });+ return;+ }+ try {+ const started = await setupTokenLoginService.start(scope);+ res.status(201).json({ sessionId: started.sessionId, state: started.state });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });++ router.get("/agents/:id/setup-token-login-sessions/:sessionId/prompt", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ res.setHeader("Cache-Control", "no-store");+ // SR-6 and SR-7: the full login URL is a confidential response.+ if (!enforceSetupTokenTransport(req, res)) return;+ try {+ const view = setupTokenLoginService.readPrompt(req.params.sessionId as string, scope);+ // SR-5: the full login URL rides only in this authorized owner response.+ res.json({ state: view.state, loginUrl: view.loginUrl });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });++ router.post("/agents/:id/setup-token-login-sessions/:sessionId/code", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ const browserCode = typeof req.body?.browserCode === "string" ? req.body.browserCode : null;+ res.setHeader("Cache-Control", "no-store");+ // SR-6 and SR-7: the browser code is the confidential OAuth authorization+ // secret. Enforce the fail-closed confidential transport guard before the+ // route reads it, so the code never rides an untrusted transport.+ if (!enforceSetupTokenTransport(req, res)) return;+ if (!browserCode) {+ // The route echoes no input; it returns fixed error text only (SR-1).+ res.status(400).json({ error: "A browserCode is required." });+ return;+ }+ try {+ const result = setupTokenLoginService.submitCode(req.params.sessionId as string, scope, browserCode);+ res.json({ state: result.state });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });++ router.post("/agents/:id/setup-token-login-sessions/:sessionId/cancel", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ try {+ const result = await setupTokenLoginService.cancel(req.params.sessionId as string, scope);+ res.json({ state: result.state });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });++ router.post("/agents/:id/setup-token-login-sessions/:sessionId/expire", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ try {+ const result = await setupTokenLoginService.expire(req.params.sessionId as string, scope);+ res.json({ state: result.state });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });++ router.post("/agents/:id/setup-token-login-sessions/:sessionId/token", async (req, res) => {+ const agent = await resolveSetupTokenAgent(req, res);+ if (!agent) return;+ const scope = buildSetupTokenScope(req, agent);+ res.setHeader("Cache-Control", "no-store");+ // SR-6 and SR-7: the token is a confidential response.+ if (!enforceSetupTokenTransport(req, res)) return;+ try {+ // The service returns the token one time from a completed session. It+ // returns the fixed unavailable error when the token is not ready or the+ // owner already received it. The full token rides only in this authorized+ // owner response over the confidential transport (SR-5, SR-6, SR-7).+ const result = setupTokenLoginService.receiveToken(req.params.sessionId as string, scope);+ res.json({ token: result.token });+ } catch (err) {+ sendSetupTokenError(res, err);+ }+ });+router.get("/companies/:companyId/heartbeat-runs", async (req, res) => {const companyId = req.params.companyId as string;assertCompanyAccess(req, companyId);diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.tsindex 1808f1aeaf..27619b7b59 100644--- a/server/src/routes/openapi.ts+++ b/server/src/routes/openapi.ts@@ -4488,6 +4488,99 @@ registry.registerPath({responses: { 200: r.ok(), 401: r.unauthorized },});+// Setup-token login session routes. The owner user starts one session, reads the+// login prompt, submits the browser code, and receives the token. The prompt,+// code, and token responses require a confidential transport; the guard returns+// 403 when the transport is not confidential.+registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/setup-token-login-sessions",+ tags: ["agents"],+ summary: "Start a setup-token login session for an agent",+ request: { params: z.object({ id: z.string() }) },+ responses: {+ 201: r.ok(),+ 400: r.badRequest,+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ 503: r.serverError,+ },+});++registry.registerPath({+ method: "get",+ path: "/api/agents/{id}/setup-token-login-sessions/{sessionId}/prompt",+ tags: ["agents"],+ summary: "Read the login prompt for a setup-token login session",+ request: { params: z.object({ id: z.string(), sessionId: z.string() }) },+ responses: {+ 200: r.ok(),+ 400: r.badRequest,+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ },+});++registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/setup-token-login-sessions/{sessionId}/code",+ tags: ["agents"],+ summary: "Submit the browser code for a setup-token login session",+ request: { params: z.object({ id: z.string(), sessionId: z.string() }) },+ responses: {+ 200: r.ok(),+ 400: r.badRequest,+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ },+});++registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/setup-token-login-sessions/{sessionId}/cancel",+ tags: ["agents"],+ summary: "Cancel a setup-token login session",+ request: { params: z.object({ id: z.string(), sessionId: z.string() }) },+ responses: {+ 200: r.ok(),+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ },+});++registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/setup-token-login-sessions/{sessionId}/expire",+ tags: ["agents"],+ summary: "Expire a setup-token login session",+ request: { params: z.object({ id: z.string(), sessionId: z.string() }) },+ responses: {+ 200: r.ok(),+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ },+});++registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/setup-token-login-sessions/{sessionId}/token",+ tags: ["agents"],+ summary: "Receive the token from a completed setup-token login session",+ request: { params: z.object({ id: z.string(), sessionId: z.string() }) },+ responses: {+ 200: r.ok(),+ 400: r.badRequest,+ 401: r.unauthorized,+ 403: r.forbidden,+ 404: r.notFound,+ },+});+// ─── Issue interactions & tree ───────────────────────────────────────────────registry.registerPath({diff --git a/server/src/routes/setup-token-route.test.ts b/server/src/routes/setup-token-route.test.tsnew file mode 100644index 0000000000..53f19d2d34--- /dev/null+++ b/server/src/routes/setup-token-route.test.ts@@ -0,0 +1,528 @@+// The wired setup-token login route. This test drives the full login path —+// start, read-prompt, submit-code, and receive-token — through the HTTP route+// with a fake transport. It proves the guarded session contract is the live+// login path and that the security controls hold end to end at the route level.+//+// The test covers these criteria (the full set is on the parent plan document):+// * The full path returns the sign-in URL to the owner, accepts one code, and+// returns the minted token one time.+// * SR-1 and SR-5: the browser code, the authorization-URL query values, and+// the token never reach the request log, an activity detail, the exception+// metadata, or a non-owner response. The owner read-prompt response carries+// the full URL with `Cache-Control: no-store`; every other response carries+// the sanitized URL form only.+// * SR-6 and SR-7: the fail-closed confidential transport guard rejects a+// non-TLS request and a spoofed forwarded protocol through the wired route.++import express from "express";+import { Writable } from "node:stream";+import request from "supertest";+import { beforeEach, describe, expect, it, vi } from "vitest";++import {+ SETUP_TOKEN_SESSION_NOT_FOUND,+ SETUP_TOKEN_SUBMIT_CONFLICT,+ SETUP_TOKEN_TRANSPORT_INSECURE,+ type SetupTokenCleanupRecord,+ type SetupTokenCleanupStore,+ type SetupTokenLeaseManager,+ type SetupTokenLoginOutcome,+ type SetupTokenLoginProcessFactory,+} from "../services/setup-token-session.js";++// --- Test fixtures -----------------------------------------------------------++const COMPANY_ID = "company-1";+const OWNER_USER_ID = "owner-user-1";+const OTHER_USER_ID = "other-user-2";+const AGENT_ID = "11111111-1111-4111-8111-111111111111";++// The distinctive secret values. Each holds a unique marker, so a substring+// check proves the value never reached a sink.+const BROWSER_CODE = "CODESECRETqrs321";+const URL_CODE_QUERY = "QUERYSECRETabc123";+const URL_STATE_QUERY = "STATESECRETdef456";+const MINTED_TOKEN = "sk-ant-oat01-TOKENSECRETxyz789aaaaaaaaaaaa";++// The full authorization URL the transport surfaces. Its query holds the two+// distinctive markers. The sanitized form keeps only the origin and the path.+const FULL_LOGIN_URL =+ "https://claude.com/cai/oauth/authorize" ++ "?client_id=abc" ++ `&code=${URL_CODE_QUERY}` ++ "&code_challenge=xyz" ++ "&code_challenge_method=S256" ++ "&redirect_uri=https%3A%2F%2Fexample.test%2Fcb" ++ "&response_type=code" ++ "&scope=user" ++ `&state=${URL_STATE_QUERY}`;+const SANITIZED_LOGIN_URL = "https://claude.com/cai/oauth/authorize";++const SECRET_MARKERS = [BROWSER_CODE, URL_CODE_QUERY, URL_STATE_QUERY, MINTED_TOKEN, "TOKENSECRETxyz789"];++function expectNoSecret(text: string): void {+ for (const marker of SECRET_MARKERS) {+ expect(text).not.toContain(marker);+ }+}++// --- Service mocks -----------------------------------------------------------++const mockAgentService = vi.hoisted(() => ({ getById: vi.fn() }));+const mockLogActivity = vi.hoisted(() => vi.fn());+const mockHeartbeatService = vi.hoisted(() => ({ wakeup: vi.fn() }));+const mockIssueService = vi.hoisted(() => ({ getById: vi.fn(), getByIdentifier: vi.fn() }));+const mockInstanceSettingsService = vi.hoisted(() => ({+ get: vi.fn(),+ getExperimental: vi.fn(),+ getGeneral: vi.fn(),+ listCompanyIds: vi.fn(),+}));+const mockRunSecretRedactionRegistry = vi.hoisted(() => ({+ redactForRun: vi.fn(async (_companyId: string, _runId: string, value: unknown) => value),+}));++function registerModuleMocks(): void {+ vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));+ vi.doMock("../services/agents.js", () => ({ agentService: () => mockAgentService }));+ vi.doMock("../services/heartbeat.js", () => ({ heartbeatService: () => mockHeartbeatService }));+ vi.doMock("../services/instance-settings.js", () => ({+ instanceSettingsService: () => mockInstanceSettingsService,+ }));+ vi.doMock("../services/issues.js", () => ({ issueService: () => mockIssueService }));+ vi.doMock("../services/run-secret-redaction.js", () => ({+ createRunSecretRedactionRegistry: () => mockRunSecretRedactionRegistry,+ }));+ vi.doMock("../services/index.js", () => ({+ agentService: () => mockAgentService,+ agentInstructionsService: () => ({}),+ accessService: () => ({+ canUser: vi.fn(async () => true),+ decide: vi.fn(async (input: { action?: string }) => ({+ allowed: true,+ action: input.action,+ reason: "allow_explicit_grant",+ explanation: "Allowed by test grant.",+ })),+ hasPermission: vi.fn(async () => true),+ }),+ approvalService: () => ({}),+ builtInAgentService: () => ({ ensureCompanyDefaultAgentGrants: vi.fn() }),+ companySkillService: () => ({ listRuntimeSkillEntries: vi.fn() }),+ budgetService: () => ({}),+ heartbeatService: () => mockHeartbeatService,+ issueApprovalService: () => ({}),+ issueService: () => mockIssueService,+ logActivity: mockLogActivity,+ secretService: () => ({}),+ syncInstructionsBundleConfigFromFilePath: vi.fn((_agent: unknown, config: unknown) => config),+ workspaceOperationService: () => ({}),+ }));+ vi.doMock("../adapters/index.js", () => ({+ findServerAdapter: vi.fn(),+ listAdapterModels: vi.fn(),+ detectAdapterModel: vi.fn(),+ findActiveServerAdapter: vi.fn(),+ requireServerAdapter: vi.fn(),+ }));+}++// The actor the request middleware installs. A test switches the owner id to+// prove the owner-binding check (SR-3).+let currentActor: Record<string, unknown>;+function useOwner(userId: string = OWNER_USER_ID): void {+ currentActor = {+ type: "board",+ userId,+ companyIds: [COMPANY_ID],+ source: "local_implicit",+ isInstanceAdmin: false,+ };+}++// --- Fake transport ----------------------------------------------------------++interface TransportHandle {+ factory: SetupTokenLoginProcessFactory;+ leases: SetupTokenLeaseManager;+ store: SetupTokenCleanupStore;+ submittedCodes: string[];+}++/**+ * Builds a fake login transport. The factory surfaces the sign-in URL at once.+ * On submit it either completes the login and delivers the token, throws an+ * internal error, or leaves the process pending. The lease manager and the store+ * are in-memory and hold no secret.+ */+function buildTransport(opts: { onSubmit?: "complete" | "throw" | "pending" } = {}): TransportHandle {+ const mode = opts.onSubmit ?? "complete";+ const submittedCodes: string[] = [];+ const rows = new Map<string, SetupTokenCleanupRecord>();+ const store: SetupTokenCleanupStore = {+ async record(record) {+ rows.set(record.sessionId, { ...record });+ },+ async markState(sessionId, state) {+ const row = rows.get(sessionId);+ if (row) row.state = state;+ },+ async remove(sessionId) {+ rows.delete(sessionId);+ },+ async listReapable() {+ return [];+ },+ };+ const leases: SetupTokenLeaseManager = {+ async acquire() {+ return { id: "lease-1" };+ },+ async release() {},+ async releaseById() {},+ };+ const factory: SetupTokenLoginProcessFactory = ({ onPrompt, onCredential }) => {+ onPrompt({ url: FULL_LOGIN_URL });+ let resolveDone!: (outcome: SetupTokenLoginOutcome) => void;+ const done = new Promise<SetupTokenLoginOutcome>((resolve) => {+ resolveDone = resolve;+ });+ return {+ done,+ submitCode(code: string) {+ submittedCodes.push(code);+ if (mode === "throw") {+ throw new Error("the sandbox pseudo-terminal write failed.");+ }+ if (mode === "complete") {+ onCredential(MINTED_TOKEN);+ resolveDone("success");+ }+ // pending: the process stays open; the test drives no completion.+ },+ stop() {},+ };+ };+ return { factory, leases, store, submittedCodes };+}++// --- App builder with a capturing request logger -----------------------------++interface AppHandle {+ app: express.Express;+ logLines: string[];+}++async function createApp(opts: {+ deploymentMode?: "local_trusted" | "authenticated";+ confidentialProxyAllowlist?: string[];+ transport?: TransportHandle;+} = {}): Promise<AppHandle> {+ const [{ agentRoutes }, { errorHandler }, pinoModule, pinoHttpModule, redactModule] =+ await Promise.all([+ vi.importActual<typeof import("../routes/agents.js")>("../routes/agents.js"),+ vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),+ vi.importActual<typeof import("pino")>("pino"),+ vi.importActual<typeof import("pino-http")>("pino-http"),+ vi.importActual<typeof import("../middleware/redact-sensitive.js")>(+ "../middleware/redact-sensitive.js",+ ),+ ]);+ const { pino } = pinoModule;+ const { pinoHttp } = pinoHttpModule;+ const { redactSensitive } = redactModule;++ // Capture every request-log line into an array. The custom properties mirror+ // the production request logger: on a 4xx or 5xx response it logs the request+ // body, params, and query through `redactSensitive`, so a secret in a request+ // body cannot reach the log line.+ const logLines: string[] = [];+ const captureStream = new Writable({+ write(chunk, _encoding, callback) {+ logLines.push(chunk.toString());+ callback();+ },+ });+ const captureLogger = pino({ level: "debug" }, captureStream);+ const httpCapture = pinoHttp({+ logger: captureLogger,+ customProps(req, res) {+ if (res.statusCode < 400) return {};+ const ctx = (res as unknown as { __errorContext?: Record<string, unknown> }).__errorContext;+ if (ctx) {+ return {+ errorContext: ctx.error,+ reqBody: redactSensitive(ctx.reqBody),+ reqParams: redactSensitive(ctx.reqParams),+ reqQuery: redactSensitive(ctx.reqQuery),+ };+ }+ const props: Record<string, unknown> = {};+ const { body, params, query } = req as unknown as {+ body?: unknown;+ params?: unknown;+ query?: unknown;+ };+ if (body && typeof body === "object" && Object.keys(body).length > 0) {+ props.reqBody = redactSensitive(body);+ }+ if (params && typeof params === "object" && Object.keys(params).length > 0) {+ props.reqParams = redactSensitive(params);+ }+ if (query && typeof query === "object" && Object.keys(query).length > 0) {+ props.reqQuery = redactSensitive(query);+ }+ return props;+ },+ });++ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ (req as unknown as { actor: unknown }).actor = currentActor;+ next();+ });+ app.use(httpCapture);+ app.use(+ "/api",+ agentRoutes({} as never, {+ deploymentMode: opts.deploymentMode,+ confidentialProxyAllowlist: opts.confidentialProxyAllowlist,+ setupTokenLogin: opts.transport+ ? { factory: opts.transport.factory, leases: opts.transport.leases, store: opts.transport.store }+ : undefined,+ }),+ );+ app.use(errorHandler);+ return { app, logLines };+}++// Lets the pending microtasks settle, so the login-process `done` handler runs+// its terminal-state transition and the cleanup before the next request.+async function settle(): Promise<void> {+ for (let i = 0; i < 3; i += 1) {+ await new Promise((resolve) => setImmediate(resolve));+ }+}++const BASE = `/api/agents/${AGENT_ID}/setup-token-login-sessions`;++beforeEach(() => {+ vi.resetModules();+ registerModuleMocks();+ vi.clearAllMocks();+ useOwner();+ mockAgentService.getById.mockResolvedValue({+ id: AGENT_ID,+ companyId: COMPANY_ID,+ name: "Claude agent",+ adapterType: "claude_local",+ });+});++describe("setup-token login route — full path", () => {+ it("drives start, read-prompt, submit-code, and receive-token with a fake transport", async () => {+ const transport = buildTransport({ onSubmit: "complete" });+ const { app } = await createApp({ transport });++ // Start the session. The route returns the opaque id and no secret.+ const startRes = await request(app).post(BASE).send({});+ expect(startRes.status, JSON.stringify(startRes.body)).toBe(201);+ const sessionId = startRes.body.sessionId as string;+ expect(sessionId).toBeTruthy();+ expect(startRes.headers["cache-control"]).toBe("no-store");+ expectNoSecret(JSON.stringify(startRes.body));++ // Read the prompt. The owner response carries the full URL, with no-store.+ const promptRes = await request(app).get(`${BASE}/${sessionId}/prompt`).send();+ expect(promptRes.status, JSON.stringify(promptRes.body)).toBe(200);+ expect(promptRes.body.loginUrl).toBe(FULL_LOGIN_URL);+ expect(promptRes.body.state).toBe("awaiting_code");+ expect(promptRes.headers["cache-control"]).toBe("no-store");++ // Submit the one browser code. The response carries no secret.+ const codeRes = await request(app).post(`${BASE}/${sessionId}/code`).send({ browserCode: BROWSER_CODE });+ expect(codeRes.status, JSON.stringify(codeRes.body)).toBe(200);+ expect(transport.submittedCodes).toEqual([BROWSER_CODE]);+ expectNoSecret(JSON.stringify(codeRes.body));++ await settle();++ // Receive the token one time. The owner response carries the token, with+ // no-store.+ const tokenRes = await request(app).post(`${BASE}/${sessionId}/token`).send({});+ expect(tokenRes.status, JSON.stringify(tokenRes.body)).toBe(200);+ expect(tokenRes.body.token).toBe(MINTED_TOKEN);+ expect(tokenRes.headers["cache-control"]).toBe("no-store");++ // The second receive returns the same not-found error as a missing session.+ const secondTokenRes = await request(app).post(`${BASE}/${sessionId}/token`).send({});+ expect(secondTokenRes.status).toBe(404);+ expect(secondTokenRes.body.error).toBe(SETUP_TOKEN_SESSION_NOT_FOUND);+ });++ it("returns the fixed no-secret error when no transport is bound", async () => {+ const { app } = await createApp({});+ const startRes = await request(app).post(BASE).send({});+ expect(startRes.status).toBe(503);+ expect(startRes.headers["cache-control"]).toBe("no-store");+ expectNoSecret(JSON.stringify(startRes.body));+ });++ it("binds the session to the owner: a different owner gets the same not-found error", async () => {+ const transport = buildTransport({ onSubmit: "pending" });+ const { app } = await createApp({ transport });++ const startRes = await request(app).post(BASE).send({});+ const sessionId = startRes.body.sessionId as string;++ // A different owner reads the same id. The route returns the not-found error,+ // so a caller cannot tell a cross-owner session from a missing one.+ useOwner(OTHER_USER_ID);+ const promptRes = await request(app).get(`${BASE}/${sessionId}/prompt`).send();+ expect(promptRes.status).toBe(404);+ expect(promptRes.body.error).toBe(SETUP_TOKEN_SESSION_NOT_FOUND);+ expect(JSON.stringify(promptRes.body)).not.toContain(URL_CODE_QUERY);+ });+});++describe("setup-token login route — SR-1 and SR-5 (no secret in a sink)", () => {+ it("keeps the code, the URL query, and the token out of every log, activity, and non-owner sink", async () => {+ const transport = buildTransport({ onSubmit: "complete" });+ const { app, logLines } = await createApp({ transport });++ const startRes = await request(app).post(BASE).send({});+ const sessionId = startRes.body.sessionId as string;++ // The invalid-session path: a bogus id with the code in the body.+ const invalidRes = await request(app)+ .post(`${BASE}/bogus-session-id/code`)+ .send({ browserCode: BROWSER_CODE });+ expect(invalidRes.status).toBe(404);+ expect(invalidRes.body.error).toBe(SETUP_TOKEN_SESSION_NOT_FOUND);+ expectNoSecret(JSON.stringify(invalidRes.body));++ // The first submit completes the login.+ const firstCode = await request(app).post(`${BASE}/${sessionId}/code`).send({ browserCode: BROWSER_CODE });+ expect(firstCode.status).toBe(200);+ await settle();++ // The duplicate-submit path: the same code again, after completion.+ const duplicateRes = await request(app)+ .post(`${BASE}/${sessionId}/code`)+ .send({ browserCode: BROWSER_CODE });+ expect(duplicateRes.status).toBe(409);+ expect(duplicateRes.body.error).toBe(SETUP_TOKEN_SUBMIT_CONFLICT);+ expectNoSecret(JSON.stringify(duplicateRes.body));++ await settle();++ // The request log holds no secret, and it did log the redacted request body,+ // so the check is not vacuous.+ const logText = logLines.join("\n");+ expectNoSecret(logText);+ expect(logText).toContain("[REDACTED]");++ // No activity detail holds a secret.+ const activityText = JSON.stringify(mockLogActivity.mock.calls);+ expectNoSecret(activityText);+ });++ it("keeps the code out of the exception metadata on the internal-error path", async () => {+ const transport = buildTransport({ onSubmit: "throw" });+ const { app, logLines } = await createApp({ transport });++ const startRes = await request(app).post(BASE).send({});+ const sessionId = startRes.body.sessionId as string;++ const errorRes = await request(app).post(`${BASE}/${sessionId}/code`).send({ browserCode: BROWSER_CODE });+ expect(errorRes.status).toBe(500);+ expect(errorRes.body.error).toBe("Internal server error");+ expectNoSecret(JSON.stringify(errorRes.body));++ await settle();+ const logText = logLines.join("\n");+ expectNoSecret(logText);+ });+});++describe("setup-token login route — SR-6 and SR-7 (fail-closed transport guard)", () => {+ it("rejects a non-TLS confidential request and a spoofed forwarded protocol", async () => {+ // Authenticated mode with no proxy allowlist: a loopback HTTP peer does not+ // pass the confidential guard, so read-prompt and receive-token fail closed.+ const transport = buildTransport({ onSubmit: "complete" });+ const { app } = await createApp({ transport, deploymentMode: "authenticated", confidentialProxyAllowlist: [] });++ const startRes = await request(app).post(BASE).send({});+ const sessionId = startRes.body.sessionId as string;++ // read-prompt over plain HTTP → fixed no-secret error, no URL.+ const promptRes = await request(app).get(`${BASE}/${sessionId}/prompt`).send();+ expect(promptRes.status).toBe(403);+ expect(promptRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expect(promptRes.headers["cache-control"]).toBe("no-store");+ expect(promptRes.body.loginUrl).toBeUndefined();+ expectNoSecret(JSON.stringify(promptRes.body));++ // A spoofed forwarded protocol does not unlock the response. The guard reads+ // the raw socket, not the header, unless the peer is on the allowlist.+ const spoofRes = await request(app)+ .get(`${BASE}/${sessionId}/prompt`)+ .set("X-Forwarded-Proto", "https")+ .send();+ expect(spoofRes.status).toBe(403);+ expect(spoofRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expectNoSecret(JSON.stringify(spoofRes.body));++ // submit-code over plain HTTP → the guard fails closed. The browser code is+ // the confidential OAuth secret, so it must never ride an untrusted transport.+ // A spoofed forwarded protocol does not unlock it either. The code never+ // reaches the transport.+ const codeRes = await request(app).post(`${BASE}/${sessionId}/code`).send({ browserCode: BROWSER_CODE });+ expect(codeRes.status).toBe(403);+ expect(codeRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expectNoSecret(JSON.stringify(codeRes.body));++ const spoofCodeRes = await request(app)+ .post(`${BASE}/${sessionId}/code`)+ .set("X-Forwarded-Proto", "https")+ .send({ browserCode: BROWSER_CODE });+ expect(spoofCodeRes.status).toBe(403);+ expect(spoofCodeRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expectNoSecret(JSON.stringify(spoofCodeRes.body));++ expect(transport.submittedCodes).toEqual([]);++ // receive-token over plain HTTP also fails closed and leaks no token.+ const tokenRes = await request(app)+ .post(`${BASE}/${sessionId}/token`)+ .set("X-Forwarded-Proto", "https")+ .send({});+ expect(tokenRes.status).toBe(403);+ expect(tokenRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expect(tokenRes.body.token).toBeUndefined();+ expectNoSecret(JSON.stringify(tokenRes.body));+ });++ it("ignores a forwarded protocol from a non-allowlisted peer", async () => {+ // A non-empty allowlist that does not match the loopback peer still fails+ // closed for a forwarded HTTPS protocol.+ const transport = buildTransport({ onSubmit: "pending" });+ const { app } = await createApp({+ transport,+ deploymentMode: "authenticated",+ confidentialProxyAllowlist: ["10.0.0.1"],+ });++ const startRes = await request(app).post(BASE).send({});+ const sessionId = startRes.body.sessionId as string;++ const promptRes = await request(app)+ .get(`${BASE}/${sessionId}/prompt`)+ .set("X-Forwarded-Proto", "https")+ .send();+ expect(promptRes.status).toBe(403);+ expect(promptRes.body.error).toBe(SETUP_TOKEN_TRANSPORT_INSECURE);+ expectNoSecret(JSON.stringify(promptRes.body));+ });+});diff --git a/server/src/services/setup-token-session.test.ts b/server/src/services/setup-token-session.test.tsnew file mode 100644index 0000000000..7614d9a807--- /dev/null+++ b/server/src/services/setup-token-session.test.ts@@ -0,0 +1,547 @@+import { describe, expect, it } from "vitest";+import {+ SetupTokenSessionService,+ SetupTokenSessionError,+ assessConfidentialStartup,+ evaluateConfidentialTransport,+ isTerminalSessionState,+ toSanitizedLoginUrl,+ SETUP_TOKEN_SESSION_NOT_FOUND,+ SETUP_TOKEN_SUBMIT_CONFLICT,+ SETUP_TOKEN_RATE_LIMITED,+ SETUP_TOKEN_CAP_EXCEEDED,+ SETUP_TOKEN_TOKEN_UNAVAILABLE,+ type SetupTokenCleanupRecord,+ type SetupTokenCleanupStore,+ type SetupTokenCredentialSink,+ type SetupTokenLease,+ type SetupTokenLeaseManager,+ type SetupTokenLoginOutcome,+ type SetupTokenLoginProcess,+ type SetupTokenLoginProcessFactory,+ type SetupTokenPromptSink,+ type SetupTokenRateLimiter,+ type SetupTokenSessionScope,+} from "./setup-token-session.js";+import { redactSensitive } from "../middleware/redact-sensitive.js";+import { sanitizeRecord } from "../redaction.js";++const FULL_LOGIN_URL =+ "https://claude.com/cai/oauth/authorize?client_id=abc&code=SECRETCODE123&code_challenge=xyz&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost&response_type=code&scope=org&state=STATEVALUE";++// A synthetic token. The session passes the token through in memory; it does not+// parse it. No real token is present.+const SYNTH_TOKEN = "sk-ant-oat01-SYNTHETICSYNTHETICSYNTHETIC01";++const OWNER_SCOPE: SetupTokenSessionScope = {+ companyId: "company-1",+ ownerUserId: "user-1",+ targetAgentId: "agent-1",+};++/** A controllable fake login process. It records the call order into `events`. */+class FakeProcess implements SetupTokenLoginProcess {+ readonly done: Promise<SetupTokenLoginOutcome>;+ private resolveDone!: (outcome: SetupTokenLoginOutcome) => void;+ submittedCode: string | null = null;+ submitCalls = 0;+ stopCalls = 0;+ constructor(+ readonly id: string,+ readonly onPrompt: SetupTokenPromptSink,+ readonly onCredential: SetupTokenCredentialSink,+ private readonly events: string[],+ ) {+ this.done = new Promise((resolve) => {+ this.resolveDone = resolve;+ });+ }+ surfacePrompt(url: string): void {+ this.onPrompt({ url });+ }+ surfaceCredential(token: string): void {+ this.onCredential(token);+ }+ finish(outcome: SetupTokenLoginOutcome): void {+ this.resolveDone(outcome);+ }+ submitCode(code: string): void {+ this.submitCalls += 1;+ this.submittedCode = code;+ this.events.push(`submit:${this.id}`);+ }+ stop(): void {+ this.stopCalls += 1;+ this.events.push(`stop:${this.id}`);+ }+}++class FakeLeaseManager implements SetupTokenLeaseManager {+ acquired: string[] = [];+ released: string[] = [];+ releaseByIdCalls: string[] = [];+ failReleaseOnce = false;+ private counter = 0;+ constructor(private readonly events: string[] = []) {}+ async acquire(input: { scope: SetupTokenSessionScope; deadline: number }): Promise<SetupTokenLease> {+ this.counter += 1;+ const id = `lease-${this.counter}`;+ this.acquired.push(id);+ return { id };+ }+ async release(lease: SetupTokenLease): Promise<void> {+ if (this.failReleaseOnce) {+ this.failReleaseOnce = false;+ throw new Error("release failed");+ }+ this.released.push(lease.id);+ this.events.push(`release:${lease.id}`);+ }+ async releaseById(leaseId: string): Promise<void> {+ this.releaseByIdCalls.push(leaseId);+ this.released.push(leaseId);+ }+}++class FakeStore implements SetupTokenCleanupStore {+ rows = new Map<string, SetupTokenCleanupRecord>();+ async record(record: SetupTokenCleanupRecord): Promise<void> {+ this.rows.set(record.sessionId, { ...record });+ }+ async markState(sessionId: string, state: SetupTokenCleanupRecord["state"]): Promise<void> {+ const row = this.rows.get(sessionId);+ if (row) row.state = state;+ }+ async remove(sessionId: string): Promise<void> {+ this.rows.delete(sessionId);+ }+ async listReapable(now: number): Promise<SetupTokenCleanupRecord[]> {+ return [...this.rows.values()].filter(+ (row) => isTerminalSessionState(row.state) || row.deadline <= now,+ );+ }+}++function allowAllRateLimiter(): SetupTokenRateLimiter {+ return { consume: () => ({ allowed: true, retryAfterSeconds: 0 }) };+}++function buildService(overrides: {+ events?: string[];+ leases?: FakeLeaseManager;+ store?: FakeStore;+ rateLimiter?: SetupTokenRateLimiter;+ caps?: { perOwner: number; perAgent: number; perCompany: number };+ ttlMs?: number;+ tokenRetentionMs?: number;+ now?: () => number;+} = {}) {+ const events = overrides.events ?? [];+ const processes: FakeProcess[] = [];+ let processCounter = 0;+ const factory: SetupTokenLoginProcessFactory = ({ onPrompt, onCredential }) => {+ processCounter += 1;+ const process = new FakeProcess(`p${processCounter}`, onPrompt, onCredential, events);+ processes.push(process);+ return process;+ };+ const leases = overrides.leases ?? new FakeLeaseManager(events);+ const store = overrides.store ?? new FakeStore();+ const service = new SetupTokenSessionService({+ factory,+ leases,+ store,+ rateLimiter: overrides.rateLimiter ?? allowAllRateLimiter(),+ caps: overrides.caps ?? { perOwner: 5, perAgent: 5, perCompany: 5 },+ ttlMs: overrides.ttlMs ?? 60_000,+ tokenRetentionMs: overrides.tokenRetentionMs,+ now: overrides.now,+ });+ return { service, processes, leases, store, events };+}++describe("SetupTokenSessionService.start", () => {+ it("returns a session id and no token, and holds one live process and lease", async () => {+ const { service, processes, leases } = buildService();+ const result = await service.start(OWNER_SCOPE);+ expect(result.sessionId).toBeTruthy();+ expect(result).not.toHaveProperty("token");+ expect(processes).toHaveLength(1);+ expect(leases.acquired).toEqual(["lease-1"]);+ expect(service.activeSessionCount()).toBe(1);+ });++ it("returns an opaque, high-entropy session id", async () => {+ const { service } = buildService();+ const a = await service.start(OWNER_SCOPE);+ const b = await service.start({ ...OWNER_SCOPE, ownerUserId: "user-2" });+ expect(a.sessionId).not.toEqual(b.sessionId);+ expect(a.sessionId.length).toBeGreaterThanOrEqual(32);+ });++ it("rejects a caller over the rate limit with 429", async () => {+ let allowed = true;+ const rateLimiter: SetupTokenRateLimiter = {+ consume: () => {+ const decision = { allowed, retryAfterSeconds: allowed ? 0 : 30 };+ allowed = false;+ return decision;+ },+ };+ const { service } = buildService({ rateLimiter });+ await service.start(OWNER_SCOPE);+ await expect(service.start(OWNER_SCOPE)).rejects.toMatchObject({+ status: 429,+ message: SETUP_TOKEN_RATE_LIMITED,+ });+ });++ it("rejects a caller over the per-owner cap with 429", async () => {+ const { service } = buildService({ caps: { perOwner: 1, perAgent: 5, perCompany: 5 } });+ await service.start(OWNER_SCOPE);+ await expect(service.start({ ...OWNER_SCOPE, targetAgentId: "agent-2" })).rejects.toMatchObject({+ status: 429,+ message: SETUP_TOKEN_CAP_EXCEEDED,+ });+ });+});++describe("SetupTokenSessionService.readPrompt", () => {+ it("returns the full login URL to the authorized owner once the prompt surfaces", async () => {+ const { service, processes } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ expect(service.readPrompt(sessionId, OWNER_SCOPE).loginUrl).toBeNull();+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ const view = service.readPrompt(sessionId, OWNER_SCOPE);+ expect(view.state).toBe("awaiting_code");+ expect(view.loginUrl).toBe(FULL_LOGIN_URL);+ });+});++describe("SetupTokenSessionService.submitCode", () => {+ it("accepts one browser code, advances the live session once, and rejects every later submit", async () => {+ const { service, processes } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);++ const first = service.submitCode(sessionId, OWNER_SCOPE, "browsercode-1");+ expect(first.state).toBe("submitting");+ expect(processes[0].submitCalls).toBe(1);+ expect(processes[0].submittedCode).toBe("browsercode-1");++ expect(() => service.submitCode(sessionId, OWNER_SCOPE, "browsercode-2")).toThrow(+ SETUP_TOKEN_SUBMIT_CONFLICT,+ );+ // A later submit, including one after an invalid-code retry, never reaches+ // the live process.+ expect(processes[0].submitCalls).toBe(1);+ });++ it("rejects a submit before the prompt surfaces", async () => {+ const { service } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ expect(() => service.submitCode(sessionId, OWNER_SCOPE, "code")).toThrow(SetupTokenSessionError);+ });+});++describe("SetupTokenSessionService authorization boundary", () => {+ const crossCompany: SetupTokenSessionScope = { ...OWNER_SCOPE, companyId: "company-2" };+ const sameCompanyOtherUser: SetupTokenSessionScope = { ...OWNER_SCOPE, ownerUserId: "user-9" };+ const otherAgent: SetupTokenSessionScope = { ...OWNER_SCOPE, targetAgentId: "agent-9" };++ it("returns the same not-found for a cross-scope caller on every operation", async () => {+ const { service, processes } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);++ for (const scope of [crossCompany, sameCompanyOtherUser, otherAgent]) {+ expect(() => service.readPrompt(sessionId, scope)).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ expect(() => service.submitCode(sessionId, scope, "code")).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ expect(() => service.receiveToken(sessionId, scope)).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ await expect(service.cancel(sessionId, scope)).rejects.toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ await expect(service.expire(sessionId, scope)).rejects.toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ }+ });++ it("returns the same not-found for a missing session", async () => {+ const { service } = buildService();+ expect(() => service.readPrompt("missing", OWNER_SCOPE)).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ });+});++describe("SetupTokenSessionService cleanup order", () => {+ it("stops the direct child before the lease release on cancel", async () => {+ const events: string[] = [];+ const { service } = buildService({ events });+ const { sessionId } = await service.start(OWNER_SCOPE);+ await service.cancel(sessionId, OWNER_SCOPE);+ const stopIndex = events.indexOf("stop:p1");+ const releaseIndex = events.indexOf("release:lease-1");+ expect(stopIndex).toBeGreaterThanOrEqual(0);+ expect(releaseIndex).toBeGreaterThanOrEqual(0);+ expect(stopIndex).toBeLessThan(releaseIndex);+ expect(service.activeSessionCount()).toBe(0);+ });++ it("stops the direct child before the lease release on expire", async () => {+ const events: string[] = [];+ const { service } = buildService({ events });+ const { sessionId } = await service.start(OWNER_SCOPE);+ const result = await service.expire(sessionId, OWNER_SCOPE);+ expect(result.state).toBe("timed_out");+ expect(events.indexOf("stop:p1")).toBeLessThan(events.indexOf("release:lease-1"));+ });++ it("releases the lease when the process ends on its own", async () => {+ const { service, processes, leases } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ service.submitCode(sessionId, OWNER_SCOPE, "code");+ processes[0].finish("success");+ await new Promise((resolve) => setImmediate(resolve));+ expect(leases.released).toEqual(["lease-1"]);+ expect(service.activeSessionCount()).toBe(0);+ });+});++describe("SetupTokenSessionService durable reaper", () => {+ it("replays the durable record and releases the orphaned lease after a restart", async () => {+ const store = new FakeStore();+ const leases = new FakeLeaseManager();+ // Simulate a prior process that crashed with a live record and a lease.+ await store.record({+ sessionId: "orphan-1",+ companyId: "company-1",+ ownerUserId: "user-1",+ targetAgentId: "agent-1",+ leaseId: "lease-orphan",+ deadline: 1_000,+ state: "awaiting_code",+ });+ const { service } = buildService({ store, leases, now: () => 5_000 });+ const summary = await service.reap(5_000);+ expect(summary.released).toBe(1);+ expect(leases.releaseByIdCalls).toEqual(["lease-orphan"]);+ expect(store.rows.size).toBe(0);+ });++ it("keeps the record when the reaper lease release fails, so it stays retryable", async () => {+ const store = new FakeStore();+ await store.record({+ sessionId: "orphan-2",+ companyId: "company-1",+ ownerUserId: "user-1",+ targetAgentId: "agent-1",+ leaseId: "lease-orphan-2",+ deadline: 1_000,+ state: "failed",+ });+ const leases = new FakeLeaseManager();+ leases.releaseById = async () => {+ throw new Error("provider down");+ };+ const { service } = buildService({ store, leases, now: () => 5_000 });+ const summary = await service.reap(5_000);+ expect(summary.failed).toBe(1);+ expect(store.rows.has("orphan-2")).toBe(true);+ });+});++describe("SetupTokenSessionService.receiveToken", () => {+ it("returns the token once to the authorized owner after a successful login", async () => {+ const { service, processes, leases } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ service.submitCode(sessionId, OWNER_SCOPE, "code");+ processes[0].surfaceCredential(SYNTH_TOKEN);+ processes[0].finish("success");+ await new Promise((resolve) => setImmediate(resolve));+ // The service releases the sandbox lease at once, but it retains the token+ // for the owner to receive it one time.+ expect(leases.released).toEqual(["lease-1"]);+ const received = service.receiveToken(sessionId, OWNER_SCOPE);+ expect(received.token).toBe(SYNTH_TOKEN);+ // One-shot: a second receive returns the same not-found as a missing session.+ expect(() => service.receiveToken(sessionId, OWNER_SCOPE)).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ });++ it("returns the fixed unavailable error before the token is delivered", async () => {+ const { service, processes } = buildService();+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ service.submitCode(sessionId, OWNER_SCOPE, "code");+ // The login has not delivered the token yet, so receive-token is unavailable.+ expect(() => service.receiveToken(sessionId, OWNER_SCOPE)).toThrow(SETUP_TOKEN_TOKEN_UNAVAILABLE);+ });++ it("purges the retained token when the retention window ends", async () => {+ const { service, processes } = buildService({ tokenRetentionMs: 5 });+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ service.submitCode(sessionId, OWNER_SCOPE, "code");+ processes[0].surfaceCredential(SYNTH_TOKEN);+ processes[0].finish("success");+ await new Promise((resolve) => setTimeout(resolve, 20));+ // The retention timer purged the token, so the session is gone.+ expect(() => service.receiveToken(sessionId, OWNER_SCOPE)).toThrow(SETUP_TOKEN_SESSION_NOT_FOUND);+ });+});++describe("no secret reaches a sink (SR-1, SR-5)", () => {+ it("keeps the full login URL, the code, and the token out of the durable record", async () => {+ const store = new FakeStore();+ const { service, processes } = buildService({ store });+ const { sessionId } = await service.start(OWNER_SCOPE);+ processes[0].surfacePrompt(FULL_LOGIN_URL);+ service.submitCode(sessionId, OWNER_SCOPE, "SECRETCODE123");+ processes[0].surfaceCredential(SYNTH_TOKEN);+ const serialized = JSON.stringify([...store.rows.values()]);+ expect(serialized).not.toContain("SECRETCODE123");+ expect(serialized).not.toContain("STATEVALUE");+ expect(serialized).not.toContain("cai/oauth/authorize");+ expect(serialized).not.toContain(SYNTH_TOKEN);+ });++ it("sanitizes the login URL to origin and path only", () => {+ expect(toSanitizedLoginUrl(FULL_LOGIN_URL)).toBe("https://claude.com/cai/oauth/authorize");+ expect(toSanitizedLoginUrl("not a url")).toBe("[unparsable-login-url]");+ });++ it("redacts the browserCode and authorization_code in the HTTP-log sanitizer", () => {+ const redacted = redactSensitive({+ browserCode: "SECRETCODE123",+ authorization_code: "AUTHCODE",+ loginUrl: FULL_LOGIN_URL,+ nested: { browserCode: "SECRETCODE123" },+ }) as Record<string, unknown>;+ expect(redacted.browserCode).toBe("[REDACTED]");+ expect(redacted.authorization_code).toBe("[REDACTED]");+ expect(redacted.loginUrl).toBe("https://claude.com/cai/oauth/authorize");+ expect((redacted.nested as Record<string, unknown>).browserCode).toBe("[REDACTED]");+ });++ it("redacts the browserCode and authorization_code in the activity sanitizer", () => {+ const redacted = sanitizeRecord({+ browserCode: "SECRETCODE123",+ authorization_code: "AUTHCODE",+ loginUrl: FULL_LOGIN_URL,+ });+ const serialized = JSON.stringify(redacted);+ expect(serialized).not.toContain("SECRETCODE123");+ expect(serialized).not.toContain("AUTHCODE");+ expect(serialized).not.toContain("STATEVALUE");+ });+});++describe("confidential transport guard (SR-6, SR-7)", () => {+ const authenticatedNoProxy = {+ deploymentMode: "authenticated" as const,+ trustedProxies: [] as string[],+ };+ const authenticatedWithProxy = {+ deploymentMode: "authenticated" as const,+ trustedProxies: ["10.0.0.5"],+ };+ const localTrusted = { deploymentMode: "local_trusted" as const, trustedProxies: [] as string[] };++ it("allows a direct TLS request", () => {+ expect(+ evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: true,+ remoteAddress: "203.0.113.7",+ forwardedProto: undefined,+ }).allowed,+ ).toBe(true);+ });++ it("denies a direct non-loopback HTTP request (SR-6)", () => {+ const decision = evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: false,+ remoteAddress: "203.0.113.7",+ forwardedProto: undefined,+ });+ expect(decision.allowed).toBe(false);+ });++ it("allows a local_trusted loopback request as the only local exception (SR-6)", () => {+ expect(+ evaluateConfidentialTransport(localTrusted, {+ socketEncrypted: false,+ remoteAddress: "127.0.0.1",+ forwardedProto: undefined,+ }).allowed,+ ).toBe(true);+ // The same loopback request under authenticated mode fails closed.+ expect(+ evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: false,+ remoteAddress: "127.0.0.1",+ forwardedProto: undefined,+ }).allowed,+ ).toBe(false);+ });++ it("denies a spoofed X-Forwarded-Proto when no trusted proxy is configured (SR-6)", () => {+ const decision = evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: false,+ remoteAddress: "203.0.113.7",+ forwardedProto: "https",+ });+ expect(decision.allowed).toBe(false);+ });++ it("allows a forwarded HTTPS request from the configured proxy allowlist (SR-6, SR-7)", () => {+ const decision = evaluateConfidentialTransport(authenticatedWithProxy, {+ socketEncrypted: false,+ remoteAddress: "10.0.0.5",+ forwardedProto: "https",+ });+ expect(decision.allowed).toBe(true);+ });++ it("allows a forwarded HTTPS request from a proxy inside a configured CIDR (SR-7)", () => {+ const decision = evaluateConfidentialTransport(+ { deploymentMode: "authenticated", trustedProxies: ["10.0.0.0/24"] },+ { socketEncrypted: false, remoteAddress: "10.0.0.200", forwardedProto: "https" },+ );+ expect(decision.allowed).toBe(true);+ });++ it("denies a forwarded HTTPS request from a peer outside the allowlist (SR-7)", () => {+ const decision = evaluateConfidentialTransport(authenticatedWithProxy, {+ socketEncrypted: false,+ remoteAddress: "10.0.0.6",+ forwardedProto: "https",+ });+ expect(decision.allowed).toBe(false);+ });++ it("fails closed at startup when no proxy allowlist is configured (SR-7)", () => {+ expect(assessConfidentialStartup(authenticatedNoProxy).proxyForwardingEnabled).toBe(false);+ expect(assessConfidentialStartup(authenticatedWithProxy).proxyForwardingEnabled).toBe(true);+ });++ it("denies a direct non-loopback HTTP receive-token request, so it delivers no token (SR-6)", () => {+ // The route calls this guard before receive-token. A denied decision makes+ // the route return the fixed no-secret error and never read the token.+ const decision = evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: false,+ remoteAddress: "203.0.113.7",+ forwardedProto: undefined,+ });+ expect(decision.allowed).toBe(false);+ });++ it("denies a spoofed forwarded HTTPS receive-token request under a broad proxy setting (SR-7)", () => {+ // A broad `TRUST_PROXY=true` setting never populates the dedicated allowlist,+ // so the guard reads an empty allowlist and fails closed on the forwarded+ // protocol. The route returns the fixed no-secret error and delivers no+ // token.+ const decision = evaluateConfidentialTransport(authenticatedNoProxy, {+ socketEncrypted: false,+ remoteAddress: "203.0.113.7",+ forwardedProto: "https",+ });+ expect(decision.allowed).toBe(false);+ });+});diff --git a/server/src/services/setup-token-session.ts b/server/src/services/setup-token-session.tsnew file mode 100644index 0000000000..d57ab21213--- /dev/null+++ b/server/src/services/setup-token-session.ts@@ -0,0 +1,832 @@+// The Claude setup-token login session service. It owns a company-scoped,+// owner-bound login session that holds one live setup-token process and one+// sandbox lease for the whole login. The login is a two-way round-trip: the+// `claude setup-token` process holds the flow state in memory, so the server+// keeps one live process and the lease alive inside one long-lived server+// process. The service never re-spawns the command per request and never splits+// the round-trip across separate runs.+//+// The service gives the harness these operations against the one live session:+// start the session, read the login prompt, submit one browser code, cancel the+// session, expire the session on a timeout, and receive the token. Every+// operation verifies the company, the owner user, and the target agent. A+// missing session and a cross-scope session both return the same not-found+// error.+//+// Security controls folded here:+// * SR-1 (no secret in a log): the service keeps the full login URL, the+// browser code, and the token out of every log, activity detail, error, and+// telemetry sink. It surfaces the full URL only through the authorized owner+// read response, and it exposes a sanitized URL form to every other reader.+// * SR-3 (owner binding, atomic one-code): an opaque random session id, an+// immutable scope, and a single compare-and-set transition from+// `awaiting_code` to `submitting`. The service rejects every later submit.+// * SR-4 (durable cleanup and caps): a non-secret cleanup record, an external+// lease expiry no later than the session deadline, idempotent cleanup on+// every terminal path, a startup reaper, per-owner/agent/company caps, and a+// start rate limit.+// * SR-5 (two login-URL representations): the full URL is transport-only; every+// sink receives the sanitized URL form.+// * SR-6 and SR-7 (fail-closed TLS transport guard): a centralized guard that+// the route applies to the confidential read-prompt and receive-token+// responses. The guard is a pure function in this module so it stays unit+// testable.++import { randomBytes } from "node:crypto";++/** The session states. The four terminal states end the login. */+export type SetupTokenSessionState =+ | "starting"+ | "awaiting_code"+ | "submitting"+ | "completed"+ | "failed"+ | "timed_out"+ | "cancelled";++/** The four terminal states. Cleanup runs once when a session reaches one. */+export const SETUP_TOKEN_TERMINAL_STATES: readonly SetupTokenSessionState[] = [+ "completed",+ "failed",+ "timed_out",+ "cancelled",+];++export function isTerminalSessionState(state: SetupTokenSessionState): boolean {+ return SETUP_TOKEN_TERMINAL_STATES.includes(state);+}++/**+ * The immutable owner scope of a session. Every operation verifies all three+ * fields against the stored scope. The service builds the scope once at start+ * and never changes it.+ */+export interface SetupTokenSessionScope {+ companyId: string;+ ownerUserId: string;+ targetAgentId: string;+}++/** The terminal outcome of the live login process. */+export type SetupTokenLoginOutcome = "success" | "failure" | "timeout" | "cancelled";++/**+ * The live login process the service drives for one session. A production+ * factory binds this to the setup-token runner over a sandbox pseudo-terminal.+ * A unit test binds it to a fake. The process holds the flow state in memory.+ */+export interface SetupTokenLoginProcess {+ /** Resolves with the terminal outcome when the login process ends. */+ readonly done: Promise<SetupTokenLoginOutcome>;+ /**+ * Forwards the one browser code to the live process. The service calls it one+ * time, only after the single `awaiting_code` to `submitting` transition wins.+ */+ submitCode(code: string): void;+ /**+ * Stops the direct child process. The service calls it before it releases the+ * lease. The method must be safe to call more than one time.+ */+ stop(): void;+}++/** The prompt sink the factory calls one time when it surfaces the sign-in URL. */+export type SetupTokenPromptSink = (prompt: { url: string }) => void;++/**+ * The credential sink the factory calls one time when the login binds the minted+ * token from the success record. The service holds the token in memory only and+ * returns it one time through receive-token. The sink never logs the token.+ */+export type SetupTokenCredentialSink = (token: string) => void;++/**+ * Builds the live login process for one session. The factory receives the+ * prompt sink, the credential sink, the host timeout, and an abort signal that+ * the service aborts on cancel and on expiry. The factory delivers the token one+ * time through the credential sink.+ */+export type SetupTokenLoginProcessFactory = (params: {+ scope: SetupTokenSessionScope;+ onPrompt: SetupTokenPromptSink;+ onCredential: SetupTokenCredentialSink;+ timeoutMs: number;+ signal: AbortSignal;+}) => SetupTokenLoginProcess;++/** An opaque sandbox lease handle. The service holds one per session. */+export interface SetupTokenLease {+ id: string;+}++/**+ * Acquires and releases the sandbox lease for a login session. The production+ * manager wraps the environment runtime. The service sets an external lease+ * expiry no later than the session deadline through the `deadline` field.+ */+export interface SetupTokenLeaseManager {+ acquire(input: { scope: SetupTokenSessionScope; deadline: number }): Promise<SetupTokenLease>;+ release(lease: SetupTokenLease): Promise<void>;+ /** Releases a lease by id. The startup reaper uses this after a restart. */+ releaseById(leaseId: string): Promise<void>;+}++/**+ * The non-secret cleanup record. It holds only ids, the deadline, and the+ * terminal state. It never holds a URL, a code, a token, or a raw process chunk+ * (SR-4). The service persists it at start so a restart can reap the lease.+ */+export interface SetupTokenCleanupRecord {+ sessionId: string;+ companyId: string;+ ownerUserId: string;+ targetAgentId: string;+ leaseId: string;+ deadline: number;+ state: SetupTokenSessionState;+}++/**+ * The durable store for the non-secret cleanup record. A restart reads the+ * store and reaps a lease whose session is terminal or past its deadline. The+ * store persists no secret.+ */+export interface SetupTokenCleanupStore {+ record(record: SetupTokenCleanupRecord): Promise<void>;+ markState(sessionId: string, state: SetupTokenSessionState): Promise<void>;+ remove(sessionId: string): Promise<void>;+ /** Returns each record whose session is terminal or whose deadline is past. */+ listReapable(now: number): Promise<SetupTokenCleanupRecord[]>;+}++/** A per-key start rate limiter. It matches the invite-rate-limit shape. */+export interface SetupTokenRateLimiter {+ consume(key: string): { allowed: boolean; retryAfterSeconds: number };+}++export interface SetupTokenSessionCaps {+ perOwner: number;+ perAgent: number;+ perCompany: number;+}++export const DEFAULT_SETUP_TOKEN_SESSION_CAPS: SetupTokenSessionCaps = {+ perOwner: 1,+ perAgent: 1,+ perCompany: 3,+};++/** The default host timeout for one login session. */+export const DEFAULT_SETUP_TOKEN_SESSION_TTL_MS = 5 * 60_000;++/**+ * The default retention window for a completed token. The service releases the+ * sandbox lease at once on success, but it keeps the token in memory for this+ * window, so the authorized owner can receive it one time. A short window bounds+ * how long the service holds the secret if the owner never receives it (SR-4).+ */+export const DEFAULT_SETUP_TOKEN_RETENTION_MS = 60_000;++// The fixed, non-secret error texts. The route returns these verbatim and+// echoes no input. A missing session and a cross-scope session share one text,+// so a caller cannot tell them apart.+export const SETUP_TOKEN_SESSION_NOT_FOUND = "Setup-token login session not found.";+export const SETUP_TOKEN_SUBMIT_CONFLICT = "The setup-token login session cannot accept this code.";+export const SETUP_TOKEN_RATE_LIMITED = "Too many setup-token login attempts. Try again later.";+export const SETUP_TOKEN_CAP_EXCEEDED = "Too many active setup-token login sessions.";+export const SETUP_TOKEN_TRANSPORT_INSECURE =+ "This response requires a secure transport and is not available on this request.";+// The fixed error for a token that is not ready, or that the owner already+// received. It never tells the two cases apart, so it leaks no session state.+export const SETUP_TOKEN_TOKEN_UNAVAILABLE = "The setup-token is not available for this session.";+export const SETUP_TOKEN_START_FAILED = "The setup-token login session could not start.";++/** A typed error the route maps to a fixed status and the fixed text above. */+export class SetupTokenSessionError extends Error {+ readonly status: number;+ constructor(status: number, message: string) {+ super(message);+ this.name = "SetupTokenSessionError";+ this.status = status;+ }+}++/**+ * Builds the sanitized login-URL form for every non-owner sink (SR-5). The+ * function removes the query, the fragment, and the credentials, so no OAuth+ * parameter and no secret reaches a log, an activity detail, an error, a trace,+ * or client telemetry. It keeps the origin and the path for a useful diagnostic.+ * It returns a fixed placeholder for a value it cannot parse, so it never falls+ * back to the raw input.+ */+export function toSanitizedLoginUrl(rawUrl: string): string {+ try {+ const url = new URL(rawUrl);+ url.username = "";+ url.password = "";+ url.search = "";+ url.hash = "";+ return url.toString();+ } catch {+ return "[unparsable-login-url]";+ }+}++// --- SR-6 and SR-7: the confidential-response transport guard ----------------++/**+ * The startup transport configuration for the confidential responses. The+ * server resolves it once at startup. `trustedProxies` is the dedicated,+ * explicit proxy IP or CIDR allowlist for the confidential routes. The global+ * `TRUST_PROXY` setting does not appear here, so `TRUST_PROXY=true` and a+ * hop-count value never satisfy the guard (SR-7).+ */+export interface ConfidentialTransportConfig {+ deploymentMode: "local_trusted" | "authenticated";+ trustedProxies: string[];+}++/** The per-request transport signals the guard reads from the raw socket. */+export interface ConfidentialTransportRequest {+ /** The raw TLS bit on the immediate socket. It ignores `trust proxy`. */+ socketEncrypted: boolean;+ /** The immediate peer address. It ignores `trust proxy`. */+ remoteAddress: string | undefined;+ /** The `X-Forwarded-Proto` header value. The guard reads its first hop only. */+ forwardedProto: string | undefined;+}++export interface ConfidentialTransportDecision {+ allowed: boolean;+ reason: string;+}++function isLoopbackAddress(address: string | undefined): boolean {+ if (!address) return false;+ const normalized = address.trim().toLowerCase();+ if (normalized === "::1" || normalized === "localhost") return true;+ // Express reports an IPv4 loopback peer as `::ffff:127.0.0.1` on a dual stack.+ const withoutV4Prefix = normalized.startsWith("::ffff:")+ ? normalized.slice("::ffff:".length)+ : normalized;+ return withoutV4Prefix.startsWith("127.");+}++function ipv4ToInt(address: string): number | null {+ const parts = address.split(".");+ if (parts.length !== 4) return null;+ let value = 0;+ for (const part of parts) {+ if (!/^\d{1,3}$/.test(part)) return null;+ const octet = Number(part);+ if (octet > 255) return null;+ value = value * 256 + octet;+ }+ return value >>> 0;+}++/**+ * Returns true when `address` matches `entry`. `entry` is a single IPv4 or IPv6+ * address, or an IPv4 CIDR range. The function normalizes an IPv4-mapped IPv6+ * peer (`::ffff:a.b.c.d`) to its IPv4 form first. It matches an IPv6 entry only+ * by an exact, case-insensitive string, because the confidential allowlist+ * expects a small set of known proxy addresses.+ */+function addressMatchesEntry(address: string, entry: string): boolean {+ const peer = address.trim().toLowerCase();+ const candidate = entry.trim().toLowerCase();+ if (candidate.length === 0) return false;++ const peerV4 = peer.startsWith("::ffff:") ? peer.slice("::ffff:".length) : peer;++ if (candidate.includes("/")) {+ const [network, prefixText] = candidate.split("/");+ const prefix = Number(prefixText);+ const networkInt = ipv4ToInt(network);+ const peerInt = ipv4ToInt(peerV4);+ if (networkInt === null || peerInt === null) return false;+ if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;+ if (prefix === 0) return true;+ const mask = prefix === 32 ? 0xffffffff : (0xffffffff << (32 - prefix)) >>> 0;+ return (networkInt & mask) === (peerInt & mask);+ }++ if (candidate === peer || candidate === peerV4) return true;+ const candidateInt = ipv4ToInt(candidate);+ const peerInt = ipv4ToInt(peerV4);+ return candidateInt !== null && peerInt !== null && candidateInt === peerInt;+}++function peerMatchesAllowlist(address: string | undefined, allowlist: string[]): boolean {+ if (!address) return false;+ return allowlist.some((entry) => addressMatchesEntry(address, entry));+}++function forwardedProtoFirstHop(forwardedProto: string | undefined): string | null {+ if (!forwardedProto) return null;+ const first = forwardedProto.split(",")[0]?.trim().toLowerCase();+ return first && first.length > 0 ? first : null;+}++/**+ * Decides whether the request may receive a confidential response (the full+ * login URL or the token). The guard fails closed. It never trusts a+ * client-supplied header for the TLS decision unless the immediate peer is on+ * the dedicated proxy allowlist. It never reads the global `trust proxy`+ * setting.+ *+ * The guard allows a confidential response only in these cases:+ * 1. The immediate socket is TLS. A direct TLS request is always valid (SR-6).+ * 2. The deployment is `local_trusted` and the peer is loopback. This is the+ * only local exception (SR-6).+ * 3. The peer is on the dedicated proxy allowlist and the forwarded protocol's+ * first hop is `https`. A `TRUST_PROXY=true` or hop-count value does not+ * reach this branch, because the guard never reads it (SR-7).+ *+ * Every other request fails closed and the route returns the fixed no-secret+ * error.+ */+export function evaluateConfidentialTransport(+ config: ConfidentialTransportConfig,+ request: ConfidentialTransportRequest,+): ConfidentialTransportDecision {+ if (request.socketEncrypted) {+ return { allowed: true, reason: "direct_tls" };+ }+ if (config.deploymentMode === "local_trusted" && isLoopbackAddress(request.remoteAddress)) {+ return { allowed: true, reason: "local_trusted_loopback" };+ }+ if (+ config.trustedProxies.length > 0 &&+ peerMatchesAllowlist(request.remoteAddress, config.trustedProxies) &&+ forwardedProtoFirstHop(request.forwardedProto) === "https"+ ) {+ return { allowed: true, reason: "allowlisted_proxy_tls" };+ }+ return { allowed: false, reason: "insecure_transport" };+}++/**+ * Assesses the confidential transport at startup (SR-7). The server disables+ * proxy-forwarded confidential responses when the dedicated allowlist is empty.+ * A direct TLS request and a `local_trusted` loopback request still pass at+ * runtime, because the runtime guard checks them first. The server logs the+ * returned reason so an operator can see why forwarded requests fail closed.+ */+export function assessConfidentialStartup(config: ConfidentialTransportConfig): {+ proxyForwardingEnabled: boolean;+ reason: string;+} {+ if (config.trustedProxies.length > 0) {+ return { proxyForwardingEnabled: true, reason: "proxy_allowlist_configured" };+ }+ return {+ proxyForwardingEnabled: false,+ reason:+ config.deploymentMode === "local_trusted"+ ? "no_proxy_allowlist_local_trusted_loopback_only"+ : "no_proxy_allowlist_direct_tls_only",+ };+}++// --- The session service -----------------------------------------------------++interface StoredSession {+ id: string;+ scope: SetupTokenSessionScope;+ state: SetupTokenSessionState;+ deadline: number;+ lease: SetupTokenLease;+ process: SetupTokenLoginProcess;+ abort: AbortController;+ // The full login URL. The service holds it in memory only and returns it only+ // through the authorized owner read response (SR-5).+ loginUrl: string | null;+ // The minted token. The service holds it in memory only, from the credential+ // sink until the authorized owner receives it one time or the retention window+ // ends (SR-1, SR-4).+ token: string | null;+ timer: ReturnType<typeof setTimeout> | null;+ // The retention timer for a completed token. The service arms it after a+ // successful login and clears it when the owner receives the token.+ retentionTimer: ReturnType<typeof setTimeout> | null;+ cleanupDone: boolean;+}++/** The public read view of a session prompt. */+export interface SetupTokenPromptView {+ state: SetupTokenSessionState;+ /** The full login URL, present only when the prompt has surfaced (SR-5). */+ loginUrl: string | null;+}++export interface SetupTokenSessionServiceOptions {+ factory: SetupTokenLoginProcessFactory;+ leases: SetupTokenLeaseManager;+ store: SetupTokenCleanupStore;+ rateLimiter: SetupTokenRateLimiter;+ caps?: SetupTokenSessionCaps;+ ttlMs?: number;+ /** The retention window for a completed token. Defaults to the constant. */+ tokenRetentionMs?: number;+ now?: () => number;+ /** Returns an opaque, cryptographically random session id. */+ generateSessionId?: () => string;+ /** A non-leaking diagnostic sink. It receives only fixed status lines. */+ log?: (line: string) => void;+}++function defaultSessionId(): string {+ return randomBytes(32).toString("base64url");+}++/**+ * The setup-token login session service. It holds every live session in memory+ * and persists a non-secret cleanup record for each. It bounds active sessions+ * per owner, per agent, and per company, and it rate-limits the start path.+ */+export class SetupTokenSessionService {+ private readonly sessions = new Map<string, StoredSession>();+ private readonly factory: SetupTokenLoginProcessFactory;+ private readonly leases: SetupTokenLeaseManager;+ private readonly store: SetupTokenCleanupStore;+ private readonly rateLimiter: SetupTokenRateLimiter;+ private readonly caps: SetupTokenSessionCaps;+ private readonly ttlMs: number;+ private readonly tokenRetentionMs: number;+ private readonly now: () => number;+ private readonly generateSessionId: () => string;+ private readonly log: (line: string) => void;++ constructor(options: SetupTokenSessionServiceOptions) {+ this.factory = options.factory;+ this.leases = options.leases;+ this.store = options.store;+ this.rateLimiter = options.rateLimiter;+ this.caps = options.caps ?? DEFAULT_SETUP_TOKEN_SESSION_CAPS;+ this.ttlMs = options.ttlMs ?? DEFAULT_SETUP_TOKEN_SESSION_TTL_MS;+ this.tokenRetentionMs = options.tokenRetentionMs ?? DEFAULT_SETUP_TOKEN_RETENTION_MS;+ this.now = options.now ?? Date.now;+ this.generateSessionId = options.generateSessionId ?? defaultSessionId;+ this.log = options.log ?? (() => {});+ }++ private countActive(predicate: (session: StoredSession) => boolean): number {+ let count = 0;+ for (const session of this.sessions.values()) {+ if (!isTerminalSessionState(session.state) && predicate(session)) count += 1;+ }+ return count;+ }++ /**+ * Starts a login session. It rate-limits the start, enforces the caps,+ * acquires the lease with an external expiry no later than the deadline,+ * persists the non-secret cleanup record, and starts the one live process.+ * It returns the opaque session id and no token.+ */+ async start(scope: SetupTokenSessionScope): Promise<{ sessionId: string; state: SetupTokenSessionState }> {+ const rate = this.rateLimiter.consume(`${scope.companyId}:${scope.ownerUserId}`);+ if (!rate.allowed) {+ throw new SetupTokenSessionError(429, SETUP_TOKEN_RATE_LIMITED);+ }+ if (this.countActive((s) => s.scope.ownerUserId === scope.ownerUserId) >= this.caps.perOwner) {+ throw new SetupTokenSessionError(429, SETUP_TOKEN_CAP_EXCEEDED);+ }+ if (this.countActive((s) => s.scope.targetAgentId === scope.targetAgentId) >= this.caps.perAgent) {+ throw new SetupTokenSessionError(429, SETUP_TOKEN_CAP_EXCEEDED);+ }+ if (this.countActive((s) => s.scope.companyId === scope.companyId) >= this.caps.perCompany) {+ throw new SetupTokenSessionError(429, SETUP_TOKEN_CAP_EXCEEDED);+ }++ const sessionId = this.generateSessionId();+ const deadline = this.now() + this.ttlMs;+ const lease = await this.leases.acquire({ scope, deadline });++ await this.store.record({+ sessionId,+ companyId: scope.companyId,+ ownerUserId: scope.ownerUserId,+ targetAgentId: scope.targetAgentId,+ leaseId: lease.id,+ deadline,+ state: "starting",+ });++ const abort = new AbortController();+ const session: StoredSession = {+ id: sessionId,+ scope,+ state: "starting",+ deadline,+ lease,+ // The factory replaces this placeholder synchronously below.+ process: undefined as unknown as SetupTokenLoginProcess,+ abort,+ loginUrl: null,+ token: null,+ timer: null,+ retentionTimer: null,+ cleanupDone: false,+ };++ let process: SetupTokenLoginProcess;+ try {+ process = this.factory({+ scope,+ onPrompt: (prompt) => this.onPrompt(session, prompt),+ onCredential: (token) => this.onCredential(session, token),+ timeoutMs: this.ttlMs,+ signal: abort.signal,+ });+ } catch {+ // The factory could not start the process. Release the lease and drop the+ // durable record, then return a fixed, non-secret error.+ await this.releaseLeaseSafely(lease);+ await this.store.remove(sessionId).catch(() => {});+ throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);+ }++ session.process = process;+ session.timer = setTimeout(() => {+ void this.expireInternal(sessionId);+ }, this.ttlMs);+ // A timer must never keep the process alive on its own.+ if (typeof session.timer.unref === "function") session.timer.unref();++ this.sessions.set(sessionId, session);+ // The process outcome drives the terminal state and the cleanup.+ void process.done.then(+ (outcome) => this.onProcessDone(session, outcome),+ () => this.onProcessDone(session, "failure"),+ );++ return { sessionId, state: session.state };+ }++ private onPrompt(session: StoredSession, prompt: { url: string }): void {+ if (isTerminalSessionState(session.state)) return;+ // Hold the full URL in memory only. Never log it (SR-1, SR-5).+ session.loginUrl = prompt.url;+ if (session.state === "starting") {+ session.state = "awaiting_code";+ void this.store.markState(session.id, "awaiting_code").catch(() => {});+ }+ }++ /**+ * Receives the minted token from the login process. The service holds the+ * token in memory only, until the authorized owner receives it one time or the+ * retention window ends. It never logs the token (SR-1). It ignores a token+ * that arrives after a non-success terminal state.+ */+ private onCredential(session: StoredSession, token: string): void {+ if (isTerminalSessionState(session.state) && session.state !== "completed") return;+ session.token = token;+ }++ /**+ * Resolves a session for an operation. It returns the session only when the+ * id exists and the stored scope equals the caller scope in all three fields.+ * A missing session and a cross-scope session both throw the same not-found+ * error, so a caller cannot tell them apart (SR-3).+ */+ private resolveOwned(sessionId: string, scope: SetupTokenSessionScope): StoredSession {+ const session = this.sessions.get(sessionId);+ if (+ !session ||+ session.scope.companyId !== scope.companyId ||+ session.scope.ownerUserId !== scope.ownerUserId ||+ session.scope.targetAgentId !== scope.targetAgentId+ ) {+ throw new SetupTokenSessionError(404, SETUP_TOKEN_SESSION_NOT_FOUND);+ }+ return session;+ }++ /**+ * Returns the prompt view for the authorized owner. The full login URL rides+ * only in this response (SR-5). The route sets `Cache-Control: no-store` and+ * applies the confidential transport guard before it calls this method.+ */+ readPrompt(sessionId: string, scope: SetupTokenSessionScope): SetupTokenPromptView {+ const session = this.resolveOwned(sessionId, scope);+ return { state: session.state, loginUrl: session.loginUrl };+ }++ /**+ * Submits the one browser code. It performs the single compare-and-set from+ * `awaiting_code` to `submitting`, then forwards the code to the live process+ * one time. It rejects every later submit, including one after an+ * invalid-code retry (SR-3).+ */+ submitCode(sessionId: string, scope: SetupTokenSessionScope, code: string): { state: SetupTokenSessionState } {+ const session = this.resolveOwned(sessionId, scope);+ if (session.state !== "awaiting_code") {+ throw new SetupTokenSessionError(409, SETUP_TOKEN_SUBMIT_CONFLICT);+ }+ session.state = "submitting";+ void this.store.markState(session.id, "submitting").catch(() => {});+ session.process.submitCode(code);+ return { state: session.state };+ }++ /**+ * Cancels a session. It stops the direct child before it releases the lease.+ * It is idempotent: a cancel on a terminal session returns the terminal state.+ */+ async cancel(sessionId: string, scope: SetupTokenSessionScope): Promise<{ state: SetupTokenSessionState }> {+ const session = this.resolveOwned(sessionId, scope);+ if (isTerminalSessionState(session.state)) {+ return { state: session.state };+ }+ await this.terminate(session, "cancelled");+ return { state: session.state };+ }++ /**+ * Expires a session on a timeout. It stops the direct child before it releases+ * the lease. The harness can call it, and the deadline timer calls the same+ * path internally.+ */+ async expire(sessionId: string, scope: SetupTokenSessionScope): Promise<{ state: SetupTokenSessionState }> {+ const session = this.resolveOwned(sessionId, scope);+ if (isTerminalSessionState(session.state)) {+ return { state: session.state };+ }+ await this.terminate(session, "timed_out");+ return { state: session.state };+ }++ private async expireInternal(sessionId: string): Promise<void> {+ const session = this.sessions.get(sessionId);+ if (!session || isTerminalSessionState(session.state)) return;+ await this.terminate(session, "timed_out");+ }++ /**+ * Returns the token for the authorized owner one time. The service returns the+ * token only from a completed session that still holds it. It clears the token+ * and drops the retained session at once, so a second receive returns the same+ * not-found error as a missing session. It returns the fixed unavailable error+ * when the token is not ready or the owner already received it. The route+ * applies the confidential transport guard and sets `Cache-Control: no-store`+ * before it calls this method.+ */+ receiveToken(sessionId: string, scope: SetupTokenSessionScope): { token: string } {+ // The scope check still runs, so a cross-scope caller gets the same+ // not-found error, not the unavailable error.+ const session = this.resolveOwned(sessionId, scope);+ if (session.state !== "completed" || session.token === null) {+ throw new SetupTokenSessionError(409, SETUP_TOKEN_TOKEN_UNAVAILABLE);+ }+ const token = session.token;+ // One-shot delivery: clear the token and drop the retained session, so the+ // service never returns the token a second time (SR-1).+ this.purgeRetained(session.id);+ return { token };+ }++ /**+ * Stops the direct child, then runs the idempotent cleanup. The order stops+ * the child before the lease release on every terminal path (SR-4).+ */+ private async terminate(session: StoredSession, state: SetupTokenSessionState): Promise<void> {+ if (isTerminalSessionState(session.state)) return;+ session.state = state;+ session.abort.abort();+ try {+ session.process.stop();+ } catch {+ this.log("[paperclip] Setup-token session: the process stop step errored.");+ }+ await this.runCleanup(session, state);+ }++ /**+ * Maps the live process outcome to the terminal state and runs the cleanup.+ * A cancel or an expire already set the state, so this call is a no-op then.+ */+ private async onProcessDone(session: StoredSession, outcome: SetupTokenLoginOutcome): Promise<void> {+ if (isTerminalSessionState(session.state) && session.cleanupDone) return;+ const state: SetupTokenSessionState =+ outcome === "success"+ ? "completed"+ : outcome === "timeout"+ ? "timed_out"+ : outcome === "cancelled"+ ? "cancelled"+ : "failed";+ if (!isTerminalSessionState(session.state)) {+ session.state = state;+ }+ await this.runCleanup(session, session.state);+ }++ /**+ * Runs the idempotent cleanup for a terminal session: clear the timer, mark+ * the durable record terminal, release the lease, and drop the in-memory+ * session. It clears the in-memory login URL reference promptly (SR-3, SR-5).+ * A cleanup failure stays retryable and records no process output (SR-4).+ *+ * A completed session that still holds a token stays in memory until the+ * authorized owner receives it one time or the retention window ends. The+ * cleanup still releases the sandbox lease at once; it only holds the token in+ * memory, not the sandbox (SR-4).+ */+ private async runCleanup(session: StoredSession, state: SetupTokenSessionState): Promise<void> {+ if (session.cleanupDone) return;+ session.cleanupDone = true;+ if (session.timer) {+ clearTimeout(session.timer);+ session.timer = null;+ }+ // Clear the secret-bearing reference promptly. Best-effort only (SR-5).+ session.loginUrl = null;+ try {+ await this.store.markState(session.id, state);+ } catch {+ this.log("[paperclip] Setup-token session: the cleanup record update failed; it stays retryable.");+ }+ await this.releaseLeaseSafely(session.lease);+ try {+ await this.store.remove(session.id);+ } catch {+ this.log("[paperclip] Setup-token session: the cleanup record removal failed; it stays retryable.");+ }+ if (state === "completed" && session.token !== null) {+ // Retain the token in memory for the owner to receive it one time. The+ // retention timer purges it if the owner never receives it (SR-4).+ session.retentionTimer = setTimeout(() => this.purgeRetained(session.id), this.tokenRetentionMs);+ if (typeof session.retentionTimer.unref === "function") session.retentionTimer.unref();+ return;+ }+ this.sessions.delete(session.id);+ }++ /**+ * Purges a retained completed session. It clears the token reference, clears+ * the retention timer, and drops the in-memory session. The owner receive path+ * and the retention timer both call it (SR-1, SR-4).+ */+ private purgeRetained(sessionId: string): void {+ const session = this.sessions.get(sessionId);+ if (!session) return;+ session.token = null;+ if (session.retentionTimer) {+ clearTimeout(session.retentionTimer);+ session.retentionTimer = null;+ }+ this.sessions.delete(sessionId);+ }++ private async releaseLeaseSafely(lease: SetupTokenLease): Promise<void> {+ try {+ await this.leases.release(lease);+ } catch {+ // The lease release stays retryable and alertable. The startup reaper+ // releases any lease that a crash or a failure left behind.+ this.log("[paperclip] Setup-token session: the lease release failed; the reaper retries it.");+ }+ }++ /**+ * The startup reaper. It reads the durable store and releases any lease whose+ * session is terminal or past its deadline. It runs after a restart, so it+ * frees a lease that a crash left behind (SR-4). A release failure stays+ * retryable: the reaper leaves the record for a later run.+ */+ async reap(now: number = this.now()): Promise<{ released: number; failed: number }> {+ const records = await this.store.listReapable(now);+ let released = 0;+ let failed = 0;+ for (const record of records) {+ try {+ await this.leases.releaseById(record.leaseId);+ await this.store.remove(record.sessionId);+ released += 1;+ } catch {+ failed += 1;+ this.log("[paperclip] Setup-token reaper: a lease release failed; it stays retryable.");+ }+ }+ return { released, failed };+ }++ /**+ * The graceful-shutdown cleanup. It cancels every live session, so the server+ * stops each direct child before it releases each lease (SR-4).+ */+ async shutdown(): Promise<void> {+ const live = [...this.sessions.values()].filter((s) => !isTerminalSessionState(s.state));+ for (const session of live) {+ await this.terminate(session, "cancelled");+ }+ }++ /** Returns the count of live sessions. The route and the tests use it. */+ activeSessionCount(): number {+ return this.countActive(() => true);+ }+}