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

package/build/src/resolvers/jwt_resolver.js

@@ -1,13 +1,15 @@
 import { jwtVerify } from 'jose';
 import { DEFAULT_ALGS, getJwks } from '../jwks.js';
+import { DpopReplayCache, verifyDpopProof } from './dpop_proof.js';
 import { buildIdentityFromClaims } from './identity.js';
 export class JwtResolver {
     config;
+    #replay = new DpopReplayCache();
     constructor(config) {
         this.config = config;
     }
-    /** Valida um JWT cru e monta a Identity (ou null se inválido). */
-    async resolveToken(token) {
+    /** The verified claims of a raw JWT, or `null`. */
+    async #verify(token) {
         const endpoints = await this.config.endpoints();
         if (!endpoints)
             return null;
@@ -21,16 +23,58 @@ export class JwtResolver {
             // uma identidade válida exige um subject (`sub`)
             if (!payload.sub)
                 return null;
-            return buildIdentityFromClaims(payload, this.config.globalRolesClaim);
+            return payload;
         }
         catch {
             return null;
         }
     }
+    #identity(claims) {
+        return claims ? buildIdentityFromClaims(claims, this.config.globalRolesClaim) : null;
+    }
+    /** Valida um JWT cru e monta a Identity (ou null se inválido). */
+    async resolveToken(token) {
+        return this.#identity(await this.#verify(token));
+    }
     async resolve(ctx) {
+        if (this.config.authorizationHeader)
+            return this.#resolveAuthorization(ctx);
         const token = this.config.getToken?.(ctx) ?? null;
         if (!token)
             return null;
         return this.resolveToken(token);
     }
+    async #resolveAuthorization(ctx) {
+        const header = ctx.request.header('authorization');
+        if (!header)
+            return null;
+        const [scheme, token, ...rest] = header.trim().split(/\s+/);
+        if (!token || rest.length > 0)
+            return null;
+        const claims = await this.#verify(token);
+        if (!claims)
+            return null;
+        const jkt = claims.cnf?.jkt;
+        switch (scheme?.toLowerCase()) {
+            case 'bearer':
+                // RFC 9449 §7.1: a DPoP-bound token is not a bearer token.
+                return typeof jkt === 'string' ? null : this.#identity(claims);
+            case 'dpop': {
+                if (typeof jkt !== 'string')
+                    return null;
+                const valid = await verifyDpopProof({
+                    proof: ctx.request.header('dpop'),
+                    method: ctx.request.method(),
+                    url: ctx.request.completeUrl(false),
+                    accessToken: token,
+                    expectedJkt: jkt,
+                    maxAge: this.config.dpopMaxAge ?? 300,
+                    replay: this.#replay,
+                });
+                return valid ? this.#identity(claims) : null;
+            }
+            default:
+                return null;
+        }
+    }
 }

package/build/stubs/config/auth.stub

@@ -0,0 +1,30 @@
+{{{
+  exports({ to: app.configPath('auth.ts') })
+}}}
+import { defineConfig } from '@adonisjs/auth'
+import { sessionUserProvider } from '@adonisjs/auth/session'
+import type { InferAuthenticators } from '@adonisjs/auth/types'
+import { authkitClientGuard } from '@adonis-agora/authkit-client/auth'
+
+/**
+ * ctx.auth is backed by the AuthKit session. The guard takes the user from
+ * resolveUser in config/authkit_client.ts when you set one (e.g. lucidMirror,
+ * which creates the local row on first login), and falls back to this provider
+ * otherwise. The model's primary key must be the IdP's sub.
+ */
+const authConfig = defineConfig({
+  default: 'web',
+  guards: {
+    web: authkitClientGuard({
+      provider: sessionUserProvider({
+        model: () => import('{{ modelImport }}'),
+      }),
+    }),
+  },
+})
+
+export default authConfig
+
+declare module '@adonisjs/auth/types' {
+  export interface Authenticators extends InferAuthenticators<typeof authConfig> {}
+}

