sentri 5.0.1 → 5.0.2

package/dist/index-CVb3-EnK.d.ts

@@ -0,0 +1,386 @@
+import { Dialect } from 'kysely';
+
+/**
+ * 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
+ * - `IDENTIFIER_NOT_FOUND` — a referenced identifier ID does not exist or does not belong to the user
+ * - `IDENTIFIER_ALREADY_EXISTS` — the identifier value is already taken by another user
+ * - `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
+ * - `RATE_LIMIT_EXCEEDED` — too many requests were made to an endpoint (e.g. login/register limit)
+ * - `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' | 'IDENTIFIER_NOT_FOUND' | 'IDENTIFIER_ALREADY_EXISTS' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'FORBIDDEN' | 'UNAUTHORIZED' | 'INVALID_ROLE' | 'VALIDATION_ERROR' | 'CONFIGURATION_ERROR' | 'TOKEN_REUSE' | 'RATE_LIMIT_EXCEEDED';
+/**
+ * Default HTTP status codes for built-in error codes.
+ * Custom codes not in this map default to 500.
+ *
+ * @internal
+ */
+declare const SENTRI_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';
+ *
+ * export class PaymentError extends SentriError {
+ *   constructor(message: string) {
+ *     super('PAYMENT_FAILED', message, 402);
+ *   }
+ * }
+ *
+ * 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;
+    constructor(code: SentriErrorCode | (string & {}), message: string, statusCode?: number);
+}
+
+/**
+ * Minimal structured logger interface accepted by Sentri.
+ *
+ * Compatible out-of-the-box with **pino**, **winston**, and **console** — all
+ * three expose `info`, `warn`, and `error` methods that accept an object argument.
+ *
+ * Pass an instance via `logger` in `ServerAuthConfig` or `ClientAuthConfig`.
+ * When omitted, Sentri produces no log output (no-op default).
+ *
+ * Each call receives a plain `Record<string, unknown>` containing structured
+ * fields — never a pre-formatted string — so your logger controls serialisation,
+ * output destination, and timestamp format.
+ *
+ * @example
+ * // pino
+ * import pino from 'pino';
+ * const auth = createAuth({ ..., logger: pino() });
+ *
+ * @example
+ * // winston
+ * import winston from 'winston';
+ * const auth = createAuth({ ..., logger: winston.createLogger({ ... }) });
+ *
+ * @example
+ * // console (zero setup, useful for development)
+ * const auth = createAuth({ ..., logger: console });
+ */
+interface SentriLogger {
+    info(data: Record<string, unknown>): void;
+    warn(data: Record<string, unknown>): void;
+    error(data: Record<string, unknown>): void;
+}
+
+/**
+ * Standardized API response format returned by Sentri endpoints.
+ * @template T - The type of the data payload.
+ */
+interface ApiResponse<T = null> {
+    error: boolean;
+    statusCode: number;
+    message: string;
+    data: T | null;
+}
+/** A single identifier entry belonging to a user. */
+interface IdentifierRecord {
+    id: string;
+    type: string;
+    value: string;
+}
+/** The authenticated user shape embedded in JWT payloads and middleware context. */
+interface AuthUser<TRole extends string = string> {
+    id: string;
+    roles: TRole[];
+    /** All identifiers for this user. Only present in full user responses, not in JWT. */
+    identifiers?: IdentifierRecord[];
+}
+/** Input for a single identifier entry. */
+interface IdentifierInput {
+    /** Arbitrary label such as 'email', 'username', or 'phone'. */
+    type: string;
+    /** The globally unique identifier value. */
+    value: string;
+}
+/** Result returned after a successful or failed registration attempt. */
+type RegisterResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned after a successful or failed login attempt. */
+type AuthResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned after assigning new roles to a user. */
+type AssignRolesResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned when fetching a specific user's details. */
+type GetUserResult<TRole extends string = string> = {
+    success: true;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned after bulk identifier operations (create/update/delete). */
+type BulkIdentifiersResult = {
+    success: true;
+    identifiers: IdentifierRecord[];
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned after changing a user's password. */
+type ChangePasswordResult = {
+    success: true;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Result returned after a successful or failed session refresh. */
+type RefreshResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: SentriError;
+};
+/** Input payload required for user registration. */
+interface RegisterInput<TRole extends string = string> {
+    /** One or more identifiers for the new user. All values must be globally unique. */
+    identifiers: IdentifierInput[];
+    password: string;
+    roles?: TRole[];
+}
+/** Input payload required for user login. */
+interface LoginInput {
+    /** Any of the user's identifier values — Sentri searches all types. */
+    identifier: string;
+    password: string;
+}
+/**
+ * Configuration options for the HTTP-only Refresh Token cookie.
+ */
+interface CookieConfig {
+    name?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    path?: string;
+}
+/**
+ * Configuration options for the Access Token cookie (if used).
+ */
+interface AccessCookieConfig {
+    name?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    path?: string;
+}
+/**
+ * Lifecycle hooks for injecting custom logic during authentication flows.
+ * Helpful for sending welcome emails, tracking analytics, or logging.
+ */
+interface AuthHooks {
+    onRegister?: (user: AuthUser) => void | Promise<void>;
+    onLoginSuccess?: (user: AuthUser, meta: {
+        ip: string;
+        userAgent: string;
+    }) => void | Promise<void>;
+    onLoginFailed?: (identifier: string, error: SentriError, meta: {
+        ip: string;
+    }) => void | Promise<void>;
+    onPasswordChanged?: (userId: string) => void | Promise<void>;
+    onLogout?: (userId: string) => void | Promise<void>;
+}
+/**
+ * Configuration for rate limiting login and registration endpoints.
+ * The default time window is 15 minutes.
+ */
+interface RateLimitOptions {
+    /** Maximum login attempts per IP within the 15-minute window. Default is 5. */
+    maxLoginAttempts?: number;
+    /** Maximum registration attempts per IP within the 15-minute window. Default is 5. */
+    maxRegisterAttempts?: number;
+}
+/**
+ * Optional overrides for the core router logic.
+ * Provide custom handler functions to completely replace default endpoints behaviors.
+ */
+interface RouterHandlers {
+    register?: (input: RegisterInput, meta: {
+        ip: string;
+        userAgent: string;
+    }) => Promise<RegisterResult>;
+    login?: (input: LoginInput, meta: {
+        ip: string;
+        userAgent: string;
+    }) => Promise<AuthResult>;
+    refresh?: (refreshToken: string, meta: {
+        ip: string;
+        userAgent: string;
+    }) => Promise<RefreshResult>;
+    logout?: (refreshToken: string | undefined) => Promise<void>;
+    logoutAll?: (userId: string) => Promise<void>;
+    getUser?: (userId: string) => Promise<GetUserResult>;
+    assignRoles?: (userId: string, roles: string[]) => Promise<AssignRolesResult>;
+    bulkCreateIdentifiers?: (userId: string, identifiers: IdentifierInput[]) => Promise<BulkIdentifiersResult>;
+    bulkUpdateIdentifiers?: (userId: string, updates: Array<{
+        id: string;
+        type: string;
+        value: string;
+    }>) => Promise<BulkIdentifiersResult>;
+    bulkDeleteIdentifiers?: (userId: string, ids: string[]) => Promise<BulkIdentifiersResult>;
+    changePassword?: (userId: string, currentPassword: string, newPassword: string) => Promise<ChangePasswordResult>;
+    getSessions?: (userId: string) => Promise<any>;
+    revokeSession?: (userId: string, sessionId: string) => Promise<void>;
+}
+interface ServerAuthConfig<TRole extends string = string> {
+    /** Indicates this configuration is for a Sentri Server instance. */
+    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';
+    /** List of valid roles accepted by the system during registration or role assignment. */
+    validRoles: readonly TRole[];
+    /** @default ['email', 'username'] */
+    validIdentifiers?: readonly string[];
+    /** @default '15m' */
+    accessExpiresIn?: string | number;
+    /** @default '7d' */
+    refreshExpiresIn?: string | number;
+    /** @default 12 */
+    saltRounds?: number;
+    /**
+     * Optional API Key required for protected endpoints (like bulk identifier operations).
+     */
+    apiKey?: string;
+    cookie?: CookieConfig;
+    accessCookie?: AccessCookieConfig;
+    hooks?: AuthHooks;
+    router?: RouterHandlers;
+    isTokenRevoked?: (sessionId: string) => boolean | Promise<boolean>;
+    /**
+     * Rate limiting configuration for login and registration endpoints.
+     * Set to \`false\` to completely disable rate limiting.
+     * @default { maxLoginAttempts: 5, maxRegisterAttempts: 5 }
+     */
+    rateLimit?: RateLimitOptions | 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;
+    /**
+     * Structured logger instance. Compatible with pino, winston, or console.
+     * When omitted, Sentri produces no log output.
+     */
+    logger?: SentriLogger;
+    /**
+     * Service name embedded in every log entry.
+     * @default 'sentri'
+     */
+    loggerService?: 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[];
+    /**
+     * Structured logger instance. Compatible with pino, winston, or console.
+     * When omitted, Sentri produces no log output.
+     */
+    logger?: SentriLogger;
+    /**
+     * Service name embedded in every log entry.
+     * @default 'sentri'
+     */
+    loggerService?: string;
+}
+type AuthConfig<TRole extends string = string> = ServerAuthConfig<TRole> | ClientAuthConfig<TRole>;
+
+export { type AuthUser as A, type BulkIdentifiersResult as B, type CookieConfig as C, type GetUserResult as G, type IdentifierInput as I, type LoginInput as L, type RouterHandlers as R, type SentriLogger as S, type AuthConfig as a, type ServerAuthConfig as b, type AccessCookieConfig as c, type AuthHooks as d, type RateLimitOptions as e, type RegisterInput as f, type RegisterResult as g, type AuthResult as h, type RefreshResult as i, type ChangePasswordResult as j, type AssignRolesResult as k, SENTRI_ERROR_STATUS as l, SentriError as m, type ApiResponse as n, type ClientAuthConfig as o, type IdentifierRecord as p, type SentriErrorCode as q };

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var t=Object.defineProperty;var N=(I,E)=>t(I,"name",{value:E,configurable:true});var O=Object.assign(Object.create(null),{UNAUTHORIZED:401,TOKEN_EXPIRED:401,TOKEN_INVALID:401,INVALID_CREDENTIALS:401,FORBIDDEN:403,USER_NOT_FOUND:404,IDENTIFIER_NOT_FOUND:404,USER_ALREADY_EXISTS:409,IDENTIFIER_ALREADY_EXISTS:409,INVALID_ROLE:400,VALIDATION_ERROR:400,CONFIGURATION_ERROR:500,TOKEN_REUSE:401}),R=class extends Error{static{N(this,"SentriError");}code;statusCode;constructor(E,T,_){super(T),this.name="SentriError",this.code=E,this.statusCode=_??O[E]??500;}};exports.SENTRI_ERROR_STATUS=O;exports.SentriError=R;
+'use strict';var t=Object.defineProperty;var T=(I,E)=>t(I,"name",{value:E,configurable:true});var _=Object.assign(Object.create(null),{UNAUTHORIZED:401,TOKEN_EXPIRED:401,TOKEN_INVALID:401,INVALID_CREDENTIALS:401,FORBIDDEN:403,USER_NOT_FOUND:404,IDENTIFIER_NOT_FOUND:404,USER_ALREADY_EXISTS:409,IDENTIFIER_ALREADY_EXISTS:409,INVALID_ROLE:400,VALIDATION_ERROR:400,CONFIGURATION_ERROR:500,TOKEN_REUSE:401,RATE_LIMIT_EXCEEDED:429}),R=class extends Error{static{T(this,"SentriError");}code;statusCode;constructor(E,N,O){super(N),this.name="SentriError",this.code=E,this.statusCode=O??_[E]??500;}};exports.SENTRI_ERROR_STATUS=_;exports.SentriError=R;

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-export { AccessCookieConfig, ApiResponse, AssignRolesResult, AuthConfig, AuthHooks, AuthResult, AuthUser, BulkIdentifiersResult, ChangePasswordResult, ClientAuthConfig, CookieConfig, GetUserResult, IdentifierInput, IdentifierRecord, LoginInput, RefreshResult, RegisterInput, RegisterResult, RouterHandlers, SENTRI_ERROR_STATUS, SentriError, SentriErrorCode, SentriLogger, ServerAuthConfig } from './core/index.cjs';
+export { c as AccessCookieConfig, n as ApiResponse, k as AssignRolesResult, a as AuthConfig, d as AuthHooks, h as AuthResult, A as AuthUser, B as BulkIdentifiersResult, j as ChangePasswordResult, o as ClientAuthConfig, C as CookieConfig, G as GetUserResult, I as IdentifierInput, p as IdentifierRecord, L as LoginInput, i as RefreshResult, f as RegisterInput, g as RegisterResult, R as RouterHandlers, l as SENTRI_ERROR_STATUS, m as SentriError, q as SentriErrorCode, S as SentriLogger, b as ServerAuthConfig } from './index-CVb3-EnK.cjs';
 import 'kysely';

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { AccessCookieConfig, ApiResponse, AssignRolesResult, AuthConfig, AuthHooks, AuthResult, AuthUser, BulkIdentifiersResult, ChangePasswordResult, ClientAuthConfig, CookieConfig, GetUserResult, IdentifierInput, IdentifierRecord, LoginInput, RefreshResult, RegisterInput, RegisterResult, RouterHandlers, SENTRI_ERROR_STATUS, SentriError, SentriErrorCode, SentriLogger, ServerAuthConfig } from './core/index.js';
+export { c as AccessCookieConfig, n as ApiResponse, k as AssignRolesResult, a as AuthConfig, d as AuthHooks, h as AuthResult, A as AuthUser, B as BulkIdentifiersResult, j as ChangePasswordResult, o as ClientAuthConfig, C as CookieConfig, G as GetUserResult, I as IdentifierInput, p as IdentifierRecord, L as LoginInput, i as RefreshResult, f as RegisterInput, g as RegisterResult, R as RouterHandlers, l as SENTRI_ERROR_STATUS, m as SentriError, q as SentriErrorCode, S as SentriLogger, b as ServerAuthConfig } from './index-CVb3-EnK.js';
 import 'kysely';

package/dist/index.js

@@ -1 +1 @@
-var t=Object.defineProperty;var N=(I,E)=>t(I,"name",{value:E,configurable:true});var O=Object.assign(Object.create(null),{UNAUTHORIZED:401,TOKEN_EXPIRED:401,TOKEN_INVALID:401,INVALID_CREDENTIALS:401,FORBIDDEN:403,USER_NOT_FOUND:404,IDENTIFIER_NOT_FOUND:404,USER_ALREADY_EXISTS:409,IDENTIFIER_ALREADY_EXISTS:409,INVALID_ROLE:400,VALIDATION_ERROR:400,CONFIGURATION_ERROR:500,TOKEN_REUSE:401}),R=class extends Error{static{N(this,"SentriError");}code;statusCode;constructor(E,T,_){super(T),this.name="SentriError",this.code=E,this.statusCode=_??O[E]??500;}};export{O as SENTRI_ERROR_STATUS,R as SentriError};
+var t=Object.defineProperty;var T=(I,E)=>t(I,"name",{value:E,configurable:true});var _=Object.assign(Object.create(null),{UNAUTHORIZED:401,TOKEN_EXPIRED:401,TOKEN_INVALID:401,INVALID_CREDENTIALS:401,FORBIDDEN:403,USER_NOT_FOUND:404,IDENTIFIER_NOT_FOUND:404,USER_ALREADY_EXISTS:409,IDENTIFIER_ALREADY_EXISTS:409,INVALID_ROLE:400,VALIDATION_ERROR:400,CONFIGURATION_ERROR:500,TOKEN_REUSE:401,RATE_LIMIT_EXCEEDED:429}),R=class extends Error{static{T(this,"SentriError");}code;statusCode;constructor(E,N,O){super(N),this.name="SentriError",this.code=E,this.statusCode=O??_[E]??500;}};export{_ as SENTRI_ERROR_STATUS,R as SentriError};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentri",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Auth/authorization library for Express, Fastify, Hono, and Elysia — PostgreSQL + JWT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",