sentri 1.0.5 → 1.1.0

package/dist/libs/config.d.ts

@@ -1,4 +1,9 @@
 import type { AuthAdapter, AuthConfig } from '../types/auth.js';
+/**
+ * Fully-resolved configuration with all optional fields filled in by
+ * their defaults. Produced by {@link resolveConfig} and used internally
+ * wherever the library needs guaranteed values.
+ */
 export interface ResolvedConfig {
     secret: string;
     accessExpiresIn: string | number;
@@ -9,10 +14,49 @@ export interface ResolvedConfig {
     adapter: AuthAdapter;
 }
 /**
- * Validates config at startup so misconfiguration is caught immediately,
+ * Validate configuration at startup so misconfiguration is caught immediately,
  * not at the first login attempt.
+ *
+ * Throws {@link AuthError} with code `CONFIGURATION_ERROR` for any of:
+ * - `secret` missing or shorter than 32 characters
+ * - `saltRounds` outside the range 10–31
+ * - `validRoles` is empty or missing
+ * - `adapter` is missing
+ *
+ * @param config - The raw config passed to {@link createAuth}.
+ * @throws {AuthError} With code `CONFIGURATION_ERROR` on any invalid field.
  */
 export declare function validateConfig(config: AuthConfig): void;
+/**
+ * Merge a partial {@link AuthConfig} with library defaults and return a
+ * fully-resolved configuration object.
+ *
+ * Does **not** validate the config — call {@link validateConfig} first.
+ *
+ * Defaults applied:
+ * - `accessExpiresIn` → `'15m'`
+ * - `refreshExpiresIn` → `'7d'`
+ * - `algorithm` → `'HS256'`
+ * - `saltRounds` → `12`
+ *
+ * @param partial - The raw config passed to {@link createAuth}.
+ * @returns A {@link ResolvedConfig} with every field guaranteed to be present.
+ */
 export declare function resolveConfig(partial: AuthConfig): ResolvedConfig;
+/**
+ * Convert a duration string or a number of seconds into milliseconds.
+ *
+ * Supported unit suffixes: `s` (seconds), `m` (minutes), `h` (hours),
+ * `d` (days), `w` (weeks). Numeric inputs are treated as seconds.
+ *
+ * @example
+ * parseExpiry('15m')  // 900_000
+ * parseExpiry('7d')   // 604_800_000
+ * parseExpiry(60)     // 60_000
+ *
+ * @param expiresIn - A duration string (e.g. `'15m'`, `'7d'`) or a number of seconds.
+ * @returns The equivalent duration in milliseconds.
+ * @throws {Error} If the string format is unrecognised.
+ */
 export declare function parseExpiry(expiresIn: string | number): number;
 //# sourceMappingURL=config.d.ts.map

package/dist/libs/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/libs/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,WAAW,CAAC;CACtB;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CA0BvD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAUjE;AAGD,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAkB9D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/libs/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,WAAW,CAAC;CACtB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CA0BvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAUjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAkB9D"}

package/dist/libs/config.js

@@ -3,8 +3,17 @@ const MIN_SECRET_LENGTH = 32;
 const MIN_SALT_ROUNDS = 10;
 const MAX_SALT_ROUNDS = 31;
 /**
- * Validates config at startup so misconfiguration is caught immediately,
+ * Validate configuration at startup so misconfiguration is caught immediately,
  * not at the first login attempt.
+ *
+ * Throws {@link AuthError} with code `CONFIGURATION_ERROR` for any of:
+ * - `secret` missing or shorter than 32 characters
+ * - `saltRounds` outside the range 10–31
+ * - `validRoles` is empty or missing
+ * - `adapter` is missing
+ *
+ * @param config - The raw config passed to {@link createAuth}.
+ * @throws {AuthError} With code `CONFIGURATION_ERROR` on any invalid field.
  */
 export function validateConfig(config) {
     if (!config.secret || config.secret.trim().length === 0) {
@@ -24,6 +33,21 @@ export function validateConfig(config) {
         throw new AuthError('CONFIGURATION_ERROR', 'adapter is required');
     }
 }
+/**
+ * Merge a partial {@link AuthConfig} with library defaults and return a
+ * fully-resolved configuration object.
+ *
+ * Does **not** validate the config — call {@link validateConfig} first.
+ *
+ * Defaults applied:
+ * - `accessExpiresIn` → `'15m'`
+ * - `refreshExpiresIn` → `'7d'`
+ * - `algorithm` → `'HS256'`
+ * - `saltRounds` → `12`
+ *
+ * @param partial - The raw config passed to {@link createAuth}.
+ * @returns A {@link ResolvedConfig} with every field guaranteed to be present.
+ */
 export function resolveConfig(partial) {
     return {
         secret: partial.secret,
@@ -35,7 +59,21 @@ export function resolveConfig(partial) {
         adapter: partial.adapter,
     };
 }
-// Parses '15m', '7d', '1h', '30s', '2w' → milliseconds
+/**
+ * Convert a duration string or a number of seconds into milliseconds.
+ *
+ * Supported unit suffixes: `s` (seconds), `m` (minutes), `h` (hours),
+ * `d` (days), `w` (weeks). Numeric inputs are treated as seconds.
+ *
+ * @example
+ * parseExpiry('15m')  // 900_000
+ * parseExpiry('7d')   // 604_800_000
+ * parseExpiry(60)     // 60_000
+ *
+ * @param expiresIn - A duration string (e.g. `'15m'`, `'7d'`) or a number of seconds.
+ * @returns The equivalent duration in milliseconds.
+ * @throws {Error} If the string format is unrecognised.
+ */
 export function parseExpiry(expiresIn) {
     if (typeof expiresIn === 'number')
         return expiresIn * 1000;

package/dist/libs/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/libs/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAanD,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,qBAAqB,EACrB,2BAA2B,iBAAiB,0CAA0C,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,eAAe,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;QAClG,MAAM,IAAI,SAAS,CACjB,qBAAqB,EACrB,yCAAyC,eAAe,QAAQ,eAAe,EAAE,CAClF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,2CAA2C,CAAC,CAAC;IAC1F,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAmB;IAC/C,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,KAAK;QACjD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,IAAI;QAClD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO;QACvC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE;QACpC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,SAA0B;IACpD,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,GAAG,IAAI,CAAC;IAC3D,MAAM,WAAW,GAA2B;QAC1C,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,SAAS;QACZ,CAAC,EAAE,UAAU;QACb,CAAC,EAAE,WAAW;KACf,CAAC;IACF,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,gCAAgC,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,gCAAgC,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;AACvC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/libs/config.ts"],"names":[],"mappings":"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"}

package/dist/libs/hash.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Hash a plain-text password using bcrypt.
+ *
+ * @param plain - The raw password string supplied by the user.
+ * @param saltRounds - bcrypt cost factor; higher values increase security at the cost of speed.
+ * @returns The bcrypt hash string to persist in the database.
+ */
 export declare function hashPassword(plain: string, saltRounds?: number): Promise<string>;
+/**
+ * Compare a plain-text password against a stored bcrypt hash.
+ *
+ * @param plain - The raw password string to verify.
+ * @param hash - The stored bcrypt hash from the database.
+ * @returns `true` if the password matches the hash, `false` otherwise.
+ */
 export declare function verifyPassword(plain: string, hash: string): Promise<boolean>;
 //# sourceMappingURL=hash.d.ts.map

package/dist/libs/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/libs/hash.ts"],"names":[],"mappings":"AAEA,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAElF;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAElF"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/libs/hash.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAElF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAElF"}

package/dist/libs/hash.js

@@ -1,7 +1,21 @@
 import bcrypt from 'bcrypt';
+/**
+ * Hash a plain-text password using bcrypt.
+ *
+ * @param plain - The raw password string supplied by the user.
+ * @param saltRounds - bcrypt cost factor; higher values increase security at the cost of speed.
+ * @returns The bcrypt hash string to persist in the database.
+ */
 export async function hashPassword(plain, saltRounds = 12) {
     return bcrypt.hash(plain, saltRounds);
 }
+/**
+ * Compare a plain-text password against a stored bcrypt hash.
+ *
+ * @param plain - The raw password string to verify.
+ * @param hash - The stored bcrypt hash from the database.
+ * @returns `true` if the password matches the hash, `false` otherwise.
+ */
 export async function verifyPassword(plain, hash) {
     return bcrypt.compare(plain, hash);
 }

package/dist/libs/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/libs/hash.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,UAAU,GAAG,EAAE;IAC/D,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAa,EAAE,IAAY;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/libs/hash.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,UAAU,GAAG,EAAE;IAC/D,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAa,EAAE,IAAY;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/libs/token.d.ts

@@ -1,7 +1,45 @@
-import type { AuthConfig, AuthUser } from '../types/auth.js';
-export declare function signAccessToken(payload: AuthUser, config: AuthConfig): string;
+import type { AccessTokenPayload, AuthConfig, AuthUser } from '../types/auth.js';
+/**
+ * Sign a short-lived access token containing the user's identity, roles, and
+ * the session ID that `protect()` uses to verify the session is still active.
+ *
+ * Uses the access-specific secret derived from config and the configured
+ * `accessExpiresIn` duration and HMAC algorithm.
+ *
+ * @param payload - The {@link AccessTokenPayload} to embed (id, identifier, roles, sessionId).
+ * @param config - Auth configuration used to derive the secret and options.
+ * @returns Compact JWT string.
+ */
+export declare function signAccessToken(payload: AuthUser | AccessTokenPayload, config: AuthConfig): string;
+/**
+ * Sign a long-lived refresh token bound to a specific session ID.
+ *
+ * Uses the refresh-specific secret derived from config and the configured
+ * `refreshExpiresIn` duration. The session ID is embedded as the sole claim
+ * so the token can be used to look up and rotate the session.
+ *
+ * @param sessionId - The database session ID to bind to this token.
+ * @param config - Auth configuration used to derive the secret and options.
+ * @returns Compact JWT string.
+ */
 export declare function signRefreshToken(sessionId: string, config: AuthConfig): string;
+/**
+ * Verify an access token and return its decoded {@link AuthUser} payload.
+ *
+ * @param token - Compact JWT access token string.
+ * @param config - Auth configuration used to derive the secret and algorithm.
+ * @returns Decoded `AuthUser` payload (id, identifier, roles).
+ * @throws {AuthError} With `TOKEN_EXPIRED` if expired, `TOKEN_INVALID` otherwise.
+ */
 export declare function verifyAccessToken(token: string, config: AuthConfig): AuthUser;
+/**
+ * Verify a refresh token and return the embedded session ID.
+ *
+ * @param token - Compact JWT refresh token string.
+ * @param config - Auth configuration used to derive the secret and algorithm.
+ * @returns Object with `sessionId` matching the one passed to {@link signRefreshToken}.
+ * @throws {AuthError} With `TOKEN_EXPIRED` if expired, `TOKEN_INVALID` otherwise.
+ */
 export declare function verifyRefreshToken(token: string, config: AuthConfig): {
     sessionId: string;
 };

package/dist/libs/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/libs/token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA2C7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAI7E;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,CAI7E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAI3F"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/libs/token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAqEjF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,kBAAkB,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAIlG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAI9E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,CAI7E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAI3F"}

package/dist/libs/token.js

@@ -1,12 +1,28 @@
 import jwt, {} from 'jsonwebtoken';
 import { AuthError } from '../errors/AuthError.js';
 import { resolveConfig } from './config.js';
+/**
+ * Derive separate HMAC secrets for access and refresh tokens from a single
+ * root secret by appending a domain suffix.
+ *
+ * Using distinct secrets prevents a refresh token from being accepted as an
+ * access token and vice versa.
+ */
 function deriveSecrets(secret) {
     return {
         access: `${secret}:access`,
         refresh: `${secret}:refresh`,
     };
 }
+/**
+ * Sign a JWT payload with the given secret and options.
+ *
+ * @param payload - Claims to embed in the token.
+ * @param secret - HMAC signing key.
+ * @param expiresIn - Expiry duration string (e.g. `'15m'`) or seconds.
+ * @param algorithm - HMAC algorithm variant.
+ * @returns Compact JWT string.
+ */
 function sign(payload, secret, expiresIn, algorithm) {
     const options = {
         expiresIn: expiresIn,
@@ -14,6 +30,16 @@ function sign(payload, secret, expiresIn, algorithm) {
     };
     return jwt.sign(payload, secret, options);
 }
+/**
+ * Verify and decode a JWT, mapping jsonwebtoken errors to typed {@link AuthError}s.
+ *
+ * @param token - Compact JWT string to verify.
+ * @param secret - HMAC key used to sign the token.
+ * @param algorithm - Expected signing algorithm.
+ * @returns Decoded payload cast to `T`.
+ * @throws {AuthError} With `TOKEN_EXPIRED` if the token's `exp` claim is in the past.
+ * @throws {AuthError} With `TOKEN_INVALID` for any other verification failure.
+ */
 function verify(token, secret, algorithm) {
     try {
         const decoded = jwt.verify(token, secret, { algorithms: [algorithm] });
@@ -31,21 +57,59 @@ function verify(token, secret, algorithm) {
         throw new AuthError('TOKEN_INVALID', 'Token is invalid or malformed');
     }
 }
+/**
+ * Sign a short-lived access token containing the user's identity, roles, and
+ * the session ID that `protect()` uses to verify the session is still active.
+ *
+ * Uses the access-specific secret derived from config and the configured
+ * `accessExpiresIn` duration and HMAC algorithm.
+ *
+ * @param payload - The {@link AccessTokenPayload} to embed (id, identifier, roles, sessionId).
+ * @param config - Auth configuration used to derive the secret and options.
+ * @returns Compact JWT string.
+ */
 export function signAccessToken(payload, config) {
     const resolved = resolveConfig(config);
     const { access } = deriveSecrets(resolved.secret);
     return sign(payload, access, resolved.accessExpiresIn, resolved.algorithm);
 }
+/**
+ * Sign a long-lived refresh token bound to a specific session ID.
+ *
+ * Uses the refresh-specific secret derived from config and the configured
+ * `refreshExpiresIn` duration. The session ID is embedded as the sole claim
+ * so the token can be used to look up and rotate the session.
+ *
+ * @param sessionId - The database session ID to bind to this token.
+ * @param config - Auth configuration used to derive the secret and options.
+ * @returns Compact JWT string.
+ */
 export function signRefreshToken(sessionId, config) {
     const resolved = resolveConfig(config);
     const { refresh } = deriveSecrets(resolved.secret);
     return sign({ sessionId }, refresh, resolved.refreshExpiresIn, resolved.algorithm);
 }
+/**
+ * Verify an access token and return its decoded {@link AuthUser} payload.
+ *
+ * @param token - Compact JWT access token string.
+ * @param config - Auth configuration used to derive the secret and algorithm.
+ * @returns Decoded `AuthUser` payload (id, identifier, roles).
+ * @throws {AuthError} With `TOKEN_EXPIRED` if expired, `TOKEN_INVALID` otherwise.
+ */
 export function verifyAccessToken(token, config) {
     const resolved = resolveConfig(config);
     const { access } = deriveSecrets(resolved.secret);
     return verify(token, access, resolved.algorithm);
 }
+/**
+ * Verify a refresh token and return the embedded session ID.
+ *
+ * @param token - Compact JWT refresh token string.
+ * @param config - Auth configuration used to derive the secret and algorithm.
+ * @returns Object with `sessionId` matching the one passed to {@link signRefreshToken}.
+ * @throws {AuthError} With `TOKEN_EXPIRED` if expired, `TOKEN_INVALID` otherwise.
+ */
 export function verifyRefreshToken(token, config) {
     const resolved = resolveConfig(config);
     const { refresh } = deriveSecrets(resolved.secret);

package/dist/libs/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/libs/token.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/libs/token.ts"],"names":[],"mappings":"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"}

package/dist/middleware/authorize.d.ts

@@ -1,3 +1,18 @@
 import type { RequestHandler } from 'express';
+/**
+ * Express middleware factory for role-based access control (RBAC).
+ *
+ * Passes if the authenticated user (set by `protect()`) has **at least one**
+ * of the specified `allowedRoles`. Calls `next(AuthError)` with code `FORBIDDEN`
+ * if no roles match, or `UNAUTHORIZED` if `req.user` is absent.
+ *
+ * Must be used **after** `protect()`.
+ *
+ * @param allowedRoles - One or more role strings. The user needs at least one of them.
+ * @returns An Express `RequestHandler` that enforces the role check.
+ *
+ * @example
+ * router.delete('/posts/:id', protect(config), authorize('admin', 'moderator'), handler);
+ */
 export declare function authorize<TRole extends string>(...allowedRoles: TRole[]): RequestHandler;
 //# sourceMappingURL=authorize.d.ts.map

package/dist/middleware/authorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../src/middleware/authorize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,KAAK,EAAE,GAAG,cAAc,CAcxF"}
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../src/middleware/authorize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,KAAK,EAAE,GAAG,cAAc,CAcxF"}

package/dist/middleware/authorize.js

@@ -1,4 +1,19 @@
 import { AuthError } from '../errors/AuthError.js';
+/**
+ * Express middleware factory for role-based access control (RBAC).
+ *
+ * Passes if the authenticated user (set by `protect()`) has **at least one**
+ * of the specified `allowedRoles`. Calls `next(AuthError)` with code `FORBIDDEN`
+ * if no roles match, or `UNAUTHORIZED` if `req.user` is absent.
+ *
+ * Must be used **after** `protect()`.
+ *
+ * @param allowedRoles - One or more role strings. The user needs at least one of them.
+ * @returns An Express `RequestHandler` that enforces the role check.
+ *
+ * @example
+ * router.delete('/posts/:id', protect(config), authorize('admin', 'moderator'), handler);
+ */
 export function authorize(...allowedRoles) {
     return (request, _response, next) => {
         if (!request.user) {

package/dist/middleware/authorize.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../../src/middleware/authorize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,UAAU,SAAS,CAAuB,GAAG,YAAqB;IACtE,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;QAClC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,SAAS,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACxD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CACT,IAAI,SAAS,CAAC,WAAW,EAAE,0BAA0B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../../src/middleware/authorize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAuB,GAAG,YAAqB;IACtE,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;QAClC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,SAAS,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACxD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CACT,IAAI,SAAS,CAAC,WAAW,EAAE,0BAA0B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/protect.d.ts

@@ -1,4 +1,31 @@
 import type { RequestHandler } from 'express';
 import type { AuthConfig } from '../types/auth.js';
+/**
+ * Express middleware factory that enforces JWT authentication and session validity.
+ *
+ * Reads the `Authorization: Bearer <token>` header, verifies the access token,
+ * and attaches the decoded payload to `req.user`. Calls `next(AuthError)` on
+ * any failure so your error handler can convert it to an HTTP response.
+ *
+ * Since sentri 1.1.0 access tokens embed a `sessionId` claim. When this claim
+ * is present, `protect()` performs a lightweight database lookup
+ * (`adapter.session.findById`) to confirm the session is still active. This
+ * means a user who has logged out (or been logged out from all devices) cannot
+ * use an access token that was issued before the logout — even if the token has
+ * not yet expired.
+ *
+ * Tokens issued before 1.1.0 (without the `sessionId` claim) are still accepted
+ * but bypass the session check.
+ *
+ * Must be used **before** `authorize()` or `permit()`.
+ *
+ * @param config - Auth configuration (secret, algorithm, adapter).
+ * @returns An Express `RequestHandler` that populates `req.user` on success.
+ *
+ * @example
+ * router.get('/profile', protect(config), (request, response) => {
+ *   response.json(request.user);
+ * });
+ */
 export declare function protect(config: AuthConfig): RequestHandler;
 //# sourceMappingURL=protect.d.ts.map

package/dist/middleware/protect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../../src/middleware/protect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAc1D"}
+{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../../src/middleware/protect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAsB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAwB1D"}

package/dist/middleware/protect.js

@@ -1,14 +1,49 @@
 import { AuthError } from '../errors/AuthError.js';
 import { verifyAccessToken } from '../libs/token.js';
+/**
+ * Express middleware factory that enforces JWT authentication and session validity.
+ *
+ * Reads the `Authorization: Bearer <token>` header, verifies the access token,
+ * and attaches the decoded payload to `req.user`. Calls `next(AuthError)` on
+ * any failure so your error handler can convert it to an HTTP response.
+ *
+ * Since sentri 1.1.0 access tokens embed a `sessionId` claim. When this claim
+ * is present, `protect()` performs a lightweight database lookup
+ * (`adapter.session.findById`) to confirm the session is still active. This
+ * means a user who has logged out (or been logged out from all devices) cannot
+ * use an access token that was issued before the logout — even if the token has
+ * not yet expired.
+ *
+ * Tokens issued before 1.1.0 (without the `sessionId` claim) are still accepted
+ * but bypass the session check.
+ *
+ * Must be used **before** `authorize()` or `permit()`.
+ *
+ * @param config - Auth configuration (secret, algorithm, adapter).
+ * @returns An Express `RequestHandler` that populates `req.user` on success.
+ *
+ * @example
+ * router.get('/profile', protect(config), (request, response) => {
+ *   response.json(request.user);
+ * });
+ */
 export function protect(config) {
-    return (request, _response, next) => {
+    return async (request, _response, next) => {
         const authHeader = request.headers['authorization'];
         if (!authHeader?.startsWith('Bearer ')) {
             return next(new AuthError('UNAUTHORIZED', 'Missing or malformed Authorization header'));
         }
         const token = authHeader.slice(7);
         try {
-            request.user = verifyAccessToken(token, config);
+            const payload = verifyAccessToken(token, config);
+            request.user = { id: payload.id, identifier: payload.identifier, roles: payload.roles };
+            // Session-bound validation: reject the request if the session was revoked (logout).
+            if (payload.sessionId) {
+                const session = await config.adapter.session.findById(payload.sessionId);
+                if (!session) {
+                    return next(new AuthError('UNAUTHORIZED', 'Session has been revoked'));
+                }
+            }
             next();
         }
         catch (error) {

package/dist/middleware/protect.js.map

@@ -1 +1 @@
-{"version":3,"file":"protect.js","sourceRoot":"","sources":["../../src/middleware/protect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,MAAM,UAAU,OAAO,CAAC,MAAkB;IACxC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;QAClC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACpD,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,2CAA2C,CAAC,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAChD,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"protect.js","sourceRoot":"","sources":["../../src/middleware/protect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,OAAO,CAAC,MAAkB;IACxC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;QACxC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACpD,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,2CAA2C,CAAC,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAuB,CAAC;YACvE,OAAO,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAExF,oFAAoF;YACpF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACzE,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;YAED,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/router.d.ts

@@ -6,12 +6,13 @@ import type { AuthConfig } from '../types/auth.js';
  * Mount it once and all routes are ready:
  *
  * ```
- * POST /signup       — register a new user
- * POST /login        — authenticate and get tokens
- * POST /refresh      — rotate refresh token
- * POST /logout       — invalidate current session
- * POST /logout-all   — invalidate all sessions for the authenticated user
- * GET  /me           — return the currently authenticated user
+ * POST /register            — register a new user (protected by X-Api-Key when config.apiKey is set)
+ * POST /login               — authenticate and get tokens
+ * POST /refresh             — rotate refresh token
+ * POST /logout              — invalidate current session; access tokens issued before logout become invalid
+ * POST /logout-all          — invalidate all sessions for the authenticated user
+ * GET  /me                  — return the currently authenticated user
+ * POST /users/:userId/roles — assign roles (admin only)
  * ```
  *
  * Requires `express.json()` to be applied before the router.
@@ -19,6 +20,12 @@ import type { AuthConfig } from '../types/auth.js';
  * When `cookie` is set in config, the refresh token is stored in an httpOnly
  * cookie automatically — no `cookie-parser` needed.
  *
+ * When `apiKey` is set in config, `POST /register` requires the caller to send
+ * an `X-Api-Key: <key>` header matching the configured value.
+ *
+ * When `router` is set in config, individual service functions can be replaced
+ * while the router still handles validation and response formatting.
+ *
  * @example
  * app.use(express.json());
  * app.use('/auth', auth.router());

package/dist/middleware/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/middleware/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAkD,MAAM,SAAS,CAAC;AAEjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAsKxF"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/middleware/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAkD,MAAM,SAAS,CAAC;AAEjF,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,kBAAkB,CAAC;AA+E5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAwLxF"}