@4xeoz/re-entry 0.2.6 → 0.2.8

package/README.md

@@ -1,6 +1,6 @@
 # Re-entry Local Connector
 
-Install it once on the Mac where Codex should open; after one browser approval, a macOS
+Install it once on the Mac where Codex should open; after one dashboard pairing code, a macOS
 LaunchAgent keeps the outbound Connector running at login.
 
 > Current boundary: this is a verified macOS Connector preview with a publish-ready npm package.
@@ -67,11 +67,11 @@ npx --yes --package=@4xeoz/re-entry re-entry install \
 ```text
 choose Desktop, the current folder, or another Codex workspace
   -> check Node + find Codex + validate the selected directory
-  -> request a device authorization from Re-entry
-  -> show the verification URL and wait for the user to press Enter
+  -> show the Re-entry account URL and wait for the user to press Enter
   -> open Re-entry in the default browser
-  -> sign in or create an account
-  -> approve this Mac once
+  -> sign in or create a user account
+  -> click Pair this Mac in the dashboard
+  -> enter the short pairing code in the CLI
   -> save the device credential with mode 0600
   -> install and start a per-user macOS LaunchAgent
 ```
@@ -89,8 +89,10 @@ re-entry --help
 ```
 
 The status view checks the local authorization, background job, Receiver reachability, Node, and
-Codex. `listen` watches the already-running background Connector and displays new activity until
-you press Ctrl+C; it does not start a competing second poller. Useful development commands are:
+Codex. If the Receiver rejects a previously saved device credential, the Connector pauses instead
+of retrying forever, and `status`/`listen` tell you to run `re-entry connect` again. `listen` watches
+the already-running background Connector and displays new activity until you press Ctrl+C; it does
+not start a competing second poller. Useful development commands are:
 
 ```sh
 re-entry doctor --codex-cd /absolute/path/to/project
@@ -131,8 +133,8 @@ Copy this prompt into a coding-agent task:
 ```text
 Install the Re-entry Local Connector on this Mac. First read the package README. Verify Node.js 24
 or newer and locate the Connector executable. Run `npx --yes --package=@4xeoz/re-entry re-entry install` with an absolute
-project directory. Let the human complete the Re-entry
-browser approval; never copy browser cookies, organization keys, Connector tokens, or private keys
+project directory. Let the human create or sign in to a Re-entry account, click Pair this Mac, and
+enter the code in the CLI; never copy browser cookies, organization keys, Connector tokens, or private keys
 into chat, logs, source files, or git. Finish by running `re-entry status` and report the bounded
 results without claiming Browser/WebMCP or production deployment.
 ```
@@ -140,7 +142,7 @@ results without claiming Browser/WebMCP or production deployment.
 ## Package map
 
 - `src/main.mjs` — `re-entry` CLI and long-running poll loop.
-- `src/pairing-client.mjs` — account-first browser device authorization.
+- `src/pairing-client.mjs` — account pairing-code redemption and legacy pairing compatibility.
 - `src/credentials.mjs` — atomic local credential storage.
 - `src/macos-service.mjs` — per-user LaunchAgent install, stop, uninstall, and status.
 - `src/workspace-picker.mjs` — interactive Codex workspace selection.
@@ -249,9 +251,10 @@ npm start -- \
   --codex-cd "$HOME/Code/my-host-project"
 ```
 
-On the first run, the Connector checks the Mac, asks for the one-time code from the Host
-backend, opens the approval page, waits for the user to approve it, stores the credential, and
-checks once for approved work. On later runs it reuses the saved credential and skips pairing:
+On the first run, the Connector checks the Mac, opens the Re-entry account page, waits for you to
+create or sign in to an account and click Pair this Mac, then asks for the
+dashboard code and stores the credential. On later runs it reuses the saved credential and skips
+pairing:
 
 ```sh
 npm start -- --codex-cd "$HOME/Code/my-host-project"
