@adonis-agora/authkit-server 0.53.0 → 0.55.0

package/build/src/host/oidc_rp_guard.js

@@ -0,0 +1,200 @@
+import { RuntimeException } from '@adonisjs/core/exceptions';
+import { ACCOUNT_SESSION_KEY } from './middleware/account_auth.js';
+/** Memo do construtor entre instâncias — o `import()` só paga o custo uma vez. */
+let cachedUnauthorizedAccess;
+/**
+ * Captura o `E_UNAUTHORIZED_ACCESS` real do `@adonisjs/auth` sem import
+ * estático. Chamado no boot pelo {@link oidcRpGuard} (falha cedo e com uma
+ * mensagem útil se o peer não estiver instalado) e, como rede de segurança, na
+ * primeira `authenticate()` de um guard construído à mão.
+ */
+export async function loadUnauthorizedAccess() {
+    if (cachedUnauthorizedAccess)
+        return cachedUnauthorizedAccess;
+    try {
+        const auth = (await import('@adonisjs/auth'));
+        cachedUnauthorizedAccess = auth.errors.E_UNAUTHORIZED_ACCESS;
+        return cachedUnauthorizedAccess;
+    }
+    catch (error) {
+        throw new RuntimeException('oidcRpGuard() precisa de "@adonisjs/auth" instalado (é um peer opcional do ' +
+            '@adonis-agora/authkit-server, só necessário se você plugar este guard em config/auth.ts). ' +
+            'Rode `npm i @adonisjs/auth` (ou pnpm/yarn).', { cause: error });
+    }
+}
+/**
+ * Guard de `@adonisjs/auth` pra Relying Parties OIDC — o app não autentica
+ * ninguém (sem senha, sem remember-me); a identidade vem da sessão gravada
+ * pelo callback OIDC (`account_user_id`). O guard só LÊ essa chave e resolve
+ * o user via provider.
+ *
+ * ```ts
+ * // config/auth.ts
+ * import { oidcRpGuard } from '@adonis-agora/authkit-server'
+ * import { sessionUserProvider } from '@adonisjs/auth/session'
+ *
+ * const authConfig = defineConfig({
+ *   default: 'web',
+ *   guards: {
+ *     web: oidcRpGuard({
+ *       provider: sessionUserProvider({ model: () => import('#models/user') }),
+ *     }),
+ *   },
+ * })
+ * ```
+ *
+ * O callback OIDC do RP chama `ctx.auth.use('web').login(user)` pra gravar a
+ * sessão; a partir daí `ctx.auth.user`, `auth.check()`, `middleware.auth()` —
+ * tudo funciona nativamente.
+ */
+export class OidcRpGuard {
+    #name;
+    #ctx;
+    #sessionKey;
+    #emitter;
+    #userProvider;
+    #unauthorized;
+    driverName = 'oidc_rp';
+    authenticationAttempted = false;
+    isAuthenticated = false;
+    isLoggedOut = false;
+    user;
+    constructor(name, ctx, sessionKey, emitter, userProvider, unauthorized) {
+        this.#name = name;
+        this.#ctx = ctx;
+        this.#sessionKey = sessionKey;
+        this.#emitter = emitter;
+        this.#userProvider = userProvider;
+        this.#unauthorized = unauthorized ?? cachedUnauthorizedAccess;
+    }
+    /**
+     * O `E_UNAUTHORIZED_ACCESS` do framework — `status` 401 e os renderers
+     * html/json, então o handler de exceção do host trata igual ao dos guards
+     * nativos. Se o construtor ainda não foi resolvido (guard instanciado à mão,
+     * antes de qualquer `authenticate()`), cai num `RuntimeException` em vez de
+     * mentir sobre o tipo.
+     */
+    #unauthorizedError(message) {
+        const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccess;
+        if (!Unauthorized)
+            return new RuntimeException(message);
+        return new Unauthorized(message, { guardDriverName: this.driverName });
+    }
+    getUserOrFail() {
+        if (!this.user) {
+            throw this.#unauthorizedError('Cannot access user. Authentication has not been attempted or failed.');
+        }
+        return this.user;
+    }
+    /**
+     * Grava a identidade na sessão. Chamado pelo callback OIDC após validar o
+     * grant — o guard NÃO verifica credenciais, só persiste o id do user.
+     */
+    async login(user) {
+        const guardUser = await this.#userProvider.createUserForGuard(user);
+        this.#ctx.session.put(this.#sessionKey, String(guardUser.getId()));
+        this.user = user;
+        this.isAuthenticated = true;
+        this.authenticationAttempted = true;
+        this.#emitter.emit('oidc_rp:login_succeeded', {
+            ctx: this.#ctx,
+            guardName: this.#name,
+            user,
+        });
+    }
+    /**
+     * Limpa a identidade da sessão. O RP-initiated logout (redirect pro
+     * `end_session` do issuer) é responsabilidade do controller — o guard só
+     * cuida da sessão local.
+     */
+    async logout() {
+        const user = this.user ?? null;
+        this.#ctx.session.forget(this.#sessionKey);
+        this.user = undefined;
+        this.isAuthenticated = false;
+        this.isLoggedOut = true;
+        this.#emitter.emit('oidc_rp:logged_out', {
+            ctx: this.#ctx,
+            guardName: this.#name,
+            user,
+        });
+    }
+    async authenticate() {
+        if (this.authenticationAttempted) {
+            return this.getUserOrFail();
+        }
+        this.authenticationAttempted = true;
+        this.#unauthorized ??= await loadUnauthorizedAccess();
+        const userId = this.#ctx.session.get(this.#sessionKey);
+        if (!userId) {
+            this.#emitter.emit('oidc_rp:authentication_failed', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+            });
+            throw this.#unauthorizedError('Unauthorized');
+        }
+        const guardUser = await this.#userProvider.findById(userId);
+        if (!guardUser) {
+            this.#ctx.session.forget(this.#sessionKey);
+            this.#emitter.emit('oidc_rp:authentication_failed', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+            });
+            throw this.#unauthorizedError('Unauthorized');
+        }
+        this.user = guardUser.getOriginal();
+        this.isAuthenticated = true;
+        this.#emitter.emit('oidc_rp:authentication_succeeded', {
+            ctx: this.#ctx,
+            guardName: this.#name,
+            user: this.user,
+        });
+        return this.user;
+    }
+    /**
+     * `authenticate()` sem lançar — mas SÓ para falha de autenticação. Igual ao
+     * `SessionGuard` nativo: engole apenas `E_UNAUTHORIZED_ACCESS` e relança o
+     * resto. Um `catch` cego aqui transformava uma queda do banco dentro de
+     * `provider.findById` em "não logado" para todo mundo, sem nada nos logs.
+     */
+    async check() {
+        try {
+            await this.authenticate();
+            return true;
+        }
+        catch (error) {
+            const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccess;
+            if (Unauthorized && error instanceof Unauthorized)
+                return false;
+            throw error;
+        }
+    }
+    async authenticateAsClient(user) {
+        const guardUser = await this.#userProvider.createUserForGuard(user);
+        return { session: { [this.#sessionKey]: String(guardUser.getId()) } };
+    }
+}
+/**
+ * Factory de config pro `oidcRpGuard` — mesmo padrão do `sessionGuard()` de
+ * `@adonisjs/auth/session`. Retorna um `GuardConfigProvider` que o
+ * `defineConfig` de `config/auth.ts` resolve no boot.
+ */
+export function oidcRpGuard(config) {
+    return {
+        async resolver(name, app) {
+            const emitter = await app.container.make('emitter');
+            const sessionKey = config.sessionKey ?? ACCOUNT_SESSION_KEY;
+            const unauthorized = await loadUnauthorizedAccess();
+            let userProvider;
+            if (typeof config.provider.resolver === 'function') {
+                userProvider = await config.provider.resolver(app);
+            }
+            else {
+                userProvider = config.provider;
+            }
+            return (ctx) => {
+                return new OidcRpGuard(name, ctx, sessionKey, emitter, userProvider, unauthorized);
+            };
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+/**
+ * The canonical public origin for links we EMAIL (password reset, magic link,
+ * OTP unlock, org invitations, email verification/change, security notices).
+ *
+ * Never derive these from `request.host()` / `request.protocol()` (which reads
+ * `X-Forwarded-Proto` under a trusting proxy config): both are client-supplied.
+ * An attacker who can reach the server directly (common when the app sits
+ * behind a load balancer that does not pin `Host`) can submit a password-reset
+ * or magic-link request for a victim's address with a `Host` of their choosing,
+ * and the victim's genuine email ends up pointing at attacker-controlled
+ * infrastructure. This is classic password-reset poisoning.
+ *
+ * Defaults to the origin (`scheme://host[:port]`, no trailing slash, mount
+ * path stripped) of the resolved `issuer` — the one canonical origin this
+ * library already has. Hosts that legitimately serve the same issuer under
+ * multiple public hostnames (and therefore want emailed links to follow the
+ * request instead of normalizing to a single hostname) can opt out via the
+ * `mail.origin` config escape hatch.
+ */
+export declare function authkitOrigin(cfg: ResolvedServerConfig): string;

package/build/src/host/origin.js

@@ -0,0 +1,22 @@
+/**
+ * The canonical public origin for links we EMAIL (password reset, magic link,
+ * OTP unlock, org invitations, email verification/change, security notices).
+ *
+ * Never derive these from `request.host()` / `request.protocol()` (which reads
+ * `X-Forwarded-Proto` under a trusting proxy config): both are client-supplied.
+ * An attacker who can reach the server directly (common when the app sits
+ * behind a load balancer that does not pin `Host`) can submit a password-reset
+ * or magic-link request for a victim's address with a `Host` of their choosing,
+ * and the victim's genuine email ends up pointing at attacker-controlled
+ * infrastructure. This is classic password-reset poisoning.
+ *
+ * Defaults to the origin (`scheme://host[:port]`, no trailing slash, mount
+ * path stripped) of the resolved `issuer` — the one canonical origin this
+ * library already has. Hosts that legitimately serve the same issuer under
+ * multiple public hostnames (and therefore want emailed links to follow the
+ * request instead of normalizing to a single hostname) can opt out via the
+ * `mail.origin` config escape hatch.
+ */
+export function authkitOrigin(cfg) {
+    return cfg.mail?.origin ?? new URL(cfg.issuer).origin;
+}

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

@@ -1,6 +1,7 @@
 import type { Router } from '@adonisjs/core/http';
 import type { AuthSocialConfig, RateLimitConfigInput } from '../define_config.js';
-import { type AccountPathsOptions } from './account_paths.js';
+import { type AccountPathKey, type AccountPathsOptions } from './account_paths.js';
+import type { PolicyRouteOption } from './config_locks.js';
 import type { SudoMethod } from './sudo/types.js';
 /** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
 export declare const ACCOUNT_LAST_SEEN_KEY = "authkit_last_seen";
@@ -108,7 +109,14 @@ export interface AuthHostOptions {
      * fechada, mas é a promessa do SPI pela metade; `magicLink()` em particular
      * não teria como ser alcançado em runtime.
      *
-     * Ausente → `[password(), passkey()]`.
+     * Ausente → `[password(), passkey(), magicLink()]`, e o config resolvido
+     * decide quais deles a tela OFERECE: host com senha recebe
+     * `[password, passkey]` (o histórico, byte a byte) e host que declarou
+     * `authMethods: { password: false }` recebe `[passkey, magicLink]` — sem isso
+     * ele não teria um único método satisfazível. Ver `derivedSudoMethods` em
+     * `sudo/runtime.ts`.
+     *
+     * Passar a opção desliga essa derivação: a lista é do host, ao pé da letra.
      */
     sudoMethods?: SudoMethod[];
     /**
@@ -203,8 +211,101 @@ export interface AccountScreensOptions {
     /** Apps com acesso / grants de consentimento OIDC (`/account/apps*`). */
     apps?: boolean;
 }
+/**
+ * Mapa RESOLVIDO das rotas montadas, devolvido por `registerAuthHost`.
+ *
+ * Existe porque os overrides de path (`accountRoutes`) chegavam ao servidor
+ * (via `accountPath()`) mas NÃO ao frontend: o layout React e os formulários do
+ * host tinham de repetir os mesmos paths à mão, e um override era meio-recurso —
+ * certo no servidor, errado na UI. Entregue este mapa ao frontend (uma shared
+ * prop do Inertia, um `<script type="application/json">`, um endpoint) em vez de
+ * hardcodar `href`s.
+ *
+ * @example
+ * const authkitRoutes = registerAuthHost(router)
+ * router.get('/', ({ inertia }) => inertia.render('home', { authkitRoutes }))
+ */
+export interface AuthHostRouteMap {
+    /** Onde o provider OIDC foi montado (o wildcard é `${mountPath}/*`). */
+    mountPath: string;
+    /** Console de conta: prefixo, base da JSON API e o path de CADA tela. */
+    account: {
+        /** Prefixo base resolvido (default `/account`). */
+        prefix: string;
+        /** Base da JSON API do console de conta (default `/account/api`). */
+        api: string;
+        /** Path completo de cada tela navegável (`security` → `/account/security`). */
+        paths: Record<AccountPathKey, string>;
+        /** Destino do redirect de "faça login" em vigor. */
+        loginUrl: string;
+        /** Quais telas foram efetivamente montadas. */
+        screens: Record<keyof AccountScreensOptions, boolean>;
+    };
+    /** Console admin: prefixo resolvido, ou `null` quando não foi montado. */
+    admin: {
+        prefix: string;
+    } | null;
+    /** Admin REST API: prefixo resolvido, ou `null` quando não foi montada. */
+    adminApi: {
+        prefix: string;
+    } | null;
+    /** Nomes das rotas nomeadas (as demais herdam o auto-naming do AdonisJS). */
+    names: Record<string, string>;
+    /** Ids dos métodos de sudo cujas rotas foram montadas, na ordem de montagem. */
+    sudoMethods: string[];
+    /**
+     * Opções de POLÍTICA passadas como argumento que foram IGNORADAS porque o
+     * `defineConfig` as declarou (config vence). Vazio no caso normal. Cada uma
+     * também sai como `console.warn` no boot — ver a regra de precedência abaixo.
+     */
+    overriddenByConfig: PolicyRouteOption[];
+}
 /**
  * Monta todas as rotas do host-kit do Authorization Server numa chamada.
  * Substitui registerOidcRoutes + o hand-wiring do start/routes.ts do host.
+ *
+ * ── A REGRA DE PRECEDÊNCIA (config × argumento) ─────────────────────────────
+ *
+ * 1. **Argumento omitido HERDA do config.** `registerAuthHost(router)` é
+ *    totalmente config-driven; `registerAuthHost(router, { mountPath: '/sso' })`
+ *    troca o mountPath e herda TODO o resto. Omitir uma chave significa "usa o
+ *    config", nunca "usa nada" — é o que dispensa repetir `sudo.methods` no
+ *    `start/routes.ts`.
+ *
+ * 2. **Chaves ESTRUTURAIS: o argumento vence.** `mountPath`, os prefixos
+ *    (`admin.prefix`, `adminApi.prefix`, `accountRoutes.prefix`), os segmentos
+ *    de tela, `account` (quais telas montar) e `accountLoginUrl`. São decisões
+ *    do ponto de chamada por natureza, e a forma de função é estritamente mais
+ *    expressiva (dá para montar duas vezes sob dois prefixos — nenhum config
+ *    expressa isso).
+ *
+ * 3. **Chaves de POLÍTICA: o config vence, e trava.** `social`, `rateLimit`,
+ *    `sudoMethods` e o liga/desliga de `admin`/`adminApi` decidem o que é
+ *    PERMITIDO. Quando o `defineConfig` as declara, o argumento NÃO as altera —
+ *    senão o `config/authkit.ts` deixa de ser auditável e seria preciso ler o
+ *    `start/routes.ts` de cada app para saber o que está valendo. Mesma regra
+ *    (e mesma derivação) de `defineConfig({ authMethods })`, que já fixa os
+ *    métodos de login contra o runtime. Ver `deriveLockedRouteOptions`.
+ *    A divergência NÃO é silenciosa: sai um `console.warn` nomeando a chave e
+ *    a chave aparece em `AuthHostRouteMap.overriddenByConfig`.
+ *
+ * Devolve o {@link AuthHostRouteMap} resolvido — entregue-o ao frontend em vez
+ * de hardcodar `href`s.
+ */
+export declare function registerAuthHost(router: Router, opts?: AuthHostOptions): AuthHostRouteMap;
+/**
+ * Auto-montagem a partir de `config.routes` (R1). Chamada UMA vez pelo
+ * `boot()` do provider.
+ *
+ * O CAMINHO AUTOMÁTICO É O CAMINHO MANUAL: chama literalmente
+ * `registerAuthHost`, sem nenhuma segunda implementação. Toda a resolução
+ * (herança do config, precedência política × estrutural, mapa de retorno) é a
+ * mesma — duas implementações de um comportamento sempre divergem.
+ *
+ * Não recebe opções: os defaults ESTRUTURAIS vêm de `config.routes` pelo stash
+ * (`AuthHostRuntimeConfig.routes`), pelo mesmo caminho que uma chamada manual
+ * os leria.
+ *
+ * @internal
  */
-export declare function registerAuthHost(router: Router, opts?: AuthHostOptions): void;
+export declare function autoMountAuthHost(router: Router): AuthHostRouteMap;