sentri 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Dialect } from 'kysely';
 import { Request, ErrorRequestHandler, RequestHandler, Router } from 'express';
 
 /**
@@ -20,11 +21,11 @@ import { Request, ErrorRequestHandler, RequestHandler, Router } from 'express';
 type SentriErrorCode = 'INVALID_CREDENTIALS' | 'USER_NOT_FOUND' | 'USER_ALREADY_EXISTS' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'FORBIDDEN' | 'UNAUTHORIZED' | 'INVALID_ROLE' | 'VALIDATION_ERROR' | 'CONFIGURATION_ERROR';
 /**
  * Default HTTP status codes for built-in error codes.
- * Custom codes that are not in this map default to 500.
+ * Custom codes not in this map default to 500.
  *
  * @internal
  */
-declare const AUTH_ERROR_STATUS: Record<string, number>;
+declare const SENTRI_ERROR_STATUS: Record<string, number>;
 /**
  * Base error class for all authentication and authorization failures in sentri.
  *
@@ -49,14 +50,12 @@ declare const AUTH_ERROR_STATUS: Record<string, number>;
  * ```typescript
  * import { SentriError } from 'sentri';
  *
- * // Domain error with a custom code and explicit HTTP status
  * export class PaymentError extends SentriError {
  *   constructor(message: string) {
  *     super('PAYMENT_FAILED', message, 402);
  *   }
  * }
  *
- * // Throw it anywhere in your routes — auth.errorHandler() catches it
  * router.post('/checkout', auth.protect(), async (req, res) => {
  *   const ok = await chargeCard(req.body.cardToken);
  *   if (!ok) throw new PaymentError('Card declined');
@@ -89,528 +88,20 @@ declare class SentriError extends Error {
      * subclassing with a custom `code`.
      */
     readonly statusCode: number;
-    /**
-     * @param code - Machine-readable error code. Use a built-in {@link SentriErrorCode}
-     *   or any string for custom subclasses.
-     * @param message - Human-readable description of the error.
-     * @param statusCode - HTTP status to use in the response. For built-in codes
-     *   this is derived automatically; for custom codes it defaults to `500`.
-     */
     constructor(code: SentriErrorCode | (string & {}), message: string, statusCode?: number);
 }
 
-/** Standard API response envelope returned by all built-in router endpoints. */
 interface ApiResponse<T = null> {
     error: boolean;
     statusCode: number;
     message: string;
     data: T | null;
 }
