commandmate 0.28.0 → 0.29.1

package/dist/lib/remote/types.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Provider abstraction for `commandmate remote` (Issue #1937, R1).
+ *
+ * The shapes here are §6.1 of `docs/design/remote-qr-pairing-1937.md` verbatim.
+ * Two of them carry a structural guarantee rather than a convention, and both
+ * exist because a Provider can destroy configuration the user created and that
+ * CommandMate has no way to restore (§6.3):
+ *
+ * 1. `RemoteProvider` has no `reset()` / `cleanupAll()`. `stop()` takes a
+ *    `RemoteHandle` and nothing else, so "read the Provider's whole config and
+ *    tear it down" is not expressible in this type. A pinning test asserts the
+ *    member list stays exactly `id` / `detect` / `start` / `stop`.
+ * 2. `start()` must return `preexisting`. `stop()` reverts only what is in
+ *    `owned` and NOT in `preexisting`; anything in both is skipped and reported
+ *    in `StopOutcome.skipped` so a human can see what was left alone.
+ *
+ * Choosing between Providers is deliberately NOT here. "Tailscale first, and do
+ * not silently fall back to a public tunnel" is a rule about selection, not a
+ * property of either Provider, so it lives in the orchestrator that will own
+ * `src/cli/commands/remote.ts` (R9). See `provider-registry.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPreexistingSnapshot = isPreexistingSnapshot;
+exports.planStop = planStop;
+/** Narrows `RemoteHandle.preexisting` to the shape the shared skip rule reads. */
+function isPreexistingSnapshot(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const keys = value.keys;
+    return Array.isArray(keys) && keys.every((key) => typeof key === 'string');
+}
+/**
+ * Splits a handle's owned revert entries into "safe to undo" and "leave alone".
+ *
+ * This is the single implementation of §6.3-2. Every Provider's `stop()` routes
+ * through it so the rule cannot drift between Providers, and so the rule can be
+ * tested once instead of once per Provider.
+ */
+function planStop(handle) {
+    const owned = handle.owned.revert ?? {};
+    const protectedKeys = new Set(isPreexistingSnapshot(handle.preexisting) ? handle.preexisting.keys : []);
+    const revert = {};
+    const skipped = [];
+    for (const key of Object.keys(owned)) {
+        if (protectedKeys.has(key)) {
+            skipped.push(key);
+            continue;
+        }
+        revert[key] = owned[key];
+    }
+    return { revert, skipped: skipped.sort() };
+}

package/dist/lib/security/pairing-code.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Pairing code lifecycle for `commandmate remote` (Issue #1937, R5)
+ *
+ * Design: docs/design/remote-qr-pairing-1937.md §7
+ *
+ * CONSTRAINTS:
+ * - NODE RUNTIME ONLY. This module touches `fs` and `crypto`; the Edge Runtime
+ *   (`src/middleware.ts`) must never import it. Pairing is an excluded path, so
+ *   middleware never needs to.
+ * - No Next.js imports, so `src/cli/**` can pull it in for `commandmate remote`
+ *   under `tsconfig.cli.json` (which declares `"paths": {}` — relative imports
+ *   only, never `@/...`).
+ *
+ * WHY A FILE AND NOT AN ENVIRONMENT VARIABLE (§7.2)
+ * -------------------------------------------------
+ * The cookie has to carry the *plaintext* long-lived token, so the server must
+ * know it. The obvious route — put it in the server's startup env — is rejected:
+ * `src/lib/tmux/**` passes no `env:` to the panes it spawns, so a pane inherits
+ * the server's environment wholesale, and `sanitizeEnvForChildProcess()` is
+ * called in only two places that an agent pane does not go through. An env var
+ * would therefore be readable by the very Claude / Codex / OpenCode processes
+ * CommandMate is driving.
+ *
+ * So the secret lands in one 0600 handoff file and only its *path* travels in
+ * `CM_REMOTE_PAIRING_FILE` (a path is not a secret). Two further consequences:
+ *
+ *   - The consumed flag is THE ABSENCE OF THE FILE. A module-level variable
+ *     cannot work here: `server.ts` and the Next route handler bundle are
+ *     separate module instances, so state written by one is invisible to the
+ *     other.
+ *   - Deleting the file destroys the plaintext token at the moment of pairing,
+ *     shrinking its window on disk to "remote start → first pairing".
+ */
+/** Env var carrying the handoff file PATH (never the secret itself). */
+export declare const PAIRING_FILE_ENV_KEY = "CM_REMOTE_PAIRING_FILE";
+/** File name inside the config directory (`~/.commandmate` for global installs). */
+export declare const PAIRING_FILE_NAME = "remote-pairing.json";
+/** Owner read/write only. Asserted by tests, not merely intended. */
+export declare const PAIRING_FILE_MODE = 384;
+/**
+ * Crockford Base32 (https://www.crockford.com/base32.html).
+ * `I`, `L`, `O` and `U` are absent so a transcribed code cannot be ambiguous.
+ */
+export declare const CROCKFORD_BASE32_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** Bits of entropy carried by a pairing code. */
+export declare const PAIRING_CODE_BITS = 128;
+/** ceil(128 / 5) — the encoded length of PAIRING_CODE_BITS. */
+export declare const PAIRING_CODE_LENGTH = 26;
+/** Default time-to-live for one pairing code (§7.4). */
+export declare const DEFAULT_PAIRING_TTL_MS: number;
+/**
+ * Input length cap for `POST /api/remote/pair`, copied from `/api/auth/login`'s
+ * 256-char cap so an oversized body cannot be used to burn CPU on hashing.
+ */
+export declare const MAX_PAIRING_CODE_LENGTH = 256;
+/** On-disk shape of the handoff file. */
+export interface PairingHandoff {
+    /** SHA-256 hex of the canonical pairing code. The code itself is never stored. */
+    pairingHash: string;
+    /** Epoch ms after which the code is dead. */
+    expiresAt: number;
+    /** Plaintext long-lived token that becomes the auth cookie value. */
+    sessionToken: string;
+}
+/** What `createPairingHandoff()` hands back to the caller (the `remote` command). */
+export interface CreatedPairing {
+    /**
+     * Plaintext pairing code. NEVER persisted — the caller renders it as a QR
+     * code and drops it. Re-displaying it means running `remote` again.
+     */
+    code: string;
+    /** Plaintext long-lived token (also written to the handoff file). */
+    sessionToken: string;
+    expiresAt: number;
+    filePath: string;
+}
+export interface CreatePairingHandoffOptions {
+    /** Defaults to `<configDir>/remote-pairing.json`. */
+    filePath?: string;
+    /** Defaults to {@link DEFAULT_PAIRING_TTL_MS}. */
+    ttlMs?: number;
+    /** Defaults to a fresh `generateToken()`. */
+    sessionToken?: string;
+    /** Injectable clock for tests. */
+    now?: number;
+}
+/**
+ * Encode bytes as Crockford Base32, MSB first, no padding character.
+ *
+ * 16 bytes (128 bits) produce 26 characters: 25 characters consume 125 bits and
+ * the remaining 3 bits are left-shifted into the 26th.
+ *
+ * @param bytes - Raw bytes to encode
+ * @returns Crockford Base32 string
+ */
+export declare function encodeCrockfordBase32(bytes: Buffer): string;
+/**
+ * Canonicalize a transcribed pairing code.
+ *
+ * This is the whole reason Crockford Base32 was picked over RFC 4648 Base32:
+ * `i`/`l` are accepted as `1`, `o` as `0`, case is irrelevant, and grouping
+ * spaces or hyphens a human inserted are dropped. `generatePairingCode()`
+ * already emits the canonical form, so `normalize(generate()) === generate()`
+ * and the QR path is unaffected.
+ *
+ * @param code - Raw user/QR supplied code
+ * @returns Canonical uppercase form used for hashing
+ */
+export declare function normalizePairingCode(code: string): string;
+/**
+ * Generate a pairing code carrying {@link PAIRING_CODE_BITS} bits of entropy.
+ *
+ * Reuses `generateToken()` (32 random bytes as hex) rather than calling
+ * `randomBytes` again, and keeps the leading 128 bits: at a 10-minute TTL,
+ * single use and a rate limit, 128 bits is already extravagant, and a 26-char
+ * code keeps the QR small enough to scan from a laptop screen.
+ *
+ * @returns 26-character Crockford Base32 code
+ */
+export declare function generatePairingCode(): string;
+/**
+ * Absolute path of the default handoff file.
+ *
+ * @returns `<configDir>/remote-pairing.json`
+ */
+export declare function getDefaultPairingFilePath(): string;
+/**
+ * Read the handoff file path out of the environment.
+ *
+ * @returns The path, or null when `remote` is not running (route answers 404)
+ */
+export declare function getPairingFilePathFromEnv(): string | null;
+/**
+ * Write the handoff file with mode 0600.
+ *
+ * An existing file is unlinked first: `writeFileSync`'s `mode` is only honoured
+ * when the file is created, so writing over a stale world-readable file would
+ * silently keep the old permissions. `chmodSync` afterwards closes the umask
+ * gap for good measure.
+ *
+ * @param filePath - Absolute path of the handoff file
+ * @param handoff - Hash, expiry and plaintext session token
+ */
+export declare function writePairingHandoff(filePath: string, handoff: PairingHandoff): void;
+/**
+ * Mint a pairing code plus its handoff file in one step.
+ *
+ * @param options - Overrides for path, TTL, session token and clock
+ * @returns The plaintext code and token, which the caller must not persist
+ */
+export declare function createPairingHandoff(options?: CreatePairingHandoffOptions): CreatedPairing;
+/**
+ * Read and validate the handoff file.
+ *
+ * Missing and malformed are deliberately the same answer: the caller turns both
+ * into 410 Gone, and "already consumed" arrives here as ENOENT.
+ *
+ * @param filePath - Absolute path of the handoff file
+ * @returns The handoff, or null when it is absent or unusable
+ */
+export declare function readPairingHandoff(filePath: string): PairingHandoff | null;
+/**
+ * Delete the handoff file. Idempotent — a missing file is success.
+ *
+ * @param filePath - Absolute path of the handoff file
+ */
+export declare function consumePairingHandoff(filePath: string): void;
+/**
+ * @param handoff - Handoff read from disk
+ * @param now - Epoch ms, injectable for tests
+ * @returns true when the pairing window has closed
+ */
+export declare function isPairingExpired(handoff: PairingHandoff, now?: number): boolean;
+/**
+ * Timing-safe comparison of a supplied code against the stored hash (S001).
+ *
+ * @param code - Code as supplied by the client
+ * @param pairingHash - SHA-256 hex from the handoff file
+ * @returns true when the code matches
+ */
+export declare function verifyPairingCode(code: string, pairingHash: string): boolean;
+//# sourceMappingURL=pairing-code.d.ts.map

package/dist/lib/security/pairing-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-code.d.ts","sourceRoot":"","sources":["../../../src/lib/security/pairing-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAUH,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,MAAQ,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAE5E,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmB3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,GAAG,IAAI,CAGzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CASnF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CAU9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CA0B1E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM5D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAE3F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAgB5E"}

package/dist/lib/security/pairing-code.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Pairing code lifecycle for `commandmate remote` (Issue #1937, R5)
+ *
+ * Design: docs/design/remote-qr-pairing-1937.md §7
+ *
+ * CONSTRAINTS:
+ * - NODE RUNTIME ONLY. This module touches `fs` and `crypto`; the Edge Runtime
+ *   (`src/middleware.ts`) must never import it. Pairing is an excluded path, so
+ *   middleware never needs to.
+ * - No Next.js imports, so `src/cli/**` can pull it in for `commandmate remote`
+ *   under `tsconfig.cli.json` (which declares `"paths": {}` — relative imports
+ *   only, never `@/...`).
+ *
+ * WHY A FILE AND NOT AN ENVIRONMENT VARIABLE (§7.2)
+ * -------------------------------------------------
+ * The cookie has to carry the *plaintext* long-lived token, so the server must
+ * know it. The obvious route — put it in the server's startup env — is rejected:
+ * `src/lib/tmux/**` passes no `env:` to the panes it spawns, so a pane inherits
+ * the server's environment wholesale, and `sanitizeEnvForChildProcess()` is
+ * called in only two places that an agent pane does not go through. An env var
+ * would therefore be readable by the very Claude / Codex / OpenCode processes
+ * CommandMate is driving.
+ *
+ * So the secret lands in one 0600 handoff file and only its *path* travels in
+ * `CM_REMOTE_PAIRING_FILE` (a path is not a secret). Two further consequences:
+ *
+ *   - The consumed flag is THE ABSENCE OF THE FILE. A module-level variable
+ *     cannot work here: `server.ts` and the Next route handler bundle are
+ *     separate module instances, so state written by one is invisible to the
+ *     other.
+ *   - Deleting the file destroys the plaintext token at the moment of pairing,
+ *     shrinking its window on disk to "remote start → first pairing".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PAIRING_CODE_LENGTH = exports.DEFAULT_PAIRING_TTL_MS = exports.PAIRING_CODE_LENGTH = exports.PAIRING_CODE_BITS = exports.CROCKFORD_BASE32_ALPHABET = exports.PAIRING_FILE_MODE = exports.PAIRING_FILE_NAME = exports.PAIRING_FILE_ENV_KEY = void 0;
+exports.encodeCrockfordBase32 = encodeCrockfordBase32;
+exports.normalizePairingCode = normalizePairingCode;
+exports.generatePairingCode = generatePairingCode;
+exports.getDefaultPairingFilePath = getDefaultPairingFilePath;
+exports.getPairingFilePathFromEnv = getPairingFilePathFromEnv;
+exports.writePairingHandoff = writePairingHandoff;
+exports.createPairingHandoff = createPairingHandoff;
+exports.readPairingHandoff = readPairingHandoff;
+exports.consumePairingHandoff = consumePairingHandoff;
+exports.isPairingExpired = isPairingExpired;
+exports.verifyPairingCode = verifyPairingCode;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const auth_config_1 = require("../../config/auth-config");
+const install_context_1 = require("../../cli/utils/install-context");
+const auth_1 = require("./auth");
+/** Env var carrying the handoff file PATH (never the secret itself). */
+exports.PAIRING_FILE_ENV_KEY = 'CM_REMOTE_PAIRING_FILE';
+/** File name inside the config directory (`~/.commandmate` for global installs). */
+exports.PAIRING_FILE_NAME = 'remote-pairing.json';
+/** Owner read/write only. Asserted by tests, not merely intended. */
+exports.PAIRING_FILE_MODE = 0o600;
+/**
+ * Crockford Base32 (https://www.crockford.com/base32.html).
+ * `I`, `L`, `O` and `U` are absent so a transcribed code cannot be ambiguous.
+ */
+exports.CROCKFORD_BASE32_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Bits of entropy carried by a pairing code. */
+exports.PAIRING_CODE_BITS = 128;
+/** ceil(128 / 5) — the encoded length of PAIRING_CODE_BITS. */
+exports.PAIRING_CODE_LENGTH = 26;
+/** Default time-to-live for one pairing code (§7.4). */
+exports.DEFAULT_PAIRING_TTL_MS = 10 * 60 * 1000;
+/**
+ * Input length cap for `POST /api/remote/pair`, copied from `/api/auth/login`'s
+ * 256-char cap so an oversized body cannot be used to burn CPU on hashing.
+ */
+exports.MAX_PAIRING_CODE_LENGTH = 256;
+/**
+ * Encode bytes as Crockford Base32, MSB first, no padding character.
+ *
+ * 16 bytes (128 bits) produce 26 characters: 25 characters consume 125 bits and
+ * the remaining 3 bits are left-shifted into the 26th.
+ *
+ * @param bytes - Raw bytes to encode
+ * @returns Crockford Base32 string
+ */
+function encodeCrockfordBase32(bytes) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += exports.CROCKFORD_BASE32_ALPHABET[(buffer >>> (bits - 5)) & 0b11111];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += exports.CROCKFORD_BASE32_ALPHABET[(buffer << (5 - bits)) & 0b11111];
+    }
+    return out;
+}
+/**
+ * Canonicalize a transcribed pairing code.
+ *
+ * This is the whole reason Crockford Base32 was picked over RFC 4648 Base32:
+ * `i`/`l` are accepted as `1`, `o` as `0`, case is irrelevant, and grouping
+ * spaces or hyphens a human inserted are dropped. `generatePairingCode()`
+ * already emits the canonical form, so `normalize(generate()) === generate()`
+ * and the QR path is unaffected.
+ *
+ * @param code - Raw user/QR supplied code
+ * @returns Canonical uppercase form used for hashing
+ */
+function normalizePairingCode(code) {
+    return code
+        .replace(/[\s-]/g, '')
+        .toUpperCase()
+        .replace(/[ILO]/g, (character) => (character === 'O' ? '0' : '1'));
+}
+/**
+ * Generate a pairing code carrying {@link PAIRING_CODE_BITS} bits of entropy.
+ *
+ * Reuses `generateToken()` (32 random bytes as hex) rather than calling
+ * `randomBytes` again, and keeps the leading 128 bits: at a 10-minute TTL,
+ * single use and a rate limit, 128 bits is already extravagant, and a 26-char
+ * code keeps the QR small enough to scan from a laptop screen.
+ *
+ * @returns 26-character Crockford Base32 code
+ */
+function generatePairingCode() {
+    const hexDigits = exports.PAIRING_CODE_BITS / 4;
+    return encodeCrockfordBase32(Buffer.from((0, auth_1.generateToken)().slice(0, hexDigits), 'hex'));
+}
+/**
+ * Absolute path of the default handoff file.
+ *
+ * @returns `<configDir>/remote-pairing.json`
+ */
+function getDefaultPairingFilePath() {
+    return (0, path_1.join)((0, install_context_1.getConfigDir)(), exports.PAIRING_FILE_NAME);
+}
+/**
+ * Read the handoff file path out of the environment.
+ *
+ * @returns The path, or null when `remote` is not running (route answers 404)
+ */
+function getPairingFilePathFromEnv() {
+    const value = process.env[exports.PAIRING_FILE_ENV_KEY];
+    return value && value.trim().length > 0 ? value : null;
+}
+/**
+ * Write the handoff file with mode 0600.
+ *
+ * An existing file is unlinked first: `writeFileSync`'s `mode` is only honoured
+ * when the file is created, so writing over a stale world-readable file would
+ * silently keep the old permissions. `chmodSync` afterwards closes the umask
+ * gap for good measure.
+ *
+ * @param filePath - Absolute path of the handoff file
+ * @param handoff - Hash, expiry and plaintext session token
+ */
+function writePairingHandoff(filePath, handoff) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true, mode: 0o700 });
+    try {
+        (0, fs_1.unlinkSync)(filePath);
+    }
+    catch {
+        // Not there yet - the normal case.
+    }
+    (0, fs_1.writeFileSync)(filePath, JSON.stringify(handoff), { encoding: 'utf8', mode: exports.PAIRING_FILE_MODE });
+    (0, fs_1.chmodSync)(filePath, exports.PAIRING_FILE_MODE);
+}
+/**
+ * Mint a pairing code plus its handoff file in one step.
+ *
+ * @param options - Overrides for path, TTL, session token and clock
+ * @returns The plaintext code and token, which the caller must not persist
+ */
+function createPairingHandoff(options = {}) {
+    const filePath = options.filePath ?? (0, path_1.join)((0, install_context_1.ensureConfigDir)(), exports.PAIRING_FILE_NAME);
+    const now = options.now ?? Date.now();
+    const code = generatePairingCode();
+    const sessionToken = options.sessionToken ?? (0, auth_1.generateToken)();
+    const expiresAt = now + (options.ttlMs ?? exports.DEFAULT_PAIRING_TTL_MS);
+    writePairingHandoff(filePath, { pairingHash: (0, auth_1.hashToken)(code), expiresAt, sessionToken });
+    return { code, sessionToken, expiresAt, filePath };
+}
+/**
+ * Read and validate the handoff file.
+ *
+ * Missing and malformed are deliberately the same answer: the caller turns both
+ * into 410 Gone, and "already consumed" arrives here as ENOENT.
+ *
+ * @param filePath - Absolute path of the handoff file
+ * @returns The handoff, or null when it is absent or unusable
+ */
+function readPairingHandoff(filePath) {
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const { pairingHash, expiresAt, sessionToken } = parsed;
+    if (typeof pairingHash !== 'string' || !(0, auth_config_1.isValidTokenHash)(pairingHash))
+        return null;
+    if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt))
+        return null;
+    if (typeof sessionToken !== 'string' || sessionToken.length === 0)
+        return null;
+    return { pairingHash, expiresAt, sessionToken };
+}
+/**
+ * Delete the handoff file. Idempotent — a missing file is success.
+ *
+ * @param filePath - Absolute path of the handoff file
+ */
+function consumePairingHandoff(filePath) {
+    try {
+        (0, fs_1.unlinkSync)(filePath);
+    }
+    catch {
+        // Already gone: the state we wanted.
+    }
+}
+/**
+ * @param handoff - Handoff read from disk
+ * @param now - Epoch ms, injectable for tests
+ * @returns true when the pairing window has closed
+ */
+function isPairingExpired(handoff, now = Date.now()) {
+    return now > handoff.expiresAt;
+}
+/**
+ * Timing-safe comparison of a supplied code against the stored hash (S001).
+ *
+ * @param code - Code as supplied by the client
+ * @param pairingHash - SHA-256 hex from the handoff file
+ * @returns true when the code matches
+ */
+function verifyPairingCode(code, pairingHash) {
+    if (typeof code !== 'string' || code.length === 0 || code.length > exports.MAX_PAIRING_CODE_LENGTH) {
+        return false;
+    }
+    if (!(0, auth_config_1.isValidTokenHash)(pairingHash)) {
+        return false;
+    }
+    const candidate = Buffer.from((0, auth_1.hashToken)(normalizePairingCode(code)), 'hex');
+    const expected = Buffer.from(pairingHash, 'hex');
+    if (candidate.length !== expected.length) {
+        return false;
+    }
+    return (0, crypto_1.timingSafeEqual)(candidate, expected);
+}

