Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(pair): offer the pairing QR in the app's URL scheme so the iPhone Camera can open it

enes3833ac80a55e
diff --git a/src/main/pairing-core.test.ts b/src/main/pairing-core.test.ts
index 128635a7e..69e02b665 100644
--- a/src/main/pairing-core.test.ts
+++ b/src/main/pairing-core.test.ts
@@ -1,4 +1,5 @@
import { describe, it, expect } from 'vitest'
+import { encodePairQr, PAIR_URL_PREFIX } from '@shared/pair-qr'
import {
buildPairingPayload,
deviceCommentFor,
@@ -370,3 +371,34 @@ describe('pickLanIPv4', () => {
).toBe(null)
})
})
+
+// The QR ENVELOPE (src/shared/pair-qr.ts) composed with the real payload builder. The encoder's
+// own edge cases are covered there; this pins the one thing only this project can check — that
+// what the builder emits survives the URL wrapping byte-for-byte (eneskirca/nodeterm#745).
+describe('encodePairQr over a built payload', () => {
+ const payload = buildPairingPayload({
+ host: '192.168.1.5',
+ port: 22,
+ user: 'enes',
+ token: 'tok',
+ pairPort: 5,
+ name: 'Mac',
+ hostKey: 'AAAAhostpub',
+ relay: {
+ hostId: 'abcABC012_-def012ghij',
+ hostPublicKeyB64: 'AAAAhostpub',
+ relayEndpoint: 'wss://relay.nodeterm.dev'
+ }
+ })
+
+ it('leaves the payload untouched in the default (json) form', () => {
+ expect(encodePairQr(payload)).toBe(payload)
+ })
+
+ it('round-trips the built payload through the url form', () => {
+ const url = encodePairQr(payload, 'url')
+ expect(url.startsWith(PAIR_URL_PREFIX)).toBe(true)
+ const code = url.slice(PAIR_URL_PREFIX.length)
+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(payload)
+ })
+})
diff --git a/src/renderer/components/settings/sections/PhoneSection.tsx b/src/renderer/components/settings/sections/PhoneSection.tsx
index ad72b58c4..10e5616c2 100644
--- a/src/renderer/components/settings/sections/PhoneSection.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.tsx
@@ -63,7 +63,21 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
// The shared pairing machine (also behind the top-right quick-pair popover); a completed
// pairing refreshes the device list below — and drops the last revoke note, which names a device
// by name and would otherwise outlive the very phone it warns about being re-paired.
- const { phase, qr, sshOpen, sshHealed, relayResult, relayPlan, error, busy, start, stop, reset } = usePhonePairing(
+ const {
+ phase,
+ qr,
+ qrForm,
+ setQrForm,
+ sshOpen,
+ sshHealed,
+ relayResult,
+ relayPlan,
+ error,
+ busy,
+ start,
+ stop,
+ reset
+ } = usePhonePairing(
() => {
setRevokeNote(null)
void refreshDevices()
@@ -232,6 +246,30 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
className="rounded-lg bg-white p-2"
/>
<p className="text-sm text-muted">Waiting for your phone… (10 min)</p>
+ {/* eneskirca/nodeterm#745: the default QR encodes the payload as raw JSON,
+ which the iPhone's Camera app can only show as text — there is nothing in
+ it to open. This switches the SAME live token to the app's URL scheme so
+ Camera can hand it to nodeterm. Opt-in, because a phone on an app version
+ without URL support reads only the JSON form. */}
+ <div className="space-y-1">
+ <button
+ type="button"
+ className="text-xs text-muted underline"
+ onClick={() => setQrForm(qrForm === 'url' ? 'json' : 'url')}
+ >
+ {qrForm === 'url'
+ ? 'Show the in-app code instead'
+ : 'Scan with the iPhone Camera app instead'}
+ </button>
+ {qrForm === 'url' ? (
+ <p className="text-xs text-muted">
+ Point the iPhone&apos;s own Camera at this and tap the nodeterm banner.
+ Needs a recent version of the iOS app — if your phone doesn&apos;t
+ recognise it, switch back and scan from inside nodeterm. Same code
+ either way; switching doesn&apos;t restart pairing.
+ </p>
+ ) : null}
+ </div>
{relayPlan === 'dev' ? (
<p className="text-sm" style={{ color: '#ff9f0a' }}>
Dev build: the relay is off regardless of the toggle, so this code pairs
diff --git a/src/renderer/components/settings/usePhonePairing.ts b/src/renderer/components/settings/usePhonePairing.ts
index c6f5c03c2..3164e03e1 100644
--- a/src/renderer/components/settings/usePhonePairing.ts
+++ b/src/renderer/components/settings/usePhonePairing.ts
@@ -1,5 +1,6 @@
import { useEffect, useRef, useState } from 'react'
import { toDataURL } from 'qrcode'
+import { DEFAULT_PAIR_QR_FORM, encodePairQr, type PairQrForm } from '@shared/pair-qr'
export type PairingPhase = 'idle' | 'waiting' | 'paired' | 'timeout'
@@ -16,6 +17,10 @@ const SSH_RECHECK_MS = 2000
export function usePhonePairing(onPaired?: () => void): {
phase: PairingPhase
qr: string
+ /** Which envelope the QR on screen encodes. Switching it re-renders the SAME live token —
+ * it never restarts pairing (eneskirca/nodeterm#745). */
+ qrForm: PairQrForm
+ setQrForm: (form: PairQrForm) => void
sshOpen: boolean
sshHealed: boolean
/** On phase 'paired': whether the pairing came with a relay leg ('off' = toggle disabled,
@@ -33,6 +38,10 @@ export function usePhonePairing(onPaired?: () => void): {
} {
const [phase, setPhase] = useState<PairingPhase>('idle')
const [qr, setQr] = useState('')
+ // The built payload JSON, kept so the QR can be re-encoded in the other envelope without
+ // minting a new token — the listener on the other end is keyed to THIS one.
+ const [payload, setPayload] = useState('')
+ const [qrForm, setQrForm] = useState<PairQrForm>(DEFAULT_PAIR_QR_FORM)
const [sshOpen, setSshOpen] = useState(true)
// Went from unreachable → reachable while the warning was showing: show a green confirmation
// instead of silently dropping the warning (the user just flipped a toggle; acknowledge it).
@@ -74,10 +83,11 @@ export function usePhonePairing(onPaired?: () => void): {
setError('')
setBusy(true)
try {
- const { payload, sshOpen: open, relayPlan: plan } = await window.nodeTerminal.pairing.start()
+ const { payload: built, sshOpen: open, relayPlan: plan } = await window.nodeTerminal.pairing.start()
setRelayPlan(plan ?? null)
- const dataUrl = await toDataURL(payload, { margin: 1, width: 240 })
- setQr(dataUrl)
+ // The image itself is rendered by the effect below, which also handles a later switch
+ // between the JSON and URL envelopes.
+ setPayload(built)
setSshOpen(open)
setSshHealed(false)
setRelayResult(null)
@@ -90,12 +100,35 @@ export function usePhonePairing(onPaired?: () => void): {
}
}
+ // Render the QR for whatever payload + envelope is current. Re-runs when the user switches
+ // envelope, which is deliberately NOT a restart: same token, same listener, different
+ // encoding of the same bytes.
+ useEffect(() => {
+ if (!payload) {
+ setQr('')
+ return
+ }
+ let cancelled = false
+ void toDataURL(encodePairQr(payload, qrForm), { margin: 1, width: 240 })
+ .then((dataUrl) => {
+ if (!cancelled) setQr(dataUrl)
+ })
+ .catch(() => {
+ // Keep whatever image is already up; the pairing listener is unaffected by a render
+ // failure, and a blank QR with no explanation is the failure mode #745 was about.
+ })
+ return () => {
+ cancelled = true
+ }
+ }, [payload, qrForm])
+
const stop = (): void => {
if (runningRef.current) {
runningRef.current = false
void window.nodeTerminal.pairing.stop()
}
setPhase('idle')
+ setPayload('')
setQr('')
}
@@ -106,6 +139,7 @@ export function usePhonePairing(onPaired?: () => void): {
useEffect(() => {
return window.nodeTerminal.pairing.onDone((result) => {
runningRef.current = false
+ setPayload('')
setQr('')
setPhase(result.ok ? 'paired' : 'timeout')
setRelayResult(result.ok ? (result.relay ?? null) : null)
@@ -123,5 +157,19 @@ export function usePhonePairing(onPaired?: () => void): {
}
}, [])
- return { phase, qr, sshOpen, sshHealed, relayResult, relayPlan, error, busy, start, stop, reset: () => setPhase('idle') }
+ return {
+ phase,
+ qr,
+ qrForm,
+ setQrForm,
+ sshOpen,
+ sshHealed,
+ relayResult,
+ relayPlan,
+ error,
+ busy,
+ start,
+ stop,
+ reset: () => setPhase('idle')
+ }
}
diff --git a/src/shared/pair-qr.test.ts b/src/shared/pair-qr.test.ts
new file mode 100644
index 000000000..25df8d070
--- /dev/null
+++ b/src/shared/pair-qr.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { encodePairQr, PAIR_URL_PREFIX, DEFAULT_PAIR_QR_FORM } from './pair-qr'
+
+// The exact string `buildPairingPayload` emits, as a literal: this file belongs to the web
+// tsconfig project and cannot import from src/main. The composition with the real builder is
+// asserted in `src/main/pairing-core.test.ts` instead.
+const payload =
+ '{"v":1,"host":"192.168.1.5","port":22,"user":"enes","token":"tok123","pairPort":54321,"nodeterm":true,"name":"MacBook"}'
+
+describe('encodePairQr', () => {
+ it('defaults to the raw JSON every shipped iOS version can read', () => {
+ expect(DEFAULT_PAIR_QR_FORM).toBe('json')
+ expect(encodePairQr(payload)).toBe(payload)
+ expect(encodePairQr(payload, 'json')).toBe(payload)
+ })
+
+ it('wraps the SAME bytes in the app URL scheme for the url form', () => {
+ const url = encodePairQr(payload, 'url')
+ expect(url.startsWith(PAIR_URL_PREFIX)).toBe(true)
+ const code = url.slice(PAIR_URL_PREFIX.length)
+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(payload)
+ })
+
+ it('emits base64url, not base64 — the code rides in a query parameter', () => {
+ // A payload whose base64 is guaranteed to contain + and / unless base64url is used.
+ const awkward = JSON.stringify({ v: 1, name: 'ÿÿÿþ>?>?', host: 'a'.repeat(3) })
+ const code = encodePairQr(awkward, 'url').slice(PAIR_URL_PREFIX.length)
+ expect(code).not.toMatch(/[+/=]/)
+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(awkward)
+ })
+
+ it('round-trips a payload carrying the relay block and host key', () => {
+ const full =
+ '{"v":1,"host":"10.0.0.2","port":22,"user":"enes","token":"tok","pairPort":5,' +
+ '"nodeterm":true,"name":"Mac","hostKey":"AAAAhostpub","relay":' +
+ '{"hostId":"abcABC012_-def012ghij","hostPublicKeyB64":"AAAAhostpub",' +
+ '"relayEndpoint":"wss://relay.nodeterm.dev"}}'
+ const code = encodePairQr(full, 'url').slice(PAIR_URL_PREFIX.length)
+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(full)
+ })
+
+ it('produces a URL the phone-side parse rules accept (scheme, host, code param)', () => {
+ const url = new URL(encodePairQr(payload, 'url'))
+ expect(url.protocol).toBe('nodeterm:')
+ expect(url.hostname).toBe('pair')
+ expect(url.pathname === '' || url.pathname === '/').toBe(true)
+ expect(url.searchParams.get('code')).toBeTruthy()
+ })
+})
diff --git a/src/shared/pair-qr.ts b/src/shared/pair-qr.ts
new file mode 100644
index 000000000..c5c038439
--- /dev/null
+++ b/src/shared/pair-qr.ts
@@ -0,0 +1,46 @@
+// What the phone-pairing QR actually encodes.
+//
+// The payload is built by `pairing-core.buildPairingPayload`, and its JSON shape is a fixed
+// contract with the nodeterm iOS app. This module is only about the ENVELOPE that JSON is
+// wrapped in on its way to becoming a QR:
+//
+// 'json' — the raw payload JSON. What every release so far has encoded, and the only shape
+// an older iOS app can read.
+// 'url' — `nodeterm://pair?code=<base64url(json)>`. The same bytes, wrapped in the app's
+// registered URL scheme.
+//
+// Why 'url' exists (eneskirca/nodeterm#745): a QR carrying raw JSON is just *text* to the
+// iPhone's system Camera app — there is nothing in it to open, which is why scanning the
+// pairing QR with Camera does nothing. A URL is the only shape Camera can act on.
+//
+// Mirrors `PairURL` + `PairingService.decode` on the phone (nodeterm-ios#23), which accept the
+// URL form, the raw JSON, and a bare base64url code. 'json' stays the DEFAULT until that phone
+// build has shipped widely — see the note on `DEFAULT_PAIR_QR_FORM`.
+
+export type PairQrForm = 'json' | 'url'
+
+/** The scheme + host + parameter the phone matches on. Same envelope as the relay offer. */
+export const PAIR_URL_PREFIX = 'nodeterm://pair?code='
+
+/**
+ * The form used unless the user asks for the other one.
+ *
+ * Deliberately 'json': a phone running an app version that predates URL support decodes the QR
+ * as payload JSON and nothing else, so emitting URLs by default would silently break pairing
+ * for everyone who has not updated — the exact failure #745 reported, re-created for a
+ * different group. Flip this only once the URL-accepting iOS build is out and adopted.
+ */
+export const DEFAULT_PAIR_QR_FORM: PairQrForm = 'json'
+
+/** base64url, no padding. Uses `btoa`, a global in both the renderer and Node ≥ 16. */
+function base64url(input: string): string {
+ const bytes = new TextEncoder().encode(input)
+ let binary = ''
+ for (const b of bytes) binary += String.fromCharCode(b)
+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/** Wrap a built pairing payload in the requested envelope. Pure; never throws. */
+export function encodePairQr(payloadJson: string, form: PairQrForm = DEFAULT_PAIR_QR_FORM): string {
+ return form === 'url' ? `${PAIR_URL_PREFIX}${base64url(payloadJson)}` : payloadJson
+}