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

package/build/src/define_config.js

@@ -1,56 +1,81 @@
 import { JwtGuard } from './guard.js';
-import { validateGuardOptions } from './validation.js';
+import { 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 = {
+        ...(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,
+    };
+    /**
+     * 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/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/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

@@ -44,7 +44,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

@@ -3,6 +3,8 @@ import { DEFAULT_TOKEN_EXPIRES_IN, } from './types.js';
 import { Secret } from '@adonisjs/core/helpers';
 import { validateGuardOptions } from './validation.js';
 import { resolveDriver } from './driver_resolver.js';
+import { installJwtUnauthorizedRenderer } from './errors.js';
+installJwtUnauthorizedRenderer();
 export class JwtGuard {
     #ctx;
     #userProvider;
@@ -12,6 +14,12 @@ 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;
@@ -98,6 +106,7 @@ export class JwtGuard {
                 }
                 : undefined);
             refreshToken = generatedRefreshToken.value.release();
+            this.#issuedRefreshToken = refreshToken;
         }
         if (this.#options.useCookies) {
             this.#ctx.response.cookie(`${this.#tokenName}`, token, {
@@ -293,7 +302,14 @@ 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) {
@@ -302,24 +318,21 @@ export class JwtGuard {
             });
         }
         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

package/build/src/validation.d.ts

@@ -1,2 +1,12 @@
 import type { JwtGuardOptions } from './types.js';
 export declare function validateGuardOptions(options: JwtGuardOptions, 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: JwtGuardOptions, prefix: string): void;

package/build/src/validation.js

@@ -1,11 +1,50 @@
+import ms from 'ms';
 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`);
-    }
+    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;
@@ -18,6 +57,10 @@ export function validateGuardOptions(options, prefix = 'JwtGuard') {
     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\``);
     }

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.4",
   "engines": {
     "node": ">=24.0.0"
   },