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

package/build/src/host/ui-dist/index.html

@@ -8,7 +8,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Sora:wght@400;500;600;700&family=JetBrains+Mono:ital,wght@0,400;0,500;0,600;1,400&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="/__AUTHKIT_BASE__/assets/index-D0EIeyKK.js"></script>
+    <script type="module" crossorigin src="/__AUTHKIT_BASE__/assets/index-u0bMxkLg.js"></script>
     <link rel="stylesheet" crossorigin href="/__AUTHKIT_BASE__/assets/index-DTSmD4RU.css">
   </head>
   <body>

package/build/src/provider/build_provider.js

@@ -3,6 +3,8 @@ import { pickModelAdapterClass } from '../adapters/factory.js';
 import { normalizeActiveOrg, readActiveOrgFromKoaCtx } from '../host/active_org_cookie.js';
 import { consoleSsoClientMetadata } from '../host/console_sso.js';
 import { findMcpResource, mcpAuthorizeMiddleware } from '../mcp/mcp_oauth.js';
+import { hideDisabledClients } from '../service_tenants/client_metadata.js';
+import { createServiceTenantHooks } from '../service_tenants/provider_hooks.js';
 import { createDeviceSources } from './device_sources.js';
 import { createLogoutSources } from './logout_sources.js';
 import { registrationPolicyMiddleware } from './registration_policy.js';
@@ -79,21 +81,35 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
         return key ? { key, rc: at.resources[key] } : null;
     };
     const mcp = config.mcp;
