@adonis-agora/authkit-server 0.76.0 → 0.77.0

package/README.md

@@ -163,3 +163,148 @@ OTel para que as séries existam.
 ## Notas
 - Access tokens são opacos; ID tokens são JWT (assinados pelo JWKS gerido).
 - PKCE (S256) é obrigatório; refresh tokens são rotacionados.
+
+### Custom primary login methods
+
+Register a class or instance for a host-specific authentication flow. AuthKit resolves classes through the request container, so normal Adonis `@inject()` dependencies work. The host validates and consumes the credential; AuthKit applies account policies, maintenance, MFA, audit, and OIDC session completion.
+
+```ts
+import { inject } from '@adonisjs/core';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { CustomLoginMethod } from '@adonis-agora/authkit-server';
+import PhoneProofs from '#services/phone_proofs';
+
+@inject()
+export default class WhatsappLogin implements CustomLoginMethod {
+  readonly passwordless = true;
+  constructor(private proofs: PhoneProofs) {}
+
+  async authenticate(ctx: HttpContext) {
+    // Host service validates and atomically consumes the proof bound to this
+    // browser session and OIDC interaction. Never trust request.accountId.
+    const accountId = await this.proofs.consume(ctx);
+    return accountId ? { accountId } : null;
+  }
+}
+```
+
+```ts
+// config/authkit.ts
+import WhatsappLogin from '#auth/whatsapp_login';
+export default defineConfig({
+  // issuer, adapter, accountStore, ...
+  customLoginMethods: { whatsapp: WhatsappLogin },
+});
+
+// Native form controller, on the host's POST /auth/interaction/:uid/... route
+return authenticateCustomLogin(ctx, 'whatsapp');
+```
+
+`authenticate` returns `{ accountId }` only after a valid proof, or `null` to deny login. It may also return a host-validated `remember` boolean; persistence is disabled by default and subject to the runtime session policy. The same session policy applies after MFA. Returning an identity does not skip MFA. The method name is retained in the OIDC `amr` claim, including when a second factor follows. Methods default to password-based policy; set `passwordless = true` for OTP, hardware or external proofs that do not use the account password.
+
+A method may implement `begin(ctx)` to initiate a challenge. Call `beginCustomLogin(ctx, 'whatsapp')` from the host route. Both dispatchers check the current OIDC interaction and its `:uid` before invoking the method. Method names contain lowercase letters, digits, `:`, `_` or `-`, start with a letter, and have at most 64 characters. Built-in factor names (`pwd`, `email`, `mfa`, `totp`, `webauthn`, `recovery`) are reserved. Registration does not automatically create routes or UI: the host owns validation, CSRF, rate limits, bot protection, delivery, proof expiry, replay protection, account lookup/signup and the response renderer. Use native form navigation for final completion so AuthKit can render MFA or redirect to the relying party.
+
+For an arbitrary flow that already verified its credential, `completeCustomLogin(ctx, { accountId, method, passwordless })` is the trusted escape hatch. Do not expose it as an endpoint accepting an account ID from the browser. A phone-only account may represent absent email as an empty string in the legacy `AuthAccount` DTO; OIDC omits `email` and `email_verified` in that case. `AuthAccount.phone`, when supplied, must represent a verified phone identity.
+
+Denied proofs and handler exceptions produce a `login.failure` audit event with the method ID and a sanitized reason; proof contents and exception messages are never included. Host-owned challenge/OTP verification endpoints must audit their own earlier failures.
+
+### WhatsApp OTP delivery providers
+
+`whatsapp.sender` accepts any `WhatsappCodeSender` instance or class. It is separate from `customLoginMethods`: login classes verify identity, senders only deliver a code. Configuring a sender does not create an OTP store, route, validator, signup flow, or UI.
+
+```ts
+import { inject } from '@adonisjs/core';
+import type { WhatsappCodeInput, WhatsappCodeSender } from '@adonis-agora/authkit-server';
+import MyWhatsappSdk from '#services/my_whatsapp_sdk';
+
+@inject()
+class MyProvider implements WhatsappCodeSender {
+  constructor(private sdk: MyWhatsappSdk) {}
+  async sendCode(input: WhatsappCodeInput): Promise<void> {
+    await this.sdk.sendText(input.phone, input.text ?? input.code);
+  }
+}
+
+export default defineConfig({
+  // issuer, adapter, accountStore, ...
+  customLoginMethods: { whatsapp: WhatsappLogin },
+  whatsapp: { sender: MyProvider }, // or an already-created instance
+});
+```
+
+After generating an OTP, resolve the sender through the request container:
+
+```ts
+const service = await ctx.containerResolver.make('authkit.server');
+const binding = service.config.whatsapp?.sender;
+if (!binding) throw new Error('WhatsApp login is not configured');
+const sender = await resolveWhatsappCodeSender(ctx.containerResolver, binding);
+await sender.sendCode({
+  phone: '5511999999999', code, locale: 'pt-BR', expiresInSeconds: 300,
+  text: ctx.i18n.t('auth.code_message', { code }),
+});
+```
+
+The sender must reject when delivery fails. The host should activate its stored OTP only after delivery acceptance and enforce expiry, retries, request binding, replay protection and rate limits. Provider acceptance is not a delivery/read receipt. `text` is optional localized copy for providers supporting free-form messages; structured providers receive the original code independently.
+
+Native adapters can be supplied as instances:
+
+```ts
+whatsapp: {
+  sender: new WhatsmiauCodeSender({ apiKey, instanceName }),
+}
+
+whatsapp: {
+  sender: new MetaWhatsappCodeSender({
+    accessToken, phoneNumberId, apiVersion, templateName,
+    languageCode: 'pt_BR',
+  }),
+}
+```
+
+Whatsmiau's optional `baseUrl` includes the API version path and defaults to `https://api.whatsmiau.dev/v2`. Meta requires an explicit supported Graph API version and an approved authentication template with an OTP/copy-code button. Template language must exist for the configured template; `languageCode` overrides automatic locale mapping (`pt-BR` → `pt_BR`, `en` → `en_US`, `es` → `es`). Meta template text and displayed expiry are managed in the approved template; `expiresInSeconds` describes the host's verification TTL and does not change template expiry. Both native adapters use bounded requests, reject redirects and discard provider error bodies so credentials/OTPs do not enter error messages.
+
+
+### Custom MFA methods (classes or instances)
+
+Register additional methods separately from primary login methods. Registration never enrolls an account: `isEnabled` must consult your enrollment store. A method may send a challenge in `begin`, describe its form fields, and verify a proof in `verify`.
+
+```ts
+import { inject } from '@adonisjs/core'
+import type { CustomMfaContext, CustomMfaMethod } from '@adonis-agora/authkit-server'
+
+// Enrollment and challenge services belong to your application and are injected by Adonis.
+@inject()
+export class WhatsappMfa implements CustomMfaMethod {
+  readonly factorId = 'phone'
+  constructor(private enrollment: PhoneEnrollment, private challenges: PhoneChallenges) {}
+
+  async isEnabled({ accountId }: CustomMfaContext) {
+    return this.enrollment.hasVerifiedPhone(accountId)
+  }
+  async describe() {
+    return { label: 'WhatsApp', fields: [{ name: 'code', label: 'Code', inputMode: 'numeric' as const }] }
+  }
+  async begin({ accountId, challengeId }: CustomMfaContext) {
+    await this.challenges.sendWhatsapp(accountId, challengeId)
+  }
+  async verify({ ctx, accountId, challengeId }: CustomMfaContext) {
+    const { code } = await ctx.request.validateUsing(phoneCodeValidator)
+    return this.challenges.consume(accountId, challengeId, code)
+  }
+}
+
+// In defineConfig:
+mfa: {
+  methods: { whatsapp: WhatsappMfa, sms: smsMfaInstance },
+  requiredFactors: 3,
+}
+```
+
+The sample enrollment/challenge services and Vine validator are host implementations. Bind proofs to both `accountId` and `challengeId`; expire them, hash stored codes, limit sends, and atomically consume successful proofs. Delivery can use the WhatsApp sender interface or any SMS/provider SDK. Proofs and provider credentials must never appear in descriptors.
+
+`requiredFactors` counts the primary login plus distinct additional groups (2 by default, configurable from 2 through 8). Omit it to challenge only accounts with an enrolled method; setting it explicitly also requires unenrolled accounts to enroll before they can authenticate. This extension does not supply an enrollment screen. Native TOTP, recovery codes and passkeys remain available; recovery and TOTP share one group. WhatsApp and SMS using the same phone must share `factorId: 'phone'`. A WhatsApp primary login class should also expose that group, preventing the same phone from counting twice. Group names express application policy; they do not prove independent physical authentication factors.
+
+AuthKit binds the challenge to the current login interaction and browser session, expires it after ten minutes, caps failed custom proofs at five, and completes OIDC only after the required number of groups. Edge and generated React challenge screens render custom descriptors and optional start buttons. The named POST routes `authkit.mfa.custom.begin` and `authkit.mfa.custom.verify` use the existing login throttling and CSRF pipeline. Public `beginCustomMfa`, `verifyCustomMfa`, and `customMfaViewProps` support host integrations; proof verification alone does not complete authentication. Use the registered routes for policy-controlled completion.
+
+Without `mfa` configuration, existing native MFA behavior is preserved. Applications can ship this extension without enabling additional methods.

