@adonis-agora/authkit-server 0.34.0

package/build/src/host/durable/account_export_workflow.d.ts

@@ -0,0 +1,68 @@
+import type { OidcService } from "../../provider/oidc_service.js";
+import type { DurableStepCtx } from "./account_deletion_workflow.js";
+/** Nome canônico do workflow durável de export de dados de conta. */
+export declare const ACCOUNT_EXPORT_WORKFLOW = "authkit.account.export";
+/** Input do workflow `authkit.account.export`. */
+export interface AccountExportWorkflowInput {
+    accountId: string;
+    /** IP da request, p/ auditoria (opcional). */
+    ip?: string | null;
+}
+/** Resultado do workflow de export (referência ao artefato persistido). */
+export interface AccountExportWorkflowResult {
+    ok: boolean;
+    /** Key/URL do artefato persistido no drive (quando persistido). */
+    artifactKey: string | null;
+    /** Bytes do payload serializado (diagnóstico). */
+    bytes: number;
+}
+/**
+ * Persiste o artefato (JSON serializado) e devolve a sua key/URL. O default usa o
+ * disk do drive do app (`@adonisjs/drive`), gravando em
+ * `<uploads.exports.directory>/authkit-data-export-<accountId>-<runId>.json`. O
+ * app pode injetar a sua própria implementação (ex.: S3 com URL assinada).
+ */
+export type PersistArtifact = (artifact: {
+    accountId: string;
+    runId: string;
+    json: string;
+    oidc: OidcService;
+}) => Promise<string | null>;
+/**
+ * Entrega o artefato ao titular: via signal durável (token `export:<runId>`)
+ * e/ou um link por e-mail. O default emite o signal (best-effort) — o app pluga
+ * o e-mail. Read-only quanto ao cascade (apenas notifica).
+ */
+export type DeliverArtifact = (delivery: {
+    accountId: string;
+    runId: string;
+    artifactKey: string | null;
+    oidc: OidcService;
+}) => Promise<void>;
+/** Deps que o app injeta ao definir o workflow de export. */
+export interface AccountExportWorkflowDeps {
+    oidc: () => OidcService | Promise<OidcService>;
+    /** Persistência do artefato (default: drive do app). */
+    persist?: PersistArtifact;
+    /** Entrega ao titular (default: no-op — o app pluga e-mail/signal). */
+    deliver?: DeliverArtifact;
+}
+/**
+ * Define a REGISTRAÇÃO do workflow durável `authkit.account.export`.
+ *
+ * Etapas (todas efeitos colaterais dentro de `ctx.step`, corpo determinístico):
+ *   1. `collect`  — reúne o payload (reusa {@link AccountExportService.collect});
+ *   2. `audit`    — registra `account.exported`;
+ *   3. `persist`  — serializa + grava o artefato no drive;
+ *   4. `deliver`  — notifica o titular (signal + link por e-mail, pluggable).
+ *
+ * Read-only + artefato → SEM compensação. Sub-fetches flaky podem ter retry
+ * por-etapa (a coleta é best-effort por dentro).
+ */
+export declare function defineAccountExportWorkflow(deps: AccountExportWorkflowDeps): {
+    name: string;
+    version: string;
+    body: (ctx: DurableStepCtx & {
+        runId?: string;
+    }, input: AccountExportWorkflowInput) => Promise<unknown>;
+};

package/build/src/host/durable/account_export_workflow.js

