@shware/security 7.1.1 → 8.0.0

package/README.md

@@ -3,8 +3,8 @@
 Session-based authentication for any server that speaks the Fetch API (`Request` → `Response`):
 Hono, Cloudflare Workers, Next.js route handlers and similar. It ships an `Auth` class with
 handlers for CSRF, logout, OAuth2 (redirect, native, Google One Tap), email verification-code
-sign-in and desktop sign-in, backed by pluggable session stores (Redis or your own database) that
-use the Spring Session key layout, so sessions can be shared with a Spring backend.
+sign-in and desktop sign-in, backed by pluggable session stores (Redis or your own database),
+indexed by principal so a user's sessions can be listed and revoked.
 
 ## Install
 
@@ -17,10 +17,10 @@ use the Redis repositories.
 
 ## Entry points
 
-| Import path                        | Contents                                                                                                         |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `@shware/security`                 | `Auth`, `PATH`, session/KV repositories, `OAuth2Client`, `OAuth2Error`, `PROVIDERS` and types                    |
-| `@shware/security/oauth2/provider` | Built-in OAuth2 providers (`apple`, `facebook`, `github`, `google`, `wechat`, `x`) and `createAppleClientSecret` |
+| Import path                        | Contents                                                                                                          |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@shware/security`                 | `Auth`, `PATH`, `AuthenticationError`, session/KV repositories, `OAuth2Client`, `OAuth2Error`, `PROVIDERS`, types |
+| `@shware/security/oauth2/provider` | Built-in OAuth2 providers (`apple`, `facebook`, `github`, `google`, `wechat`, `x`) and `createAppleClientSecret`  |
 
 ## Quick start (Hono)
 
@@ -151,6 +151,47 @@ export async function onAuthorized(
 `PROVIDERS` is the list of `Provider` values (`APPLE`, `GITHUB`, `GOOGLE`, ..., `EMAIL`, `PHONE`),
 handy for a database enum.
 
+To refuse a sign-in the handler could complete but will not, throw an `AuthenticationError` with a
+reason and, when the client needs it to act, metadata (string fields only, since it travels as URL
+parameters and JSON). The built-in reasons cover the account states every host meets:
+
+| Reason               | Metadata               | When                                                        |
+| -------------------- | ---------------------- | ----------------------------------------------------------- |
+| `ACCOUNT_DISABLED`   |                        | Banned, or closed by its owner.                             |
+| `ACCOUNT_LOCKED`     | `{ until?: string }`   | Locked for now; `until` is when it opens again, when known. |
+| `EMAIL_ALREADY_USED` | `{ provider?: string}` | The address belongs to another account; sign in with that.  |
+| `EMAIL_NOT_VERIFIED` | `{ provider?: string}` | Only verified addresses are accepted and this one is not.   |
+| `SIGNUP_DISABLED`    |                        | No new accounts: registration closed or by invitation.      |
+
+Add your own by augmenting `AuthenticationReasons`, each with the shape of its metadata; the
+constructor accepts exactly the built-in and declared reasons, and requires the metadata when one
+of its fields is required:
+
+```ts
+import { AuthenticationError } from '@shware/security';
+
+declare module '@shware/security' {
+  interface AuthenticationReasons {
+    CLOSED_BETA: { invite?: string };
+    REGION_BLOCKED: { region: string }; // required: the throw must pass it
+  }
+}
+
+throw new AuthenticationError('EMAIL_ALREADY_USED', {
+  metadata: { provider: 'GOOGLE' },
+  message: 'Email already used by another account',
+});
+```
+
+`AuthenticationReason` is the union of all reasons, for the client-side switch;
+`AUTHENTICATION_REASONS` lists the built-in ones at runtime, for a message table.
+
+`Auth` answers it in the shape of the route: the redirect flow lands on `errorUri` with
+`error=access_denied&reason=EMAIL_ALREADY_USED&provider=GOOGLE`; the JSON routes (native, One
+Tap, email) answer `403` with a google.rpc error body whose `ErrorInfo` holds the `reason` and
+`metadata` (what `@shware/http`'s `getErrorInfo` reads). Anything else the handler throws is a
+server fault: `server_error` on the redirect, rethrown to your error handler on the JSON routes.
+
 ## `Auth` options
 
 | Option               | Type                                | Notes                                                                                         |
@@ -164,7 +205,13 @@ handy for a database enum.
 | `verificationCode`   | `{ maxAttempts?, resendCooldown? }` | Email code limits: guesses per code (default 5), seconds between sends (default 60).          |
 | `timing`             | `boolean`                           | Adds a `Server-Timing` header to OAuth2 responses.                                            |
 
-The session id is read from the cookie or from an `Authorization: Bearer <session id>` header.
+The session id lives in the cookie. For clients without a cookie jar (a CLI, a desktop shell),
+`session: { header: true }` also carries it in `X-Auth-Token`, as Spring Session does: every
+response that sets the cookie answers `X-Auth-Token: <id>`, and a request without the cookie is
+read from the same header. Off by default: it exposes the id to same-origin scripts, which the
+cookie's `HttpOnly` keeps it from, and a cross-origin client needs the header in
+`Access-Control-Expose-Headers`. `Authorization` is never read: an API token is a different
+credential from a session and is not handled here.
 `logout` clears the cookie with the same attributes it was set with (`domain`, `path`, …), so a
 cookie set with `Domain=.example.com` is actually removed.
 
@@ -184,16 +231,15 @@ export async function getUserId(c: Context) {
 }
 ```
 
-Errors thrown by providers during the token exchange are `OAuth2Error` (`status`, `error`), which
-you can map to a 401 in your error handler:
+The JSON routes answer every failure they know themselves (see "Errors" below), so your error
+handler only sees genuine server faults: what `onAuthorized` or a session store threw besides an
+`AuthenticationError`. A flow of your own that calls `Auth` directly (`verifyEmailCode`) can throw
+the same errors; `errorResponse(error)` gives the response the routes would, or `null`:
 
 ```ts
-import { OAuth2Error } from '@shware/security';
+import { errorResponse } from '@shware/security';
 
-app.onError((error, c) => {
-  if (error instanceof OAuth2Error) return c.json({ error: error.error }, 401);
-  throw error;
-});
+app.onError((error, c) => errorResponse(error) ?? yourErrorHandler(error, c));
 ```
 
 ## Session repositories
