@adonis-agora/authkit-core 0.10.1 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,231 @@
+# @adonis-agora/authkit-core
+
+## 1.0.0-rc.1
+
+### Minor Changes
+
+- [#471](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/471) [`66ccc36`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/66ccc365dbbd7d9d5bf22dba7aad196aff9f5d4b) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Account console extensions from another app. An app that signs in through an authkit IdP can now add pages to the IdP's account console:
+  
+  - authkit-client binds the same `authkit.accountExtensions` registry, so packages register their pages the same way in both setups. With `accountConsole: { remote: true }` the app serves them at `/.well-known/agora-account-extensions` (mounted by `registerOidcClient`, or `registerAccountExtensionsEndpoint(router)`), only to requests the IdP signed for its client id with the scope `authkit:account-extensions`. `accountConsole.subject` maps the IdP account to the app's user.
+  - authkit-server: `accountConsole.remote: [{ clientId, url }]` lists those apps; their pages show in the console next to the in-process ones, with the same sign-in, sudo, confirmation, rate limit and audit rules.
+  - The contract types and validation now live in authkit-core (still exported from `@adonis-agora/authkit-server/account-extension`).
+
+## 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).
+
+## 0.10.1
+
+### 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)! - Declare `"sideEffects": false` so bundlers can tree-shake the package in client bundles. It has no module-level side effects.
+
+## 0.10.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.
+
+## 0.9.0
+
+### Minor Changes
+
+- [#233](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/233) [`94644e6`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/94644e6b1d8d10e0fd3c4b57706cce46b70412cb) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `applicationType?: 'web' | 'native'` nos tipos de client
+  
+  `ClientConfig` (core) e `AdminClient`/`CreateClientInput` (react) ganham o campo opcional
+  `applicationType`, para os clientes nativos (RFC 8252) do `@adonis-agora/authkit-server`.
+
+## 0.8.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.
+
+## 0.7.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.
+
+## 0.7.0
+
+### Minor Changes
+
+- 0542665: Re-scope to @adonis-agora/authkit-\* (join the Agora ecosystem)
+
+## 0.6.0
+
+### Minor Changes
+
+- 93eaf69: feat: cofre do keystore JWKS no HashiCorp Vault (KV v2). Novo driver
+  `{ driver: 'hashicorp-vault', endpoint, path, token?, mount?, field? }` — usa a API
+  HTTP do Vault (sem SDK), então mora em core como file/drive/lucid/redis. Encryption
+  at-rest fica OFF por default (o Vault tem cifra/ACL próprios; ligável p/ envelope).
+- e2582b8: feat: cofres do keystore JWKS em Lucid e Redis. Novos drivers `jwks.store`:
+  `{ driver: 'lucid' }` (tabela dedicada `authkit_keystore`, auto-criada) e
+  `{ driver: 'redis' }` (uma key). Diferente de `file`, ambos são COMPARTILHADOS entre
+  instâncias — o melhor default para multi-instância + hot-reload (o poll lê um `head`
+  barato). Encryption at-rest (APP_KEY) ON por default nos dois. Warning no boot quando
+  `redis` é usado (exige persistência RDB/AOF). `resolveKeystoreVault` agora recebe um
+  contexto com acesso ao container (mudança de assinatura interna).
+
+## 0.5.0
+
+### Minor Changes
+
+- df4b41f: feat: keystore JWKS managed com cofre pluggável + encryption at-rest (Fatia A+B)
+
+  O keystore managed deixa de ser fs-síncrono-num-path e passa por uma abstração de
+  cofre (`KeystoreVault`): `file` (default) e `drive` (`@adonisjs/drive`, bucket), com
+  contrato para cofres custom. O keystore PRIVADO agora é encriptado em repouso por
+  default (APP_KEY) para file/drive via um envelope versionado; decrypt falho lança
+  (nunca regenera em silêncio). O boot e o comando `authkit:keys:rotate` usam o mesmo
+  stack (defaults de encryption idênticos). Novidades: aviso no boot quando
+  `jwks: 'auto'` cai no fallback de disco, e idade da chave de assinatura no
+  `authkit:doctor`. Config: `jwks.store` aceita `{ driver: 'file' | 'drive' | ... }`
+  além de string, e novo `jwks.encrypt`.
+
+  Nota (0.x): sem migração de keystore legado — um `tmp/authkit_jwks.json` plaintext
+  pré-existente deve ser apagado uma vez (regenera encriptado).
+
+## 0.4.0
+
+### Minor Changes
+
+- Breaking cleanup (0.x, no external consumers): every deprecation shim is gone.
+  - Policy now lives ONLY in runtime settings (DB) with library defaults — removed from config: static `clients`, lockout policy fields (`store` stays), rate-limit buckets (`enabled`/`store` stay), `notifications`, trusted-devices `enabled`/`days`, `admin.impersonation`, organizations `roles`/`allowSelfCreate`/`invitationTtlHours`, and `password.policy`/`password.checkPwned` store options (`legacyVerifier`/`pepper`/`pwnedTimeoutMs` stay — they are code/infra).
+  - Removed commands `authkit:clients:import` and the legacy `authkit:rotate-keys` alias. New `authkit:clients:create` creates OIDC clients programmatically through the configured storage (confidential secret printed once; `--public`, repeatable `--redirect-uri`/`--grant`, `--json`).
+  - Removed the no-op `passthroughParsed` option from `jsonColumn` and the `checkLegacyPolicyConfig` doctor check.
+
+## 0.3.1
+
+### Patch Changes
+
+- Runtime-first administration:
+  - **Three new runtime toggles** (auth_settings-backed, with admin console cards showing effective state): `registration` (open/close self-service signup without affecting org invites or admin-created users; static fallback `registration.enabled`), `require_verified_email` (overrides `login.requireVerifiedEmail` across password/magic-link/passkey flows), and `maintenance_mode` (`{ enabled, message? }` — blocks login/signup/forgot for non-admins with a maintenance page while admin accounts keep logging in; userinfo/introspection/existing sessions keep working; the Admin API is never blocked, providing a guaranteed escape hatch). Audit events `maintenance.enabled`/`maintenance.disabled`.
+  - **Clients are now managed at runtime** (admin console + Admin REST API are the canonical path): the static `clients` config field is optional and deprecated (boot warning, doctor warning, console banner). New `authkit:clients:import` ace command (`--dry-run`) migrates config clients to the adapter preserving secrets and skipping existing ones. Booting with zero configured clients is fully supported. New doctor check warns when clients live in a volatile adapter. Backchannel logout URI/session-required are now editable via console and API.
+
+## 0.3.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()`.
+
+## 0.2.0
+
+### Minor Changes
+
+- 1872a30: DX & ops infra:
+  - New package `@adonis-agora/authkit-testing` — test helpers for host apps:
+    `createTestIdentity`, `mintTestIdToken` + `serveJwks`/`testJwks`/`jwksFromKey`
+    (real RS256 tokens validated by a local JWKS), `fakeAuthenticator`, and a
+    capability-aware `fakeAccountStore`.
+  - `node ace authkit:doctor` — validates host config and prints ✅/⚠️/❌ findings
+    (issuer/mountPath, clients, accountStore capabilities, session, shield, ally,
+    rate-limit, admin, webauthn, jwks). Non-zero exit on errors.
+  - `node ace authkit:rotate-keys` — rotates managed JWKS signing keys via a new
+    file-backed keystore (`jwks: { source: 'managed', store }`), keeping the last
+    N public keys so pre-rotation tokens still verify.

package/build/index.d.ts

@@ -1,7 +1,12 @@
+export type { AccountAction, AccountActionField, AccountActionResult, AccountActiveOrg, AccountBlockKind, AccountExtension, AccountExtensionContext, AccountExtensionOverride, AccountExtensionRegistry, AccountPage, AccountPageNav, AccountPageView, AccountSubject, AccountTenantLevel, AccountTenantRef, ActionRef, Block, ComponentScript, ListItem, Text, Value, } from './src/account_extensions/contract.js';
+export { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, ACCOUNT_EXTENSIONS_BINDING, } from './src/account_extensions/contract.js';
+export type { AccountExtensionsManifest, RemoteAccount, RemoteActionManifest, RemoteCall, RemoteCallResponse, RemoteExtensionManifest, RemotePageManifest, RunAccountExtensionCallOptions, } from './src/account_extensions/remote.js';
+export { ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT, ACCOUNT_EXTENSIONS_SCOPE, ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL, ACCOUNT_EXTENSIONS_TOKEN_TYP, ACCOUNT_EXTENSIONS_WELL_KNOWN, ACCOUNT_EXTENSIONS_WIRE_VERSION, accountExtensionsBodyHash, buildAccountExtensionsManifest, parseAccountExtensionCall, runAccountExtensionCall, } from './src/account_extensions/remote.js';
+export { ACCOUNT_RESERVED_SEGMENTS, ACCOUNT_SEGMENT, AccountExtensionError, BaseAccountExtensionRegistry, failAccountExtension, validateAccountExtension, } from './src/account_extensions/validate.js';
 export type { AuthkitMetricName } from './src/metrics.js';
 export { AUTHKIT_METRICS } from './src/metrics.js';
 export type { MetricsRecorder, MetricsSnapshot } from './src/metrics_recorder.js';
 export { InMemorySnapshot, NoopRecorder } from './src/metrics_recorder.js';
 export type { Identity, SessionResolver } from './src/types/identity.js';
 export { deriveOrgId, deriveOrgRole, deriveOrgSlug, ORG_ID_CLAIMS, } from './src/types/identity.js';
-export type { AccessTokenFormat, AccessTokenResourceConfig, AccessTokensConfig, ClientConfig, JwksConfig, KeystoreStoreConfig, ObservabilityConfig, ResolvedAuthServerConfig, TtlConfig, } from './src/types/server_config.js';
+export type { AccessTokenFormat, AccessTokenResourceConfig, AccessTokensConfig, JwksConfig, KeystoreStoreConfig, ObservabilityConfig, ResolvedAuthServerConfig, TtlConfig, } from './src/types/server_config.js';

package/build/index.js

@@ -1,3 +1,6 @@
+export { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, ACCOUNT_EXTENSIONS_BINDING, } from './src/account_extensions/contract.js';
+export { ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT, ACCOUNT_EXTENSIONS_SCOPE, ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL, ACCOUNT_EXTENSIONS_TOKEN_TYP, ACCOUNT_EXTENSIONS_WELL_KNOWN, ACCOUNT_EXTENSIONS_WIRE_VERSION, accountExtensionsBodyHash, buildAccountExtensionsManifest, parseAccountExtensionCall, runAccountExtensionCall, } from './src/account_extensions/remote.js';
+export { ACCOUNT_RESERVED_SEGMENTS, ACCOUNT_SEGMENT, AccountExtensionError, BaseAccountExtensionRegistry, failAccountExtension, validateAccountExtension, } from './src/account_extensions/validate.js';
 export { AUTHKIT_METRICS } from './src/metrics.js';
 export { InMemorySnapshot, NoopRecorder } from './src/metrics_recorder.js';
 export { deriveOrgId, deriveOrgRole, deriveOrgSlug, ORG_ID_CLAIMS, } from './src/types/identity.js';

package/build/src/account_extensions/contract.d.ts

@@ -0,0 +1,324 @@
+/** Account console extensions: the contract every authkit package and contributor shares. */
+/**
+ * Account console extensions — the surface another package (or the app) uses to add pages to the
+ * signed-in user's own console (`/account/*`).
+ *
+ * **Stable for all of 1.x.** A 1.x release only adds optional members and new block kinds. This
+ * module holds types and constants only, so a contributor can `import type` it from an internal
+ * module without a runtime dependency on authkit.
+ *
+ * A contributor registers itself from its provider's `boot()`:
+ *
+ * ```ts
+ * if (this.app.container.hasBinding('authkit.accountExtensions')) {
+ *   const registry = await this.app.container.make('authkit.accountExtensions')
+ *   if (registry.contract >= 1) registry.register(myAccountExtension)
+ * }
+ * ```
+ *
+ * Everything a page returns ({@link AccountPageView}, {@link AccountActionResult}) is plain JSON
+ * (dates may be `Date` or ISO strings), so the same page can also be served from another app.
+ */
+/** The container binding the registry is bound at. */
+export declare const ACCOUNT_EXTENSIONS_BINDING = "authkit.accountExtensions";
+/** The contract major this authkit implements. */
+export declare const ACCOUNT_EXTENSION_CONTRACT = 1;
+/** Block kinds this authkit renders. A contributor degrades when one it needs is missing. */
+export declare const ACCOUNT_BLOCK_KINDS: readonly ['notice', 'keyValue', 'list', 'table', 'meter', 'actions', 'link', 'toolPreview', 'component'];
+/** One of {@link ACCOUNT_BLOCK_KINDS}. */
+export type AccountBlockKind = (typeof ACCOUNT_BLOCK_KINDS)[number];
+/** A message key (looked up in the merged catalog) or literal text. Always escaped. */
+export type Text = string | {
+    key: string;
+    params?: Record<string, string | number>;
+};
+/** The active organization (signed cookie), when organizations are on. */
+export interface AccountActiveOrg {
+    id: string;
+    slug: string;
+    role: string;
+}
+/** One level of a tenant chain (outermost first). */
+export interface AccountTenantLevel {
+    id: string;
+    kind: string;
+    slug?: string;
+    role?: string;
+}
+/** The tenant of the request, in the shape `@adonis-agora/context` uses. */
+export interface AccountTenantRef {
+    id: string;
+    kind: 'organization' | 'user' | (string & {});
+    source: 'authkit' | 'app' | 'carrier' | 'legacy' | (string & {});
+    slug?: string;
+    role?: string;
+    /** The nested chain, outermost first, ending with this tenant. */
+    chain?: readonly AccountTenantLevel[];
+}
+/** Who the account is in the app: what billing, media or agents key their rows on. */
+export interface AccountSubject {
+    type: string;
+    id: string;
+}
+/** What every `visible`, `load` and action `handle` receives. */
+export interface AccountExtensionContext {
+    account: {
+        id: string;
+        email: string | null;
+        name: string | null;
+        roles: readonly string[];
+    };
+    /** The active org (signed cookie, membership re-checked), when organizations are on. */
+    activeOrg: AccountActiveOrg | null;
+    /** The tenant of the request: the active organization, when there is one. */
+    tenant?: AccountTenantRef | null;
+    /**
+     * The account mapped to the app's subject by `accountConsole.subject` in `config/authkit.ts`
+     * (default `{ type: 'User', id: account.id }`). A lib may still map it its own way.
+     */
+    subject: AccountSubject;
+    /** The admin acting as this account, when an impersonation is active. Sensitive actions refuse it. */
+    impersonatedBy: string | null;
+    /** The console locale (`'en'`, `'pt-BR'`…). */
+    locale: string;
+    /** Validated query: `cursor` and `tab` only. */
+    query: {
+        cursor?: string;
+        tab?: string;
+    };
+    /** Same-origin path of a console page (`url('payments.invoices', { cursor })`). */
+    url(pageId: string, query?: Record<string, string>): string;
+    /** Resolves a container binding. */
+    make(binding: string): Promise<any>;
+    now(): Date;
+}
+/** A formatted value. Money is in minor units; dates are `Date` or ISO strings. */
+export type Value = {
+    type: 'text';
+    text: Text;
+} | {
+    type: 'money';
+    amount: number;
+    currency: string;
+} | {
+    type: 'date';
+    at: Date | string;
+    style?: 'date' | 'datetime' | 'relative';
+} | {
+    type: 'badge';
+    text: Text;
+    tone?: 'neutral' | 'success' | 'warning' | 'danger';
+} | {
+    type: 'number';
+    value: number;
+    unit?: Text;
+};
+/** Points at `page.actions[action]`; `target` is an opaque id the handler MUST re-authorize. */
+export interface ActionRef {
+    action: string;
+    target?: string;
+}
+/** An item of a `list` block. */
+export interface ListItem {
+    title: Text;
+    subtitle?: Text;
+    meta?: Value[];
+    badge?: Value;
+    /** Same-origin path, or an https URL with `external: true`. */
+    href?: string;
+    external?: boolean;
+    actions?: ActionRef[];
+}
+/** A script a `component` block loads. */
+export interface ComponentScript {
+    /** Same-origin path (`/payments/assets/card.js`) or an https URL on one of `scriptOrigins`. */
+    src: string;
+    /** Subresource integrity (`sha384-…`). */
+    integrity?: string;
+    /** Load as an ES module. */
+    module?: boolean;
+}
+/** One block of a page. Unknown kinds render as a notice. */
+export type Block = {
+    kind: 'notice';
+    tone: 'info' | 'success' | 'warning' | 'danger';
+    text: Text;
+} | {
+    kind: 'keyValue';
+    title?: Text;
+    rows: ReadonlyArray<{
+        label: Text;
+        value: Value;
+    }>;
+    actions?: ActionRef[];
+} | {
+    kind: 'list';
+    title?: Text;
+    empty: Text;
+    items: ReadonlyArray<ListItem>;
+    nextCursor?: string | null;
+} | {
+    kind: 'table';
+    title?: Text;
+    empty: Text;
+    columns: ReadonlyArray<{
+        id: string;
+        label: Text;
+    }>;
+    rows: ReadonlyArray<{
+        cells: Record<string, Value>;
+        actions?: ActionRef[];
+    }>;
+    nextCursor?: string | null;
+} | {
+    kind: 'meter';
+    label: Text;
+    used: number;
+    limit: number | null;
+    unit?: Text;
+    resetsAt?: Date | string;
+} | {
+    kind: 'actions';
+    items: ActionRef[];
+} | {
+    kind: 'link';
+    label: Text;
+    href: string;
+    external?: boolean;
+}
+/**
+ * A structured preview of something waiting for a decision (an agent's tool call): its title,
+ * the arguments as rows, and an optional body shown verbatim (escaped).
+ */
+ | {
+    kind: 'toolPreview';
+    title: Text;
+    tool?: string;
+    subtitle?: Text;
+    args?: ReadonlyArray<{
+        label: Text;
+        value: Value;
+    }>;
+    body?: {
+        format: 'json' | 'text';
+        content: string;
+    };
+    actions?: ActionRef[];
+}
+/**
+ * A provider's own UI (card fields of Stripe Elements, Asaas, Efí, PayPal…). authkit renders
+ * the mount point, the props as a JSON data block and the scripts with the request's CSP nonce.
+ * The script mounts into `[data-block="component"][data-provider="<provider>"]`, reads its props
+ * from the `<script type="application/json">` the mount point names in `data-props`, and submits
+ * the mount point's `<form>` (the `submit` action) with the fields it adds. Until it mounts (or
+ * when scripts are blocked) the `fallback` link shows.
+ */
+ | {
+    kind: 'component';
+    provider: string;
+    scripts: ReadonlyArray<ComponentScript>;
+    props?: Record<string, unknown>;
+    submit?: ActionRef;
+    fallback?: {
+        label: Text;
+        href: string;
+        external?: boolean;
+    };
+};
+/** What `load` returns. */
+export interface AccountPageView {
+    blocks: readonly Block[];
+    /** Tabs inside one page (`query.tab`). */
+    tabs?: ReadonlyArray<{
+        id: string;
+        label: Text;
+    }>;
+}
+/** A field of an action's form. Values arrive validated, as strings. */
+export interface AccountActionField {
+    name: string;
+    label: Text;
+    kind: 'text' | 'select' | 'textarea';
+    options?: ReadonlyArray<{
+        value: string;
+        label: Text;
+    }>;
+    required?: boolean;
+    maxLength?: number;
+}
+/** What an action returns. */
+export type AccountActionResult = {
+    ok: true;
+    flash?: Text;
+    redirectTo?: {
+        page: string;
+    } | {
+        external: string;
+    };
+} | {
+    ok: false;
+    error: Text;
+    status?: 400 | 403 | 404 | 409;
+};
+/** An action a page offers. */
+export interface AccountAction {
+    label: Text;
+    tone?: 'default' | 'danger';
+    /** Confirmation text, shown on a second step page (no inline JS). */
+    confirm?: Text;
+    /** Needs recent re-authentication: authkit sends the user through `/account/confirm` first. */
+    sudo?: boolean;
+    /** Simple form fields, shown on the confirmation step. */
+    fields?: ReadonlyArray<AccountActionField>;
+    handle(ctx: AccountExtensionContext, input: {
+        target: string | null;
+        fields: Record<string, string>;
+    }): Promise<AccountActionResult>;
+}
+/** Where a page sits in the console's navigation. */
+export interface AccountPageNav {
+    label?: Text;
+    order?: number;
+    group?: 'account' | 'billing' | 'ai' | 'content';
+}
+/** One page of an extension. */
+export interface AccountPage {
+    /** Stable id `<extension>.<page>` (`'payments.subscription'`). */
+    id: string;
+    /** URL segment under the account prefix (`'billing'` → `/account/billing`). The host can rename it. */
+    segment: string;
+    title: Text;
+    /** `false` hides it from the navigation (still reachable by URL and `url()`). */
+    nav?: AccountPageNav | false;
+    /** Show this page (and its nav entry) for this account? Default: yes. Runs once per request. */
+    visible?(ctx: AccountExtensionContext): boolean | Promise<boolean>;
+    /** Builds the page on every GET. */
+    load(ctx: AccountExtensionContext): Promise<AccountPageView>;
+    actions?: Readonly<Record<string, AccountAction>>;
+}
+/** An account console extension. */
+export interface AccountExtension {
+    /** 2–16 of `a-z`, `0-9`, `-`; unique; not a built-in screen. */
+    readonly id: string;
+    /** The contract major it was written against. authkit skips a higher one. */
+    readonly contract: number;
+    /** `locale → key → text`; keys start with `<id>.`. The host's `i18n.messages` still win. */
+    messages?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** https origins its `component` blocks may load scripts from (`'https://js.stripe.com'`). */
+    scriptOrigins?: readonly string[];
+    pages: readonly AccountPage[];
+}
+/** The registry bound at {@link ACCOUNT_EXTENSIONS_BINDING}. */
+export interface AccountExtensionRegistry {
+    readonly contract: number;
+    /** Block kinds this authkit renders. */
+    readonly blockKinds: readonly string[];
+    register(extension: AccountExtension): void;
+}
+/** Host controls for one extension (`accountConsole.extensions` in `config/authkit.ts`). */
+export type AccountExtensionOverride = false | {
+    pages?: Record<string, false | {
+        segment?: string;
+        order?: number;
+    }>;
+};

package/build/src/account_extensions/contract.js

@@ -0,0 +1,37 @@
+/** Account console extensions: the contract every authkit package and contributor shares. */
+/**
+ * Account console extensions — the surface another package (or the app) uses to add pages to the
+ * signed-in user's own console (`/account/*`).
+ *
+ * **Stable for all of 1.x.** A 1.x release only adds optional members and new block kinds. This
+ * module holds types and constants only, so a contributor can `import type` it from an internal
+ * module without a runtime dependency on authkit.
+ *
+ * A contributor registers itself from its provider's `boot()`:
+ *
+ * ```ts
+ * if (this.app.container.hasBinding('authkit.accountExtensions')) {
+ *   const registry = await this.app.container.make('authkit.accountExtensions')
+ *   if (registry.contract >= 1) registry.register(myAccountExtension)
+ * }
+ * ```
+ *
+ * Everything a page returns ({@link AccountPageView}, {@link AccountActionResult}) is plain JSON
+ * (dates may be `Date` or ISO strings), so the same page can also be served from another app.
+ */
+/** The container binding the registry is bound at. */
+export const ACCOUNT_EXTENSIONS_BINDING = 'authkit.accountExtensions';
+/** The contract major this authkit implements. */
+export const ACCOUNT_EXTENSION_CONTRACT = 1;
+/** Block kinds this authkit renders. A contributor degrades when one it needs is missing. */
+export const ACCOUNT_BLOCK_KINDS = [
+    'notice',
+    'keyValue',
+    'list',
+    'table',
+    'meter',
+    'actions',
+    'link',
+    'toolPreview',
+    'component',
+];

package/build/src/account_extensions/remote.d.ts

@@ -0,0 +1,137 @@
+import type { AccountActionField, AccountActionResult, AccountActiveOrg, AccountExtension, AccountPageNav, AccountPageView, AccountSubject, AccountTenantRef, Text } from './contract.js';
+/**
+ * Remote account extensions: the wire between an authkit IdP (which renders the account console)
+ * and an app that signs in through it (which owns the extensions: billing, files, agents…).
+ *
+ * The app serves `GET {WELL_KNOWN}` (the manifest) and `POST {WELL_KNOWN}` (one call: visible,
+ * load or action). The IdP calls both with a short-lived JWT it signs with its own keys:
+ * `typ` {@link ACCOUNT_EXTENSIONS_TOKEN_TYP}, `aud` = the app's client id, `scope`
+ * {@link ACCOUNT_EXTENSIONS_SCOPE}, `sub` = the account (or {@link ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT}
+ * for the manifest) and `bh` = {@link accountExtensionsBodyHash} of the POST body.
+ */
+/** Wire version of the manifest and calls. */
+export declare const ACCOUNT_EXTENSIONS_WIRE_VERSION = 1;
+/** The scope every remote-extension token carries. */
+export declare const ACCOUNT_EXTENSIONS_SCOPE = "authkit:account-extensions";
+/** The JWT `typ` of a remote-extension token (never accepted as an access token elsewhere). */
+export declare const ACCOUNT_EXTENSIONS_TOKEN_TYP = "agora-account-ext+jwt";
+/** Path the app serves the manifest (GET) and the calls (POST) at. */
+export declare const ACCOUNT_EXTENSIONS_WELL_KNOWN = "/.well-known/agora-account-extensions";
+/** `sub` of the token that fetches the manifest (no account involved). */
+export declare const ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT = "authkit:account-console";
+/** Longest lifetime (seconds) a remote-extension token may have. */
+export declare const ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL = 300;
+/** One action, as the manifest describes it (the handler stays in the app). */
+export interface RemoteActionManifest {
+    label: Text;
+    tone: 'default' | 'danger';
+    confirm: Text | null;
+    sudo: boolean;
+    fields: AccountActionField[];
+}
+/** One page, as the manifest describes it. */
+export interface RemotePageManifest {
+    id: string;
+    segment: string;
+    title: Text;
+    nav: AccountPageNav | false;
+    /** The page has a `visible()`: the IdP asks before showing it. */
+    conditional: boolean;
+    actions: Record<string, RemoteActionManifest>;
+}
+/** One extension, as the manifest describes it. */
+export interface RemoteExtensionManifest {
+    id: string;
+    contract: number;
+    messages: Record<string, Record<string, string>>;
+    scriptOrigins: string[];
+    pages: RemotePageManifest[];
+}
+/** What `GET {WELL_KNOWN}` answers. */
+export interface AccountExtensionsManifest {
+    version: 1;
+    contract: number;
+    extensions: RemoteExtensionManifest[];
+}
+/** The signed-in account, as the IdP sends it. */
+export interface RemoteAccount {
+    id: string;
+    email: string | null;
+    name: string | null;
+    roles: string[];
+}
+interface RemoteCallBase {
+    account: RemoteAccount;
+    activeOrg: AccountActiveOrg | null;
+    tenant: AccountTenantRef | null;
+    impersonatedBy: string | null;
+    locale: string;
+    /** IdP paths of this app's pages (`pageId → /account/billing`), for `ctx.url()`. */
+    urls: Record<string, string>;
+}
+/** The body of `POST {WELL_KNOWN}`. */
+export type RemoteCall = (RemoteCallBase & {
+    op: 'visible';
+    pageIds: string[];
+}) | (RemoteCallBase & {
+    op: 'load';
+    pageId: string;
+    query: {
+        cursor?: string;
+        tab?: string;
+    };
+}) | (RemoteCallBase & {
+    op: 'action';
+    pageId: string;
+    action: string;
+    query: {
+        cursor?: string;
+        tab?: string;
+    };
+    input: {
+        target: string | null;
+        fields: Record<string, string>;
+    };
+});
+/** What a call answers (status 200), or an `error` with another status. */
+export type RemoteCallResponse = {
+    visible: string[];
+} | {
+    view: AccountPageView;
+} | {
+    result: AccountActionResult;
+} | {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** `bh` claim: base64url SHA-256 of the exact POST body. */
+export declare function accountExtensionsBodyHash(body: string): string;
+/** The manifest of these extensions. */
+export declare function buildAccountExtensionsManifest(extensions: readonly AccountExtension[], contract: number): AccountExtensionsManifest;
+/** Validates a call body; `null` when it is malformed. */
+export declare function parseAccountExtensionCall(raw: unknown): RemoteCall | null;
+export interface RunAccountExtensionCallOptions {
+    /** Maps the account to the app's subject. Default `{ type: 'User', id: account.id }`. */
+    subject?: (account: RemoteAccount, context: {
+        activeOrg: AccountActiveOrg | null;
+        tenant: AccountTenantRef | null;
+    }) => AccountSubject | Promise<AccountSubject>;
+    /** Resolves a container binding for the extensions. */
+    make: (binding: string) => Promise<any>;
+    loadTimeoutMs?: number;
+    actionTimeoutMs?: number;
+    now?: () => Date;
+    /** Where a throwing extension is reported (never sent to the IdP). */
+    log?: (message: string) => void;
+}
+/**
+ * Runs one call against the app's extensions with the same rules as in the IdP's own process:
+ * time budgets, declared action fields only, and a failure that stays inside the page.
+ */
+export declare function runAccountExtensionCall(extensions: readonly AccountExtension[], call: RemoteCall, options: RunAccountExtensionCallOptions): Promise<{
+    status: number;
+    body: RemoteCallResponse;
+}>;
+export {};

package/build/src/account_extensions/remote.js

@@ -0,0 +1,286 @@
+import { createHash } from 'node:crypto';
+/**
+ * Remote account extensions: the wire between an authkit IdP (which renders the account console)
+ * and an app that signs in through it (which owns the extensions: billing, files, agents…).
+ *
+ * The app serves `GET {WELL_KNOWN}` (the manifest) and `POST {WELL_KNOWN}` (one call: visible,
+ * load or action). The IdP calls both with a short-lived JWT it signs with its own keys:
+ * `typ` {@link ACCOUNT_EXTENSIONS_TOKEN_TYP}, `aud` = the app's client id, `scope`
+ * {@link ACCOUNT_EXTENSIONS_SCOPE}, `sub` = the account (or {@link ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT}
+ * for the manifest) and `bh` = {@link accountExtensionsBodyHash} of the POST body.
+ */
+/** Wire version of the manifest and calls. */
+export const ACCOUNT_EXTENSIONS_WIRE_VERSION = 1;
+/** The scope every remote-extension token carries. */
+export const ACCOUNT_EXTENSIONS_SCOPE = 'authkit:account-extensions';
+/** The JWT `typ` of a remote-extension token (never accepted as an access token elsewhere). */
+export const ACCOUNT_EXTENSIONS_TOKEN_TYP = 'agora-account-ext+jwt';
+/** Path the app serves the manifest (GET) and the calls (POST) at. */
+export const ACCOUNT_EXTENSIONS_WELL_KNOWN = '/.well-known/agora-account-extensions';
+/** `sub` of the token that fetches the manifest (no account involved). */
+export const ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT = 'authkit:account-console';
+/** Longest lifetime (seconds) a remote-extension token may have. */
+export const ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL = 300;
+/** `bh` claim: base64url SHA-256 of the exact POST body. */
+export function accountExtensionsBodyHash(body) {
+    return createHash('sha256').update(body).digest('base64url');
+}
+/** The manifest of these extensions. */
+export function buildAccountExtensionsManifest(extensions, contract) {
+    return {
+        version: ACCOUNT_EXTENSIONS_WIRE_VERSION,
+        contract,
+        extensions: extensions.map((extension) => ({
+            id: extension.id,
+            contract: extension.contract,
+            messages: Object.fromEntries(Object.entries(extension.messages ?? {}).map(([locale, catalog]) => [
+                locale,
+                { ...catalog },
+            ])),
+            scriptOrigins: [...(extension.scriptOrigins ?? [])],
+            pages: extension.pages.map((page) => ({
+                id: page.id,
+                segment: page.segment,
+                title: page.title,
+                nav: page.nav === false ? false : { ...(page.nav ?? {}) },
+                conditional: typeof page.visible === 'function',
+                actions: Object.fromEntries(Object.entries(page.actions ?? {}).map(([name, action]) => [
+                    name,
+                    {
+                        label: action.label,
+                        tone: action.tone === 'danger' ? 'danger' : 'default',
+                        confirm: action.confirm ?? null,
+                        sudo: action.sudo === true,
+                        fields: (action.fields ?? []).map((field) => ({ ...field })),
+                    },
+                ])),
+            })),
+        })),
+    };
+}
+// ── parsing a call ────────────────────────────────────────────────────────────────────────────────
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v, max = 512) => typeof v === 'string' && v.length > 0 && v.length <= max ? v : null;
+const strOrNull = (v, max = 512) => (v === null ? null : str(v, max));
+function parseQuery(raw) {
+    const out = {};
+    if (!isObject(raw))
+        return out;
+    const cursor = str(raw.cursor);
+    if (cursor)
+        out.cursor = cursor;
+    const tab = raw.tab;
+    if (typeof tab === 'string' && /^[a-zA-Z0-9_-]{1,64}$/.test(tab))
+        out.tab = tab;
+    return out;
+}
+function parseOrg(raw) {
+    if (!isObject(raw))
+        return null;
+    const id = str(raw.id);
+    if (!id)
+        return null;
+    return { id, slug: String(raw.slug ?? ''), role: String(raw.role ?? '') };
+}
+function parseTenant(raw) {
+    if (!isObject(raw))
+        return null;
+    const id = str(raw.id);
+    const kind = str(raw.kind, 64);
+    if (!id || !kind)
+        return null;
+    const tenant = { id, kind, source: str(raw.source, 64) ?? 'authkit' };
+    const slug = str(raw.slug);
+    if (slug)
+        tenant.slug = slug;
+    const role = str(raw.role, 128);
+    if (role)
+        tenant.role = role;
+    if (Array.isArray(raw.chain)) {
+        tenant.chain = raw.chain.filter(isObject).flatMap((level) => {
+            const levelId = str(level.id);
+            const levelKind = str(level.kind, 64);
+            if (!levelId || !levelKind)
+                return [];
+            const out = { id: levelId, kind: levelKind };
+            const levelSlug = str(level.slug);
+            if (levelSlug)
+                out.slug = levelSlug;
+            const levelRole = str(level.role, 128);
+            if (levelRole)
+                out.role = levelRole;
+            return [out];
+        });
+    }
+    return tenant;
+}
+/** Validates a call body; `null` when it is malformed. */
+export function parseAccountExtensionCall(raw) {
+    if (!isObject(raw) || !isObject(raw.account))
+        return null;
+    const accountId = str(raw.account.id);
+    if (!accountId)
+        return null;
+    const roles = Array.isArray(raw.account.roles)
+        ? raw.account.roles.filter((r) => typeof r === 'string')
+        : [];
+    const urls = {};
+    if (isObject(raw.urls)) {
+        for (const [pageId, path] of Object.entries(raw.urls)) {
+            if (typeof path === 'string' && path.startsWith('/') && !path.startsWith('//')) {
+                urls[pageId] = path;
+            }
+        }
+    }
+    const base = {
+        account: {
+            id: accountId,
+            email: strOrNull(raw.account.email ?? null),
+            name: strOrNull(raw.account.name ?? null),
+            roles,
+        },
+        activeOrg: parseOrg(raw.activeOrg),
+        tenant: parseTenant(raw.tenant),
+        impersonatedBy: strOrNull(raw.impersonatedBy ?? null),
+        locale: str(raw.locale, 35) ?? 'en',
+        urls,
+    };
+    if (raw.op === 'visible') {
+        const pageIds = Array.isArray(raw.pageIds)
+            ? raw.pageIds.filter((id) => typeof id === 'string').slice(0, 100)
+            : [];
+        return { ...base, op: 'visible', pageIds };
+    }
+    const pageId = str(raw.pageId, 128);
+    if (!pageId)
+        return null;
+    if (raw.op === 'load')
+        return { ...base, op: 'load', pageId, query: parseQuery(raw.query) };
+    if (raw.op === 'action') {
+        const action = str(raw.action, 64);
+        if (!action || !isObject(raw.input))
+            return null;
+        const fields = {};
+        if (isObject(raw.input.fields)) {
+            for (const [name, value] of Object.entries(raw.input.fields)) {
+                if (typeof value === 'string' && value.length <= 10_000)
+                    fields[name] = value;
+            }
+        }
+        return {
+            ...base,
+            op: 'action',
+            pageId,
+            action,
+            query: parseQuery(raw.query),
+            input: { target: strOrNull(raw.input.target ?? null), fields },
+        };
+    }
+    return null;
+}
+async function within(work, ms, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms} ms`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+const err = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+/**
+ * Runs one call against the app's extensions with the same rules as in the IdP's own process:
+ * time budgets, declared action fields only, and a failure that stays inside the page.
+ */
+export async function runAccountExtensionCall(extensions, call, options) {
+    const log = options.log ?? ((message) => console.error(message));
+    const subject = options.subject
+        ? await options.subject(call.account, { activeOrg: call.activeOrg, tenant: call.tenant })
+        : { type: 'User', id: call.account.id };
+    const base = {
+        account: call.account,
+        activeOrg: call.activeOrg,
+        tenant: call.tenant,
+        subject,
+        impersonatedBy: call.impersonatedBy,
+        locale: call.locale,
+        url(pageId, query) {
+            const path = call.urls[pageId] ?? '/';
+            const qs = query
+                ? new URLSearchParams(Object.entries(query).filter(([, v]) => v !== '')).toString()
+                : '';
+            return qs ? `${path}?${qs}` : path;
+        },
+        make: options.make,
+        now: options.now ?? (() => new Date()),
+    };
+    const pages = new Map(extensions.flatMap((e) => e.pages.map((p) => [p.id, p])));
+    if (call.op === 'visible') {
+        const visible = [];
+        await Promise.all(call.pageIds.map(async (pageId) => {
+            const page = pages.get(pageId);
+            if (!page)
+                return;
+            if (typeof page.visible !== 'function') {
+                visible.push(pageId);
+                return;
+            }
+            try {
+                const shown = await within(Promise.resolve(page.visible({ ...base, query: {} })), options.loadTimeoutMs ?? 5000, 'visible()');
+                if (shown !== false)
+                    visible.push(pageId);
+            }
+            catch (error) {
+                log(`authkit: account extension page "${pageId}" visible() failed: ${String(error)}`);
+            }
+        }));
+        return { status: 200, body: { visible: visible.sort() } };
+    }
+    const page = pages.get(call.pageId);
+    if (!page)
+        return err(404, 'not_found', 'No such page.');
+    const ctx = { ...base, query: call.query };
+    if (call.op === 'load') {
+        try {
+            const view = await within(page.load(ctx), options.loadTimeoutMs ?? 5000, 'load()');
+            if (!view || typeof view !== 'object' || !Array.isArray(view.blocks)) {
+                throw new Error('load() must return { blocks: [...] }');
+            }
+            return { status: 200, body: { view } };
+        }
+        catch (error) {
+            log(`authkit: account extension page "${call.pageId}" load() failed: ${String(error)}`);
+            return err(502, 'load_failed', 'The page could not be loaded.');
+        }
+    }
+    const actions = page.actions ?? {};
+    const action = Object.hasOwn(actions, call.action) ? actions[call.action] : undefined;
+    if (!action)
+        return err(404, 'not_found', 'No such action.');
+    const fields = {};
+    for (const field of action.fields ?? []) {
+        const value = call.input.fields[field.name];
+        if (typeof value === 'string')
+            fields[field.name] = value;
+    }
+    try {
+        const result = await within(action.handle(ctx, { target: call.input.target, fields }), options.actionTimeoutMs ?? 15_000, 'handle()');
+        if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+            throw new Error('handle() must return { ok: true | false, … }');
+        }
+        return { status: 200, body: { result } };
+    }
+    catch (error) {
+        log(`authkit: account extension action "${call.pageId}.${call.action}" failed: ${String(error)}`);
+        return err(502, 'action_failed', 'The action failed.');
+    }
+}

package/build/src/account_extensions/validate.d.ts

@@ -0,0 +1,30 @@
+import { type AccountExtension, type AccountExtensionRegistry } from './contract.js';
+export declare const ACCOUNT_SEGMENT: RegExp;
+/** Segments authkit itself uses under the account prefix, whatever the host renames. */
+export declare const ACCOUNT_RESERVED_SEGMENTS: Set<string>;
+export declare class AccountExtensionError extends Error {
+}
+export declare function failAccountExtension(id: string, message: string): never;
+/** Validates an extension's own shape (no knowledge of the other extensions). */
+export declare function validateAccountExtension(extension: AccountExtension): void;
+/**
+ * The registry an authkit package binds at `authkit.accountExtensions`: validates each extension
+ * and keeps them in registration order. Throws on an invalid one outside production; in
+ * production it is skipped and logged, so one bad contributor cannot take the console down.
+ */
+export declare class BaseAccountExtensionRegistry implements AccountExtensionRegistry {
+    readonly contract = 1;
+    readonly blockKinds: readonly string[];
+    protected readonly registered: AccountExtension[];
+    protected readonly isProduction: () => boolean;
+    protected readonly log: (message: string) => void;
+    constructor(options?: {
+        production?: () => boolean;
+        log?: (message: string) => void;
+    });
+    /** Hook for subclasses: throw to refuse a registration (e.g. after a freeze). */
+    protected beforeRegister(_extension: AccountExtension): void;
+    register(extension: AccountExtension): void;
+    /** The registered extensions, in registration order. */
+    extensions(): readonly AccountExtension[];
+}

package/build/src/account_extensions/validate.js

@@ -0,0 +1,161 @@
+import { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, } from './contract.js';
+const EXTENSION_ID = /^[a-z0-9-]{2,16}$/;
+const PAGE_LOCAL_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+export const ACCOUNT_SEGMENT = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ACTION_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const FIELD_NAME = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+/** Segments authkit itself uses under the account prefix, whatever the host renames. */
+export const ACCOUNT_RESERVED_SEGMENTS = new Set([
+    'api',
+    'login',
+    'logout',
+    'security',
+    'mfa',
+    'confirm',
+    'tokens',
+    'apps',
+    'orgs',
+    'email',
+    'x',
+    'assets',
+]);
+/** Built-in screen keys (an extension id may not shadow one). */
+const BUILTIN_IDS = new Set([
+    'login',
+    'logout',
+    'security',
+    'mfa',
+    'confirm',
+    'tokens',
+    'apps',
+    'orgs',
+    'account',
+    'authkit',
+]);
+export class AccountExtensionError extends Error {
+}
+export function failAccountExtension(id, message) {
+    throw new AccountExtensionError(`authkit: account extension "${id}" — ${message}`);
+}
+function validateAction(id, pageId, name, action) {
+    if (!ACTION_NAME.test(name))
+        failAccountExtension(id, `page "${pageId}" has an invalid action name "${name}".`);
+    if (typeof action?.handle !== 'function') {
+        failAccountExtension(id, `action "${pageId}.${name}" has no handle().`);
+    }
+    for (const field of action.fields ?? []) {
+        if (!FIELD_NAME.test(field?.name ?? '')) {
+            failAccountExtension(id, `action "${pageId}.${name}" has an invalid field name "${String(field?.name)}".`);
+        }
+        if (!['text', 'select', 'textarea'].includes(field.kind)) {
+            failAccountExtension(id, `field "${field.name}" of "${pageId}.${name}" has an unknown kind.`);
+        }
+        if (field.kind === 'select' && !(field.options && field.options.length > 0)) {
+            failAccountExtension(id, `select field "${field.name}" of "${pageId}.${name}" needs options.`);
+        }
+    }
+}
+/** Validates an extension's own shape (no knowledge of the other extensions). */
+export function validateAccountExtension(extension) {
+    const id = String(extension?.id);
+    if (!EXTENSION_ID.test(id) || BUILTIN_IDS.has(id)) {
+        failAccountExtension(id, 'invalid id (2–16 of a-z, 0-9, -; not a built-in screen).');
+    }
+    if (typeof extension.contract !== 'number' || !Number.isInteger(extension.contract)) {
+        failAccountExtension(id, 'contract must be the major it was written against (1).');
+    }
+    if (extension.contract > ACCOUNT_EXTENSION_CONTRACT) {
+        failAccountExtension(id, `written against contract ${extension.contract}; this authkit implements ${ACCOUNT_EXTENSION_CONTRACT}. Upgrade @adonis-agora/authkit.`);
+    }
+    for (const [locale, catalog] of Object.entries(extension.messages ?? {})) {
+        for (const key of Object.keys(catalog ?? {})) {
+            if (!key.startsWith(`${id}.`)) {
+                failAccountExtension(id, `message key "${key}" (${locale}) must start with "${id}.".`);
+            }
+        }
+    }
+    for (const origin of extension.scriptOrigins ?? []) {
+        let parsed = null;
+        try {
+            parsed = new URL(origin);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed || parsed.protocol !== 'https:' || parsed.origin !== origin) {
+            failAccountExtension(id, `scriptOrigins entry "${origin}" must be an https origin (no path).`);
+        }
+    }
+    if (!Array.isArray(extension.pages) || extension.pages.length === 0) {
+        failAccountExtension(id, 'needs at least one page.');
+    }
+    const pageIds = new Set();
+    const segments = new Set();
+    for (const page of extension.pages) {
+        const pageId = String(page?.id);
+        const [prefix, local, ...rest] = pageId.split('.');
+        if (prefix !== id || !local || rest.length > 0 || !PAGE_LOCAL_ID.test(local)) {
+            failAccountExtension(id, `page id "${pageId}" must be "${id}.<page>" (a-z, 0-9, -).`);
+        }
+        if (pageIds.has(pageId))
+            failAccountExtension(id, `page "${pageId}" is listed twice.`);
+        pageIds.add(pageId);
+        if (!ACCOUNT_SEGMENT.test(String(page.segment)) ||
+            ACCOUNT_RESERVED_SEGMENTS.has(page.segment)) {
+            failAccountExtension(id, `page "${pageId}" has an invalid or reserved segment "${String(page.segment)}".`);
+        }
+        if (segments.has(page.segment))
+            failAccountExtension(id, `segment "${page.segment}" is used twice.`);
+        segments.add(page.segment);
+        if (typeof page.load !== 'function')
+            failAccountExtension(id, `page "${pageId}" has no load().`);
+        for (const [name, action] of Object.entries(page.actions ?? {})) {
+            validateAction(id, pageId, name, action);
+        }
+    }
+}
+/**
+ * The registry an authkit package binds at `authkit.accountExtensions`: validates each extension
+ * and keeps them in registration order. Throws on an invalid one outside production; in
+ * production it is skipped and logged, so one bad contributor cannot take the console down.
+ */
+export class BaseAccountExtensionRegistry {
+    contract = ACCOUNT_EXTENSION_CONTRACT;
+    blockKinds = ACCOUNT_BLOCK_KINDS;
+    registered = [];
+    isProduction;
+    log;
+    constructor(options = {}) {
+        this.isProduction = options.production ?? (() => false);
+        this.log = options.log ?? ((message) => console.error(message));
+    }
+    /** Hook for subclasses: throw to refuse a registration (e.g. after a freeze). */
+    beforeRegister(_extension) { }
+    register(extension) {
+        this.beforeRegister(extension);
+        try {
+            validateAccountExtension(extension);
+            if (this.registered.some((e) => e.id === extension.id)) {
+                failAccountExtension(extension.id, 'is registered twice.');
+            }
+            for (const other of this.registered) {
+                for (const page of extension.pages) {
+                    if (other.pages.some((p) => p.segment === page.segment)) {
+                        failAccountExtension(extension.id, `segment "${page.segment}" is already used by "${other.id}".`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (!this.isProduction())
+                throw error;
+            this.log(`${error.message} The extension is skipped.`);
+            return;
+        }
+        this.registered.push(extension);
+    }
+    /** The registered extensions, in registration order. */
+    extensions() {
+        return this.registered;
+    }
+}

package/build/src/types/server_config.d.ts

@@ -1,36 +1,3 @@
-/**
- * Client OIDC persistido no adapter/DB, gerenciável via console admin ou Admin API
- * em runtime. Usado internamente pela lib para representar clients em memória.
- */
-export interface ClientConfig {
-    clientId: string;
-    clientSecret?: string;
-    redirectUris: string[];
-    postLogoutRedirectUris?: string[];
-    grants?: string[];
-    /** 'none' para public clients (SPA com PKCE) */
-    tokenEndpointAuthMethod?: 'client_secret_basic' | 'client_secret_post' | 'none';
-    /**
-     * Tipo de aplicação (OIDC Registration §2, `application_type`). Default `'web'`.
-     *
-     * `'native'` (RFC 8252 — OAuth 2.0 for Native Apps) libera os redirects de app
-     * mobile/desktop: esquema privado (`com.example.app:/callback`), URL https
-     * "claimed" (universal/app links) e loopback `http://127.0.0.1` com qualquer
-     * porta. Client nativo é SEMPRE público (sem `clientSecret`,
-     * `tokenEndpointAuthMethod: 'none'`) — PKCE já é obrigatório no issuer.
-     */
-    applicationType?: 'web' | 'native';
-    /**
-     * Endpoint do RP que recebe o POST de OIDC Back-Channel Logout. Quando definido,
-     * o IdP envia um `logout_token` para esta URI ao encerrar a sessão/grant do usuário.
-     */
-    backchannelLogoutUri?: string;
-    /**
-     * Exige que o `logout_token` inclua a claim `sid` (session id). Mapeado para
-     * `backchannel_logout_session_required` do oidc-provider. Default: false.
-     */
-    backchannelLogoutSessionRequired?: boolean;
-}
 export interface TtlConfig {
     accessToken?: string | number;
     refreshToken?: string | number;
@@ -146,7 +113,6 @@ export interface AccessTokensConfig {
 /** Forma normalizada do config do server (pós-`defineConfig`). */
 export interface ResolvedAuthServerConfig {
     issuer: string;
-    clients: ClientConfig[];
     ttl: Required<TtlConfig>;
     jwks: JwksConfig;
     globalRolesClaim: string;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adonis-agora/authkit-core",
-  "version": "0.10.1",
+  "version": "1.0.0-rc.1",
   "description": "Shared core types and utilities for AuthKit — the AdonisJS OIDC/OAuth2 server and client toolkits.",
   "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-core"
   },
   "homepage": "https://davidecarvalho.github.io/agora/docs/authkit",
@@ -28,7 +28,8 @@
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "files": [
-    "build"
+    "build",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": "./build/index.js",
@@ -43,8 +44,8 @@
     "@adonisjs/tsconfig": "2.0.0",
     "@japa/assert": "4.2.0",
     "@japa/runner": "5.4.0",
-    "@poppinss/ts-exec": "1.5.1",
-    "@types/node": "26.6.5",
+    "@poppinss/ts-exec": "1.5.2",
+    "@types/node": "26.6.6",
     "typescript": "7.0.2"
   },
   "scripts": {