@adonis-agora/authkit-server 0.76.0 → 0.77.0

package/build/src/host/register_auth_host.js

@@ -441,6 +441,18 @@ export function registerAuthHost(router, opts = {}) {
     router.post('/auth/interaction/:uid/identifier', [C.interaction, 'identifier']);
     withLogin(router.post('/auth/interaction/:uid/login', [C.interaction, 'login']));
     withLogin(router.post('/auth/interaction/:uid/mfa', [C.interaction, 'mfaVerify']));
+    const customMfaBeginRoute = router.post('/auth/interaction/:uid/mfa/custom/:method/begin', [
+        C.interaction,
+        'customMfaBegin',
+    ]);
+    withLogin(customMfaBeginRoute);
+    customMfaBeginRoute.as('authkit.mfa.custom.begin');
+    const customMfaVerifyRoute = router.post('/auth/interaction/:uid/mfa/custom/:method/verify', [
+        C.interaction,
+        'customMfaVerify',
+    ]);
+    withLogin(customMfaVerifyRoute);
+    customMfaVerifyRoute.as('authkit.mfa.custom.verify');
     // Troca de senha obrigatória quando a senha expirou (password expiration gate).
     withLogin(router.post('/auth/interaction/:uid/password-expired', [
         C.interaction,

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

@@ -0,0 +1,20 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/** Provider-neutral delivery input. Only the host generates and verifies the OTP. */
+export interface WhatsappCodeInput {
+    phone: string;
+    code: string;
+    locale: string;
+    expiresInSeconds: number;
+    /** Optional host-localized copy for transports that send free-form messages. */
+    text?: string;
+}
+/** Implement this interface to support any WhatsApp provider. Reject on failed delivery. */
+export interface WhatsappCodeSender {
+    sendCode(input: WhatsappCodeInput): Promise<void>;
+}
+/** A configured instance, or an injectable class resolved by the request container. */
+export type WhatsappCodeSenderConstructor = new (...args: never[]) => WhatsappCodeSender;
+export type WhatsappCodeSenderBinding = WhatsappCodeSender | WhatsappCodeSenderConstructor;
+export declare function resolveWhatsappCodeSender(resolver: Pick<HttpContext['containerResolver'], 'make'>, binding: WhatsappCodeSenderBinding): Promise<WhatsappCodeSender>;
+export { MetaWhatsappCodeSender, type MetaWhatsappCodeSenderOptions, } from './whatsapp_senders/meta_whatsapp_code_sender.js';
+export { WhatsmiauCodeSender, type WhatsmiauCodeSenderOptions, } from './whatsapp_senders/whatsmiau_code_sender.js';

package/build/src/host/whatsapp_code_sender.js

@@ -0,0 +1,9 @@
+export async function resolveWhatsappCodeSender(resolver, binding) {
+    const sender = typeof binding === 'function' ? await resolver.make(binding) : binding;
+    if (!sender || typeof sender.sendCode !== 'function') {
+        throw new Error('Invalid WhatsApp code sender: expected sendCode(input)');
+    }
+    return sender;
+}
+export { MetaWhatsappCodeSender, } from './whatsapp_senders/meta_whatsapp_code_sender.js';
+export { WhatsmiauCodeSender, } from './whatsapp_senders/whatsmiau_code_sender.js';

package/build/src/host/whatsapp_senders/http.d.ts

@@ -0,0 +1,5 @@
+/** Never include configuration values in validation errors. */
+export declare function requireString(value: string, field: string): void;
+export declare function recipientPhone(phone: string): string;
+/** Response bodies and fetch causes can contain credentials and OTPs: discard both. */
+export declare function postJson(provider: string, url: URL, headers: Record<string, string>, body: unknown): Promise<void>;

package/build/src/host/whatsapp_senders/http.js

@@ -0,0 +1,33 @@
+/** Never include configuration values in validation errors. */
+export function requireString(value, field) {
+    if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) {
+        throw new Error(`Invalid WhatsApp sender ${field}`);
+    }
+}
+export function recipientPhone(phone) {
+    if (typeof phone !== 'string' || !/^\+?[1-9]\d{6,14}$/.test(phone)) {
+        throw new Error('Invalid WhatsApp recipient phone');
+    }
+    return phone.replace(/^\+/, '');
+}
+/** Response bodies and fetch causes can contain credentials and OTPs: discard both. */
+export async function postJson(provider, url, headers, body) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15_000),
+            redirect: 'error',
+        });
+    }
+    catch {
+        throw new Error(`WhatsApp code delivery failed (${provider})`);
+    }
+    // Do not parse or log the body, even when a provider echoes the submitted code.
+    void response.body?.cancel().catch(() => { });
+    if (!response.ok) {
+        throw new Error(`WhatsApp code delivery failed (${provider}, HTTP ${response.status})`);
+    }
+}

