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

package/build/src/doctor/checks.js

@@ -238,7 +238,90 @@ export function checkSession(input) {
     }
     return findings;
 }
-/** Hint de exceções de CSRF do shield para o mountPath. */
+/**
+ * The server-to-server POST endpoints authkit mounts, which shield's CSRF check must not reject:
+ * the OIDC provider's token, introspection and revocation endpoints (under the `${mountPath}/*`
+ * wildcard route), PAT introspection, and — with `personalAgents` on — the agents' OAuth
+ * endpoints plus every extension's `csrfExemptPaths`.
+ */
+export function authkitCsrfExemptEndpoints(authkitConfig) {
+    const mount = String(authkitConfig?.mountPath ?? '/oidc').replace(/\/+$/, '') || '/oidc';
+    const endpoints = ['token', 'token/introspection', 'token/revocation'].map((rest) => ({ path: `${mount}/${rest}`, pattern: `${mount}/*` }));
+    endpoints.push({ path: '/authkit/pat/introspect', pattern: '/authkit/pat/introspect' });
+    const agents = authkitConfig?.personalAgents;
+    if (agents?.prefix) {
+        for (const rest of ['device_authorization', 'token']) {
+            const path = `${agents.prefix}/oauth/${rest}`;
+            endpoints.push({ path, pattern: path });
+        }
+        for (const extension of agents.extensions ?? []) {
+            for (const path of extension.csrfExemptPaths ?? [])
+                endpoints.push({ path, pattern: path });
+        }
+    }
+    return endpoints;
+}
+/** A minimal HttpContext for a token-less `POST path`, enough for an `exceptRoutes` function. */
+function csrfProbeContext(endpoint) {
+    const [pathname, query = ''] = endpoint.path.split('?');
+    const completeUrl = `http://localhost${endpoint.path}`;
+    const request = {
+        url: (includeQueryString) => includeQueryString && query ? `${pathname}?${query}` : pathname,
+        completeUrl: () => completeUrl,
+        method: () => 'POST',
+        intended: () => 'POST',
+        parsedUrl: { pathname, query, href: endpoint.path },
+        header: () => undefined,
+        headers: () => ({}),
+        hostname: () => 'localhost',
+        host: () => 'localhost',
+        protocol: () => 'http',
+        ip: () => '127.0.0.1',
+        input: () => undefined,
+        qs: () => ({}),
+        all: () => ({}),
+        matchesRoute: (identifier) => (Array.isArray(identifier) ? identifier : [identifier]).includes(endpoint.pattern),
+    };
+    return {
+        request,
+        route: { pattern: endpoint.pattern, methods: ['POST'] },
+        routeKey: `POST-${endpoint.pattern}`,
+    };
+}
+/**
+ * Whether shield's CSRF check (as configured in `config/shield.ts`) would reject a token-less POST
+ * to `endpoint`, mirroring `@adonisjs/shield`: CSRF off → no; a non-empty `methods` without POST →
+ * no (an empty or missing `methods` checks every method); `exceptRoutes` as a function → rejected
+ * unless it returns a truthy value for that request; as an array → rejected unless it holds the route
+ * pattern. `'unknown'` when the function throws on the probe context.
+ */
+export function csrfRejects(shieldConfig, endpoint) {
+    const csrf = shieldConfig?.csrf;
+    if (!csrf || csrf.enabled !== true)
+        return false;
+    const methods = Array.isArray(csrf.methods)
+        ? csrf.methods.map((m) => String(m).toLowerCase())
+        : [];
+    if (methods.length > 0 && !methods.includes('post'))
+        return false;
+    const except = csrf.exceptRoutes ?? [];
+    if (typeof except === 'function') {
+        try {
+            // Shield skips validation on any truthy return (`!this.#routesToIgnore(ctx)`).
+            return !except(csrfProbeContext(endpoint));
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    if (Array.isArray(except))
+        return !except.includes(endpoint.pattern);
+    return true;
+}
+/**
+ * `authkit.shield`: evaluates the app's real `config/shield.ts` against the server-to-server POST
+ * endpoints authkit mounts, and warns only about the ones shield would actually reject.
+ */
 export function checkShield(input) {
     if (!input.peers.shield) {
         return {
@@ -247,9 +330,41 @@ export function checkShield(input) {
         };
     }
     const mountPath = input.authkitConfig?.mountPath ?? '/oidc';
+    const helper = `authkitCsrfExceptions(ctx.request.url(), { mountPath: '${mountPath}' })`;
+    if (input.shieldConfig === undefined) {
+        return {
+            level: 'warn',
+            message: `config('shield') was not read, so the CSRF exemptions could not be checked. Make sure config/shield.ts's csrf.exceptRoutes exempts the IdP POST routes under "${mountPath}" (e.g. with ${helper}).`,
+        };
+    }
+    const endpoints = authkitCsrfExemptEndpoints(input.authkitConfig);
+    const rejected = [];
+    const unknown = [];
+    for (const endpoint of endpoints) {
+        const verdict = csrfRejects(input.shieldConfig, endpoint);
+        if (verdict === 'unknown')
+            unknown.push(endpoint.path);
+        else if (verdict)
+            rejected.push(endpoint.path);
+    }
+    if (rejected.length > 0) {
+        return {
+            level: 'warn',
+            message: `Shield's CSRF check rejects POST ${rejected.join(', ')} — server-to-server calls to these authkit endpoints fail. Exempt them in config/shield.ts's csrf.exceptRoutes, e.g. \`exceptRoutes: (ctx) => ${helper}\` (combine with your own exemptions using ||).`,
+        };
+    }
+    if (unknown.length > 0) {
+        return {
+            level: 'warn',
+            message: `csrf.exceptRoutes in config/shield.ts threw when probed with POST ${unknown.join(', ')}, so the doctor cannot tell whether they are exempt. Make sure it exempts them (e.g. with ${helper}).`,
+        };
+    }
+    const csrfOn = input.shieldConfig?.csrf?.enabled === true;
     return {
-        level: 'warn',
-        message: `Make sure the IdP POST routes under "${mountPath}" are in the shield CSRF exceptions (e.g. the /token endpoint), otherwise server-to-server calls fail. Use the exported authkitCsrfExceptions(url, { mountPath: '${mountPath}' }) helper in config/shield.ts's exceptRoutes instead of hand-writing the route-pattern check.`,
+        level: 'ok',
+        message: csrfOn
+            ? `shield's CSRF check exempts authkit's server-to-server POST endpoints (${endpoints.length} checked).`
+            : 'shield CSRF is off: authkit endpoints are not affected.',
     };
 }
 /** ally só é necessário quando social está configurado. */

package/build/src/doctor/db_schema_check.d.ts

@@ -0,0 +1,6 @@
+import type { AgoraDoctorResult } from './agora_doctor.js';
+/**
+ * `agora:doctor` check for `schema.name`: the schema exists, AuthKit's tables are in it, and the
+ * connection can write there. No result at all without `schema.name`.
+ */
+export declare function dbSchemaResults(config: Record<string, any> | null, makeDb: () => Promise<any>, docs: string): Promise<AgoraDoctorResult[]>;

package/build/src/doctor/db_schema_check.js

@@ -0,0 +1,87 @@
+/** Thrown inside the probe transaction so the probe row is never kept. */
+class ProbeRollback extends Error {
+}
+function rows(result) {
+    if (Array.isArray(result))
+        return Array.isArray(result[0]) ? result[0] : result;
+    return result?.rows ?? [];
+}
+/**
+ * `agora:doctor` check for `schema.name`: the schema exists, AuthKit's tables are in it, and the
+ * connection can write there. No result at all without `schema.name`.
+ */
+export async function dbSchemaResults(config, makeDb, docs) {
+    const schema = config?.schema?.name;
+    if (!schema)
+        return [];
+    const [{ AUTHKIT_TABLE_NAMES }, { authkitTable, authkitTablesClient, dialectOf }] = await Promise.all([import('../schema/ensure.js'), import('../schema/tables_location.js')]);
+    const client = authkitTablesClient(await makeDb(), { connection: config?.schema?.connection });
+    const dialect = dialectOf(client);
+    if (dialect !== 'postgres' && dialect !== 'mysql') {
+        return [
+            {
+                status: 'error',
+                message: `schema.name "${schema}" is set, but the connection uses ${dialect ?? 'an unknown dialect'}, which has no schemas`,
+                fix: 'Remove schema.name from config/authkit.ts, or use Postgres or MySQL',
+                docs,
+            },
+        ];
+    }
+    const exists = rows(await client.rawQuery('select 1 as ok from information_schema.schemata where schema_name = ?', [
+        schema,
+    ]));
+    if (exists.length === 0) {
+        return [
+            {
+                status: 'error',
+                message: `database schema "${schema}" does not exist on this connection`,
+                fix: dialect === 'mysql'
+                    ? `Boot the app once with schema.autoManage on, or run CREATE DATABASE \`${schema}\``
+                    : `Boot the app once with schema.autoManage on, or run CREATE SCHEMA "${schema}"`,
+                docs,
+            },
+        ];
+    }
+    const found = new Set(rows(await client.rawQuery('select table_name as name from information_schema.tables where table_schema = ?', [schema])).map((r) => String(r.name ?? r.NAME ?? r.TABLE_NAME)));
+    const missing = AUTHKIT_TABLE_NAMES.filter((name) => !found.has(name));
+    if (missing.length > 0) {
+        return [
+            {
+                status: 'error',
+                message: `AuthKit tables missing from schema "${schema}": ${missing.join(', ')}`,
+                fix: 'Boot the app once with schema.autoManage on, or run ensureAuthkitSchema(db, { schema }) in a migration',
+                docs,
+            },
+        ];
+    }
+    try {
+        await client.transaction(async (trx) => {
+            await trx.table(authkitTable({ schema }, 'auth_settings')).insert({
+                key: '__authkit_doctor_probe',
+                organization_id: null,
+                value: 'null',
+            });
+            throw new ProbeRollback();
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ProbeRollback)) {
+            return [
+                {
+                    status: 'error',
+                    message: `the connection cannot write to schema "${schema}": ${error?.message ?? error}`,
+                    fix: dialect === 'mysql'
+                        ? `GRANT INSERT, UPDATE, DELETE ON \`${schema}\`.* TO the app user`
+                        : `GRANT USAGE ON SCHEMA "${schema}" and INSERT, UPDATE, DELETE on its tables to the app role`,
+                    docs,
+                },
+            ];
+        }
+    }
+    return [
+        {
+            status: 'ok',
+            message: `AuthKit tables are in schema "${schema}" and the connection can write there`,
+        },
+    ];
+}

package/build/src/doctor/doctor_input.js

@@ -47,9 +47,11 @@ export async function buildDoctorInput(app, logger) {
     // senão todo campo aparece como "ausente" (provider cru não tem issuer etc.).
     const authkitConfig = await resolveAuthkitConfig(app, config.get('authkit', null));
     const sessionConfig = config.get('session', null) ?? null;
+    const shieldConfig = config.get('shield', null) ?? null;
     return {
         authkitConfig,
         sessionConfig,
+        shieldConfig,
         peers: {
             session: await canImport('@adonisjs/session', logger),
             shield: await canImport('@adonisjs/shield', logger),

package/build/src/host/admin_sessions_service.js

@@ -1,6 +1,7 @@
 import { getBootedApp } from '../../services/booted_app.js';
 import { pickModelAdapterClass } from '../adapters/factory.js';
 import { buildPersonalAgentsRuntime } from '../agents/runtime.js';
+import { authkitTable } from '../schema/tables_location.js';
 import { normalizeActiveOrg } from './active_org_cookie.js';
 /**
  * Serviço de inspeção/revogação das SESSÕES e GRANTS ativos de uma conta.
@@ -22,8 +23,10 @@ export class AdminSessionsService {
     #AdapterClass;
     #SessionAdapterClass;
     #accountStore;
-    /** Conexão Lucid das tabelas authkit (schema `auth`) — onde vive auth_session_revocations. */
+    /** Conexão Lucid das tabelas authkit (`schema.connection`) — onde vive auth_session_revocations. */
     #schemaConnection;
+    /** `auth_session_revocations`, qualificada com `schema.name` quando há um. */
+    #revocationsTable;
     #oidc;
     constructor(oidc) {
         this.#oidc = oidc;
@@ -34,6 +37,7 @@ export class AdminSessionsService {
         this.#SessionAdapterClass = oidc.config.SessionAdapterClass ?? oidc.config.AdapterClass;
         this.#accountStore = oidc.config.accountStore;
         this.#schemaConnection = oidc.config.schema?.connection;
+        this.#revocationsTable = authkitTable({ schema: oidc.config.schema?.name }, 'auth_session_revocations');
     }
     #adapter(model) {
         return new (pickModelAdapterClass(model, this.#AdapterClass, this.#SessionAdapterClass))(model);
@@ -70,7 +74,7 @@ export class AdminSessionsService {
             const conn = this.#schemaConnection
                 ? db.connection(this.#schemaConnection)
                 : db.connection();
-            await conn.insertQuery().table('auth_session_revocations').insert({
+            await conn.insertQuery().table(this.#revocationsTable).insert({
                 sid: null,
                 sub: accountId,
                 revoked_at: revokedAt,

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

@@ -20,5 +20,8 @@ export interface AuthkitCsrfOptions {
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
  * rota de back-channel logout do client e os endpoints OAuth de personal agents.
+ *
+ * O match é ANCORADO no pathname: `/oidc` e `/oidc/...` casam, mas `/foo/oidc/x`,
+ * `/oidc-admin` ou `/x?next=/oidc` não. A query string é ignorada.
  */
 export declare function authkitCsrfExceptions(url: string, options?: AuthkitCsrfOptions): boolean;

package/build/src/host/csrf.js

@@ -11,19 +11,39 @@
  * csrf: {
  *   enabled: true,
  *   exceptRoutes: (ctx) => authkitCsrfExceptions(ctx.request.url(), { mountPath: '/oidc' })
- *     || ctx.request.url().includes('/api'),
+ *     || ctx.request.url().startsWith('/api/'),
  * }
  * ```
  */
 import { normalizePersonalAgentsPrefix } from '../agents/config.js';
 import { getAuthHostConfig } from './auth_host_config.js';
+/** `path` é `prefix` ou fica debaixo dele (`prefix/...`) — nunca um substring solto. */
+function underPrefix(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/** O pathname de `url`: sem query/hash, aceitando também uma URL absoluta. */
+function pathnameOf(url) {
+    let path = url;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) {
+        try {
+            path = new URL(path).pathname;
+        }
+        catch {
+            // Segue com a string crua: o match ancorado abaixo simplesmente não casa.
+        }
+    }
+    return path.split(/[?#]/, 1)[0] ?? '';
+}
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
  * rota de back-channel logout do client e os endpoints OAuth de personal agents.
+ *
+ * O match é ANCORADO no pathname: `/oidc` e `/oidc/...` casam, mas `/foo/oidc/x`,
+ * `/oidc-admin` ou `/x?next=/oidc` não. A query string é ignorada.
  */
 export function authkitCsrfExceptions(url, options = {}) {
-    const mountPath = options.mountPath ?? '/oidc';
+    const mountPath = (options.mountPath ?? '/oidc').replace(/\/+$/, '');
     const backchannel = options.backchannelLogoutPath === false
         ? null
         : (options.backchannelLogoutPath ?? '/auth/backchannel-logout');
@@ -33,12 +53,12 @@ export function authkitCsrfExceptions(url, options = {}) {
             ? normalizePersonalAgentsPrefix(options.personalAgentsPrefix)
             : getAuthHostConfig()?.personalAgents?.prefix;
     const agentsOAuth = agentsPrefix ? `${agentsPrefix}/oauth/` : null;
-    const path = url.split('?')[0];
+    const path = pathnameOf(url);
     const extensionExempt = options.personalAgentExtensions !== false &&
         (getAuthHostConfig()?.personalAgents?.extensions ?? []).some((e) => e.csrfExemptPaths?.includes(path));
-    return (url.includes(mountPath) ||
-        url.includes('/authkit/pat') ||
-        (backchannel !== null && url === backchannel) ||
-        (agentsOAuth !== null && url.startsWith(agentsOAuth)) ||
+    return ((mountPath !== '' && underPrefix(path, mountPath)) ||
+        underPrefix(path, '/authkit/pat') ||
+        (backchannel !== null && path === backchannel) ||
+        (agentsOAuth !== null && path.startsWith(agentsOAuth)) ||
         extensionExempt);
 }

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

@@ -98,7 +98,20 @@ export interface RuntimeSettingsOptions {
      * Ausente (ou undefined) → conexão default.
      */
     connection?: string;
+    /**
+     * Schema do banco de `auth_settings` (MySQL: o database) — o `schema.name` do
+     * `defineConfig`. Escrito em cada statement (`"auth"."auth_settings"`).
+     */
+    schema?: string;
 }
+/**
+ * `{ connection, schema }` das tabelas do authkit a partir do config resolvido
+ * (`schema.connection`/`schema.name`), no formato de {@link RuntimeSettingsOptions}.
+ */
+export declare function settingsLocation(config: any): {
+    connection?: string;
+    schema?: string;
+};
 /**
  * Implementação default do SettingsCapability sobre um `Database` Lucid.
  *
@@ -108,6 +121,8 @@ export declare class RuntimeSettings implements SettingsCapability {
     private readonly db;
     private readonly ttlMs;
     private readonly connectionName;
+    /** `auth_settings`, qualificada com o schema quando há um. */
+    private readonly table;
     private readonly shared;
     constructor(db: any, opts?: RuntimeSettingsOptions);
     private get cache();

package/build/src/host/runtime_settings.js

@@ -50,6 +50,7 @@
  * );
  * ```
  */
+import { authkitTable } from '../schema/tables_location.js';
 import { isSettingLocked, SettingLockedError } from './config_locks.js';
 /**
  * Type guard: o objeto (store ou serviço) expõe SettingsCapability?
@@ -58,7 +59,7 @@ export function supportsSettings(obj) {
     return !!obj && typeof obj.getSetting === 'function';
 }
 const sharedStates = new WeakMap();
-function sharedStateFor(db, connection) {
+function sharedStateFor(db, connection, table) {
     const fresh = () => ({ cache: new Map(), tablePresent: null, tableAbsentUntil: 0 });
     if (!db || (typeof db !== 'object' && typeof db !== 'function'))
         return fresh();
@@ -67,7 +68,7 @@ function sharedStateFor(db, connection) {
         byConnection = new Map();
         sharedStates.set(db, byConnection);
     }
-    const name = connection ?? '';
+    const name = `${connection ?? ''}\x00${table}`;
     let state = byConnection.get(name);
     if (!state) {
         state = fresh();
@@ -75,6 +76,18 @@ function sharedStateFor(db, connection) {
     }
     return state;
 }
+/**
+ * `{ connection, schema }` das tabelas do authkit a partir do config resolvido
+ * (`schema.connection`/`schema.name`), no formato de {@link RuntimeSettingsOptions}.
+ */
+export function settingsLocation(config) {
+    const out = {};
+    if (config?.schema?.connection)
+        out.connection = config.schema.connection;
+    if (config?.schema?.name)
+        out.schema = config.schema.name;
+    return out;
+}
 /** Chave de cache: combina key + escopo de org (null = global). */
 function cacheKey(key, orgId) {
     return orgId ? `${key}\x00${orgId}` : key;
@@ -88,12 +101,15 @@ export class RuntimeSettings {
     db;
     ttlMs;
     connectionName;
+    /** `auth_settings`, qualificada com o schema quando há um. */
+    table;
     shared;
     constructor(db, opts = {}) {
         this.db = db;
         this.ttlMs = opts.ttlMs ?? 15_000;
         this.connectionName = opts.connection;
-        this.shared = sharedStateFor(db, opts.connection);
+        this.table = authkitTable({ schema: opts.schema }, 'auth_settings');
+        this.shared = sharedStateFor(db, opts.connection, this.table);
     }
     get cache() {
         return this.shared.cache;
@@ -127,7 +143,7 @@ export class RuntimeSettings {
         if (shared.tablePresent === false && shared.tableAbsentUntil > Date.now())
             return false;
         try {
-            await this.conn().from('auth_settings').select('key').limit(1);
+            await this.conn().from(this.table).select('key').limit(1);
             shared.tablePresent = true;
             return true;
         }
@@ -152,7 +168,7 @@ export class RuntimeSettings {
             return null;
         }
         try {
-            let q = this.conn().from('auth_settings').where('key', key);
+            let q = this.conn().from(this.table).where('key', key);
             if (orgId) {
                 q = q.where('organization_id', orgId);
             }
@@ -192,7 +208,7 @@ export class RuntimeSettings {
         const resolvedOrgId = orgId ?? null;
         try {
             // Delete first then insert = upsert (compatível com sqlite + pg sem UPSERT syntax).
-            let q = this.conn().from('auth_settings').where('key', key);
+            let q = this.conn().from(this.table).where('key', key);
             if (resolvedOrgId) {
                 q = q.where('organization_id', resolvedOrgId);
             }
@@ -200,7 +216,7 @@ export class RuntimeSettings {
                 q = q.whereNull('organization_id');
             }
             await q.delete();
-            await this.conn().table('auth_settings').insert({
+            await this.conn().table(this.table).insert({
                 key,
                 organization_id: resolvedOrgId,
                 value: json,
@@ -220,7 +236,7 @@ export class RuntimeSettings {
             return;
         const resolvedOrgId = orgId ?? null;
         try {
-            let q = this.conn().from('auth_settings').where('key', key);
+            let q = this.conn().from(this.table).where('key', key);
             if (resolvedOrgId) {
                 q = q.where('organization_id', resolvedOrgId);
             }
@@ -238,7 +254,7 @@ export class RuntimeSettings {
         if (!(await this.hasTable()))
             return [];
         try {
-            let q = this.conn().from('auth_settings').select('*');
+            let q = this.conn().from(this.table).select('*');
             if (orgId !== undefined) {
                 // orgId fornecido: filtra pelo escopo
                 if (orgId) {
@@ -325,9 +341,8 @@ export async function resolveRuntimeSettings(ctx) {
     try {
         const db = await ctx.containerResolver.make('lucid.db');
         const service = await ctx.containerResolver.make('authkit.server').catch(() => null);
-        // `auth_settings` vive na conexão das tabelas do authkit, não na do model da conta.
-        const connection = service?.config?.schema?.connection;
-        return new RuntimeSettings(db, connection ? { connection } : {});
+        // `auth_settings` vive onde estão as tabelas do authkit, não na conexão do model da conta.
+        return new RuntimeSettings(db, settingsLocation(service?.config));
     }
     catch {
         return null;

package/build/src/keys/keystore_manager.js

@@ -1,3 +1,4 @@
+import { validateSchemaName } from '../schema/tables_location.js';
 import { generateSigningJwk, planRotation, } from './keystore.js';
 import { DriveKeystoreVault, FileKeystoreVault, HashicorpVaultKeystoreVault, LazyExternalVault, LucidKeystoreVault, RedisKeystoreVault, } from './keystore_vault.js';
 /**
@@ -80,7 +81,7 @@ export function resolveKeystoreVault(store, ctx) {
             return new LucidKeystoreVault(async () => {
                 const db = await ctx.container.make('lucid.db');
                 return cfg.connection ? db.connection(cfg.connection) : db.connection();
-            }, cfg.table, cfg.key);
+            }, cfg.table, cfg.key, validateSchemaName(cfg.schema, 'jwks.store.schema'));
         case 'redis':
             return new RedisKeystoreVault(async () => {
                 const rm = await ctx.container.make('redis');

package/build/src/keys/keystore_vault.d.ts

@@ -30,7 +30,15 @@ export declare class LucidKeystoreVault implements KeystoreVault {
     private getConn;
     private table;
     private key;
-    constructor(getConn: () => Promise<any>, table?: string, key?: string);
+    /** Schema do banco da tabela (MySQL: o database). Escrito em cada statement. */
+    private schema?;
+    constructor(getConn: () => Promise<any>, table?: string, key?: string, 
+    /** Schema do banco da tabela (MySQL: o database). Escrito em cada statement. */
+    schema?: string | undefined);
+    /** Schema builder no schema da tabela (`withSchema`), ou o da conexão. */
+    private ddl;
+    /** `schema.tabela` (o knex cita cada parte) ou só `tabela`. */
+    private get qualified();
     private ensureTable;
     read(): Promise<string | null>;
     write(blob: string): Promise<void>;

package/build/src/keys/keystore_vault.js

@@ -8,6 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { assertSchemaSupported, createDbSchema } from '../schema/tables_location.js';
 /** Cofre em arquivo local (default; mode 0600). */
 export class FileKeystoreVault {
     path;
@@ -49,16 +50,30 @@ export class LucidKeystoreVault {
     getConn;
     table;
     key;
-    constructor(getConn, table = 'authkit_keystore', key = 'jwks') {
+    schema;
+    constructor(getConn, table = 'authkit_keystore', key = 'jwks', 
+    /** Schema do banco da tabela (MySQL: o database). Escrito em cada statement. */
+    schema) {
         this.getConn = getConn;
         this.table = table;
         this.key = key;
+        this.schema = schema;
+    }
+    /** Schema builder no schema da tabela (`withSchema`), ou o da conexão. */
+    ddl(conn) {
+        return this.schema ? conn.schema.withSchema(this.schema) : conn.schema;
+    }
+    /** `schema.tabela` (o knex cita cada parte) ou só `tabela`. */
+    get qualified() {
+        return this.schema ? `${this.schema}.${this.table}` : this.table;
     }
     async ensureTable(conn) {
-        if (await conn.schema.hasTable(this.table))
+        if (await this.ddl(conn).hasTable(this.table))
             return;
+        if (this.schema)
+            await createDbSchema(conn, this.schema);
         try {
-            await conn.schema.createTable(this.table, (t) => {
+            await this.ddl(conn).createTable(this.table, (t) => {
                 t.string('key').notNullable().primary();
                 t.text('blob').notNullable();
                 t.bigInteger('updated_at').notNullable();
@@ -67,31 +82,34 @@ export class LucidKeystoreVault {
         catch (err) {
             // Outra instância criou a tabela entre o hasTable e o createTable (race no boot
             // multi-instância). Se já existe agora, OK; senão propaga.
-            if (!(await conn.schema.hasTable(this.table)))
+            if (!(await this.ddl(conn).hasTable(this.table)))
                 throw err;
         }
     }
     async read() {
         const conn = await this.getConn();
-        if (!(await conn.schema.hasTable(this.table)))
+        assertSchemaSupported(conn, this.schema);
+        if (!(await this.ddl(conn).hasTable(this.table)))
             return null;
-        const row = await conn.from(this.table).where('key', this.key).first();
+        const row = await conn.from(this.qualified).where('key', this.key).first();
         return row ? row.blob : null;
     }
     async write(blob) {
         const conn = await this.getConn();
+        assertSchemaSupported(conn, this.schema);
         await this.ensureTable(conn);
         await conn
-            .table(this.table)
+            .table(this.qualified)
             .insert({ key: this.key, blob, updated_at: Date.now() })
             .onConflict('key')
             .merge();
     }
     async head() {
         const conn = await this.getConn();
-        if (!(await conn.schema.hasTable(this.table)))
+        assertSchemaSupported(conn, this.schema);
+        if (!(await this.ddl(conn).hasTable(this.table)))
             return null;
-        const row = await conn.from(this.table).where('key', this.key).first();
+        const row = await conn.from(this.qualified).where('key', this.key).first();
         return row ? String(row.updated_at) : null;
     }
 }

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

@@ -24,6 +24,8 @@
  * ```
  */
 import type { AuthkitTable } from '../agents/extension.js';
+/** Os nomes (sem schema) das tabelas que {@link ensureAuthkitSchema} garante. */
+export declare const AUTHKIT_TABLE_NAMES: readonly string[];
 export interface EnsureSchemaOptions {
     /**
      * Conexão Lucid das tabelas do authkit (`schema.connection`). Default: conexão
@@ -36,6 +38,12 @@ export interface EnsureSchemaOptions {
      * O provider passa a do `accountStore` no boot. Ignorada quando `db` já é um client.
      */
     accountConnection?: string;
+    /**
+     * Database schema of the tables (MySQL: the database) — `schema.name`. Every statement
+     * names it (`"auth"."auth_settings"`), and it is created when missing. Never a
+     * `searchPath`. Ignored for the account table, which stays where the app put it.
+     */
+    schema?: string;
     /**
      * Tabelas de `personalAgents.extensions` (`tables` de cada uma), garantidas junto. O provider
      * passa as do config no boot.
@@ -73,6 +81,7 @@ export interface EnsureSchemaReport {
  */
 export declare function ensureAuthkitTables(db: any, tables: readonly AuthkitTable[], options?: {
     connection?: string;
+    schema?: string;
 }): Promise<Pick<EnsureSchemaReport, 'created' | 'altered' | 'indexed'>>;
 /**
  * Garante que as tabelas do authkit existem e têm todas as colunas que esta