@dotpress/auth 2.0.0-alpha.4 → 2.0.0-alpha.5

package/README.md

@@ -22,7 +22,7 @@ declare module '@dotpress/auth' {
 
 const auth = createAuth({
   keys: {
-    secretKey: process.env.JWT_PRIVATE_KEY!, // PKCS#8 PEM
+    privateKey: process.env.JWT_PRIVATE_KEY!, // PKCS#8 PEM
     publicKey: process.env.JWT_PUBLIC_KEY!, // SPKI PEM
   },
   issuer: 'https://api.example.com', // checked on every request

package/dist/index.d.ts

@@ -1,40 +1,7 @@
 import * as _dotpress_core from '@dotpress/core';
-import { DotpressRequest, HttpError, PluginCors, DotpressResponse } from '@dotpress/core';
+import { Duration, RateLimitStore, DotpressRequest, HttpError, DotpressResponse } from '@dotpress/core';
 import { JWK } from 'jose';
 
-/** State of a rate limit counter. */
-interface RateLimitState {
-    /** Number of hits in the current window, including the last one. */
-    count: number;
-    /** End of the current window. */
-    resetAt: Date;
-}
-/**
- * Storage of rate limit counters (fixed windows). Use a shared store
- * (Redis, database) when the app runs on several instances.
- */
-interface RateLimitStore {
-    /**
-     * Atomically increments the counter of a key and returns its state. A
-     * missing or expired counter starts a new window of `windowSeconds`.
-     */
-    increment(key: string, windowSeconds: number): Promise<RateLimitState>;
-    /** Deletes the counter of a key. */
-    reset(key: string): Promise<void>;
-}
-interface MemoryRateLimitStoreOptions {
-    /**
-     * Maximum number of counters kept in memory: expired counters are purged
-     * first, then the oldest ones. Defaults to 10 000.
-     */
-    maxKeys?: number;
-}
-/**
- * In-memory rate limit store, for a single instance. With several
- * instances, each one counts on its own: use a shared store.
- */
-declare const memoryRateLimitStore: (options?: MemoryRateLimitStoreOptions) => RateLimitStore;
-
 /**
  * Authenticated user, as returned by `DataProvider.findUserById()`.
  * Declare its shape through module augmentation:
@@ -56,14 +23,13 @@ interface AuthSession {
     readonly userId: string;
     /** `username` claim, with the `usernameClaim` setting only. */
     readonly username: string | undefined;
-    /** Token identifier (`jti`), shared with its refresh token. */
-    readonly tokenId: string;
+    /** Identifier of the access token (`jti` claim), stored with its refresh token. */
+    readonly accessTokenId: string;
     /**
      * Session of the token (`sid` claim): shared by the tokens rotated from
-     * the same login. `undefined` for tokens issued without refresh token
-     * (`generateAccessToken()`).
+     * the same login.
      */
-    readonly sessionId: string | undefined;
+    readonly sessionId: string;
     /** Client the token was issued for (`client_id` claim). */
     readonly clientId: string | undefined;
     /** Roles of the user, used by `requireRole()`. */
@@ -71,9 +37,9 @@ interface AuthSession {
     /** Decoded token claims. */
     readonly claims: Readonly<Record<string, unknown>>;
 }
-interface KeyPairSettings {
+interface KeyPairOptions {
     /** RSA private key, PEM encoded in PKCS#8 (`BEGIN PRIVATE KEY`). */
-    secretKey: string;
+    privateKey: string;
     /** RSA public key, PEM encoded in SPKI (`BEGIN PUBLIC KEY`). */
     publicKey: string;
     /**
@@ -92,7 +58,7 @@ interface AdditionalPublicKey {
     publicKey: string;
     kid?: string;
 }
-interface CookieSettings {
+interface AuthCookieOptions {
     /** Enables cookie mode. Defaults to `false`. */
     enabled?: boolean;
     /** Defaults to `true`. */
@@ -141,14 +107,13 @@ interface CookieSettings {
     /** Also stores the access token in a cookie. Defaults to `false`. */
     accessTokenInCookie?: boolean;
 }
-type ResolvedCookieSettings = Required<Omit<CookieSettings, 'domain'>> & {
-    domain: string | undefined;
-};
+/** Why a login failed. */
+type LoginErrorType = 'invalid_username' | 'invalid_password' | 'invalid_role'
+/** Blocked by the login throttle, before checking the password. */
+ | 'too_many_attempts';
 interface LoginFailedEvent {
     username: string;
-    errorType: 'invalid_username' | 'invalid_password' | 'invalid_role'
-    /** Blocked by the login throttle, before checking the password. */
-     | 'too_many_attempts';
+    errorType: LoginErrorType;
     /** `clientId` sent at login; empty when missing. */
     clientId: string;
     ipAddress: string;
@@ -161,16 +126,17 @@ interface BeforeLoginEvent {
     ipAddress: string;
     req: DotpressRequest;
 }
-/** At most `max` failed logins per `window` seconds. */
+/** At most `max` failed logins per `window`. */
 interface RateLimit {
     max: number;
-    window: number;
+    /** A number of seconds, or a duration like `'1m'` or `'1h'`. */
+    window: Duration;
 }
 /**
  * Login throttle: failed logins are counted per username and IP address,
  * and per username, whether the account exists or not.
  */
-interface LoginThrottleSettings {
+interface LoginThrottleOptions {
     /**
      * Counters storage. Defaults to an in-memory store, for a single
      * instance: use a shared store (Redis, database) with several instances.
@@ -189,19 +155,12 @@ interface LoginThrottleSettings {
         username?: RateLimit | false;
     };
 }
-interface ResolvedLoginThrottleSettings {
-    store: RateLimitStore;
-    limits: {
-        usernameAndIp: RateLimit | undefined;
-        username: RateLimit | undefined;
-    };
-}
 interface RefreshTokenReuseEvent {
     userId: string;
-    /** Revoked session; undefined for tokens stored without family. */
-    familyId: string | undefined;
+    /** Revoked session; undefined for tokens stored before sessions (V1). */
+    sessionId: string | undefined;
     /** `jti` of the access token the reused refresh token was issued with. */
-    jwtId: string;
+    accessTokenId: string;
 }
 interface LoginSuccessEvent {
     userId: string;
@@ -210,16 +169,20 @@ interface LoginSuccessEvent {
     clientId: string;
     ipAddress: string;
 }
-interface StoreRefreshTokenDto {
-    token: string;
+/**
+ * Refresh token to store. The token itself is never given: only its
+ * SHA-256 hash, which `findRefreshToken()` receives.
+ */
+interface NewRefreshToken {
     tokenHash: string;
     userId: string;
-    jwtId: string;
+    /** `jti` of the access token issued with the refresh token. */
+    accessTokenId: string;
     /**
      * Session the token belongs to: created at login, kept by every
      * rotation. Used to revoke the whole session when a token is reused.
      */
-    familyId: string;
+    sessionId: string;
     expiresAt: Date;
 }
 /**
@@ -230,14 +193,14 @@ type LogoutScope = 'current' | 'all';
 /** Session revoked by `revokeSession()`. */
 interface RevokedSession {
     userId: string;
-    /** `undefined` for tokens stored without family (before V2). */
+    /** `undefined` for tokens stored before sessions (V1). */
     sessionId: string | undefined;
 }
 interface RefreshTokenData {
     userId: string;
-    jwtId: string;
-    /** `null` or missing for tokens stored before families existed. */
-    familyId?: string | null;
+    accessTokenId: string;
+    /** `null` or missing for tokens stored before sessions (V1). */
+    sessionId?: string | null;
     expiresAt: Date;
     isUsed: boolean;
     /** When the token was used (see `refreshTokenReuseInterval`). */
@@ -259,14 +222,14 @@ interface UserIdentifiers {
  * (Prisma, Drizzle, SQL…).
  */
 interface DataProvider {
-    storeRefreshToken(payload: StoreRefreshTokenDto): Promise<void>;
+    storeRefreshToken(payload: NewRefreshToken): Promise<void>;
     findRefreshToken(tokenHash: string): Promise<RefreshTokenData | undefined>;
     /** Marks a token as used, storing `usedAt`. */
     markRefreshTokenAsUsed(tokenHash: string, usedAt: Date): Promise<void>;
     /** Revokes every refresh token of a user. */
-    revokeTokens(userId: string): Promise<void>;
-    /** Revokes every refresh token of a session (`familyId`). */
-    revokeTokenFamily(familyId: string): Promise<void>;
+    revokeUserTokens(userId: string): Promise<void>;
+    /** Revokes every refresh token of a session. */
+    revokeSessionTokens(sessionId: string): Promise<void>;
     /**
      * User of a token, on every authenticated request and every refresh.
      * Return `undefined` for a deleted, disabled or banned account: its
@@ -276,7 +239,7 @@ interface DataProvider {
     findUserById(userId: string): Promise<AuthUser | undefined>;
     findUserIdentifiers(username: string): Promise<UserIdentifiers | undefined>;
     /**
-     * Optional. Whether a session (`familyId`, the `sid` claim) was revoked.
+     * Optional. Whether a session (the `sid` claim) was revoked.
      * When defined, it is checked on every authenticated request, so that
      * the access tokens of a revoked session (logout, refresh token reuse,
      * password change) stop working at once, instead of at their expiry.
@@ -298,53 +261,54 @@ interface DataProvider {
  * prove which application sends a request. It means that the token was
  * issued under the policy of that client (see `isUserRoleAllowed`).
  */
-interface ClientSettings {
+interface ClientOptions {
     /** Accepted client identifiers. Others are rejected at login (`400`). */
     allowed: readonly string[];
     /** Requires a `clientId` at login. Defaults to `false`. */
     required?: boolean;
     /** Checks at login that a user may get a token for a client. */
-    isUserRoleAllowed?: (role: string, clientId: string) => boolean;
+    isUserRoleAllowed?: (login: {
+        userId: string;
+        /** `role` of `findUserIdentifiers()`. */
+        role: string | undefined;
+        clientId: string;
+    }) => boolean;
     /**
      * Session lifetimes of some clients, overriding the `session` setting
      * (an explicit `absoluteTimeout: undefined` removes the global limit).
      *
      * @example
-     * sessions: { backoffice: { idleTimeout: 86400, absoluteTimeout: 86400 } }
+     * sessions: { backoffice: { idleTimeout: '1d', absoluteTimeout: '1d' } }
      */
-    sessions?: Readonly<Record<string, SessionSettings>>;
+    sessions?: Readonly<Record<string, SessionOptions>>;
 }
 /**
- * Session lifetimes, in seconds. A session starts at login and is extended
- * by each refresh.
+ * Session lifetimes: numbers of seconds, or durations like `'14d'`. A
+ * session starts at login and is extended by each refresh.
  */
-interface SessionSettings {
+interface SessionOptions {
     /**
      * Inactivity timeout: the session ends when it is not refreshed during
      * this delay (lifetime of each refresh token). Defaults to 14 days.
      */
-    idleTimeout?: number;
+    idleTimeout?: Duration;
     /**
      * Absolute timeout: the session ends this delay after login, even when
      * it is active. Defaults to none: active sessions never end.
      */
-    absoluteTimeout?: number | undefined;
+    absoluteTimeout?: Duration | undefined;
 }
-interface ResolvedSessionSettings {
-    idleTimeout: number;
-    absoluteTimeout: number | undefined;
-}
-interface AuthSettings {
-    keys: KeyPairSettings;
+interface AuthOptions {
+    keys: KeyPairOptions;
     dataProvider: DataProvider;
     /**
-     * Access token lifetime, in seconds. Defaults to 900 (15 minutes): the
-     * longest delay during which the token of a revoked session still
-     * works, without `DataProvider.isSessionRevoked()`.
+     * Access token lifetime: a number of seconds, or a duration like `'15m'`.
+     * Defaults to 15 minutes: the longest delay during which the token of a
+     * revoked session still works, without `DataProvider.isSessionRevoked()`.
      */
-    accessTokenTTL?: number;
+    accessTokenTTL?: Duration;
     /** Session lifetimes (inactivity and absolute timeouts). */
-    session?: SessionSettings;
+    session?: SessionOptions;
     /**
      * `iss` claim of the access tokens, checked on every request: for
      * example the URL of the API. Use a different value per environment
@@ -356,16 +320,16 @@ interface AuthSettings {
      * on every request. Defaults to `issuer`.
      */
     audience?: string;
-    cookies?: CookieSettings;
-    clients?: ClientSettings;
-    onLoginFailed?: (event: LoginFailedEvent) => Promise<void>;
-    onLoginSuccess?: (event: LoginSuccessEvent) => Promise<void>;
+    cookies?: AuthCookieOptions;
+    clients?: ClientOptions;
+    onLoginFailed?: (event: LoginFailedEvent) => void | Promise<void>;
+    onLoginSuccess?: (event: LoginSuccessEvent) => void | Promise<void>;
     /**
      * Login throttle (brute force protection), enabled by default. `false`
      * disables it, when the infrastructure (gateway, WAF) already limits
      * `/auth/login`.
      */
-    loginThrottle?: LoginThrottleSettings | false;
+    loginThrottle?: LoginThrottleOptions | false;
     /**
      * Called before checking the password, after the login throttle: return
      * an error (`tooManyRequestsError()`, `forbiddenError()`…) to reject the
@@ -386,48 +350,25 @@ interface AuthSettings {
      */
     usernameClaim?: boolean;
     /**
-     * Delay, in seconds after its first use, during which a refresh token can
-     * be presented again without being treated as stolen: concurrent
-     * refreshes (several tabs) and retries after a lost response get a new
-     * token pair in the same session. Defaults to 10; 0 disables it.
+     * Delay after its first use during which a refresh token can be
+     * presented again without being treated as stolen: concurrent refreshes
+     * (several tabs) and retries after a lost response get a new token pair
+     * in the same session. A number of seconds, or a duration like `'10s'`.
+     * Defaults to 10 seconds; 0 disables it.
      */
-    refreshTokenReuseInterval?: number;
+    refreshTokenReuseInterval?: Duration;
     /**
      * Called when a used refresh token is presented again after the reuse
      * interval: the session has been revoked, as the token was probably
      * stolen. Errors thrown by the hook are ignored.
      */
-    onRefreshTokenReuse?: (event: RefreshTokenReuseEvent) => Promise<void>;
+    onRefreshTokenReuse?: (event: RefreshTokenReuseEvent) => void | Promise<void>;
     /**
      * Roles of a user, checked by `requireRole()`. Defaults to its `roles`
      * array, or to its `role` string.
      */
     getUserRoles?: (user: AuthUser) => readonly string[];
 }
-/** Options of `auth.init()`. */
-interface AuthInitOptions {
-    /**
-     * Browser path of the auth routes, used as the default path of the
-     * refresh token cookie. An auth service serves a single path.
-     */
-    routesPath?: string;
-    /**
-     * CORS settings of the app (`api.cors`). When `cookies.trustedOrigins`
-     * is not set and CORS allows credentials, the origins allowed by CORS
-     * are trusted.
-     */
-    cors?: PluginCors;
-}
-interface ResolvedAuthSettings extends Required<Omit<AuthSettings, 'cookies' | 'clients' | 'session' | 'onLoginFailed' | 'onLoginSuccess' | 'loginThrottle' | 'beforeLogin' | 'onRefreshTokenReuse'>> {
-    cookies: ResolvedCookieSettings;
-    clients: ClientSettings | undefined;
-    session: ResolvedSessionSettings;
-    onLoginFailed: ((event: LoginFailedEvent) => Promise<void>) | undefined;
-    onLoginSuccess: ((event: LoginSuccessEvent) => Promise<void>) | undefined;
-    loginThrottle: ResolvedLoginThrottleSettings | undefined;
-    beforeLogin: AuthSettings['beforeLogin'];
-    onRefreshTokenReuse: ((event: RefreshTokenReuseEvent) => Promise<void>) | undefined;
-}
 interface TokenPair {
     accessToken: string;
     refreshToken: string;
@@ -446,15 +387,6 @@ interface IssuedTokens extends TokenPair {
     /** End of the session, when an absolute timeout applies. */
     sessionExpiresAt: Date | undefined;
 }
-interface CreatedAccessToken {
-    jwtId: string;
-    accessToken: string;
-    expiresAt: Date;
-}
-interface CreatedRefreshToken {
-    token: string;
-    tokenHash: string;
-}
 
 declare module '@dotpress/core' {
     interface RequestContext {
@@ -478,14 +410,6 @@ declare class AuthError extends Error {
     constructor(code: AuthErrorCode, options?: ErrorOptions);
 }
 interface Auth {
-    readonly settings: ResolvedAuthSettings;
-    /**
-     * Imports the keys. Fails with an explicit message on invalid keys.
-     * `authPlugin()` calls it at startup, with the browser path of its routes.
-     */
-    init(options?: AuthInitOptions): Promise<void>;
-    generateAccessToken(subject: TokenSubject): Promise<CreatedAccessToken>;
-    generateRefreshToken(): Promise<CreatedRefreshToken>;
     /** Generates and stores a token pair, starting a session. */
     generateTokensForUser(subject: TokenSubject): Promise<IssuedTokens>;
     /**
@@ -496,7 +420,7 @@ interface Auth {
      * `refreshTokenReuseInterval` after its first use, it may be presented
      * again (concurrent refreshes, retries after a lost response): a new pair
      * is issued in the same session. After, presenting it again means it was
-     * probably stolen: the whole session (token family) is revoked, and
+     * probably stolen: the whole session is revoked, and
      * `REFRESH_TOKEN_REUSED` is thrown.
      *
      * Throws `EXPIRED_REFRESH_TOKEN` when the session reached its inactivity
@@ -516,7 +440,7 @@ interface Auth {
     /**
      * Revokes the session of a refresh token (logout). The token may be
      * used, revoked or expired: it still designates its session. Tokens
-     * stored without family (before V2) revoke every session of the user.
+     * stored before sessions (V1) revoke every session of the user.
      *
      * With `scope: 'all'`, revokes every session of the user, on every
      * device. The token must then be active (neither used, revoked nor
@@ -528,6 +452,13 @@ interface Auth {
     revokeSession(refreshToken: string, options?: {
         scope?: LogoutScope;
     }): Promise<RevokedSession | undefined>;
+    /**
+     * Revokes every session of a user, on every device: after a password
+     * change, or when an account is disabled. Their refresh tokens stop
+     * working at once; their access tokens too with
+     * `DataProvider.isSessionRevoked()`, else at their expiry.
+     */
+    revokeUserSessions(userId: string): Promise<void>;
     /**
      * End of a session, when an absolute timeout applies to it (computed
      * from the `auth_time` claim).
@@ -550,7 +481,7 @@ interface Auth {
      */
     setAuthCookies(res: DotpressResponse, tokens: TokenPair & {
         refreshTokenExpiresAt?: Date;
-    }, expiresInSeconds?: number): void;
+    }): void;
     clearAuthCookies(res: DotpressResponse): void;
     /**
      * Whether a request may be authenticated by the cookies: protection
@@ -560,11 +491,11 @@ interface Auth {
      */
     isCookieAuthenticationAllowed(req: DotpressRequest): Promise<boolean>;
     /**
-     * Hashes a password with bcrypt. Defaults to `passwordHashRounds`.
-     * Throws a `RangeError` for passwords longer than 72 bytes (see
+     * Hashes a password with bcrypt, with `passwordHashRounds`. Throws a
+     * `RangeError` for passwords longer than 72 bytes (see
      * `isPasswordTooLong()`).
      */
-    hashPassword(password: string, saltRounds?: number): Promise<string>;
+    hashPassword(password: string): Promise<string>;
     /** Whether a bcrypt hash has another cost than `passwordHashRounds`. */
     passwordNeedsRehash(passwordHash: string): boolean;
     /**
@@ -589,9 +520,7 @@ interface Auth {
  * const auth = createAuth({ keys, dataProvider })
  * await createApp({ adapter, plugins: [authPlugin(auth)] })
  */
-declare const createAuth: (input: AuthSettings) => Auth;
-/** Longest password bcrypt reads, in UTF-8 bytes. */
-declare const MAX_PASSWORD_BYTES = 72;
+declare const createAuth: (input: AuthOptions) => Auth;
 /**
  * Whether a password exceeds the 72 bytes (UTF-8) read by bcrypt. Check
  * it in the sign-up and password change schemas: `hashPassword()` rejects
@@ -601,12 +530,16 @@ declare const MAX_PASSWORD_BYTES = 72;
  * password: z.string().min(12).refine((p) => !isPasswordTooLong(p), 'Password too long')
  */
 declare const isPasswordTooLong: (password: string) => boolean;
+interface PasswordHashOptions {
+    /** bcrypt cost, from 4 to 31. Defaults to 12. */
+    rounds?: number;
+}
 /**
- * Hashes a password with bcrypt (cost 12 by default). Throws a
- * `RangeError` for passwords longer than 72 bytes (see
+ * Hashes a password with bcrypt, out of an auth service (seeds, scripts).
+ * Throws a `RangeError` for passwords longer than 72 bytes (see
  * `isPasswordTooLong()`).
  */
-declare const generatePasswordHash: (password: string, saltRounds?: number) => Promise<string>;
+declare const generatePasswordHash: (password: string, options?: PasswordHashOptions) => Promise<string>;
 
 /** Context guaranteed by `requireAuth`, `requireRole()` and `requireClient()`. */
 interface AuthenticatedContext {
@@ -652,11 +585,6 @@ declare const AUTH_SECURITY_SCHEMES: {
         readonly bearerFormat: "JWT";
     };
 };
-/**
- * Access token of a request: `Authorization: Bearer` header, then cookie
- * (when enabled). The request body is never read.
- */
-declare const extractAccessToken: (req: DotpressRequest, cookies: ResolvedCookieSettings) => string | undefined;
 /**
  * Plugs an authentication service into an app:
  *
@@ -678,5 +606,5 @@ declare const authPlugin: (auth: Auth, options?: AuthPluginOptions) => {
     readonly setup: (api: _dotpress_core.PluginAPI) => Promise<void>;
 };
 
-export { AUTH_SECURITY_SCHEMES, AuthError, MAX_PASSWORD_BYTES, authPlugin, createAuth, extractAccessToken, generatePasswordHash, isPasswordTooLong, memoryRateLimitStore, requireAuth, requireClient, requireRole };
-export type { AdditionalPublicKey, Auth, AuthErrorCode, AuthInitOptions, AuthPluginOptions, AuthSession, AuthSettings, AuthUser, AuthenticatedContext, BeforeLoginEvent, ClientSettings, CookieSettings, CreatedAccessToken, CreatedRefreshToken, DataProvider, IssuedTokens, KeyPairSettings, LoginFailedEvent, LoginSuccessEvent, LoginThrottleSettings, LogoutScope, MemoryRateLimitStoreOptions, RateLimit, RateLimitState, RateLimitStore, RefreshTokenData, RefreshTokenReuseEvent, ResolvedAuthSettings, ResolvedCookieSettings, ResolvedLoginThrottleSettings, ResolvedSessionSettings, RevokedSession, SessionSettings, StoreRefreshTokenDto, TokenPair, TokenSubject, UserIdentifiers };
+export { AUTH_SECURITY_SCHEMES, AuthError, authPlugin, createAuth, generatePasswordHash, isPasswordTooLong, requireAuth, requireClient, requireRole };
+export type { AdditionalPublicKey, Auth, AuthCookieOptions, AuthErrorCode, AuthOptions, AuthPluginOptions, AuthSession, AuthUser, AuthenticatedContext, BeforeLoginEvent, ClientOptions, DataProvider, IssuedTokens, KeyPairOptions, LoginErrorType, LoginFailedEvent, LoginSuccessEvent, LoginThrottleOptions, LogoutScope, NewRefreshToken, PasswordHashOptions, RateLimit, RefreshTokenData, RefreshTokenReuseEvent, RevokedSession, SessionOptions, TokenPair, TokenSubject, UserIdentifiers };