@adonis-agora/authkit-client 0.18.9 → 0.19.0

package/build/index.d.ts

@@ -1,13 +1,16 @@
 export type { Identity } from '@adonis-agora/authkit-core';
 export { configure } from './commands/configure.js';
+export type { AuthkitClientLogger, AuthkitClientManagerDeps, } from './providers/authkit_client_provider.js';
 export { AuthkitClientManager } from './providers/authkit_client_provider.js';
 export { Authenticator } from './src/authenticator.js';
+export type { AuthorizationRequest, CompleteAuthorizationParams, CompletedAuthorization, CreateAuthorizationRequestParams, OidcCallbackErrorCode, PendingAuthorization, } from './src/authorization.js';
+export { completeAuthorization, createAuthorizationRequest, OidcCallbackError, } from './src/authorization.js';
 export type { SessionIndex, SessionIndexEntry, ValidatedLogoutToken, ValidateLogoutTokenOptions, } from './src/backchannel_logout.js';
 export { BACKCHANNEL_LOGOUT_EVENT, InMemorySessionIndex, InvalidLogoutTokenError, validateLogoutToken, } from './src/backchannel_logout.js';
 export type { BackchannelLogoutCallback, BackchannelLogoutInput, ClientConfigInput, ResolvedClientConfig, } from './src/define_config.js';
 export { defineConfig, resolvers } from './src/define_config.js';
 export type { DiscoverOptions, OidcEndpoints } from './src/discovery.js';
-export { conventionEndpoints, discoverEndpoints } from './src/discovery.js';
+export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
 export type { CreateDpopProofInput, DpopKeyPair } from './src/dpop.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
 export type { UnauthorizedAccessConstructor } from './src/host/authkit_client_guard.js';
@@ -17,13 +20,16 @@ export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin,
 export { getAuthkit } from './src/host/request_authenticator.js';
 export type { ResiliencePolicy } from './src/http/resilient_fetch.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';
+export type { IdTokenClaims, ValidateIdTokenOptions } from './src/id_token.js';
+export { InvalidIdTokenError, validateIdToken } from './src/id_token.js';
+export { clearJwksCache } from './src/jwks.js';
 export type { LucidMirrorOptions } from './src/lucid_mirror.js';
 export { lucidMirror } from './src/lucid_mirror.js';
 export { default as AuthkitContextMiddleware } from './src/middleware/authkit_context_middleware.js';
 export { default as BackchannelRevocationMiddleware } from './src/middleware/backchannel_revocation_middleware.js';
 export type { RequireOrgMiddlewareOptions } from './src/middleware/require_org_middleware.js';
 export { default as RequireOrgMiddleware } from './src/middleware/require_org_middleware.js';
-export type { EndSessionParams, RefreshParams } from './src/oidc_login.js';
+export type { AuthorizeParams, EndSessionParams, ExchangeParams, RefreshParams, } from './src/oidc_login.js';
 export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, generatePkce, refreshTokens, } from './src/oidc_login.js';
 export type { PostLoginRedirects, RegisterOidcClientOptions, } from './src/register_oidc_client.js';
 export { registerOidcClient } from './src/register_oidc_client.js';
@@ -33,4 +39,4 @@ export type { TokenSet } from './src/types.js';
 export type { ClaimsUser, ResolveUserContext, UserinfoResolverOptions, } from './src/user_resolvers.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';
 export type { JwtAccessTokenClaims, VerifyJwtAccessTokenOptions, } from './src/verify_access_token.js';
-export { clearJwksCache, verifyJwtAccessToken, } from './src/verify_access_token.js';
+export { verifyJwtAccessToken } from './src/verify_access_token.js';

package/build/index.js

@@ -1,14 +1,17 @@
 export { configure } from './commands/configure.js';
 export { AuthkitClientManager } from './providers/authkit_client_provider.js';
 export { Authenticator } from './src/authenticator.js';
+export { completeAuthorization, createAuthorizationRequest, OidcCallbackError, } from './src/authorization.js';
 export { BACKCHANNEL_LOGOUT_EVENT, InMemorySessionIndex, InvalidLogoutTokenError, validateLogoutToken, } from './src/backchannel_logout.js';
 export { defineConfig, resolvers } from './src/define_config.js';