-    const resourceIndicatorFeatures = at.anyJwt || declaredResources.length > 0 || mcp.enabled
+    // Service tenants (`serviceTenants`): `client_credentials` clients with a partition,
+    // whose tokens are JWTs for a service-tenant resource. See `service_tenants/`.
+    const serviceTenants = createServiceTenantHooks({
+        serviceTenants: config.serviceTenants ?? { enabled: false, resources: {} },
+        AdapterClass: config.AdapterClass,
+        audit: config.audit,
+    });
+    const signAlg = config.jwks.keys[0]?.alg ?? 'RS256';
+    const resourceIndicatorFeatures = at.anyJwt || declaredResources.length > 0 || mcp.enabled || serviceTenants.enabled
         ? {
             resourceIndicators: {
                 enabled: true,
-                defaultResource: async (_ctx, _client, oneOf) => {
+                defaultResource: async (ctx, client, oneOf) => {
                     // Nas trocas (code/refresh/device), o provider passa `oneOf` com as
                     // resources já concedidas — devolvemos para não falhar a request.
                     if (oneOf)
                         return oneOf;
+                    const serviceResource = await serviceTenants.defaultResource(ctx, client);
+                    if (serviceResource)
+                        return serviceResource;
                     // Authorize/sem resource explícito: no modo JWT, liga ao resource
                     // default (modo simples). Só opaco: sem resource (AT de sempre).
                     return at.anyJwt ? at.audience : undefined;
                 },
                 useGrantedResource: async () => true,
-                getResourceServerInfo: (_ctx, resourceIndicator, _client) => {
+                getResourceServerInfo: async (ctx, resourceIndicator, client) => {
+                    const serviceInfo = await serviceTenants.resourceServerInfo(ctx, resourceIndicator, client, signAlg);
+                    if (serviceInfo)
+                        return serviceInfo;
                     const found = findResource(resourceIndicator);
                     const isDefault = at.anyJwt && resourceIndicator === at.audience;
                     // Servidores MCP (`mcp`): os declarados e os registrados em runtime.
@@ -122,7 +138,7 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
                         info.accessTokenTTL = ttl;
                     if (format === 'jwt') {
                         // Assina com a chave de assinatura corrente do keystore (mesma do JWKS).
-                        info.jwt = { sign: { alg: config.jwks.keys[0]?.alg ?? 'RS256' } };
+                        info.jwt = { sign: { alg: signAlg } };
                     }
                     return info;
                 },
@@ -138,13 +154,23 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
         // O ator (`act`, RFC 8693) dos access tokens de impersonation — ver
         // `impersonationExtraClaims` em `token_exchange.ts`. Sem isto o token trocado
         // não se distingue de um token do próprio alvo no resource server.
-        extraTokenClaims: async (_ctx, token) => impersonationExtraClaims(token),
+        // Service tenants add `partition`/`capabilities` (see `service_tenants/`).
+        extraTokenClaims: async (ctx, token) => {
+            const actor = impersonationExtraClaims(token);
+            const tenant = await serviceTenants.extraClaims(ctx, token);
+            return actor || tenant ? { ...tenant, ...actor } : undefined;
+        },
         // Dispatcher por modelo (suportado pelo oidc-provider: `Adapter` aceita
         // função `(name) => adapter` além de classe). Session-scoped vai pro
         // `SessionAdapterClass`, o resto pro `AdapterClass` — mesma regra de
         // `pickModelAdapterClass`, usada também pelos serviços que instanciam
         // adapter na mão. Sem `session.adapter`, as duas classes são a mesma.
-        adapter: ((name) => new (pickModelAdapterClass(name, config.AdapterClass, config.SessionAdapterClass))(name)),
+        // A disabled client (`authkit_disabled`) is "not found" for the provider: every
+        // endpoint answers `invalid_client` on the next request.
+        adapter: ((name) => {
+            const instance = new (pickModelAdapterClass(name, config.AdapterClass, config.SessionAdapterClass))(name);
+            return name === 'Client' ? hideDisabledClients(instance) : instance;
+        }),
         findAccount: options.findAccount,
         // Grant REAPROVEITADO (consent já lembrado): o org capturado no primeiro
         // consent ficaria VELHO se o usuário trocasse de org no console e voltasse a
@@ -244,6 +270,7 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
             backchannelLogout: { enabled: true },
             revocation: { enabled: true },
             introspection: { enabled: true },
+            ...(serviceTenants.enabled ? { clientCredentials: { enabled: true } } : {}),
             ...registrationFeatures,
             ...deviceFlowFeatures,
             ...dpopFeatures,
@@ -279,6 +306,10 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
                     ? sessionTtlHolder.transientSec
                     : sessionTtlHolder.rememberSec
                 : config.ttl.session,
+            // `client_credentials` tokens: the resource's lifetime (a service-tenant resource
+            // always sets one), else the access-token TTL.
+            ClientCredentials: (_ctx, token) => token?.resourceServer?.accessTokenTTL ??
+                (tokenTtlHolder ? tokenTtlHolder.accessTokenSec : config.ttl.accessToken),
             Interaction: 3600,
             Grant: tokenTtlHolder
                 ? () => tokenTtlHolder.refreshTokenSec

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

@@ -28,7 +28,7 @@ export declare class OidcService {
     };
     /**
      * @internal Segredo derivado da app key para um uso (`label`) — HMAC dos nonces
-     * DPoP do Poppy, por exemplo. Igual em todas as instâncias, sem expor a chave.
+     * DPoP de uma extension de personal agents, por exemplo. Igual em todas as instâncias, sem expor a chave.
      */
     deriveSecret(label: string): Buffer;
     /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */

package/build/src/provider/oidc_service.js

@@ -44,7 +44,7 @@ export class OidcService {
     }
     /**
      * @internal Segredo derivado da app key para um uso (`label`) — HMAC dos nonces
-     * DPoP do Poppy, por exemplo. Igual em todas as instâncias, sem expor a chave.
+     * DPoP de uma extension de personal agents, por exemplo. Igual em todas as instâncias, sem expor a chave.
      */
     deriveSecret(label) {
         return createHmac('sha256', this.#appKey).update(`authkit:${label}`).digest();

package/build/src/schema/ensure.d.ts

@@ -23,9 +23,15 @@
  * }
  * ```
  */
+import type { AuthkitTable } from '../agents/extension.js';
 export interface EnsureSchemaOptions {
     /** Conexão Lucid a usar. Default: conexão primária. */
     connection?: string;
+    /**
+     * Tabelas de `personalAgents.extensions` (`tables` de cada uma), garantidas junto. O provider
+     * passa as do config no boot.
+     */
+    tables?: readonly AuthkitTable[];
     /**
      * Tabela da conta, onde a coluna opcional `login_methods` pertence. Vem do
      * metadado `accountStore.accountTable` (o provider repassa no boot). Undefined
@@ -51,6 +57,14 @@ export interface EnsureSchemaReport {
         ensured: boolean;
     };
 }
+/**
+ * Garante tabelas lib-owned no formato {@link AuthkitTable} — o que `ensureAuthkitSchema` faz com as
+ * do authkit: cria as que faltam, adiciona colunas e índices novos, nunca dropa nem altera. Para
+ * uma extension expor o próprio `ensure*Schema()` para migrations do host. Estável no 1.x.
+ */
+export declare function ensureAuthkitTables(db: any, tables: readonly AuthkitTable[], options?: {
+    connection?: string;
+}): Promise<Pick<EnsureSchemaReport, 'created' | 'altered' | 'indexed'>>;
 /**
  * Garante que as tabelas do authkit existem e têm todas as colunas que esta
  * versão da lib espera. Aditivo e idempotente — seguro de rodar em todo boot

package/build/src/schema/ensure.js

@@ -309,7 +309,7 @@ const TABLES = [
         name: 'auth_agent_registry',
         /**
          * Agentes liberados (`allowed`) ou bloqueados (`blocked`) pelo console admin,
-         * somados ao `defineConfig` — PACT pelo `iss`, Poppy pelo `client_id`.
+         * somados ao `defineConfig` — PACT pelo `iss`; uma extension pelo identificador dela.
          */
         create: (t) => {
             t.string('id').primary();
@@ -333,135 +333,6 @@ const TABLES = [
             updated_at: (t) => t.dateTime('updated_at', { useTz: true, precision: 3 }).nullable(),
         },
     },
-    /*
-     * Personal Agent Protocol (Poppy). Os refresh tokens são grants de
-     * `auth_agent_grants` (prefixo `pgrant_`) com o hash em
-     * `auth_agent_refresh_tokens`; aqui ficam Sessions, access tokens, pedidos de
-     * sign-in e os `jti` vistos. Mesmas regras de data das tabelas acima.
-     */
-    {
-        name: 'auth_poppy_sessions',
-        /**
-         * Uma Session: um usuário do agente (`user_id`, opaco) num agente (`client_id`), com o
-         * `agent_id` opcional. `account_id` é a conta que já usou. `grant_id` e `scope` ficaram da
-         * Draft 0.1, sem uso (o schema só é aditivo).
-         */
-        create: (t) => {
-            t.string('id').primary();
-            t.string('client_id', 2048).notNullable();
-            t.string('user_id').notNullable();
-            t.string('agent_id').nullable();
-            t.string('account_id').nullable().index();
-            t.string('grant_id').nullable().index();
-            t.text('scope').notNullable();
-            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable();
-            t.dateTime('ended_at', { useTz: true, precision: 3 }).nullable();
-            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
-            t.dateTime('updated_at', { useTz: true, precision: 3 }).notNullable();
-        },
-        columns: {
-            client_id: (t) => t.string('client_id', 2048),
-            user_id: (t) => t.string('user_id'),
-            agent_id: (t) => t.string('agent_id').nullable(),
-            account_id: (t) => t.string('account_id').nullable().index(),
-            grant_id: (t) => t.string('grant_id').nullable().index(),
-            scope: (t) => t.text('scope'),
-            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
-            ended_at: (t) => t.dateTime('ended_at', { useTz: true, precision: 3 }).nullable(),
-            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
-            updated_at: (t) => t.dateTime('updated_at', { useTz: true, precision: 3 }).nullable(),
-        },
-    },
-    {
-        name: 'auth_poppy_tokens',
-        /**
-         * Access tokens — só o hash. `jkt` = chave DPoP; `null` = Bearer. `session_id` e `user_id`
-         * ficaram da Draft 0.1 e saem vazios: o sign-in não conhece a Session.
-         */
-        create: (t) => {
-            t.string('token_hash', 64).primary();
-            t.string('session_id').notNullable().index();
-            t.string('client_id', 2048).notNullable();
-            t.string('user_id').notNullable();
-            t.string('account_id').nullable();
-            t.string('grant_id').nullable().index();
-            t.text('scope').notNullable();
-            t.string('resource', 2048).nullable();
-            t.string('jkt', 64).nullable();
-            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable().index();
-            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
-        },
-        columns: {
-            session_id: (t) => t.string('session_id').index(),
-            client_id: (t) => t.string('client_id', 2048),
-            user_id: (t) => t.string('user_id'),
-            account_id: (t) => t.string('account_id').nullable(),
-            grant_id: (t) => t.string('grant_id').nullable().index(),
-            scope: (t) => t.text('scope'),
-            resource: (t) => t.string('resource', 2048).nullable(),
-            jkt: (t) => t.string('jkt', 64).nullable(),
-            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
-            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
-        },
-    },
-    {
-        name: 'auth_poppy_requests',
-        /**
-         * Pedidos: `authorize` (Direct — vira código após o consentimento), `device` (RFC 8628),
-         * `mediated` (aguardando o código de uso único) e `browser` (entrada de um navegador, §6).
-         * Códigos só como hash. Linhas expiradas são apagadas no próximo pedido.
-         */
-        create: (t) => {
-            t.string('id').primary();
-            t.string('kind', 16).notNullable();
-            t.string('code_hash', 64).nullable().unique();
-            t.string('user_code', 16).nullable().unique();
-            t.string('client_id', 2048).notNullable();
-            t.string('session_id').nullable();
-            t.string('account_id').nullable();
-            t.text('requested_scope').notNullable();
-            t.text('granted_scope').nullable();
-            t.string('redirect_uri', 2048).nullable();
-            t.string('code_challenge', 128).nullable();
-            t.string('status', 16).notNullable();
-            t.integer('attempts').notNullable().defaultTo(0);
-            t.integer('interval_seconds').nullable();
-            t.dateTime('last_polled_at', { useTz: true, precision: 3 }).nullable();
-            t.text('data').nullable();
-            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable().index();
-            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
-        },
-        columns: {
-            kind: (t) => t.string('kind', 16),
-            code_hash: (t) => t.string('code_hash', 64).nullable(),
-            user_code: (t) => t.string('user_code', 16).nullable(),
-            client_id: (t) => t.string('client_id', 2048),
-            session_id: (t) => t.string('session_id').nullable(),
-            account_id: (t) => t.string('account_id').nullable(),
-            requested_scope: (t) => t.text('requested_scope'),
-            granted_scope: (t) => t.text('granted_scope').nullable(),
-            redirect_uri: (t) => t.string('redirect_uri', 2048).nullable(),
-            code_challenge: (t) => t.string('code_challenge', 128).nullable(),
-            status: (t) => t.string('status', 16),
-            attempts: (t) => t.integer('attempts').defaultTo(0),
-            interval_seconds: (t) => t.integer('interval_seconds').nullable(),
-            last_polled_at: (t) => t.dateTime('last_polled_at', { useTz: true, precision: 3 }).nullable(),
-            data: (t) => t.text('data').nullable(),
-            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
-            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
-        },
-    },
-    {
-        name: 'auth_poppy_jtis',
-        /** `jti` já aceitos (client assertions, Session JWTs, provas DPoP), até expirarem — anti-replay entre instâncias. */
-        create: (t) => {
-            t.string('key', 100).primary();
-            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable().index();
-        },
-        columns: {
-            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
-        },
-    },
 ];
 /** Linhas de um `rawQuery`, no formato de cada driver (pg, mysql2, sqlite). */
 function catalogRows(result) {
@@ -586,26 +457,9 @@ async function ensureIndex(conn, table, index) {
         throw error;
     }
 }
-/**
- * Garante que as tabelas do authkit existem e têm todas as colunas que esta
- * versão da lib espera. Aditivo e idempotente — seguro de rodar em todo boot
- * e dentro de migrations.
- *
- * `db` é o manager (`Database`, no boot) ou o client da própria migration
- * (`this.db`, um `QueryClient`/`TransactionClient`, usado como está).
- */
-export async function ensureAuthkitSchema(db, options = {}) {
-    const conn = typeof db.connection !== 'function'
-        ? db
-        : options.connection
-            ? db.connection(options.connection)
-            : db.connection();
-    const report = {
-        created: [],
-        altered: {},
-        loginMethods: { table: options.accountTable ?? 'users', ensured: false },
-    };
-    for (const def of TABLES) {
+/** Cria/completa as tabelas (o miolo de {@link ensureAuthkitSchema}). */
+async function ensureTables(conn, tables, report) {
+    for (const def of tables) {
         if (!(await tableExists(conn, def.name))) {
             try {
                 await conn.schema.createTable(def.name, def.create);
@@ -639,6 +493,45 @@ export async function ensureAuthkitSchema(db, options = {}) {
             report.indexed[def.name].push(index.name);
         }
     }
+}
+/**
+ * Garante tabelas lib-owned no formato {@link AuthkitTable} — o que `ensureAuthkitSchema` faz com as
+ * do authkit: cria as que faltam, adiciona colunas e índices novos, nunca dropa nem altera. Para
+ * uma extension expor o próprio `ensure*Schema()` para migrations do host. Estável no 1.x.
+ */
+export async function ensureAuthkitTables(db, tables, options = {}) {
+    const conn = typeof db.connection !== 'function'
+        ? db
+        : options.connection
+            ? db.connection(options.connection)
+            : db.connection();
+    const report = {
+        created: [],
+        altered: {},
+    };
+    await ensureTables(conn, tables, report);
+    return report;
+}
+/**
+ * Garante que as tabelas do authkit existem e têm todas as colunas que esta
+ * versão da lib espera. Aditivo e idempotente — seguro de rodar em todo boot
+ * e dentro de migrations.
+ *
+ * `db` é o manager (`Database`, no boot) ou o client da própria migration
+ * (`this.db`, um `QueryClient`/`TransactionClient`, usado como está).
+ */
+export async function ensureAuthkitSchema(db, options = {}) {
+    const conn = typeof db.connection !== 'function'
+        ? db
+        : options.connection
+            ? db.connection(options.connection)
+            : db.connection();
+    const report = {
+        created: [],
+        altered: {},
+        loginMethods: { table: options.accountTable ?? 'users', ensured: false },
+    };
+    await ensureTables(conn, [...TABLES, ...(options.tables ?? [])], report);
     // Coluna `login_methods` na tabela da CONTA — a tabela é HOST-owned (não está
     // em TABLES porque o nome/shape são decisão do app), mas a LIB consome a
     // coluna (LoginMethodsPreferenceCapability). Alguns deploys de host só migram

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

@@ -0,0 +1,39 @@
+import type { OidcAdapter } from '../adapters/adapter_contract.js';
+/**
+ * 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 declare const SERVICE_TENANT_KEY = "authkit_service_tenant";
+export declare const CLIENT_DISABLED_KEY = "authkit_disabled";
+/** The service-tenant part of a client. */
+export interface ServiceTenantInfo {
+    /** Partition (tenant) the client acts as. Emitted as the `partition` claim. */
+    partition: string;
+    /** Granted capabilities. Emitted as the `capabilities` claim when non-empty. */
+    capabilities: string[];
+}
+/** Letters, digits, `.`, `_`, `:` and `-`; starts with a letter or digit; up to 128 chars. */
+export declare const PARTITION_PATTERN: RegExp;
+/** Like {@link PARTITION_PATTERN}, plus `*` and `/`. */
+export declare const CAPABILITY_PATTERN: RegExp;
+export declare const MAX_CAPABILITIES = 64;
+/** Reads the service-tenant metadata from a raw client payload, or `null`. */
+export declare function serviceTenantOf(payload: Record<string, unknown> | undefined | null): ServiceTenantInfo | null;
+/** `true` when the raw client payload is disabled. */
+export declare function isClientDisabled(payload: Record<string, unknown> | undefined | null): boolean;
+/**
+ * Validates and normalizes service-tenant input. Returns an error message or the
+ * normalized value (trimmed, de-duplicated capabilities).
+ */
+export declare function normalizeServiceTenant(input: {
+    partition: string;
+    capabilities?: string[];
+}): ServiceTenantInfo | string;
+/**
+ * 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 declare function hideDisabledClients<T extends OidcAdapter>(adapter: T): T;

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>;