@adonis-agora/authkit-client 0.18.4 → 0.18.6

package/README.md

@@ -12,6 +12,30 @@ O `configure` publica `config/authkit_client.ts`, o controller `app/controllers/
 (login/callback/logout) e registra o provider + o middleware `authkit_middleware`.
 
 ## Rotas de sessão
+
+O caminho **recomendado** é `registerOidcClient(router)`: uma chamada que monta
+`/auth/login`, `/auth/callback`, `/auth/logout` e o back-channel logout
+(`POST /auth/backchannel-logout`), já usando `startSession`/`endSession` e o
+RP-initiated logout. Substitui o boilerplate do controller ejetado.
+```ts
+// start/routes.ts
+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 + '/'
+  backchannelLogout: true,                           // default
+})
+```
+Opções: `prefix`, `afterLogin`, `redirects`, `postLogoutRedirect`, `backchannelLogout`,
+`loginMiddleware` e `passthroughParams`. `AUTHKIT_REDIRECT_URI` deve apontar para a rota de callback.
+
+### Customização (controller ejetado)
+Se precisar de rotas próprias, o `configure` publica `app/controllers/oidc_session_controller.ts`
+(login/callback/logout) para você adaptar:
 ```ts
 // start/routes.ts
 import OidcSessionController from '#controllers/oidc_session_controller'