package/build/stubs/config/authkit_client.stub

@@ -10,7 +10,8 @@ const authkitClientConfig = defineConfig({
   clientSecret: env.get('AUTHKIT_CLIENT_SECRET'),
   redirectUri: env.get('AUTHKIT_REDIRECT_URI'),
   resolver: resolvers.jwt({ tokenSource: 'session' }),
-  // resolveUser: async (identity) => User.find(identity.userId),
+  // Creates/updates the local user on each login; ctx.auth.user is this user.
+  // resolveUser: lucidMirror(User, { sync: (identity) => ({ email: identity.email }) }),
   // Roles do app? Configure resolveRoles no @adonis-agora/authz (não aqui — o AuthKit só autentica).
 })
 

package/build/stubs/middleware/auth_middleware.stub

@@ -0,0 +1,25 @@
+{{{
+  exports({ to: app.middlewarePath('auth_middleware.ts') })
+}}}
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+import type { Authenticators } from '@adonisjs/auth/types'
+
+/**
+ * Denies access to unauthenticated requests and sends them to the AuthKit
+ * login route registered by registerOidcClient(router).
+ */
+export default class AuthMiddleware {
+  redirectTo = '/auth/login'
+
+  async handle(
+    ctx: HttpContext,
+    next: NextFn,
+    options: {
+      guards?: (keyof Authenticators)[]
+    } = {}
+  ) {
+    await ctx.auth.authenticateUsing(options.guards, { loginRoute: this.redirectTo })
+    return next()
+  }
+}

package/build/stubs/middleware/silent_auth_middleware.stub

@@ -0,0 +1,16 @@
+{{{
+  exports({ to: app.middlewarePath('silent_auth_middleware.ts') })
+}}}
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+
+/**
+ * Checks the AuthKit session without requiring one, so ctx.auth.user is set
+ * on routes that also serve guests.
+ */
+export default class SilentAuthMiddleware {
+  async handle(ctx: HttpContext, next: NextFn) {
+    await ctx.auth.check()
+    return next()
+  }
+}

package/build/types.d.ts

@@ -1,43 +1,16 @@
-import './container_bindings.js';
+import './src/host/request_authenticator.js';
 import type { AuthkitClientManager } from './providers/authkit_client_provider.js';
 import type { Authenticator } from './src/authenticator.js';
 /**
- * OPT-IN typing for `ctx.auth`.
+ * Types of `@adonis-agora/authkit-client`.
  *
- * Reference this module from your app when you want `ctx.auth` typed as
- * AuthKit's `Authenticator` and you are NOT declaring the property yourself:
+ * Importing this module brings the container bindings (`authkit.client`) and the
+ * `ctx.authkit` declaration into your program. `ctx.auth` belongs to
+ * `@adonisjs/auth`; use `authkitClientGuard` to back it with the AuthKit session.
  *
  * ```ts
  * // any file in your app, e.g. app/types.ts
  * import '@adonis-agora/authkit-client/types'
  * ```
- *
- * NOTHING in this package imports this module on your behalf, and that is the
- * point. `Authenticator` is generic (`Authenticator<TUser>`), and most apps
- * declare their own augmentation so `auth.getUser()` returns their user model:
- *
- * ```ts
- * declare module '@adonisjs/core/http' {
- *   interface HttpContext {
- *     auth: Authenticator<AppUser>
- *   }
- * }
- * ```
- *
- * Two declarations of the same property with different types do not merge —
- * they conflict, and because `skipLibCheck` is on in every AdonisJS app the
- * conflict is never reported: one simply wins by include order. When the
- * library's won, `auth.getUser()` collapsed to `unknown` across the whole app.
- * So the library ships the declaration and lets you decide whether to load it,
- * rather than forcing it through a middleware import.
- *
- * The container bindings come along with it (see `container_bindings.ts`); they
- * are also available on their own, which is what the provider and the middleware
- * use.
  */
-declare module '@adonisjs/core/http' {
-    interface HttpContext {
-        auth: Authenticator;
-    }
-}
 export type { Authenticator, AuthkitClientManager };

