@adonis-agora/authkit-client 1.0.0-rc.6 → 1.0.0-rc.7

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @adonis-agora/authkit-client
 
+## 1.0.0-rc.7
+
+### Minor Changes
+
+- [#495](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/495) [`4830805`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/4830805039c3f0e978c403d3062275a892704eb7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Separate servers: every piece of an Agora deployment can run without authkit-server in its process.
+  
+  - `authkitTenantVerifier({ issuer, resource, environment? })` (authkit-client) verifies service-tenant tokens on any server against the issuer's discovered JWKS and returns `{ partition, environment?, capabilities, clientId, expiresAt }` or `null`. `authkitTenantToken` now takes the token endpoint only from discovery (no guessed path).
+  - Service tenants get an optional `environment` (console, Admin API, SDK, `--environment`), emitted as the `environment` claim. Both verifiers take `environment` and, when it is set, accept only tokens claiming exactly that environment (fail closed); authkit-server's in-process verifier also returns `environment`. One service-tenant client gets tokens for every `urn:agora:*` resource declared.
+  - `registerOidcClient` announces `POST /auth/logout` as `account.signOut` on the `agora.consoles` registry (skipped when authkit-server runs in the app), so every console shows a sign-out.
+  - `Identity.actor` (`{ sub, email? }`) from the RFC 8693 `act` claim of an impersonated token (`deriveActor` in authkit-core).
+  - Org labels: authkit-server serves `GET /api/orgs/labels?ids=` (first-party confidential clients, Basic auth) and emits `org_name` for the active org; authkit-client installs a cached `Context.setTenantLabeler` (`orgLabels` option, `authkitOrgLabels`).
+  - Webhooks: the body carries `id` and `actorId`, `events.webhook` accepts a list; authkit-client's `registerAuthkitWebhook` / `authkitWebhookHandler` verify the HMAC, the `ts` window and the id, and re-emit on the diagnostics bus as `agora:authkit:<type>` with the in-process payload.
+  - `identityFromAccessToken`, `bindAuthkitIdentity` and `bridgeAuthkitToken` put a verified authkit bearer token on `ctx.authkit`.
+
+### Patch Changes
+
+- Updated dependencies [[`4830805`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/4830805039c3f0e978c403d3062275a892704eb7)]:
+  - @adonis-agora/authkit-core@1.0.0-rc.3
+
 ## 1.0.0-rc.6
 
 ### Minor Changes

package/build/index.d.ts

@@ -1,15 +1,17 @@
-export type { Identity } from '@adonis-agora/authkit-core';
+export type { Identity, IdentityActor } 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 type { AgoraConsoleSignOut, ConsolesAppLike } from './src/agora_consoles.js';
+export { AGORA_CONSOLES_BINDING, announceAgoraSignOut } from './src/agora_consoles.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, ClientAccountConsoleConfig, ClientConfigInput, ResolvedClientConfig, } from './src/define_config.js';
+export type { BackchannelLogoutCallback, BackchannelLogoutInput, ClientAccountConsoleConfig, ClientConfigInput, ClientOrgLabelsConfig, 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';
@@ -25,6 +27,8 @@ export type { ResiliencePolicy } from './src/http/resilient_fetch.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';
 export type { IdTokenClaims, ValidateIdTokenOptions } from './src/id_token.js';
 export { InvalidIdTokenError, validateIdToken } from './src/id_token.js';
+export type { AuthkitAccessTokenIdentityOptions } from './src/identity_bridge.js';
+export { bindAuthkitIdentity, bridgeAuthkitToken, identityFromAccessToken, } from './src/identity_bridge.js';
 export { clearJwksCache } from './src/jwks.js';
 export type { LucidMirrorOptions } from './src/lucid_mirror.js';
 export { lucidMirror } from './src/lucid_mirror.js';
@@ -35,13 +39,19 @@ export { default as RequireOrgMiddleware } from './src/middleware/require_org_mi
 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 { AuthkitOrgLabelsOptions, OrgLabelResolver } from './src/org_labels.js';
+export { authkitOrgLabels, installOrgLabeler, ORG_LABELS_PATH } from './src/org_labels.js';
 export type { PostLoginRedirects, RegisterOidcClientOptions, } from './src/register_oidc_client.js';
 export { registerAccountExtensionsEndpoint, registerOidcClient, } from './src/register_oidc_client.js';
+export { buildIdentityFromClaims as identityFromClaims } from './src/resolvers/identity.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';
+export { AuthkitTenantVerifier, type AuthkitTenantVerifierFn, type AuthkitTenantVerifierOptions, authkitTenantVerifier, type TenantVerifier, type TenantVerifierRequest, type VerifiedTenantToken, } from './src/tenant_verifier.js';
 export type { TokenSet } from './src/types.js';
 export type { ClaimsUser, ResolveUserContext, UserinfoResolverOptions, } from './src/user_resolvers.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';
 export type { JwtAccessTokenClaims, VerifyJwtAccessTokenOptions, } from './src/verify_access_token.js';
 export { verifyJwtAccessToken } from './src/verify_access_token.js';
+export type { AuthkitDiagnosticPayload, AuthkitWebhookEvent, AuthkitWebhookOptions, WebhookRejection, WebhookReplayStore, WebhookVerification, } from './src/webhook_receiver.js';
+export { authkitWebhookHandler, emitAuthkitEvent, memoryReplayStore, registerAuthkitWebhook, verifyAuthkitWebhook, } from './src/webhook_receiver.js';

package/build/index.js

@@ -1,6 +1,7 @@
 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 { AGORA_CONSOLES_BINDING, announceAgoraSignOut } from './src/agora_consoles.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';
@@ -12,14 +13,19 @@ export { authkitDashboardAuthorize, isAuthkitAdmin, } from './src/host/dashboard
 export { getAuthkit } from './src/host/request_authenticator.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';
 export { InvalidIdTokenError, validateIdToken } from './src/id_token.js';
+export { bindAuthkitIdentity, bridgeAuthkitToken, identityFromAccessToken, } from './src/identity_bridge.js';
 export { clearJwksCache } from './src/jwks.js';
 export { lucidMirror } from './src/lucid_mirror.js';
 export { default as AuthkitContextMiddleware } from './src/middleware/authkit_context_middleware.js';
 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 { authkitOrgLabels, installOrgLabeler, ORG_LABELS_PATH } from './src/org_labels.js';
 export { registerAccountExtensionsEndpoint, registerOidcClient, } from './src/register_oidc_client.js';
+export { buildIdentityFromClaims as identityFromClaims } from './src/resolvers/identity.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
 export { AuthkitTenantToken, authkitTenantToken, TenantTokenError, } from './src/tenant_token.js';
+export { AuthkitTenantVerifier, authkitTenantVerifier, } from './src/tenant_verifier.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';
 export { verifyJwtAccessToken } from './src/verify_access_token.js';
+export { authkitWebhookHandler, emitAuthkitEvent, memoryReplayStore, registerAuthkitWebhook, verifyAuthkitWebhook, } from './src/webhook_receiver.js';

package/build/providers/authkit_client_provider.d.ts

@@ -175,6 +175,12 @@ export declare class AuthkitClientManager {
      * is `resolvers.jwt()` (local verify, no network).
      */
     eagerTenancy(): boolean;
+    /**
+     * Registers the org labeler (see `orgLabels` in `config/authkit_client.ts`) on
+     * `@adonis-agora/context`. `false` when it is off, the client has no secret, or the
+     * context is not installed.
+     */
+    installOrgLabeler(): 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).
@@ -187,4 +193,10 @@ export default class AuthkitClientProvider {
     protected app: ApplicationService;
     constructor(app: ApplicationService);
     register(): void;
+    /**
+     * Org labels for the consoles' org pickers, when authkit-server is not in this app (it
+     * serves them locally through `tenancy.label: authkitTenantLabels()`). Best effort: a
+     * config that cannot resolve here fails later, on first use, as before.
+     */
+    ready(): Promise<void>;
 }

package/build/providers/authkit_client_provider.js

@@ -14,6 +14,7 @@ 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';
+import { authkitOrgLabels, installOrgLabeler } from '../src/org_labels.js';
 /** Margem (ms) antes do `expiresAt` em que o access token é renovado proativamente. */
 const REFRESH_SKEW_MS = 60_000;
 /** Aceita só o formato COM vínculo; o formato legado (TokenSet cru) vira `null`. */
@@ -509,6 +510,25 @@ export class AuthkitClientManager {
             return eager;
         return this.config.resolverFactory?.kind === 'jwt' && contextTenancyEnabled();
     }
+    /**
+     * Registers the org labeler (see `orgLabels` in `config/authkit_client.ts`) on
+     * `@adonis-agora/context`. `false` when it is off, the client has no secret, or the
+     * context is not installed.
+     */
+    installOrgLabeler() {
+        const cfg = this.config;
+        if (cfg.orgLabels === false || !cfg.clientSecret)
+            return false;
+        const options = cfg.orgLabels ?? {};
+        return installOrgLabeler(authkitOrgLabels({
+            issuer: cfg.issuer,
+            clientId: cfg.clientId,
+            clientSecret: cfg.clientSecret,
+            ...(options.endpoint ? { endpoint: options.endpoint } : {}),
+            ...(options.ttlMs !== undefined ? { ttlMs: options.ttlMs } : {}),
+            ...(this.deps.fetchImpl ? { fetch: this.deps.fetchImpl } : {}),
+        }));
+    }
     /**
      * The request's {@link Authenticator}. `options.resolver` replaces the configured
      * resolver for this authenticator only (e.g. a guard for bearer-token API routes).
@@ -559,6 +579,22 @@ export default class AuthkitClientProvider {
             this.app.container.singleton(ACCOUNT_EXTENSIONS_BINDING, async () => registry);
         }
     }
+    /**
+     * Org labels for the consoles' org pickers, when authkit-server is not in this app (it
+     * serves them locally through `tenancy.label: authkitTenantLabels()`). Best effort: a
+     * config that cannot resolve here fails later, on first use, as before.
+     */
+    async ready() {
+        if (this.app.container.hasBinding('authkit.server'))
+            return;
+        try {
+            const manager = await this.app.container.make(AuthkitClientManager);
+            manager.installOrgLabeler();
+        }
+        catch {
+            // no usable config yet: nothing to install
+        }
+    }
 }
 /** `sub` of a stored id_token, or undefined when there is none / it is unreadable. */
 function subjectOf(idToken) {

package/build/src/agora_consoles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The `'agora.consoles'` registry every `@adonis-agora` console reads (declared
+ * structurally, like in every other lib: nothing is imported). authkit-client only
+ * writes `account.signOut` into it, so every console on a relying-party app shows a
+ * working sign-out with no per-console config.
+ */
+/** The container binding the registry lives at. */
+export declare const AGORA_CONSOLES_BINDING = "agora.consoles";
+/** Where every console's footer signs the viewer out. */
+export type AgoraConsoleSignOut = {
+    action: string;
+    method?: 'POST';
+} | {
+    href: string;
+};
+/** The slice of an AdonisJS application the announcement needs. */
+export interface ConsolesAppLike {
+    container: {
+        hasBinding(binding: string): boolean;
+        bindValue(binding: string, value: unknown): void;
+        make(binding: string): Promise<unknown>;
+    };
+}
+/**
+ * Announces `action` (a same-origin `POST` route, e.g. `/auth/logout`) as
+ * `account.signOut` on the `'agora.consoles'` registry. Creates the registry when no
+ * console bound it yet. Keeps a sign-out something else announced first (authkit-server
+ * in the same app, or the app itself), skips a registry of another version, and never
+ * throws on one. Returns `true` when it wrote the announcement.
+ */
+export declare function announceAgoraSignOut(app: ConsolesAppLike, action: string): Promise<boolean>;

package/build/src/agora_consoles.js

@@ -0,0 +1,40 @@
+/**
+ * The `'agora.consoles'` registry every `@adonis-agora` console reads (declared
+ * structurally, like in every other lib: nothing is imported). authkit-client only
+ * writes `account.signOut` into it, so every console on a relying-party app shows a
+ * working sign-out with no per-console config.
+ */
+/** The container binding the registry lives at. */
+export const AGORA_CONSOLES_BINDING = 'agora.consoles';
+function isSameOriginPath(path) {
+    return (typeof path === 'string' &&
+        path.startsWith('/') &&
+        !path.startsWith('//') &&
+        !path.includes('\\') &&
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+        !/[\u0000-\u001f\u007f]/.test(path));
+}
+/**
+ * Announces `action` (a same-origin `POST` route, e.g. `/auth/logout`) as
+ * `account.signOut` on the `'agora.consoles'` registry. Creates the registry when no
+ * console bound it yet. Keeps a sign-out something else announced first (authkit-server
+ * in the same app, or the app itself), skips a registry of another version, and never
+ * throws on one. Returns `true` when it wrote the announcement.
+ */
+export async function announceAgoraSignOut(app, action) {
+    if (!isSameOriginPath(action)) {
+        throw new Error(`announceAgoraSignOut: sign-out action ${JSON.stringify(action)} must be a same-origin absolute path`);
+    }
+    const container = app.container;
+    if (!container.hasBinding(AGORA_CONSOLES_BINDING)) {
+        container.bindValue(AGORA_CONSOLES_BINDING, { version: 1, entries: [] });
+    }
+    const registry = (await container.make(AGORA_CONSOLES_BINDING));
+    if (!registry || registry.version !== 1 || !Array.isArray(registry.entries))
+        return false;
+    const account = typeof registry.account === 'object' && registry.account !== null ? registry.account : {};
+    if (account.signOut !== undefined)
+        return false;
+    registry.account = { ...account, signOut: { action, method: 'POST' } };
+    return true;
+}

package/build/src/authenticator.js

@@ -1,5 +1,6 @@
 import { AUTHKIT_METRICS, NoopRecorder } from '@adonis-agora/authkit-core';
 import { populateContext } from './observability/context_bridge.js';
+import { rememberOrgLabel } from './org_labels.js';
 /**
  * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`
  * devolve — o app o fixa pela interface `AuthkitUserType`, e aí `getUser()` passa a devolver
@@ -35,8 +36,10 @@ export class Authenticator {
             // Ponte estrutural: popula o contexto do Agora quando há sessão de fato
             // (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)
+            if (this.#identity) {
                 populateContext(this.#identity, this.deps.tenancy);
+                rememberOrgLabel(this.#identity);
+            }
         }
         return this.#identity;
     }

package/build/src/define_config.d.ts

@@ -103,6 +103,21 @@ export interface ClientConfigInput {
     tenancy?: ClientTenancyOptions;
     /** Account console pages this app serves to the IdP. See {@link ClientAccountConsoleConfig}. */
     accountConsole?: ClientAccountConsoleConfig;
+    /**
+     * Organization names for every console's org picker (`Context.tenantLabels`): the active
+     * org from the `org_name` claim, any other from the authkit server's
+     * `GET /api/orgs/labels` (authenticated with `clientId`/`clientSecret`), cached.
+     * Installed at boot when `@adonis-agora/context` is present, the client is confidential
+     * and authkit-server does not run in this app. `false` turns it off. Default: on.
+     */
+    orgLabels?: false | ClientOrgLabelsConfig;
+}
+/** `orgLabels` in `config/authkit_client.ts`. */
+export interface ClientOrgLabelsConfig {
+    /** The labels endpoint. Default: `/api/orgs/labels` on the issuer's origin. */
+    endpoint?: string;
+    /** How long a label is reused, in ms. Default: 5 minutes. */
+    ttlMs?: number;
 }
 export interface ResolvedClientConfig {
     issuer: string;
@@ -132,5 +147,7 @@ export interface ResolvedClientConfig {
     tenancy?: ClientTenancyOptions;
     /** See {@link ClientConfigInput.accountConsole}. */
     accountConsole?: ClientAccountConsoleConfig;
+    /** See {@link ClientConfigInput.orgLabels}. Absent means on with the defaults. */
+    orgLabels?: false | ClientOrgLabelsConfig;
 }
 export declare function defineConfig(config: ClientConfigInput): import("@adonisjs/core/types").ConfigProvider<ResolvedClientConfig>;

package/build/src/define_config.js

@@ -37,6 +37,7 @@ export function defineConfig(config) {
             endpoints: config.endpoints,
             tenancy: config.tenancy ?? {},
             ...(config.accountConsole ? { accountConsole: config.accountConsole } : {}),
+            ...(config.orgLabels !== undefined ? { orgLabels: config.orgLabels } : {}),
         };
     });
 }

