codexteer 0.17.0 → 0.18.1

package/src/remote-control-auth.mjs

@@ -0,0 +1,109 @@
+import { lstat, readFile, realpath, mkdtemp, writeFile, rm } from "node:fs/promises";
+import { createHash, verify } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+import { BUNDLED_NODE } from "./wrapper.mjs";
+
+export const CONTROL_URL = "wss://chatgpt.com/backend-api/codex/remote/control/client";
+export const CONTROL_SCOPE = "remote_control_controller_websocket";
+export const CONTROL_AUDIENCE = "remote_control_client_websocket";
+export const controlFailure = (message, code = "REMOTE_CONTROL_UNVERIFIED") => Object.assign(new Error(message), { code });
+
+export function authIdentity(status) {
+  try {
+    if (!["chatgpt", "chatgptAuthTokens"].includes(status.authMethod) || typeof status.authToken !== "string") throw new Error();
+    const jwt = JSON.parse(Buffer.from(status.authToken.split(".")[1], "base64url")), auth = jwt["https://api.openai.com/auth"];
+    const accountId = auth.chatgpt_account_id ?? auth.account_id, accountUserId = auth.chatgpt_account_user_id ?? auth.account_user_id;
+    if (typeof accountId !== "string" || !accountId || typeof accountUserId !== "string" || !accountUserId
+      || !Number.isSafeInteger(jwt.exp) || jwt.exp <= Date.now() / 1000 || auth.is_fedramp === true) throw new Error();
+    const authUserId = typeof auth.user_id === "string" && auth.user_id && auth.user_id !== accountUserId ? auth.user_id : undefined;
+    return { accountId, accountUserId, ...(authUserId ? { authUserId } : {}) };
+  } catch { throw controlFailure("A current standard ChatGPT account token is required for the explicitly selected Remote Control route.", "REMOTE_AUTH_UNAVAILABLE"); }
+}
+
+export async function readEnrollment(home, identity) {
+  const canonical = await realpath(home), file = path.join(canonical, ".codex-global-state.json"), info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o022) || info.size > 32 * 1024 * 1024) throw controlFailure("Unsafe Desktop enrollment registry.", "REMOTE_ENROLLMENT_UNSAFE");
+  const state = JSON.parse(await readFile(file, "utf8"));
+  // Desktop also accepts the auth user alias from this same token when the
+  // account header matches its account claim. Our header is pinned to accountId.
+  const candidates = [...new Set([identity.accountUserId, identity.authUserId].filter(Boolean))];
+  let record;
+  for (const candidate of candidates) {
+    const key = ["Codex Desktop", "http://localhost:8000/api", "https://chatgpt.com/backend-api", "after-first-unlock-device-key-v1", candidate].join("\n");
+    const entry = state["electron-remote-control-client-enrollments"]?.[key];
+    if (entry?.accountUserId === candidate) { record = entry; break; }
+  }
+  if (!record || record.algorithm !== "ecdsa_p256_sha256"
+    || !["hardware_secure_enclave", "os_protected_nonextractable"].includes(record.protectionClass)
+    || ![record.clientId, record.keyId, record.publicKeySpkiDerBase64].every(x => typeof x === "string" && x.length > 0 && x.length < 8192)) {
+    throw controlFailure("No matching existing Desktop device-key enrollment. Enroll through Desktop settings; codexteer does not create keys or change authorization.", "REMOTE_ENROLLMENT_REQUIRED");
+  }
+  return { accountUserId: record.accountUserId, algorithm: record.algorithm, clientId: record.clientId, keyId: record.keyId,
+    protectionClass: record.protectionClass, publicKeySpkiDerBase64: record.publicKeySpkiDerBase64 };
+}
+
+export const enrollmentHash = record => createHash("sha256").update(JSON.stringify(record)).digest("hex");
+
+export function connectionPayload(challenge, enrollment, now = Date.now()) {
+  const url = new URL(CONTROL_URL), hash = x => typeof x === "string" && /^[A-Za-z0-9_-]{43}$/.test(x);
+  if (challenge?.type !== "device_key_challenge" || challenge.purpose !== CONTROL_AUDIENCE || challenge.audience !== CONTROL_AUDIENCE
+    || challenge.targetOrigin !== "https://chatgpt.com" || challenge.targetPath !== url.pathname
+    || challenge.clientId !== enrollment.clientId || challenge.accountUserId !== enrollment.accountUserId
+    || !Number.isSafeInteger(challenge.tokenExpiresAt) || challenge.tokenExpiresAt <= Math.floor(now / 1000)
+    || !Array.isArray(challenge.scopes) || challenge.scopes.length !== 1 || challenge.scopes[0] !== CONTROL_SCOPE
+    || typeof challenge.nonce !== "string" || !/^[A-Za-z0-9_-]{43,512}$/.test(challenge.nonce)
+    || typeof challenge.sessionId !== "string" || !challenge.sessionId || challenge.sessionId.length > 512 || !hash(challenge.tokenSha256Base64url)) {
+    throw controlFailure("Remote device-key challenge does not match the selected account, client, official destination or allowed scope.", "REMOTE_AUTH_CHALLENGE_MISMATCH");
+  }
+  // Desktop canonicalizes the payload before signing (Qdt), independently of
+  // the order in which its WebSocket challenge handler constructs the object.
+  return { accountUserId: challenge.accountUserId, audience: challenge.audience, clientId: challenge.clientId, nonce: challenge.nonce,
+    scopes: challenge.scopes, sessionId: challenge.sessionId, targetOrigin: challenge.targetOrigin, targetPath: challenge.targetPath,
+    tokenExpiresAt: challenge.tokenExpiresAt, tokenSha256Base64url: challenge.tokenSha256Base64url, type: "remoteControlClientConnection" };
+}
+
+export function verifyDeviceProof(proof, challenge, enrollment) {
+  const payload = Buffer.from(JSON.stringify({ domain: "codex-device-key-sign-payload/v1", payload: connectionPayload(challenge, enrollment) }));
+  if (proof?.type !== "device_key_proof" || proof.keyId !== enrollment.keyId || proof.algorithm !== enrollment.algorithm
+    || proof.signedPayloadBase64 !== payload.toString("base64") || typeof proof.signatureDerBase64 !== "string"
+    || !verify("sha256", payload, { key: Buffer.from(enrollment.publicKeySpkiDerBase64, "base64"), format: "der", type: "spki" }, Buffer.from(proof.signatureDerBase64, "base64"))) {
+    throw controlFailure("Device-key proof does not match the enrolled public key or validated connection challenge.", "REMOTE_AUTH_PROOF_INVALID");
+  }
+  return proof;
+}
+
+// Only the fixed signing worker runs on Desktop's signed Node. No bearer token
+// is placed on disk, in argv, in command output, or in the worker's input.
+export async function signConnectionChallenge(local, home, identity, enrollment, challenge) {
+  connectionPayload(challenge, enrollment);
+  const output = await keyWorker(local, home, identity, enrollment, { operation: "sign", challenge });
+  return verifyDeviceProof(output.proof, challenge, enrollment);
+}
+
+export async function inspectConnectionKey(local, home, identity, enrollment) {
+  const output = await keyWorker(local, home, identity, enrollment, { operation: "inspect" });
+  if (output.operation !== "inspect" || output.device_key_access !== "verified" || output.proof !== undefined) {
+    throw controlFailure("Device-key inspection did not confirm access without signing.", "REMOTE_AUTH_SIGNING_FAILED");
+  }
+}
+
+async function keyWorker(local, home, identity, enrollment, operation) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "codexteer-device-proof-"));
+  try {
+    const file = path.join(directory, "challenge.json");
+    await writeFile(file, JSON.stringify({ home, identity, enrollmentHash: enrollmentHash(enrollment), ...operation }), { mode: 0o600, flag: "wx" });
+    const result = await local.request("command/exec", { command: [BUNDLED_NODE, fileURLToPath(new URL("./remote-key-worker.mjs", import.meta.url)), file],
+      cwd: fileURLToPath(new URL("..", import.meta.url)), timeoutMs: 10000, outputBytesCap: 16384, sandboxPolicy: { type: "readOnly", networkAccess: false } });
+    let output;
+    try { output = JSON.parse(result.stdout); } catch { throw controlFailure("Device-key worker did not return a proof.", "REMOTE_AUTH_SIGNING_FAILED"); }
+    if (result.exitCode !== 0 || output.ok !== true) {
+      const stage = ["input", "enrollment", "addon", "public-key", "public-key-match", "sign", "verify"].includes(output.stage) ? output.stage : "worker";
+      const code = typeof output.native_code === "number" || /^[A-Z][A-Z0-9_:-]{0,79}$/.test(output.native_code ?? "") ? output.native_code : null;
+      throw Object.assign(controlFailure(`Device-key signing failed at ${stage}${code == null ? "" : ` (${code})`}. No alternative key was used.`, "REMOTE_AUTH_SIGNING_FAILED"),
+        { key_stage: stage, key_error: code });
+    }
+    return output;
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}

