@julr/sesame 0.5.1 → 0.7.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2023
+Copyright (c) 2025-present Julien Ripouteau
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -2,51 +2,106 @@
 
 > OAuth 2.1 + OIDC server for AdonisJS
 
-Sésame is an AdonisJS package that turns your application into a full-featured OAuth 2.1 authorization server. It implements the core OAuth 2.1 specification along with OIDC discovery, token introspection, dynamic client registration, and MCP (Model Context Protocol) support.
+Sésame turns your AdonisJS application into a full-featured OAuth 2.1 authorization server. This guide covers:
 
-## Features
+- Installing and configuring the package
+- Registering OAuth and discovery routes
+- Protecting your API with the OAuth guard and scope checking
+- Managing tokens (refresh, revoke, introspect)
+- Enabling OpenID Connect (OIDC) for `id_token` emission, `/userinfo`, and JWKS
+- Using the Client Credentials grant for machine-to-machine authentication
+- Dynamic client registration and MCP support
 
-- **Authorization Code Grant** with PKCE (S256)
-- **Refresh Token Rotation** with replay detection
-- **Token Introspection** (RFC 7662) and **Revocation** (RFC 7009)
-- **Dynamic Client Registration** (RFC 7591)
-- **OIDC Discovery** (`/.well-known/openid-configuration`)
-- **OAuth Server Metadata** (RFC 8414)
-- **Protected Resource Metadata** (RFC 9728) for MCP servers
-- **Type-safe scopes** via module augmentation
-- **OAuth guard** for `@adonisjs/auth` with scope-checking middleware
-- **Token cleanup** via `sesame:purge` Ace command
+## Overview
+
+Modern applications need a reliable way to delegate authorization. Sésame implements the OAuth 2.1 specification on top of AdonisJS, giving you an authorization code flow with PKCE, refresh token rotation with replay detection, token introspection, revocation, and dynamic client registration out of the box.
+
+When you need identity claims on top of authorization, Sésame supports OpenID Connect. You provide an RSA key pair, wire up a user provider, and the server starts issuing signed `id_token` JWTs alongside access tokens.
 
 ## Installation
 
+`@adonisjs/auth` is required, including when you use Kysely without Lucid. If your application does not already have it, run `pnpm add @adonisjs/auth` before installing Sésame.
+
 ```bash
 node ace add @julr/sesame
 ```
 
-This will:
-
-- Publish the configuration file to `config/sesame.ts`
-- Publish database migrations (6 tables)
-- Register the service provider and commands
-
-Then run the migrations:
+By default, this publishes `config/sesame.ts`, creates six Lucid migrations, and registers the service provider and commands. Make sure `@adonisjs/lucid` is installed in your application, then run the migrations:
 
 ```bash
 node ace migration:run
 ```
 
