@adonis-agora/authkit-server 0.34.0

package/build/src/pat/pat_tokens.js

@@ -0,0 +1,9 @@
+import { createHash, randomBytes } from 'node:crypto';
+/** Gera um Personal Access Token opaco no formato `pat_<base64url>`. */
+export function generatePatToken() {
+    return 'pat_' + randomBytes(32).toString('base64url');
+}
+/** SHA-256 (hex) do token — é o que se persiste; o token cru nunca é guardado. */
+export function hashPatToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}

package/build/src/provider/build_provider.d.ts

@@ -0,0 +1,45 @@
+import * as oidc from 'oidc-provider';
+import type { ResolvedServerConfig } from '../define_config.js';
+export interface BuildProviderOptions {
+    /** APP_KEY do consumidor; usado p/ derivar cookies.keys se não houver. */
+    appKey: string;
+    findAccount: (ctx: any, sub: string, token?: any) => Promise<any>;
+}
+/**
+ * Holder mutável dos TTLs de sessão OIDC. Lido de forma SÍNCRONA pelo TTL function do
+ * oidc-provider (que não aceita async). Atualizado assincronamente após write/reset
+ * da setting `session_policy` via `updateSessionTtlHolder`.
+ *
+ * Valores em SEGUNDOS. `rememberSec` é o TTL da sessão persistente (remember-me ON).
+ * `transientSec` é o TTL da sessão transiente (remember-me OFF ou rememberEnabled=false).
+ */
+export interface SessionTtlHolder {
+    /** TTL da sessão persistente (remember-me ON). Segundos. */
+    rememberSec: number;
+    /** TTL da sessão transiente (browser session). Segundos. */
+    transientSec: number;
+}
+/** Atualiza o holder mutável do TTL de sessão com os valores da setting. */
+export declare function updateSessionTtlHolder(holder: SessionTtlHolder, policy: {
+    rememberDays: number;
+    defaultSessionHours: number;
+}): void;
+/**
+ * Holder mutável dos TTLs de access/id/refresh tokens OIDC. Lido de forma
+ * SÍNCRONA pelo TTL function do oidc-provider. Atualizado assincronamente após
+ * write/reset da setting `token_ttl` via `updateTokenTtlHolder`.
+ *
+ * Valores em SEGUNDOS.
+ */
+export interface TokenTtlHolder {
+    accessTokenSec: number;
+    idTokenSec: number;
+    refreshTokenSec: number;
+}
+/** Atualiza o holder mutável de TTL de tokens com os valores da setting. */
+export declare function updateTokenTtlHolder(holder: TokenTtlHolder, ttl: {
+    accessTokenSec: number;
+    idTokenSec: number;
+    refreshTokenSec: number;
+}): void;
+export declare function buildProvider(config: ResolvedServerConfig, options: BuildProviderOptions, sessionTtlHolder?: SessionTtlHolder, tokenTtlHolder?: TokenTtlHolder): oidc.Provider;

package/build/src/provider/build_provider.js