package/build/src/host/whatsapp_senders/meta_whatsapp_code_sender.d.ts

@@ -0,0 +1,20 @@
+import type { WhatsappCodeInput, WhatsappCodeSender } from '../whatsapp_code_sender.js';
+export interface MetaWhatsappCodeSenderOptions {
+    accessToken: string;
+    phoneNumberId: string;
+    /** Explicit supported Graph API version, for example v23.0. */
+    apiVersion: string;
+    /** An approved authentication template with an OTP URL button. */
+    templateName: string;
+    /** Overrides the host locale when the template uses a different language. */
+    languageCode?: string;
+}
+/** Meta Cloud API authentication template transport (copy-code / OTP URL button). */
+export declare class MetaWhatsappCodeSender implements WhatsappCodeSender {
+    private readonly accessToken;
+    private readonly endpoint;
+    private readonly templateName;
+    private readonly languageCode?;
+    constructor(options: MetaWhatsappCodeSenderOptions);
+    sendCode(input: WhatsappCodeInput): Promise<void>;
+}

package/build/src/host/whatsapp_senders/meta_whatsapp_code_sender.js

@@ -0,0 +1,51 @@
+import { postJson, recipientPhone, requireString } from './http.js';
+const LANGUAGE_CODES = { 'pt-BR': 'pt_BR', en: 'en_US', es: 'es' };
+/** Meta Cloud API authentication template transport (copy-code / OTP URL button). */
+export class MetaWhatsappCodeSender {
+    accessToken;
+    endpoint;
+    templateName;
+    languageCode;
+    constructor(options) {
+        requireString(options.accessToken, 'accessToken');
+        if (typeof options.apiVersion !== 'string' || !/^v\d+\.\d+$/.test(options.apiVersion)) {
+            throw new Error('Invalid WhatsApp sender apiVersion');
+        }
+        if (typeof options.phoneNumberId !== 'string' || !/^\d+$/.test(options.phoneNumberId)) {
+            throw new Error('Invalid WhatsApp sender phoneNumberId');
+        }
+        if (typeof options.templateName !== 'string' || !/^[a-z0-9_]+$/.test(options.templateName)) {
+            throw new Error('Invalid WhatsApp sender templateName');
+        }
+        if (options.languageCode !== undefined) {
+            requireString(options.languageCode, 'languageCode');
+        }
+        this.endpoint = new URL(`https://graph.facebook.com/${options.apiVersion}/${options.phoneNumberId}/messages`);
+        this.accessToken = options.accessToken;
+        this.templateName = options.templateName;
+        this.languageCode = options.languageCode;
+    }
+    async sendCode(input) {
+        await postJson('Meta', this.endpoint, { Authorization: `Bearer ${this.accessToken}` }, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to: recipientPhone(input.phone),
+            type: 'template',
+            template: {
+                name: this.templateName,
+                language: {
+                    code: this.languageCode ?? LANGUAGE_CODES[input.locale] ?? input.locale.replace(/-/g, '_'),
+                },
+                components: [
+                    { type: 'body', parameters: [{ type: 'text', text: input.code }] },
+                    {
+                        type: 'button',
+                        sub_type: 'url',
+                        index: '0',
+                        parameters: [{ type: 'text', text: input.code }],
+                    },
+                ],
+            },
+        });
+    }
+}

package/build/src/host/whatsapp_senders/whatsmiau_code_sender.d.ts

@@ -0,0 +1,14 @@
+import type { WhatsappCodeInput, WhatsappCodeSender } from '../whatsapp_code_sender.js';
+export interface WhatsmiauCodeSenderOptions {
+    apiKey: string;
+    instanceName: string;
+    /** Includes the API version path. Defaults to Whatsmiau Cloud's /v2 endpoint. */
+    baseUrl?: string;
+}
+/** Whatsmiau Cloud v2 / Evolution-compatible free-form text transport. */
+export declare class WhatsmiauCodeSender implements WhatsappCodeSender {
+    private readonly apiKey;
+    private readonly endpoint;
+    constructor(options: WhatsmiauCodeSenderOptions);
+    sendCode(input: WhatsappCodeInput): Promise<void>;
+}