package/build/src/identity_bridge.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Puts an identity verified somewhere else (an MCP bearer token, a remote JWT) on the
+ * request the way a browser session would, so `ctx.authkit` / `getAuthkit(ctx)` and an
+ * `authkitClientGuard` default guard see it. A console gated by `authkitDashboardAuthorize`
+ * then accepts the caller.
+ */
+import type { Identity } from '@adonis-agora/authkit-core';
+import type { HttpContext } from '@adonisjs/core/http';
+import { type DiscoverOptions } from './discovery.js';
+export interface AuthkitAccessTokenIdentityOptions {
+    /** Issuer URL of the authkit server. Its `jwks_uri` comes from discovery. */
+    issuer: string;
+    /** The `aud` the token must carry (the resource URL of the endpoint that received it). */
+    audience: string | string[];
+    /** Claim holding the global roles. Default: `'roles'`. */
+    globalRolesClaim?: string;
+    /** Accept a token without `typ: at+jwt`. Default: `false`. */
+    allowAnyTyp?: boolean;
+    /** Discovery options (custom `fetchImpl`, cache TTL, resilience policy). */
+    discovery?: Pick<DiscoverOptions, 'fetchImpl' | 'cacheTtlMs' | 'resilience' | 'overrides'>;
+}
+/**
+ * Verifies an authkit JWT access token (RFC 9068) against the issuer's discovered JWKS and
+ * maps it to an {@link Identity} (`userId`, `email`, `globalRoles`, org, `actor`). `null`
+ * for an invalid token or a `client_credentials` token (no user behind it). Throws when the
+ * issuer cannot be discovered.
+ */
+export declare function identityFromAccessToken(token: string, options: AuthkitAccessTokenIdentityOptions): Promise<Identity | null>;
+/**
+ * Binds `identity` to the request:
+ *
+ * 1. `ctx.authkit` becomes an `Authenticator` resolving to it, built by this app's authkit
+ *    client when there is one (so `resolveUser`, e.g. `lucidMirror`, gives `getUser()` the
+ *    app's user, and the tenant reaches `@adonis-agora/context`), else a plain one.
+ * 2. When `ctx.auth`'s default guard is `authkitClientGuard`, it is authenticated from it,
+ *    so `ctx.auth.user` sees the account too.
+ *
+ * Best effort past step 1.
+ */
+export declare function bindAuthkitIdentity(ctx: HttpContext, identity: Identity): Promise<void>;
+/**
+ * {@link identityFromAccessToken} then {@link bindAuthkitIdentity}: the one call an MCP or
+ * API endpoint makes after reading a bearer token issued by a remote authkit. Returns the
+ * identity, or `null` (nothing bound) when the token does not verify.
+ */
+export declare function bridgeAuthkitToken(ctx: HttpContext, token: string, options: AuthkitAccessTokenIdentityOptions): Promise<Identity | null>;