@@ -201,9 +247,8 @@ app.onError((error, c) => {
 All repositories implement `SessionRepository` and index sessions by principal name
 (`PRINCIPAL_NAME_INDEX_NAME`), so `kick` and `listSessions` work.
 
-- `RedisIndexedSessionRepository(redis, namespace = 'spring:session')`: Spring Session's Redis
-  indexed layout (`<namespace>:sessions:<id>` hashes, a principal index set, and an expirations
-  sorted set). Takes an `ioredis` client.
+- `RedisIndexedSessionRepository(redis, namespace = 'app:session')`: `<namespace>:sessions:<id>`
+  hashes, a principal index set, and an expirations sorted set. Takes an `ioredis` client.
 - `DBIndexedSessionRepository(adapter)`: for any database; you implement `DBAdapter`
   (`save`, `deleteById`, `findById`, `findByPrincipalName`, `cleanupExpiredSessions`).
 - `RedisKVRepository(redis)`: `KVRepository` on Redis. Implement `KVRepository`
@@ -335,6 +380,8 @@ Every failure of the callback lands on `errorUri` — never a raw JSON error in
   `console.warn` and reported by code only: `invalid_grant` (an expired or reused code),
   `access_denied` or `temporarily_unavailable` as is, any other as `server_error`. Its message
   stays in the logs, since it can name a client id or quote a provider's response;
+- an `AuthenticationError` thrown by `onAuthorized` as `access_denied` with its `reason` and
+  metadata entries as parameters (logged with `console.warn`; see "The `onAuthorized` handler");
 - anything else thrown by the exchange, `onAuthorized` or the session store, as `server_error`
   (logged with `console.error`).
 
@@ -413,7 +460,7 @@ Android any app can register the same scheme and receive the code. The app:
 4. posts `code_verifier` with the `code` to `/login/oauth2/native/:provider`.
 
 `loginOAuth2Native` hands `code_verifier` to the provider's token exchange (Google refuses the
-code without the matching verifier) and answers `400 invalid_request` when it is not 43-128
+code without the matching verifier) and answers `400 INVALID_CODE_VERIFIER` when it is not 43-128
 unreserved characters. Providers whose token endpoint takes no verifier (Apple) leave it out.
 Without `code_verifier` the exchange runs as before. With expo-crypto and expo-web-browser:
 
