@spfn/auth 0.3.0-beta.26 → 0.3.0-beta.28

package/README.md

@@ -104,12 +104,16 @@ Import it for its side-effect (it self-registers); it must run before the proxy
 // app/api/rpc/[routeName]/route.ts
 import '@spfn/auth/nextjs/api';        // side-effect: registers auth interceptors
 import { createRpcProxy } from '@spfn/core/nextjs/server';
-import { authRouteMap } from '@spfn/auth';
 import { routeMap } from '@/generated/route-map';
 
-export const { GET, POST } = createRpcProxy({ routeMap: { ...routeMap, ...authRouteMap } });
+export const { GET, POST } = createRpcProxy({ routeMap });
 ```
 
+No auth route map is merged: the generated `routeMap` carries the routes of every package
+router the app router mounts with `.packages()`, `authRouter`'s included. `authRouteMap` is
+still exported and `{ ...routeMap, ...authRouteMap }` is still harmless — the two hold the
+same entries — but it is a no-op.
+
 ### 4. Run migrations
 
 ```bash
@@ -215,6 +219,13 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `getDeviceAuthInfo` | POST `/_auth/device/info` | yes | what device is asking, so the approval screen can show it |
 | `approveDeviceAuth` | POST `/_auth/device/approve` | yes | let the waiting device in |
 | `denyDeviceAuth` | POST `/_auth/device/deny` | yes | refuse it |
