@adonis-agora/authkit-client 1.0.0-rc.3 → 1.0.0-rc.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @adonis-agora/authkit-client
 
+## 1.0.0-rc.5
+
+### 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`).
+
+### Patch Changes
+
+- Updated dependencies [[`66ccc36`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/66ccc365dbbd7d9d5bf22dba7aad196aff9f5d4b)]:
+  - @adonis-agora/authkit-core@1.0.0-rc.1
+
+## 1.0.0-rc.4
+
+### Minor Changes
+
+- [#465](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/465) [`6bd9575`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/6bd95759752c0fac14a061875abebb38c0e238b7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - The active organization is published as the request's tenant in `@adonis-agora/context`: `Context.tenant()` returns `{ id, kind: 'organization', source: 'authkit', slug, role }` (and `tenantId` as before). New client option `tenancy`: `eager` resolves the session at request start (default on when `config/context.ts` enables tenancy and the resolver is `jwt`), `personal` makes the user the tenant when there is no active organization (off by default), and `resolve` maps the session to your own (optionally nested) tenants. A tenant the app sets itself with `Context.setTenant` is never overwritten. authkit-server ships `authkitTenantLabels()`, a label resolver for `config/context.ts` → `tenancy.label` that shows organization names in the consoles, and account stores gain the optional `findOrgsByIds` (implemented by the Lucid store).
+
 ## 1.0.0-rc.3
 
 ### Patch Changes

package/build/index.d.ts

@@ -2,12 +2,14 @@ export type { Identity } from '@adonis-agora/authkit-core';
 export { configure } from './commands/configure.js';
 export type { AuthkitClientLogger, AuthkitClientManagerDeps, } from './providers/authkit_client_provider.js';
 export { AuthkitClientManager } from './providers/authkit_client_provider.js';
+export type { AccountExtensionsAnswer, AccountExtensionsVerifier, ServeAccountExtensionsInput, } from './src/account_extensions.js';
+export { ACCOUNT_EXTENSIONS_BINDING, ClientAccountExtensionRegistry, serveAccountExtensions, verifyAccountExtensionsToken, } from './src/account_extensions.js';
 export { Authenticator } from './src/authenticator.js';
 export type { AuthorizationRequest, CompleteAuthorizationParams, CompletedAuthorization, CreateAuthorizationRequestParams, OidcCallbackErrorCode, PendingAuthorization, } from './src/authorization.js';
 export { completeAuthorization, createAuthorizationRequest, OidcCallbackError, } from './src/authorization.js';
 export type { SessionIndex, SessionIndexEntry, ValidatedLogoutToken, ValidateLogoutTokenOptions, } from './src/backchannel_logout.js';
 export { BACKCHANNEL_LOGOUT_EVENT, InMemorySessionIndex, InvalidLogoutTokenError, validateLogoutToken, } from './src/backchannel_logout.js';
-export type { BackchannelLogoutCallback, BackchannelLogoutInput, ClientConfigInput, ResolvedClientConfig, } from './src/define_config.js';
+export type { BackchannelLogoutCallback, BackchannelLogoutInput, ClientAccountConsoleConfig, ClientConfigInput, ResolvedClientConfig, } from './src/define_config.js';
 export { defineConfig, resolvers } from './src/define_config.js';
 export type { DiscoverOptions, OidcEndpoints } from './src/discovery.js';
 export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
@@ -30,10 +32,11 @@ export { default as AuthkitContextMiddleware } from './src/middleware/authkit_co
 export { default as BackchannelRevocationMiddleware } from './src/middleware/backchannel_revocation_middleware.js';
 export type { RequireOrgMiddlewareOptions } from './src/middleware/require_org_middleware.js';
 export { default as RequireOrgMiddleware } from './src/middleware/require_org_middleware.js';
+export type { ClientTenancyOptions, ContextTenant, ContextTenantLink, TenantInput, } from './src/observability/context_bridge.js';
 export type { AuthorizeParams, EndSessionParams, ExchangeParams, RefreshParams, } from './src/oidc_login.js';
 export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, generatePkce, refreshTokens, } from './src/oidc_login.js';
 export type { PostLoginRedirects, RegisterOidcClientOptions, } from './src/register_oidc_client.js';
-export { registerOidcClient } from './src/register_oidc_client.js';
+export { registerAccountExtensionsEndpoint, registerOidcClient, } from './src/register_oidc_client.js';
 export type { LucidRevocationStoreOptions, RevocationStore, } from './src/revocation/revocation_store.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
 export { AuthkitTenantToken, type AuthkitTenantTokenFn, type AuthkitTenantTokenOptions, authkitTenantToken, TenantTokenError, } from './src/tenant_token.js';

package/build/index.js

@@ -1,5 +1,6 @@
 export { configure } from './commands/configure.js';
 export { AuthkitClientManager } from './providers/authkit_client_provider.js';
+export { ACCOUNT_EXTENSIONS_BINDING, ClientAccountExtensionRegistry, serveAccountExtensions, verifyAccountExtensionsToken, } from './src/account_extensions.js';
 export { Authenticator } from './src/authenticator.js';
 export { completeAuthorization, createAuthorizationRequest, OidcCallbackError, } from './src/authorization.js';
 export { BACKCHANNEL_LOGOUT_EVENT, InMemorySessionIndex, InvalidLogoutTokenError, validateLogoutToken, } from './src/backchannel_logout.js';
