@localauth/cli 0.1.0 → 0.3.0

package/README.md

@@ -59,7 +59,7 @@ 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
 ```
 
@@ -156,6 +156,76 @@ input and answers with their link key in either mode. The Secret toggle only con
 a CLI login needs a browser on a machine you are not sitting at. Copy or link it into your agent's
 skills directory, for example `~/.claude/skills/localauth`.
 
+## Public API and browser tools
+
+The [API reference](https://localauth.dev/docs/api) and
+[OpenAPI 3.1 document](https://localauth.dev/api/v1/openapi.json) describe the public `/api/v1` API.
+Changes within v1 are additive; incompatible changes get a new path version.
+The website and CLI 0.2.0 use this same API. Better Auth stays at `/api/auth/*`, including the
+iOS app's OAuth endpoints.
+
+**Breaking upgrade to CLI 0.2.0.** The old `/api/me`, `/api/account/*`, `/api/runs/*`,
+`/api/machines/*`, `/api/pairings/*`, `/api/verifications/*`, `/api/r/*` and `/api/tokens/*`
+routes are removed. `/api/m/*` returns HTTP 410 with an instruction to run
+`npm install -g @localauth/cli`. Existing scripts must use `/api/v1` paths, direct single
+resources, paginated lists and the nested error shape. Open website tabs should reload.
+Machine tokens, saved configuration, account keys and encrypted envelopes do not need conversion.
+
+CLI 0.1.0 stops working once the Worker is updated, and CLI 0.2.0 needs the updated Worker:
+update both together. Self-hosted Access deployments must move their machine-route bypass policy
+to `/api/v1/machine/*` first.
+
+Create a personal access token in **Account, API tokens**. Choose a name, permissions and,
+optionally, an expiry. Copy it when it appears; the service stores only a hash of it.
+The card lists creation, last use and expiry, and lets you revoke a token immediately.
+
+```sh
+curl https://localauth.dev/api/v1/runs \
+  -H 'Authorization: Bearer lat_YOUR_TOKEN'
+```
+
+Permissions are `runs:read`, `runs:write`, `machines:read` and `machines:write`.
+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.
+
+Responses use camelCase JSON and epoch milliseconds. Lists return `{ data, nextCursor }`
+and accept `limit` (1–100, default 50) and `cursor`. Scripts and native clients use the
+Authorization header. The website can also use its same-origin session cookie or Access JWT.
+Browser credentials require matching Origin or `Sec-Fetch-Site: same-origin` on reads and
+mutations; contradictory signals are rejected. An Authorization header always takes precedence,
+even if invalid. Cross-origin clients use explicit header credentials; CORS never permits
+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 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
+[encryption protocol and fixed test vectors](docs/protocol.md). An OAuth token alone cannot
+decrypt it. Machine-side callback checks and account-key pinning remain mandatory.
+
+On browsers supporting WebMCP, dashboard and link pages register login tools and the dashboard
+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 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
 
 By default, any browser signed in to your account can read your logins. The Worker encrypts
@@ -187,15 +257,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
@@ -257,8 +327,9 @@ production modes. Set it to a securely generated random value and retain it acro
 npx wrangler secret put DATA_KEY
 ```
 
-Machines talk to `/api/m/*` without a browser. Either add a Bypass policy for `/api/m/*` (those
-routes check machine tokens themselves), or create an Access service token, allow it with a
+Machines talk to `/api/v1/machine/*` without a browser. Either add a Bypass policy for
+`/api/v1/machine/*` (those routes check machine tokens themselves), or create an Access service
+token, allow it with a
 Service Auth policy and set `LOCALAUTH_ACCESS_CLIENT_ID` and `LOCALAUTH_ACCESS_CLIENT_SECRET`
 before `localauth login`. Remove the `send_email` binding if you don't use email.
 
@@ -275,6 +346,37 @@ npx wrangler email sending enable <your domain>     # sign-in codes by email
 
 Sign-in options without credentials are hidden. Passkeys need no setup.
 
+**Sign in with Apple.** In Apple Developer, create an App ID with Sign in with Apple enabled,
+then a web Services ID associated with that primary App ID. Configure the service's domain
+and the return URL `https://YOUR_DOMAIN/api/auth/callback/apple`. Download a Sign in with
+Apple `.p8` key, keeping its Key ID and your Team ID. Set these Worker secrets:
+
+```sh
+npx wrangler secret put APPLE_CLIENT_ID       # web Services ID
+npx wrangler secret put APPLE_TEAM_ID
+npx wrangler secret put APPLE_KEY_ID
+npx wrangler secret put APPLE_PRIVATE_KEY     # full .p8 PEM contents
+```
+
+The Worker signs and caches Apple's ES256 client secret and renews it before its 180-day
+expiry. There is no manually maintained client-secret JWT. Apple appears first on the sign-in
+page once all four values exist; it can also be connected or disconnected in Account.
+Apple's cross-site form callback is allowed only at its exact POST callback endpoint; OAuth
+state validation still applies. Apple requires an HTTPS domain for callbacks.
+
+When the app's bundle ID is decided, enable its Sign in with Apple capability and set
+`APPLE_APP_BUNDLE_ID` to accept native identity-token audiences as well as the web Services ID.
+Set `OAUTH_IOS_REDIRECT_URIS` to the comma-separated exact redirect URLs selected for the app
+(a universal link and/or its custom scheme). No value is invented by the server, and an empty
+allowlist disables authorization. The app's associated-domain file and push notifications
+come with the iOS app; they are not part of this change.
+
+Apple's Hide My Email can supply a private relay address. Automatic account linking uses a
+verified email, so a relay address creates a separate localauth account from a different
+GitHub or Google email. To use the same account, sign in to that localauth account first,
+then connect Apple from Connected accounts. Configure Apple's private email relay sender
+registration if you send sign-in email to relay addresses.
+
 Then create the tables and deploy:
 
 ```sh
@@ -297,7 +399,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/cli.ts

@@ -9,7 +9,7 @@ import type { Flow, PairingResult, PairingStart, RunData, RunRecord } from '../s
 import { accessFromEnv, configPath, loadConnection, removeConnection, saveConnection, serviceUrl, type Connection } from './config.ts'
 import { parseRunArgs } from './retry.ts'
 import { reportBrowserUrls, runWrapped } from './run.ts'
-import { createService, messageOf, Unreachable } from './service.ts'
+import { createService, listAll, messageOf, Unreachable } from './service.ts'
 import { verifyMachine } from './verify.ts'
 
 const HELP = `localauth: finish CLI logins on this machine from your phone
@@ -36,7 +36,7 @@ Usage:
                                       (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
@@ -130,7 +130,7 @@ export async function main(args: string[]): Promise<number> {
           terminal.writeLine(`Not connected. Run: localauth login`)
           return 1
         }
-        let reply = await createService(connection.url, connection)('GET', '/api/m/me')
+        let reply = await createService(connection.url, connection)('GET', '/api/v1/machine/me')
         if (reply.status === 401) return fail(`${connection.url} no longer knows this machine. Run: localauth login`)
         if (reply.status !== 200) return fail(messageOf(reply))
         let encryption = await refreshPin(connection).then(
@@ -157,7 +157,7 @@ export async function main(args: string[]): Promise<number> {
           terminal.writeLine('Not connected.')
           return 0
         }
-        await createService(connection.url, connection)('DELETE', '/api/m/me').catch(() => null)
+        await createService(connection.url, connection)('DELETE', '/api/v1/machine/me').catch(() => null)
         removeConnection()
         terminal.writeLine(`Disconnected from ${connection.url}.`)
         return 0
@@ -198,7 +198,7 @@ function requireConnection(): Connection {
 async function login(url: string, name: string): Promise<number> {
   let keys = await generateKeyPair()
   let service = createService(url, { token: '', access: accessFromEnv() })
-  let started = await service<PairingStart>('POST', '/api/m/pair', { publicKey: keys.publicKey, name })
+  let started = await service<PairingStart>('POST', '/api/v1/machine/pair', { publicKey: keys.publicKey, name })
   if (started.status !== 201) return fail(`${url} refused the connection: ${messageOf(started)}`)
 
   // Build the link from the requested service URL, never an address returned by the service.
@@ -214,7 +214,7 @@ async function login(url: string, name: string): Promise<number> {
   let deadline = Date.now() + started.data.expiresIn * 1000
   while (Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, started.data.interval * 1000))
-    let reply = await service<PairingResult>('POST', '/api/m/pair/token', { deviceCode: started.data.deviceCode }).catch(
+    let reply = await service<PairingResult>('POST', '/api/v1/machine/pair/token', { deviceCode: started.data.deviceCode }).catch(
       () => null,
     )
     if (!reply || reply.status === 202) continue
@@ -229,9 +229,9 @@ async function login(url: string, name: string): Promise<number> {
     }
     saveConnection(connection)
     terminal.writeLine(`${styles.green('✓')} Connected as ${styles.bold(reply.data.user.email)}.`)
-    let me = await createService(url, connection)<{ accountKey: { publicKey: string } | null }>('GET', '/api/m/me')
+    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}/`)
@@ -252,12 +252,12 @@ interface OpenedRun {
 }
 
 async function openRuns(connection: Connection): Promise<OpenedRun[]> {
-  let reply = await createService(connection.url, connection)<{ runs: RunRecord[] }>('GET', '/api/m/runs')
+  let reply = await listAll<RunRecord>(createService(connection.url, connection), '/api/v1/machine/runs')
   if (reply.status === 401) throw new NotConnected(`${connection.url} no longer knows this machine. Run: localauth login`)
   if (reply.status !== 200) throw new Unreachable(messageOf(reply))
   await refreshPin(connection)
   return Promise.all(
-    reply.data.runs.map(async (record) => ({
+    reply.data.data.map(async (record) => ({
       record,
       data: await decodeRun(connection, record).catch(() => null),
     })),
@@ -277,7 +277,7 @@ async function finish(connection: Connection, pasted: string, runId: string | un
   let { run, flow } = match
   await refreshPin(connection)
   let service = createService(connection.url, connection)
-  let sent = await service('POST', `/api/m/runs/${run.record.id}/callbacks`, await encodeCallback(connection, run.record, { flowId: flow.id, url: pasted.trim() }))
+  let sent = await service('POST', `/api/v1/machine/runs/${run.record.id}/callbacks`, await encodeCallback(connection, run.record, { flowId: flow.id, url: pasted.trim() }))
   if (sent.status !== 202) return fail(messageOf(sent))
 
   let deadline = Date.now() + 30_000

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)
@@ -20,11 +20,11 @@ export async function refreshPin(connection: Connection, say: (text: string) =>
     connection.accountPublicKey = saved.accountPublicKey
     connection.accountFingerprint = saved.accountFingerprint
   }
-  let reply = await createService(connection.url, connection)<{ accountKey: { publicKey: string } | null; machine: { name: string } }>('GET', '/api/m/me', undefined, signal)
+  let reply = await createService(connection.url, connection)<{ accountKey: { publicKey: string } | null; machine: { name: string } }>('GET', '/api/v1/machine/me', undefined, signal)
   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/m/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.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
@@ -249,16 +249,16 @@ export async function createRun(connection: Connection | null, argv: string[], s
     async takeMessages(signal: AbortSignal) {
       if (!service) return []
       await refreshPin(connection!, say, signal)
-      let reply = await service<{ callbacks: { kind?: MessageKind; data: unknown }[] }>('POST', `/api/m/runs/${id}/callbacks/take`, undefined, signal)
+      let reply = await service<{ data: { kind?: MessageKind; data: unknown }[] }>('POST', `/api/v1/machine/runs/${id}/callbacks/take`, undefined, signal)
       if (reply.status === 404) throw new Error('This request expired or was dismissed.')
-      return reply.status === 200 ? reply.data.callbacks : []
+      return reply.status === 200 ? reply.data.data : []
     },
     async openMessage<T>(kind: MessageKind, value: unknown) {
       return openMessage<T>({ privateKey: key!, publicKey: connection!.publicKey, accountPublicKey: connection?.accountPublicKey, linkKey: link?.key }, kind, id, value)
     },
     async takeRetry(signal: AbortSignal) {
       if (!service) return false
-      let reply = await service<{ retry: boolean }>('POST', `/api/m/runs/${id}/retry/take`, undefined, signal)
+      let reply = await service<{ retry: boolean }>('POST', `/api/v1/machine/runs/${id}/retry/take`, undefined, signal)
       return reply.status === 200 && reply.data.retry === true
     },
     startCallbacks(onInput?: (text: string) => void) {
@@ -270,10 +270,10 @@ export async function createRun(connection: Connection | null, argv: string[], s
           await sleep(POLL_MS, undefined, { signal })
           if (!service || (!options.input && !data.flows.some((f) => f.status === 'waiting'))) continue
           await refreshPin(connection!, say, signal)
-          let reply = await service<{ callbacks: { id: string; kind?: MessageKind; data: string | CallbackData }[] }>(
-            'POST', `/api/m/runs/${id}/callbacks/take`, undefined, signal,
+          let reply = await service<{ data: { id: string; kind?: MessageKind; data: string | CallbackData }[] }>(
+            'POST', `/api/v1/machine/runs/${id}/callbacks/take`, undefined, signal,
           ).catch(() => null)
-          for (let message of reply?.status === 200 ? reply.data.callbacks : []) {
+          for (let message of reply?.status === 200 ? reply.data.data : []) {
             if (message.kind === 'input') {
               if (options.input !== true || !onInput) continue
               let input = await openMessage<InputData>({ privateKey: key!, publicKey: connection!.publicKey, accountPublicKey: connection?.accountPublicKey, linkKey: link?.key }, 'input', id, message.data)

package/cli/service.ts

@@ -2,7 +2,7 @@ import type { Connection } from './config.ts'
 
 export interface Reply<T = any> {
   status: number
-  data: T & { error?: string; message?: string }
+  data: T & { error?: string | { code: string; message: string }; message?: string }
 }
 
 export class Unreachable extends Error {}
@@ -48,5 +48,19 @@ export function createService(url: string, connection?: Pick<Connection, 'token'
 export type Service = ReturnType<typeof createService>
 
 export function messageOf(reply: Reply): string {
-  return reply.data?.error ?? reply.data?.message ?? `HTTP ${reply.status}`
+  let error = reply.data?.error
+  return (typeof error === 'string' ? error : error?.message) ?? reply.data?.message ?? `HTTP ${reply.status}`
+}
+
+/** Follow v1 cursors rather than silently truncating a machine's run history. */
+export async function listAll<T>(service: Service, path: string): Promise<Reply<{ data: T[]; nextCursor: string | null }>> {
+  let data: T[] = [], cursor: string | null = null
+  do {
+    let query: string = cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''
+    let reply: Reply<{ data: T[]; nextCursor: string | null }> = await service<{ data: T[]; nextCursor: string | null }>('GET', path + query)
+    if (reply.status !== 200) return reply
+    data.push(...reply.data.data)
+    cursor = reply.data.nextCursor
+  } while (cursor)
+  return { status: 200, data: { data, nextCursor: null } }
 }

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,27 +15,28 @@ 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/m/verifications', {
+  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')
   if (view.status !== 'answered' || !view.browserEphemeral || !view.accountPublicKey) return refused(say, view)
 