package/build/types.js

@@ -1 +1 @@
-import './container_bindings.js';
+import './src/host/request_authenticator.js';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.20.5",
+  "version": "1.0.0-rc.0",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DavideCarvalho/adonis-agora-authkit.git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-agora-authkit.git",
     "directory": "packages/authkit-client"
   },
   "homepage": "https://davidecarvalho.github.io/agora/docs/authkit",
@@ -33,7 +33,8 @@
   "files": [
     "build",
     "stubs",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": "./build/index.js",
@@ -41,14 +42,11 @@
     "./container_bindings": "./build/container_bindings.js",
     "./services/main": "./build/services/main.js",
     "./authkit_client_provider": "./build/providers/authkit_client_provider.js",
-    "./auth": "./build/src/host/authkit_client_guard.js",
+    "./auth": "./build/auth.js",
     "./dashboard_guard": "./build/src/host/dashboard_guard.js",
-    "./authkit_middleware": "./build/src/middleware/authkit_middleware.js",
-    "./authkit_context_middleware": "./build/src/middleware/authkit_context_middleware.js",
+    "./authkit_context_middleware": "./build/authkit_context_middleware.js",
     "./backchannel_revocation_middleware": "./build/src/middleware/backchannel_revocation_middleware.js",
-    "./auth_middleware": "./build/src/middleware/auth_middleware.js",
     "./require_org_middleware": "./build/src/middleware/require_org_middleware.js",
-    "./silent_auth_middleware": "./build/src/middleware/silent_auth_middleware.js",
     "./commands": "./build/commands/configure.js"
   },
   "adonisjs": {
@@ -64,16 +62,13 @@
     "node": ">=24"
   },
   "peerDependencies": {
-    "@adonis-agora/resilience": ">=0.1.0 <1.0.0",
+    "@adonis-agora/resilience": ">=0.1.0 <2.0.0 || >=1.0.0-rc.0 <2.0.0",
     "@adonisjs/auth": "^10.1.0",
     "@adonisjs/core": "^7.5.0",
     "@adonisjs/lucid": "^22.4.2",
     "@adonisjs/session": "^8.1.0"
   },
   "peerDependenciesMeta": {
-    "@adonisjs/auth": {
-      "optional": true
-    },
     "@adonisjs/lucid": {
       "optional": true
     },
@@ -82,11 +77,11 @@
     }
   },
   "dependencies": {
-    "@adonis-agora/authkit-core": "0.10.1",
+    "@adonis-agora/authkit-core": "1.0.0-rc.0",
     "jose": "6.2.15"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "0.90.1",
+    "@adonis-agora/authkit-server": "1.0.0-rc.0",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",
@@ -95,7 +90,7 @@
     "@adonisjs/tsconfig": "2.0.0",
     "@japa/assert": "4.2.0",
     "@japa/runner": "5.4.0",
-    "@poppinss/ts-exec": "1.5.1",
+    "@poppinss/ts-exec": "1.5.2",
     "@tanstack/intent": "0.5.6",
     "@types/node": "26.6.5",
     "ioredis-mock": "8.13.1",

package/skills/authkit-rp-client/SKILL.md

@@ -2,16 +2,16 @@
 name: authkit-rp-client
 description: >-
   Integrate an AdonisJS app as an OpenID Connect relying party with
-  @adonis-agora/authkit-client. Covers defineConfig({ issuer, clientId, redirectUri,
-  resolver }), resolvers.jwt({ tokenSource }) / resolvers.pat / resolvers.opaque,
-  resolveUser topologies (identityToUser, createUserinfoResolver, local Lucid model),
-  the authkit_middleware + @adonisjs/session ordering rule, ctx.auth
-  (getIdentity/getUser/hasGlobalRole), registerOidcClient(router, { prefix, redirects,
-  afterLogin, loginMiddleware }), backchannelLogout: { store } +
-  BackchannelRevocationMiddleware, AUTHKIT_REDIRECT_URI, and why app-role gating
-  belongs to @adonis-agora/authz instead. Use when wiring a client app to the IdP,
-  fixing null identity, choosing a user-resolution topology, or adding back-channel
-  logout.
+  @adonis-agora/authkit-client. Covers defineConfig, resolvers.jwt / pat / opaque,
+  resolveUser (lucidMirror, identityToUser, createUserinfoResolver), ctx.auth via the
+  required @adonisjs/auth peer (authkitClientGuard with sessionUserProvider or
+  authkitIdentityProvider, middleware.auth(), auth.user), API guards with
+  authkitClientGuard({ resolver }) for bearer JWT, DPoP, opaque and PAT, the session ->
+  initialize_auth -> authkit_context_middleware ordering rule, ctx.authkit
+  (getIdentity/hasGlobalRole/toSharedProps), registerOidcClient, backchannelLogout:
+  { store }, and why app-role gating belongs to @adonis-agora/authz. Use when wiring a
+  client app to the IdP, fixing a null identity or a first-login loop, choosing a user
+  provider, protecting API routes, or adding back-channel logout.
 license: MIT
 metadata:
   type: core
@@ -29,10 +29,15 @@ sources:
 
 `@adonis-agora/authkit-client` makes an AdonisJS app consume an OIDC provider (the
 AuthKit IdP or any other) with session-based auth: PKCE authorization-code login,
-locally-validated ID tokens (JWKS), typed `ctx.auth` per request. `configure`
-publishes `config/authkit_client.ts` and registers the provider + middleware; the
-login/callback/logout routes come from `registerOidcClient(router)`. (`configure` also
-publishes an `OidcSessionController` stub, only for apps that must customise the flow.)
+locally-validated ID tokens (JWKS). `ctx.auth` is `@adonisjs/auth` (a required peer)
+backed by the AuthKit session through `authkitClientGuard`; `ctx.authkit` carries the
+AuthKit-only data. `configure` installs `@adonisjs/auth` if missing, publishes
+`config/authkit_client.ts`, `config/auth.ts` (guard + `sessionUserProvider`, `--model`,
+default `#models/user`; an existing file is left alone) and the named `auth` /
+`silentAuth` middleware, and registers the providers plus `initialize_auth_middleware` and
+`authkit_context_middleware`; the login/callback/logout routes come from
+`registerOidcClient(router)`. (`configure` also publishes an `OidcSessionController` stub,
+only for apps that must customise the flow.)
 
 ## Setup
 
@@ -43,7 +48,8 @@ node ace add @adonis-agora/authkit-client
 ```ts
 // config/authkit_client.ts
 import env from '#start/env'
-import { defineConfig, resolvers } from '@adonis-agora/authkit-client'
+import { defineConfig, lucidMirror, resolvers } from '@adonis-agora/authkit-client'
+import AppUser from '#models/app_user'
 
 const authkitClientConfig = defineConfig({
   issuer: env.get('AUTHKIT_ISSUER'),
@@ -51,11 +57,29 @@ const authkitClientConfig = defineConfig({
   clientSecret: env.get('AUTHKIT_CLIENT_SECRET'),
   redirectUri: env.get('AUTHKIT_REDIRECT_URI'), // must point at the callback route
   resolver: resolvers.jwt({ tokenSource: 'session' }),
+  // Creates the local row on first login; ctx.auth.user is this user.
+  resolveUser: lucidMirror(AppUser, { sync: (i) => ({ email: i.email }) }),
 })
 
 export default authkitClientConfig
 ```
 
+```ts
+// config/auth.ts (written by configure)
+import { defineConfig } from '@adonisjs/auth'
+import { sessionUserProvider } from '@adonisjs/auth/session'
+import { authkitClientGuard } from '@adonis-agora/authkit-client/auth'
+
+export default defineConfig({
+  default: 'web',
+  guards: {
+    web: authkitClientGuard({
+      provider: sessionUserProvider({ model: () => import('#models/app_user') }),
+    }),
+  },
+})
+```
+
 ```ts
 // start/routes.ts
 import router from '@adonisjs/core/services/router'
@@ -74,26 +98,48 @@ Source: `packages/authkit-client/README.md`, `stubs/config/authkit_client.stub`.
 
 ## Core patterns
 
-### Pattern 1 — `ctx.auth` per request
-
-The `authkit_middleware` populates `ctx.auth`; identity comes from the validated
-token, the user from your `resolveUser`:
+### Pattern 1 — `ctx.auth` per request, `ctx.authkit` for AuthKit-only data
 
 ```ts
-router.get('/me', async ({ auth }) => {
-  const identity = await auth.getIdentity() // validated OIDC claims, or null
-  const user = await auth.getUser()         // app model via resolveUser
-  const isAdmin = auth.hasGlobalRole('ADMIN') // sync — reads token claims
-  return { identity, user, isAdmin }
-})
+// app/controllers/me_controller.ts
+export default class MeController {
+  async handle({ auth, authkit }: HttpContext) {
+    const user = auth.getUserOrFail()             // the resolveUser user (sync, behind auth)
+    const identity = await authkit.getIdentity()  // validated OIDC claims
+    const isAdmin = authkit.hasGlobalRole('ADMIN') // sync — reads token claims
+    return { user, identity, isAdmin }
+  }
+}
+
+// start/routes.ts
+router.get('/me', [MeController]).use(middleware.auth())
 ```
 
-`getIdentity()` resolves once per request and memoizes; `authenticate()` throws when
-anonymous; `check()` returns a boolean. `identity` (getter) is only populated after
-the first async call — prefer `getIdentity()`.
+The guard's user comes from `resolveUser` first (so `lucidMirror` provisions on first
+login; `ctx.auth.user` is the same object as `await ctx.authkit.getUser()`), then from the
+provider. No local user table: `provider: authkitIdentityProvider()` makes `ctx.auth.user`
+the `Identity`. `auth.getUserOrFail()` is synchronous and throws unless
+`middleware.auth()`/`middleware.silentAuth()`/`auth.check()` ran.
 
 Source: `packages/authkit-client/README.md` § Uso por request,
-`src/authenticator.ts` (`Authenticator`).
+`src/host/authkit_client_guard.ts`.
+
+### Pattern 1b — API routes (bearer JWT, DPoP, opaque, PAT)
+
+```ts
+// config/auth.ts
+api: authkitClientGuard({
+  provider: authkitIdentityProvider(),
+  resolver: resolvers.jwt({ tokenSource: 'bearer' }), // Bearer <jwt> or DPoP <jwt> + DPoP proof
+}),
+
+// start/routes.ts
+router.group(() => { /* … */ }).prefix('/api').use(middleware.auth({ guards: ['api'] }))
+```
+
+`resolver` replaces the configured resolver for that guard only; `resolvers.opaque({
+tokenSource: 'bearer' })` and `resolvers.pat({ introspectionUrl, introspectionSecret })`
+work the same way. A DPoP-bound token (`cnf.jkt`) sent as `Bearer` is refused.
 
 ### Pattern 2 — `resolveUser` per database topology
 
@@ -124,11 +170,9 @@ RP-initiated logout and role-based redirects in one call:
 
 ```ts
 import router from '@adonisjs/core/services/router'
-import middleware from '#start/kernel'
 import { registerOidcClient } from '@adonis-agora/authkit-client'
 
 registerOidcClient(router, {
-  loginMiddleware: middleware.guest(),
   redirects: { byGlobalRole: { ADMIN: '/admin' }, default: '/' },
   // prefix defaults to /auth → /auth/login, /auth/callback, /auth/logout
   // backchannelLogout defaults to true → also registers POST /auth/backchannel-logout
@@ -162,16 +206,23 @@ Source: `src/define_config.ts` (`BackchannelLogoutInput`), README.
 
 ## Common mistakes
 
-### HIGH — Session middleware running after `authkit_middleware`
+### HIGH — Session middleware running after `authkit_context_middleware`
 
 ```ts
 // Wrong — resolver reads an empty session; every request looks anonymous
-router.use([middleware.authkit(), middleware.session()])
+router.use([
+  () => import('@adonis-agora/authkit-client/authkit_context_middleware'),
+  () => import('@adonisjs/session/session_middleware'),
+])
 ```
 
 ```ts
-// Correct — @adonisjs/session MUST run BEFORE the authkit middleware
-router.use([middleware.session(), middleware.authkit()])
+// Correct — session, then initialize_auth, then the AuthKit context middleware
+router.use([
+  () => import('@adonisjs/session/session_middleware'),
+  () => import('@adonisjs/auth/initialize_auth_middleware'),
+  () => import('@adonis-agora/authkit-client/authkit_context_middleware'),
+])
 ```
 
 With `resolvers.jwt({ tokenSource: 'session' })` (the default) the resolver reads
@@ -185,20 +236,20 @@ Source: `packages/authkit-client/README.md` § Ordem de middleware (importante).
 
 ```ts
 // Wrong — expecting authkit to resolve app roles/permissions
-if (auth.hasGlobalRole('ADMIN')) { /* app-role check? */ }
+if (authkit.hasGlobalRole('ADMIN')) { /* app-role check? */ }
 const can = await authkit.checkPermission(user, 'posts.edit') // does not exist
 ```
 
 ```ts
 // Correct — AuthKit authenticates + exposes token globalRoles; authz decides access
-if (auth.hasGlobalRole('ADMIN')) { /* global role from the token claims */ }
+if (authkit.hasGlobalRole('ADMIN')) { /* global role from the token claims */ }
 // App roles/permissions: configure resolveRoles in @adonis-agora/authz
-// and enforce with authz/Bouncer route guards, not authkit_middleware.
+// and enforce with authz/Bouncer route guards, not middleware.auth().
 ```
 
 AuthKit only authenticates and knows the `globalRoles` claim; app roles (domain
 tables) and permissions were deliberately moved out to `@adonis-agora/authz`.
-The `authkit_middleware` only enforces login.
+`middleware.auth()` only enforces login.
 
 Source: `packages/authkit-client/README.md` callout ("Autorização por app-role saiu
 do AuthKit"), `stubs/config/authkit_client.stub` comment.
@@ -227,21 +278,25 @@ token's `exp`, and the cache holds at most 10,000 tokens per resolver.
 
 Source: `src/resolvers/factory.ts` (`resolvers.opaque` throw), README.
 
-### MEDIUM — Bearer resolver in a browser session app (or vice versa)
+### MEDIUM — API routes on the session guard
 
 ```ts
-// Wrong — SPA/API app still using the default session source
-resolver: resolvers.jwt() // tokenSource defaults to 'session'
+// Wrong — the web guard reads the OIDC session; a Bearer header is ignored
+router.group(() => { /* … */ }).prefix('/api').use(middleware.auth())
 ```
 
 ```ts
-// Correct — pick the source matching the transport
-resolver: resolvers.jwt({ tokenSource: 'bearer' }) // reads Authorization header
+// Correct — an API guard with its own resolver
+api: authkitClientGuard({
+  provider: authkitIdentityProvider(),
+  resolver: resolvers.jwt({ tokenSource: 'bearer' }),
+}),
+router.group(() => { /* … */ }).prefix('/api').use(middleware.auth({ guards: ['api'] }))
 ```
 
-`tokenSource` decides where the ID token is read from: `'session'` (default, cookie
-apps) vs `'bearer'` (`Authorization` header for SPA/API callers). The mismatched
-source yields a silent `null` identity, not an error.
+`tokenSource` decides where the token is read from: `'session'` (default, cookie
+apps) vs `'bearer'` (`Authorization` header). The mismatched source yields a silent
+`null` identity (a 401 / redirect), not an error.
 
 Source: `packages/authkit-client/README.md` § Resolução de sessão,
 `src/resolvers/factory.ts` (`JwtResolverFactoryConfig`).

package/stubs/config/auth.stub

@@ -0,0 +1,30 @@
+{{{
+  exports({ to: app.configPath('auth.ts') })
+}}}
+import { defineConfig } from '@adonisjs/auth'
+import { sessionUserProvider } from '@adonisjs/auth/session'
+import type { InferAuthenticators } from '@adonisjs/auth/types'
+import { authkitClientGuard } from '@adonis-agora/authkit-client/auth'
+
+/**
+ * ctx.auth is backed by the AuthKit session. The guard takes the user from
+ * resolveUser in config/authkit_client.ts when you set one (e.g. lucidMirror,
+ * which creates the local row on first login), and falls back to this provider
+ * otherwise. The model's primary key must be the IdP's sub.
+ */
+const authConfig = defineConfig({
+  default: 'web',
+  guards: {
+    web: authkitClientGuard({
+      provider: sessionUserProvider({
+        model: () => import('{{ modelImport }}'),
+      }),
+    }),
+  },
+})
+
+export default authConfig
+
+declare module '@adonisjs/auth/types' {
+  export interface Authenticators extends InferAuthenticators<typeof authConfig> {}
+}

package/stubs/config/authkit_client.stub

@@ -10,7 +10,8 @@ const authkitClientConfig = defineConfig({
   clientSecret: env.get('AUTHKIT_CLIENT_SECRET'),
   redirectUri: env.get('AUTHKIT_REDIRECT_URI'),
   resolver: resolvers.jwt({ tokenSource: 'session' }),
-  // resolveUser: async (identity) => User.find(identity.userId),
+  // Creates/updates the local user on each login; ctx.auth.user is this user.
+  // resolveUser: lucidMirror(User, { sync: (identity) => ({ email: identity.email }) }),
   // Roles do app? Configure resolveRoles no @adonis-agora/authz (não aqui — o AuthKit só autentica).
 })
 

package/stubs/middleware/auth_middleware.stub

@@ -0,0 +1,25 @@
+{{{
+  exports({ to: app.middlewarePath('auth_middleware.ts') })
+}}}
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+import type { Authenticators } from '@adonisjs/auth/types'
+
+/**
+ * Denies access to unauthenticated requests and sends them to the AuthKit
+ * login route registered by registerOidcClient(router).
+ */
+export default class AuthMiddleware {
+  redirectTo = '/auth/login'
+
+  async handle(
+    ctx: HttpContext,
+    next: NextFn,
+    options: {
+      guards?: (keyof Authenticators)[]
+    } = {}
+  ) {
+    await ctx.auth.authenticateUsing(options.guards, { loginRoute: this.redirectTo })
+    return next()
+  }
+}

package/stubs/middleware/silent_auth_middleware.stub

@@ -0,0 +1,16 @@
+{{{
+  exports({ to: app.middlewarePath('silent_auth_middleware.ts') })
+}}}
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+
+/**
+ * Checks the AuthKit session without requiring one, so ctx.auth.user is set
+ * on routes that also serve guests.
+ */
+export default class SilentAuthMiddleware {
+  async handle(ctx: HttpContext, next: NextFn) {
+    await ctx.auth.check()
+    return next()
+  }
+}

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

@@ -1,6 +0,0 @@
-import type { HttpContext } from '@adonisjs/core/http';
-import type { Authenticator } from '../authenticator.js';
-/** Read the authenticator the middleware placed on the context. */
-export declare function ctxAuth(ctx: HttpContext): Authenticator;
-/** Place the authenticator on the context. */
-export declare function setCtxAuth(ctx: HttpContext, authenticator: Authenticator): void;

package/build/src/host/ctx_auth.js

@@ -1,8 +0,0 @@
-/** Read the authenticator the middleware placed on the context. */
-export function ctxAuth(ctx) {
-    return ctx.auth;
-}
-/** Place the authenticator on the context. */
-export function setCtxAuth(ctx, authenticator) {
-    ctx.auth = authenticator;
-}