Skip to content

Release 0.6.0

Choose a tag to compare

@Julien-R44 Julien-R44 released this 02 Apr 20:38
· 108 commits to main since this release

0.6.0

Breaking Changes

refresh_token.access_token_id now stores a UUID instead of a SHA-256 hash

The access_token_id column in the oauth_refresh_tokens table previously stored the SHA-256 hash of the access token. It now stores the access token's UUID primary key. This affects how token revocation lookups are performed internally.

Migration required:

// database/migrations/xxxx_update_oauth_refresh_tokens_access_token_id.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  async up() {
    // 1. Truncate existing refresh tokens (they will be re-issued on next auth)
    await this.db.rawQuery('DELETE FROM oauth_refresh_tokens')

    // 2. Change column type from string to uuid
    this.schema.alterTable('oauth_refresh_tokens', (table) => {
      table.uuid('access_token_id').notNullable().alter()
    })
  }

  async down() {
    this.schema.alterTable('oauth_refresh_tokens', (table) => {
      table.string('access_token_id').notNullable().alter()
    })
  }
}

Note: Existing refresh tokens are incompatible with the new format and must be cleared. Users will need to re-authenticate once after the migration. Refresh tokens have a max TTL of 30 days, so alternatively you can just change the column type and let old tokens expire naturally (they will fail gracefully with invalid_grant).

DCR default grant_types now includes refresh_token

Clients registered via Dynamic Client Registration (RFC 7591) without an explicit grant_types field now default to ['authorization_code', 'refresh_token'] instead of ['authorization_code'].

This is technically a behavior change: previously, dynamically registered clients had to explicitly request the refresh_token grant type. Most MCP clients (Claude Code, etc.) already do this, so the impact should be minimal. If you relied on the old default to prevent refresh token issuance for dynamic clients, you will need to handle this at the application level.

New Features

OIDC Support

Full OpenID Connect support with ID token issuance, /userinfo endpoint, and JWKS endpoint. Requires configuring a JWK and an OIDC user provider.

New ace command sesame:key to generate the required RSA JWK.

Two new nullable columns are required for OIDC nonce support:

// database/migrations/xxxx_add_nonce_to_oauth_tables.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  async up() {
    this.schema.alterTable('oauth_authorization_codes', (table) => {
      table.string('nonce').nullable()
    })

    this.schema.alterTable('oauth_pending_authorization_requests', (table) => {
      table.string('nonce').nullable()
    })
  }

  async down() {
    this.schema.alterTable('oauth_authorization_codes', (table) => {
      table.dropColumn('nonce')
    })

    this.schema.alterTable('oauth_pending_authorization_requests', (table) => {
      table.dropColumn('nonce')
    })
  }
}

Note: These columns are only used when OIDC is enabled (jwk + oidcProvider configured). If you don't use OIDC, you should still add them to avoid runtime errors from the model.

Refresh Token Rotation Grace Period

New refreshTokenRotationGracePeriod config option (default: 120 seconds). Allows a recently-rotated refresh token to be reused within a short window instead of triggering replay-attack detection.

This fixes disconnection issues with MCP clients (Claude Code, etc.) where concurrent refresh attempts (proactive refresh + SDK 401 retry) caused the old refresh token to be replayed, nuking all tokens for that client.

Same approach as Auth0 ("reuse interval") and Cloudflare workers-oauth-provider ("previous token"). Set to 0 to disable and restore the previous strict behavior.

// config/sesame.ts
const sesameConfig = defineConfig({
  // ...
  refreshTokenRotationGracePeriod: 120, // seconds (default)
})

Client CRUD API & sesame:client command

Programmatic API for creating, updating, listing, and deleting OAuth clients. New sesame:client ace command for managing clients from the CLI.

Other Changes

  • Export exceptions via @julr/sesame/exceptions subpath
  • Support Lucid v21 and v22 in peer dependencies