@adonis-agora/authkit-client 0.20.4 → 1.0.0-rc.0

package/README.md

@@ -8,8 +8,16 @@ Authorization Server (`@adonis-agora/authkit-server`), validando o ID token loca
 node ace add @adonis-agora/authkit-client
 # ou: pnpm add @adonis-agora/authkit-client && node ace configure @adonis-agora/authkit-client
 ```
-O `configure` publica `config/authkit_client.ts`, o controller `app/controllers/oidc_session_controller.ts`
-(login/callback/logout) e registra o provider + o middleware `authkit_middleware`.
+`@adonisjs/auth` é peer obrigatório: `ctx.auth` é o autenticador do `@adonisjs/auth`, apoiado
+na sessão do AuthKit pelo `authkitClientGuard`. O `configure`:
+
+- instala `@adonisjs/auth` se o app ainda não depende dele (`--no-install` só imprime o comando);
+- publica `config/authkit_client.ts` e `config/auth.ts` (`authkitClientGuard` +
+  `sessionUserProvider` com `--model`, default `#models/user`; um `config/auth.ts` existente não é
+  tocado e o guard a adicionar é impresso);
+- publica `app/middleware/auth_middleware.ts` / `silent_auth_middleware.ts` (named `auth` e
+  `silentAuth`) e o controller `app/controllers/oidc_session_controller.ts`;
+- registra os providers e, no `router`, `initialize_auth_middleware` + `authkit_context_middleware`.
 
 ## Rotas de sessão
 
