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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/authkit-client
 
+## 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

@@ -30,6 +30,7 @@ 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';

package/build/providers/authkit_client_provider.d.ts

@@ -162,6 +162,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

@@ -11,6 +11,7 @@ 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;
@@ -457,6 +458,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 +480,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;

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

@@ -2,6 +2,7 @@ import type { Identity } 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 };
@@ -76,6 +77,12 @@ 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;
 }
 export interface ResolvedClientConfig {
     issuer: string;
@@ -101,5 +108,7 @@ export interface ResolvedClientConfig {
     };
     /** Endpoint overrides. See {@link ClientConfigInput.endpoints}. */
     endpoints?: Partial<OidcEndpoints>;
+    /** Tenancy options. See {@link ClientConfigInput.tenancy}. */
+    tenancy?: ClientTenancyOptions;
 }
 export declare function defineConfig(config: ClientConfigInput): import("@adonisjs/core/types").ConfigProvider<ResolvedClientConfig>;

package/build/src/define_config.js

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

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/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.4",
   "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",
@@ -81,7 +81,7 @@
     "jose": "6.2.16"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "1.0.0-rc.4",
+    "@adonis-agora/authkit-server": "1.0.0-rc.7",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",