@adonis-agora/authkit-server 0.79.0 → 0.80.1

package/build/index.d.ts

@@ -19,6 +19,7 @@ export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgent
 export type { PoppyAgentProtocolEntry, PoppyApiEntry, PoppyBrowserLogin, PoppyClientsConfigInput, PoppyConfigInput, PoppyLimiter, PoppyMediatedConfigInput, PoppyMediatedField, PoppyMediatedResult, PoppyMediatedVerifyInput, PoppyPrincipalBase, PoppyReplayStore, ResolvedPoppyConfig, } from './src/agents/poppy/config.js';
 export { POPPY_READ, POPPY_WRITE } from './src/agents/poppy/config.js';
 export { accessTokenHash, type DpopNonceSource, type DpopResult, hmacNonceSource, type VerifyDpopInput, verifyDpopProof, } from './src/agents/poppy/dpop.js';
+export { maskEmail, type PoppyEmailCodeSignInOptions, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
 export { PoppyError, type PoppyErrorCode } from './src/agents/poppy/errors.js';
 export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
 export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, type PoppyAuthenticate, type PoppyAuthResult, type PoppyPrincipal, type PoppySlotRequest, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';

package/build/index.js

@@ -11,6 +11,7 @@ export { PersonalAgentVerifier } from './src/agents/agent_identity.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
 export { POPPY_READ, POPPY_WRITE } from './src/agents/poppy/config.js';
 export { accessTokenHash, hmacNonceSource, verifyDpopProof, } from './src/agents/poppy/dpop.js';
+export { maskEmail, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
 export { PoppyError } from './src/agents/poppy/errors.js';
 export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
 export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';

package/build/src/agents/poppy/email_code_sign_in.d.ts

@@ -0,0 +1,27 @@
+import { type AuthAccount } from '../../accounts/account_store.js';
+import type { PoppyMediatedConfigInput } from './config.js';
+export interface PoppyEmailCodeSignInOptions {
+    /** Scopes que este sign-in pode conceder. Default: `['poppy:read']` (o default do Mediated). */
+    scopes?: string[];
+    /** Validade do código, em segundos. Default: 600. */
+    codeTtl?: number;
+    /** Tentativas de código antes de `failed`. Default: 5. */
+    maxCodeAttempts?: number;
+    /**
+     * Quem pode entrar por aqui (ex.: só pacientes, não profissionais). `false` = recebe a
+     * resposta de conta inexistente. Default: toda conta ativa.
+     */
+    eligible?: (account: AuthAccount) => boolean | Promise<boolean>;
+    /**
+     * Códigos por e-mail por hora, nesta instância — impede um agente de lotar a caixa de
+     * alguém. Acima disso a resposta é a mesma, sem e-mail. Default: 5.
+     */
+    maxPerHour?: number;
+    /** Rótulo do campo que o agente mostra ao usuário. Default: `'Email address'`. */
+    label?: string;
+    /** Texto de `sentTo` a partir do e-mail mascarado. Default: `` `Email to ${masked}` ``. */
+    sentTo?: (masked: string) => string;
+}
+/** `ana.souza@gmail.com` → `a***@gmail.com`: o bastante para a pessoa reconhecer. */
+export declare function maskEmail(email: string): string;
+export declare function poppyEmailCodeSignIn(options?: PoppyEmailCodeSignInOptions): PoppyMediatedConfigInput;

package/build/src/agents/poppy/email_code_sign_in.js

@@ -0,0 +1,140 @@
+/**
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ *
+ * Mediated Sign-In pronto (§4.7): o agente pede o e-mail da conta, o authkit manda
+ * um código de 6 dígitos para ele e o agente devolve o código. Usa as contas
+ * (`accountStore`) e o e-mail (hook `mail.onPoppySignInCode` ou o mailer default)
+ * do próprio authkit — o app só liga:
+ *
+ * ```ts
+ * personalAgents: {
+ *   poppy: { signIn: { mediated: poppyEmailCodeSignIn() } },
+ * }
+ * ```
+ *
+ * Sem enumeração de contas: e-mail sem conta, conta desativada, conta recusada
+ * por `eligible` ou e-mail acima do limite recebem a MESMA resposta, sem código
+ * (`accountId: null`) — a lib recusa qualquer código como errado. O envio não é
+ * esperado, então o tempo de resposta também não denuncia.
+ */
+import { randomInt } from 'node:crypto';
+import { supportsAccountStatus } from '../../accounts/account_store.js';
+import { sendPoppySignInCodeEmail } from '../../host/default_mailer.js';
+import { personalAgentsFor } from '../runtime.js';
+/** `ana.souza@gmail.com` → `a***@gmail.com`: o bastante para a pessoa reconhecer. */
+export function maskEmail(email) {
+    const at = email.lastIndexOf('@');
+    const user = at > 0 ? email.slice(0, at) : '';
+    const domain = at > 0 ? email.slice(at + 1) : '';
+    if (!user || !domain)
+        return '***';
+    return `${user[0]}***@${domain}`;
+}
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const HOUR_MS = 3600 * 1000;
+const MAX_TRACKED = 10_000;
+export function poppyEmailCodeSignIn(options = {}) {
+    const positive = (value, fallback, what) => {
+        if (value === undefined)
+            return fallback;
+        if (!Number.isFinite(value) || value < 1) {
+            throw new Error(`authkit: poppyEmailCodeSignIn ${what} precisa ser um número >= 1.`);
+        }
+        return Math.floor(value);
+    };
+    const codeTtl = positive(options.codeTtl, 600, 'codeTtl');
+    const maxPerHour = positive(options.maxPerHour, 5, 'maxPerHour');
+    const maxCodeAttempts = positive(options.maxCodeAttempts, 5, 'maxCodeAttempts');
+    const sentToText = options.sentTo ?? ((masked) => `Email to ${masked}`);
+    const sends = new Map();
+    /** `true` = ainda cabe um envio para este e-mail na última hora (e conta este). */
+    const claim = (email) => {
+        const now = Date.now();
+        const recent = (sends.get(email) ?? []).filter((t) => now - t < HOUR_MS);
+        if (recent.length >= maxPerHour) {
+            sends.set(email, recent);
+            return false;
+        }
+        recent.push(now);
+        sends.delete(email);
+        sends.set(email, recent);
+        if (sends.size > MAX_TRACKED)
+            sends.delete(sends.keys().next().value);
+        return true;
+    };
+    const eligibleAccount = async (ctx, email) => {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const store = service.config.accountStore;
+        const account = await store.findByEmail(email);
+        if (!account)
+            return null;
+        if (supportsAccountStatus(store) && (await store.isDisabled(account.id)))
+            return null;
+        if (options.eligible) {
+            // Um `eligible` que lança vira "não elegível": um 500 só para algumas contas as denunciaria.
+            try {
+                if (!(await options.eligible(account)))
+                    return null;
+            }
+            catch (error) {
+                ctx.logger.error({ err: error }, 'authkit: poppyEmailCodeSignIn eligible lançou');
+                return null;
+            }
+        }
+        return account;
+    };
+    return {
+        fields: [{ name: 'email', label: options.label ?? 'Email address', secret: false }],
+        ...(options.scopes ? { scopes: options.scopes } : {}),
+        codeTtl,
+        maxCodeAttempts,
+        async verify({ credentials, clientId, ctx }) {
+            const email = (credentials.email ?? '').trim().toLowerCase();
+            if (!EMAIL.test(email))
+                return { status: 'failed' };
+            const sentTo = sentToText(maskEmail(email));
+            const decoy = { status: 'code_required', accountId: null, sentTo };
+            // O limite conta para qualquer e-mail — com ou sem conta, a resposta não muda.
+            if (!claim(email))
+                return decoy;
+            const account = await eligibleAccount(ctx, email);
+            if (!account)
+                return decoy;
+            const code = String(randomInt(0, 1_000_000)).padStart(6, '0');
+            // Sem `await`: o caminho com conta não pode demorar mais que o sem conta.
+            void deliver(ctx, { email, code, clientId, expiresInMinutes: Math.ceil(codeTtl / 60) });
+            return { status: 'code_required', accountId: account.id, sentTo, code };
+        },
+    };
+}
+function hostOf(clientId) {
+    try {
+        return new URL(clientId).host;
+    }
+    catch {
+        return clientId;
+    }
+}
+async function deliver(ctx, data) {
+    try {
+        const runtime = await personalAgentsFor(ctx);
+        const agentName = runtime?.poppy
+            ? await runtime.poppy.registry.displayName(data.clientId)
+            : hostOf(data.clientId);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const hook = service.config.mail?.onPoppySignInCode;
+        const input = {
+            email: data.email,
+            code: data.code,
+            agentName,
+            expiresInMinutes: data.expiresInMinutes,
+        };
+        if (hook)
+            await hook(input);
+        else
+            await sendPoppySignInCodeEmail(ctx, input);
+    }
+    catch (error) {
+        ctx.logger.error({ err: error }, 'authkit: o código do Poppy Mediated Sign-In não saiu');
+    }
+}

package/build/src/define_config.d.ts

@@ -78,6 +78,18 @@ export interface MailHooks {
         email: string;
         sudoUrl: string;
     }) => Promise<void>;
+    /**
+     * Código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`): um personal
+     * agent quer entrar na conta e a pessoa precisa dar o código a ele. Sem o hook, o
+     * host-kit envia pelo mailer default, com branding e i18n.
+     */
+    onPoppySignInCode?: (data: {
+        email: string;
+        code: string;
+        /** Nome do agente (metadata dele, ou o host do `client_id`). */
+        agentName: string;
+        expiresInMinutes: number;
+    }) => Promise<void>;
     /**
      * Disparado num login bem-sucedido a partir de um dispositivo NOVO (sem cookie
      * de dispositivo confiável válido para a conta). Best-effort, fire-and-forget:

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

@@ -66,6 +66,17 @@ export declare function sendMagicLinkEmail(ctx: HttpContext, data: {
     code?: string;
     channel?: 'code' | 'link';
 }): Promise<void>;
+/**
+ * Envia o código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`) pelo
+ * mailer default do host. Só código, sem link: quem digita é a pessoa, no agente.
+ * Best-effort: no fallback (sem mail) loga o código, como o magic link loga o link; nunca lança.
+ */
+export declare function sendPoppySignInCodeEmail(ctx: HttpContext, data: {
+    email: string;
+    code: string;
+    agentName: string;
+    expiresInMinutes: number;
+}): Promise<void>;
 /**
  * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo) pelo mailer default do host.
  *

package/build/src/host/default_mailer.js

@@ -294,6 +294,35 @@ export async function sendMagicLinkEmail(ctx, data) {
         ctx.logger.error({ err: error, email: data.email }, 'authkit: falha ao enviar magic link de login');
     }
 }
+/**
+ * Envia o código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`) pelo
+ * mailer default do host. Só código, sem link: quem digita é a pessoa, no agente.
+ * Best-effort: no fallback (sem mail) loga o código, como o magic link loga o link; nunca lança.
+ */
+export async function sendPoppySignInCodeEmail(ctx, data) {
+    try {
+        const brand = resolveBrand(ctx);
+        const { messages: t, locale } = resolveMailMessages(ctx);
+        const params = { agent: data.agentName, minutes: data.expiresInMinutes };
+        const content = renderTransactionalEmail({
+            brand,
+            locale,
+            subject: translate(t, 'mail.poppy_sign_in.subject', params),
+            heading: translate(t, 'mail.poppy_sign_in.heading', params),
+            intro: translate(t, 'mail.poppy_sign_in.intro', params),
+            footnote: translate(t, 'mail.poppy_sign_in.fallback'),
+            code: data.code,
+            codeLabel: translate(t, 'mail.poppy_sign_in.code_label'),
+        });
+        const sent = await sendEmail(ctx, data.email, content);
+        if (!sent) {
+            ctx.logger.info({ email: data.email, agent: data.agentName, code: data.code }, 'authkit: código do Poppy Mediated Sign-In (dev — @adonisjs/mail ausente)');
+        }
+    }
+    catch (error) {
+        ctx.logger.error({ err: error, email: data.email }, 'authkit: falha ao enviar o código do Poppy Mediated Sign-In');
+    }
+}
 /**
  * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo) pelo mailer default do host.
  *

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

@@ -561,6 +561,11 @@ export declare const DEFAULT_MESSAGES: {
     'mail.magic_link.code_subject': string;
     'mail.magic_link.code_intro': string;
     'mail.magic_link.code_only_label': string;
+    'mail.poppy_sign_in.subject': string;
+    'mail.poppy_sign_in.heading': string;
+    'mail.poppy_sign_in.intro': string;
+    'mail.poppy_sign_in.code_label': string;
+    'mail.poppy_sign_in.fallback': string;
     'mail.sudo_link.subject': string;
     'mail.sudo_link.heading': string;
     'mail.sudo_link.intro': string;
@@ -1315,6 +1320,11 @@ export declare const PT_BR_MESSAGES: {
     'mail.magic_link.code_subject': string;
     'mail.magic_link.code_intro': string;
     'mail.magic_link.code_only_label': string;
+    'mail.poppy_sign_in.subject': string;
+    'mail.poppy_sign_in.heading': string;
+    'mail.poppy_sign_in.intro': string;
+    'mail.poppy_sign_in.code_label': string;
+    'mail.poppy_sign_in.fallback': string;
     'mail.sudo_link.subject': string;
     'mail.sudo_link.heading': string;
     'mail.sudo_link.intro': string;

package/build/src/host/i18n.js

@@ -604,6 +604,12 @@ export const DEFAULT_MESSAGES = {
     'mail.magic_link.code_subject': 'Your login code',
     'mail.magic_link.code_intro': 'Use the code below to sign in. It expires shortly and can be used once.',
     'mail.magic_link.code_only_label': 'Enter this code to sign in:',
+    // Código do Mediated Sign-In do Poppy: um personal agent pede para entrar na conta.
+    'mail.poppy_sign_in.subject': 'Your code to connect {agent}',
+    'mail.poppy_sign_in.heading': 'Connect {agent} to your account',
+    'mail.poppy_sign_in.intro': '{agent} asked to sign in to your account. If that was you, give it the code below. It expires in {minutes} minutes and works once.',
+    'mail.poppy_sign_in.code_label': 'Your code:',
+    'mail.poppy_sign_in.fallback': 'If you did not ask for this, ignore this email — nobody gets in without the code. Never share it with anyone else.',
     // Link de CONFIRMAÇÃO DE IDENTIDADE (sudo). Copy DISTINTA da do magic link de
     // login de propósito: este link não autentica ninguém — quem o abre já está
     // logado e só reprova que é quem diz ser. Prometer "entre na sua conta" num
@@ -1444,6 +1450,12 @@ export const PT_BR_MESSAGES = {
     'mail.magic_link.code_subject': 'Seu código de login',
     'mail.magic_link.code_intro': 'Use o código abaixo para entrar. Ele expira em instantes e serve para um único acesso.',
     'mail.magic_link.code_only_label': 'Digite este código para entrar:',
+    // Código do Mediated Sign-In do Poppy — ver o comentário no catálogo `en`.
+    'mail.poppy_sign_in.subject': 'Seu código para conectar {agent}',
+    'mail.poppy_sign_in.heading': 'Conecte {agent} à sua conta',
+    'mail.poppy_sign_in.intro': '{agent} pediu para entrar na sua conta. Se foi você, informe o código abaixo. Ele expira em {minutes} minutos e serve uma única vez.',
+    'mail.poppy_sign_in.code_label': 'Seu código:',
+    'mail.poppy_sign_in.fallback': 'Se não foi você, ignore este e-mail — ninguém entra sem o código. Nunca o compartilhe com outra pessoa.',
     // Link de CONFIRMAÇÃO DE IDENTIDADE (sudo) — ver o comentário no catálogo `en`.
     'mail.sudo_link.subject': 'Confirme que é você',
     'mail.sudo_link.heading': 'Confirme sua identidade',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.79.0",
+  "version": "0.80.1",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -60,17 +60,17 @@
     "@adonis-agora/durable": ">=0.7.0 <1.0.0",
     "@adonis-agora/media": ">=0.5.0 <1.0.0",
     "@adonis-agora/telescope": ">=0.1.0 <1.0.0",
-    "@adonisjs/ally": "6.3.0",
-    "@adonisjs/auth": "10.1.0",
-    "@adonisjs/core": "7.5.0",
-    "@adonisjs/drive": "4.0.0",
-    "@adonisjs/lock": "2.1.0",
-    "@adonisjs/lucid": "22.4.2",
-    "@adonisjs/redis": "11.0.0",
-    "@adonisjs/session": "8.1.0",
-    "@adonisjs/shield": "9.0.0",
-    "@vinejs/vine": "4.4.0",
-    "edge.js": "6.5.1"
+    "@adonisjs/ally": "^6.3.0",
+    "@adonisjs/auth": "^10.1.0",
+    "@adonisjs/core": "^7.5.0",
+    "@adonisjs/drive": "^4.0.0",
+    "@adonisjs/lock": "^2.1.0",
+    "@adonisjs/lucid": "^22.4.2",
+    "@adonisjs/redis": "^9.2.0 || ^10.0.0 || ^11.0.0",
+    "@adonisjs/session": "^8.1.0",
+    "@adonisjs/shield": "^9.0.0",
+    "@vinejs/vine": "^4.4.0",
+    "edge.js": "^6.5.1"
   },
   "peerDependenciesMeta": {
     "@adonis-agora/durable": {
@@ -113,7 +113,7 @@
     "qrcode": "1.5.4"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-react": "0.24.0",
+    "@adonis-agora/authkit-react": "0.24.1",
     "@adonis-agora/durable": "0.40.0",
     "@adonis-agora/telescope": "0.21.1",
     "@adonisjs/ally": "6.3.0",

package/skills/authkit-interactions/SKILL.md

@@ -145,7 +145,7 @@ JWKS, and fakes the authenticator for controller tests:
 
 ```ts
 import { mintTestIdToken, serveJwks, fakeAuthenticator } from '@adonis-agora/authkit-testing'
-import { resolvers } from '@adonis-agora/authkit-client'
+import { conventionEndpoints, resolvers } from '@adonis-agora/authkit-client'
 
 const { token, jwks } = await mintTestIdToken({
   issuer: 'https://idp.test',
@@ -160,6 +160,8 @@ const resolver = await factory.resolver({
   clientId: 'my-app',
   sessionKey: 'authkit',
   globalRolesClaim: 'roles',
+  endpoints: async () => conventionEndpoints('https://idp.test'),
+  logger: { warn: () => {} },
 })
 const ctx = { auth: fakeAuthenticator({ identity: null }) } // anonymous request fake
 await served.close()