@maximemrf/adonisjs-jwt 0.9.0 → 1.0.0-rc.2

package/build/src/define_config.js

@@ -1,62 +1,27 @@
-import { JwtGuard } from './jwt.js';
-import { createPrivateKey, createPublicKey } from 'node:crypto';
-function validateAsymmetricConfig(config) {
-    const partial = config.privateKey !== undefined ||
-        config.publicKey !== undefined ||
-        config.algorithm !== undefined;
-    if (!partial) {
-        return;
-    }
-    if (!config.privateKey || !config.publicKey || !config.algorithm) {
-        throw new Error('JWT guard asymmetric mode requires `privateKey`, `publicKey`, and `algorithm` to be set together');
-    }
-    if (config.jwks) {
-        throw new Error('JWT guard cannot use `jwks` together with asymmetric `privateKey` / `publicKey`');
-    }
-    const expectedKeyType = config.algorithm.startsWith('RS')
-        ? 'rsa'
-        : config.algorithm.startsWith('ES')
-            ? 'ec'
-            : null;
-    if (!expectedKeyType) {
-        throw new Error(`Unsupported asymmetric algorithm "${config.algorithm}"`);
-    }
-    try {
-        const privateKey = createPrivateKey(config.privateKey);
-        const publicKey = createPublicKey(config.publicKey);
-        if (privateKey.asymmetricKeyType !== expectedKeyType) {
-            throw new Error(`privateKey type "${privateKey.asymmetricKeyType}" does not match algorithm "${config.algorithm}"`);
-        }
-        if (publicKey.asymmetricKeyType !== expectedKeyType) {
-            throw new Error(`publicKey type "${publicKey.asymmetricKeyType}" does not match algorithm "${config.algorithm}"`);
-        }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : 'Invalid asymmetric key configuration';
-        throw new Error(`JWT guard asymmetric key validation failed: ${message}`);
-    }
-}
+import { JwtGuard } from './guard.js';
+import { validateGuardOptions } from './validation.js';
+import { resolveDriver } from './driver_resolver.js';
+import { hkdfSync } from 'node:crypto';
 export function jwtGuard(config) {
     return {
-        async resolver(_, app) {
-            validateAsymmetricConfig(config);
-            const appKey = app.config.get('app.appKey').release();
-            const usesAsymmetric = config.privateKey !== undefined &&
-                config.publicKey !== undefined &&
-                config.algorithm !== undefined;
+        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
-                    ? {
-                        privateKey: config.privateKey,
-                        publicKey: config.publicKey,
-                        algorithm: config.algorithm,
-                    }
-                    : {
-                        secret: config.secret ?? appKey,
-                    }),
+                ...(usesAsymmetric ? asymmetricKeys : { secret: resolvedSecret }),
                 refreshTokenUserProvider: config.refreshTokenUserProvider,
                 tokenName: config.tokenName,
-                expiresIn: config.tokenExpiresIn,
+                refreshTokenName: config.refreshTokenName,
+                tokenExpiresIn: config.tokenExpiresIn,
                 refreshTokenExpiresIn: config.refreshTokenExpiresIn,
                 useCookies: config.useCookies,
                 useCookiesForRefreshToken: config.useCookiesForRefreshToken,
@@ -64,8 +29,39 @@ export function jwtGuard(config) {
                 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,
             };
-            return (ctx) => new JwtGuard(ctx, config.provider, options);
+            validateGuardOptions(options, 'JWT guard');
+            const driver = resolveDriver(options, 'JWT guard');
+            return (ctx) => new JwtGuard(ctx, config.provider, { ...options, driver });
         },
     };
 }
+/**
+ * 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');
+    }
+    return Buffer.from(hkdfSync('sha256', rawAppKey, '', `@maximemrf/adonisjs-jwt:${guardName}`, 32)).toString('hex');
+}
+/**
+ * AdonisJS v6 exposes the app key as `app.appKey` in config/app.ts. AdonisJS
+ * v7 apps only pass APP_KEY to config/encryption.ts, and the env loader
+ * copies it to process.env.
+ */
+function readAppKey(app) {
+    const appKey = app.config.get('app.appKey', undefined);
+    if (appKey) {
+        return typeof appKey === 'string' ? appKey : appKey.release();
+    }
+    return process.env.APP_KEY;
+}

package/build/src/driver_resolver.d.ts

