fix(cli): keep the Remote Control link token-free and make the relay configurable

The tunnel client already adds the bearer token to every request it
replays against the local server, so the link needs no credential. Drop
the token fragment that was leaking the machine-wide server token into
the terminal, the QR image on disk, and the remote browser's URL bar.

Add --relay-origin and PYTHINKER_CODE_REMOTE_CONTROL_RELAY: this build
ships no relay, so the relay had no way to be set outside tests. Restrict
the lock file and the QR image to owner-only permissions.

Author: elkaix

apps/pythinker-code/src/cli/sub/web/remote-control-lock.ts

@@ -53,7 +53,8 @@ export async function acquireRemoteControlLock(
   details: { localOrigin: string; deviceId: string; url: string },
 ): Promise<RemoteControlLock> {
   const lockPath = remoteControlLockPath(homeDir);
-  await mkdir(dirname(lockPath), { recursive: true });
+  // The lock sits beside `server.token`; keep the same owner-only permissions.
+  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
   const info: RemoteControlLockInfo = {
     pid: process.pid,
     nonce: randomBytes(8).toString('hex'),
@@ -64,7 +65,7 @@ export async function acquireRemoteControlLock(
   };
   for (let attempt = 0; ; attempt += 1) {
     try {
-      const handle = await open(lockPath, 'wx');
+      const handle = await open(lockPath, 'wx', 0o600);
       try {
         await handle.writeFile(encodeLock(info));
       } finally {

apps/pythinker-code/src/cli/sub/web/remote-control.ts

@@ -15,6 +15,26 @@ export const REMOTE_CONTROL_RELAY_ORIGIN = 'https://code-rc.pythinker.com';
 
 export const REMOTE_CONTROL_FLAG_ENV = 'PYTHINKER_CODE_EXPERIMENTAL_REMOTE_CONTROL';
 
+export const REMOTE_CONTROL_RELAY_ENV = 'PYTHINKER_CODE_REMOTE_CONTROL_RELAY';
+
+/**
+ * Resolve the relay to tunnel through. Pythinker ships no relay, so an operator
+ * running their own points at it with `--relay-origin` or the env var; the
+ * default constant is the last resort.
+ */
+export function resolveRelayOrigin(
+  explicit?: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+  const candidate = explicit?.trim() ?? env[REMOTE_CONTROL_RELAY_ENV]?.trim() ?? '';
+  if (candidate.length === 0) return REMOTE_CONTROL_RELAY_ORIGIN;
+  const url = new URL(candidate);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`Remote Control relay must be an http(s) URL: ${candidate}`);
+  }
+  return candidate;
+}
+
 const TRUTHY_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
 
 export function isRemoteControlEnabled(
@@ -181,7 +201,6 @@ export function buildRemoteControlUrl(
   deviceId: string,
   sessionId?: string,
   relayOrigin = REMOTE_CONTROL_RELAY_ORIGIN,
-  serverToken?: string,
 ): string {
   const url = new URL(relayOrigin);
   const relayPath = url.pathname.replace(/\/+$/, '');
@@ -191,7 +210,7 @@ export function buildRemoteControlUrl(
       ? `${devicePath}/`
       : `${devicePath}/sessions/${encodeURIComponent(sessionId)}`;
   url.search = new URLSearchParams({ rc: '1', from: 'pythinker_code_cli' }).toString();
-  url.hash = serverToken === undefined ? '' : `token=${serverToken}`;
+  url.hash = '';
   return url.toString();
 }
 
@@ -294,7 +313,7 @@ export async function startRemoteControl(
   const relayOrigin = options.relayOrigin ?? REMOTE_CONTROL_RELAY_ORIGIN;
   const deviceId = createPythinkerDeviceId(options.homeDir);
   const deviceName = hostname();
-  const url = buildRemoteControlUrl(deviceId, undefined, relayOrigin, options.localServerToken);
+  const url = buildRemoteControlUrl(deviceId, undefined, relayOrigin);
   const lock = await acquireRemoteControlLock(options.homeDir, {
     localOrigin: options.localOrigin.replace(/\/+$/, ''),
     deviceId,

apps/pythinker-code/src/cli/sub/web/run.ts

@@ -45,6 +45,7 @@ import {
   formatRemoteControlStatus,
   isRemoteControlEnabled,
   REMOTE_CONTROL_FLAG_ENV,
+  resolveRelayOrigin,
   startRemoteControl,
   type RemoteControlHandle,
   type RemoteControlOptions,
@@ -78,6 +79,7 @@ interface RoutedServer {
 export interface WebCliOptions extends ServerCliOptions {
   open?: boolean;
   remoteControl?: boolean;
+  relayOrigin?: string;
 }
 
 export interface StartForegroundHooks {
@@ -182,6 +184,12 @@ export function buildWebCommand(
         .hideHelp(!isRemoteControlEnabled()),
     );
   }
+  withServerOptions.addOption(
+    new Option(
+      '--relay-origin <url>',
+      'Remote Control relay to tunnel through. Defaults to $PYTHINKER_CODE_REMOTE_CONTROL_RELAY.',
+    ).hideHelp(!isRemoteControlEnabled()),
+  );
   return withServerOptions
     .option('--no-open', 'Do not open the web UI in the default browser.', true)
     .action(async (opts: WebCliOptions) => {
@@ -212,6 +220,7 @@ export async function handleWebCommand(
   if (opts.remoteControl === true && !isLoopbackHost(parsed.host)) {
     throw new Error('--remote-control requires a loopback host.');
   }
+  const relayOrigin = opts.remoteControl === true ? resolveRelayOrigin(opts.relayOrigin) : undefined;
   const run = deps.startServerForeground ?? startServerForeground;
   let remoteControl: RemoteControlHandle | undefined;
   await run(parsed, {
@@ -241,6 +250,7 @@ export async function handleWebCommand(
           homeDir: dataDir,
           localOrigin: origin,
           localServerToken: token,
+          relayOrigin,
           stderr: deps.stderr,
           onStatus,
         });

apps/pythinker-code/src/tui/commands/web.ts

@@ -5,6 +5,7 @@ import {
   buildRemoteControlUrl,
   formatRemoteControlOutput,
   formatRemoteControlStatus,
+  resolveRelayOrigin,
   startRemoteControl,
   type RemoteControlStatus,
 } from '#/cli/sub/web/remote-control';
@@ -61,6 +62,7 @@ export async function handleRemoteControlCommand(host: SlashCommandHost): Promis
 
   host.setExitForegroundTask(async () => {
     const options = parseServerOptions({});
+    const relayOrigin = resolveRelayOrigin();
     let remoteControl: Awaited<ReturnType<typeof startRemoteControl>> | undefined;
     try {
       await startServerForeground(options, {
@@ -79,9 +81,10 @@ export async function handleRemoteControlCommand(host: SlashCommandHost): Promis
             homeDir: dataDir,
             localOrigin: origin,
             localServerToken: token,
+            relayOrigin,
             onStatus,
           });
-          const url = buildRemoteControlUrl(remoteControl.deviceId, session?.id, undefined, token);
+          const url = buildRemoteControlUrl(remoteControl.deviceId, session?.id, relayOrigin);
           const qrCode = await generateRemoteControlQr(url, dataDir);
           process.stdout.write(
             formatRemoteControlOutput({

apps/pythinker-code/src/utils/remote-control-qr.ts

@@ -21,10 +21,10 @@ export async function generateRemoteControlQr(
   url: string,
   dataDir: string,
 ): Promise<{ terminal: string; pngPath: string }> {
-  await mkdir(dataDir, { recursive: true });
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
   const pngPath = resolve(dataDir, 'rc-qrcode.png');
   const png = await QRCode.toBuffer(url, { type: 'png', margin: QR_PNG_MARGIN });
-  await writeFile(pngPath, png);
+  await writeFile(pngPath, png, { mode: 0o600 });
   const terminal = renderInlineImageQr(url, png) ?? renderTerminalQr(url);
   return { terminal, pngPath };
 }

apps/pythinker-code/test/cli/web/remote-control.test.ts

@@ -168,6 +168,32 @@ describe('Remote Control HTTP forwarding', () => {
   });
 });
 
+describe('resolveRelayOrigin', () => {
+  it('prefers the explicit value, then the env var, then the built-in default', async () => {
+    const { resolveRelayOrigin, REMOTE_CONTROL_RELAY_ORIGIN } = await import(
+      '#/cli/sub/web/remote-control'
+    );
+    expect(resolveRelayOrigin('https://relay.example.test', {})).toBe('https://relay.example.test');
+    expect(
+      resolveRelayOrigin(undefined, {
+        PYTHINKER_CODE_REMOTE_CONTROL_RELAY: 'https://env.example.test',
+      }),
+    ).toBe('https://env.example.test');
+    expect(resolveRelayOrigin(undefined, {})).toBe(REMOTE_CONTROL_RELAY_ORIGIN);
+    expect(resolveRelayOrigin('  ', { PYTHINKER_CODE_REMOTE_CONTROL_RELAY: '  ' })).toBe(
+      REMOTE_CONTROL_RELAY_ORIGIN,
+    );
+  });
+
+  it('rejects a relay that is not http(s)', async () => {
+    const { resolveRelayOrigin } = await import('#/cli/sub/web/remote-control');
+    expect(() => resolveRelayOrigin('ws://relay.example.test', {})).toThrow(
+      'Remote Control relay must be an http(s) URL',
+    );
+    expect(() => resolveRelayOrigin('not-a-url', {})).toThrow();
+  });
+});
+
 describe('Remote Control tunnel', () => {
   it('surfaces register_nak details', async () => {
     const homeDir = mkdtempSync(join(tmpdir(), 'pythinker-rc-nak-'));

apps/pythinker-code/test/cli/web/web.test.ts

@@ -404,6 +404,35 @@ describe('`pythinker web` opens the browser', () => {
     }
   });
 
+  it('passes the resolved relay origin to the tunnel', async () => {
+    vi.stubEnv('PYTHINKER_CODE_EXPERIMENTAL_REMOTE_CONTROL', '1');
+    const { handleWebCommand } = await import('#/cli/sub/web/run');
+    const { runner } = makeRunner();
+    const { stdout, stderr } = makeIo();
+    const startRemoteControl = vi.fn(async () => ({
+      deviceId: 'device-1',
+      deviceName: 'example-device',
+      url: 'https://relay.example.test/devices/device-1/?rc=1&from=pythinker_code_cli',
+      close: async () => {},
+    }));
+
+    await handleWebCommand(
+      { remoteControl: true, relayOrigin: 'https://relay.example.test', open: false },
+      {
+        startServerForeground: runner,
+        openUrl: vi.fn(),
+        resolveToken: () => 'tok-1',
+        startRemoteControl,
+        stdout,
+        stderr,
+      },
+    );
+
+    expect(startRemoteControl).toHaveBeenCalledWith(
+      expect.objectContaining({ relayOrigin: 'https://relay.example.test' }),
+    );
+  });
+
   it('rejects Remote Control on a non-loopback host', async () => {
     vi.stubEnv('PYTHINKER_CODE_EXPERIMENTAL_REMOTE_CONTROL', '1');
     const { handleWebCommand } = await import('#/cli/sub/web/run');

apps/pythinker-code/test/tui/commands/web.test.ts

@@ -184,7 +184,7 @@ describe('handleRemoteControlCommand', () => {
     }
   });
 
-  it('starts the tunnel and saves a session QR code carrying the server token', async () => {
+  it('starts the tunnel and saves a token-free session QR code', async () => {
     vi.clearAllMocks();
     setCapabilities({ images: null, trueColor: true, hyperlinks: false });
     const { mkdtempSync, readFileSync, rmSync } = await import('node:fs');
@@ -196,7 +196,7 @@ describe('handleRemoteControlCommand', () => {
     const entryUrl =
       'https://code-rc.pythinker.com/devices/device-1/?rc=1&from=pythinker_code_cli';
     const sessionUrl =
-      'https://code-rc.pythinker.com/devices/device-1/sessions/ses-1?rc=1&from=pythinker_code_cli#token=local-server-token';
+      'https://code-rc.pythinker.com/devices/device-1/sessions/ses-1?rc=1&from=pythinker_code_cli';
     const pngPath = join(dataDir, 'rc-qrcode.png');
     mocks.getDataDir.mockReturnValue(dataDir);
     mocks.tryResolveServerToken.mockReturnValue('local-server-token');
@@ -244,7 +244,8 @@ describe('handleRemoteControlCommand', () => {
       const png = readFileSync(pngPath);
       expect(png.subarray(0, 8)).toEqual(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
       expect(png).toEqual(await QRCode.toBuffer(sessionUrl));
-      expect(written).toContain('#token=local-server-token');
+      expect(written).not.toContain('local-server-token');
+      expect(written).not.toContain('#token=');
       expect(close).toHaveBeenCalledOnce();
     } finally {
       writeSpy.mockRestore();
@@ -263,7 +264,6 @@ describe('handleRemoteControlCommand', () => {
     const dataDir = join(tempRoot, 'custom-home');
     const entryUrl =
       'https://code-rc.pythinker.com/devices/device-1/?rc=1&from=pythinker_code_cli';
-    const entryUrlWithToken = `${entryUrl}#token=local-server-token`;
     mocks.getDataDir.mockReturnValue(dataDir);
     mocks.tryResolveServerToken.mockReturnValue('local-server-token');
     const close = vi.fn(async () => {});
@@ -300,12 +300,12 @@ describe('handleRemoteControlCommand', () => {
       const task = host.setExitForegroundTask.mock.calls[0]![0] as () => Promise<void>;
       await task();
 
-      expect(mocks.openUrl).toHaveBeenCalledWith(entryUrlWithToken);
+      expect(mocks.openUrl).toHaveBeenCalledWith(entryUrl);
       const written = writeSpy.mock.calls.map((call) => String(call[0])).join('');
-      expect(written).toContain(indentedQr(entryUrlWithToken));
+      expect(written).toContain(indentedQr(entryUrl));
       expect(written).not.toContain('/sessions/');
       expect(readFileSync(join(dataDir, 'rc-qrcode.png'))).toEqual(
-        await QRCode.toBuffer(entryUrlWithToken),
+        await QRCode.toBuffer(entryUrl),
       );
       expect(close).toHaveBeenCalledOnce();
     } finally {

docs/guides/remote-control.md

@@ -24,11 +24,19 @@ The terminal prints a QR code, a link, and the path of a PNG copy of the QR code
 
 ## Security
 
-The link grants control of this machine. It carries the access token in its URL fragment, which the browser keeps to itself and never sends to the relay. Do not share the link or the QR code.
+The link grants control of this machine. Do not share the link or the QR code.
+
+The link carries no access token. Requests reach the local server through the tunnel, and the Pythinker Code process on this machine adds the bearer token to each one, so the token never leaves this machine.
 
 ## Relay
 
-Traffic reaches the remote device through a relay. Set `relayOrigin` to point at your own relay; the default is `https://code-rc.pythinker.com`.
+Traffic reaches the remote device through a relay. Point Remote Control at your own relay with `--relay-origin`:
+
+```sh
+pythinker rc --relay-origin https://relay.example.com
+```
+
+`PYTHINKER_CODE_REMOTE_CONTROL_RELAY` sets the same thing for `/rc` in the terminal UI and for every run in a shell.
 
 ## Stop it