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

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

package/build/src/schema/ensure.js

@@ -23,7 +23,7 @@
  * }
  * ```
  */
-import { authkitTablesClient } from './tables_location.js';
+import { assertSchemaSupported, authkitTable, authkitTablesClient, createDbSchema, validateSchemaName, } from './tables_location.js';
 /** Busca por conta (`account_id`) e limpeza dos expirados (`expires_at`). */
 const OIDC_PAYLOAD_INDEXES = [
     { name: 'authkit_oidc_payloads_account_idx', columns: ['model_name', 'account_id'] },
@@ -139,12 +139,12 @@ const TABLES = [
     },
     {
         name: 'auth_organization_members',
-        create: (t) => {
+        create: (t, ctx) => {
             t.string('id').primary();
             t.string('organization_id')
                 .notNullable()
                 .references('id')
-                .inTable('auth_organizations')
+                .inTable(ctx.table('auth_organizations'))
                 .onDelete('CASCADE');
             t.string('account_id').notNullable();
             t.string('role').notNullable().defaultTo('member');
@@ -186,12 +186,12 @@ const TABLES = [
     },
     {
         name: 'auth_organization_invitations',
-        create: (t) => {
+        create: (t, ctx) => {
             t.string('id').primary();
             t.string('organization_id')
                 .notNullable()
                 .references('id')
-                .inTable('auth_organizations')
+                .inTable(ctx.table('auth_organizations'))
                 .onDelete('CASCADE');
             t.string('email').notNullable();
             t.string('role').notNullable().defaultTo('member');
@@ -335,6 +335,8 @@ const TABLES = [
         },
     },
 ];
+/** Os nomes (sem schema) das tabelas que {@link ensureAuthkitSchema} garante. */
+export const AUTHKIT_TABLE_NAMES = TABLES.map((t) => t.name);
 /** Linhas de um `rawQuery`, no formato de cada driver (pg, mysql2, sqlite). */
 function catalogRows(result) {
     if (Array.isArray(result))
@@ -420,7 +422,10 @@ async function columnExists(conn, table, column) {
 async function indexExists(conn, table, name) {
     const dialect = conn.dialect?.name;
     if (dialect === 'postgres' || dialect === 'redshift') {
-        const found = catalogRows(await conn.rawQuery('select to_regclass(?) as oid', [name]));
+        // Índice mora no schema da tabela: com schema explícito, o nome vai qualificado.
+        const [schema] = mysqlRelation(table);
+        const relation = pgRelation(schema ? `${schema}.${name}` : name);
+        const found = catalogRows(await conn.rawQuery('select to_regclass(?) as oid', [relation]));
         return found[0]?.oid != null;
     }
     if (dialect === 'mysql') {
@@ -441,11 +446,12 @@ async function indexExists(conn, table, name) {
  * Cria o índice quando falta. Idempotente: um índice já existente (inclusive
  * criado por outra instância no mesmo boot) não é erro.
  */
-async function ensureIndex(conn, table, index) {
+async function ensureIndex(conn, loc, name, index) {
+    const table = authkitTable(loc, name);
     if ((await indexExists(conn, table, index.name)) === true)
         return false;
     try {
-        await conn.schema.alterTable(table, (t) => t.index(index.columns, index.name));
+        await ddl(conn, loc).alterTable(name, (t) => t.index(index.columns, index.name));
         return true;
     }
     catch (error) {
@@ -458,12 +464,23 @@ async function ensureIndex(conn, table, index) {
         throw error;
     }
 }
+/**
+ * O schema builder das tabelas do authkit: com `schema`, `withSchema` — o knex escreve
+ * `"schema"."tabela"` em todo DDL e mantém os nomes de índice derivados da tabela pura.
+ */
+function ddl(conn, loc) {
+    return loc.schema ? conn.schema.withSchema(loc.schema) : conn.schema;
+}
 /** Cria/completa as tabelas (o miolo de {@link ensureAuthkitSchema}). */
-async function ensureTables(conn, tables, report) {
+async function ensureTables(conn, loc, tables, report) {
+    const context = { table: (name) => authkitTable(loc, name) };
+    if (loc.schema)
+        await createDbSchema(conn, loc.schema);
     for (const def of tables) {
-        if (!(await tableExists(conn, def.name))) {
+        const table = authkitTable(loc, def.name);
+        if (!(await tableExists(conn, table))) {
             try {
-                await conn.schema.createTable(def.name, def.create);
+                await ddl(conn, loc).createTable(def.name, (t) => def.create(t, context));
                 report.created.push(def.name);
                 continue;
             }
@@ -472,20 +489,20 @@ async function ensureTables(conn, tables, report) {
                  * Corrida entre instâncias subindo juntas: se outra instância criou
                  * a tabela entre o probe e o CREATE, segue o jogo; senão, propaga.
                  */
-                if (!(await tableExists(conn, def.name)))
+                if (!(await tableExists(conn, table)))
                     throw error;
             }
         }
         for (const [column, add] of Object.entries(def.columns)) {
-            if (await columnExists(conn, def.name, column))
+            if (await columnExists(conn, table, column))
                 continue;
-            await conn.schema.alterTable(def.name, (t) => add(t));
+            await ddl(conn, loc).alterTable(def.name, (t) => add(t));
             if (!report.altered[def.name])
                 report.altered[def.name] = [];
             report.altered[def.name].push(column);
         }
         for (const index of def.indexes ?? []) {
-            if (!(await ensureIndex(conn, def.name, index)))
+            if (!(await ensureIndex(conn, loc, def.name, index)))
                 continue;
             if (!report.indexed)
                 report.indexed = {};
@@ -495,18 +512,26 @@ async function ensureTables(conn, tables, report) {
         }
     }
 }
+function resolveLocation(options) {
+    return {
+        connection: options.connection,
+        schema: validateSchemaName(options.schema, 'schema'),
+    };
+}
 /**
  * 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 = authkitTablesClient(db, { connection: options.connection });
+    const loc = resolveLocation(options);
+    const conn = authkitTablesClient(db, loc);
+    assertSchemaSupported(conn, loc.schema);
     const report = {
         created: [],
         altered: {},
     };
-    await ensureTables(conn, tables, report);
+    await ensureTables(conn, loc, tables, report);
     return report;
 }
 /**
@@ -518,13 +543,15 @@ export async function ensureAuthkitTables(db, tables, options = {}) {
  * (`this.db`, um `QueryClient`/`TransactionClient`, usado como está).
  */
 export async function ensureAuthkitSchema(db, options = {}) {
-    const conn = authkitTablesClient(db, { connection: options.connection });
+    const loc = resolveLocation(options);
+    const conn = authkitTablesClient(db, loc);
+    assertSchemaSupported(conn, loc.schema);
     const report = {
         created: [],
         altered: {},
         loginMethods: { table: options.accountTable ?? 'users', ensured: false },
     };
-    await ensureTables(conn, [...TABLES, ...(options.tables ?? [])], report);
+    await ensureTables(conn, loc, [...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/schema/tables_location.d.ts

@@ -4,19 +4,48 @@
  * `authkit_keystore` of the Lucid keystore, and the tables of agent extensions).
  *
  * The rule: every lib-owned table goes through `schema.connection` of `defineConfig`
- * (default: the primary Lucid connection). The app's account table is not lib-owned: it
- * stays on the account model's connection (`static connection` of the model).
+ * (default: the primary Lucid connection) and, with `schema.name`, lives in that database
+ * schema (MySQL: that database). The app's account table is not lib-owned: it stays on the
+ * account model's connection and table (`static connection`/`static table` of the model).
+ *
+ * The schema is written INTO every statement (`"auth"."auth_settings"`). Never put
+ * AuthKit's tables in another schema with a connection `searchPath`: knex sends
+ * `SET search_path` on the session, and behind PgBouncer in transaction mode that leaks to
+ * other clients' connections.
  */
 export interface AuthkitTablesLocation {
     /** Lucid connection name. `undefined` = the primary connection. */
     connection?: string;
+    /** Database schema of the tables (MySQL: the database). `undefined` = the connection's default. */
+    schema?: string;
+}
+/** Raised for a `schema.name` the database cannot use. The provider fails the boot with it. */
+export declare class AuthkitSchemaError extends Error {
+    constructor(message: string);
 }
+/** Throws {@link AuthkitSchemaError} unless `name` is a plain identifier of at most 63 chars. */
+export declare function validateSchemaName(name: unknown, option?: string): string | undefined;
+/** `schema.table` when a schema is set (knex quotes each part: `"schema"."table"`), else `table`. */
+export declare function authkitTable(location: AuthkitTablesLocation | undefined, table: string): string;
 /**
  * The query client for AuthKit's tables. `db` is the Lucid manager (`Database`) or a
  * client the caller already holds (a migration's `this.db`, a transaction), which is
  * used as is.
  */
 export declare function authkitTablesClient(db: any, location?: AuthkitTablesLocation): any;
+/** The Lucid dialect name of a client or manager (`postgres`, `mysql`, `better-sqlite3`…). */
+export declare function dialectOf(client: any): string | undefined;
+/**
+ * Throws {@link AuthkitSchemaError} when `schema` is set on a dialect AuthKit cannot use it on:
+ * SQLite (no schemas) and any dialect other than Postgres and MySQL. AuthKit never ignores the
+ * option nor falls back to unqualified tables.
+ */
+export declare function assertSchemaSupported(client: any, schema: string | undefined): void;
+/**
+ * `CREATE SCHEMA IF NOT EXISTS` (Postgres) / `CREATE DATABASE IF NOT EXISTS` (MySQL). A role
+ * that cannot create it gets an {@link AuthkitSchemaError} naming the schema and the grant.
+ */
+export declare function createDbSchema(client: any, schema: string): Promise<void>;
 /**
  * Hidden hook a store built by `lucidAccountStore` exposes so `defineConfig` can tell it
  * where AuthKit's tables live (the store is built before `defineConfig` sees the `schema`

package/build/src/schema/tables_location.js

@@ -1,3 +1,24 @@
+/** Raised for a `schema.name` the database cannot use. The provider fails the boot with it. */
+export class AuthkitSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthkitSchemaError';
+    }
+}
+const SCHEMA_NAME = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/** Throws {@link AuthkitSchemaError} unless `name` is a plain identifier of at most 63 chars. */
+export function validateSchemaName(name, option = 'schema.name') {
+    if (name === undefined)
+        return undefined;
+    if (typeof name !== 'string' || name.length > 63 || !SCHEMA_NAME.test(name)) {
+        throw new AuthkitSchemaError(`authkit: ${option} must match /^[A-Za-z_][A-Za-z0-9_$]*$/ and have at most 63 characters (got ${JSON.stringify(name)})`);
+    }
+    return name;
+}
+/** `schema.table` when a schema is set (knex quotes each part: `"schema"."table"`), else `table`. */
+export function authkitTable(location, table) {
+    return location?.schema ? `${location.schema}.${table}` : table;
+}
 /**
  * The query client for AuthKit's tables. `db` is the Lucid manager (`Database`) or a
  * client the caller already holds (a migration's `this.db`, a transaction), which is
@@ -8,6 +29,49 @@ export function authkitTablesClient(db, location = {}) {
         return db;
     return location.connection ? db.connection(location.connection) : db.connection();
 }
+const SQLITE_DIALECTS = new Set(['sqlite3', 'better-sqlite3', 'libsql']);
+/** Dialects AuthKit writes and creates schemas on. */
+const SCHEMA_DIALECTS = new Set(['postgres', 'redshift', 'mysql']);
+/** The Lucid dialect name of a client or manager (`postgres`, `mysql`, `better-sqlite3`…). */
+export function dialectOf(client) {
+    return client?.dialect?.name;
+}
+/**
+ * Throws {@link AuthkitSchemaError} when `schema` is set on a dialect AuthKit cannot use it on:
+ * SQLite (no schemas) and any dialect other than Postgres and MySQL. AuthKit never ignores the
+ * option nor falls back to unqualified tables.
+ */
+export function assertSchemaSupported(client, schema) {
+    if (!schema)
+        return;
+    const dialect = dialectOf(client);
+    if (dialect && SCHEMA_DIALECTS.has(dialect))
+        return;
+    throw new AuthkitSchemaError(dialect && SQLITE_DIALECTS.has(dialect)
+        ? `authkit: schema.name "${schema}" is set, but the connection uses ${dialect}, which has no schemas. Remove schema.name or use Postgres or MySQL.`
+        : `authkit: schema.name "${schema}" is set, but the connection uses ${dialect ?? 'an unknown dialect'}; schema.name supports Postgres and MySQL. Remove schema.name or use one of them.`);
+}
+/**
+ * `CREATE SCHEMA IF NOT EXISTS` (Postgres) / `CREATE DATABASE IF NOT EXISTS` (MySQL). A role
+ * that cannot create it gets an {@link AuthkitSchemaError} naming the schema and the grant.
+ */
+export async function createDbSchema(client, schema) {
+    assertSchemaSupported(client, schema);
+    const dialect = dialectOf(client);
+    const mysql = dialect === 'mysql';
+    const sql = mysql
+        ? `create database if not exists \`${schema}\``
+        : `create schema if not exists "${schema}"`;
+    try {
+        await client.rawQuery(sql);
+    }
+    catch (error) {
+        const grant = mysql
+            ? `GRANT CREATE ON *.* (or create it: CREATE DATABASE \`${schema}\`)`
+            : `GRANT CREATE ON DATABASE <db> TO <role> (or create it: CREATE SCHEMA "${schema}")`;
+        throw new AuthkitSchemaError(`authkit: could not create schema "${schema}" (${error?.message ?? error}). The database role needs ${grant}.`);
+    }
+}
 /**
  * Hidden hook a store built by `lucidAccountStore` exposes so `defineConfig` can tell it
  * where AuthKit's tables live (the store is built before `defineConfig` sees the `schema`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.12",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -108,7 +108,7 @@
     }
   },
   "dependencies": {
-    "@adonis-agora/authkit-core": "1.0.0-rc.1",
+    "@adonis-agora/authkit-core": "1.0.0-rc.2",
     "@simplewebauthn/browser": "14.0.0",
     "@simplewebauthn/server": "14.1.0",
     "jose": "6.2.16",
@@ -119,7 +119,7 @@
     "qrcode": "1.5.4"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-react": "1.0.0-rc.4",
+    "@adonis-agora/authkit-react": "1.0.0-rc.5",
     "@adonis-agora/durable": "0.60.0",
     "@adonis-agora/telescope": "0.27.1",
     "@adonisjs/ally": "6.3.2",

package/skills/authkit-idp-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up the @adonis-agora/authkit-server OIDC/OAuth2 Authorization Server (Identity
   Provider) in an AdonisJS app. Covers `node ace add @adonis-agora/authkit-server`,
   defineConfig({ issuer, adapter, jwks, ttl, globalRolesClaim, accountStore }) with
-  adapters.redis({ connection }) vs adapters.database({ connection? }),
+  adapters.redis({ connection }) vs adapters.database({ connection?, schema? }),
   lucidAccountStore(AuthUser), JWKS management ({ source: 'managed' | 'jwks' } or
   'auto', keystore store file/drive/lucid/redis/hashicorp vaults plus
   @adonis-agora/authkit-vault-aws/azure/gcp createKeystoreVault add-ons),
@@ -83,12 +83,18 @@ export default authServerConfig
 
 `adapter` is where oidc-provider persists grants/tokens/codes: `adapters.redis({
 connection })` requires `@adonisjs/redis` configured; `adapters.database({
-connection? })` uses Lucid and stores artifacts in `authkit_oidc_payloads`, which
-`ensureAuthkitSchema` creates on boot (with `schema: { autoManage: false }`, call it
-from a migration). The table carries an indexed `account_id` column so per-account
+connection?, schema? })` uses Lucid and stores artifacts in `authkit_oidc_payloads`, which
+`ensureAuthkitSchema` creates on boot (with `schema: { autoManage: false }`, call
+`ensureAuthkitSchema(db)` — or `ensureAuthkitSchema(db, { schema })` when `schema.name`
+is set — from a migration). The `schema` defaults to `schema.name` of `defineConfig`.
+The table carries an indexed `account_id` column so per-account
 session lookups and revocation stay in SQL; rows with a NULL `account_id` are still
-found and get classified on read, so no backfill is needed. Works on Postgres,
-MySQL and SQLite; expired rows are pruned every 10 minutes per connection. `accountStore` is the identity contract — `lucidAccountStore(AuthUser)`
+found and get classified on read, so no backfill is needed. Without `schema.name` it
+works on Postgres, MySQL and SQLite; with `schema: { name: 'auth' }` every AuthKit
+table lives in that DB schema (`"auth"."auth_settings"`), the boot creates it
+(`CREATE SCHEMA IF NOT EXISTS`; MySQL: `CREATE DATABASE IF NOT EXISTS`), and SQLite
+fails the boot instead of ignoring the option. Never use `searchPath` for this
+(it leaks across clients behind PgBouncer in transaction mode). Expired rows are pruned every 10 minutes per connection. `accountStore` is the identity contract — `lucidAccountStore(AuthUser)`
 derives `findAccount`/`verifyCredentials` from your user model.
 
 Source: `stubs/config/authkit.stub`, `src/define_config.ts` (`AuthServerConfigInput`),
@@ -112,7 +118,7 @@ blob lives); `{ source: 'jwks', keys }` supplies keys inline.
 
 The managed keystore's `store` accepts a path shortcut (`store: 'tmp/keystore.json'`)
 or `{ driver: ... }`: built-in vaults are `file`, `drive` (a `@adonisjs/drive` disk),
-`lucid` (table created on first write), `redis`, and `hashicorp`; for cloud secret
+`lucid` (table created on first write; `schema` overrides, default `schema.name`), `redis`, and `hashicorp`; for cloud secret
 managers install the add-ons `@adonis-agora/authkit-vault-aws` / `-azure` / `-gcp`
 and pass their `createKeystoreVault(...)` result as `store` (any object with a
 `read()` method is accepted). With no `store` at all, keys are ephemeral per boot.