@tickernelz/paperclip-pro-adapter-claude-local 2026.925.0

package/dist/server/setup-token-characterization.test.js

@@ -0,0 +1,123 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { parseSetupTokenPrompt, SETUP_TOKEN_AUTH_URLS, SETUP_TOKEN_PROMPT, SETUP_TOKEN_URL_QUERY_KEYS, } from "./setup-token-parse.js";
+// The live characterization of `claude setup-token`. This suite runs the real
+// Claude Code login command in a real pseudo-terminal, captures the sign-in
+// prompt output, and confirms the parser reads the real terminal contract. It
+// records the tested Claude Code version. It fails loudly on a parse miss, so a
+// terminal-contract drift breaks the suite instead of passing silently.
+//
+// The suite is opt-in. It needs the real `claude` binary, `python3` for the
+// pseudo-terminal, and network access to claude.com to mint the authorization
+// URL, so it never runs in a normal or a continuous-integration test run. Set
+// `RUN_CLAUDE_SETUP_TOKEN_CHARACTERIZATION=1` to run it in a real sandbox.
+//
+// Security: the suite drives only the prompt phase. It never submits a browser
+// code, so the command never mints a token. It parses the captured bytes in
+// memory and asserts only the non-secret shape (the URL origin, the URL path,
+// the URL query keys, and the constant prompt). It never writes the captured
+// bytes, the real authorization URL, or any token to a durable file, a log, or
+// an assertion message.
+const OPT_IN = process.env.RUN_CLAUDE_SETUP_TOKEN_CHARACTERIZATION === "1";
+// A pseudo-terminal harness. It runs `claude setup-token` on a real
+// pseudo-terminal with a wide window, streams the raw terminal bytes to its own
+// standard output, and stops when it sees the prompt phrase or after a timeout.
+// It never submits a code, so the command never mints a token.
+const PTY_HARNESS = `
+import os, pty, sys, select, time, fcntl, termios, struct, signal
+duration = float(os.environ.get("STCHAR_DURATION", "40"))
+cols, rows = 200, 50
+pid, fd = pty.fork()
+if pid == 0:
+    os.execvp("claude", ["claude", "setup-token"])
+    os._exit(127)
+fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+acc = b""
+start = time.time()
+try:
+    while time.time() - start < duration:
+        r, _, _ = select.select([fd], [], [], 0.5)
+        if fd in r:
+            try:
+                data = os.read(fd, 65536)
+            except OSError:
+                break
+            if not data:
+                break
+            acc += data
+            os.write(1, data)
+            if b"Paste code here if prompted" in acc:
+                break
+finally:
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    try:
+        os.waitpid(pid, 0)
+    except ChildProcessError:
+        pass
+`;
+function hasCommand(command) {
+    const probe = spawnSync("sh", ["-c", `command -v ${command}`], { encoding: "utf8" });
+    return probe.status === 0;
+}
+function readClaudeVersion() {
+    const raw = execFileSync("claude", ["--version"], { encoding: "utf8" });
+    // The version line reads like `2.1.226 (Claude Code)`. Read the leading
+    // semantic version.
+    const match = raw.match(/(\d+\.\d+\.\d+)/);
+    if (!match)
+        throw new Error("could not read the Claude Code version");
+    return match[1];
+}
+// Removes the terminal control sequences the same way the parser does, so the
+// test can assert on the rendered banner text. It keeps this local, so the test
+// never imports a parser internal.
+function renderForBanner(raw) {
+    return raw
+        // OSC sequences (hyperlinks and other OSC), BEL or ST terminated.
+        .replace(/\x1b\][^\x1b\x07]*(?:\x1b\\|\x07)/g, "")
+        // Horizontal-move CSI sequences render as one space.
+        .replace(/\x1b\[[0-9;]*[GC]/g, " ")
+        // Any remaining CSI sequence.
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "");
+}
+const run = OPT_IN ? describe : describe.skip;
+run("claude setup-token live characterization", () => {
+    it("reads the real sign-in prompt contract and records the Claude Code version", () => {
+        expect(hasCommand("claude"), "the claude binary must be installed").toBe(true);
+        expect(hasCommand("python3"), "python3 must be installed for the pseudo-terminal").toBe(true);
+        const version = readClaudeVersion();
+        const result = spawnSync("python3", ["-c", PTY_HARNESS], {
+            encoding: "buffer",
+            maxBuffer: 8 * 1024 * 1024,
+            env: { ...process.env, STCHAR_DURATION: "40" },
+        });
+        if (result.error)
+            throw result.error;
+        const raw = (result.stdout ?? Buffer.alloc(0)).toString("utf8");
+        // Fail loudly on a parse miss. A terminal-contract drift breaks the suite
+        // here instead of passing silently.
+        const parsed = parseSetupTokenPrompt(raw);
+        expect(parsed, "the parser did not read the live setup-token prompt").not.toBeNull();
+        const url = new URL(parsed.url);
+        // The live CLI emits one of the two accepted origin-and-path pairs. The
+        // installed version decides which pair the run records.
+        expect(SETUP_TOKEN_AUTH_URLS).toContain(`${url.origin}${url.pathname}`);
+        expect([...url.searchParams.keys()].sort()).toEqual([...SETUP_TOKEN_URL_QUERY_KEYS].sort());
+        expect(url.hash).toBe("");
+        expect(parsed.prompt).toBe(SETUP_TOKEN_PROMPT);
+        // The banner names the tested Claude Code version. This ties the recorded
+        // contract to the version that produced it.
+        const banner = renderForBanner(raw);
+        expect(banner).toContain(`Claude Code v${version}`);
+        // Record the tested version and the non-secret anchors. The reporter shows
+        // this line; it names no secret.
+        // eslint-disable-next-line no-console
+        console.log(`[characterization] Claude Code v${version}: prompt "${SETUP_TOKEN_PROMPT}", ` +
+            `URL ${url.origin}${url.pathname} with query keys ` +
+            `[${[...SETUP_TOKEN_URL_QUERY_KEYS].join(", ")}].`);
+    }, 60_000);
+});
+//# sourceMappingURL=setup-token-characterization.test.js.map