@@ -0,0 +1,16 @@
+import type { Options } from 'jwks-rsa';
+import type { JwtAsymmetricAlgorithm, JwtJwksAlgorithm } from './types.js';
+import type { JwtDriver } from './drivers/types.js';
+export declare function resolveDriver(options: {
+    driver?: JwtDriver;
+    secret?: string;
+    privateKey?: string;
+    publicKey?: string;
+    algorithm?: JwtAsymmetricAlgorithm;
+    jwks?: Options;
+    issuer?: string;
+    audience?: string | string[];
+    algorithms?: JwtJwksAlgorithm[];
+    clockTolerance?: number;
+    verifyPayload?: unknown;
+}, contextName?: string): JwtDriver;

package/build/src/driver_resolver.js

@@ -0,0 +1,46 @@
+import { SymmetricDriver } from './drivers/symmetric.js';
+import { AsymmetricDriver } from './drivers/asymmetric.js';
+import { JwksDriver } from './drivers/jwks.js';
+export function resolveDriver(options, contextName = 'JWT guard') {
+    if (options.driver) {
+        return options.driver;
+    }
+    const usesAsymmetric = options.privateKey !== undefined &&
+        options.publicKey !== undefined &&
+        options.algorithm !== undefined;
+    if (options.jwks) {
+        try {
+            return new JwksDriver(options.jwks, {
+                issuer: options.issuer,
+                audience: options.audience,
+                clockTolerance: options.clockTolerance,
+                algorithms: options.algorithms,
+                verifiesPayload: options.verifyPayload !== undefined,
+            });
+        }
+        catch (error) {
+            throw new Error(`${contextName} JWKS validation failed: ${error.message}`);
+        }
+    }
+    if (usesAsymmetric) {
+        try {
+            return new AsymmetricDriver({
+                privateKey: options.privateKey,
+                publicKey: options.publicKey,
+                algorithm: options.algorithm,
+                issuer: options.issuer,
+                audience: options.audience,
+                clockTolerance: options.clockTolerance,
+            });
+        }
+        catch (error) {
+            throw new Error(`${contextName} asymmetric key validation failed: ${error.message}`);
+        }
+    }
+    return new SymmetricDriver({
+        secret: options.secret,
+        issuer: options.issuer,
+        audience: options.audience,
+        clockTolerance: options.clockTolerance,
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { StringValue } from 'ms';
+import type { JwtDriver } from './types.js';
+import type { JwtAsymmetricAlgorithm } from '../types.js';
+export declare class AsymmetricDriver implements JwtDriver {
+    #private;
+    readonly canSign = true;
+    constructor(options: {
+        privateKey: string;
+        publicKey: string;
+        algorithm: JwtAsymmetricAlgorithm;
+        issuer?: string;
+        audience?: string | string[];
+        clockTolerance?: number;
+    });
+    sign(payload: Record<string, any>, options?: {
+        expiresIn?: number | StringValue;
+    }): string;
+    verify(token: string): Record<string, any> | string;
+}

package/build/src/drivers/asymmetric.js

@@ -0,0 +1,57 @@
+import jwt from 'jsonwebtoken';
+import { createPrivateKey, createPublicKey } from 'node:crypto';
+export class AsymmetricDriver {
+    canSign = true;
+    #privateKey;
+    #publicKey;
+    #algorithm;
+    #issuer;
+    #audience;
+    #clockTolerance;
+    constructor(options) {
+        this.#privateKey = options.privateKey;
+        this.#publicKey = options.publicKey;
+        this.#algorithm = options.algorithm;
+        this.#issuer = options.issuer;
+        this.#audience = options.audience;
+        this.#clockTolerance = options.clockTolerance;
+        this.#assertAsymmetricKeyMatchesAlgorithm();
+    }
+    #assertAsymmetricKeyMatchesAlgorithm() {
+        const algorithm = this.#algorithm;
+        const expectedKeyType = algorithm.startsWith('RS')
+            ? 'rsa'
+            : algorithm.startsWith('ES')
+                ? 'ec'
+                : null;
+        if (!expectedKeyType) {
+            throw new Error(`Unsupported asymmetric algorithm "${algorithm}"`);
+        }
+        const privateKey = createPrivateKey(this.#privateKey);
+        const publicKey = createPublicKey(this.#publicKey);
+        if (privateKey.asymmetricKeyType !== expectedKeyType) {
+            throw new Error(`privateKey type "${privateKey.asymmetricKeyType}" does not match algorithm "${algorithm}"`);
+        }
+        if (publicKey.asymmetricKeyType !== expectedKeyType) {
+            throw new Error(`publicKey type "${publicKey.asymmetricKeyType}" does not match algorithm "${algorithm}"`);
+        }
+    }
+    sign(payload, options) {
+        const signOptions = {
+            ...(options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}),
+            algorithm: this.#algorithm,
+            ...(this.#issuer ? { issuer: this.#issuer } : {}),
+            ...(this.#audience ? { audience: this.#audience } : {}),
+        };
+        return jwt.sign(payload, this.#privateKey, signOptions);
+    }
+    verify(token) {
+        const verifyOptions = {
+            algorithms: [this.#algorithm],
+            ...(this.#issuer ? { issuer: this.#issuer } : {}),
+            ...(this.#audience ? { audience: this.#audience } : {}),
+            ...(this.#clockTolerance !== undefined ? { clockTolerance: this.#clockTolerance } : {}),
+        };
+        return jwt.verify(token, this.#publicKey, verifyOptions);
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { Options } from 'jwks-rsa';
+import type { StringValue } from 'ms';
+import type { JwtDriver } 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
+ * the identity provider. They can be overridden through the `jwks` option.
+ */
+export declare const DEFAULT_JWKS_OPTIONS: {
+    cache: true;
+    rateLimit: true;
+    jwksRequestsPerMinute: number;
+    timeout: number;
+};
+export declare class JwksDriver implements JwtDriver {
+    #private;
+    readonly canSign = false;
+    constructor(options: Options, driverOptions?: {
+        issuer?: string;
+        audience?: string | string[];
+        algorithms?: JwtJwksAlgorithm[];
+        clockTolerance?: number;
+        verifiesPayload?: boolean;
+    });
+    sign(_payload: Record<string, any>, _options?: {
+        expiresIn?: number | StringValue;
+    }): never;
+    verify(token: string): Promise<Record<string, any> | string>;
+}

package/build/src/drivers/jwks.js

@@ -0,0 +1,68 @@
+import jwt from 'jsonwebtoken';
+import { errors } from '@adonisjs/auth';
+import { JwksManager } from '../jwks.js';
+import { ALLOWED_JWKS_ALGORITHMS } 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
+ * the identity provider. They can be overridden through the `jwks` option.
+ */
+export const DEFAULT_JWKS_OPTIONS = {
+    cache: true,
+    rateLimit: true,
+    jwksRequestsPerMinute: 10,
+    timeout: 5000,
+};
+export class JwksDriver {
+    canSign = false;
+    #jwksManager;
+    #issuer;
+    #audience;
+    #clockTolerance;
+    #algorithms;
+    constructor(options, driverOptions) {
+        if (!driverOptions?.issuer ||
+            !(hasAudience(driverOptions.audience) || driverOptions.verifiesPayload)) {
+            throw new Error('`issuer` and either `audience` or `verifyPayload` are required, otherwise any token signed by the identity provider is accepted, including tokens issued for other applications');
+        }
+        const algorithms = driverOptions.algorithms ?? [...ALLOWED_JWKS_ALGORITHMS];
+        if (algorithms.length === 0) {
+            throw new Error('`algorithms` must not be empty');
+        }
+        const unsupported = algorithms.filter((alg) => !ALLOWED_JWKS_ALGORITHMS.includes(alg));
+        if (unsupported.length > 0) {
+            throw new Error(`unsupported algorithm(s): ${unsupported.join(', ')}. Allowed: ${ALLOWED_JWKS_ALGORITHMS.join(', ')}`);
+        }
+        this.#jwksManager = new JwksManager({ ...DEFAULT_JWKS_OPTIONS, ...options });
+        this.#issuer = driverOptions.issuer;
+        this.#audience = driverOptions.audience;
+        this.#clockTolerance = driverOptions.clockTolerance;
+        this.#algorithms = algorithms;
+    }
+    sign(_payload, _options) {
+        throw new errors.E_UNAUTHORIZED_ACCESS("You can't use the auth.generate method with jwks", {
+            guardDriverName: 'jwt',
+        });
+    }
+    async verify(token) {
+        const decoded = jwt.decode(token, { complete: true });
+        if (!decoded || !decoded.header || !decoded.header.kid || !decoded.header.alg) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: 'jwt',
+            });
+        }
+        const key = await this.#jwksManager.getSigningKey(decoded.header.kid);
+        const verifyOptions = {
+            algorithms: [...this.#algorithms],
+            ...(this.#issuer ? { issuer: this.#issuer } : {}),
+            ...(this.#audience ? { audience: this.#audience } : {}),
+            ...(this.#clockTolerance !== undefined ? { clockTolerance: this.#clockTolerance } : {}),
+        };
+        return jwt.verify(token, key, verifyOptions);
+    }
+}
+function hasAudience(audience) {
+    return Array.isArray(audience)
+        ? audience.length > 0 && audience.every(Boolean)
+        : Boolean(audience);
+}

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

@@ -0,0 +1,16 @@
+import type { StringValue } from 'ms';
+import type { JwtDriver } from './types.js';
+export declare class SymmetricDriver implements JwtDriver {
+    #private;
+    readonly canSign = true;
+    constructor(options: {
+        secret: string;
+        issuer?: string;
+        audience?: string | string[];
+        clockTolerance?: number;
+    });
+    sign(payload: Record<string, any>, options?: {
+        expiresIn?: number | StringValue;
+    }): string;
+    verify(token: string): Record<string, any> | string;
+}

package/build/src/drivers/symmetric.js

@@ -0,0 +1,38 @@
+import jwt from 'jsonwebtoken';
+import { ALLOWED_SYMMETRIC_ALGORITHMS } from '../types.js';
+export class SymmetricDriver {
+    canSign = true;
+    #secret;
+    #issuer;
+    #audience;
+    #clockTolerance;
+    constructor(options) {
+        if (!options.secret) {
+            throw new Error('Symmetric JWT driver requires a secret key');
+        }
+        if (options.secret.length < 32) {
+            throw new Error('Symmetric JWT driver requires a secret of at least 32 characters to ensure sufficient entropy');
+        }
+        this.#secret = options.secret;
+        this.#issuer = options.issuer;
+        this.#audience = options.audience;
+        this.#clockTolerance = options.clockTolerance;
+    }
+    sign(payload, options) {
+        const signOptions = {
+            ...(options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}),
+            ...(this.#issuer ? { issuer: this.#issuer } : {}),
+            ...(this.#audience ? { audience: this.#audience } : {}),
+        };
+        return jwt.sign(payload, this.#secret, signOptions);
+    }
+    verify(token) {
+        const verifyOptions = {
+            algorithms: [...ALLOWED_SYMMETRIC_ALGORITHMS],
+            ...(this.#issuer ? { issuer: this.#issuer } : {}),
+            ...(this.#audience ? { audience: this.#audience } : {}),
+            ...(this.#clockTolerance !== undefined ? { clockTolerance: this.#clockTolerance } : {}),
+        };
+        return jwt.verify(token, this.#secret, verifyOptions);
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { StringValue } from 'ms';
+export interface JwtDriver {
+    readonly canSign: boolean;
+    sign(payload: Record<string, any>, options?: {
+        expiresIn?: number | StringValue;
+    }): string;
+    verify(token: string): Promise<Record<string, any> | string> | Record<string, any> | string;
+}

package/build/src/drivers/types.js

@@ -0,0 +1 @@
+export {};

package/build/src/{jwt.d.ts → guard.d.ts}

@@ -1,9 +1,8 @@
 import { symbols } from '@adonisjs/auth';
 import type { AuthClientResponse, GuardContract } from '@adonisjs/auth/types';
 import type { HttpContext } from '@adonisjs/core/http';
-import type { StringValue } from 'ms';
-import type { JwtUserProviderContract, JwtGuardOptions } from './types.js';
-export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof symbols.PROVIDER_REAL_USER]> {
+import { type JwtUserProviderContract, type JwtGuardOptions, type JwtGenerateResult } from './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]>);
     /**
@@ -34,13 +33,7 @@ export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unkno
     /**
      * Generate a JWT token for a given user.
      */
-    generate(user: UserProvider[typeof symbols.PROVIDER_REAL_USER]): Promise<{
-        type: string;
-        token: string;
-        expiresIn: number | StringValue | undefined;
-        refreshToken: string | undefined;
-        refreshTokenExpiresIn: number | StringValue | undefined;
-    }>;
+    generate(user: UserProvider[typeof symbols.PROVIDER_REAL_USER]): Promise<JwtGenerateResult<WithRefreshToken>>;
     /**
      * Authenticate the current HTTP request and return
      * the user instance if there is a valid JWT token
@@ -49,13 +42,7 @@ export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unkno
     authenticate(): Promise<UserProvider[typeof symbols.PROVIDER_REAL_USER] & {
         currentToken: string;
     }>;
-    generateWithRefreshToken(refreshToken?: string): Promise<{
-        type: string;
-        token: string;
-        expiresIn: number | StringValue | undefined;
-        refreshToken: string | undefined;
-        refreshTokenExpiresIn: number | StringValue | undefined;
-    } | undefined>;
+    generateWithRefreshToken(refreshToken?: string): Promise<JwtGenerateResult<true>>;
     /**
      * Revoke the refresh token
      */