@julr/sesame 0.5.0 → 0.6.0

package/build/src/types.d.ts

@@ -1,4 +1,6 @@
 import type { HttpContext } from '@adonisjs/core/http';
+import type { JWK } from 'jose';
+import type { OAuthUserProviderContract } from './guard/types.ts';
 /**
  * Augment this interface via module augmentation to enable
  * type-safe scope names across the application.
@@ -30,14 +32,63 @@ export type InferScopes<T extends {
  * Standard OAuth/OIDC scopes that are always valid regardless
  * of server or client scope configuration.
  *
+ * These scopes are:
+ * - Accepted during scope validation (client and server level)
+ * - Advertised in `scopes_supported` of all metadata endpoints
+ *   (protected resource, OIDC discovery) so MCP clients know
+ *   they can request them
+ *
  * - `offline_access`: signals that the client needs a refresh token
- *   (OIDC Core §11, OAuth 2.1). Without this built-in treatment,
- *   MCP clients that don't explicitly configure scopes would never
- *   receive a refresh token and would expire after the access token TTL.
+ *   (OIDC Core §11). Note: Sesame issues refresh tokens by default
+ *   when the `refresh_token` grant is enabled, regardless of whether
+ *   the client requests this scope (per RFC 6749 §5.1). This scope
+ *   is still advertised for clients that check metadata before
+ *   building their authorization request.
  *
  * @see https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
  */
 export declare const BUILTIN_SCOPES: Set<string>;