-  let revealed = await service('POST', `/api/m/verifications/${id}/reveal`, { ephemeral: own.publicKey })
+  let revealed = await service('POST', `/api/v1/machine/verifications/${id}/reveal`, { ephemeral: own.publicKey })
   if (revealed.status !== 200) throw new Error(messageOf(revealed))
   let transcript: Transcript = {
     verificationId: id,
@@ -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.')
@@ -64,9 +69,9 @@ export async function verifyMachine(connection: Connection, say: Say, timeoutMs
 
 async function waitFor(service: ReturnType<typeof createService>, id: string, deadline: number, done: (v: MachineView) => boolean) {
   while (Date.now() < deadline) {
-    let reply = await service<{ verification: MachineView }>('GET', `/api/m/verifications/${id}`).catch(() => null)
+    let reply = await service<MachineView>('GET', `/api/v1/machine/verifications/${id}`).catch(() => null)
     if (reply?.status === 404) throw new Error('This verification expired. Run localauth verify again.')
-    if (reply?.status === 200 && done(reply.data.verification)) return reply.data.verification
+    if (reply?.status === 200 && done(reply.data)) return reply.data
     await new Promise((resolve) => setTimeout(resolve, POLL_MS))
   }
   throw new Error('Nobody finished the verification in time. Run localauth verify again.')
@@ -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.1.0",
+  "version": "0.3.0",
   "description": "Finish CLI logins on a headless server from your phone, with optional passkey-based end-to-end encryption",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,11 @@
     "!cli/*.test.ts",
     "shared/*.ts",
     "!shared/*.test.ts",
+    "!shared/protocol-vectors.ts",
     "skills/localauth/SKILL.md"
   ],
   "scripts": {
+    "prepare": "patch-package",
     "dev": "DESIGN_PREVIEW=1 wrangler dev --local-upstream localhost:8787 --var DESIGN_PREVIEW:1",
     "build": "node scripts/build-client.ts",
     "deploy": "wrangler deploy",
@@ -53,17 +55,20 @@
     "remix": "^3.0.0"
   },
   "devDependencies": {
-    "@better-auth/passkey": "^1.7.10",
+    "@better-auth/api-key": "1.7.12",
+    "@better-auth/oauth-provider": "1.7.12",
+    "@better-auth/passkey": "1.7.12",
     "@cloudflare/workers-types": "^5.20261016.1",
     "@remix-run/ui": "0.12.1",
     "@simplewebauthn/browser": "^13.3.0",
     "@types/node": "^26.6.5",
-    "auth": "^1.7.10",
-    "better-auth": "^1.7.10",
+    "auth": "1.7.12",
+    "better-auth": "1.7.12",
     "drizzle-kit": "^0.31.11",
     "drizzle-orm": "^0.45.4",
     "esbuild": "^0.28.2",
     "jose": "^6.2.12",
+    "patch-package": "8.0.1",
     "playwright-core": "^1.64.1",
     "typescript": "^7.0.2",
     "wrangler": "^4.151.0"

package/shared/protocol.ts

@@ -92,7 +92,7 @@ export interface VerificationRecord {
   expiresAt: number
 }
 
-/** Response of POST /api/m/pair: what `localauth login` shows and polls with. */
+/** Response of POST /api/v1/machine/pair: what `localauth login` shows and polls with. */
 export interface PairingStart {
   deviceCode: string
   userCode: string
@@ -104,7 +104,7 @@ export interface PairingStart {
   signInFirst?: boolean
 }
 
-/** Response of POST /api/m/pair/token once approved. */
+/** Response of POST /api/v1/machine/pair/token once approved. */
 export interface PairingResult {
   token: string
   machineId: string

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/skills/localauth/SKILL.md

@@ -13,6 +13,16 @@ the user opens anywhere (localauth.dev, or their own deployment), and forwards t
 address they bring back to the waiting command. Data is encrypted at rest by default, with optional passkey-based end-to-end encryption.
 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 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 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.
+
 ## 1. Check that localauth is ready
 
 ```sh
@@ -24,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.
@@ -37,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.