-/** Shape of a user row returned by the adapter — used internally by the library. */
-interface UserRecord {
-    id: string;
-    /**
-     * The credential identifier for this user (email, username, phone number, etc.).
-     * The adapter decides which column(s) this maps to.
-     */
-    identifier: string;
-    passwordHash: string;
-    /** Role names currently assigned to the user. */
-    roles: string[];
-}
-/** Shape of a session row returned by the adapter. */
-interface SessionRecord {
-    id: string;
-    userId: string;
-    expiresAt: Date;
-    createdAt: Date;
-}
-/** Data the library passes to the adapter when creating a new user. */
-interface CreateUserData {
-    /**
-     * The credential identifier supplied at registration (email, username, phone, etc.).
-     * Store this in whichever column(s) your schema uses for login lookup.
-     */
-    identifier: string;
-    passwordHash: string;
-    /** Validated role names to assign at creation. */
-    roles: string[];
-}
-/**
- * The database adapter interface the library depends on.
- *
- * Implement this to connect the library to any ORM or data layer.
- *
- * The library uses a single `identifier` string for credentials — your adapter
- * decides what that means: email column, username column, phone column, or a
- * query across multiple columns.
- */
-interface AuthAdapter {
-    user: {
-        /**
-         * Find a user by their login identifier.
-         *
-         * The adapter decides which column(s) to query — email, username, phone,
-         * or a combined lookup (`WHERE email = $1 OR username = $1`).
-         * Returns `null` if not found.
-         */
-        findByIdentifier(identifier: string): Promise<UserRecord | null>;
-        /** Find a user by their primary key. Returns `null` if not found. */
-        findById(id: string): Promise<UserRecord | null>;
-        /**
-         * Persist a new user with the given identifier, hashed password, and roles.
-         * The adapter maps `identifier` to the appropriate column(s) in your schema.
-         */
-        create(data: CreateUserData): Promise<{
-            id: string;
-        }>;
-        /**
-         * Replace the complete role list for a user.
-         * Called by `assignRoles` after merging the new roles with the existing ones.
-         */
-        updateRoles(userId: string, roles: string[]): Promise<void>;
-    };
-    session: {
-        /**
-         * Persist a new session and return its generated ID.
-         * `expiresAt` is computed from `refreshExpiresIn` in config.
-         */
-        create(data: {
-            userId: string;
-            expiresAt: Date;
-        }): Promise<{
-            id: string;
-        }>;
-        /**
-         * Find a session by its ID, including the associated user.
-         * Returns `null` if the session does not exist (i.e. has been revoked).
-         */
-        findById(sessionId: string): Promise<(SessionRecord & {
-            user: UserRecord;
-        }) | null>;
-        /** Delete a single session. Used during logout and token rotation. */
-        delete(sessionId: string): Promise<void>;
-        /** Delete all sessions belonging to a user. Used for "logout from all devices". */
-        deleteAllForUser(userId: string): Promise<void>;
-    };
-}
-/**
- * Custom service functions for the built-in auth router.
- *
- * Each key matches the internal service function name. When provided, the
- * custom function replaces the default service call for that route while the
- * router still handles request parsing, input validation, and response formatting.
- *
- * The function signatures mirror the internal services exactly but without the
- * `config` parameter — the library passes config at bind time.
- *
- * @example
- * createAuth({
- *   // ...
- *   router: {
- *     login: async (input) => {
- *       // add OTP check, custom user lookup, etc.
- *       // must return AuthResult
- *     },
- *     register: async (input) => {
- *       // send welcome email, set default profile, etc.
- *       // must return RegisterResult
- *     },
- *   },
- * });
- */
-interface RouterHandlers {
-    /**
-     * Replaces the default register service (`POST /register`).
-     *
-     * The router validates the request body (identifier, password, roles) first,
-     * then calls this function with the parsed input. Must return a `RegisterResult`.
-     * If omitted, the library's built-in registration logic runs instead.
-     *
-     * @example
-     * register: async (input) => {
-     *   const result = await defaultRegister(input);
-     *   if (result.success) {
-     *     await emailService.sendWelcome(input.identifier);
-     *   }
-     *   return result;
-     * }
-     */
-    register?: (input: RegisterInput) => Promise<RegisterResult>;
-    /**
-     * Replaces the default login service.
-     *
-     * The router validates the request body (identifier, password) first,
-     * then calls this function with the parsed input. Must return an `AuthResult`.
-     * If omitted, the library's built-in login logic runs instead.
-     *
-     * @example
-     * login: async (input) => {
-     *   // verify OTP before issuing tokens
-     *   const otpValid = await redis.get(`otp:${input.identifier}`);
-     *   if (!otpValid) {
-     *     return { success: false, error: new SentriError('INVALID_CREDENTIALS', 'OTP required') };
-     *   }
-     *   return defaultLogin(input);
-     * }
-     */
-    login?: (input: LoginInput) => Promise<AuthResult>;
-    /**
-     * Replaces the default refresh service.
-     *
-     * Receives the raw refresh token string extracted from the cookie.
-     * Must return a `RefreshResult`. If omitted, the built-in session-rotation
-     * logic runs instead.
-     *
-     * @example
-     * refresh: async (refreshToken) => {
-     *   const result = await defaultRefresh(refreshToken);
-     *   if (result.success) {
-     *     await auditLog.record('token_rotated', result.user.id);
-     *   }
-     *   return result;
-     * }
-     */
-    refresh?: (refreshToken: string) => Promise<RefreshResult>;
-    /**
-     * Replaces the default logout service.
-     *
-     * Receives the raw refresh token from the cookie, or `undefined` if no cookie
-     * was present. The router clears the cookie after this function resolves.
-     * If omitted, the built-in session deletion logic runs instead.
-     *
-     * @example
-     * logout: async (refreshToken) => {
-     *   if (refreshToken) {
-     *     await defaultLogout(refreshToken);
-     *     await auditLog.record('logout', refreshToken);
-     *   }
-     * }
-     */
-    logout?: (refreshToken: string | undefined) => Promise<void>;
-    /**
-     * Replaces the default logoutAll service.
-     *
-     * Receives the authenticated user's ID (from `req.user`, set by `protect()`).
-     * If omitted, the built-in "delete all sessions" logic runs instead.
-     *
-     * @example
-     * logoutAll: async (userId) => {
-     *   await defaultLogoutAll(userId);
-     *   await notifyService.push(userId, 'You have been signed out from all devices.');
-     * }
-     */
-    logoutAll?: (userId: string) => Promise<void>;
-    /**
-     * Replaces the default assignRoles service.
-     *
-     * The router validates the request body and params first, then calls this
-     * function with the target `userId` and the validated `roles` array.
-     * Must return an `AssignRolesResult`. If omitted, the built-in role-merge
-     * logic runs instead.
-     *
-     * @example
-     * assignRoles: async (userId, roles) => {
-     *   const result = await defaultAssignRoles(userId, roles);
-     *   if (result.success) {
-     *     await auditLog.record('roles_assigned', { userId, roles });
-     *   }
-     *   return result;
-     * }
-     */
-    assignRoles?: (userId: string, roles: string[]) => Promise<AssignRolesResult>;
-}
-/**
- * Lifecycle hooks called by the built-in auth router at key points in the
- * authentication flow. All hooks are optional and fire as side effects —
- * returning a rejected Promise from a hook **does not** abort the request.
- *
- * Common uses: audit logging, metrics, rate-limit counters, notifications.
- *
- * @example
- * createAuth({
- *   hooks: {
- *     onLogin: (user) => logger.info('login', { userId: user.id }),
- *     onFailedLogin: (identifier) => rateLimiter.hit(identifier),
- *     onLogout: (userId) => cache.invalidate(userId),
- *   },
- * });
- */
-interface AuthHooks {
-    /**
-     * Called after a successful login.
-     * Receives the authenticated user. Use for audit logs, login notifications, etc.
-     */
-    onLogin?: (user: AuthUser) => void | Promise<void>;
-    /**
-     * Called after a failed login attempt (wrong password or unknown identifier).
-     * Receives the identifier that was attempted and the error.
-     * Use to increment rate-limit counters or alert on repeated failures.
-     */
-    onFailedLogin?: (identifier: string, error: SentriError) => void | Promise<void>;
-    /**
-     * Called after a successful logout (single session or all sessions).
-     * Receives the user ID. Use for audit logs or cache invalidation.
-     */
-    onLogout?: (userId: string) => void | Promise<void>;
-}
-/**
- * Configuration passed to {@link createAuth}.
- *
- * Only `secret`, `validRoles`, and `adapter` are required.
- * All other fields have sensible defaults.
- *
- * @example
- * createAuth({
- *   secret: process.env.JWT_SECRET!,
- *   validRoles: ['user', 'admin'] as const,
- *   adapter: myAdapter,
- * });
- */
-interface AuthConfig<TRole extends string = string> {
-    /** Secret used to sign JWT tokens. Must not be empty. Keep this in an env variable. */
-    secret: string;
-    /**
-     * How long access tokens are valid.
-     * Accepts a duration string (`'15m'`, `'1h'`) or seconds as a number.
-     * @default '15m'
-     */
-    accessExpiresIn?: string | number;
-    /**
-     * How long refresh tokens / sessions are valid.
-     * Accepts a duration string (`'7d'`, `'30d'`) or seconds as a number.
-     * @default '7d'
-     */
-    refreshExpiresIn?: string | number;
-    /**
-     * HMAC signing algorithm used for JWTs.
-     * @default 'HS256'
-     */
-    algorithm?: 'HS256' | 'HS384' | 'HS512';
-    /**
-     * bcrypt cost factor. Higher = slower hashing but more secure.
-     * @default 12
-     */
-    saltRounds?: number;
-    /**
-     * Exhaustive list of role names your application uses.
-     * Registration will be rejected with `INVALID_ROLE` if a role outside this list is requested.
-     * Use `as const` to get TypeScript union-type safety on `authorize()`.
-     *
-     * @example
-     * validRoles: ['user', 'admin', 'moderator'] as const
-     */
-    validRoles: readonly TRole[];
-    /** ORM adapter that connects the library to your database. */
-    adapter: AuthAdapter;
-    /**
-     * API key required to call `POST /register`.
-     *
-     * When set, the `/register` endpoint expects an `X-Api-Key` header whose
-     * value matches this string exactly. Requests without the header, or with
-     * the wrong value, are rejected with HTTP 401 (`UNAUTHORIZED`).
-     *
-     * Use this to restrict self-registration — for example, only your own
-     * back-office service or admin panel should be able to create new accounts,
-     * so you never expose user registration to arbitrary callers.
-     *
-     * @example
-     * createAuth({
-     *   // ...
-     *   apiKey: process.env.REGISTER_API_KEY!,
-     * });
-     *
-     * // Client must send:
-     * // POST /auth/register
-     * // X-Api-Key: <value of REGISTER_API_KEY>
-     */
-    apiKey?: string;
-    /**
-     * Custom service functions for individual routes in the built-in auth router.
-     *
-     * The router still handles request parsing, validation, and response formatting.
-     * Only the core service logic is replaced by your function.
-     *
-     * @example
-     * createAuth({
-     *   // ...
-     *   router: {
-     *     login: async (input) => {
-     *       // verify OTP, then delegate to default or return custom result
-     *       return { success: true, accessToken, refreshToken, user };
-     *     },
-     *     register: async (input) => {
-     *       // send welcome email after successful registration
-     *       const result = await defaultRegister(input);
-     *       if (result.success) await emailService.sendWelcome(input.identifier);
-     *       return result;
-     *     },
-     *   },
-     * });
-     */
-    router?: RouterHandlers;
-    /**
-     * When set, the built-in router (`auth.router()`) stores the refresh token
-     * in an httpOnly cookie instead of returning it in the response body.
-     *
-     * The `refreshToken` field is omitted from `/login` and `/refresh` responses.
-     * The `/logout` and `/logout-all` routes automatically clear the cookie.
-     *
-     * No extra middleware (e.g. `cookie-parser`) is required.
-     *
-     * @example
-     * createAuth({
-     *   // ...
-     *   cookie: { secure: process.env.NODE_ENV === 'production' },
-     * });
-     */
-    cookie?: CookieConfig;
-    /**
-     * Lifecycle hooks called at key points in the auth flow.
-     *
-     * All hooks fire as side effects — a rejected hook Promise is silently
-     * swallowed so a broken hook can never take down a login request.
-     *
-     * @example
-     * createAuth({
-     *   hooks: {
-     *     onLogin: async (user) => {
-     *       await auditLog.record('login', user.id);
-     *     },
-     *     onFailedLogin: (identifier) => {
-     *       rateLimiter.hit(`login:${identifier}`);
-     *     },
-     *   },
-     * });
-     */
-    hooks?: AuthHooks;
-    /**
-     * Optional guard called by `protect()` after verifying the access token's
-     * signature and expiry. Return `true` to reject the token immediately, even
-     * if it is cryptographically valid.
-     *
-     * Use this for **immediate token revocation** — for example, store revoked
-     * `sessionId` values in Redis and check membership here:
-     *
-     * ```typescript
-     * isTokenRevoked: async (sessionId) =>
-     *   await redis.sismember('revoked_sessions', sessionId),
-     * ```
-     *
-     * **Performance note:** this function is called on every protected request.
-     * Keep it fast (e.g. a single Redis GET/SISMEMBER) or the latency benefit
-     * of stateless access tokens is lost. If you can tolerate a short revocation
-     * window equal to `accessExpiresIn`, omit this hook entirely.
-     *
-     * @param sessionId - The `sessionId` embedded in the access token at login time.
-     * @returns `true` if the token should be rejected, `false` (or `undefined`) to allow.
-     */
-    isTokenRevoked?: (sessionId: string) => boolean | Promise<boolean>;
-    /**
-     * When set, the built-in router also stores the **access token** in a
-     * non-httpOnly cookie so browser JavaScript can read it via
-     * `document.cookie` or the `getCurrentAccessToken` helper.
-     *
-     * `protect()` reads the access token from this cookie when no
-     * `Authorization: Bearer` header is present, so clients can skip the
-     * manual header management entirely.
-     *
-     * The cookie's `max-age` is derived automatically from `config.accessExpiresIn`.
-     * When `protect()` performs a silent refresh, the access token cookie is
-     * updated in the same response.
-     *
-     * @example
-     * createAuth({
-     *   accessExpiresIn: '5m',
-     *   accessCookie: { secure: process.env.NODE_ENV === 'production' },
-     *   cookie:        { secure: process.env.NODE_ENV === 'production' },
-     * });
-     */
-    accessCookie?: AccessCookieConfig;
-}
-/**
- * Cookie settings for storing the refresh token in an httpOnly cookie.
- * All fields are optional — defaults are chosen for security.
- */
-interface CookieConfig {
-    /**
-     * Name of the cookie.
-     * @default 'refresh_token'
-     */
-    name?: string;
-    /**
-     * Prevents JavaScript from reading the cookie (`document.cookie`).
-     * @default true
-     */
-    httpOnly?: boolean;
-    /**
-     * Restricts the cookie to HTTPS connections.
-     * Set to `true` in production.
-     * @default false
-     */
-    secure?: boolean;
-    /**
-     * Controls cross-site request behaviour.
-     * @default 'strict'
-     */
-    sameSite?: 'strict' | 'lax' | 'none';
-    /**
-     * URL path the cookie is scoped to.
-     * @default '/'
-     */
-    path?: string;
-}
-/**
- * Cookie settings for storing the access token in a **non**-httpOnly cookie.
- *
- * Because `httpOnly` is intentionally `false`, browser JavaScript can read this
- * cookie via `document.cookie` or the `getCurrentAccessToken` helper, which makes
- * it convenient for SPAs that need to attach the token to outgoing requests.
- *
- * The cookie's `max-age` is derived automatically from `config.accessExpiresIn`.
- *
- * All fields are optional — safe defaults are applied.
- */
-interface AccessCookieConfig {
-    /**
-     * Name of the access token cookie.
-     * @default 'access_token'
-     */
-    name?: string;
-    /**
-     * Restricts the cookie to HTTPS connections.
-     * Set to `true` in production.
-     * @default false
-     */
-    secure?: boolean;
-    /**
-     * Controls cross-site request behaviour.
-     * @default 'strict'
-     */
-    sameSite?: 'strict' | 'lax' | 'none';
-    /**
-     * URL path the cookie is scoped to.
-     * @default '/'
-     */
-    path?: string;
-}
-/**
- * The user payload injected as `req.user` after `protect()` runs.
- *
- * Access tokens issued by sentri >= 1.1.0 embed a `sessionId` that is
- * validated against the database on every request. Tokens from older
- * versions that lack this claim are accepted but bypass session validation.
- */
 interface AuthUser<TRole extends string = string> {
     id: string;
-    /**
-     * The credential identifier for this user (email, username, phone, etc.).
-     * Reflects whatever value was passed as `identifier` at registration or login.
-     */
     identifier: string;
     roles: TRole[];
 }
