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

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/configure.js

@@ -10,7 +10,7 @@
 | Flags: --refresh-tokens / --no-refresh-tokens to skip the question.
 |
 */
-import { existsSync, readdirSync } from 'node:fs';
+import { appendFileSync, existsSync, readdirSync } from 'node:fs';
 import { stubsRoot } from './stubs/main.js';
 const DOCS_URL = 'https://maximemrf.github.io/adonisjs-jwt';
 const MIGRATION_SUFFIX = '_create_jwt_refresh_tokens_table.ts';
@@ -127,11 +127,17 @@ async function createMigration(command, codemods) {
             .skipped('the migration already exists');
         return;
     }
-    await codemods.makeUsingStub(stubsRoot, 'migration.stub', {
+    const output = await codemods.makeUsingStub(stubsRoot, 'migration.stub', {
         entity: {
             filename: `${Date.now()}${MIGRATION_SUFFIX}`,
         },
     });
+    /**
+     * The stub renderer trims the final newline, which prettier reports
+     */
+    if (output.status !== 'skipped' && !output.contents.endsWith('\n')) {
+        appendFileSync(output.destination, '\n');
+    }
 }
 function getSourceFile(project, path) {
     return project.getSourceFile(path) ?? project.addSourceFileAtPath(path);

package/build/src/define_config.d.ts

@@ -6,9 +6,9 @@ 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>>(config: {
+export declare function jwtGuard<UserProvider extends JwtUserProviderContract<unknown>, RefreshTokenUserProvider extends AccessTokensUserProviderContract<unknown> | undefined = undefined>(config: {
     provider: UserProvider;
-    refreshTokenUserProvider?: AccessTokensUserProviderContract<unknown>;
+    refreshTokenUserProvider?: RefreshTokenUserProvider;
     tokenName?: string;
     refreshTokenName?: string;
     tokenExpiresIn?: number | StringValue;
@@ -29,4 +29,4 @@ export declare function jwtGuard<UserProvider extends JwtUserProviderContract<un
     clockTolerance?: number;
     getUserId?: JwtGetUserId;
     verifyPayload?: JwtVerifyPayload;
-}): GuardConfigProvider<(ctx: HttpContext) => JwtGuard<UserProvider>>;
+}): GuardConfigProvider<(ctx: HttpContext) => JwtGuard<UserProvider, [RefreshTokenUserProvider] extends [undefined] ? false : true>>;

package/build/src/guard.d.ts

@@ -2,7 +2,7 @@ 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';
-export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof symbols.PROVIDER_REAL_USER]> {
+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]>);
     /**
@@ -33,7 +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<JwtGenerateResult>;
+    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
@@ -42,7 +42,7 @@ export declare class JwtGuard<UserProvider extends JwtUserProviderContract<unkno
     authenticate(): Promise<UserProvider[typeof symbols.PROVIDER_REAL_USER] & {
         currentToken: string;
     }>;
-    generateWithRefreshToken(refreshToken?: string): Promise<JwtGenerateResult>;
+    generateWithRefreshToken(refreshToken?: string): Promise<JwtGenerateResult<true>>;
     /**
      * Revoke the refresh token
      */

package/build/src/guard.js

@@ -159,10 +159,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);
@@ -244,6 +256,9 @@ export class JwtGuard {
         this.isAuthenticated = true;
         this.user = user;
         this.user.currentToken = result.token;
+        /**
+         * The guard has a refresh token provider, so `generate()` issued a refresh token
+         */
         return result;
     }
     async #findRefreshToken() {
@@ -295,7 +310,16 @@ export class JwtGuard {
                 return;
             }
         }
-        await this.#refreshTokenUserProvider.invalidateToken(new Secret(refreshToken));
+        /**
+         * 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;
+        }
+        await this.#refreshTokenUserProvider.invalidateToken(secret);
     }
     /**
      * Remove the access and refresh token cookies set by the guard

package/build/src/types.d.ts

@@ -56,13 +56,19 @@ export declare const ALLOWED_ASYMMETRIC_ALGORITHMS: readonly ["RS256", "RS384",
 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];
-export type JwtGenerateResult = {
+/**
+ * `refreshToken` is a string when the guard has a `refreshTokenUserProvider`
+ */
+export type JwtGenerateResult<WithRefreshToken extends boolean = boolean> = {
     type: string;
     token: string;
     expiresIn?: number | StringValue;
-    refreshToken?: string;
     refreshTokenExpiresIn?: number | StringValue;
-};
+} & ([WithRefreshToken] extends [true] ? {
+    refreshToken: string;
+} : {
+    refreshToken?: string;
+});
 export type JwtGuardOptions<RealUser extends any = unknown> = {
     /**
      * Driver resolved by `jwtGuard()`. Not part of the public API: custom
@@ -133,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maximemrf/adonisjs-jwt",
   "description": "AdonisJS package for authentication with JWT tokens",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "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/"
 }