@@ -0,0 +1,93 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { AccountExportService, } from "../account_export_service.js";
+/** Nome canônico do workflow durável de export de dados de conta. */
+export const ACCOUNT_EXPORT_WORKFLOW = "authkit.account.export";
+/** Persistência default: grava o JSON no disk do drive do app (best-effort). */
+const defaultPersist = async ({ accountId, runId, json, oidc, }) => {
+    // Indireção via variável: `@adonisjs/drive` é peer/opcional — pode não estar
+    // instalado, então o specifier não é resolvido em build-time.
+    const specifier = "@adonisjs/drive/services/main";
+    let drive = null;
+    try {
+        const mod = await import(__rewriteRelativeImportExtension(specifier));
+        drive = mod.default ?? null;
+    }
+    catch {
+        return null;
+    }
+    if (!drive)
+        return null;
+    const cfg = oidc.config;
+    const exportsCfg = cfg.uploads.exports;
+    const directory = (exportsCfg?.directory ?? "authkit/exports").replace(/\/+$/, "");
+    const diskName = exportsCfg?.disk ?? cfg.uploads.avatars?.disk;
+    const key = `${directory}/authkit-data-export-${accountId}-${runId}.json`;
+    try {
+        const disk = diskName ? drive.use(diskName) : drive.use();
+        await disk.put(key, json, {
+            contentType: "application/json; charset=utf-8",
+        });
+        return key;
+    }
+    catch {
+        return null;
+    }
+};
+/** Entrega default: emite o signal `export:<runId>` (best-effort, fail-safe). */
+const noopDeliver = async () => { };
+/**
+ * Define a REGISTRAÇÃO do workflow durável `authkit.account.export`.
+ *
+ * Etapas (todas efeitos colaterais dentro de `ctx.step`, corpo determinístico):
+ *   1. `collect`  — reúne o payload (reusa {@link AccountExportService.collect});
+ *   2. `audit`    — registra `account.exported`;
+ *   3. `persist`  — serializa + grava o artefato no drive;
+ *   4. `deliver`  — notifica o titular (signal + link por e-mail, pluggable).
+ *
+ * Read-only + artefato → SEM compensação. Sub-fetches flaky podem ter retry
+ * por-etapa (a coleta é best-effort por dentro).
+ */
+export function defineAccountExportWorkflow(deps) {
+    const persist = deps.persist ?? defaultPersist;
+    const deliver = deps.deliver ?? noopDeliver;
+    const body = async (ctx, input) => {
+        const { accountId } = input;
+        const runId = ctx.runId ?? accountId;
+        // 1) Coleta o payload (reusa a coleta inline do AccountExportService).
+        const payload = await ctx.step("collect", async () => {
+            const oidc = await deps.oidc();
+            return new AccountExportService(oidc).collect(accountId);
+        });
+        if (!payload)
+            return { ok: false, artifactKey: null, bytes: 0 };
+        // 2) Audita o export (account.exported).
+        await ctx.step("audit", async () => {
+            const cfg = (await deps.oidc()).config;
+            await cfg.audit?.record({
+                type: "account.exported",
+                accountId,
+                ip: input.ip ?? null,
+            });
+        });
+        // 3) Serializa + persiste o artefato.
+        const json = JSON.stringify(payload, null, 2);
+        const artifactKey = await ctx.step("persist", async () => {
+            const oidc = await deps.oidc();
+            return persist({ accountId, runId, json, oidc });
+        });
+        // 4) Entrega ao titular (signal + e-mail, pluggable).
+        await ctx.step("deliver", async () => {
+            const oidc = await deps.oidc();
+            await deliver({ accountId, runId, artifactKey, oidc });
+        });
+        return { ok: true, artifactKey, bytes: json.length };
+    };
+    return { name: ACCOUNT_EXPORT_WORKFLOW, version: "1", body };
+}

