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

package/build/src/accounts/lucid_store/password_hygiene.js

@@ -17,8 +17,10 @@ export function buildPasswordHistory(ctx, db) {
      * Lucid expõe `db.query().from(table)` para SELECT e `db.table(table).insert()` para INSERT.
      * Para DELETE usamos `db.query().from(table)`.
      */
+    // Lido a cada uso: o `defineConfig` informa o schema depois de o store existir.
+    const table = () => ctx.tableName ? ctx.tableName('auth_password_history') : 'auth_password_history';
     function qFrom() {
-        return db.query().from('auth_password_history');
+        return db.query().from(table());
     }
     return {
         async isPasswordReused(accountId, plainPassword, count, nativeVerify) {
@@ -51,7 +53,7 @@ export function buildPasswordHistory(ctx, db) {
         },
         async recordPasswordHistory(accountId, oldHash) {
             try {
-                await db.table('auth_password_history').insert({
+                await db.table(table()).insert({
                     account_id: accountId,
                     password_hash: oldHash,
                     created_at: DateTime.now().toISO(),

package/build/src/accounts/lucid_store/shared.d.ts

@@ -78,6 +78,17 @@ export interface LucidStoreContext {
      * recovery da conta. Ver nota de `emailVerificationTtlHours`.
      */
     emailChangeTtlHours?: number;
+    /**
+     * Query client for AuthKit's own tables (`auth_mfa`, `auth_password_history`):
+     * `schema.connection` of `defineConfig`, NOT the account model's connection. Absent
+     * → the model's connection (a store used without `defineConfig`).
+     */
+    tablesClient?: () => any;
+    /**
+     * Nome de uma tabela do authkit como os statements a escrevem: com `schema.name`,
+     * `schema.tabela` (o knex cita cada parte). Ausente → o nome puro.
+     */
+    tableName?: (name: string) => string;
 }
 export declare const sha256: (value: string) => string;
 /** Recovery code legível: 10 chars hex em duas metades (ex.: a1b2c-3d4e5). */
@@ -105,15 +116,17 @@ export interface MfaStatePatch {
 }
 /**
  * Repositório do estado de MFA na tabela LIB-OWNED `auth_mfa`, keyed por
- * `account_id`. Acessa o banco pela CONEXÃO do próprio model (`Model.query().client`),
- * a mesma usada pelo restante do store — sem exigir migration no host.
+ * `account_id`. Acessa o banco pela conexão das tabelas do authkit
+ * (`schema.connection`, via `tablesClient`), a mesma em que o `autoManage` cria a
+ * tabela — sem exigir migration no host. Sem `tablesClient` (store fora do
+ * `defineConfig`), cai na conexão do model.
  *
  * O `upsert` é portável (sqlite + pg sem UPSERT nativo): tenta UPDATE pela PK;
  * se não afetou nenhuma linha, faz INSERT. `recovery_codes` é serializado como
  * JSON (string) na escrita e desserializado na leitura (aceita tanto string —
  * sqlite/text — quanto array já parseado — pg jsonb).
  */
-export declare function buildMfaStateRepo(Model: any): {
+export declare function buildMfaStateRepo(Model: any, tablesClient?: () => any, tableName?: (name: string) => string): {
     /** Lê o estado de MFA da conta; null se não há linha em `auth_mfa`. */
     read(accountId: string): Promise<MfaState | null>;
     /**

package/build/src/accounts/lucid_store/shared.js

@@ -39,19 +39,22 @@ export function hashesEqual(a, b) {
 }
 /**
  * Repositório do estado de MFA na tabela LIB-OWNED `auth_mfa`, keyed por
- * `account_id`. Acessa o banco pela CONEXÃO do próprio model (`Model.query().client`),
- * a mesma usada pelo restante do store — sem exigir migration no host.
+ * `account_id`. Acessa o banco pela conexão das tabelas do authkit
+ * (`schema.connection`, via `tablesClient`), a mesma em que o `autoManage` cria a
+ * tabela — sem exigir migration no host. Sem `tablesClient` (store fora do
+ * `defineConfig`), cai na conexão do model.
  *
  * O `upsert` é portável (sqlite + pg sem UPSERT nativo): tenta UPDATE pela PK;
  * se não afetou nenhuma linha, faz INSERT. `recovery_codes` é serializado como
  * JSON (string) na escrita e desserializado na leitura (aceita tanto string —
  * sqlite/text — quanto array já parseado — pg jsonb).
  */
-export function buildMfaStateRepo(Model) {
-    const TABLE = 'auth_mfa';
-    /** QueryClient ligado à conexão do model (equivale ao `db` do password_history). */
+export function buildMfaStateRepo(Model, tablesClient, tableName = (name) => name) {
+    // Lido a cada uso: o `defineConfig` informa o schema depois de o store existir.
+    const table = () => tableName('auth_mfa');
+    /** QueryClient das tabelas do authkit (equivale ao `db` do password_history). */
     function client() {
-        return Model.query().client;
+        return tablesClient ? tablesClient() : Model.query().client;
     }
     /** Normaliza `recovery_codes` vindo do banco (json string OU array já parseado). */
     function parseRecoveryCodes(raw) {
@@ -90,7 +93,7 @@ export function buildMfaStateRepo(Model) {
     return {
         /** Lê o estado de MFA da conta; null se não há linha em `auth_mfa`. */
         async read(accountId) {
-            const row = await client().from(TABLE).where('account_id', accountId).first();
+            const row = await client().from(table()).where('account_id', accountId).first();
             if (!row)
                 return null;
             return {
@@ -124,17 +127,17 @@ export function buildMfaStateRepo(Model) {
             }
             if ('lastTotpStep' in patch)
                 update.last_totp_step = patch.lastTotpStep ?? null;
-            const affected = await client().from(TABLE).where('account_id', accountId).update(update);
+            const affected = await client().from(table()).where('account_id', accountId).update(update);
             // knex update retorna o nº de linhas afetadas (0 = linha ainda não existe).
             if (!affected) {
                 await client()
-                    .table(TABLE)
+                    .table(table())
                     .insert({ account_id: accountId, ...update });
             }
         },
         /** Remove o estado de MFA da conta (disable / reset total). No-op se ausente. */
         async clear(accountId) {
-            await client().from(TABLE).where('account_id', accountId).delete();
+            await client().from(table()).where('account_id', accountId).delete();
         },
     };
 }

package/build/src/accounts/lucid_store/webauthn.js

@@ -8,7 +8,7 @@ export function buildWebauthn(ctx, Credential, webauthn, ceremonies) {
     const { Model } = ctx;
     // Estado de MFA é LIB-OWNED (tabela `auth_mfa`): registrar uma passkey habilita
     // o MFA gravando `mfa_enabled_at` em `auth_mfa`, não numa coluna do model.
-    const mfaState = buildMfaStateRepo(Model);
+    const mfaState = buildMfaStateRepo(Model, ctx.tablesClient, ctx.tableName);
     return {
         async generatePasskeyRegistrationOptions(accountId) {
             const row = await Model.find(accountId);

package/build/src/adapters/database_adapter.d.ts

@@ -1,10 +1,16 @@
 import type { Database } from '@adonisjs/lucid/database';
 import type { EnumeratedArtifact, OidcAdapter, OidcPayload } from './adapter_contract.js';
+/** Nome da tabela (sem schema). O adapter recebe o nome já qualificado pelo factory. */
+export declare const OIDC_PAYLOADS_TABLE = "authkit_oidc_payloads";
 export declare class DatabaseAdapter implements OidcAdapter {
     #private;
     private name;
     private db;
-    constructor(name: string, db: Database);
+    /** `authkit_oidc_payloads`, qualificada com `schema.name` quando há schema. */
+    private table;
+    constructor(name: string, db: Database, 
+    /** `authkit_oidc_payloads`, qualificada com `schema.name` quando há schema. */
+    table?: string);
     upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
     renewSession(id: string, expiresIn: number): Promise<boolean>;
     find(id: string): Promise<OidcPayload | undefined>;

package/build/src/adapters/database_adapter.js

@@ -1,4 +1,5 @@
-const TABLE = 'authkit_oidc_payloads';
+/** Nome da tabela (sem schema). O adapter recebe o nome já qualificado pelo factory. */
+export const OIDC_PAYLOADS_TABLE = 'authkit_oidc_payloads';
 /** Intervalo mínimo, por conexão, entre duas limpezas das linhas expiradas. */
 const PRUNE_INTERVAL_MS = 10 * 60_000;
 /** Quanto tempo a ausência da coluna `account_id` vale antes de re-checar. */
@@ -6,11 +7,17 @@ const ACCOUNT_COLUMN_RECHECK_MS = 60_000;
 /** Tamanho máximo de uma lista `IN (...)`. */
 const IN_CHUNK = 500;
 const connectionStates = new WeakMap();
-function connectionState(db) {
-    let state = connectionStates.get(db);
+/** Estado por conexão E tabela (duas instalações em schemas diferentes não se misturam). */
+function connectionState(db, table) {
+    let byTable = connectionStates.get(db);
+    if (!byTable) {
+        byTable = new Map();
+        connectionStates.set(db, byTable);
+    }
+    let state = byTable.get(table);
     if (!state) {
         state = { accountColumn: null, accountColumnRecheckAt: 0, nextPruneAt: 0 };
-        connectionStates.set(db, state);
+        byTable.set(table, state);
     }
     return state;
 }
@@ -29,12 +36,16 @@ function chunks(items) {
 export class DatabaseAdapter {
     name;
     db;
-    constructor(name, db) {
+    table;
+    constructor(name, db, 
+    /** `authkit_oidc_payloads`, qualificada com `schema.name` quando há schema. */
+    table = OIDC_PAYLOADS_TABLE) {
         this.name = name;
         this.db = db;
+        this.table = table;
     }
     #query() {
-        return this.db.query().from(TABLE).where('model_name', this.name);
+        return this.db.query().from(this.table).where('model_name', this.name);
     }
     /**
      * Valor de `expires_at` (gravação e comparação) para o dialeto da conexão. No
@@ -43,7 +54,7 @@ export class DatabaseAdapter {
      * driver serializa no formato do banco — o MySQL recusa o ISO com `Z`.
      */
     #timestamp(ms) {
-        const state = connectionState(this.db);
+        const state = connectionState(this.db, this.table);
         if (state.dialect === undefined) {
             // O factory passa o manager (`Database`) ou um `QueryClient` de conexão nomeada.
             const db = this.db;
@@ -66,13 +77,13 @@ export class DatabaseAdapter {
      * re-checado, para pegar o ALTER do boot que rodou depois do primeiro request.
      */
     async #hasAccountColumn() {
-        const state = connectionState(this.db);
+        const state = connectionState(this.db, this.table);
         if (state.accountColumn === true)
             return true;
         if (state.accountColumn === false && state.accountColumnRecheckAt > Date.now())
             return false;
         try {
-            await this.db.query().from(TABLE).select('account_id').limit(1);
+            await this.db.query().from(this.table).select('account_id').limit(1);
             state.accountColumn = true;
         }
         catch {
@@ -88,7 +99,7 @@ export class DatabaseAdapter {
      * do caminho do request e nunca lança.
      */
     #maybePrune() {
-        const state = connectionState(this.db);
+        const state = connectionState(this.db, this.table);
         const now = Date.now();
         if (state.nextPruneAt > now)
             return;
@@ -96,7 +107,7 @@ export class DatabaseAdapter {
         Promise.resolve()
             .then(() => this.db
             .query()
-            .from(TABLE)
+            .from(this.table)
             .whereNotNull('expires_at')
             .where('expires_at', '<=', this.#timestamp(now))
             .delete())
@@ -125,7 +136,7 @@ export class DatabaseAdapter {
             await this.#query().where('id', id).update(row);
         }
         else {
-            await this.db.table(TABLE).insert(row);
+            await this.db.table(this.table).insert(row);
         }
         this.#maybePrune();
     }
@@ -185,7 +196,7 @@ export class DatabaseAdapter {
         await this.#query().where('id', id).delete();
     }
     async revokeByGrantId(grantId) {
-        await this.db.query().from(TABLE).where('grant_id', grantId).delete();
+        await this.db.query().from(this.table).where('grant_id', grantId).delete();
     }
     /**
      * Enumeração genérica dos artefatos do model deste adapter (id + payload).

package/build/src/adapters/factory.d.ts

@@ -1,8 +1,18 @@
 import type { ApplicationService } from '@adonisjs/core/types';
 import type { OidcAdapter } from './adapter_contract.js';
 export type OidcAdapterClass = new (name: string) => OidcAdapter;
+/** What `defineConfig` hands every adapter factory. */
+export interface AdapterResolveContext {
+    /**
+     * `schema.connection` of `defineConfig`: the Lucid connection AuthKit's tables live
+     * on. A database adapter without its own `connection` uses it.
+     */
+    connection?: string;
+    /** `schema.name` of `defineConfig`. A database adapter without its own `schema` uses it. */
+    schema?: string;
+}
 export interface AdapterFactory {
-    resolver(app: ApplicationService): Promise<OidcAdapterClass>;
+    resolver(app: ApplicationService, context?: AdapterResolveContext): Promise<OidcAdapterClass>;
 }
 /**
  * Modelos do oidc-provider de vida curta, amarrados ao ciclo da sessão de
@@ -35,8 +45,16 @@ export interface RedisAdapterConfig {
     prefix?: string;
 }
 export interface DatabaseAdapterConfig {
-    /** nome da conexão Lucid (default: a primária) */
+    /**
+     * Nome da conexão Lucid. Default: `schema.connection` do `defineConfig` (a conexão
+     * de todas as tabelas do authkit), e sem ela a primária.
+     */
     connection?: string;
+    /**
+     * Schema do banco da tabela `authkit_oidc_payloads` (MySQL: o database). Default:
+     * `schema.name` do `defineConfig`. Vai escrito em cada statement — nunca via searchPath.
+     */
+    schema?: string;
 }
 export declare const adapters: {
     /**

package/build/src/adapters/factory.js

@@ -1,4 +1,5 @@
-import { DatabaseAdapter } from './database_adapter.js';
+import { assertSchemaSupported, authkitTable, validateSchemaName, } from '../schema/tables_location.js';
+import { DatabaseAdapter, OIDC_PAYLOADS_TABLE } from './database_adapter.js';
 import { RedisAdapter } from './redis_adapter.js';
 /**
  * Modelos do oidc-provider de vida curta, amarrados ao ciclo da sessão de
@@ -67,13 +68,16 @@ export const adapters = {
      */
     database(config = {}) {
         return {
-            async resolver(app) {
+            async resolver(app, context) {
                 const db = await app.container.make('lucid.db');
-                const connection = config.connection;
+                const connection = config.connection ?? context?.connection;
+                const schema = validateSchemaName(config.schema ?? context?.schema, 'adapters.database({ schema })');
                 const conn = connection ? db.connection(connection) : db;
+                assertSchemaSupported(connection ? conn : db.connection(), schema);
+                const table = authkitTable({ schema }, OIDC_PAYLOADS_TABLE);
                 return class extends DatabaseAdapter {
                     constructor(name) {
-                        super(name, conn);
+                        super(name, conn, table);
                     }
                 };
             },

package/build/src/agents/delegation_store.d.ts

@@ -46,8 +46,12 @@ export interface LiveGrantFilter {
 export declare class DelegationStore {
     #private;
     private conn;
+    /** Nome da tabela como os statements o escrevem (`schema.tabela` com `schema.name`). */
+    private t;
     /** `conn` = uma conexão Lucid (`db.connection(name?)`) — ou uma transação. */
-    constructor(conn: () => any);
+    constructor(conn: () => any, 
+    /** Nome da tabela como os statements o escrevem (`schema.tabela` com `schema.name`). */
+    t?: (name: string) => string);
     insertDevice(row: Omit<DeviceCodeRow, 'accountId' | 'grantId' | 'lastPolledAt'>): Promise<void>;
     findDeviceByCodeHash(hash: string): Promise<DeviceCodeRow | null>;
     findDeviceByUserCode(userCode: string): Promise<DeviceCodeRow | null>;

package/build/src/agents/delegation_store.js

@@ -63,13 +63,17 @@ function affected(result) {
 }
 export class DelegationStore {
     conn;
+    t;
     /** `conn` = uma conexão Lucid (`db.connection(name?)`) — ou uma transação. */
-    constructor(conn) {
+    constructor(conn, 
+    /** Nome da tabela como os statements o escrevem (`schema.tabela` com `schema.name`). */
+    t = (name) => name) {
         this.conn = conn;
+        this.t = t;
     }
     // ─── device codes ─────────────────────────────────────────────────────────
     async insertDevice(row) {
-        await this.conn().table(DEVICE_TABLE).insert({
+        await this.conn().table(this.t(DEVICE_TABLE)).insert({
             id: row.id,
             device_code_hash: row.deviceCodeHash,
             user_code: row.userCode,
@@ -83,19 +87,22 @@ export class DelegationStore {
         });
     }
     async findDeviceByCodeHash(hash) {
-        const row = await this.conn().from(DEVICE_TABLE).where('device_code_hash', hash).first();
+        const row = await this.conn()
+            .from(this.t(DEVICE_TABLE))
+            .where('device_code_hash', hash)
+            .first();
         return row ? toDevice(row) : null;
     }
     async findDeviceByUserCode(userCode) {
-        const row = await this.conn().from(DEVICE_TABLE).where('user_code', userCode).first();
+        const row = await this.conn().from(this.t(DEVICE_TABLE)).where('user_code', userCode).first();
         return row ? toDevice(row) : null;
     }
     /** Liga o pedido aprovado ao grant — a partir daqui o polling do agente recebe o token. */
     async setDeviceGrant(id, grantId) {
-        await this.conn().from(DEVICE_TABLE).where('id', id).update({ grant_id: grantId });
+        await this.conn().from(this.t(DEVICE_TABLE)).where('id', id).update({ grant_id: grantId });
     }
     async markPolled(id, at) {
-        await this.conn().from(DEVICE_TABLE).where('id', id).update({ last_polled_at: at });
+        await this.conn().from(this.t(DEVICE_TABLE)).where('id', id).update({ last_polled_at: at });
     }
     /**
      * Transição de estado ATÔMICA: só aplica se o pedido ainda está em `from`.
@@ -108,7 +115,7 @@ export class DelegationStore {
         if (patch.grantId !== undefined)
             update.grant_id = patch.grantId;
         const result = await this.conn()
-            .from(DEVICE_TABLE)
+            .from(this.t(DEVICE_TABLE))
             .where('id', id)
             .where('status', from)
             .update(update);
@@ -119,11 +126,11 @@ export class DelegationStore {
      * vai pelo mesmo binding do INSERT, então a comparação é coerente no dialeto.
      */
     async deleteDevicesExpiredBefore(before) {
-        await this.conn().from(DEVICE_TABLE).where('expires_at', '<', before).delete();
+        await this.conn().from(this.t(DEVICE_TABLE)).where('expires_at', '<', before).delete();
     }
     // ─── grants ───────────────────────────────────────────────────────────────
     async insertGrant(row) {
-        await this.conn().table(GRANT_TABLE).insert({
+        await this.conn().table(this.t(GRANT_TABLE)).insert({
             id: row.id,
             account_id: row.accountId,
             client_id: row.clientId,
@@ -135,13 +142,13 @@ export class DelegationStore {
         });
     }
     async findGrant(id) {
-        const row = await this.conn().from(GRANT_TABLE).where('id', id).first();
+        const row = await this.conn().from(this.t(GRANT_TABLE)).where('id', id).first();
         return row ? toGrant(row) : null;
     }
     /** Grants NÃO revogados da tripla (conta, agente, usuário do agente). */
     async findGrantsFor(accountId, clientId, agentSub) {
         const rows = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('account_id', accountId)
             .where('client_id', clientId)
             .where('agent_sub', agentSub)
@@ -151,7 +158,7 @@ export class DelegationStore {
     /** Atualiza um grant NÃO revogado. `false` = revogado (ou sumiu) nesse meio-tempo. */
     async updateGrant(id, patch) {
         const result = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('id', id)
             .whereNull('revoked_at')
             .update({ scope: patch.scope, expires_at: patch.expiresAt, updated_at: patch.updatedAt });
@@ -159,7 +166,7 @@ export class DelegationStore {
     }
     async listGrants(accountId) {
         const rows = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('account_id', accountId)
             .whereNull('revoked_at')
             .orderBy('created_at', 'desc');
@@ -168,7 +175,7 @@ export class DelegationStore {
     /** Revoga um grant DA CONTA. `false` = não existe, é de outra conta ou já revogado. */
     async revokeGrant(accountId, id, at) {
         const result = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('id', id)
             .where('account_id', accountId)
             .whereNull('revoked_at')
@@ -177,7 +184,7 @@ export class DelegationStore {
     }
     async revokeAllGrants(accountId, at) {
         const result = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('account_id', accountId)
             .whereNull('revoked_at')
             .update({ revoked_at: at, updated_at: at });
@@ -189,7 +196,10 @@ export class DelegationStore {
      * protocolo sai do prefixo do id: `agrant_` (PACT) ou o `grantIdPrefix` de uma extension.
      */
     #live(now, filter = {}) {
-        let q = this.conn().from(GRANT_TABLE).whereNull('revoked_at').where('expires_at', '>', now);
+        let q = this.conn()
+            .from(this.t(GRANT_TABLE))
+            .whereNull('revoked_at')
+            .where('expires_at', '>', now);
         // O prefixo é `[a-z0-9]+_`: o `_` do LIKE (um caractere qualquer) casa com ele mesmo.
         if (filter.idPrefix)
             q = q.where('id', 'like', `${filter.idPrefix}%`);
@@ -222,7 +232,7 @@ export class DelegationStore {
     /** Ids dos grants não revogados de um agente (vivos ou não) — para revogar todos. */
     async unrevokedGrantIdsOfClient(clientId) {
         const rows = await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('client_id', clientId)
             .whereNull('revoked_at')
             .select('id');
@@ -231,14 +241,14 @@ export class DelegationStore {
     /** Revoga um grant sem checar a conta — reação a reuso de refresh token. */
     async revokeGrantById(id, at) {
         await this.conn()
-            .from(GRANT_TABLE)
+            .from(this.t(GRANT_TABLE))
             .where('id', id)
             .whereNull('revoked_at')
             .update({ revoked_at: at, updated_at: at });
     }
     // ─── refresh tokens ───────────────────────────────────────────────────────
     async insertRefreshToken(row) {
-        await this.conn().table(REFRESH_TABLE).insert({
+        await this.conn().table(this.t(REFRESH_TABLE)).insert({
             token_hash: row.tokenHash,
             grant_id: row.grantId,
             expires_at: row.expiresAt,
@@ -246,7 +256,10 @@ export class DelegationStore {
         });
     }
     async findRefreshToken(tokenHash) {
-        const row = await this.conn().from(REFRESH_TABLE).where('token_hash', tokenHash).first();
+        const row = await this.conn()
+            .from(this.t(REFRESH_TABLE))
+            .where('token_hash', tokenHash)
+            .first();
         return row
             ? {
                 grantId: row.grant_id,
@@ -258,7 +271,7 @@ export class DelegationStore {
     /** Marca o refresh como usado (uso único, atômico). `false` = já tinha sido usado. */
     async useRefreshToken(tokenHash, at) {
         const result = await this.conn()
-            .from(REFRESH_TABLE)
+            .from(this.t(REFRESH_TABLE))
             .where('token_hash', tokenHash)
             .whereNull('used_at')
             .update({ used_at: at });

package/build/src/agents/extension.d.ts

@@ -27,10 +27,18 @@ import type { HttpContext } from '@adonisjs/core/http';
  * A lib-owned table: created when missing, new columns added with `ALTER ADD`, never dropped or
  * altered. The builders receive a Knex `TableBuilder`.
  */
+/** What {@link AuthkitTable.create} receives next to the table builder. */
+export interface AuthkitTableContext {
+    /** `name` as AuthKit's tables are addressed: `schema.name` + `.` + `name` when a schema is set. */
+    table(name: string): string;
+}
 export interface AuthkitTable {
     name: string;
-    /** Full builder — runs when the table does not exist. */
-    create: (table: any) => void;
+    /**
+     * Full builder — runs when the table does not exist. A foreign key into another lib-owned
+     * table names it through `context.table(name)` (qualified with `schema.name` when set).
+     */
+    create: (table: any, context: AuthkitTableContext) => void;
     /**
      * One builder per column — runs (`ALTER ADD`) when the table exists but the column does not.
      * No constraints that break on populated tables (unique/FK belong in `create`).
@@ -125,6 +133,12 @@ export interface PersonalAgentHost {
     readonly issuer: string;
     /** The Lucid connection AuthKit's tables live on (`schema.connection`). */
     db(): any;
+    /**
+     * `name` as every statement must write it: `schema.name` + `.` + `name` when the app puts
+     * AuthKit's tables in a database schema (knex quotes each part), else `name`. Name every
+     * lib-owned table through it — the shared ledger tables and the extension's own.
+     */
+    table(name: string): string;
     readonly grants: PersonalAgentGrantLedger;
     /** The admin console's verdict on an agent of this protocol. `null` = not listed. */
     registryStatus(identifier: string): Promise<'allowed' | 'blocked' | null>;

package/build/src/agents/registry_store.d.ts

@@ -22,6 +22,7 @@ export declare class AgentRegistryStore {
     #private;
     constructor(conn: () => any, options?: {
         now?: () => number;
+        table?: (name: string) => string;
     });
     /** Todas as linhas, mais recentes primeiro. Lê do banco (console). */
     list(): Promise<AgentRegistryRow[]>;

package/build/src/agents/registry_store.js

@@ -47,13 +47,15 @@ export class AgentRegistryStore {
     #now;
     #snapshot = null;
     #loading = null;
+    #table;
     constructor(conn, options = {}) {
         this.#conn = conn;
+        this.#table = (options.table ?? ((name) => name))(REGISTRY_TABLE);
         this.#now = options.now ?? Date.now;
     }
     /** Todas as linhas, mais recentes primeiro. Lê do banco (console). */
     async list() {
-        const rows = await this.#conn().from(REGISTRY_TABLE).orderBy('updated_at', 'desc');
+        const rows = await this.#conn().from(this.#table).orderBy('updated_at', 'desc');
         return rows.map(toRow);
     }
     /** A linha do agente, pelo snapshot. `null` = o console não diz nada sobre ele. */
@@ -61,14 +63,14 @@ export class AgentRegistryStore {
         return (await this.#rows()).get(key(protocol, identifier)) ?? null;
     }
     async findById(id) {
-        const row = await this.#conn().from(REGISTRY_TABLE).where('id', id).first();
+        const row = await this.#conn().from(this.#table).where('id', id).first();
         return row ? toRow(row) : null;
     }
     /** Cria ou troca a linha de (protocolo, identificador). */
     async upsert(input) {
         const now = new Date(this.#now());
         const existing = await this.#conn()
-            .from(REGISTRY_TABLE)
+            .from(this.#table)
             .where('protocol', input.protocol)
             .where('identifier', input.identifier)
             .first();
@@ -80,11 +82,11 @@ export class AgentRegistryStore {
             updated_at: now,
         };
         if (existing) {
-            await this.#conn().from(REGISTRY_TABLE).where('id', existing.id).update(values);
+            await this.#conn().from(this.#table).where('id', existing.id).update(values);
         }
         else {
             await this.#conn()
-                .table(REGISTRY_TABLE)
+                .table(this.#table)
                 .insert({
                 id: `areg_${randomBytes(12).toString('base64url')}`,
                 protocol: input.protocol,
@@ -95,14 +97,14 @@ export class AgentRegistryStore {
         }
         this.invalidate();
         const row = await this.#conn()
-            .from(REGISTRY_TABLE)
+            .from(this.#table)
             .where('protocol', input.protocol)
             .where('identifier', input.identifier)
             .first();
         return toRow(row);
     }
     async delete(id) {
-        const result = await this.#conn().from(REGISTRY_TABLE).where('id', id).delete();
+        const result = await this.#conn().from(this.#table).where('id', id).delete();
         this.invalidate();
         return (typeof result === 'number' ? result : Array.isArray(result) ? result.length : 0) > 0;
     }
@@ -116,7 +118,7 @@ export class AgentRegistryStore {
         if (!this.#loading) {
             this.#loading = (async () => {
                 try {
-                    const rows = (await this.#conn().from(REGISTRY_TABLE)).map(toRow);
+                    const rows = (await this.#conn().from(this.#table)).map(toRow);
                     const map = new Map(rows.map((r) => [key(r.protocol, r.identifier), r]));
                     this.#snapshot = { rows: map, expiresAt: this.#now() + SNAPSHOT_TTL_MS };
                     return map;