@@ -17,7 +18,7 @@ export { default as AuthkitContextMiddleware } from './src/middleware/authkit_co
 export { default as BackchannelRevocationMiddleware } from './src/middleware/backchannel_revocation_middleware.js';
 export { default as RequireOrgMiddleware } from './src/middleware/require_org_middleware.js';
 export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, generatePkce, refreshTokens, } from './src/oidc_login.js';
-export { registerOidcClient } from './src/register_oidc_client.js';
+export { registerAccountExtensionsEndpoint, registerOidcClient, } from './src/register_oidc_client.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
 export { AuthkitTenantToken, authkitTenantToken, TenantTokenError, } from './src/tenant_token.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';

package/build/providers/authkit_client_provider.d.ts

@@ -97,6 +97,12 @@ export declare class AuthkitClientManager {
      * Sempre seta `Cache-Control: no-store` (exigência do spec).
      */
     handleBackchannelLogout(ctx: HttpContext): Promise<unknown>;
+    /**
+     * Answers the IdP's account console (`GET`/`POST /.well-known/agora-account-extensions`): the
+     * manifest of this app's account extensions, or one call to them. 404 unless
+     * `accountConsole.remote` is on. Mounted by {@link registerOidcClient}.
+     */
+    handleAccountExtensions(ctx: HttpContext): Promise<unknown>;
     /**
      * Impersona `requestedSubject` via token-exchange (RFC 8693): guarda o token set
      * atual e o substitui pelo do alvo. Encapsula o malabarismo de session keys que o
@@ -162,6 +168,13 @@ export declare class AuthkitClientManager {
      * sobrevive à sessão que a parqueou.
      */
     startSession(ctx: HttpContext, tokenSet: TokenSet): void;
+    /**
+     * Whether `authkit_context_middleware` resolves the session at request start, so
+     * the tenant is in `@adonis-agora/context` before any handler runs. `tenancy.eager`
+     * when set; otherwise `true` only when context tenancy is enabled and the resolver
+     * is `resolvers.jwt()` (local verify, no network).
+     */
+    eagerTenancy(): boolean;
     /**
      * The request's {@link Authenticator}. `options.resolver` replaces the configured
      * resolver for this authenticator only (e.g. a guard for bearer-token API routes).

package/build/providers/authkit_client_provider.js

@@ -5,12 +5,14 @@ import { randomUUID } from 'node:crypto';
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { decodeJwt } from 'jose';
+import { ACCOUNT_EXTENSIONS_BINDING, ClientAccountExtensionRegistry, serveAccountExtensions, } from '../src/account_extensions.js';
 import { Authenticator } from '../src/authenticator.js';
 import { assertCallbackBelongs, completeAuthorization, createAuthorizationRequest, } from '../src/authorization.js';
 import { validateLogoutToken } from '../src/backchannel_logout.js';
 import { conventionEndpoints, discoverEndpoints, mergeEndpoints, } from '../src/discovery.js';
 import { validateIdToken, } from '../src/id_token.js';
 import { getJwks } from '../src/jwks.js';
+import { contextTenancyEnabled } from '../src/observability/context_bridge.js';
 import { exchangeToken, refreshTokens } from '../src/oidc_login.js';
 /** Margem (ms) antes do `expiresAt` em que o access token é renovado proativamente. */
 const REFRESH_SKEW_MS = 60_000;
@@ -322,6 +324,44 @@ export class AuthkitClientManager {
         });
         return {};
     }
+    /**
+     * Answers the IdP's account console (`GET`/`POST /.well-known/agora-account-extensions`): the
+     * manifest of this app's account extensions, or one call to them. 404 unless
+     * `accountConsole.remote` is on. Mounted by {@link registerOidcClient}.
+     */
+    async handleAccountExtensions(ctx) {
+        const { request, response } = ctx;
+        response.header('Cache-Control', 'no-store');
+        const settings = this.config.accountConsole;
+        if (!settings?.remote)
+            return response.status(404).send({ error: { code: 'not_found' } });
+        let idp;
+        try {
+            idp = await this.#idp();
+        }
+        catch (error) {
+            this.#logger.warn({ err: error, issuer: this.config.issuer }, 'authkit-client: account extensions called while discovery is failing');
+            return response.status(503).send({ error: { code: 'temporarily_unavailable' } });
+        }
+        const resolver = ctx.containerResolver;
+        const registry = (await resolver.make(ACCOUNT_EXTENSIONS_BINDING));
+        const method = request.method();
+        const raw = method === 'POST' ? request.raw() : null;
+        const answer = await serveAccountExtensions({
+            method,
+            authorization: request.header('authorization'),
+            rawBody: typeof raw === 'string' ? raw : null,
+            extensions: typeof registry.extensions === 'function' ? registry.extensions() : [],
+            contract: registry.contract,
+            verifier: { issuer: idp.endpoints.issuer, clientId: this.config.clientId, keys: idp.keys },
+            config: settings,
+            make: (binding) => resolver.make(binding),
+            log: (message) => this.#logger.warn({}, message),
+        });
+        for (const [name, value] of Object.entries(answer.headers ?? {}))
+            response.header(name, value);
+        return response.status(answer.status).send(answer.body);
+    }
     /** Chave de sessão onde o token set ORIGINAL fica guardado durante a impersonação. */
     get #impersonatorKey() {
         return `${this.config.sessionKey}_impersonator`;