-/** Return type of `register`. */
 type RegisterResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -618,7 +109,6 @@ type RegisterResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
-/** Return type of `login`. */
 type AuthResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -628,7 +118,6 @@ type AuthResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
-/** Return type of `assignRoles`. */
 type AssignRolesResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -636,7 +125,26 @@ type AssignRolesResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
-/** Return type of `refresh`. */
+type GetUserResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+type ChangeIdentifierResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+type ChangePasswordResult = {
+    success: true;
+} | {
+    success: false;
+    error: SentriError;
+};
 type RefreshResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -646,26 +154,87 @@ type RefreshResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
-/** Input for `register`. */
 interface RegisterInput<TRole extends string = string> {
-    /**
-     * The user's login credential — email, username, phone number, or any unique string.
-     * The adapter maps this to the appropriate column in your database.
-     */
     identifier: string;
     password: string;
-    /** Roles to assign at creation. Must be a subset of `validRoles`. */
     roles?: TRole[];
 }
-/** Input for `login`. */
 interface LoginInput {
-    /**
-     * The user's login credential — email, username, phone number, or any unique string.
-     * The adapter's `findByIdentifier` handles the lookup.
-     */
     identifier: string;
     password: string;
 }
+interface CookieConfig {
+    name?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    path?: string;
+}
+interface AccessCookieConfig {
+    name?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    path?: string;
+}
+interface AuthHooks {
+    onLogin?: (user: AuthUser) => void | Promise<void>;
+    onFailedLogin?: (identifier: string, error: SentriError) => void | Promise<void>;
+    onLogout?: (userId: string) => void | Promise<void>;
+}
+interface RouterHandlers {
+    register?: (input: RegisterInput) => Promise<RegisterResult>;
+    login?: (input: LoginInput) => Promise<AuthResult>;
+    refresh?: (refreshToken: string) => Promise<RefreshResult>;
+    logout?: (refreshToken: string | undefined) => Promise<void>;
+    logoutAll?: (userId: string) => Promise<void>;
+    assignRoles?: (userId: string, roles: string[]) => Promise<AssignRolesResult>;
+    changeIdentifier?: (userId: string, newIdentifier: string) => Promise<ChangeIdentifierResult>;
+    changePassword?: (userId: string, currentPassword: string, newPassword: string) => Promise<ChangePasswordResult>;
+}
+interface ServerAuthConfig<TRole extends string = string> {
+    mode: 'server';
+    /** Kysely Dialect (e.g. PostgresDialect, MysqlDialect, SqliteDialect). */
+    dialect: Dialect;
+    /**
+     * JWT signing secret.
+     * - HS256/HS384/HS512: plain string, minimum 32 characters.
+     * - RS256/RS384/RS512: RSA private key in PEM format.
+     */
+    secret: string;
+    /**
+     * JWT signing algorithm.
+     * Use RS256/RS384/RS512 to enable the GET /keys endpoint for SSO.
+     * @default 'HS256'
+     */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    validRoles: readonly TRole[];
+    /** @default '15m' */
+    accessExpiresIn?: string | number;
+    /** @default '7d' */
+    refreshExpiresIn?: string | number;
+    /** @default 12 */
+    saltRounds?: number;
+    apiKey?: string;
+    cookie?: CookieConfig;
+    accessCookie?: AccessCookieConfig;
+    hooks?: AuthHooks;
+    router?: RouterHandlers;
+    isTokenRevoked?: (sessionId: string) => boolean | Promise<boolean>;
+    /**
+     * Redis connection URL (e.g. `redis://localhost:6379`).
+     * When set, `auth.idempotencyMiddleware()` uses Redis as the cache backend
+     * instead of an in-memory Map — required for multi-process deployments.
+     */
+    redisUrl?: string;
+}
+interface ClientAuthConfig<TRole extends string = string> {
+    mode: 'client';
+    /** URL of the auth server's public key endpoint (e.g. https://auth.myapp.com/auth/keys). */
+    keyUri: string;
+    /** Optional — only needed for TypeScript type safety on authorize(). */
+    validRoles?: readonly TRole[];
+}
+type AuthConfig<TRole extends string = string> = ServerAuthConfig<TRole> | ClientAuthConfig<TRole>;
 
 /** A function that determines whether the current request is permitted. */
 type PermitCheck = (request: Request) => boolean | Promise<boolean>;
