@adonis-agora/authkit-server 0.42.0 → 0.44.0

package/build/src/define_config.d.ts

@@ -561,6 +561,21 @@ export interface AuthServerConfigInput {
     ttl?: TtlConfig;
     /** Nome da CLAIM (não do scope) onde os papéis globais são emitidos. Default: 'roles'. */
     globalRolesClaim?: string;
+    /**
+     * Resolves the global-roles claim at token-mint time. Return the roles to embed
+     * in the `<globalRolesClaim>` claim for a first-party client. Lets the host source
+     * roles from an external authority (e.g. @adonis-agora/authz) or a custom store
+     * instead of the account's stored `globalRoles`. Default when omitted:
+     * `account.globalRoles ?? []` (unchanged behavior).
+     */
+    resolveTokenRoles?: (account: AuthAccount, context: {
+        clientId?: string;
+        activeOrg?: {
+            orgId: string;
+            orgSlug: string;
+            orgRole: string;
+        } | null;
+    }) => string[] | Promise<string[]>;
     cookieKeys?: string[];
     observability?: ObservabilityConfig;
     /** Contrato primário de identidade. Deriva findAccount/verifyCredentials do provider. */
@@ -769,6 +784,18 @@ export interface ResolvedServerConfig {
         session: number;
     };
     globalRolesClaim: string;
+    /**
+     * Resolves the global-roles claim at token-mint time (first-party only). When
+     * omitted, the mint falls back to `account.globalRoles ?? []` (unchanged behavior).
+     */
+    resolveTokenRoles?: (account: AuthAccount, context: {
+        clientId?: string;
+        activeOrg?: {
+            orgId: string;
+            orgSlug: string;
+            orgRole: string;
+        } | null;
+    }) => string[] | Promise<string[]>;
     cookieKeys: string[];
     observability: ObservabilityConfig;
     findAccount: (sub: string) => Promise<AuthAccount | null>;

package/build/src/define_config.js

@@ -303,6 +303,7 @@ export function defineConfig(config) {
                 session: toSeconds(config.ttl?.session, 604800),
             },
             globalRolesClaim: config.globalRolesClaim ?? "roles",
+            resolveTokenRoles: config.resolveTokenRoles,
             cookieKeys: config.cookieKeys ?? [],
             observability: config.observability ?? {},
             findAccount: (sub) => config.accountStore.findById(sub),

package/build/src/host/account_roles.d.ts

@@ -0,0 +1,26 @@
+import type { AuthAccount } from '../accounts/account_store.js';
+/** The slice of the resolved config the role resolution needs (structurally typed). */
+type RoleResolverConfig = {
+    resolveTokenRoles?: (account: AuthAccount, context: {
+        clientId?: string;
+        activeOrg?: {
+            orgId: string;
+            orgSlug: string;
+            orgRole: string;
+        } | null;
+    }) => string[] | Promise<string[]>;
+};
+/**
+ * An account's effective roles for host-side gating (the admin console).
+ *
+ * When the host configures `resolveTokenRoles`, that hook is the single source of an account's roles
+ * — the same one the OIDC `roles` claim is minted from — so console access tracks the host's role
+ * authority (e.g. an app that keeps roles in its own table via `@adonis-agora/authz`) instead of the
+ * account's stored `globalRoles`. Falls back to `account.globalRoles ?? []` when no hook is set, so
+ * default behavior is unchanged.
+ *
+ * The console is not OIDC-client- or org-scoped for role purposes, so the hook is called with an
+ * empty context (`clientId: undefined`, `activeOrg: null`).
+ */
+export declare function resolveAccountRoles(cfg: RoleResolverConfig, account: AuthAccount): Promise<string[]>;
+export {};

package/build/src/host/account_roles.js

@@ -0,0 +1,18 @@
+/**
+ * An account's effective roles for host-side gating (the admin console).
+ *
+ * When the host configures `resolveTokenRoles`, that hook is the single source of an account's roles
+ * — the same one the OIDC `roles` claim is minted from — so console access tracks the host's role
+ * authority (e.g. an app that keeps roles in its own table via `@adonis-agora/authz`) instead of the
+ * account's stored `globalRoles`. Falls back to `account.globalRoles ?? []` when no hook is set, so
+ * default behavior is unchanged.
+ *
+ * The console is not OIDC-client- or org-scoped for role purposes, so the hook is called with an
+ * empty context (`clientId: undefined`, `activeOrg: null`).
+ */
+export async function resolveAccountRoles(cfg, account) {
+    if (cfg.resolveTokenRoles) {
+        return cfg.resolveTokenRoles(account, { clientId: undefined, activeOrg: null });
+    }
+    return account.globalRoles ?? [];
+}

package/build/src/host/admin_console/admin_shell_controller.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { getAdminPrefix } from '../admin_prefix.js';
+import { resolveAccountRoles } from '../account_roles.js';
 // ─── Shell HTML cache ─────────────────────────────────────────────────────────
 /**
  * Points to the Vite-built index.html inside build/host/ui-dist/.
@@ -120,7 +121,7 @@ export default class AdminShellController {
                 currentUser = {
                     id: account.id,
                     email: account.email,
-                    roles: account.globalRoles ?? [],
+                    roles: await resolveAccountRoles(cfg, account),
                 };
             }
         }

package/build/src/host/register_auth_host.js

@@ -2,6 +2,7 @@ import { resolveRateLimit } from '../define_config.js';
 import { createAuthThrottles } from './rate_limit.js';
 import { ACCOUNT_SESSION_KEY } from './middleware/account_auth.js';
 import { accountHome } from './account_home.js';
+import { resolveAccountRoles } from './account_roles.js';
 import { adminApiGuard } from './admin_api/admin_api_guard.js';
 import { setAdminPrefix, normalizeAdminPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './admin_prefix.js';
 import { resolveRuntimeSettings } from './runtime_settings.js';
@@ -112,7 +113,10 @@ export const adminGuard = async (ctx, next) => {
     }
     const allowed = cfg.admin.roles;
     const account = await cfg.accountStore.findById(accountId);
-    const roles = account?.globalRoles ?? [];
+    // Resolve roles through the host's role authority (`resolveTokenRoles`) when set — the same source
+    // the token claim is minted from — so an app-role admin reaches the console. Falls back to the
+    // account's stored `globalRoles` when no hook is configured.
+    const roles = account ? await resolveAccountRoles(cfg, account) : [];
     const isAdmin = roles.some((r) => allowed.includes(r));
     if (!isAdmin) {
         // Evita vazar a existência do console admin: redireciona para o accountHome

package/build/src/provider/oidc_service.js

@@ -98,7 +98,9 @@ export class OidcService {
                         };
                         // roles/org_* são dados de autorização interna: só para first-party.
                         if (firstParty) {
-                            base[config.globalRolesClaim] = user.globalRoles ?? [];
+                            base[config.globalRolesClaim] = config.resolveTokenRoles
+                                ? await config.resolveTokenRoles(user, { clientId, activeOrg })
+                                : (user.globalRoles ?? []);
                             // Emite claims de org somente quando há uma org ativa na sessão.
                             if (activeOrg) {
                                 base['org_id'] = activeOrg.orgId;
@@ -115,6 +117,7 @@ export class OidcService {
         registerTokenExchange(provider, {
             findAccount: config.findAccount,
             globalRolesClaim: config.globalRolesClaim,
+            resolveTokenRoles: config.resolveTokenRoles,
             // Resource indicators (RFC 8707) suportados: o `audience` default + cada
             // resource declarado. Usado para validar `audience`/`resource` no pedido de
             // token-exchange — alvos fora desta lista são rejeitados (invalid_target).

package/build/src/provider/token_exchange.d.ts

@@ -1,4 +1,5 @@
 import type { AuditSink } from '../audit/audit_sink.js';
+import type { AuthAccount } from '../accounts/account_store.js';
 export interface TokenExchangeAccount {
     id: string;
     email?: string;
@@ -8,6 +9,20 @@ export interface TokenExchangeAccount {
 export interface TokenExchangeDeps {
     findAccount: (sub: string) => Promise<TokenExchangeAccount | null>;
     globalRolesClaim: string;
+    /**
+     * Resolves the global-roles claim at token-mint time. When omitted, falls back to
+     * `target.globalRoles ?? []` (unchanged behavior). Mirrors the mint-time hook used
+     * by the authorization-code flow so impersonated tokens source roles from the same
+     * authority (e.g. @adonis-agora/authz) or custom store.
+     */
+    resolveTokenRoles?: (account: AuthAccount, context: {
+        clientId?: string;
+        activeOrg?: {
+            orgId: string;
+            orgSlug: string;
+            orgRole: string;
+        } | null;
+    }) => string[] | Promise<string[]>;
     adminRole?: string;
     /**
      * Resource indicators (RFC 8707) suportados pelo provider. Quando o pedido traz

package/build/src/provider/token_exchange.js

@@ -82,12 +82,20 @@ export function registerTokenExchange(provider, deps) {
         }
         const at = new provider.AccessToken({ accountId: target.id, client, scope });
         const accessToken = await at.save();
+        // Token exchange is not tied to a browser session, so there is no active org
+        // context here — roles are resolved for the impersonated target with clientId only.
+        const roles = deps.resolveTokenRoles
+            ? await deps.resolveTokenRoles(target, {
+                clientId: client?.clientId,
+                activeOrg: null,
+            })
+            : (target.globalRoles ?? []);
         const idToken = new provider.IdToken({
             sub: target.id,
             email: target.email,
             email_verified: true,
             name: target.name,
-            [deps.globalRolesClaim]: target.globalRoles ?? [],
+            [deps.globalRolesClaim]: roles,
         }, { ctx });
         idToken.scope = scope;
         idToken.set('act', { sub: actor.id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",