@localauth/cli 0.2.0 → 0.4.0

package/README.md

@@ -59,8 +59,9 @@ localauth finish                    # hand a pasted callback (read from stdin) t
 localauth list                      # this machine's logins and their status
 localauth show <id>                 # one login with its output (--json for scripts)
 localauth status                    # account and service this machine is connected to
-localauth verify                    # compare four emoji with the page to trust end-to-end encryption
+localauth verify                    # match a number on the page to trust end-to-end encryption
 localauth logout                    # disconnect this machine
+localauth approve --title <text> [--description <text>] [--timeout <minutes>]
 ```
 
 `localauth finish` matches the address to the waiting login by port and OAuth state, so a user
@@ -185,7 +186,7 @@ curl https://localauth.dev/api/v1/runs \
 ```
 
 Permissions are `runs:read`, `runs:write`, `machines:read` and `machines:write`.
-Personal tokens cannot change the account, encryption keys, passkeys, other tokens or emoji
+Personal tokens cannot change the account, encryption keys, passkeys, other tokens or machine
 verification. In Cloudflare Access mode, personal tokens and OAuth are disabled.
 The website uses the Access JWT and the CLI uses its machine token.
 
@@ -198,16 +199,21 @@ even if invalid. Cross-origin clients use explicit header credentials; CORS neve
 cookie credentials. Errors return `{ error: { code, message } }`; rate limits return 429
 with `Retry-After`. Machine tokens and link capabilities have separate routes and authority.
 
+The first time someone signs in to the iOS app, localauth.dev shows what the app will be able to
+do and asks them to allow it (`/oauth/consent`); the answer is remembered. **Account, Signed-in
+apps** lists each device where the app is signed in and signs one out at once; the same list is
+`GET /api/v1/app-sessions` and `DELETE /api/v1/app-sessions/{id}` (account scope).
+
 The iOS app (client `localauth-ios`) signs in with Better Auth's OAuth provider:
 `/api/auth/oauth2/authorize`, `/api/auth/oauth2/token` and `/api/auth/oauth2/revoke`, with S256
 PKCE and an exact redirect allowlist. Access tokens last an hour; refresh tokens last 90 days and
 rotate on use. A retry within 10 seconds gets the same new pair; reusing a rotated refresh token
-later revokes all of the app's tokens for that person. The app stays signed in independently
-of the browser session it signed in through (it asks for `offline_access`). The app revokes its
-refresh token on sign-out, deleting the account removes every token, and disabling the client
-row switches the whole app off. Third-party clients, registration and
-consent are not offered. The plugin has a documented race in that revocation, which this
-repository patches; see [patches/README.md](patches/README.md).
+later revokes all of the app's tokens for that person. The app stays signed in independently of
+the browser session it signed in through (it asks for `offline_access`). The app revokes its
+refresh token on sign-out, deleting the account removes every token, and disabling the client row
+switches the whole app off. Third-party clients and registration are not offered. The plugin has a
+documented race in that revocation, which this repository patches; see
+[patches/README.md](patches/README.md).
 
 End-to-end data stays sealed through the API. A client that needs plaintext must hold the
 account private key, obtained locally from a passkey PRF wrap, and implement the
@@ -218,8 +224,8 @@ On browsers supporting WebMCP, dashboard and link pages register login tools and
 and device page register machine approval tools. They use the page's existing decryption,
 sealing, callback checks and confirmation dialogs. A link page sees only its run. A locked
 browser asks the person to unlock on the page. Machine output and names are untrusted data.
-There are no WebMCP tools for emoji verification, account, encryption, passkey or token changes,
-sign-out or deletion. A person still compares emoji after approving an E2E machine.
+There are no WebMCP tools for machine verification, account, encryption, passkey or token changes,
+sign-out or deletion. A person still taps the matching number after approving an E2E machine.
 
 ## Encryption
 
@@ -252,15 +258,15 @@ public-key-only envelopes, and messages from a different account key. The servic
 private key, so it cannot forge or alter these messages. Input is bound to the current attempt
 and deduplicated by an authenticated message id. Ciphertexts bind their kind and record to prevent swapping.
 
-A machine trusts the account public key only after a short emoji check, so the service can't
+A machine trusts the account public key only after a short number check, so the service can't
 hand it a key of its own. `localauth verify` (and `localauth login` on an end-to-end account)
 prints a link; the page and the machine exchange ephemeral ECDH keys through the service, the