-export { conventionEndpoints, discoverEndpoints } from './src/discovery.js';
+export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
 export { AuthkitClientGuard, authkitClientGuard } from './src/host/authkit_client_guard.js';
 export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
 export { getAuthkit } from './src/host/request_authenticator.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';
+export { InvalidIdTokenError, validateIdToken } from './src/id_token.js';
+export { clearJwksCache } from './src/jwks.js';
 export { lucidMirror } from './src/lucid_mirror.js';
 export { default as AuthkitContextMiddleware } from './src/middleware/authkit_context_middleware.js';
 export { default as BackchannelRevocationMiddleware } from './src/middleware/backchannel_revocation_middleware.js';
@@ -17,4 +20,4 @@ export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, gen
 export { registerOidcClient } from './src/register_oidc_client.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';
-export { clearJwksCache, verifyJwtAccessToken, } from './src/verify_access_token.js';
+export { verifyJwtAccessToken } from './src/verify_access_token.js';

package/build/providers/authkit_client_provider.d.ts

@@ -1,18 +1,70 @@
 import '../container_bindings.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
+import { type JWTVerifyGetKey } from 'jose';
 import { Authenticator } from '../src/authenticator.js';
+import { type AuthorizationRequest, type CompleteAuthorizationParams, type CompletedAuthorization, type CreateAuthorizationRequestParams } from '../src/authorization.js';
 import type { ResolvedClientConfig } from '../src/define_config.js';
+import { type OidcEndpoints } from '../src/discovery.js';
+import { type IdTokenClaims, type ValidateIdTokenOptions } from '../src/id_token.js';
 import type { TokenSet } from '../src/types.js';
 /** Deps injetáveis (relógio/fetch) para testar `maybeRefresh` sem rede/tempo real. */
 export interface RefreshDeps {
     now?: () => number;
     fetchImpl?: typeof fetch;
 }