package/src/remote-control-socket.mjs

@@ -0,0 +1,137 @@
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { CONTROL_URL, connectionPayload, controlFailure, verifyDeviceProof } from "./remote-control-auth.mjs";
+import { REMOTE_CLIENT_INFO } from "./remote-client-info.mjs";
+
+export const MAX_CONTROL_REQUEST = 65536;
+const MAX_FRAME = 153600, MAX_MESSAGE = 64 * 1024 * 1024;
+
+// Deliberately no reconnect, envelope replay or mutation retry. A new read/watch
+// connection may be opened by the existing monitor after it reports an outage.
+export class RemoteControlSocket extends EventEmitter {
+  constructor(wire, { enrollment, environmentId, streamId = randomUUID(), signal }) {
+    super();
+    Object.assign(this, { wire, enrollment, environmentId, streamId, signal, readyState: WebSocket.OPEN, sequence: 0, lastServerSequence: null, assembly: null });
+    this.on("error", () => {});
+    this.cancel = () => this.terminate();
+    signal?.addEventListener("abort", this.cancel, { once: true });
+    wire.on("message", (data, binary) => {
+      try { this.receive(data, binary); }
+      catch { this.emit("error", controlFailure("Invalid, oversized or mismatched Remote Control envelope.", "REMOTE_CONTROL_PROTOCOL_ERROR")); this.terminate(); }
+    });
+    wire.on("error", () => this.emit("error", controlFailure("Remote Control connection failed.", "CONNECTION_FAILED")));
+    wire.on("close", () => { if (this.readyState !== WebSocket.CLOSED) { this.readyState = WebSocket.CLOSED; this.cleanup(); this.emit("close"); } });
+    this.ping = setInterval(() => {
+      if (this.readyState === WebSocket.OPEN) this.envelope("ping", { state: "foreground", skip_history: true });
+    }, 30000);
+    this.ping.unref();
+  }
+
+  static async connect({ identity, token, enrollment, environmentId, sign, signal, timeoutMs = 10000, createWire = (url, options) => new WebSocket(url, options) }) {
+    if (signal?.aborted) throw controlFailure("Remote Control connection cancelled.", "CANCELLED");
+    const wire = createWire(CONTROL_URL, { headers: { Authorization: `Bearer ${token}`, "ChatGPT-Account-Id": identity.accountId,
+      originator: "codexteer", "User-Agent": REMOTE_CLIENT_INFO.user_agent, "x-codex-client-id": enrollment.clientId, "x-codex-protocol-version": "3", "x-codex-client-auth": "socket-refresh-v1" },
+      perMessageDeflate: false, maxPayload: MAX_FRAME, followRedirects: false, handshakeTimeout: timeoutMs });
+    wire.on("error", () => {});
+    return new Promise((resolve, reject) => {
+      let settled = false, challenged = false, proofSent = false;
+      const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); wire.off("message", message); wire.off("close", closed); wire.off("error", failed); };
+      const stop = error => { if (settled) return; settled = true; cleanup(); wire.terminate(); reject(error); };
+      const cancel = () => stop(controlFailure("Remote Control authentication cancelled.", "CANCELLED"));
+      const failed = () => stop(controlFailure("Remote Control authentication connection failed.", "REMOTE_AUTH_CONNECTION_FAILED"));
+      const closed = () => stop(controlFailure("Remote Control closed before authentication completed.", "REMOTE_AUTH_CONNECTION_FAILED"));
+      const timer = setTimeout(() => stop(controlFailure("Remote Control authentication timed out.", "TIMEOUT")), timeoutMs);
+      const message = async (bytes, binary) => {
+        try {
+          if (binary || bytes.length > MAX_FRAME) throw new Error();
+          const value = JSON.parse(String(bytes));
+          if (value.type === "device_key_authenticated") {
+            if (!proofSent || value.clientId !== enrollment.clientId || settled) throw new Error();
+            settled = true; cleanup();
+            resolve(new RemoteControlSocket(wire, { enrollment, environmentId, signal }));
+            return;
+          }
+          if (challenged || settled) throw new Error();
+          challenged = true; connectionPayload(value, enrollment);
+          const proof = verifyDeviceProof(await sign(value), value, enrollment);
+          if (settled || signal?.aborted) return;
+          proofSent = true; wire.send(JSON.stringify(proof), error => { if (error) failed(); });
+        } catch (error) {
+          const code = /^REMOTE_[A-Z_]+$/.test(error?.code ?? "") ? error.code : "REMOTE_AUTH_CHALLENGE_MISMATCH";
+          const message = code === "REMOTE_AUTH_SIGNING_FAILED" && /^Device-key signing failed at (input|enrollment|addon|public-key|public-key-match|sign|verify|worker)( \([A-Z0-9_:-]+\))?\. No alternative key was used\.$/.test(error.message)
+            ? error.message : "Remote Control device challenge or proof was rejected.";
+          stop(controlFailure(message, code));
+        }
+      };
+      wire.on("message", message); wire.once("close", closed); wire.once("error", failed);
+      wire.once("unexpected-response", (_request, response) => {
+        response.resume();
+        stop(controlFailure(`Remote Control authentication HTTP ${response.statusCode}; no credential or connection fallback was attempted.`, response.statusCode === 400 ? "REMOTE_AUTH_UNSUPPORTED" : "REMOTE_AUTH_REJECTED"));
+      });
+      signal?.addEventListener("abort", cancel, { once: true });
+      if (signal?.aborted) cancel();
+    });
+  }
+
+  envelope(type, extra = {}, callback) {
+    if (this.readyState !== WebSocket.OPEN) { callback?.(new Error("closed")); return; }
+    this.wire.send(JSON.stringify({ type, client_id: this.enrollment.clientId, env_id: this.environmentId, stream_id: this.streamId,
+      seq_id: this.sequence++, ...extra }), error => { if (error) this.terminate(); callback?.(error); });
+  }
+
+  send(text, callback) {
+    if (Buffer.byteLength(text) > MAX_CONTROL_REQUEST) { callback?.(new Error("Remote Control request exceeds 64 KiB.")); return; }
+    let message;
+    try { message = JSON.parse(text); } catch { callback?.(new Error("invalid JSON")); return; }
+    this.envelope("client_message", { skip_history: false, message }, callback);
+  }
+
+  receive(bytes, binary) {
+    if (binary || bytes.length > MAX_FRAME) throw new Error();
+    const value = JSON.parse(String(bytes));
+    if (value.client_id !== this.enrollment.clientId) throw new Error();
+    // Other streams of the same enrolled Desktop client are never exposed.
+    if (value.stream_id !== this.streamId) return;
+    if (value.env_id !== this.environmentId || !Number.isSafeInteger(value.seq_id) || value.seq_id < 0) throw new Error();
+    if (value.type === "ack") return; // Transport acknowledgement is not RPC acceptance.
+    if (!["server_message", "server_message_chunk", "pong"].includes(value.type)) throw new Error();
+    if (this.lastServerSequence !== null && value.seq_id <= this.lastServerSequence) return;
+    if (this.lastServerSequence !== null && value.seq_id !== this.lastServerSequence + 1) throw new Error();
+    if (value.type === "pong") {
+      if (value.status !== "active" || this.assembly) throw new Error();
+      this.lastServerSequence = value.seq_id; return;
+    }
+    let message = value.message;
+    if (value.type === "server_message_chunk") {
+      if (!Number.isInteger(value.segment_count) || value.segment_count < 2 || value.segment_count > 1024
+        || !Number.isInteger(value.segment_id) || !Number.isSafeInteger(value.message_size_bytes) || value.message_size_bytes < 1 || value.message_size_bytes > MAX_MESSAGE
+        || typeof value.message_chunk_base64 !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(value.message_chunk_base64)) throw new Error();
+      this.assembly ??= { sequence: value.seq_id, size: value.message_size_bytes, count: value.segment_count, chunks: [], bytes: 0 };
+      const assembly = this.assembly;
+      if (assembly.sequence !== value.seq_id || assembly.count !== value.segment_count || assembly.size !== value.message_size_bytes
+        || value.segment_id !== assembly.chunks.length) throw new Error();
+      const chunk = Buffer.from(value.message_chunk_base64, "base64");
+      assembly.bytes += chunk.length;
+      if (assembly.bytes > assembly.size) throw new Error();
+      assembly.chunks.push(chunk);
+      if (assembly.chunks.length !== assembly.count) return;
+      if (assembly.bytes !== assembly.size) throw new Error();
+      message = JSON.parse(Buffer.concat(assembly.chunks).toString("utf8")); this.assembly = null;
+    } else if (this.assembly) throw new Error();
+    if (!message || typeof message !== "object" || Array.isArray(message) || !["method", "result", "error"].some(field => Object.hasOwn(message, field))) throw new Error();
+    this.lastServerSequence = value.seq_id;
+    this.emit("message", Buffer.from(JSON.stringify(message)), false);
+  }
+
+  pause() { this.wire.pause(); }
+  resume() { this.wire.resume(); }
+  cleanup() { clearInterval(this.ping); this.signal?.removeEventListener("abort", this.cancel); this.assembly = null; }
+  close() {
+    if (this.readyState !== WebSocket.OPEN) return;
+    this.envelope("client_closed", {}, () => this.wire.close());
+    if (this.readyState !== WebSocket.CLOSED) this.readyState = WebSocket.CLOSING;
+    this.cleanup();
+  }
+  terminate() { this.cleanup(); this.wire.terminate(); }
+}

