@adonis-agora/authkit-server 0.57.1 → 0.58.0

package/build/src/host/controllers/account_orgs_controller.js

@@ -3,6 +3,7 @@ import { supportsOrganizations } from '../../accounts/account_store.js';
 import { getAccountLoginUrl } from '../account_login_url.js';
 import { accountPath } from '../account_paths.js';
 import { ACTIVE_ORG_COOKIE, ACTIVE_ORG_COOKIE_TTL, encodeActiveOrgCookie, } from '../active_org_cookie.js';
+import { sendOrgInvitationEmail } from '../default_mailer.js';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
 import { authkitOrigin } from '../origin.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
@@ -188,25 +189,31 @@ export default class AccountOrgsController {
             invitedBy: accountId,
             ttlHours: cfg.organizations.invitationTtlHours,
         });
-        // Dispara e-mail via mail hook (best-effort)
-        if (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 org = await store.findOrgById(params.id);
             const acceptUrl = `${authkitOrigin(cfg)}${accountPath('orgs')}/invitations/${token}/accept`;
-            try {
-                await cfg.mail.onOrgInvitation({
-                    email,
-                    invitationId: invitation.id,
-                    orgName: org?.name ?? params.id,
-                    orgSlug: org?.slug ?? params.id,
-                    role,
-                    acceptUrl,
-                    token,
-                });
+            const payload = {
+                email,
+                invitationId: invitation.id,
+                orgName: org?.name ?? params.id,
+                orgSlug: org?.slug ?? params.id,
+                role,
+                acceptUrl,
+                token,
+            };
+            if (cfg.mail?.onOrgInvitation) {
+                await cfg.mail.onOrgInvitation(payload);
             }
-            catch {
-                // best-effort
+            else {
+                await sendOrgInvitationEmail(ctx, payload);
             }
         }
+        catch {
+            // best-effort
+        }
         await cfg.audit?.record({
             type: 'organization.invitation_sent',
             accountId,

package/build/src/host/default_mailer.d.ts

@@ -134,6 +134,27 @@ export declare function sendOtpUnlockEmail(ctx: HttpContext, data: {
     email: string;
     unlockUrl: string;
 }): Promise<void>;
+/**
+ * Sends the organization invitation email through the host default mailer.
+ *
+ * WHY IT EXISTS. `mail.onOrgInvitation` used to be the ONLY hook without a
+ * default-mailer fallback: without it the invitation row was created and NO
+ * email was ever sent — a silent failure where the invited person never learned
+ * about the invitation. This restores the same posture as every other email of
+ * the library: the host hook wins when present, otherwise the host-kit itself
+ * sends a branded/translated email; with no mailer at all, the link is logged (dev).
+ *
+ * Best-effort: never throws — invitation creation must not depend on delivery.
+ */
+export declare function sendOrgInvitationEmail(ctx: HttpContext, data: {
+    email: string;
+    invitationId: string;
+    orgName: string;
+    orgSlug: string;
+    role: string;
+    acceptUrl: string;
+    token: string;
+}): Promise<void>;
 /**
  * Envia o e-mail de verificação pelo mailer default do host.
  * Best-effort: no fallback (sem mail) loga o link; nunca lança.

package/build/src/host/default_mailer.js

@@ -475,6 +475,47 @@ export async function sendOtpUnlockEmail(ctx, data) {
         ctx.logger.error({ err: error, email: data.email }, 'authkit: falha ao enviar e-mail de desbloqueio OTP');
     }
 }
+/**
+ * Sends the organization invitation email through the host default mailer.
+ *
+ * WHY IT EXISTS. `mail.onOrgInvitation` used to be the ONLY hook without a
+ * default-mailer fallback: without it the invitation row was created and NO
+ * email was ever sent — a silent failure where the invited person never learned
+ * about the invitation. This restores the same posture as every other email of
+ * the library: the host hook wins when present, otherwise the host-kit itself
+ * sends a branded/translated email; with no mailer at all, the link is logged (dev).
+ *
+ * Best-effort: never throws — invitation creation must not depend on delivery.
+ */
+export async function sendOrgInvitationEmail(ctx, data) {
+    try {
+        const brand = resolveBrand(ctx);
+        const { messages: t, locale } = resolveMailMessages(ctx);
+        const content = renderTransactionalEmail({
+            brand,
+            locale,
+            linkFallback: translate(t, 'mail.common.link_fallback'),
+            subject: translate(t, 'mail.org_invitation.subject', { org: data.orgName }),
+            heading: translate(t, 'mail.org_invitation.heading', { org: data.orgName }),
+            intro: translate(t, 'mail.org_invitation.intro', { org: data.orgName, role: data.role }),
+            ctaLabel: translate(t, 'mail.org_invitation.cta'),
+            ctaUrl: data.acceptUrl,
+            footnote: translate(t, 'mail.org_invitation.fallback'),
+        });
+        const sent = await sendEmail(ctx, data.email, content);
+        if (!sent) {
+            ctx.logger?.info({
+                acceptUrl: data.acceptUrl,
+                email: data.email,
+                orgSlug: data.orgSlug,
+                invitationId: data.invitationId,
+            }, 'authkit: convite de organização (dev — @adonisjs/mail ausente)');
+        }
+    }
+    catch (error) {
+        ctx.logger?.error({ err: error, email: data.email, orgSlug: data.orgSlug }, 'authkit: falha ao enviar convite de organização');
+    }
+}
 /**
  * Envia o e-mail de verificação pelo mailer default do host.
  * Best-effort: no fallback (sem mail) loga o link; nunca lança.

package/build/src/host/i18n.d.ts

@@ -570,6 +570,11 @@ export declare const DEFAULT_MESSAGES: {
     'mail.security_notice.kind_passkey_added': string;
     'mail.security_notice.kind_passkey_removed': string;
     'mail.security_notice.kind_email_changed': string;
+    'mail.org_invitation.subject': string;
+    'mail.org_invitation.heading': string;
+    'mail.org_invitation.intro': string;
+    'mail.org_invitation.cta': string;
+    'mail.org_invitation.fallback': string;
     'mail.otp_unlock.subject': string;
     'mail.otp_unlock.heading': string;
     'mail.otp_unlock.intro': string;
@@ -1309,6 +1314,11 @@ export declare const PT_BR_MESSAGES: {
     'admin.settings.sudo_mode_from_config': string;
     'admin.settings.sudo_mode_from_setting': string;
     'admin.settings.sudo_mode_grace_label': string;
+    'mail.org_invitation.subject': string;
+    'mail.org_invitation.heading': string;
+    'mail.org_invitation.intro': string;
+    'mail.org_invitation.cta': string;
+    'mail.org_invitation.fallback': string;
     'mail.otp_unlock.subject': string;
     'mail.otp_unlock.heading': string;
     'mail.otp_unlock.intro': string;

package/build/src/host/i18n.js

@@ -323,7 +323,7 @@ export const DEFAULT_MESSAGES = {
     'admin.impersonation.title': 'Impersonate this user',
     'admin.impersonation.help': 'Token Exchange (RFC 8693) lets an admin act as this user. There is no auth bypass: you exchange YOUR OWN admin access token for one scoped to the target.',
     'admin.impersonation.curl_label': 'Ready-to-run request',
-    'admin.impersonation.note': 'Replace <ADMIN_ACCESS_TOKEN> with a current admin access token. The resulting id_token carries act={sub: admin}; the event is audited as impersonation.started.',
+    'admin.impersonation.note': 'Replace <ADMIN_ACCESS_TOKEN> with a current admin access token. The resulting id_token carries act={sub: admin}; the exchange is audited as impersonation.',
     'admin.impersonation.no_client': 'No client has the token-exchange grant enabled. Add "urn:ietf:params:oauth:grant-type:token-exchange" to a client to enable impersonation.',
     // Console admin — clients.
     'admin.clients.page_title': 'OAuth clients',
@@ -621,6 +621,13 @@ export const DEFAULT_MESSAGES = {
     'mail.security_notice.kind_passkey_added': 'passkey added',
     'mail.security_notice.kind_passkey_removed': 'passkey removed',
     'mail.security_notice.kind_email_changed': 'email address changed',
+    // E-mail de convite para organização (fallback quando o host não define o
+    // hook `mail.onOrgInvitation`).
+    'mail.org_invitation.subject': 'You have been invited to join {org}',
+    'mail.org_invitation.heading': 'You have been invited to join {org}',
+    'mail.org_invitation.intro': 'You have been invited to join the organization {org} as {role}. Accept the invitation to get access.',
+    'mail.org_invitation.cta': 'Accept invitation',
+    'mail.org_invitation.fallback': 'If you were not expecting this invitation, you can ignore this email.',
     // E-mail de desbloqueio do fator OTP.
     'mail.otp_unlock.subject': 'Two-factor authentication unlock',
     'mail.otp_unlock.heading': 'Unlock your two-factor authentication',
@@ -1161,7 +1168,7 @@ export const PT_BR_MESSAGES = {
     'admin.impersonation.title': 'Personificar este usuário',
     'admin.impersonation.help': 'O Token Exchange (RFC 8693) permite que um admin aja como este usuário. Não há bypass de auth: você troca o SEU PRÓPRIO access token de admin por um escopado ao alvo.',
     'admin.impersonation.curl_label': 'Requisição pronta para rodar',
-    'admin.impersonation.note': 'Troque <ADMIN_ACCESS_TOKEN> por um access token de admin válido. O id_token resultante carrega act={sub: admin}; o evento é auditado como impersonation.started.',
+    'admin.impersonation.note': 'Troque <ADMIN_ACCESS_TOKEN> por um access token de admin válido. O id_token resultante carrega act={sub: admin}; o exchange é auditado como impersonation.',
     'admin.impersonation.no_client': 'Nenhum client tem o grant token-exchange habilitado. Adicione "urn:ietf:params:oauth:grant-type:token-exchange" a um client para habilitar a personificação.',
     // Console admin — clients.
     'admin.clients.page_title': 'Clients OAuth',
@@ -1443,6 +1450,12 @@ export const PT_BR_MESSAGES = {
     'admin.settings.sudo_mode_from_config': 'Fonte: padrão',
     'admin.settings.sudo_mode_from_setting': 'Fonte: setting em runtime',
     'admin.settings.sudo_mode_grace_label': 'Período de graça (minutos)',
+    // E-mail de convite para organização (pt-BR).
+    'mail.org_invitation.subject': 'Você foi convidado para {org}',
+    'mail.org_invitation.heading': 'Você foi convidado para {org}',
+    'mail.org_invitation.intro': 'Você foi convidado para participar da organização {org} como {role}. Aceite o convite para ter acesso.',
+    'mail.org_invitation.cta': 'Aceitar convite',
+    'mail.org_invitation.fallback': 'Se você não esperava este convite, pode ignorar este e-mail.',
     // E-mail de desbloqueio do fator OTP (pt-BR).
     'mail.otp_unlock.subject': 'Desbloqueio da verificação em duas etapas',
     'mail.otp_unlock.heading': 'Desbloqueie sua verificação em duas etapas',

package/build/src/host/impersonation.d.ts

@@ -17,9 +17,30 @@ export interface ImpersonationPanel {
     /** Comando curl pronto (subject_token como placeholder a preencher). */
     curl: string;
 }
+/**
+ * Um client candidato a hospedar o token-exchange. Modelado estruturalmente para
+ * aceitar tanto os clients ESTÁTICOS do config (`ResolvedServerConfig['clients']`,
+ * que trazem o secret) quanto os clients de RUNTIME lidos do adapter pelo
+ * `AdminClientsService` (que NÃO trazem o secret — ele não é recuperável).
+ */
+export interface ImpersonationClientLike {
+    clientId: string;
+    clientSecret?: string;
+    grants?: string[];
+    /** Runtime clients reportam confidencialidade sem expor o secret. */
+    confidential?: boolean;
+}
 /**
  * Monta o painel de impersonation para o `targetId`. Retorna `null` quando NENHUM
- * client da config tem o grant token-exchange habilitado (sem ele o fluxo não
+ * client candidato tem o grant token-exchange habilitado (sem ele o fluxo não
  * funciona) — a UI então mostra a instrução de habilitar o grant.
+ *
+ * ⚠️ `clients` é OBRIGATÓRIO na prática. `cfg.clients` é sempre `[]` num host
+ * real: clients são 100% de runtime (console admin / Admin API / `authkit:clients:create`),
+ * e o config resolvido nunca os carrega — é o que o `checkClients` do doctor
+ * afirma. Passar só o config faria o painel devolver `null` SEMPRE, que foi
+ * exatamente o bug: o botão do console nunca teve um client para oferecer.
+ * O fallback para `cfg.clients` existe só para hosts que ainda declaram clients
+ * estáticos e para os testes que os declaram.
  */
-export declare function buildImpersonationPanel(cfg: Pick<ResolvedServerConfig, 'issuer' | 'clients'>, targetId: string): ImpersonationPanel | null;
+export declare function buildImpersonationPanel(cfg: Pick<ResolvedServerConfig, 'issuer' | 'clients'>, targetId: string, clients?: readonly ImpersonationClientLike[]): ImpersonationPanel | null;

package/build/src/host/impersonation.js

@@ -1,17 +1,33 @@
 const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
 const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+/** Placeholder do secret quando o client é confidencial mas o secret não é legível. */
+const SECRET_PLACEHOLDER = '<CLIENT_SECRET>';
 /**
  * Monta o painel de impersonation para o `targetId`. Retorna `null` quando NENHUM
- * client da config tem o grant token-exchange habilitado (sem ele o fluxo não
+ * client candidato tem o grant token-exchange habilitado (sem ele o fluxo não
  * funciona) — a UI então mostra a instrução de habilitar o grant.
+ *
+ * ⚠️ `clients` é OBRIGATÓRIO na prática. `cfg.clients` é sempre `[]` num host
+ * real: clients são 100% de runtime (console admin / Admin API / `authkit:clients:create`),
+ * e o config resolvido nunca os carrega — é o que o `checkClients` do doctor
+ * afirma. Passar só o config faria o painel devolver `null` SEMPRE, que foi
+ * exatamente o bug: o botão do console nunca teve um client para oferecer.
+ * O fallback para `cfg.clients` existe só para hosts que ainda declaram clients
+ * estáticos e para os testes que os declaram.
  */
-export function buildImpersonationPanel(cfg, targetId) {
-    const client = cfg.clients.find((c) => (c.grants ?? []).includes(TOKEN_EXCHANGE));
+export function buildImpersonationPanel(cfg, targetId, clients) {
+    const candidates = clients && clients.length > 0 ? clients : (cfg.clients ?? []);
+    const client = candidates.find((c) => (c.grants ?? []).includes(TOKEN_EXCHANGE));
     if (!client)
         return null;
     const tokenEndpoint = `${cfg.issuer.replace(/\/+$/, '')}/token`;
-    const auth = client.clientSecret
-        ? `  -u '${client.clientId}:${client.clientSecret}' \\\n`
+    // Confidencial = tem secret conhecido, ou o adapter marcou como confidencial.
+    // No segundo caso o secret NÃO é recuperável (o adapter guarda o hash/valor
+    // opaco e a lib mostra o secret uma única vez na criação), então o curl sai
+    // com um placeholder em vez de mentir com uma string vazia.
+    const confidential = client.confidential ?? client.clientSecret !== undefined;
+    const auth = confidential
+        ? `  -u '${client.clientId}:${client.clientSecret ?? SECRET_PLACEHOLDER}' \\\n`
         : `  -d 'client_id=${client.clientId}' \\\n`;
     const curl = `curl -X POST '${tokenEndpoint}' \\\n${auth}  -d 'grant_type=${TOKEN_EXCHANGE}' \\\n  -d 'subject_token=<ADMIN_ACCESS_TOKEN>' \\\n  -d 'subject_token_type=${ACCESS_TOKEN_TYPE}' \\\n  -d 'requested_subject=${targetId}' \\\n  -d 'scope=openid profile email'`;
     return {