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

package/README.md

@@ -13,498 +13,79 @@
 
 > AdonisJS package to authenticate users using JWT tokens.
 
-## Compatibility & Versions
+**📖 Documentation: [maximemrf.github.io/adonisjs-jwt](https://maximemrf.github.io/adonisjs-jwt/)**
 
-| Package Version | AdonisJS Version  | Node.js Required |
-| --------------- | ----------------- | ---------------- |
-| `v0.7.x`        | `AdonisJS v6`     | `>= 20.6.0`      |
-| **`>= v0.8.x`**    | **`AdonisJS v7`** | **`>= 24.0.0`**  |
+- Access tokens signed with HMAC, RSA or ECDSA, or verified with JWKS
+- Rotating refresh tokens stored in the database
+- Bearer header or `HttpOnly` cookies
+- Works with the `auth` middleware and Japa's `loginAs`
 
-## Upgrading to 1.0
+## Compatibility
 
-Version 1.0 contains breaking changes. Check this list before upgrading from `0.9.x`:
+| Package version | AdonisJS version | Node.js     |
+| --------------- | ---------------- | ----------- |
+| `0.7.x`         | AdonisJS v6      | `>= 20.6.0` |
+| `>= 0.8.x`      | AdonisJS v7      | `>= 24.0.0` |
 
-- **Signing key**: without a `secret`, tokens are now signed with a key derived from the application key instead of the raw application key, and the application key must be at least 32 characters. Access tokens issued by `0.9.x` are rejected, so users have to log in again or use their refresh token, which stays valid. See [Security](#security).
-- **Default expiration**: `tokenExpiresIn` defaults to `1h`. A `content` function that sets `exp` itself now fails, use `tokenExpiresIn` instead.
-- **JWKS**: `issuer` is required, along with `audience` or `verifyPayload`. The guard throws at startup if they are missing. See [JWKS](#jwks).
-- **Refresh token in the query string**: it is ignored, send it in the body, a cookie or the `Authorization` header.
-- **Refresh token body field**: the field follows `refreshTokenName`. If you set a custom `refreshTokenName` and your clients send the token in a `refreshToken` body field, rename that field to match `refreshTokenName`.
-- **Refresh token lookup order**: when `useCookiesForRefreshToken` is enabled, the cookie is now read before the request body. See [Refresh token transport](#refresh-token-transport).
-- **Access token lookup order**: the `Authorization` header is now read before the cookie, and the cookie is only read when `useCookies` is enabled. If you set the `token` cookie yourself without `useCookies`, enable `useCookies`.
-- **`JwtGuardOptions.expiresIn`** is renamed to `tokenExpiresIn`, like the `jwtGuard()` option. This only affects code that instantiates `JwtGuard` directly.
+Upgrading from 0.9? Read the [1.0 upgrade guide](https://maximemrf.github.io/adonisjs-jwt/upgrading/1.0).
 
-Imports can now come from the main entrypoint: `import { jwtGuard } from '@maximemrf/adonisjs-jwt'`. The `@maximemrf/adonisjs-jwt/jwt_config` path still works. `@adonisjs/auth` is now a peer dependency.
+## Installation
 
-## Prerequisites
-
-You have to install the auth package from AdonisJS
-
-```bash
-node ace add @adonisjs/auth
-```
-
-## Setup (AdonisJS v7)
-
-Install the package:
-
-```bash
+```sh
+node ace add @adonisjs/auth # if not installed yet
 npm i @maximemrf/adonisjs-jwt
+node ace configure @maximemrf/adonisjs-jwt
 ```
 
-## Setup for AdonisJS v6
+## Quick start
 
-If you are using AdonisJS v6, you have to install the `v0.7.x` version of the package:
-
-```bash
-npm i @maximemrf/adonisjs-jwt@0.7.1
-```
+Register the guard in `config/auth.ts`:
 
-## Usage
-
-Go to `config/auth.ts` and add the following configuration:
-
-```typescript
+```ts
 import { defineConfig } from '@adonisjs/auth'
-import { InferAuthEvents, Authenticators } from '@adonisjs/auth/types'
-import { sessionGuard, sessionUserProvider } from '@adonisjs/auth/session'
-import { tokensUserProvider } from '@adonisjs/auth/access_tokens'
+import { sessionUserProvider } from '@adonisjs/auth/session'
 import { jwtGuard } from '@maximemrf/adonisjs-jwt'
-import env from '#start/env'
 
 const authConfig = defineConfig({
-  // define the default authenticator to jwt
   default: 'jwt',
   guards: {
-    web: sessionGuard({
-      useRememberMeTokens: false,
-      provider: sessionUserProvider({
-        model: () => import('#models/user'),
-      }),
-    }),
-    // add the jwt guard
     jwt: jwtGuard({
-      // tokenName is the name of the token passed as cookie, it can be optional, by default it is 'token'
-      tokenName: 'custom-name',
-      // tokenExpiresIn can be a string or a number, it can be optional, by default it is '1h'
-      tokenExpiresIn: '1h',
-      // if you want to use cookies for the authentication instead of the bearer token (optional)
-      useCookies: true,
-      // secret is the secret used to sign the token, it can be optional, by default a key derived from the application key is used
-      // you can use a env variable like JWT_SECRET or set it directly with a string
-      // if you don't have specific needs, please discard this option
-      secret: env.get('JWT_SECRET'),
       provider: sessionUserProvider({
         model: () => import('#models/user'),
       }),
-      // if you want to use refresh tokens, you have to set the refreshTokenUserProvider
-      refreshTokenUserProvider: tokensUserProvider({
-        tokens: 'refreshTokens',
-        model: () => import('#models/user'),
-      }),
-      // optionally set the expiry for the refresh token
-      refreshTokenExpiresIn: '7d',
-      // ability to separate cookie usage for refresh token
-      useCookiesForRefreshToken: true,
-      // ability to configure the cookies options
-      cookie: {
-        httpOnly: true,
-        secure: true,
-      },
-      // abilities given to refresh tokens, generateWithRefreshToken rejects tokens that don't have all of them
-      refreshTokenAbilities: ['refresh_token'],
-      // optional issuer (iss) and audience (aud) claims for token verification
-      issuer: 'my-app',
-      audience: 'my-api',
-      // content is a function that takes the user and returns the content of the token, it can be optional, by default it returns only the user id
-      // user.getOriginal() is typed after the provider's model, no cast needed
-      content: (user) => {
-        return {
-          userId: user.getId(),
-          email: user.getOriginal().email,
-        }
-      },
     }),
   },
 })
-```
-
-`tokenName` is the name of the jwt token passed as a cookie, it can be optional, by default it is `token`.
-`refreshTokenName` is the name of the refresh token cookie and of the request body field the guard reads it from, by default it is `refreshToken`.
-`issuer` and `audience` allow validating the `iss` and `aud` claims on incoming tokens to prevent cross-service token misuse in multi-service architecture.
-
-```typescript
-tokenName: 'custom-name'
-```
-
-`tokenExpiresIn` is the time before the jwt token expires, it can be a string or a number (in seconds) and it can be optional. It defaults to `1h`, so access tokens always expire. A number must be positive, otherwise the guard throws at startup.
-
-```typescript
-// string
-tokenExpiresIn: '1h'
-// number
-tokenExpiresIn: 60 * 60
-```
-
-You can also use cookies for the authentication instead of the bearer token by setting `useCookies` to `true`.
-
-```typescript
-useCookies: true
-```
-
-If you just want to use jwt with the bearer token no need to set `useCookies` to `false` you can just remove it.
-
-The guard reads the access token from the `Authorization: Bearer <token>` header first, then from the cookie when `useCookies` is enabled. A stale cookie therefore never shadows a valid bearer token, and the cookie is ignored when `useCookies` is disabled.
-
-You can also pass options to the cookies. Note that `maxAge` and `expires` are omitted from the options because they are automatically handled by the package based on the token validity (`tokenExpiresIn` and `refreshTokenExpiresIn`).
-By default, `httpOnly: true` and `secure: true` are enforced for better security, but you can override them using the `cookie` object configuration.
 
-```typescript
-cookie: {
-  httpOnly: true, // Default
-  secure: true,   // Default
-  path: '/',
-  sameSite: 'lax',
-  // maxAge and expires cannot be set here
-}
+export default authConfig
 ```
 
-## Asymmetric signing (RSA / ECDSA)
+Issue a token and protect routes:
 
-You can sign access tokens with a **private key** and verify them with a **public key** only. Other services can validate JWTs using the public key without receiving your signing secret.
+```ts
+import router from '@adonisjs/core/services/router'
+import { middleware } from '#start/kernel'
+import User from '#models/user'
 
-Set `privateKey`, `publicKey`, and `algorithm` together on `jwtGuard`. Supported algorithms: `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`.
-
-Do not set `secret` for this mode (the guard resolver omits it when asymmetric keys are configured). Asymmetric signing cannot be combined with `jwks`.
-
-```typescript
-import env from '#start/env'
-
-jwt: jwtGuard({
-  tokenExpiresIn: '15m',
-  privateKey: env.get('JWT_PRIVATE_KEY').replace(/\\n/g, '\n'),
-  publicKey: env.get('JWT_PUBLIC_KEY').replace(/\\n/g, '\n'),
-  algorithm: 'RS256',
-  content: (user) => ({ userId: user.getId() }),
-  provider: sessionUserProvider({
-    model: () => import('#models/user'),
-  }),
-}),
-```
-
-## JWKS
-
-You can use JWKS to verify the token by setting the `jwks` option in the guard configuration.
-
-```typescript
-// ...
-jwt: jwtGuard({
-  // ...
-  jwks: {
-    jwksUri: 'https://your-auth-server/.well-known/jwks.json',
-    // you can pass any options accepted by jwks-rsa package
-  },
-  // required in JWKS mode
-  issuer: 'https://your-auth-server',
-  audience: 'my-api',
-}),
-// ...
-```
-
-`issuer` is required in JWKS mode, along with `audience` or `verifyPayload` (see [Checking other claims](#check-other-claims)): the guard throws at startup if they are missing.
-
-Tokens with an unknown `kid` trigger a JWKS fetch, so the guard applies these jwks-rsa defaults, which you can override in the `jwks` option: `cache: true`, `rateLimit: true`, `jwksRequestsPerMinute: 10` and `timeout: 5000` (ms).
-
-> [!WARNING]
-> If you enable JWKS, you cannot use the `auth.use('jwt').generate(user)` and `auth.use('jwt').generateWithRefreshToken()` method because the token is signed by an external provider. You can only use the `authenticate` (or `check` / `getUserOrFail`) method to verify the token.
-
-Tokens issued by an external provider usually don't carry a `userId` claim. Use `getUserId` to tell the guard where to find the user id, and `algorithms` to restrict the accepted signing algorithms (default: every asymmetric algorithm supported in JWKS mode; symmetric `HS*` algorithms are never accepted):
-
-```typescript
-jwt: jwtGuard({
-  // ...
-  jwks: {
-    jwksUri: 'https://your-auth-server/.well-known/jwks.json',
-  },
-  issuer: 'https://your-auth-server',
-  audience: 'my-api',
-  algorithms: ['RS256'],
-  // seconds of clock skew tolerated on `exp` / `nbf` (optional, works in every mode)
-  clockTolerance: 30,
-  // default: (payload) => payload.userId
-  getUserId: (payload) => payload.sub,
-}),
-```
-
-> [!WARNING]
-> `issuer` and `audience` (or `verifyPayload`) are required in JWKS mode. Without them, **any** token signed by the identity provider would be accepted, including tokens issued for other applications. With Kubernetes, that means every pod's default ServiceAccount token.
-
-### Check other claims
-
-Some providers don't put your application in the `aud` claim. Amazon Cognito access tokens, for example, carry the app client in `client_id` and have no `aud`. Use `verifyPayload` to check those claims: it receives the verified payload before the user lookup, and the request is rejected when it returns `false`. In JWKS mode, it can replace `audience`:
-
-```typescript
-jwt: jwtGuard({
-  // ...
-  jwks: {
-    jwksUri: 'https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/jwks.json',
-  },
-  issuer: 'https://cognito-idp.<region>.amazonaws.com/<userPoolId>',
-  verifyPayload: (payload) => payload.client_id === '<appClientId>' && payload.token_use === 'access',
-  getUserId: (payload) => payload.sub,
-}),
-```
-
-`verifyPayload` works in every mode and can be async.
-
-### Example: Kubernetes ServiceAccount tokens
-
-The Kubernetes API server exposes its signing keys at `https://kubernetes.default.svc/openid/v1/jwks`. From inside the cluster, fetching them requires the cluster CA and a ServiceAccount token, which you can provide with a custom jwks-rsa `fetcher` (the token is re-read on each fetch because projected tokens are rotated):
-
-```typescript
-import { readFileSync } from 'node:fs'
-import https from 'node:https'
-
-const SA_DIR = '/var/run/secrets/kubernetes.io/serviceaccount'
-
-jwt: jwtGuard({
-  // findById receives the token `sub`, e.g. "system:serviceaccount:my-namespace:my-sa"
-  provider: new ServiceAccountUserProvider(),
-  jwks: {
-    jwksUri: 'https://kubernetes.default.svc/openid/v1/jwks',
-    cache: true,
-    fetcher: (uri) =>
-      new Promise((resolve, reject) => {
-        https
-          .get(
-            uri,
-            {
-              ca: readFileSync(`${SA_DIR}/ca.crt`),
-              headers: { Authorization: `Bearer ${readFileSync(`${SA_DIR}/token`, 'utf8')}` },
-            },
-            (res) => {
-              let body = ''
-              res.on('data', (chunk) => (body += chunk))
-              res.on('end', () => {
-                if (res.statusCode !== 200) {
-                  return reject(new Error(`JWKS fetch failed with status ${res.statusCode}`))
-                }
-                resolve(JSON.parse(body))
-              })
-            }
-          )
-          .on('error', reject)
-      }),
-  },
-  // must match the `audiences` of the projected token mounted in the calling pods
-  audience: 'my-api',
-  // default issuer on kubeadm-based clusters; managed clusters use their own URL (see below)
-  issuer: 'https://kubernetes.default.svc.cluster.local',
-  getUserId: (payload) => payload.sub,
-}),
-```
-
-The issuer depends on your cluster: `https://kubernetes.default.svc.cluster.local` is the kubeadm default, while managed clusters use their own URL (e.g. `https://oidc.eks.<region>.amazonaws.com/id/<id>` on EKS, `https://container.googleapis.com/v1/projects/<project>/locations/<location>/clusters/<cluster>` on GKE). Check yours with:
-
-```bash
-kubectl get --raw /.well-known/openid-configuration
-```
-
-Legacy Secret-based ServiceAccount tokens (issuer `kubernetes/serviceaccount`, no expiration) are rejected by the `issuer` check.
-
-The calling pod mounts a projected token with that audience and sends it as a Bearer token:
-
-```yaml
-spec:
-  containers:
-    - name: my-client
-      volumeMounts:
-        - name: api-token
-          mountPath: /var/run/secrets/my-api
-          readOnly: true
-  volumes:
-    - name: api-token
-      projected:
-        sources:
-          - serviceAccountToken:
-              path: token
-              audience: my-api
-              expirationSeconds: 3600
-```
-
-The kubelet rotates this token before it expires, so the client must re-read `/var/run/secrets/my-api/token` on each request (or at least regularly) instead of caching it at startup.
-
-> [!NOTE]
-> Tokens are verified offline against the JWKS, not through the Kubernetes `TokenReview` API. A token stays valid until its `exp` even if the pod it was issued for has been deleted (up to `expirationSeconds`, minimum 600). Keep `expirationSeconds` short, or call `TokenReview` from your user provider if you need immediate revocation.
-
-## Refresh Tokens
-
-To use refresh tokens, you have to set the `refreshTokenUserProvider` in the guard configuration, see the example above.
-
-Create a new AdonisJS migration file and run it to create the `jwt_refresh_tokens` table:
-
-```typescript
-import { BaseSchema } from '@adonisjs/lucid/schema'
-
-export default class extends BaseSchema {
-  protected tableName = 'jwt_refresh_tokens'
-
-  async up() {
-    this.schema.createTable(this.tableName, (table) => {
-      table.increments()
-      table
-        .integer('tokenable_id')
-        .notNullable()
-        .unsigned()
-        .references('id')
-        .inTable('users')
-        .onDelete('CASCADE')
-      table.string('type').notNullable()
-      table.string('name').nullable()
-      table.string('hash', 80).notNullable()
-      table.text('abilities').notNullable()
-      table.timestamp('created_at', { precision: 6, useTz: true }).notNullable()
-      table.timestamp('updated_at', { precision: 6, useTz: true }).notNullable()
-      table.timestamp('expires_at', { precision: 6, useTz: true }).nullable()
-      table.timestamp('last_used_at', { precision: 6, useTz: true }).nullable()
-    })
-  }
-
-  async down() {
-    this.schema.dropTable(this.tableName)
-  }
-}
-```
-
-And add the `refreshTokens` property to your User model:
-
-```typescript
-import { column, BaseModel } from '@adonisjs/lucid/orm'
-import { DbAccessTokensProvider } from '@adonisjs/auth/access_tokens'
-
-export default class User extends BaseModel {
-  @column({ isPrimary: true })
-  declare id: number
-
-  @column()
-  declare username: string
-
-  @column()
-  declare email: string
-
-  @column()
-  declare password: string
-
-  static refreshTokens = DbAccessTokensProvider.forModel(User, {
-    prefix: 'rt_',
-    table: 'jwt_refresh_tokens',
-    type: 'jwt_refresh_token',
-    tokenSecretLength: 40,
-  })
-}
-```
-
-## Authentication
-
-To make a protected route, you have to use the `auth` middleware with the `jwt` guard.
-
-```typescript
 router.post('login', async ({ request, auth }) => {
-  const { email, password } = request.all()
+  const { email, password } = request.only(['email', 'password'])
   const user = await User.verifyCredentials(email, password)
-
-  // to generate a token (and refresh token if configured)
-  // this returns { type, token, expiresIn, refreshToken, refreshTokenExpiresIn }
-  // if useCookies is true, it sets cookies on the response instead
   return await auth.use('jwt').generate(user)
 })
 
-// if the jwt guard is the default guard
-router
-  .get('/', async ({ auth }) => {
-    return auth.getUserOrFail()
-  })
-  .use(middleware.auth())
-
-// if the jwt guard is not the default guard
-router
-  .get('/', async ({ auth }) => {
-    return auth.use('jwt').getUserOrFail()
-  })
-  .use(middleware.auth({ guards: ['jwt'] }))
-
-// if you use the refresh token
-router.post('jwt/refresh', async ({ auth }) => {
-  // this will authenticate the user using the refresh token
-  // it will delete the old refresh token and generate a new one
-  // it accepts an optional refresh token, otherwise it looks in:
-  // 1. cookies (if useCookiesForRefreshToken is enabled)
-  // 2. request body, field named after refreshTokenName (never the query string)
-  // 3. Authorization header
-  return await auth.use('jwt').generateWithRefreshToken()
-})
-
-// to logout (revoke refresh token and clear the guard cookies)
-router.post('logout', async ({ auth }) => {
-  await auth.use('jwt').revoke()
-  return { message: 'Logged out' }
-})
-```
-
-After `authenticate()` or `generateWithRefreshToken()`, the access token of the request is available as `user.currentToken`, like `user.currentAccessToken` with the AdonisJS access tokens guard. After a refresh, it holds the new access token.
-
-## Security
-
-When no `secret` is configured, the guard signs tokens with a key derived from the AdonisJS application key (HKDF-SHA256, salted with the guard name), so you don't have to manage a secret and [avoid this](https://trufflesecurity.com/blog/stop-recommending-jwts). The raw application key is never used to sign JWTs, so tokens signed elsewhere with the application key (e.g. password reset links) are not accepted as access tokens, and two JWT guards never accept each other's tokens. The application key must be at least 32 characters.
-
-> [!NOTE]
-> Tokens issued before this key derivation was introduced (signed with the raw application key) are no longer accepted: users have to log in again, or use their refresh token, which is stored in the database and stays valid.
-
-### Refresh token transport
-
-The guard reads the refresh token from these sources, in order:
-
-1. An `HttpOnly` cookie named after `refreshTokenName`, when `useCookiesForRefreshToken` is enabled.
-2. The request body, in a field named after `refreshTokenName` (`refreshToken` by default). This is how OAuth 2.0 transmits refresh tokens ([RFC 6749 §6](https://datatracker.ietf.org/doc/html/rfc6749#section-6)).
-3. The `Authorization: Bearer <token>` header.
-
-A refresh token passed in the query string is ignored, since URLs end up in access logs, browser history and `Referer` headers.
-
-> [!IMPORTANT]
-> **Breaking change in 1.0**: the body field used to be `refreshToken` whatever `refreshTokenName` was set to, and the body was read before the cookie. If you set a custom `refreshTokenName`, your clients must now send the token in a body field with that name.
-
-Which transport to pick:
-
-- **Browsers**: use cookies (`useCookiesForRefreshToken: true`). The token is stored in an `HttpOnly` + `Secure` cookie, out of reach of JavaScript and scoped by the `SameSite` policy.
-- **Mobile apps, CLIs and other API clients**: send the token in the request body or the `Authorization` header.
-
-> [!WARNING]
-> Make sure your logging middleware does not record request bodies or `Authorization` headers on authentication routes, otherwise refresh tokens end up in plain text in your logs.
-
-### Symmetric secret strength
-
-When using symmetric signing (HMAC), the `secret` must be **at least 32 characters** long. A shorter secret can be brute-forced offline once an attacker obtains a signed token.
-
+router.get('me', async ({ auth }) => auth.getUserOrFail()).use(middleware.auth())
 ```
-// Too short — will throw at startup
-secret: 'mysecret'
 
-// Sufficient entropy
-secret: env.get('JWT_SECRET') // generate with: openssl rand -hex 32
-```
+Then see the [documentation](https://maximemrf.github.io/adonisjs-jwt/) for refresh tokens, cookies, asymmetric keys, JWKS and security.
 
-Generate a strong secret with:
+## Contributing
 
-```bash
-openssl rand -hex 32
+```sh
+npm install
+npm test          # lint, tests and coverage
+npm run docs:dev  # documentation, on http://localhost:5173/adonisjs-jwt/
 ```
 
-### Access token revocation & Statelessness
-
-JWT access tokens are **stateless** — once issued, they are cryptographically validated without querying the database until their expiration time (`tokenExpiresIn`).
-
-Calling `auth.use('jwt').revoke()` invalidates the **refresh token** stored in the database, preventing attackers from generating *new* access tokens, and clears the access and refresh token cookies set by the guard (when `useCookies` / `useCookiesForRefreshToken` are enabled). However, any existing, unexpired access token will remain valid until `tokenExpiresIn` elapses.
-
-> [!TIP]
-> Keep `tokenExpiresIn` short (e.g. `15m` or `1h`) to limit the lifetime of issued access tokens, and rely on `generateWithRefreshToken()` to silently rotate tokens.
-
+## License
 
+MIT

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, {
@@ -159,10 +168,22 @@ export class JwtGuard {
                 guardDriverName: this.driverName,
             });
         }
-        if (this.#options.verifyPayload && !(await this.#options.verifyPayload(payload))) {
-            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
-                guardDriverName: this.driverName,
-            });
+        if (this.#options.verifyPayload) {
+            /**
+             * Only an explicit `true` accepts the token: a truthy value such as
+             * a claim or an error message must not let it through. A callback
+             * that throws rejects the token instead of failing the request.
+             */
+            let isValid = false;
+            try {
+                isValid = await this.#options.verifyPayload(payload);
+            }
+            catch { }
+            if (isValid !== true) {
+                throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                    guardDriverName: this.driverName,
+                });
+            }
         }
         const getUserId = this.#options.getUserId ?? ((claims) => claims.userId);
         const userId = getUserId(payload);
@@ -281,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) {
@@ -290,15 +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)) ||
+            !(await this.#refreshTokenUserProvider.invalidateToken(secret))) {
+            throw new errors.E_UNAUTHORIZED_ACCESS('Unauthorized access', {
+                guardDriverName: this.driverName,
+            });
         }
-        await this.#refreshTokenUserProvider.invalidateToken(new Secret(refreshToken));
+        if (refreshToken === this.#issuedRefreshToken)
+            this.#issuedRefreshToken = undefined;
     }
     /**
      * Remove the access and refresh token cookies set by the guard

package/build/src/types.d.ts

@@ -139,7 +139,8 @@ export type JwtGuardOptions<RealUser extends any = unknown> = {
     getUserId?: JwtGetUserId;
     /**
      * Extra check on a verified token payload, run before looking up the user.
-     * Return `false` to reject the token. Use it to check claims other than
+     * Only an explicit `true` accepts the token: any other value, or an
+     * exception, rejects it. Use it to check claims other than
      * `iss` and `aud`, e.g. `client_id` and `token_use` for Amazon Cognito.
      */
     verifyPayload?: JwtVerifyPayload;

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.2",
+  "version": "1.0.0-rc.4",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -37,7 +37,10 @@
     "postbuild": "npm run copy:templates",
     "release": "np",
     "version": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
     "@adonisjs/assembler": "^8.4.0",
@@ -65,6 +68,7 @@
     "sqlite3": "^6.0.1",
     "timekeeper": "^2.3.1",
     "typescript": "~6.0.3",
+    "vitepress": "^1.6.4",
     "youch": "^4.1.1"
   },
   "dependencies": {
@@ -116,5 +120,6 @@
     "exclude": [
       "tests/**"
     ]
-  }
+  },
+  "homepage": "https://maximemrf.github.io/adonisjs-jwt/"
 }