-machine having committed to its key before seeing the browser's, and both derive four emoji
-from the shared secret and everything exchanged (the 64 emoji of Matrix's SAS verification,
-shown with their names so different emoji fonts still compare). The terminal prints the four;
-the page offers four rows of them and "None of these match", so nobody types emoji. Picking the
-right row sends a MAC of the exchange that the machine checks before pinning the key. A service
-in the middle would have to guess the emoji, a 1 in 2^24 chance per attempt. The browser also
+machine having committed to its key before seeing the browser's, and both derive a three-digit
+number from the shared secret and everything exchanged. The terminal prints the number; the page
+offers it among two decoys and "None of these match", like a phone sign-in prompt, so nobody
+types anything. Tapping the right number sends a MAC of the exchange that the machine checks
+before pinning the key. A service in the middle would have to guess the number, a 1 in 1000
+chance per attempt, and every failed attempt shows a warning on both sides. The browser also
 stores the account's MAC over the machine's key so other browsers show it as verified.
 
 Until it is verified, a machine refuses to run logins for an end-to-end account. If the service
@@ -394,7 +400,7 @@ npm run design:qa      # screenshots of every design preview, light and dark, ph
 ```
 
 While `npm run dev` runs, http://localhost:8787/design shows every page in every state (signed
-out, waiting logins, failed retries, emoji verification, dialogs, …) with made-up data, and
+out, waiting logins, failed retries, number verification, dialogs, …) with made-up data, and
 `/design/<id>` opens one with a switcher in the bottom right for states and light/dark. They are
 for tuning the design: no real data, no API calls, and they don't exist in deployed Workers.
 

package/cli/ask.ts

@@ -159,3 +159,60 @@ export async function ask(connection: Connection, options: AskOptions, say: (tex
     await run.close()
   }
 }
+
+export interface ApproveOptions { title: string; description?: string; timeout: number }
+export function parseApproveArgs(rest: string[]): ApproveOptions {
+  let options: ApproveOptions = { title: '', timeout: 15 }
+  for (let i = 0; i < rest.length; i++) {
+    let value = rest[i + 1]
+    if (value === undefined) throw new Error(`${rest[i]} needs a value.`)
+    if (rest[i] === '--title') options.title = value
+    else if (rest[i] === '--description') options.description = value
+    else if (rest[i] === '--timeout') {
+      options.timeout = Number(value)
+      if (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout > 60) throw new Error('--timeout must be greater than 0 and at most 60.')
+    } else throw new Error(`Unknown localauth approve option "${rest[i]}".`)
+    i++
+  }
+  if (!options.title) throw new Error('localauth approve needs --title.')
+  return options
+}
+
+/** Only an answer sealed with the pinned account key can approve; anything else that arrives can only decline. */
+export async function approve(connection: Connection, options: ApproveOptions, say: (text: string) => void): Promise<number> {
+  if (!connection.accountPublicKey) throw new Error('localauth approve needs end-to-end encryption: add a passkey on your account, then run localauth verify.')
+  let expiresAt = Date.now() + Math.ceil(options.timeout * 60_000)
+  let request: AskRequest = { title: options.title, description: options.description, fields: [{ name: 'APPROVE', label: 'Approve', secret: false, required: true }] }
+  let data: RunData = { authenticatedMessages: true, kind: 'ask', approval: true, title: options.title, ask: request, expiresAt, command: '', flows: [], output: '', exitCode: null, attempt: 1, retryUntil: null }
+  if (!isAskRequest(data.ask)) throw new Error('Invalid approval request.')
+  let run = await createRun(connection, [], say, { retry: false, link: false }, data)
+  let stop = new AbortController(), interrupted = 0
+  let listeners = Object.entries({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }).map(([signal, code]) => {
+    let listener = () => { interrupted = code; stop.abort() }
+    process.on(signal, listener); return { signal, listener }
+  })
+  try {
+    await run.publish()
+    let decided: boolean | null = null
+    while (!stop.signal.aborted && Date.now() < expiresAt && decided === null) {
+      let signal = AbortSignal.any([stop.signal, AbortSignal.timeout(Math.max(1, expiresAt - Date.now()))])
+      try {
+        for (let message of await run.takeMessages(signal)) {
+          if (message.kind === 'decline') { decided = false; break }
+          if (message.kind !== 'answer' || typeof message.data !== 'string' || !message.data.startsWith('a1.')) continue
+          let value = await run.openMessage<AnswerData>('answer', message.data)
+          if (isAnswer(value) && !value.declined && answerFields(value, request)?.APPROVE === 'yes') { decided = true; break }
+        }
+        if (decided === null) await sleep(Math.min(1500, Math.max(1, expiresAt - Date.now())), undefined, { signal })
+      } catch (error) { if (!signal.aborted) throw error }
+    }
+    data.exitCode = decided ? 0 : 1
+    await run.publish(AbortSignal.timeout(3000)).catch(() => {})
+    if (interrupted) return interrupted
+    say(decided ? 'localauth: approved.' : decided === false ? 'localauth: the owner declined the request.' : 'localauth: the request timed out.')
+    return decided ? 0 : 1
+  } finally {
+    for (let { signal, listener } of listeners) process.off(signal, listener)
+    await run.close()
+  }
+}

package/cli/cli.ts

@@ -1,4 +1,4 @@
-import { ask, parseAskArgs } from './ask.ts'
+import { ask, parseAskArgs, approve, parseApproveArgs } from './ask.ts'
 import * as os from 'node:os'
 import { createTerminal } from 'remix/terminal'
 
@@ -32,11 +32,15 @@ Usage:
                                       LD_*, NODE_OPTIONS, BROWSER, LOCALAUTH_* or other loader variables
                                       Title/labels: max 120; description: max 2000 (plain text + links)
                                       Requests expire in 15 minutes (max 60); decline/timeout exits 1
+  localauth approve --title <text> [--description <text>] [--timeout <minutes>]
+                                      Wait for the owner to allow something. They answer from their
+                                      signed-in list with a fresh passkey check; no link is made
+                                      Needs end-to-end encryption; exits 0 if approved, 1 otherwise
   localauth finish [<callback-url>]   Hand a pasted http://localhost:... address to the waiting command
                                       (reads it from stdin when omitted, keeping it out of ps)
   localauth list [--json]             This machine's logins and requests
   localauth show <id> [--json]        One login or request with its output
-  localauth verify                    Compare four emoji with the page to trust the account's encryption key
+  localauth verify                    Match a number on the page to trust the account's encryption key
   localauth status                    Which account and service this machine is connected to
   localauth url                       The page to open to finish logins
   localauth logout                    Disconnect this machine
@@ -78,6 +82,9 @@ export async function main(args: string[]): Promise<number> {
       case 'ask':
         return await ask(requireConnection(), parseAskArgs(rest), say)
 
+      case 'approve':
+        return await approve(requireConnection(), parseApproveArgs(rest), say)
+
       case 'browser':
         return await reportBrowserUrls(rest, say)
 
@@ -231,7 +238,7 @@ async function login(url: string, name: string): Promise<number> {
     terminal.writeLine(`${styles.green('✓')} Connected as ${styles.bold(reply.data.user.email)}.`)
     let me = await createService(url, connection)<{ accountKey: { publicKey: string } | null }>('GET', '/api/v1/machine/me')
     if (me.status === 200 && me.data.accountKey) {
-      terminal.writeLine('This account uses end-to-end encryption, so check this machine with four emoji.')
+      terminal.writeLine('This account uses end-to-end encryption, so check this machine with a number.')
       if (!(await verifyMachine(connection, (line) => terminal.writeLine(line)))) return 1
     }
     terminal.writeLine(`Run logins with: localauth run -- <command>   Finish them at ${url}/`)

package/cli/config.ts

@@ -16,7 +16,7 @@ export interface Connection {
   publicKey: string
   accountPublicKey?: string
   accountFingerprint?: string
-  /** True once the account key was confirmed with emoji (localauth verify), not just trusted on first sight. */
+  /** True once the account key was confirmed with a number (localauth verify), not just trusted on first sight. */
   accountVerified?: boolean
   user: { email: string; name: string }
   /** A Cloudflare Access service token, when the service sits behind Access. */

package/cli/encryption.ts

@@ -6,7 +6,7 @@ import { createService, messageOf } from './service.ts'
 export const KEY_CHANGED = 'the account key changed; run localauth verify to check and trust the new one'
 export const KEY_REMOVED = 'end-to-end encryption was reset for this account; run localauth login to reconnect this machine'
 export const NEEDS_VERIFY = 'this account uses end-to-end encryption; verify this machine first: localauth verify'
-/** A pinned key that changed needs a new emoji check; one that vanished needs a new connection, never a quiet downgrade. */
+/** A pinned key that changed needs a new number check; one that vanished needs a new connection, never a quiet downgrade. */
 export function checkPin(pinned: string | undefined, reported: string | null) {
   if (pinned && !reported) throw new Error(KEY_REMOVED)
   if (pinned && pinned !== reported) throw new Error(KEY_CHANGED)
@@ -24,7 +24,7 @@ export async function refreshPin(connection: Connection, say: (text: string) =>
   if (reply.status !== 200) throw new Error(messageOf(reply))
   let publicKey = reply.data.accountKey?.publicKey ?? null
   checkPin(connection.accountPublicKey, publicKey)
-  // An account key is trusted only after the person compared emoji (localauth verify), never on sight.
+  // An account key is trusted only after the person matched a number (localauth verify), never on sight.
   if (publicKey && !connection.accountPublicKey) throw new Error(NEEDS_VERIFY)
   void say
   return { publicKey, machineName: reply.data.machine?.name }

package/cli/run.ts

@@ -159,7 +159,7 @@ export async function createRun(connection: Connection | null, argv: string[], s
     snapshot.output = redactor.redact(snapshot.output)
     for (let flow of snapshot.flows) flow.note = redactor.redact(flow.note)
     let sealed = await encodeRun(connection!, id, snapshot, signal)
-    let reply = await service('PUT', `/api/v1/machine/runs/${id}`, { state: runState(snapshot), data: sealed, kind: data.kind ?? 'login', ...(data.kind === 'ask' ? { expiresAt: data.expiresAt } : {}), ...(link ? { linkTokenHash: link.tokenHash, linkData: await sealLink(link.key, 'run', id, snapshot) } : {}) }, signal).catch((error) => {
+    let reply = await service('PUT', `/api/v1/machine/runs/${id}`, { state: runState(snapshot), data: sealed, kind: data.kind ?? 'login', ...(data.approval ? { approval: true } : {}), ...(data.kind === 'ask' ? { expiresAt: data.expiresAt } : {}), ...(link ? { linkTokenHash: link.tokenHash, linkData: await sealLink(link.key, 'run', id, snapshot) } : {}) }, signal).catch((error) => {
       if (!offline) say(`localauth: ${(error as Error).message}`)
       offline = true
       return null
@@ -253,7 +253,7 @@ export async function createRun(connection: Connection | null, argv: string[], s
       if (reply.status === 404) throw new Error('This request expired or was dismissed.')
       return reply.status === 200 ? reply.data.data : []
     },
-    async openMessage<T>(kind: MessageKind, value: unknown) {
+    async openMessage<T>(kind: Exclude<MessageKind, 'decline'>, value: unknown) {
       return openMessage<T>({ privateKey: key!, publicKey: connection!.publicKey, accountPublicKey: connection?.accountPublicKey, linkKey: link?.key }, kind, id, value)
     },
     async takeRetry(signal: AbortSignal) {

package/cli/verify.ts

@@ -1,5 +1,5 @@
 import { fingerprint } from '../shared/e2e.ts'
-import { checkConfirmation, commitment, deriveSas, ephemeral, sasText, type Transcript } from '../shared/sas.ts'
+import { checkConfirmation, commitment, deriveSas, ephemeral, type Transcript } from '../shared/sas.ts'
 import { saveConnection, type Connection } from './config.ts'
 import { createService, messageOf } from './service.ts'
 
@@ -15,21 +15,22 @@ interface MachineView {
 const POLL_MS = 1500
 
 /**
- * Verify the account key with a browser that holds it (shared/sas.ts): print a link, print the four
- * emoji once the page has answered, and trust the account key only after the browser confirms that
- * the person picked them. Returns true when this machine now trusts a verified account key.
+ * Verify the account key with a browser that holds it (shared/sas.ts): print a link, print a
+ * three-digit number once the page has answered, and trust the account key only after the browser
+ * confirms that the person tapped the same number there. Returns true when this machine now trusts a verified account key.
  */
 export async function verifyMachine(connection: Connection, say: Say, timeoutMs = 10 * 60 * 1000): Promise<boolean> {
   let service = createService(connection.url, connection)
   let own = await ephemeral()
   let started = await service<{ id: string }>('POST', '/api/v1/machine/verifications', {
     commitment: await commitment(own.publicKey, connection.publicKey),
+    version: 2,
   })
   if (started.status === 409) throw new Error('This account has no end-to-end encryption to verify. Add a passkey on the Account page first.')
   if (started.status !== 201) throw new Error(messageOf(started))
   let id = started.data.id
   say(`To verify this machine, open ${connection.url}/verify/${id}`)
-  say('The emoji to pick there appear here once the page is open.')
+  say('The number to tap there appears here once the page is open.')
 
   let deadline = Date.now() + timeoutMs
   let view = await waitFor(service, id, deadline, (v) => v.status !== 'committed')
@@ -44,18 +45,22 @@ export async function verifyMachine(connection: Connection, say: Say, timeoutMs
     machineEphemeral: own.publicKey,
     browserEphemeral: view.browserEphemeral,
   }
-  let { sas, macKey } = await deriveSas(own.privateKey, view.browserEphemeral, transcript)
+  let { code, macKey } = await deriveSas(own.privateKey, view.browserEphemeral, transcript)
   say('')
-  say(`On the page, pick the row with:   ${sasText(sas)}`)
+  say(`On the page, tap ${code}`)
   say('')
 
   view = await waitFor(service, id, deadline, (v) => v.status === 'confirmed' || v.status === 'rejected')
-  if (view.status !== 'confirmed' || !view.confirmation || !(await checkConfirmation(macKey, transcript, view.confirmation))) {
+  // The MAC vouches for the transcript only, so trust nothing else from this reply: a relay could
+  // keep a valid MAC and report a key of its own next to it.
+  let unchanged = view.accountPublicKey === transcript.accountPublicKey && view.browserEphemeral === transcript.browserEphemeral
+  if (view.status !== 'confirmed' || !unchanged || !view.confirmation || !(await checkConfirmation(macKey, transcript, view.confirmation))) {
     return refused(say, view)
   }
-  let changed = connection.accountPublicKey && connection.accountPublicKey !== view.accountPublicKey
-  connection.accountPublicKey = view.accountPublicKey!
-  connection.accountFingerprint = await fingerprint(view.accountPublicKey!)
+  let accountPublicKey = transcript.accountPublicKey
+  let changed = connection.accountPublicKey && connection.accountPublicKey !== accountPublicKey
+  connection.accountPublicKey = accountPublicKey
+  connection.accountFingerprint = await fingerprint(accountPublicKey)
   connection.accountVerified = true
   saveConnection(connection)
   say(changed ? '✓ Verified the new account key. This machine now encrypts to it.' : '✓ Verified. Logins from this machine are end-to-end encrypted to your account.')
@@ -75,7 +80,7 @@ async function waitFor(service: ReturnType<typeof createService>, id: string, de
 function refused(say: Say, view: MachineView): false {
   say(
     view.status === 'rejected'
-      ? '✗ Not verified: the page said the emoji did not match, or the request was declined.'
+      ? '✗ Not verified: the page said the number did not match, or the request was declined.'
       : '✗ Not verified: the confirmation from the page did not check out.',
   )
   say('  Someone may be intercepting this connection. Do not send secrets to this machine until it verifies.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localauth/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Finish CLI logins on a headless server from your phone, with optional passkey-based end-to-end encryption",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "build": "node scripts/build-client.ts",
     "deploy": "wrangler deploy",
     "test": "NODE_ENV=test remix test",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p app/landing-demo",
     "db:generate": "drizzle-kit generate",
     "db:migrate:local": "wrangler d1 migrations apply localauth --local",
     "db:migrate": "wrangler d1 migrations apply localauth --remote",
@@ -52,6 +52,7 @@
     "node": ">=24.3.0"
   },
   "dependencies": {
+    "@simplewebauthn/server": "13.3.3",
     "remix": "^3.0.0"
   },
   "devDependencies": {
@@ -62,6 +63,8 @@
     "@remix-run/ui": "0.12.1",
     "@simplewebauthn/browser": "^13.3.0",
     "@types/node": "^26.6.5",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
     "auth": "1.7.12",
     "better-auth": "1.7.12",
     "drizzle-kit": "^0.31.11",
@@ -70,6 +73,7 @@
     "jose": "^6.2.12",
     "patch-package": "8.0.1",
     "playwright-core": "^1.64.1",
+    "preact": "10.25.4",
     "typescript": "^7.0.2",
     "wrangler": "^4.151.0"
   }

package/shared/protocol.ts

@@ -21,7 +21,7 @@ export interface Flow {
 }
 
 /** Login details: plaintext in the owner API by default, opaque in end-to-end mode. */
-export type MessageKind = 'callback' | 'input' | 'answer'
+export type MessageKind = 'callback' | 'input' | 'answer' | 'decline'
 export interface InputData { attempt: number; text: string; messageId: string }
 export interface AskField { name: string; label: string; secret: boolean; required: boolean }
 export interface AskRequest { title?: string; description?: string; fields: AskField[] }
@@ -33,6 +33,8 @@ export type AnswerData = { declined: true; messageId: string }
 export interface RunData {
   authenticatedMessages?: boolean
   kind?: 'login' | 'ask'
+  /** Answered only with a fresh passkey check, never by typing or through a link. */
+  approval?: boolean
   inputEnabled?: boolean
   secret?: boolean
   ask?: AskRequest

package/shared/sas.ts

@@ -7,31 +7,22 @@ import { fromBase64Url, generateKeyPair, importPrivateKey, importPublicKey, toBa
  * 1. The machine makes an ephemeral ECDH key and sends only a commitment to it.
  * 2. The browser sends its ephemeral key and the account public key.
  * 3. The machine reveals its ephemeral key; the browser checks it against the commitment.
- * 4. Both derive four emoji and a MAC key from ECDH(ephemerals) and the whole transcript.
+ * 4. Both derive a short number and a MAC key from ECDH(ephemerals) and the whole transcript.
  *
  * Someone in the middle must fix their key toward the browser before seeing the browser's, and
  * toward the machine before seeing the machine's, so they can't search for keys that make both
- * sides show the same emoji: they get one guess in 2^24 per attempt. The person compares the
- * emoji the terminal prints with the options on the page; the browser then confirms with a MAC.
- *
- * The emoji are the 64 of the Matrix SAS specification, chosen to be told apart easily.
+ * sides show the same number: each attempt succeeds with probability 10^-SAS_DIGITS, and every
+ * failed one shows the person a warning. The terminal prints the number; the page offers it among
+ * decoys, like a phone sign-in prompt, and the person taps the one that matches. The browser then
+ * confirms with a MAC.
  */
 
-export const SAS_EMOJI: ReadonlyArray<readonly [emoji: string, name: string]> = [
-  ['🐶', 'Dog'], ['🐱', 'Cat'], ['🦁', 'Lion'], ['🐎', 'Horse'], ['🦄', 'Unicorn'], ['🐷', 'Pig'], ['🐘', 'Elephant'], ['🐰', 'Rabbit'],
-  ['🐼', 'Panda'], ['🐓', 'Rooster'], ['🐧', 'Penguin'], ['🐢', 'Turtle'], ['🐟', 'Fish'], ['🐙', 'Octopus'], ['🦋', 'Butterfly'], ['🌷', 'Flower'],
-  ['🌳', 'Tree'], ['🌵', 'Cactus'], ['🍄', 'Mushroom'], ['🌏', 'Globe'], ['🌙', 'Moon'], ['☁️', 'Cloud'], ['🔥', 'Fire'], ['🍌', 'Banana'],
-  ['🍎', 'Apple'], ['🍓', 'Strawberry'], ['🌽', 'Corn'], ['🍕', 'Pizza'], ['🎂', 'Cake'], ['❤️', 'Heart'], ['😀', 'Smiley'], ['🤖', 'Robot'],
-  ['🎩', 'Hat'], ['👓', 'Glasses'], ['🔧', 'Spanner'], ['🎅', 'Santa'], ['👍', 'Thumbs up'], ['☂️', 'Umbrella'], ['⌛', 'Hourglass'], ['⏰', 'Clock'],
-  ['🎁', 'Gift'], ['💡', 'Light bulb'], ['📕', 'Book'], ['✏️', 'Pencil'], ['📎', 'Paperclip'], ['✂️', 'Scissors'], ['🔒', 'Lock'], ['🔑', 'Key'],
-  ['🔨', 'Hammer'], ['☎️', 'Telephone'], ['🏁', 'Flag'], ['🚂', 'Train'], ['🚲', 'Bicycle'], ['✈️', 'Aeroplane'], ['🚀', 'Rocket'], ['🏆', 'Trophy'],
-  ['⚽', 'Ball'], ['🎸', 'Guitar'], ['🎺', 'Trumpet'], ['🔔', 'Bell'], ['⚓', 'Anchor'], ['🎧', 'Headphones'], ['📁', 'Folder'], ['📌', 'Pin'],
-]
-
-/** Four indexes into SAS_EMOJI. */
-export type Sas = [number, number, number, number]
-
-/** Everything both sides must agree on; any difference changes the emoji and the MAC key. */
+/** Digits in the code. The owner chose three: one chance in a thousand per attempt. */
+export const SAS_DIGITS = 3
+/** Numbers the page offers: the right one and decoys. */
+export const SAS_CHOICES = 3
+
+/** Everything both sides must agree on; any difference changes the number and the MAC key. */
 export interface Transcript {
   verificationId: string
   machinePublicKey: string
@@ -43,7 +34,7 @@ export interface Transcript {
 const enc = new TextEncoder()
 
 export async function commitment(machineEphemeral: string, machinePublicKey: string): Promise<string> {
-  let digest = await crypto.subtle.digest('SHA-256', enc.encode(`localauth/sas/v1/commit|${machineEphemeral}|${machinePublicKey}`))
+  let digest = await crypto.subtle.digest('SHA-256', enc.encode(`localauth/sas/v2/commit|${machineEphemeral}|${machinePublicKey}`))
   return toBase64Url(new Uint8Array(digest))
 }
 
@@ -53,28 +44,51 @@ export async function ephemeral() {
   return { publicKey: pair.publicKey, privateKey: await importPrivateKey(pair.privateKey) }
 }
 
-/** The emoji and the confirmation MAC key, from our ephemeral private key and the peer's ephemeral. */
+/** What the browser pins from the verification before it sends its own ephemeral key. */
+export interface Pinned {
+  commitment: string
+  machineId: string
+  machinePublicKey: string
+}
+
+/**
+ * Whether the machine's revealed ephemeral is the one it committed to, judged only against values
+ * pinned before the browser sent its own key. A service that could change the commitment or the
+ * machine key afterwards would see the browser's key first and could try keys until the numbers
+ * match, which defeats the commitment.
+ */
+export async function honestReveal(
+  pinned: Pinned,
+  revealed: { commitment: string; machineId: string; machinePublicKey: string; machineEphemeral: string | null },
+): Promise<boolean> {
+  if (!revealed.machineEphemeral) return false
+  if (revealed.commitment !== pinned.commitment || revealed.machineId !== pinned.machineId || revealed.machinePublicKey !== pinned.machinePublicKey) return false
+  return (await commitment(revealed.machineEphemeral, pinned.machinePublicKey)) === pinned.commitment
+}
+
+/** The code and the confirmation MAC key, from our ephemeral private key and the peer's ephemeral. */
 export async function deriveSas(ownEphemeral: CryptoKey, peerEphemeral: string, transcript: Transcript) {
   let shared = new Uint8Array(await crypto.subtle.deriveBits({ name: 'ECDH', public: await importPublicKey(peerEphemeral) }, ownEphemeral, 256))
   let material = await crypto.subtle.importKey('raw', shared, 'HKDF', false, ['deriveBits'])
   let bits = new Uint8Array(
     await crypto.subtle.deriveBits(
-      { name: 'HKDF', hash: 'SHA-256', salt: enc.encode('localauth/sas/v1'), info: enc.encode(transcriptText(transcript)) },
+      { name: 'HKDF', hash: 'SHA-256', salt: enc.encode('localauth/sas/v2'), info: enc.encode(transcriptText(transcript)) },
       material,
-      (3 + 32) * 8,
+      (4 + 32) * 8,
     ),
   )
-  let n = (bits[0] << 16) | (bits[1] << 8) | bits[2]
-  let sas: Sas = [(n >> 18) & 63, (n >> 12) & 63, (n >> 6) & 63, n & 63]
-  let macKey = await crypto.subtle.importKey('raw', bits.slice(3), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
-  return { sas, macKey }
+  // A 32-bit number reduced to SAS_DIGITS digits: the bias is below one part in four million.
+  let n = new DataView(bits.buffer).getUint32(0)
+  let code = String(n % 10 ** SAS_DIGITS).padStart(SAS_DIGITS, '0')
+  let macKey = await crypto.subtle.importKey('raw', bits.slice(4), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
+  return { code, macKey }
 }
 
 function transcriptText(t: Transcript): string {
-  return ['localauth/sas/v1', t.verificationId, t.machinePublicKey, t.accountPublicKey, t.machineEphemeral, t.browserEphemeral].join('|')
+  return ['localauth/sas/v2', t.verificationId, t.machinePublicKey, t.accountPublicKey, t.machineEphemeral, t.browserEphemeral].join('|')
 }
 
-/** The browser's confirmation that the person picked the matching emoji. */
+/** The browser's confirmation that the person picked the matching number. */
 export async function confirmation(macKey: CryptoKey, transcript: Transcript): Promise<string> {
   let mac = await crypto.subtle.sign('HMAC', macKey, enc.encode(`confirm|${transcriptText(transcript)}`))
   return toBase64Url(new Uint8Array(mac))
@@ -88,27 +102,28 @@ export async function checkConfirmation(macKey: CryptoKey, transcript: Transcrip
   }
 }
 
-export function sameSas(a: Sas, b: Sas): boolean {
-  return a.every((value, i) => value === b[i])
+/** Positions where two codes differ. */
+function distance(a: string, b: string) {
+  return [...a].filter((digit, i) => digit !== b[i]).length
 }
 
 /**
  * Wrong answers to show next to the right one: random, distinct, and each differing from the right
- * one and from each other in at least two places, so a glance can't confuse them.
+ * one and from each other in at least two digits, so a glance can't confuse them.
  */
-export function decoys(correct: Sas, count = 3, random: (n: number) => number = randomBelow): Sas[] {
-  let chosen: Sas[] = []
-  let far = (a: Sas, b: Sas) => a.filter((value, i) => value !== b[i]).length >= 2
+export function decoys(correct: string, count = SAS_CHOICES - 1, random: (n: number) => number = randomBelow): string[] {
+  let chosen: string[] = []
+  let far = (a: string, b: string) => distance(a, b) >= Math.min(2, SAS_DIGITS)
   while (chosen.length < count) {
-    let candidate = [random(64), random(64), random(64), random(64)] as Sas
+    let candidate = Array.from({ length: SAS_DIGITS }, () => random(10)).join('')
     if (far(candidate, correct) && chosen.every((other) => far(candidate, other))) chosen.push(candidate)
   }
   return chosen
 }
 
-/** The right answer and the decoys in random order. */
-export function options(correct: Sas, random: (n: number) => number = randomBelow): Sas[] {
-  let all = [correct, ...decoys(correct, 3, random)]
+/** The right code and the decoys in random order. */
+export function options(correct: string, random: (n: number) => number = randomBelow): string[] {
+  let all = [correct, ...decoys(correct, SAS_CHOICES - 1, random)]
   for (let i = all.length - 1; i > 0; i--) {
     let j = random(i + 1)
     ;[all[i], all[j]] = [all[j], all[i]]
@@ -125,10 +140,6 @@ function randomBelow(n: number): number {
   }
 }
 
-export function sasText(sas: Sas): string {
-  return sas.map((i) => `${SAS_EMOJI[i][0]} ${SAS_EMOJI[i][1]}`).join('   ')
-}
-
 /**
  * Cross-device record that this account verified a machine's key: an HMAC under a key only holders
  * of the account private key can derive (ECDH of the account key with itself), so the service

package/shared/validation.ts

@@ -10,6 +10,7 @@ export function isRunData(value: unknown): value is RunData {
   return !!v && typeof v.title === 'string' && typeof v.command === 'string' && typeof v.output === 'string'
     && (v.authenticatedMessages === undefined || typeof v.authenticatedMessages === 'boolean')
     && (v.kind === undefined || ['login', 'ask'].includes(v.kind))
+    && (v.approval === undefined || (v.approval === true && v.kind === 'ask'))
     && (v.inputEnabled === undefined || typeof v.inputEnabled === 'boolean')
     && (v.secret === undefined || typeof v.secret === 'boolean')
     && (v.ask === undefined || (v.kind === 'ask' && isAskRequest(v.ask)))

package/skills/localauth/SKILL.md

@@ -16,9 +16,9 @@ Tokens are created on this machine.
 For scripts, the public API is documented at https://localauth.dev/docs/api and
 https://localauth.dev/api/v1/openapi.json. The owner can create a scoped personal token on the
 Account page and send it as `Authorization: Bearer lat_…`. It cannot change the account,
-encryption, passkeys, tokens or emoji verification. End-to-end API data stays sealed; a client
+encryption, passkeys, tokens or machine verification. End-to-end API data stays sealed; a client
 needs the account key to read or answer it. Browser agents may use the page's WebMCP login
-and machine-pairing tools; a person still compares emoji. CLI 0.2.0 uses `/api/v1/machine/*`;
+and machine-pairing tools; a person still taps the matching number. CLI 0.2.0 uses `/api/v1/machine/*`;
 link clients use `/api/v1/links/*`.
 After the API upgrade, CLI 0.1.0 receives HTTP 410 with the update instruction. Ask the owner
 to update it; never change an installed CLI or its config without authorization.
@@ -34,9 +34,8 @@ localauth status
 - "not verified yet: run localauth verify" (or a command refusing with "verify this machine
   first"): the account uses end-to-end encryption and this machine hasn't checked its key. Run
   `localauth verify` in the background and send the user the link it prints. Once they open it,
-  the command prints a line of four emoji with names ("pick the row with: 🐶 Dog   🍎 Apple …"):
-  send that line too. On the page they pick the row with the same four emoji, or "None of these
-  match". It exits 0 when verified. If it reports a mismatch, stop: someone may be intercepting
+  the command prints a three-digit number ("On the page, tap 482"): send that number too. On the
+  page they tap the same number among three, or "None of these match". It exits 0 when verified. If it reports a mismatch, stop: someone may be intercepting
   the connection, and the user should not send secrets to this machine.
 - "the account key changed": run `localauth verify` as above. "end-to-end encryption was reset":
   reconnect with `localauth login`. Never edit the config to get around either.
@@ -47,7 +46,7 @@ localauth status
 To connect, run `localauth login` in the background (it waits for approval) and send the user the
 link it prints, with the code it shows. They open it, sign in, check the code and tap **Connect**;
 `localauth login` then exits by itself. If the account uses end-to-end encryption, it then prints
-four emoji: send that line, and the user picks the matching row on the same page. If it says to
+a three-digit number: send it, and the user taps the same number on the same page. If it says to
 sign in at the service first (a self-hosted copy behind Cloudflare Access), pass that on too.
 Links contain only the device code or a verification id, never keys.
 
@@ -186,3 +185,12 @@ nothing to paste, the command finishes on its own once the user approves.
   title on the page (Kargo, Codex, …).
 - If the user gives up, stop the background `localauth run` process so the command stops listening.
 - `localauth help` lists every command.
+
+## Asking the owner to allow something
+
+```sh
+localauth approve --title "Allow access to the production database" --description "Why it is needed"
+```
+
+It exits 0 if approved and 1 if declined or timed out. The owner answers from their signed-in list with a new passkey check, so there is no link to send them: tell them to open localauth.dev. It needs end-to-end encryption on the account.
+