package/build/src/identity_bridge.js

@@ -0,0 +1,99 @@
+/**
+ * Puts an identity verified somewhere else (an MCP bearer token, a remote JWT) on the
+ * request the way a browser session would, so `ctx.authkit` / `getAuthkit(ctx)` and an
+ * `authkitClientGuard` default guard see it. A console gated by `authkitDashboardAuthorize`
+ * then accepts the caller.
+ */
+import { Authenticator } from './authenticator.js';
+import { discoverEndpoints } from './discovery.js';
+import { buildIdentityFromClaims } from './resolvers/identity.js';
+import { verifyJwtAccessToken } from './verify_access_token.js';
+/**
+ * Verifies an authkit JWT access token (RFC 9068) against the issuer's discovered JWKS and
+ * maps it to an {@link Identity} (`userId`, `email`, `globalRoles`, org, `actor`). `null`
+ * for an invalid token or a `client_credentials` token (no user behind it). Throws when the
+ * issuer cannot be discovered.
+ */
+export async function identityFromAccessToken(token, options) {
+    if (typeof token !== 'string' || !token)
+        return null;
+    const endpoints = await discoverEndpoints(options.issuer, {
+        ...options.discovery,
+        onError: 'throw',
+    });
+    let claims;
+    try {
+        claims = (await verifyJwtAccessToken(token, {
+            issuer: endpoints.issuer,
+            jwksUri: endpoints.jwksUri,
+            audience: options.audience,
+            ...(options.allowAnyTyp ? { allowAnyTyp: true } : {}),
+        }));
+    }
+    catch {
+        return null;
+    }
+    if (typeof claims.sub !== 'string' || !claims.sub)
+        return null;
+    // An access token without an expiry is never accepted, whatever the issuer mints.
+    if (typeof claims.exp !== 'number')
+        return null;
+    // A client_credentials token authenticates a client, never a user.
+    if (typeof claims.client_id === 'string' && claims.sub === claims.client_id)
+        return null;
+    return buildIdentityFromClaims(claims, options.globalRolesClaim ?? 'roles');
+}
+/**
+ * Binds `identity` to the request:
+ *
+ * 1. `ctx.authkit` becomes an `Authenticator` resolving to it, built by this app's authkit
+ *    client when there is one (so `resolveUser`, e.g. `lucidMirror`, gives `getUser()` the
+ *    app's user, and the tenant reaches `@adonis-agora/context`), else a plain one.
+ * 2. When `ctx.auth`'s default guard is `authkitClientGuard`, it is authenticated from it,
+ *    so `ctx.auth.user` sees the account too.
+ *
+ * Best effort past step 1.
+ */
+export async function bindAuthkitIdentity(ctx, identity) {
+    const resolver = { resolve: async () => identity };
+    let authenticator;
+    try {
+        const container = ctx.containerResolver;
+        const manager = (await container?.make?.('authkit.client'));
+        if (manager && typeof manager.createAuthenticator === 'function') {
+            authenticator = await manager.createAuthenticator(ctx, {
+                resolver: { resolver: async () => resolver },
+            });
+        }
+    }
+    catch {
+        authenticator = undefined;
+    }
+    ctx.authkit =
+        authenticator ?? new Authenticator(ctx, { resolver });
+    const auth = ctx.auth;
+    if (auth === undefined || typeof auth.use !== 'function')
+        return;
+    try {
+        const guard = auth.use();
+        if (guard?.driverName !== 'authkit_client' || guard.isAuthenticated === true)
+            return;
+        // A silent-auth middleware may already have tried (and found no browser session).
+        guard.authenticationAttempted = false;
+        await auth.check();
+    }
+    catch {
+        // leave ctx.auth alone
+    }
+}
+/**
+ * {@link identityFromAccessToken} then {@link bindAuthkitIdentity}: the one call an MCP or
+ * API endpoint makes after reading a bearer token issued by a remote authkit. Returns the
+ * identity, or `null` (nothing bound) when the token does not verify.
+ */
+export async function bridgeAuthkitToken(ctx, token, options) {
+    const identity = await identityFromAccessToken(token, options);
+    if (identity)
+        await bindAuthkitIdentity(ctx, identity);
+    return identity;
+}

