@adonis-agora/authkit-server 0.57.0 → 0.58.0

package/README.md

@@ -31,7 +31,7 @@ node ace add @adonis-agora/authkit-server
 # ou: pnpm add @adonis-agora/authkit-server && node ace configure @adonis-agora/authkit-server
 ```
 
-O `configure` publica `config/authkit_server.ts`, o model `app/models/auth_user.ts`,
+O `configure` publica `config/authkit.ts`, o model `app/models/auth_user.ts`,
 o controller de interactions (`app/controllers/auth_interaction_controller.ts`) e
 registra o provider.
 
@@ -89,7 +89,7 @@ Em todos os presets o controller ejetado é **casca**: a lógica vive em
 `details(ctx)`, `login(ctx, { email, password })` e `consent(ctx)`. Você edita só a parte de
 render/redirect.
 
-Quem decide se as credenciais valem é o `verifyCredentials` do `config/authkit_server.ts`
+Quem decide se as credenciais valem é o `verifyCredentials` do `config/authkit.ts`
 — é o que o `service.interactions.login` chama. O default consulta o `AuthUser` por e-mail e
 usa `verifyPassword`; sobrescreva para plugar sua própria base de usuários.
 
@@ -105,7 +105,7 @@ router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'conse
 
 ## Persistência
 
-Escolha o backend no `config/authkit_server.ts`:
+Escolha o backend no `config/authkit.ts`:
 - `adapters.redis({ connection })` — requer `@adonisjs/redis` configurado.
 - `adapters.database({ connection? })` — Lucid; rode a migração `authkit_oidc_payloads`.
 
@@ -116,7 +116,7 @@ de resolve) e as expõe de forma opt-in.
 
 ### Configuração
 
-No `config/authkit_server.ts`, use a chave `observability`:
+No `config/authkit.ts`, use a chave `observability`:
 
 ```ts
 observability: {

package/build/index.d.ts

@@ -49,7 +49,7 @@ export type { AuthkitScreen } from './src/host/renderers/inertia_renderer.js';
 export type { InertiaRendererOptions } from './src/host/renderers/inertia_renderer.js';
 export type { AccountLoginProps, AccountSecurityProps, AccountMfaProps, AccountConfirmProps, AccountConfirmMethod, AccountEmailConfirmedProps, } from './src/host/account_screen_props.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
-export { brandFor, isFirstParty } from './src/host/branding.js';
+export { brandFor, isFirstParty, isFirstPartyClient } from './src/host/branding.js';
 export type { BrandingConfig, ClientBrand } from './src/host/branding.js';
 export { resolveMessages, translate, DEFAULT_MESSAGES, PT_BR_MESSAGES, BUILTIN_MESSAGES, DEFAULT_LOCALE, } from './src/host/i18n.js';
 export type { I18nConfig, AuthMessages } from './src/host/i18n.js';
@@ -105,7 +105,7 @@ export { computeAdminStats } from './src/host/admin_stats_service.js';
 export type { AdminStats, DailyPoint } from './src/host/admin_stats_service.js';
 export { barChartSvg } from './src/host/svg_chart.js';
 export { buildImpersonationPanel } from './src/host/impersonation.js';
-export type { ImpersonationPanel } from './src/host/impersonation.js';
+export type { ImpersonationPanel, ImpersonationClientLike } from './src/host/impersonation.js';
 export { ACTIVE_ORG_COOKIE, ACTIVE_ORG_COOKIE_TTL, encodeActiveOrgCookie, decodeActiveOrgCookie, readActiveOrgFromKoaCtx, } from './src/host/active_org_cookie.js';
 export { resolveOrganizations } from './src/define_config.js';
 export type { OrganizationsConfigInput, ResolvedOrganizationsConfig, } from './src/define_config.js';

package/build/index.js

@@ -30,7 +30,7 @@ export { withAuditLog } from './src/mixins/with_audit_log.js';
 export { composeAuditSink, resolveEvents, buildWebhookBody, signWebhookBody, } from './src/events/dispatcher.js';
 export { inertiaRenderer } from './src/host/renderers/inertia_renderer.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
-export { brandFor, isFirstParty } from './src/host/branding.js';
+export { brandFor, isFirstParty, isFirstPartyClient } from './src/host/branding.js';
 export { resolveMessages, translate, DEFAULT_MESSAGES, PT_BR_MESSAGES, BUILTIN_MESSAGES, DEFAULT_LOCALE, } from './src/host/i18n.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { POLICY_ROUTE_OPTIONS } from './src/host/config_locks.js';

package/build/providers/authkit_server_provider.d.ts

@@ -1,16 +1,5 @@
-import type { MetricsRecorder } from '@adonis-agora/authkit-core';
+import '../types.js';
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { AccountStore } from '../src/accounts/account_store.js';
-import type { PatStore } from '../src/pat/pat_store.js';
-import { OidcService } from '../src/provider/oidc_service.js';
-declare module '@adonisjs/core/types' {
-    interface ContainerBindings {
-        'authkit.server': OidcService;
-        'authkit.metrics': MetricsRecorder;
-        'authkit.accountStore': AccountStore;
-        'authkit.patStore': PatStore;
-    }
-}
 export default class AuthkitServerProvider {
     #private;
     protected app: ApplicationService;

package/build/providers/authkit_server_provider.js

@@ -1,3 +1,16 @@
+// Side-effect import, and it is load-bearing: the `ContainerBindings`
+// augmentation for this package's four bindings lives in the root `types.ts`,
+// and this is the module that carries it into a host app's declaration graph —
+// every host registers this provider in `adonisrc.ts`.
+//
+// The declaration used to be duplicated here as well. One copy typed the hosts
+// and the other backed the `./types` subpath, and the two had drifted: this one
+// declared four bindings, `types.ts` declared one. There is a single table now.
+//
+// It must be a bare side-effect import — the `import type {} from` form is erased
+// from the emitted `.d.ts` and would drop the augmentation. `build/types.js`
+// compiles down to `export {}`, so the runtime cost is nil.
+import '../types.js';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { configProvider } from '@adonisjs/core';

package/build/src/audit/audit_sink.d.ts

@@ -1,7 +1,16 @@
 /**
- * Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP.
+ * Tipos de eventos de auditoria emitidos pelo IdP, como VALOR em runtime.
+ *
+ * A união {@link AuditEventType} é DERIVADA desta lista, e não escrita à mão,
+ * porque uma união escrita à mão não tem como ser conferida contra o que o
+ * código de fato emite — foi assim que cinco eventos passaram a existir sem
+ * estar no tipo. Com a lista em runtime, `tests/audit/audit_event_drift.spec.ts`
+ * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
+ * emitido não está aqui.
  */
-export type AuditEventType = 'login.success' | 'login.failure' | 'signup' | 'password_reset.issued' | 'password_reset.consumed' | 'pat.issued' | 'pat.revoked' | 'pat.used' | 'impersonation' | 'impersonation.started' | 'mfa.enabled' | 'mfa.disabled' | 'account.locked' | 'passkey.registered' | 'passkey.removed' | 'email_verification.issued' | 'email_verification.consumed' | 'client.created' | 'client.updated' | 'client.deleted' | 'session.revoked_all' | 'password.changed' | 'password.rehashed' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified' | 'login.new_device' | 'login.otp_sent' | 'login.otp_verified' | 'login.otp_failed' | 'login.otp_invalidated' | 'bot_protection.rejected' | 'grant.revoked_by_user' | 'user.created' | 'user.password_reset_sent' | 'user.disabled' | 'user.enabled' | 'user.deleted' | 'profile.updated' | 'account.deleted' | 'account.exported' | 'keys.rotated' | 'organization.created' | 'organization.updated' | 'organization.deleted' | 'organization.member_added' | 'organization.member_removed' | 'organization.member_role_changed' | 'organization.member_role_updated' | 'organization.switched' | 'organization.deactivated' | 'organization.invitation_sent' | 'organization.invitation_accepted' | 'organization.invitation_revoked' | 'email_change.requested' | 'email_change.confirmed' | 'email_change.cancelled' | 'security_notice.sent' | 'settings.updated' | 'maintenance.enabled' | 'maintenance.disabled' | 'trusted_device.revoked' | 'password.expired_change_forced' | 'otp.locked' | 'otp.unlocked' | 'otp.unlock_failed' | 'sudo.confirmed' | 'session.single_enforced' | 'account.expired_login_blocked' | 'account.expiration_warned';
+export declare const AUDIT_EVENT_TYPES: readonly ["login.success", "login.failure", "signup", "password_reset.issued", "password_reset.consumed", "pat.issued", "pat.revoked", "pat.used", "impersonation", "impersonation.panel_viewed", "mfa.enabled", "mfa.disabled", "account.locked", "passkey.registered", "passkey.removed", "email_verification.issued", "email_verification.consumed", "client.created", "client.updated", "client.deleted", "session.revoked_all", "password.changed", "password.rehashed", "email.change_requested", "email.changed", "login.new_ip_notified", "login.new_device", "login.otp_sent", "login.otp_verified", "login.otp_failed", "login.otp_invalidated", "bot_protection.rejected", "grant.revoked_by_user", "user.created", "user.password_reset_sent", "user.disabled", "user.enabled", "user.deleted", "profile.updated", "account.deleted", "account.exported", "keys.rotated", "organization.created", "organization.updated", "organization.deleted", "organization.member_added", "organization.member_removed", "organization.member_role_changed", "organization.member_role_updated", "organization.switched", "organization.deactivated", "organization.invitation_sent", "organization.invitation_accepted", "organization.invitation_revoked", "email_change.requested", "email_change.confirmed", "email_change.cancelled", "security_notice.sent", "settings.updated", "maintenance.enabled", "maintenance.disabled", "trusted_device.revoked", "password.expired_change_forced", "otp.locked", "otp.unlocked", "otp.unlock_failed", "sudo.confirmed", "session.single_enforced", "account.expired_login_blocked", "account.expiration_warned", "login.magic_link_sent", "session.revoked", "account.signed_out_all", "client.secret_regenerated", "roles_catalog.updated"];
+/** Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP. */
+export type AuditEventType = (typeof AUDIT_EVENT_TYPES)[number];
 /**
  * Evento de auditoria a registrar. O timestamp é definido pelo sink (não aqui).
  */

package/build/src/audit/audit_sink.js

@@ -1 +1,104 @@
-export {};
+/**
+ * Tipos de eventos de auditoria emitidos pelo IdP, como VALOR em runtime.
+ *
+ * A união {@link AuditEventType} é DERIVADA desta lista, e não escrita à mão,
+ * porque uma união escrita à mão não tem como ser conferida contra o que o
+ * código de fato emite — foi assim que cinco eventos passaram a existir sem
+ * estar no tipo. Com a lista em runtime, `tests/audit/audit_event_drift.spec.ts`
+ * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
+ * emitido não está aqui.
+ */
+export const AUDIT_EVENT_TYPES = [
+    'login.success',
+    'login.failure',
+    'signup',
+    'password_reset.issued',
+    'password_reset.consumed',
+    'pat.issued',
+    'pat.revoked',
+    'pat.used',
+    // O exchange RFC 8693 de fato aconteceu: uma identidade foi assumida.
+    'impersonation',
+    // O admin abriu o painel do console e revelou os parâmetros do exchange.
+    // NÃO é uma impersonação: nada foi assumido ainda, e o exchange pode nunca
+    // acontecer. Manter os dois separados é o que impede a trilha de auditoria de
+    // afirmar uma impersonação que só foi consultada.
+    'impersonation.panel_viewed',
+    'mfa.enabled',
+    'mfa.disabled',
+    'account.locked',
+    'passkey.registered',
+    'passkey.removed',
+    'email_verification.issued',
+    'email_verification.consumed',
+    'client.created',
+    'client.updated',
+    'client.deleted',
+    'session.revoked_all',
+    'password.changed',
+    'password.rehashed',
+    'email.change_requested',
+    'email.changed',
+    'login.new_ip_notified',
+    'login.new_device',
+    // Login por OTP (código digitável)
+    'login.otp_sent',
+    'login.otp_verified',
+    'login.otp_failed',
+    'login.otp_invalidated',
+    'bot_protection.rejected',
+    'grant.revoked_by_user',
+    'user.created',
+    'user.password_reset_sent',
+    'user.disabled',
+    'user.enabled',
+    'user.deleted',
+    'profile.updated',
+    'account.deleted',
+    'account.exported',
+    'keys.rotated',
+    'organization.created',
+    'organization.updated',
+    'organization.deleted',
+    'organization.member_added',
+    'organization.member_removed',
+    'organization.member_role_changed',
+    'organization.member_role_updated',
+    'organization.switched',
+    'organization.deactivated',
+    'organization.invitation_sent',
+    'organization.invitation_accepted',
+    'organization.invitation_revoked',
+    // Email change (verified flow)
+    'email_change.requested',
+    'email_change.confirmed',
+    'email_change.cancelled',
+    // Security notices
+    'security_notice.sent',
+    // Settings
+    'settings.updated',
+    'maintenance.enabled',
+    'maintenance.disabled',
+    'trusted_device.revoked',
+    // Password hygiene
+    'password.expired_change_forced',
+    // OTP lockout
+    'otp.locked',
+    'otp.unlocked',
+    'otp.unlock_failed',
+    // Sudo mode
+    'sudo.confirmed',
+    // Session
+    'session.single_enforced',
+    // Account expiration
+    'account.expired_login_blocked',
+    'account.expiration_warned',
+    // Emitidos pelo host-kit e antes AUSENTES desta lista — o switch exaustivo
+    // de um consumidor os perdia silenciosamente. Ver `audit_event_drift.spec.ts`,
+    // que varre os call sites e falha se a divergência voltar.
+    'login.magic_link_sent',
+    'session.revoked',
+    'account.signed_out_all',
+    'client.secret_regenerated',
+    'roles_catalog.updated',
+];

package/build/src/define_config.d.ts

@@ -87,7 +87,14 @@ export interface MailHooks {
         userAgent?: string | null;
         timestamp: string;
     }) => Promise<void>;
-    /** Disparado ao criar um convite de organização. */
+    /**
+     * Disparado ao criar um convite de organização.
+     *
+     * OPTIONAL, like every other mail hook here: without it the host-kit itself
+     * sends the invitation email through the default mailer (`@adonisjs/mail`),
+     * branded and translated. Best-effort — a delivery failure never breaks the
+     * invitation.
+     */
     onOrgInvitation?: (data: {
         email: string;
         invitationId: string;
@@ -131,6 +138,19 @@ export interface MailHooks {
         unlockUrl: string;
         token: string;
     }) => Promise<void>;
+    /**
+     * Disparado pelo `authkit:expire-scan` quando uma conta está prestes a ser
+     * desativada por inatividade. Substitui o e-mail default de aviso quando
+     * fornecido. Best-effort, fire-and-forget; deduplicado pela janela de
+     * `warnDays` da setting `account_expiration`, então cada conta recebe no
+     * máximo um aviso por janela.
+     */
+    onAccountExpirationWarning?: (data: {
+        /** E-mail da conta que será desativada. */
+        email: string;
+        /** Dias restantes até a desativação. */
+        expiresInDays: number;
+    }) => Promise<void>;
     /**
      * Disparado após um evento de segurança (senha alterada, MFA habilitado/desabilitado,
      * passkey adicionada/removida, e-mail alterado). Substitui o e-mail default quando
@@ -776,6 +796,28 @@ export interface AuthServerConfigInput {
     interactionRecovery?: InteractionRecoveryConfigInput;
     /** Configuração de branding por cliente. */
     branding?: BrandingConfig;
+    /**
+     * Allowlist dos clients FIRST-PARTY: quem recebe as claims de AUTORIZAÇÃO
+     * (`<globalRolesClaim>`, `org_id`, `org_slug`, `org_role`) nos tokens.
+     *
+     * Ausente (default) → TODO client registrado é first-party. Isso NÃO é
+     * "qualquer um vê as roles": a claim está amarrada ao escopo `roles` (ver
+     * `claims` em `provider/build_provider.ts`), então o client precisa (a) ter
+     * sido registrado por um admin e (b) pedir `scope=roles`. A allowlist é uma
+     * terceira barreira, opcional, para quem hospeda clients de terceiros.
+     *
+     * Declarada → só os clients listados recebem; os demais nunca, nem pedindo
+     * `scope=roles`.
+     *
+     * Por que existe separado de `branding.firstParty`: aquele campo vive num
+     * bloco de TEMA. Quem não personalizava a aparência não declarava `branding`,
+     * e o gate lia isso como "ninguém é first-party" — todo RP recebia
+     * `globalRoles: []` enquanto o console admin seguia funcionando (ele lê roles
+     * da sessão, não do token). Uma decisão de autorização não pode depender de o
+     * host ter ou não escolhido uma cor. `branding.firstParty` continua sendo lido
+     * como fallback para quem já o declarou.
+     */
+    firstPartyClients?: string[];
     /** Internacionalização das telas. Default: pt-BR embutido (zero config). */
     i18n?: I18nConfig;
     /** Configuração de providers sociais. */
@@ -888,15 +930,21 @@ export interface AuthServerConfigInput {
      */
     accessTokens?: AccessTokensConfig;
     /**
-     * Console admin do IdP (B6). Default: desligado. Quando ligado, o host também
-     * deve passar `admin: true` em {@link AuthHostOptions} no registro de rotas
-     * (a montagem das rotas acontece antes do config resolver).
+     * Console admin do IdP (B6). Default: desligado.
+     *
+     * Declarar esta chave TRAVA o liga/desliga: `registerAuthHost(router, { admin })`
+     * passa a ser ignorado (ver `deriveLockedRouteOptions`). Não repita o
+     * `enabled` no `start/routes.ts` — no máximo passe `admin: { prefix }`, que é
+     * estrutural e continua valendo.
      */
     admin?: AdminConfigInput;
     /**
-     * Admin REST API (R6). Default: desligada. Quando ligada, o host também deve
-     * passar `adminApi: true` em {@link AuthHostOptions} no registro de rotas (a
-     * montagem das rotas acontece antes do config resolver). Autenticação por API key.
+     * Admin REST API (R6). Default: desligada. Autenticação por API key.
+     *
+     * Declarar esta chave TRAVA o liga/desliga: `registerAuthHost(router, { adminApi })`
+     * passa a ser ignorado (ver `deriveLockedRouteOptions`). Não repita o
+     * `enabled` no `start/routes.ts` — no máximo passe `adminApi: { prefix }`, que
+     * é estrutural e continua valendo.
      */
     adminApi?: AdminApiConfigInput;
     /**
@@ -913,8 +961,16 @@ export interface AuthServerConfigInput {
      */
     resolveGeo?: ResolveGeo;
     /**
-     * Gestão automática do schema das tabelas do authkit (`authkit_oidc_payloads`,
-     * `auth_settings`, `auth_password_history` e as três de organizations).
+     * Gestão automática do schema das OITO tabelas do authkit:
+     * `authkit_oidc_payloads`, `auth_settings`, `auth_password_history`,
+     * `auth_mfa`, `auth_session_revocations` e as três de organizations
+     * (`auth_organizations`, `auth_organization_members`,
+     * `auth_organization_invitations`). Ver `TABLES` em `schema/ensure.ts` — a
+     * lista aqui existe para o leitor, mas quem manda é aquele array.
+     *
+     * FORA desta gestão: `authkit_keystore`, criada sob demanda pelo
+     * `LucidKeystoreVault` na primeira escrita, e as tabelas do MODEL do host
+     * (`auth_users` etc.), que são migrations do app.
      *
      * - `autoManage` (default `true`): no boot, cria as tabelas que faltam e
      *   adiciona colunas novas (aditivo — nunca dropa nem altera tipos).
@@ -1011,6 +1067,12 @@ export interface ResolvedServerConfig {
     /** Recuperação de sessão de interaction perdida resolvida (default `{ mode: 'screen' }`). */
     interactionRecovery: ResolvedInteractionRecoveryConfig;
     branding?: BrandingConfig;
+    /**
+     * Allowlist resolvida de clients first-party, ou `undefined` quando o host não
+     * declarou nenhuma — caso em que todo client registrado é first-party. Ver
+     * {@link AuthServerConfigInput.firstPartyClients}.
+     */
+    firstPartyClients?: string[];
     social?: AuthSocialConfig;
     patIntrospectionSecret?: string;
     rateLimit: ResolvedRateLimitConfig;

package/build/src/define_config.js

@@ -360,6 +360,9 @@ export function defineConfig(config) {
                 redirectTo: config.interactionRecovery?.redirectTo,
             },
             branding: config.branding,
+            // `firstPartyClients` manda; `branding.firstParty` é o fallback de
+            // back-compat. Nenhum dos dois declarado → `undefined` = sem allowlist.
+            firstPartyClients: config.firstPartyClients ?? config.branding?.firstParty,
             social: config.social,
             patIntrospectionSecret: config.patIntrospectionSecret,
             rateLimit: resolveRateLimit(config.rateLimit),

package/build/src/doctor/checks.d.ts

@@ -138,9 +138,11 @@ export declare function checkEmailChange(input: DoctorInput): Finding | null;
  */
 export declare function checkSecurityNotifications(input: DoctorInput): Finding | null;
 /**
- * Verifica a capability de histórico de senhas.
- * - Informa se a tabela `auth_password_history` está presente.
- * - Avisa quando pepper está configurado como string (não array) — rotation recomendada.
+ * Verifica o pepper de senha (`accountStore.password.pepper`).
+ * - Silencioso quando não há pepper configurado.
+ * - Reporta o pepper como string e sugere a forma `[novo, antigo]`, que permite
+ *   rotação sem downtime (lazy re-hash no verify).
+ * - Reporta quantos peppers a rotação tem quando já é array.
  */
 export declare function checkPasswordPepper(input: DoctorInput): Finding | null;
 /**
@@ -186,6 +188,16 @@ export declare function checkAccountExpiration(input: DoctorInput): Finding | nu
  * Informativo: se webauthn não estiver configurado, o autofill nunca será exibido.
  */
 export declare function checkPasskeyAutofill(input: DoctorInput): Finding | null;
+/**
+ * Allowlist de clients first-party — quem recebe as claims de autorização
+ * (`<globalRolesClaim>`, `org_id`, `org_slug`, `org_role`).
+ *
+ * Informativa quando declarada. `warn` quando NÃO declarada, porque aí todo
+ * client registrado recebe as claims ao pedir `scope=roles` — o que é o default
+ * certo (o oposto apagava as roles de todo RP), mas um host que registra clients
+ * de TERCEIROS precisa saber que existe uma lista para fechar.
+ */
+export declare function checkFirstPartyClients(input: DoctorInput): Finding | null;
 /**
  * Finding da idade da chave de assinatura managed. `ageDays === null` (sem
  * keystore em arquivo/cofre) → no-op `ok`. Acima de `maxAgeDays` → `warn`.

package/build/src/doctor/checks.js

@@ -573,9 +573,11 @@ export function checkSecurityNotifications(input) {
     return null; // Silencioso quando tudo está ok (não-obrigatório).
 }
 /**
- * Verifica a capability de histórico de senhas.
- * - Informa se a tabela `auth_password_history` está presente.
- * - Avisa quando pepper está configurado como string (não array) — rotation recomendada.
+ * Verifica o pepper de senha (`accountStore.password.pepper`).
+ * - Silencioso quando não há pepper configurado.
+ * - Reporta o pepper como string e sugere a forma `[novo, antigo]`, que permite
+ *   rotação sem downtime (lazy re-hash no verify).
+ * - Reporta quantos peppers a rotação tem quando já é array.
  */
 export function checkPasswordPepper(input) {
     const store = input.authkitConfig?.accountStore;
@@ -780,6 +782,41 @@ export function checkPasskeyAutofill(input) {
             'Requires browsers with PublicKeyCredential.isConditionalMediationAvailable() support.',
     };
 }
+/**
+ * Allowlist de clients first-party — quem recebe as claims de autorização
+ * (`<globalRolesClaim>`, `org_id`, `org_slug`, `org_role`).
+ *
+ * Informativa quando declarada. `warn` quando NÃO declarada, porque aí todo
+ * client registrado recebe as claims ao pedir `scope=roles` — o que é o default
+ * certo (o oposto apagava as roles de todo RP), mas um host que registra clients
+ * de TERCEIROS precisa saber que existe uma lista para fechar.
+ */
+export function checkFirstPartyClients(input) {
+    const cfg = input.authkitConfig;
+    if (!cfg)
+        return null;
+    const allowlist = cfg.firstPartyClients;
+    if (allowlist === undefined) {
+        return {
+            level: 'warn',
+            message: 'firstPartyClients is not declared: every registered client that requests `scope=roles` ' +
+                'receives the roles and organization claims. That is the default on purpose — the claims ' +
+                'are already gated by client registration and by the requested scope. Declare ' +
+                '`firstPartyClients: [...]` in config/authkit.ts to restrict them to your own apps.',
+        };
+    }
+    if (allowlist.length === 0) {
+        return {
+            level: 'ok',
+            message: 'firstPartyClients is an empty list: NO client receives the roles/organization claims. ' +
+                'Remove the key entirely if you meant "no restriction".',
+        };
+    }
+    return {
+        level: 'ok',
+        message: `firstPartyClients: ${allowlist.length} client(s) receive the roles/organization claims (${allowlist.join(', ')}).`,
+    };
+}
 /**
  * Finding da idade da chave de assinatura managed. `ageDays === null` (sem
  * keystore em arquivo/cofre) → no-op `ok`. Acima de `maxAgeDays` → `warn`.
@@ -875,6 +912,9 @@ export function runAllChecks(input) {
     const passkeyAutofill = checkPasskeyAutofill(input);
     if (passkeyAutofill)
         findings.push(passkeyAutofill);
+    const firstPartyClients = checkFirstPartyClients(input);
+    if (firstPartyClients)
+        findings.push(firstPartyClients);
     return findings;
 }
 /** Há algum finding de nível 'error'? (define o exit code). */

package/build/src/host/admin_api/admin_orgs_service.d.ts

@@ -1,3 +1,4 @@
+import type { HttpContext } from '@adonisjs/core/http';
 import type { OrgInvitation, OrgMember, OrgSummary } from '../../accounts/account_store.js';
 import type { ResolvedServerConfig } from '../../define_config.js';
 import type { SettingsCapability } from '../runtime_settings.js';
@@ -109,8 +110,14 @@ export declare class AdminOrgsService {
         ok: false;
         reason: 'member_not_found';
     }>;
-    /** Cria um convite por e-mail. Dispara o mail hook quando configurado. */
-    createInvitation(orgId: string, input: CreateInvitationInput, actor: AdminActor, origin: string, settings?: SettingsCapability | null): Promise<{
+    /**
+     * Cria um convite por e-mail. Dispara o mail hook quando configurado.
+     *
+     * `ctx` is optional only for back-compat with callers that have no request in
+     * hand; when given (both HTTP call sites do), the library default invitation
+     * email is sent whenever the host defines no `mail.onOrgInvitation` hook.
+     */
+    createInvitation(orgId: string, input: CreateInvitationInput, actor: AdminActor, origin: string, settings?: SettingsCapability | null, ctx?: HttpContext): Promise<{
         ok: true;
         invitation: OrgInvitation;
         token: string;

package/build/src/host/admin_api/admin_orgs_service.js

@@ -1,5 +1,6 @@
 import { supportsOrganizations } from '../../accounts/account_store.js';
 import { accountPath } from '../account_paths.js';
+import { sendOrgInvitationEmail } from '../default_mailer.js';
 import { isRoleInCatalog, resolveRoleCatalogList } from '../runtime_toggles.js';
 /**
  * Lógica de gestão de organizações compartilhada entre o console admin (HTML)
@@ -247,8 +248,14 @@ export class AdminOrgsService {
         });
         return { ok: true };
     }
-    /** Cria um convite por e-mail. Dispara o mail hook quando configurado. */
-    async createInvitation(orgId, input, actor, origin, settings = null) {
+    /**
+     * Cria um convite por e-mail. Dispara o mail hook quando configurado.
+     *
+     * `ctx` is optional only for back-compat with callers that have no request in
+     * hand; when given (both HTTP call sites do), the library default invitation
+     * email is sent whenever the host defines no `mail.onOrgInvitation` hook.
+     */
+    async createInvitation(orgId, input, actor, origin, settings = null, ctx) {
         const store = this.cfg.accountStore;
         if (!supportsOrganizations(store))
             return { ok: false, reason: 'not_supported' };
@@ -266,24 +273,30 @@ export class AdminOrgsService {
             invitedBy: actor.actorId ?? 'admin',
             ttlHours: this.cfg.organizations.invitationTtlHours,
         });
-        // Dispara mail hook (best-effort)
-        if (this.cfg.mail?.onOrgInvitation) {
+        // Sends the invitation email (best-effort). The host hook wins when present;
+        // otherwise the host-kit sends its own branded/translated email, like every
+        // other email of the library. Delivery NEVER breaks invitation creation.
+        try {
             const acceptUrl = `${origin}${accountPath('orgs')}/invitations/${token}/accept`;
-            try {
-                await this.cfg.mail.onOrgInvitation({
-                    email: input.email,
-                    invitationId: invitation.id,
-                    orgName: org.name,
-                    orgSlug: org.slug,
-                    role: input.role,
-                    acceptUrl,
-                    token,
-                });
+            const payload = {
+                email: input.email,
+                invitationId: invitation.id,
+                orgName: org.name,
+                orgSlug: org.slug,
+                role: input.role,
+                acceptUrl,
+                token,
+            };
+            if (this.cfg.mail?.onOrgInvitation) {
+                await this.cfg.mail.onOrgInvitation(payload);
             }
-            catch {
-                // best-effort
+            else if (ctx) {
+                await sendOrgInvitationEmail(ctx, payload);
             }
         }
+        catch {
+            // best-effort
+        }
         await this.cfg.audit?.record({
             type: 'organization.invitation_sent',
             actorId: actor.actorId,

package/build/src/host/admin_api/api_orgs_controller.js

@@ -160,7 +160,7 @@ export default class ApiOrgsController {
         const orgId = ctx.request.param('id');
         const { email, role } = await ctx.request.validateUsing(orgInvitationValidator);
         const origin = authkitOrigin(cfg);
-        const result = await svc.createInvitation(orgId, { email, role: role ?? 'member' }, actor, origin, await resolveRuntimeSettings(ctx));
+        const result = await svc.createInvitation(orgId, { email, role: role ?? 'member' }, actor, origin, await resolveRuntimeSettings(ctx), ctx);
         if (!result.ok) {
             if (result.reason === 'not_supported')
                 return notSupported(ctx);

package/build/src/host/admin_api/dto.d.ts

@@ -49,7 +49,7 @@ export declare function grantDto(grant: AdminGrant): {
 };
 export declare function auditDto(event: StoredAuditEvent): {
     id: string;
-    type: import("../../audit/audit_sink.js").AuditEventType;
+    type: "login.success" | "login.failure" | "signup" | "password_reset.issued" | "password_reset.consumed" | "pat.issued" | "pat.revoked" | "pat.used" | "impersonation" | "impersonation.panel_viewed" | "mfa.enabled" | "mfa.disabled" | "account.locked" | "passkey.registered" | "passkey.removed" | "email_verification.issued" | "email_verification.consumed" | "client.created" | "client.updated" | "client.deleted" | "session.revoked_all" | "password.changed" | "password.rehashed" | "email.change_requested" | "email.changed" | "login.new_ip_notified" | "login.new_device" | "login.otp_sent" | "login.otp_verified" | "login.otp_failed" | "login.otp_invalidated" | "bot_protection.rejected" | "grant.revoked_by_user" | "user.created" | "user.password_reset_sent" | "user.disabled" | "user.enabled" | "user.deleted" | "profile.updated" | "account.deleted" | "account.exported" | "keys.rotated" | "organization.created" | "organization.updated" | "organization.deleted" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.deactivated" | "organization.invitation_sent" | "organization.invitation_accepted" | "organization.invitation_revoked" | "email_change.requested" | "email_change.confirmed" | "email_change.cancelled" | "security_notice.sent" | "settings.updated" | "maintenance.enabled" | "maintenance.disabled" | "trusted_device.revoked" | "password.expired_change_forced" | "otp.locked" | "otp.unlocked" | "otp.unlock_failed" | "sudo.confirmed" | "session.single_enforced" | "account.expired_login_blocked" | "account.expiration_warned" | "login.magic_link_sent" | "session.revoked" | "account.signed_out_all" | "client.secret_regenerated" | "roles_catalog.updated";
     accountId: string | null;
     email: string | null;
     clientId: string | null;