package/build/src/host/durable/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Subpath OPT-IN: workflows duráveis para os fluxos LGPD/GDPR de deleção e export
+ * de conta. ISOLADO do barrel principal (`@adonis-agora/authkit-server`) — só é
+ * carregado quando o app importa `@adonis-agora/authkit-server/durable` e tem o
+ * peer OPCIONAL `@adonis-agora/durable` instalado.
+ *
+ * Quando o modo durável NÃO está ligado (config `accountLifecycle.durable`
+ * ausente/false), NADA aqui é importado e o comportamento síncrono de sempre
+ * permanece byte-idêntico.
+ *
+ * Wiring no app:
+ *
+ * ```ts
+ * import { WorkflowEngine } from '@adonis-agora/durable'
+ * import {
+ *   defineAccountDeletionWorkflow,
+ *   defineAccountExportWorkflow,
+ * } from '@adonis-agora/authkit-server/durable'
+ *
+ * const engine = await app.container.make(WorkflowEngine)
+ * const oidc = () => app.container.make('authkit.server')
+ * const del = defineAccountDeletionWorkflow({ oidc })
+ * const exp = defineAccountExportWorkflow({ oidc })
+ * engine.register(del.name, del.version, del.body)
+ * engine.register(exp.name, exp.version, exp.body)
+ * // ...e rode um worker (engine.runPending / runOne) p/ o grupo do authkit.
+ * ```
+ */
+import type { DeletionActor } from "../account_deletion_service.js";
+import { type AccountDeleteWorkflowInput } from "./account_deletion_workflow.js";
+import { type AccountExportWorkflowInput } from "./account_export_workflow.js";
+export { defineAccountDeletionWorkflow, ACCOUNT_DELETE_WORKFLOW, type AccountDeleteWorkflowInput, type AccountDeletionWorkflowDeps, type DurableStepCtx, type WorkflowBody, } from "./account_deletion_workflow.js";
+export { defineAccountExportWorkflow, ACCOUNT_EXPORT_WORKFLOW, type AccountExportWorkflowInput, type AccountExportWorkflowResult, type AccountExportWorkflowDeps, type PersistArtifact, type DeliverArtifact, } from "./account_export_workflow.js";
+/**
+ * Superfície mínima do `WorkflowEngine` que o enqueue usa (`start` idempotente por
+ * run-id). Tipada estruturalmente p/ NÃO acoplar o build ao peer opcional.
+ */
+export interface EnqueueEngine {
+    start(workflow: string, input: unknown, runId: string, opts?: unknown): Promise<unknown>;
+}
+/** Um resolver de container (`ctx.containerResolver` ou `app.container`). */
+export interface ContainerResolverLike {
+    make(binding: unknown): Promise<unknown>;
+}
+/**
+ * Resolve o `WorkflowEngine` do container — SÓ no caminho durável. Importa
+ * `@adonis-agora/durable` dinamicamente (peer opcional), então o barrel principal
+ * nunca o carrega. Lança uma mensagem clara se o peer não estiver instalado.
+ */
+export declare function resolveWorkflowEngine(resolver: ContainerResolverLike): Promise<EnqueueEngine>;
+/**
+ * Enfileira o workflow durável de deleção, idempotente por `accountId` (run-id =
+ * `authkit.account.delete:<accountId>` → requests duplicadas dedupam no mesmo run).
+ * Retorna o run-id usado.
+ */
+export declare function enqueueAccountDeletion(engine: EnqueueEngine, input: AccountDeleteWorkflowInput): Promise<string>;
+/**
+ * Enfileira o workflow durável de export. Idempotente por `accountId` no run-id —
+ * uma exportação em voo dedupa pedidos repetidos do mesmo titular.
+ */
+export declare function enqueueAccountExport(engine: EnqueueEngine, input: AccountExportWorkflowInput): Promise<string>;
+/**
+ * Constrói um callback `EnqueueDeletion` (para `AdminUsersService.delete`) a partir
+ * de um resolver de container — resolve o `WorkflowEngine` e enfileira o cascade.
+ */
+export declare function enqueueDeletionVia(resolver: ContainerResolverLike): (input: AccountDeleteWorkflowInput) => Promise<string>;
+/** Re-export por conveniência: o tipo do ator de deleção. */
+export type { DeletionActor };

package/build/src/host/durable/index.js