@@ -23,7 +31,6 @@ import { registerOidcClient } from '@adonis-agora/authkit-client'
 
 registerOidcClient(router, {
   prefix: '/auth',                                  // default
-  loginMiddleware: middleware.guest(),
   redirects: { byGlobalRole: { ADMIN: '/admin' }, default: '/' },
   afterLogin: async (ctx, identity) => undefined,   // retornar string redireciona
   postLogoutRedirect: '/',                          // default: origem do redirectUri + '/'
@@ -51,25 +58,52 @@ router.post('/auth/logout', [OidcSessionController, 'logout'])
 > `startSession`/`endSession` são os caminhos que mantêm a invariante.
 
 ## Uso por request
-`ctx.auth` é populado pelo `authkit_middleware`:
+Rotas usam `middleware.auth()` / `middleware.silentAuth()` e os controllers leem o usuário em
+`ctx.auth`:
 ```ts
-const identity = await ctx.auth.getIdentity()   // claims OIDC validadas (ou null)
-const user = await ctx.auth.getUser()            // model do app (via resolveUser)
-ctx.auth.hasGlobalRole('ADMIN')                  // síncrono, das claims (roles do token)
+// app/controllers/dashboard_controller.ts
+export default class DashboardController {
+  async handle({ auth, authkit, inertia }: HttpContext) {
+    const user = auth.getUserOrFail()                // atrás de middleware.auth()
+    const isAdmin = authkit.hasGlobalRole('ADMIN')   // síncrono, das claims do token
+    return inertia.render('dashboard', { user, isAdmin })
+  }
+}
 ```
+O guard pega o usuário do `resolveUser` (ex.: `lucidMirror`, que cria a linha no primeiro login)
+e cai no provider quando não há `resolveUser`. Sem tabela local de usuários, use
+`authkitIdentityProvider()` como provider: `ctx.auth.user` é a `Identity`.
+
+`ctx.authkit` (populado pelo `authkit_context_middleware`) traz o que só o AuthKit sabe — a
+`Identity` (`getIdentity()`), `hasGlobalRole`, a org ativa e `toSharedProps()` para o
+`@adonis-agora/authkit-react` — inclusive em rotas públicas.
 
 > **Autorização por app-role saiu do AuthKit.** O AuthKit só autentica e conhece as `globalRoles` do
 > token. Roles do app (numa tabela do domínio) e permissões são do `@adonis-agora/authz` — configure
-> o seam `resolveRoles` lá. Guard de rota por role vai pra authz/Bouncer, não para o `authkit_middleware`
+> o seam `resolveRoles` lá. Guard de rota por role vai pra authz/Bouncer, não para o `middleware.auth()`
 > (que só exige login).
 
 ## Resolução de sessão
 `resolvers.jwt({ tokenSource })` valida o **ID token** (JWT) por JWKS:
 - `tokenSource: 'session'` (default) — lê o token set do `@adonisjs/session`.
-- `tokenSource: 'bearer'` — lê do header `Authorization` (SPA/API).
+- `tokenSource: 'bearer'` — lê do header `Authorization` (SPA/API): `Bearer <jwt>` ou
+  `DPoP <jwt>` com a prova no header `DPoP` (token com `cnf.jkt` enviado como `Bearer` é recusado).
+
+Rotas de API ganham um guard próprio com `resolver`:
+```ts
+// config/auth.ts
+api: authkitClientGuard({
+  provider: authkitIdentityProvider(),
+  resolver: resolvers.jwt({ tokenSource: 'bearer' }), // ou resolvers.opaque/resolvers.pat
+}),
+```
+```ts
+// start/routes.ts
+router.group(() => { /* … */ }).prefix('/api').use(middleware.auth({ guards: ['api'] }))
+```
 
 ## Topologias de banco
-A identidade (`ctx.auth.identity`) sempre vem do **token validado** e independe da
+A identidade (`ctx.authkit.identity`) sempre vem do **token validado** e independe da
 topologia de banco. O que muda é como `resolveUser` obtém o model do app.
 
 ### Mesmo banco + schemas
@@ -102,8 +136,9 @@ Roles do app (a tabela de roles do próprio domínio) não passam mais pelo Auth
 `resolveRoles` do `@adonis-agora/authz`, que as une às `globalRoles` do token para decidir permissão.
 
 ## Ordem de middleware (importante)
-O middleware do `@adonisjs/session` DEVE rodar ANTES do `authkit_middleware` no stack `router`
-(o resolver lê o token da session). Garanta essa ordem em `start/kernel.ts`.
+No stack `router`: `@adonisjs/session` → `@adonisjs/auth/initialize_auth_middleware` →
+`authkit_context_middleware` (o resolver lê o token da session). O `configure` já registra nessa
+ordem.
 
 ## Observabilidade (opcional)
 O `Authenticator` registra métricas de resolução (`authkit.resolve.duration` e

package/build/auth.d.ts

@@ -0,0 +1,2 @@
+export type { IdentityUserProviderContract } from './src/host/authkit_client_guard.js';
+export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';

package/build/auth.js

@@ -0,0 +1 @@
+export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';

package/build/authkit_context_middleware.d.ts

@@ -0,0 +1 @@
+export { default } from './src/middleware/authkit_context_middleware.js';

package/build/authkit_context_middleware.js

@@ -0,0 +1,2 @@
+// `@adonis-agora/authkit-client/authkit_context_middleware`: populates `ctx.authkit`.
+export { default } from './src/middleware/authkit_context_middleware.js';

package/build/commands/configure.d.ts

@@ -1,2 +1,12 @@
 import type Configure from '@adonisjs/core/commands/configure';
+/**
+ * `node ace configure @adonis-agora/authkit-client`
+ *
+ * `ctx.auth` comes from `@adonisjs/auth`, backed by the AuthKit session through
+ * `authkitClientGuard`, and `ctx.authkit` carries the AuthKit-only surface.
+ * Flags:
+ *
+ * - `--model=<import>`: the user model the guard's provider loads (default `#models/user`).
+ * - `--no-install`: print the install command instead of installing `@adonisjs/auth`.
+ */
 export declare function configure(command: Configure): Promise<void>;

package/build/commands/configure.js

@@ -1,11 +1,46 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { stubsRoot } from '../stubs/main.js';
+const ADONIS_AUTH = '@adonisjs/auth';
+/**
+ * `node ace configure @adonis-agora/authkit-client`
+ *
+ * `ctx.auth` comes from `@adonisjs/auth`, backed by the AuthKit session through
+ * `authkitClientGuard`, and `ctx.authkit` carries the AuthKit-only surface.
+ * Flags:
+ *
+ * - `--model=<import>`: the user model the guard's provider loads (default `#models/user`).
+ * - `--no-install`: print the install command instead of installing `@adonisjs/auth`.
+ */
 export async function configure(command) {
+    const flags = (command.parsedFlags ?? {});
+    const modelImport = typeof flags.model === 'string' && flags.model.trim() ? flags.model.trim() : '#models/user';
     const codemods = await command.createCodemods();
     await codemods.makeUsingStub(stubsRoot, 'config/authkit_client.stub', {});
     await codemods.makeUsingStub(stubsRoot, 'controllers/oidc_session_controller.stub', {});
-    await codemods.updateRcFile((rc) => rc.addProvider('@adonis-agora/authkit-client/authkit_client_provider'));
+    await codemods.updateRcFile((rc) => {
+        rc.addProvider('@adonisjs/auth/auth_provider');
+        rc.addProvider('@adonis-agora/authkit-client/authkit_client_provider');
+    });
+    await ensureAdonisAuth(command, codemods, flags.install !== false);
+    const authConfigPath = command.app.configPath('auth.ts');
+    if (existsSync(authConfigPath)) {
+        command.logger.warning('config/auth.ts already exists, so it was left as is. Add the AuthKit guard to it:\n' +
+            "  import { authkitClientGuard } from '@adonis-agora/authkit-client/auth'\n" +
+            `  web: authkitClientGuard({ provider: sessionUserProvider({ model: () => import('${modelImport}') }) }),`);
+    }
+    else {
+        await codemods.makeUsingStub(stubsRoot, 'config/auth.stub', { modelImport });
+    }
+    await codemods.makeUsingStub(stubsRoot, 'middleware/auth_middleware.stub', {});
+    await codemods.makeUsingStub(stubsRoot, 'middleware/silent_auth_middleware.stub', {});
     await codemods.registerMiddleware('router', [
-        { path: '@adonis-agora/authkit-client/authkit_middleware' },
+        { path: '@adonisjs/auth/initialize_auth_middleware' },
+        { path: '@adonis-agora/authkit-client/authkit_context_middleware' },
+    ]);
+    await codemods.registerMiddleware('named', [
+        { name: 'auth', path: '#middleware/auth_middleware' },
+        { name: 'silentAuth', path: '#middleware/silent_auth_middleware' },
     ]);
     await codemods.defineEnvValidations({
         leadingComment: 'Variáveis do @adonis-agora/authkit-client (OIDC client)',
@@ -22,4 +57,24 @@ export async function configure(command) {
     command.logger.info('Registre as rotas de sessão em start/routes.ts com registerOidcClient(router) ' +
         "(import { registerOidcClient } from '@adonis-agora/authkit-client'). " +
         'O app/controllers/oidc_session_controller.ts publicado é só para customizar o fluxo.');
+    command.logger.info(`ctx.auth usa o authkitClientGuard (config/auth.ts, model ${modelImport}): proteja rotas com ` +
+        'middleware.auth() e leia auth.user. Para criar o usuário local no primeiro login, ' +
+        'configure resolveUser: lucidMirror(User, …) em config/authkit_client.ts.');
+}
+/** Installs `@adonisjs/auth` when the app does not depend on it yet. */
+async function ensureAdonisAuth(command, codemods, install) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(await readFile(command.app.makePath('package.json'), 'utf8'));
+    }
+    catch {
+        // No readable package.json: treat the dependency as missing.
+    }
+    if (manifest.dependencies?.[ADONIS_AUTH] || manifest.devDependencies?.[ADONIS_AUTH])
+        return;
+    const packages = [{ name: ADONIS_AUTH, isDevDependency: false }];
+    if (install)
+        await codemods.installPackages(packages);
+    else
+        await codemods.listPackagesToInstall(packages);
 }

package/build/index.d.ts

@@ -13,10 +13,11 @@ export type { DiscoverOptions, OidcEndpoints } from './src/discovery.js';
 export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
 export type { CreateDpopProofInput, DpopKeyPair } from './src/dpop.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
-export type { UnauthorizedAccessConstructor } from './src/host/authkit_client_guard.js';
-export { AuthkitClientGuard, authkitClientGuard } from './src/host/authkit_client_guard.js';
+export type { IdentityUserProviderContract } from './src/host/authkit_client_guard.js';
+export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';
 export type { DashboardGuardOptions } from './src/host/dashboard_guard.js';
 export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
+export type { AuthkitUser, AuthkitUserType } from './src/host/request_authenticator.js';
 export { getAuthkit } from './src/host/request_authenticator.js';
 export type { ResiliencePolicy } from './src/http/resilient_fetch.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';

package/build/index.js

@@ -6,7 +6,7 @@ export { BACKCHANNEL_LOGOUT_EVENT, InMemorySessionIndex, InvalidLogoutTokenError
 export { defineConfig, resolvers } from './src/define_config.js';
 export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
-export { AuthkitClientGuard, authkitClientGuard } from './src/host/authkit_client_guard.js';
+export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';
 export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
 export { getAuthkit } from './src/host/request_authenticator.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';

package/build/providers/authkit_client_provider.d.ts

@@ -7,6 +7,7 @@ import { type AuthorizationRequest, type CompleteAuthorizationParams, type Compl
 import type { ResolvedClientConfig } from '../src/define_config.js';
 import { type OidcEndpoints } from '../src/discovery.js';
 import { type IdTokenClaims, type ValidateIdTokenOptions } from '../src/id_token.js';
+import type { ResolverFactory } from '../src/resolvers/factory.js';
 import type { TokenSet } from '../src/types.js';
 /** Deps injetáveis (relógio/fetch) para testar `maybeRefresh` sem rede/tempo real. */
 export interface RefreshDeps {
@@ -161,7 +162,13 @@ export declare class AuthkitClientManager {
      * sobrevive à sessão que a parqueou.
      */
     startSession(ctx: HttpContext, tokenSet: TokenSet): void;
-    createAuthenticator(ctx: HttpContext): Promise<Authenticator>;
+    /**
+     * The request's {@link Authenticator}. `options.resolver` replaces the configured
+     * resolver for this authenticator only (e.g. a guard for bearer-token API routes).
+     */
+    createAuthenticator(ctx: HttpContext, options?: {
+        resolver?: ResolverFactory;
+    }): Promise<Authenticator>;
 }
 export default class AuthkitClientProvider {
     protected app: ApplicationService;

package/build/providers/authkit_client_provider.js

@@ -41,17 +41,29 @@ export class AuthkitClientManager {
         this.deps = deps;
         this.#logger = deps.logger ?? { warn: () => { } };
     }
-    async #getResolver() {
+    #extraResolvers = new WeakMap();
+    #buildResolver(factory) {
+        return factory.resolver({
+            issuer: this.config.issuer,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            sessionKey: this.config.sessionKey,
+            globalRolesClaim: this.config.globalRolesClaim,
+            endpoints: () => this.endpoints(),
+            logger: this.#logger,
+        });
+    }
+    async #getResolver(factory) {
+        if (factory && factory !== this.config.resolverFactory) {
+            let resolver = this.#extraResolvers.get(factory);
+            if (!resolver) {
+                resolver = this.#buildResolver(factory);
+                this.#extraResolvers.set(factory, resolver);
+            }
+            return resolver;
+        }
         if (!this.#resolverCache) {
-            this.#resolverCache = await this.config.resolverFactory.resolver({
-                issuer: this.config.issuer,
-                clientId: this.config.clientId,
-                clientSecret: this.config.clientSecret,
-                sessionKey: this.config.sessionKey,
-                globalRolesClaim: this.config.globalRolesClaim,
-                endpoints: () => this.endpoints(),
-                logger: this.#logger,
-            });
+            this.#resolverCache = await this.#buildResolver(this.config.resolverFactory);
         }
         return this.#resolverCache;
     }
@@ -445,8 +457,12 @@ export class AuthkitClientManager {
         session.forget(this.#impersonatorKey);
         session.put(this.config.sessionKey, tokenSet);
     }
-    async createAuthenticator(ctx) {
-        const resolver = await this.#getResolver();
+    /**
+     * The request's {@link Authenticator}. `options.resolver` replaces the configured
+     * resolver for this authenticator only (e.g. a guard for bearer-token API routes).
+     */
+    async createAuthenticator(ctx, options = {}) {
+        const resolver = await this.#getResolver(options.resolver);
         const sessionKey = this.config.sessionKey;
         return new Authenticator(ctx, {
             resolver,

package/build/src/authenticator.d.ts

@@ -13,9 +13,8 @@ export interface AuthenticatorDeps {
 }
 /**
  * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`
- * devolve — o app o fixa via augmentation de `HttpContext.auth` (`auth: Authenticator<AppUser>`),
- * e aí `getUser()` passa a devolver `AppUser | null` em todo call-site, sem cast. Default `unknown`
- * mantém o comportamento anterior (nada a mudar em quem não augmenta).
+ * devolve — o app o fixa pela interface `AuthkitUserType`, e aí `getUser()` passa a devolver
+ * `AppUser | null` em todo call-site, sem cast. Default `unknown`.
  */
 export declare class Authenticator<TUser = unknown> {
     #private;
@@ -26,6 +25,8 @@ export declare class Authenticator<TUser = unknown> {
     get identity(): Identity | null;
     authenticate(): Promise<Identity>;
     check(): Promise<boolean>;
+    /** `true` when the app configured `resolveUser` (e.g. `lucidMirror`) for this client. */
+    get resolvesUser(): boolean;
     hasGlobalRole(role: string): boolean;
     getUser(): Promise<TUser | null>;
     /**

package/build/src/authenticator.js

@@ -2,9 +2,8 @@ import { AUTHKIT_METRICS, NoopRecorder } from '@adonis-agora/authkit-core';
 import { populateContext } from './observability/context_bridge.js';
 /**
  * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`
- * devolve — o app o fixa via augmentation de `HttpContext.auth` (`auth: Authenticator<AppUser>`),
- * e aí `getUser()` passa a devolver `AppUser | null` em todo call-site, sem cast. Default `unknown`
- * mantém o comportamento anterior (nada a mudar em quem não augmenta).
+ * devolve — o app o fixa pela interface `AuthkitUserType`, e aí `getUser()` passa a devolver
+ * `AppUser | null` em todo call-site, sem cast. Default `unknown`.
  */
 export class Authenticator {
     ctx;
@@ -53,6 +52,10 @@ export class Authenticator {
     async check() {
         return (await this.getIdentity()) !== null;
     }
+    /** `true` when the app configured `resolveUser` (e.g. `lucidMirror`) for this client. */
+    get resolvesUser() {
+        return typeof this.deps.resolveUser === 'function';
+    }
     hasGlobalRole(role) {
         return this.#identity?.globalRoles.includes(role) ?? false;
     }

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

@@ -1,29 +1,33 @@
-import type { symbols } from '@adonisjs/auth';
+import type { Identity } from '@adonis-agora/authkit-core';
+import { type symbols } from '@adonisjs/auth';
 import type { AuthClientResponse, GuardConfigProvider } from '@adonisjs/auth/types';
-import type { SessionUserProviderContract } from '@adonisjs/auth/types/session';
+import type { SessionGuardUser, SessionUserProviderContract } from '@adonisjs/auth/types/session';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ConfigProvider } from '@adonisjs/core/types';
 import type { Authenticator } from '../authenticator.js';
-/**
- * Construtor do `E_UNAUTHORIZED_ACCESS` do `@adonisjs/auth`, capturado no boot
- * (ver {@link authkitClientGuard}) para que `getUserOrFail()` — que o contrato
- * exige SÍNCRONO — possa lançá-lo sem um `await import()`.
- */
-export type UnauthorizedAccessConstructor = new (message: string, options: {
-    guardDriverName: string;
-    redirectTo?: string;
-}) => Error;
+import type { ResolverFactory } from '../resolvers/factory.js';
+import { type AuthkitUser } from './request_authenticator.js';
 /** O tipo de usuário REAL por trás de um user provider do `@adonisjs/auth`. */
 type RealUser<UserProvider> = UserProvider extends SessionUserProviderContract<infer User> ? User : never;
 /**
- * Guard de `@adonisjs/auth` apoiado na sessão OIDC do `@adonis-agora/authkit-client`.
+ * User provider que pode montar o usuário direto da `Identity` (sem banco). É o
+ * que {@link authkitIdentityProvider} devolve; o guard o usa antes de `findById`.
+ */
+export interface IdentityUserProviderContract<User> extends SessionUserProviderContract<User> {
+    fromIdentity(identity: Identity): Promise<SessionGuardUser<User> | null>;
+}
+/**
+ * Guard de `@adonisjs/auth` apoiado na sessão do `@adonis-agora/authkit-client`.
  *
  * A fonte da verdade de "quem está logado" é o `SessionResolver` do authkit
- * (JWT/opaco/PAT, conforme `config/authkit_client.ts`) — o guard NÃO reimplementa
- * resolução de sessão nem lê a sessão por conta própria. Ele só faz a ponte:
- * pega o `sub` da `Identity` (`identity.userId`) e pede o usuário do app ao
- * `provider`, exatamente como o `sessionGuard` nativo faria com o id que ele
- * guarda na sessão.
+ * (sessão OIDC, bearer JWT, opaco/introspecção ou PAT, conforme
+ * `config/authkit_client.ts` ou a opção `resolver` do guard). O guard não lê a
+ * sessão por conta própria.
+ *
+ * O usuário vem, nesta ordem: do `resolveUser` de `config/authkit_client.ts`
+ * (ex.: `lucidMirror`, que cria a linha local no primeiro login; é a MESMA
+ * instância de `ctx.authkit.getUser()`), do provider montando o usuário da
+ * `Identity` ({@link authkitIdentityProvider}), ou de `provider.findById(sub)`.
  *
  * Consequência: `middleware.auth()`, `ctx.auth.user`, `auth.check()` e o Bouncer
  * passam a funcionar sobre uma sessão do authkit.
@@ -36,20 +40,21 @@ export declare class AuthkitClientGuard<UserProvider extends SessionUserProvider
     authenticationAttempted: boolean;
     isAuthenticated: boolean;
     user?: RealUser<UserProvider>;
-    constructor(_name: string, ctx: HttpContext, userProvider: UserProvider, unauthorized: UnauthorizedAccessConstructor);
+    constructor(_name: string, ctx: HttpContext, userProvider: UserProvider, options?: {
+        resolver?: ResolverFactory;
+    });
     /**
-     * O {@link Authenticator} do authkit desta request (a `Identity` crua,
+     * O {@link Authenticator} do authkit que este guard usou (a `Identity` crua,
      * `hasGlobalRole`, `toSharedProps`). Só existe depois de uma tentativa de
      * autenticação; use `ctx.authkit` (via `authkit_context_middleware`) quando
      * precisar dele em rota pública.
      */
-    get authkit(): Authenticator | undefined;
+    get authkit(): Authenticator<AuthkitUser> | undefined;
     /**
-     * Autentica a request: resolve a sessão do authkit e mapeia o `sub` para o
-     * usuário do app via `provider.findById`. Lança `E_UNAUTHORIZED_ACCESS` (o
-     * MESMO erro dos guards nativos, então o `middleware.auth()` e o handler de
-     * exceção do host tratam igual) quando não há sessão OU quando a sessão é
-     * válida mas não existe usuário local correspondente (fail-closed).
+     * Autentica a request. Lança `E_UNAUTHORIZED_ACCESS` (o MESMO erro dos guards
+     * nativos, então o `middleware.auth()` e o handler de exceção do host tratam
+     * igual) quando não há sessão OU quando a sessão é válida mas nenhuma fonte
+     * devolve usuário (fail-closed).
      */
     authenticate(): Promise<RealUser<UserProvider>>;
     /** Igual aos guards nativos: `authenticate()` sem lançar. */
@@ -71,7 +76,8 @@ export declare class AuthkitClientGuard<UserProvider extends SessionUserProvider
  * ```ts
  * import { defineConfig } from '@adonisjs/auth'
  * import { sessionUserProvider } from '@adonisjs/auth/session'
- * import { authkitClientGuard } from '@adonis-agora/authkit-client'
+ * import { authkitClientGuard, authkitIdentityProvider } from '@adonis-agora/authkit-client/auth'
+ * import { resolvers } from '@adonis-agora/authkit-client'
  *
  * export default defineConfig({
  *   default: 'web',
@@ -79,22 +85,31 @@ export declare class AuthkitClientGuard<UserProvider extends SessionUserProvider
  *     web: authkitClientGuard({
  *       provider: sessionUserProvider({ model: () => import('#models/user') }),
  *     }),
+ *     // API routes authenticated by a bearer access token.
+ *     api: authkitClientGuard({
+ *       provider: authkitIdentityProvider(),
+ *       resolver: resolvers.jwt({ tokenSource: 'bearer' }),
+ *     }),
  *   },
  * })
  * ```
  *
- * O `provider` é o MESMO contrato do `sessionGuard` nativo, então qualquer user
- * provider de session serve. O `findById` recebe `identity.userId` (a claim
- * `sub`) — a coluna de id do model precisa ser essa (é o que o `lucidMirror()`
- * grava).
- *
- * Precedência com `resolveUser` de `config/authkit_client.ts`: são superfícies
- * SEPARADAS e ambas continuam valendo. `ctx.auth.user` (framework) vem SEMPRE do
- * `provider`; `ctx.authkit.getUser()` (authkit) continua vindo do `resolveUser`.
- * O guard nunca chama `resolveUser`. Com o guard configurado, o normal é apagar
- * o `resolveUser` e deixar só o `provider`.
+ * - `provider`: any session user provider. Its `findById` receives `identity.userId`
+ *   (the `sub` claim). With `resolveUser` in `config/authkit_client.ts`, the guard
+ *   uses that user first and the provider is the fallback.
+ * - `resolver`: replaces the resolver of `config/authkit_client.ts` for this guard
+ *   only (bearer JWT, opaque, PAT). Without it the guard uses the configured one.
  */
 export declare function authkitClientGuard<UserProvider extends SessionUserProviderContract<unknown>>(config: {
     provider: UserProvider | ConfigProvider<UserProvider>;
+    resolver?: ResolverFactory;
 }): GuardConfigProvider<(ctx: HttpContext) => AuthkitClientGuard<UserProvider>>;
+/**
+ * User provider with no database: `ctx.auth.user` is the AuthKit {@link Identity}
+ * of the request (`userId`, `email`, `globalRoles`, `profile`, the raw claims).
+ * Use it when the app keeps no local user table, or for API guards that only need
+ * the token's subject. When `config/authkit_client.ts` sets `resolveUser`, the
+ * guard uses that user instead.
+ */
+export declare function authkitIdentityProvider(): IdentityUserProviderContract<Identity>;
 export {};