+/** The slice of the AdonisJS logger the manager uses. */
+export interface AuthkitClientLogger {
+    warn(obj: object, msg: string): void;
+}
+export interface AuthkitClientManagerDeps {
+    /** Where best-effort failures (refresh, logout without end_session) are reported. */
+    logger?: AuthkitClientLogger;
+    /** fetch used for discovery (tests). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Key function for id_token and logout_token signatures, replacing the
+     * discovered `jwks_uri` (tests, or a JWKS shipped with the app).
+     */
+    keys?: JWTVerifyGetKey;
+}
 export declare class AuthkitClientManager {
     #private;
     private config;
-    constructor(config: ResolvedClientConfig);
+    private deps;
+    constructor(config: ResolvedClientConfig, deps?: AuthkitClientManagerDeps);
+    /**
+     * The IdP endpoints this client talks to: discovered from
+     * `{issuer}/.well-known/openid-configuration` (cached, 15 min by default) with
+     * the config's `endpoints` overrides applied on top. With `discovery: false`,
+     * the authkit-server convention plus the overrides — no network.
+     *
+     * Throws `OidcDiscoveryError` when discovery fails and nothing was discovered
+     * before; the next call retries.
+     */
+    endpoints(): Promise<OidcEndpoints>;
+    /**
+     * Starts a login: authorize URL with fresh `state`, `nonce` and PKCE, built from
+     * this client's config and endpoints. Store `pending` in the session and pass it
+     * to {@link completeAuthorization} in the callback.
+     *
+     * ```ts
+     * const { url, pending } = await authkit.createAuthorizationRequest({ extraParams: { prompt: 'login' } })
+     * session.put('oidc_pending', pending)
+     * return response.redirect(url)
+     * ```
+     */
+    createAuthorizationRequest(options?: Partial<Pick<CreateAuthorizationRequestParams, 'scopes' | 'extraParams' | 'maxAge'>>): Promise<AuthorizationRequest>;
+    /**
+     * Finishes a login: checks `state`/`iss`, exchanges the code and validates the
+     * id_token (`nonce` included). Does NOT touch the session — call
+     * {@link startSession} with the returned `tokens`.
+     *
+     * Throws `OidcCallbackError`; `error.restartable` means "send them back to login".
+     */
+    completeAuthorization(params: Pick<CompleteAuthorizationParams, 'pending' | 'callbackParams'>): Promise<CompletedAuthorization>;
+    /** Validates an id_token issued to this client (issuer, client_id and keys filled in). */
+    validateIdToken(idToken: string, options?: Omit<ValidateIdTokenOptions, 'issuer' | 'clientId' | 'jwksUri' | 'keys'>): Promise<IdTokenClaims>;
     get clientConfig(): ResolvedClientConfig;
     /**
      * Lê o id_token armazenado no token set da sessão. Usado pelo logout federado
@@ -21,12 +73,8 @@ export declare class AuthkitClientManager {
     getIdToken(ctx: HttpContext): string | undefined;
     /**
      * Renova o TokenSet da sessão proativamente se o access token estiver perto de
-     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token. Persiste o TokenSet
-     * renovado — incluindo o refresh_token ROTACIONADO — de volta na sessão. Preserva
-     * o id_token / refresh_token anteriores quando o IdP não os reemite.
-     *
-     * Preserva TAMBÉM o `impersonationBinding`: renovar o token do alvo não muda a
-     * sessão, então não pode invalidar o vínculo e trancar o ator na impersonação.
+     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token, e persiste o resultado
+     * de {@link #renew} — incluindo o refresh_token ROTACIONADO — de volta na sessão.
      *
      * Dedup por sessionId: requests concorrentes da mesma sessão (ex.: autosave + vários
      * GETs chegando juntos quando o access token vence) disparam UM refresh só. Quem
@@ -35,8 +83,8 @@ export declare class AuthkitClientManager {
      * com o access token vencido (→ 401) e com o refresh token antigo, já invalidado
      * pela rotação, que ele poderia gravar de volta e envenenar a sessão.
      *
-     * Best-effort: qualquer falha (token revogado, IdP fora) é silenciosa — o resolver
-     * lida com a sessão expirada no fluxo normal. Chamado pelo middleware por request.
+     * Best-effort: uma falha (token revogado, IdP fora) vai para o logger e não lança —
+     * o resolver lida com a sessão expirada no fluxo normal. Chamado pelo middleware.
      */
     maybeRefresh(ctx: HttpContext, deps?: RefreshDeps): Promise<void>;
     /**

package/build/providers/authkit_client_provider.js

@@ -4,8 +4,13 @@ import '../container_bindings.js';
 import { randomUUID } from 'node:crypto';
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
+import { decodeJwt } from 'jose';
 import { Authenticator } from '../src/authenticator.js';
+import { completeAuthorization, createAuthorizationRequest, } from '../src/authorization.js';
 import { validateLogoutToken } from '../src/backchannel_logout.js';
+import { conventionEndpoints, discoverEndpoints, mergeEndpoints, } from '../src/discovery.js';
+import { validateIdToken, } from '../src/id_token.js';
+import { getJwks } from '../src/jwks.js';
 import { exchangeToken, refreshTokens } from '../src/oidc_login.js';
 /** Margem (ms) antes do `expiresAt` em que o access token é renovado proativamente. */
 const REFRESH_SKEW_MS = 60_000;
@@ -22,6 +27,7 @@ function readParked(value) {
 }
 export class AuthkitClientManager {
     config;
+    deps;
     #resolverCache;
     /**
      * Refreshes in-flight por sessionId (dedup thundering herd). A promise resolve com o
@@ -29,8 +35,11 @@ export class AuthkitClientManager {
      * o refresh token de origem, pra quem espera saber se é da mesma linhagem.
      */
     #refreshPromises = new Map();
-    constructor(config) {
+    #logger;
+    constructor(config, deps = {}) {
         this.config = config;
+        this.deps = deps;
+        this.#logger = deps.logger ?? { warn: () => { } };
     }
     async #getResolver() {
         if (!this.#resolverCache) {
@@ -40,10 +49,90 @@ export class AuthkitClientManager {
                 clientSecret: this.config.clientSecret,
                 sessionKey: this.config.sessionKey,
                 globalRolesClaim: this.config.globalRolesClaim,
+                endpoints: () => this.endpoints(),
+                logger: this.#logger,
             });
         }
         return this.#resolverCache;
     }
+    /**
+     * The IdP endpoints this client talks to: discovered from
+     * `{issuer}/.well-known/openid-configuration` (cached, 15 min by default) with
+     * the config's `endpoints` overrides applied on top. With `discovery: false`,
+     * the authkit-server convention plus the overrides — no network.
+     *
+     * Throws `OidcDiscoveryError` when discovery fails and nothing was discovered
+     * before; the next call retries.
+     */
+    async endpoints() {
+        const { discovery, endpoints: overrides, issuer } = this.config;
+        if (discovery === false)
+            return mergeEndpoints(conventionEndpoints(issuer), overrides);
+        return discoverEndpoints(issuer, {
+            overrides,
+            cacheTtlMs: discovery.cacheTtlMs,
+            resilience: this.config.resilience,
+            fetchImpl: this.deps.fetchImpl,
+            onError: 'throw',
+        });
+    }
+    /** {@link endpoints} plus the key function every token signature is checked with. */
+    async #idp() {
+        const endpoints = await this.endpoints();
+        return { endpoints, keys: this.deps.keys ?? getJwks(endpoints.jwksUri) };
+    }
+    /**
+     * Starts a login: authorize URL with fresh `state`, `nonce` and PKCE, built from
+     * this client's config and endpoints. Store `pending` in the session and pass it
+     * to {@link completeAuthorization} in the callback.
+     *
+     * ```ts
+     * const { url, pending } = await authkit.createAuthorizationRequest({ extraParams: { prompt: 'login' } })
+     * session.put('oidc_pending', pending)
+     * return response.redirect(url)
+     * ```
+     */
+    async createAuthorizationRequest(options = {}) {
+        return createAuthorizationRequest({
+            issuer: this.config.issuer,
+            clientId: this.config.clientId,
+            redirectUri: this.config.redirectUri,
+            scopes: options.scopes ?? this.config.scopes,
+            extraParams: options.extraParams,
+            maxAge: options.maxAge,
+            endpoints: await this.endpoints(),
+        });
+    }
+    /**
+     * Finishes a login: checks `state`/`iss`, exchanges the code and validates the
+     * id_token (`nonce` included). Does NOT touch the session — call
+     * {@link startSession} with the returned `tokens`.
+     *
+     * Throws `OidcCallbackError`; `error.restartable` means "send them back to login".
+     */
+    async completeAuthorization(params) {
+        const { endpoints, keys } = await this.#idp();
+        return completeAuthorization({
+            ...params,
+            issuer: this.config.issuer,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            redirectUri: this.config.redirectUri,
+            endpoints,
+            idToken: { keys },
+            resilience: this.config.resilience,
+        });
+    }
+    /** Validates an id_token issued to this client (issuer, client_id and keys filled in). */
+    async validateIdToken(idToken, options = {}) {
+        const { endpoints, keys } = await this.#idp();
+        return validateIdToken(idToken, {
+            ...options,
+            issuer: endpoints.issuer,
+            clientId: this.config.clientId,
+            keys,
+        });
+    }
     get clientConfig() {
         return this.config;
     }