+| `issueDeviceLink` | POST `/_auth/device/link/issue` | yes | show a code a new device can come in by — see [Device link](#device-link) |
+| `redeemDeviceLink` | POST `/_auth/device/link/redeem` | public | the new device parks its key on that code and gets the match number to show |
+| `getDeviceLinkStatus` | POST `/_auth/device/link/status` | issuing key | where the link stands; the device and three numbers once redeemed |
+| `confirmDeviceLink` | POST `/_auth/device/link/confirm` | issuing key | pick the number the new device shows |
+| `denyDeviceLink` | POST `/_auth/device/link/deny` | issuing key | refuse the new device |
+| `cancelDeviceLink` | POST `/_auth/device/link/cancel` | issuing key | close the link before anyone is let in |
+| `pollDeviceLink` | POST `/_auth/device/link/poll` | public | ask whether the issuer picked; the approved answer *is* the login |
 | `passkeyRegisterOptions` | POST `/_auth/passkeys/register/options` | yes | begin enrolling a passkey — see [Passkeys](#passkeys-webauthn) |
 | `passkeyRegisterVerify` | POST `/_auth/passkeys/register/verify` | yes | verify the attestation and keep the credential |
 | `passkeyLoginOptions` | POST `/_auth/passkeys/login/options` | public | begin a passkey sign-in; takes no identifier |
@@ -499,6 +510,31 @@ const answer = await authApi.pollDeviceAuth.call({ body: { deviceCode } });
 // → { status: 'approved', userId, publicId, email?, phone?, passwordChangeRequired }
 ```
 
+Or long-poll: send `waitMillis` and the server holds a pending request until the owner
+answers or the wait runs out, so the device learns of an approval the moment it is made
+instead of at its next tick.
+
+```typescript
+let answer;
+
+do
+{
+    // Held up to 20s (the server's maxWaitMs caps it). A pending answer takes the time
+    // already waited off intervalMillis — 0 after a full wait, so ask again at once.
+    // An error ends the loop, as before.
+    answer = await authApi.pollDeviceAuth.call({ body: { deviceCode, waitMillis: 20_000 } });
+
+    if (answer.status === 'pending' && answer.intervalMillis > 0)
+    {
+        await new Promise(resolve => setTimeout(resolve, answer.intervalMillis));
+    }
+}
+while (answer.status === 'pending');
+```
+
+Keep the loop's sleep on `intervalMillis > 0`. It covers a server that answered without
+waiting — an older one that ignores the field — so the loop never spins.
+
 ```typescript
 // On the signed-in device — the user typed the code they read off the other screen.
 const asking = await authApi.getDeviceAuthInfo.call({ body: { userCode } });
@@ -553,26 +589,175 @@ two ways in are indistinguishable.
   who cannot authenticate, so `publicKey`, `keyId` and `fingerprint` carry length limits —
   generous next to a real key (an RSA-2048 SPKI is 392 base64 characters against a 2048 limit)
   and small next to the megabyte that would otherwise sit in a table no job clears.
+- **A long poll holds no transaction.** The wait is route middleware in front of the poll's
+  `Transactional()`, so a waiting device does not pin a pooled connection, and the answer is
+  judged inside the transaction exactly as a poll without `waitMillis` is — same atomicity,
+  same database-error answers. Approve, deny and a global revocation wake a poll parked in the
+  same process after they commit. A poll parked on another instance re-reads its record every
+  second, so an approval committed elsewhere reaches it within about a second. A device that
+  hangs up mid-wait is not judged, so an approval it can no longer hear waits for its next poll;
+  at most three polls wait on one code at a time — a fourth is answered at once; and a server
+  that starts shutting down ends every wait with a pending answer rather than a cut connection.
 - **Clock skew cannot affect this.** Every timestamp in the decision is the server's. The
   `expiresAtMillis` in the start response is for the waiting device's countdown display, and
   nothing the client believes about the time reaches the server's judgement.
 
-Two knobs, both announced to the waiting device in the start response and therefore resolved
-at lifecycle time rather than read per call:
+Three knobs, resolved at lifecycle time rather than read per call — the first two are
+announced to the waiting device in the start response:
 
 ```typescript
 createAuthLifecycle({
     deviceAuth: {
         ttlMs: 10 * 60 * 1000,   // how long a code lives. default 10 minutes
         intervalMs: 5000,        // poll interval the server asks for. default 5s
+        maxWaitMs: 20_000,       // longest a long poll is held. default 20s
     },
 })
 ```
 
+Keep `maxWaitMs` under the idle timeout of every proxy and load balancer in front of the
+server. A long poll cut off by one reaches the device as a network error, not as a pending
+answer — Google Cloud's load balancer closes a backend request at 30 seconds by default.
+
 No job sweeps the table. Rows are judged by `expiresAt` whenever they are read or moved, so a
 stale row authorizes nothing; it only keeps its user code out of circulation, and 31⁸ codes do
 not run out.
 
+### Device link
+
+Device-code login the other way round: the device that is already signed in shows the code,
+and the new one reads it. This is the natural way onto a phone — the signed-in device is a
+laptop with a screen, and the phone has a camera. The signed-in device (the *issuer*) asks for a
+code and shows it, as text and as a QR its own client draws. The new device reads it, sends it
+with its fresh public key, and shows a two-digit number. The issuer is shown the new device and
+three numbers, and taps the one on the new device's screen. The new device's next poll is its
+login.
+
+```typescript
+// On the signed-in device — the issuer. Every call below is signed with its key.
+const { linkId, userCode, expiresAtMillis } = await authApi.issueDeviceLink.call({});
+
+// Show `userCode` (XXXX-XXXX) as text and in a QR code, then wait for a device to use it.
+let link;
+
+do
+{
+    // Held up to 20s while nobody has redeemed the code (deviceAuth.maxWaitMs caps it).
+    link = await authApi.getDeviceLinkStatus.call({ body: { linkId, waitMillis: 20_000 } });
+}
+while (link.status === 'issued');
+// → { status: 'redeemed', deviceName?, platform?, fingerprintPrefix, redeemedAtMillis,
+//     choices: [37, 82, 15], expiresAtMillis }
+
+// Show the device and the three numbers; the person taps the one on the new device.
+await authApi.confirmDeviceLink.call({ body: { linkId, choice: tapped } });
+// or authApi.denyDeviceLink.call({ body: { linkId } }); closing the screen:
+// authApi.cancelDeviceLink.call({ body: { linkId } })
+```
+
+```typescript
+// On the new device — it has no key on file, so both calls are public.
+const { deviceCode, matchNumber, expiresAtMillis, intervalMillis } =
+    await authApi.redeemDeviceLink.call({ body: {
+        userCode,                          // read from the QR, or typed
+        publicKey, keyId, fingerprint, algorithm: 'ES256',
+        deviceName: 'Pocket phone', platform: 'ios',
+    } });
+
+// Show `matchNumber` large ("tap 37 on your computer"), then long-poll as device-code does.
+let answer;
+
+do
+{
+    answer = await authApi.pollDeviceLink.call({ body: { deviceCode, waitMillis: 20_000 } });
+
+    if (answer.status === 'pending' && answer.intervalMillis > 0)
+    {
+        await new Promise(resolve => setTimeout(resolve, answer.intervalMillis));
+    }
+}
+while (answer.status === 'pending');
+// → { status: 'approved', userId, publicId, email?, phone?, passwordChangeRequired }
+```
+
+The approved answer is the one `pollDeviceAuth` and `login` return, produced by the same
+completion — account status checks, key registration, the login event — so a client cannot tell
+which way in it took. Its key is registered under the issuer's account with channel
+`device-link` on `auth.device.registered`.
+
+| state ↓ call → | redeem | status | confirm | deny | cancel | poll |
+| --- | --- | --- | --- | --- | --- | --- |
+| issued | → redeemed | `issued` | 409 NotRedeemed | 409 NotRedeemed | → expired | — |
+| redeemed | 404 | device + `choices` | right number → approved; wrong → denied + 400 WrongMatch | → denied | → expired | `pending` |
+| approved | 404 | `approved` | 409 AlreadyHandled | 409 AlreadyHandled | 409 AlreadyHandled | login, → consumed |
+| denied | 404 | `denied` | 409 AlreadyHandled | 409 AlreadyHandled | 409 AlreadyHandled | 403 Denied |
+| consumed | 404 | `consumed` | 409 AlreadyHandled | 409 AlreadyHandled | 409 AlreadyHandled | 404 |
+| dead (TTL, cancelled, replaced, issuer signed out) | 400 Expired | 400 Expired | 400 Expired | 400 Expired | 400 Expired | 400 Expired |
+| unknown, or another key's link | 404 | 404 | 404 | 404 | 404 | 404 |
+
+Error names are `DeviceLink` + the cell: `DeviceLinkNotFoundError` (404),
+`DeviceLinkExpiredError` (400), `DeviceLinkWrongMatchError` (400), `DeviceLinkDeniedError` (403),
+`DeviceLinkNotRedeemedError` (409), `DeviceLinkAlreadyHandledError` (409). A consumed link stays
+404 to the new device after its TTL, for device-code login's reason.
+
+- **Single use.** A code is redeemed once, by one device: redeem moves the link from `issued` and
+  nowhere else, so of two devices sending the same code exactly one parks its key, and the other
+  is told the code does not exist. The approval is collected once, the same way: of two polls
+  arriving together, one registers the key and the other gets 404.
+- **Five-minute TTL.** A link code lives 5 minutes (`deviceLink.ttlMs`). Every decision uses the
+  server's clock, carried into the statement that moves the link; `expiresAtMillis` is for the
+  countdown on screen and nothing else. Issuing again from the same device expires the previous
+  link, so there is one live link per issuing key.
+- **Only the issuing key can confirm.** Status, confirm, deny and cancel are bound to the key that
+  signed `issue` — not merely the account. Another device of the same account, or another account,
+  is answered 404, exactly as for a link that never existed. The link also dies with that key: once
+  it is revoked, signed out or past its own expiry, every call on the link answers expired — and
+  confirm and the poll that registers the key re-check the issuing key inside the statement that
+  moves the link, under a lock on the key row, so a sign-out landing at the same moment is never
+  read around. A global revocation (`revoke-all`, even the kind that spares the calling device, a
+  password change, a deletion request) expires the account's links as well.
+- **The match number, and its limit, stated plainly.** Redeem answers the new device with a number
+  from 10 to 99; the issuer is shown it among two other distinct numbers, in an order fixed when the
+  code was redeemed. The number is what ties the device the issuer is looking at to the device that
+  redeemed the code: someone who read the code off the issuer's screen redeems it on a phone the
+  issuer cannot see, so the issuer has no number to match. **A person who taps without looking at
+  the new device picks the right number one time in three.** That is the whole of the odds, because
+  one wrong pick denies the link — there is no second try, and the new device is told it was refused.
+  Typing the number would be stronger; three to tap is the trade taken for a flow people finish.
+- **The new device's key is registered only after a confirm.** It is parked in
+  `spfn_auth.device_links`, not in `user_public_keys`, until the poll after the right pick moves it
+  over. A key parked on a link that was denied, cancelled, or expired can never sign anything and
+  can never be collected.
+- **A redeemed, spent or never-issued code answer alike** (`DeviceLinkNotFoundError`, 404), so a
+  guesser cannot learn a code was real. A code that died of age answers 400.
+- **Rate limits.** `issue` per account (10/min, and 50/min per IP); `redeem` and `poll` per IP
+  (10/min and 30/min); `status` per account (30/min, 150/min per IP) and `confirm` / `deny` /
+  `cancel` per account (10/min, 50/min per IP) — the device-code policies' sizes.
+- **The device code is stored only as a SHA-256 hash**, returned once, as in device-code login.
+  Nothing in the flow logs a user code, device code, match number or key.
+- **Long polls hold no transaction.** Both `status` (the issuer, while the link waits on the other
+  device) and `poll` (the new device, while it waits on the pick) take `waitMillis` and wait exactly
+  as the device-code poll does: ahead of the transaction, capped at `deviceAuth.maxWaitMs`, at most
+  three requests waiting on one link, a re-read every second for a change committed on another
+  instance, every transition waking both after commit, and a shutdown ending every wait with the
+  current answer.
+- **`redeem` bounds what it stores** exactly as `device/start` does — it is the other route that
+  takes key material from a caller who cannot authenticate.
+
+One knob of its own; the poll interval and long-poll cap are `deviceAuth`'s:
+
+```typescript
+createAuthLifecycle({
+    deviceLink: {
+        ttlMs: 5 * 60 * 1000,   // how long a link code lives. default 5 minutes
+    },
+})
+```
+
+The mobile contract carries the new device's half — `auth.deviceLink.redeem` and
+`auth.deviceLink.poll`, since contract 0.13.2. The issuer's five routes run on the signed-in
+device and are not on that surface.
+
 ### Registered devices (key management)
 
 A [passkey](#passkeys-webauthn) is **not** one of these keys: it is a credential that proves
@@ -2129,8 +2314,8 @@ whoever opened a link in a mailbox, so it is the notice to send the owner.
 
 `authDeviceRegisteredEvent` (`auth.device.registered`) fires after commit whenever a device key is
 registered on an account, on every channel that registers one — `channel` says which: `register`,
-`signup-link`, `invitation`, `password`, `oauth`, `oauth-native`, `device-code`, `password-reset`
-or `passkey`. It carries `userId`, `keyId`, `algorithm`, a 12-character `fingerprintPrefix`,
+`signup-link`, `invitation`, `password`, `oauth`, `oauth-native`, `device-code`, `device-link`,
+`password-reset` or `passkey`. It carries `userId`, `keyId`, `algorithm`, a 12-character `fingerprintPrefix`,
 `createdAtMillis`, and whatever the registration knew about the device: `deviceName?`, `platform?`,
 `ip?` and `userAgent?` — the web OAuth callback has neither label, because the sealed state does
 not carry them. Subscribe to tell the owner a device was added: a login event says a session began
@@ -2478,6 +2663,8 @@ Every operation in the exported bundle carries `since` — the contract version
 | `auth.keys.list`, `auth.keys.revoke`, `auth.keys.revokeAll` | 0.4.1 |
 | `core.time` | 0.9.0 |
 | `auth.device.start`, `auth.device.poll`, `auth.device.info`, `auth.device.approve`, `auth.device.deny` | 0.10.0 |
+| `auth.mfa.verify`, `auth.mfa.status` | 0.13.0 |
+| `auth.deviceLink.redeem`, `auth.deviceLink.poll` | 0.13.2 |
 
 - **This is history, not policy.** The mobile contract's compatibility policy is `allOrNothing`: one
   contract version passes or refuses the whole surface, so these three fields change no verdict here.
@@ -3231,9 +3418,8 @@ export type AppRouter = typeof appRouter;
 // app/api/rpc/[routeName]/route.ts
 import '@spfn/auth/nextjs/api';
 import { createRpcProxy } from '@spfn/core/nextjs/server';
-import { authRouteMap } from '@spfn/auth';
-import { routeMap } from '@/generated/route-map';
-export const { GET, POST } = createRpcProxy({ routeMap: { ...routeMap, ...authRouteMap } });
+import { routeMap } from '@/generated/route-map';   // already holds authRouter's routes
+export const { GET, POST } = createRpcProxy({ routeMap });
 
 // any client component
 import { authApi } from '@spfn/auth';

package/dist/client-proof.d.ts

@@ -398,7 +398,7 @@ declare function getClientProofReplayStore(): ClientProofReplayStore;
  */
 
 interface ContractOperation {
-    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.mfa.verify' | 'auth.mfa.status' | 'auth.keys.rotate' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll' | 'auth.device.start' | 'auth.device.poll' | 'auth.device.info' | 'auth.device.approve' | 'auth.device.deny' | typeof CORE_TIME_OPERATION_ID;
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.mfa.verify' | 'auth.mfa.status' | 'auth.keys.rotate' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll' | 'auth.device.start' | 'auth.device.poll' | 'auth.device.info' | 'auth.device.approve' | 'auth.device.deny' | 'auth.deviceLink.redeem' | 'auth.deviceLink.poll' | typeof CORE_TIME_OPERATION_ID;
     method: 'GET' | 'POST';
     path: string;
     /**
@@ -482,6 +482,13 @@ declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
  * which is what lets the server read the approving account from the caller
  * rather than from the request body.
  *
+ * Device link is device-code login's mirror image, and only the new device's
+ * half of it is here: `redeem` and `poll`, both unproven for the same reason.
+ * The issuer's five operations — issue, status, confirm, deny, cancel — are
+ * bound to the key that signed `issue`, and the device that runs them is the
+ * already-signed-in one showing a code, not the phone this contract generates
+ * a client for. They stay REST routes, as the `mfa/*` enrolment routes do.
+ *
  * `auth.mfa.verify` is unproven for the same reason the sign-ins are: the key it
  * activates is not usable until it succeeds, so there is nothing to sign the
  * call with. It is the only way to finish a sign-in that answered

package/dist/client-proof.js

@@ -1153,6 +1153,28 @@ var AUTH_SURFACE_OPERATIONS = [
     requestType: "DenyDeviceAuthRequest",
     summary: "Refuses the waiting device. Answers 204 with no body, so it names no response type.",
     since: "0.10.0"
+  },
+  {
+    id: "auth.deviceLink.redeem",
+    method: "POST",
+    path: "/_auth/device/link/redeem",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "RedeemDeviceLinkRequest",
+    responseType: "RedeemDeviceLinkResponse",
+    summary: "Parks a new device's public key on the code a signed-in device shows, and returns the match number to show.",
+    since: "0.13.2"
+  },
+  {
+    id: "auth.deviceLink.poll",
+    method: "POST",
+    path: "/_auth/device/link/poll",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "PollDeviceLinkRequest",
+    responseType: "PollDeviceAuthResponse",
+    summary: "Asks whether the issuer picked the match number; the approved answer is the login it produced.",
+    since: "0.13.2"
   }
 ];
 var ContractTypeError = class extends Error {
@@ -1419,7 +1441,7 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.13.0";
+var CONTRACT_VERSION = "0.13.2";
 var CONTRACT_MAJOR = 0;
 var CONTRACT_SUPPORTED_RANGE = ">=0.13.0 <0.14.0";
 function required(name, type) {
@@ -1754,7 +1776,8 @@ var CONTRACT_TYPES = [
   {
     name: "PollDeviceAuthRequest",
     fields: [
-      required("deviceCode", "string")
+      required("deviceCode", "string"),
+      optional("waitMillis", "integer")
     ]
   },
   /**
@@ -1815,6 +1838,39 @@ var CONTRACT_TYPES = [
     fields: [
       required("userCode", "string")
     ]
+  },
+  /**
+   * `StartDeviceAuthRequest` with the code it redeems in front: the same key
+   * material under the same bounds, since this is the other place a caller
+   * with nothing to authenticate parks a key before anyone agreed to it.
+   */
+  {
+    name: "RedeemDeviceLinkRequest",
+    fields: [
+      required("userCode", "string"),
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      optional("algorithm", "KeyAlgorithm"),
+      optional("deviceName", "string"),
+      optional("platform", "KeyPlatform")
+    ]
+  },
+  {
+    name: "RedeemDeviceLinkResponse",
+    fields: [
+      required("deviceCode", "string"),
+      required("matchNumber", "integer"),
+      required("expiresAtMillis", "integer"),
+      required("intervalMillis", "integer")
+    ]
+  },
+  {
+    name: "PollDeviceLinkRequest",
+    fields: [
+      required("deviceCode", "string"),
+      optional("waitMillis", "integer")
+    ]
   }
 ];
 var CONTRACT_ENUMS = [