@maximemrf/adonisjs-jwt 1.0.0-rc.3 → 1.0.0-rc.5

package/README.md

@@ -7,7 +7,6 @@
   <a href="https://www.npmjs.com/package/@maximemrf/adonisjs-jwt"><img src="https://img.shields.io/npm/v/@maximemrf/adonisjs-jwt.svg?style=flat-square" alt="Version"></a>
   <a href="https://www.npmjs.com/package/@maximemrf/adonisjs-jwt"><img src="https://img.shields.io/npm/last-update/@maximemrf/adonisjs-jwt.svg?style=flat-square" alt="NPM Last Update"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/@maximemrf/adonisjs-jwt.svg?style=flat-square" alt="License"></a>
-  <a href="https://adonisjs.com/"><img src="https://img.shields.io/badge/AdonisJS-v6-5A45FF.svg?style=flat-square" alt="AdonisV6"></a>
   <a href="https://adonisjs.com/"><img src="https://img.shields.io/badge/AdonisJS-v7-5A45FF.svg?style=flat-square" alt="AdonisV7"></a>
 </p>
 

package/build/index.d.ts

@@ -1,4 +1,4 @@
 export { configure } from './configure.js';
 export { jwtGuard } from './src/define_config.js';
 export { JwtGuard } from './src/guard.js';
-export { DEFAULT_TOKEN_EXPIRES_IN } from './src/types.js';
+export { DEFAULT_TOKEN_EXPIRES_IN } from './src/constants.js';

package/build/index.js

@@ -9,4 +9,4 @@
 export { configure } from './configure.js';
 export { jwtGuard } from './src/define_config.js';
 export { JwtGuard } from './src/guard.js';
-export { DEFAULT_TOKEN_EXPIRES_IN } from './src/types.js';
+export { DEFAULT_TOKEN_EXPIRES_IN } from './src/constants.js';

package/build/src/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lifetime of access tokens when `tokenExpiresIn` is not configured
+ */
+export declare const DEFAULT_TOKEN_EXPIRES_IN = "1h";
+/**
+ * Lifetime of refresh tokens when `refreshTokenExpiresIn` is not configured
+ */
+export declare const DEFAULT_REFRESH_TOKEN_EXPIRES_IN = "7d";
+export declare const ALLOWED_SYMMETRIC_ALGORITHMS: readonly ["HS256", "HS384", "HS512"];
+export declare const ALLOWED_ASYMMETRIC_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"];
+export declare const ALLOWED_JWKS_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512"];

package/build/src/constants.js

@@ -0,0 +1,23 @@
+/**
+ * Lifetime of access tokens when `tokenExpiresIn` is not configured
+ */
+export const DEFAULT_TOKEN_EXPIRES_IN = '1h';
+/**
+ * Lifetime of refresh tokens when `refreshTokenExpiresIn` is not configured
+ */
+export const DEFAULT_REFRESH_TOKEN_EXPIRES_IN = '7d';
+export const ALLOWED_SYMMETRIC_ALGORITHMS = ['HS256', 'HS384', 'HS512'];
+export const ALLOWED_ASYMMETRIC_ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'ES256',
+    'ES384',
+    'ES512',
+];
+export const ALLOWED_JWKS_ALGORITHMS = [
+    ...ALLOWED_ASYMMETRIC_ALGORITHMS,
+    'PS256',
+    'PS384',
+    'PS512',
+];

package/build/src/define_config.d.ts

@@ -1,32 +1,6 @@
-import type { symbols } from '@adonisjs/auth';
 import type { GuardConfigProvider } from '@adonisjs/auth/types';
 import type { HttpContext } from '@adonisjs/core/http';
-import type { JwtAsymmetricAlgorithm, JwtGuardUser, JwtUserProviderContract, JwtCookieOptions, BaseJwtContent, JwtJwksAlgorithm, JwtGetUserId, JwtVerifyPayload } from './types.js';
+import type { JwtUserProviderContract, JwtGuardConfig } from './types.js';
 import { JwtGuard } from './guard.js';
