@adonis-agora/authkit-server 0.60.0 → 0.61.0

package/build/providers/authkit_server_provider.js

@@ -77,6 +77,13 @@ export default class AuthkitServerProvider {
                         // Defaults estruturais de `config.routes` (o argumento ainda vence).
                         routes: typeof config.routes === 'object' ? config.routes : undefined,
                         lockedRouteOptions: config.lockedRouteOptions,
+                        // API headless — repassa pro registerAuthHost montar as rotas.
+                        headless: config.headless
+                            ? {
+                                baseUrl: config.headless.baseUrl,
+                                resolveAccountId: config.headless.resolveAccountId,
+                            }
+                            : undefined,
                     });
                 }
             }

package/build/src/define_config.d.ts

@@ -822,6 +822,24 @@ export interface AuthServerConfigInput {
     i18n?: I18nConfig;
     /** Configuração de providers sociais. */
     social?: AuthSocialConfig;
+    /**
+     * API headless do AuthKit (Clerk-style). Quando declarada, o host-kit monta
+     * uma JSON API (`GET/PUT {baseUrl}/login-methods`) autenticada por um resolver
+     * de conta fornecido pelo HOST (`resolveAccountId`) — tipicamente a própria
+     * sessão do RP (`await ctx.auth.getUserOrFail()`). Assim um app usa AuthKit
+     * como frontend sem expor o console `/account/*`. Default: desligado (opt-in).
+     */
+    headless?: {
+        /** Base da JSON API headless. Default: `/api/authkit`. */
+        baseUrl?: string;
+        /**
+         * Resolve o id da conta (na identidade do IdP) a partir do contexto da
+         * request do HOST. Retorne null quando não autenticado → 401. Um `throw`
+         * do resolver também vira 401. O id deve ser o mesmo `sub`/`AuthAccount.id`
+         * usado pelo account store (no entre-textos, `auth.user.id === app.user.id`).
+         */
+        resolveAccountId: (ctx: import('@adonisjs/core/http').HttpContext) => string | null;
+    };
     /** Segredo para autenticar requests de introspecção de PAT. */
     patIntrospectionSecret?: string;
     /** Rate-limiting das rotas sensíveis (anti-brute-force). Default: ligado (no-op se o limiter não estiver configurado). */
@@ -1075,6 +1093,11 @@ export interface ResolvedServerConfig {
     firstPartyClients?: string[];
     social?: AuthSocialConfig;
     patIntrospectionSecret?: string;
+    /** API headless resolvida (Clerk-style). Presente só quando o host a declarou. */
+    headless?: {
+        baseUrl: string;
+        resolveAccountId: (ctx: import('@adonisjs/core/http').HttpContext) => string | null;
+    };
     rateLimit: ResolvedRateLimitConfig;
     /** Bloqueio progressivo de conta resolvido (sempre presente; default ligado). */
     lockout: ResolvedLockoutConfig;

package/build/src/define_config.js

@@ -395,6 +395,12 @@ export function defineConfig(config) {
             passwordless: resolvePasswordless(config.passwordless),
             authMethods: resolveAuthMethodsConfig(config.authMethods),
             login: resolveLogin(config.login),
+            headless: config.headless
+                ? {
+                    baseUrl: config.headless.baseUrl ?? '/api/authkit',
+                    resolveAccountId: config.headless.resolveAccountId,
+                }
+                : undefined,
             registration: resolveRegistration(config.registration),
             accessTokens: resolveAccessTokens(config.issuer, config.accessTokens),
             admin: resolveAdmin(config.admin),

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

@@ -1,3 +1,4 @@
+import type { HttpContext } from '@adonisjs/core/http';
 import type { AuthSocialConfig, ResolvedRateLimitConfig } from '../define_config.js';
 import type { PolicyRouteOption } from './config_locks.js';
 import type { AuthHostOptions } from './register_auth_host.js';
@@ -34,6 +35,14 @@ export interface AuthHostRuntimeConfig {
      * Ver `deriveLockedRouteOptions`.
      */
     lockedRouteOptions?: PolicyRouteOption[];
+    /**
+     * API headless (Clerk-style). Presente quando o host a declarou — o provider o
+     * stash no boot para `registerAuthHost` montar as rotas sem reler o config inteiro.
+     */
+    headless?: {
+        baseUrl: string;
+        resolveAccountId: (ctx: HttpContext) => string | null;
+    };
 }
 /** Stash dos bits de routing (chamado no boot do provider). */
 export declare function setAuthHostConfig(config: AuthHostRuntimeConfig): void;

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

@@ -0,0 +1,31 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * API headless do AuthKit (Clerk-style).
+ *
+ * Diferente da JSON API do console (`/account/api/*`, guardada pela sessão de
+ * CONTA), esta API é protegida por um resolver de conta fornecido pelo HOST
+ * (`headless.resolveAccountId`) — tipicamente a própria sessão do app
+ * (`await ctx.auth.getUserOrFail()`). Assim um RP integrado usa o app como
+ * frontend sem expor o console `/account/*`.
+ */
+export default class HeadlessLoginMethodsController {
+    #private;
+    /**
+     * GET {baseUrl}/login-methods
+     * Estado final de tipos de login para a conta resolvida pelo host.
+     */
+    index(ctx: HttpContext): Promise<void | import("../login_methods_state.js").LoginMethodsState>;
+    /**
+     * PUT {baseUrl}/login-methods
+     * Grava a preferência de tipos de login para a conta resolvida pelo host.
+     */
+    update(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        methods: {
+            password?: boolean;
+            magicLink?: boolean;
+            passkey?: boolean;
+            social?: boolean;
+        };
+    }>;
+}

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

@@ -0,0 +1,79 @@
+import { supportsLoginMethodsPreference } from '../../accounts/account_store.js';
+import { loginMethodsStateForAccount, resolveGlobalAuthMethods } from '../login_methods_state.js';
+import { resolveRuntimeSettingsOrNoop } from '../runtime_settings.js';
+import { parseUserLoginMethodsPayload } from '../user_login_methods.js';
+/** Erro JSON padrão. */
+function apiErr(code, message) {
+    return { error: { code, message } };
+}
+/**
+ * API headless do AuthKit (Clerk-style).
+ *
+ * Diferente da JSON API do console (`/account/api/*`, guardada pela sessão de
+ * CONTA), esta API é protegida por um resolver de conta fornecido pelo HOST
+ * (`headless.resolveAccountId`) — tipicamente a própria sessão do app
+ * (`await ctx.auth.getUserOrFail()`). Assim um RP integrado usa o app como
+ * frontend sem expor o console `/account/*`.
+ */
+export default class HeadlessLoginMethodsController {
+    /**
+     * GET {baseUrl}/login-methods
+     * Estado final de tipos de login para a conta resolvida pelo host.
+     */
+    async index(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const accountId = await this.#resolveAccount(ctx, cfg);
+        if (!accountId) {
+            return ctx.response.unauthorized(apiErr('unauthorized', 'Not authenticated.'));
+        }
+        const settings = await resolveRuntimeSettingsOrNoop(ctx);
+        return loginMethodsStateForAccount(accountId, cfg.accountStore, settings, cfg);
+    }
+    /**
+     * PUT {baseUrl}/login-methods
+     * Grava a preferência de tipos de login para a conta resolvida pelo host.
+     */
+    async update(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const accountId = await this.#resolveAccount(ctx, cfg);
+        if (!accountId) {
+            return ctx.response.unauthorized(apiErr('unauthorized', 'Not authenticated.'));
+        }
+        if (!supportsLoginMethodsPreference(cfg.accountStore)) {
+            return ctx.response.notFound(apiErr('not_supported', 'Login methods preference not supported.'));
+        }
+        const parsed = parseUserLoginMethodsPayload(ctx.request.body());
+        if (!parsed.ok) {
+            return ctx.response.badRequest(apiErr(parsed.error, 'Invalid login methods payload.'));
+        }
+        // All-off guard: preferência não pode zerar todos os métodos globais.
+        const settings = await resolveRuntimeSettingsOrNoop(ctx);
+        const { resolved: global } = await resolveGlobalAuthMethods(settings, cfg);
+        const value = { ...parsed.value };
+        const wouldBeAllOff = (value.password === false || !global.password) &&
+            (value.magicLink === false || !global.magicLink) &&
+            (value.passkey === false || !global.passkey) &&
+            (value.social === false || global.social.length === 0);
+        if (wouldBeAllOff) {
+            return ctx.response.badRequest(apiErr('all_methods_off', 'Cannot disable every login method.'));
+        }
+        await cfg.accountStore.setLoginMethods(accountId, Object.keys(value).length > 0 ? value : null);
+        return { ok: true, methods: value };
+    }
+    /** Delega ao resolver do host; null (ou throw de auth) => 401. */
+    async #resolveAccount(ctx, cfg) {
+        const resolve = cfg.headless?.resolveAccountId;
+        if (!resolve)
+            return null;
+        try {
+            const id = await resolve(ctx);
+            return id ? String(id) : null;
+        }
+        catch {
+            // Resolver do host lançou (ex.: auth.getUserOrFail sem sessão) → não-autorizado.
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+import type { SettingsCapability } from './runtime_settings.js';
+import { type UserLoginMethods } from './user_login_methods.js';
+/** Resultado compartilhado de "estado de tipos de login" entregue à UI. */
+export interface LoginMethodsState {
+    supported: boolean;
+    /** Preferência crua do usuário; {} = sem preferência (herda globais). */
+    methods: UserLoginMethods | Record<string, never>;
+    /** Estado final por método (global ∩ preferência) — o que a tela de login mostra. */
+    available: {
+        password: boolean;
+        magicLink: boolean;
+        passkey: boolean;
+        social: string[];
+        forgotPassword: boolean;
+    } | null;
+    /** Métodos fora do controle do usuário (globalmente off ou pin de config). */
+    locked: {
+        password: boolean;
+        magicLink: boolean;
+        passkey: boolean;
+        social: boolean;
+    } | null;
+}
+/**
+ * Métodos globais efetivos + pins de config — resolução compartilhada entre o
+ * console (account API) e a API headless. Fail-safe: erro → defaults.
+ */
+export declare function resolveGlobalAuthMethods(settings: SettingsCapability, cfg: ResolvedServerConfig): Promise<{
+    resolved: import("./runtime_toggles.js").ResolvedAuthMethods;
+    locked: (keyof import("./runtime_toggles.js").AuthMethodsConfigOverride)[];
+}>;
+/**
+ * Monta o estado final de tipos de login para uma conta, intersectando a
+ * preferência do usuário com os métodos globais efetivos. Reusado pelo console
+ * de conta (`/account/api/login-methods`) e pela API headless
+ * (`{baseUrl}/login-methods`) — sem duplicar regra.
+ */
+export declare function loginMethodsStateForAccount(accountId: string, store: ResolvedServerConfig['accountStore'], settings: SettingsCapability, cfg: ResolvedServerConfig): Promise<LoginMethodsState>;

package/build/src/host/login_methods_state.js

@@ -0,0 +1,52 @@
+import { supportsMagicLink } from '../accounts/account_store.js';
+import { supportsPasskeys } from '../accounts/account_store.js';
+import { supportsLoginMethodsPreference } from '../accounts/account_store.js';
+import { resolveEffectiveAuthMethods } from './runtime_toggles.js';
+import { configLockedAuthMethods } from './runtime_toggles.js';
+import { normalizeUserLoginMethods, resolveEffectiveUserLoginMethods, } from './user_login_methods.js';
+/**
+ * Métodos globais efetivos + pins de config — resolução compartilhada entre o
+ * console (account API) e a API headless. Fail-safe: erro → defaults.
+ */
+export async function resolveGlobalAuthMethods(settings, cfg) {
+    const resolved = await resolveEffectiveAuthMethods(settings, {
+        configuredSocialProviders: cfg.social?.providers ?? [],
+        magicLinkCapable: cfg.passwordless?.magicLink && supportsMagicLink(cfg.accountStore),
+        passkeyCapable: supportsPasskeys(cfg.accountStore),
+        configOverrides: cfg.authMethods,
+    });
+    return { resolved, locked: configLockedAuthMethods(cfg.authMethods) };
+}
+/**
+ * Monta o estado final de tipos de login para uma conta, intersectando a
+ * preferência do usuário com os métodos globais efetivos. Reusado pelo console
+ * de conta (`/account/api/login-methods`) e pela API headless
+ * (`{baseUrl}/login-methods`) — sem duplicar regra.
+ */
+export async function loginMethodsStateForAccount(accountId, store, settings, cfg) {
+    if (!supportsLoginMethodsPreference(store)) {
+        return { supported: false, methods: {}, available: null, locked: null };
+    }
+    const pref = normalizeUserLoginMethods(await store.getLoginMethods(accountId));
+    const { resolved: global, locked: cfgLocked } = await resolveGlobalAuthMethods(settings, cfg);
+    const effective = resolveEffectiveUserLoginMethods(global, pref);
+    return {
+        supported: true,
+        // Preferência crua do usuário; {} = sem preferência (herda globais).
+        methods: pref ?? {},
+        available: {
+            password: effective.password,
+            magicLink: effective.magicLink,
+            passkey: effective.passkey,
+            social: effective.social,
+            forgotPassword: effective.forgotPassword,
+        },
+        // Métodos que o usuário NÃO pode controlar (globalmente off ou pin de config).
+        locked: {
+            password: !global.password || cfgLocked.includes('password'),
+            magicLink: !global.magicLink || cfgLocked.includes('magicLink'),
+            passkey: !global.passkey || cfgLocked.includes('passkey'),
+            social: global.social.length === 0,
+        },
+    };
+}

package/build/src/host/register_auth_host.js

@@ -201,6 +201,8 @@ const C = {
     apiKeys: () => import('./admin_api/api_keys_controller.js'),
     // Account self-service JSON API (session-authed, under /account/api/*).
     accountApi: () => import('./account_api/account_api_controller.js'),
+    // API headless (Clerk-style) — host-session-authed via `headless.resolveAccountId`.
+    headlessLoginMethods: () => import('./controllers/headless_login_methods_controller.js'),
 };
 /**
  * Monta todas as rotas do host-kit do Authorization Server numa chamada.
@@ -622,6 +624,19 @@ export function registerAuthHost(router, opts = {}) {
         router.get(`${apiBase}/orgs/:id`, [C.accountApi, 'showOrg']);
     })
         .use([accountGuard]);
+    // API headless (Clerk-style) — montada fora do `accountGuard` (não depende da
+    // sessão de CONTA), autenticada pelo resolver do host (`headless.resolveAccountId`).
+    // `PUT` usa CSRF igual à API do console (middleware de shield do host).
+    const headlessCfg = hostCfg?.headless;
+    if (headlessCfg) {
+        const hb = headlessCfg.baseUrl;
+        router
+            .get(`${hb}/login-methods`, [C.headlessLoginMethods, 'index'])
+            .as('authkit.headless.login_methods.index');
+        router
+            .put(`${hb}/login-methods`, [C.headlessLoginMethods, 'update'])
+            .as('authkit.headless.login_methods.update');
+    }
     // Prefixos resolvidos dos consoles — `null` quando o grupo não foi montado.
     // Compõem o `AuthHostRouteMap` devolvido no fim.
     let resolvedAdminPrefix = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.60.0",
+  "version": "0.61.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",
@@ -23,7 +23,8 @@
     "identity-provider",
     "rate-limiting",
     "mfa",
-    "totp"
+    "totp",
+    "tanstack-intent"
   ],
   "publishConfig": {
     "access": "public"
@@ -33,7 +34,8 @@
   "types": "./build/index.d.ts",
   "files": [
     "build",
-    "stubs"
+    "stubs",
+    "skills"
   ],
   "exports": {
     ".": "./build/index.js",
@@ -113,6 +115,7 @@
   "devDependencies": {
     "@adonis-agora/durable": "0.22.0",
     "@adonis-agora/telescope": "0.6.0",
+    "@tanstack/intent": "^0.3.2",
     "@adonisjs/ally": "6.3.0",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.4.0",
@@ -150,7 +153,7 @@
     "react-error-boundary": "6.1.2",
     "nuqs": "2.9.5",
     "recharts": "3.10.1",
-    "@adonis-agora/authkit-react": "0.20.0"
+    "@adonis-agora/authkit-react": "0.20.1"
   },
   "scripts": {
     "build": "node scripts/build_host_css.mjs && node scripts/build_webauthn.mjs && node scripts/build_ui.mjs && node -e \"const fs=require('node:fs');for(const d of ['build/stubs','build/host/views'])fs.rmSync(d,{recursive:true,force:true})\" && tsc && node -e \"require('node:fs').cpSync('src/host/assets','build/src/host/assets',{recursive:true})\" && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\" && node -e \"const fs=require('node:fs');if(fs.existsSync('assets'))fs.cpSync('assets','build/assets',{recursive:true})\" && node -e \"require('node:fs').cpSync('src/host/views','build/host/views',{recursive:true})\" && node -e \"const fs=require('node:fs');fs.mkdirSync('build/host/ui',{recursive:true});fs.readdirSync('src/host/ui').filter(f=>f.endsWith('.html')).forEach(f=>fs.copyFileSync('src/host/ui/'+f,'build/host/ui/'+f))\" && node -e \"require('node:fs').copyFileSync('commands/commands.json','build/commands/commands.json')\" && node -e \"const fs=require('node:fs');fs.mkdirSync('build/src/password',{recursive:true});fs.copyFileSync('src/password/common_passwords.txt','build/src/password/common_passwords.txt')\"",

package/skills/authkit-idp-setup/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: authkit-idp-setup
+description: >-
+  Set up the @adonis-agora/authkit-server OIDC/OAuth2 Authorization Server (Identity
+  Provider) in an AdonisJS app. Covers `node ace add @adonis-agora/authkit-server`,
+  defineConfig({ issuer, adapter, jwks, ttl, globalRolesClaim, accountStore }) with
+  adapters.redis({ connection }) vs adapters.database({ connection? }),
+  lucidAccountStore(AuthUser), JWKS management ({ source: 'managed' | 'jwks' } or
+  'auto', keystore store file/drive/lucid/redis/hashicorp vaults plus
+  @adonis-agora/authkit-vault-aws/azure/gcp createKeystoreVault add-ons),
+  registerOidcRoutes(router, { mountPath?, metrics?, dashboard? }), mounting consoles
+  via registerAuthHost(router, { admin, adminApi, account... }) or config.routes,
+  and AUTHKIT_ISSUER / observability env. Use when booting an IdP app, wiring
+  config/authkit.ts, choosing a persistence adapter, managing signing keys, or
+  debugging 404s on /oidc, /account/*, /admin.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/authkit-server"
+  library_version: "0.60.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-authkit:README.md"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/README.md"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/src/define_config.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/src/register_routes.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/stubs/config/authkit.stub"
+---
+
+# Setting up the AuthKit Authorization Server
+
+`@adonis-agora/authkit-server` turns an AdonisJS app into an OpenID Connect /
+OAuth2 Authorization Server (IdP) on top of `oidc-provider`. Setup has three
+independent pieces that all must exist before anything works: **config**
+(`config/authkit.ts` via `defineConfig`), **OIDC routes** (`registerOidcRoutes`),
+and the host routes/consoles (`registerAuthHost` or `config.routes`). The login
+screens are a separate concern — see `authkit-interactions`.
+
+## Setup
+
+Install and run the configurator:
+
+```bash
+node ace add @adonis-agora/authkit-server
+```
+
+`configure` publishes `config/authkit.ts`, the model `app/models/auth_user.ts`, the
+interaction controller stub and registers the provider. Then wire the routes:
+
+```ts
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { registerOidcRoutes } from '@adonis-agora/authkit-server'
+
+registerOidcRoutes(router) // mounts the oidc-provider catch-all at /oidc
+```
+
+Point `AUTHKIT_ISSUER` at `<host>/oidc` — the issuer must end with the mount path.
+
+Source: `packages/authkit-server/README.md`, `src/register_routes.ts`.
+
+## Core patterns
+
+### Pattern 1 — `defineConfig`: issuer, adapter, accountStore
+
+```ts
+// config/authkit.ts
+import env from '#start/env'
+import AuthUser from '#models/auth_user'
+import { defineConfig, adapters, lucidAccountStore } from '@adonis-agora/authkit-server'
+
+const authServerConfig = defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  adapter: adapters.redis({ connection: 'main' }), // or adapters.database()
+  jwks: { source: 'managed', algorithm: 'RS256' },
+  ttl: { accessToken: '15m', refreshToken: '30d' },
+  globalRolesClaim: 'roles',
+  accountStore: lucidAccountStore(AuthUser),
+})
+
+export default authServerConfig
+```
+
+`adapter` is where oidc-provider persists grants/tokens/codes: `adapters.redis({
+connection })` requires `@adonisjs/redis` configured; `adapters.database({
+connection? })` uses Lucid and requires running the `authkit_oidc_payloads`
+migration. `accountStore` is the identity contract — `lucidAccountStore(AuthUser)`
+derives `findAccount`/`verifyCredentials` from your user model.
+
+Source: `stubs/config/authkit.stub`, `src/define_config.ts` (`AuthServerConfigInput`),
+`src/adapters/factory.ts`, README § Persistência.
+
+### Pattern 2 — signing keys: managed JWKS, `'auto'`, and inline keys
+
+```ts
+defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  adapter: adapters.redis({ connection: 'main' }),
+  // Ephemeral-friendly: AUTHKIT_JWKS inline JSON wins, else file-managed keystore.
+  jwks: 'auto',
+  accountStore: lucidAccountStore(AuthUser),
+})
+```
+
+Explicit forms: `{ source: 'managed' }` generates/rotates/persists the private
+keystore (`rotationDays`, `algorithm`, `encrypt`, and `store` choosing where the
+blob lives); `{ source: 'jwks', keys }` supplies keys inline.
+
+The managed keystore's `store` accepts a path shortcut (`store: 'tmp/keystore.json'`)
+or `{ driver: ... }`: built-in vaults are `file`, `drive` (a `@adonisjs/drive` disk),
+`lucid` (table created on first write), `redis`, and `hashicorp`; for cloud secret
+managers install the add-ons `@adonis-agora/authkit-vault-aws` / `-azure` / `-gcp`
+and pass their `createKeystoreVault(...)` result as `store` (any object with a
+`read()` method is accepted). With no `store` at all, keys are ephemeral per boot.
+
+Rotation tooling ships as `node ace authkit:rotate-keys`; health checks via
+`node ace authkit:doctor`.
+
+Source: `src/keys/keystore_manager.ts` (`resolveKeystoreVault`),
+`packages/authkit-core/src/types/server_config.ts` (`JwksConfig`), index.ts exports.
+
+### Pattern 3 — mounting consoles with `registerAuthHost` (or `config.routes`)
+
+```ts
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { registerOidcRoutes, registerAuthHost } from '@adonis-agora/authkit-server'
+
+registerOidcRoutes(router)
+const authkitRoutes = registerAuthHost(router, {
+  mountPath: '/oidc',
+  admin: true,    // admin console under /admin
+  adminApi: true, // Admin REST API under /api/authkit/v1
+})
+// Hand authkitRoutes to your frontend instead of hardcoding hrefs.
+router.get('/', async ({ inertia }) => inertia.render('home', { authkitRoutes }))
+```
+
+Alternatively set `routes: true` in `config/authkit.ts` to auto-mount in the
+provider's `boot()` (before `start/routes.ts`) — then do NOT also call
+`registerAuthHost` manually (double registration crashes the boot). Policy flags
+(`admin`, `adminApi`, `social`, `rateLimit`) declared in `defineConfig` LOCK the
+on/off switch: `registerAuthHost` may only adjust structural prefixes.
+
+Observability routes are opt-in on the OIDC mount itself:
+`registerOidcRoutes(router, { metrics: true, dashboard: true })` mounts
+`GET /authkit/metrics` (JSON snapshot) and `GET /authkit/dashboard` (embedded HTML).
+
+Source: `src/host/register_auth_host.ts` (`AuthHostOptions`, policy-vs-structural),
+`src/define_config.ts` (`routes`, `admin`, `adminApi` JSDoc), server README
+§ Observabilidade.
+
+## Common mistakes
+
+### CRITICAL — Issuer not ending with the mount path
+
+```ts
+// Wrong — issuer says /oauth but routes mount at default /oidc
+defineConfig({ issuer: 'https://idp.example.com/oauth' })
+registerOidcRoutes(router) // mounts /oidc/*
+```
+
+```ts
+// Correct — issuer ends exactly at the mount path
+defineConfig({ issuer: 'https://idp.example.com/oidc' })
+registerOidcRoutes(router) // default mountPath '/oidc' matches the issuer
+```
+
+oidc-provider routes internally UNDER the issuer URL, so a trailing mismatch makes
+discovery and every protocol endpoint unreachable while the app otherwise boots fine.
+
+Source: `packages/authkit-server/README.md` § Montar as rotas OIDC;
+`src/host/register_auth_host.ts` (`mountPath` doc: "Deve casar com o final do issuer").
+
+### HIGH — Consoles/account screens 404 because no host routes were mounted
+
+```ts
+// Wrong — only the protocol endpoints exist; /account/* and /admin are dead
+registerOidcRoutes(router)
+```
+
+```ts
+// Correct — mount the host surface too (or set config.routes: true)
+registerOidcRoutes(router)
+registerAuthHost(router, { mountPath: '/oidc', admin: true })
+```
+
+`registerOidcRoutes` only registers the oidc-provider catch-all; everything else
+(account console `/account/*`, admin console, Admin API, sudo routes) exists solely
+after `registerAuthHost` runs or `config.routes` auto-mounts them. Conversely,
+calling `registerAuthHost` while `config.routes: true` double-registers named routes
+and throws at boot — pick one.
+
+Source: `src/define_config.ts` (`routes` JSDoc: "duplo registro ... derrubam o boot"),
+`src/register_routes.ts`.
+
+### HIGH — `jwks: 'auto'` in production without AUTHKIT_JWKS
+
+```ts
+// Wrong — prod deploy with no AUTHKIT_JWKS env: falls back to a file keystore in tmp/
+jwks: 'auto'
+```
+
+```ts
+// Correct — explicit managed keystore persisted in a durable vault for prod
+jwks: {
+  source: 'managed',
+  algorithm: 'RS256',
+  store: { driver: 'lucid' }, // or redis/drive/hashicorp/vault add-on
+}
+```
+
+`'auto'` prefers the `AUTHKIT_JWKS` env JSON but silently degrades to
+`tmp/authkit_jwks.json` on disk — on ephemeral filesystems every restart mints new
+signing keys and every issued token fails validation after redeploy.
+
+Source: `src/define_config.ts` (`jwks` JSDoc: "'auto' (recomendado p/ deploys
+efêmeros)... senão cai no managed persistido em arquivo"),
+`packages/authkit-core/src/types/server_config.ts`.
+
+See also: `authkit-interactions/SKILL.md` — after setup, the authorization flow ends
+at the interaction screens, which the host must register and render itself.

package/skills/authkit-interactions/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: authkit-interactions
+description: >-
+  Implement the host-owned login/consent interaction screens of @adonis-agora/authkit-server.
+  Covers oidc-provider's interactions.url redirect to /auth/interaction/:uid, the three
+  routes every IdP app must register (show/login/consent on AuthInteractionController),
+  `node ace configure --ui=edge|react|headless` presets, the shell-controller +
+  service.interactions split (details(ctx), login(ctx,{email,password}), consent(ctx)),
+  overriding verifyCredentials in config/authkit.ts, renderers edgeRenderer/inertiaRenderer,
+  and end-to-end testing with @adonis-agora/authkit-testing (createTestIdentity,
+  mintTestIdToken, serveJwks, fakeAuthenticator). Use when the authorization flow 404s at
+  the login screen, wiring custom login UI, plugging an external user base, or testing
+  OIDC flows without booting an IdP.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/authkit-server"
+  library_version: "0.60.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/README.md"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/src/host/renderers/inertia_renderer.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-server/src/define_config.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-testing/README.md"
+---
+
+# Login & consent screens (interactions)
+
+When `oidc-provider` meets an unauthenticated user it redirects to
+`interactions.url` (`/auth/interaction/:uid`). Those screens are **yours** — the kit
+ejects a controller shell via `node ace configure` and you register the routes that
+point at it. Without them the authorization code flow dies with a 404 exactly when
+the user should log in.
+
+## Setup
+
+Pick a UI preset when configuring (asks interactively if omitted):
+
+```bash
+node ace configure @adonis-agora/authkit-server --ui=edge
+# values: edge | react | headless
+```
+
+Each preset publishes `app/controllers/auth_interaction_controller.ts`; `edge` adds
+Edge views, `react` adds Inertia pages (validating that `@adonisjs/inertia` + Vite +
+React exist first), `headless` returns JSON only. Register the three routes:
+
+```ts
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import AuthInteractionController from '#controllers/auth_interaction_controller'
+
+router.get('/auth/interaction/:uid', [AuthInteractionController, 'show'])
+router.post('/auth/interaction/:uid/login', [AuthInteractionController, 'login'])
+router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'consent'])
+```
+
+Source: `packages/authkit-server/README.md` § Rotas de interaction.
+
+## Core patterns
+
+### Pattern 1 — edit the shell, keep logic in `service.interactions`
+
+In all presets the ejected controller is a thin shell: the logic lives in
+`service.interactions`, resolved via `containerResolver.make('authkit.server')`.
+It exposes `details(ctx)` (the prompt + params), `login(ctx, { email, password })`
+and `consent(ctx)`. You only edit the render/redirect parts:
+
+```ts
+// headless preset flavor — show() returns JSON, you build your own front
+async show({ request, response }) {
+  const service = await this.ctx.containerResolver.make('authkit.server')
+  const details = await service.interactions.details(this.ctx)
+  return response.json({ uid: request.param('uid'), prompt: details.prompt, params: details.params })
+}
+```
+
+Keep validation, MFA prompts and grant bookkeeping inside `service.interactions`;
+the shell only translates between HTTP and those calls.
+
+Source: `packages/authkit-server/README.md` § UI de login/consent ("o controller
+ejetado é casca: a lógica vive em `service.interactions`").
+
+### Pattern 2 — plug your user base via `verifyCredentials`
+
+`verifyCredentials` in `config/authkit.ts` decides whether credentials are valid;
+`service.interactions.login` calls it. The default queries the `AuthUser` model by
+email and uses `verifyPassword` — override to authenticate against anything else:
+
+```ts
+// config/authkit.ts
+defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  adapter: adapters.redis({ connection: 'main' }),
+  accountStore: lucidAccountStore(AuthUser),
+  verifyCredentials: async (email, password) => {
+    // Return the account on success; throw/falsy paths fail the login.
+    const account = await AuthUser.query().where('email', email).first()
+    if (!account) throw new Error('Invalid credentials')
+    await verifyPassword(account.passwordHash, password)
+    return account
+  },
+})
+```
+
+Whatever it returns must be the same identity surface the configured
+`accountStore` serves, or downstream `findAccount` lookups diverge from what just
+logged in.
+
+Source: `packages/authkit-server/README.md` § UI de login/consent (verifyCredentials),
+`src/define_config.ts` (`accountStore` derives findAccount/verifyCredentials).
+
+### Pattern 3 — custom rendering with `inertiaRenderer`
+
+Hosts building their own React screens set the `render` option instead of relying
+on the default Edge renderer:
+
+```ts
+import { defineConfig, inertiaRenderer } from '@adonis-agora/authkit-server'
+
+defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  adapter: adapters.database(),
+  accountStore: lucidAccountStore(AuthUser),
+  render: inertiaRenderer(), // renders Inertia pages for /account/* and /auth/interaction/*
+})
+```
+
+Without any renderer, every `/account/*` and `/auth/interaction/*` request fails
+with an unexplained 500 (`render` is undefined).
+
+Source: `src/define_config.ts` (`render` JSDoc), `index.ts` exports
+(`inertiaRenderer`, `edgeRenderer`).
+
+### Pattern 4 — test flows without booting an IdP
+
+`@adonis-agora/authkit-testing` mints real signed ID tokens validated by a local
+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'
+
+const { token, jwks } = await mintTestIdToken({
+  issuer: 'https://idp.test',
+  clientId: 'my-app',
+  claims: { sub: 'user-42', email: 'jane@test.dev', roles: ['ADMIN'] },
+})
+
+const served = await serveJwks(jwks)
+const factory = resolvers.jwt({ jwksUri: served.jwksUri })
+const resolver = await factory.resolver({
+  issuer: 'https://idp.test',
+  clientId: 'my-app',
+  sessionKey: 'authkit',
+  globalRolesClaim: 'roles',
+})
+const ctx = { auth: fakeAuthenticator({ identity: null }) } // anonymous request fake
+await served.close()
+```
+
+Also available: `createTestIdentity(overrides?)` for valid `Identity` defaults,
+`fakeAccountStore({ withMfa: true, ... })` for capability-probed store fakes.
+
+Source: `packages/authkit-testing/README.md`.
+
+## Common mistakes
+
+### CRITICAL — Forgetting to register the interaction routes
+
+```ts
+// Wrong — only the protocol endpoints exist
+registerOidcRoutes(router)
+// no GET /auth/interaction/:uid anywhere
+```
+
+```ts
+// Correct — the three host-owned routes are registered next to the OIDC mount
+registerOidcRoutes(router)
+router.get('/auth/interaction/:uid', [AuthInteractionController, 'show'])
+router.post('/auth/interaction/:uid/login', [AuthInteractionController, 'login'])
+router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'consent'])
+```
+
+Nothing crashes at boot; the failure surfaces mid-flow — the user's browser lands
+on `/auth/interaction/:uid` and gets a 404, so no client can ever complete login.
+
+Source: `packages/authkit-server/README.md` § Rotas de interaction ("Sem essas rotas
+o fluxo de autorização cai num 404 ao chegar na tela de login").
+
+### HIGH — Writing login/consent logic inside the ejected controller shell
+
+```ts
+// Wrong — reimplementing prompt handling/grants in the ejected shell
+async consent(ctx) {
+  // hand-rolling grant persistence against oidc-provider internals...
+}
+```
+
+```ts
+// Correct — shell delegates; the service owns the flow
+async consent(ctx) {
+  const service = await ctx.containerResolver.make('authkit.server')
+  await service.interactions.consent(ctx) // handles the grant, returns the redirect
+}
+```
+
+The shell is regenerated by `configure` and has no access to the provider's
+interaction plumbing; duplicating logic there silently drifts from prompt/consent
+semantics the provider expects.
+
+Source: `packages/authkit-server/README.md` § UI de login/consent ("Você edita só a
+parte de render/redirect").
+
+### MEDIUM — Choosing `--ui=react` without the Inertia stack installed
+
+```bash
+# Wrong — react preset in a bare API-only AdonisJS app
+node ace configure @adonis-agora/authkit-server --ui=react
+```
+
+```bash
+# Correct — match the preset to the app stack
+node ace configure @adonis-agora/authkit-server --ui=edge   # server-rendered views
+node ace configure @adonis-agora/authkit-server --ui=headless # build your own front
+```
+
+The `react` preset requires `@adonisjs/inertia` + Vite + React in the host app —
+`configure` validates the stack before publishing, so the command aborts instead of
+half-configuring your app.
+
+Source: `packages/authkit-server/README.md` § UI de login/consent ("Exige
+@adonisjs/inertia + Vite + React no app — o configure valida essa stack").
+
+See also: `authkit-rp-client/SKILL.md` — the consuming side that ends up holding
+the session these screens create.