@adonis-agora/authkit-server 0.34.0

package/build/src/events/dispatcher.d.ts

@@ -0,0 +1,45 @@
+import type { AuditEvent, AuditSink } from "../audit/audit_sink.js";
+/**
+ * Configuração de eventos/webhooks para o host observar tudo que o IdP audita.
+ *
+ *   - `onEvent`: callback in-process disparado para CADA evento de auditoria
+ *     (best-effort, fire-and-forget). Útil para encaminhar a um bus interno.
+ *   - `webhook`: POST JSON do evento para uma URL externa. Quando `secret` é dado,
+ *     assina o corpo com HMAC-SHA256 no header `x-authkit-signature`.
+ *
+ * Nada aqui pode lançar para dentro do caminho da request: todo erro é engolido.
+ */
+export interface EventsConfigInput {
+    /** Callback in-process para cada evento auditado (best-effort). */
+    onEvent?: (event: AuditEvent) => void | Promise<void>;
+    /** Webhook HTTP: POST do evento em JSON. */
+    webhook?: {
+        /** URL de destino do POST. */
+        url: string;
+        /** Segredo opcional para assinar o corpo (HMAC-SHA256). */
+        secret?: string;
+    };
+}
+export interface ResolvedEventsConfig {
+    onEvent?: (event: AuditEvent) => void | Promise<void>;
+    webhook?: {
+        url: string;
+        secret?: string;
+    };
+}
+export declare function resolveEvents(input?: EventsConfigInput): ResolvedEventsConfig | undefined;
+/**
+ * Constrói o corpo JSON canônico do webhook a partir de um evento de auditoria.
+ * O `ts` é o instante do dispatch (ISO 8601).
+ */
+export declare function buildWebhookBody(event: AuditEvent): string;
+/** Calcula o header de assinatura `sha256=<hmac>` para um corpo + segredo. */
+export declare function signWebhookBody(body: string, secret: string): string;
+/**
+ * Decora um AuditSink (ou cria um do zero) num sink fan-out: cada `record`
+ * persiste no sink original (se houver) E dispara onEvent + webhook. Falhas em
+ * qualquer ramo são isoladas — uma não impede as outras nem a request.
+ *
+ * `list` é delegado ao sink original quando existir (preserva a consulta admin).
+ */
+export declare function composeAuditSink(original: AuditSink | undefined, events?: ResolvedEventsConfig): AuditSink;

package/build/src/events/dispatcher.js