package/src/remote-control.mjs

@@ -0,0 +1,134 @@
+import { RpcClient } from "./rpc.mjs";
+import { discoverRuntime } from "./runtime.mjs";
+import { assertRuntimeOperation } from "./compatibility.mjs";
+import { inspectNativeCommandProtocol, mutationOutcomeUnknown } from "./native-command.mjs";
+import { targetHost, remoteTransport } from "./target.mjs";
+import { VERSION } from "./version.mjs";
+import { authIdentity, readEnrollment, enrollmentHash, signConnectionChallenge, inspectConnectionKey, controlFailure } from "./remote-control-auth.mjs";
+import { RemoteControlSocket, MAX_CONTROL_REQUEST } from "./remote-control-socket.mjs";
+import { inspectKeychainIdentities } from "./remote-key-access.mjs";
+import { readDevice, dedicatedEnrollment } from "./remote-device-store.mjs";
+import { deviceKey, dedicatedConnectionProof } from "./remote-device-key.mjs";
+
+const methods = new Set(["thread/read", "thread/loaded/list", "thread/turns/list", "thread/items/list", "turn/steer"]);
+const managementReads = new Set(["thread/list", "project/list", "project/read", "fs/readFile", "fs/getMetadata", "fs/readDirectory", "fs/watch", "fs/unwatch"]);
+const managementWrites = new Set(["turn/start", "thread/metadata/update", "command/exec", "command/exec/terminate", "thread/shellCommand"]);
+const executionWrites = new Set(["command/exec", "command/exec/terminate", "thread/shellCommand"]);
+const capabilities = { thread_read: [1], history_pagination: [1], turn_steer: [1], turn_start: [], desktop_subscribe: [] };
+export const remoteNewTurnUnsupported = () => Object.assign(controlFailure("Remote Control supports steering an existing active turn only. --new-turn remains unavailable because this route does not establish Desktop approval ownership.", "REMOTE_NEW_TURN_UNSUPPORTED"), { sent: false, delivery_status: "not_sent" });
+
+export function validateControlRequest(method, params, options = {}) {
+  if (Buffer.byteLength(JSON.stringify({ id: "0".repeat(36), method, params })) > MAX_CONTROL_REQUEST) throw controlFailure("Remote Control requests are limited to 64 KiB before dispatch.", "REMOTE_REQUEST_TOO_LARGE");
+  if ((method === "turn/start" && !options.management) || method === "thread/resume") throw remoteNewTurnUnsupported();
+  if (!methods.has(method) && !(options.management && (managementReads.has(method) || managementWrites.has(method)))
+    || (options.mutation && method !== "turn/steer" && !(options.management && managementWrites.has(method)))) throw controlFailure("Unsupported Remote Control operation.", "REMOTE_METHOD_UNSUPPORTED");
+  if (method === "turn/start" && (typeof params.threadId !== "string" || !params.threadId || typeof params.clientUserMessageId !== "string" || !params.clientUserMessageId
+    || !Array.isArray(params.input) || !params.input.length || params.input.some(item => item.type !== "text" || typeof item.text !== "string")
+    || Object.keys(params).some(key => !["threadId", "input", "clientUserMessageId"].includes(key)))) throw controlFailure("Remote new-turn requires a task, text input and client message ID.", "REMOTE_STEER_INVALID");
+  if (method === "thread/metadata/update" && (typeof params.threadId !== "string" || !params.threadId || typeof params.projectId !== "string" || !params.projectId
+    || Object.keys(params).some(key => !["threadId", "projectId"].includes(key)))) throw controlFailure("Remote project assignment requires an exact task and project.", "REMOTE_PROJECT_INVALID");
+  if (method === "command/exec" && (!Array.isArray(params.command) || !params.command.length || params.command.some(arg => typeof arg !== "string")
+    || Object.keys(params).some(key => !["command", "cwd", "timeoutMs", "outputBytesCap", "processId"].includes(key)))) throw controlFailure("Remote command execution preserves the host's configured permissions; overrides are unsupported.", "REMOTE_COMMAND_INVALID");
+  if (method === "thread/shellCommand" && (typeof params.threadId !== "string" || !params.threadId || typeof params.command !== "string" || !params.command.trim()
+    || Object.keys(params).some(key => !["threadId", "command", "timeoutMs"].includes(key)))) throw controlFailure("Remote shell commands require an exact task and explicit command.", "REMOTE_COMMAND_INVALID");
+  if (method === "turn/steer" && (typeof params.threadId !== "string" || typeof params.expectedTurnId !== "string" || !params.expectedTurnId
+    || !Array.isArray(params.input) || !params.input.length || params.input.some(input => input.type !== "text" || typeof input.text !== "string")
+    || typeof params.clientUserMessageId !== "string" || !params.clientUserMessageId
+    || Object.keys(params).some(key => !["threadId", "expectedTurnId", "input", "clientUserMessageId"].includes(key)))) {
+    throw controlFailure("Remote steering requires the exact thread, expectedTurnId, text input and client message ID.", "REMOTE_STEER_INVALID");
+  }
+}
+
+export function remoteControlConnection({ hostId = targetHost(), transport = remoteTransport() === "paired" ? "paired" : "control" } = {}, dependencies = {}) {
+  const paired = transport === "paired";
+  const loadDedicated = async (home, identity) => {
+    const record = await readDevice(home, identity), enrollment = dedicatedEnrollment(record, identity);
+    if (record.pairing_unknown || !record.pairings.some(pair => pair.host_id === hostId)) throw controlFailure("Pair this dedicated client with the selected host using remote pair, then remote verify.", "REMOTE_PAIR_REQUIRED");
+    return enrollment;
+  };
+  const { discover = discoverRuntime, connect = RpcClient.connect, inspectCommand = inspectNativeCommandProtocol,
+    enrollment = paired ? loadDedicated : readEnrollment,
+    sign = paired ? async (_local, home, identity, enrolled, challenge) => dedicatedConnectionProof(enrolled, challenge, { home, identity }) : signConnectionChallenge,
+    open = RemoteControlSocket.connect,
+    inspectKey = paired ? async (_local, home, identity, enrolled) => deviceKey("inspect", { enrollment: enrolled, home, identity }) : inspectConnectionKey,
+    inspectIdentities = inspectKeychainIdentities } = dependencies;
+  if (!/^remote-control:env_[A-Za-z0-9_-]+$/.test(hostId)) throw controlFailure("The control transport requires a remote-control:env_... host ID; SSH and cloud hosts are not reinterpreted.", "REMOTE_HOST_UNSUPPORTED");
+  let selected;
+  return {
+    async discover(home) {
+      const runtime = await discover(home);
+      assertRuntimeOperation(runtime.state, "read");
+      if (selected && (selected.paths.socket !== runtime.paths.socket || selected.state.instance !== runtime.state.instance)) throw controlFailure("Shared runtime changed during Remote Control operation.", "RUNTIME_CHANGED");
+      selected = runtime;
+      return { paths: runtime.paths, state: { codex_steer_protocol: 1, codex_steer_capabilities: paired ? { ...capabilities, turn_start: [1], desktop_subscribe: [1] } : capabilities,
+        remote_host_id: hostId, remote_transport: transport, cli_version: runtime.state.cli_version,
+        instance: runtime.state.instance, node_path: runtime.state.node_path, node_version: runtime.state.node_version } };
+    },
+    async connect(socket, options = {}) {
+      if (!selected || selected.paths.socket !== socket) throw controlFailure("Discover the selected shared runtime first.");
+      const local = await connect(socket, { ...options, timeoutMs: 15000 });
+      let remote, wire, cancelled = false;
+      const close = () => { if (cancelled) return; cancelled = true; options.signal?.removeEventListener("abort", close); remote?.close(); if (!remote) wire?.terminate(); local.close(); };
+      options.signal?.addEventListener("abort", close, { once: true });
+      try {
+        if (options.signal?.aborted) throw controlFailure("Remote Control cancelled.", "CANCELLED");
+        const protocol = await inspectCommand(selected.state, { remoteControl: true });
+        const status = await local.request("getAuthStatus", { includeToken: true, refreshToken: false }), identity = authIdentity(status);
+        let registered;
+        try { registered = await enrollment(selected.paths.home, identity); }
+        catch (error) {
+          if (paired && ["REMOTE_PAIR_REQUIRED", "REMOTE_DEDICATED_ENROLLMENT_REQUIRED"].includes(error.code)) error.remote_control_auth = {
+            stage: error.code === "REMOTE_PAIR_REQUIRED" ? "host-pairing" : "dedicated-registration", credential_source: "codexteer-dedicated", gateway_attempted: false, proof_created: false };
+          throw error;
+        }
+        const pinned = enrollmentHash(registered);
+        // Verify public-key access before transmitting the token to a gateway.
+        // This does not sign, enroll, resume, or borrow Desktop's credentials.
+        try { await inspectKey(local, selected.paths.home, identity, registered); }
+        catch (error) {
+          if (!["REMOTE_AUTH_SIGNING_FAILED", "REMOTE_DEDICATED_KEY_UNAVAILABLE"].includes(error.code)) throw error;
+          const diagnosis = { stage: "public-key-preflight", credential_source: paired ? "codexteer-dedicated" : "desktop", gateway_attempted: false, proof_created: false,
+            key_access: { status: "unavailable", stage: error.key_stage ?? "worker", reason: error.key_error ?? "UNVERIFIED" },
+            keychain_identity: await inspectIdentities(),
+            app_server_delegation: { status: "unverified", source: protocol.source ?? "unverified", methods: protocol.remote_control_methods ?? [] } };
+          throw Object.assign(controlFailure("The selected enrolled key is unavailable to its signing helper. No gateway connection or device-key proof was attempted. Inspect doctor.remote_control_auth; native read-only observation remains a separately selected route.", "REMOTE_DEVICE_KEY_UNAVAILABLE"),
+            { remote_control_auth: diagnosis });
+        }
+        const check = async () => {
+          if (cancelled) throw controlFailure("Remote Control connection closed.", "CONNECTION_FAILED");
+          const current = await discover(selected.paths.home);
+          if (current.paths.socket !== selected.paths.socket || current.state.instance !== selected.state.instance) throw controlFailure("Runtime changed before Remote Control request.", "RUNTIME_CHANGED");
+          const now = authIdentity(await local.request("getAuthStatus", { includeToken: true, refreshToken: false }));
+          if (now.accountId !== identity.accountId || now.accountUserId !== identity.accountUserId || now.authUserId !== identity.authUserId
+            || enrollmentHash(await enrollment(selected.paths.home, now)) !== pinned) throw controlFailure("Account or enrolled device changed. No request was sent to another account.", "REMOTE_IDENTITY_CHANGED");
+        };
+        wire = await open({ identity, token: status.authToken, enrollment: registered, environmentId: hostId.slice("remote-control:".length), signal: options.signal,
+          timeoutMs: Math.min(options.timeoutMs ?? 10000, 15000), sign: async challenge => { await check(); return sign(local, selected.paths.home, identity, registered, challenge); } });
+        await check();
+        remote = new RpcClient(wire, options);
+        remote.initialization = await remote.request("initialize", { clientInfo: { name: "codexteer", title: "Codexteer", version: VERSION }, capabilities: { experimentalApi: true } });
+        if (!remote.initialization || typeof remote.initialization !== "object" || Array.isArray(remote.initialization)) throw controlFailure("Invalid remote App Server initialization.", "REMOTE_CONTROL_PROTOCOL_ERROR");
+        remote.notify("initialized", {});
+        return {
+          close,
+          on: (event, listener) => remote.on(event, listener),
+          off: (event, listener) => remote.off(event, listener),
+          isOpen: () => wire.readyState === 1,
+          async request(method, params = {}, requestOptions = {}) {
+            validateControlRequest(method, params, { ...requestOptions, management: paired });
+            await check();
+            // The server, not a Desktop view or a fresh inferred turn, performs
+            // the atomic expectedTurnId comparison. Never resume or retry here.
+            const mutation = method === "turn/steer" || managementWrites.has(method);
+            try { return await remote.request(method, params, { ...requestOptions, mutation }); }
+            catch (error) {
+              // An RPC error is not proof that the host rolled a mutation back.
+              if (executionWrites.has(method) && error.code === "RPC_REJECTED") error.uncertain = mutationOutcomeUnknown(error);
+              throw error;
+            }
+          },
+        };
+      } catch (error) { close(); throw error; }
+    },
+  };
+}