package/build/host/views/mfa-challenge.edge

@@ -12,6 +12,12 @@
         {{ t('mfa_challenge.intro') }}
       </p>
 
+      @if(requiredMfaFactors > 2)
+        <p class="mt-3 text-sm text-gray-600" role="status">
+          {{ t('mfa_challenge.progress', { completed: 1 + (completedMfaMethods || []).length, required: requiredMfaFactors }) }}
+        </p>
+      @end
+
       @if(error)
         <p class="mt-4 text-sm text-red-600">{{ error }}</p>
       @end
@@ -21,7 +27,7 @@
            `totpAvailable === false` = a conta só tem passkey, sem app autenticador
            confirmado: pedir um código de 6 dígitos seria pedir o impossível. Ausente
            (stores que não reportam o estado) mantém o campo visível. --}}
-      @if(!noEnrollment && totpAvailable !== false)
+      @if(!noEnrollment && !otpLocked && totpAvailable !== false)
         <div class="mt-6">
           <label for="code" class="mb-1 block text-sm font-medium text-gray-700">{{ t('mfa_challenge.code_label') }}</label>
           <input id="code" name="code" inputmode="numeric" autocomplete="one-time-code"
@@ -43,6 +49,39 @@
       @end
     </form>
 
+    @if(!noEnrollment)
+      @each(method in (customMfaMethods || []))
+        @if(!(completedMfaMethods || []).includes(method.id))
+          <section class="mt-6">
+            <h2 class="text-sm font-semibold text-gray-900">{{ method.label }}</h2>
+            @if(method.requiresBegin && !method.started)
+              <form method="POST" action="{{ method.beginUrl }}" class="mt-3">
+                <input type="hidden" name="_csrf" value="{{ csrfToken }}">
+                <button type="submit" class="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">
+                  {{ t('mfa_challenge.start') }}
+                </button>
+              </form>
+            @else
+              <form method="POST" action="{{ method.verifyUrl }}" class="mt-3 space-y-3">
+                <input type="hidden" name="_csrf" value="{{ csrfToken }}">
+                @each(field in (method.fields || []))
+                  <div>
+                    <label for="custom-{{ method.id }}-{{ field.name }}" class="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' }}"
+                      class="w-full rounded-lg border border-gray-300 px-3 py-2 text-base outline-hidden focus:border-gray-900 focus:ring-2 focus:ring-gray-900">
+                  </div>
+                @end
+                <button type="submit" class="w-full rounded-lg bg-gray-900 px-3 py-2.5 text-sm font-semibold text-white transition hover:opacity-90">
+                  {{ t('mfa_challenge.submit') }}
+                </button>
+              </form>
+            @end
+          </section>
+        @end
+      @end
+    @end
+
     @if(passkeyAvailable && !noEnrollment)
       {{-- Passkey como alternativa ao código TOTP. O form é submetido por página
            inteira (não fetch) para que o 303 de volta ao client navegue o browser. --}}