@@ -0,0 +1,117 @@
+import { createHmac } from "node:crypto";
+import { emitDiagnostic } from "../observability/diagnostics_bridge.js";
+export function resolveEvents(input) {
+    if (!input || (!input.onEvent && !input.webhook))
+        return undefined;
+    return {
+        onEvent: input.onEvent,
+        webhook: input.webhook,
+    };
+}
+/** Timeout (ms) do POST do webhook antes de abortar. */
+const WEBHOOK_TIMEOUT_MS = 5000;
+/**
+ * Constrói o corpo JSON canônico do webhook a partir de um evento de auditoria.
+ * O `ts` é o instante do dispatch (ISO 8601).
+ */
+export function buildWebhookBody(event) {
+    return JSON.stringify({
+        type: event.type,
+        accountId: event.accountId ?? null,
+        email: event.email ?? null,
+        clientId: event.clientId ?? null,
+        ip: event.ip ?? null,
+        metadata: event.metadata ?? {},
+        ts: new Date().toISOString(),
+    });
+}
+/** Calcula o header de assinatura `sha256=<hmac>` para um corpo + segredo. */
+export function signWebhookBody(body, secret) {
+    return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+}
+/**
+ * Dispara o webhook de forma fire-and-forget: timeout de 5s via AbortSignal,
+ * captura QUALQUER erro (rede, abort, HMAC) sem propagar. Nunca lança.
+ */
+async function dispatchWebhook(webhook, event) {
+    try {
+        const body = buildWebhookBody(event);
+        const headers = {
+            "content-type": "application/json",
+        };
+        if (webhook.secret) {
+            headers["x-authkit-signature"] = signWebhookBody(body, webhook.secret);
+        }
+        await fetch(webhook.url, {
+            method: "POST",
+            headers,
+            body,
+            signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // best-effort: erro de webhook nunca quebra o caminho da request.
+    }
+}
+/**
+ * Decora um AuditSink (ou cria um do zero) num sink fan-out: cada `record`
+ * persiste no sink original (se houver) E dispara onEvent + webhook. Falhas em
+ * qualquer ramo são isoladas — uma não impede as outras nem a request.
+ *
+ * `list` é delegado ao sink original quando existir (preserva a consulta admin).
+ */
+export function composeAuditSink(original, events = {}) {
+    const composed = {
+        async record(event) {
+            // Persistência original (best-effort, isolada).
+            if (original) {
+                try {
+                    await original.record(event);
+                }
+                catch {
+                    // sink original com defeito não impede os demais ramos.
+                }
+            }
+            // Callback in-process (best-effort, isolado).
+            if (events.onEvent) {
+                try {
+                    await events.onEvent(event);
+                }
+                catch {
+                    // onEvent com defeito não quebra a request.
+                }
+            }
+            // Webhook fire-and-forget (não aguardamos a entrega).
+            if (events.webhook) {
+                void dispatchWebhook(events.webhook, event);
+            }
+            // Diagnostics Agora (best-effort, sempre ligado, no-op sem o slot).
+            // Canal: `agora:authkit:<AuditEventType>` (o `type` É o sufixo).
+            emitDiagnostic(event.type, event);
+        },
+    };
+    // Preserva a capacidade de consulta do sink original (console admin).
+    if (original && typeof original.list === "function") {
+        composed.list = original.list.bind(original);
+    }
+    // Preserva a anonimização (LGPD) do sink original (deleção de conta).
+    if (original && typeof original.anonymizeAccount === "function") {
+        composed.anonymizeAccount = original.anonymizeAccount.bind(original);
+    }
+    // Preserva quaisquer propriedades extras do sink original (ex.: campos de
+    // introspecção/diagnóstico que sinks customizados expõem) — o fan-out é um
+    // decorador transparente sobre a superfície do sink original. Funções são
+    // re-ligadas ao original para manter o `this`; métodos já tratados acima e o
+    // `record` (sobrescrito) não são copiados.
+    if (original) {
+        const src = original;
+        const dst = composed;
+        for (const key of Object.keys(src)) {
+            if (key === "record" || key === "list" || key === "anonymizeAccount")
+                continue;
+            const value = src[key];
+            dst[key] = typeof value === "function" ? value.bind(original) : value;
+        }
+    }
+    return composed;
+}

package/build/src/host/account_api/account_api_controller.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Account Self-Service JSON API
+ *
+ * Endpoints JSON sob `/account/api/*` (session-authed via accountGuard, mutating
+ * com CSRF). Reusa a lógica dos controllers de conta existentes sem duplicar regras.
+ *
+ * Mapa de rotas:
+ *   GET  /account/api/me                    → perfil + flags
+ *   GET  /account/api/security              → overview de segurança (sessões, MFA, etc.)
+ *   PATCH /account/api/profile              → atualizar nome/avatar
+ *   POST /account/api/password              → trocar senha (sudo + senha atual)
+ *   POST /account/api/email-change          → solicitar troca de e-mail (sudo)
+ *   POST /account/api/email-change/cancel   → cancelar troca pendente
+ *   GET  /account/api/sessions              → sessões ativas
+ *   DELETE /account/api/sessions/:id        → revogar uma sessão
+ *   POST /account/api/sessions/revoke-others → revogar todas exceto a atual
+ *   POST /account/api/sessions/revoke-all   → revogar TODAS + logout global (signedOut: true)
+ *   GET  /account/api/apps                  → grants (apps autorizados)
+ *   DELETE /account/api/apps/:clientId      → revogar consentimento de um app
+ *   GET  /account/api/mfa                   → status MFA (totp + passkeys + recovery)
+ *   GET  /account/api/passkeys              → lista passkeys
+ *   DELETE /account/api/passkeys/:id        → remover passkey
+ *   GET  /account/api/tokens               → lista PATs
+ *   POST /account/api/tokens               → criar PAT (sudo)
+ *   DELETE /account/api/tokens/:id         → revogar PAT (sudo)
+ *   GET  /account/api/orgs                 → lista orgs do usuário
+ *   GET  /account/api/orgs/:id             → detalhe de org (requer membership)
+ *   GET  /account/api/orgs/invitations     → convites pendentes
+ */
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+export default class AccountApiController {
+    /** Perfil + flags do usuário logado. */
+    me(ctx: HttpContext): Promise<void | {
+        id: any;
+        email: any;
+        emailVerified: any;
+        name: any;
+        avatarUrl: any;
+        globalRoles: any;
+        hasPassword: boolean;
+        mfaEnabled: boolean;
+        passkeyCount: number;
+        sudoActive: boolean;
+        capabilities: {
+            securitySupported: boolean;
+            profileSupported: boolean;
+            passkeysSupported: boolean;
+            orgsSupported: boolean;
+            tokensSupported: boolean;
+            avatarUploadSupported: boolean;
+            sessionsSupported: boolean;
+        };
+    }>;
+    /** Overview de segurança: sessões ativas, status MFA, passkeys, last pw change. */
+    securityOverview(ctx: HttpContext): Promise<void | {
+        email: any;
+        pendingEmail: any;
+        securitySupported: boolean;
+        profileSupported: boolean;
+        sessionsSupported: boolean;
+        activeSessions: {
+            id: string;
+            loginTs: string | null;
+            browser: string | null;
+            os: string | null;
+            ip: string | null;
+            location: string | null;
+            amr: string[];
+        }[];
+        mfa: {
+            enabled: boolean;
+            totpEnrolled: boolean;
+            passkeyCount: number;
+            passkeysSupported: boolean;
+        };
+    }>;
+    /** Atualizar nome + avatar do perfil. */
+    updateProfile(ctx: HttpContext): Promise<void | {
+        id: string;
+        name: string | null;
+        avatarUrl: string | null;
+    }>;
+    /** Trocar senha. Exige sudo + senha atual (mesmo comportamento da tela). */
+    changePassword(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+    }>;
+    /** Solicitar troca de e-mail. Exige sudo. */
+    requestEmailChange(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        email: string;
+    }>;
+    /** Cancelar troca de e-mail pendente. */
+    cancelEmailChange(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+    }>;
+    /** Sessões ativas do usuário logado. */
+    listSessions(ctx: HttpContext): Promise<{
+        supported: boolean;
+        sessions: {
+            id: string;
+            loginTs: string | null;
+            browser: string | null;
+            os: string | null;
+            ip: string | null;
+            location: string | null;
+            amr: string[];
+        }[];
+    }>;
+    /** Revogar uma sessão específica (verifica que pertence ao usuário logado). */
+    revokeSession(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        revoked: string;
+    }>;
+    /** Revogar todas as sessões exceto a atual (identificada pelo cookie de sessão). */
+    revokeOtherSessions(ctx: HttpContext): Promise<void | {
+        sessions: number;
+        grants: number;
+        accessTokens: number;
+        refreshTokens: number;
+        ok: boolean;
+    }>;
+    /**
+     * Revogar TODAS as sessões OIDC + grants/tokens da conta e encerrar a sessão
+     * Adonis do console (logout global). Retorna `{ ok, signedOut: true }` para que
+     * a UI redirecione para o login.
+     *
+     * i18n keys: account.sessions.revoke_all_success (unused server-side — JSON API)
+     */
+    revokeAllSessions(ctx: HttpContext): Promise<void | {
+        sessions: number;
+        grants: number;
+        accessTokens: number;
+        refreshTokens: number;
+        ok: boolean;
+        signedOut: boolean;
+    }>;
+    /** Apps com acesso (grants) do usuário logado. */
+    listApps(ctx: HttpContext): Promise<{
+        supported: boolean;
+        apps: {
+            clientId: string;
+            accessTokens: number;
+            refreshTokens: number;
+        }[];
+    }>;
+    /** Revogar consentimento de um app (clientId). */
+    revokeApp(ctx: HttpContext): Promise<void | {
+        sessions: number;
+        grants: number;
+        accessTokens: number;
+        refreshTokens: number;
+        ok: boolean;
+    }>;
+    /** Status completo do MFA: TOTP + passkeys + recovery. */
+    mfaStatus(ctx: HttpContext): Promise<{
+        enabled: any;
+        totp: {
+            enrolled: any;
+        };
+        passkeys: {
+            supported: boolean;
+            count: number;
+            items: {
+                id: string;
+                label: string | null;
+                createdAt: string;
+            }[];
+        };
+        recovery: {
+            available: any;
+        };
+    }>;
+    /** Lista passkeys do usuário logado. */
+    listPasskeys(ctx: HttpContext): Promise<{
+        supported: boolean;
+        passkeys: any;
+    }>;
+    /** Remover uma passkey. Exige sudo. */
+    removePasskey(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        removed: string;
+    }>;
+    /** Lista PATs (Personal Access Tokens) do usuário logado. */
+    listTokens(ctx: HttpContext): Promise<{
+        supported: boolean;
+        tokens: any;
+    }>;
+    /** Criar um PAT. Exige sudo. O secret é retornado UMA vez. */
+    createToken(ctx: HttpContext): Promise<void | {
+        id: any;
+        name: any;
+        scopes: any;
+        audience: any;
+        createdAt: any;
+        secret: any;
+    }>;
+    /** Revogar um PAT. Exige sudo. */
+    revokeToken(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        revoked: string;
+    }>;
+    /** Lista orgs do usuário logado. Alias consolidado dos /account/orgs/json existentes. */
+    listOrgs(ctx: HttpContext): Promise<{
+        supported: boolean;
+        activeOrgId: any;
+        orgs: {
+            id: string;
+            name: string;
+            slug: string;
+            logoUrl: string | null;
+            role: string;
+            isActive: boolean;
+        }[];
+    }>;
+    /** Detalhe de uma org (requer membership). */
+    showOrg(ctx: HttpContext): Promise<void | {
+        id: string;
+        name: string;
+        slug: string;
+        logoUrl: string | null;
+        role: string;
+        canManage: boolean;
+        members: {
+            accountId: string;
+            email: string | null;
+            role: string;
+            joinedAt: string;
+        }[];
+    }>;
+    /** Convites pendentes para o e-mail do usuário logado. */
+    listOrgInvitations(ctx: HttpContext): Promise<void | {
+        supported: boolean;
+        invitations: {
+            id: string;
+            organizationId: string;
+            orgName: string;
+            orgSlug: string;
+            email: string;
+            role: string;
+            expiresAt: string;
+            createdAt: string;
+        }[];
+    }>;
+}