+/**
+ * OIDC-recognized scopes that are accepted by server-level validation
+ * without needing to be declared in the config `scopes` map.
+ *
+ * Unlike `BUILTIN_SCOPES`, these still require explicit client authorization
+ * via `ClientService.validateClientScopes()`.
+ */
+export declare const OIDC_SCOPES: Set<string>;
+/**
+ * Protocol-managed claims that must never be overridden by `getOidcClaims()`.
+ */
+export declare const RESERVED_OIDC_CLAIMS: Set<string>;
+/**
+ * Interface for User models that provide OIDC claims.
+ * Implement this on your User model to include custom claims
+ * in id_tokens and /userinfo responses.
+ *
+ * If not implemented, only protocol-level claims (sub, iss, aud, exp, iat)
+ * are included.
+ */
+export interface OidcSubject {
+    getOidcClaims(scopes: Scope[]): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+/**
+ * Collect OIDC claims based on the granted scopes.
+ *
+ * Maps each scope to its corresponding claims object and merges
+ * only the claims for scopes present in the granted set.
+ *
+ * @example
+ * ```ts
+ * getOidcClaims(scopes: Scope[]) {
+ *   return collectOidcClaims(scopes, {
+ *     profile: { name: this.fullName },
+ *     email: { email: this.email },
+ *   })
+ * }
+ * ```
+ */
+export declare function collectOidcClaims(scopes: Scope[], claimsMap: Partial<Record<Scope, Record<string, unknown>>>): Record<string, unknown>;
 /**
  * Supported OAuth 2.1 grant types.
  *
@@ -50,6 +101,39 @@ export declare const BUILTIN_SCOPES: Set<string>;
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
  */
 export type GrantType = 'authorization_code' | 'refresh_token' | 'client_credentials';
+/**
+ * Options for creating an OAuth client programmatically.
+ */
+export interface CreateClientOptions {
+    name: string;
+    redirectUris: string[];
+    scopes?: string[];
+    grantTypes?: GrantType[];
+    isPublic?: boolean;
+    requirePkce?: boolean;
+    userId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for updating an existing OAuth client.
+ */
+export interface UpdateClientOptions {
+    name?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+    grantTypes?: GrantType[];
+    isDisabled?: boolean;
+    requirePkce?: boolean;
+    metadata?: Record<string, any>;
+}
+/**
+ * Result returned when creating a client.
+ * Includes the raw secret (only available at creation time).
+ */
+export interface CreateClientResult {
+    client: import('./models/oauth_client.ts').OAuthClient;
+    clientSecret: string | null;
+}
 /**
  * User-facing configuration interface for Sésame.
  *
@@ -91,6 +175,18 @@ export interface SesameConfig {
      * Defaults to '30d'.
      */
     refreshTokenTtl?: string;
+    /**
+     * Grace period (in seconds) during which a recently-rotated
+     * refresh token is still accepted instead of triggering
+     * replay-attack detection. Handles race conditions in
+     * multi-process clients (e.g. MCP SDK).
+     *
+     * Set to `0` to disable (strict rotation, no grace period).
+     * Defaults to `120` (2 minutes).
+     *
+     * @see https://auth0.com/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation
+     */
+    refreshTokenRotationGracePeriod?: number;
     /**
      * Access token TTL for the client_credentials grant (M2M).
      * Defaults to `accessTokenTtl`.
@@ -133,6 +229,27 @@ export interface SesameConfig {
      * Defaults to `false`.
      */
     allowPublicRegistration?: boolean;
+    /**
+     * JWK (JSON Web Key) for signing ID tokens.
+     * Must be an RSA private key in JWK format.
+     * Required together with `oidcProvider` when OIDC scopes (openid) are used.
+     * Passed via env var, parsed at boot, lives in memory.
+     */
+    jwk?: JWK;
+    /**
+     * User provider used by OIDC flows to resolve the subject for
+     * `id_token` emission and `/userinfo`.
+     *
+     * This is independent from `@adonisjs/auth` guards. The provider is
+     * configured once for the authorization server and must be stable for
+     * the issuer. Required together with `jwk` to enable OIDC.
+     */
+    oidcProvider?: OAuthUserProviderContract<unknown>;
+    /**
+     * ID token TTL as a string duration (e.g. '1h', '10m').
+     * Defaults to '1h'.
+     */
+    idTokenTtl?: string;
 }
 /**
  * Fully resolved configuration with defaults applied.
@@ -146,12 +263,16 @@ export interface ResolvedSesameConfig {
     accessTokenTtl: string;
     clientCredentialsAccessTokenTtl: string;
     refreshTokenTtl: string;
+    refreshTokenRotationGracePeriod: number;
     authorizationCodeTtl: string;
     authorizationRequestTtl: string;
     loginPage: string | ((ctx: HttpContext, params: URLSearchParams) => string);
     consentPage: string | ((ctx: HttpContext, params: URLSearchParams) => string);
     allowDynamicRegistration: boolean;
     allowPublicRegistration: boolean;
+    jwk?: JWK;
+    oidcProvider?: OAuthUserProviderContract<unknown>;
+    idTokenTtl: string;
 }
 /**
  * OAuth 2.0 Authorization Server Metadata as defined by RFC 8414.

package/build/stubs/main.ts

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export const stubsRoot = import.meta.dirname

package/build/stubs/migrations/create_oauth_authorization_codes_table.stub

@@ -15,6 +15,7 @@ export default class extends BaseSchema {
       table.text('redirect_uri').notNullable()
       table.string('code_challenge').nullable()
       table.string('code_challenge_method').nullable()
+      table.string('nonce').nullable()
       table.timestamp('expires_at').notNullable()
       table.timestamp('created_at').notNullable()
       table.timestamp('updated_at').notNullable()

package/build/stubs/migrations/create_oauth_pending_authorization_requests_table.stub

@@ -21,6 +21,7 @@ export default class extends BaseSchema {
       table.string('state').nullable()
       table.string('code_challenge').nullable()
       table.string('code_challenge_method').nullable()
+      table.string('nonce').nullable()
       table.timestamp('expires_at').notNullable()
       table.timestamp('created_at').notNullable()
     })

package/build/stubs/migrations/create_oauth_refresh_tokens_table.stub

@@ -9,7 +9,7 @@ export default class extends BaseSchema {
     this.schema.createTable(this.tableName, (table) => {
       table.uuid('id').primary()
       table.string('token').notNullable().index()
-      table.string('access_token_id').notNullable()
+      table.uuid('access_token_id').notNullable()
       table.string('client_id').notNullable().references('client_id').inTable('oauth_clients').onDelete('CASCADE')
       table.string('user_id').notNullable()
       table.json('scopes').notNullable()