@@ -0,0 +1,77 @@
+/**
+ * Subpath OPT-IN: workflows duráveis para os fluxos LGPD/GDPR de deleção e export
+ * de conta. ISOLADO do barrel principal (`@adonis-agora/authkit-server`) — só é
+ * carregado quando o app importa `@adonis-agora/authkit-server/durable` e tem o
+ * peer OPCIONAL `@adonis-agora/durable` instalado.
+ *
+ * Quando o modo durável NÃO está ligado (config `accountLifecycle.durable`
+ * ausente/false), NADA aqui é importado e o comportamento síncrono de sempre
+ * permanece byte-idêntico.
+ *
+ * Wiring no app:
+ *
+ * ```ts
+ * import { WorkflowEngine } from '@adonis-agora/durable'
+ * import {
+ *   defineAccountDeletionWorkflow,
+ *   defineAccountExportWorkflow,
+ * } from '@adonis-agora/authkit-server/durable'
+ *
+ * const engine = await app.container.make(WorkflowEngine)
+ * const oidc = () => app.container.make('authkit.server')
+ * const del = defineAccountDeletionWorkflow({ oidc })
+ * const exp = defineAccountExportWorkflow({ oidc })
+ * engine.register(del.name, del.version, del.body)
+ * engine.register(exp.name, exp.version, exp.body)
+ * // ...e rode um worker (engine.runPending / runOne) p/ o grupo do authkit.
+ * ```
+ */
+import { ACCOUNT_DELETE_WORKFLOW, } from "./account_deletion_workflow.js";
+import { ACCOUNT_EXPORT_WORKFLOW, } from "./account_export_workflow.js";
+export { defineAccountDeletionWorkflow, ACCOUNT_DELETE_WORKFLOW, } from "./account_deletion_workflow.js";
+export { defineAccountExportWorkflow, ACCOUNT_EXPORT_WORKFLOW, } from "./account_export_workflow.js";
+/**
+ * Resolve o `WorkflowEngine` do container — SÓ no caminho durável. Importa
+ * `@adonis-agora/durable` dinamicamente (peer opcional), então o barrel principal
+ * nunca o carrega. Lança uma mensagem clara se o peer não estiver instalado.
+ */
+export async function resolveWorkflowEngine(resolver) {
+    let mod;
+    try {
+        mod = (await import("@adonis-agora/durable"));
+    }
+    catch {
+        throw new Error('[authkit] durable account-lifecycle is enabled but "@adonis-agora/durable" is not installed. ' +
+            "Add it as a dependency and register the workflows on your WorkflowEngine.");
+    }
+    return resolver.make(mod.WorkflowEngine);
+}
+/**
+ * Enfileira o workflow durável de deleção, idempotente por `accountId` (run-id =
+ * `authkit.account.delete:<accountId>` → requests duplicadas dedupam no mesmo run).
+ * Retorna o run-id usado.
+ */
+export async function enqueueAccountDeletion(engine, input) {
+    const runId = `${ACCOUNT_DELETE_WORKFLOW}:${input.accountId}`;
+    await engine.start(ACCOUNT_DELETE_WORKFLOW, input, runId);
+    return runId;
+}
+/**
+ * Enfileira o workflow durável de export. Idempotente por `accountId` no run-id —
+ * uma exportação em voo dedupa pedidos repetidos do mesmo titular.
+ */
+export async function enqueueAccountExport(engine, input) {
+    const runId = `${ACCOUNT_EXPORT_WORKFLOW}:${input.accountId}`;
+    await engine.start(ACCOUNT_EXPORT_WORKFLOW, input, runId);
+    return runId;
+}
+/**
+ * Constrói um callback `EnqueueDeletion` (para `AdminUsersService.delete`) a partir
+ * de um resolver de container — resolve o `WorkflowEngine` e enfileira o cascade.
+ */
+export function enqueueDeletionVia(resolver) {
+    return async (input) => {
+        const engine = await resolveWorkflowEngine(resolver);
+        return enqueueAccountDeletion(engine, input);
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Renderização de e-mails transacionais do host-kit (reset de senha / verificação).
+ *
+ * Sem dependências (template literals) e com HTML email-safe: estilos inline,
+ * layout em tabela centralizada, botão de CTA com a cor de acento da marca, e
+ * sempre um corpo `text` de fallback. Branding vem do `config/authkit.ts`
+ * (`branding.default` ou a marca do client). Tudo escapado para evitar injeção.
+ */
+export interface EmailContent {
+    subject: string;
+    html: string;
+    text: string;
+}
+interface EmailTemplateInput {
+    /** Marca usada no cabeçalho/botão/rodapé (accent/company opcionais). */
+    brand: {
+        appName: string;
+        accent?: string;
+        company?: string;
+    };
+    /** Assunto do e-mail. */
+    subject: string;
+    /** Saudação/título dentro do card. */
+    heading: string;
+    /** Parágrafo de introdução (texto puro, será escapado). */
+    intro: string;
+    /** Rótulo do botão de CTA. */
+    ctaLabel: string;
+    /** URL do CTA. */
+    ctaUrl: string;
+    /** Linha auxiliar abaixo do botão (ex.: validade do link). */
+    footnote?: string;
+    /** Texto que precede o link de fallback (i18n). Default em inglês. */
+    linkFallback?: string;
+    /** Locale do documento HTML (atributo `lang`). Default: 'en'. */
+    locale?: string;
+}
+export declare function renderTransactionalEmail(input: EmailTemplateInput): EmailContent;
+export {};

package/build/src/host/email_templates.js

@@ -0,0 +1,69 @@
+/**
+ * Renderização de e-mails transacionais do host-kit (reset de senha / verificação).
+ *
+ * Sem dependências (template literals) e com HTML email-safe: estilos inline,
+ * layout em tabela centralizada, botão de CTA com a cor de acento da marca, e
+ * sempre um corpo `text` de fallback. Branding vem do `config/authkit.ts`
+ * (`branding.default` ou a marca do client). Tudo escapado para evitar injeção.
+ */
+/** Escapa texto para interpolação segura em HTML. */
+function esc(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const FALLBACK_ACCENT = '#4f46e5';
+export function renderTransactionalEmail(input) {
+    const appName = input.brand.appName || input.brand.company || 'AuthKit';
+    const accent = input.brand.accent || FALLBACK_ACCENT;
+    const company = input.brand.company || appName;
+    const year = '©'; // ano resolvido fora (sem Date.* aqui); rodapé usa só o nome.
+    const lang = input.locale || 'en';
+    const linkFallback = input.linkFallback ||
+        'If the button does not work, copy and paste this link into your browser:';
+    const html = `<!doctype html>
+<html lang="${esc(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(input.subject)}</title>
+</head>
+<body style="margin:0;padding:0;background:#f3f4f6;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#f3f4f6;padding:32px 12px;">
+<tr><td align="center">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:480px;background:#ffffff;border-radius:14px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,.08);">
+<tr><td style="background:${esc(accent)};padding:20px 28px;">
+<span style="color:#ffffff;font-size:18px;font-weight:700;letter-spacing:.2px;">${esc(appName)}</span>
+</td></tr>
+<tr><td style="padding:32px 28px 8px;">
+<h1 style="margin:0 0 12px;font-size:20px;line-height:1.3;color:#111827;">${esc(input.heading)}</h1>
+<p style="margin:0 0 24px;font-size:15px;line-height:1.6;color:#374151;">${esc(input.intro)}</p>
+<table role="presentation" cellpadding="0" cellspacing="0"><tr><td style="border-radius:8px;background:${esc(accent)};">
+<a href="${esc(input.ctaUrl)}" style="display:inline-block;padding:12px 24px;font-size:15px;font-weight:600;color:#ffffff;text-decoration:none;border-radius:8px;">${esc(input.ctaLabel)}</a>
+</td></tr></table>
+${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(input.footnote)}</p>` : ''}
+<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(linkFallback)}<br><a href="${esc(input.ctaUrl)}" style="color:${esc(accent)};word-break:break-all;">${esc(input.ctaUrl)}</a></p>
+</td></tr>
+<tr><td style="padding:24px 28px 28px;border-top:1px solid #f3f4f6;">
+<p style="margin:0;font-size:12px;line-height:1.5;color:#9ca3af;">${esc(company)} ${year}</p>
+</td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+    const text = [
+        input.heading,
+        '',
+        input.intro,
+        '',
+        `${input.ctaLabel}: ${input.ctaUrl}`,
+        ...(input.footnote ? ['', input.footnote] : []),
+        '',
+        `— ${company}`,
+    ].join('\n');
+    return { subject: input.subject, html, text };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Resolução de geolocalização PLUGÁVEL e FAIL-SAFE para o IP de uma sessão.
+ *
+ * A lib NÃO embute nenhum banco de geo (MaxMind/ipapi/etc.) — o host pluga o
+ * `resolveGeo` na config (ex.: lookup MaxMind local ou um fetch a um serviço). O
+ * default (hook ausente) é NÃO mostrar geo (só o IP). A resolução é best-effort
+ * com timeout curto: erro/timeout → `null` (a UI só omite a localização).
+ */
+/**
+ * Hook do host que mapeia um IP para um rótulo de localização legível
+ * (ex.: "São Paulo, BR"). Recebe o IP e devolve a string OU `null` quando não
+ * resolve. Pode ser síncrono ou assíncrono.
+ */
+export type ResolveGeo = (ip: string) => Promise<string | null> | (string | null);
+/** Timeout default (ms) da resolução de geo — curto para não atrasar listagens. */
+export declare const GEO_RESOLVE_TIMEOUT_MS = 1500;
+/**
+ * Aplica o `resolveGeo` do host a um IP de forma defensiva: sem hook, sem IP, ou
+ * erro/timeout → `null`. NUNCA lança. O timeout evita que um lookup lento
+ * (ex.: rede) trave a renderização da lista de sessões.
+ */
+export declare function resolveGeoSafe(resolveGeo: ResolveGeo | undefined, ip: string | null | undefined, timeoutMs?: number): Promise<string | null>;

package/build/src/host/geo.js

@@ -0,0 +1,39 @@
+/**
+ * Resolução de geolocalização PLUGÁVEL e FAIL-SAFE para o IP de uma sessão.
+ *
+ * A lib NÃO embute nenhum banco de geo (MaxMind/ipapi/etc.) — o host pluga o
+ * `resolveGeo` na config (ex.: lookup MaxMind local ou um fetch a um serviço). O
+ * default (hook ausente) é NÃO mostrar geo (só o IP). A resolução é best-effort
+ * com timeout curto: erro/timeout → `null` (a UI só omite a localização).
+ */
+/** Timeout default (ms) da resolução de geo — curto para não atrasar listagens. */
+export const GEO_RESOLVE_TIMEOUT_MS = 1500;
+/**
+ * Aplica o `resolveGeo` do host a um IP de forma defensiva: sem hook, sem IP, ou
+ * erro/timeout → `null`. NUNCA lança. O timeout evita que um lookup lento
+ * (ex.: rede) trave a renderização da lista de sessões.
+ */
+export async function resolveGeoSafe(resolveGeo, ip, timeoutMs = GEO_RESOLVE_TIMEOUT_MS) {
+    if (!resolveGeo || !ip)
+        return null;
+    try {
+        const result = await withTimeout(Promise.resolve(resolveGeo(ip)), timeoutMs);
+        return typeof result === 'string' && result.length > 0 ? result : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rejeita após `ms` se a promise não resolver antes (limpa o timer ao fim). */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('geo resolve timeout')), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}