@@ -470,7 +517,7 @@ A `credential` must carry a nonce: fetch one from `GET /oauth2/nonce/google` (`o
 10 minutes) right before `prompt` and pass it on, so Google writes it into the ID token's `nonce`
 claim. The login consumes the nonce, so a leaked ID token cannot be replayed for another session; a
 credential without one, or with one that was not issued or was already used, is answered
-`401 invalid_request` (`nonce missing` / `nonce mismatch`). The nonce takes the place of Google's
+`403 NONCE_MISSING` / `403 NONCE_MISMATCH`. The nonce takes the place of Google's
 `g_csrf_token` double-submit cookie, which FedCM mode no longer sets. A `code` (the popup fallback)
 is single use already and needs no nonce.
 
@@ -515,6 +562,15 @@ app.post(PATH.LOGIN_EMAIL, (c) => auth.loginEmail(c.req.raw, onAuthorized));
 ```
 
 - `POST /auth/sendEmailVerificationCode` with `{ email, turnstileToken }`.
+- `auth.verifyEmailCode(email, code)` spends a mailed code without signing in, for a host flow that
+  only needs proof of the address (a signed-in user verifying or changing their email). Same
+  storage and limits as `loginEmail`; a wrong code throws the `AuthenticationError` `loginEmail`
+  would answer with (`INVALID_VERIFICATION_CODE`, `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`), so
+  letting it propagate to an error handler that maps `AuthenticationError` answers the same 403.
+- `claims.email_verified` is set only by providers that state it (Google, Apple, GitHub, and X
+  when it returns `confirmed_email`); Facebook leaves it unset. Trust an address only when it is
+  `true`. X hands out the address only with the `users.email` scope (in the default scope) and
+  "Request email from users" enabled on the app in the X developer console.
 - `POST /login/email` with `{ email, verificationCode }`. On success `onAuthorized` is called with
   `provider: 'EMAIL'`, claims `{ sub: email, email, email_verified: true }` and no `token`.
 
@@ -524,20 +580,44 @@ resend cooldown, and the claims' `sub` and `email`. The local part is lowercased
 mailboxes are allowed by RFC 5321 but practically unused, and honouring them would let one mailbox
 hold several accounts.
 
-Error reasons (`google.rpc.ErrorInfo`), all `400 INVALID_ARGUMENT` unless noted:
+Error reasons (`google.rpc.ErrorInfo`, see "Errors"):
 
-| Reason                                | When                                                                              |
-| ------------------------------------- | --------------------------------------------------------------------------------- |
-| `TURNSTILE_VERIFICATION_FAILED`       | The Turnstile token was rejected.                                                 |
-| `VERIFICATION_CODE_RESEND_TOO_SOON`   | `429 RESOURCE_EXHAUSTED`: a code was sent to this email within `resendCooldown`.  |
-| `EMAIL_DELIVERY_FAILED`               | The sender threw; the cooldown is released, so the user can retry at once.        |
-| `INVALID_VERIFICATION_CODE`           | Wrong code, or no code is pending for this email.                                 |
-| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | More than `maxAttempts` guesses at this code; it is discarded, ask for a new one. |
+| Reason                                | Status                   | When                                                                              |
+| ------------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
+| `TURNSTILE_VERIFICATION_FAILED`       | `400 INVALID_ARGUMENT`   | The Turnstile token was rejected.                                                 |
+| `VERIFICATION_CODE_RESEND_TOO_SOON`   | `429 RESOURCE_EXHAUSTED` | A code was sent to this email within `resendCooldown`.                            |
+| `EMAIL_DELIVERY_FAILED`               | `503 UNAVAILABLE`        | The sender threw; the cooldown is released, so the user can retry at once.        |
+| `INVALID_VERIFICATION_CODE`           | `403 PERMISSION_DENIED`  | Wrong code, or no code is pending for this email.                                 |
+| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `403 PERMISSION_DENIED`  | More than `maxAttempts` guesses at this code; it is discarded, ask for a new one. |
 
 Every login attempt against a pending code is counted before the code is compared, so parallel
 requests cannot exceed `maxAttempts` guesses either. A new code starts with a fresh budget.
 
-`sendPhoneVerificationCode` and `loginPhone` exist but currently answer `501 not_implemented`.
+## Errors
+
+The JSON routes (native, One Tap, email, desktop) answer every failure with a google.rpc error
+body, the shape `@shware/http`'s `getErrorInfo` reads: `{ error: { code, status, message, details:
+[{ '@type': '…google.rpc.ErrorInfo', reason, metadata? }] } }`. Branch on `reason`; the status
+tells the kind:
+
+| Status                   | What                                                                                                                                                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `400 INVALID_ARGUMENT`   | The request itself: a body that is not JSON (`INVALID_JSON`), a wrong content type, a field that failed validation (`INVALID_ARGUMENT` with a `BadRequest` detail naming it), `INVALID_ATTRIBUTES`, `INVALID_CODE_VERIFIER`.               |
+| `401 UNAUTHENTICATED`    | `desktopAuthorize` without a signed-in session.                                                                                                                                                                                            |
+| `403 PERMISSION_DENIED`  | An `AuthenticationError`: the host refused the sign-in (see "The `onAuthorized` handler"), or the SDK did (`INVALID_VERIFICATION_CODE`, `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`, `NONCE_MISSING`, `NONCE_MISMATCH`, `INVALID_DESKTOP_CODE`). |
+| `429 RESOURCE_EXHAUSTED` | `VERIFICATION_CODE_RESEND_TOO_SOON`.                                                                                                                                                                                                       |
+| `503 UNAVAILABLE`        | `EMAIL_DELIVERY_FAILED`, or the provider is down.                                                                                                                                                                                          |
+
+An `OAuth2Error` from the provider client is answered by what it means, with `OAUTH2_<error>` as
+the reason: `OAUTH2_INVALID_REQUEST` and the other malformed-request codes as `400`,
+`OAUTH2_INVALID_GRANT` (a code or id token that is expired, used, or for another client or
+issuer), `OAUTH2_INVALID_CLIENT`, `OAUTH2_INVALID_TOKEN`, `OAUTH2_ACCESS_DENIED` as `403`,
+`OAUTH2_SERVER_ERROR` and `OAUTH2_TEMPORARILY_UNAVAILABLE` as `503`. Its message stays in the logs:
+it can name a client id or quote the provider's response.
+
+Anything else thrown (by `onAuthorized`, a session store, a sender) propagates to your error
+handler as the server fault it is. The redirect flow is the exception to all of this: a page, not
+a client, reads its outcome, so it lands on `errorUri` with `error=…` (see "Redirect flow").
 
 ## Routes (`PATH`)
 
@@ -556,9 +636,7 @@ its own constant.
 | `LOGIN_OAUTH2_NATIVE`          | `/login/oauth2/native/:provider`  | `loginOAuth2Native`                               |
 | `LOGIN_OAUTH2_ONETAP`          | `/login/oauth2/onetap/google`     | `loginOAuth2Onetap`                               |
 | `LOGIN_EMAIL`                  | `/login/email`                    | `loginEmail`                                      |
-| `LOGIN_PHONE`                  | `/login/phone`                    | `loginPhone` (not implemented)                    |
 | `SEND_EMAIL_VERIFICATION_CODE` | `/auth/sendEmailVerificationCode` | `sendEmailVerificationCode`                       |
-| `SEND_PHONE_VERIFICATION_CODE` | `/auth/sendPhoneVerificationCode` | `sendPhoneVerificationCode` (not implemented)     |
 | `DESKTOP_AUTHORIZE`            | `/auth/desktop/authorize`         | `desktopAuthorize`                                |
 | `DESKTOP_EXCHANGE`             | `/auth/desktop/exchange`          | `desktopExchange`                                 |
 | `CLEANUP_EXPIRED_SESSIONS`     | `/sessions/expired/cleanup`       | `cleanupExpiredSessions`                          |

package/dist/auth/attributes.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_respond = require("./respond.cjs");
 let zod_mini = require("zod/mini");
 // src/auth/attributes.ts
 /** Upper bound on serialized attributes: they ride in a session or a request body. */
@@ -13,13 +14,13 @@ function attributesSize(attributes) {
 */
 const attributesSchema = (0, zod_mini.optional)((0, zod_mini.record)((0, zod_mini.string)(), (0, zod_mini.string)()).check((0, zod_mini.refine)((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, { message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes` })));
 /**
-* Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when
-* present but invalid.
+* The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but
+* not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.
 */
 function bodyAttributes(body) {
 	const value = typeof body === "object" && body !== null && "attributes" in body ? body.attributes : void 0;
 	const parsed = attributesSchema.safeParse(value);
-	if (!parsed.success) return null;
+	if (!parsed.success) throw require_auth_respond.invalidArgument("INVALID_ATTRIBUTES", `attributes must map strings to strings, at most ${MAX_ATTRIBUTES_BYTES} bytes`);
 	return parsed.data ?? {};
 }
 exports.MAX_ATTRIBUTES_BYTES = MAX_ATTRIBUTES_BYTES;

