agent-dealer 1.2.1 → 1.2.2

package/bundle/server/dist/capacity/cursor-individual-credentials.js

@@ -0,0 +1,238 @@
+// packages/server/src/capacity/cursor-individual-credentials.ts
+//
+// NOT-250: isolated credential lookup for the experimental Cursor Individual
+// dashboard adapter.
+//
+// The dashboard endpoints this feature calls are undocumented: the only
+// credential available is the existing local Cursor login, whose file
+// location and JSON shape are themselves not a supported contract and may
+// change without notice. All of that risk lives in this one module:
+//
+// - Candidate files are tried in order; the first readable file wins.
+// - Accepted JSON shapes are an explicit allowlist below — anything else
+//   reads `unparsable` (changed format), never a guess.
+// - `cursorIndividualCredentialStatus()` (the diagnostics surface) returns
+//   presence/path/format ONLY — never secret material.
+// - `loadCursorIndividualCredential()` additionally returns an in-memory
+//   `authHeader` for the dashboard HTTP call. The header value must never be
+//   persisted, returned to the browser, or logged — the adapter, repository,
+//   and route layers enforce that, and tests pin it.
+//
+// No silent opt-in or credential migration lives here: this module only
+// *finds* credentials; whether they may be *used* is decided by the
+// explicit `AGENT_DEALER_CURSOR_INDIVIDUAL_CAPACITY=experimental` opt-in in
+// cursor-individual.ts, which short-circuits before touching this module.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Explicit credential-file override (tests point this at tmp fixtures). */
+export const CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV = "CURSOR_INDIVIDUAL_CREDENTIAL_FILE";
+/** Home-directory override for tests (mirrors how OS home resolution works). */
+export const CURSOR_INDIVIDUAL_HOME_ENV = "CURSOR_INDIVIDUAL_HOME";
+/**
+ * Community-observed local Cursor login file. The location is undocumented
+ * and may move — when it does, reads degrade to `absent`/`unparsable`, never
+ * to a scan of unrelated files. Exactly one default candidate is listed on
+ * purpose: this module must not go hunting through the home directory.
+ */
+export const CURSOR_INDIVIDUAL_DEFAULT_RELATIVE_PATH = path.join(".cursor", "auth.json");
+/**
+ * Accepted top-level token keys. The credential format is undocumented, so
+ * both camelCase and snake_case spellings are tolerated — but ONLY these
+ * keys. An object with none of them is a changed format (`unparsable`).
+ */
+export const CURSOR_INDIVIDUAL_TOKEN_KEYS = [
+    "token",
+    "accessToken",
+    "access_token",
+    "sessionToken",
+    "session_token",
+    "authToken",
+    "auth_token",
+    "apiKey",
+    "api_key",
+    "jwt",
+];
+/**
+ * Accepted top-level WorkOS user-id keys. The dashboard's session cookie is
+ * `<userId>%3A%3A<token>` (see `cursorIndividualAuthHeader`) — a bare token
+ * is not enough. Same allowlist discipline as the token keys: an explicit
+ * field here wins; otherwise the id is derived from the token's own JWT
+ * `sub` claim (see `decodeJwtSubject`). Either source is normalized through
+ * `normalizeWorkosUserId` to strip a provider prefix.
+ */
+export const CURSOR_INDIVIDUAL_USER_ID_KEYS = [
+    "userId",
+    "user_id",
+    "workosUserId",
+    "workos_user_id",
+    "sub",
+];
+/** Nested objects tolerated one level deep (same key allowlists apply). */
+const NESTED_KEYS = ["auth", "data", "user"];
+function homeDir() {
+    const override = process.env[CURSOR_INDIVIDUAL_HOME_ENV]?.trim();
+    if (override)
+        return override;
+    return os.homedir();
+}
+/** Ordered candidate files: explicit override first, then the local login. */
+export function cursorIndividualCredentialCandidates() {
+    const override = process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV]?.trim();
+    if (override)
+        return [override];
+    return [path.join(homeDir(), CURSOR_INDIVIDUAL_DEFAULT_RELATIVE_PATH)];
+}
+function pickByKeys(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.trim())
+            return { key, value: value.trim() };
+    }
+    for (const nest of NESTED_KEYS) {
+        const inner = obj[nest];
+        if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+            for (const key of keys) {
+                const value = inner[key];
+                if (typeof value === "string" && value.trim()) {
+                    return { key: `${nest}.${key}`, value: value.trim() };
+                }
+            }
+        }
+    }
+    return null;
+}
+function pickToken(obj) {
+    const picked = pickByKeys(obj, CURSOR_INDIVIDUAL_TOKEN_KEYS);
+    return picked ? { key: picked.key, token: picked.value } : null;
+}
+function pickUserId(obj) {
+    return pickByKeys(obj, CURSOR_INDIVIDUAL_USER_ID_KEYS)?.value ?? null;
+}
+function base64UrlDecode(segment) {
+    try {
+        const padded = segment.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(segment.length / 4) * 4, "=");
+        return Buffer.from(padded, "base64").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The WorkOS session id is normally the JWT's own `sub` claim — decoded
+ * locally (no network, no signature verification: this only *reads* an id
+ * already present in a credential the caller trusts) so a plain access-token
+ * file still yields a usable id without a separate stored field. WorkOS
+ * subjects are commonly provider-prefixed (e.g. `google-oauth2|user_abc`);
+ * the raw claim is returned as-is here — `normalizeWorkosUserId` strips the
+ * prefix, applied uniformly to both this and an explicit `userId` field so
+ * either source lands on the same bare id.
+ */
+export function decodeJwtSubject(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const json = base64UrlDecode(parts[1]);
+    if (json === null)
+        return null;
+    try {
+        const payload = JSON.parse(json);
+        if (!payload || typeof payload !== "object")
+            return null;
+        const sub = payload.sub;
+        return typeof sub === "string" && sub.trim() ? sub.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Strips a WorkOS connection-type prefix (`google-oauth2|user_abc` →
+ * `user_abc`): the dashboard's own session cookie carries the bare id after
+ * the final `|`, never the provider-qualified subject.
+ */
+export function normalizeWorkosUserId(id) {
+    const at = id.lastIndexOf("|");
+    return at === -1 ? id : id.slice(at + 1);
+}
+/**
+ * Dashboard auth scheme: a `WorkosCursorSessionToken` cookie of
+ * `<userId>%3A%3A<token>` (community-observed: cursor-pulse, oh-my-pi,
+ * vct-core) — the dashboard rejects a Bearer `Authorization` header, and the
+ * `::` delimiter itself is percent-encoded in the live cookie value, not
+ * sent literally. The scheme is part of the undocumented surface and may
+ * drift (drift reads `unparsable`/`forbidden` at the HTTP layer, never a
+ * credential guess here). Returns the `Cookie` header VALUE (the caller
+ * sends it under the `Cookie` header name).
+ */
+export function cursorIndividualAuthHeader(userId, token) {
+    return `WorkosCursorSessionToken=${userId}%3A%3A${token}`;
+}
+function defaultReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a usable local Cursor credential. Never throws: unreadable files,
+ * invalid JSON, and unknown shapes all map to `absent`/`unparsable`.
+ * The raw token leaves this module only inside `authHeader`, held in memory
+ * for the single dashboard call the adapter makes with it.
+ */
+export function loadCursorIndividualCredential(readFile = defaultReadFile) {
+    for (const candidate of cursorIndividualCredentialCandidates()) {
+        const raw = readFile(candidate);
+        if (raw === null)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { status: "unparsable", path: candidate, format: null };
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { status: "unparsable", path: candidate, format: null };
+        }
+        const picked = pickToken(parsed);
+        if (!picked)
+            return { status: "unparsable", path: candidate, format: null };
+        // The cookie needs a user id too — an explicit field wins; otherwise
+        // derive it from the token's own JWT `sub` claim. Neither present means
+        // this credential cannot build a usable session, same as any other
+        // format drift. Either source may be provider-prefixed
+        // (`google-oauth2|user_abc`) — normalize both the same way.
+        const rawUserId = pickUserId(parsed) ?? decodeJwtSubject(picked.token);
+        if (!rawUserId)
+            return { status: "unparsable", path: candidate, format: picked.key };
+        // Re-check AFTER normalization: an id ending in `|` (e.g. a bare
+        // `"google-oauth2|"` with nothing after it) is non-empty here but
+        // normalizes to "" — that must degrade too, not build a cookie with an
+        // empty user id.
+        const userId = normalizeWorkosUserId(rawUserId);
+        if (!userId)
+            return { status: "unparsable", path: candidate, format: picked.key };
+        return {
+            status: "found",
+            path: candidate,
+            format: picked.key,
+            authHeader: cursorIndividualAuthHeader(userId, picked.token),
+        };
+    }
+    return { status: "absent", path: null, format: null };
+}
+/**
+ * Diagnostics-safe credential presence: delegates to the loader, then
+ * strips the in-memory secret. Safe to expose via logs and API responses.
+ */
+export function cursorIndividualCredentialStatus(readFile = defaultReadFile) {
+    const credential = loadCursorIndividualCredential(readFile);
+    return {
+        present: credential.status === "found",
+        path: credential.path,
+        format: credential.format,
+    };
+}

package/bundle/server/dist/capacity/cursor-individual-credentials.test.js

@@ -0,0 +1,185 @@
+// packages/server/src/capacity/cursor-individual-credentials.test.ts
+//
+// NOT-250: credential lookup is isolated behind an adapter, returns no
+// secret on diagnostics surfaces, and degrades on absent/changed formats.
+// Every case uses temporary fixture files (or an injected reader) — CI
+// never touches the real local Cursor login.
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV, CURSOR_INDIVIDUAL_HOME_ENV, cursorIndividualAuthHeader, cursorIndividualCredentialCandidates, cursorIndividualCredentialStatus, decodeJwtSubject, loadCursorIndividualCredential, normalizeWorkosUserId, } from "./cursor-individual-credentials.js";
+const SECRET = "fixture-secret-token-abc123";
+const USER_ID = "user_fixture_abc123";
+/** header.payload.signature with { sub: USER_ID } — no signature verification, so any value works. */
+function fixtureJwt(sub) {
+    const b64url = (obj) => Buffer.from(JSON.stringify(obj)).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return `${b64url({ alg: "none" })}.${b64url({ sub })}.sig`;
+}
+let dir;
+let savedFileEnv;
+let savedHomeEnv;
+beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cursor-indiv-creds-"));
+    savedFileEnv = process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
+    savedHomeEnv = process.env[CURSOR_INDIVIDUAL_HOME_ENV];
+});
+afterEach(() => {
+    if (savedFileEnv === undefined)
+        delete process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
+    else
+        process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV] = savedFileEnv;
+    if (savedHomeEnv === undefined)
+        delete process.env[CURSOR_INDIVIDUAL_HOME_ENV];
+    else
+        process.env[CURSOR_INDIVIDUAL_HOME_ENV] = savedHomeEnv;
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+function fixture(name, content) {
+    const file = path.join(dir, name);
+    fs.writeFileSync(file, content);
+    process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV] = file;
+    return file;
+}
+test("absent credential file reads absent with no path", () => {
+    process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV] = path.join(dir, "does-not-exist.json");
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "absent");
+    assert.equal(credential.path, null);
+    assert.equal(credential.format, null);
+    assert.equal(credential.authHeader, undefined);
+    const status = cursorIndividualCredentialStatus();
+    assert.deepEqual(status, { present: false, path: null, format: null });
+});
+test("empty home directory reads absent (no real login touched)", () => {
+    delete process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
+    process.env[CURSOR_INDIVIDUAL_HOME_ENV] = dir;
+    assert.deepEqual(cursorIndividualCredentialCandidates(), [
+        path.join(dir, ".cursor", "auth.json"),
+    ]);
+    assert.equal(loadCursorIndividualCredential().status, "absent");
+    assert.equal(cursorIndividualCredentialStatus().present, false);
+});
+test("accepted token shapes load with an in-memory auth header", () => {
+    const cases = [
+        { body: { token: SECRET, userId: USER_ID }, format: "token" },
+        { body: { accessToken: SECRET, userId: USER_ID }, format: "accessToken" },
+        { body: { access_token: SECRET, user_id: USER_ID }, format: "access_token" },
+        { body: { sessionToken: SECRET, userId: USER_ID }, format: "sessionToken" },
+        { body: { apiKey: SECRET, userId: USER_ID }, format: "apiKey" },
+        { body: { auth: { accessToken: SECRET }, userId: USER_ID }, format: "auth.accessToken" },
+    ];
+    for (const { body, format } of cases) {
+        const file = fixture("auth.json", JSON.stringify(body));
+        const credential = loadCursorIndividualCredential();
+        assert.equal(credential.status, "found");
+        assert.equal(credential.path, file);
+        assert.equal(credential.format, format);
+        assert.equal(credential.authHeader, cursorIndividualAuthHeader(USER_ID, SECRET));
+        assert.ok(credential.authHeader.includes(SECRET), "header carries the token in memory only");
+    }
+});
+test("a user id is derived from the token's own JWT `sub` claim when no explicit field is present", () => {
+    const jwt = fixtureJwt(USER_ID);
+    assert.equal(decodeJwtSubject(jwt), USER_ID);
+    fixture("auth.json", JSON.stringify({ token: jwt }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader(USER_ID, jwt));
+});
+test("an explicit user-id field wins over the token's own JWT `sub` claim", () => {
+    const jwt = fixtureJwt("jwt-subject-should-lose");
+    fixture("auth.json", JSON.stringify({ token: jwt, userId: USER_ID }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader(USER_ID, jwt));
+});
+test("a token with no derivable user id reads unparsable — never a Bearer-only guess", () => {
+    fixture("auth.json", JSON.stringify({ token: SECRET }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "unparsable");
+    assert.equal(credential.authHeader, undefined);
+});
+test("the auth header is the WorkosCursorSessionToken cookie with the :: delimiter percent-encoded", () => {
+    const header = cursorIndividualAuthHeader(USER_ID, SECRET);
+    assert.equal(header, `WorkosCursorSessionToken=${USER_ID}%3A%3A${SECRET}`);
+    // Never the raw, unencoded delimiter the dashboard rejects.
+    assert.ok(!header.includes(`${USER_ID}::${SECRET}`));
+});
+test("normalizeWorkosUserId strips a provider connection-type prefix", () => {
+    assert.equal(normalizeWorkosUserId("google-oauth2|user_abc"), "user_abc");
+    assert.equal(normalizeWorkosUserId("github|12345"), "12345");
+    // A bare id (no prefix) passes through unchanged.
+    assert.equal(normalizeWorkosUserId(USER_ID), USER_ID);
+    // Only the LAST `|` matters, in case a value itself contains one.
+    assert.equal(normalizeWorkosUserId("a|b|c"), "c");
+});
+test("a provider-prefixed JWT subject is normalized before it reaches the cookie", () => {
+    const jwt = fixtureJwt("google-oauth2|user_fixture");
+    fixture("auth.json", JSON.stringify({ token: jwt }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    // The cookie carries the bare id, never the provider-qualified subject.
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader("user_fixture", jwt));
+    assert.ok(!credential.authHeader.includes("google-oauth2"));
+});
+test("a provider-prefixed explicit userId field is normalized the same way", () => {
+    fixture("auth.json", JSON.stringify({ token: SECRET, userId: "github|user_fixture" }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader("user_fixture", SECRET));
+});
+test("an id that normalizes to empty (nothing after the final |) reads unparsable, never an empty-id cookie", () => {
+    // Non-empty before normalization (passes the raw presence check), but
+    // normalizeWorkosUserId("github|") === "" — must still degrade, not build
+    // WorkosCursorSessionToken=%3A%3A<token>.
+    assert.equal(normalizeWorkosUserId("github|"), "");
+    // Explicit-field path.
+    fixture("auth.json", JSON.stringify({ token: SECRET, userId: "github|" }));
+    const fromField = loadCursorIndividualCredential();
+    assert.equal(fromField.status, "unparsable");
+    assert.equal(fromField.authHeader, undefined);
+    // JWT-`sub`-derived path.
+    const jwt = fixtureJwt("github|");
+    fixture("auth.json", JSON.stringify({ token: jwt }));
+    const fromJwt = loadCursorIndividualCredential();
+    assert.equal(fromJwt.status, "unparsable");
+    assert.equal(fromJwt.authHeader, undefined);
+});
+test("changed credential formats read unparsable, never a guess", () => {
+    const changed = [
+        { totallyNewShape: true, session: { id: "abc" } },
+        { token: "" },
+        { token: "   " },
+        { token: 12345 },
+        { accessToken: null },
+        ["token-array"],
+        "just-a-string",
+        42,
+        null,
+    ];
+    for (const body of changed) {
+        fixture("auth.json", JSON.stringify(body));
+        const credential = loadCursorIndividualCredential();
+        assert.equal(credential.status, "unparsable", `body ${JSON.stringify(body)} must not parse`);
+        assert.equal(credential.authHeader, undefined);
+    }
+    fixture("auth.json", "{ not valid json{{{");
+    assert.equal(loadCursorIndividualCredential().status, "unparsable");
+});
+test("diagnostics status never carries secret material", () => {
+    fixture("auth.json", JSON.stringify({ token: SECRET, userId: USER_ID }));
+    const status = cursorIndividualCredentialStatus();
+    assert.equal(status.present, true);
+    assert.equal(status.format, "token");
+    assert.ok(!JSON.stringify(status).includes(SECRET), "raw token must not appear in status output");
+});
+test("unreadable files degrade to absent without throwing", () => {
+    // The default reader swallows read errors (missing file, directory at the
+    // candidate path, permissions): none of them throw out of the loader.
+    process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV] = dir;
+    assert.equal(loadCursorIndividualCredential().status, "absent");
+    process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV] = path.join(dir, "missing.json");
+    assert.equal(loadCursorIndividualCredential().status, "absent");
+    const dirAsFile = loadCursorIndividualCredential((_p) => null);
+    assert.equal(dirAsFile.status, "absent");
+});