@shware/security 7.1.0 → 8.0.0

package/dist/auth/index.d.mts

@@ -1,7 +1,7 @@
 import { Principal } from "../core/index.mjs";
 import { Session } from "../session/types.mjs";
+import { EmailSender } from "./email-codes.mjs";
 import { AuthConfig, AuthService, AuthorizedHandler, LoggedHandler, OAuth2AuthorizationOptions } from "./types.mjs";
-//#region src/auth/index.d.ts
 export declare const PATH: {
   readonly CSRF: '/csrf';
   readonly LOGOUT: '/logout';
@@ -13,13 +13,18 @@ export declare const PATH: {
   readonly LOGIN_OAUTH2_NATIVE: '/login/oauth2/native/:provider';
   readonly LOGIN_OAUTH2_ONETAP: '/login/oauth2/onetap/google';
   readonly LOGIN_EMAIL: '/login/email';
-  readonly LOGIN_PHONE: '/login/phone';
   readonly SEND_EMAIL_VERIFICATION_CODE: '/auth/sendEmailVerificationCode';
-  readonly SEND_PHONE_VERIFICATION_CODE: '/auth/sendPhoneVerificationCode';
   readonly DESKTOP_AUTHORIZE: '/auth/desktop/authorize';
   readonly DESKTOP_EXCHANGE: '/auth/desktop/exchange';
   readonly CLEANUP_EXPIRED_SESSIONS: '/sessions/expired/cleanup';
 };
+/**
+ * The login routes and session helpers. Every route is one straight line: read and validate the
+ * request, check the credential, call the host's `onAuthorized`, sign in. Failures are thrown and
+ * answered in one place per kind of route: a JSON route runs under `guard`, which maps a
+ * `RequestError`, an `AuthenticationError` or an `OAuth2Error` to its google.rpc body (see
+ * `respond.ts`); the redirect callback maps the same errors to `errorUri` parameters (`redirect`).
+ */
 export declare class Auth implements AuthService {
   private readonly timing;
   private readonly cookieName;
@@ -27,87 +32,92 @@ export declare class Auth implements AuthService {
   private readonly kv;
   private readonly repository;
   private readonly turnstileSecretKey?;
-  private readonly maxVerificationAttempts;
-  private readonly verificationResendCooldown;
+  private readonly emailCodes;
+  private readonly desktopCodes;
   private readonly oauth2Client;
   private readonly onetapRequireNonce;
   private readonly touchInterval;
+  private readonly sessionHeader;
   private readonly ATTR_OAUTH2_AUTHORIZATION_REQUEST;
   constructor({ sessionRepository, kvRepository, turnstileSecretKey, verificationCode, oauth2, cookie, session, timing }: AuthConfig);
   private getSessionId;
+  /** The session the request carries, if it exists. */
+  private loadSession;
+  /** The signed-in principal of a session, if any. */
+  private principalOf;
+  /**
+   * A new session signed in as `principal`. With `carryOver`, what the host kept in the pre-login
+   * session moves to the new one; the authorization request (state, PKCE verifier, flow
+   * attributes) is single-use and was consumed, and a principal left there from an earlier
+   * sign-in is replaced. The new id is never the one the browser brought, which may have been
+   * planted by an attacker who started the flow (session fixation).
+   */
+  private signIn;
+  /**
+   * `response` carrying `session`: its cookie, renewed for the whole inactive interval, and with
+   * `session.header` on, the `X-Auth-Token` header a client without a cookie jar reads.
+   */
+  private withSession;
+  /** Runs a JSON route: a failure it knows is its response, anything else is the host's. */
+  private guard;
+  /** The error redirect of the callback flow; `refusal`'s reason and metadata ride along. */
+  private redirect;
   csrf: (_request: Request) => Promise<Response>;
   logout: (request: Request) => Promise<Response>;
   logged: (request: Request, onLogged?: LoggedHandler) => Promise<Response>;
   private createPkceParameters;
   private getOauth2StateKey;
   private getOauth2NonceKey;
-  private getEmailVerificationCodeKey;
-  private getEmailVerificationAttemptsKey;
-  private getEmailVerificationCooldownKey;
-  private getPhoneVerificationCodeKey;
-  private getDesktopCodeKey;
+  /**
+   * Spends a nonce `oauth2Nonce` issued for `provider`: `NONCE_MISMATCH` for one that was not,
+   * or was used already. An id token is replayable until it expires; the nonce it carries makes
+   * it sign in once.
+   */
+  private consumeNonce;
   oauth2State: (request: Request) => Promise<Response>;
   oauth2Nonce: (request: Request) => Promise<Response>;
   oauth2Authorization: (request: Request, options?: OAuth2AuthorizationOptions) => Promise<Response>;
-  private readonly redirect;
   loginOAuth2Code: (request: Request, handler: AuthorizedHandler) => Promise<Response>;
-  /**
-   * A fresh session for `name`, carrying over what the host kept in the pre-login one. The
-   * authorization request (state, PKCE verifier, flow attributes) is single-use and was consumed
-   * by this callback, and a principal left there from an earlier sign-in is replaced.
-   */
-  private signedInSession;
+  /** The shared tail of the JSON login routes: the host's handler, then a signed-in session. */
+  private authorize;
   loginOAuth2Native: (request: Request, handler: AuthorizedHandler) => Promise<Response>;
   loginOAuth2Onetap: (request: Request, handler: AuthorizedHandler, provider?: string) => Promise<Response>;
-  sendEmailVerificationCode: (request: Request, sender: (data: {
-    email: string;
-    verificationCode: string;
-  }) => Promise<void>) => Promise<Response>;
+  sendEmailVerificationCode: (request: Request, sender: EmailSender) => Promise<Response>;
+  verifyEmailCode: (email: string, verificationCode: string) => Promise<void>;
   loginEmail: (request: Request, handler: AuthorizedHandler) => Promise<Response>;
   /**
-   * Step 1 of the desktop / native app sign-in handshake. The caller already
-   * completed normal sign-in on the web (so a cookie session exists); this
-   * issues a 5-minute single-use code that the web page hands off to the
-   * desktop client via a loopback redirect.
+   * Step 1 of the desktop / native app sign-in handshake. The caller already completed normal
+   * sign-in on the web (so a cookie session exists); this issues a 5-minute single-use code that
+   * the web page hands off to the desktop client via a loopback redirect.
    *
-   * PKCE (RFC 7636, S256 only): the desktop generates a random `code_verifier`
-   * before opening the browser, derives `code_challenge = base64url(sha256(verifier))`,
-   * and threads the challenge through the URL → web page → here. We pin
-   * the challenge to the code in KV; `desktopExchange` enforces that the
-   * caller knows the matching verifier. This blocks an attacker who only
-   * intercepts the auth code (browser history, malicious extension, packet
-   * capture on loopback) from exchanging it.
+   * PKCE (RFC 7636, S256 only): the desktop generates a random `code_verifier` before opening the
+   * browser, derives `code_challenge = base64url(sha256(verifier))`, and threads the challenge
+   * through the URL → web page → here. The challenge is pinned to the code; `desktopExchange`
+   * enforces that the caller knows the matching verifier. This blocks an attacker who only
+   * intercepts the auth code (browser history, malicious extension, packet capture on loopback)
+   * from exchanging it.
    *
-   * Requires an authenticated cookie session — anonymous callers get 401.
-   * Throttling / abuse protection on this endpoint is the API layer's job
-   * (rate-limit per principal); the SDK doesn't gate it because the
-   * upstream sign-in flow already passed CAPTCHA / OAuth / verification.
+   * Requires an authenticated cookie session: anonymous callers get 401. Throttling / abuse
+   * protection on this endpoint is the API layer's job (rate-limit per principal); the SDK does
+   * not gate it because the upstream sign-in flow already passed CAPTCHA / OAuth / verification.
    */
   desktopAuthorize: (request: Request) => Promise<Response>;
   /**
-   * Step 2 of the desktop / native app sign-in handshake. The desktop
-   * client hands back the auth code it received via the loopback callback,
-   * and we mint a fresh session for it — independent of the web cookie
-   * session that originally `authorize`'d the code, so logging out on
-   * either side doesn't cascade to the other.
+   * Step 2 of the desktop / native app sign-in handshake. The desktop client hands back the auth
+   * code it received via the loopback callback, and we mint a fresh session for it, independent
+   * of the web cookie session that originally authorized the code, so logging out on either side
+   * does not cascade to the other.
    *
-   * Cookie attributes: defaults to `SameSite=None; Secure` so the cookie
-   * survives cross-site fetches from the desktop renderer's `file://` /
-   * `app://` origin. The configured base `cookieOptions` provide
-   * everything else (`domain`, `path`, `httpOnly`, `maxAge`); the override
-   * is targeted at the SameSite/Secure pair only. In a non-HTTPS dev
-   * backend this combination is rejected by Chromium — see the desktop
-   * sign-in PRD for workarounds.
+   * Cookie attributes: `SameSite=None; Secure` so the cookie survives cross-site fetches from the
+   * desktop renderer's `file://` / `app://` origin. The configured `cookieOptions` provide
+   * everything else (`domain`, `path`, `httpOnly`); the override is targeted at the
+   * SameSite/Secure pair only. In a non-HTTPS dev backend this combination is rejected by
+   * Chromium, see the desktop sign-in PRD for workarounds.
    *
-   * No CSRF check needed — the request carries no cookie, the auth code
-   * itself is the credential, and KV's single-use removal blocks replay.
+   * No CSRF check needed: the request carries no cookie, the auth code itself is the credential,
+   * and the code's single-use removal blocks replay.
    */
   desktopExchange: (request: Request) => Promise<Response>;
-  sendPhoneVerificationCode: (_request: Request, _sender: (data: {
-    phone: string;
-    verificationCode: string;
-  }) => Promise<void>) => Promise<Response>;
-  loginPhone: (_request: Request, _handler: AuthorizedHandler) => Promise<Response>;
   kick: (principal: Principal) => Promise<void>;
   /**
    * Sliding expiration: an authenticated request renews the session, as `logged` does, so a user
@@ -117,12 +127,11 @@ export declare class Auth implements AuthService {
    * `AuthConfig`), so a session accessed again within the interval is not rewritten.
    */
   private touch;
+  getPrincipal: (request: Request) => Promise<Principal | null>;
   isAuthenticated: (request: Request) => Promise<boolean>;
   getSession: <T extends boolean>(request: Request, create: T) => Promise<T extends true ? Session : Session | null>;
   deleteSession: (sessionId: string) => Promise<void>;
-  getPrincipal: (request: Request) => Promise<Principal | null>;
   listSessions: (principal: Principal) => Promise<Session[]>;
   cleanupExpiredSessions: (cleanupCount?: number) => Promise<Response>;
 }
-//#endregion
 //# sourceMappingURL=index.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/auth/index.ts"],"mappings":";;;;qBA4Ga;WACX;WACA;WACA;WAEA;WACA;WACA;WACA;WACA;WACA;WAEA;WACA;WACA;WACA;WASA;WACA;WAEA;;qBAMW,gBAAgB;mBACV;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;EAEjB,cACE,mBACA,cACA,oBACA,kBACA,QACA,QACA,SACA,UACC;UA2BK;EAYR,OAAI,UAAoB,YAAU,QAAQ;EAmB1C,SAAM,SAAmB,YAAU,QAAQ;EAU3C,SAAM,SAAmB,SAAO,WAAa,kBAAgB,QAAQ;UAsB7D;UAUA;UAIA;UAIA;UAIA;UAIA;UAIA;UAIA;EAIR,cAAW,SAAmB,YAAU,QAAQ;EAOhD,cAAW,SAAmB,YAAU,QAAQ;EAOhD,sBAAmB,SACR,SAAO,UACN,+BACT,QAAQ;mBAmCM;EAUjB,kBAAe,SAAmB,SAAO,SAAW,sBAAoB,QAAQ;;;;;;UA+HxE;EAYR,oBAAiB,SAAmB,SAAO,SAAW,sBAAoB,QAAQ;EAmDlF,oBAAiB,SACN,SAAO,SACP,mBAAiB,sBAEzB,QAAQ;EA6EX,4BAAyB,SACd,SAAO,SACP;IAAQ;IAAe;QAA+B,kBAC9D,QAAQ;EA0CX,aAAU,SAAmB,SAAO,SAAW,sBAAoB,QAAQ;;;;;;;;;;;;;;;;;;;;EAsE3E,mBAAgB,SAAmB,YAAU,QAAQ;;;;;;;;;;;;;;;;;;;EA0DrD,kBAAe,SAAmB,YAAU,QAAQ;EAgEpD,4BAAyB,UACb,SAAO,UACP;IAAQ;IAAe;QAA+B,kBAC/D,QAAQ;EAIX,aAAU,UAAoB,SAAO,UAAY,sBAAoB,QAAQ;EAI7E,OAAI,WAAqB,cAAY;;;;;;;;UAcvB;EAOd,kBAAe,SAAmB,YAAU;EAW5C,aAAoB,mBAAiB,SAC1B,SAAO,QACR,MACP,QAAQ,iBAAiB,UAAU;EAwBtC,gBAAa,sBAA8B;EAI3C,eAAY,SAAmB,YAAU,QAAQ;EAWjD,eAAY,WAAqB,cAAY,QAAQ;EAKrD,yBAAsB,0BAAkC,QAAQ"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/auth/index.ts"],"mappings":";;;;qBAyHa;WACX;WACA;WACA;WAEA;WACA;WACA;WACA;WACA;WACA;WAEA;WACA;WASA;WACA;WAEA;;;;;;;;;qBAUW,gBAAgB;mBACV;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;EAEjB,cACE,mBACA,cACA,oBACA,kBACA,QACA,QACA,SACA,UACC;UA6BK;;UAOM;;UAMN;;;;;;;;UAYM;;;;;UAiBN;;UAYM;;UAWN;EAqBR,OAAI,UAAoB,YAAU,QAAQ;EAmB1C,SAAM,SAAmB,YAAU,QAAQ;EAU3C,SAAM,SAAmB,SAAO,WAAa,kBAAgB,QAAQ;UAc7D;UAUA;UAIA;;;;;;UASM;EAMd,cAAW,SAAmB,YAAU,QAAQ;EAOhD,cAAW,SAAmB,YAAU,QAAQ;EAOhD,sBAAmB,SACR,SAAO,UACN,+BACT,QAAQ;EA+BX,kBAAe,SAAmB,SAAO,SAAW,sBAAoB,QAAQ;;UAoGlE;EAad,oBAAiB,SAAa,SAAO,SAAW,sBAAoB,QAAQ;EAwC5E,oBAAiB,SACN,SAAO,SACP,mBAAiB,sBAEzB,QAAQ;EAqDX,4BAAyB,SAAa,SAAO,QAAU,gBAAc,QAAQ;EAY7E,kBAAe,eAAiB,6BAA6B;EAG7D,aAAU,SAAa,SAAO,SAAW,sBAAoB,QAAQ;;;;;;;;;;;;;;;;;EAoCrE,mBAAgB,SAAa,YAAU,QAAQ;;;;;;;;;;;;;;;;EAwB/C,kBAAe,SAAa,YAAU,QAAQ;EAe9C,OAAI,WAAqB,cAAY;;;;;;;;UAcvB;EAOd,eAAY,SAAmB,YAAU,QAAQ;EAQjD,kBAAe,SAAmB,YAAU;EAI5C,aAAoB,mBAAiB,SAC1B,SAAO,QACR,MACP,QAAQ,iBAAiB,UAAU;EAStC,gBAAa,sBAA8B;EAI3C,eAAY,WAAqB,cAAY,QAAQ;EAKrD,yBAAsB,0BAAkC,QAAQ"}