@@ -19,7 +43,12 @@ router.get('/auth/login', [OidcSessionController, 'login'])
 router.get('/auth/callback', [OidcSessionController, 'callback'])
 router.post('/auth/logout', [OidcSessionController, 'logout'])
 ```
-`AUTHKIT_REDIRECT_URI` deve apontar para a rota de callback.
+> **Ao editar o controller, use o manager — não escreva a sessão cru.** No callback chame
+> `manager.startSession(ctx, tokenSet)` e no logout `manager.endSession(ctx)`; **nunca**
+> `session.put(sessionKey)` / `session.forget(sessionKey)`. A escrita crua não limpa o
+> `impersonationBinding` nem a credencial de impersonação parqueada — o refresh token do ator
+> continua serializado no cookie da próxima identidade, e o logout deixa a credencial viva.
+> `startSession`/`endSession` são os caminhos que mantêm a invariante.
 
 ## Uso por request
 `ctx.auth` é populado pelo `authkit_middleware`:

package/build/src/register_oidc_client.js

@@ -18,6 +18,13 @@ export function registerOidcClient(router, options = {}) {
     const prefix = options.prefix ?? '/auth';
     const passthrough = options.passthroughParams ?? ['audience'];
     const pkceKey = 'authkit_pkce';
+    // Todo redirect desta função vai para uma URL que a PRÓPRIA lib monta (authorize,
+    // /login, destino do app, end-session). O Adonis encaminha a query string da
+    // request atual por padrão (`redirect.forwardQueryString`), então `redirect(dest)`
+    // sem o `false` explícito arrasta o `code`/`state`/`iss` do callback para o
+    // destino — o app terminava em `/?code=…&state=…&iss=…` depois do login, e o
+    // `/auth/login` de um callback falho carregava o code antigo para o authorize
+    // seguinte. Nenhum desses redirects deve encaminhar query: o destino já a tem.
     const loginRoute = router.get(`${prefix}/login`, async (ctx) => {
         const manager = await ctx.containerResolver.make('authkit.client');
         const cfg = manager.clientConfig;
@@ -39,7 +46,7 @@ export function registerOidcClient(router, options = {}) {
             codeChallenge: challenge,
             ...(Object.keys(extraParams).length ? { extraParams } : {}),
         });
-        return ctx.response.redirect(url);
+        return ctx.response.redirect(url, false);
     });
     if (options.loginMiddleware)
         loginRoute.use(options.loginMiddleware);
@@ -53,7 +60,7 @@ export function registerOidcClient(router, options = {}) {
         // Callback velho/expirado (state perdido ou code ausente) → recomeça o login.
         if (!pkce || pkce.state !== state || !code) {
             ctx.session?.forget(pkceKey);
-            return ctx.response.redirect(`${prefix}/login`);
+            return ctx.response.redirect(`${prefix}/login`, false);
         }
         const tokenSet = await exchangeCode({
             issuer: cfg.issuer,
@@ -72,10 +79,10 @@ export function registerOidcClient(router, options = {}) {
         // 1) Hook do app tem prioridade quando retorna uma rota.
         const hook = await options.afterLogin?.(ctx, identity);
         if (typeof hook === 'string')
-            return ctx.response.redirect(hook);
+            return ctx.response.redirect(hook, false);
         // 2) Redirect por role global (do token).
         const dest = resolveDestination(identity, options.redirects);
-        return ctx.response.redirect(dest);
+        return ctx.response.redirect(dest, false);
     })
         .as('auth.callback');
     router
@@ -95,7 +102,7 @@ export function registerOidcClient(router, options = {}) {
             postLogoutRedirectUri,
             clientId: cfg.clientId,
         });
-        return ctx.response.redirect(endSessionUrl);
+        return ctx.response.redirect(endSessionUrl, false);
     })
         .as('auth.logout');
     if (options.backchannelLogout !== false) {

package/build/stubs/controllers/oidc_session_controller.stub

@@ -29,14 +29,14 @@ export default class OidcSessionController {
       issuer: cfg.issuer, clientId: cfg.clientId, clientSecret: cfg.clientSecret,
       redirectUri: cfg.redirectUri, code, codeVerifier: pkce.verifier,
     })
-    ctx.session.put(cfg.sessionKey, tokenSet)
+    manager.startSession(ctx, tokenSet)
     ctx.session.forget('authkit_pkce')
     return ctx.response.redirect('/')
   }
 
   async logout(ctx: HttpContext) {
     const manager = await ctx.containerResolver.make('authkit.client')
-    ctx.session.forget(manager.clientConfig.sessionKey)
+    manager.endSession(ctx)
     return ctx.response.redirect('/')
   }
 }

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "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",
-  "homepage": "https://github.com/DavideCarvalho/adonis-agora-authkit/tree/main/packages/authkit-client#readme",
   "repository": {
     "type": "git",
     "url": "https://github.com/DavideCarvalho/adonis-agora-authkit.git",
     "directory": "packages/authkit-client"
   },
+  "homepage": "https://davidecarvalho.github.io/agora/docs/authkit",
   "bugs": {
     "url": "https://github.com/DavideCarvalho/adonis-agora-authkit/issues"
   },
@@ -62,10 +62,10 @@
   },
   "peerDependencies": {
     "@adonis-agora/resilience": ">=0.1.0 <1.0.0",
-    "@adonisjs/auth": "^10.1.0",
-    "@adonisjs/core": "^7.5.0",
-    "@adonisjs/lucid": "^22.4.2",
-    "@adonisjs/session": "^8.1.0"
+    "@adonisjs/auth": "10.1.0",
+    "@adonisjs/core": "7.5.0",
+    "@adonisjs/lucid": "22.4.2",
+    "@adonisjs/session": "8.1.0"
   },
   "peerDependenciesMeta": {
     "@adonisjs/auth": {
@@ -83,8 +83,8 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "0.66.0",
-    "@adonis-agora/resilience": "0.3.6",
+    "@adonis-agora/authkit-server": "0.68.2",
+    "@adonis-agora/resilience": "0.3.7",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.5.0",
     "@adonisjs/lucid": "22.4.2",
@@ -93,8 +93,8 @@
     "@japa/assert": "4.2.0",
     "@japa/runner": "5.3.0",
     "@poppinss/ts-exec": "1.4.4",
-    "@tanstack/intent": "^0.4.0",
-    "@types/node": "26.5.0",
+    "@tanstack/intent": "0.4.0",
+    "@types/node": "26.5.1",
     "ioredis-mock": "8.13.1",
     "tempura": "0.4.1",
     "typescript": "7.0.2"

package/stubs/controllers/oidc_session_controller.stub

@@ -29,14 +29,14 @@ export default class OidcSessionController {
       issuer: cfg.issuer, clientId: cfg.clientId, clientSecret: cfg.clientSecret,
       redirectUri: cfg.redirectUri, code, codeVerifier: pkce.verifier,
     })
-    ctx.session.put(cfg.sessionKey, tokenSet)
+    manager.startSession(ctx, tokenSet)
     ctx.session.forget('authkit_pkce')
     return ctx.response.redirect('/')
   }
 
   async logout(ctx: HttpContext) {
     const manager = await ctx.containerResolver.make('authkit.client')
-    ctx.session.forget(manager.clientConfig.sessionKey)
+    manager.endSession(ctx)
     return ctx.response.redirect('/')
   }
 }