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

package/CHANGELOG.md

@@ -0,0 +1,957 @@
+# @adonis-agora/authkit-client
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- [#436](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/436) [`c942fe3`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/c942fe30483346217c9c89112e13db0d4a65c647) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - AuthKit 1.0. See the [Migrating to 1.0](https://github.com/DavideCarvalho/adonis-agora-authkit/blob/main/apps/docs/content/docs/migrating-to-1-0.mdx) guide.
+  
+  Breaking changes (`@adonis-agora/authkit-server`):
+  
+  - `withMfa` is removed. MFA state lives in the lib-owned `auth_mfa` table, so drop the mixin from your `AuthUser` model's `compose(...)`.
+  - `markSudo` is no longer exported. Grant sudo with `completeSudo(sudoContextFrom(ctx), methodId)`, which also writes the `sudo.confirmed` audit event, remembers the method and redirects to the validated `return_to`.
+  - The email-change confirmation link is sent through `mail.onEmailChangeConfirm` only. Without it, AuthKit sends its built-in email; `onEmailVerification` no longer receives email-change confirmations.
+  - The `clients` option of `defineConfig` is removed. Create clients in the admin console, through the Admin API or with `node ace authkit:clients:create` (new `--client-secret` flag keeps an existing secret). `buildImpersonationPanel(cfg, targetId, clients)` now requires `clients`, and the impersonation curl always shows the `<CLIENT_SECRET>` placeholder.
+  - `inertiaRenderer({ prefix, views })`: `views` is required. Screens not listed render with the built-in Edge view. `AuthkitScreen` is now the exact union of the screens AuthKit renders (adds `throttled`, `agents/consent`, `agents/done`; no arbitrary strings), and every screen's props are exported: `AuthkitScreenProps['<view>']` plus named types (`LoginProps`, `SessionExpiredProps`, …). The controllers are checked against them. Hosts declare screens of their own by augmenting `AuthkitScreenProps` (`declare module '@adonis-agora/authkit-server'`).
+  - The Admin API client body reads `grantTypes` only; the `grants` alias is gone (responses still return `grants`).
+  - `lucidAccountStore` always mounts password history over the model's connection (`auth_password_history`).
+  - `/account/orgs/json`, `/account/orgs/invitations/json` and `/account/orgs/:id/json` are removed; use `/account/api/orgs/*`.
+  - `GET /account/api/apps` entries gain `name` and `logoUrl`.
+  
+  - The admin console reads its config from a `<script type="application/json" id="authkit-admin-config">` data block (CSP-safe) instead of an inline `window.__AUTHKIT__` script; the dev fallback is gone.
+  - The admin client DTO returns `grantTypes` (was `grants`), plus `clientName` and `logoUri`, which the console and the Admin API can now set (`null` removes them, as it does `backchannelLogoutUri`). `GET {admin}/api/clients/:id` exists.
+  - Anonymous JSON callers of the admin and account JSON APIs get `401` (and `403` without an admin role) instead of a redirect to the login page.
+  - Fixes: the Redis adapter's `list()` honours the connection `keyPrefix` (sessions, apps and admin lists were empty); a password login posted without a password is an invalid-credentials answer, not a 500.
+  
+  Breaking changes (`@adonis-agora/authkit-core`):
+  
+  - `ClientConfig` and `ResolvedAuthServerConfig.clients` are removed.
+  
+  Breaking changes (`@adonis-agora/authkit-client`):
+  
+  - `@adonisjs/auth` is a required peer. `ctx.auth` is `@adonisjs/auth`, backed by the AuthKit session through `authkitClientGuard`; `ctx.authkit` (from `authkit_context_middleware`) carries the AuthKit-only data (identity, `hasGlobalRole`, active org, `toSharedProps`).
+  - `authkit_middleware`, `auth_middleware` and `silent_auth_middleware` (and their subpaths) are removed: `ctx.auth` comes from `@adonisjs/auth`, and `middleware.auth()` / `silentAuth` are the `#middleware/auth_middleware` / `#middleware/silent_auth_middleware` files `node ace configure` publishes. `require_org_middleware` stays. `@adonis-agora/authkit-client/types` no longer declares `HttpContext.auth`; type `ctx.authkit.getUser()` through the `AuthkitUserType` interface.
+  - `node ace configure @adonis-agora/authkit-client` installs `@adonisjs/auth` when missing (`--no-install` prints the command), writes `config/auth.ts` with `authkitClientGuard` + `sessionUserProvider` (`--model`, default `#models/user`; an existing file is left alone and the guard to add is printed), registers `@adonisjs/auth/auth_provider`, `initialize_auth_middleware` + `authkit_context_middleware`, and publishes the named `auth` / `silentAuth` middleware.
+  - `authkitClientGuard` takes its user from `resolveUser` when one is configured (so `lucidMirror` provisions the row on first login, and what it loads is on `ctx.auth.user`, the same instance as `ctx.authkit.getUser()`), with the provider as the fallback.
+  - New `authkitIdentityProvider()`: a user provider with no database; `ctx.auth.user` is the AuthKit `Identity`.
+  - New `authkitClientGuard({ provider, resolver })` option: a per-guard resolver for API routes (bearer JWT, opaque, PAT).
+  - `resolvers.jwt({ tokenSource: 'bearer' })` accepts `Authorization: DPoP <jwt>` with a valid `DPoP` proof for `cnf.jkt`-bound tokens, and refuses DPoP-bound tokens sent as `Bearer`.
+  - `UnauthorizedAccessConstructor` is no longer exported, and `AuthkitClientGuard` no longer takes an exception class; it always throws `@adonisjs/auth`'s `E_UNAUTHORIZED_ACCESS`.
+  
+  Breaking changes (`@adonis-agora/authkit-sdk`):
+  
+  - `clients.*` return `grantTypes` (was `grants`), plus `clientName` and `logoUri`.
+  
+  Breaking changes (`@adonis-agora/authkit-react`):
+  
+  - `createAuthkitClient()` no longer reads `window.__AUTHKIT__`: pass `baseUrl` for `client.admin.*` and `csrfToken`.
+  - Admin response types match the server: `users.remove` / `clients.remove` → `{ ok, deleted }`, `users.resetPassword` → `{ ok, email }`, `users.disable` / `enable` → the user, `SettingListResult.locked`; `AdminClient.grants` → `grantTypes` (+ `clientName`, `logoUri`); `UpdateUserInput` is `{ globalRoles? }`, `CreateUserInput` takes no `null`.
+  - New: `client.account.agents.list()` / `revoke()`, `useAccountAgentsQueryOptions`, `useRevokeAccountAgentMutationOptions`.
+  - Peers: `react` / `react-dom` `^19.0.0`, `@inertiajs/react` `^2.0.0 || ^3.0.0`.
+  
+  - `useProfile`, `useSessions`, `useAuthorizedApps`, `useOrganizations`, `useOrganization`, `useOrgInvitations`, `useSwitchOrganization` and their types are removed, with the `profile`, `sessions`, `apps`, `orgs` and `orgInvitations` keys of `endpoints`. Use the query options (`useMeQueryOptions`, `useAccountSessionsQueryOptions`, `useAppsQueryOptions`, `useAccountOrgsQueryOptions`, …).
+  - `UserProfile`, `AuthorizedApps`, `OrganizationSwitcher` and `OrganizationProfile` need `QueryClientProvider` and `AuthkitClientProvider`.
+  
+  All packages:
+  
+  - `@adonis-agora/*` peer ranges accept 1.x and its release candidates (`<2.0.0 || >=1.0.0-rc.0 <2.0.0`): `durable`, `media`, `telescope` (authkit-server), `resilience` (authkit-client), `authkit-server` (authkit-sdk).
+  - Node.js `>=24` is required (tested on 24 and 26).
+
+### Patch Changes
+
+- Updated dependencies [[`c942fe3`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/c942fe30483346217c9c89112e13db0d4a65c647)]:
+  - @adonis-agora/authkit-core@1.0.0-rc.0
+
+## 0.20.5
+
+### Patch Changes
+
+- fix(deps): update dependency jose to v6.2.15 ([#405](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/405))
+
+## 0.20.4
+
+### Patch Changes
+
+- fix(deps): update dependency jose to v6.2.14 ([#388](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/388))
+
+## 0.20.3
+
+### Patch Changes
+
+- [#361](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/361) [`1b9c90c`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/1b9c90ced4356d2c754e850e307954455ddeeb3a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Performance: `lucidRevocationStore` imports the Lucid `db` service module once per process instead of running a dynamic `import()` on every `isRevoked` call (every authenticated request when back-channel logout is on). It still reads the service's live binding on each call, and a failed import is retried.
+- Updated dependencies [[`1b9c90c`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/1b9c90ced4356d2c754e850e307954455ddeeb3a)]:
+  - @adonis-agora/authkit-core@0.10.1
+
+## 0.20.2
+
+### Patch Changes
+
+- [#349](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/349) [`5512d90`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/5512d907f1a1960f7387651616c2a12d25abfa14) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `discoverEndpoints` shares one in-flight fetch per issuer, keeps serving an expired document while a single background refetch replaces it, and aborts the request after 10 s. The `OpaqueResolver` cache (with `cacheTtlMs`) now expires an entry at the token's `exp` when that comes first, and is capped at 10,000 tokens. `lucidMirror` returns an up-to-date row from a plain `findBy` instead of a locking `updateOrCreate` transaction on every request.
+
+## 0.20.1
+
+### Patch Changes
+
+- fix(deps): update dependency jose to v6.2.13 ([#323](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/323))
+
+## 0.20.0
+
+### Minor Changes
+
+- [#269](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/269) [`b0ca480`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/b0ca4802419aba93a9f913775f697cc4075cff88) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Drop Node 20, which reached end-of-life on 2026-04-30, and Node 22, which AdonisJS 7 does not support (it requires Node >=24): `engines.node` is now `>=24`. The supported Node lines are 24 and 26, and CI runs the test suite on each of them.
+
+### Patch Changes
+
+- Updated dependencies [[`b0ca480`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/b0ca4802419aba93a9f913775f697cc4075cff88)]:
+  - @adonis-agora/authkit-core@0.10.0
+
+## 0.19.2
+
+### Patch Changes
+
+- [#265](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/265) [`e94c12f`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/e94c12f708562392af9a0b0d593f554702d382c0) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `AuthkitClientManager.completeAuthorization` checks that a callback belongs to the pending authorization (`missing_pending`, `state_mismatch`) before it discovers the IdP. A stale or forged callback that arrived while discovery was failing surfaced as an `OidcDiscoveryError` (a 500 in `registerOidcClient`) instead of a restartable `OidcCallbackError` that sends the user back to login.
+
+- [#266](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/266) [`660ce2d`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/660ce2d13a94fb971d2e14a2bfa94eeb04b90a36) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `bindValue('authkit.client', fake)` replaces the manager again. Since 0.19 the manager is bound by class and the string key was an `alias`, and the container follows an alias before it checks bound values: a fake bound under the string key was silently ignored, and the real manager came back. This is how apps replaced it in tests before 0.19, and the changelog promised the key was kept. The key is now a binding that resolves the class: the same singleton, overridable under either name, and a `swap` of the class reaches it even after its first use.
+
+## 0.19.1
+
+### Patch Changes
+
+- [#260](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/260) [`f374913`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/f37491386d6b7a5ce6874b8b3cd5740eceb05872) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `node ace configure @adonis-agora/authkit-client` works again: a backtick in a comment of the `oidc_session_controller` stub broke the stub template engine. The stub compile test never failed because `assert.doesNotThrow(fn, message)` treats the string as an error-message matcher; it now collects compile errors explicitly, and a new test runs the real `configure` hook against a scratch app. `configure` also points to `registerOidcClient(router)` as the way to register the session routes, and the getting-started guide and the agent skill teach it first, keeping the ejected controller for apps that customise the flow ([#202](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/202)).
+
+## 0.19.0
+
+### Minor Changes
+
+- [#256](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/256) [`95ba5fa`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/95ba5fa80c5269940f8a9e227d792bcd896c3ce2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Third-party IdPs (Keycloak, Auth0, Okta, Entra) now work with the integrated client, and the id_token is validated ([#237](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/237)).
+  
+  - **Discovery by default.** `defineConfig` gains `discovery` (default `true`) and `endpoints` (per-field overrides). The endpoints published at `{issuer}/.well-known/openid-configuration` are used everywhere: `registerOidcClient` login/callback/logout, `maybeRefresh`, impersonation, back-channel logout and the default `jwksUri` / introspection URL of `resolvers.jwt()` / `resolvers.opaque()`. Discovery is lazy (the app boots while the IdP is down), a failure throws `OidcDiscoveryError` and is retried on the next request, and a document discovered earlier keeps being served while refetches fail. The document's `issuer` must match the configured one; its exact value is used for `iss` checks, which fixes trailing-slash issuers (Auth0). `discovery: false` restores the previous behaviour (authkit-server route layout + `endpoints`), e.g. for tests that run against a fake issuer.
+  - **id_token validation.** New `validateIdToken` (signature, `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, `max_age`, `sub`). The callback now sends and checks a `nonce` and validates the id_token; a refreshed id_token must be valid and about the same user, otherwise the refresh is discarded.
+  - **New flow helpers.** `createAuthorizationRequest` / `completeAuthorization` (also as `AuthkitClientManager` methods, together with `endpoints()` and `validateIdToken()`) wrap state, nonce, PKCE, the RFC 9207 `iss` check and id_token validation; failures throw `OidcCallbackError` with a `code` and `restartable`.
+  - **Container binding by class.** `AuthkitClientManager` is bound by class (with `authkit.client` kept as an alias), so it can be used with `@inject()`. The scaffolded `OidcSessionController` uses it.
+  - **No more silent failures.** A failing refresh is logged as a warning; `/auth/logout` goes straight to the post-logout destination when the IdP publishes no `end_session_endpoint`.
+  - Token endpoint failures now carry the IdP's `error` / `error_description` (`Token endpoint returned 400: not_allowed (…)`) instead of a bare status.
+  - `discoverEndpoints` gains `onError: 'fallback' | 'throw'`. With the default `'fallback'`, the convention fallback is no longer cached, and a document without a matching `issuer` is treated as unusable.
+  - `OidcEndpoints.issuer` is now always present: the document's exact issuer when discovered, the configured one otherwise (`conventionEndpoints(issuer)` fills it in). Code that builds an `OidcEndpoints` literal by hand must add it.
+  - The context passed to `ResolverFactory.resolver()` now always carries `endpoints` (the resolved IdP endpoints, called per request) and `logger`; the built-in resolvers read the endpoints on every request, so a rotated `jwks_uri` takes effect without a restart. Code that calls `factory.resolver({ ... })` by hand, typically in tests, must pass both — e.g. `endpoints: async () => conventionEndpoints(issuer), logger: { warn: () => {} }`.
+  - Back-channel logout reuses the cached remote JWKS instead of fetching the IdP keys on every `logout_token`.
+
+### Patch Changes
+
+- [#255](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/255) [`481051c`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/481051c86c67b2bf5026f7a49028d260236667c9) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Publish peer dependencies as ranges again (`^7.5.0` instead of `7.5.0`, etc.). A Renovate pinning pass had turned the peer catalogs into exact versions, so any upstream patch release (e.g. `@adonisjs/core` 7.5.1) fell outside the accepted peer range.
+
+## 0.18.9
+
+### Patch Changes
+
+- [#253](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/253) [`d6fc1b8`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/d6fc1b8c34037022f22c0a21e0a0866e7d716fa3) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `maybeRefresh`: concurrent requests of the same session no longer get a 401 when the access token
+  expires. The refresh is still deduplicated per session id, but requests that wait for the in-flight
+  refresh now also write the renewed TokenSet (new access token and rotated refresh token) into their
+  own session — before, only the request that started the refresh got it, and the others kept the
+  expired access token and the already-rotated refresh token. The in-flight entry is now always
+  cleared, even when the refresh fails.
+
+## 0.18.8
+
+### Patch Changes
+
+- Updated dependencies [[`94644e6`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/94644e6b1d8d10e0fd3c4b57706cce46b70412cb)]:
+  - @adonis-agora/authkit-core@0.9.0
+
+## 0.18.7
+
+### Patch Changes
+
+- [#215](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/215) [`db4f3db`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/db4f3db082b47cd628d22826bfa5d9db91dd57c6) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - fix(authkit-client): opt-out do encaminhamento de query precisa ser `withQs(false)`
+  
+  A correção anterior (0.18.6) passou `false` como segundo argumento de
+  `ctx.response.redirect(destino, false)`. **Isso não desliga o encaminhamento**
+  quando o app declara `redirect.forwardQueryString: true` no `config/app.ts`, que
+  é o caso comum: nessa situação o positional é ignorado e o `Redirect` herda a
+  configuração global, continuando a encaminhar. O sintoma seguia igual — o
+  callback mandava `code`/`state`/`iss` para o destino e o app terminava em
+  `/?code=…` depois do login.
+  
+  O opt-out por redirect é o builder: `ctx.response.redirect().withQs(false).toPath(destino)`.
+  Os cinco redirects do `registerOidcClient` (login, `/auth/login` de recuperação,
+  destino pós-login, hook `afterLogin` e `end-session` do logout) passam a usá-lo.
+  
+  O teste passava antes porque o `response` falso honrava o argumento posicional —
+  ou seja, testava uma premissa que o framework não cumpre. Ele agora modela o
+  comportamento real (config ligada ⇒ positional ignorado; só `withQs(false)`
+  desliga), então falha com a forma antiga e passa com a correta.
+
+## 0.18.6
+
+### Patch Changes
+
+- [#213](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/213) [`7e6b8ef`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/7e6b8ef81df0c2bb498d6b4728baa0f9abc4d0bb) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - fix(authkit-client): redirect de login/callback encaminhava a query string da request
+  
+  O AdonisJS encaminha a query string da request atual no `redirect` por padrão
+  (`redirect.forwardQueryString`). O `registerOidcClient` chamava
+  `ctx.response.redirect(destino)` sem o segundo argumento, e **todos** os seus
+  destinos são URLs que a própria lib monta — então a query da request não tinha
+  por que ir junto. Duas consequências visíveis:
+  
+  - **Pós-login:** o callback redireciona para o destino do app, mas arrastava
+    `code`/`state`/`iss` consigo. Quem entrava caía em `/?code=…&state=…&iss=…`
+    em vez de `/` — parecia que o botão "Entrar" não fazia nada.
+  - **Callback falho:** o redirect para `/auth/login` levava o `code`/`state`
+    antigos, que então eram encaminhados de novo para o authorize seguinte —
+    lixo de uma tentativa anterior viajando pelo fluxo.
+  
+  Os cinco redirects (`login`, `/auth/login` de recuperação, destino pós-login,
+  hook `afterLogin` e `end-session` do logout) agora passam `forwardQueryString:
+  false`. O destino já carrega a query que precisa; nada da request atual deve ser
+  somado a ela.
+
+## 0.18.5
+
+### Patch Changes
+
+- [#207](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/207) [`9682830`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/96828307192ad4de7478c84b1e0cae3eefe18d0b) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - O controller ejetado (`stubs/controllers/oidc_session_controller.stub`) escrevia a sessão crua: `ctx.session.put(cfg.sessionKey, tokenSet)` no callback e `ctx.session.forget(sessionKey)` no logout. Isso não limpa o `impersonationBinding` nem a credencial de impersonação parqueada — o refresh token do ator continuava serializado no cookie da próxima identidade, e o logout deixava a credencial viva. O stub agora usa o manager: `manager.startSession(ctx, tokenSet)` no callback e `manager.endSession(ctx)` no logout, mantendo PKCE/state e a troca de code. O README passa a recomendar `registerOidcClient(router)` e documenta o controller apenas como caminho de customização, deixando explícito o requisito de `startSession`/`endSession`. Teste de regressão assere que o stub chama o manager e não contém a escrita crua.
+
+## 0.18.4
+
+### Patch Changes
+
+- bc32ea4: Bump runtime dependencies to their latest releases.
+  
+  - `@simplewebauthn/server` and `@simplewebauthn/browser` go to `14.x`. The committed
+    `src/host/assets/webauthn.js` bundle was regenerated from the new `@simplewebauthn/browser`
+    (the `check:webauthn-bundle` guard would have caught the drift otherwise). The `authkit-react`
+    peer was **widened** to `^13.3.0 || ^14.0.0` instead of moved, so apps still on 13 keep
+    installing cleanly.
+  - `oidc-provider` 9.12.0 → 9.12.2 and `jose` 6.2.10 → 6.2.12 (patch releases on the token/JWT path).
+  
+  No API change on our side: typecheck, tests, packaging smoke and the WebAuthn bundle check all pass.
+
+## 0.18.3
+
+### Patch Changes
+
+- dcb3408: `node ace configure @adonis-agora/authkit-client` sempre crashava com `SyntaxError: Unexpected identifier 'resolveRoles'`. O stub publicado (`config/authkit_client.stub`) tinha um comentário com o nome `resolveRoles` entre crases (markdown-style), e o codemod de stubs (`tempura`) compila o conteúdo bruto do stub envolvendo-o numa template literal JS — a crase não-escapada fechava essa literal cedo. Removidas as crases do comentário (não havia motivo funcional para elas ali). Adicionado um teste que compila TODO `.stub` publicado do pacote via `tempura`, para pegar essa classe de regressão automaticamente em vez de só checar a existência do arquivo.
+
+## 0.18.2
+
+### Patch Changes
+
+- 76b1314: fix(maybeRefresh): deduplicate concurrent refresh token requests per session
+
+  When multiple requests arrive simultaneously and the access token is within
+  the REFRESH_SKEW_MS window, every request would independently fire a
+  refresh token grant to the IdP. Since refresh tokens rotate, only the first
+  succeeds — the remaining N-1 requests fail with an already-invalidated
+  refresh token, creating unnecessary load and log noise.
+
+  This commit introduces an in-memory dedup map keyed by `sessionId`:
+  concurrent requests to the same session share a single in-flight refresh
+  promise. Sessions without a `sessionId` (e.g. some test contexts) fall
+  back to the original behavior.
+
+## 0.18.1
+
+### Patch Changes
+
+- a6d271c: Ship TanStack Intent AI-agent skills with each package (`skills/` added to `files`), add the `tanstack-intent` keyword, and take a devDependency on `@tanstack/intent` for skill validation.
+
+## 0.18.0
+
+### Minor Changes
+
+- 813a321: Multi-tenancy: `orgId` de primeira classe no evento, `orgId`/`orgSlug`/`orgRole` na `Identity`, e o middleware `requireOrg`
+
+  Três buracos no caminho de multi-tenancy por organização, achados ao seguir o
+  fluxo inteiro (org criada → claim → contexto → RBAC escopado):
+
+  **1. O barramento de diagnostics não dizia QUAL org.** `redactAuditEventForDiagnostics`
+  dropa `metadata` inteiro por LGPD (é campo livre e carrega PII — o e-mail do
+  convidado, por exemplo). Só que o `orgId` dos eventos de organização vivia
+  justamente ali. Resultado: um assinante de `agora:authkit:organization.created`
+  — o provisioning do `@adonis-agora/authz`, entre outros — recebia o tipo do
+  evento e nada mais, o que torna o hook inútil na prática. Além disso o
+  `organization.created` self-service auditava só `{ slug }`, sem id nenhum.
+
+  `orgId` agora é campo de primeira classe do `AuditEvent`, preenchido nos 15
+  call-sites de eventos de organização (`organization.deactivated` não tem org, é
+  a limpeza), preservado na projeção de diagnostics junto dos demais ids opacos
+  (`accountId`/`actorId`/`clientId`) e incluído no corpo do webhook. A redação de
+  PII continua intacta: `email`, `ip` e `metadata` seguem fora do barramento.
+
+  **2. A `Identity` não expunha a org.** O tenant ativo só existia em
+  `identity.raw.org_id`, sem tipo, e cada app reescrevia a derivação. Agora
+  `identity.orgId`, `identity.orgSlug` e `identity.orgRole` são campos da
+  `Identity`, preenchidos por `buildIdentityFromClaims` (portanto nos três
+  resolvers: jwt, pat e opaque). A tabela de claims aceitas — que já existia
+  duplicada dentro da ponte de contexto — virou `ORG_ID_CLAIMS` +
+  `deriveOrgId`/`deriveOrgSlug`/`deriveOrgRole` no `authkit-core`, e a ponte
+  passou a consumi-la. Os aliases de IdPs de terceiros (`tid`,
+  `organization_id`, `tenant_id`, `active_organization_id`) continuam valendo,
+  agora num lugar só.
+
+  **3. Não havia como exigir org ativa.** `RequireOrgMiddleware`
+  (`@adonis-agora/authkit-client/require_org_middleware`) barra request
+  autenticada mas sem tenant. Isso importa porque "logado" e "dentro de um
+  tenant" são coisas distintas: sem a barreira, a request chega no controller com
+  tenant indefinido e a checagem escopada do authz cai no escopo GLOBAL — o pior
+  lugar para se cair por acidente. Fail-closed, com `mode: 'api'` (403
+  `no_active_organization` em vez de redirect) e `oneOf` para restringir a um
+  conjunto conhecido de orgs.
+
+### Patch Changes
+
+- Updated dependencies [813a321]
+  - @adonis-agora/authkit-core@0.8.0
+
+## 0.17.4
+
+### Patch Changes
+
+- b97f28e: Importing the middleware no longer forces `HttpContext.auth` on your app.
+
+  **If you pinned to 0.17.1 to get your typecheck passing, this releases you.**
+
+  0.17.2 added `import '../../types.js'` to the middleware's emitted declarations so
+  that `ctx.auth` would be typed for apps that had no declaration of their own. But
+  that same file also carries the library's _unparameterised_
+  `auth: Authenticator`, and `start/kernel.ts` imports the middleware — so the
+  declaration entered every consumer's type program.
+
+  `HttpContext.auth` declared twice with different types does not merge.
+  TypeScript keeps whichever declaration it reached first and reports the conflict
+  on the other; that conflict lands inside a `.d.ts`, where `skipLibCheck` — on in
+  every AdonisJS app — discards it. The library's file is reached first through the
+  kernel, so an app's own `auth: Authenticator<AppUser>` lost and `getUser()`
+  collapsed to `unknown` **across the entire codebase**. One app went from 24 type
+  errors to 351, another from 0 to 105, with nothing pointing at the cause.
+
+  The two augmentations are now separate modules:
+
+  - `container_bindings.ts` declares only `ContainerBindings['authkit.client']`, a
+    key nothing else can claim. The provider and the middleware import this, so
+    `containerResolver.make('authkit.client')` stays typed.
+  - `types.ts` declares only `HttpContext.auth`, and **nothing in the package
+    imports it**. Apps that want the library's default typing opt in with
+    `import '@adonis-agora/authkit-client/types'`; apps that declare their own
+    parameterised version are left alone.
+
+  The library's middleware reads and writes `ctx.auth` through a local cast rather
+  than a global declaration, so the knowledge stays inside the package.
+
+  Nothing changes at runtime, and no app-level change is required: if you already
+  declare `auth: Authenticator<AppUser>`, it now simply wins, because it is the
+  only declaration in the program.
+
+  A spec walks the emitted declaration graph and fails if any consumer entrypoint
+  reaches the `HttpContext.auth` augmentation again — the monorepo's own typecheck
+  compiles every file in one program and structurally cannot catch this.
+
+  `@adonis-agora/authkit-server` was checked for the same defect and does not have
+  it: it ships no `HttpContext.auth`, and its four container bindings still reach
+  hosts through both the provider and the `./types` subpath. It gets the same guard
+  anyway, because the thing protecting it is easy to break by accident —
+  `src/host/augmentations.ts` loads the framework's own augmentations with
+  `import type {} from '…'`, a form tsc erases from the emitted declarations, and
+  rewriting any one of them as a bare `import '…'` would inherit
+  `@adonisjs/auth`'s `HttpContext.auth` and reproduce this bug package-wide. Both
+  guards now also reject a bare side-effect import of any external module from a
+  shipped declaration file.
+
+## 0.17.3
+
+### Patch Changes
+
+- f287ade: Widen the `@adonis-agora/*` peer ranges so they survive the peer's next minor.
+
+  Below 1.0.0 a caret does not mean "this minor and up" — it stops at the next
+  minor, so `^0.22.0` expands to `>=0.22.0 <0.23.0`. Every sibling package in this
+  ecosystem ships minors constantly, which meant **all four** `@adonis-agora/*`
+  peers were unsatisfiable against the current release of the package they name.
+  Under npm this is not a warning: installing `@adonis-agora/authkit-server`
+  alongside `@adonis-agora/durable@0.24.0` failed outright with
+  `ERESOLVE — Conflicting peer dependency: @adonis-agora/durable@0.22.0`.
+
+  Each floor was chosen from what the code actually calls, not from what the range
+  happened to say:
+
+  | peer                       | was       | now              | why that floor                                                                                                           |
+  | -------------------------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+  | `@adonis-agora/durable`    | `^0.22.0` | `>=0.7.0 <1.0.0` | first release with `ctx.localStep`, absent in 0.6.1                                                                      |
+  | `@adonis-agora/media`      | `^0.1.0`  | `>=0.5.0 <1.0.0` | first release exporting the `./single-file` subpath the avatar uploader imports, absent in 0.4.0                         |
+  | `@adonis-agora/telescope`  | `^0.1.0`  | `>=0.1.0 <1.0.0` | all five imported types are shape-identical from 0.1.0 through 0.8.1                                                     |
+  | `@adonis-agora/resilience` | `^0.1.0`  | `>=0.1.0 <1.0.0` | `wrap()` has existed since 0.1.0, and the policy is duck-typed against a locally declared interface rather than imported |
+
+  The `^0.22.0` on durable in particular came from the `ctx.step` → `ctx.localStep`
+  migration and recorded the version current on that day, some fifteen minors above
+  what the migration actually required.
+
+  `@adonis-agora/authkit-sdk`'s peer on `@adonis-agora/authkit-server` gains the
+  same upper bound (`>=0.10.0 <1.0.0`), which it was missing entirely — it would
+  have accepted a future 1.0 with breaking changes.
+
+  A spec now scans every package manifest and fails on a caret or tilde over a 0.x
+  `@adonis-agora/*` peer, so this cannot come back quietly.
+
+## 0.17.2
+
+### Patch Changes
+
+- 8f23a85: Ship the module augmentations so they actually reach a consuming app.
+
+  **The client.** `HttpContext.auth` was declared in the package's root `types.ts`,
+  and nothing reachable from `build/index.d.ts` referenced that file — so TypeScript
+  never loaded it in a host app and `ctx.auth` came back as `Property 'auth' does
+not exist on type 'HttpContext'`, no matter what the app imported. Verified
+  against packed tarballs in a scratch AdonisJS app across five wiring variants; a
+  `/// <reference path>` straight at the built `types.d.ts` type-checked cleanly,
+  which isolates it to reachability rather than to the declarations. The
+  augmentation is now pulled in by a bare side-effect import from
+  `authkit_middleware` — the middleware that actually assigns `ctx.auth`, and the
+  one `configure` registers.
+
+  Putting that import in `index.ts` was considered and rejected: apps that hand
+  `ctx.auth` to `@adonisjs/auth` through `authkitClientGuard` would then load two
+  competing `HttpContext.auth` declarations, and because `skipLibCheck` is on in
+  every AdonisJS app the conflict is not reported — one simply wins by include
+  order. Anchoring on the middleware keeps the two owners of `ctx.auth` mutually
+  exclusive, the same way `@adonisjs/auth` does with its own
+  `initialize_auth_middleware`.
+
+  **The server** was a smaller problem than it first looked. Hosts _were_ getting
+  `app.container.make('authkit.server')` typed all along, because the service
+  provider carried its own copy of the `ContainerBindings` declaration and every
+  host registers the provider. What was broken is that `exports["./types"]` pointed
+  at the barrel rather than at the built `types.js`, so importing
+  `@adonis-agora/authkit-server/types` gave `Property 'authkit.server' does not
+exist on type 'ContainerBindings'`.
+
+  Retargeting that subpath exposed a second problem: the root `types.ts` declared
+  one binding while the provider declared four, so the newly-live subpath was a
+  partial view. Two binding tables with nothing checking they agree is how they
+  drifted in the first place, so there is one table now — in `types.ts`, with the
+  provider reaching it through a side-effect import.
+
+  **`adonisjs.types` covers neither package.** No version of `@adonisjs/core`,
+  `@adonisjs/assembler` or `@adonisjs/application` in this repo's dependency tree
+  reads that package.json field. It is an AdonisJS 5 leftover, left alone.
+
+## 0.17.1
+
+### Patch Changes
+
+- 1f15367: Point `homepage` and `bugs.url` at the repository's current name.
+
+  The repository was renamed to `adonis-agora-authkit`; `repository.url` followed,
+  `homepage` and `bugs.url` did not. Every package therefore shipped a manifest
+  that disagreed with itself, and the "Repository"/"Homepage" links on npm leaned
+  on GitHub's rename redirect — which lasts only until someone claims the old
+  name. All three fields now name the same repository.
+
+- Updated dependencies [1f15367]
+  - @adonis-agora/authkit-core@0.7.1
+
+## 0.17.0
+
+### Minor Changes
+
+- 659862c: Exporta `isAuthkitAdmin`/`authkitDashboardAuthorize`/`authkitDashboardMiddleware` — o gate admin dos dashboards embutidos, pronto pra plugar
+
+  Todo host que embute o console admin de uma lib irmã (`@adonis-agora/durable`,
+  `@adonis-agora/media`, `@adonis-agora/agent`, `@adonis-agora/telescope`) reescrevia
+  o mesmo gate: checar `ctx.auth.hasGlobalRole('ADMIN')` e traduzir pra QUALQUER
+  formato que o `config/*_dashboard.ts` daquela lib espera — `authorize: (ctx) =>
+boolean` (durable/agent/telescope) ou `middleware: (ctx, next) => Promise<void>`
+  (media). Mesma checagem, dois shims hand-rolled por app.
+
+  `packages/authkit-client/src/host/dashboard_guard.ts` (novo subpath
+  `@adonis-agora/authkit-client/dashboard_guard`, também no entrypoint raiz) fixa a
+  checagem uma vez sobre o próprio `Authenticator` do authkit e expõe os dois
+  adapters prontos:
+
+  ```ts
+  // config/durable_dashboard.ts (authorize)
+  import { authkitDashboardAuthorize } from "@adonis-agora/authkit-client";
+  export default defineConfig({ authorize: authkitDashboardAuthorize() });
+
+  // config/media_dashboard.ts (middleware)
+  import { authkitDashboardMiddleware } from "@adonis-agora/authkit-client";
+  export default defineConfig({ middleware: authkitDashboardMiddleware() });
+  ```
+
+  `isAuthkitAdmin(ctx, { role? })` é o predicado por trás dos dois: resolve a
+  sessão via `getAuthkit(ctx)` (funciona tanto com o `ctx.auth` do
+  `authkit_middleware` legado quanto com o `authkitClientGuard` mais novo, sem
+  depender da augmentation de `HttpContext.auth` que cada host declara pro seu
+  próprio model de usuário — este módulo é da lib, não vê essa augmentation) e
+  checa `hasGlobalRole('ADMIN')` por padrão; `role` troca o nome da global role
+  pra quem usa outra convenção. Sem sessão -> `false`/`401`; sessão sem a role ->
+  `false`/`403` — mesma semântica que o `authorize`/`middleware` de cada lib já
+  espera de um retorno negativo.
+
+  Só cobre o caso que já usa o mecanismo NATIVO do authkit (`hasGlobalRole`) — apps
+  que gateiam admin por outra via (uma role de app separada, uma coluna
+  `isAdmin`, um pacote de authz por cima) continuam com o helper deles; nada aqui
+  migra esse mecanismo.
+
+## 0.16.0
+
+### Minor Changes
+
+- 40bb1a8: Amarra o restore da impersonação à sessão que guardou a credencial, e faz a revogação central levá-la junto
+
+  **Segurança — leia antes de subir. Impersonações EM VOO caem no upgrade** (ver
+  "O que acontece no upgrade", no fim).
+
+  Dois defeitos, ambos no `AuthkitClientManager`.
+
+  **A — `stopImpersonating()` restaurava uma credencial que não sabia atribuir.**
+  `impersonate()` parqueia o TokenSet INTEIRO do ator — refresh token incluso —
+  em `${sessionKey}_impersonator`, e a única conferência do restore era se a chave
+  existia. Como nada na lib limpava essa chave, a credencial sobrevivia à sessão
+  que a guardou. A cadeia completa: um admin impersona alguém, faz logout, uma
+  outra identidade loga no MESMO cookie jar e chama o endpoint de stop — e recebe
+  o TokenSet do admin, mantido vivo indefinidamente pelo `maybeRefresh` a cada
+  request. Em versões anteriores, **a lib entregava a credencial de impersonação a
+  quem ficasse com a sessão depois.**
+
+  **B — a revogação central deixava a credencial parqueada.**
+  `BackchannelRevocationMiddleware` fazia `session.forget(sessionKey)` e só. É o
+  mecanismo que o operador usa para matar uma sessão de fora, e ele deixava o
+  refresh token do ator parqueado no browser. **Nenhum consumidor conseguia
+  corrigir isso de fora** — o middleware é da lib. O logout RP-initiated do
+  `registerOidcClient` tinha o mesmo furo.
+
+  **O que mudou.** `impersonate()` gera um nonce e escreve o mesmo valor nos dois
+  lados: no registro parqueado e dentro do token set ATIVO da sessão
+  (`TokenSet.impersonationBinding`). O slot ativo é o único que todo caminho de
+  fim-de-sessão já limpa, então uma troca de identidade apaga o vínculo por
+  construção — não por convenção. `stopImpersonating()` exige que os dois batam;
+  `maybeRefresh` propaga o nonce (renovar o token do alvo não muda a sessão, então
+  não pode trancar o ator). Recusa é **fail-closed**: a credencial órfã é
+  descartada, nunca devolvida, e o token set da sessão cai junto — uma recusa não
+  é uma tentativa a repetir, e ninguém fica preso impersonando. Revogação
+  back-channel e logout passaram a usar `manager.endSession(ctx)`, o único ponto
+  que conhece as duas chaves.
+
+  E o callback de login passou a usar `manager.startSession(ctx, tokenSet)`, o par
+  de `endSession()`. Recusar o restore já fecha o roubo, mas recusar é só não
+  DEVOLVER: com um `session.put(sessionKey, …)` cru, o refresh token do ator
+  continuava serializado no cookie de sessão da identidade nova até a sessão
+  expirar. Não devolver e não guardar são coisas diferentes, e é a segunda que
+  sustenta a invariante — a credencial parqueada nunca sobrevive à sessão que a
+  parqueou. Aplicações que escrevem o token set em `sessionKey` por conta própria
+  num fluxo de login devem chamar `startSession()` no lugar.
+
+  **Limite honesto**, também no docblock: quem controla o cookie jar DURANTE uma
+  impersonação ativa continua indistinguível do ator — é literalmente a mesma
+  sessão. Isso é o modelo de sessão, não esta conferência. O que fecha é a janela
+  em que a credencial sobrevive à sessão que a guardou.
+
+  **O que acontece no upgrade.** Uma sessão parqueada por uma versão anterior não
+  tem vínculo nenhum — é exatamente a credencial que não dá para atribuir.
+  `stopImpersonating()` a **recusa e descarta**, e limpa o token set da sessão. Na
+  prática: **todo admin que estiver impersonando alguém no momento do deploy é
+  deslogado e precisa entrar de novo.** Nenhum outro usuário é afetado, e não
+  sobra nada a fazer depois do primeiro ciclo de requests.
+
+  A alternativa (restaurar uma vez com aviso) foi descartada: seria devolver
+  justamente a credencial deste aviso a justamente a parte que não conseguimos
+  identificar, e num cookie session store "uma vez" é por cookie jar — o atacante
+  também ganharia a dele. O custo do fail-closed é um login de admin; o da
+  leniência é manter o furo aberto por uma sessão inteira.
+
+  **API.** Nada removido. Novo `AuthkitClientManager.endSession(ctx)` (use no
+  lugar de `session.forget(sessionKey)` se o seu app derruba a sessão à mão) e
+  novo campo opcional `TokenSet.impersonationBinding` — gerenciado pela lib; não
+  escreva nele. Se o seu app escreve o TokenSet direto no `sessionKey` (ex.: um
+  refresh próprio), preserve esse campo, senão um stop legítimo será recusado
+  (fail-closed: o ator é deslogado, não travado).
+
+## 0.15.0
+
+### Minor Changes
+
+- 618d83f: `authkitClientGuard()`: um guard de verdade do `@adonisjs/auth` (opt-in)
+
+  Até agora o `authkit-client` não tinha guard nenhum, e o `authkit_middleware`
+  ainda **atropelava** o `ctx.auth` do framework com o `Authenticator` da lib. Um
+  host em cima do `authkit-client` simplesmente não conseguia usar `@adonisjs/auth`:
+  sem `middleware.auth()`, sem `ctx.auth.user` tipado com o model do app, sem
+  Bouncer em cima do usuário logado. Cada host reescrevia o próprio middleware de
+  autenticação — e cada um desses é um lugar a mais para errar autorização.
+
+  **Nada muda para quem já usa a lib.** Sem guard em `config/auth.ts`, o
+  `authkit_middleware` continua idêntico: `ctx.auth` segue sendo o `Authenticator`
+  do authkit, `getIdentity()` / `getUser()` / `getUserOrFail()` / `hasGlobalRole()`
+  / `toSharedProps()` seguem com o mesmo comportamento, e o `auth_middleware` /
+  `silent_auth_middleware` continuam funcionando. Não há deprecação, não há aviso
+  em runtime, não é preciso migrar.
+
+  ## O que entrou
+
+  - `authkitClientGuard({ provider })` — implementa o `GuardContract` do
+    `@adonisjs/auth` (mesmo `authenticate()` / `check()` / `getUserOrFail()`, e o
+    MESMO `E_UNAUTHORIZED_ACCESS` dos guards nativos, então o `middleware.auth()` e
+    o exception handler do host tratam igual).
+  - `AuthkitContextMiddleware` (`@adonis-agora/authkit-client/authkit_context_middleware`)
+    — popula `ctx.authkit` **sem tocar em `ctx.auth`**.
+  - `getAuthkit(ctx)` — o resolvedor memoizado por request que os dois usam.
+
+  O guard **não reimplementa resolução de sessão**. Ele passa pelo
+  `AuthkitClientManager` exatamente como o `authkit_middleware`: refresh proativo
+  do token (`maybeRefresh`), o `SessionResolver` configurado (JWT/opaco/PAT),
+  as métricas e a ponte do `@agora/context` continuam valendo no caminho do guard.
+  A única coisa que ele acrescenta é a ponte: pega `identity.userId` (a claim
+  `sub` — a `Identity` **não** tem `id`) e pede o usuário do app ao `provider`.
+
+  `@adonisjs/auth` é um **peer opcional**: todo import dele é type-only, exceto um
+  `await import('@adonisjs/auth')` dentro do resolver do config — que só roda
+  quando o host resolve o `config/auth.ts`. Quem não usa `@adonisjs/auth` não
+  carrega nada a mais.
+
+  ## Como habilitar (3 passos)
+
+  1. `config/auth.ts`:
+
+     ```ts
+     import { defineConfig } from "@adonisjs/auth";
+     import { sessionUserProvider } from "@adonisjs/auth/session";
+     import { authkitClientGuard } from "@adonis-agora/authkit-client";
+
+     export default defineConfig({
+       default: "web",
+       guards: {
+         web: authkitClientGuard({
+           provider: sessionUserProvider({
+             model: () => import("#models/user"),
+           }),
+         }),
+       },
+     });
+     ```
+
+     A coluna de id do model precisa casar com `identity.userId` (é o que o
+     `lucidMirror()` grava).
+
+  2. `start/kernel.ts`: **troque** o `authkit_middleware` pelo par do framework +
+     o middleware de contexto do authkit. Os dois donos de `ctx.auth` não convivem
+     na mesma request — é ou um ou outro, de propósito:
+
+     ```diff
+      router.use([
+     -  () => import('@adonis-agora/authkit-client/authkit_middleware'),
+     +  () => import('@adonisjs/auth/initialize_auth_middleware'),
+     +  () => import('@adonis-agora/authkit-client/authkit_context_middleware'),
+      ])
+     ```
+
+     Registrar os dois resolveria a sessão duas vezes em objetos diferentes — não
+     faça isso.
+
+  3. Nas rotas, use o `middleware.auth()` do framework no lugar do
+     `auth_middleware` / `silent_auth_middleware` da lib (que passam a ser o
+     caminho legado — continuam existindo e funcionando para quem NÃO adotou o
+     guard).
+
+  Depois disso:
+
+  - `ctx.auth.user` é o model do app, vindo do `provider`;
+  - `ctx.authkit` é o `Authenticator` do authkit — `hasGlobalRole()`,
+    `getIdentity()` (a `Identity` crua), `toSharedProps()`.
+
+  ## `provider` + `resolveUser`
+
+  São superfícies separadas e ambas continuam valendo:
+  `ctx.auth.user` vem **sempre** do `provider`; `ctx.authkit.getUser()` continua
+  vindo do `resolveUser` de `config/authkit_client.ts`. **O guard nunca chama
+  `resolveUser`.** Com o guard configurado, o normal é apagar o `resolveUser` e
+  deixar só o `provider`.
+
+  ## Limitação conhecida
+
+  `authenticateAsClient()` (o `loginAs` dos plugins de teste do `@adonisjs/auth`)
+  lança: a sessão deste guard é um TokenSet OIDC assinado pelo IdP, e a lib não
+  tem como forjar um `id_token` a partir de um objeto de usuário. Em teste, use
+  `mintTestIdToken()` de `@adonis-agora/authkit-testing` e plante o TokenSet na
+  sessão, ou injete `fakeAuthenticator()` em `ctx.authkit`.
+
+## 0.14.0
+
+### Minor Changes
+
+- 4a3be7a: Adiciona o acessor singleton `@adonis-agora/authkit-client/services/main` (convenção `services/main` do
+  Adonis, como `db`/`mail`/`drive`). Deixa o app usar
+  `import authkit from "@adonis-agora/authkit-client/services/main"` e ler `authkit.clientConfig` / chamar
+  `authkit.getIdToken(ctx)`, `authkit.handleBackchannelLogout(ctx)` etc., em vez de resolver a binding
+  string-keyed `"authkit.client"` pelo container na mão (`ctx.containerResolver.make("authkit.client")`).
+  Funciona tanto em controllers-classe quanto em route handlers inline.
+
+## 0.13.0
+
+### Minor Changes
+
+- 960f39e: `Authenticator.getUserOrFail(): Promise<TUser>` — o usuário autenticado NÃO-nulo, fail-closed (lança quando não há sessão ou `resolveUser` não devolve usuário). Espelha `authenticate()` (que devolve a `Identity`); este devolve o usuário do app.
+
+  Substitui o wrapper `currentUser(auth)` que cada app reescrevia sobre `getUser()`:
+
+  ```ts
+  // antes (helper por app):
+  const user = await currentUser(auth);
+  // agora:
+  const user = await auth.getUserOrFail();
+  ```
+
+  Com o generic na augmentation (`auth: Authenticator<AppUser>`), devolve `AppUser` direto, sem cast. Para rotas com visitante, siga usando `getUser()` (`TUser | null`).
+
+## 0.12.0
+
+### Minor Changes
+
+- c016a62: `Authenticator` agora é genérico no tipo do usuário do app: `Authenticator<TUser = unknown>`, com `getUser(): Promise<TUser | null>` e `toSharedProps().user: TUser | null`. Non-breaking (default `unknown` mantém o comportamento anterior). Um app fixa o tipo augmentando `HttpContext.auth` (`auth: Authenticator<AppUser>`) e aí `getUser()` devolve `AppUser | null` em todo call-site — acaba o `(await auth.getUser()) as AppUser` repetido. A asserção do model do app fica UMA vez, dentro de `getUser`, em vez de espalhada.
+
+## 0.11.0
+
+### Minor Changes
+
+- c12bac9: `authkit-client` now only authenticates — app-role/authorization concerns moved out to
+  `@adonis-agora/authz`.
+
+  Removed:
+
+  - `AuthenticatorDeps.resolveAppRoles`, `Authenticator.hasAppRole`/`getAppRoles`.
+  - `appRoles`/`abilities` from `Authenticator.toSharedProps()` — it now returns
+    `{ user, globalRoles }`.
+  - `ClientConfigInput.resolveAppRoles`/`ResolvedClientConfig.resolveAppRoles` (`defineConfig`).
+  - `AuthMiddlewareOptions.roles`/`unauthorizedRedirect` — the built-in `auth_middleware` now only
+    requires a valid session (redirects to `options.redirectTo ?? '/auth/login'` when absent). Use
+    `@adonis-agora/authz` (or Bouncer) on the route for role/permission gating.
+  - `PostLoginRedirects.byAppRole` in `registerOidcClient` — `byGlobalRole` (claims from the token)
+    and `default` still work; the `resolveDestination` helper no longer takes an `authenticator`.
+
+  Kept: `hasGlobalRole`, `getIdentity` (still populates the Agora context), `getUser`,
+  `authenticate`, `check` — these read from the token/session, not from app-defined roles.
+
+## 0.10.1
+
+### Patch Changes
+
+- 70f5721: Ship peer dependencies as ranges instead of exact versions
+
+  `peerDependencies` pointed at the pinned `adonis`/`frontend` catalogs, and pnpm
+  inlines a catalog's literal value at publish time — so every published peer came
+  out exact. `@adonis-agora/authkit-server@0.34.1` on npm requires
+  `"@adonisjs/core": "7.3.3"`, which no app on 7.3.5 can satisfy;
+  `@adonis-agora/authkit-react@0.13.0` requires `"react": "19.2.6"`, which locks
+  out every consumer not on that exact patch.
+
+  Peers now resolve from three new range-only catalogs (`adonisPeers`,
+  `frontendPeers`, `miscPeers`). Dependencies keep the pinned catalogs — a pin is
+  right for reproducible installs and wrong for consumer compatibility, and the
+  two were sharing one source.
+
+  No source or runtime behaviour changes.
+
+## 0.10.0
+
+### Minor Changes
+
+- 12df185: Write `globalRoles` into the @agora context from the resolved session (so the Authz global-role bridge can read them), and add Authz permission gating to authkit-react: `useCan(permission, resource?)` and `<CanPermission>`, which consult the Authz `POST <canPath>` endpoint (`{ permission, resource? }` → `{ allowed }`, credentials included) with in-memory caching/dedupe. The endpoint path is configurable via `AuthkitProvider` (`canPath` / `endpoints.can`, default `/authz/can`).
+
+## 0.9.0
+
+### Minor Changes
+
+- 394b9aa: Bridge audit events to the @agora diagnostics bus; populate @agora context from the resolved session
+- 0542665: Re-scope to @adonis-agora/authkit-\* (join the Agora ecosystem)
+- 08e721e: Optional resilience policy for outbound OIDC/JWKS calls
+
+### Patch Changes
+
+- Updated dependencies [0542665]
+  - @adonis-agora/authkit-core@0.7.0
+
+## 0.8.0
+
+### Minor Changes
+
+- dd80bb8: Segurança (least privilege): a claim de papéis globais e as claims de organização saem do scope `profile` para um scope dedicado `roles`, e sua emissão é gated a clients first-party (`branding.firstParty`). Clients third-party NÃO recebem papéis/org, mesmo solicitando o scope `roles`. O default de scopes do authkit-client passa a incluir `roles` (consumidores first-party continuam recebendo papéis sem mudança de comportamento). BREAKING para quem dependia de papéis no scope `profile`: o client precisa solicitar o scope `roles`.
+
+## 0.7.2
+
+### Patch Changes
+
+- Updated dependencies [93eaf69]
+- Updated dependencies [e2582b8]
+  - @adonis-agora/authkit-core@0.6.0
+
+## 0.7.1
+
+### Patch Changes
+
+- Updated dependencies [df4b41f]
+  - @adonis-agora/authkit-core@0.5.0
+
+## 0.7.0
+
+### Minor Changes
+
+- 68a8f4c: `lucidRevocationStore` agora faz auto-prune — limpeza vem da lib, não do app
+
+  Antes, o app precisava agendar o `prune()` das revogações de back-channel logout
+  (scheduler/job). Agora o `lucidRevocationStore` limpa sozinho: no `revoke()`, de
+  forma OPORTUNÍSTICA e throttled (no máx. 1× por `everyHours` por processo, default
+  24h), remove revogações mais velhas que `olderThanDays` (default 35). Best-effort —
+  falha não atrapalha o logout.
+
+  - Default LIGADO; configure via `lucidRevocationStore({ autoPrune: { everyHours, olderThanDays } })`.
+  - Desligue com `autoPrune: false` (ex.: se preferir agendar você mesmo).
+
+  Resultado: o consumidor não precisa mais de nenhum scheduler/job para a limpeza.
+
+## 0.6.0
+
+### Minor Changes
+
+- 262eb79: Back-Channel Logout pronto para sessões cookie-based + DX do client
+
+  Antes, fechar o gap de logout SSO em sessão cookie-based exigia escrever model + service + middleware à mão em cada app (e era fácil esquecer — deixando a sessão válida por até 30 dias após um logout SSO). Agora o AuthKit absorve isso:
+
+  **`@adonis-agora/authkit-client`**
+
+  - `lucidRevocationStore({ connection?, table? })` + interface `RevocationStore`: persistência append-only de revogações (sid/sub/revoked_at), sem precisar declarar model.
+  - `BackchannelRevocationMiddleware` (subpath `/backchannel_revocation_middleware`): derruba a sessão revogada na próxima request.
+  - `defineConfig({ backchannelLogout: { store } })`: deriva o `onBackchannelLogout` e expõe o store ao middleware.
+  - `lucidMirror(Model, { sync, preload, injectGlobalRoles })`: factory do `resolveUser` "espelho local".
+  - Middlewares prontos `auth_middleware` (com `roles`) e `silent_auth_middleware` (subpaths).
+  - `buildAuthorizeUrl({ extraParams })`: anexa `audience`/`prompt`/`login_hint`/etc. sem manipular URL na mão.
+  - `Authenticator.toSharedProps()`: `{ user, globalRoles, appRoles, abilities }` pronto p/ Inertia share.
+  - `AuthkitClientManager.impersonate()` / `stopImpersonating()` / `isImpersonating()`: ciclo de impersonação (RFC 8693) gerenciado.
+  - `registerOidcClient(router, { redirects, afterLogin, loginMiddleware })`: registra login/callback/logout (+back-channel) absorvendo PKCE/state/exchange/redirect-por-papel do OidcSessionController.
+
+  **`@adonis-agora/authkit-server`**
+
+  - Tabela `auth_session_revocations` gerenciada pelo `ensureAuthkitSchema()` (schema auto-manage) — compartilhável entre apps no mesmo banco.
+  - Revogação em massa do admin (`AdminSessionsService.revokeAll`) grava uma revogação `sub` na tabela compartilhada → logout INSTANTÂNEO nos clients cookie-based (antes esperava o refresh token falhar, ~TTL do access token).
+  - **Config locks (BREAKING semântico):** settings definidas no `defineConfig` ficam TRAVADAS — config vence e a UI/Admin API não pode alterá-las (`getSetting` → null p/ resolvers caírem no config; `setSetting`/`deleteSetting` → 423 `SettingLockedError`). O console mostra badge "definido via config" e desabilita o controle. Exports: `isSettingLocked`, `lockedSettingKeys`, `deriveLockedSettingKeys`, `SettingLockedError`.
+  - **`encrypter` do TOTP agora é DEFAULT (BREAKING):** `lucidAccountStore` encripta o segredo TOTP com `APP_KEY` por padrão (`appKeyEncrypter()`); `encrypter: false` desliga. ⚠️ Segredos gravados em claro por versões anteriores deixam de decriptar — migre ou passe `false`.
+  - `jwks: 'auto'` — resolve env-aware (`AUTHKIT_JWKS` inline, senão managed em arquivo); elimina o ternário no config.
+  - `adminApi.apiKeys: 'env'` (lê `AUTHKIT_ADMIN_API_KEY`) + `enabled` auto quando há key — elimina o spread condicional.
+  - `lucidStores({ account, pat, audit, providerIdentity, webauthnCredential, organizations }, { mfaIssuer, webauthn })`: monta os stores declarando mfaIssuer/webauthn UMA vez.
+  - `defineConfig` reusa `mfaIssuer`/`webauthn` do `lucidAccountStore` quando o top-level não os fornece (declare uma vez).
+  - `authkitCsrfExceptions(url, { mountPath })`: helper de isenção CSRF das rotas machine-to-machine.
+  - **`registerAuthHost(router)` sem opts** — lê mountPath/social/rateLimit/admin/adminApi do `config/authkit.ts` (stash no boot do provider, que roda antes do preload do routes.ts). Acaba com o drift config↔registerAuthHost; `opts` viram só override (ex.: `{ admin: { prefix } }`). Fallback p/ defaults quando não há stash (testes).
+
+## 0.5.0
+
+### Minor Changes
+
+- a6ca8a7: Bring your own IdP — use AuthKit against any OIDC-compliant provider
+  - **client**: new `discoverEndpoints(issuer)` resolves the IdP's real endpoints from `/.well-known/openid-configuration` (cached per issuer, field-level manual overrides, silent fallback to the oidc-provider conventions when the document is unreachable). All flow helpers (`buildAuthorizeUrl`, `exchangeCode`, `refreshTokens`, `exchangeToken`, `buildEndSessionUrl`) now accept explicit endpoint params — Keycloak, Auth0, Okta, Entra et al. work out of the box.
+  - **react**: new `idp: 'authkit' | 'external'` config on `AuthkitProvider`. With an external IdP, the components that depend on authkit-server's REST surface (`UserProfile`, `OrganizationSwitcher`, `OrganizationProfile`, `AuthorizedApps`) degrade to `null` instead of calling endpoints that don't exist; sign-in/out, auth state, role gates and the password strength meter keep working.
+  - New "Bring your own IdP" docs page tying the two together.
+
+## 0.4.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @adonis-agora/authkit-core@0.4.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @adonis-agora/authkit-core@0.3.1
+
+## 0.4.0
+
+### Minor Changes
+
+- Round 7 — production pack + multi-tenancy:
+  - **Organizations (multi-tenancy)**: optional capability-probed tables (`auth_organizations`, `auth_organization_members`, `auth_organization_invitations`), per-org roles (owner/admin/member), email invitations with hashed tokens, active-org session cookie with `org_id`/`org_slug`/`org_role` claims in id_token/userinfo/JWT access tokens, `/account/orgs` page, admin console section, Admin REST API (`/api/authkit/v1/organizations`), SDK `organizations.*` namespace (remote + embedded), React `useOrganizations`/`useOrganization`/`useSwitchOrganization`/`useOrgInvitations` hooks plus `<OrganizationSwitcher />` and `<OrganizationProfile />` components.
+  - **LGPD/GDPR compliance**: self-service and admin account deletion with full cascade (sessions, grants, PATs, passkeys, identities, MFA, avatar) and audit anonymization (stable pseudonym), data export endpoint (`GET /account/security/export`), `login.requireVerifiedEmail` gate across password/magic-link/passkey flows, SDK `users.delete()`.
+  - **User migration & password hygiene**: transparent lazy password rehash on login, `password.legacyVerifier` hook for foreign hash formats, `authkit:users:import` ace command (JSON/NDJSON, `--dry-run`), configurable `password.policy`, HaveIBeenPwned k-anonymity breach check (fail-safe), React `usePasswordStrength` + `<PasswordStrengthMeter />`.
+  - **JWT access tokens (RFC 9068)**: `accessTokens: { format: 'jwt' }` with per-resource overrides, `verifyJwtAccessToken` local validation in the client package, `authkit:keys:rotate` command with grace-period JWKS rotation.
+  - **Bot protection**: pluggable vendor-agnostic `botProtection` config (Turnstile/hCaptcha-ready, fail-safe) on login/signup/reset.
+  - **New-device login notification**: `notifications.newDeviceEmail` + `mail.onNewDeviceLogin` hook driven by the trusted-device signal.
+  - **Console polish**: session context (user-agent/OS/IP/geo via pluggable `resolveGeo`), RFC 8693 impersonation panel (`admin.impersonation`, default off), dashboard with MAU/daily sign-ins, `GET /api/authkit/v1/stats` + SDK `stats()`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @adonis-agora/authkit-core@0.3.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 0c33640: Round 4 — events/webhooks, DPoP client, full e2e harness, polish.
+
+  **server (minor):** add `events` config — observe every audit event in-process (`onEvent`)
+  and/or via an HMAC-signed webhook (`x-authkit-signature: sha256=...`, 5s fire-and-forget,
+  never throws into the request path). When set, the resolved `audit` sink becomes a fan-out
+  (original sink + onEvent + webhook), preserving the admin `list()` query. Also: a full
+  interaction e2e harness driving login → consent → token (plus step-up MFA and device-flow
+  variants) through the real host controllers, and English `authkit:doctor` messages. Builds on
+  the existing consent/account-console, admin user CRUD, profile self-service, trusted-device,
+  and passwordless (magic-link / passkey-first) features.
+
+  **client (minor):** add DPoP (RFC 9449) proof generation — `generateDpopKeyPair()` (jose
+  ES256, exportable JWK) and `createDpopProof({ key, htm, htu, nonce?, accessToken? })` producing
+  a signed `dpop+jwt`, plus `dpopJwkThumbprint()`.
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [1872a30]
+  - @adonis-agora/authkit-core@0.2.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Refactors do code review (comportamento preservado, contratos mais limpos):
+
+  **server (minor):**
+
+  - `AccountStore` decomposto em interfaces de capacidade (`CoreAccountStore`,
+    `MfaCapability`, `WebauthnCapability`, `ProviderIdentityCapability`) com type
+    guards (`supportsMfa`/`supportsPasskeys`/`supportsProviderIdentity`). O tipo
+    `AccountStore` continua existindo (core & Partial<capacidades>) — compatível.
+    `lucidAccountStore` agora OMITE os métodos de capacidades não configuradas em
+    vez de lançar em runtime; social login sem provider-identity degrada pro login.
+  - Sequência login+lockout centralizada em `attemptPasswordLogin` (era duplicada
+    em 2 controllers).
+  - `adminGuard` agora retorna 404 quando `admin.enabled: false` (fecha bypass de
+    drift entre config e `AuthHostOptions.admin`).
+  - `dynamicRegistration.management: true` sem `enabled: true` agora falha no
+    resolve do config (RFC 7592 exige 7591).
+  - Serialização JSON dos mixins unificada em `jsonColumn()` (semântica por coluna
+    preservada).
+
+  **client (minor):**
+
+  - POST ao token endpoint unificado (`exchangeCode`/`refreshTokens`/`exchangeToken`).
+  - Introspection + claims→Identity compartilhados entre resolvers; `pat`/`opaque`
+    agora também mapeiam `picture→profile.avatarUrl` e `sid→sessionId` (alinhados
+    ao `jwt`).
+
+  **react (patch):**
+
+  - Helpers genéricos de roles; warn de dev no `useAuth` quando não há
+    `AuthProvider` nem shared prop do Inertia.
+
+## 0.1.1
+
+### Patch Changes
+
+- Corrige os stubs de scaffolding (`node ace configure`):
+  - Usa os nomes renomeados dos pacotes (`@adonis-agora/authkit-*`) — antes os
+    stubs ainda importavam de `@authkit/*` (inexistente), gerando código quebrado.
+  - O model `AuthUser` scaffoldado passa a usar a **conexão default da aplicação**
+    (config/database.ts) por padrão, em vez de forçar `static connection = 'auth'`.
+    Para isolar o AuthKit num schema/banco dedicado, basta definir a conexão no
+    model — documentado no próprio stub. A lib cria as tabelas no banco do app, ou
+    onde o dev definir.