@@ -766,288 +335,218 @@ interface ErrorHandlerOptions {
  */
 declare function createErrorHandler(options?: ErrorHandlerOptions): ErrorRequestHandler;
 
+interface IdempotencyOptions {
+    /** @default 300_000 (5 minutes) */
+    ttl?: number;
+    /** @default 'X-Idempotency-Key' */
+    header?: string;
+    /** @default ['POST', 'PUT', 'PATCH'] */
+    methods?: string[];
+    /**
+     * Max in-memory entries (ignored when redisUrl is set).
+     * @default 10_000
+     */
+    maxSize?: number;
+    /**
+     * Redis connection URL (e.g. `redis://localhost:6379`).
+     * When set, uses Redis as the cache backend instead of in-memory Map.
+     */
+    redisUrl?: string;
+}
 /**
- * The bound auth client returned by {@link createAuth}.
+ * Middleware that deduplicates non-idempotent requests.
+ *
+ * When a request arrives with a matching idempotency key header, the cached
+ * response is replayed immediately — the handler is not called again.
+ * Responses are only cached for 2xx status codes.
  *
- * All methods are pre-configured with the options passed to `createAuth` —
- * you never need to pass config around yourself.
+ * Two backends are available:
+ * - **In-memory** (default) — zero dependencies, single-process only.
+ * - **Redis** — set `redisUrl` to share state across processes/instances.
+ *
+ * When using `createAuthServer()`, prefer `auth.idempotencyMiddleware()` instead —
+ * it automatically inherits the `redisUrl` from server config.
+ *
+ * @example
+ * // Standalone usage
+ * app.use(createIdempotencyMiddleware({ ttl: 60_000 }));
  *
- * `TRole` is inferred from `validRoles` and narrows role strings to your
- * application's exact union type everywhere (authorize, req.user, etc.).
+ * @example
+ * // Multi-process (Redis)
+ * app.use(createIdempotencyMiddleware({ redisUrl: 'redis://localhost:6379' }));
  */
+declare function createIdempotencyMiddleware(options?: IdempotencyOptions): RequestHandler;
+
 interface AuthClient<TRole extends string = string> {
-    /**
-     * Express middleware factory that enforces authentication.
-     *
-     * Reads the `Authorization: Bearer <token>` header, verifies the access token,
-     * confirms the session is still active in the database, and injects the decoded
-     * payload as `request.user`. Calls `next(SentriError)` on any failure.
-     *
-     * @example
-     * router.get('/me', auth.protect(), (request, response) => {
-     *   response.json(request.user);
-     * });
-     */
+    /** JWT authentication middleware. Reads Bearer token or access_token cookie. */
     protect(): RequestHandler;
-    /**
-     * Express middleware factory that enforces role-based access.
-     *
-     * Must be used **after** `protect()`. Passes if the authenticated user has
-     * at least one of the specified roles; otherwise calls `next(SentriError)` with
-     * code `FORBIDDEN`.
-     *
-     * @example
-     * router.delete('/posts/:id', auth.protect(), auth.authorize('admin'), handler);
-     */
+    /** Role-based access middleware. Must follow protect(). */
     authorize(...roles: TRole[]): RequestHandler;
-    /**
-     * Express middleware factory for resource-level permission checks.
-     *
-     * Must be used **after** `protect()`. Evaluates a check function against the
-     * current request and calls `next(SentriError)` with `FORBIDDEN` if it returns `false`.
-     *
-     * Accepts either a bare check function or an options object with an optional
-     * `roles` list whose members bypass the check entirely.
-     *
-     * @example
-     * // User can only update their own profile
-     * router.put('/users/:id',
-     *   auth.protect(),
-     *   auth.permit((request) => request.user!.id === request.params['id']),
-     *   handler,
-     * );
-     *
-     * @example
-     * // Admins bypass the check; others must own the resource
-     * router.delete('/posts/:id',
-     *   auth.protect(),
-     *   auth.permit({
-     *     roles: ['admin'],
-     *     check: async (request) => {
-     *       const post = await db.post.findUnique({ where: { id: request.params['id'] } });
-     *       return post?.authorId === request.user!.id;
-     *     },
-     *   }),
-     *   handler,
-     * );
-     */
+    /** Resource-level permission middleware. Must follow protect(). */
     permit(check: PermitCheck): RequestHandler;
     permit(options: PermitOptions<TRole>): RequestHandler;
-    /** Hash a plain-text password using the configured `saltRounds`. */
+    /** Global error handler middleware. Mount after all routes. */
+    errorHandler(options?: ErrorHandlerOptions): ErrorRequestHandler;
+}
+interface ServerAuthClient<TRole extends string = string> extends AuthClient<TRole> {
+    /** Hash a plain-text password. */
     hashPassword(plain: string): Promise<string>;
-    /** Compare a plain-text password against a stored bcrypt hash. */
+    /** Compare a plain-text password against a bcrypt hash. */
     verifyPassword(plain: string, hash: string): Promise<boolean>;
-    /** Sign an access token for the given user payload. */
+    /** Sign an access token. */
     signAccessToken(payload: AuthUser<TRole>): string;
-    /** Sign a refresh token bound to a session ID. */
+    /** Sign a refresh token. */
     signRefreshToken(sessionId: string): string;
-    /** Verify and decode an access token. Throws `SentriError` if invalid or expired. */
+    /** Verify an access token. */
     verifyAccessToken(token: string): AuthUser<TRole>;
-    /** Verify and decode a refresh token. Throws `SentriError` if invalid or expired. */
+    /** Verify a refresh token. */
     verifyRefreshToken(token: string): {
         sessionId: string;
     };
-    /**
-     * Extract the raw access token string from an incoming Express request.
-     *
-     * Checks two sources in order:
-     * 1. `Authorization: Bearer <token>` header
-     * 2. Access token cookie (name from `config.accessCookie.name`, default `'access_token'`)
-     *
-     * Returns `undefined` when neither source is present.
-     *
-     * Useful in custom middleware or logging where you need the raw token without
-     * running full JWT verification.
-     *
-     * @example
-     * app.use((req, _res, next) => {
-     *   const token = auth.getCurrentAccessToken(req);
-     *   if (token) logger.debug('access token present');
-     *   next();
-     * });
-     */
+    /** Extract the raw access token from an Express request. */
     getCurrentAccessToken(request: Request): string | undefined;
     /**
-     * Returns a pre-built Express Router with all standard auth endpoints mounted.
-     *
-     * Endpoints:
-     * - `POST /register` — register a new user. Requires `X-Api-Key` header when `config.apiKey` is set.
-     * - `POST /login` — authenticate, sets refresh token cookie, returns `{ accessToken, user }`
-     * - `POST /refresh` — rotate refresh token, returns new `{ accessToken }`
-     * - `POST /logout` — delete the current session; the bound access token is immediately rejected by `protect()`
-     * - `POST /logout-all` — delete all sessions for the user (requires valid access token)
-     * - `GET  /me` — return the authenticated user
-     * - `POST /users/:userId/roles` — assign roles (requires admin)
-     *
-     * Requires `express.json()` before the router.
-     *
-     * @example
-     * app.use(express.json());
-     * app.use('/auth', auth.router());
+     * Pre-built Express Router with auth endpoints:
+     * POST /register, POST /login, POST /refresh, POST /logout,
+     * POST /logout-all, GET /me, POST /users/:userId/roles,
+     * GET /keys (only when algorithm is RS256/RS384/RS512)
      */
     router(): Router;
     /**
-     * Returns an Express error-handling middleware that formats every `SentriError`
-     * (and any subclass) into the standard sentri response envelope:
-     *
-     * ```json
-     * { "error": true, "statusCode": 401, "code": "UNAUTHORIZED", "message": "...", "data": null }
-     * ```
-     *
-     * Mount it **after all your routes** so it acts as the global catch-all for
-     * both sentri errors and your own `SentriError` subclasses.
-     *
-     * @example
-     * import { SentriError } from 'sentri';
-     *
-     * // Define app-specific errors by extending SentriError
-     * class NotFoundError extends SentriError {
-     *   constructor(resource: string) {
-     *     super('NOT_FOUND', `${resource} not found`, 404);
-     *   }
-     * }
-     *
-     * app.use('/auth', auth.router());
-     * app.use('/api', apiRouter);
-     *
-     * // Catches errors from sentri AND your own subclasses
-     * app.use(auth.errorHandler());
-     *
-     * @example
-     * // With optional unhandled-error logger
-     * app.use(auth.errorHandler({
-     *   onUnhandled: (err) => logger.error('Unexpected error', { err }),
-     * }));
-     */
-    errorHandler(options?: ErrorHandlerOptions): ErrorRequestHandler;
+     * Run database migrations to create sentri_users and sentri_sessions tables.
+     * Safe to call on every startup — uses IF NOT EXISTS.
+     */
+    migrate(): Promise<void>;
+    /**
+     * Idempotency middleware. Caches successful responses and replays them for
+     * duplicate requests with the same idempotency key header.
+     * Uses Redis backend when `redisUrl` is set in server config; otherwise in-memory.
+     */
+    idempotencyMiddleware(options?: IdempotencyOptions): RequestHandler;
+    /** Register a new user. */
+    register(input: RegisterInput<TRole>): Promise<RegisterResult<TRole>>;
+    /** Authenticate a user, returns access + refresh tokens. */
+    login(input: LoginInput): Promise<AuthResult<TRole>>;
+    /** Rotate a refresh token, returns new token pair. */
+    refresh(refreshToken: string): Promise<RefreshResult<TRole>>;
+    /** Invalidate the session associated with the given refresh token. */
+    logout(refreshToken: string): Promise<void>;
+    /** Invalidate all sessions for a user. */
+    logoutAll(userId: string): Promise<void>;
+    /** Fetch a user by ID. Returns `success: false` if not found. */
+    getUser(userId: string): Promise<GetUserResult<TRole>>;
+    /** Change a user's identifier (username/email). */
+    changeIdentifier(userId: string, newIdentifier: string): Promise<ChangeIdentifierResult<TRole>>;
+    /** Change a user's password and revoke all their sessions. */
+    changePassword(userId: string, currentPassword: string, newPassword: string): Promise<ChangePasswordResult>;
+    /** Add roles to a user (existing roles are preserved). */
+    assignRoles(userId: string, roles: TRole[]): Promise<AssignRolesResult<TRole>>;
+}
+interface ClientAuthClient<TRole extends string = string> extends AuthClient<TRole> {
 }
 /**
- * Create a fully configured auth client for your application.
+ * Create a Sentri auth client.
  *
- * Pass your config once here and use the returned client everywhere — it
- * binds all library functions to your settings so you never need to pass
- * config manually.
+ * Pass `mode: 'server'` to get a full auth server with database, JWT signing,
+ * and built-in endpoints. Pass `mode: 'client'` to get a stateless verifier
+ * that validates tokens via the server's JWKS endpoint.
  *
- * The generic parameter `TRole` is inferred automatically from `validRoles`
- * when you use `as const`:
+ * For server mode with PostgreSQL, prefer `createAuthServer()` — it handles
+ * RSA key generation and database setup automatically.
  *
  * @example
- * export const auth = createAuth({
+ * // Server mode
+ * const auth = createAuth({
+ *   mode: 'server',
+ *   dialect: new PostgresDialect({ pool: new Pool({ connectionString: DATABASE_URL }) }),
  *   secret: process.env.JWT_SECRET!,
- *   validRoles: ['user', 'admin', 'moderator'] as const,
- *   adapter: myAdapter,
+ *   validRoles: ['user', 'admin'] as const,
  * });
  *
- * // auth.authorize('admin') is type-safe — 'superuser' would be a compile error.
+ * @example
+ * // Client mode
+ * const auth = createAuth({
+ *   mode: 'client',
+ *   keyUri: 'https://auth.myapp.com/auth/keys',
+ * });
  */
-declare function createAuth<TRole extends string = string>(config: AuthConfig<TRole>): AuthClient<TRole>;
+declare function createAuth<TRole extends string = string>(config: ServerAuthConfig<TRole>): ServerAuthClient<TRole>;
+declare function createAuth<TRole extends string = string>(config: ClientAuthConfig<TRole>): ClientAuthClient<TRole>;
 
-/**
- * Options for {@link createIdempotencyMiddleware}.
- */
-interface IdempotencyOptions {
-    /**
-     * How long a cached response is kept, in milliseconds.
-     * @default 300_000 (5 minutes)
-     */
-    ttl?: number;
-    /**
-     * Name of the request header that carries the idempotency key.
-     * @default 'X-Idempotency-Key'
-     */
-    header?: string;
-    /**
-     * HTTP methods to apply idempotency checking to.
-     * @default ['POST', 'PUT', 'PATCH']
-     */
-    methods?: string[];
+type PostgresConfig = {
+    connectionString: string;
+    max?: number;
+} | {
+    host?: string;
+    port?: number;
+    database: string;
+    user: string;
+    password: string;
+    max?: number;
+};
+
+interface CreateServerOptions<TRole extends string = string> {
+    validRoles: readonly TRole[];
+    db: PostgresConfig;
+    accessExpiresIn?: string | number;
+    refreshExpiresIn?: string | number;
+    saltRounds?: number;
+    apiKey?: string;
+    cookie?: CookieConfig;
+    accessCookie?: AccessCookieConfig;
+    hooks?: AuthHooks;
+    router?: RouterHandlers;
+    isTokenRevoked?: (sessionId: string) => boolean | Promise<boolean>;
     /**
-     * Maximum number of cached entries. When the limit is reached, the oldest
-     * entry (by insertion order) is evicted before a new one is stored. This
-     * prevents unbounded memory growth under high traffic with unique keys.
-     * @default 10_000
+     * Redis connection URL (e.g. `redis://localhost:6379`).
+     * When set, `auth.idempotencyMiddleware()` uses Redis as the cache backend.
      */
-    maxSize?: number;
+    redisUrl?: string;
 }
 /**
- * Creates an Express middleware that makes mutating operations idempotent.
+ * Create a Sentri auth server for PostgreSQL.
  *
- * When a request includes an idempotency-key header (default `X-Idempotency-Key`),
- * the middleware:
- * 1. Attaches the key as `req.requestId` and echoes it in the `X-Request-Id` response header.
- * 2. Checks an in-memory cache for a prior successful response under that key.
- *    - **Cache hit**: replies immediately with the stored response and sets
- *      `X-Idempotent-Replayed: true` — no handler runs.
- *    - **Cache miss**: intercepts `response.json()` to store the result after the
- *      handler completes (only 2xx responses are cached).
- *
- * The cache is per-process and in-memory with a configurable TTL. It is suitable
- * for protecting create/update operations against duplicate submissions (network
- * retries, double-clicks) within the same server process. For multi-process
- * deployments consider using a shared cache such as Redis.
- *
- * Requests without the idempotency-key header, or using non-mutating methods, pass
- * straight through to the next middleware.
+ * Convenience wrapper over `createAuth()` that:
+ * - Accepts plain PostgreSQL connection params instead of a Kysely dialect
+ * - Generates an RSA-2048 key pair at startup (RS256, ephemeral per process)
+ * - Exposes `GET /keys` (JWKS) automatically for SSO with client-mode apps
  *
  * @example
- * import { createIdempotencyMiddleware } from 'sentri';
- *
- * // Apply globally before routes
- * app.use(createIdempotencyMiddleware());
- *
- * // Or scoped to a router with a shorter TTL
- * apiRouter.use(createIdempotencyMiddleware({ ttl: 60_000 }));
- */
-declare function createIdempotencyMiddleware(options?: IdempotencyOptions): RequestHandler;
-
-/**
- * Extract the access token from an incoming Express request.
- *
- * Looks in two places, in order:
- * 1. `Authorization: Bearer <token>` header
- * 2. The access token cookie (name from `config.accessCookie.name`, default `'access_token'`)
- *
- * Returns `undefined` when neither source is present.
- *
- * This is the server-side companion to reading `document.cookie` on the client.
- * Use it when you need the raw token string for custom middleware or logging.
+ * const auth = createAuthServer({
+ *   validRoles: ['user', 'admin'] as const,
+ *   db: { connectionString: process.env.DATABASE_URL! },
+ * });
+ * await auth.migrate();
+ * app.use('/auth', auth.router());
  *
  * @example
- * import { getCurrentAccessToken } from 'sentri';
- *
- * app.get('/debug/token', (req, res) => {
- *   const token = getCurrentAccessToken(req, config);
- *   res.json({ token });
+ * // With Redis idempotency cache (multi-process deployments)
+ * const auth = createAuthServer({
+ *   validRoles: ['user', 'admin'] as const,
+ *   db: { connectionString: process.env.DATABASE_URL! },
+ *   redisUrl: process.env.REDIS_URL,
  * });
+ * app.use(auth.idempotencyMiddleware());
  */
-declare function getCurrentAccessToken(request: Request, config: AuthConfig): string | undefined;
+declare function createAuthServer<TRole extends string = string>(options: CreateServerOptions<TRole>): ServerAuthClient<TRole>;
 
 /**
- * Register a new user.
- *
- * Validates that every requested role is in `validRoles`, rejects duplicate
- * identifiers, hashes the password with bcrypt, creates the user record via
- * the adapter, and returns the created user.
- *
- * No tokens are issued — the caller should invoke `login` after registration
- * if immediate authentication is desired.
- *
- * @param input - Registration data: identifier, plain-text password, and optional roles.
- * @param config - Auth configuration containing the adapter and role definitions.
- * @returns `{ success: true, user }` on success, or `{ success: false, error }` with
- *   code `INVALID_ROLE` or `USER_ALREADY_EXISTS` on failure.
+ * Extract the raw access token string from an Express request.
+ * Reads `Authorization: Bearer <token>` header first; falls back to the
+ * `access_token` cookie (or the name set in `accessCookie.name`).
+ * Returns `undefined` when no token is present.
  */
-declare function register(input: RegisterInput, config: AuthConfig): Promise<RegisterResult>;
+declare function getCurrentAccessToken(request: Request, config: ServerAuthConfig): string | undefined;
+
+declare function register(input: RegisterInput, config: ServerAuthConfig): Promise<RegisterResult>;
 
 declare global {
     namespace Express {
         interface Request {
-            /** Decoded user payload injected by `protect()` on every authenticated request. */
             user?: AuthUser;
-            /** Idempotency key from `X-Idempotency-Key` header, attached by `createIdempotencyMiddleware()`. */
             requestId?: string;
         }
     }
 }
 
-export { AUTH_ERROR_STATUS, type AccessCookieConfig, type ApiResponse, type AssignRolesResult, type AuthAdapter, type AuthClient, type AuthConfig, type AuthHooks, type AuthResult, type AuthUser, type CookieConfig, type CreateUserData, type ErrorHandlerOptions, type IdempotencyOptions, type LoginInput, type PermitCheck, type PermitOptions, type RefreshResult, type RegisterInput, type RegisterResult, type RouterHandlers, SentriError, type SentriErrorCode, type SessionRecord, type UserRecord, createAuth, createErrorHandler, createIdempotencyMiddleware, getCurrentAccessToken, register };
+export { type AccessCookieConfig, type ApiResponse, type AssignRolesResult, type AuthClient, type AuthConfig, type AuthHooks, type AuthResult, type AuthUser, type ChangeIdentifierResult, type ChangePasswordResult, type ClientAuthClient, type ClientAuthConfig, type CookieConfig, type CreateServerOptions, type ErrorHandlerOptions, type GetUserResult, type IdempotencyOptions, type LoginInput, type PermitCheck, type PermitOptions, type PostgresConfig, type RefreshResult, type RegisterInput, type RegisterResult, type RouterHandlers, SENTRI_ERROR_STATUS, SentriError, type SentriErrorCode, type ServerAuthClient, type ServerAuthConfig, createAuth, createAuthServer, createErrorHandler, createIdempotencyMiddleware, getCurrentAccessToken, register };