sentri 1.1.2 → 2.0.0

package/dist/index.d.ts

@@ -1,18 +1,1053 @@
-import type { AuthUser } from './types/auth.js';
+import { Request, ErrorRequestHandler, RequestHandler, Router } from 'express';
+
+/**
+ * Discriminant codes for built-in {@link SentriError} instances.
+ *
+ * - `INVALID_CREDENTIALS` — identifier or password did not match (intentionally vague to prevent user enumeration)
+ * - `USER_NOT_FOUND` — an operation required a user that does not exist
+ * - `USER_ALREADY_EXISTS` — registration was attempted with an identifier already in the database
+ * - `TOKEN_EXPIRED` — the JWT was valid but its `exp` claim is in the past
+ * - `TOKEN_INVALID` — the JWT could not be verified (bad signature, malformed, wrong type)
+ * - `FORBIDDEN` — the user is authenticated but lacks the required role
+ * - `UNAUTHORIZED` — no valid access token was present on the request, or the session was revoked
+ * - `INVALID_ROLE` — a role name was used that is not in `validRoles`
+ * - `VALIDATION_ERROR` — a required field was missing or had an invalid value
+ * - `CONFIGURATION_ERROR` — `createAuth` was called with an invalid configuration
+ *
+ * When you extend {@link SentriError} for your own error types you can use any
+ * string as `code` — it does not need to be one of these built-in values.
+ */
+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.
+ *
+ * @internal
+ */
+declare const AUTH_ERROR_STATUS: Record<string, number>;
+/**
+ * Base error class for all authentication and authorization failures in sentri.
+ *
+ * Every error thrown by sentri is an instance of `SentriError`. The `code`
+ * property is a machine-readable string that lets you distinguish error
+ * types without string-matching on the message. Built-in codes are listed
+ * in {@link SentriErrorCode}; custom subclasses may use any string.
+ *
+ * The `statusCode` property holds the HTTP status that the built-in router
+ * and `auth.errorHandler()` will use in the response. For built-in codes
+ * it is derived automatically. Pass it explicitly when subclassing with a
+ * custom code.
+ *
+ * ---
+ *
+ * **Extending SentriError**
+ *
+ * You can create application-specific error classes by extending `SentriError`.
+ * Any subclass will be caught automatically by `auth.errorHandler()` because
+ * `instanceof SentriError` is `true` for all subclasses.
+ *
+ * ```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');
+ *   res.json({ success: true });
+ * });
+ * ```
+ *
+ * ---
+ *
+ * **Error handling in custom routes**
+ *
+ * ```typescript
+ * app.use('/auth', auth.router());
+ * app.use('/api', apiRouter);
+ *
+ * // Mount after all routes — catches SentriError from sentri AND your subclasses
+ * app.use(auth.errorHandler());
+ * ```
+ */
+declare class SentriError extends Error {
+    /**
+     * Machine-readable error code.
+     * Built-in codes are defined by {@link SentriErrorCode}.
+     * Custom subclasses may use any string.
+     */
+    readonly code: string;
+    /**
+     * HTTP status code associated with this error.
+     * Derived automatically for built-in codes; pass it explicitly when
+     * 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>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Return type of `login`. */
+type AuthResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Return type of `assignRoles`. */
+type AssignRolesResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Return type of `refresh`. */
+type RefreshResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    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;
+}
+
+/** A function that determines whether the current request is permitted. */
+type PermitCheck = (request: Request) => boolean | Promise<boolean>;
+/**
+ * Options for {@link permit} when you need role-bypass alongside a resource check.
+ *
+ * @example
+ * // Admins can edit any post; others only their own
+ * auth.permit({
+ *   roles: ['admin'],
+ *   check: async (request) => {
+ *     const post = await db.findPost(request.params['id']);
+ *     return post?.authorId === request.user!.id;
+ *   },
+ * })
+ */
+interface PermitOptions<TRole extends string> {
+    /**
+     * Roles whose members are granted access without running `check`.
+     * Use for privileged roles like `'admin'` that should bypass ownership checks.
+     */
+    roles?: TRole[];
+    /**
+     * Permission check executed when the user has none of the bypass `roles`.
+     * Return `true` to allow, `false` to deny with `FORBIDDEN`.
+     * May be async — useful for database-backed ownership checks.
+     */
+    check: PermitCheck;
+}
+
+/**
+ * Options for {@link createErrorHandler}.
+ */
+interface ErrorHandlerOptions {
+    /**
+     * Called for errors that are **not** a `SentriError` instance (or subclass).
+     *
+     * Use this to log unexpected server errors before the generic 500 response
+     * is sent. The error is passed as-is and may be any unknown value.
+     *
+     * @example
+     * app.use(auth.errorHandler({
+     *   onUnhandled: (err) => logger.error('Unhandled error', { err }),
+     * }));
+     */
+    onUnhandled?: (error: unknown) => void;
+}
+/**
+ * Creates an Express error-handling middleware that formats every `SentriError`
+ * (including subclasses) into the standard sentri response envelope:
+ *
+ * ```json
+ * { "error": true, "statusCode": 401, "code": "UNAUTHORIZED", "message": "...", "data": null }
+ * ```
+ *
+ * Prefer using `auth.errorHandler()` instead of calling this directly:
+ *
+ * ```typescript
+ * app.use('/auth', auth.router());
+ * app.use('/api', apiRouter);
+ *
+ * // Must come after all route/middleware registrations
+ * app.use(auth.errorHandler());
+ * ```
+ *
+ * ---
+ *
+ * **Works with built-in sentri errors and your own subclasses**
+ *
+ * Because `instanceof SentriError` matches any subclass, you can define
+ * application-specific error types and have them automatically formatted
+ * by this handler:
+ *
+ * ```typescript
+ * import { SentriError } from 'sentri';
+ *
+ * // Extend SentriError for domain-specific failures
+ * export class NotFoundError extends SentriError {
+ *   constructor(resource: string) {
+ *     super('NOT_FOUND', `${resource} not found`, 404);
+ *   }
+ * }
+ *
+ * export class PaymentError extends SentriError {
+ *   constructor(message: string) {
+ *     super('PAYMENT_FAILED', message, 402);
+ *   }
+ * }
+ *
+ * // All of the above are caught and formatted by one handler
+ * app.use(auth.errorHandler({
+ *   onUnhandled: (err) => console.error('Unexpected error:', err),
+ * }));
+ * ```
+ *
+ * @param options - Optional configuration (see {@link ErrorHandlerOptions}).
+ * @returns An Express `ErrorRequestHandler` (4-argument middleware).
+ */
+declare function createErrorHandler(options?: ErrorHandlerOptions): ErrorRequestHandler;
+
+/**
+ * The bound auth client returned by {@link createAuth}.
+ *
+ * All methods are pre-configured with the options passed to `createAuth` —
+ * you never need to pass config around yourself.
+ *
+ * `TRole` is inferred from `validRoles` and narrows role strings to your
+ * application's exact union type everywhere (authorize, req.user, etc.).
+ */
+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);
+     * });
+     */
+    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);
+     */
+    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,
+     * );
+     */
+    permit(check: PermitCheck): RequestHandler;
+    permit(options: PermitOptions<TRole>): RequestHandler;
+    /** Hash a plain-text password using the configured `saltRounds`. */
+    hashPassword(plain: string): Promise<string>;
+    /** Compare a plain-text password against a stored bcrypt hash. */
+    verifyPassword(plain: string, hash: string): Promise<boolean>;
+    /** Sign an access token for the given user payload. */
+    signAccessToken(payload: AuthUser<TRole>): string;
+    /** Sign a refresh token bound to a session ID. */
+    signRefreshToken(sessionId: string): string;
+    /** Verify and decode an access token. Throws `SentriError` if invalid or expired. */
+    verifyAccessToken(token: string): AuthUser<TRole>;
+    /** Verify and decode a refresh token. Throws `SentriError` if invalid or expired. */
+    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();
+     * });
+     */
+    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());
+     */
+    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;
+}
+/**
+ * Create a fully configured auth client for your application.
+ *
+ * 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.
+ *
+ * The generic parameter `TRole` is inferred automatically from `validRoles`
+ * when you use `as const`:
+ *
+ * @example
+ * export const auth = createAuth({
+ *   secret: process.env.JWT_SECRET!,
+ *   validRoles: ['user', 'admin', 'moderator'] as const,
+ *   adapter: myAdapter,
+ * });
+ *
+ * // auth.authorize('admin') is type-safe — 'superuser' would be a compile error.
+ */
+declare function createAuth<TRole extends string = string>(config: AuthConfig<TRole>): AuthClient<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[];
+    /**
+     * 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
+     */
+    maxSize?: number;
+}
+/**
+ * Creates an Express middleware that makes mutating operations idempotent.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @example
+ * import { getCurrentAccessToken } from 'sentri';
+ *
+ * app.get('/debug/token', (req, res) => {
+ *   const token = getCurrentAccessToken(req, config);
+ *   res.json({ token });
+ * });
+ */
+declare function getCurrentAccessToken(request: Request, config: AuthConfig): string | undefined;
+
+/**
+ * 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.
+ */
+declare function register(input: RegisterInput, config: AuthConfig): 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 type { AuthConfig, CookieConfig, AuthUser, ApiResponse, AuthAdapter, UserRecord, SessionRecord, CreateUserData, RouterHandlers, RegisterInput, LoginInput, RegisterResult, AuthResult, RefreshResult, AssignRolesResult, } from './types/auth.js';
-export type { SentriErrorCode } from './errors/AuthError.js';
-export type { AuthClient } from './client.js';
-export type { ErrorHandlerOptions } from './middleware/errorHandler.js';
-export { SentriError, AUTH_ERROR_STATUS } from './errors/AuthError.js';
-export { createAuth } from './client.js';
-export { createErrorHandler } from './middleware/errorHandler.js';
-export { register } from './services/auth.js';
-export type { PermitCheck, PermitOptions } from './middleware/permit.js';
-//# sourceMappingURL=index.d.ts.map
+
+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 };