@adonis-agora/authkit-server 1.0.0-rc.1 → 1.0.0-rc.11

package/build/src/service_tenants/client_metadata.js

@@ -0,0 +1,80 @@
+/**
+ * authkit-owned keys in a persisted `Client` payload. oidc-provider strips unknown
+ * metadata when it builds a `Client` (and when dynamic registration persists one), so
+ * these keys can only be written by authkit itself (console, Admin API, CLI) and are
+ * read straight from the adapter.
+ */
+export const SERVICE_TENANT_KEY = 'authkit_service_tenant';
+export const CLIENT_DISABLED_KEY = 'authkit_disabled';
+/** Letters, digits, `.`, `_`, `:` and `-`; starts with a letter or digit; up to 128 chars. */
+export const PARTITION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** Like {@link PARTITION_PATTERN}, plus `*` and `/`. */
+export const CAPABILITY_PATTERN = /^[A-Za-z0-9*][A-Za-z0-9._:*/-]{0,127}$/;
+export const MAX_CAPABILITIES = 64;
+/** Reads the service-tenant metadata from a raw client payload, or `null`. */
+export function serviceTenantOf(payload) {
+    const raw = payload?.[SERVICE_TENANT_KEY];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    if (typeof raw.partition !== 'string' || !PARTITION_PATTERN.test(raw.partition))
+        return null;
+    const capabilities = Array.isArray(raw.capabilities)
+        ? raw.capabilities.filter((c) => typeof c === 'string' && c.length > 0)
+        : [];
+    return { partition: raw.partition, capabilities };
+}
+/** `true` when the raw client payload is disabled. */
+export function isClientDisabled(payload) {
+    return payload?.[CLIENT_DISABLED_KEY] === true;
+}
+/**
+ * Validates and normalizes service-tenant input. Returns an error message or the
+ * normalized value (trimmed, de-duplicated capabilities).
+ */
+export function normalizeServiceTenant(input) {
+    // Called directly too (not only behind the HTTP validators): check the types here.
+    const rawPartition = input?.partition;
+    const partition = typeof rawPartition === 'string' ? rawPartition.trim() : '';
+    if (!PARTITION_PATTERN.test(partition)) {
+        return `partition "${partition}" is invalid: use letters, digits, ".", "_", ":" or "-" (max 128 chars)`;
+    }
+    const rawCapabilities = input.capabilities ?? [];
+    if (!Array.isArray(rawCapabilities))
+        return 'capabilities must be an array of strings';
+    const capabilities = [];
+    for (const raw of rawCapabilities) {
+        if (typeof raw !== 'string')
+            return 'capabilities must be an array of strings';
+        const cap = raw.trim();
+        if (!CAPABILITY_PATTERN.test(cap)) {
+            return `capability "${cap}" is invalid: use letters, digits, ".", "_", ":", "*", "/" or "-" (max 128 chars)`;
+        }
+        if (!capabilities.includes(cap))
+            capabilities.push(cap);
+    }
+    if (capabilities.length > MAX_CAPABILITIES) {
+        return `at most ${MAX_CAPABILITIES} capabilities per client`;
+    }
+    return { partition, capabilities };
+}
+/**
+ * Wraps the provider's `Client` adapter so a disabled client is "not found": every
+ * endpoint answers `invalid_client` from the next request on, on every instance that
+ * shares the adapter. Writes are untouched.
+ */
+export function hideDisabledClients(adapter) {
+    return new Proxy(adapter, {
+        get(target, prop, receiver) {
+            if (prop === 'find') {
+                return async (id) => {
+                    const payload = await target.find(id);
+                    return isClientDisabled(payload)
+                        ? undefined
+                        : payload;
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}

package/build/src/service_tenants/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Service tenants: confidential `client_credentials` clients that act as a partition
+ * (`partition` claim) of a resource server (e.g. a durable control plane). Their tokens
+ * are JWT access tokens (RFC 9068) whose `aud` is the resource (RFC 8707).
+ */
+/** One resource that issues service-tenant tokens. */
+export interface ServiceTenantResourceInput {
+    /** `aud` of the token. Default: the resource indicator itself. */
+    audience?: string;
+    /** Token lifetime in seconds. Default: 600 (10 minutes). */
+    expiresIn?: number;
+    /** Scopes a service tenant may request for this resource. Default: none. */
+    scopes?: string[];
+}
+export interface ServiceTenantsConfigInput {
+    /**
+     * Resource indicators (RFC 8707) that issue service-tenant tokens, e.g.
+     * `{ 'urn:agora:durable': {} }`. Only service-tenant clients can get tokens for them.
+     */
+    resources: Record<string, ServiceTenantResourceInput>;
+}
+export interface ResolvedServiceTenantResource {
+    audience: string;
+    expiresIn: number;
+    scopes: string[];
+}
+export interface ResolvedServiceTenantsConfig {
+    /** `true` when at least one resource is declared. */
+    enabled: boolean;
+    resources: Record<string, ResolvedServiceTenantResource>;
+}
+/** Default token lifetime: 10 minutes. */
+export declare const DEFAULT_SERVICE_TENANT_TTL = 600;
+/**
+ * Resolves `serviceTenants`. Throws on an invalid resource indicator, a non-positive
+ * `expiresIn`, or a resource also declared in `accessTokens.resources` (a resource is
+ * either for users or for service tenants, never both).
+ */
+export declare function resolveServiceTenants(input: ServiceTenantsConfigInput | undefined, accessTokenResources?: Record<string, unknown>): ResolvedServiceTenantsConfig;
+/** Finds a declared service-tenant resource, tolerating a trailing slash. */
+export declare function findServiceTenantResource(config: ResolvedServiceTenantsConfig, indicator: string): {
+    key: string;
+    resource: ResolvedServiceTenantResource;
+} | null;

package/build/src/service_tenants/config.js

@@ -0,0 +1,44 @@
+/**
+ * Service tenants: confidential `client_credentials` clients that act as a partition
+ * (`partition` claim) of a resource server (e.g. a durable control plane). Their tokens
+ * are JWT access tokens (RFC 9068) whose `aud` is the resource (RFC 8707).
+ */
+/** Default token lifetime: 10 minutes. */
+export const DEFAULT_SERVICE_TENANT_TTL = 600;
+const trimSlash = (s) => s.replace(/\/+$/, '');
+/**
+ * Resolves `serviceTenants`. Throws on an invalid resource indicator, a non-positive
+ * `expiresIn`, or a resource also declared in `accessTokens.resources` (a resource is
+ * either for users or for service tenants, never both).
+ */
+export function resolveServiceTenants(input, accessTokenResources = {}) {
+    const resources = {};
+    const userResources = new Set(Object.keys(accessTokenResources).map(trimSlash));
+    for (const [indicator, rc] of Object.entries(input?.resources ?? {})) {
+        const parsed = URL.parse(indicator);
+        if (!parsed || indicator.includes('#')) {
+            throw new Error(`authkit: serviceTenants.resources["${indicator}"] must be an absolute URI without a fragment (e.g. "urn:agora:durable").`);
+        }
+        if (userResources.has(trimSlash(indicator))) {
+            throw new Error(`authkit: "${indicator}" is declared in both accessTokens.resources and serviceTenants.resources. Pick one.`);
+        }
+        const expiresIn = rc?.expiresIn ?? DEFAULT_SERVICE_TENANT_TTL;
+        if (!Number.isInteger(expiresIn) || expiresIn <= 0) {
+            throw new Error(`authkit: serviceTenants.resources["${indicator}"].expiresIn must be a positive integer (seconds).`);
+        }
+        resources[indicator] = {
+            audience: rc?.audience ?? indicator,
+            expiresIn,
+            scopes: [...(rc?.scopes ?? [])],
+        };
+    }
+    return { enabled: Object.keys(resources).length > 0, resources };
+}
+/** Finds a declared service-tenant resource, tolerating a trailing slash. */
+export function findServiceTenantResource(config, indicator) {
+    if (config.resources[indicator])
+        return { key: indicator, resource: config.resources[indicator] };
+    const trimmed = trimSlash(indicator);
+    const key = Object.keys(config.resources).find((k) => trimSlash(k) === trimmed);
+    return key ? { key, resource: config.resources[key] } : null;
+}

package/build/src/service_tenants/provider_hooks.d.ts

@@ -0,0 +1,52 @@
+import type { OidcAdapterClass } from '../adapters/factory.js';
+import type { AuditSink } from '../audit/audit_sink.js';
+import { type ResolvedServiceTenantsConfig } from './config.js';
+export interface ServiceTenantHooksDeps {
+    serviceTenants: ResolvedServiceTenantsConfig;
+    /** Adapter class of the `Client` model (raw: sees authkit's own keys). */
+    AdapterClass: OidcAdapterClass;
+    audit?: AuditSink;
+}
+/** Resource server info for a service-tenant resource, in oidc-provider's shape. */
+export interface ServiceTenantResourceServerInfo {
+    scope: string;
+    audience: string;
+    accessTokenFormat: 'jwt';
+    accessTokenTTL: number;
+    jwt: {
+        sign: {
+            alg: string;
+        };
+    };
+}
+/**
+ * The provider hooks behind service tenants:
+ *
+ * - a service-tenant resource is granted only to a service-tenant client, only on the
+ *   `client_credentials` grant, always as a JWT access token (RFC 9068);
+ * - a service-tenant client can only get tokens for a service-tenant resource (when
+ *   it sends no `resource` and exactly one is declared, that one is used);
+ * - its tokens carry the `partition` (and `capabilities`) claims read from the client
+ *   at issuance time, so an edit applies to the next token.
+ */
+export declare function createServiceTenantHooks(deps: ServiceTenantHooksDeps): {
+    enabled: boolean;
+    /**
+     * `defaultResource` for a service-tenant client: the only declared resource, or
+     * `invalid_target` when several are declared. `undefined` for any other client.
+     */
+    defaultResource(ctx: any, client: any): Promise<string | undefined>;
+    /**
+     * `getResourceServerInfo` for service tenants. Returns the info for a
+     * service-tenant resource, `undefined` when neither the resource nor the client is
+     * a service-tenant one (the caller handles it), and throws `invalid_target` for a
+     * mismatch.
+     */
+    resourceServerInfo(ctx: any, indicator: string, client: any, signAlg: string): Promise<ServiceTenantResourceServerInfo | undefined>;
+    /** `extraTokenClaims` for a service-tenant token; audits the issuance. */
+    extraClaims(ctx: any, token: any): Promise<{
+        partition: string;
+        capabilities?: string[];
+    } | undefined>;
+};
+export type ServiceTenantHooks = ReturnType<typeof createServiceTenantHooks>;

package/build/src/service_tenants/provider_hooks.js

@@ -0,0 +1,124 @@
+import { errors } from 'oidc-provider';
+import { serviceTenantOf } from './client_metadata.js';
+import { findServiceTenantResource } from './config.js';
+/**
+ * The provider hooks behind service tenants:
+ *
+ * - a service-tenant resource is granted only to a service-tenant client, only on the
+ *   `client_credentials` grant, always as a JWT access token (RFC 9068);
+ * - a service-tenant client can only get tokens for a service-tenant resource (when
+ *   it sends no `resource` and exactly one is declared, that one is used);
+ * - its tokens carry the `partition` (and `capabilities`) claims read from the client
+ *   at issuance time, so an edit applies to the next token.
+ */
+export function createServiceTenantHooks(deps) {
+    const { serviceTenants } = deps;
+    const memo = new WeakMap();
+    let adapter;
+    const read = async (clientId) => {
+        adapter ??= new deps.AdapterClass('Client');
+        return serviceTenantOf((await adapter.find(clientId)));
+    };
+    /** Service-tenant info of the client, memoized per request. */
+    const tenantOf = (ctx, clientId) => {
+        if (!clientId)
+            return Promise.resolve(null);
+        const key = ctx && typeof ctx === 'object' ? ctx : null;
+        if (!key)
+            return read(clientId);
+        let byClient = memo.get(key);
+        if (!byClient) {
+            byClient = new Map();
+            memo.set(key, byClient);
+        }
+        let pending = byClient.get(clientId);
+        if (!pending) {
+            pending = read(clientId);
+            byClient.set(clientId, pending);
+        }
+        return pending;
+    };
+    return {
+        enabled: serviceTenants.enabled,
+        /**
+         * `defaultResource` for a service-tenant client: the only declared resource, or
+         * `invalid_target` when several are declared. `undefined` for any other client.
+         */
+        async defaultResource(ctx, client) {
+            if (!serviceTenants.enabled)
+                return undefined;
+            if (!(await tenantOf(ctx, client?.clientId)))
+                return undefined;
+            const keys = Object.keys(serviceTenants.resources);
+            if (keys.length === 1)
+                return keys[0];
+            throw new errors.InvalidTarget('a service tenant must send the resource parameter');
+        },
+        /**
+         * `getResourceServerInfo` for service tenants. Returns the info for a
+         * service-tenant resource, `undefined` when neither the resource nor the client is
+         * a service-tenant one (the caller handles it), and throws `invalid_target` for a
+         * mismatch.
+         */
+        async resourceServerInfo(ctx, indicator, client, signAlg) {
+            if (!serviceTenants.enabled)
+                return undefined;
+            const found = findServiceTenantResource(serviceTenants, indicator);
+            const tenant = await tenantOf(ctx, client?.clientId);
+            if (found) {
+                const grantType = ctx?.oidc?.params?.grant_type;
+                if (!tenant || grantType !== 'client_credentials') {
+                    throw new errors.InvalidTarget(`resource indicator not allowed: ${indicator}`);
+                }
+                return {
+                    scope: found.resource.scopes.join(' '),
+                    audience: found.resource.audience,
+                    accessTokenFormat: 'jwt',
+                    accessTokenTTL: found.resource.expiresIn,
+                    jwt: { sign: { alg: signAlg } },
+                };
+            }
+            if (tenant) {
+                throw new errors.InvalidTarget(`resource indicator not allowed for a service tenant: ${indicator}`);
+            }
+            return undefined;
+        },
+        /** `extraTokenClaims` for a service-tenant token; audits the issuance. */
+        async extraClaims(ctx, token) {
+            if (!serviceTenants.enabled || token?.kind !== 'ClientCredentials')
+                return undefined;
+            const rs = token.resourceServer;
+            const indicator = typeof rs?.identifier === 'function' ? rs.identifier() : undefined;
+            if (typeof indicator !== 'string')
+                return undefined;
+            const found = findServiceTenantResource(serviceTenants, indicator);
+            if (!found)
+                return undefined;
+            const tenant = await tenantOf(ctx, token.clientId);
+            if (!tenant)
+                return undefined;
+            try {
+                await deps.audit
+                    ?.record({
+                    type: 'service_tenant.token_issued',
+                    clientId: token.clientId,
+                    ip: typeof ctx?.ip === 'string' ? ctx.ip : null,
+                    metadata: {
+                        partition: tenant.partition,
+                        resource: found.key,
+                        jti: token.jti,
+                        expiresIn: found.resource.expiresIn,
+                    },
+                })
+                    .catch(() => { });
+            }
+            catch {
+                // Auditing is best-effort: it never fails an issuance.
+            }
+            return {
+                partition: tenant.partition,
+                ...(tenant.capabilities.length ? { capabilities: tenant.capabilities } : {}),
+            };
+        },
+    };
+}

package/build/src/service_tenants/tenant_verifier.d.ts

@@ -0,0 +1,73 @@
+import type { ResolvedServiceTenantsConfig } from './config.js';
+/**
+ * What a verified tenant token authenticates as. Same shape as `VerifiedTenant` in
+ * `@adonis-agora/durable` (declared here: authkit never imports durable).
+ */
+export interface VerifiedTenant {
+    tenant: string;
+    capabilities?: string[] | undefined;
+}
+/** The input a control plane hands to its tenant verifier. */
+export interface TenantVerifierInput {
+    /** The token the tenant presented. */
+    token?: string | undefined;
+    /** The tenant the request claims to be. Advisory only: the token decides. */
+    tenant?: string | undefined;
+}
+/** The issuer the verifier checks against: the local authkit server. */
+export interface TenantTokenIssuer {
+    readonly publicJwks: {
+        keys: Record<string, any>[];
+    };
+    readonly config: {
+        issuer: string;
+        serviceTenants?: ResolvedServiceTenantsConfig;
+    };
+}
+export interface AuthkitTenantVerifierOptions {
+    /**
+     * Expected `aud`. Default: the audience of the only resource in
+     * `serviceTenants.resources` (required when several are declared).
+     */
+    audience?: string;
+    /** Claim holding the partition. Default: `'partition'`. */
+    partitionClaim?: string;
+    /** Claim holding the capabilities. Default: `'capabilities'`. */
+    capabilitiesClaim?: string;
+    /** Allowed clock skew in seconds for `exp`/`nbf`/`iat`. Default: 30. */
+    clockToleranceSec?: number;
+    /**
+     * Where the issuer comes from. Default: the `authkit.server` binding of the booted
+     * app. Read on every call, so a signing-key rotation applies right away.
+     */
+    issuer?: () => TenantTokenIssuer | Promise<TenantTokenIssuer>;
+}
+/**
+ * Verifies service-tenant tokens against the local authkit issuer and its JWKS (no
+ * network call), and returns the tenant they authenticate as, or `null`.
+ *
+ * Satisfies durable's `TenantVerifierContract` (`verify(input)`); usable as a class in
+ * `verifyTenant` (built by the container with the default options) or through
+ * {@link authkitTenantVerifier}.
+ */
+export declare class AuthkitTenantVerifier {
+    #private;
+    constructor(options?: AuthkitTenantVerifierOptions);
+    verify(input: TenantVerifierInput): Promise<VerifiedTenant | null>;
+}
+/** A tenant verifier usable both as a function and as an object with `verify`. */
+export type AuthkitTenantVerifierFn = ((input: TenantVerifierInput) => Promise<VerifiedTenant | null>) & {
+    verify(input: TenantVerifierInput): Promise<VerifiedTenant | null>;
+};
+/**
+ * Tenant verifier for a durable control plane hosted by the authkit app:
+ *
+ * ```ts
+ * // config/durable.ts
+ * verifyTenant: authkitTenantVerifier()
+ * ```
+ *
+ * The result is a function (durable's `TenantVerifier`) that also has `verify`
+ * (durable's `TenantVerifierContract`).
+ */
+export declare function authkitTenantVerifier(options?: AuthkitTenantVerifierOptions): AuthkitTenantVerifierFn;

package/build/src/service_tenants/tenant_verifier.js

@@ -0,0 +1,104 @@
+import { createLocalJWKSet, errors as joseErrors, jwtVerify } from 'jose';
+import { getBootedApp } from '../../services/booted_app.js';
+/** Asymmetric JWS algorithms only: never `none`, never `HS*`. */
+const ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+    'Ed25519',
+];
+const defaultIssuer = async () => (await getBootedApp().container.make('authkit.server'));
+function audienceFor(issuer, explicit) {
+    if (explicit)
+        return explicit;
+    const resources = Object.values(issuer.config.serviceTenants?.resources ?? {});
+    if (resources.length === 1)
+        return resources[0].audience;
+    throw new Error(resources.length === 0
+        ? 'authkitTenantVerifier: no serviceTenants.resources declared in config/authkit.ts'
+        : 'authkitTenantVerifier: several serviceTenants.resources are declared; pass { audience }');
+}
+/**
+ * Verifies service-tenant tokens against the local authkit issuer and its JWKS (no
+ * network call), and returns the tenant they authenticate as, or `null`.
+ *
+ * Satisfies durable's `TenantVerifierContract` (`verify(input)`); usable as a class in
+ * `verifyTenant` (built by the container with the default options) or through
+ * {@link authkitTenantVerifier}.
+ */
+export class AuthkitTenantVerifier {
+    #options;
+    #jwks;
+    #keySet;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    #keySetFor(jwks) {
+        // `publicJwks` is a new object whenever the keys change (rotation/reload).
+        if (jwks !== this.#jwks || !this.#keySet) {
+            this.#jwks = jwks;
+            this.#keySet = createLocalJWKSet(jwks);
+        }
+        return this.#keySet;
+    }
+    async verify(input) {
+        const token = input?.token;
+        if (typeof token !== 'string' || !token)
+            return null;
+        const issuer = await (this.#options.issuer ?? defaultIssuer)();
+        const audience = audienceFor(issuer, this.#options.audience);
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, this.#keySetFor(issuer.publicJwks), {
+                issuer: issuer.config.issuer,
+                audience,
+                algorithms: ALGORITHMS,
+                typ: 'at+jwt',
+                clockTolerance: this.#options.clockToleranceSec ?? 30,
+                requiredClaims: ['exp', 'sub'],
+            }));
+        }
+        catch (error) {
+            if (error instanceof joseErrors.JOSEError)
+                return null;
+            throw error;
+        }
+        // A client_credentials token: no user behind it, `sub` is the client.
+        const clientId = payload.client_id;
+        if (typeof clientId !== 'string' || payload.sub !== clientId)
+            return null;
+        const partition = payload[this.#options.partitionClaim ?? 'partition'];
+        if (typeof partition !== 'string' || !partition)
+            return null;
+        const rawCapabilities = payload[this.#options.capabilitiesClaim ?? 'capabilities'];
+        if (rawCapabilities === undefined)
+            return { tenant: partition };
+        if (!Array.isArray(rawCapabilities) || rawCapabilities.some((c) => typeof c !== 'string')) {
+            return null;
+        }
+        return { tenant: partition, capabilities: rawCapabilities };
+    }
+}
+/**
+ * Tenant verifier for a durable control plane hosted by the authkit app:
+ *
+ * ```ts
+ * // config/durable.ts
+ * verifyTenant: authkitTenantVerifier()
+ * ```
+ *
+ * The result is a function (durable's `TenantVerifier`) that also has `verify`
+ * (durable's `TenantVerifierContract`).
+ */
+export function authkitTenantVerifier(options = {}) {
+    const verifier = new AuthkitTenantVerifier(options);
+    const verify = (input) => verifier.verify(input);
+    return Object.assign(verify, { verify });
+}

package/build/src/tenancy/tenant_labels.d.ts

@@ -0,0 +1,30 @@
+import type { AccountStore, OrgSummary } from '../accounts/account_store.js';
+/** What `config/context.ts` → `tenancy.label` expects: tenant id → display label. */
+export type TenantLabelResolver = (ids: readonly string[]) => Promise<Record<string, string>>;
+export interface AuthkitTenantLabelsOptions {
+    /** Which field labels an organization: `'name'` (default), `'slug'`, or your own function. */
+    label?: 'name' | 'slug' | ((org: OrgSummary) => string);
+    /**
+     * Where the account store comes from. Default: the `authkit.server` binding of the
+     * booted app (`config/authkit.ts` → `accountStore`).
+     */
+    store?: () => AccountStore | Promise<AccountStore>;
+}
+/**
+ * A tenant label resolver backed by authkit organizations, for
+ * `config/context.ts` → `tenancy.label`. Consoles call it with the tenant ids they
+ * are about to show; it returns `{ [orgId]: name }` for the ids that are authkit
+ * organizations. Ids it does not know (personal tenants, other kinds) are left
+ * out, so the console shows the id. It only reads labels: no membership, role or
+ * metadata leaves it.
+ *
+ * ```ts
+ * // config/context.ts
+ * import { authkitTenantLabels } from '@adonis-agora/authkit-server'
+ *
+ * export default defineConfig({
+ *   tenancy: { enabled: true, kinds: ['organization'], label: authkitTenantLabels() },
+ * })
+ * ```
+ */
+export declare function authkitTenantLabels(options?: AuthkitTenantLabelsOptions): TenantLabelResolver;

package/build/src/tenancy/tenant_labels.js

@@ -0,0 +1,64 @@
+import { getBootedApp } from '../../services/booted_app.js';
+import { supportsOrganizations } from '../accounts/account_store.js';
+/** Fallback walk without `findOrgsByIds`: one lookup per id, at most this many ids. */
+const FALLBACK_MAX = 200;
+const defaultStore = async () => {
+    const service = (await getBootedApp().container.make('authkit.server'));
+    return service.config.accountStore;
+};
+/**
+ * A tenant label resolver backed by authkit organizations, for
+ * `config/context.ts` → `tenancy.label`. Consoles call it with the tenant ids they
+ * are about to show; it returns `{ [orgId]: name }` for the ids that are authkit
+ * organizations. Ids it does not know (personal tenants, other kinds) are left
+ * out, so the console shows the id. It only reads labels: no membership, role or
+ * metadata leaves it.
+ *
+ * ```ts
+ * // config/context.ts
+ * import { authkitTenantLabels } from '@adonis-agora/authkit-server'
+ *
+ * export default defineConfig({
+ *   tenancy: { enabled: true, kinds: ['organization'], label: authkitTenantLabels() },
+ * })
+ * ```
+ */
+export function authkitTenantLabels(options = {}) {
+    const pick = typeof options.label === 'function'
+        ? options.label
+        : options.label === 'slug'
+            ? (org) => org.slug
+            : (org) => org.name;
+    return async (ids) => {
+        const wanted = [
+            ...new Set((Array.isArray(ids) ? ids : []).filter((id) => typeof id === 'string' && id)),
+        ];
+        if (wanted.length === 0)
+            return {};
+        const store = await (options.store ?? defaultStore)();
+        if (!store || !supportsOrganizations(store))
+            return {};
+        let orgs;
+        if (typeof store.findOrgsByIds === 'function') {
+            orgs = await store.findOrgsByIds(wanted);
+        }
+        else {
+            orgs = [];
+            for (const id of wanted.slice(0, FALLBACK_MAX)) {
+                const org = await store.findOrgById(id);
+                if (org)
+                    orgs.push(org);
+            }
+        }
+        const asked = new Set(wanted);
+        const labels = {};
+        for (const org of orgs) {
+            if (!asked.has(org.id))
+                continue;
+            const label = pick(org);
+            if (typeof label === 'string' && label !== '')
+                labels[org.id] = label;
+        }
+        return labels;
+    };
+}

package/build/types.d.ts

@@ -1,4 +1,5 @@
 import type { MetricsRecorder } from '@adonis-agora/authkit-core';
+import type { AccountExtensionRegistry } from './src/account/extension.js';
 import type { AccountStore } from './src/accounts/account_store.js';
 import type { PatStore } from './src/pat/pat_store.js';
 import type { OidcService } from './src/provider/oidc_service.js';
@@ -22,6 +23,7 @@ declare module '@adonisjs/core/types' {
         'authkit.metrics': MetricsRecorder;
         'authkit.accountStore': AccountStore;
         'authkit.patStore': PatStore;
+        'authkit.accountExtensions': AccountExtensionRegistry;
     }
 }
-export type { AccountStore, MetricsRecorder, OidcService, PatStore };
+export type { AccountExtensionRegistry, AccountStore, MetricsRecorder, OidcService, PatStore };