@gotcos/glasses-server 6.66.0 → 6.67.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 6.67.0 — 2026-10-09 — glasses pairing
+
+- Pair COS Glasses with your Mac by scanning a code instead of pasting the pairing token. COS Control shows a QR and a short code; the phone claims it, and nothing happens until you press Allow on the Mac. Pairs with COS Glasses 6.10.621 and the COS Control pairing release. Contract: `docs/pairing-contract.md`.
+  - `GET /api/health` adds `capabilities.pairing = { version: 1 }`. An older server leaves it out, which is how the phone knows to say "Update COS on your Mac".
+  - `POST /api/pairing/code` (token, and only from this Mac) makes an 8-character code, good for 5 minutes and one use, plus the QR text `COS1/MAC/<CODE>/<host>:<port>[+…]/<EXP>`, which uses only characters a QR can pack tightly. Tailscale addresses come first. A Wi-Fi address is offered only when "Allow pairing on this Wi-Fi" is on, and that lasts 10 minutes. A new code cancels the old one and any claim waiting for Allow.
+  - `POST /api/pairing/claim` and `GET /api/pairing/claim/<nonce>` need no token. A claim is accepted over Tailscale, or over the home Wi-Fi only while that is allowed. It waits up to 60 seconds for Allow. The phone then reads the pairing token once; a second read says `delivered` without it. The poll must come from the same address as the claim, and keeps answering during an update so an allowed token is never lost.
+  - `GET /api/pairing/status` and `POST /api/pairing/decision` (token, and only from this Mac) are how Control shows "wants to pair: Allow / Deny" and turns green, which happens only when the new phone makes its first signed-in request.
+  - Limits: 5 claims a minute per address, 20 tries per code (then it locks until a new code). The limits use the real connection address, never `X-Forwarded-For`.
+  - Everything is kept in memory. A restart forgets every code (`unknown_code`, a new `bootId`). The pairing routes write no files, so they never hold up an update; during one they answer `draining`.
+  - Logs carry the address, the result and a 2-character hash of the code, never the code, the nonce, the token or the QR text.
+- A rejected token now says "Paste the pairing token from COS Control, or scan its code with COS Glasses 6.10.621 or newer." The `reason` stays `pairing_token_rejected`.
+- The pairing token is still the only standing credential. See SECURITY.md.
+- Compatibility: nothing changes for existing users. Pasting the pairing token still works, and older COS Control and COS Glasses builds keep working with this server. Scanning needs COS Glasses 6.10.621 and the COS Control release with the Glasses setup section. The QR needs Tailscale on both the Mac and the iPhone, or the 10-minute "Allow pairing on this Wi-Fi" switch at home.
+- `docs/pairing-fixture.json` is a parity fixture the glasses app copies: the alphabet, real QR text, the reasons and the limits, checked against the server's code by its tests.
+
 ## 6.66.0 — 2026-10-08 — Managed voice setup and Haiku polish
 
 - Advertise Haiku, Sonnet and GPT-5.6 Luna Fast. Default omitted-model polish to Haiku for lower cost, while honoring explicit model choices and retaining the transcript on failure.

package/SECURITY.md

@@ -27,6 +27,22 @@ reproduction you have. Do not include real transcripts.
 
 - The pairing token (`X-Cos-Token`) is the only credential. Rotating it
   invalidates every display-stream ticket; there is no server-side ticket store.
+- Pairing codes (6.67.0, `docs/pairing-contract.md`) are not credentials. A code
+  lives 5 minutes in memory, works once, is made only over loopback with the token,
+  and releases the pairing token only after someone presses Allow on the Mac, and
+  then only once, to the address that claimed it. Claims are accepted over Tailscale
+  (100.64.0.0/10), or a private Wi-Fi address only while the user has allowed it for
+  10 minutes. Limits: 5 claims a minute per connection address, 20 tries per code.
+  Codes, nonces, tokens and QR text are never logged. The pairing token is still the
+  only standing credential.
+- A device on your tailnet can lock a live pairing code by guessing at it 20 times.
+  This is accepted: COS Control says why and offers a new code, and a code already
+  claimed is never locked by later guesses.
+- While "Allow pairing on this Wi-Fi" is on, the pairing token reaches the phone over
+  plain HTTP on that Wi-Fi, as the pasted token always has. Use it only at home; it
+  turns itself off after 10 minutes. Over Tailscale the traffic is encrypted.
+- Behind `tailscale serve` or `funnel`, requests arrive from a loopback proxy, so
+  every claim is refused (`not_allowed_network`): pairing fails closed there.
 - `GET /api/display-stream` is public by design and returns lifecycle events
   only. Content requires a ticket or the token header. See
   `server/routes/display.ts` for the allowlist.

package/docs/pairing-contract.md

