@adonis-agora/authkit-client 0.18.4 → 0.18.5

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/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.5",
   "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.0",
+    "@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('/')
   }
 }