package/build/src/org_labels.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Organization display labels on a relying-party app, for the org pickers of every
+ * `@adonis-agora` console (`Context.tenantLabels`). The active org's name comes from the
+ * session's `org_name` claim; any other id is asked to the authkit server
+ * (`GET /api/orgs/labels?ids=`, authenticated with this app's client id and secret) and
+ * cached.
+ */
+import type { Identity } from '@adonis-agora/authkit-core';
+/** `(ids, { kind? }) => { [id]: label }`, the shape `@adonis-agora/context` expects. */
+export type OrgLabelResolver = (ids: readonly string[], options?: {
+    kind?: string;
+}) => Promise<Record<string, string>>;
+export interface AuthkitOrgLabelsOptions {
+    /** Issuer URL of the authkit server. */
+    issuer: string;
+    /** This app's client id (a confidential, first-party client of the authkit server). */
+    clientId: string;
+    /** This app's client secret. */
+    clientSecret: string;
+    /** The labels endpoint. Default: `/api/orgs/labels` on the issuer's origin. */
+    endpoint?: string;
+    /** How long a fetched label (or a miss) is reused, in ms. Default: 5 minutes. */
+    ttlMs?: number;
+    /** Abort a labels request after this many ms. Default: 5000. */
+    timeoutMs?: number;
+    /** Custom `fetch` (proxy, tests). Default: the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Default path of authkit-server's labels endpoint. */
+export declare const ORG_LABELS_PATH = "/api/orgs/labels";
+/**
+ * Records the active org's name from a resolved session (`org_name` claim), so the
+ * labeler answers it with no call. Called by the `Authenticator`; best effort.
+ */
+export declare function rememberOrgLabel(identity: Identity | null | undefined): void;
+/** Clears the labels learned from claims (tests). */
+export declare function __clearOrgLabelsForTests(): void;
+/**
+ * A label resolver backed by the authkit server. Ids of another tenant kind (`kind` other
+ * than `'organization'`) get no label. Never throws: an unreachable server answers what is
+ * already known, and the ids it could not resolve show as ids.
+ */
+export declare function authkitOrgLabels(options: AuthkitOrgLabelsOptions): OrgLabelResolver;
+/**
+ * Registers `resolver` as the context's tenant labeler (`Context.setTenantLabeler`), so
+ * console org pickers show names. `tenancy.label` in `config/context.ts` still wins.
+ * Returns `false` (and does nothing) without `@adonis-agora/context`.
+ */
+export declare function installOrgLabeler(resolver: OrgLabelResolver): boolean;