@@ -269,13 +272,13 @@ events instead so another process can consume it:
 npm start -- --json --codex-cd "$HOME/Code/my-host-project"
 ```
 
-## Pair this Mac with a Host user
+## Compatibility: Host-code pairing (legacy)
 
 Pairing connects one local Connector to one already-authenticated Host user. It is separate from
 the Host organization's API key and does not give the Connector permission to create Grants or
 send Host events.
 
-The flow is:
+The older compatibility flow is:
 
 ```text
 Host backend -> Receiver: start pairing for its Host-user reference
@@ -288,7 +291,8 @@ Receiver -> Connector: one Connector credential
 Connector -> local disk: save the credential with mode 0600
 ```
 
-The Host backend starts pairing with its organization credential. In the current local preview:
+The current preview does not use this Host-issued code path. Use `re-entry install` above, where
+the authenticated Re-entry dashboard creates the code.
 
 ```sh
 curl -s -X POST http://127.0.0.1:43218/v0.1/pairing-sessions \

package/node_modules/@webmcp-challenge/reentry-core/src/cloud-receiver-http.mjs

@@ -42,7 +42,7 @@ export function createCloudReceiverHttpHandler(options) {
   requireReceiver(options.receiver);
 
   return function cloudReceiverHttpHandler(request, response) {
-    handleRequest(options.receiver, request, response).catch((error) => {
+    return handleRequest(options.receiver, request, response).catch((error) => {
       if (response.destroyed) return;
       if (response.headersSent) {
         response.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "description": "Outbound Local Connector process for the Re-entry Core local preview.",
   "publishConfig": {

package/src/credentials.mjs

@@ -49,6 +49,48 @@ export class LocalConnectorCredentialStore {
   }
 }
 
+export function reauthorizationMarkerPath(filename) {
+  if (typeof filename !== "string" || filename.length === 0) {
+    throw new TypeError("Credential filename is required");
+  }
+  return `${filename}.reauthorization-required.json`;
+}
+
+export async function markConnectorReauthorizationRequired(filename, value = {}) {
+  const marker = reauthorizationMarkerPath(filename);
+  await mkdir(dirname(marker), { recursive: true, mode: 0o700 });
+  await writeFile(marker, `${JSON.stringify({
+    receiver_origin: value.receiver_origin ?? null,
+    reason: "connector_identity_invalid",
+    observed_at: new Date().toISOString(),
+  })}\n`, { encoding: "utf8", mode: 0o600 });
+  await chmod(marker, 0o600);
+}
+
+export async function hasConnectorReauthorizationRequired(filename) {
+  try {
+    await readFile(reauthorizationMarkerPath(filename), "utf8");
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw credentialFailure(
+      "connector_status_unreadable",
+      "Connector authorization status could not be read",
+      error,
+    );
+  }
+}
+
+export async function clearConnectorReauthorizationRequired(filename) {
+  await unlink(reauthorizationMarkerPath(filename)).catch((error) => {
+    if (error?.code !== "ENOENT") throw credentialFailure(
+      "connector_status_unwritable",
+      "Connector authorization status could not be cleared",
+      error,
+    );
+  });
+}
+
 function normalizeCredentials(value) {
   requireExactRecord(value, CREDENTIAL_FIELDS, CREDENTIAL_FIELDS, "Connector credentials");
   if (value.version !== 1) throw credentialFailure("connector_credentials_invalid", "Connector credential version is unsupported");

package/src/macos-service.mjs

@@ -91,7 +91,7 @@ export async function inspectMacConnectorService(options = {}) {
   return Object.freeze({
     supported: true,
     installed: true,
-    running: result.code === 0,
+    running: result.code === 0 && isLoadedAndRunning(result.stdout),
     plistPath,
   });
 }
@@ -127,6 +127,7 @@ export async function uninstallMacConnectorService(options = {}) {
   const paths = [...new Set([
     service.plistPath,
     credentialFile,
+    `${credentialFile}.reauthorization-required.json`,
     join(stateDirectory, "connector.log"),
     join(stateDirectory, "connector-error.log"),
   ])];
@@ -192,6 +193,7 @@ ${argumentsXml}
 function runLaunchctl(argumentsList) {
   return new Promise((resolve) => {
     const child = spawn("launchctl", argumentsList, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
     let stderr = "";
     let settled = false;
     const finish = (result) => {
@@ -199,15 +201,29 @@ function runLaunchctl(argumentsList) {
       settled = true;
       resolve(result);
     };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      if (stdout.length < 16_384) stdout += chunk;
+    });
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
       if (stderr.length < 4_096) stderr += chunk;
     });
-    child.once("error", (error) => finish({ code: -1, stderr: error.message }));
-    child.once("close", (code) => finish({ code: code ?? -1, stderr }));
+    child.once("error", (error) => finish({ code: -1, stdout, stderr: error.message }));
+    child.once("close", (code) => finish({ code: code ?? -1, stdout, stderr }));
   });
 }
 
+function isLoadedAndRunning(stdout) {
+  // Test doubles historically return only { code: 0 }; preserve that contract while
+  // treating launchctl's explicit not-running state as stopped in production.
+  if (stdout === undefined) return true;
+  const state = stdout.match(/^[\t ]*state\s*=\s*([^\r\n]+)$/m)?.[1]?.trim();
+  if (state) return state === "running";
+  const activeCount = stdout.match(/^[\t ]*active count\s*=\s*(\d+)$/m)?.[1];
+  return activeCount !== undefined && Number(activeCount) > 0;
+}
+
 function requireServiceConfiguration(options, operation) {
   if (!options || typeof options !== "object" || Array.isArray(options)) {
     throw serviceFailure("connector_service_input_invalid", `Service ${operation} options are invalid`);

package/src/main.mjs

@@ -18,9 +18,13 @@ import {
   verifyCodexExecutable,
 } from "./codex-discovery.mjs";
 import { LocalConnector } from "./local-connector.mjs";
-import { LocalConnectorCredentialStore } from "./credentials.mjs";
-import { LocalConnectorPairingClient } from "./pairing-client.mjs";
-import { waitForEnterToOpenBrowser } from "./browser-prompt.mjs";
+import {
+  LocalConnectorCredentialStore,
+  clearConnectorReauthorizationRequired,
+  hasConnectorReauthorizationRequired,
+  markConnectorReauthorizationRequired,
+} from "./credentials.mjs";
+import { LocalConnectorPairingClient, openBrowser } from "./pairing-client.mjs";
 import { chooseWorkspaceDirectory } from "./workspace-picker.mjs";
 import {
   inspectMacConnectorService,
@@ -130,7 +134,7 @@ Commands:
   test         Start one fresh local Codex session with the supplied prompt
   stop         Stop the background Connector without removing its credential
   uninstall    Stop the Connector and remove its local service data
-  connect      Authorize this Mac without installing the background service
+  connect      Open Re-entry, redeem a dashboard pairing code, and connect this Mac
   start        Poll for approved work until stopped
   doctor       Check Node.js, Codex, and the optional project directory
   claim-once   Check once for approved work
@@ -267,14 +271,15 @@ async function pair(flags, ui, options = {}) {
 
 async function connect(flags, ui, options = {}) {
   if (!options.quietHeader && ui.interactive) {
-    ui.begin("Connect this Mac", "One browser approval, then Re-entry stays connected");
+    ui.begin("Connect this Mac", "Create a Re-entry account, pair this Mac, then leave it running");
   }
   const receiver = flags.receiver ?? DEFAULT_RECEIVER_ORIGIN;
   const credentialFile = flags["credential-file"] ?? defaultCredentialFile();
   const store = new LocalConnectorCredentialStore({ filename: credentialFile });
   const current = await store.load();
+  const reauthorizationRequired = await hasConnectorReauthorizationRequired(credentialFile);
   const currentIsValid = current && Date.parse(current.connector_expires_at) > Date.now();
-  if (currentIsValid && current.receiver_origin === receiver) {
+  if (currentIsValid && current.receiver_origin === receiver && !reauthorizationRequired) {
     if (ui.interactive) {
       ui.success("Account", "already connected");
       if (!options.guidedInstall) {
@@ -302,28 +307,28 @@ async function connect(flags, ui, options = {}) {
     baseUrl: receiver,
     requestTimeoutMs: DEFAULT_PAIRING_REQUEST_TIMEOUT_MS,
   });
-  if (ui.interactive) ui.wait("Contacting Re-entry…");
-  const credentials = await client.connect(
-    { deviceName: flags["device-name"] ?? defaultDeviceName() },
-    async ({ verificationUri }) => {
-      if (ui.interactive) {
-        ui.stopWait("Secure link", "ready");
-        ui.info("Browser link", verificationUri);
-        await waitForEnterToOpenBrowser();
-        ui.wait("Waiting for approval in your browser…");
-      } else {
-        process.stdout.write(`${JSON.stringify({
-          event: "connector_authorization_waiting",
-          verification_uri: verificationUri,
-        })}\n`);
-      }
-    },
-  );
+  const portalUrl = `${receiver}/register?flow=pair&next=${encodeURIComponent("/dashboard")}`;
   if (ui.interactive) {
-    ui.stopWait("Account", "connected");
-    if (!credentials.browserOpened) {
-      ui.warning("Browser", "did not open automatically; use the URL shown above");
+    ui.stopWait("Secure link", "ready");
+    ui.info("Re-entry", portalUrl);
+    ui.info("Next", "Create or sign in, click Pair this Mac, then return here with the code.");
+    if (!(await openBrowser(portalUrl))) {
+      ui.warning("Browser", "could not open automatically; use the URL above");
     }
+  } else {
+    process.stdout.write(`${JSON.stringify({ event: "connector_account_pairing", portal_url: portalUrl })}\n`);
+  }
+  const pairingCode = flags["pairing-code"] ?? await askForPairingCode(
+    ui,
+    "  Enter the pairing code shown in your Re-entry dashboard (XXXX-XXXX): ",
+  );
+  if (ui.interactive) ui.step("Pairing code", "received");
+  const credentials = await client.connectWithPairingCode({
+    pairingCode,
+    deviceName: flags["device-name"] ?? defaultDeviceName(),
+  });
+  if (ui.interactive) {
+    ui.success("Account", "connected");
   }
   const saved = {
     version: 1,
@@ -333,6 +338,7 @@ async function connect(flags, ui, options = {}) {
     connector_expires_at: credentials.connector_expires_at,
   };
   await store.save(saved);
+  await clearConnectorReauthorizationRequired(credentialFile);
   if (ui.interactive) {
     if (!options.guidedInstall) {
       ui.complete("This Mac is connected", "Re-entry can now route approved work here.");
@@ -351,23 +357,32 @@ async function status(flags, ui) {
   if (ui.interactive) ui.begin("Status", "A quick check of this Mac and Re-entry.");
   const credentialFile = flags["credential-file"] ?? defaultCredentialFile();
   const credentials = await new LocalConnectorCredentialStore({ filename: credentialFile }).load();
+  const reauthorizationRequired = await hasConnectorReauthorizationRequired(credentialFile);
   const readiness = inspectReadiness(flags);
   const service = await inspectMacConnectorService();
   const receiverReady = credentials ? await inspectReceiver(credentials.receiver_origin) : false;
-  const connected = Boolean(credentials && Date.parse(credentials.connector_expires_at) > Date.now());
+  const connected = Boolean(
+    credentials &&
+    Date.parse(credentials.connector_expires_at) > Date.now() &&
+    !reauthorizationRequired,
+  );
   if (ui.interactive) {
     ui.section("SYSTEM", "This Mac");
     showReadiness(readiness, ui);
     ui.section("CONNECTION", "Re-entry");
-    if (connected) ui.success("Account", "connected");
+    if (reauthorizationRequired) ui.warning("Account", "reconnect required");
+    else if (connected) ui.success("Account", "connected");
     else ui.warning("Account", "not connected");
-    if (service.running) ui.success("Background", "running");
+    if (reauthorizationRequired && service.running) ui.warning("Background", "paused until this Mac is reconnected");
+    else if (service.running) ui.success("Background", "running");
     else if (service.installed) ui.warning("Background", "stopped");
     else ui.warning("Background", "not installed");
-    if (connected && receiverReady) ui.success("Cloud", "online");
-    else if (connected) ui.warning("Cloud", "unavailable");
+    if (receiverReady) ui.success("Cloud", "online");
+    else if (credentials) ui.warning("Cloud", "unavailable");
 
-    if (!connected || !service.running) {
+    if (reauthorizationRequired) {
+      ui.next("re-entry connect", "Approve this Mac again in your browser; the old credential was rejected.");
+    } else if (!connected || !service.running) {
       ui.next("re-entry install", "Finish setup and start Re-entry in the background.");
     } else if (!receiverReady) {
       ui.next("re-entry status", "Check again when the Re-entry Cloud service is available.");
@@ -379,6 +394,7 @@ async function status(flags, ui) {
     process.stdout.write(`${JSON.stringify({
       event: "connector_status",
       connected,
+      reauthorization_required: reauthorizationRequired,
       connector_id: credentials?.connector_id ?? null,
       receiver_origin: credentials?.receiver_origin ?? null,
       receiver_ready: receiverReady,
@@ -399,8 +415,13 @@ async function listen(flags, ui) {
   const credentials = await new LocalConnectorCredentialStore({
     filename: defaultCredentialFile(),
   }).load();
-  if (!service.running || !credentials) {
+  const reauthorizationRequired = await hasConnectorReauthorizationRequired(defaultCredentialFile());
+  if (reauthorizationRequired || !service.running || !credentials) {
     if (ui.interactive) {
+      if (reauthorizationRequired) {
+        ui.warning("Account", "reconnect required; the Cloud Receiver rejected this Mac");
+        ui.next("re-entry connect", "Approve this Mac again in your browser.");
+      }
       if (!credentials) ui.warning("Account", "not connected");
       if (!service.running) ui.warning("Background", "not running");
       ui.next("re-entry install", "Finish setup and start the background Connector.");
@@ -408,6 +429,7 @@ async function listen(flags, ui) {
       process.stdout.write(`${JSON.stringify({
         event: "connector_listener_unavailable",
         connected: Boolean(credentials),
+        reauthorization_required: reauthorizationRequired,
         service_running: service.running,
       })}\n`);
     }
@@ -482,6 +504,10 @@ function reportLiveActivity(event, ui) {
       accepted ? "a fresh Codex session was started" : String(event.outcome ?? "unknown"),
       accepted ? "success" : "warning",
     );
+  } else if (event.event === "connector_reauthorization_required" || event.code === "connector_identity_invalid") {
+    ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
+    ui.next("re-entry connect", "Approve this Mac again in your browser.");
+    return;
   } else if (event.event === "connector_poll_failed" || event.event === "local_connector_failed") {
     ui.stopWait("Connection interrupted", "Re-entry is retrying", "warning");
   } else if (event.event === "connector_ready") {
@@ -545,7 +571,7 @@ async function install(flags, ui) {
     ui.success("Selected", readiness.workingDirectory);
     ui.section("2 OF 3", "System check");
     showReadiness(readiness, ui, { includeWorkspace: false });
-    ui.section("3 OF 3", "Connect Re-entry", "Approve this Mac in your browser.");
+    ui.section("3 OF 3", "Connect Re-entry", "Create or sign in to your account, then pair this Mac from the dashboard.");
   }
   const credentials = await connect(runtimeFlags, ui, { quietHeader: true, guidedInstall: true });
   if (ui.interactive) ui.wait("Starting Re-entry in the background…");
@@ -592,8 +618,16 @@ async function start(flags, ui) {
   const store = new LocalConnectorCredentialStore({ filename: credentialFile });
   let credentials = await store.load();
   if (!credentials) {
-    if (ui.interactive) ui.info("Re-entry", "first run — browser approval is required once");
+    if (ui.interactive) ui.info("Re-entry", "first run — create an account and enter a dashboard pairing code");
     credentials = await connect(runtimeFlags, ui, { quietHeader: true });
+  } else if (await hasConnectorReauthorizationRequired(credentialFile)) {
+    if (ui.interactive) {
+      ui.warning("Account", "this Mac needs to be connected again");
+      ui.next("re-entry connect", "Create a new dashboard pairing code and connect this Mac again.");
+    } else {
+      process.stdout.write('{"event":"connector_reauthorization_required"}\n');
+    }
+    return;
   } else if (ui.interactive) {
     ui.success("Re-entry", "existing account connection loaded");
   }
@@ -629,6 +663,18 @@ async function start(flags, ui) {
           if (ui.interactive) ui.wait("Connected. Waiting for approved work…");
         }
       } catch (error) {
+        if (error?.code === "connector_identity_invalid") {
+          await markConnectorReauthorizationRequired(credentialFile, {
+            receiver_origin: credentials.receiver_origin,
+          });
+          if (ui.interactive) {
+            ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
+            ui.next("re-entry connect", "Approve this Mac again in your browser.");
+          } else {
+            process.stdout.write('{"event":"connector_reauthorization_required"}\n');
+          }
+          return;
+        }
         consecutiveErrors += 1;
         if (ui.interactive) {
           ui.stopWait("Receiver unavailable", `${safeErrorMessage(error)} · ${consecutiveErrors}/${maximumErrors}`, "warning");
@@ -810,7 +856,7 @@ function validateCommandFlags(command, flags, positionals) {
   const allowedByCommand = {
     doctor: new Set(["codex-binary", "codex-cd", "json"]),
     pair: new Set(["receiver", "code", "credential-file", "json"]),
-    connect: new Set(["receiver", "device-name", "credential-file", "json"]),
+    connect: new Set(["receiver", "device-name", "credential-file", "pairing-code", "json"]),
     status: new Set(["credential-file", "codex-cd", "codex-binary", "json"]),
     listen: new Set(["json"]),
     test: new Set(["codex-cd", "codex-binary", "activation-timeout", "json"]),
@@ -822,6 +868,7 @@ function validateCommandFlags(command, flags, positionals) {
       "credential-file",
       "codex-cd",
       "codex-binary",
+      "pairing-code",
       "json",
     ]),
     "claim-once": new Set([
@@ -957,13 +1004,13 @@ function safeErrorMessage(error) {
     : error.message;
 }
 
-async function askForPairingCode(ui) {
+async function askForPairingCode(ui, prompt = "  Enter the pairing code: ") {
   if (!ui.interactive || process.stdin.isTTY !== true) {
     throw cliFailure("connector_pairing_code_missing");
   }
   const readline = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = await readline.question("  Enter the pairing code from your Host (XXXX-XXXX-XXXX-XXXX): ");
+    const answer = await readline.question(prompt);
     return answer.trim();
   } finally {
     readline.close();
@@ -990,6 +1037,8 @@ function errorHint(error) {
     connector_node_unsupported: "use Node.js 24 or newer, then run the command again",
     connector_credentials_missing: "connect this Mac once with `re-entry connect`",
     connector_credentials_expired: "run `re-entry connect` to authorize this Mac again",
+    connector_identity_invalid: "run `re-entry connect` and approve this Mac again",
+    connector_reauthorization_required: "run `re-entry connect` and approve this Mac again",
     connector_pairing_code_missing: "ask the Host backend for a new pairing code, then run pair in a terminal",
     pairing_code_invalid: "use the 16-character code returned by the Host, for example ABCD-EFGH-IJKL-MNOP",
     host_subject_already_paired: "use the existing Connector credential or revoke/reset the preview pairing",

package/src/pairing-client.mjs

@@ -2,15 +2,21 @@ import { spawn } from "node:child_process";
 import { TextDecoder } from "node:util";
 
 export const PAIRING_CLIENT_ROUTES = Object.freeze({
+  accountPairingClaim: "/v0.1/account/pairing-sessions/claim",
   claim: "/v0.1/pairing-sessions/claim",
   poll: "/v0.1/pairing-sessions/poll",
   deviceStart: "/v0.1/device-authorizations",
   devicePoll: "/v0.1/device-authorizations/poll",
 });
 
+export async function openBrowser(url) {
+  return defaultOpenBrowser(url);
+}
+
 const OPTION_FIELDS = Object.freeze(["baseUrl", "requestTimeoutMs", "openBrowser", "sleep"]);
 const PAIR_INPUT_FIELDS = Object.freeze(["userCode"]);
 const CONNECT_INPUT_FIELDS = Object.freeze(["deviceName"]);
+const ACCOUNT_PAIRING_INPUT_FIELDS = Object.freeze(["pairingCode", "deviceName"]);
 const DEVICE_AUTHORIZATION_FIELDS = Object.freeze([
   "type",
   "protocol_version",
@@ -68,6 +74,7 @@ const ERROR_BODY_FIELDS = Object.freeze(["code"]);
 const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
 const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 const USER_CODE_PATTERN = /^[A-F0-9]{16}$/;
+const ACCOUNT_PAIRING_CODE_PATTERN = /^[A-F0-9]{8}$/;
 const CONTENT_TYPE_PATTERN = /^application\/json(?:\s*;\s*charset=utf-8)?$/i;
 const MIN_REQUEST_TIMEOUT_MS = 100;
 const MAX_REQUEST_TIMEOUT_MS = 60_000;
@@ -197,6 +204,26 @@ export class LocalConnectorPairingClient {
     }
   }
 
+  async connectWithPairingCode(input) {
+    requireExactRecord(
+      input,
+      ACCOUNT_PAIRING_INPUT_FIELDS,
+      ACCOUNT_PAIRING_INPUT_FIELDS,
+      "Account pairing input",
+    );
+    const pairingCode = normalizeAccountPairingCode(input.pairingCode);
+    const deviceName = requireDeviceName(input.deviceName);
+    const response = await this.#post(PAIRING_CLIENT_ROUTES.accountPairingClaim, {
+      pairing_code: pairingCode,
+      device_name: deviceName,
+    });
+    if (response.status !== 200) throw await parseHttpFailure(response);
+    return Object.freeze({
+      ...normalizeCredentials(await parseJsonResponse(response)),
+      browserOpened: false,
+    });
+  }
+
   async #post(path, body) {
     let response;
     try {
@@ -331,6 +358,17 @@ function normalizeCredentials(value) {
   };
 }
 
+function normalizeAccountPairingCode(value) {
+  if (typeof value !== "string") {
+    throw pairingFailure("account_pairing_code_invalid", "Pairing code is invalid");
+  }
+  const normalized = value.replaceAll("-", "").trim().toUpperCase();
+  if (!ACCOUNT_PAIRING_CODE_PATTERN.test(normalized)) {
+    throw pairingFailure("account_pairing_code_invalid", "Pairing code is invalid");
+  }
+  return normalized;
+}
+
 async function parseJsonResponse(response) {
   const declared = response.headers.get("content-length");
   if (declared !== null && (!/^(?:0|[1-9][0-9]*)$/.test(declared) || Number(declared) > MAX_RESPONSE_BYTES)) {