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

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

@@ -24,9 +24,26 @@
  * ```
  */
 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 a usar. Default: conexão primária. */
+    /**
+     * Conexão Lucid das tabelas do authkit (`schema.connection`). Default: conexão
+     * primária. Ignorada quando `db` já é um client (o `this.db` de uma migration).
+     */
     connection?: string;
+    /**
+     * Conexão Lucid do model da conta, onde vive a tabela da conta (a coluna
+     * `login_methods`). Default: a conexão primária — NÃO a das tabelas do authkit.
+     * 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.
@@ -64,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,6 +23,7 @@
  * }
  * ```
  */
+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'] },
@@ -138,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');
@@ -185,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');
@@ -334,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))
@@ -419,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') {
@@ -440,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) {
@@ -457,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;
             }
@@ -471,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 = {};
@@ -494,22 +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 = typeof db.connection !== 'function'
-        ? db
-        : options.connection
-            ? db.connection(options.connection)
-            : db.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;
 }
 /**
@@ -521,17 +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 = typeof db.connection !== 'function'
-        ? db
-        : options.connection
-            ? db.connection(options.connection)
-            : db.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
@@ -547,11 +567,15 @@ export async function ensureAuthkitSchema(db, options = {}) {
     // `users` fixo: com a conta em `auth_users` (o nome que o próprio scaffold da
     // lib usa), o `users` fixo acertava uma tabela qualquer de mesmo nome e a
     // coluna ia parar no lugar errado sem erro nenhum.
+    //
+    // A tabela da conta fica na conexão do MODEL da conta, não na das tabelas do
+    // authkit (`schema.connection`).
     const accountTable = options.accountTable ?? 'users';
-    if (await tableExists(conn, accountTable)) {
+    const accountConn = authkitTablesClient(db, { connection: options.accountConnection });
+    if (await tableExists(accountConn, accountTable)) {
         try {
-            if (!(await columnExists(conn, accountTable, 'login_methods'))) {
-                await conn.schema.alterTable(accountTable, (t) => {
+            if (!(await columnExists(accountConn, accountTable, 'login_methods'))) {
+                await accountConn.schema.alterTable(accountTable, (t) => {
                     t.jsonb('login_methods').nullable();
                 });
                 report.altered[accountTable] = ['login_methods'];
@@ -568,7 +592,7 @@ export async function ensureAuthkitSchema(db, options = {}) {
              * o boot não avisava nada — o silêncio que este bloco existe para acabar.
              * (Mesma semântica do probe de `createTable` logo acima.)
              */
-            if (await columnExists(conn, accountTable, 'login_methods')) {
+            if (await columnExists(accountConn, accountTable, 'login_methods')) {
                 report.loginMethods.ensured = true;
             }
             else {

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

@@ -0,0 +1,56 @@
+/**
+ * Where AuthKit's OWN tables live (`auth_settings`, `auth_mfa`, `auth_password_history`,
+ * the organization tables, `authkit_oidc_payloads`, the personal-agent tables, the
+ * `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) 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`
+ * option). Not part of the `AccountStore` contract.
+ */
+export declare const BIND_TABLES_LOCATION: unique symbol;
+/** Hands `location` to a store that accepts it (see {@link BIND_TABLES_LOCATION}). */
+export declare function bindTablesLocation(store: unknown, location: AuthkitTablesLocation): void;

package/build/src/schema/tables_location.js

@@ -0,0 +1,86 @@
+/** 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
+ * used as is.
+ */
+export function authkitTablesClient(db, location = {}) {
+    if (typeof db?.connection !== 'function')
+        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`
+ * option). Not part of the `AccountStore` contract.
+ */
+export const BIND_TABLES_LOCATION = Symbol.for('authkit.bindTablesLocation');
+/** Hands `location` to a store that accepts it (see {@link BIND_TABLES_LOCATION}). */
+export function bindTablesLocation(store, location) {
+    const bind = store?.[BIND_TABLES_LOCATION];
+    if (typeof bind === 'function')
+        bind(location);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "1.0.0-rc.10",
+  "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.