package/dist/server/src/config/auth-config.js

@@ -35,6 +35,11 @@ exports.AUTH_EXCLUDED_PATHS = [
     '/api/auth/login',
     '/api/auth/logout',
     '/api/auth/status',
+    // Issue #1937 (R5): one-shot pairing-code exchange for `commandmate remote`.
+    // The pairing SCREEN is '/login' above, driven by a '#code=' fragment, so
+    // this is the only entry the remote feature adds. Handler:
+    // src/app/api/remote/pair/route.ts (it authenticates the code itself).
+    '/api/remote/pair',
     // Issue #1124 (PWA): non-sensitive resources that must stay reachable before
     // auth so the app is installable and the offline fallback can be precached.
     // All carry no user data (app metadata / public SW code / static fallback).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",
@@ -92,6 +92,7 @@
     "next-intl": "^4.8.2",
     "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
+    "qr.js": "0.0.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-markdown": "^10.1.0",

package/.next/static/0GHE2JGlFzqvSBZAcBFSt/_buildManifest.js

@@ -1 +0,0 @@
-self.__BUILD_MANIFEST=function(e,r,t,_){return{__rewrites:{afterFiles:[],beforeFiles:[],fallback:[]},__routerFilterStatic:{numItems:59,errorRate:1e-4,numBits:1132,numHashes:14,bitArray:[1,0,0,1,e,r,e,e,e,r,r,e,r,e,r,r,r,e,e,e,r,e,e,e,r,e,r,r,r,e,r,r,r,e,e,r,e,r,e,r,r,e,r,e,e,e,e,e,e,r,e,r,e,r,r,r,e,e,r,r,e,e,e,r,e,e,r,r,r,r,r,e,e,r,r,r,e,r,r,e,e,e,r,r,r,e,e,e,r,r,r,r,r,e,e,e,r,r,e,r,r,r,e,e,r,e,r,e,r,r,r,r,r,r,e,e,r,r,e,r,e,r,e,e,e,e,r,r,r,r,e,e,e,r,r,r,e,e,e,e,e,e,r,e,e,e,r,e,e,r,e,e,e,r,e,e,e,e,r,e,e,e,e,r,r,e,e,r,r,e,r,r,e,r,e,r,e,e,r,r,r,r,e,e,r,e,r,e,e,e,e,e,r,e,e,r,r,r,e,e,r,e,e,r,e,r,e,e,e,r,r,e,r,e,r,e,e,r,e,e,e,r,e,r,r,r,r,e,e,e,r,e,r,e,r,r,e,e,r,r,e,e,e,r,e,e,r,e,e,r,e,e,e,e,e,r,e,e,e,e,r,e,e,e,r,r,e,e,r,e,r,e,r,e,e,r,e,e,r,e,r,r,r,e,e,r,r,r,e,e,e,e,e,e,r,r,r,e,r,e,e,r,r,r,r,e,r,e,e,r,e,e,e,r,r,e,e,r,e,r,r,e,r,e,e,e,r,r,e,e,e,r,e,e,r,e,e,r,r,e,e,r,e,e,r,r,e,e,e,r,r,e,r,e,e,r,r,r,e,e,e,r,e,r,r,e,r,e,e,e,r,r,r,e,r,e,e,e,r,e,r,e,r,r,e,r,e,e,r,r,e,r,r,r,r,r,r,e,r,e,e,r,r,r,e,r,e,e,e,r,e,e,r,r,r,r,e,e,r,e,e,r,r,e,r,e,e,r,e,e,r,r,r,e,r,e,e,e,e,e,e,e,r,e,r,e,e,e,e,e,r,e,e,r,e,e,r,r,r,e,e,r,r,e,e,r,e,e,r,r,r,r,r,e,e,e,r,e,e,e,e,r,r,r,r,e,r,r,e,r,e,r,e,e,r,r,r,r,e,r,r,e,e,e,e,r,r,e,e,r,e,e,r,e,e,r,r,e,r,e,r,e,e,e,r,r,e,e,e,r,e,e,r,r,r,r,e,r,r,e,r,e,e,e,r,r,e,e,e,e,e,r,e,e,r,e,r,e,r,r,r,r,e,e,r,e,r,r,r,r,r,r,r,r,e,e,e,e,r,e,r,r,e,r,r,r,e,r,e,r,e,e,e,e,r,r,r,e,r,e,r,e,e,r,r,e,e,e,e,e,e,r,r,e,e,r,r,e,e,r,e,e,e,r,e,r,e,e,e,e,e,e,r,r,e,e,e,e,e,r,r,e,r,r,r,r,e,r,e,r,e,e,r,e,e,r,e,r,r,e,r,e,e,e,e,e,r,e,e,r,r,e,e,e,e,e,e,e,e,r,r,r,r,r,e,r,r,e,e,e,r,e,e,r,r,e,r,e,e,r,e,r,e,r,e,e,r,r,r,e,e,e,r,e,r,r,r,r,r,e,e,e,r,e,e,r,r,e,r,e,e,e,r,e,r,e,r,e,e,e,e,r,e,r,e,r,e,r,e,r,e,r,e,r,e,e,e,e,e,e,r,e,r,r,r,r,r,e,e,r,r,e,r,e,r,r,r,e,e,e,e,r,r,e,e,r,r,e,r,r,e,r,e,e,r,r,r,e,r,e,r,r,r,e,r,e,r,e,r,e,e,e,e,r,r,e,e,e,e,r,r,r,r,e,e,e,e,r,r,e,r,e,e,r,e,r,e,e,e,e,e,e,r,r,e,e,r,r,e,e,r,e,e,r,r,r,e,r,r,r,r,e,r,r,e,r,e,e,e,r,r,r,e,r,e,e,r,e,r,r,r,r,e,r,e,e,r,r,e,r,e,r,r,r,e,r,e,r,e,r,e,r,r,r,r,r,r,r,r,e,r,r,r,e,r,r,e,r,r,r,r,e,e,r,r,r,e,e,r,e,e,e,e,r,r,r,e,e,e,r,r,e,r,r,r,r,r,r,r,r,e,e,r,e,e,r,r,e,r,e,e,r,r,e,r,e,r,r,e,e,e,e,r,e,r,r,r,r,r,e,e,r,r,e,r,r,r,r,r,e,r,e,r,e,r,r,r,e,r,e,r,r,e,e,e,r,e,r,e,r,e,e,r,e,r,r,r,e,e,r,r,r,e,r,e,r,e,r,e,e,r,r,r,r,e,r,r,r,e,r,e,r,r,e,e,r,e,e,e,e,r,r,e,r,e,e,r,r,e,e,e,e,r,r,e,e,r,e,e,e,e,e,r,r,r,r,e,e,e,r,e,e,r,e,e,r,e,e,r,r,r,r,r,r,r,r,r,e,e,e,r,r,e,e,e,e,r,e,e,e,r,r,r,e,e,e,r,e,e,r,e,r,r,r,r,e,e,r,r,e,e,r]},__routerFilterDynamic:{numItems:11,errorRate:1e-4,numBits:211,numHashes:14,bitArray:[r,e,e,e,r,e,r,r,r,r,e,r,r,e,r,e,r,e,e,e,r,r,e,e,e,r,e,e,e,r,r,e,r,e,e,r,r,r,e,r,e,e,e,r,r,e,r,e,e,r,r,e,e,e,r,e,r,e,r,r,e,r,e,e,r,e,e,r,e,e,e,e,r,e,e,r,r,r,e,e,e,e,e,r,r,r,e,r,e,e,e,r,e,r,e,r,e,e,r,r,e,e,r,e,r,e,r,e,e,e,e,r,r,e,e,r,e,e,e,e,r,e,e,r,r,e,e,r,e,r,e,e,r,e,e,e,e,r,r,e,r,r,r,e,r,r,r,r,r,e,e,e,r,e,r,e,r,e,e,e,e,e,r,r,r,e,e,r,r,e,e,r,r,e,r,r,e,e,r,r,r,e,e,r,e,r,r,r,e,r,e,r,e,e,e,r,e,r,r,r,e,r,e,e,e,r,e,e,r,r,e]},"/_error":["static/chunks/pages/_error-c970d8b55ace1b48.js"],sortedPages:["/_app","/_error"]}}(1,0,1e-4,14),self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();