package/dist/server/setup-token-characterization.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-token-characterization.test.js","sourceRoot":"","sources":["../../src/server/setup-token-characterization.test.ts"],"names":[],"mappings":"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"}

package/dist/server/setup-token-parse.d.ts

@@ -0,0 +1,47 @@
+export interface SetupTokenPrompt {
+    url: string;
+    prompt: string;
+}
+export declare const SETUP_TOKEN_PROMPT = "Paste code here if prompted";
+export declare const SETUP_TOKEN_AUTH_URLS: readonly ["https://claude.ai/oauth/authorize", "https://claude.com/cai/oauth/authorize"];
+export declare const SETUP_TOKEN_REDIRECT_URI = "https://platform.claude.com/oauth/code/callback";
+export declare const SETUP_TOKEN_URL_QUERY_KEYS: readonly ["client_id", "code", "code_challenge", "code_challenge_method", "redirect_uri", "response_type", "scope", "state"];
+/**
+ * Parses Claude `setup-token` login output. Removes the terminal control
+ * sequences first, so colored and hyperlinked output reads the same as plain
+ * output. The parser finds the URL preamble, then a physical line that starts the
+ * authorization URL within {@link MAX_PREAMBLE_TO_URL_GAP} characters of the
+ * preamble, then reassembles the wrapped URL and validates the final string, then
+ * binds the browser-code prompt on the dedicated line after the URL block. 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 host, 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 declare function parseSetupTokenPrompt(text: string): SetupTokenPrompt | null;
+export declare const SETUP_TOKEN_PREFIX = "sk-ant-oat01-";
+export declare const SETUP_TOKEN_BEFORE_ANCHOR = "Your OAuth token (valid for 1 year):";
+export declare const SETUP_TOKEN_AFTER_ANCHOR = "Store this token securely. You won't be able to see it again.";
+/**
+ * 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 declare function parseSetupTokenCredential(text: string): string | null;
+//# sourceMappingURL=setup-token-parse.d.ts.map

package/dist/server/setup-token-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-token-parse.d.ts","sourceRoot":"","sources":["../../src/server/setup-token-parse.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,gBAAgB;IAE/B,GAAG,EAAE,MAAM,CAAC;IAGZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAOhE,eAAO,MAAM,qBAAqB,YAChC,mCAAmC,EACnC,wCAAwC,CAChC,CAAC;AAiBX,eAAO,MAAM,wBAAwB,oDAAoD,CAAC;AAK1F,eAAO,MAAM,0BAA0B,YACrC,WAAW,EACX,MAAM,EACN,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,OAAO,EACP,OAAO,CACC,CAAC;AAgTX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAyB3E;AAMD,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAIlD,eAAO,MAAM,yBAAyB,yCAAyC,CAAC;AAIhF,eAAO,MAAM,wBAAwB,kEAC4B,CAAC;AA6BlE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiCrE"}