@@ -0,0 +1,219 @@
+import * as oidc from 'oidc-provider';
+import { createDeviceSources } from './device_sources.js';
+import { createLogoutSources } from './logout_sources.js';
+/** Atualiza o holder mutável do TTL de sessão com os valores da setting. */
+export function updateSessionTtlHolder(holder, policy) {
+    holder.rememberSec = Math.max(1, Math.floor(policy.rememberDays * 86400));
+    holder.transientSec = Math.max(1, Math.floor(policy.defaultSessionHours * 3600));
+}
+/** Atualiza o holder mutável de TTL de tokens com os valores da setting. */
+export function updateTokenTtlHolder(holder, ttl) {
+    holder.accessTokenSec = Math.max(1, ttl.accessTokenSec);
+    holder.idTokenSec = Math.max(1, ttl.idTokenSec);
+    holder.refreshTokenSec = Math.max(1, ttl.refreshTokenSec);
+}
+export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder) {
+    const cookieKeys = config.cookieKeys.length ? config.cookieKeys : [options.appKey];
+    // OIDC Dynamic Client Registration (RFC 7591/7592). Só montamos as chaves de feature
+    // quando habilitado — desligado (default), o oidc-provider não expõe o endpoint /reg.
+    // O `initialAccessToken`: string => valida o bearer contra esse valor estático; ausente
+    // => `false` (registro ABERTO; raramente desejável em prod). Clients registrados aqui
+    // são persistidos automaticamente pelo MESMO AdapterClass, coexistindo com os estáticos.
+    const dynReg = config.dynamicRegistration;
+    const registrationFeatures = dynReg.enabled
+        ? {
+            registration: {
+                enabled: true,
+                initialAccessToken: dynReg.initialAccessToken ?? false,
+            },
+            ...(dynReg.management ? { registrationManagement: { enabled: true } } : {}),
+        }
+        : {};
+    // Device Authorization Grant (RFC 8628). Quando ligado, montamos a feature com
+    // as três sources de UI i18n-izadas (entrada/confirmação/sucesso do user-code).
+    const deviceFlowFeatures = config.deviceFlow.enabled
+        ? { deviceFlow: { enabled: true, ...createDeviceSources(config.messages) } }
+        : {};
+    // DPoP (RFC 9449). A chave EXATA do oidc-provider v9 é `dPoP`.
+    const dpopFeatures = config.dpop.enabled ? { dPoP: { enabled: true } } : {};
+    // PAR (RFC 9126).
+    const parFeatures = config.par.enabled
+        ? {
+            pushedAuthorizationRequests: {
+                enabled: true,
+                requirePushedAuthorizationRequests: config.par.requirePushedAuthorizationRequests,
+            },
+        }
+        : {};
+    // Access Tokens RFC 9068 (JWT) via Resource Indicators (RFC 8707). Só montamos a
+    // feature quando ALGUM AT deve ser JWT — caso contrário (default opaque) o
+    // oidc-provider mantém o comportamento atual (AT opaco introspecionável) intocado.
+    //
+    // Um JWT AT no oidc-provider SEMPRE exige um resource indicator com `aud`: o
+    // `defaultResource` injeta a resource default (o `audience`, default issuer) quando
+    // o client não pede `resource` explicitamente, e o `getResourceServerInfo` descreve
+    // a API (scope/audience/formato/TTL) — onde `accessTokenFormat: 'jwt'` faz o token
+    // sair como JWS `typ: at+jwt` assinado com a chave corrente do JWKS.
+    const at = config.accessTokens;
+    const allScopes = ['openid', 'profile', 'email', 'offline_access', 'roles'];
+    const resourceIndicatorFeatures = at.anyJwt
+        ? {
+            resourceIndicators: {
+                enabled: true,
+                defaultResource: async (_ctx, _client, oneOf) => {
+                    // Nas trocas (code/refresh/device), o provider passa `oneOf` com as
+                    // resources já concedidas — devolvemos para não falhar a request.
+                    if (oneOf)
+                        return oneOf;
+                    // Authorize/sem resource explícito: liga ao resource default (modo simples).
+                    return at.audience;
+                },
+                useGrantedResource: async () => true,
+                getResourceServerInfo: (_ctx, resourceIndicator, _client) => {
+                    const rc = at.resources[resourceIndicator];
+                    const format = rc?.format ?? (resourceIndicator === at.audience ? at.format : 'opaque');
+                    const audience = rc?.audience ?? resourceIndicator;
+                    const scope = (rc?.scopes ?? allScopes).join(' ');
+                    const info = {
+                        scope,
+                        audience,
+                        accessTokenFormat: format,
+                    };
+                    const ttl = rc?.expiresIn;
+                    if (ttl !== undefined)
+                        info.accessTokenTTL = ttl;
+                    if (format === 'jwt') {
+                        // Assina com a chave de assinatura corrente do keystore (mesma do JWKS).
+                        info.jwt = { sign: { alg: config.jwks.keys[0]?.alg ?? 'RS256' } };
+                    }
+                    return info;
+                },
+            },
+        }
+        : {};
+    const provider = new oidc.Provider(config.issuer, {
+        adapter: config.AdapterClass,
+        clients: config.clients.map((c) => ({
+            client_id: c.clientId,
+            client_secret: c.clientSecret,
+            redirect_uris: c.redirectUris,
+            post_logout_redirect_uris: c.postLogoutRedirectUris ?? [],
+            grant_types: c.grants ?? ['authorization_code', 'refresh_token'],
+            response_types: (c.grants ?? ['authorization_code']).includes('authorization_code')
+                ? ['code']
+                : [],
+            token_endpoint_auth_method: c.tokenEndpointAuthMethod ?? (c.clientSecret ? 'client_secret_basic' : 'none'),
+            // OIDC Back-Channel Logout: só envia as chaves quando o client as declara,
+            // p/ não forçar metadata vazio em clients que não usam o recurso.
+            ...(c.backchannelLogoutUri ? { backchannel_logout_uri: c.backchannelLogoutUri } : {}),
+            ...(c.backchannelLogoutSessionRequired !== undefined
+                ? { backchannel_logout_session_required: c.backchannelLogoutSessionRequired }
+                : {}),
+        })),
+        findAccount: options.findAccount,
+        jwks: config.jwks,
+        cookies: {
+            keys: cookieKeys,
+            // O oidc-provider define o path do cookie _interaction como
+            // `/auth/interaction/<uid>` (exato) via `...cookieOptions` que
+            // SOBRESCREVE o path explícito. Sem `path: '/'` o cookie ficaria
+            // restrito ao path exato da tela de interaction e NÃO seria enviado
+            // pelo browser no POST de subpaths como `.../consent` ou `.../login`.
+            // Definir path: '/' na família "short" garante que os cookies de
+            // interaction e resume sejam enviados em todos os endpoints OIDC/auth.
+            short: { path: '/' },
+            long: { path: '/' },
+        },
+        // conformIdTokenClaims=false: caso contrário (default v9), no fluxo Authorization Code
+        // — onde também é emitido um Access Token — o oidc-provider mascara o ID token para
+        // apenas o escopo `openid` (só `sub`), removendo email/profile/roles do ID token.
+        // O client valida o ID TOKEN, então precisamos que as claims configuradas cheguem nele.
+        conformIdTokenClaims: false,
+        // DECISÃO DE SEGURANÇA (least privilege, 2026-06-09 — fix do achado L3):
+        // a claim de roles globais e as claims de org (`org_*`) ficam num escopo `roles`
+        // DEDICADO — fora do `profile`. O `profile` volta a ser só identidade (name/picture),
+        // de modo que QUALQUER client (inclusive third-party/dynamic registration futuro) que
+        // peça `scope=profile` NÃO recebe mais dados de autorização interna do usuário.
+        //
+        // Defesa em duas camadas:
+        //  1) Escopo dedicado `roles` (aqui) — roles/org_* só são candidatas a aparecer no
+        //     token quando o client solicita explicitamente `scope=roles`.
+        //  2) Gate first-party no `findAccount.claims()` (ver oidc_service.ts) — mesmo pedindo
+        //     `scope=roles`, um client third-party NUNCA tem essas claims emitidas. Só clients
+        //     listados em `branding.firstParty` recebem.
+        //
+        // O authkit-client passa a incluir `roles` no default de scopes, então consumidores
+        // first-party continuam recebendo `hasGlobalRole`/org sem mudança de comportamento.
+        claims: {
+            openid: ['sub'],
+            profile: ['name', 'picture'],
+            email: ['email', 'email_verified'],
+            roles: [config.globalRolesClaim, 'org_id', 'org_slug', 'org_role'],
+        },
+        scopes: ['openid', 'profile', 'email', 'offline_access', 'roles'],
+        // Permite que o parametro `audience` (hint de intencao do client, ex.: 'advisor')
+        // sobreviva ao authorize e fique disponivel em interactionDetails().params.audience.
+        extraParams: ['audience'],
+        pkce: { methods: ['S256'], required: () => true },
+        rotateRefreshToken: true,
+        features: {
+            devInteractions: { enabled: false },
+            // RP-initiated logout com splash de marca que auto-confirma (sem a tela
+            // default em inglês "Do you want to sign-out from…?").
+            rpInitiatedLogout: { enabled: true, ...createLogoutSources(config.messages) },
+            // OIDC Back-Channel Logout: o oidc-provider POSTa um logout_token para o
+            // `backchannel_logout_uri` de cada RP quando a sessão/grant é encerrada.
+            backchannelLogout: { enabled: true },
+            revocation: { enabled: true },
+            introspection: { enabled: true },
+            ...registrationFeatures,
+            ...deviceFlowFeatures,
+            ...dpopFeatures,
+            ...parFeatures,
+            ...resourceIndicatorFeatures,
+        },
+        // Step-up auth (acr_values): anuncia os acr suportados para que clients possam
+        // solicitá-los. A exigência efetiva do 2º fator acontece na interaction de login.
+        acrValues: config.stepUp.acrValues,
+        ttl: {
+            // AccessToken TTL: quando um TokenTtlHolder é fornecido, lê o valor atual do holder
+            // (atualizado em runtime via setting `token_ttl`). Sem holder: fallback ao config.
+            AccessToken: tokenTtlHolder
+                ? () => tokenTtlHolder.accessTokenSec
+                : config.ttl.accessToken,
+            // RefreshToken TTL: idem ao AccessToken.
+            RefreshToken: tokenTtlHolder
+                ? () => tokenTtlHolder.refreshTokenSec
+                : config.ttl.refreshToken,
+            // IdToken TTL: idem ao AccessToken.
+            IdToken: tokenTtlHolder
+                ? () => tokenTtlHolder.idTokenSec
+                : config.ttl.idToken,
+            // Session TTL: quando um SessionTtlHolder é fornecido, usa uma função que diferencia
+            // sessões persistentes (remember-me ON → rememberSec) das transientes (remember-me
+            // OFF → transientSec). A função é SÍNCRONA (restrição do oidc-provider). O holder é
+            // atualizado de forma assíncrona após write/reset da setting `session_policy`.
+            // `session.transient` é true quando `result.login.remember === false` (o provider
+            // seta `transient: !remember` em loginAccount — ver shared/session.js do oidc-provider).
+            // Sem holder: fallback ao TTL estático do config (zero regressão).
+            Session: sessionTtlHolder
+                ? (_ctx, session) => session.transient
+                    ? sessionTtlHolder.transientSec
+                    : sessionTtlHolder.rememberSec
+                : config.ttl.session,
+            Interaction: 3600,
+            Grant: tokenTtlHolder
+                ? () => tokenTtlHolder.refreshTokenSec
+                : config.ttl.refreshToken,
+        },
+        interactions: {
+            // Telas de interaction são servidas pelo CONSUMIDOR na RAIZ (fora do koa-mount do
+            // provider sob /oidc), evitando colisão com o catch-all /oidc/*. O provider redireciona
+            // o browser para cá; o consumidor chama interactionFinished, que devolve ao resume do
+            // provider em /oidc/auth/:uid (já corretamente prefixado pelo koa-mount).
+            url: (_ctx, interaction) => `/auth/interaction/${interaction.uid}`,
+        },
+    });
+    provider.proxy = true;
+    return provider;
+}