@@ -61,7 +100,7 @@
 
     {{-- Códigos de recuperação só existem junto com o TOTP (são gerados no
          enrollment); sem ele, a seção não tem o que receber. --}}
-    @if(!noEnrollment && totpAvailable !== false)
+    @if(!noEnrollment && !otpLocked && totpAvailable !== false)
       <details class="mt-6 text-sm text-gray-600">
         <summary class="cursor-pointer hover:underline">{{ t('mfa_challenge.recovery_summary') }}</summary>
         <form method="POST" action="/auth/interaction/{{ uid }}/mfa" class="mt-3">
@@ -77,7 +116,7 @@
     @end
   </div>
 
-  @if(passkeyAvailable)
+  @if(passkeyAvailable && !noEnrollment)
     {{-- M12: script inline sem nonce é bloqueado por CSP `script-src 'self'` — extraído
          para asset same-origin (compartilhado com login.edge). --}}
     <script type="module" src="/authkit/assets/passkey_button.js"></script>

package/build/index.d.ts

@@ -76,12 +76,16 @@ export { deriveLockedSettingKeys, isSettingLocked, lockedSettingKeys, POLICY_ROU
 export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from './src/host/console_session.js';
 export type { AuthkitCsrfOptions } from './src/host/csrf.js';
 export { authkitCsrfExceptions } from './src/host/csrf.js';
+export type { CustomLoginIdentity, CustomLoginMethod, CustomLoginMethodBinding, CustomLoginMethodConstructor, CustomLoginMethods, } from './src/host/custom_login.js';
+export { authenticateCustomLogin, beginCustomLogin, completeCustomLogin, } from './src/host/custom_login.js';
+export type { CustomMfaContext, CustomMfaDescription, CustomMfaDescriptor, CustomMfaField, CustomMfaMethod, CustomMfaMethodBinding, CustomMfaMethodConstructor, CustomMfaMethods, } from './src/host/custom_mfa.js';
+export { beginCustomMfa, customMfaViewProps, verifyCustomMfa } from './src/host/custom_mfa.js';
 export { normalizeEmailIdentifier } from './src/host/email_identifier.js';
 export type { ResolveGeo } from './src/host/geo.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export type { AuthMessages, I18nConfig } from './src/host/i18n.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
-export { ensureConsoleSession } from './src/host/idp_session_bridge.js';
+export { ACCOUNT_IDP_SESSION_KEY, ensureConsoleSession, readIdpSession, } from './src/host/idp_session_bridge.js';
 export type { ImpersonationClientLike, ImpersonationPanel } from './src/host/impersonation.js';
 export { buildImpersonationPanel } from './src/host/impersonation.js';
 export type { ImpersonationStartErrorCode, ImpersonationState, StartImpersonationParams, StopImpersonationOptions, TokenExchangeResult, } from './src/host/impersonation_session.js';
@@ -93,6 +97,8 @@ export { OidcBearerGuard, oidcBearerGuard } from './src/host/oidc_bearer_guard.j
 export type { OidcRpGuardEvents, OidcRpGuardOptions } from './src/host/oidc_rp_guard.js';
 export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, type OtpLoginConfigInput, type OtpVerifyOutcome, type ResolvedOtpLoginConfig, resolveOtpLoginConfig, } from './src/host/otp_login.js';
