@dotpress/auth 1.3.1 → 2.0.0-alpha.0

package/dist/index.d.ts

@@ -1,10 +1,682 @@
-import type { Plugin } from 'dotpress';
-import { AuthSettings, DataProvider, KeyPairSettings } from './types/types.js';
-import { generateAccessToken, generateTokensForUser, generateRefreshToken } from './lib/tokens.js';
-type Settings = Partial<AuthSettings> & {
+import * as _dotpress_core from '@dotpress/core';
+import { DotpressRequest, HttpError, PluginCors, 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:
+ *
+ * @example
+ * declare module '@dotpress/auth' {
+ *   interface AuthUser {
+ *     id: string
+ *     roles: string[]
+ *   }
+ * }
+ */
+interface AuthUser {
+}
+/**
+ * Data of the access token of the current request.
+ */
+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;
+    /**
+     * Session of the token (`sid` claim): shared by the tokens rotated from
+     * the same login. `undefined` for tokens issued without refresh token
+     * (`generateAccessToken()`).
+     */
+    readonly sessionId: string | undefined;
+    /** Client the token was issued for (`client_id` claim). */
+    readonly clientId: string | undefined;
+    /** Roles of the user, used by `requireRole()`. */
+    readonly roles: readonly string[];
+    /** Decoded token claims. */
+    readonly claims: Readonly<Record<string, unknown>>;
+}
+interface KeyPairSettings {
+    /** RSA private key, PEM encoded in PKCS#8 (`BEGIN PRIVATE KEY`). */
+    secretKey: string;
+    /** RSA public key, PEM encoded in SPKI (`BEGIN PUBLIC KEY`). */
+    publicKey: string;
+    /**
+     * Key identifier (`kid` header of the tokens). Defaults to the RFC 7638
+     * thumbprint of the public key.
+     */
+    kid?: string;
+    /**
+     * Other public keys accepted to verify tokens (SPKI PEM, with an optional
+     * `kid`, defaulting to their thumbprint): the previous key after a
+     * rotation, or the next key before it, during rolling deployments.
+     */
+    additionalPublicKeys?: readonly (string | AdditionalPublicKey)[];
+}
+interface AdditionalPublicKey {
+    publicKey: string;
+    kid?: string;
+}
+interface CookieSettings {
+    /** Enables cookie mode. Defaults to `false`. */
+    enabled?: boolean;
+    /** Defaults to `true`. */
+    httpOnly?: boolean;
+    /** Defaults to `true` (browsers accept secure cookies on `localhost`). */
+    secure?: boolean;
+    /** Defaults to `lax`. */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /**
+     * `SameSite` attribute of the refresh token cookie, which never needs to
+     * accompany a navigation from another site. Defaults to `strict`, or to
+     * `none` when `sameSite` is `none`.
+     */
+    refreshTokenSameSite?: 'strict' | 'lax' | 'none';
+    /**
+     * Origins allowed to send requests authenticated by the cookies, besides
+     * the API origin: for example `https://app.example.com` when the app is
+     * served from another subdomain. Other cross-origin requests do not use
+     * the cookies (protection against cross-site request forgery).
+     *
+     * Defaults to the origins allowed by the `cors` option of the app, when
+     * it allows credentials (`authPlugin()`), else to none.
+     */
+    trustedOrigins?: readonly string[];
+    domain?: string;
+    /** Path of the access token cookie. Defaults to `/`. */
+    path?: string;
+    /**
+     * Path of the refresh token cookie: the browser path of the auth routes,
+     * the only ones that need it. With `authPlugin()`, defaults to the path
+     * of its routes, including the `basePath` or `publicBasePath` of the app
+     * (for example `/my-app/api/auth`). Defaults to `/auth` otherwise.
+     */
+    refreshTokenPath?: string;
+    /**
+     * Defaults to `dotpress_access_token`, prefixed with `__Host-` when the
+     * cookie is secure, without domain and with path `/`, or with
+     * `__Secure-` when it is only secure.
+     */
+    accessTokenName?: string;
+    /**
+     * Defaults to `dotpress_refresh_token`, prefixed like the access token
+     * cookie (`__Secure-` with the default path).
+     */
+    refreshTokenName?: string;
+    /** Also stores the access token in a cookie. Defaults to `false`. */
+    accessTokenInCookie?: boolean;
+}
+type ResolvedCookieSettings = Required<Omit<CookieSettings, 'domain'>> & {
+    domain: string | undefined;
+};
+interface LoginFailedEvent {
+    username: string;
+    errorType: 'invalid_username' | 'invalid_password' | 'invalid_role'
+    /** Blocked by the login throttle, before checking the password. */
+     | 'too_many_attempts';
+    /** `clientId` sent at login; empty when missing. */
+    clientId: string;
+    ipAddress: string;
+}
+/** Login attempt, before the password is checked. */
+interface BeforeLoginEvent {
+    username: string;
+    /** `clientId` sent at login; empty when missing. */
+    clientId: string;
+    ipAddress: string;
+    req: DotpressRequest;
+}
+/** At most `max` failed logins per `window` seconds. */
+interface RateLimit {
+    max: number;
+    window: number;
+}
+/**
+ * Login throttle: failed logins are counted per username and IP address,
+ * and per username, whether the account exists or not.
+ */
+interface LoginThrottleSettings {
+    /**
+     * Counters storage. Defaults to an in-memory store, for a single
+     * instance: use a shared store (Redis, database) with several instances.
+     */
+    store?: RateLimitStore;
+    limits?: {
+        /**
+         * Against brute force from one client, without letting others block
+         * the account. Defaults to 5 per minute; `false` disables it.
+         */
+        usernameAndIp?: RateLimit | false;
+        /**
+         * Against distributed brute force on an account. Defaults to 100 per
+         * hour (NIST 800-63B); `false` disables it.
+         */
+        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;
+    /** `jti` of the access token the reused refresh token was issued with. */
+    jwtId: string;
+}
+interface LoginSuccessEvent {
+    userId: string;
+    username: string;
+    /** `clientId` sent at login; empty when missing. */
+    clientId: string;
+    ipAddress: string;
+}
+interface StoreRefreshTokenDto {
+    token: string;
+    tokenHash: string;
+    userId: string;
+    jwtId: 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;
+    expiresAt: Date;
+}
+/**
+ * Sessions revoked by a logout: the current session, or every session of
+ * the user.
+ */
+type LogoutScope = 'current' | 'all';
+/** Session revoked by `revokeSession()`. */
+interface RevokedSession {
+    userId: string;
+    /** `undefined` for tokens stored without family (before V2). */
+    sessionId: string | undefined;
+}
+interface RefreshTokenData {
+    userId: string;
+    jwtId: string;
+    /** `null` or missing for tokens stored before families existed. */
+    familyId?: string | null;
+    expiresAt: Date;
+    isUsed: boolean;
+    /** When the token was used (see `refreshTokenReuseInterval`). */
+    usedAt?: Date | null;
+    revokedAt?: Date | null;
+}
+interface UserIdentifiers {
+    userId: string;
+    /**
+     * bcrypt hash of the password. `null` (or an empty string) for accounts
+     * without password (SSO, pending invitation): their login fails like a
+     * wrong password, in the same time.
+     */
+    passwordHash: string | null;
+    role?: string;
+}
+/**
+ * Storage of users and refresh tokens, implemented by the application
+ * (Prisma, Drizzle, SQL…).
+ */
+interface DataProvider {
+    storeRefreshToken(payload: StoreRefreshTokenDto): 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>;
+    /**
+     * User of a token, on every authenticated request and every refresh.
+     * Return `undefined` for a deleted, disabled or banned account: its
+     * requests are rejected at once, and its sessions end at their next
+     * refresh.
+     */
+    findUserById(userId: string): Promise<AuthUser | undefined>;
+    findUserIdentifiers(username: string): Promise<UserIdentifiers | undefined>;
+    /**
+     * Optional. Whether a session (`familyId`, 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.
+     * It costs one lookup per request: see the README for implementations.
+     */
+    isSessionRevoked?(sessionId: string): Promise<boolean>;
+    /**
+     * Optional. Stores a new hash of the password of a user, computed at
+     * login when the stored hash has another cost than `passwordHashRounds`
+     * (for example after raising it). Errors are logged, and do not fail
+     * the login.
+     */
+    updatePasswordHash?(userId: string, passwordHash: string): Promise<void>;
+}
+/**
+ * Client applications (`client_id` claim), such as `app` or `backoffice`.
+ *
+ * The client identifier is declared by the caller at login: it does not
+ * prove which application sends a request. It means that the token was
+ * issued under the policy of that client (see `isUserRoleAllowed`).
+ */
+interface ClientSettings {
+    /** 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;
+    /**
+     * 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?: Readonly<Record<string, SessionSettings>>;
+}
+/**
+ * Session lifetimes, in seconds. A session starts at login and is extended
+ * by each refresh.
+ */
+interface SessionSettings {
+    /**
+     * Inactivity timeout: the session ends when it is not refreshed during
+     * this delay (lifetime of each refresh token). Defaults to 14 days.
+     */
+    idleTimeout?: number;
+    /**
+     * Absolute timeout: the session ends this delay after login, even when
+     * it is active. Defaults to none: active sessions never end.
+     */
+    absoluteTimeout?: number | undefined;
+}
+interface ResolvedSessionSettings {
+    idleTimeout: number;
+    absoluteTimeout: number | undefined;
+}
+interface AuthSettings {
     keys: KeyPairSettings;
     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()`.
+     */
+    accessTokenTTL?: number;
+    /** Session lifetimes (inactivity and absolute timeouts). */
+    session?: SessionSettings;
+    /**
+     * `iss` claim of the access tokens, checked on every request: for
+     * example the URL of the API. Use a different value per environment
+     * and application, especially when they share a key pair.
+     */
+    issuer: string;
+    /**
+     * `aud` claim of the access tokens: the API that accepts them, checked
+     * on every request. Defaults to `issuer`.
+     */
+    audience?: string;
+    cookies?: CookieSettings;
+    clients?: ClientSettings;
+    onLoginFailed?: (event: LoginFailedEvent) => Promise<void>;
+    onLoginSuccess?: (event: LoginSuccessEvent) => 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;
+    /**
+     * Called before checking the password, after the login throttle: return
+     * an error (`tooManyRequestsError()`, `forbiddenError()`…) to reject the
+     * attempt, for example to require a CAPTCHA or to block an IP address.
+     */
+    beforeLogin?: (event: BeforeLoginEvent) => Promise<HttpError | void> | HttpError | void;
+    /**
+     * bcrypt cost of `hashPassword()`, and of the dummy hash compared when
+     * the user is unknown or has no password, so that every login takes the
+     * same time. Hashes with another cost are upgraded at login when
+     * `DataProvider.updatePasswordHash()` is defined. Defaults to 12.
+     */
+    passwordHashRounds?: number;
+    /**
+     * Writes the `username` claim in the access tokens. Defaults to `false`:
+     * a username is often an email address, readable by anyone holding the
+     * token (it is only base64 encoded); `sub` identifies the user.
+     */
+    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.
+     */
+    refreshTokenReuseInterval?: number;
+    /**
+     * 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>;
+    /**
+     * 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;
+}
+interface TokenSubject {
+    userId: string;
+    /** Written in the token with the `usernameClaim` setting only. */
+    username?: string;
+    /** `client_id` claim. Must be allowed by the `clients` setting. */
+    clientId?: string;
+}
+/** Token pair issued at login or by a refresh. */
+interface IssuedTokens extends TokenPair {
+    accessTokenExpiresAt: Date;
+    refreshTokenExpiresAt: Date;
+    /** 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 {
+        /** Authenticated user (`authPlugin`). Use `requireAuth` to require it. */
+        user: AuthUser | undefined;
+        /** Access token data of the authenticated user (`authPlugin`). */
+        auth: AuthSession | undefined;
+    }
+}
+
+type AuthErrorCode = 'INVALID_ACCESS_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'EXPIRED_REFRESH_TOKEN'
+/** A used refresh token was presented again: its session is revoked. */
+ | 'REFRESH_TOKEN_REUSED'
+/** Valid access token of a revoked session (`isSessionRevoked()`). */
+ | 'SESSION_REVOKED';
+/**
+ * Error raised by the token helpers.
+ */
+declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    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>;
+    /**
+     * Rotates a token pair. The access token may be expired, but must be
+     * signed by the key pair and match the refresh token.
+     *
+     * A refresh token can only be used once. Within
+     * `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
+     * `REFRESH_TOKEN_REUSED` is thrown.
+     *
+     * Throws `EXPIRED_REFRESH_TOKEN` when the session reached its inactivity
+     * or absolute timeout, and `INVALID_REFRESH_TOKEN` when
+     * `findUserById()` no longer returns the user (the session is revoked).
+     */
+    refreshTokens(tokens: TokenPair): Promise<IssuedTokens & {
+        userId: string;
+        user: AuthUser;
+    }>;
+    /**
+     * Verifies a valid (not expired) access token. With
+     * `DataProvider.isSessionRevoked()`, throws `SESSION_REVOKED` for the
+     * tokens of a revoked session.
+     */
+    verifyAccessToken(accessToken: string): Promise<AuthSession>;
+    /**
+     * 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.
+     *
+     * With `scope: 'all'`, revokes every session of the user, on every
+     * device. The token must then be active (neither used, revoked nor
+     * expired).
+     *
+     * Returns `undefined`, without revoking anything, for an unknown token,
+     * or an inactive token with `scope: 'all'`.
+     */
+    revokeSession(refreshToken: string, options?: {
+        scope?: LogoutScope;
+    }): Promise<RevokedSession | undefined>;
+    /**
+     * End of a session, when an absolute timeout applies to it (computed
+     * from the `auth_time` claim).
+     */
+    getSessionExpiresAt(session: AuthSession): Date | undefined;
+    /**
+     * Public keys as a JSON Web Key Set (RFC 7517): the active key first,
+     * then the additional keys. Other services can verify the tokens with
+     * it (`createRemoteJWKSet()` of jose).
+     */
+    getJwks(): Promise<{
+        keys: JWK[];
+    }>;
+    /** Roles of a user, from the `getUserRoles` setting. */
+    getUserRoles(user: AuthUser): readonly string[];
+    /**
+     * Sets the token cookies (cookie mode only). They expire with the
+     * refresh token (`refreshTokenExpiresAt` of issued tokens), or after the
+     * inactivity timeout.
+     */
+    setAuthCookies(res: DotpressResponse, tokens: TokenPair & {
+        refreshTokenExpiresAt?: Date;
+    }, expiresInSeconds?: number): void;
+    clearAuthCookies(res: DotpressResponse): void;
+    /**
+     * Whether a request may be authenticated by the cookies: protection
+     * against cross-site request forgery (see `cookies.trustedOrigins`).
+     * `authPlugin()` checks it on its routes and before reading the access
+     * token cookie.
+     */
+    isCookieAuthenticationAllowed(req: DotpressRequest): Promise<boolean>;
+    /**
+     * Hashes a password with bcrypt. Defaults to `passwordHashRounds`.
+     * Throws a `RangeError` for passwords longer than 72 bytes (see
+     * `isPasswordTooLong()`).
+     */
+    hashPassword(password: string, saltRounds?: number): Promise<string>;
+    /** Whether a bcrypt hash has another cost than `passwordHashRounds`. */
+    passwordNeedsRehash(passwordHash: string): boolean;
+    /**
+     * Hashes a verified password with `passwordHashRounds`, to upgrade its
+     * stored hash. Unlike `hashPassword()`, it accepts passwords longer than
+     * 72 bytes, created before the check.
+     */
+    rehashPassword(password: string): Promise<string>;
+    /**
+     * Verifies a password against its bcrypt hash. Without valid hash
+     * (unknown user, account without password), it compares the password
+     * with a dummy hash and returns `false`: the answer takes the same time,
+     * and does not reveal whether the account exists.
+     */
+    verifyPassword(password: string, passwordHash: string | null | undefined): Promise<boolean>;
+}
+/**
+ * Creates the authentication service. It works without an app (scripts,
+ * workers), and is plugged into an app with `authPlugin()`.
+ *
+ * @example
+ * 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;
+/**
+ * Whether a password exceeds the 72 bytes (UTF-8) read by bcrypt. Check
+ * it in the sign-up and password change schemas: `hashPassword()` rejects
+ * these passwords instead of silently truncating them.
+ *
+ * @example
+ * password: z.string().min(12).refine((p) => !isPasswordTooLong(p), 'Password too long')
+ */
+declare const isPasswordTooLong: (password: string) => boolean;
+/**
+ * Hashes a password with bcrypt (cost 12 by default). Throws a
+ * `RangeError` for passwords longer than 72 bytes (see
+ * `isPasswordTooLong()`).
+ */
+declare const generatePasswordHash: (password: string, saltRounds?: number) => Promise<string>;
+
+/** Context guaranteed by `requireAuth`, `requireRole()` and `requireClient()`. */
+interface AuthenticatedContext {
+    user: AuthUser;
+    auth: AuthSession;
+}
+/**
+ * Requires an authenticated user (`401 UNAUTHORIZED` otherwise). In the
+ * handlers of the routes using it, `ctx.user` and `ctx.auth` are defined.
+ */
+declare const requireAuth: _dotpress_core.Middleware<AuthenticatedContext>;
+/**
+ * Requires an authenticated user with at least one of the roles
+ * (`401 UNAUTHORIZED` without user, `403 FORBIDDEN` without role). Roles
+ * come from the `getUserRoles` setting of `createAuth()`.
+ */
+declare const requireRole: (...roles: [string, ...string[]]) => _dotpress_core.Middleware<AuthenticatedContext>;
+/**
+ * Requires an access token issued for one of the clients (`401
+ * UNAUTHORIZED` without user, `403 FORBIDDEN` for another client). For
+ * example, keeps the tokens of a mobile app away from the backoffice
+ * routes. It does not prove which application sends the request: combine
+ * it with `requireRole()`.
+ */
+declare const requireClient: (...clientIds: [string, ...string[]]) => _dotpress_core.Middleware<AuthenticatedContext>;
+
+interface AuthPluginOptions {
+    /** Prefix of the authentication routes. Defaults to `/auth`. */
+    prefix?: string;
+    /** Registers the authentication routes. Defaults to `true`. */
+    routes?: boolean;
+    /**
+     * Publishes the public keys at `GET /.well-known/jwks.json`, for other
+     * services verifying the tokens. Defaults to `false`.
+     */
+    jwks?: boolean;
+}
+/** Security schemes of the plugin, for documentation generators. */
+declare const AUTH_SECURITY_SCHEMES: {
+    readonly bearerAuth: {
+        readonly type: "http";
+        readonly scheme: "bearer";
+        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:
+ *
+ * - reads the access token of every request, and sets `ctx.user` and
+ *   `ctx.auth` when it is valid;
+ * - registers the `POST /auth/login`, `POST /auth/refresh`,
+ *   `GET /auth/me`, `POST /auth/restore` and `POST /auth/logout` routes.
+ */
+declare const authPlugin: (auth: Auth, options?: AuthPluginOptions) => {
+    readonly name: "auth";
+    readonly auth: Auth;
+    readonly securitySchemes: {
+        readonly bearerAuth: {
+            readonly type: "http";
+            readonly scheme: "bearer";
+            readonly bearerFormat: "JWT";
+        };
+    };
+    readonly setup: (api: _dotpress_core.PluginAPI) => Promise<void>;
 };
-export declare const configurePlugin: (settings: Settings) => Plugin;
-export declare const generatePasswordHash: (password: string, salt?: number) => Promise<string>;
-export { generateAccessToken, generateRefreshToken, generateTokensForUser };
+
+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 };