+### Kysely installation
+
+You can use Sésame in a Kysely application without installing Lucid. The installer publishes a configuration file and a migration, but it does not connect to the database or create tables automatically.
+
+```bash title="Terminal"
+pnpm add kysely
+node ace add @julr/sesame --store=kysely
+```
+
+The generated `config/sesame.ts` selects the Kysely driver. Its `#services/kysely` import is a placeholder. Replace it with the module that exports your application's existing Kysely connection. For example, if that module exports `appDb` from `#services/database`, configure the store like this:
+
+```ts title="config/sesame.ts"
+import env from '#start/env'
+import { defineConfig, stores } from '@julr/sesame'
+import type { InferScopes } from '@julr/sesame/types'
+
+const sesameConfig = defineConfig({
+  issuer: env.get('APP_URL'),
+  store: stores.kysely({
+    connection: async () => {
+      const { appDb } = await import('#services/database')
+      return appDb
+    },
+  }),
+  scopes: {},
+  defaultScopes: [],
+  grantTypes: ['authorization_code', 'refresh_token'],
+  accessTokenTtl: '1h',
+  refreshTokenTtl: '30d',
+  authorizationCodeTtl: '10m',
+  loginPage: '/login',
+  consentPage: '/oauth/consent',
+  allowDynamicRegistration: false,
+  allowPublicRegistration: false,
+})
+
+export default sesameConfig
+
+declare module '@julr/sesame/types' {
+  interface SesameScopes extends InferScopes<typeof sesameConfig> {}
+}
+```
+
+> [!WARNING]
+> The generated config reads `APP_URL`. Your `start/env.ts` must validate that variable, and its value must be the public URL of the OAuth server, not the frontend URL or a `0.0.0.0` bind address. If your application already validates another public API URL, use that variable for `issuer` instead. Without a validated value, `env.get('APP_URL')` can be `undefined` and TypeScript will reject the config.
+
+The installer writes the complete migration to `database/kysely_migrations/create_oauth_tables.ts`. Keep that generated file in your application as a schema snapshot. When you already have a Kysely migrator, move it into that migrator's `migrationFolder`, give it a filename that sorts after your existing migrations, and run your usual migration command. For example, an application whose migrator reads `database/migrations` should put the file there. Do not pass it to Lucid's `node ace migration:run`.
+
+If Sésame uses its own migration folder, configure a separate [Kysely migrator](https://kysely-org.github.io/kysely-apidoc/classes/migration.Migrator.html) for `database/kysely_migrations` and call `migrateToLatest()` explicitly. Give that migrator unique `migrationTableName` and `migrationLockTableName` values when your application already has another Kysely migrator on the same database. Commit the generated migration so future Sésame upgrades cannot alter a migration you already applied.
+
+The Kysely driver supports SQLite, PostgreSQL, and MySQL. The default tests cover SQLite; `pnpm test:sql` runs the PostgreSQL and MySQL integration suite in temporary Docker containers. For a custom adapter backed by one of these databases, pass its `dialect` explicitly to `stores.kysely()`.
+
+Sésame configures one `store` at a time. It must be an AdonisJS `ConfigProvider<SesameStore>`; the service provider resolves it with the application before creating the manager. Choose `stores.lucid()`, `stores.kysely()`, or a custom driver. To add a custom driver, implement `SesameStore` from `@julr/sesame/types` and wrap it with `configProvider.create()`. The store interface exposes OAuth operations rather than generic CRUD queries. Its `exchangeAuthorizationCode`, `rotateRefreshToken`, and `issueTokenPair` methods must use real database transactions; the first two return `false` when another request consumed the credential first.
+
+Upgrading an existing Lucid application from 0.6.0 requires config and import changes. Follow the [0.6.0 to 0.7.0 migration guide](docs/migration-0.6-to-0.7.md).
+
 ## Configuration
 
-The configuration file lives at `config/sesame.ts`:
+The configuration file lives at `config/sesame.ts`. You define your issuer URL, available scopes, grant types, token lifetimes, and page redirects for the authorization flow.
 
-```ts
+```ts title="config/sesame.ts"
 import env from '#start/env'
-import { defineConfig } from '@julr/sesame'
+import { defineConfig, stores } from '@julr/sesame'
 import type { InferScopes } from '@julr/sesame/types'
 
 const sesameConfig = defineConfig({
   issuer: env.get('APP_URL'),
 
+  store: stores.lucid(),
+
   scopes: {
     read: 'Read access',
     write: 'Write access',
@@ -74,13 +129,13 @@ declare module '@julr/sesame/types' {
 }
 ```
 
-The `SesameScopes` augmentation gives you type-safe scope names throughout your application.
+The `SesameScopes` module augmentation gives you type-safe scope names throughout your application. When you reference a scope in middleware or guard calls, TypeScript will autocomplete and validate against the scopes you declared.
 
 ## Routes
 
-Register OAuth routes from your `start/routes.ts` file:
+You must register OAuth routes from your `start/routes.ts` file. The OAuth endpoints go inside a prefix group, and the discovery endpoints go at the root level so they remain at `/.well-known/...`.
 
-```ts
+```ts title="start/routes.ts"
 import sesame from '@julr/sesame/services/main'
 
 // OAuth endpoints under /oauth
@@ -90,31 +145,51 @@ router
   })
   .prefix('/oauth')
 
-// Discovery endpoints at the root
-sesame.registerWellKnownRoutes()
+// Discovery + JWKS endpoints at root
+sesame.registerDiscoveryRoutes()
 ```
 
 This registers the following endpoints:
 
-| Method | Path                                      | Description                            |
-| ------ | ----------------------------------------- | -------------------------------------- |
-| `POST` | `/oauth/token`                            | Token endpoint                         |
-| `GET`  | `/oauth/authorize`                        | Authorization endpoint                 |
-| `POST` | `/oauth/consent`                          | Consent submission                     |
-| `POST` | `/oauth/introspect`                       | Token introspection (RFC 7662)         |
-| `POST` | `/oauth/revoke`                           | Token revocation (RFC 7009)            |
-| `POST` | `/oauth/register`                         | Dynamic client registration (RFC 7591) |
-| `GET`  | `/oauth/client-info`                      | Public client info                     |
-| `GET`  | `/.well-known/oauth-authorization-server` | Server metadata (RFC 8414)             |
-| `GET`  | `/.well-known/openid-configuration`       | OIDC discovery                         |
+| Method     | Path                                      | Description                              |
+| ---------- | ----------------------------------------- | ---------------------------------------- |
+| `POST`     | `/oauth/token`                            | Token endpoint (RFC 6749 §3.2)           |
+| `GET`      | `/oauth/authorize`                        | Authorization endpoint (RFC 6749 §3.1)   |
+| `POST`     | `/oauth/consent`                          | Consent submission                       |
+| `POST`     | `/oauth/introspect`                       | Token introspection (RFC 7662)           |
+| `POST`     | `/oauth/revoke`                           | Token revocation (RFC 7009)              |
+| `POST`     | `/oauth/register`                         | Dynamic client registration (RFC 7591)   |
+| `GET`      | `/oauth/client-info`                      | Public client information                |
+| `GET/POST` | `/oauth/userinfo`                         | OpenID Connect UserInfo (OIDC Core §5.3) |
+| `GET`      | `/.well-known/oauth-authorization-server` | Server metadata (RFC 8414)               |
+| `GET`      | `/.well-known/openid-configuration`       | OIDC discovery                           |
+| `GET`      | `/.well-known/oauth-protected-resource`   | Protected resource metadata (RFC 9728)   |
+| `GET`      | `/jwks`                                   | JSON Web Key Set (RFC 7517)              |
+
+The JWKS path defaults to `/jwks`. You can customize it:
+
+```ts title="start/routes.ts"
+sesame.registerDiscoveryRoutes({ jwksPath: '/.well-known/jwks.json' })
+```
+
+## Authorization Code Flow
+
+The authorization code flow works in three steps. All clients must use PKCE with S256 (mandatory per OAuth 2.1).
+
+1. The consuming app redirects the user to `GET /oauth/authorize` with `client_id`, `redirect_uri`, `response_type=code`, `scope`, `state`, `code_challenge`, and `code_challenge_method=S256`. If the user is not logged in, they are sent to your `loginPage`. Once authenticated, they see the consent screen (your `consentPage`). If the user has already approved the requested scopes, consent is skipped and the code is issued directly.
+
+2. After the user approves, they are redirected back to the `redirect_uri` with a `code` and `state` parameter. The consuming app exchanges the code at `POST /oauth/token` with `grant_type=authorization_code`, the `code`, `redirect_uri`, client credentials, and the PKCE `code_verifier`. The response contains an `access_token`, `refresh_token` (when the `refresh_token` grant is enabled), `token_type`, `expires_in`, and `scope`. The `iss` parameter is included in all redirect responses per RFC 9207.
+
+3. The consuming app passes the access token as a `Bearer` token in the `Authorization` header when calling your API.
 
 ## Authentication Guard
 
-Sésame provides an OAuth guard for `@adonisjs/auth`. Configure it in `config/auth.ts`:
+Sésame provides an OAuth guard for `@adonisjs/auth` that verifies opaque Bearer tokens against the database, checks revocation and expiry, and resolves the user model. Configure it in `config/auth.ts`:
 
-```ts
-import { oauthGuard, oauthUserProvider } from '@julr/sesame/guard'
-import User from '#models/user'
+```ts title="config/auth.ts"
+import { defineConfig } from '@adonisjs/auth'
+import { oauthGuard } from '@julr/sesame/guard'
+import { oauthUserProvider } from '@julr/sesame/guard/lucid'
 
 const authConfig = defineConfig({
   default: 'web',
@@ -127,25 +202,32 @@ const authConfig = defineConfig({
 })
 ```
 
-Then use it in your controllers:
+Then use the guard in your controllers. After authentication, you have access to the user, the granted scopes, and the client ID.
+
+```ts title="app/controllers/api_controller.ts"
+import type { HttpContext } from '@adonisjs/core/http'
 
-```ts
 export default class ApiController {
   async index({ auth }: HttpContext) {
     const guard = auth.use('oauth')
     await guard.authenticate()
 
     const user = auth.user!
-    const scopes = guard.scopes
+    const scopes = guard.scopes // e.g. ['read', 'write']
+    const clientId = guard.clientId // e.g. 'my-app-client-id'
+
+    return { user, scopes, clientId }
   }
 }
 ```
 
-## Scope Middleware
+## Scopes
 
-Two named middleware are available for checking scopes on authenticated requests:
+### Scope Middleware
 
-```ts
+Two named middleware are available for checking scopes on authenticated requests. Use `scopes` when the client must have **all** listed scopes, and `anyScope` when having **at least one** is sufficient.
+
+```ts title="start/routes.ts"
 // Requires ALL listed scopes
 router.get('/admin', [AdminController]).use(middleware.scopes({ scopes: ['admin', 'write'] }))
 
@@ -153,32 +235,351 @@ router.get('/admin', [AdminController]).use(middleware.scopes({ scopes: ['admin'
 router.get('/data', [DataController]).use(middleware.anyScope({ scopes: ['read', 'write'] }))
 ```
 
-## MCP Support
+Important: these middleware are `TransientToken`-like. If the request carries an OAuth Bearer token, scopes are enforced against that token. If there is no Bearer token but the request is already authenticated through a session/web guard, the middleware lets the request through instead of rejecting on missing OAuth scopes.
 
-For MCP (Model Context Protocol) servers, register per-resource discovery:
+Use these middleware on routes that are allowed to accept either:
+
+- a scoped OAuth access token
+- or a first-party session-authenticated user
+
+If you want to require OAuth scopes strictly, authenticate with `auth.use('oauth').authenticate()` in your controller or route pipeline and check scopes on that guard explicitly.
+
+### Programmatic Scope Checking
+
+You can also check scopes directly in your controller logic using `hasScope()` and `hasAnyScope()` on the guard instance. This is useful when you need conditional behavior based on scopes rather than a hard reject.
+
+```ts title="app/controllers/posts_controller.ts"
+import type { HttpContext } from '@adonisjs/core/http'
+
+export default class PostsController {
+  async index({ auth }: HttpContext) {
+    const guard = auth.use('oauth')
+    await guard.authenticate()
+
+    // Check if the token has a specific scope
+    if (guard.hasScope('write')) {
+      return { posts: await Post.all(), canEdit: true }
+    }
+
+    return { posts: await Post.all(), canEdit: false }
+  }
+}
+```
+
+`hasScope()` requires **all** provided scopes. `hasAnyScope()` requires **at least one**.
+
+## Managing Tokens
+
+### Refreshing tokens
+
+The consuming app sends `POST /oauth/token` with `grant_type=refresh_token`, the `refresh_token`, and client credentials to get a new token pair. Sésame uses **refresh token rotation**: every refresh returns a new refresh token and the old one is revoked immediately. If an attacker replays a revoked refresh token, all tokens for that client+user pair are nuked as a security measure. The client can request a narrower set of scopes by passing a `scope` parameter, but cannot request scopes that were not in the original grant.
+
+### Revoking tokens
+
+The consuming app can call `POST /oauth/revoke` with the `token`, optional `token_type_hint`, and client credentials. The endpoint always returns HTTP 200, even if the token was not found (to prevent information leakage per RFC 7009). When revoking a refresh token, the associated access token is also revoked automatically.
+
+On the server side, you can revoke all tokens for a user at once. This is useful when a user is deleted or deactivated.
 
 ```ts
-sesame.registerProtectedResource({
-  resource: '/api/mcp',
-  scopes: ['read:mcp'],
+import sesame from '@julr/sesame/services/main'
+
+await sesame.revokeAllForUser(user.id)
+```
+
+### Introspecting tokens
+
+Resource servers can verify a token's state by calling `POST /oauth/introspect` with the `token`, optional `token_type_hint`, and client credentials. The response is `{ "active": true, "token_type": "Bearer", "client_id": "...", "sub": "...", "scope": "...", ... }` for valid tokens, or `{ "active": false }` for invalid, expired, or revoked tokens. This is useful when a separate service needs to validate tokens without sharing database access.
+
+## OpenID Connect (OIDC)
+
+Sésame supports OpenID Connect on top of OAuth 2.1. When OIDC is enabled, the server issues signed `id_token` JWTs alongside access tokens, exposes a `/userinfo` endpoint for retrieving user claims, and publishes a JWKS so relying parties can verify token signatures.
+
+OIDC is opt-in. You need two things: an RSA key pair (JWK) for signing ID tokens, and a user provider so the server can resolve user claims.
+
+### Generating a JWK
+
+You need an RSA private key in JWK format. The easiest way is to write it directly to your `.env` file:
+
+```bash
+node ace sesame:key --write-env
+```
+
+This generates a JWK and adds (or replaces) `OIDC_JWK` in your `.env` file. Never commit the private key to your repository.
+
+You can also output the raw JSON for piping to a secret manager or file:
+
+```bash
+node ace sesame:key --raw > jwk.json
+```
+
+Or run `node ace sesame:key` without flags to see the key with usage instructions.
+
+### Configuration
+
+Pass the JWK and a user provider to `defineConfig`. The `oidcProvider` uses the same `oauthUserProvider` helper you configure for the auth guard.
+
+```ts title="config/sesame.ts"
+import env from '#start/env'
+import { defineConfig, stores } from '@julr/sesame'
+import { oauthUserProvider } from '@julr/sesame/guard/lucid'
+
+const sesameConfig = defineConfig({
+  issuer: env.get('APP_URL'),
+
+  store: stores.lucid(),
+
+  scopes: {
+    read: 'Read access',
+    write: 'Write access',
+  },
+
+  loginPage: '/login',
+  consentPage: '/oauth/consent',
+
+  // OIDC configuration
+  jwk: JSON.parse(env.get('OIDC_JWK')),
+  oidcProvider: oauthUserProvider({ model: () => import('#models/user') }),
+  idTokenTtl: '1h',
 })
 ```
 
-This creates a `/.well-known/oauth-protected-resource/api/mcp` endpoint following RFC 9728.
+Both `jwk` and `oidcProvider` must be set for OIDC to be active. If either is missing, the server works as a pure OAuth 2.1 server and OIDC endpoints return 404.
 
-You can also enable public client registration for MCP clients:
+### User Claims
 
-```ts
+When the `openid` scope is granted, Sésame calls `getOidcClaims()` on your User model to populate the `id_token` and `/userinfo` response with user-specific claims. If the method is not implemented, only protocol-level claims (`sub`, `iss`, `aud`, `exp`, `iat`) are included.
+
+Implement the `OidcSubject` interface and use the `collectOidcClaims` helper for a type-safe, declarative mapping of scopes to claims:
+
+```ts title="app/models/user.ts"
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+import { collectOidcClaims } from '@julr/sesame/types'
+import type { OidcSubject, Scope } from '@julr/sesame/types'
+
+export default class User extends BaseModel implements OidcSubject {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare fullName: string
+
+  @column()
+  declare email: string
+
+  /**
+   * Return OIDC claims based on the granted scopes.
+   * Protocol-managed claims (sub, iss, aud, exp, iat, nonce, at_hash)
+   * are filtered out automatically so you cannot accidentally override them.
+   */
+  getOidcClaims(scopes: Scope[]) {
+    return collectOidcClaims(scopes, {
+      profile: { name: this.fullName },
+      email: { email: this.email },
+    })
+  }
+}
+```
+
+### OIDC Scopes
+
+Three scopes are OIDC-specific: `openid`, `profile`, and `email`. They are recognized by the server without needing to be declared in your `scopes` config.
+
+- `openid` triggers `id_token` emission. The `profile` and `email` scopes are only valid when `openid` is also requested.
+- If a client requests `openid` but OIDC is not configured, the authorization endpoint rejects the request with `invalid_scope`.
+
+### How `id_token` Is Issued
+
+When the `openid` scope is present in the authorization code or refresh token exchange, the token response includes an `id_token` field alongside `access_token` and `refresh_token`:
+
+```json
+{
+  "access_token": "oat_...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "ort_...",
+  "id_token": "eyJhbGciOiJSUzI1NiIs..."
+}
+```
+
+The `id_token` is a signed JWT containing `iss`, `sub`, `aud`, `iat`, `exp`, `at_hash`, and any claims returned by `getOidcClaims()`. When the authorization request included a `nonce` parameter, it is echoed in the `id_token` payload. On refresh token exchanges, the `nonce` is omitted per OIDC Core §12.2.
+
+### UserInfo Endpoint
+
+The `/userinfo` endpoint (GET and POST) returns claims about the authenticated user. It requires a valid access token with the `openid` scope. The token can be passed as a `Bearer` header or as an `access_token` body parameter.
+
+```bash
+curl -H "Authorization: Bearer oat_..." https://auth.example.com/oauth/userinfo
+```
+
+```json
+{
+  "sub": "42",
+  "name": "Julien Ripouteau",
+  "email": "julien@example.com"
+}
+```
+
+### JWKS Endpoint
+
+The `/jwks` endpoint serves the public key(s) used to sign ID tokens. Relying parties use this to verify `id_token` signatures without needing the private key. The response includes a `Cache-Control` header (`public, max-age=900`) so clients can cache the key set.
+
+## Client Credentials Grant
+
+For machine-to-machine (M2M) authentication, enable the `client_credentials` grant. This allows a confidential client to send `POST /oauth/token` with `grant_type=client_credentials`, its credentials (via Basic auth or POST body), and the requested `scope`. No refresh token is issued.
+
+```ts title="config/sesame.ts"
+const sesameConfig = defineConfig({
+  // ...
+  grantTypes: ['authorization_code', 'refresh_token', 'client_credentials'],
+  clientCredentialsAccessTokenTtl: '2h',
+})
+```
+
+User-centric scopes (`openid`, `profile`, `email`, `offline_access`) are rejected for client credentials since they are meaningless in an M2M context. The client must be associated with a user (`userId` on the client record) and must be confidential (not public).
+
+## Dynamic Client Registration
+
+Sésame supports RFC 7591 dynamic client registration. Clients send their metadata (`redirect_uris`, `client_name`, `grant_types`, `scope`, `token_endpoint_auth_method`) to `POST /oauth/register` and receive a `client_id` and `client_secret` in return. Set `token_endpoint_auth_method` to `"none"` for public clients (no secret issued). Requested scopes and grant types are validated against your server config.
+
+```ts title="config/sesame.ts"
 const sesameConfig = defineConfig({
   // ...
   allowDynamicRegistration: true,
-  allowPublicRegistration: true,
+  allowPublicRegistration: true, // allows unauthenticated registration
 })
 ```
 
+## Managing Clients
+
+### Creating clients from the CLI
+
+The `sesame:client` Ace command creates a new OAuth client interactively. It prompts for a name, redirect URIs, and client type, then outputs the generated credentials.
+
+```bash
+node ace sesame:client
+```
+
+You can also pass flags to skip the prompts:
+
+```bash
+node ace sesame:client --name "My App" --redirect-uris https://app.example.com/callback
+node ace sesame:client --name "SPA" --public --redirect-uris https://spa.example.com/callback
+node ace sesame:client --name "M2M Service" --grant-types client_credentials --user-id 42
+```
+
+The client secret is displayed once at creation time and cannot be retrieved later (it is stored as a SHA-256 hash).
+
+### Programmatic client management
+
+The `SesameManager` exposes methods for managing clients from your application code. This is useful for admin panels, seeding scripts, or any workflow where you need to create and manage clients without the CLI or dynamic registration.
+
+```ts
+import sesame from '@julr/sesame/services/main'
+
+// Create a confidential client
+const { client, clientSecret } = await sesame.createClient({
+  name: 'Partner App',
+  redirectUris: ['https://partner.example.com/callback'],
+  scopes: ['read', 'write'],
+  grantTypes: ['authorization_code', 'refresh_token'],
+})
+
+// Create a public client (no secret)
+const { client: spa } = await sesame.createClient({
+  name: 'SPA',
+  redirectUris: ['https://spa.example.com/callback'],
+  isPublic: true,
+})
+```
+
+`createClient` returns a plain client record and the raw secret. The secret is only available at creation time. Client records returned by the public management methods do not serialize the stored `clientSecret` hash.
+
+To find, list, update, or delete clients:
+
+```ts
+// Find by public client_id
+const client = await sesame.findClient('a1b2c3...')
+
+// List all clients (optionally filtered by owner)
+const allClients = await sesame.listClients()
+const userClients = await sesame.listClients({ userId: '42' })
+
+// Update specific fields
+await sesame.updateClient('a1b2c3...', {
+  name: 'New Name',
+  redirectUris: ['https://new.example.com/callback'],
+  isDisabled: true,
+})
+
+// Delete a client and all its tokens, codes, and consents
+await sesame.deleteClient('a1b2c3...')
+```
+
+To rotate a confidential client's secret (e.g. after a suspected leak):
+
+```ts
+const newSecret = await sesame.rotateClientSecret('a1b2c3...')
+// Returns the new raw secret, or null if the client is public or not found
+```
+
+## MCP Support
+
+For MCP (Model Context Protocol) servers, you can register per-resource discovery endpoints following RFC 9728. This tells MCP clients which authorization server protects a given resource.
+
+```ts title="start/routes.ts"
+sesame.registerProtectedResource({
+  resource: '/api/mcp',
+  scopes: ['read:mcp'],
+})
+```
+
+This creates a `/.well-known/oauth-protected-resource/api/mcp` endpoint. MCP clients that support the latest spec will discover this automatically.
+
+MCP clients typically need to self-register, so you will want to enable dynamic client registration with public access (see the [Dynamic Client Registration](#dynamic-client-registration) section above).
+
+## Events
+
+The OAuth guard emits events during authentication that you can listen to for logging, analytics, or custom behavior.
+
+| Event                                 | When                                                                   |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `oauth_auth:authentication_attempted` | A bearer token has been received and authentication starts             |
+| `oauth_auth:authentication_succeeded` | The token is valid and the user has been resolved                      |
+| `oauth_auth:authentication_failed`    | The token is invalid, expired, revoked, or the user cannot be resolved |
+
+```ts title="start/events.ts"
+import emitter from '@adonisjs/core/services/emitter'
+
+emitter.on('oauth_auth:authentication_failed', (event) => {
+  logger.warn({ guardName: event.guardName, err: event.error }, 'OAuth authentication failed')
+})
+```
+
+## Testing
+
+The OAuth guard implements `authenticateAsClient`, which integrates with Japa's `loginAs` helper. This automatically creates a test OAuth client and access token in the database, so your tests can make authenticated API requests without going through the full authorization flow.
+
+```ts title="tests/functional/api.spec.ts"
+import { test } from '@japa/runner'
+import User from '#models/user'
+
+test.group('API', () => {
+  test('returns user data for authenticated request', async ({ client }) => {
+    const user = await User.find(1)
+
+    const response = await client.get('/api/me').loginAs(user, 'oauth')
+
+    response.assertStatus(200)
+    response.assertBodyContains({ id: user.id })
+  })
+})
+```
+
+The test client is created with `defaultScopes` from your config. The token is scoped to a `__test_client__` OAuth client that gets auto-created on first use.
+
 ## Token Cleanup
 
-Purge expired and revoked tokens with the Ace command:
+Expired and revoked tokens accumulate over time. Purge them with the Ace command:
 
 ```bash
 node ace sesame:purge
@@ -187,22 +588,27 @@ node ace sesame:purge --expired-only
 node ace sesame:purge --retention-hours=168
 ```
 
+The `--retention-hours` flag (default: 168, i.e. 7 days) controls how long expired tokens are kept for audit purposes before deletion.
+
 You can also call it programmatically:
 
 ```ts
 import sesame from '@julr/sesame/services/main'
 
 const result = await sesame.purgeTokens({ retentionHours: 168 })
+// => { accessTokens: 42, refreshTokens: 12, authorizationCodes: 3, pendingRequests: 7 }
 ```
 
 ## Security
 
-- Tokens (access, refresh, authorization codes, client secrets) are stored as **SHA-256 hashes** — raw values are never persisted
-- PKCE with **S256** is required for public clients
-- Refresh tokens use **rotation** — the old token is revoked on each use
-- **Replay detection**: if a revoked refresh token is reused, all tokens for that client+user pair are revoked
-- Client secret verification uses **timing-safe comparison**
-- OAuth errors follow the standard JSON format with proper HTTP status codes and `WWW-Authenticate` headers
+- All tokens (access tokens, refresh tokens, authorization codes, client secrets) are stored as **SHA-256 hashes**. Raw values are never persisted in the database.
+- PKCE with **S256** is mandatory for all clients (OAuth 2.1).
+- Refresh tokens use **rotation**. The old token is revoked immediately on use.
+- **Replay detection**: if a revoked refresh token is presented, all tokens for that client+user pair are revoked to mitigate stolen token reuse.
+- Client secret verification uses **timing-safe comparison**.
+- ID tokens are signed with **RS256** using the configured JWK. The JWKS endpoint only exposes public key components.
+- Protocol-managed claims (`sub`, `iss`, `aud`, `exp`, `iat`, `nonce`, `at_hash`) cannot be overridden by `getOidcClaims()`.
+- OAuth errors follow the standard JSON format with proper HTTP status codes and `WWW-Authenticate` headers.
 
 ## License