package/dist/auth/attributes.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.cjs","names":["optional","record","string","refine"],"sources":["../../src/auth/attributes.ts"],"sourcesContent":["import { optional, record, refine, string } from 'zod/mini';\n\n/** Upper bound on serialized attributes: they ride in a session or a request body. */\nexport const MAX_ATTRIBUTES_BYTES = 2048;\n\nexport function attributesSize(attributes: Record<string, string>) {\n  return new TextEncoder().encode(JSON.stringify(attributes)).length;\n}\n\n/**\n * The optional `attributes` field of a login body (native, One Tap, email): string values only,\n * at most `MAX_ATTRIBUTES_BYTES` serialized. Sent by the client itself, so a bad one is the\n * client's error (400), unlike oversized attributes passed to `oauth2Authorization` by the host.\n */\nexport const attributesSchema = optional(\n  record(string(), string()).check(\n    refine((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, {\n      message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes`,\n    })\n  )\n);\n\n/**\n * Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when\n * present but invalid.\n */\nexport function bodyAttributes(body: unknown): Record<string, string> | null {\n  const value =\n    typeof body === 'object' && body !== null && 'attributes' in body ? body.attributes : undefined;\n  const parsed = attributesSchema.safeParse(value);\n  if (!parsed.success) return null;\n  return parsed.data ?? {};\n}\n"],"mappings":";;;;AAGA,MAAa,uBAAuB;AAEpC,SAAgB,eAAe,YAAoC;CACjE,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,UAAU,CAAC,CAAC,CAAC;AAC9D;;;;;;AAOA,MAAa,oBAAA,GAAmBA,SAAAA,SAAAA,EAAAA,GAC9BC,SAAAA,OAAAA,EAAAA,GAAOC,SAAAA,OAAAA,CAAO,IAAA,GAAGA,SAAAA,OAAAA,CAAO,CAAC,CAAC,CAAC,OAAA,GACzBC,SAAAA,OAAAA,EAAQ,UAAU,eAAe,KAAK,KAAK,sBAAsB,EAC/D,SAAS,8BAA8B,qBAAqB,QAC9D,CAAC,CACH,CACF;;;;;AAMA,SAAgB,eAAe,MAA8C;CAC3E,MAAM,QACJ,OAAO,SAAS,YAAY,SAAS,QAAQ,gBAAgB,OAAO,KAAK,aAAa,KAAA;CACxF,MAAM,SAAS,iBAAiB,UAAU,KAAK;CAC/C,IAAI,CAAC,OAAO,SAAS,OAAO;CAC5B,OAAO,OAAO,QAAQ,CAAC;AACzB"}
+{"version":3,"file":"attributes.cjs","names":["optional","record","string","refine","invalidArgument"],"sources":["../../src/auth/attributes.ts"],"sourcesContent":["import { optional, record, refine, string } from 'zod/mini';\nimport { invalidArgument } from './respond';\n\n/** Upper bound on serialized attributes: they ride in a session or a request body. */\nexport const MAX_ATTRIBUTES_BYTES = 2048;\n\nexport function attributesSize(attributes: Record<string, string>) {\n  return new TextEncoder().encode(JSON.stringify(attributes)).length;\n}\n\n/**\n * The optional `attributes` field of a login body (native, One Tap, email): string values only,\n * at most `MAX_ATTRIBUTES_BYTES` serialized. Sent by the client itself, so a bad one is the\n * client's error (400), unlike oversized attributes passed to `oauth2Authorization` by the host.\n */\nexport const attributesSchema = optional(\n  record(string(), string()).check(\n    refine((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, {\n      message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes`,\n    })\n  )\n);\n\n/**\n * The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but\n * not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.\n */\nexport function bodyAttributes(body: unknown): Record<string, string> {\n  const value =\n    typeof body === 'object' && body !== null && 'attributes' in body ? body.attributes : undefined;\n  const parsed = attributesSchema.safeParse(value);\n  if (!parsed.success) {\n    throw invalidArgument(\n      'INVALID_ATTRIBUTES',\n      `attributes must map strings to strings, at most ${MAX_ATTRIBUTES_BYTES} bytes`\n    );\n  }\n  return parsed.data ?? {};\n}\n"],"mappings":";;;;;AAIA,MAAa,uBAAuB;AAEpC,SAAgB,eAAe,YAAoC;CACjE,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,UAAU,CAAC,CAAC,CAAC;AAC9D;;;;;;AAOA,MAAa,oBAAA,GAAmBA,SAAAA,SAAAA,EAAAA,GAC9BC,SAAAA,OAAAA,EAAAA,GAAOC,SAAAA,OAAAA,CAAO,IAAA,GAAGA,SAAAA,OAAAA,CAAO,CAAC,CAAC,CAAC,OAAA,GACzBC,SAAAA,OAAAA,EAAQ,UAAU,eAAe,KAAK,KAAK,sBAAsB,EAC/D,SAAS,8BAA8B,qBAAqB,QAC9D,CAAC,CACH,CACF;;;;;AAMA,SAAgB,eAAe,MAAuC;CACpE,MAAM,QACJ,OAAO,SAAS,YAAY,SAAS,QAAQ,gBAAgB,OAAO,KAAK,aAAa,KAAA;CACxF,MAAM,SAAS,iBAAiB,UAAU,KAAK;CAC/C,IAAI,CAAC,OAAO,SACV,MAAMC,qBAAAA,gBACJ,sBACA,mDAAmD,qBAAqB,OAC1E;CAEF,OAAO,OAAO,QAAQ,CAAC;AACzB"}

package/dist/auth/attributes.d.cts

@@ -8,8 +8,8 @@ export declare function attributesSize(attributes: Record<string, string>): numb
  */
 export declare const attributesSchema: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniRecord<import("zod/mini").ZodMiniString<string>, import("zod/mini").ZodMiniString<string>>>;
 /**
- * Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when
- * present but invalid.
+ * The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but
+ * not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.
  */
-export declare function bodyAttributes(body: unknown): Record<string, string> | null;
+export declare function bodyAttributes(body: unknown): Record<string, string>;
 //# sourceMappingURL=attributes.d.cts.map

package/dist/auth/attributes.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.d.cts","names":[],"sources":["../../src/auth/attributes.ts"],"mappings":";qBAGa;wBAEG,eAAe,YAAY;;;;;;qBAS9B,qCAAgB,mCAAA,iCAAA,0CAAA;;;;;wBAYb,eAAe,gBAAgB"}
+{"version":3,"file":"attributes.d.cts","names":[],"sources":["../../src/auth/attributes.ts"],"mappings":";qBAIa;wBAEG,eAAe,YAAY;;;;;;qBAS9B,qCAAgB,mCAAA,iCAAA,0CAAA;;;;;wBAYb,eAAe,gBAAgB"}

package/dist/auth/attributes.d.mts

@@ -8,8 +8,8 @@ export declare function attributesSize(attributes: Record<string, string>): numb
  */
 export declare const attributesSchema: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniRecord<import("zod/mini").ZodMiniString<string>, import("zod/mini").ZodMiniString<string>>>;
 /**
- * Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when
- * present but invalid.
+ * The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but
+ * not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.
  */
-export declare function bodyAttributes(body: unknown): Record<string, string> | null;
+export declare function bodyAttributes(body: unknown): Record<string, string>;
 //# sourceMappingURL=attributes.d.mts.map

package/dist/auth/attributes.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.d.mts","names":[],"sources":["../../src/auth/attributes.ts"],"mappings":";qBAGa;wBAEG,eAAe,YAAY;;;;;;qBAS9B,qCAAgB,mCAAA,iCAAA,0CAAA;;;;;wBAYb,eAAe,gBAAgB"}
+{"version":3,"file":"attributes.d.mts","names":[],"sources":["../../src/auth/attributes.ts"],"mappings":";qBAIa;wBAEG,eAAe,YAAY;;;;;;qBAS9B,qCAAgB,mCAAA,iCAAA,0CAAA;;;;;wBAYb,eAAe,gBAAgB"}

package/dist/auth/attributes.mjs

@@ -1,3 +1,4 @@
+import { invalidArgument } from "./respond.mjs";
 import { optional, record, refine, string } from "zod/mini";
 // src/auth/attributes.ts
 /** Upper bound on serialized attributes: they ride in a session or a request body. */
@@ -12,13 +13,13 @@ function attributesSize(attributes) {
 */
 const attributesSchema = optional(record(string(), string()).check(refine((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, { message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes` })));
 /**
-* Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when
-* present but invalid.
+* The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but
+* not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.
 */
 function bodyAttributes(body) {
 	const value = typeof body === "object" && body !== null && "attributes" in body ? body.attributes : void 0;
 	const parsed = attributesSchema.safeParse(value);
-	if (!parsed.success) return null;
+	if (!parsed.success) throw invalidArgument("INVALID_ATTRIBUTES", `attributes must map strings to strings, at most ${MAX_ATTRIBUTES_BYTES} bytes`);
 	return parsed.data ?? {};
 }
 export { MAX_ATTRIBUTES_BYTES, attributesSchema, attributesSize, bodyAttributes };

package/dist/auth/attributes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.mjs","names":[],"sources":["../../src/auth/attributes.ts"],"sourcesContent":["import { optional, record, refine, string } from 'zod/mini';\n\n/** Upper bound on serialized attributes: they ride in a session or a request body. */\nexport const MAX_ATTRIBUTES_BYTES = 2048;\n\nexport function attributesSize(attributes: Record<string, string>) {\n  return new TextEncoder().encode(JSON.stringify(attributes)).length;\n}\n\n/**\n * The optional `attributes` field of a login body (native, One Tap, email): string values only,\n * at most `MAX_ATTRIBUTES_BYTES` serialized. Sent by the client itself, so a bad one is the\n * client's error (400), unlike oversized attributes passed to `oauth2Authorization` by the host.\n */\nexport const attributesSchema = optional(\n  record(string(), string()).check(\n    refine((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, {\n      message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes`,\n    })\n  )\n);\n\n/**\n * Reads `attributes` off a login body without trusting its shape: `{}` when absent, `null` when\n * present but invalid.\n */\nexport function bodyAttributes(body: unknown): Record<string, string> | null {\n  const value =\n    typeof body === 'object' && body !== null && 'attributes' in body ? body.attributes : undefined;\n  const parsed = attributesSchema.safeParse(value);\n  if (!parsed.success) return null;\n  return parsed.data ?? {};\n}\n"],"mappings":";;;AAGA,MAAa,uBAAuB;AAEpC,SAAgB,eAAe,YAAoC;CACjE,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,UAAU,CAAC,CAAC,CAAC;AAC9D;;;;;;AAOA,MAAa,mBAAmB,SAC9B,OAAO,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,MACzB,QAAQ,UAAU,eAAe,KAAK,KAAK,sBAAsB,EAC/D,SAAS,8BAA8B,qBAAqB,QAC9D,CAAC,CACH,CACF;;;;;AAMA,SAAgB,eAAe,MAA8C;CAC3E,MAAM,QACJ,OAAO,SAAS,YAAY,SAAS,QAAQ,gBAAgB,OAAO,KAAK,aAAa,KAAA;CACxF,MAAM,SAAS,iBAAiB,UAAU,KAAK;CAC/C,IAAI,CAAC,OAAO,SAAS,OAAO;CAC5B,OAAO,OAAO,QAAQ,CAAC;AACzB"}
+{"version":3,"file":"attributes.mjs","names":[],"sources":["../../src/auth/attributes.ts"],"sourcesContent":["import { optional, record, refine, string } from 'zod/mini';\nimport { invalidArgument } from './respond';\n\n/** Upper bound on serialized attributes: they ride in a session or a request body. */\nexport const MAX_ATTRIBUTES_BYTES = 2048;\n\nexport function attributesSize(attributes: Record<string, string>) {\n  return new TextEncoder().encode(JSON.stringify(attributes)).length;\n}\n\n/**\n * The optional `attributes` field of a login body (native, One Tap, email): string values only,\n * at most `MAX_ATTRIBUTES_BYTES` serialized. Sent by the client itself, so a bad one is the\n * client's error (400), unlike oversized attributes passed to `oauth2Authorization` by the host.\n */\nexport const attributesSchema = optional(\n  record(string(), string()).check(\n    refine((value) => attributesSize(value) <= MAX_ATTRIBUTES_BYTES, {\n      message: `attributes must be at most ${MAX_ATTRIBUTES_BYTES} bytes`,\n    })\n  )\n);\n\n/**\n * The optional `attributes` of a login body (native): `{}` when absent, a 400 when present but\n * not strings-to-strings within `MAX_ATTRIBUTES_BYTES`.\n */\nexport function bodyAttributes(body: unknown): Record<string, string> {\n  const value =\n    typeof body === 'object' && body !== null && 'attributes' in body ? body.attributes : undefined;\n  const parsed = attributesSchema.safeParse(value);\n  if (!parsed.success) {\n    throw invalidArgument(\n      'INVALID_ATTRIBUTES',\n      `attributes must map strings to strings, at most ${MAX_ATTRIBUTES_BYTES} bytes`\n    );\n  }\n  return parsed.data ?? {};\n}\n"],"mappings":";;;;AAIA,MAAa,uBAAuB;AAEpC,SAAgB,eAAe,YAAoC;CACjE,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,UAAU,CAAC,CAAC,CAAC;AAC9D;;;;;;AAOA,MAAa,mBAAmB,SAC9B,OAAO,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,MACzB,QAAQ,UAAU,eAAe,KAAK,KAAK,sBAAsB,EAC/D,SAAS,8BAA8B,qBAAqB,QAC9D,CAAC,CACH,CACF;;;;;AAMA,SAAgB,eAAe,MAAuC;CACpE,MAAM,QACJ,OAAO,SAAS,YAAY,SAAS,QAAQ,gBAAgB,OAAO,KAAK,aAAa,KAAA;CACxF,MAAM,SAAS,iBAAiB,UAAU,KAAK;CAC/C,IAAI,CAAC,OAAO,SACV,MAAM,gBACJ,sBACA,mDAAmD,qBAAqB,OAC1E;CAEF,OAAO,OAAO,QAAQ,CAAC;AACzB"}

package/dist/auth/desktop-codes.cjs

@@ -0,0 +1,57 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_error = require("./error.cjs");
+let node_crypto = require("node:crypto");
+// src/auth/desktop-codes.ts
+/** Seconds a desktop sign-in code may be redeemed within. */
+const DESKTOP_CODE_TTL = 300;
+/**
+* The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in
+* web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the
+* matching `code_verifier`, and nothing else ever travels over the loopback.
+*/
+var DesktopCodes = class {
+	kv;
+	constructor(kv) {
+		this.kv = kv;
+	}
+	key(code) {
+		return `desktop:code:${code}`;
+	}
+	async issue(principal, codeChallenge) {
+		const code = (0, node_crypto.randomUUID)();
+		const record = {
+			principal,
+			code_challenge: codeChallenge
+		};
+		await this.kv.setItem(this.key(code), JSON.stringify(record), 300);
+		return code;
+	}
+	/**
+	* The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one
+	* that is unknown, expired, already used, or whose verifier does not hash to its challenge. A
+	* verifier mismatch does not burn the code: that would let an attacker who races a network
+	* retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is
+	* infeasible.
+	*/
+	async redeem(code, codeVerifier) {
+		const key = this.key(code);
+		const raw = await this.kv.getItem(key);
+		if (typeof raw !== "string") throw new require_auth_error.AuthenticationError("INVALID_DESKTOP_CODE");
+		let record;
+		try {
+			record = JSON.parse(raw);
+		} catch {
+			await this.kv.removeItem(key);
+			throw new require_auth_error.AuthenticationError("INVALID_DESKTOP_CODE");
+		}
+		const computed = (0, node_crypto.createHash)("sha256").update(codeVerifier).digest();
+		const stored = Buffer.from(record.code_challenge, "base64url");
+		if (stored.length !== computed.length || !(0, node_crypto.timingSafeEqual)(computed, stored)) throw new require_auth_error.AuthenticationError("INVALID_DESKTOP_CODE");
+		await this.kv.removeItem(key);
+		return record.principal;
+	}
+};
+exports.DESKTOP_CODE_TTL = DESKTOP_CODE_TTL;
+exports.DesktopCodes = DesktopCodes;
+
+//# sourceMappingURL=desktop-codes.cjs.map

package/dist/auth/desktop-codes.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-codes.cjs","names":["randomUUID","AuthenticationError","createHash","timingSafeEqual"],"sources":["../../src/auth/desktop-codes.ts"],"sourcesContent":["import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';\nimport type { Principal } from '../core/index';\nimport type { KVRepository } from '../session/types';\nimport { AuthenticationError } from './error';\n\n/** Seconds a desktop sign-in code may be redeemed within. */\nexport const DESKTOP_CODE_TTL = 5 * 60;\n\ninterface DesktopCodeRecord {\n  /** Who the web session that issued the code is signed in as. */\n  principal: Principal;\n  /** The S256 `code_challenge` the desktop sent; the verifier it redeems with must hash to it. */\n  code_challenge: string;\n}\n\n/**\n * The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in\n * web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the\n * matching `code_verifier`, and nothing else ever travels over the loopback.\n */\nexport class DesktopCodes {\n  private readonly kv: KVRepository;\n\n  constructor(kv: KVRepository) {\n    this.kv = kv;\n  }\n\n  private key(code: string) {\n    return `desktop:code:${code}`;\n  }\n\n  async issue(principal: Principal, codeChallenge: string): Promise<string> {\n    const code = randomUUID();\n    const record: DesktopCodeRecord = { principal, code_challenge: codeChallenge };\n    await this.kv.setItem(this.key(code), JSON.stringify(record), DESKTOP_CODE_TTL);\n    return code;\n  }\n\n  /**\n   * The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one\n   * that is unknown, expired, already used, or whose verifier does not hash to its challenge. A\n   * verifier mismatch does not burn the code: that would let an attacker who races a network\n   * retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is\n   * infeasible.\n   */\n  async redeem(code: string, codeVerifier: string): Promise<Principal> {\n    const key = this.key(code);\n    const raw = await this.kv.getItem(key);\n    if (typeof raw !== 'string') throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    let record: DesktopCodeRecord;\n    try {\n      record = JSON.parse(raw) as DesktopCodeRecord;\n    } catch {\n      await this.kv.removeItem(key);\n      throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    }\n    const computed = createHash('sha256').update(codeVerifier).digest();\n    const stored = Buffer.from(record.code_challenge, 'base64url');\n    if (stored.length !== computed.length || !timingSafeEqual(computed, stored)) {\n      throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    }\n    // Removed before the caller creates a session, so a concurrent duplicate exchange (a retry\n    // after a timeout) sees the code as consumed even if the session save races it.\n    await this.kv.removeItem(key);\n    return record.principal;\n  }\n}\n"],"mappings":";;;;;AAMA,MAAa,mBAAmB;;;;;;AAchC,IAAa,eAAb,MAA0B;CACxB;CAEA,YAAY,IAAkB;EAC5B,KAAK,KAAK;CACZ;CAEA,IAAY,MAAc;EACxB,OAAO,gBAAgB;CACzB;CAEA,MAAM,MAAM,WAAsB,eAAwC;EACxE,MAAM,QAAA,GAAOA,YAAAA,WAAAA,CAAW;EACxB,MAAM,SAA4B;GAAE;GAAW,gBAAgB;EAAc;EAC7E,MAAM,KAAK,GAAG,QAAQ,KAAK,IAAI,IAAI,GAAG,KAAK,UAAU,MAAM,GAAA,GAAmB;EAC9E,OAAO;CACT;;;;;;;;CASA,MAAM,OAAO,MAAc,cAA0C;EACnE,MAAM,MAAM,KAAK,IAAI,IAAI;EACzB,MAAM,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG;EACrC,IAAI,OAAO,QAAQ,UAAU,MAAM,IAAIC,mBAAAA,oBAAoB,sBAAsB;EACjF,IAAI;EACJ,IAAI;GACF,SAAS,KAAK,MAAM,GAAG;EACzB,QAAQ;GACN,MAAM,KAAK,GAAG,WAAW,GAAG;GAC5B,MAAM,IAAIA,mBAAAA,oBAAoB,sBAAsB;EACtD;EACA,MAAM,YAAA,GAAWC,YAAAA,WAAAA,CAAW,QAAQ,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,OAAO;EAClE,MAAM,SAAS,OAAO,KAAK,OAAO,gBAAgB,WAAW;EAC7D,IAAI,OAAO,WAAW,SAAS,UAAU,EAAA,GAACC,YAAAA,gBAAAA,CAAgB,UAAU,MAAM,GACxE,MAAM,IAAIF,mBAAAA,oBAAoB,sBAAsB;EAItD,MAAM,KAAK,GAAG,WAAW,GAAG;EAC5B,OAAO,OAAO;CAChB;AACF"}

package/dist/auth/desktop-codes.d.cts

@@ -0,0 +1,24 @@
+import { Principal } from "../core/index.cjs";
+import { KVRepository } from "../session/types.cjs";
+/** Seconds a desktop sign-in code may be redeemed within. */
+export declare const DESKTOP_CODE_TTL: number;
+/**
+ * The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in
+ * web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the
+ * matching `code_verifier`, and nothing else ever travels over the loopback.
+ */
+export declare class DesktopCodes {
+  private readonly kv;
+  constructor(kv: KVRepository);
+  private key;
+  issue(principal: Principal, codeChallenge: string): Promise<string>;
+  /**
+   * The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one
+   * that is unknown, expired, already used, or whose verifier does not hash to its challenge. A
+   * verifier mismatch does not burn the code: that would let an attacker who races a network
+   * retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is
+   * infeasible.
+   */
+  redeem(code: string, codeVerifier: string): Promise<Principal>;
+}
+//# sourceMappingURL=desktop-codes.d.cts.map

package/dist/auth/desktop-codes.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-codes.d.cts","names":[],"sources":["../../src/auth/desktop-codes.ts"],"mappings":";;;qBAMa;;;;;;qBAcA;mBACM;EAEjB,YAAY,IAAI;UAIR;EAIF,MAAM,WAAW,WAAW,wBAAwB;;;;;;;;EAcpD,OAAO,cAAc,uBAAuB,QAAQ"}

package/dist/auth/desktop-codes.d.mts

@@ -0,0 +1,24 @@
+import { Principal } from "../core/index.mjs";
+import { KVRepository } from "../session/types.mjs";
+/** Seconds a desktop sign-in code may be redeemed within. */
+export declare const DESKTOP_CODE_TTL: number;
+/**
+ * The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in
+ * web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the
+ * matching `code_verifier`, and nothing else ever travels over the loopback.
+ */
+export declare class DesktopCodes {
+  private readonly kv;
+  constructor(kv: KVRepository);
+  private key;
+  issue(principal: Principal, codeChallenge: string): Promise<string>;
+  /**
+   * The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one
+   * that is unknown, expired, already used, or whose verifier does not hash to its challenge. A
+   * verifier mismatch does not burn the code: that would let an attacker who races a network
+   * retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is
+   * infeasible.
+   */
+  redeem(code: string, codeVerifier: string): Promise<Principal>;
+}
+//# sourceMappingURL=desktop-codes.d.mts.map

package/dist/auth/desktop-codes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-codes.d.mts","names":[],"sources":["../../src/auth/desktop-codes.ts"],"mappings":";;;qBAMa;;;;;;qBAcA;mBACM;EAEjB,YAAY,IAAI;UAIR;EAIF,MAAM,WAAW,WAAW,wBAAwB;;;;;;;;EAcpD,OAAO,cAAc,uBAAuB,QAAQ"}

package/dist/auth/desktop-codes.mjs

@@ -0,0 +1,55 @@
+import { AuthenticationError } from "./error.mjs";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+// src/auth/desktop-codes.ts
+/** Seconds a desktop sign-in code may be redeemed within. */
+const DESKTOP_CODE_TTL = 300;
+/**
+* The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in
+* web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the
+* matching `code_verifier`, and nothing else ever travels over the loopback.
+*/
+var DesktopCodes = class {
+	kv;
+	constructor(kv) {
+		this.kv = kv;
+	}
+	key(code) {
+		return `desktop:code:${code}`;
+	}
+	async issue(principal, codeChallenge) {
+		const code = randomUUID();
+		const record = {
+			principal,
+			code_challenge: codeChallenge
+		};
+		await this.kv.setItem(this.key(code), JSON.stringify(record), 300);
+		return code;
+	}
+	/**
+	* The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one
+	* that is unknown, expired, already used, or whose verifier does not hash to its challenge. A
+	* verifier mismatch does not burn the code: that would let an attacker who races a network
+	* retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is
+	* infeasible.
+	*/
+	async redeem(code, codeVerifier) {
+		const key = this.key(code);
+		const raw = await this.kv.getItem(key);
+		if (typeof raw !== "string") throw new AuthenticationError("INVALID_DESKTOP_CODE");
+		let record;
+		try {
+			record = JSON.parse(raw);
+		} catch {
+			await this.kv.removeItem(key);
+			throw new AuthenticationError("INVALID_DESKTOP_CODE");
+		}
+		const computed = createHash("sha256").update(codeVerifier).digest();
+		const stored = Buffer.from(record.code_challenge, "base64url");
+		if (stored.length !== computed.length || !timingSafeEqual(computed, stored)) throw new AuthenticationError("INVALID_DESKTOP_CODE");
+		await this.kv.removeItem(key);
+		return record.principal;
+	}
+};
+export { DESKTOP_CODE_TTL, DesktopCodes };
+
+//# sourceMappingURL=desktop-codes.mjs.map

package/dist/auth/desktop-codes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-codes.mjs","names":[],"sources":["../../src/auth/desktop-codes.ts"],"sourcesContent":["import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';\nimport type { Principal } from '../core/index';\nimport type { KVRepository } from '../session/types';\nimport { AuthenticationError } from './error';\n\n/** Seconds a desktop sign-in code may be redeemed within. */\nexport const DESKTOP_CODE_TTL = 5 * 60;\n\ninterface DesktopCodeRecord {\n  /** Who the web session that issued the code is signed in as. */\n  principal: Principal;\n  /** The S256 `code_challenge` the desktop sent; the verifier it redeems with must hash to it. */\n  code_challenge: string;\n}\n\n/**\n * The single-use codes of the desktop sign-in handshake (RFC 8252 loopback + PKCE): a signed-in\n * web session issues one pinned to the desktop's `code_challenge`, the desktop redeems it with the\n * matching `code_verifier`, and nothing else ever travels over the loopback.\n */\nexport class DesktopCodes {\n  private readonly kv: KVRepository;\n\n  constructor(kv: KVRepository) {\n    this.kv = kv;\n  }\n\n  private key(code: string) {\n    return `desktop:code:${code}`;\n  }\n\n  async issue(principal: Principal, codeChallenge: string): Promise<string> {\n    const code = randomUUID();\n    const record: DesktopCodeRecord = { principal, code_challenge: codeChallenge };\n    await this.kv.setItem(this.key(code), JSON.stringify(record), DESKTOP_CODE_TTL);\n    return code;\n  }\n\n  /**\n   * The principal a code was issued for, consuming the code; `INVALID_DESKTOP_CODE` for one\n   * that is unknown, expired, already used, or whose verifier does not hash to its challenge. A\n   * verifier mismatch does not burn the code: that would let an attacker who races a network\n   * retry brick a legitimate exchange, and guessing the 256-bit verifier within the TTL is\n   * infeasible.\n   */\n  async redeem(code: string, codeVerifier: string): Promise<Principal> {\n    const key = this.key(code);\n    const raw = await this.kv.getItem(key);\n    if (typeof raw !== 'string') throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    let record: DesktopCodeRecord;\n    try {\n      record = JSON.parse(raw) as DesktopCodeRecord;\n    } catch {\n      await this.kv.removeItem(key);\n      throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    }\n    const computed = createHash('sha256').update(codeVerifier).digest();\n    const stored = Buffer.from(record.code_challenge, 'base64url');\n    if (stored.length !== computed.length || !timingSafeEqual(computed, stored)) {\n      throw new AuthenticationError('INVALID_DESKTOP_CODE');\n    }\n    // Removed before the caller creates a session, so a concurrent duplicate exchange (a retry\n    // after a timeout) sees the code as consumed even if the session save races it.\n    await this.kv.removeItem(key);\n    return record.principal;\n  }\n}\n"],"mappings":";;;;AAMA,MAAa,mBAAmB;;;;;;AAchC,IAAa,eAAb,MAA0B;CACxB;CAEA,YAAY,IAAkB;EAC5B,KAAK,KAAK;CACZ;CAEA,IAAY,MAAc;EACxB,OAAO,gBAAgB;CACzB;CAEA,MAAM,MAAM,WAAsB,eAAwC;EACxE,MAAM,OAAO,WAAW;EACxB,MAAM,SAA4B;GAAE;GAAW,gBAAgB;EAAc;EAC7E,MAAM,KAAK,GAAG,QAAQ,KAAK,IAAI,IAAI,GAAG,KAAK,UAAU,MAAM,GAAA,GAAmB;EAC9E,OAAO;CACT;;;;;;;;CASA,MAAM,OAAO,MAAc,cAA0C;EACnE,MAAM,MAAM,KAAK,IAAI,IAAI;EACzB,MAAM,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG;EACrC,IAAI,OAAO,QAAQ,UAAU,MAAM,IAAI,oBAAoB,sBAAsB;EACjF,IAAI;EACJ,IAAI;GACF,SAAS,KAAK,MAAM,GAAG;EACzB,QAAQ;GACN,MAAM,KAAK,GAAG,WAAW,GAAG;GAC5B,MAAM,IAAI,oBAAoB,sBAAsB;EACtD;EACA,MAAM,WAAW,WAAW,QAAQ,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,OAAO;EAClE,MAAM,SAAS,OAAO,KAAK,OAAO,gBAAgB,WAAW;EAC7D,IAAI,OAAO,WAAW,SAAS,UAAU,CAAC,gBAAgB,UAAU,MAAM,GACxE,MAAM,IAAI,oBAAoB,sBAAsB;EAItD,MAAM,KAAK,GAAG,WAAW,GAAG;EAC5B,OAAO,OAAO;CAChB;AACF"}

package/dist/auth/email-codes.cjs

@@ -0,0 +1,77 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_error = require("./error.cjs");
+const require_auth_respond = require("./respond.cjs");
+let node_crypto = require("node:crypto");
+// src/auth/email-codes.ts
+/** Seconds an email verification code, and its attempt counter, stay valid. */
+const EMAIL_VERIFICATION_CODE_TTL = 600;
+/**
+* The six-digit codes mailed to prove an address, in the KV store: one pending code per email,
+* its guess counter, and the resend cooldown. `send` and `verify` are the whole protocol, so the
+* login route and a host flow that only needs proof of the address (verifying or changing a
+* signed-in user's email) share it.
+*/
+var EmailVerificationCodes = class {
+	kv;
+	maxAttempts;
+	resendCooldown;
+	constructor(kv, options) {
+		this.kv = kv;
+		this.maxAttempts = options.maxAttempts;
+		this.resendCooldown = options.resendCooldown;
+	}
+	codeKey(email) {
+		return `email:verification:${email}`;
+	}
+	attemptsKey(email) {
+		return `email:verification-attempts:${email}`;
+	}
+	cooldownKey(email) {
+		return `email:verification-cooldown:${email}`;
+	}
+	/**
+	* Mails a fresh code, at most once per `resendCooldown`. The cooldown is claimed before sending,
+	* so of concurrent requests exactly one sends. A failed delivery releases it again: no code was
+	* stored, so an immediate retry gains an attacker nothing, while keeping it would lock the user
+	* out of signing in for the whole cooldown.
+	*/
+	async send(email, sender) {
+		const cooldownKey = this.cooldownKey(email);
+		if (await this.kv.increment(cooldownKey, this.resendCooldown) > 1) throw require_auth_respond.resourceExhausted("VERIFICATION_CODE_RESEND_TOO_SOON", "A code was sent recently");
+		const verificationCode = (0, node_crypto.randomInt)(1e6).toString().padStart(6, "0");
+		try {
+			await sender({
+				email,
+				verificationCode
+			});
+		} catch (error) {
+			console.error("Failed to send email verification code", error);
+			await this.kv.removeItem(cooldownKey);
+			throw require_auth_respond.unavailable("EMAIL_DELIVERY_FAILED", "The verification email could not be sent");
+		}
+		await this.kv.removeItem(this.attemptsKey(email));
+		await this.kv.setItem(this.codeKey(email), verificationCode, 600);
+	}
+	/**
+	* Spends the pending code if `verificationCode` is it; otherwise throws `AuthenticationError`:
+	* `INVALID_VERIFICATION_CODE` (wrong, or none pending), or `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`
+	* once more than `maxAttempts` guesses were made, which discards the code.
+	*/
+	async verify(email, verificationCode) {
+		const codeKey = this.codeKey(email);
+		const attemptsKey = this.attemptsKey(email);
+		const stored = await this.kv.getItem(codeKey);
+		if (typeof stored !== "string") throw new require_auth_error.AuthenticationError("INVALID_VERIFICATION_CODE");
+		if (await this.kv.increment(attemptsKey, 600) > this.maxAttempts) {
+			await this.kv.removeItem(codeKey);
+			throw new require_auth_error.AuthenticationError("VERIFICATION_CODE_ATTEMPTS_EXCEEDED");
+		}
+		if (stored.length !== verificationCode.length || !(0, node_crypto.timingSafeEqual)(Buffer.from(stored), Buffer.from(verificationCode))) throw new require_auth_error.AuthenticationError("INVALID_VERIFICATION_CODE");
+		await this.kv.removeItem(codeKey);
+		await this.kv.removeItem(attemptsKey);
+	}
+};
+exports.EMAIL_VERIFICATION_CODE_TTL = EMAIL_VERIFICATION_CODE_TTL;
+exports.EmailVerificationCodes = EmailVerificationCodes;
+
+//# sourceMappingURL=email-codes.cjs.map