package/src/remote-device-key.mjs

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+import { BUNDLED_NODE } from "./wrapper.mjs";
+import { controlFailure, verifyDeviceProof } from "./remote-control-auth.mjs";
+import { validateDeviceKey } from "./remote-device-store.mjs";
+import { keychainOperation } from "./remote-keychain.mjs";
+
+const execute = promisify(execFile);
+export async function deviceKey(operation, input = {}, { run = execute } = {}) {
+  if (!["create", "inspect", "enrollment-proof", "connection-proof"].includes(operation)) throw controlFailure("Unsupported dedicated key operation.");
+  if (input.provider === "keychain" || input.enrollment?.keyProvider === "keychain") return keychainOperation(operation, { ...input, runtime: input.runtime ?? input.enrollment?.keyRuntime });
+  const directory = await mkdtemp(path.join(os.tmpdir(), "codexteer-dedicated-key-"));
+  try {
+    const file = path.join(directory, "input.json");
+    await writeFile(file, JSON.stringify({ operation, ...input }), { mode: 0o600, flag: "wx" });
+    let response;
+    try {
+      const result = await run(BUNDLED_NODE, [fileURLToPath(new URL("./remote-device-worker.mjs", import.meta.url)), file], {
+        env: { ...process.env, NODE_OPTIONS: "", NODE_PATH: "", ELECTRON_RUN_AS_NODE: "" }, timeout: 10000, maxBuffer: 32768, windowsHide: true });
+      response = JSON.parse(result.stdout);
+    } catch { throw controlFailure("Dedicated key helper failed. No software key or Desktop key fallback was attempted.", "REMOTE_DEDICATED_KEY_UNAVAILABLE"); }
+    if (response.ok !== true) {
+      const stage = ["input", "addon", "create", "validate", "public-key", "sign"].includes(response.stage) ? response.stage : "worker";
+      const reason = ["KEYCHAIN_UNAVAILABLE", "DEVICE_KEY_NOT_FOUND", "MISSING_ENTITLEMENT", "OS_INTERACTION_REQUIRED", "OS_KEY_OPERATION_FAILED"].includes(response.reason) ? response.reason : "UNAVAILABLE";
+      const codes = Array.isArray(response.os_statuses) && response.os_statuses.every(Number.isSafeInteger) ? response.os_statuses.slice(0, 3) : [];
+      throw Object.assign(controlFailure(`Dedicated OS key operation failed at ${stage} (${reason}${codes.length ? `: ${codes.join(",")}` : ""}).`, "REMOTE_DEDICATED_KEY_UNAVAILABLE"),
+        { key_creation_rejected: stage === "create" && codes.includes(-34018) });
+    }
+    if (operation === "create") return validateDeviceKey(response.key);
+    if (operation === "inspect") { if (response.verified !== true || response.proof) throw controlFailure("Invalid dedicated key inspection receipt."); return; }
+    return response.proof;
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+export async function dedicatedConnectionProof(enrollment, challenge, context = {}) {
+  return verifyDeviceProof(await deviceKey("connection-proof", { ...context, enrollment, challenge }), challenge, enrollment);
+}

package/src/remote-device-login.mjs

@@ -0,0 +1,76 @@
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { controlFailure } from "./remote-control-auth.mjs";
+
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann", ISSUER = "https://auth.openai.com", SCOPE = "codex.remote_control.enroll";
+const open = promisify(execFile);
+
+export function validateStepUpToken(token, identity, now = Date.now()) {
+  try {
+    if (typeof token !== "string" || token.length > 32768) throw new Error();
+    const claims = JSON.parse(Buffer.from(token.split(".")[1], "base64url")), account = claims["https://api.openai.com/auth"];
+    const scopes = [...new Set([...(claims.scope?.split(/\s+/) ?? []), ...(claims.scp ?? [])].filter(Boolean))];
+    if ((account.chatgpt_account_user_id ?? account.account_user_id) !== identity.accountUserId
+      || ((account.chatgpt_account_id ?? account.account_id) != null && (account.chatgpt_account_id ?? account.account_id) !== identity.accountId)
+      || !Number.isSafeInteger(claims.iat) || now / 1000 - claims.iat > 300 || claims.iat > now / 1000 + 60
+      || !Number.isSafeInteger(claims.exp) || claims.exp <= now / 1000
+      || !Number.isSafeInteger(claims.pwd_auth_time) || now - claims.pwd_auth_time > 300000 || claims.pwd_auth_time > now + 60000
+      || scopes.length !== 1 || scopes[0] !== SCOPE) throw new Error();
+    return token;
+  } catch { throw controlFailure("Complete a fresh official browser authentication for this account and remote-control enrollment scope.", "REMOTE_STEP_UP_REQUIRED"); }
+}
+
+export function stepUpUrl(identity, redirectUri, verifier, state) {
+  const url = new URL("/oauth/authorize", ISSUER);
+  url.search = new URLSearchParams({ response_type: "code", client_id: CLIENT_ID, redirect_uri: redirectUri, scope: SCOPE,
+    code_challenge: createHash("sha256").update(verifier).digest("base64url"), code_challenge_method: "S256", state,
+    originator: "codexteer", reauth: "remote_control", max_age: "0", codex_cli_simplified_flow: "true",
+    allowed_workspace_id: identity.accountId, current_workspace_id: identity.accountId }).toString();
+  return url.toString();
+}
+
+export async function stepUpLogin(identity, { fetch: request = globalThis.fetch, openBrowser = url => open("/usr/bin/open", [url]),
+  ports = [1455, 1457], timeoutMs = 600000, progress = () => {} } = {}) {
+  const state = randomBytes(32).toString("base64url"), verifier = randomBytes(32).toString("base64url");
+  let server, port, timer, resolveCode, rejectCode, settled = false;
+  const code = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; }); code.catch(() => {});
+  const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); error ? rejectCode(error) : resolveCode(value); };
+  const cancel = () => finish(controlFailure("Official enrollment login was cancelled.", "REMOTE_STEP_UP_REQUIRED"));
+  process.once("SIGINT", cancel); process.once("SIGTERM", cancel);
+  try {
+    for (const candidate of ports) {
+      const listener = createServer((req, res) => {
+        const respond = (status, text) => { res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", Connection: "close", "Referrer-Policy": "no-referrer" }); res.end(text); };
+        try {
+          if (req.method !== "GET" || req.url?.length > 16384 || ![`localhost:${port}`, `127.0.0.1:${port}`].includes(req.headers.host)) return respond(400, "Invalid callback");
+          const url = new URL(req.url, `http://localhost:${port}`);
+          if (url.pathname !== "/auth/callback") return respond(404, "Not found");
+          if (settled || url.searchParams.getAll("state").length !== 1 || url.searchParams.get("state") !== state) return respond(400, "State mismatch");
+          if (url.searchParams.has("error")) { respond(400, "Authorization failed"); finish(controlFailure("Official browser authorization was not completed.", "REMOTE_STEP_UP_REQUIRED")); return; }
+          const value = url.searchParams.get("code");
+          if (!value || url.searchParams.getAll("code").length !== 1) return respond(400, "Missing code");
+          respond(200, "Authorization received. Return to the codexteer terminal to check registration."); finish(null, value);
+        } catch { respond(400, "Invalid callback"); }
+      });
+      try { await new Promise((resolve, reject) => { listener.once("error", reject); listener.listen(candidate, "127.0.0.1", resolve); }); server = listener; port = listener.address().port; break; }
+      catch (error) { listener.close(); if (error.code !== "EADDRINUSE") throw error; }
+    }
+    if (!server) throw controlFailure("Official callback ports 1455 and 1457 are unavailable. Nothing was enrolled.", "REMOTE_CALLBACK_UNAVAILABLE");
+    const redirectUri = `http://localhost:${port}/auth/callback`;
+    timer = setTimeout(() => finish(controlFailure("Browser authentication timed out. No enrollment was sent.", "REMOTE_STEP_UP_REQUIRED")), timeoutMs);
+    progress("Complete fresh account authentication in the official browser window. Server registration has not been sent.");
+    try { await openBrowser(stepUpUrl(identity, redirectUri, verifier, state)); }
+    catch { throw controlFailure("Could not open the official browser authentication window. No registration was sent.", "REMOTE_BROWSER_OPEN_FAILED"); }
+    const authorizationCode = await code;
+    let response;
+    try { response = await request(`${ISSUER}/oauth/token`, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "authorization_code", code: authorizationCode, redirect_uri: redirectUri, client_id: CLIENT_ID, code_verifier: verifier }).toString(), redirect: "error", signal: AbortSignal.timeout(15000) }); }
+    catch { throw controlFailure("Official enrollment token exchange failed.", "REMOTE_STEP_UP_REQUIRED"); }
+    if (!response.ok) { await response.body?.cancel(); throw controlFailure(`Official enrollment token exchange returned HTTP ${response.status}.`, "REMOTE_STEP_UP_REQUIRED"); }
+    const text = await response.text(); if (text.length > 65536) throw controlFailure("Invalid official enrollment token response.", "REMOTE_STEP_UP_REQUIRED");
+    let token; try { token = JSON.parse(text).access_token; } catch { throw controlFailure("Invalid official enrollment token response.", "REMOTE_STEP_UP_REQUIRED"); }
+    return validateStepUpToken(token, identity);
+  } finally { process.removeListener("SIGINT", cancel); process.removeListener("SIGTERM", cancel); clearTimeout(timer); if (!settled) finish(controlFailure("Browser authentication cancelled.", "REMOTE_STEP_UP_REQUIRED")); if (server) { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); } }
+}