@@ -457,6 +497,18 @@ export class AuthkitClientManager {
         session.forget(this.#impersonatorKey);
         session.put(this.config.sessionKey, tokenSet);
     }
+    /**
+     * Whether `authkit_context_middleware` resolves the session at request start, so
+     * the tenant is in `@adonis-agora/context` before any handler runs. `tenancy.eager`
+     * when set; otherwise `true` only when context tenancy is enabled and the resolver
+     * is `resolvers.jwt()` (local verify, no network).
+     */
+    eagerTenancy() {
+        const eager = this.config.tenancy?.eager;
+        if (typeof eager === 'boolean')
+            return eager;
+        return this.config.resolverFactory?.kind === 'jwt' && contextTenancyEnabled();
+    }
     /**
      * The request's {@link Authenticator}. `options.resolver` replaces the configured
      * resolver for this authenticator only (e.g. a guard for bearer-token API routes).
@@ -467,6 +519,7 @@ export class AuthkitClientManager {
         return new Authenticator(ctx, {
             resolver,
             resolveUser: this.config.resolveUser,
+            tenancy: this.config.tenancy,
             getAccessToken: () => {
                 const tokenSet = ctx.session?.get(sessionKey);
                 return tokenSet?.accessToken;
@@ -497,6 +550,14 @@ export default class AuthkitClientProvider {
         // bound by class, would silently get the real one. Not cached here, so a `swap` of the class
         // also reaches the string key, even after its first use.
         this.app.container.bind('authkit.client', (resolver) => resolver.make(AuthkitClientManager));
+        // Account console extensions register here from their `boot()`, exactly as next to
+        // authkit-server. When authkit-server is in this app too, its registry is the one bound.
+        if (!this.app.container.hasBinding(ACCOUNT_EXTENSIONS_BINDING)) {
+            const registry = new ClientAccountExtensionRegistry({
+                production: () => this.app.inProduction === true,
+            });
+            this.app.container.singleton(ACCOUNT_EXTENSIONS_BINDING, async () => registry);
+        }
     }
 }
 /** `sub` of a stored id_token, or undefined when there is none / it is unreadable. */

package/build/src/account_extensions.d.ts

@@ -0,0 +1,49 @@
+import { type AccountExtension, BaseAccountExtensionRegistry } from '@adonis-agora/authkit-core';
+import { type JWTPayload, type JWTVerifyGetKey } from 'jose';
+import type { ClientAccountConsoleConfig } from './define_config.js';
+/** The container binding contributors register into (same name as authkit-server's). */
+export declare const ACCOUNT_EXTENSIONS_BINDING = "authkit.accountExtensions";
+/**
+ * The account extensions registry of an app whose IdP runs elsewhere. Contributors register
+ * exactly as they would next to authkit-server; this app then serves the pages to the IdP.
+ */
+export declare class ClientAccountExtensionRegistry extends BaseAccountExtensionRegistry {
+}
+/** What verifying a remote-extension token needs. */
+export interface AccountExtensionsVerifier {
+    issuer: string;
+    clientId: string;
+    keys: JWTVerifyGetKey;
+}
+/** A refusal: `status` plus the JSON body to send. */
+export interface AccountExtensionsAnswer {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+/** Verifies the IdP's token: signature, issuer, audience, `typ`, lifetime and scope. */
+export declare function verifyAccountExtensionsToken(authorization: string | undefined, verifier: AccountExtensionsVerifier): Promise<{
+    ok: true;
+    claims: JWTPayload;
+} | {
+    ok: false;
+    answer: AccountExtensionsAnswer;
+}>;
+export interface ServeAccountExtensionsInput {
+    method: string;
+    authorization: string | undefined;
+    /** The exact POST body (its hash is signed by the IdP). */
+    rawBody: string | null;
+    extensions: readonly AccountExtension[];
+    contract: number;
+    verifier: AccountExtensionsVerifier;
+    config: ClientAccountConsoleConfig;
+    make: (binding: string) => Promise<any>;
+    log?: (message: string) => void;
+}
+/**
+ * Answers the IdP: `GET` → the manifest, `POST` → one call (visible, load or action). Only a token
+ * the IdP signed for this app (audience = client id, scope `authkit:account-extensions`) gets in;
+ * a POST must also match the signed body hash and name the token's account.
+ */
+export declare function serveAccountExtensions(input: ServeAccountExtensionsInput): Promise<AccountExtensionsAnswer>;

package/build/src/account_extensions.js

@@ -0,0 +1,105 @@
+import { ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT, ACCOUNT_EXTENSIONS_SCOPE, ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL, ACCOUNT_EXTENSIONS_TOKEN_TYP, accountExtensionsBodyHash, BaseAccountExtensionRegistry, buildAccountExtensionsManifest, parseAccountExtensionCall, runAccountExtensionCall, } from '@adonis-agora/authkit-core';
+import { jwtVerify } from 'jose';
+import { DEFAULT_ALGS } from './jwks.js';
+/** The container binding contributors register into (same name as authkit-server's). */
+export const ACCOUNT_EXTENSIONS_BINDING = 'authkit.accountExtensions';
+/**
+ * The account extensions registry of an app whose IdP runs elsewhere. Contributors register
+ * exactly as they would next to authkit-server; this app then serves the pages to the IdP.
+ */
+export class ClientAccountExtensionRegistry extends BaseAccountExtensionRegistry {
+}
+const refuse = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+    ...(status === 401
+        ? {
+            headers: {
+                'WWW-Authenticate': `Bearer error="${code}", scope="${ACCOUNT_EXTENSIONS_SCOPE}"`,
+            },
+        }
+        : {}),
+});
+/** Verifies the IdP's token: signature, issuer, audience, `typ`, lifetime and scope. */
+export async function verifyAccountExtensionsToken(authorization, verifier) {
+    const match = /^Bearer\s+(\S+)$/i.exec(authorization ?? '');
+    if (!match?.[1]) {
+        return { ok: false, answer: refuse(401, 'invalid_token', 'A bearer token is required.') };
+    }
+    let claims;
+    try {
+        ({ payload: claims } = await jwtVerify(match[1], verifier.keys, {
+            issuer: verifier.issuer,
+            audience: verifier.clientId,
+            typ: ACCOUNT_EXTENSIONS_TOKEN_TYP,
+            algorithms: DEFAULT_ALGS,
+            maxTokenAge: ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL,
+            requiredClaims: ['exp', 'iat', 'sub'],
+        }));
+    }
+    catch {
+        return { ok: false, answer: refuse(401, 'invalid_token', 'The token is not valid.') };
+    }
+    if (claims.exp - claims.iat > ACCOUNT_EXTENSIONS_TOKEN_MAX_TTL) {
+        return { ok: false, answer: refuse(401, 'invalid_token', 'The token lives too long.') };
+    }
+    const scopes = typeof claims.scope === 'string' ? claims.scope.split(' ') : [];
+    if (!scopes.includes(ACCOUNT_EXTENSIONS_SCOPE)) {
+        return {
+            ok: false,
+            answer: refuse(403, 'insufficient_scope', `The token lacks "${ACCOUNT_EXTENSIONS_SCOPE}".`),
+        };
+    }
+    return { ok: true, claims };
+}
+/**
+ * Answers the IdP: `GET` → the manifest, `POST` → one call (visible, load or action). Only a token
+ * the IdP signed for this app (audience = client id, scope `authkit:account-extensions`) gets in;
+ * a POST must also match the signed body hash and name the token's account.
+ */
+export async function serveAccountExtensions(input) {
+    const verified = await verifyAccountExtensionsToken(input.authorization, input.verifier);
+    if (!verified.ok)
+        return verified.answer;
+    const { claims } = verified;
+    if (input.method === 'GET') {
+        if (claims.sub !== ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT) {
+            return refuse(403, 'invalid_token', 'This token is not for the manifest.');
+        }
+        return { status: 200, body: buildAccountExtensionsManifest(input.extensions, input.contract) };
+    }
+    if (input.method !== 'POST') {
+        return {
+            status: 405,
+            body: { error: { code: 'method_not_allowed', message: 'GET or POST.' } },
+        };
+    }
+    if (input.rawBody === null || claims.bh !== accountExtensionsBodyHash(input.rawBody)) {
+        return refuse(403, 'invalid_token', 'The token does not match the body.');
+    }
+    let raw;
+    try {
+        raw = JSON.parse(input.rawBody);
+    }
+    catch {
+        raw = null;
+    }
+    const call = parseAccountExtensionCall(raw);
+    if (!call) {
+        return { status: 400, body: { error: { code: 'invalid_request', message: 'Bad call.' } } };
+    }
+    if (call.account.id !== claims.sub) {
+        return refuse(403, 'invalid_token', 'The token is for another account.');
+    }
+    return runAccountExtensionCall(input.extensions, call, {
+        ...(input.config.subject ? { subject: input.config.subject } : {}),
+        make: input.make,
+        ...(input.config.loadTimeoutMs !== undefined
+            ? { loadTimeoutMs: input.config.loadTimeoutMs }
+            : {}),
+        ...(input.config.actionTimeoutMs !== undefined
+            ? { actionTimeoutMs: input.config.actionTimeoutMs }
+            : {}),
+        ...(input.log ? { log: input.log } : {}),
+    });
+}