package/build/src/provider/device_sources.d.ts

@@ -0,0 +1,6 @@
+import { type AuthMessages } from '../host/i18n.js';
+export declare function createDeviceSources(messages: AuthMessages): {
+    userCodeInputSource(_ctx: any, form: string, _out: any, err: any): Promise<void>;
+    userCodeConfirmSource(_ctx: any, form: string, _client: any, _deviceInfo: any, userCode: string): Promise<void>;
+    successSource(_ctx: any): Promise<void>;
+};

package/build/src/provider/device_sources.js

@@ -0,0 +1,65 @@
+import { translate } from '../host/i18n.js';
+/**
+ * Fontes (sources) de renderização do Device Authorization Grant (RFC 8628).
+ *
+ * O oidc-provider chama estas funções com o KOA ctx (não o HttpContext do Adonis),
+ * então elas NÃO têm acesso ao renderer Inertia/Edge do host. Emitimos HTML
+ * auto-contido e i18n-izado (mesmo idioma das demais telas), o que também silencia
+ * os avisos `shouldChange` dos defaults da lib. As três telas:
+ *  - userCodeInputSource: entrada do user-code (`/device`)
+ *  - userCodeConfirmSource: confirmação após o code casar
+ *  - successSource: tela final pós-aprovação
+ */
+function esc(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+const STYLE = `
+  body{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#f5f5f7;margin:0;padding:48px 16px;color:#1d1d1f}
+  .card{max-width:340px;margin:0 auto;background:#fff;border-radius:14px;padding:32px;box-shadow:0 1px 4px rgba(0,0,0,.08)}
+  h1{font-size:1.4rem;font-weight:600;margin:0 0 12px;text-align:center}
+  p{font-size:.95rem;line-height:1.5;text-align:center;color:#444}
+  p.red{color:#c0392b}
+  code{display:block;font-size:1.6rem;letter-spacing:.15em;text-align:center;margin:16px 0;font-weight:600}
+  input[type=text]{width:100%;box-sizing:border-box;height:46px;font-size:1rem;text-align:center;text-transform:uppercase;border:1px solid #d2d2d7;border-radius:10px;padding:0 12px;margin-bottom:14px}
+  button{width:100%;height:44px;font-size:.95rem;font-weight:600;color:#fff;background:#0071e3;border:0;border-radius:10px;cursor:pointer}
+  button:hover{background:#0077ed}
+  .abort{margin-top:12px;background:none;color:#666;font-weight:400}
+  .abort:hover{background:none;text-decoration:underline}
+`;
+function page(title, inner) {
+    return `<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(title)}</title><style>${STYLE}</style></head><body><div class="card">${inner}</div></body></html>`;
+}
+export function createDeviceSources(messages) {
+    const t = (key, params) => translate(messages, key, params);
+    return {
+        async userCodeInputSource(_ctx, form, _out, err) {
+            const ctx = _ctx;
+            let msg;
+            if (err && (err.userCode || err.name === 'NoCodeError')) {
+                msg = `<p class="red">${esc(t('device.input.error_invalid'))}</p>`;
+            }
+            else if (err && err.name === 'AbortedError') {
+                msg = `<p class="red">${esc(t('device.input.error_aborted'))}</p>`;
+            }
+            else if (err) {
+                msg = `<p class="red">${esc(t('device.input.error_generic'))}</p>`;
+            }
+            else {
+                msg = `<p>${esc(t('device.input.intro'))}</p>`;
+            }
+            ctx.body = page(t('device.input.title'), `<h1>${esc(t('device.input.title'))}</h1>${msg}${form}<button type="submit" form="op.deviceInputForm">${esc(t('device.input.submit'))}</button>`);
+        },
+        async userCodeConfirmSource(_ctx, form, _client, _deviceInfo, userCode) {
+            const ctx = _ctx;
+            ctx.body = page(t('device.confirm.title'), `<h1>${esc(t('device.confirm.title'))}</h1><p>${esc(t('device.confirm.body'))}</p><code>${esc(userCode)}</code>${form}<button autofocus type="submit" form="op.deviceConfirmForm">${esc(t('device.confirm.submit'))}</button><button class="abort" type="submit" form="op.deviceConfirmForm" value="yes" name="abort">${esc(t('device.confirm.abort'))}</button>`);
+        },
+        async successSource(_ctx) {
+            const ctx = _ctx;
+            ctx.body = page(t('device.success.title'), `<h1>${esc(t('device.success.title'))}</h1><p>${esc(t('device.success.body'))}</p>`);
+        },
+    };
+}

package/build/src/provider/interaction_actions.d.ts

@@ -0,0 +1,36 @@
+import type { HttpContext } from '@adonisjs/core/http';
+export interface InteractionDeps {
+    verifyCredentials?: (email: string, password: string) => Promise<{
+        id: string;
+    } | null>;
+}
+/** Detalhes opcionais de login (step-up auth): acr alcançado + amr (métodos). */
+export interface CompleteLoginExtra {
+    acr?: string;
+    amr?: string[];
+    /**
+     * "Manter conectado" (remember-me). Mapeado para `result.login.remember` do
+     * oidc-provider. Quando `false`, a sessão se torna transiente (cookie expira ao
+     * fechar o browser); o TTL function do provider usa `session.transient` para
+     * aplicar o TTL curto (defaultSessionHours). Default: `true` (persistente).
+     *
+     * NOTA: o campo `remember` em `result.login` é NATIVO do oidc-provider v9 —
+     * ver `resume.js`: `let { remember = true, accountId, ... } = result.login`.
+     */
+    remember?: boolean;
+}
+export interface InteractionActions {
+    details(ctx: HttpContext): Promise<any>;
+    login(ctx: HttpContext, input: {
+        email: string;
+        password: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    completeLogin(ctx: HttpContext, accountId: string, extra?: CompleteLoginExtra): Promise<{
+        ok: boolean;
+    }>;
+    consent(ctx: HttpContext): Promise<unknown>;
+}
+/** Lógica de interaction (login/consent) sobre o provider. Testável com um provider fake. */
+export declare function createInteractionActions(provider: any, deps: InteractionDeps): InteractionActions;

package/build/src/provider/interaction_actions.js

@@ -0,0 +1,55 @@
+/** Lógica de interaction (login/consent) sobre o provider. Testável com um provider fake. */
+export function createInteractionActions(provider, deps) {
+    return {
+        async details(ctx) {
+            return provider.interactionDetails(ctx.request.request, ctx.response.response);
+        },
+        async login(ctx, { email, password }) {
+            if (!deps.verifyCredentials) {
+                throw new Error('authkit: defina `verifyCredentials` no config/authkit.ts para usar o login das interactions.');
+            }
+            const account = await deps.verifyCredentials(email, password);
+            if (!account)
+                return { ok: false };
+            await provider.interactionFinished(ctx.request.request, ctx.response.response, { login: { accountId: account.id } }, { mergeWithLastSubmission: false });
+            return { ok: true };
+        },
+        async completeLogin(ctx, accountId, extra) {
+            // acr/amr (RFC 8176): quando um step-up de MFA foi efetivamente cumprido,
+            // passamos o acr alcançado + os métodos (amr) para que o id_token os carregue.
+            const login = { accountId };
+            if (extra?.acr)
+                login.acr = extra.acr;
+            if (extra?.amr && extra.amr.length)
+                login.amr = extra.amr;
+            // remember-me: `remember: false` → sessão transiente (transient: true no provider);
+            // `remember: true` ou ausente → sessão persistente (padrão do oidc-provider).
+            // O campo `remember` é nativo do oidc-provider v9 — veja resume.js.
+            if (extra?.remember === false)
+                login.remember = false;
+            await provider.interactionFinished(ctx.request.request, ctx.response.response, { login }, { mergeWithLastSubmission: false });
+            return { ok: true };
+        },
+        async consent(ctx) {
+            const details = await provider.interactionDetails(ctx.request.request, ctx.response.response);
+            const grant = new provider.Grant({
+                accountId: details.session.accountId,
+                clientId: details.params.client_id,
+            });
+            grant.addOIDCScope(String(details.params.scope ?? 'openid'));
+            // Resource Indicators (RFC 8707): quando o authorize/token pede um `resource`
+            // (ex.: JWT Access Tokens RFC 9068), o provider sinaliza os scopes faltantes
+            // por resource em `prompt.details.missingResourceScopes`. Concedemos cada um
+            // para que o resume materialize o AT vinculado àquela API; sem isto o provider
+            // re-emite o prompt de consent num laço.
+            const missingResourceScopes = details.prompt?.details?.missingResourceScopes;
+            if (missingResourceScopes) {
+                for (const [resource, scopes] of Object.entries(missingResourceScopes)) {
+                    grant.addResourceScope(resource, (scopes ?? []).join(' '));
+                }
+            }
+            const grantId = await grant.save();
+            return provider.interactionFinished(ctx.request.request, ctx.response.response, { consent: { grantId } }, { mergeWithLastSubmission: true });
+        },
+    };
+}

package/build/src/provider/key_rotation_scheduler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Housekeeping da lib: rotação de chave JWKS age-based. A cada intervalo, se a
+ * setting `key_rotation` está enabled e a chave corrente passou de `maxAgeDays`,
+ * adquire um lock single-flight (só UMA instância rotaciona) e chama `rotateKeys`,
+ * que aplica ao vivo. Re-checa a idade DENTRO do lock para não rotacionar duas
+ * vezes quando outra instância acabou de rotacionar. Fail-safe; `unref` no timer.
+ * Toda a lógica é pura+injetada (testável sem app).
+ */
+export interface KeyRotationSchedulerOptions {
+    policy: () => Promise<{
+        enabled: boolean;
+        maxAgeDays: number;
+        keep: number;
+    }>;
+    ageDays: () => Promise<number | null>;
+    rotateKeys: (keep: number) => Promise<void>;
+    withLock: (fn: () => Promise<void>) => Promise<void>;
+    intervalMs: number;
+    onError?: (err: unknown) => void;
+}
+export declare class KeyRotationScheduler {
+    #private;
+    private opts;
+    constructor(opts: KeyRotationSchedulerOptions);
+    tick(): Promise<void>;
+    start(): void;
+    stop(): void;
+}

package/build/src/provider/key_rotation_scheduler.js

@@ -0,0 +1,40 @@
+export class KeyRotationScheduler {
+    opts;
+    #timer;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async tick() {
+        try {
+            const policy = await this.opts.policy();
+            if (!policy.enabled)
+                return;
+            const age = await this.opts.ageDays();
+            if (age === null || age < policy.maxAgeDays)
+                return;
+            await this.opts.withLock(async () => {
+                // re-check dentro do lock: outra instância pode ter rotacionado.
+                const age2 = await this.opts.ageDays();
+                if (age2 === null || age2 < policy.maxAgeDays)
+                    return;
+                await this.opts.rotateKeys(policy.keep);
+            });
+        }
+        catch (err) {
+            this.opts.onError?.(err);
+        }
+    }
+    start() {
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => { void this.tick(); }, this.opts.intervalMs);
+        if (typeof this.#timer.unref === 'function')
+            this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+}

package/build/src/provider/keystore_reload.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Poll de housekeeping (da lib): lê um `head` barato do cofre e dispara `reload`
+ * quando ele muda desde o último observado. Propaga rotações feitas por outro
+ * processo/instância sem restart. Fail-safe: erros viram no-op (repassados a
+ * `onError` se fornecido). `start()`/`stop()` controlam o intervalo; `tick()` é
+ * exposto p/ teste.
+ */
+export interface KeystoreReloadOptions {
+    head: () => Promise<string | null>;
+    reload: () => Promise<void>;
+    intervalMs: number;
+    onError?: (err: unknown) => void;
+}
+export declare class KeystoreReloadPoller {
+    #private;
+    private opts;
+    constructor(opts: KeystoreReloadOptions);
+    tick(): Promise<void>;
+    start(): void;
+    stop(): void;
+}

package/build/src/provider/keystore_reload.js

@@ -0,0 +1,39 @@
+export class KeystoreReloadPoller {
+    opts;
+    #last;
+    #timer;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async tick() {
+        try {
+            const head = await this.opts.head();
+            if (this.#last === undefined) {
+                this.#last = head;
+                return;
+            } // baseline, sem reload
+            if (head !== this.#last) {
+                this.#last = head;
+                await this.opts.reload();
+            }
+        }
+        catch (err) {
+            this.opts.onError?.(err);
+        }
+    }
+    start() {
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => {
+            void this.tick();
+        }, this.opts.intervalMs);
+        if (typeof this.#timer.unref === 'function')
+            this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+}

package/build/src/provider/logout_sources.d.ts

@@ -0,0 +1,13 @@
+import { type AuthMessages } from '../host/i18n.js';
+export declare function createLogoutSources(messages: AuthMessages): {
+    /**
+     * Splash de saída que auto-confirma. `form` já contém o <form> com o xsrf
+     * e a action de confirmação; injetamos o campo `logout` e submetemos.
+     */
+    logoutSource(ctx: any, form: string): Promise<void>;
+    /**
+     * Mostrada apenas quando NÃO há `post_logout_redirect_uri` (senão o provider
+     * redireciona o browser direto pro RP). Tela de marca em vez do default.
+     */
+    postLogoutSuccessSource(ctx: any): Promise<void>;
+};

package/build/src/provider/logout_sources.js

@@ -0,0 +1,64 @@
+import { translate } from '../host/i18n.js';
+/**
+ * Sources de RP-initiated logout (end_session).
+ *
+ * Por padrão o oidc-provider renderiza uma página em INGLÊS e sem estilo
+ * ("Do you want to sign-out from …?") com dois botões. Como o usuário já
+ * clicou em "Sair" no app, a confirmação é fricção pura: sobrescrevemos
+ * `logoutSource` por um splash de marca que AUTO-CONFIRMA (injeta o campo
+ * `logout=yes` e submete via JS), com fallback `<noscript>` acessível.
+ *
+ * Como `device_sources`, recebem o KOA ctx (sem acesso ao renderer do host),
+ * então emitem HTML auto-contido e i18n-izado.
+ */
+function esc(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+// Papel quente neutro + tinta — alinhado ao espírito "Manuscrito Vivo" sem
+// depender da marca de um client específico (o end_session é cross-client).
+const STYLE = `
+  *{box-sizing:border-box}
+  body{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#faf6ee;margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;color:#2f1a47}
+  .card{max-width:360px;width:100%;text-align:center}
+  .spinner{width:30px;height:30px;margin:0 auto 20px;border:2.5px solid rgba(47,26,71,.15);border-top-color:#f17e42;border-radius:50%;animation:spin .7s linear infinite}
+  @keyframes spin{to{transform:rotate(360deg)}}
+  h1{font-family:Georgia,'Times New Roman',serif;font-size:1.5rem;font-weight:500;letter-spacing:-.01em;margin:0 0 8px}
+  p{font-size:.95rem;line-height:1.5;color:#6e5d85;margin:0}
+  button{margin-top:20px;height:44px;padding:0 22px;font-size:.95rem;font-weight:600;color:#2f1a47;background:#f17e42;border:0;border-radius:10px;cursor:pointer}
+  @media (prefers-reduced-motion:reduce){.spinner{animation:none}}
+  @media (prefers-color-scheme:dark){body{background:#1d112e;color:#f3ecdf}p{color:rgba(243,236,223,.65)}}
+`;
+function page(title, inner) {
+    return `<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(title)}</title><style>${STYLE}</style></head><body><div class="card">${inner}</div></body></html>`;
+}
+export function createLogoutSources(messages) {
+    const t = (key, params) => translate(messages, key, params);
+    return {
+        /**
+         * Splash de saída que auto-confirma. `form` já contém o <form> com o xsrf
+         * e a action de confirmação; injetamos o campo `logout` e submetemos.
+         */
+        async logoutSource(ctx, form) {
+            // Injeta o campo de confirmação dentro do form fornecido pela lib.
+            const confirmedForm = form.replace(/<\/form>/, '<input type="hidden" name="logout" value="yes"/></form>');
+            ctx.body = page(t('logout.title'), `<div class="spinner" aria-hidden="true"></div>` +
+                `<h1>${esc(t('logout.title'))}</h1>` +
+                `<p>${esc(t('logout.body'))}</p>` +
+                confirmedForm +
+                `<noscript><button type="submit" form="op.logoutForm">${esc(t('logout.fallback'))}</button></noscript>` +
+                `<script>(function(){var f=document.forms['op.logoutForm'];if(f){f.submit();}})();</script>`);
+        },
+        /**
+         * Mostrada apenas quando NÃO há `post_logout_redirect_uri` (senão o provider
+         * redireciona o browser direto pro RP). Tela de marca em vez do default.
+         */
+        async postLogoutSuccessSource(ctx) {
+            ctx.body = page(t('logout.success.title'), `<h1>${esc(t('logout.success.title'))}</h1>` +
+                `<p>${esc(t('logout.success.body'))}</p>`);
+        },
+    };
+}