@@ -0,0 +1,118 @@
+<!-- Copy of operations/personal/wk41_2026/CONTRACT_glasses_pairing_2026-10-09.md in the COS repo, the single source of truth for server 6.67.0, glasses 6.10.621 and the Control pairing branch. Server notes on what the contract left open are at the end. -->
+
+# Contract: glasses pairing (server 6.67.0, glasses 6.10.621, Control branch for Codex)
+
+This is the single source of truth for the three builders. Design and reasons: `PLAN_glasses_onboarding_quick_connect_2026-10-08.md`, sections v2 and v4.
+
+**Miles, 2026-10-09 07:23:** "We'll use the next version release as the canary. We'll start with Miles network, he should see the QR with the newer Activity setup view that contains the QR code for scanning."
+
+**Scope of this release: pairing only.** Durability (Part C), approve-from-glasses (Part B) and the tour come in later releases.
+
+## Capability
+- `GET /api/health` adds `capabilities.pairing = { version: 1 }`.
+- Clients check it before any pairing call. When it is missing, the phone says "Update COS on your Mac (server 6.67 or newer)" and Control shows "Update the server".
+
+## Code and QR grammar (the server builds both, clients only parse)
+- **Code:** 8 characters, Crockford base32 (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`).
+  - Normalize input: uppercase it, map O→0, I and L→1, and strip spaces and dashes.
+  - Display it as `XXXX-XXXX`.
+- **QR text:** `COS1/MAC/<CODE>/<host>:<port>[+<host>:<port>]/<EXP>`
+  - All uppercase alphanumeric plus `/ : + .`, so the QR stays at version 3 or 4. (Changed from `,` after QA round 1: a comma is not in the QR alphanumeric set. The server writes `+`; clients accept `+` and `,`.)
+  - `<EXP>` is the expiry, in unix seconds, written in base36 uppercase.
+  - Hosts are IPv4 only, http. Tailscale (100.64.0.0/10) comes first; a LAN address (RFC1918) is included only while LAN pairing is armed.
+  - `MAC` is the kind. `CLOUD` is reserved for later. Any other kind, or a version other than `COS1`, is refused with "Update COS to use this code".
+  - Clients refuse hosts outside 100.64/10 and RFC1918.
+
+## Server routes (6.67.0)
+All under `/api/pairing`. Every response carries a `reason` string on failure. The reasons are:
+`expired`, `used`, `locked`, `rate_limited`, `not_loopback`, `not_allowed_network`, `unknown_code`, `denied`, `draining`, `bad_request`.
+
+| Route | Auth | Body or params | 200/202 response |
+|---|---|---|---|
+| `POST /pairing/code` | token **and** loopback socket (`req.socket.remoteAddress`, both forms; never `req.ip` or XFF) | `{ allowLan?: boolean }` (`allowLan` arms LAN claims for 10 minutes) | `{ code, display, qr, expiresAt, bootId, hosts:[{host,port,kind:'tailscale'|'lan'}], lanArmedUntil|null }`. A new code cancels the previous one and any pending claim. |
+| `POST /pairing/claim` | **public**, an exact `POST` match in `isPublicApiRequest`, with its own JSON parser capped at 1 KB | `{ code, nonce }` (`nonce` is 16 to 64 characters from `[A-Za-z0-9_-]`, made by the phone) | 202 `{ pending: true }`. Idempotent for the same nonce and code. |
+| `GET /pairing/claim/:nonce` | **public**, and the caller's socket IP must equal the claim's IP | | `{ state: 'pending'|'allowed'|'denied'|'expired'|'delivered', token?, serverName? }`. The token is returned **once** (the `allowed` state moves to `delivered`). A later read returns `delivered` with no token. |
+| `GET /pairing/status` | token and loopback | | `{ code: {display, expiresAt}|null, pending: {nonce, ip, at}|null, lastClaim: {ip, at, allowed}|null, firstAuthAfterClaimAt|null, lanArmedUntil|null, bootId }` |
+| `POST /pairing/decision` | token and loopback | `{ nonce, allow: boolean }` | `{ ok: true }` |
+
+### Rules
+- **Network:** a claim is accepted from 100.64/10. It is accepted from RFC1918 only while LAN is armed. Anything else gets `not_allowed_network`. This check sits on top of the existing network allowlist.
+- **Code lifetime:** 5 minutes, single use (the first successful claim moves it to `used`).
+- **Pending claims:** one at a time. A pending claim waits up to 60 s for a decision, then becomes `expired`. A second claim while one is pending is refused with `locked`, and that does not cancel the first.
+- **Limits:**
+  - 5 claim attempts per minute per socket IP, then `rate_limited`.
+  - 20 attempts per code, then the code is `locked` until a new code is made.
+  - The limiter keys on the socket IP. Trust-proxy is never enabled.
+- **State:** in memory only. A restart loses codes, so a claim with an old code gets `unknown_code`, and `bootId` changes.
+- **Drain:** the pairing routes are exempt from the mutation lease, since they write no files. When shutting down, `code`, `claim`, `status` and `decision` return 503 `draining`. The poll `GET /pairing/claim/:nonce` is still served (QA round 1), so a token already allowed reaches the phone even if the update gate closes before the next poll.
+- **First authenticated call:** when a request passes `requireApiToken` and its socket IP equals an allowed `lastClaim.ip`, stamp `firstAuthAfterClaimAt` once.
+- **Logging:** never the code, nonce, token or QR text. Log the IP, the result, and the first 2 characters of a sha256 of the code. A test must fail if any of those values appear in log output.
+- **Docs:**
+  - SECURITY.md: the pairing token is still the only standing credential; pairing codes are short-lived and single use.
+  - `docs/pairing-contract.md`: a copy of this file.
+  - Change the 401 copy to "Paste the pairing token from COS Control, or scan its code with COS Glasses 6.10.621 or newer." (QA round 1: older glasses show it word for word.) The `reason` value stays `pairing_token_rejected`.
+
+## Glasses 6.10.621
+- **Parser:** `src/lib/pair-code.ts` parses the QR grammar, normalizes codes and orders hosts. It is unit tested and exposed to the ES5 wizard as `window.__COS_PAIR`.
+- **Scan entry points:**
+  - the wizard Start screen (first option, "Scan code on your Mac")
+  - `setup-step1` (the reauth path)
+  - the Settings overlay
+  - the local starter banner's Connect Mac
+- **Ways in:**
+  - **Scan:** `window._evenBridge.captureImageFromCamera()`
+  - **Use a screenshot:** `pickImageFromAlbum()`
+  - **Type the code:** the code plus the Mac address
+  - Scan and screenshot are shown only when the bridge method is a function.
+- **Decoding:** jsQR, decoding at the native width capped at 1920, then a second pass at 1280. A miss shows "Move closer so the code fills your screen".
+- **Flow:**
+  1. Check health on the first host that answers (try hosts in order, 3 s each).
+  2. Make a nonce, then claim.
+  3. Poll `GET /pairing/claim/:nonce` every 1.5 s for up to 70 s. The screen and the lens say "Waiting for Allow on your Mac".
+  4. When the token arrives, write `cos_server_url = http://host:port` and `cos_api_token`, then run the existing `fetchAuthenticatedTarget`, then `finishConnectedSetup`, exactly as the IP form does.
+  5. Keep the token in memory and retry if `/api/models` fails.
+- **Re-pairing:** when a committed target already exists, ask "Replace <old host> with <host>?" first.
+- **Lens lines:** "Pairing with your Mac…", "Waiting for Allow on your Mac", "Paired", "Code expired: show a new one", "Mac is updating". Each fits 6 lines and the width, using only drawable glyphs. isWearing is never used.
+- **Manifest:** `camera` and `album` go in app.json **and** app-hub.json. Update `verify-timer-quarantine-build.mjs` and the `marketplace-hardening` pin. Strip URL-bearing comments from the jsQR bundle. Add a `THIRD_PARTY_NOTICES` entry.
+- **Version touchpoints:** COS_VERSION, package.json, package-lock (both fields), CHANGELOG, the index.html changelog, app.json, app-hub.json, and the Hub receipt.
+
+## Control (branch off `origin/codex/whisper-runtime` 601a944, released by Codex)
+- **New helper verbs:**
+  - `tailscale-status` runs the Tailscale bundle binary, `/Applications/Tailscale.app/Contents/MacOS/tailscale`, with **`SHLVL=1`** in the child's environment. It returns `{installed, running, selfIPv4, selfDNS, peers:[{os, dns, ipv4, online, sameUser}]}`, read from `status --json`. Use `Self.UserID` to work out `sameUser`; never use `HostName`.
+  - `tailscale-whois <ip>` returns `{node, os, user}`.
+  - `pairing-code [--allow-lan]`, `pairing-status` and `pairing-decision <nonce> allow|deny` call the server routes above over loopback with the token.
+- **Setup guide, new "Glasses" section.** It is **not counted** in Finish setup, and it replaces `GlassesGuideRow`. It has three rows:
+  1. **Tailscale on this Mac:**
+     - not installed: Get Tailscale (https://tailscale.com/download/mac)
+     - signed out: Open Tailscale
+     - running: green, with the address
+  2. **Tailscale on your iPhone:**
+     - shows a QR for `https://apps.apple.com/app/tailscale/id1470499037`
+     - copy: "Sign in with the same account as this Mac"
+     - turns green when a same-user iOS peer is online, naming it ("iphone-15-pro-max is on your tailnet")
+  3. **Connect your glasses:**
+     - Shown only when `capabilities.pairing` is present.
+     - The QR is drawn with CoreImage `CIQRCodeGenerator`, correction level Q, from the server's `qr` string, at least 220 pt. Show `display` and the first host as text, with the copy "Hold your phone so the code fills the screen".
+     - Re-mint only while the pane is visible: when the code expires or `bootId` changes, and on **Show a new code**.
+     - When `pending` appears, show the **Allow / Deny** card: "<whois node> (<user>) wants to pair". For a non-tailnet IP: "Device on Wi-Fi <ip>".
+     - It turns green on `firstAuthAfterClaimAt`, showing "Paired: <node>, <time>".
+     - "Allow pairing on this Wi-Fi (home only)" is a toggle (`--allow-lan`), off by default.
+- **Plumbing:** add new Swift files to every `Tests/run.sh` source list. Every compile goes through `Tests/compile-guard.sh`, one at a time.
+- **Reset pairing** (token rotation): **not in this release.** It ships with Part B.
+
+## Server 6.67.0: what the contract left open, as built
+
+- **Times** in JSON (`expiresAt`, `lanArmedUntil`, `at`, `firstAuthAfterClaimAt`) are ISO 8601 strings, or null. Only the QR `<EXP>` is base36 unix seconds.
+- **No host:** when the Mac has no Tailscale IPv4 and LAN is not armed, `POST /pairing/code` still mints, with `hosts: []` and `qr: null`, so Control can say why instead of drawing a QR no phone can use.
+- **Hosts:** at most 3, Tailscale first. LAN addresses come only from RFC1918 on interfaces a phone can reach (never `utun` VPNs that are not Tailscale, `bridge`, `awdl`, `llw`, `vmnet`, `vboxnet`).
+- **allowLan:** `true` arms LAN for 10 minutes; a mint without it disarms LAN, so Control's toggle is the source of truth.
+- **Failures** are `{ reason, message }`: 400 `bad_request`, 403 `not_loopback` / `not_allowed_network` / `denied`, 404 `unknown_code`, 409 `used` / `locked`, 410 `expired`, 429 `rate_limited` (with `Retry-After`), 503 `draining`.
+- **Poll:** an unknown nonce (for example after a restart) is 404 `unknown_code`; a poll from a different socket IP is 403 `not_allowed_network` and does not spend the token. `serverName` comes with the token and with `delivered`. Only a real GET may read the token: a HEAD (which needs the token header to get past the gate at all) is answered 405.
+- **Status:** `code` is present while the current code is unexpired and carries an extra `state: 'active'|'used'|'locked'`.
+- **Decision** on a nonce that is not pending: 404 `unknown_code`, 410 `expired`, or 409 `used` (already decided).
+- **Per-code limit:** every claim attempt while a code is active counts against it, right code or wrong; the 21st attempt locks it. Once a code is `used`, later attempts neither count nor lock it: the right code answers `locked` while its claim waits for Allow and `used` after, a wrong one `unknown_code`. Codes are compared in constant time.
+- **firstAuthAfterClaimAt** is stamped only after the allowed claim's token was delivered, on the first token-authenticated request from that claim's IP. A new Allow clears it.
+- **Draining** means the server is shutting down or the maintenance gate is closed (an update in progress, including the startup gate before Control releases it). The poll is never refused for draining.
+- **Loopback** accepts any 127.0.0.0/8, `::1` and `::ffff:127.x` socket at the pairing check, but the server's global network allowlist (unchanged) admits only `127.0.0.1` and `::1` exactly, so another 127.x address is refused before pairing sees it.
+- **QR alphabet:** hosts are joined with `+`, which is in the QR alphanumeric set (`0-9 A-Z space $ % * + - . / :`), so every QR the server writes can be encoded in alphanumeric mode.
+- **Parity fixture:** `docs/pairing-fixture.json` holds the alphabet, nonce pattern, QR pattern and charset, normalization cases, two real `buildPairingQr` outputs (one and two hosts), the reason list with statuses and messages, the poll states and the limits. `server/lib/glasses-pairing.test.ts` recomputes every value, so it fails if the fixture drifts. Clients copy it; nobody edits it by hand.

package/docs/pairing-fixture.json

@@ -0,0 +1,94 @@
+{
+  "$comment": "Server-generated parity fixture for glasses pairing (docs/pairing-contract.md). server/lib/glasses-pairing.test.ts fails if any value here stops matching what the server produces. Clients copy it; never hand-edit it.",
+  "protocolVersion": 1,
+  "capability": {
+    "pairing": {
+      "version": 1
+    }
+  },
+  "alphabet": "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+  "codeLength": 8,
+  "noncePattern": "^[A-Za-z0-9_-]{16,64}$",
+  "qrHostSeparator": "+",
+  "qrPattern": "^COS1\\/MAC\\/[0-9A-HJKMNP-TV-Z]{8}\\/(?:\\d{1,3}(?:\\.\\d{1,3}){3}:\\d{1,5})(?:\\+\\d{1,3}(?:\\.\\d{1,3}){3}:\\d{1,5})*\\/[0-9A-Z]+$",
+  "qrCharset": "^[0-9A-Z/:+.]+$",
+  "normalize": {
+    "abcd-efgh": "ABCDEFGH",
+    " oOil LI10 ": "00111110",
+    "7k3m 9pqr": "7K3M9PQR",
+    "ABCD-EFGU": null,
+    "ABCD-EFG": null
+  },
+  "examples": [
+    {
+      "code": "7K3M9PQR",
+      "display": "7K3M-9PQR",
+      "expiresAtMs": 1791547500000,
+      "hosts": [
+        {
+          "host": "100.100.10.20",
+          "port": 3141,
+          "kind": "tailscale"
+        }
+      ],
+      "qr": "COS1/MAC/7K3M9PQR/100.100.10.20:3141/TMN2WC"
+    },
+    {
+      "code": "7K3M9PQR",
+      "display": "7K3M-9PQR",
+      "expiresAtMs": 1791547500000,
+      "hosts": [
+        {
+          "host": "100.100.10.20",
+          "port": 3141,
+          "kind": "tailscale"
+        },
+        {
+          "host": "192.168.1.20",
+          "port": 3141,
+          "kind": "lan"
+        }
+      ],
+      "qr": "COS1/MAC/7K3M9PQR/100.100.10.20:3141+192.168.1.20:3141/TMN2WC"
+    }
+  ],
+  "reasons": {
+    "bad_request": 400,
+    "not_loopback": 403,
+    "not_allowed_network": 403,
+    "denied": 403,
+    "unknown_code": 404,
+    "used": 409,
+    "locked": 409,
+    "expired": 410,
+    "rate_limited": 429,
+    "draining": 503
+  },
+  "reasonMessages": {
+    "bad_request": "That pairing request was not understood. Scan the code again.",
+    "not_loopback": "Pairing codes are made only by COS Control on this Mac.",
+    "not_allowed_network": "Connect over Tailscale, or turn on \"Allow pairing on this Wi-Fi\" in COS Control.",
+    "denied": "Pairing was denied on the Mac.",
+    "unknown_code": "This code is not current. Show a new one in COS Control.",
+    "used": "This code was already used. Show a new one in COS Control.",
+    "locked": "Too many tries, or another device is waiting. Show a new code in COS Control.",
+    "expired": "Code expired: show a new one in COS Control.",
+    "rate_limited": "Too many tries. Wait a minute and try again.",
+    "draining": "Your Mac is updating. Try again in a minute."
+  },
+  "pollStates": [
+    "pending",
+    "allowed",
+    "denied",
+    "expired",
+    "delivered"
+  ],
+  "limits": {
+    "codeTtlMs": 300000,
+    "pendingTtlMs": 60000,
+    "lanArmMs": 600000,
+    "claimsPerIpPerMinute": 5,
+    "attemptsPerCode": 20,
+    "maxQrHosts": 3
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.66.0",
+  "version": "6.67.0",
   "description": "COS Glasses: self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {
@@ -47,6 +47,7 @@
     "!server/scripts/work-intake-mutation-gate.mjs",
     "!server/scripts/work-progress-mutation-gate.mjs",
     "!server/scripts/work-search-mutation-gate.mjs",
+    "!server/scripts/pairing-mutation-gate.mjs",
     "!server/scripts/away-hold-mutation-gate.mjs",
     "!server/scripts/nemotron-mutation-gate.mjs",
     "!server/scripts/merged-scribe-mutation-gate.mjs",
@@ -78,6 +79,8 @@
     "!server/scripts/build-work-task-runtime.py",
     "bin/hooks/cos-cursor-observer.cjs",
     "docs/provider-parity.md",
+    "docs/pairing-contract.md",
+    "docs/pairing-fixture.json",
     "bin/whisper-runtime.cjs",
     "bin/whisper-runtime.d.cts"
   ],

package/server/index.ts

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { createServer as createHttpsServer } from 'node:https'
 import { createServer as createHttpServer } from 'node:http'
 import { readFileSync, existsSync } from 'node:fs'
-import { networkInterfaces, homedir } from 'node:os'
+import { networkInterfaces, homedir, hostname } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
 import { randomBytes, randomUUID } from 'node:crypto'
@@ -162,9 +162,12 @@ import {
 import {
   isAllowedNetworkIp,
   isAllowedNetworkOrigin,
-  isTailscaleIpv4,
+  isLoopbackSocket,
+  reachableIpv4Addresses,
 } from './lib/network-policy.js'
 import { requireApiToken } from './lib/api-auth.js'
+import { PairingState, pairingHostsFrom } from './lib/glasses-pairing.js'
+import { createPairingRouter } from './routes/pairing.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
 import { reportClaudeExtraToolConfiguration } from './lib/claude-tool-access.js'
 import {
@@ -317,7 +320,27 @@ if (threadAttachEnabled()) {
 // authenticated /tts/prepare for native audio players) and
 // /display-stream/<exp>.<hmac> GET/HEAD (minted on authenticated /api/models for
 // EventSource, which cannot set X-Cos-Token either). See api-auth.ts.
-app.use('/api', requireApiToken(API_TOKEN))
+// 6.67.0 glasses pairing state: in memory only, so a restart loses every code and
+// claim and `bootId` changes (docs/pairing-contract.md).
+const pairingState = new PairingState({
+  token: () => API_TOKEN,
+  // The Mac's name as the phone shows it ("Paired with <name>").
+  serverName: () => hostname().replace(/\.local$/i, ''),
+  hosts: lanArmed => pairingHostsFrom(reachableIpv4Addresses(networkInterfaces()), PORT, lanArmed),
+})
+app.use('/api', requireApiToken(API_TOKEN, {
+  onAuthenticated: req => pairingState.noteAuthenticated(req.socket?.remoteAddress),
+}))
+
+// Pairing routes sit HERE on purpose: after the token gate (mint, status and decision
+// need it; the claim and its poll are exact public doors in api-auth.ts), and BEFORE the
+// mutation-lease catch-all and the global 10 MB parser. They write no files, so they
+// never hold the lease, and each parses its own body at 1 KB. During a drain or
+// shutdown they answer 503 `draining`.
+app.use('/api', createPairingRouter({
+  state: () => pairingState,
+  isDraining: () => gracefulShutdownStarted || !maintenanceAdmissionsOpen(),
+}))
 
 // Fail-closed catch-all for mutation routes that do not own a more specific
 // lifecycle lease below. This closes the admission/drain race for secondary
@@ -375,9 +398,7 @@ app.use('/api', (req, res, next) => {
   // still closed. Permit only its two bounded loopback proofs, and only with
   // the controller-held operation receipt. Normal phone/LAN admissions stay
   // closed throughout the update.
-  const address = req.socket.remoteAddress ?? ''
-  const loopback = address === '::1' || address === '127.0.0.1'
-    || address.startsWith('127.') || address.startsWith('::ffff:127.')
+  const loopback = isLoopbackSocket(req)
   const controllerProofPath = req.path === '/diagnostics/provider-proof'
     || req.path === '/tts/prepare'
   const controllerProof = loopback && controllerProofPath
@@ -1225,17 +1246,11 @@ listenRequiredServers(listeners).then(() => {
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
   // not paste-able — enumerate real interfaces and label the Tailscale one.
   try {
-    const nets = networkInterfaces()
-    const addrs: Array<{ ip: string; label: string }> = []
-    for (const [name, infos] of Object.entries(nets)) {
-      for (const info of infos ?? []) {
-        if (info.family !== 'IPv4' || info.internal) continue
-        const isTailscale = isTailscaleIpv4(info.address) || name.startsWith('tailscale')
-        addrs.push({ ip: info.address, label: isTailscale ? 'Tailscale — works from anywhere' : `${name} — same Wi-Fi only` })
-      }
-    }
+    const addrs = reachableIpv4Addresses(networkInterfaces()).map(entry => ({
+      ip: entry.address,
+      label: entry.kind === 'tailscale' ? 'Tailscale — works from anywhere' : `${entry.name} — same Wi-Fi only`,
+    }))
     if (addrs.length > 0) {
-      addrs.sort((a, b) => Number(b.label.startsWith('Tailscale')) - Number(a.label.startsWith('Tailscale')))
       console.log('')
       console.log('[COS API] Server URL for the COS Glasses app:')
       for (const a of addrs) console.log(`[COS API]   http://${a.ip}:${PORT}   (${a.label})`)

package/server/lib/api-auth.ts

@@ -1,5 +1,6 @@
 import type { RequestHandler } from 'express'
 import { timingSafeTokenEqual } from './token-auth.js'
+import { PAIRING_NONCE_BODY } from './glasses-pairing.js'
 
 // Recovery/setup clients need these availability surfaces before they have a
 // usable token. Keep private provider state and every mutation route out.
@@ -34,24 +35,48 @@ const TTS_PLAYBACK_CAPABILITY_PATH = /^\/tts\/play\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-
 // callers that can send one; the ticket exists only for the ones that cannot.
 const DISPLAY_STREAM_CAPABILITY_PATH = /^\/display-stream\/\d{1,15}\.[0-9a-f]{64}$/
 
+// 6.67.0 glasses pairing (docs/pairing-contract.md). Exactly two public doors, each
+// matched on METHOD and path, never through the method-agnostic set above:
+// - POST /pairing/claim: a phone with no token yet presents the short-lived code.
+// - GET /pairing/claim/<nonce>: the same phone polls for the decision. The route binds
+//   the poll to the claim's socket IP, and the token is released only after Allow.
+// Minting, status and decisions stay behind the token AND a loopback socket.
+const PAIRING_POLL_PATH = new RegExp(`^/pairing/claim/${PAIRING_NONCE_BODY}$`)
+
 export function isPublicApiRequest(method: string, path: string): boolean {
   if (PUBLIC_API_PATHS.has(path)) return true
+  if (method === 'POST' && path === '/pairing/claim') return true
+  if (method === 'GET' && PAIRING_POLL_PATH.test(path)) return true
   if (method !== 'GET' && method !== 'HEAD') return false
   return TTS_PLAYBACK_CAPABILITY_PATH.test(path)
     || DISPLAY_STREAM_CAPABILITY_PATH.test(path)
 }
 
+export interface RequireApiTokenOptions {
+  /**
+   * Called once per request that passed the token check (never for a public path).
+   * Pairing uses it to stamp `firstAuthAfterClaimAt`. A throw here is swallowed: an
+   * observer must never turn an authenticated request into a failure.
+   */
+  onAuthenticated?: (req: Parameters<RequestHandler>[0]) => void
+}
+
 /** Global /api authentication boundary. Mount before all body parsers. */
-export function requireApiToken(apiToken: string): RequestHandler {
+export function requireApiToken(apiToken: string, options: RequireApiTokenOptions = {}): RequestHandler {
   return (req, res, next) => {
     if (isPublicApiRequest(req.method, req.path)) return next()
     if (!timingSafeTokenEqual(req.headers['x-cos-token'], apiToken)) {
       return res.status(401).json({
         error: 'unauthorized',
+        // Stable on purpose: clients key off this value, not the message.
         reason: 'pairing_token_rejected',
-        message: 'In COS Control choose Copy Pairing Token, then paste the complete value into COS Glasses.',
+        // Older COS Glasses builds, which cannot scan, show this message word for word.
+        message: 'Paste the pairing token from COS Control, or scan its code with COS Glasses 6.10.621 or newer.',
       })
     }
+    if (options.onAuthenticated) {
+      try { options.onAuthenticated(req) } catch { /* observer only */ }
+    }
     next()
   }
 }

package/server/lib/glasses-pairing.ts

@@ -0,0 +1,444 @@
+// Glasses pairing (6.67.0). Contract: docs/pairing-contract.md.
+//
+// COS Control mints a short-lived, single-use code over loopback and shows it as a QR.
+// The phone claims it over Tailscale (or the home Wi-Fi while that is armed), the Mac
+// user presses Allow, and only then does the phone's poll receive the pairing token,
+// exactly once. Everything here is in memory: a restart loses every code and claim,
+// and `bootId` changes so Control knows to show a new code.
+//
+// This module is pure. The clock, the random source, the token, the host list and
+// the server name are injected so every rule in the contract is testable.
+
+import { createHash, randomInt as cryptoRandomInt, randomUUID, timingSafeEqual } from 'node:crypto'
+import { isRfc1918Ipv4, isTailscaleIpv4, normalizeRemoteIp } from './network-policy.js'
+
+export const PAIRING_PROTOCOL_VERSION = 1
+export const CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+export const PAIRING_CODE_LENGTH = 8
+export const PAIRING_CODE_TTL_MS = 5 * 60_000
+export const PAIRING_PENDING_TTL_MS = 60_000
+export const PAIRING_LAN_ARM_MS = 10 * 60_000
+export const PAIRING_IP_LIMIT_PER_MINUTE = 5
+export const PAIRING_IP_WINDOW_MS = 60_000
+export const PAIRING_CODE_ATTEMPT_LIMIT = 20
+/** Decided claims stay pollable this long, so a slow phone still sees `denied`. */
+export const PAIRING_CLAIM_RETENTION_MS = 10 * 60_000
+/** At most this many hosts in a QR, Tailscale first, so the QR stays small. */
+export const PAIRING_MAX_QR_HOSTS = 3
+/** The nonce body, unanchored. The single source for the route check and the public door in api-auth.ts. */
+export const PAIRING_NONCE_BODY = '[A-Za-z0-9_-]{16,64}'
+export const PAIRING_NONCE_PATTERN = new RegExp(`^${PAIRING_NONCE_BODY}$`)
+/**
+ * Between hosts in the QR. `+` is in the QR alphanumeric set (`0-9 A-Z space $ % * + - . / :`);
+ * a comma is not, and would push a two-host code into byte mode. Clients accept `+` and `,`.
+ */
+export const PAIRING_QR_HOST_SEPARATOR = '+'
+/** The QR grammar. Clients parse it; the server is the only writer. */
+export const PAIRING_QR_PATTERN = /^COS1\/MAC\/[0-9A-HJKMNP-TV-Z]{8}\/(?:\d{1,3}(?:\.\d{1,3}){3}:\d{1,5})(?:\+\d{1,3}(?:\.\d{1,3}){3}:\d{1,5})*\/[0-9A-Z]+$/
+/** Every character the server ever writes into a QR: QR alphanumeric mode, so the code stays small. */
+export const PAIRING_QR_CHARSET = /^[0-9A-Z/:+.]+$/
+
+export type PairingReason =
+  | 'expired'
+  | 'used'
+  | 'locked'
+  | 'rate_limited'
+  | 'not_loopback'
+  | 'not_allowed_network'
+  | 'unknown_code'
+  | 'denied'
+  | 'draining'
+  | 'bad_request'
+
+export const PAIRING_REASON_STATUS: Record<PairingReason, number> = {
+  bad_request: 400,
+  not_loopback: 403,
+  not_allowed_network: 403,
+  denied: 403,
+  unknown_code: 404,
+  used: 409,
+  locked: 409,
+  expired: 410,
+  rate_limited: 429,
+  draining: 503,
+}
+
+export const PAIRING_REASON_MESSAGE: Record<PairingReason, string> = {
+  bad_request: 'That pairing request was not understood. Scan the code again.',
+  not_loopback: 'Pairing codes are made only by COS Control on this Mac.',
+  not_allowed_network: 'Connect over Tailscale, or turn on "Allow pairing on this Wi-Fi" in COS Control.',
+  denied: 'Pairing was denied on the Mac.',
+  unknown_code: 'This code is not current. Show a new one in COS Control.',
+  used: 'This code was already used. Show a new one in COS Control.',
+  locked: 'Too many tries, or another device is waiting. Show a new code in COS Control.',
+  expired: 'Code expired: show a new one in COS Control.',
+  rate_limited: 'Too many tries. Wait a minute and try again.',
+  draining: 'Your Mac is updating. Try again in a minute.',
+}
+
+export type PairingHostKind = 'tailscale' | 'lan'
+export interface PairingHost {
+  host: string
+  port: number
+  kind: PairingHostKind
+}
+
+export type ClaimState = 'pending' | 'allowed' | 'denied' | 'expired' | 'delivered'
+
+export class PairingError extends Error {
+  readonly reason: PairingReason
+  readonly status: number
+  readonly retryAfterSeconds?: number
+  constructor(reason: PairingReason, retryAfterSeconds?: number) {
+    super(reason)
+    this.reason = reason
+    this.status = PAIRING_REASON_STATUS[reason]
+    this.retryAfterSeconds = retryAfterSeconds
+  }
+}
+
+// ── Code and QR grammar ─────────────────────────────────────────────────────
+
+export function generatePairingCode(randomInt: (max: number) => number = max => cryptoRandomInt(max)): string {
+  let code = ''
+  for (let i = 0; i < PAIRING_CODE_LENGTH; i++) code += CROCKFORD_ALPHABET[randomInt(CROCKFORD_ALPHABET.length)]
+  return code
+}
+
+/** Uppercase, O→0, I/L→1, strip spaces and dashes. Null unless 8 Crockford characters remain. */
+export function normalizePairingCode(input: unknown): string | null {
+  if (typeof input !== 'string' || input.length > 32) return null
+  const code = input.toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1')
+  if (code.length !== PAIRING_CODE_LENGTH) return null
+  for (const ch of code) if (!CROCKFORD_ALPHABET.includes(ch)) return null
+  return code
+}
+
+export function displayPairingCode(code: string): string {
+  return `${code.slice(0, 4)}-${code.slice(4)}`
+}
+
+/** `COS1/MAC/<CODE>/<host>:<port>[+<host>:<port>]/<EXP>`, EXP = unix seconds in base36 uppercase. */
+export function buildPairingQr(code: string, hosts: readonly PairingHost[], expiresAtMs: number): string {
+  const hostList = hosts.map(h => `${h.host}:${h.port}`).join(PAIRING_QR_HOST_SEPARATOR)
+  const exp = Math.floor(expiresAtMs / 1000).toString(36).toUpperCase()
+  return `COS1/MAC/${code}/${hostList}/${exp}`
+}
+
+/** Constant-time compare of two normalized codes. */
+export function pairingCodesEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a, 'utf8')
+  const right = Buffer.from(b, 'utf8')
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+/** First 2 hex characters of sha256(code): the only form of a code that is ever logged. */
+export function pairingCodeTag(code: string): string {
+  return createHash('sha256').update(code).digest('hex').slice(0, 2)
+}
+
+/**
+ * Pairing hosts from the reachable-address list: Tailscale IPv4 first, then RFC1918
+ * only while LAN is armed. Never IPv6 or MagicDNS. Deduplicated, capped for QR size.
+ */
+export function pairingHostsFrom(
+  addresses: ReadonlyArray<{ address: string; kind: 'tailscale' | 'lan' | 'other' }>,
+  port: number,
+  lanArmed: boolean,
+): PairingHost[] {
+  const seen = new Set<string>()
+  const tailscale: PairingHost[] = []
+  const lan: PairingHost[] = []
+  for (const entry of addresses) {
+    if (seen.has(entry.address)) continue
+    if (isTailscaleIpv4(entry.address)) {
+      seen.add(entry.address)
+      tailscale.push({ host: entry.address, port, kind: 'tailscale' })
+    } else if (lanArmed && entry.kind === 'lan' && isRfc1918Ipv4(entry.address)) {
+      seen.add(entry.address)
+      lan.push({ host: entry.address, port, kind: 'lan' })
+    }
+  }
+  return [...tailscale, ...lan].slice(0, PAIRING_MAX_QR_HOSTS)
+}
+
+// ── State machine ───────────────────────────────────────────────────────────
+
+interface CodeRecord {
+  code: string
+  expiresAt: number
+  attempts: number
+  status: 'active' | 'used' | 'locked'
+}
+
+interface ClaimRecord {
+  nonce: string
+  code: string
+  ip: string
+  at: number
+  state: ClaimState
+  decidedAt: number | null
+  deliveredAt: number | null
+}
+
+export interface PairingStateOptions {
+  now?: () => number
+  randomInt?: (max: number) => number
+  bootId?: string
+  /** The standing pairing token, read at delivery time so a rotation is honoured. */
+  token: () => string
+  serverName: () => string
+  /** Hosts for the QR, given whether LAN is armed right now. */
+  hosts: (lanArmed: boolean) => PairingHost[]
+  log?: (line: string) => void
+}
+
+export interface MintResult {
+  code: string
+  display: string
+  qr: string | null
+  expiresAt: string
+  bootId: string
+  hosts: PairingHost[]
+  lanArmedUntil: string | null
+}
+
+export interface PollResult {
+  state: ClaimState
+  token?: string
+  serverName?: string
+}
+
+export interface PairingStatus {
+  code: { display: string; expiresAt: string; state: CodeRecord['status'] } | null
+  pending: { nonce: string; ip: string; at: string } | null
+  lastClaim: { ip: string; at: string; allowed: boolean } | null
+  firstAuthAfterClaimAt: string | null
+  lanArmedUntil: string | null
+  bootId: string
+}
+
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export class PairingState {
+  readonly bootId: string
+  private readonly now: () => number
+  private readonly randomInt?: (max: number) => number
+  private readonly opts: PairingStateOptions
+  private readonly log: (line: string) => void
+  private current: CodeRecord | null = null
+  private pendingNonce: string | null = null
+  private readonly claims = new Map<string, ClaimRecord>()
+  private lastClaimNonce: string | null = null
+  private firstAuthAfterClaimAt: number | null = null
+  private lanArmedUntil: number | null = null
+  private readonly ipAttempts = new Map<string, number[]>()
+
+  constructor(opts: PairingStateOptions) {
+    this.opts = opts
+    this.now = opts.now ?? (() => Date.now())
+    this.randomInt = opts.randomInt
+    this.bootId = opts.bootId ?? randomUUID()
+    this.log = opts.log ?? (line => console.log(line))
+  }
+
+  private lanArmed(at: number): boolean {
+    return this.lanArmedUntil != null && at < this.lanArmedUntil
+  }
+
+  /** Lazy timers: a pending claim older than 60 s expires; old decided claims are dropped. */
+  private sweep(at: number): void {
+    if (this.pendingNonce) {
+      const pending = this.claims.get(this.pendingNonce)
+      if (!pending || pending.state !== 'pending') {
+        this.pendingNonce = null
+      } else if (at - pending.at >= PAIRING_PENDING_TTL_MS) {
+        pending.state = 'expired'
+        pending.decidedAt = at
+        this.pendingNonce = null
+        this.log(`[pairing] claim expired ip=${pending.ip} code#=${pairingCodeTag(pending.code)}`)
+      }
+    }
+    for (const [nonce, claim] of this.claims) {
+      if (claim.state !== 'pending' && at - claim.at > PAIRING_CLAIM_RETENTION_MS && nonce !== this.lastClaimNonce) {
+        this.claims.delete(nonce)
+      }
+    }
+    if (this.lanArmedUntil != null && at >= this.lanArmedUntil) this.lanArmedUntil = null
+  }
+
+  /** POST /pairing/code. A new code cancels the previous code and any pending claim. */
+  mint(input: { allowLan?: boolean } = {}): MintResult {
+    const at = this.now()
+    this.sweep(at)
+    if (this.pendingNonce) {
+      const pending = this.claims.get(this.pendingNonce)
+      if (pending && pending.state === 'pending') {
+        pending.state = 'expired'
+        pending.decidedAt = at
+      }
+      this.pendingNonce = null
+    }
+    this.lanArmedUntil = input.allowLan === true ? at + PAIRING_LAN_ARM_MS : null
+    const code = generatePairingCode(this.randomInt)
+    const expiresAt = at + PAIRING_CODE_TTL_MS
+    this.current = { code, expiresAt, attempts: 0, status: 'active' }
+    const hosts = this.opts.hosts(this.lanArmed(at))
+    const qr = hosts.length > 0 ? buildPairingQr(code, hosts, expiresAt) : null
+    this.log(`[pairing] code minted hosts=${hosts.map(h => h.host).join(',') || 'none'} lan=${this.lanArmedUntil ? 'armed' : 'off'} code#=${pairingCodeTag(code)}`)
+    return {
+      code,
+      display: displayPairingCode(code),
+      qr,
+      expiresAt: iso(expiresAt),
+      bootId: this.bootId,
+      hosts,
+      lanArmedUntil: this.lanArmedUntil != null ? iso(this.lanArmedUntil) : null,
+    }
+  }
+
+  /** Throws PairingError unless `ip` may claim at all (network, then per-IP limit). */
+  private admitClaimer(ip: string, at: number): void {
+    if (!isTailscaleIpv4(ip) && !(isRfc1918Ipv4(ip) && this.lanArmed(at))) {
+      throw new PairingError('not_allowed_network')
+    }
+    const recent = (this.ipAttempts.get(ip) ?? []).filter(t => at - t < PAIRING_IP_WINDOW_MS)
+    if (recent.length >= PAIRING_IP_LIMIT_PER_MINUTE) {
+      this.ipAttempts.set(ip, recent)
+      const retry = Math.max(1, Math.ceil((PAIRING_IP_WINDOW_MS - (at - recent[0])) / 1000))
+      throw new PairingError('rate_limited', retry)
+    }
+    recent.push(at)
+    this.ipAttempts.set(ip, recent)
+    if (this.ipAttempts.size > 1000) {
+      for (const [key, times] of this.ipAttempts) {
+        if (times.every(t => at - t >= PAIRING_IP_WINDOW_MS)) this.ipAttempts.delete(key)
+      }
+    }
+  }
+
+  /** POST /pairing/claim. Returns normally for 202 `{ pending: true }`; throws PairingError otherwise. */
+  claim(input: { code: unknown; nonce: unknown }, socketIp: string): void {
+    const at = this.now()
+    this.sweep(at)
+    const ip = normalizeRemoteIp(socketIp)
+    this.admitClaimer(ip, at)
+    const nonce = typeof input.nonce === 'string' && PAIRING_NONCE_PATTERN.test(input.nonce) ? input.nonce : null
+    const code = normalizePairingCode(input.code)
+    if (!nonce || !code) {
+      this.log(`[pairing] claim ip=${ip} result=bad_request`)
+      throw new PairingError('bad_request')
+    }
+    const tag = pairingCodeTag(code)
+    const refuse = (reason: PairingReason): never => {
+      this.log(`[pairing] claim ip=${ip} result=${reason} code#=${tag}`)
+      throw new PairingError(reason)
+    }
+
+    // Idempotent for the same nonce and code from the same socket IP.
+    const existing = this.claims.get(nonce)
+    if (existing) {
+      if (!pairingCodesEqual(existing.code, code) || existing.ip !== ip) refuse('locked')
+      if (existing.state === 'pending') return
+      if (existing.state === 'denied') refuse('denied')
+      if (existing.state === 'expired') refuse('expired')
+      // allowed or delivered: the claim already succeeded; the poll carries the token.
+      return
+    }
+
+    const current = this.current
+    if (!current) refuse('unknown_code')
+    const record = current as CodeRecord
+    const matches = pairingCodesEqual(record.code, code)
+    if (at >= record.expiresAt) refuse(matches ? 'expired' : 'unknown_code')
+    if (record.status === 'locked') refuse('locked')
+    // A used code has nothing left to guess: further attempts neither count nor lock it,
+    // so a tailnet peer cannot turn "used" into "locked" under the claim that won.
+    if (record.status === 'used') {
+      if (!matches) refuse('unknown_code')
+      refuse(this.pendingNonce ? 'locked' : 'used')
+    }
+    // Every attempt while a code is live counts against it, right or wrong.
+    record.attempts++
+    if (record.attempts > PAIRING_CODE_ATTEMPT_LIMIT) {
+      record.status = 'locked'
+      refuse('locked')
+    }
+    if (!matches) refuse('unknown_code')
+
+    record.status = 'used'
+    this.claims.set(nonce, { nonce, code, ip, at, state: 'pending', decidedAt: null, deliveredAt: null })
+    this.pendingNonce = nonce
+    this.lastClaimNonce = nonce
+    this.log(`[pairing] claim ip=${ip} result=pending code#=${tag}`)
+  }
+
+  /** GET /pairing/claim/:nonce. The token is returned once; `allowed` then reads `delivered`. */
+  poll(nonce: string, socketIp: string): PollResult {
+    const at = this.now()
+    this.sweep(at)
+    const ip = normalizeRemoteIp(socketIp)
+    const claim = this.claims.get(nonce)
+    if (!claim) throw new PairingError('unknown_code')
+    if (claim.ip !== ip) {
+      this.log(`[pairing] poll ip=${ip} result=not_allowed_network code#=${pairingCodeTag(claim.code)}`)
+      throw new PairingError('not_allowed_network')
+    }
+    if (claim.state === 'allowed') {
+      claim.state = 'delivered'
+      claim.deliveredAt = at
+      this.log(`[pairing] token delivered ip=${ip} code#=${pairingCodeTag(claim.code)}`)
+      return { state: 'allowed', token: this.opts.token(), serverName: this.opts.serverName() }
+    }
+    if (claim.state === 'delivered') return { state: 'delivered', serverName: this.opts.serverName() }
+    return { state: claim.state }
+  }
+
+  /** POST /pairing/decision. */
+  decide(nonce: unknown, allow: unknown): void {
+    const at = this.now()
+    this.sweep(at)
+    if (typeof nonce !== 'string' || typeof allow !== 'boolean') throw new PairingError('bad_request')
+    const claim = this.claims.get(nonce)
+    if (!claim) throw new PairingError('unknown_code')
+    if (claim.state === 'expired') throw new PairingError('expired')
+    if (claim.state !== 'pending') throw new PairingError('used')
+    claim.state = allow ? 'allowed' : 'denied'
+    claim.decidedAt = at
+    this.pendingNonce = null
+    this.lastClaimNonce = nonce
+    if (allow) this.firstAuthAfterClaimAt = null
+    this.log(`[pairing] decision ip=${claim.ip} result=${allow ? 'allowed' : 'denied'} code#=${pairingCodeTag(claim.code)}`)
+  }
+
+  /**
+   * Called after a request passes requireApiToken. Stamps `firstAuthAfterClaimAt` once,
+   * for the first authenticated request from the allowed claim's IP after its token
+   * was delivered, so another phone's traffic can never turn Control green.
+   */
+  noteAuthenticated(socketIp: string | undefined): void {
+    if (this.firstAuthAfterClaimAt != null || !this.lastClaimNonce) return
+    const claim = this.claims.get(this.lastClaimNonce)
+    if (!claim || claim.state !== 'delivered') return
+    if (normalizeRemoteIp(socketIp ?? '') !== claim.ip) return
+    this.firstAuthAfterClaimAt = this.now()
+    this.log(`[pairing] first authenticated request ip=${claim.ip}`)
+  }
+
+  /** GET /pairing/status. */
+  status(): PairingStatus {
+    const at = this.now()
+    this.sweep(at)
+    const current = this.current && at < this.current.expiresAt ? this.current : null
+    const pending = this.pendingNonce ? this.claims.get(this.pendingNonce) ?? null : null
+    const last = this.lastClaimNonce ? this.claims.get(this.lastClaimNonce) ?? null : null
+    return {
+      code: current ? { display: displayPairingCode(current.code), expiresAt: iso(current.expiresAt), state: current.status } : null,
+      pending: pending ? { nonce: pending.nonce, ip: pending.ip, at: iso(pending.at) } : null,
+      lastClaim: last ? { ip: last.ip, at: iso(last.at), allowed: last.state === 'allowed' || last.state === 'delivered' } : null,
+      firstAuthAfterClaimAt: this.firstAuthAfterClaimAt != null ? iso(this.firstAuthAfterClaimAt) : null,
+      lanArmedUntil: this.lanArmedUntil != null ? iso(this.lanArmedUntil) : null,
+      bootId: this.bootId,
+    }
+  }
+}

package/server/lib/network-policy.ts

@@ -40,3 +40,67 @@ export function isAllowedNetworkOrigin(origin: string): boolean {
     return false
   }
 }
+
+/** True for RFC1918 private IPv4 (10/8, 172.16/12, 192.168/16). */
+export function isRfc1918Ipv4(value: string): boolean {
+  const octets = parseIpv4(normalizeRemoteIp(value))
+  if (!octets) return false
+  return octets[0] === 10 ||
+    (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) ||
+    (octets[0] === 192 && octets[1] === 168)
+}
+
+/** Loopback in every form a Node socket reports it: 127.0.0.0/8, ::1, ::ffff:127.x. */
+export function isLoopbackAddress(value: string | undefined | null): boolean {
+  const address = value ?? ''
+  return address === '::1' || address === '127.0.0.1'
+    || address.startsWith('127.') || address.startsWith('::ffff:127.')
+}
+
+/**
+ * Loopback check on the SOCKET, never `req.ip` or `X-Forwarded-For`. The server never
+ * enables trust-proxy, but reading the socket keeps this true even if someone does.
+ */
+export function isLoopbackSocket(req: { socket?: { remoteAddress?: string | undefined } | null }): boolean {
+  return isLoopbackAddress(req.socket?.remoteAddress)
+}
+
+export type ReachableIpv4Kind = 'tailscale' | 'lan' | 'other'
+export interface ReachableIpv4 {
+  name: string
+  address: string
+  kind: ReachableIpv4Kind
+}
+type InterfaceInfo = { address: string; family: string | number; internal: boolean }
+
+// Interfaces a phone can never reach: macOS VPN tunnels that are not Tailscale's
+// address, Internet Sharing / VM bridges, AirDrop (awdl) and low-latency WLAN (llw),
+// and VM host-only networks.
+const UNREACHABLE_INTERFACE = /^(utun|bridge|awdl|llw|vmnet|vboxnet)/
+
+/**
+ * Every external IPv4 address on this machine, Tailscale first. `kind` is
+ * `tailscale` for 100.64/10 (or a Linux `tailscale*` interface), `lan` for RFC1918 on
+ * an interface a phone can reach, `other` for the rest. Shared by the startup print
+ * and the pairing host list.
+ */
+export function reachableIpv4Addresses(
+  nets: Record<string, InterfaceInfo[] | undefined>,
+): ReachableIpv4[] {
+  const out: ReachableIpv4[] = []
+  for (const [name, infos] of Object.entries(nets)) {
+    for (const info of infos ?? []) {
+      const family = typeof info.family === 'number' ? (info.family === 4 ? 'IPv4' : 'IPv6') : info.family
+      if (family !== 'IPv4' || info.internal) continue
+      const kind: ReachableIpv4Kind = isTailscaleIpv4(info.address) || name.startsWith('tailscale')
+        ? 'tailscale'
+        : isRfc1918Ipv4(info.address) && !UNREACHABLE_INTERFACE.test(name) ? 'lan' : 'other'
+      out.push({ name, address: info.address, kind })
+    }
+  }
+  const rank = (kind: ReachableIpv4Kind) => (kind === 'tailscale' ? 0 : kind === 'lan' ? 1 : 2)
+  return out
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => rank(a.entry.kind) - rank(b.entry.kind) || a.index - b.index)
+    .map(({ entry }) => entry)
+}

package/server/routes/health.ts

@@ -1,4 +1,5 @@
 import { DICTATION_CLEAN_MODELS } from '../lib/dictation-clean-models.js'
+import { PAIRING_PROTOCOL_VERSION } from '../lib/glasses-pairing.js'
 import { taskBridgeAvailable } from '../lib/task-bridge.js'
 import { Router } from 'express'
 import { isWorthRecovering } from '../lib/quarantine-auto-recover.js'
@@ -465,6 +466,10 @@ healthRouter.get('/health', async (_req, res) => {
     ...(voiceProvenance ? { voice_provenance: voiceProvenance } : {}),
     capabilities: {
       dictationCleanup: { models: DICTATION_CLEAN_MODELS },
+      // 6.67.0: glasses pairing (docs/pairing-contract.md). Public on purpose: the phone
+      // reads it before it holds a token, and an older server omits it, which is how
+      // the phone knows to say "Update COS on your Mac (server 6.67 or newer)".
+      pairing: { version: PAIRING_PROTOCOL_VERSION },
       // Advertised on the PUBLIC health route on purpose: a client deciding whether
       // to request a display ticket may not hold a usable token yet, and an old
       // server simply omits this key, which is how a new client detects it.

package/server/routes/pairing.ts

@@ -0,0 +1,121 @@
+// Glasses pairing routes (6.67.0). Contract: docs/pairing-contract.md.
+//
+// Mounted under /api AFTER requireApiToken and BEFORE the mutation-lease catch-all and
+// the global 10 MB JSON parser:
+// - POST /pairing/claim and GET /pairing/claim/:nonce are public (exact matches in
+//   isPublicApiRequest); everything else here needs the token AND a loopback socket.
+// - The routes write no files, so they never take the mutation lease. During a drain or
+//   shutdown, minting, claiming, status and decisions answer 503 `draining`. The poll is
+//   still served: it writes nothing, and a token the user already allowed must still
+//   reach the phone if the update gate closes between Allow and the next poll.
+// - Each route parses its own body with a 1 KB cap.
+//
+// Every address decision reads `req.socket.remoteAddress`, never `req.ip` or
+// X-Forwarded-For. Codes, nonces, tokens and QR text are never logged (lib/glasses-pairing.ts
+// logs the IP, the result and a 2-character hash of the code).
+
+import express, { Router, type ErrorRequestHandler, type Request, type RequestHandler, type Response } from 'express'
+import { isLoopbackSocket } from '../lib/network-policy.js'
+import {
+  PAIRING_NONCE_PATTERN,
+  PAIRING_REASON_MESSAGE,
+  PAIRING_REASON_STATUS,
+  PairingError,
+  type PairingReason,
+  type PairingState,
+} from '../lib/glasses-pairing.js'
+
+export interface PairingRouterOptions {
+  /** Read per request so a restart created after mount is honoured in tests. */
+  state: () => PairingState
+  /** True while the server is shutting down or the maintenance gate is closed. */
+  isDraining: () => boolean
+}
+
+function sendReason(res: Response, reason: PairingReason, retryAfterSeconds?: number, status?: number): void {
+  if (retryAfterSeconds != null) res.setHeader('Retry-After', String(retryAfterSeconds))
+  res.status(status ?? PAIRING_REASON_STATUS[reason]).json({ reason, message: PAIRING_REASON_MESSAGE[reason] })
+}
+
+function sendError(res: Response, error: unknown): void {
+  if (error instanceof PairingError) return sendReason(res, error.reason, error.retryAfterSeconds)
+  console.error('[pairing] internal error:', error instanceof Error ? error.message : 'unknown')
+  res.status(500).json({ reason: 'internal', message: 'Pairing failed on the Mac. Try again.' })
+}
+
+function socketIp(req: Request): string {
+  return req.socket?.remoteAddress ?? ''
+}
+
+export function createPairingRouter(options: PairingRouterOptions): Router {
+  const router = Router()
+  const smallJson = express.json({ limit: '1kb' })
+
+  const notDraining: RequestHandler = (_req, res, next) => {
+    if (options.isDraining()) return sendReason(res, 'draining', 30)
+    next()
+  }
+  const loopbackOnly: RequestHandler = (req, res, next) => {
+    if (!isLoopbackSocket(req)) return sendReason(res, 'not_loopback')
+    next()
+  }
+  const body = (req: Request): Record<string, unknown> =>
+    req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body as Record<string, unknown> : {}
+
+  router.post('/pairing/code', notDraining, loopbackOnly, smallJson, (req, res) => {
+    const input = body(req)
+    if (input.allowLan !== undefined && typeof input.allowLan !== 'boolean') return sendReason(res, 'bad_request')
+    try {
+      res.json(options.state().mint({ allowLan: input.allowLan === true }))
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.post('/pairing/claim', notDraining, smallJson, (req, res) => {
+    const input = body(req)
+    try {
+      options.state().claim({ code: input.code, nonce: input.nonce }, socketIp(req))
+      res.status(202).json({ pending: true })
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.get('/pairing/claim/:nonce', (req, res) => {
+    // Express routes HEAD to a GET handler. Only a real GET may read (and so spend) the
+    // token; api-auth.ts already keeps HEAD behind the token, this holds it here too.
+    if (req.method !== 'GET') {
+      res.setHeader('Allow', 'GET')
+      return sendReason(res, 'bad_request', undefined, 405)
+    }
+    const nonce = req.params.nonce
+    if (typeof nonce !== 'string' || !PAIRING_NONCE_PATTERN.test(nonce)) return sendReason(res, 'bad_request')
+    try {
+      res.setHeader('Cache-Control', 'no-store')
+      res.json(options.state().poll(nonce, socketIp(req)))
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.get('/pairing/status', notDraining, loopbackOnly, (_req, res) => {
+    try {
+      res.setHeader('Cache-Control', 'no-store')
+      res.json(options.state().status())
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.post('/pairing/decision', notDraining, loopbackOnly, smallJson, (req, res) => {
+    const input = body(req)
+    try {
+      options.state().decide(input.nonce, input.allow)
+      res.json({ ok: true })
+    } catch (error) { sendError(res, error) }
+  })
+
+  // A body over 1 KB or one that is not JSON answers in the contract's shape, not
+  // Express's HTML error page. Scoped to this router's own parsers.
+  const parseError: ErrorRequestHandler = (error, req, res, next) => {
+    if (!req.path.startsWith('/pairing/')) return next(error)
+    if (res.headersSent) return next(error)
+    sendReason(res, 'bad_request')
+  }
+  router.use(parseError)
+
+  return router
+}