package/build/src/authenticator.d.ts

@@ -1,6 +1,7 @@
 import type { Identity, SessionResolver } from '@adonis-agora/authkit-core';
 import { type MetricsRecorder } from '@adonis-agora/authkit-core';
 import type { HttpContext } from '@adonisjs/core/http';
+import { type ClientTenancyOptions } from './observability/context_bridge.js';
 /** Contexto opcional repassado a `resolveUser` (extensão backward-compatible). */
 export interface ResolveUserContext {
     accessToken?: string;
@@ -10,6 +11,8 @@ export interface AuthenticatorDeps {
     resolveUser?: (identity: Identity, context: ResolveUserContext) => Promise<unknown>;
     /** lê o access token do token set da sessão (opcional; usado por resolvers userinfo) */
     getAccessToken?: () => string | null | undefined;
+    /** Opções de tenancy (`config/authkit_client.ts` → `tenancy`) usadas ao publicar o tenant. */
+    tenancy?: ClientTenancyOptions;
 }
 /**
  * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`

package/build/src/authenticator.js

@@ -36,7 +36,7 @@ export class Authenticator {
             // (best-effort, no-op sem o slot `@agora/context:set`). Apenas no caminho
             // de sucesso — não força resolução para requests anônimas.
             if (this.#identity)
-                populateContext(this.#identity);
+                populateContext(this.#identity, this.deps.tenancy);
         }
         return this.#identity;
     }

package/build/src/define_config.d.ts

@@ -1,7 +1,8 @@
-import type { Identity } from '@adonis-agora/authkit-core';
+import type { Identity, RunAccountExtensionCallOptions } from '@adonis-agora/authkit-core';
 import type { SessionIndex } from './backchannel_logout.js';
 import type { OidcEndpoints } from './discovery.js';
 import type { ResiliencePolicy } from './http/resilient_fetch.js';
+import type { ClientTenancyOptions } from './observability/context_bridge.js';
 import { type ResolverFactory, resolvers } from './resolvers/factory.js';
 import type { RevocationStore } from './revocation/revocation_store.js';
 export { resolvers };
@@ -22,6 +23,24 @@ export interface BackchannelLogoutInput {
     /** Store que persiste/consulta revogações (ex.: `lucidRevocationStore({ connection: 'auth' })`). */
     store: RevocationStore;
 }