package/build/src/host/whatsapp_senders/whatsmiau_code_sender.js

@@ -0,0 +1,36 @@
+import { postJson, recipientPhone, requireString } from './http.js';
+/** Whatsmiau Cloud v2 / Evolution-compatible free-form text transport. */
+export class WhatsmiauCodeSender {
+    apiKey;
+    endpoint;
+    constructor(options) {
+        requireString(options.apiKey, 'apiKey');
+        if (typeof options.instanceName !== 'string' ||
+            !/^[A-Za-z0-9_-]+$/.test(options.instanceName)) {
+            throw new Error('Invalid WhatsApp sender instanceName');
+        }
+        let baseUrl;
+        try {
+            baseUrl = new URL(options.baseUrl ?? 'https://api.whatsmiau.dev/v2');
+        }
+        catch {
+            throw new Error('Invalid WhatsApp sender baseUrl');
+        }
+        if (!['http:', 'https:'].includes(baseUrl.protocol) ||
+            baseUrl.username ||
+            baseUrl.password ||
+            baseUrl.search ||
+            baseUrl.hash) {
+            throw new Error('Invalid WhatsApp sender baseUrl');
+        }
+        baseUrl.pathname = `${baseUrl.pathname.replace(/\/+$/, '')}/message/sendText/${options.instanceName}`;
+        this.endpoint = baseUrl;
+        this.apiKey = options.apiKey;
+    }
+    async sendCode(input) {
+        await postJson('Whatsmiau', this.endpoint, { apikey: this.apiKey }, {
+            number: recipientPhone(input.phone),
+            text: input.text ?? input.code,
+        });
+    }
+}

package/build/src/provider/oidc_service.js