+export type { PersistentRpOptions } from './src/host/persistent_rp_session.js';
+export { endRpSession } from './src/host/persistent_rp_session.js';
 export type { AuthThrottles, ThrottleMiddleware } from './src/host/rate_limit.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export type { AccountScreensOptions, AuthHostOptions, AuthHostRouteMap, } from './src/host/register_auth_host.js';
@@ -117,6 +123,8 @@ export type { ParsedUserAgent } from './src/host/user_agent.js';
 export { parseUserAgent } from './src/host/user_agent.js';
 export type { ResolvedUserLoginMethods, UserLoginMethodKey, UserLoginMethods, } from './src/host/user_login_methods.js';
 export { normalizeUserLoginMethods, parseUserLoginMethodsPayload, resolveEffectiveUserLoginMethods, USER_LOGIN_METHOD_KEYS, } from './src/host/user_login_methods.js';
+export type { MetaWhatsappCodeSenderOptions, WhatsappCodeInput, WhatsappCodeSender, WhatsappCodeSenderBinding, WhatsappCodeSenderConstructor, WhatsmiauCodeSenderOptions, } from './src/host/whatsapp_code_sender.js';
+export { MetaWhatsappCodeSender, resolveWhatsappCodeSender, WhatsmiauCodeSender, } from './src/host/whatsapp_code_sender.js';
 export { MCP_CLIENT_REDIRECTS, MCP_RESOURCE_SCOPES, type McpOAuthConfigInput, type OAuthResourceRegistration, registeredOAuthResources, registerOAuthResource, } from './src/mcp/mcp_oauth.js';
 export { withAuditLog } from './src/mixins/with_audit_log.js';
 export { withAuthUser } from './src/mixins/with_auth_user.js';

