@adonis-agora/authkit-server 0.72.0 → 0.74.0

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

@@ -0,0 +1,113 @@
+import type { symbols } from '@adonisjs/auth';
+import type { AuthClientResponse, GuardConfigProvider, GuardContract } from '@adonisjs/auth/types';
+import type { SessionUserProviderContract } from '@adonisjs/auth/types/session';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ConfigProvider } from '@adonisjs/core/types';
+import type { EmitterLike } from '@adonisjs/core/types/events';
+import { type AccessTokenVerifier, type IssueAccessTokenOptions, type RemoteAccessTokenVerifierOptions, type VerifiedAccessToken } from './access_token_verifier.js';
+import { type UnauthorizedAccessConstructor } from './oidc_rp_guard.js';
+type RealUser<UserProvider> = UserProvider extends SessionUserProviderContract<infer U> ? U : never;
+/** Política de aceitação do token, além de "é válido e não expirou". */
+export interface OidcBearerGuardPolicy {
+    /** Escopos exigidos (TODOS). Token sem algum deles → 401 `insufficient_scope`. */
+    scopes?: string[];
+    /**
+     * Audience(s) aceitas (RFC 8707 resource indicators). Quando definido, o `aud`
+     * do token precisa conter pelo menos uma. Token opaco emitido SEM `resource`
+     * não tem `aud` e é recusado.
+     */
+    audience?: string | string[];
+    /** Allowlist de `client_id` cujos tokens são aceitos. Ausente = qualquer client. */
+    clientIds?: string[];
+}
+export type OidcBearerGuardOptions<UserProvider extends SessionUserProviderContract<unknown>> = OidcBearerGuardPolicy & {
+    /**
+     * User provider — o MESMO tipo do `oidcRpGuard` (`sessionUserProvider(...)`
+     * ou `authkitUserProvider()`): o `sub` do token vai para `findById`.
+     */
+    provider: UserProvider | ConfigProvider<UserProvider>;
+    /**
+     * Modo resource server REMOTO (a API não hospeda o issuer): JWT access tokens
+     * via JWKS do issuer (RFC 9068) e/ou tokens opacos via introspecção (RFC 7662).
+     * Ausente = modo IN-PROCESS: verifica contra o issuer embarcado
+     * (`authkit.server`), opaco e JWT.
+     */
+    remote?: RemoteAccessTokenVerifierOptions;
+    /** Verificador próprio (avançado). Tem precedência sobre `remote`. */
+    verifier?: AccessTokenVerifier;
+};
+export type OidcBearerGuardEvents<User> = {
+    'oidc_bearer:authentication_succeeded': {
+        ctx: HttpContext;
+        guardName: string;
+        user: User;
+        token: VerifiedAccessToken;
+    };
+    'oidc_bearer:authentication_failed': {
+        ctx: HttpContext;
+        guardName: string;
+        error: Error;
+    };
+};
+/**
+ * Guard de `@adonisjs/auth` para APIs chamadas com access token do issuer do
+ * authkit — o par do {@link OidcRpGuard} para clientes SEM sessão web: apps
+ * nativos (React Native/Expo, RFC 8252), SPAs que falam direto com a API,
+ * serviços. Lê `Authorization: Bearer <token>`, verifica o token (assinatura ou
+ * adapter, expiração, revogação), aplica a política (escopos, audience, clients)
+ * e resolve o user pelo `sub` no user provider.
+ *
+ * ```ts
+ * // config/auth.ts
+ * import { oidcBearerGuard, oidcRpGuard } from '@adonis-agora/authkit-server'
+ * import { sessionUserProvider } from '@adonisjs/auth/session'
+ *
+ * const provider = sessionUserProvider({ model: () => import('#models/user') })
+ *
+ * const authConfig = defineConfig({
+ *   default: 'web',
+ *   guards: {
+ *     web: oidcRpGuard({ provider }),
+ *     api: oidcBearerGuard({ provider, scopes: ['openid'] }),
+ *   },
+ * })
+ *
+ * // start/routes.ts — aceita sessão OU bearer:
+ * router.get('/me', ...).use(middleware.auth({ guards: ['web', 'api'] }))
+ * ```
+ *
+ * Falha SEMPRE vira `E_UNAUTHORIZED_ACCESS` (401, sem redirect), com o header
+ * `WWW-Authenticate: Bearer …` da RFC 6750 §3.
+ */
+export declare class OidcBearerGuard<UserProvider extends SessionUserProviderContract<unknown>> implements GuardContract<RealUser<UserProvider>> {
+    #private;
+    [symbols.GUARD_KNOWN_EVENTS]: OidcBearerGuardEvents<RealUser<UserProvider>>;
+    driverName: 'oidc_bearer';
+    authenticationAttempted: boolean;
+    isAuthenticated: boolean;
+    user?: RealUser<UserProvider>;
+    /** O access token verificado desta request (após `authenticate()` com sucesso). */
+    accessToken?: VerifiedAccessToken;
+    constructor(name: string, ctx: HttpContext, emitter: EmitterLike<OidcBearerGuardEvents<RealUser<UserProvider>>>, userProvider: UserProvider, verifier: AccessTokenVerifier, policy?: OidcBearerGuardPolicy, unauthorized?: UnauthorizedAccessConstructor);
+    getUserOrFail(): RealUser<UserProvider>;
+    /** `true` quando o token autenticado tem TODOS os escopos pedidos. */
+    hasScopes(...scopes: string[]): boolean;
+    authenticate(): Promise<RealUser<UserProvider>>;
+    /**
+     * `authenticate()` sem lançar — só para falha de AUTENTICAÇÃO (mesma regra do
+     * `OidcRpGuard#check`): erro de infraestrutura (banco, rede) é relançado.
+     */
+    check(): Promise<boolean>;
+    /**
+     * Para testes (`client.get('/api').loginAs(user)`): emite um access token REAL
+     * no issuer embarcado e devolve o header `Authorization`. Só no modo in-process
+     * — um resource server remoto não emite tokens.
+     */
+    authenticateAsClient(user: RealUser<UserProvider>, options?: IssueAccessTokenOptions): Promise<AuthClientResponse>;
+}
+/**
+ * Factory de config pro {@link OidcBearerGuard} — mesmo padrão do `oidcRpGuard()`
+ * e do `sessionGuard()` nativo.
+ */
+export declare function oidcBearerGuard<UserProvider extends SessionUserProviderContract<unknown>>(config: OidcBearerGuardOptions<UserProvider>): GuardConfigProvider<(ctx: HttpContext) => OidcBearerGuard<UserProvider>>;
+export {};

