@localauth/cli 0.1.0 → 0.2.0

package/README.md

@@ -156,6 +156,71 @@ 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 emoji
+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 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).
+
+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 emoji verification, account, encryption, passkey or token changes,
+sign-out or deletion. A person still compares emoji after approving an E2E machine.
+
 ## Encryption
 
 By default, any browser signed in to your account can read your logins. The Worker encrypts
@@ -257,8 +322,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 +341,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

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
@@ -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,7 +229,7 @@ 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.')
       if (!(await verifyMachine(connection, (line) => terminal.writeLine(line)))) return 1
@@ -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/encryption.ts

@@ -20,7 +20,7 @@ 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)

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

@@ -22,7 +22,7 @@ const POLL_MS = 1500
 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),
   })
   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.')
@@ -35,7 +35,7 @@ export async function verifyMachine(connection: Connection, say: Say, 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,
@@ -64,9 +64,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.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localauth/cli",
-  "version": "0.1.0",
+  "version": "0.2.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/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 emoji 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/*`;
+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