+/** `accountConsole` in `config/authkit_client.ts`: pages this app serves for the IdP's account console. */
+export interface ClientAccountConsoleConfig {
+    /**
+     * Serve this app's account console extensions to the IdP over
+     * `/.well-known/agora-account-extensions` (the IdP lists this app in its own
+     * `accountConsole.remote`). Default `false`.
+     */
+    remote?: boolean;
+    /**
+     * Maps the IdP account to this app's subject (what billing, media and agents key on). Every
+     * extension receives it as `ctx.subject`. Default `{ type: 'User', id: account.id }`.
+     */
+    subject?: RunAccountExtensionCallOptions['subject'];
+    /** Budget of one page's `load()` / `visible()`, in ms. Default 5000. */
+    loadTimeoutMs?: number;
+    /** Budget of one action's `handle()`, in ms. Default 15000. */
+    actionTimeoutMs?: number;
+}
 export interface ClientConfigInput {
     issuer: string;
     clientId: string;
@@ -76,6 +95,14 @@ export interface ClientConfigInput {
     };
     /** Per-field endpoint overrides; always win over discovery. */
     endpoints?: Partial<OidcEndpoints>;
+    /**
+     * How the session's tenant is published into `@adonis-agora/context` (the active
+     * organization by default). See {@link ClientTenancyOptions}: `eager`, `personal`,
+     * `resolve`. No effect without `@adonis-agora/context`.
+     */
+    tenancy?: ClientTenancyOptions;
+    /** Account console pages this app serves to the IdP. See {@link ClientAccountConsoleConfig}. */
+    accountConsole?: ClientAccountConsoleConfig;
 }
 export interface ResolvedClientConfig {
     issuer: string;
@@ -101,5 +128,9 @@ export interface ResolvedClientConfig {
     };
     /** Endpoint overrides. See {@link ClientConfigInput.endpoints}. */
     endpoints?: Partial<OidcEndpoints>;
+    /** Tenancy options. See {@link ClientConfigInput.tenancy}. */
+    tenancy?: ClientTenancyOptions;
+    /** See {@link ClientConfigInput.accountConsole}. */
+    accountConsole?: ClientAccountConsoleConfig;
 }
 export declare function defineConfig(config: ClientConfigInput): import("@adonisjs/core/types").ConfigProvider<ResolvedClientConfig>;

package/build/src/define_config.js

@@ -35,6 +35,8 @@ export function defineConfig(config) {
                     ? config.discovery
                     : {},
             endpoints: config.endpoints,
+            tenancy: config.tenancy ?? {},
+            ...(config.accountConsole ? { accountConsole: config.accountConsole } : {}),
         };
     });
 }

package/build/src/middleware/authkit_context_middleware.d.ts

@@ -21,6 +21,11 @@ import type { NextFn } from '@adonisjs/core/types/http';
  *
  * Sem `@adonisjs/auth`, é ele sozinho que dá a sessão ao app: `ctx.authkit`
  * em qualquer rota, e `auth_middleware` para exigir login.