package/build/src/host/oidc_bearer_guard.js

@@ -0,0 +1,223 @@
+import { RuntimeException } from '@adonisjs/core/exceptions';
+import { inProcessAccessTokenVerifier, remoteAccessTokenVerifier, } from './access_token_verifier.js';
+import { clearBearerAccountId, setBearerAccountId } from './bearer_account.js';
+import { cachedUnauthorizedAccessConstructor, loadUnauthorizedAccess, } from './oidc_rp_guard.js';
+/**
+ * Driver do `E_UNAUTHORIZED_ACCESS` lançado pelo guard. `access_tokens` é o
+ * renderer do `@adonisjs/auth` para o guard NATIVO de access tokens: 401 com
+ * `{ errors: [{ message }] }` em JSON (ou texto/JSON:API) e NUNCA redirect — o que
+ * uma API consumida por app mobile espera.
+ */
+const ERROR_RENDERER = 'access_tokens';
+/** `Authorization: Bearer <token>` (RFC 6750 §2.1). Esquema case-insensitive. */
+const BEARER = /^Bearer\s+([A-Za-z0-9\-._~+/]+=*)\s*$/i;
+/**
+ * Guard de `@adonisjs/auth` para APIs chamadas com access token do issuer do
+ * authkit — o par do {@link OidcRpGuard} para clientes SEM sessão web: apps
+ * nativos (React Native/Expo, RFC 8252), SPAs que falam direto com a API,
+ * serviços. Lê `Authorization: Bearer <token>`, verifica o token (assinatura ou
+ * adapter, expiração, revogação), aplica a política (escopos, audience, clients)
+ * e resolve o user pelo `sub` no user provider.
+ *
+ * ```ts
+ * // config/auth.ts
+ * import { oidcBearerGuard, oidcRpGuard } from '@adonis-agora/authkit-server'
+ * import { sessionUserProvider } from '@adonisjs/auth/session'
+ *
+ * const provider = sessionUserProvider({ model: () => import('#models/user') })
+ *
+ * const authConfig = defineConfig({
+ *   default: 'web',
+ *   guards: {
+ *     web: oidcRpGuard({ provider }),
+ *     api: oidcBearerGuard({ provider, scopes: ['openid'] }),
+ *   },
+ * })
+ *
+ * // start/routes.ts — aceita sessão OU bearer:
+ * router.get('/me', ...).use(middleware.auth({ guards: ['web', 'api'] }))
+ * ```
+ *
+ * Falha SEMPRE vira `E_UNAUTHORIZED_ACCESS` (401, sem redirect), com o header
+ * `WWW-Authenticate: Bearer …` da RFC 6750 §3.
+ */
+export class OidcBearerGuard {
+    #name;
+    #ctx;
+    #emitter;
+    #userProvider;
+    #verifier;
+    #policy;
+    #unauthorized;
+    driverName = 'oidc_bearer';
+    authenticationAttempted = false;
+    isAuthenticated = false;
+    user;
+    /** O access token verificado desta request (após `authenticate()` com sucesso). */
+    accessToken;
+    constructor(name, ctx, emitter, userProvider, verifier, policy = {}, unauthorized) {
+        this.#name = name;
+        this.#ctx = ctx;
+        this.#emitter = emitter;
+        this.#userProvider = userProvider;
+        this.#verifier = verifier;
+        this.#policy = policy;
+        this.#unauthorized = unauthorized ?? cachedUnauthorizedAccessConstructor();
+    }
+    #unauthorizedError(message) {
+        const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccessConstructor();
+        if (!Unauthorized)
+            return new RuntimeException(message);
+        return new Unauthorized(message, { guardDriverName: ERROR_RENDERER });
+    }
+    /**
+     * Falha de autenticação: header `WWW-Authenticate` (RFC 6750 §3), evento, e o
+     * `E_UNAUTHORIZED_ACCESS`. Sem token → só o desafio `Bearer`; token recusado →
+     * `error="invalid_token"` / `"insufficient_scope"`.
+     */
+    #fail(bearerError) {
+        let challenge = 'Bearer';
+        if (bearerError)
+            challenge += ` error="${bearerError}"`;
+        if (bearerError === 'insufficient_scope' && this.#policy.scopes?.length) {
+            challenge += `, scope="${this.#policy.scopes.join(' ')}"`;
+        }
+        this.#ctx.response?.header?.('WWW-Authenticate', challenge);
+        clearBearerAccountId(this.#ctx);
+        const error = this.#unauthorizedError('Unauthorized access');
+        this.#emitter.emit('oidc_bearer:authentication_failed', {
+            ctx: this.#ctx,
+            guardName: this.#name,
+            error,
+        });
+        return error;
+    }
+    getUserOrFail() {
+        if (!this.user) {
+            throw this.#unauthorizedError('Cannot access user. Authentication has not been attempted or failed.');
+        }
+        return this.user;
+    }
+    /** `true` quando o token autenticado tem TODOS os escopos pedidos. */
+    hasScopes(...scopes) {
+        const granted = new Set(this.accessToken?.scopes ?? []);
+        return scopes.every((s) => granted.has(s));
+    }
+    #bearerToken() {
+        const header = this.#ctx.request.header('authorization');
+        if (!header)
+            return undefined;
+        return BEARER.exec(header)?.[1];
+    }
+    #policyError(token) {
+        const { clientIds, audience, scopes } = this.#policy;
+        if (clientIds && (!token.clientId || !clientIds.includes(token.clientId))) {
+            return 'invalid_token';
+        }
+        if (audience !== undefined) {
+            const accepted = Array.isArray(audience) ? audience : [audience];
+            if (!token.audience.some((a) => accepted.includes(a)))
+                return 'invalid_token';
+        }
+        if (scopes?.length) {
+            const granted = new Set(token.scopes);
+            if (!scopes.every((s) => granted.has(s)))
+                return 'insufficient_scope';
+        }
+        return null;
+    }
+    async authenticate() {
+        if (this.authenticationAttempted) {
+            return this.getUserOrFail();
+        }
+        this.authenticationAttempted = true;
+        this.#unauthorized ??= await loadUnauthorizedAccess('oidcBearerGuard');
+        const raw = this.#bearerToken();
+        if (!raw)
+            throw this.#fail();
+        const token = await this.#verifier.verify(raw);
+        if (!token)
+            throw this.#fail('invalid_token');
+        const policyError = this.#policyError(token);
+        if (policyError)
+            throw this.#fail(policyError);
+        const guardUser = await this.#userProvider.findById(token.sub);
+        if (!guardUser)
+            throw this.#fail('invalid_token');
+        this.user = guardUser.getOriginal();
+        this.accessToken = token;
+        this.isAuthenticated = true;
+        setBearerAccountId(this.#ctx, String(guardUser.getId()));
+        this.#emitter.emit('oidc_bearer:authentication_succeeded', {
+            ctx: this.#ctx,
+            guardName: this.#name,
+            user: this.user,
+            token,
+        });
+        return this.user;
+    }
+    /**
+     * `authenticate()` sem lançar — só para falha de AUTENTICAÇÃO (mesma regra do
+     * `OidcRpGuard#check`): erro de infraestrutura (banco, rede) é relançado.
+     */
+    async check() {
+        try {
+            await this.authenticate();
+            return true;
+        }
+        catch (error) {
+            const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccessConstructor();
+            if (Unauthorized && error instanceof Unauthorized)
+                return false;
+            throw error;
+        }
+    }
+    /**
+     * Para testes (`client.get('/api').loginAs(user)`): emite um access token REAL
+     * no issuer embarcado e devolve o header `Authorization`. Só no modo in-process
+     * — um resource server remoto não emite tokens.
+     */
+    async authenticateAsClient(user, options) {
+        if (!this.#verifier.issue) {
+            throw new RuntimeException('oidcBearerGuard: authenticateAsClient só funciona no modo in-process (o app hospeda o issuer).');
+        }
+        const guardUser = await this.#userProvider.createUserForGuard(user);
+        const token = await this.#verifier.issue(String(guardUser.getId()), {
+            ...options,
+            scopes: options?.scopes ?? this.#policy.scopes,
+        });
+        return { headers: { authorization: `Bearer ${token}` } };
+    }
+}
+/**
+ * Factory de config pro {@link OidcBearerGuard} — mesmo padrão do `oidcRpGuard()`
+ * e do `sessionGuard()` nativo.
+ */
+export function oidcBearerGuard(config) {
+    return {
+        async resolver(name, app) {
+            const emitter = await app.container.make('emitter');
+            const unauthorized = await loadUnauthorizedAccess('oidcBearerGuard');
+            let userProvider;
+            if (typeof config.provider.resolver === 'function') {
+                userProvider = await config.provider.resolver(app);
+            }
+            else {
+                userProvider = config.provider;
+            }
+            // In-process: o `authkit.server` é resolvido na PRIMEIRA verificação (não
+            // aqui) — a config do auth pode ser resolvida antes do provider do authkit
+            // terminar o boot.
+            const verifier = config.verifier ??
+                (config.remote
+                    ? remoteAccessTokenVerifier(config.remote)
+                    : inProcessAccessTokenVerifier(async () => (await app.container.make('authkit.server'))));
+            const policy = {
+                scopes: config.scopes,
+                audience: config.audience,
+                clientIds: config.clientIds,
+            };
+            return (ctx) => new OidcBearerGuard(name, ctx, emitter, userProvider, verifier, policy, unauthorized);
+        },
+    };
+}

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