package/src/remote-device-protocol.mjs

@@ -0,0 +1,72 @@
+import { createHash, verify } from "node:crypto";
+import { controlFailure, CONTROL_SCOPE } from "./remote-control-auth.mjs";
+import { REMOTE_CLIENT_INFO } from "./remote-client-info.mjs";
+
+export const ENROLL_START = "/codex/remote/control/client/enroll/start";
+export const ENROLL_FINISH = "/codex/remote/control/client/enroll/finish";
+export const PAIR_PATH = "/wham/remote/control/client/pair";
+export const deviceIdentity = key => ({ key_id: key.keyId, public_key_spki_der_base64: key.publicKeySpkiDerBase64, algorithm: key.algorithm, protection_class: key.protectionClass });
+export const deviceIdentityHash = key => createHash("sha256").update(JSON.stringify({ algorithm: key.algorithm, keyId: key.keyId, protectionClass: key.protectionClass, publicKeySpkiDerBase64: key.publicKeySpkiDerBase64 })).digest("base64url");
+const expires = value => Number.isSafeInteger(value) ? value * 1000 : typeof value === "string" ? Date.parse(value) : NaN;
+
+export function enrollmentPayload(challenge, enrollment, targetPath, now = Date.now()) {
+  const hash = deviceIdentityHash(enrollment);
+  if (![ENROLL_FINISH, "/codex/remote/control/client/refresh/finish"].includes(targetPath)
+    || challenge?.purpose !== "remote_control_client_enrollment" || challenge.audience !== "remote_control_client_enrollment"
+    || challenge.target_origin !== "https://chatgpt.com" || challenge.target_path !== `/backend-api${targetPath}`
+    || challenge.account_user_id !== enrollment.accountUserId || challenge.client_id !== enrollment.clientId
+    || typeof challenge.nonce !== "string" || !/^[A-Za-z0-9_-]{43,512}$/.test(challenge.nonce)
+    || !Number.isFinite(expires(challenge.challenge_expires_at)) || expires(challenge.challenge_expires_at) <= now
+    || typeof challenge.challenge_id !== "string" || !challenge.challenge_id || challenge.challenge_id.length > 512
+    || typeof challenge.challenge_token !== "string" || !challenge.challenge_token || challenge.challenge_token.length > 16384
+    || (challenge.device_identity_hash != null && challenge.device_identity_hash !== hash)
+    || (targetPath.endsWith("/refresh/finish") && challenge.device_identity_hash == null)) {
+    throw controlFailure("Enrollment challenge does not match this dedicated key, account or official destination.", "REMOTE_ENROLLMENT_CHALLENGE_INVALID");
+  }
+  // Canonical order from Desktop Qdt, including the hash of our new public key.
+  return { accountUserId: enrollment.accountUserId, audience: challenge.audience, challengeExpiresAt: challenge.challenge_expires_at,
+    challengeId: challenge.challenge_id, clientId: enrollment.clientId, deviceIdentitySha256Base64url: hash, nonce: challenge.nonce,
+    targetOrigin: challenge.target_origin, targetPath: challenge.target_path, type: "remoteControlClientEnrollment" };
+}
+
+export function validateRegistration(result, enrollment) {
+  if (result?.client_id !== enrollment.clientId || result.account_user_id !== enrollment.accountUserId
+    || expires(result.expires_at) <= Date.now() || !Number.isFinite(expires(result.expires_at))
+    || !Array.isArray(result.scopes) || result.scopes.length !== 1 || result.scopes[0] !== CONTROL_SCOPE
+    || typeof result.remote_control_token !== "string" || !result.remote_control_token) {
+    throw controlFailure("Enrollment response was not confirmed for this dedicated client. Verify before retrying.", "REMOTE_ENROLLMENT_UNKNOWN");
+  }
+}
+
+export function verifyEnrollmentProof(proof, challenge, enrollment, path = ENROLL_FINISH) {
+  const bytes = Buffer.from(JSON.stringify({ domain: "codex-device-key-sign-payload/v1", payload: enrollmentPayload(challenge, enrollment, path) }));
+  if (proof?.challenge_token !== challenge.challenge_token || proof.key_id !== enrollment.keyId || proof.algorithm !== enrollment.algorithm
+    || proof.signed_payload_base64 !== bytes.toString("base64") || typeof proof.signature_der_base64 !== "string"
+    || !verify("sha256", bytes, { key: Buffer.from(enrollment.publicKeySpkiDerBase64, "base64"), type: "spki", format: "der" }, Buffer.from(proof.signature_der_base64, "base64"))) {
+    throw controlFailure("Dedicated enrollment proof does not match its challenge and public key.", "REMOTE_AUTH_PROOF_INVALID");
+  }
+  return proof;
+}
+
+// Fixed official origin and a small operation allowlist. No overrides, redirects,
+// raw error bodies, request retries or credential-bearing debug output.
+export async function officialDeviceRequest(auth, route, { method = "POST", body, fetch: request = globalThis.fetch } = {}) {
+  const allowed = method === "POST" ? [ENROLL_START, ENROLL_FINISH, PAIR_PATH].includes(route)
+    : method === "GET" && /^(?:\/codex\/remote\/control\/clients\/[A-Za-z0-9_-]+\/environments|\/wham\/remote\/control\/clients)\?limit=100(?:&cursor=[A-Za-z0-9%_.~-]+)?$/.test(route);
+  if (!allowed) throw controlFailure("Unsupported official device endpoint.", "REMOTE_DEVICE_ENDPOINT_INVALID");
+  let response;
+  try {
+    response = await request(`https://chatgpt.com/backend-api${route}`, { method, headers: { Authorization: `Bearer ${auth.token}`,
+      "ChatGPT-Account-Id": auth.identity.accountId, originator: "codexteer", "User-Agent": REMOTE_CLIENT_INFO.user_agent, "Content-Type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }), redirect: "error", signal: AbortSignal.timeout(15000) });
+  } catch { throw controlFailure("Official device request lost its acknowledgement. Inspect the registration before retrying.", "REMOTE_ENROLLMENT_UNKNOWN"); }
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw controlFailure(`Official device request returned HTTP ${response.status}. No authentication fallback was attempted.`, response.status >= 500 ? "REMOTE_ENROLLMENT_UNKNOWN" : "REMOTE_ENROLLMENT_REJECTED");
+  }
+  try {
+    const reader = response.body.getReader(); let size = 0; const chunks = [];
+    for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > 1024 * 1024) { await reader.cancel(); throw new Error(); } chunks.push(Buffer.from(value)); }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch { throw controlFailure("Official device response was incomplete. Verify before retrying.", "REMOTE_ENROLLMENT_UNKNOWN"); }
+}