-import type { StringValue } from 'ms';
 import type { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens';
-import type { Options } from 'jwks-rsa';
-export declare function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>, RefreshTokenUserProvider extends AccessTokensUserProviderContract<unknown> | undefined = undefined>(config: {
-    provider: UserProvider;
-    refreshTokenUserProvider?: RefreshTokenUserProvider;
-    tokenName?: string;
-    refreshTokenName?: string;
-    tokenExpiresIn?: number | StringValue;
-    refreshTokenExpiresIn?: number | StringValue;
-    useCookies?: boolean;
-    useCookiesForRefreshToken?: boolean;
-    refreshTokenAbilities?: string[];
-    secret?: string;
-    privateKey?: string;
-    publicKey?: string;
-    algorithm?: JwtAsymmetricAlgorithm;
-    content?: (user: JwtGuardUser<UserProvider[typeof symbols.PROVIDER_REAL_USER]>) => Record<string, any> & BaseJwtContent;
-    jwks?: Options;
-    cookie?: JwtCookieOptions;
-    issuer?: string;
-    audience?: string | string[];
-    algorithms?: JwtJwksAlgorithm[];
-    clockTolerance?: number;
-    getUserId?: JwtGetUserId;
-    verifyPayload?: JwtVerifyPayload;
-}): GuardConfigProvider<(ctx: HttpContext) => JwtGuard<UserProvider, [RefreshTokenUserProvider] extends [undefined] ? false : true>>;
+export declare function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>, RefreshTokenUserProvider extends AccessTokensUserProviderContract<unknown> | undefined = undefined>(config: JwtGuardConfig<UserProvider, RefreshTokenUserProvider>): GuardConfigProvider<(ctx: HttpContext) => JwtGuard<UserProvider, [RefreshTokenUserProvider] extends [undefined] ? false : true>>;

package/build/src/define_config.js

@@ -1,56 +1,85 @@
 import { JwtGuard } from './guard.js';
-import { validateGuardOptions } from './validation.js';
+import { releaseSecrets, validateLifetimes, validateSigningMethod } from './validation.js';
 import { resolveDriver } from './driver_resolver.js';
 import { hkdfSync } from 'node:crypto';
 export function jwtGuard(config) {
+    const asymmetricKeys = {
+        privateKey: config.privateKey,
+        publicKey: config.publicKey,
+        algorithm: config.algorithm,
+    };
+    const usesAsymmetric = Object.values(asymmetricKeys).some((value) => value !== undefined);
+    /**
+     * Only fall back on the app key when no other signing method is configured
+     */
+    const usesAppKey = config.secret === undefined && !usesAsymmetric && !config.jwks;
+    const options = releaseSecrets({
+        ...(usesAsymmetric ? asymmetricKeys : { secret: config.secret }),
+        refreshTokenUserProvider: config.refreshTokenUserProvider,
+        tokenName: config.tokenName,
+        refreshTokenName: config.refreshTokenName,
+        tokenExpiresIn: config.tokenExpiresIn,
+        refreshTokenExpiresIn: config.refreshTokenExpiresIn,
+        useCookies: config.useCookies,
+        useCookiesForRefreshToken: config.useCookiesForRefreshToken,
+        refreshTokenAbilities: config.refreshTokenAbilities,
+        content: config.content,
+        jwks: config.jwks,
+        cookie: config.cookie,
+        issuer: config.issuer,
+        audience: config.audience,
+        algorithms: config.algorithms,
+        clockTolerance: config.clockTolerance,
+        getUserId: config.getUserId,
+        verifyPayload: config.verifyPayload,
+        /**
+         * `content` and `getUserId` come from the same config, so they keep
+         * the pairing checked by `JwtContentOptions`
+         */
+    });
+    /**
+     * Validate the configuration when config/auth.ts is loaded, so a bad
+     * configuration stops the app from booting. The resolver only runs on
+     * the first request, when the app would already be serving traffic.
+     */
+    validateLifetimes(options, PREFIX);
+    let driver;
+    if (usesAppKey) {
+        /**
+         * The derived key depends on the guard name, only known in the resolver,
+         * but the app key itself can already be checked when the env has it
+         */
+        if (process.env.APP_KEY !== undefined)
+            assertAppKey(process.env.APP_KEY);
+    }
+    else {
+        validateSigningMethod(options, PREFIX);
+        driver = resolveDriver(options, PREFIX);
+    }
     return {
         async resolver(name, app) {
-            const asymmetricKeys = {
-                privateKey: config.privateKey,
-                publicKey: config.publicKey,
-                algorithm: config.algorithm,
-            };
-            const usesAsymmetric = Object.values(asymmetricKeys).some((value) => value !== undefined);
-            /**
-             * Only fall back on the app key when no other signing method is configured
-             */
-            const resolvedSecret = config.secret ??
-                (usesAsymmetric || config.jwks ? undefined : deriveSecretFromAppKey(readAppKey(app), name));
-            const options = {
-                ...(usesAsymmetric ? asymmetricKeys : { secret: resolvedSecret }),
-                refreshTokenUserProvider: config.refreshTokenUserProvider,
-                tokenName: config.tokenName,
-                refreshTokenName: config.refreshTokenName,
-                tokenExpiresIn: config.tokenExpiresIn,
-                refreshTokenExpiresIn: config.refreshTokenExpiresIn,
-                useCookies: config.useCookies,
-                useCookiesForRefreshToken: config.useCookiesForRefreshToken,
-                refreshTokenAbilities: config.refreshTokenAbilities,
-                content: config.content,
-                jwks: config.jwks,
-                cookie: config.cookie,
-                issuer: config.issuer,
-                audience: config.audience,
-                algorithms: config.algorithms,
-                clockTolerance: config.clockTolerance,
-                getUserId: config.getUserId,
-                verifyPayload: config.verifyPayload,
-            };
-            validateGuardOptions(options, 'JWT guard');
-            const driver = resolveDriver(options, 'JWT guard');
-            return (ctx) => new JwtGuard(ctx, config.provider, { ...options, driver });
+            if (usesAppKey) {
+                const secret = deriveSecretFromAppKey(readAppKey(app), name);
+                driver = resolveDriver({ ...options, secret }, PREFIX);
+            }
+            const resolvedDriver = driver;
+            return (ctx) => new JwtGuard(ctx, config.provider, { ...options, driver: resolvedDriver });
         },
     };
 }
+const PREFIX = 'JWT guard';
+function assertAppKey(rawAppKey) {
+    if (!rawAppKey || rawAppKey.length < 32) {
+        throw new Error('JWT guard requires the application key (APP_KEY) to be at least 32 characters when no `secret` is configured');
+    }
+}
 /**
  * Derive a dedicated signing key from the app key, so the guard never signs
  * with the raw app key used elsewhere by the application, and two JWT guards
  * never accept each other's tokens.
  */
 function deriveSecretFromAppKey(rawAppKey, guardName) {
-    if (!rawAppKey || rawAppKey.length < 32) {
-        throw new Error('JWT guard requires the application key (APP_KEY) to be at least 32 characters when no `secret` is configured');
-    }
+    assertAppKey(rawAppKey);
     return Buffer.from(hkdfSync('sha256', rawAppKey, '', `@maximemrf/adonisjs-jwt:${guardName}`, 32)).toString('hex');
 }
 /**

package/build/src/driver_resolver.js

@@ -15,7 +15,7 @@ export function resolveDriver(options, contextName = 'JWT guard') {
                 audience: options.audience,
                 clockTolerance: options.clockTolerance,
                 algorithms: options.algorithms,
-                verifiesPayload: options.verifyPayload !== undefined,
+                verifiesPayload: typeof options.verifyPayload === 'function',
             });
         }
         catch (error) {

package/build/src/drivers/asymmetric.js

@@ -35,6 +35,13 @@ export class AsymmetricDriver {
         if (publicKey.asymmetricKeyType !== expectedKeyType) {
             throw new Error(`publicKey type "${publicKey.asymmetricKeyType}" does not match algorithm "${algorithm}"`);
         }
+        /**
+         * With keys from two different pairs, every token the guard issues
+         * would be rejected by the same guard: all users would be locked out
+         */
+        if (!createPublicKey(privateKey).equals(publicKey)) {
+            throw new Error('publicKey does not belong to the same key pair as privateKey');
+        }
     }
     sign(payload, options) {
         const signOptions = {

package/build/src/drivers/jwks.d.ts

@@ -1,7 +1,7 @@
 import type { Options } from 'jwks-rsa';
 import type { StringValue } from 'ms';
 import type { JwtDriver } from './types.js';
-import { type JwtJwksAlgorithm } from '../types.js';
+import type { JwtJwksAlgorithm } from '../types.js';
 /**
  * Safe jwks-rsa defaults: tokens with an unknown `kid` trigger a JWKS
  * fetch, so fetches must be cached and rate limited to avoid hammering

package/build/src/drivers/jwks.js

@@ -1,7 +1,8 @@
 import jwt from 'jsonwebtoken';
 import { errors } from '@adonisjs/auth';
+import { RuntimeException } from '@adonisjs/core/exceptions';
 import { JwksManager } from '../jwks.js';
-import { ALLOWED_JWKS_ALGORITHMS } from '../types.js';
+import { ALLOWED_JWKS_ALGORITHMS } from '../constants.js';
 /**
  * Safe jwks-rsa defaults: tokens with an unknown `kid` trigger a JWKS
  * fetch, so fetches must be cached and rate limited to avoid hammering
@@ -40,9 +41,7 @@ export class JwksDriver {
         this.#algorithms = algorithms;
     }
     sign(_payload, _options) {
-        throw new errors.E_UNAUTHORIZED_ACCESS("You can't use the auth.generate method with jwks", {
-            guardDriverName: 'jwt',
-        });
+        throw new RuntimeException('JWT guard cannot issue tokens in JWKS mode: tokens are issued by the identity provider');
     }
     async verify(token) {
         const decoded = jwt.decode(token, { complete: true });

package/build/src/drivers/symmetric.js

@@ -1,5 +1,5 @@
 import jwt from 'jsonwebtoken';
-import { ALLOWED_SYMMETRIC_ALGORITHMS } from '../types.js';
+import { ALLOWED_SYMMETRIC_ALGORITHMS } from '../constants.js';
 export class SymmetricDriver {
     canSign = true;
     #secret;
@@ -8,10 +8,10 @@ export class SymmetricDriver {
     #clockTolerance;
     constructor(options) {
         if (!options.secret) {
-            throw new Error('Symmetric JWT driver requires a secret key');
+            throw new Error('JWT guard requires a `secret`');
         }
         if (options.secret.length < 32) {
-            throw new Error('Symmetric JWT driver requires a secret of at least 32 characters to ensure sufficient entropy');
+            throw new Error('JWT guard `secret` must be at least 32 characters to ensure sufficient entropy');
         }
         this.#secret = options.secret;
         this.#issuer = options.issuer;

package/build/src/drivers/types.d.ts

@@ -6,3 +6,14 @@ export interface JwtDriver {
     }): string;
     verify(token: string): Promise<Record<string, any> | string> | Record<string, any> | string;
 }
+/**
+ * Options of the `JwtGuard` constructor that are not part of the public
+ * API: `jwtGuard()` resolves the driver once and passes it to every guard.
+ * Custom drivers are not supported and the `JwtDriver` interface may change.
+ */
+export type JwtGuardInternalOptions = {
+    /**
+     * @internal
+     */
+    driver?: JwtDriver;
+};

package/build/src/errors.d.ts

@@ -0,0 +1,23 @@
+import { errors } from '@adonisjs/auth';
+import type { HttpContext } from '@adonisjs/core/http';
+type UnauthorizedAccess = InstanceType<typeof errors.E_UNAUTHORIZED_ACCESS>;
+type Renderer = (message: string, error: UnauthorizedAccess, ctx: HttpContext) => any;
+/**
+ * Renders the 401 raised by the JWT guard, or by the `auth` middleware when
+ * the JWT guard was the last one tried.
+ *
+ * - JSON and JSON:API requests get the same body as the `access_tokens` guard.
+ * - HTML requests (pages, Inertia visits) are redirected to the login route
+ *   when the `auth` middleware passes one (`loginRoute`), like the `session`
+ *   guard does. Without a login route, they get a plain text 401.
+ */
+export declare const renderJwtUnauthorizedAccess: Renderer;
+/**
+ * @adonisjs/auth only ships renderers for its own guards, and the `auth`
+ * middleware re-throws its own `E_UNAUTHORIZED_ACCESS` with
+ * `guardDriverName: 'jwt'`, so a subclass would never reach the exception
+ * handler. Register the `jwt` renderer on every instance instead, unless
+ * the application already registered its own.
+ */
+export declare function installJwtUnauthorizedRenderer(): void;
+export {};

package/build/src/errors.js

@@ -0,0 +1,56 @@
+import { errors } from '@adonisjs/auth';
+/**
+ * Renders the 401 raised by the JWT guard, or by the `auth` middleware when
+ * the JWT guard was the last one tried.
+ *
+ * - JSON and JSON:API requests get the same body as the `access_tokens` guard.
+ * - HTML requests (pages, Inertia visits) are redirected to the login route
+ *   when the `auth` middleware passes one (`loginRoute`), like the `session`
+ *   guard does. Without a login route, they get a plain text 401.
+ */
+export const renderJwtUnauthorizedAccess = (message, error, ctx) => {
+    switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
+        case 'html':
+        case null:
+            if (error.redirectTo) {
+                /**
+                 * `withIntendedUrl` is added by @adonisjs/session, which is optional
+                 */
+                const redirect = ctx.response.redirect();
+                if (typeof redirect.withIntendedUrl === 'function')
+                    redirect.withIntendedUrl();
+                redirect.withQs().toPath(error.redirectTo);
+                return;
+            }
+            ctx.response.status(error.status).send(message);
+            return;
+        case 'json':
+            ctx.response.status(error.status).send({ errors: [{ message }] });
+            return;
+        case 'application/vnd.api+json':
+            ctx.response.status(error.status).send({ errors: [{ code: error.code, title: message }] });
+            return;
+    }
+};
+const INSTALLED = Symbol.for('@maximemrf/adonisjs-jwt/unauthorized-renderer');
+/**
+ * @adonisjs/auth only ships renderers for its own guards, and the `auth`
+ * middleware re-throws its own `E_UNAUTHORIZED_ACCESS` with
+ * `guardDriverName: 'jwt'`, so a subclass would never reach the exception
+ * handler. Register the `jwt` renderer on every instance instead, unless
+ * the application already registered its own.
+ */
+export function installJwtUnauthorizedRenderer() {
+    const prototype = errors.E_UNAUTHORIZED_ACCESS.prototype;
+    if (prototype[INSTALLED])
+        return;
+    const handle = prototype.handle;
+    prototype.handle = function (error, ctx) {
+        const renderers = this.renderers;
+        if (this.guardDriverName === 'jwt' && !renderers.jwt) {
+            renderers.jwt = renderJwtUnauthorizedAccess;
+        }
+        return handle.call(this, error, ctx);
+    };
+    prototype[INSTALLED] = true;
+}

package/build/src/guard.d.ts

@@ -1,10 +1,11 @@
 import { symbols } from '@adonisjs/auth';
 import type { AuthClientResponse, GuardContract } from '@adonisjs/auth/types';
 import type { HttpContext } from '@adonisjs/core/http';
-import { type JwtUserProviderContract, type JwtGuardOptions, type JwtGenerateResult } from './types.js';
+import type { JwtUserProviderContract, JwtGuardOptions, JwtGenerateResult } from './types.js';
+import type { JwtGuardInternalOptions } from './drivers/types.js';
 export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>, WithRefreshToken extends boolean = boolean> implements GuardContract<UserProvider[typeof symbols.PROVIDER_REAL_USER]> {
     #private;
-    constructor(ctx: HttpContext, userProvider: UserProvider, option: JwtGuardOptions<UserProvider[typeof symbols.PROVIDER_REAL_USER]>);
+    constructor(ctx: HttpContext, userProvider: UserProvider, option: JwtGuardOptions<UserProvider[typeof symbols.PROVIDER_REAL_USER]> & JwtGuardInternalOptions);
     /**
      * A list of events and their types emitted by
      * the guard.
@@ -44,7 +45,14 @@ export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unkno
     }>;
     generateWithRefreshToken(refreshToken?: string): Promise<JwtGenerateResult<true>>;
     /**
-     * Revoke the refresh token
+     * Revoke the refresh token passed as argument, or else the one issued
+     * during this request, or else the one sent by the client (cookie, body
+     * or Authorization header).
+     *
+     * The cookies are always cleared. When no valid refresh token is found,
+     * nothing is revoked and `E_UNAUTHORIZED_ACCESS` is raised, so a client
+     * that sends the wrong token (e.g. its access token) does not believe it
+     * has logged out while its refresh token stays valid.
      */
     revoke(refreshToken?: string): Promise<void>;
     /**

package/build/src/guard.js

@@ -1,8 +1,11 @@
 import { errors } from '@adonisjs/auth';
-import { DEFAULT_TOKEN_EXPIRES_IN, } from './types.js';
+import { RuntimeException } from '@adonisjs/core/exceptions';
+import { DEFAULT_REFRESH_TOKEN_EXPIRES_IN, DEFAULT_TOKEN_EXPIRES_IN } from './constants.js';
 import { Secret } from '@adonisjs/core/helpers';
-import { validateGuardOptions } from './validation.js';
+import { releaseSecrets, toSeconds, validateGuardOptions, } from './validation.js';
 import { resolveDriver } from './driver_resolver.js';
+import { installJwtUnauthorizedRenderer } from './errors.js';
+installJwtUnauthorizedRenderer();
 export class JwtGuard {
     #ctx;
     #userProvider;
@@ -12,10 +15,19 @@ export class JwtGuard {
     #refreshTokenName = 'refreshToken';
     #driver;
     #cookieOptions;
+    /**
+     * Refresh token issued during the current request, by `generate()` or a
+     * refresh. A logout in the same request revokes it: the request still
+     * carries the previous one, which the refresh has already deleted.
+     */
+    #issuedRefreshToken;
     constructor(ctx, userProvider, option) {
         this.#ctx = ctx;
         this.#userProvider = userProvider;
-        this.#options = option;
+        /**
+         * Copy the options: the defaults below must not leak into the caller's object
+         */
+        this.#options = releaseSecrets({ ...option });
         this.#refreshTokenUserProvider = this.#options.refreshTokenUserProvider;
         if (!this.#options.content)
             this.#options.content = (user) => ({ userId: user.getId() });
@@ -25,13 +37,21 @@ export class JwtGuard {
          * Never issue access tokens without an expiration
          */
         this.#options.tokenExpiresIn = this.#options.tokenExpiresIn ?? DEFAULT_TOKEN_EXPIRES_IN;
+        /**
+         * Give refresh tokens a lifetime, so the database row, the cookie and
+         * the response always agree
+         */
+        if (this.#refreshTokenUserProvider) {
+            this.#options.refreshTokenExpiresIn =
+                this.#options.refreshTokenExpiresIn ?? DEFAULT_REFRESH_TOKEN_EXPIRES_IN;
+        }
         this.#cookieOptions = {
             httpOnly: true,
             secure: true,
             ...this.#options.cookie,
         };
-        validateGuardOptions(this.#options, 'JwtGuard');
-        this.#driver = resolveDriver(this.#options, 'JwtGuard');
+        validateGuardOptions(this.#options, 'JWT guard');
+        this.#driver = resolveDriver(this.#options, 'JWT guard');
     }
     #signAccessToken(payload) {
         return this.#driver.sign(payload, { expiresIn: this.#options.tokenExpiresIn });
@@ -83,9 +103,7 @@ export class JwtGuard {
      */
     async generate(user) {
         if (!this.#driver.canSign) {
-            throw new errors.E_UNAUTHORIZED_ACCESS("You can't use the auth.generate method with jwks", {
-                guardDriverName: this.driverName,
-            });
+            throw new RuntimeException('JWT guard cannot issue tokens in JWKS mode: tokens are issued by the identity provider');
         }
         const providerUser = await this.#userProvider.createUserForGuard(user);
         const signPayload = this.#options.content(providerUser);
@@ -98,6 +116,7 @@ export class JwtGuard {
                 }
                 : undefined);
             refreshToken = generatedRefreshToken.value.release();
+            this.#issuedRefreshToken = refreshToken;
         }
         if (this.#options.useCookies) {
             this.#ctx.response.cookie(`${this.#tokenName}`, token, {
@@ -114,9 +133,11 @@ export class JwtGuard {
         return {
             type: 'bearer',
             token: token,
-            expiresIn: this.#options.tokenExpiresIn,
+            expiresIn: toSeconds(this.#options.tokenExpiresIn),
             refreshToken: refreshToken,
-            refreshTokenExpiresIn: this.#options.refreshTokenExpiresIn,
+            refreshTokenExpiresIn: refreshToken
+                ? toSeconds(this.#options.refreshTokenExpiresIn)
+                : undefined,
         };
     }
     /**
@@ -154,7 +175,12 @@ export class JwtGuard {
                 guardDriverName: this.driverName,
             });
         }
-        if (!payload || typeof payload !== 'object') {
+        /**
+         * jsonwebtoken only checks `exp` when the claim is present: a token
+         * without it (issued by another service sharing the secret, or by an
+         * identity provider) would otherwise be valid forever
+         */
+        if (!payload || typeof payload !== 'object' || typeof payload.exp !== 'number') {
             throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
                 guardDriverName: this.driverName,
             });
@@ -176,9 +202,17 @@ export class JwtGuard {
                 });
             }
         }
-        const getUserId = this.#options.getUserId ?? ((claims) => claims.userId);
-        const userId = getUserId(payload);
-        if (userId === undefined || userId === null) {
+        /**
+         * A `getUserId` that throws, or a claim of an unexpected type (an object
+         * or an array from an identity provider), rejects the token instead of
+         * failing the request or reaching the database
+         */
+        let userId;
+        try {
+            userId = (this.#options.getUserId ?? ((claims) => claims.userId))(payload);
+        }
+        catch { }
+        if (!isUserId(userId)) {
             throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
                 guardDriverName: this.driverName,
             });
@@ -200,14 +234,10 @@ export class JwtGuard {
     async generateWithRefreshToken(refreshToken) {
         this.authenticationAttempted = true;
         if (!this.#driver.canSign) {
-            throw new errors.E_UNAUTHORIZED_ACCESS('JWKS is not supported for refresh token', {
-                guardDriverName: this.driverName,
-            });
+            throw new RuntimeException('JWT guard cannot issue tokens in JWKS mode: tokens are issued by the identity provider');
         }
         if (!this.#refreshTokenUserProvider) {
-            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
-                guardDriverName: this.driverName,
-            });
+            throw new RuntimeException(REFRESH_TOKENS_NOT_CONFIGURED);
         }
         if (!refreshToken) {
             refreshToken = await this.#findRefreshToken();
@@ -293,33 +323,35 @@ export class JwtGuard {
         });
     }
     /**
-     * Revoke the refresh token
+     * Revoke the refresh token passed as argument, or else the one issued
+     * during this request, or else the one sent by the client (cookie, body
+     * or Authorization header).
+     *
+     * The cookies are always cleared. When no valid refresh token is found,
+     * nothing is revoked and `E_UNAUTHORIZED_ACCESS` is raised, so a client
+     * that sends the wrong token (e.g. its access token) does not believe it
+     * has logged out while its refresh token stays valid.
      */
     async revoke(refreshToken) {
         if (!this.#refreshTokenUserProvider) {
-            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
-                guardDriverName: this.driverName,
-            });
+            throw new RuntimeException(REFRESH_TOKENS_NOT_CONFIGURED);
         }
         this.#clearCookies();
-        if (!refreshToken) {
-            try {
-                refreshToken = await this.#findRefreshToken();
-            }
-            catch {
-                return;
-            }
-        }
+        refreshToken = refreshToken ?? this.#issuedRefreshToken ?? (await this.#findRefreshToken());
         /**
          * Only delete a refresh token whose secret is valid. The tokens
          * provider deletes by id alone, so a forged token with a guessed
          * id would otherwise revoke another user's refresh token.
          */
         const secret = new Secret(refreshToken);
-        if (!(await this.#refreshTokenUserProvider.verifyToken(secret))) {
-            return;
+        if (!(await this.#refreshTokenUserProvider.verifyToken(secret)) ||
+            !(await this.#refreshTokenUserProvider.invalidateToken(secret))) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
         }
-        await this.#refreshTokenUserProvider.invalidateToken(secret);
+        if (refreshToken === this.#issuedRefreshToken)
+            this.#issuedRefreshToken = undefined;
     }
     /**
      * Remove the access and refresh token cookies set by the guard
@@ -340,8 +372,14 @@ export class JwtGuard {
             await this.authenticate();
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            /**
+             * Like the official guards, only an authentication failure means
+             * "not logged in": a database outage must not look like a guest
+             */
+            if (error instanceof errors.E_UNAUTHORIZED_ACCESS)
+                return false;
+            throw error;
         }
     }
     /**
@@ -368,3 +406,9 @@ export class JwtGuard {
         };
     }
 }
+const REFRESH_TOKENS_NOT_CONFIGURED = 'JWT guard refresh tokens are not configured: set `refreshTokenUserProvider` in the guard config';
+function isUserId(value) {
+    return ((typeof value === 'string' && value !== '') ||
+        (typeof value === 'number' && Number.isFinite(value)) ||
+        typeof value === 'bigint');
+}

package/build/src/types.d.ts

@@ -1,9 +1,10 @@
-import { type symbols } from '@adonisjs/auth';
+import type { symbols } from '@adonisjs/auth';
 import type { StringValue } from 'ms';
 import type { AccessTokensUserProviderContract } from '@adonisjs/auth/types/access_tokens';
 import type { Options } from 'jwks-rsa';
 import type { CookieOptions } from '@adonisjs/core/types/http';
-import type { JwtDriver } from './drivers/types.js';
+import type { ALLOWED_ASYMMETRIC_ALGORITHMS, ALLOWED_JWKS_ALGORITHMS, ALLOWED_SYMMETRIC_ALGORITHMS } from './constants.js';
+import type { Secret } from '@adonisjs/core/helpers';
 export type JwtCookieOptions = Omit<Partial<CookieOptions>, 'maxAge' | 'expires'>;
 /**
  * The bridge between the User provider and the
@@ -28,7 +29,7 @@ export interface JwtUserProviderContract<RealUser> {
      * A property the guard implementation can use to infer
      * the data type of the actual user (aka RealUser)
      */
-    [symbols.PROVIDER_REAL_USER]?: RealUser;
+    [symbols.PROVIDER_REAL_USER]: RealUser;
     /**
      * Create a user object that acts as an adapter between
      * the guard and real user value.
@@ -42,47 +43,43 @@ export interface JwtUserProviderContract<RealUser> {
 export type BaseJwtContent = {
     userId: string | number | BigInt;
 };
-/**
- * Lifetime of access tokens when `tokenExpiresIn` is not configured
- */
-export declare const DEFAULT_TOKEN_EXPIRES_IN = "1h";
-export declare const ALLOWED_SYMMETRIC_ALGORITHMS: readonly ["HS256", "HS384", "HS512"];
 export type JwtSymmetricAlgorithm = (typeof ALLOWED_SYMMETRIC_ALGORITHMS)[number];
-export declare const ALLOWED_ASYMMETRIC_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"];
 /**
  * Algorithms supported for asymmetric (RSA / ECDSA) JWT signing and verification.
  * Use with `privateKey` + `publicKey` so access tokens can be verified elsewhere with only the public key.
  */
 export type JwtAsymmetricAlgorithm = (typeof ALLOWED_ASYMMETRIC_ALGORITHMS)[number];
-export declare const ALLOWED_JWKS_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512"];
 export type JwtJwksAlgorithm = (typeof ALLOWED_JWKS_ALGORITHMS)[number];
 /**
- * `refreshToken` is a string when the guard has a `refreshTokenUserProvider`
+ * Tokens returned by `generate()` and `generateWithRefreshToken()`.
+ * Lifetimes are in seconds, like `expires_in` in OAuth 2.0 (RFC 6749),
+ * whatever the format used in the config (`'1h'` gives `3600`).
+ * `refreshToken` and `refreshTokenExpiresIn` are set when the guard has
+ * a `refreshTokenUserProvider`.
  */
 export type JwtGenerateResult<WithRefreshToken extends boolean = boolean> = {
-    type: string;
+    type: 'bearer';
     token: string;
-    expiresIn?: number | StringValue;
-    refreshTokenExpiresIn?: number | StringValue;
+    expiresIn: number;
 } & ([WithRefreshToken] extends [true] ? {
     refreshToken: string;
+    refreshTokenExpiresIn: number;
 } : {
     refreshToken?: string;
+    refreshTokenExpiresIn?: number;
 });
-export type JwtGuardOptions<RealUser extends any = unknown> = {
-    /**
-     * Driver resolved by `jwtGuard()`. Not part of the public API: custom
-     * drivers are not supported and the `JwtDriver` interface may change.
-     */
-    driver?: JwtDriver;
+/**
+ * Options shared by `jwtGuard()` and the `JwtGuard` constructor
+ */
+type JwtSharedOptions = {
     /**
      * Symmetric signing secret (HMAC). Used when asymmetric keys are not set.
      */
-    secret?: string;
+    secret?: string | Secret<string>;
     /**
      * PEM-encoded private key for signing access tokens (asymmetric mode).
      */
-    privateKey?: string;
+    privateKey?: string | Secret<string>;
     /**
      * PEM-encoded public key for verifying access tokens (asymmetric mode).
      */
@@ -92,7 +89,6 @@ export type JwtGuardOptions<RealUser extends any = unknown> = {
      */
     algorithm?: JwtAsymmetricAlgorithm;
     jwks?: Options;
-    refreshTokenUserProvider?: AccessTokensUserProviderContract<RealUser>;
     tokenName?: string;
     /**
      * Name of the refresh token cookie and request body field.
@@ -112,7 +108,6 @@ export type JwtGuardOptions<RealUser extends any = unknown> = {
      */
     refreshTokenAbilities?: string[];
     cookie?: JwtCookieOptions;
-    content?: (user: JwtGuardUser<RealUser>) => Record<string, any> & BaseJwtContent;
     /**
      * Expected JWT issuer (iss). Validated during token verification.
      * Required in JWKS mode.
@@ -132,11 +127,6 @@ export type JwtGuardOptions<RealUser extends any = unknown> = {
      * Number of seconds of clock skew tolerated when checking `exp` / `nbf`.
      */
     clockTolerance?: number;
-    /**
-     * Extract the user id from a verified token payload.
-     * Defaults to `payload.userId`. Use e.g. `(payload) => payload.sub` for external providers.
-     */
-    getUserId?: JwtGetUserId;
     /**
      * Extra check on a verified token payload, run before looking up the user.
      * Only an explicit `true` accepts the token: any other value, or an
@@ -145,5 +135,39 @@ export type JwtGuardOptions<RealUser extends any = unknown> = {
      */
     verifyPayload?: JwtVerifyPayload;
 };
+/**
+ * `content` builds the payload of the access tokens. Without `getUserId`,
+ * the guard reads the user id from the `userId` claim, so `content` must
+ * set it. With `getUserId`, `content` is free to use another claim.
+ */
+export type JwtContentOptions<RealUser> = {
+    /**
+     * Extract the user id from a verified token payload.
+     * Defaults to `payload.userId`. Use e.g. `(payload) => payload.sub` for external providers.
+     */
+    getUserId?: undefined;
+    content?: (user: JwtGuardUser<RealUser>) => Record<string, any> & BaseJwtContent;
+} | {
+    /**
+     * Extract the user id from a verified token payload.
+     * Defaults to `payload.userId`. Use e.g. `(payload) => payload.sub` for external providers.
+     */
+    getUserId: JwtGetUserId;
+    content?: (user: JwtGuardUser<RealUser>) => Record<string, any>;
+};
+/**
+ * Options of the `JwtGuard` constructor
+ */
+export type JwtGuardOptions<RealUser = unknown> = JwtSharedOptions & {
+    refreshTokenUserProvider?: AccessTokensUserProviderContract<RealUser>;
+} & JwtContentOptions<RealUser>;
+/**
+ * Config accepted by `jwtGuard()` in `config/auth.ts`
+ */
+export type JwtGuardConfig<UserProvider extends JwtUserProviderContract<unknown>, RefreshTokenUserProvider extends AccessTokensUserProviderContract<unknown> | undefined = undefined> = JwtSharedOptions & {
+    provider: UserProvider;
+    refreshTokenUserProvider?: RefreshTokenUserProvider;
+} & JwtContentOptions<UserProvider[typeof symbols.PROVIDER_REAL_USER]>;
 export type JwtVerifyPayload = (payload: Record<string, any>) => boolean | Promise<boolean>;
 export type JwtGetUserId = (payload: Record<string, any>) => string | number | BigInt | undefined | null;
+export {};

package/build/src/types.js

@@ -1,19 +1 @@
-/**
- * Lifetime of access tokens when `tokenExpiresIn` is not configured
- */
-export const DEFAULT_TOKEN_EXPIRES_IN = '1h';
-export const ALLOWED_SYMMETRIC_ALGORITHMS = ['HS256', 'HS384', 'HS512'];
-export const ALLOWED_ASYMMETRIC_ALGORITHMS = [
-    'RS256',
-    'RS384',
-    'RS512',
-    'ES256',
-    'ES384',
-    'ES512',
-];
-export const ALLOWED_JWKS_ALGORITHMS = [
-    ...ALLOWED_ASYMMETRIC_ALGORITHMS,
-    'PS256',
-    'PS384',
-    'PS512',
-];
+export {};

package/build/src/validation.d.ts

@@ -1,2 +1,30 @@
 import type { JwtGuardOptions } from './types.js';
-export declare function validateGuardOptions(options: JwtGuardOptions, prefix?: string): void;
+import type { JwtGuardInternalOptions } from './drivers/types.js';
+export declare function validateGuardOptions(options: ReleasedSecrets<JwtGuardOptions & JwtGuardInternalOptions>, prefix?: string): void;
+/**
+ * Token lifetimes and clock tolerance. A lifetime that is not a positive
+ * duration would issue tokens that are already expired (`'-1h'`), or fail
+ * on every login (`'abc'`).
+ */
+export declare function validateLifetimes(options: Pick<JwtGuardOptions, 'tokenExpiresIn' | 'refreshTokenExpiresIn' | 'clockTolerance'>, prefix: string): void;
+/**
+ * Exactly one signing method: a secret, an asymmetric key pair, or a JWKS endpoint
+ */
+export declare function validateSigningMethod(options: ReleasedSecrets<JwtGuardOptions>, prefix: string): void;
+/**
+ * Accept `Secret` values (`Env.schema.secret()` in AdonisJS v7) for the
+ * signing keys, and work with their string value
+ */
+export type ReleasedSecrets<Options> = Options extends any ? Omit<Options, 'secret' | 'privateKey'> & {
+    secret?: string;
+    privateKey?: string;
+} : never;
+export declare function releaseSecrets<Options extends {
+    secret?: unknown;
+    privateKey?: unknown;
+}>(options: Options): ReleasedSecrets<Options>;
+/**
+ * A lifetime from the config (a number of seconds or a `ms` duration such
+ * as `'1h'`), as a whole number of seconds. Lifetimes are validated first.
+ */
+export declare function toSeconds(value: number | string): number;

package/build/src/validation.js

@@ -1,11 +1,50 @@
-export function validateGuardOptions(options, prefix = 'JwtGuard') {
-    if (typeof options.tokenExpiresIn === 'number' &&
-        !(Number.isFinite(options.tokenExpiresIn) && options.tokenExpiresIn > 0)) {
-        throw new Error(`${prefix} \`tokenExpiresIn\` must be a positive number of seconds`);
-    }
+import ms from 'ms';
+export function validateGuardOptions(options, prefix = 'JWT guard') {
+    validateLifetimes(options, prefix);
     if (options.driver) {
         return;
     }
+    validateSigningMethod(options, prefix);
+}
+/**
+ * Token lifetimes and clock tolerance. A lifetime that is not a positive
+ * duration would issue tokens that are already expired (`'-1h'`), or fail
+ * on every login (`'abc'`).
+ */
+export function validateLifetimes(options, prefix) {
+    assertDuration(options.tokenExpiresIn, 'tokenExpiresIn', prefix);
+    assertDuration(options.refreshTokenExpiresIn, 'refreshTokenExpiresIn', prefix);
+    if (options.clockTolerance !== undefined &&
+        !(Number.isFinite(options.clockTolerance) && options.clockTolerance >= 0)) {
+        throw new Error(`${prefix} \`clockTolerance\` must be a number of seconds greater than or equal to 0`);
+    }
+}
+function assertDuration(value, name, prefix) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!(Number.isFinite(value) && value > 0)) {
+            throw new Error(`${prefix} \`${name}\` must be a positive number of seconds`);
+        }
+        return;
+    }
+    /**
+     * A numeric string such as '3600' (read from an env variable) is parsed as
+     * milliseconds by jsonwebtoken, so it is ambiguous: ask for a unit
+     */
+    if (typeof value !== 'string' || /^\s*[-+]?\d*\.?\d+\s*$/.test(value)) {
+        throw new Error(`${prefix} \`${name}\` must be a number of seconds or a duration with a unit, such as '15m' or '7d' (received ${JSON.stringify(value)})`);
+    }
+    const milliseconds = ms(value);
+    if (milliseconds === undefined || !Number.isFinite(milliseconds) || milliseconds < 1000) {
+        throw new Error(`${prefix} \`${name}\` must be a duration of at least 1 second, such as '15m' or '7d' (received ${JSON.stringify(value)})`);
+    }
+}
+/**
+ * Exactly one signing method: a secret, an asymmetric key pair, or a JWKS endpoint
+ */
+export function validateSigningMethod(options, prefix) {
     const asymmetricPartial = options.privateKey !== undefined ||
         options.publicKey !== undefined ||
         options.algorithm !== undefined;
@@ -15,10 +54,64 @@ export function validateGuardOptions(options, prefix = 'JwtGuard') {
     if (asymmetricPartial && !usesAsymmetric) {
         throw new Error(`${prefix} asymmetric mode requires \`privateKey\`, \`publicKey\`, and \`algorithm\` to be set together`);
     }
+    /**
+     * A falsy `verifyPayload` (`null`, `false`) must not count as a payload
+     * check: in JWKS mode it would replace the required `audience`
+     */
+    if (options.verifyPayload !== undefined && typeof options.verifyPayload !== 'function') {
+        throw new Error(`${prefix} \`verifyPayload\` must be a function`);
+    }
+    if (options.jwks && options.refreshTokenUserProvider) {
+        throw new Error(`${prefix} cannot use refresh tokens with \`jwks\`: tokens are issued by the identity provider, remove \`refreshTokenUserProvider\``);
+    }
+    if (options.secret !== undefined && typeof options.secret !== 'string') {
+        throw new Error(`${prefix} \`secret\` must be a string or a Secret`);
+    }
+    /**
+     * In JWKS mode, the driver checks them with its own message. Elsewhere,
+     * an empty value is signed into every token, then rejects all of them.
+     */
+    if (!options.jwks) {
+        if (options.issuer !== undefined && !isNonEmptyString(options.issuer)) {
+            throw new Error(`${prefix} \`issuer\` must be a non-empty string`);
+        }
+        if (options.audience !== undefined &&
+            !(Array.isArray(options.audience)
+                ? options.audience.length > 0 && options.audience.every(isNonEmptyString)
+                : isNonEmptyString(options.audience))) {
+            throw new Error(`${prefix} \`audience\` must be a non-empty string or array of strings`);
+        }
+    }
     if (options.jwks && usesAsymmetric) {
         throw new Error(`${prefix} cannot use \`jwks\` together with asymmetric \`privateKey\` / \`publicKey\``);
     }
+    if (options.jwks &&
+        !(typeof options.jwks.jwksUri === 'string' && options.jwks.jwksUri.trim() !== '')) {
+        throw new Error(`${prefix} \`jwks.jwksUri\` is required to fetch the identity provider keys`);
+    }
     if (!options.jwks && !usesAsymmetric && !options.secret) {
         throw new Error(`${prefix} requires \`secret\` (symmetric), or \`privateKey\` + \`publicKey\` + \`algorithm\` (asymmetric), or \`jwks\``);
     }
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+export function releaseSecrets(options) {
+    return {
+        ...options,
+        ...(options.secret !== undefined ? { secret: release(options.secret) } : {}),
+        ...(options.privateKey !== undefined ? { privateKey: release(options.privateKey) } : {}),
+    };
+}
+function release(value) {
+    return value && typeof value.release === 'function'
+        ? value.release()
+        : value;
+}
+/**
+ * A lifetime from the config (a number of seconds or a `ms` duration such
+ * as `'1h'`), as a whole number of seconds. Lifetimes are validated first.
+ */
+export function toSeconds(value) {
+    return Math.floor(typeof value === 'number' ? value : ms(value) / 1000);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maximemrf/adonisjs-jwt",
   "description": "AdonisJS package for authentication with JWT tokens",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "engines": {
     "node": ">=24.0.0"
   },