@@ -15,13 +15,15 @@ export type UnauthorizedAccessConstructor = new (message: string, options: {
     guardDriverName: string;
     redirectTo?: string;
 }) => Error;
+/** O construtor já resolvido por {@link loadUnauthorizedAccess}, se houver. */
+export declare function cachedUnauthorizedAccessConstructor(): UnauthorizedAccessConstructor | undefined;
 /**
  * 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 declare function loadUnauthorizedAccess(): Promise<UnauthorizedAccessConstructor>;
+export declare function loadUnauthorizedAccess(guardFactoryName?: string): Promise<UnauthorizedAccessConstructor>;
 export type OidcRpGuardOptions<UserProvider extends SessionUserProviderContract<unknown>> = {
     provider: UserProvider | ConfigProvider<UserProvider>;
     sessionKey?: string;

package/build/src/host/oidc_rp_guard.js

@@ -2,13 +2,17 @@ import { RuntimeException } from '@adonisjs/core/exceptions';
 import { ACCOUNT_SESSION_KEY } from './account_session_key.js';
 /** Memo do construtor entre instâncias — o `import()` só paga o custo uma vez. */
 let cachedUnauthorizedAccess;
+/** O construtor já resolvido por {@link loadUnauthorizedAccess}, se houver. */
+export function cachedUnauthorizedAccessConstructor() {
+    return 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() {
+export async function loadUnauthorizedAccess(guardFactoryName = 'oidcRpGuard') {
     if (cachedUnauthorizedAccess)
         return cachedUnauthorizedAccess;
     try {
@@ -17,7 +21,7 @@ export async function loadUnauthorizedAccess() {
         return cachedUnauthorizedAccess;
     }
     catch (error) {
-        throw new RuntimeException('oidcRpGuard() precisa de "@adonisjs/auth" instalado (é um peer opcional do ' +
+        throw new RuntimeException(`${guardFactoryName}() 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 });
     }

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

@@ -0,0 +1,20 @@
+import type { OidcService } from '../provider/oidc_service.js';
+import { type RevokeResult } from './admin_sessions_service.js';
+/**
+ * Derruba os grants (e os tokens deles) que carregam a org `orgId` — de uma conta
+ * (membro removido / saiu da org) ou de todas (org apagada, `accountId` omitido).
+ *
+ * Chamado DEPOIS que o store confirmou a remoção. Os quatro caminhos que removem
+ * membro (form `/account/orgs`, `/account/api/orgs`, console admin, Admin API) e o
+ * `deleteOrg` passam por aqui, para que a regra seja uma só.
+ *
+ * Best-effort, e nunca silencioso: a membership JÁ saiu do store, então falhar a
+ * request aqui só mentiria para quem removeu ("deu erro", mas o membro saiu). A
+ * conferência da emissão (`verifyActiveOrgMembership`) continua sendo a rede de
+ * segurança — no pior caso, o claim cai no próximo refresh. A falha é logada em
+ * `error`, porque uma revogação que não aconteceu precisa aparecer.
+ *
+ * `service` sem `config.AdapterClass` (um ctx de teste que só carrega a config)
+ * não tem adapter OIDC onde revogar: devolve `null` sem tentar.
+ */
+export declare function revokeOrgAccess(service: Pick<OidcService, 'config'> | undefined, orgId: string, accountId?: string): Promise<RevokeResult | null>;

package/build/src/host/org_access_revocation.js

@@ -0,0 +1,41 @@
+import { getBootedApp } from '../../services/booted_app.js';
+import { AdminSessionsService } from './admin_sessions_service.js';
+/**
+ * Derruba os grants (e os tokens deles) que carregam a org `orgId` — de uma conta
+ * (membro removido / saiu da org) ou de todas (org apagada, `accountId` omitido).
+ *
+ * Chamado DEPOIS que o store confirmou a remoção. Os quatro caminhos que removem
+ * membro (form `/account/orgs`, `/account/api/orgs`, console admin, Admin API) e o
+ * `deleteOrg` passam por aqui, para que a regra seja uma só.
+ *
+ * Best-effort, e nunca silencioso: a membership JÁ saiu do store, então falhar a
+ * request aqui só mentiria para quem removeu ("deu erro", mas o membro saiu). A
+ * conferência da emissão (`verifyActiveOrgMembership`) continua sendo a rede de
+ * segurança — no pior caso, o claim cai no próximo refresh. A falha é logada em
+ * `error`, porque uma revogação que não aconteceu precisa aparecer.
+ *
+ * `service` sem `config.AdapterClass` (um ctx de teste que só carrega a config)
+ * não tem adapter OIDC onde revogar: devolve `null` sem tentar.
+ */
+export async function revokeOrgAccess(service, orgId, accountId) {
+    if (!service?.config?.AdapterClass)
+        return null;
+    try {
+        return await new AdminSessionsService(service).revokeOrgGrants(orgId, accountId);
+    }
+    catch (error) {
+        await logFailure(error, orgId, accountId);
+        return null;
+    }
+}
+async function logFailure(error, orgId, accountId) {
+    const msg = 'authkit: falha ao revogar os grants da org — o claim de org cai só no próximo refresh';
+    try {
+        const logger = await getBootedApp().container.make('logger');
+        logger.error({ err: error, orgId, accountId }, msg);
+    }
+    catch {
+        // eslint-disable-next-line no-console
+        console.error(msg, { orgId, accountId, error });
+    }
+}