@@ -137,8 +137,12 @@ export class OidcService {
                     claims: async (_use, _scope) => {
                         const base = {
                             sub: user.id,
-                            email: user.email,
-                            email_verified: true,
+                            ...(user.email
+                                ? {
+                                    email: user.email,
+                                    email_verified: (await config.accountStore.isEmailVerified?.(user.id)) ?? false,
+                                }
+                                : {}),
                             name: user.name,
                             picture: user.avatarUrl,
                         };

package/build/stubs/ui/react/pages/mfa-challenge.tsx

@@ -2,34 +2,124 @@
   exports({ to: app.makePath('inertia/pages/authkit/mfa-challenge.tsx') });
 }
 
-import AuthShell from '../components/auth_shell';
+import { useRef, useState } from 'react';
+import AuthShell, { type AuthBrand } from '../../components/auth_shell';
+
+interface CustomMethod {
+  id: string;
+  factorId: string;
+  label: string;
+  fields?: {
+    name: string;
+    label: string;
+    type?: 'text' | 'password';
+    inputMode?: 'numeric' | 'text';
+    autoComplete?: string;
+  }[];
+  requiresBegin: boolean;
+  started: boolean;
+  beginUrl: string;
+  verifyUrl: string;
+}
 
 const inputClass =
-  'w-full rounded-lg border border-gray-300 px-3 py-2 text-center text-lg tracking-[0.4em] outline-none transition focus:border-transparent focus:ring-2 focus:ring-gray-800';
+  'w-full rounded-lg border border-gray-300 px-3 py-2 text-base outline-none transition focus:border-gray-900 focus:ring-2 focus:ring-gray-900';
+const buttonClass =
+  'w-full rounded-lg bg-gray-900 px-3 py-2.5 text-sm font-semibold text-white transition hover:opacity-90 disabled:opacity-50';
+const secondaryButtonClass =
+  'w-full rounded-lg border border-gray-300 px-3 py-2.5 text-sm font-semibold text-gray-700 transition hover:bg-gray-50 disabled:opacity-50';
 
 export default function AuthkitMfaChallenge({
   uid,
   csrfToken,
   error,
+  brand,
+  messages = {},
+  noEnrollment = false,
+  otpLocked = false,
+  totpAvailable = true,
+  passkeyAvailable = false,
+  trustedDevicesEnabled = false,
+  trustedDeviceDays = 30,
+  customMfaMethods = [],
+  completedMfaMethods = [],
+  requiredMfaFactors = 2,
 }: {
   uid: string;
   csrfToken: string;
   error?: string;
+  brand?: AuthBrand;
+  messages?: Record<string, string>;
+  noEnrollment?: boolean;
+  otpLocked?: boolean;
+  totpAvailable?: boolean;
+  passkeyAvailable?: boolean;
+  trustedDevicesEnabled?: boolean;
+  trustedDeviceDays?: number;
+  customMfaMethods?: CustomMethod[];
+  completedMfaMethods?: string[];
+  requiredMfaFactors?: number;
 }) {
+  const [passkeyPending, setPasskeyPending] = useState(false);
+  const [passkeyError, setPasskeyError] = useState(false);
+  const [trustDevice, setTrustDevice] = useState(false);
+  const passkeyForm = useRef<HTMLFormElement>(null);
+  const passkeyResponse = useRef<HTMLInputElement>(null);
+  const t = (key: string, fallback: string) => messages[`mfa_challenge.${key}`] ?? fallback;
+  const showTotp = !noEnrollment && !otpLocked && totpAvailable;
+  const showPasskey = !noEnrollment && passkeyAvailable;
+  const remainingMethods = noEnrollment
+    ? []
+    : customMfaMethods.filter((method) => !completedMfaMethods.includes(method.id));
+
+  async function authenticatePasskey() {
+    setPasskeyPending(true);
+    setPasskeyError(false);
+    try {
+      const result = await fetch(`/auth/interaction/${uid}/passkey/options`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-csrf-token': csrfToken },
+        body: JSON.stringify({}),
+      });
+      if (!result.ok) throw new Error('Passkey options failed');
+      const moduleUrl = '/authkit/assets/webauthn.js';
+      const { startAuthentication } = await import(/* @vite-ignore */ moduleUrl);
+      const assertion = await startAuthentication({ optionsJSON: await result.json() });
+      if (!passkeyResponse.current || !passkeyForm.current) throw new Error('Missing passkey form');
+      passkeyResponse.current.value = JSON.stringify(assertion);
+      passkeyForm.current.submit();
+    } catch {
+      setPasskeyError(true);
+      setPasskeyPending(false);
+    }
+  }
+
   return (
-    <AuthShell>
-      <form method="POST" action={`/auth/interaction/${uid}/mfa`}>
-        <input type="hidden" name="_csrf" value={csrfToken} />
-        <h1 className="text-xl font-semibold text-gray-900">Verificação em duas etapas</h1>
-        <p className="mt-1 text-sm text-gray-500">
-          Abra seu app autenticador e informe o código de 6 dígitos.
+    <AuthShell brand={brand}>
+      <h1 className="text-xl font-semibold text-gray-900">
+        {t('title', 'Verificação multifator')}
+      </h1>
+      <p className="mt-1 text-sm text-gray-500">
+        {t('intro', 'Verifique sua identidade usando um método disponível.')}
+      </p>
+      {requiredMfaFactors > 2 && (
+        <p className="mt-3 text-sm text-gray-600" role="status">
+          {t('progress', '{completed} de {required} fatores verificados.')
+            .replace('{completed}', String(1 + completedMfaMethods.length))
+            .replace('{required}', String(requiredMfaFactors))}
         </p>
+      )}
+      {error && (
+        <p className="mt-4 text-sm text-red-600" role="alert">
+          {error}
+        </p>
+      )}
 
-        {error && <p className="mt-4 text-sm text-red-600">{error}</p>}
-
-        <div className="mt-6">
+      {showTotp && (
+        <form method="POST" action={`/auth/interaction/${uid}/mfa`} className="mt-6">
+          <input type="hidden" name="_csrf" value={csrfToken} />
           <label htmlFor="code" className="mb-1 block text-sm font-medium text-gray-700">
-            Código
+            {t('code_label', 'Código')}
           </label>
           <input
             id="code"
@@ -40,33 +130,113 @@ export default function AuthkitMfaChallenge({
             maxLength={6}
             className={inputClass}
           />
-        </div>
-
-        <button
-          type="submit"
-          className="mt-6 w-full rounded-lg bg-gray-900 py-2.5 text-sm font-semibold text-white transition hover:opacity-90"
-        >
-          Verificar
-        </button>
-      </form>
-
-      <details className="mt-6 text-sm text-gray-600">
-        <summary className="cursor-pointer hover:underline">Usar um código de recuperação</summary>
-        <form method="POST" action={`/auth/interaction/${uid}/mfa`} className="mt-3">
-          <input type="hidden" name="_csrf" value={csrfToken} />
-          <input
-            name="recoveryCode"
-            placeholder="xxxxx-xxxxx"
-            className="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-gray-900"
-          />
-          <button
-            type="submit"
-            className="mt-3 w-full rounded-lg border border-gray-300 py-2.5 text-sm font-semibold text-gray-700 transition hover:bg-gray-50"
-          >
-            Entrar com código de recuperação
+          {trustedDevicesEnabled && (
+            <label className="mt-4 flex items-center gap-2 text-sm text-gray-600">
+              <input
+                type="checkbox"
+                name="trustDevice"
+                value="on"
+                checked={trustDevice}
+                onChange={(event) => setTrustDevice(event.target.checked)}
+              />
+              {t('trust_device', 'Confiar neste dispositivo por {days} dias').replace(
+                '{days}',
+                String(trustedDeviceDays),
+              )}
+            </label>
+          )}
+          <button type="submit" className={`mt-6 ${buttonClass}`}>
+            {t('submit', 'Verificar')}
           </button>
         </form>
-      </details>
+      )}
+
+      {remainingMethods.map((method) => (
+        <section key={method.id} className="mt-6">
+          <h2 className="text-sm font-semibold text-gray-900">{method.label}</h2>
+          {method.requiresBegin && !method.started ? (
+            <form method="POST" action={method.beginUrl} className="mt-3">
+              <input type="hidden" name="_csrf" value={csrfToken} />
+              <button type="submit" className={secondaryButtonClass}>
+                {t('start', 'Iniciar verificação')}
+              </button>
+            </form>
+          ) : (
+            <form method="POST" action={method.verifyUrl} className="mt-3 space-y-3">
+              <input type="hidden" name="_csrf" value={csrfToken} />
+              {(method.fields ?? []).map((field) => (
+                <div key={field.name}>
+                  <label
+                    htmlFor={`custom-${method.id}-${field.name}`}
+                    className="mb-1 block text-sm font-medium text-gray-700"
+                  >
+                    {field.label}
+                  </label>
+                  <input
+                    id={`custom-${method.id}-${field.name}`}
+                    name={field.name}
+                    type={field.type ?? 'text'}
+                    inputMode={field.inputMode ?? 'text'}
+                    autoComplete={field.autoComplete ?? 'off'}
+                    className={inputClass}
+                  />
+                </div>
+              ))}
+              <button type="submit" className={buttonClass}>
+                {t('submit', 'Verificar')}
+              </button>
+            </form>
+          )}
+        </section>
+      ))}
+
+      {showPasskey && (
+        <div className="mt-4">
+          <form ref={passkeyForm} method="POST" action={`/auth/interaction/${uid}/passkey/verify`}>
+            <input type="hidden" name="_csrf" value={csrfToken} />
+            <input ref={passkeyResponse} type="hidden" name="response" />
+            <input type="hidden" name="trustDevice" value={trustDevice ? 'on' : ''} />
+            <button
+              type="button"
+              onClick={authenticatePasskey}
+              disabled={passkeyPending}
+              aria-busy={passkeyPending}
+              className={secondaryButtonClass}
+            >
+              {t('passkey_button', 'Usar passkey')}
+            </button>
+          </form>
+          {passkeyError && (
+            <p className="mt-3 text-sm text-red-600" role="alert">
+              {t('passkey_error', 'Não foi possível autenticar com a passkey. Tente novamente.')}
+            </p>
+          )}
+        </div>
+      )}
+
+      {showTotp && (
+        <details className="mt-6 text-sm text-gray-600">
+          <summary className="cursor-pointer hover:underline">
+            {t('recovery_summary', 'Usar um código de recuperação')}
+          </summary>
+          <form method="POST" action={`/auth/interaction/${uid}/mfa`} className="mt-3">
+            <input type="hidden" name="_csrf" value={csrfToken} />
+            <label htmlFor="recovery-code" className="mb-1 block text-sm font-medium text-gray-700">
+              {t('recovery_summary', 'Usar um código de recuperação')}
+            </label>
+            <input
+              id="recovery-code"
+              name="recoveryCode"
+              autoComplete="off"
+              placeholder="xxxxx-xxxxx"
+              className={inputClass}
+            />
+            <button type="submit" className={`mt-3 ${secondaryButtonClass}`}>
+              {t('recovery_submit', 'Entrar com código de recuperação')}
+            </button>
+          </form>
+        </details>
+      )}
     </AuthShell>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "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",
@@ -153,6 +153,7 @@
     "react-dom": "19.2.8",
     "react-error-boundary": "6.1.5",
     "recharts": "3.10.1",
+    "reflect-metadata": "0.2.2",
     "tempura": "^0.4.1",
     "typescript": "7.0.2",
     "vite": "8.2.2"