package/build/index.js

@@ -54,10 +54,12 @@ export { assertClientMetadata, ClientMetadataError, redirectUriProblem, } from '
 export { deriveLockedSettingKeys, isSettingLocked, lockedSettingKeys, POLICY_ROUTE_OPTIONS, resetLockedSettingKeys, SettingLockedError, setLockedSettingKeys, } from './src/host/config_locks.js';
 export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from './src/host/console_session.js';
 export { authkitCsrfExceptions } from './src/host/csrf.js';
+export { authenticateCustomLogin, beginCustomLogin, completeCustomLogin, } from './src/host/custom_login.js';
+export { beginCustomMfa, customMfaViewProps, verifyCustomMfa } from './src/host/custom_mfa.js';
 export { normalizeEmailIdentifier } from './src/host/email_identifier.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
-export { ensureConsoleSession } from './src/host/idp_session_bridge.js';
+export { ACCOUNT_IDP_SESSION_KEY, ensureConsoleSession, readIdpSession, } from './src/host/idp_session_bridge.js';
 export { buildImpersonationPanel } from './src/host/impersonation.js';
 // Session impersonation — RP-side glue that routes through the IdP's RFC 8693
 // token-exchange (the IdP validates the admin role + audits). See
@@ -77,6 +79,7 @@ export { OidcBearerGuard, oidcBearerGuard } from './src/host/oidc_bearer_guard.j
 export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 // Login por OTP (código digitável): config + helpers puros.
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, resolveOtpLoginConfig, } from './src/host/otp_login.js';
+export { endRpSession } from './src/host/persistent_rp_session.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
@@ -110,6 +113,7 @@ export { buildTrustedDevicePayload, isTrustedDeviceValid, resolveTrustedDevices,
 export { parseUserAgent } from './src/host/user_agent.js';
 // Tipos de login POR USUÁRIO (self-service no console de conta).
 export { normalizeUserLoginMethods, parseUserLoginMethodsPayload, resolveEffectiveUserLoginMethods, USER_LOGIN_METHOD_KEYS, } from './src/host/user_login_methods.js';
+export { MetaWhatsappCodeSender, resolveWhatsappCodeSender, WhatsmiauCodeSender, } from './src/host/whatsapp_code_sender.js';
 export { MCP_CLIENT_REDIRECTS, MCP_RESOURCE_SCOPES, registeredOAuthResources, registerOAuthResource, } from './src/mcp/mcp_oauth.js';
 export { withAuditLog } from './src/mixins/with_audit_log.js';
 export { withAuthUser } from './src/mixins/with_auth_user.js';

package/build/src/accounts/account_store.d.ts

@@ -3,6 +3,8 @@ import type { UserLoginMethods } from '../host/user_login_methods.js';
 export interface AuthAccount {
     id: string;
     email: string;
+    /** Host-verified phone identity. Omit until possession has been verified. */
+    phone?: string;
     globalRoles?: string[];
     name?: string;
     avatarUrl?: string;

package/build/src/accounts/lucid_account_store.js

@@ -182,6 +182,7 @@ export function lucidAccountStore(Model, options = {}) {
             // token (e para todo call-site tipado como string).
             id: String(row.id),
             email: row.email,
+            ...(row.phone && row.phoneVerifiedAt ? { phone: row.phone } : {}),
             globalRoles: row.globalRoles ?? [],
             name: row.fullName ?? undefined,
             avatarUrl: row.avatarUrl ?? undefined,
@@ -328,6 +329,7 @@ export async function lucidAccountStoreAsync(Model, options = {}) {
                     // Ver a nota em `toAccount` acima: `sub` precisa ser string.
                     id: String(row.id),
                     email: row.email,
+                    ...(row.phone && row.phoneVerifiedAt ? { phone: row.phone } : {}),
                     globalRoles: row.globalRoles ?? [],
                     name: row.fullName ?? undefined,
                     avatarUrl: row.avatarUrl ?? undefined,

package/build/src/adapters/adapter_contract.d.ts

@@ -24,6 +24,8 @@ export interface OidcAdapter {
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     consume(id: string): Promise<void>;
     destroy(id: string): Promise<void>;
+    /** Extend an existing remembered Session atomically; never recreate revoked records. */
+    renewSession?(id: string, expiresIn: number): Promise<boolean>;
     revokeByGrantId(grantId: string): Promise<void>;
     /**
      * Enumeração GENÉRICA dos artefatos do model deste adapter (id + payload). Usada

package/build/src/adapters/database_adapter.d.ts

@@ -6,6 +6,7 @@ export declare class DatabaseAdapter implements OidcAdapter {
     private db;
     constructor(name: string, db: Database);
     upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
+    renewSession(id: string, expiresIn: number): Promise<boolean>;
     find(id: string): Promise<OidcPayload | undefined>;
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     findByUserCode(userCode: string): Promise<OidcPayload | undefined>;

package/build/src/adapters/database_adapter.js

@@ -38,6 +38,32 @@ export class DatabaseAdapter {
         }
         return JSON.parse(record.payload);
     }
+    async renewSession(id, expiresIn) {
+        if (this.name !== 'Session' || !Number.isSafeInteger(expiresIn) || expiresIn < 1)
+            return false;
+        const row = await this.#query().where('id', id).first();
+        const payload = await this.#parse(row);
+        const now = Date.now();
+        if (!payload ||
+            payload.transient ||
+            typeof payload.exp !== 'number' ||
+            payload.exp <= now / 1000)
+            return false;
+        // Compare-and-set: concurrent logout or mutation cannot be undone by renewal.
+        const changed = await this.#query()
+            .where('id', id)
+            .where('payload', row.payload)
+            .where('expires_at', '>', new Date(now).toISOString())
+            .update({
+            payload: JSON.stringify({ ...payload, exp: Math.floor(now / 1000) + expiresIn }),
+            expires_at: new Date(now + expiresIn * 1000).toISOString(),
+        });
+        if (Number(changed) > 0)
+            return true;
+        // A parallel renewal is harmless; a deletion must remain deleted.
+        const current = await this.find(id);
+        return Boolean(current && !current.transient && typeof current.exp === 'number' && current.exp > now / 1000);
+    }
     async find(id) {
         return this.#parse(await this.#query().where('id', id).first());
     }

package/build/src/adapters/redis_adapter.d.ts

@@ -7,6 +7,7 @@ export declare class RedisAdapter implements OidcAdapter {
     private prefix;
     constructor(name: string, redis: Redis, prefix: string);
     upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
+    renewSession(id: string, expiresIn: number): Promise<boolean>;
     find(id: string): Promise<OidcPayload | undefined>;
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     findByUserCode(userCode: string): Promise<OidcPayload | undefined>;

package/build/src/adapters/redis_adapter.js

@@ -52,6 +52,36 @@ export class RedisAdapter {
             multi.expire(key, expiresIn);
         await multi.exec();
     }
+    async renewSession(id, expiresIn) {
+        if (this.name !== 'Session' || !Number.isSafeInteger(expiresIn) || expiresIn < 1)
+            return false;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const raw = await this.redis.get(this.#key(id));
+            if (!raw)
+                return false;
+            const payload = JSON.parse(raw);
+            const now = Math.floor(Date.now() / 1000);
+            if (payload.transient || typeof payload.exp !== 'number' || payload.exp <= now)
+                return false;
+            const updated = JSON.stringify({ ...payload, exp: now + expiresIn });
+            const result = await this.redis.eval(`
+        local raw = redis.call('GET', KEYS[1])
+        if not raw then return 0 end
+        if raw ~= ARGV[1] then return 2 end
+        redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
+        if ARGV[4] ~= '' then redis.call('SET', KEYS[2], ARGV[4], 'EX', ARGV[3]) end
+        return 1
+      `, 2, this.#key(id), payload.uid ? this.#uidKey(payload.uid) : this.#key(id), raw, updated, expiresIn, payload.uid ? id : '');
+            if (result !== 2)
+                return result === 1;
+        }
+        // Another request may have renewed while we were comparing the payload.
+        const current = await this.find(id);
+        return Boolean(current &&
+            !current.transient &&
+            typeof current.exp === 'number' &&
+            current.exp > Date.now() / 1000);
+    }
     async find(id) {
         const data = await this.redis.get(this.#key(id));
         if (!data)

package/build/src/define_config.d.ts

@@ -8,12 +8,15 @@ import { type EventsConfigInput } from './events/dispatcher.js';
 import { type BotProtectionConfigInput, type ResolvedBotProtectionConfig } from './host/bot_protection.js';
 import { type BrandingConfig } from './host/branding.js';
 import { type PolicyRouteOption } from './host/config_locks.js';
+import type { CustomLoginMethods } from './host/custom_login.js';
+import type { CustomMfaMethods } from './host/custom_mfa.js';
 import type { ResolveGeo } from './host/geo.js';
 import { type AuthMessages, type I18nConfig } from './host/i18n.js';
 import { type OtpLoginConfigInput, type ResolvedOtpLoginConfig } from './host/otp_login.js';
 import type { AuthHostOptions } from './host/register_auth_host.js';
 import type { SudoMethod } from './host/sudo/types.js';
 import { type ResolvedTrustedDevicesConfig, type TrustedDevicesConfigInput } from './host/trusted_device.js';
+import type { WhatsappCodeSenderBinding } from './host/whatsapp_code_sender.js';
 import { type McpOAuthConfigInput, type ResolvedMcpOAuthConfig } from './mcp/mcp_oauth.js';
 import type { PatStore } from './pat/pat_store.js';
 import { type RedirectUriPolicy, type ResolvedRedirectUriPolicy, type ValidateRegistrationHook } from './provider/registration_policy.js';
@@ -759,6 +762,17 @@ export interface ResolvedInteractionRecoveryConfig {
     redirectTo?: string;
 }
 export interface AuthServerConfigInput {
+    /** Host-defined primary authentication classes or instances, keyed by stable method ID. */
+    customLoginMethods?: CustomLoginMethods;
+    /** Optional enrolled factor registry and total distinct factor count (primary included). */
+    mfa?: {
+        methods?: CustomMfaMethods;
+        requiredFactors?: number;
+    };
+    /** OTP delivery only. The host remains responsible for issuing and verifying codes. */
+    whatsapp?: {
+        sender: WhatsappCodeSenderBinding;
+    };
     issuer: string;
     adapter: AdapterFactory;
     /**
@@ -1152,6 +1166,16 @@ export interface AuthServerConfigInput {
     };
 }
 export interface ResolvedServerConfig {
+    customLoginMethods?: CustomLoginMethods;
+    /** Optional enrolled factor registry and total distinct factor count (primary included). */
+    mfa?: {
+        methods?: CustomMfaMethods;
+        requiredFactors?: number;
+    };
+    /** OTP delivery only. The host remains responsible for issuing and verifying codes. */
+    whatsapp?: {
+        sender: WhatsappCodeSenderBinding;
+    };
     issuer: string;
     AdapterClass: OidcAdapterClass;
     /**

package/build/src/define_config.js

@@ -273,6 +273,11 @@ export function jwksAutoFallbackWarning(storePath) {
     return `AuthKit: jwks 'auto' caiu no fallback de disco (${storePath}) — a chave privada de assinatura será persistida em arquivo. Para produção, defina AUTHKIT_JWKS (secret manager) ou configure jwks.store explicitamente.`;
 }
 export function defineConfig(config) {
+    const requiredFactors = config.mfa?.requiredFactors;
+    if (requiredFactors !== undefined &&
+        (!Number.isInteger(requiredFactors) || requiredFactors < 2 || requiredFactors > 8)) {
+        throw new Error('mfa.requiredFactors must be an integer between 2 and 8');
+    }
     return configProvider.create(async (app) => {
         const AdapterClass = await config.adapter.resolver(app);
         // `session.adapter` ausente ⇒ mesma classe do default (back-compat: o
@@ -394,6 +399,9 @@ export function defineConfig(config) {
                 return acc ? { id: acc.id } : null;
             },
             accountStore: config.accountStore,
+            customLoginMethods: config.customLoginMethods,
+            mfa: config.mfa,
+            whatsapp: config.whatsapp,
             patStore: config.patStore,
             mountPath: config.mountPath ?? '/oidc',
             accountHome: config.accountHome,

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

@@ -158,15 +158,19 @@ export default class AccountSecurityController {
             return ctx.response.redirect(getAccountLoginUrl());
         }
         const { currentPassword, confirmEmail } = await ctx.request.validateUsing(deleteAccountValidator);
-        // Confirmação: senha atual correta OU e-mail digitado batendo com o da conta
-        // (case-insensitive). Sem nenhuma das duas → recusa (não deleta).
+        // Confirmação: senha atual correta OU e-mail digitado batendo com o da conta.
+        // Contas sem e-mail podem confirmar o telefone já verificado pelo host.
         let confirmed = false;
         if (currentPassword) {
             confirmed = !!(await store.verifyCredentials(account.email, currentPassword));
         }
         if (!confirmed && confirmEmail) {
-            confirmed =
-                normalizeEmailIdentifier(confirmEmail) === normalizeEmailIdentifier(account.email);
+            confirmed = account.email
+                ? normalizeEmailIdentifier(confirmEmail) === normalizeEmailIdentifier(account.email)
+                : !!account.phone &&
+                    /^[+\d\s().-]+$/.test(confirmEmail) &&
+                    /\d/.test(confirmEmail) &&
+                    confirmEmail.replace(/\D/g, '') === account.phone.replace(/\D/g, '');
         }
         if (!confirmed) {
             ctx.session.flash('deleteError', translate(cfg.messages, 'account.delete.invalid_confirmation'));

package/build/src/host/controllers/interaction_controller.d.ts

@@ -1,7 +1,14 @@
 import '../augmentations.js';
 import type { HttpContext } from '@adonisjs/core/http';
+import { type CustomLoginIdentity } from '../custom_login.js';
 export default class AuthInteractionController {
     #private;
+    /** Shared completion for trusted host authentication; primary proof is the host's responsibility. */
+    completeCustomLogin(ctx: HttpContext, input: CustomLoginIdentity & {
+        method: string;
+        factorId?: string;
+        passwordless?: boolean;
+    }): Promise<unknown>;
     show(ctx: HttpContext): Promise<any>;
     /**
      * POST /auth/interaction/:uid/identifier
@@ -29,7 +36,12 @@ export default class AuthInteractionController {
      * 2º fator: lê o accountId pendente da sessão e aceita um código TOTP (`code`)
      * OU um recovery code (`recoveryCode`). Em caso de sucesso finaliza a interaction.
      */
-    mfaVerify(ctx: HttpContext): Promise<any>;
+    private renderMfaChallenge;
+    private configuredMfaGate;
+    customMfaBegin(ctx: HttpContext): Promise<unknown>;
+    customMfaVerify(ctx: HttpContext): Promise<unknown>;
+    private finishVerifiedMfa;
+    mfaVerify(ctx: HttpContext): Promise<unknown>;
     /**
      * true se o authorize request exige MFA via acr_values (contém o mfaAcr da
      * config de step-up). `acr_values` é a string separada por espaços padrão OIDC.