@@ -57,12 +146,8 @@ export class AuthkitClientManager {
     }
     /**
      * Renova o TokenSet da sessão proativamente se o access token estiver perto de
-     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token. Persiste o TokenSet
-     * renovado — incluindo o refresh_token ROTACIONADO — de volta na sessão. Preserva
-     * o id_token / refresh_token anteriores quando o IdP não os reemite.
-     *
-     * Preserva TAMBÉM o `impersonationBinding`: renovar o token do alvo não muda a
-     * sessão, então não pode invalidar o vínculo e trancar o ator na impersonação.
+     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token, e persiste o resultado
+     * de {@link #renew} — incluindo o refresh_token ROTACIONADO — de volta na sessão.
      *
      * Dedup por sessionId: requests concorrentes da mesma sessão (ex.: autosave + vários
      * GETs chegando juntos quando o access token vence) disparam UM refresh só. Quem
@@ -71,15 +156,16 @@ export class AuthkitClientManager {
      * com o access token vencido (→ 401) e com o refresh token antigo, já invalidado
      * pela rotação, que ele poderia gravar de volta e envenenar a sessão.
      *
-     * Best-effort: qualquer falha (token revogado, IdP fora) é silenciosa — o resolver
-     * lida com a sessão expirada no fluxo normal. Chamado pelo middleware por request.
+     * Best-effort: uma falha (token revogado, IdP fora) vai para o logger e não lança —
+     * o resolver lida com a sessão expirada no fluxo normal. Chamado pelo middleware.
      */
     async maybeRefresh(ctx, deps = {}) {
         const session = ctx.session;
         if (!session)
             return;
         const tokenSet = session.get(this.config.sessionKey);
-        if (!tokenSet?.refreshToken)
+        const refreshToken = tokenSet?.refreshToken;
+        if (!tokenSet || !refreshToken)
             return;
         const now = deps.now ?? Date.now;
         // Sem expiresAt conhecido, não renova proativamente (evita refresh a cada request).
@@ -94,7 +180,7 @@ export class AuthkitClientManager {
             // Só aproveita o refresh in-flight se ele partiu do MESMO refresh token que esta
             // request tem — senão o TokenSet renovado é de outra linhagem (ex.: a sessão
             // trocou de token set no meio do caminho) e não pode ser gravado aqui.
-            if (inFlight && inFlight.refreshToken === tokenSet.refreshToken) {
+            if (inFlight && inFlight.refreshToken === refreshToken) {
                 const refreshed = await inFlight.promise;
                 if (refreshed) {
                     session.put(this.config.sessionKey, {
@@ -111,31 +197,22 @@ export class AuthkitClientManager {
         }
         // Promise que NUNCA rejeita: resolve com o TokenSet gravado, ou `null` se a
         // renovação falhou — aí o TokenSet original fica como está (o resolver decide).
-        const promise = refreshTokens({
-            issuer: this.config.issuer,
-            clientId: this.config.clientId,
-            clientSecret: this.config.clientSecret,
-            refreshToken: tokenSet.refreshToken,
-            fetchImpl: deps.fetchImpl,
-            resilience: this.config.resilience,
-        })
-            .then((next) => {
-            const merged = {
-                idToken: next.idToken || tokenSet.idToken,
-                accessToken: next.accessToken,
-                refreshToken: next.refreshToken ?? tokenSet.refreshToken,
-                expiresAt: next.expiresAt,
-                impersonationBinding: tokenSet.impersonationBinding,
-            };
-            session.put(this.config.sessionKey, merged);
-            return merged;
+        const promise = this.#renew(tokenSet, refreshToken, deps)
+            .then((renewed) => {
+            session.put(this.config.sessionKey, renewed);
+            return renewed;
         })
-            .catch(() => null);
+            .catch((error) => {
+            // Still best-effort — the resolver handles the expired session — but no
+            // longer silent: a misconfigured token endpoint used to fail here forever.
+            this.#logger.warn({ err: error, issuer: this.config.issuer }, 'authkit-client: token refresh failed; keeping the current token set');
+            return null;
+        });
         if (!sessionId) {
             await promise;
             return;
         }
-        const entry = { refreshToken: tokenSet.refreshToken, promise };
+        const entry = { refreshToken, promise };
         this.#refreshPromises.set(sessionId, entry);
         try {
             await promise;
@@ -146,6 +223,41 @@ export class AuthkitClientManager {
                 this.#refreshPromises.delete(sessionId);
         }
     }
+    /**
+     * Um refresh: tokens novos do IdP, id_token reemitido validado, mesclados sobre
+     * `tokenSet`. Preserva o id_token / refresh_token anteriores quando o IdP não os
+     * reemite, e TAMBÉM o `impersonationBinding`: renovar o token do alvo não muda a
+     * sessão, então não pode invalidar o vínculo e trancar o ator na impersonação.
+     */
+    async #renew(tokenSet, refreshToken, deps) {
+        const { endpoints, keys } = await this.#idp();
+        const next = await refreshTokens({
+            issuer: this.config.issuer,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            refreshToken,
+            tokenEndpoint: endpoints.tokenEndpoint,
+            fetchImpl: deps.fetchImpl,
+            resilience: this.config.resilience,
+        });
+        // OIDC Core §12.2: a re-issued id_token must be valid and about the same
+        // end-user. No nonce here — none is sent on refresh.
+        if (next.idToken) {
+            await validateIdToken(next.idToken, {
+                issuer: endpoints.issuer,
+                clientId: this.config.clientId,
+                keys,
+                subject: subjectOf(tokenSet.idToken),
+            });
+        }
+        return {
+            idToken: next.idToken || tokenSet.idToken,
+            accessToken: next.accessToken,
+            refreshToken: next.refreshToken ?? refreshToken,
+            expiresAt: next.expiresAt,
+            impersonationBinding: tokenSet.impersonationBinding,
+        };
+    }
     /**
      * Recebe o POST `application/x-www-form-urlencoded` de OIDC Back-Channel Logout. Lê o
      * `logout_token` do body, valida (assinatura + regras do spec), consulta o SessionIndex
@@ -161,11 +273,21 @@ export class AuthkitClientManager {
         if (!token || typeof token !== 'string') {
             return response.badRequest({ error: 'invalid_request' });
         }
+        let idp;
+        try {
+            idp = await this.#idp();
+        }
+        catch (error) {
+            // Not the token's fault: tell the OP to retry instead of rejecting it.
+            this.#logger.warn({ err: error, issuer: this.config.issuer }, 'authkit-client: back-channel logout received while discovery is failing');
+            return response.status(503).send({ error: 'temporarily_unavailable' });
+        }
         let validated;
         try {
             validated = await validateLogoutToken(token, {
-                issuer: this.config.issuer,
+                issuer: idp.endpoints.issuer,
                 clientId: this.config.clientId,
+                keys: idp.keys,
             });
         }
         catch {
@@ -210,6 +332,7 @@ export class AuthkitClientManager {
             clientSecret: this.config.clientSecret,
             subjectToken: current.accessToken,
             requestedSubject,
+            tokenEndpoint: (await this.endpoints()).tokenEndpoint,
             resilience: this.config.resilience,
         });
         // Vínculo: o mesmo nonce nos dois lados. O lado ATIVO mora dentro do token set
@@ -339,13 +462,29 @@ export default class AuthkitClientProvider {
         this.app = app;
     }
     register() {
-        this.app.container.singleton('authkit.client', async () => {
+        // Bound by class, like the first-party packages do, so `@inject()` works with
+        // `AuthkitClientManager` as a constructor type. The string key stays as an alias.
+        this.app.container.singleton(AuthkitClientManager, async (resolver) => {
             const value = this.app.config.get('authkit_client');
             const config = (await configProvider.resolve(this.app, value));
             if (!config) {
                 throw new RuntimeException('Config inválido em "config/authkit_client.ts". Use defineConfig de @adonis-agora/authkit-client.');
             }
-            return new AuthkitClientManager(config);
+            const logger = await resolver.make('logger');
+            return new AuthkitClientManager(config, { logger });
         });
+        this.app.container.alias('authkit.client', AuthkitClientManager);
+    }
+}
+/** `sub` of a stored id_token, or undefined when there is none / it is unreadable. */
+function subjectOf(idToken) {
+    if (!idToken)
+        return undefined;
+    try {
+        const sub = decodeJwt(idToken).sub;
+        return typeof sub === 'string' ? sub : undefined;
+    }
+    catch {
+        return undefined;
     }
 }

package/build/src/authorization.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Authorization-code flow in two calls: one to start it, one to finish it.
+ *
+ * `buildAuthorizeUrl` + `exchangeCode` are the raw steps; these two wrap them
+ * with everything a callback must check and is easy to forget — `state`, the
+ * RFC 9207 `iss` parameter, PKCE and the id_token (signature, `aud`, `nonce`…).
+ *
+ * ```ts
+ * const { url, pending } = await createAuthorizationRequest({ issuer, clientId, redirectUri, scopes, endpoints })
+ * session.put('oidc_pending', pending)
+ * // ...IdP redirects back...
+ * const { tokens, claims } = await completeAuthorization({
+ *   issuer, clientId, clientSecret, redirectUri, endpoints,
+ *   pending: session.pull('oidc_pending'),
+ *   callbackParams: request.qs(),
+ * })
+ * ```
+ *
+ * Inside an AdonisJS app, prefer the `AuthkitClientManager` methods of the same
+ * name — they fill the config and the discovered endpoints in for you.
+ */
+import { type OidcEndpoints } from './discovery.js';
+import type { ResiliencePolicy } from './http/resilient_fetch.js';
+import { type IdTokenClaims, type ValidateIdTokenOptions } from './id_token.js';
+import type { TokenSet } from './types.js';
+/**
+ * What the app keeps (in the session) between the redirect to the IdP and the
+ * callback. Plain JSON — safe to store in any session driver.
+ */
+export interface PendingAuthorization {
+    state: string;
+    nonce: string;
+    codeVerifier: string;
+    /** `max_age` sent in the request, if any — re-checked against `auth_time`. */
+    maxAge?: number;
+}
+export interface CreateAuthorizationRequestParams {
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    scopes: string[];
+    /** Discovered endpoints. Without them, the authkit-server convention is used. */
+    endpoints?: Pick<OidcEndpoints, 'authorizationEndpoint'>;
+    /** Extra authorize parameters (`prompt`, `login_hint`, `audience`, `ui_locales`…). */
+    extraParams?: Record<string, string | number | undefined | null>;
+    /** OIDC `max_age` in seconds; the callback then requires a fresh enough `auth_time`. */
+    maxAge?: number;
+}
+export interface AuthorizationRequest {
+    /** Where to redirect the browser. */
+    url: string;
+    /** Store this until the callback, then pass it to `completeAuthorization`. */
+    pending: PendingAuthorization;
+}
+/** Builds the authorize URL with fresh `state`, `nonce` and PKCE (S256). */
+export declare function createAuthorizationRequest(p: CreateAuthorizationRequestParams): Promise<AuthorizationRequest>;
+/** Why a callback was rejected. */
+export type OidcCallbackErrorCode = 
+/** No pending authorization in the session (expired, or a stale/forged callback). */
+'missing_pending'
+/** `state` does not match the pending authorization. */
+ | 'state_mismatch'
+/** RFC 9207 `iss` parameter present and not the expected issuer (mix-up attack). */
+ | 'issuer_mismatch'
+/** The IdP redirected back with `error` (e.g. `access_denied`, `login_required`). */
+ | 'idp_error'
+/** No `code` in the callback. */
+ | 'missing_code'
+/** Token endpoint call failed. */
+ | 'token_exchange_failed'
+/** Token endpoint answered without an id_token (was `openid` in the scopes?). */
+ | 'missing_id_token'
+/** id_token failed validation — see `cause`. */
+ | 'invalid_id_token';
+export declare class OidcCallbackError extends Error {
+    readonly code: OidcCallbackErrorCode;
+    constructor(code: OidcCallbackErrorCode, message: string, options?: {
+        cause?: unknown;
+        /** `error` / `error_description` sent by the IdP, for `idp_error`. */
+        idpError?: {
+            error: string;
+            description?: string;
+        };
+    });
+    readonly idpError?: {
+        error: string;
+        description?: string;
+    };
+    /**
+     * True when the right answer is to send the user back to login: the callback is
+     * stale or did not belong to this browser, or the IdP sent the user back with an
+     * error (`access_denied`, `login_required`…; see `idpError` to tell them apart).
+     * False for real failures — a mix-up, a failed token exchange or id_token check.
+     */
+    get restartable(): boolean;
+}
+export interface CompleteAuthorizationParams {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    /** Discovered endpoints. Without them, the authkit-server convention is used. */
+    endpoints?: Pick<OidcEndpoints, 'issuer' | 'tokenEndpoint' | 'jwksUri'>;
+    /** What `createAuthorizationRequest` returned in `pending`. */
+    pending: PendingAuthorization | null | undefined;
+    /** The callback query string (`request.qs()`). */
+    callbackParams: Record<string, unknown>;
+    /** Overrides for the id_token check (keys in tests, clock tolerance…). */
+    idToken?: Pick<ValidateIdTokenOptions, 'keys' | 'algorithms' | 'clockTolerance' | 'currentDate'>;
+    fetchImpl?: typeof fetch;
+    resilience?: ResiliencePolicy;
+}
+export interface CompletedAuthorization {
+    tokens: TokenSet;
+    /** Validated id_token claims. */
+    claims: IdTokenClaims;
+}
+/**
+ * Finishes the authorization-code flow: checks `state` and `iss`, exchanges the
+ * code (with the PKCE verifier) and validates the id_token, `nonce` included.
+ *
+ * Throws {@link OidcCallbackError}; `error.restartable` tells "send the user back
+ * to login" from a real failure.
+ */
+export declare function completeAuthorization(p: CompleteAuthorizationParams): Promise<CompletedAuthorization>;