+ *
+ * With tenancy eager (`tenancy.eager`, default on when `config/context.ts` enables
+ * tenancy and the resolver is `jwt`), it also resolves the session here, so the
+ * request's tenant is in `@adonis-agora/context` before any handler, job dispatch
+ * or console query runs.
  */
 export default class AuthkitContextMiddleware {
     handle(ctx: HttpContext, next: NextFn): Promise<any>;

package/build/src/middleware/authkit_context_middleware.js

@@ -22,10 +22,27 @@ import { getAuthkit } from '../host/request_authenticator.js';
  *
  * Sem `@adonisjs/auth`, é ele sozinho que dá a sessão ao app: `ctx.authkit`
  * em qualquer rota, e `auth_middleware` para exigir login.
+ *
+ * With tenancy eager (`tenancy.eager`, default on when `config/context.ts` enables
+ * tenancy and the resolver is `jwt`), it also resolves the session here, so the
+ * request's tenant is in `@adonis-agora/context` before any handler, job dispatch
+ * or console query runs.
  */
 export default class AuthkitContextMiddleware {
     async handle(ctx, next) {
-        await getAuthkit(ctx);
+        const authkit = await getAuthkit(ctx);
+        if (await eagerTenancy(ctx)) {
+            try {
+                await authkit.getIdentity();
+            }
+            catch {
+                // Same as lazy: the failure surfaces when the app asks for the session.
+            }
+        }
         return next();
     }
 }
+async function eagerTenancy(ctx) {
+    const manager = (await ctx.containerResolver.make('authkit.client'));
+    return typeof manager.eagerTenancy === 'function' && manager.eagerTenancy();
+}

package/build/src/observability/context_bridge.d.ts

@@ -1,8 +1,64 @@
 import type { Identity } from '@adonis-agora/authkit-core';
+/**
+ * The tenant authkit publishes into `@agora/context` (structural copy of the
+ * context's `TenantRef`). `chain` lists the active path from the outermost
+ * tenant to this one (this one last) when tenants nest; absent for a flat tenant.
+ */
+export interface ContextTenant {
+    id: string;
+    kind: 'organization' | 'user' | (string & {});
+    source: 'authkit' | 'app' | 'carrier' | 'legacy' | (string & {});
+    slug?: string;
+    role?: string;
+    chain?: ContextTenantLink[];
+}
+/** One level of a nested tenant chain. */
+export interface ContextTenantLink {
+    id: string;
+    kind: string;
+    slug?: string;
+    role?: string;
+}
+/** What `tenancy.resolve` may return: one tenant, a chain (outermost first, active last), or none. */
+export type TenantInput = Omit<ContextTenantLink, 'kind'> & {
+    kind?: string;
+};
+/** Client-side tenancy options (`config/authkit_client.ts` → `tenancy`). */
+export interface ClientTenancyOptions {
+    /**
+     * Resolve the session (and so publish the tenant) at the start of every request
+     * that runs `authkit_context_middleware`, instead of on first use. Default: `true`
+     * when `config/context.ts` enables tenancy AND the resolver is `resolvers.jwt()`
+     * (local verify, cheap); `false` otherwise.
+     */
+    eager?: boolean;
+    /**
+     * With no active organization, publish the user as the tenant (`kind: 'user'`),
+     * so personal workspaces are tenants too. Default: `false` (orgless requests
+     * have no tenant).
+     */
+    personal?: boolean;
+    /**
+     * Map the session to your own tenant model (e.g. clinic → unit). Return one
+     * tenant, a chain (outermost first, active last), or `null` for no tenant;
+     * return `undefined` to keep authkit's default (the active organization).
+     */
+    resolve?: (identity: Identity) => TenantInput | TenantInput[] | null | undefined;
+}
+/**
+ * `true` when the installed `@adonis-agora/context` has tenancy enabled
+ * (`config/context.ts` → `tenancy.enabled`). `false` without context, or with a
+ * context version that predates tenancy.
+ */
+export declare function contextTenancyEnabled(): boolean;
+/** The tenant authkit would publish for `identity` under `options`. */
+export declare function tenantFor(identity: Identity, options?: ClientTenancyOptions): ContextTenant | null;
 /**
  * Popula o contexto do Agora a partir de uma identidade recém-resolvida:
  * `userRef` ({ type: 'user', id: userId }), os `globalRoles` da identidade e,
- * quando presente nas claims, `tenantId`. Best-effort: qualquer erro é engolido
- * e nada acontece sem o slot.
+ * quando há um tenant, `tenant` (id, kind, slug, role, e `chain` quando aninhado)
+ * mais `tenantId`. Um tenant que o próprio app já definiu nesta request
+ * (`Context.setTenant`, `source: 'app'`) nunca é sobrescrito. Best-effort:
+ * qualquer erro é engolido e nada acontece sem o slot.
  */
-export declare function populateContext(identity: Identity): void;
+export declare function populateContext(identity: Identity, options?: ClientTenancyOptions): void;

package/build/src/observability/context_bridge.js

@@ -1,11 +1,44 @@
-import { deriveOrgId } from '@adonis-agora/authkit-core';
+import { deriveOrgId, deriveOrgRole, deriveOrgSlug } from '@adonis-agora/authkit-core';
 /**
  * Ponte estrutural (best-effort) entre a sessão resolvida do authkit e o
- * contexto do Agora. Lê o slot global `@agora/context:set` de forma ESTRUTURAL —
- * nunca importa `@adonis-agora/context` — e degrada para no-op quando o context
- * não está instalado. Mesmo idioma da `diagnostics_bridge`.
+ * contexto do Agora. Lê os slots globais `@agora/context:set` e
+ * `@agora/context:accessor` de forma ESTRUTURAL — nunca importa
+ * `@adonis-agora/context` — e degrada para no-op quando o context não está
+ * instalado (ou é uma versão sem tenancy). Mesmo idioma da `diagnostics_bridge`.
  */
 const SET_SLOT = Symbol.for('@agora/context:set');
+const ACCESSOR_SLOT = Symbol.for('@agora/context:accessor');
+function accessor() {
+    const value = globalThis[ACCESSOR_SLOT];
+    return value && typeof value === 'object' ? value : undefined;
+}
+/**
+ * `true` when the installed `@adonis-agora/context` has tenancy enabled
+ * (`config/context.ts` → `tenancy.enabled`). `false` without context, or with a
+ * context version that predates tenancy.
+ */
+export function contextTenancyEnabled() {
+    try {
+        const tenancy = accessor()?.tenancy;
+        return typeof tenancy === 'function' && tenancy()?.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The tenant an app set itself (`Context.setTenant`) on this request, if any. */
+function appTenantAlreadySet() {
+    try {
+        const get = accessor()?.get;
+        if (typeof get !== 'function')
+            return false;
+        const current = get('tenant');
+        return !!current && current.source === 'app';
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Deriva o tenant ativo da identidade. Prefere o `orgId` já resolvido (o caminho
  * normal — `buildIdentityFromClaims` o preenche); cai para as claims cruas
@@ -13,25 +46,80 @@ const SET_SLOT = Symbol.for('@agora/context:set');
  * populou. A tabela de claims aceitas vive em `@adonis-agora/authkit-core`
  * (`ORG_ID_CLAIMS`) para não divergir entre a identidade e esta ponte.
  */
-function deriveTenant(identity) {
-    return identity.orgId ?? deriveOrgId(identity.raw) ?? undefined;
+function organizationTenant(identity) {
+    const id = identity.orgId ?? deriveOrgId(identity.raw);
+    if (!id)
+        return null;
+    const slug = identity.orgSlug ?? deriveOrgSlug(identity.raw);
+    const role = identity.orgRole ?? deriveOrgRole(identity.raw);
+    return {
+        id,
+        kind: 'organization',
+        source: 'authkit',
+        ...(slug ? { slug } : {}),
+        ...(role ? { role } : {}),
+    };
+}
+function link(input, fallbackKind) {
+    if (!input || typeof input.id !== 'string' || input.id === '')
+        return null;
+    return {
+        id: input.id,
+        kind: typeof input.kind === 'string' && input.kind !== '' ? input.kind : fallbackKind,
+        ...(typeof input.slug === 'string' && input.slug ? { slug: input.slug } : {}),
+        ...(typeof input.role === 'string' && input.role ? { role: input.role } : {}),
+    };
+}
+function fromResolved(resolved) {
+    const inputs = Array.isArray(resolved) ? resolved : [resolved];
+    const links = inputs.map((input) => link(input, 'organization'));
+    if (links.length === 0 || links.some((l) => l === null))
+        return null;
+    const chain = links;
+    const active = chain[chain.length - 1];
+    return { ...active, source: 'authkit', ...(chain.length > 1 ? { chain } : {}) };
+}
+/** The tenant authkit would publish for `identity` under `options`. */
+export function tenantFor(identity, options = {}) {
+    if (options.resolve) {
+        const resolved = options.resolve(identity);
+        if (resolved === null)
+            return null;
+        if (resolved !== undefined)
+            return fromResolved(resolved);
+    }
+    const org = organizationTenant(identity);
+    if (org)
+        return org;
+    if (options.personal === true && identity.userId) {
+        return { id: identity.userId, kind: 'user', source: 'authkit' };
+    }
+    return null;
 }
 /**
  * Popula o contexto do Agora a partir de uma identidade recém-resolvida:
  * `userRef` ({ type: 'user', id: userId }), os `globalRoles` da identidade e,
- * quando presente nas claims, `tenantId`. Best-effort: qualquer erro é engolido
- * e nada acontece sem o slot.
+ * quando há um tenant, `tenant` (id, kind, slug, role, e `chain` quando aninhado)
+ * mais `tenantId`. Um tenant que o próprio app já definiu nesta request
+ * (`Context.setTenant`, `source: 'app'`) nunca é sobrescrito. Best-effort:
+ * qualquer erro é engolido e nada acontece sem o slot.
  */
-export function populateContext(identity) {
+export function populateContext(identity, options = {}) {
     try {
         const set = globalThis[SET_SLOT];
         if (!set)
             return;
-        const tenant = deriveTenant(identity);
+        let tenant = null;
+        try {
+            tenant = appTenantAlreadySet() ? null : tenantFor(identity, options);
+        }
+        catch {
+            tenant = null;
+        }
         set({
             userRef: { type: 'user', id: identity.userId },
             globalRoles: identity.globalRoles,
-            ...(tenant ? { tenantId: tenant } : {}),
+            ...(tenant ? { tenantId: tenant.id, tenant } : {}),
         });
     }
     catch {

package/build/src/register_oidc_client.d.ts

@@ -1,4 +1,4 @@
-import type { Identity } from '@adonis-agora/authkit-core';
+import { type Identity } from '@adonis-agora/authkit-core';
 import type { HttpContext, Router } from '@adonisjs/core/http';
 /**
  * Mapa role → rota de redirect pós-login. `byGlobalRole` checa as roles globais do
@@ -24,6 +24,11 @@ export interface RegisterOidcClientOptions {
     postLogoutRedirect?: string | ((ctx: HttpContext) => string);
     /** Registra também `POST {prefix}/backchannel-logout` (OIDC Back-Channel Logout). Default: true. */
     backchannelLogout?: boolean;
+    /**
+     * Registra também `GET`/`POST /.well-known/agora-account-extensions` (account console pages this
+     * app serves to the IdP; 404 until `accountConsole.remote` is on). Default: true.
+     */
+    accountExtensions?: boolean;
     /**
      * Middleware(s) aplicados à rota de login (ex.: `middleware.guest()`). Array no
      * formato aceito por `.use()` do AdonisJS.
@@ -47,3 +52,10 @@ export interface RegisterOidcClientOptions {
  * ```
  */
 export declare function registerOidcClient(router: Router, options?: RegisterOidcClientOptions): void;
+/**
+ * Mounts `GET`/`POST /.well-known/agora-account-extensions`, where the IdP's account console
+ * fetches this app's account extension pages (answers 404 until `accountConsole.remote` is on).
+ * {@link registerOidcClient} calls it; call it yourself when you mount the client routes by hand.
+ * The IdP POSTs without a CSRF token: add the path to shield's `csrf.exceptRoutes`.
+ */
+export declare function registerAccountExtensionsEndpoint(router: Router): void;

package/build/src/register_oidc_client.js

@@ -1,3 +1,4 @@
+import { ACCOUNT_EXTENSIONS_WELL_KNOWN } from '@adonis-agora/authkit-core';
 import { OidcCallbackError } from './authorization.js';
 import { buildEndSessionUrl } from './oidc_login.js';
 /**
@@ -114,6 +115,22 @@ export function registerOidcClient(router, options = {}) {
         })
             .as('auth.backchannel_logout');
     }
+    if (options.accountExtensions !== false)
+        registerAccountExtensionsEndpoint(router);
+}
+/**
+ * Mounts `GET`/`POST /.well-known/agora-account-extensions`, where the IdP's account console
+ * fetches this app's account extension pages (answers 404 until `accountConsole.remote` is on).
+ * {@link registerOidcClient} calls it; call it yourself when you mount the client routes by hand.
+ * The IdP POSTs without a CSRF token: add the path to shield's `csrf.exceptRoutes`.
+ */
+export function registerAccountExtensionsEndpoint(router) {
+    const handle = async (ctx) => {
+        const manager = await ctx.containerResolver.make('authkit.client');
+        return manager.handleAccountExtensions(ctx);
+    };
+    router.get(ACCOUNT_EXTENSIONS_WELL_KNOWN, handle).as('authkit.account_extensions');
+    router.post(ACCOUNT_EXTENSIONS_WELL_KNOWN, handle).as('authkit.account_extensions.call');
 }
 /** Resolve o destino pós-login a partir do mapa de redirects por role global (do token). */
 function resolveDestination(identity, redirects) {

package/build/src/resolvers/factory.d.ts

@@ -45,6 +45,8 @@ export interface ResolverContext {
     };
 }
 export interface ResolverFactory {
+    /** Which built-in resolver this is (`jwt`, `opaque`, `pat`); absent for a custom one. */
+    readonly kind?: 'jwt' | 'opaque' | 'pat' | (string & {});
     resolver(ctx: ResolverContext): Promise<SessionResolver>;
 }
 export declare const resolvers: {

package/build/src/resolvers/factory.js

@@ -23,6 +23,7 @@ export const resolvers = {
     jwt(config = {}) {
         const tokenSource = config.tokenSource ?? 'session';
         return {
+            kind: 'jwt',
             async resolver(rc) {
                 return new JwtResolver({
                     endpoints: async () => {
@@ -41,6 +42,7 @@ export const resolvers = {
     },
     pat(config) {
         return {
+            kind: 'pat',
             async resolver(_rc) {
                 return new PatResolver({
                     introspectionUrl: config.introspectionUrl,
@@ -52,6 +54,7 @@ export const resolvers = {
     opaque(config = {}) {
         const tokenSource = config.tokenSource ?? 'session';
         return {
+            kind: 'opaque',
             async resolver(rc) {
                 if (!rc.clientSecret) {
                     throw new Error('resolvers.opaque requer um client confidencial (clientSecret) para introspection');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -77,11 +77,11 @@
     }
   },
   "dependencies": {
-    "@adonis-agora/authkit-core": "1.0.0-rc.0",
+    "@adonis-agora/authkit-core": "1.0.0-rc.1",
     "jose": "6.2.16"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "1.0.0-rc.4",
+    "@adonis-agora/authkit-server": "1.0.0-rc.10",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",