@opensaas/stack-auth 0.39.1 → 0.40.0

package/dist/config/derive-auth-lists.js

@@ -1,280 +1,636 @@
 /**
- * Pure `better-auth config → Auth lists` derivation.
- *
- * This module is intentionally free of side effects and plugin/runtime
- * concerns: given the resolved better-auth model config (per-model `modelName`,
- * `tableName`, and `fields` column maps) plus any custom User fields, it
- * produces the four OpenSaaS Auth lists (user/session/account/verification)
- * with:
- *
- *  - list keys taken from each model's `modelName`
- *  - a table `@@map` (list-level `db.map`) taken from each model's resolved
- *    `tableName` — independent of `modelName`, so a renamed list key can still
- *    adopt a differently-named live table
- *  - field-level `@map` (`db.map`) for any better-auth field → column override
- *  - relationship refs between the auth lists wired to the *derived* keys
- *    (e.g. `Session.user → AuthUser.sessions`)
- *
- * When the developer supplies no `modelName`/`fields` overrides, the output
- * keeps the historical default keys (`User`/`Session`/`Account`/
- * `Verification`) and field shapes — see the unit tests. Per ADR-0013, each
- * list ships with **no** operation-level access unless the caller supplies it
- * (`accessConfig`, or `userConfig.access` for the user list) — deny-by-default,
- * not the plugin's former permissive defaults.
- *
- * `getAuthLists`/`convertBetterAuthSchema` (and the runtime user-key
- * resolution) consume this module so derivation lives in exactly one place.
+ * `better-auth config → Auth lists` derivation, free of side effects and
+ * plugin/runtime concerns. Reads better-auth's own resolved table
+ * definitions (`getAuthTables`, re-exported from `better-auth/db`) rather
+ * than hand-transcribing them, so the Auth lists cannot silently drift from
+ * what better-auth itself declares (issue #987). This single derivation also
+ * covers better-auth *plugin* tables (e.g. the MCP plugin's OAuth tables) —
+ * `getAuthTables` merges a plugin's own `schema` into its result when
+ * `options.plugins` is populated, so one registry and one field-derivation
+ * pass cover base models and plugin tables alike (issue #992). See
+ * `packages/auth/CLAUDE.md` ("Deriving Auth lists from better-auth config")
+ * for the full behavior and examples.
  */
 import { list } from '@opensaas/stack-core';
 import { text, timestamp, checkbox, integer, bigInt, relationship, } from '@opensaas/stack-core/fields';
+import { getAuthTables } from 'better-auth/db';
+const BASE_MODEL_KEYS = [
+    'user',
+    'session',
+    'account',
+    'verification',
+    'rateLimit',
+];
+/**
+ * Declared field order for each of the five base models, independent of the
+ * order `getAuthTables` happens to return fields in. Prisma doesn't care
+ * about field order, but pinning it keeps the generated schema stable across
+ * this change (and future better-auth releases) instead of reshuffling on
+ * every regenerate — the reverse relations (`user.sessions`/`user.accounts`)
+ * are appended after these, in the order their owning model is processed
+ * below. A plugin table has no entry here — `assembleFields` falls back to
+ * upstream field order for any model this table doesn't list, which is every
+ * plugin table.
+ */
+const FIELD_ORDER = {
+    user: ['name', 'email', 'emailVerified', 'image'],
+    session: ['token', 'expiresAt', 'ipAddress', 'userAgent', 'user'],
+    account: [
+        'accountId',
+        'providerId',
+        // `issuer` (better-auth 1.7+, issue #986) groups with accountId/providerId
+        // as the account's identity fields — together the table-level
+        // `@@unique([issuer, accountId])` better-auth declares (not yet emitted;
+        // blocked on #986 reading better-auth's own table-level `indexes` through
+        // the app-supplied `db.indexes` passthrough #985 adds).
+        'issuer',
+        'user',
+        'accessToken',
+        'refreshToken',
+        'accessTokenExpiresAt',
+        'refreshTokenExpiresAt',
+        'scope',
+        'idToken',
+        'password',
+    ],
+    verification: ['identifier', 'value', 'expiresAt'],
+    rateLimit: ['key', 'count', 'lastRequest'],
+};
+/** Carried via list-level `db.timestamps` (see `listDb`) rather than as ordinary derived fields. */
+const TIMESTAMP_FIELDS = new Set(['createdAt', 'updatedAt']);
 /**
- * Build the list-level `db` config (`timestamps` + `@@map` + `@@schema`) for a
- * derived list.
+ * Fields that hold a live, presentable credential — reading the value is
+ * equivalent to holding it (session hijack, account takeover, replaying an
+ * OAuth token) — rather than merely identifying a row. Keyed by better-auth's
+ * own model/field keys, not the app's list/column names, so the deny holds
+ * under `modelName` and column `fields` remapping alike (ADR-0036).
  *
- * `timestamps` is a per-model input rather than hardcoded: better-auth's
- * adapter writes `createdAt`/`updatedAt` on every user/session/account/
- * verification row (and the schema converter returns `null` for those columns,
- * assuming the generator injects them), so those four opt back into
- * auto-timestamps now that they're OFF by default (ADR-0004). The `RateLimit`
- * model has neither column in better-auth's own schema, so it passes `false`.
+ * Covers the four base models plus every better-auth plugin table the stack
+ * has first-class support for (ADR-0034's registry of known plugins) — the
+ * `mcp`/oauth-provider plugin's client secret and token columns, and
+ * `twoFactor()`'s encrypted secret/backup codes (issue #1014). An app can
+ * mark further fields via `authPlugin({ credentialFields })`, merged in by
+ * {@link buildCredentialFieldRegistry} — this constant is never mutated.
+ */
+const CREDENTIAL_FIELDS = {
+    session: ['token'],
+    verification: ['value'],
+    account: ['password', 'accessToken', 'refreshToken', 'idToken'],
+    oauthClient: ['clientSecret'],
+    oauthAccessToken: ['token'],
+    oauthRefreshToken: ['token'],
+    twoFactor: ['secret', 'backupCodes'],
+};
+const DENY_READ = { read: () => false };
+/**
+ * Merges the stack-seeded {@link CREDENTIAL_FIELDS} with an app's
+ * `authPlugin({ credentialFields })`, then validates every entry against the
+ * models actually being derived (`tables`, keyed by better-auth model key).
  *
- * The physical table name (`@@map`) comes from the model's resolved
- * `tableName` — independent of the list key/`modelName` — so a renamed list
- * key can still adopt a differently-named live table (e.g. better-auth's own
- * default lowercase table names). When a `schema` is configured (plugin-level
- * or per-model), the list is placed in that Postgres schema via `@@schema(...)`.
+ * Additive only: an app entry can add fields to a model — including a
+ * stack-seeded one — but nothing can remove a seeded field, so a config that
+ * omits or empties a seeded model's list leaves that model's seeded deny
+ * standing.
  *
- * With no `tableName`/`schema` overrides and `timestamps: true` we emit only
- * `{ timestamps: true }`, leaving the default `User`/`Session`/... output
- * unchanged.
+ * A field named on a model that isn't in `tables` at all (a plugin the app
+ * doesn't use) is a silent no-op — the entry simply never matches anything.
+ * A field named on a model that IS in `tables` but doesn't declare that field
+ * throws, naming the model and field, since that is a config mistake the app
+ * would otherwise never learn about (the deny would just never fire).
  */
-function listDb(model, timestamps) {
-    const schema = model.schema;
+function buildCredentialFieldRegistry(tables, appConfig) {
+    const merged = new Map();
+    for (const [modelKey, fields] of Object.entries(CREDENTIAL_FIELDS)) {
+        merged.set(modelKey, new Set(fields));
+    }
+    for (const [modelKey, fields] of Object.entries(appConfig)) {
+        const set = merged.get(modelKey) ?? new Set();
+        for (const fieldKey of fields)
+            set.add(fieldKey);
+        merged.set(modelKey, set);
+    }
+    const registry = {};
+    for (const [modelKey, fields] of merged) {
+        const table = tables[modelKey];
+        if (!table)
+            continue; // model not derived (plugin unused) -> silent no-op
+        for (const fieldKey of fields) {
+            const upstream = table.fields[fieldKey];
+            if (!upstream) {
+                throw new Error(`deriveAuthLists: credentialFields names "${modelKey}.${fieldKey}", but "${modelKey}" has no field "${fieldKey}"`);
+            }
+            // An id-referencing field derives to a relationship() (see the
+            // `references.field === 'id'` branch below), never a scalar field —
+            // withCredentialAccess is only ever applied on the scalar-field path,
+            // so a deny registered against one would silently never apply. Fail
+            // loudly instead of accepting a config that has no effect.
+            if (upstream.references?.field === 'id') {
+                throw new Error(`deriveAuthLists: credentialFields names "${modelKey}.${fieldKey}", but "${fieldKey}" is a ` +
+                    `relationship field (references "${upstream.references.model}.id"), not a scalar credential column`);
+            }
+        }
+        registry[modelKey] = fields;
+    }
+    return registry;
+}
+function withCredentialAccess(registry, modelKey, fieldKey, field) {
+    if (!registry[modelKey]?.has(fieldKey))
+        return field;
     return {
-        ...(timestamps ? { timestamps: true } : {}),
-        ...(model.tableName !== undefined ? { map: model.tableName } : {}),
-        ...(schema !== undefined ? { schema } : {}),
+        ...field,
+        access: DENY_READ,
+        // Curated out of the admin's default table columns too (issue #1018),
+        // via the same declared flag as everything else — a read-denied column
+        // would otherwise render permanently empty rather than simply absent.
+        ui: {
+            ...field.ui,
+            listView: { ...field.ui?.listView, defaultColumn: false },
+        },
     };
 }
 /**
- * Resolve the `db.map` (`@map` column override) for a better-auth field, or
- * `undefined` when there is no override (so default output is unchanged).
- *
- * The field builders capture `options.db` in a closure when generating Prisma
- * types, so the column map MUST be passed through the builder's `db` option
- * rather than patched onto the returned field object.
+ * Whether a model declares BOTH `createdAt` and `updatedAt` upstream — the
+ * only shape `db.timestamps: true` can express, since it always emits both
+ * columns together (`resolveListTimestamps` in the Prisma generator). The
+ * four base models always satisfy this. A better-auth plugin table is not
+ * guaranteed to: the MCP plugin's OAuth tables (better-auth 1.7, issue #992)
+ * include several with only `createdAt` (e.g. `oauthAccessToken`,
+ * `oauthRefreshToken`, `oauthClientResource`) — those fall through to the
+ * general field-derivation loop below instead, so `createdAt` alone is still
+ * derived as an ordinary scalar column rather than silently dropped (which
+ * previously crashed a real write the moment better-auth's own adapter tried
+ * to set it — see `oauthResource`'s seeded row in the MCP OAuth cascade e2e
+ * test).
  */
-function fieldDb(fieldName, fields) {
-    const column = fields[fieldName];
-    return column ? { map: column } : undefined;
+function hasSymmetricTimestamps(upstreamFields) {
+    return 'createdAt' in upstreamFields && 'updatedAt' in upstreamFields;
 }
 /**
- * Build the `db` config for a `user` relationship (`Session.user` /
- * `Account.user`), honouring a `userId` column override from the better-auth
- * `fields` map and mirroring better-auth's own FK shape: no separate FK index
- * — the index is applied at the field level via `isIndexed: false` —
- * `onDelete: Cascade`, and a required (non-nullable) foreign key, since
- * better-auth's adapter always writes a `userId` on every session/account row
- * it creates. This means a generated Auth schema diffs clean against a live
- * better-auth database on all three dimensions instead of showing a spurious
- * index drop, a referential-action change, and a `DROP NOT NULL` (issues #679,
- * #863).
+ * The reverse relation field name a foreign key implies on its target model
+ * (e.g. `User.sessions`) has no source in better-auth's metadata at all —
+ * `references` declares only the child→parent link, never a name for the
+ * parent's reverse collection. Derived by pluralizing the child model's own
+ * key, which reproduces every current name; override here for a collision or
+ * a bad pluralization, one entry per better-auth model key (base or plugin).
  */
-function userRelationshipDb(fields) {
-    const column = fields.userId;
-    return {
-        isNullable: false,
-        ...(column ? { foreignKey: { map: column } } : {}),
-        extendPrismaSchema: ({ fkLine, relationLine }) => ({
-            fkLine,
-            relationLine: relationLine.replace('@relation(', '@relation(onDelete: Cascade, '),
-        }),
-    };
+const REVERSE_RELATION_NAME_OVERRIDES = {};
+function pluralize(word) {
+    if (/[sxz]$|[cs]h$/.test(word))
+        return `${word}es`;
+    if (/[^aeiou]y$/.test(word))
+        return `${word.slice(0, -1)}ies`;
+    return `${word}s`;
+}
+function reverseRelationName(modelKey) {
+    return REVERSE_RELATION_NAME_OVERRIDES[modelKey] ?? pluralize(modelKey);
 }
 /**
- * Create the Auth user list, applying derived field column maps + table map and
- * wiring the session/account relationships to the derived keys.
- *
- * Per ADR-0013, the plugin ships no permissive access default: the list is
- * closed unless the application supplies access via `extendUserList.access`
- * (takes precedence — it predates the keyed `access` passthrough and is
- * User-specific) or the `access.user` passthrough.
+ * The relationship field name a foreign key column derives to (e.g. `userId`
+ * → `user`) — better-auth models the column as a plain scalar carrying
+ * `references`; the stack models the same column as a `relationship()` under
+ * a different key. Stripping a trailing `Id` is the naming convention
+ * better-auth's own FK columns (and the stack's prior hand-written lists)
+ * already follow.
  */
-function createUserList(model, keys, userConfig, access) {
-    const f = model.fields;
-    return list({
-        fields: {
-            name: text({ validation: { isRequired: true }, db: fieldDb('name', f) }),
-            email: text({
-                validation: { isRequired: true },
-                isIndexed: 'unique',
-                db: fieldDb('email', f),
-            }),
-            emailVerified: checkbox({ defaultValue: false, db: fieldDb('emailVerified', f) }),
-            image: text({ db: fieldDb('image', f) }),
-            // Relationships to the other auth lists — refs follow the derived keys.
-            sessions: relationship({ ref: `${keys.session}.user`, many: true }),
-            accounts: relationship({ ref: `${keys.account}.user`, many: true }),
-            // Custom fields from user config
-            ...(userConfig.fields || {}),
-        },
-        db: listDb(model, true),
-        access: userConfig.access || access,
-        hooks: userConfig.hooks,
-    });
+function relationshipFieldName(upstreamFieldKey) {
+    return upstreamFieldKey.endsWith('Id') ? upstreamFieldKey.slice(0, -2) : upstreamFieldKey;
+}
+const ON_DELETE_ACTIONS = {
+    cascade: 'Cascade',
+    restrict: 'Restrict',
+    'set null': 'SetNull',
+    'set default': 'SetDefault',
+    'no action': 'NoAction',
+};
+function mapOnDelete(action) {
+    return ON_DELETE_ACTIONS[action] ?? 'Cascade';
 }
 /**
- * Create the Auth session list.
- *
- * Per ADR-0013, the plugin ships no permissive access default — closed unless
- * the application supplies `access.session`.
+ * PascalCase a better-auth `modelName`, preserving internal word boundaries.
+ * Base models never go through this — their list key is always the
+ * configured `modelName` as-is (see `buildModelRegistry`) — only plugin
+ * tables do, since better-auth plugins declare camelCase (`oauthApplication`)
+ * or snake_case (`oauth_application`) model names and list keys must be
+ * PascalCase (issue #991).
  */
-function createSessionList(model, keys, access) {
-    const f = model.fields;
-    return list({
-        fields: {
-            token: text({
-                validation: { isRequired: true },
-                isIndexed: 'unique',
-                db: fieldDb('token', f),
-            }),
-            expiresAt: timestamp({
-                db: { isNullable: false, ...fieldDb('expiresAt', f) },
-            }),
-            ipAddress: text({ db: fieldDb('ipAddress', f) }),
-            userAgent: text({ db: fieldDb('userAgent', f) }),
-            user: relationship({
-                ref: `${keys.user}.sessions`,
-                isIndexed: false,
-                db: userRelationshipDb(f),
-            }),
-        },
-        db: listDb(model, true),
-        access,
-    });
+function pascalCaseModelName(modelName) {
+    if (/[_-]/.test(modelName)) {
+        return modelName
+            .split(/[_-]/)
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .join('');
+    }
+    return modelName.charAt(0).toUpperCase() + modelName.slice(1);
+}
+function scalarIsIndexed(upstream) {
+    if (upstream.unique)
+        return 'unique';
+    if (upstream.index)
+        return true;
+    return undefined;
+}
+/**
+ * The OpenSaaS field keys an app-supplied `db.indexes` entry (ADR-0035)
+ * claims on this model — every field named in any entry's `fields` array,
+ * regardless of that entry's own arity or uniqueness. A claimed column's
+ * derived `isIndexed` (from better-auth's own `unique`/`index` flags) is
+ * suppressed so only the app's entry is emitted; suppression is per-column,
+ * so a composite entry claiming `identifier` leaves every other derived
+ * index on the model untouched.
+ */
+function claimedIndexFields(indexes) {
+    const claimed = new Set();
+    for (const index of indexes) {
+        for (const fieldRef of index.fields) {
+            claimed.add(typeof fieldRef === 'string' ? fieldRef : fieldRef.field);
+        }
+    }
+    return claimed;
+}
+/**
+ * `db.isNullable` is set explicitly from `required` rather than left to each
+ * field builder's own default — `timestamp()` in particular defaults nullable
+ * off of whether it carries a `now()` default, not off requiredness, so
+ * leaving it implicit would silently produce a nullable column for a
+ * required upstream date field. `db.map` is set only when the resolved
+ * column name differs from the field's own key, so an unmodified field
+ * doesn't grow a redundant `@map`.
+ */
+function scalarFieldDb(fieldKey, upstream) {
+    const columnName = upstream.fieldName ?? fieldKey;
+    return {
+        isNullable: !(upstream.required ?? true),
+        ...(columnName !== fieldKey ? { map: columnName } : {}),
+    };
+}
+function buildScalarField(fieldKey, upstream, suppressIndex) {
+    const isRequired = upstream.required ?? true;
+    const isIndexed = suppressIndex ? undefined : scalarIsIndexed(upstream);
+    const db = scalarFieldDb(fieldKey, upstream);
+    switch (upstream.type) {
+        case 'string': {
+            const staticDefault = typeof upstream.defaultValue === 'function' ? undefined : upstream.defaultValue;
+            return text({
+                ...(isRequired ? { validation: { isRequired: true } } : {}),
+                ...(isIndexed ? { isIndexed } : {}),
+                ...(staticDefault !== undefined ? { defaultValue: staticDefault } : {}),
+                db,
+            });
+        }
+        case 'boolean': {
+            const staticDefault = typeof upstream.defaultValue === 'function' ? undefined : upstream.defaultValue;
+            return checkbox({
+                ...(isIndexed ? { isIndexed } : {}),
+                ...(staticDefault !== undefined ? { defaultValue: staticDefault } : {}),
+                db,
+            });
+        }
+        case 'date':
+            return timestamp({ ...(isIndexed ? { isIndexed } : {}), db });
+        case 'number': {
+            const staticDefault = typeof upstream.defaultValue === 'function' ? undefined : upstream.defaultValue;
+            return upstream.bigint
+                ? bigInt({
+                    ...(isRequired ? { validation: { isRequired: true } } : {}),
+                    ...(isIndexed ? { isIndexed } : {}),
+                    ...(staticDefault !== undefined ? { defaultValue: staticDefault } : {}),
+                    db,
+                })
+                : integer({
+                    ...(isRequired ? { validation: { isRequired: true } } : {}),
+                    ...(isIndexed ? { isIndexed } : {}),
+                    ...(staticDefault !== undefined ? { defaultValue: staticDefault } : {}),
+                    db,
+                });
+        }
+        default:
+            // better-auth's `DBFieldType` also allows `json`, `string[]`/`number[]`,
+            // and an enum array — none of which any built-in plugin (MCP, admin,
+            // organization, two-factor, ...) or the four base models actually use
+            // today. Warn and fall back to a plain `text()` column rather than
+            // throwing, so an app config that happens to hit this still generates
+            // (matching the pre-consolidation plugin-table converter's behavior)
+            // instead of crashing the whole `config()`/`generate` pipeline.
+            console.warn(`[stack-auth] Unknown better-auth field type "${upstream.type}" for field "${fieldKey}", defaulting to text field`);
+            return text({
+                ...(isRequired ? { validation: { isRequired: true } } : {}),
+                ...(isIndexed ? { isIndexed } : {}),
+                db,
+            });
+    }
 }
 /**
- * Create the Auth account list.
+ * Build the `relationship()` field for a foreign-key column (e.g.
+ * `Session.user`), mirroring better-auth's own FK shape exactly: the
+ * physical column always maps explicitly to better-auth's resolved column
+ * name (even when it equals the field name — leaving it conditional would
+ * let the generator's Keystone-parity default take over and map to the
+ * relationship field name instead, reintroducing issue #935), requiredness
+ * and `onDelete` come from `references`, and the FK index/uniqueness mirror
+ * better-auth's own `index`/`unique` flags (ADR-0007).
  *
- * Per ADR-0013, the plugin ships no permissive access default — closed unless
- * the application supplies `access.account`.
+ * Only called for a reference whose target field is the target's `id` — see
+ * the field-derivation loop in {@link deriveAuthLists} for the non-PK case
+ * (e.g. better-auth's own oidc-provider schema references
+ * `oauthApplication.clientId`, not its `id`), which `relationship()` cannot
+ * express and stays a plain scalar column instead.
  */
-function createAccountList(model, keys, access) {
-    const f = model.fields;
-    return list({
-        fields: {
-            accountId: text({ validation: { isRequired: true }, db: fieldDb('accountId', f) }),
-            providerId: text({ validation: { isRequired: true }, db: fieldDb('providerId', f) }),
-            user: relationship({
-                ref: `${keys.user}.accounts`,
-                isIndexed: false,
-                db: userRelationshipDb(f),
+function buildForeignKeyField(fieldKey, upstream, targetListKey, reverseFieldName, suppressIndex) {
+    const references = upstream.references;
+    if (!references) {
+        throw new Error(`deriveAuthLists: "${fieldKey}" was routed as a foreign key but has no references`);
+    }
+    const isRequired = upstream.required ?? true;
+    const columnName = upstream.fieldName ?? fieldKey;
+    const onDelete = mapOnDelete(references.onDelete ?? 'cascade');
+    // A relationship field's own generator defaults its FK index to indexed
+    // (true) whenever `isIndexed` is *omitted*, unlike a scalar field — so
+    // suppression can't just drop the property here the way `buildScalarField`
+    // does; it must set `isIndexed: false` explicitly to actually turn the
+    // derived index off.
+    const isIndexed = suppressIndex ? false : scalarIsIndexed(upstream);
+    return relationship({
+        ref: `${targetListKey}.${reverseFieldName}`,
+        ...(isIndexed !== undefined ? { isIndexed } : {}),
+        db: {
+            isNullable: !isRequired,
+            foreignKey: { map: columnName },
+            extendPrismaSchema: ({ fkLine, relationLine }) => ({
+                fkLine,
+                relationLine: relationLine.replace('@relation(', `@relation(onDelete: ${onDelete}, `),
             }),
-            accessToken: text({ db: fieldDb('accessToken', f) }),
-            refreshToken: text({ db: fieldDb('refreshToken', f) }),
-            accessTokenExpiresAt: timestamp({ db: fieldDb('accessTokenExpiresAt', f) }),
-            refreshTokenExpiresAt: timestamp({ db: fieldDb('refreshTokenExpiresAt', f) }),
-            scope: text({ db: fieldDb('scope', f) }),
-            idToken: text({ db: fieldDb('idToken', f) }),
-            password: text({ db: fieldDb('password', f) }),
         },
-        db: listDb(model, true),
-        access,
     });
 }
 /**
- * Create the Auth verification list.
+ * Build the list-level `db` config (`timestamps` + `@@map` + `@@schema`) for
+ * a derived base-model list.
  *
- * Per ADR-0013, the plugin ships no permissive access default — closed unless
- * the application supplies `access.verification`.
+ * `timestamps` is a per-model input, not hardcoded: better-auth's adapter
+ * writes `createdAt`/`updatedAt` on every user/session/account/verification
+ * row, so those four opt back into auto-timestamps now that they're OFF by
+ * default (ADR-0004). The `RateLimit` model has neither column upstream, so
+ * it passes `false`. Plugin tables don't go through this — see the "Out of
+ * scope" note on `deriveAuthLists` about not adding fields/behavior
+ * better-auth doesn't declare a JS-level default for.
  */
-function createVerificationList(model, access) {
-    const f = model.fields;
-    return list({
-        fields: {
-            identifier: text({ validation: { isRequired: true }, db: fieldDb('identifier', f) }),
-            value: text({ validation: { isRequired: true }, db: fieldDb('value', f) }),
-            expiresAt: timestamp({
-                db: { isNullable: false, ...fieldDb('expiresAt', f) },
-            }),
-        },
-        db: listDb(model, true),
-        access,
-    });
+function listDb(model, timestamps) {
+    const schema = model.schema;
+    const indexes = model.indexes;
+    return {
+        ...(timestamps ? { timestamps: true } : {}),
+        ...(model.tableName !== undefined ? { map: model.tableName } : {}),
+        ...(schema !== undefined ? { schema } : {}),
+        ...(indexes && indexes.length > 0 ? { indexes } : {}),
+    };
+}
+function betterAuthModelOptions(model) {
+    return { fields: model.fields };
 }
 /**
- * Create the Auth rate-limit list, present only when `rateLimit.storage ===
- * 'database'` derives a `rateLimit` model. Mirrors better-auth's own
- * `rateLimit` table exactly (`getAuthTables` in `@better-auth/core`, verified
- * against better-auth@1.6.25): `key` (unique — load-bearing, not cosmetic,
- * since the limiter races concurrent requests into a create and relies on the
- * resulting constraint violation to serialise them), `count`, and
- * `lastRequest` (a millisecond epoch, hence `bigInt()` rather than
- * `integer()`, which would overflow). None of the three columns carries a
- * Prisma default — the limiter supplies `lastRequest` explicitly on every
- * create/update, and an adopted live table has no default to match. No
- * `createdAt`/`updatedAt` either (see `listDb`'s `timestamps` argument):
- * better-auth's own rate-limit table has neither column.
+ * The options object fed to `getAuthTables` — carries the per-model column
+ * overrides the app configured, plus the app's better-auth plugins so their
+ * own `schema` (base-model extensions and standalone plugin tables alike)
+ * merges into the same resolved table set (issue #992).
+ */
+function buildBetterAuthTableOptions(models, plugins) {
+    return {
+        user: betterAuthModelOptions(models.user),
+        session: betterAuthModelOptions(models.session),
+        account: betterAuthModelOptions(models.account),
+        verification: betterAuthModelOptions(models.verification),
+        ...(models.rateLimit
+            ? { rateLimit: { storage: 'database', ...betterAuthModelOptions(models.rateLimit) } }
+            : {}),
+        ...(plugins.length ? { plugins } : {}),
+    };
+}
+/**
+ * The model registry: every better-auth model key (base or plugin) mapped to
+ * its derived list key. Built in one pass over `getAuthTables`' full result,
+ * before any field is derived — reference resolution needs a target's
+ * derived list key, and a reference can cross from a plugin table to a base
+ * model, from a plugin table to another plugin table, or (for the base
+ * models themselves) to another base model, so the whole set has to be known
+ * up front rather than resolved lazily per model.
  *
- * Per ADR-0013, the plugin ships no permissive access default — closed unless
- * the application supplies `access.rateLimit`.
+ * Base models keep their existing behavior: the list key is exactly the
+ * configured `modelName` (already assumed PascalCase by convention, not
+ * re-cased here). A plugin table's list key is PascalCased from its resolved
+ * `modelName` (issue #991) — `getAuthTables` always resolves a plugin
+ * table's `modelName` (defaulting to its own schema key when the plugin
+ * doesn't set one), so this is never applied to an empty string.
  */
-function createRateLimitList(model, access) {
-    const f = model.fields;
-    return list({
-        fields: {
-            key: text({
-                validation: { isRequired: true },
-                isIndexed: 'unique',
-                db: fieldDb('key', f),
-            }),
-            count: integer({
-                validation: { isRequired: true },
-                db: { isNullable: false, ...fieldDb('count', f) },
-            }),
-            lastRequest: bigInt({
-                validation: { isRequired: true },
-                db: { isNullable: false, ...fieldDb('lastRequest', f) },
-            }),
-        },
-        db: listDb(model, false),
-        access,
-    });
+function buildModelRegistry(tables, models) {
+    const keys = {
+        user: models.user.modelName,
+        session: models.session.modelName,
+        account: models.account.modelName,
+        verification: models.verification.modelName,
+        ...(models.rateLimit ? { rateLimit: models.rateLimit.modelName } : {}),
+    };
+    const registry = new Map();
+    for (const baseKey of BASE_MODEL_KEYS) {
+        const listKey = keys[baseKey];
+        if (listKey)
+            registry.set(baseKey, listKey);
+    }
+    for (const modelKey of Object.keys(tables)) {
+        if (registry.has(modelKey))
+            continue;
+        registry.set(modelKey, pascalCaseModelName(tables[modelKey].modelName));
+    }
+    return { keys, registry };
 }
 /**
- * Derive the OpenSaaS Auth lists from the resolved better-auth model config.
+ * Derive the OpenSaaS Auth lists from the resolved better-auth model config —
+ * the four base models, an optional database-backed `RateLimit`, and any
+ * table a better-auth plugin declares in its own `schema` (issue #992).
  *
- * Per ADR-0013 the derived lists ship **closed** (no permissive operation
+ * Per ADR-0013 every derived list ships **closed** (no permissive operation
  * access) unless the application supplies access via `accessConfig` (the
  * `authPlugin({ access: … })` passthrough, keyed by better-auth model name) or,
  * for the user list specifically, `userConfig.access` (`extendUserList.access`,
- * which takes precedence — see {@link AuthAccessConfig}).
+ * which takes precedence — see {@link AuthAccessConfig}). Plugin tables have no
+ * `access` passthrough at all — an app that needs to grant access declares the
+ * list itself under the same derived key so this function's field-only merge
+ * (in `authPlugin`'s add-vs-extend loop) leaves the app's own access standing.
  *
  * A fifth `RateLimit` list is included only when `models.rateLimit` is
  * present (i.e. `rateLimit.storage === 'database'`).
  *
- * @param models - Resolved better-auth per-model config (modelName + field column maps)
+ * Each base model's `indexes` (`AuthModelConfig.indexes`) carries through to
+ * the derived list's `db.indexes` unchanged, and suppresses this function's
+ * own derived field-level `isIndexed` for any column an entry names — the
+ * application's declaration wins over a derived default (ADR-0035).
+ *
+ * @param models - Resolved better-auth per-model config (modelName + field column maps + app-supplied indexes)
  * @param userConfig - Extra User-list fields/access/hooks supplied via `extendUserList`
- * @param accessConfig - App-authored access for each Auth list, keyed by better-auth model name
- * @returns The derived list keys and the Auth list configs keyed by those keys
+ * @param accessConfig - App-authored access for each base Auth list, keyed by better-auth model name
+ * @param plugins - The app's better-auth plugins (`authPlugin({ betterAuthPlugins })`), whose own
+ *   `schema` (base-model extensions and standalone plugin tables) is derived alongside the base models
+ * @param credentialFieldsConfig - App-authored additions to the credential-field read-deny
+ *   (`authPlugin({ credentialFields })`), keyed by better-auth model key. Additive only — see
+ *   {@link buildCredentialFieldRegistry}.
+ * @returns The derived base-model list keys and every derived list config (base models and plugin tables)
  */
-export function deriveAuthLists(models, userConfig = {}, accessConfig = {}) {
-    const keys = {
-        user: models.user.modelName,
-        session: models.session.modelName,
-        account: models.account.modelName,
-        verification: models.verification.modelName,
-        ...(models.rateLimit ? { rateLimit: models.rateLimit.modelName } : {}),
-    };
+export function deriveAuthLists(models, userConfig = {}, accessConfig = {}, plugins = [], credentialFieldsConfig = {}) {
+    const tables = getAuthTables(buildBetterAuthTableOptions(models, plugins));
+    const { keys, registry } = buildModelRegistry(tables, models);
+    const credentialRegistry = buildCredentialFieldRegistry(tables, credentialFieldsConfig);
+    // Only the five base models carry an app-authored `db.indexes` passthrough
+    // (`AuthModelConfig.indexes`) — plugin tables have no per-model config
+    // block to declare them through (deliberately out of scope, see the issue
+    // brief). Computed once per model rather than per field.
+    const claimedFieldsByModel = {};
+    for (const baseKey of BASE_MODEL_KEYS) {
+        const model = models[baseKey];
+        if (model)
+            claimedFieldsByModel[baseKey] = claimedIndexFields(model.indexes ?? []);
+    }
+    const scalarFields = {};
+    const foreignKeyFields = {};
+    const reverseRelationFields = {};
+    for (const modelKey of Object.keys(tables)) {
+        const upstreamFields = tables[modelKey].fields;
+        // Base models always carry `db.timestamps: true` below regardless of
+        // this check; a plugin table only skips createdAt/updatedAt here when it
+        // declares both (so db.timestamps: true, set further down, can stand in
+        // for them) — otherwise they fall through and derive as ordinary scalar
+        // columns instead of being silently dropped.
+        const skipTimestampFields = BASE_MODEL_KEYS.includes(modelKey) ||
+            hasSymmetricTimestamps(upstreamFields);
+        for (const [fieldKey, upstream] of Object.entries(upstreamFields)) {
+            if (TIMESTAMP_FIELDS.has(fieldKey) && skipTimestampFields)
+                continue;
+            if (upstream.references) {
+                const targetModelKey = upstream.references.model;
+                const targetListKey = registry.get(targetModelKey);
+                if (!targetListKey) {
+                    throw new Error(`deriveAuthLists: "${modelKey}.${fieldKey}" references unknown model "${targetModelKey}"`);
+                }
+                if (upstream.references.field === 'id') {
+                    const relationFieldKey = relationshipFieldName(fieldKey);
+                    const reverseName = reverseRelationName(modelKey);
+                    if (reverseRelationFields[targetModelKey]?.[reverseName]) {
+                        // The reverse name is derived from the *model* (pluralized), not
+                        // the field — two id-referencing FKs on the same model targeting
+                        // the same model would collapse onto one reverse field and
+                        // silently produce an ambiguous/incorrect relation. Fail loudly;
+                        // resolve via `REVERSE_RELATION_NAME_OVERRIDES`.
+                        throw new Error(`deriveAuthLists: "${modelKey}" has more than one reference to "${targetModelKey}" ` +
+                            `resolving to the same reverse relation name "${reverseName}" — add an override to ` +
+                            `REVERSE_RELATION_NAME_OVERRIDES in derive-auth-lists.ts`);
+                    }
+                    ;
+                    (foreignKeyFields[modelKey] ??= {})[relationFieldKey] = buildForeignKeyField(fieldKey, upstream, targetListKey, reverseName, claimedFieldsByModel[modelKey]?.has(relationFieldKey) ?? false);
+                    (reverseRelationFields[targetModelKey] ??= {})[reverseName] = relationship({
+                        ref: `${registry.get(modelKey)}.${relationFieldKey}`,
+                        many: true,
+                    });
+                }
+                else {
+                    // relationship() always references the target's `id` column —
+                    // better-auth's own oidc-provider schema (the MCP plugin's OAuth
+                    // tables) references oauthApplication.clientId instead, which a
+                    // relation can't express without pointing Prisma at the wrong
+                    // column. Left as a plain scalar column, same as pre-consolidation
+                    // behavior (issue #992).
+                    ;
+                    (scalarFields[modelKey] ??= {})[fieldKey] = withCredentialAccess(credentialRegistry, modelKey, fieldKey, buildScalarField(fieldKey, upstream, claimedFieldsByModel[modelKey]?.has(fieldKey) ?? false));
+                }
+            }
+            else {
+                ;
+                (scalarFields[modelKey] ??= {})[fieldKey] = withCredentialAccess(credentialRegistry, modelKey, fieldKey, buildScalarField(fieldKey, upstream, claimedFieldsByModel[modelKey]?.has(fieldKey) ?? false));
+            }
+        }
+    }
+    /**
+     * `FIELD_ORDER` only pins the position of fields it names — it is never
+     * the source of truth for *which* fields exist. Every key derived from
+     * `tables[modelKey].fields` above (scalar or foreign-key) is emitted here
+     * regardless of whether `FIELD_ORDER` lists it, appended after the pinned
+     * ones in the order `getAuthTables` returned them, so a field a future
+     * better-auth release adds — the exact drift class this derivation exists
+     * to close (#986) — still reaches the generated schema; it just lands at
+     * the end of the model until `FIELD_ORDER` is updated to place it. A
+     * plugin table has no `FIELD_ORDER` entry at all, so every one of its
+     * fields lands in upstream order.
+     */
+    function assembleFields(modelKey) {
+        const fields = {};
+        const remaining = new Map([
+            ...Object.entries(scalarFields[modelKey] ?? {}),
+            ...Object.entries(foreignKeyFields[modelKey] ?? {}),
+        ]);
+        for (const fieldKey of FIELD_ORDER[modelKey] ?? []) {
+            const field = remaining.get(fieldKey);
+            if (field) {
+                fields[fieldKey] = field;
+                remaining.delete(fieldKey);
+            }
+        }
+        for (const [fieldKey, field] of remaining) {
+            fields[fieldKey] = field;
+        }
+        Object.assign(fields, reverseRelationFields[modelKey]);
+        return fields;
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
     const lists = {
-        [keys.user]: createUserList(models.user, keys, userConfig, accessConfig.user),
-        [keys.session]: createSessionList(models.session, keys, accessConfig.session),
-        [keys.account]: createAccountList(models.account, keys, accessConfig.account),
-        [keys.verification]: createVerificationList(models.verification, accessConfig.verification),
+        [keys.user]: list({
+            fields: { ...assembleFields('user'), ...(userConfig.fields || {}) },
+            db: listDb(models.user, true),
+            access: userConfig.access || accessConfig.user,
+            hooks: userConfig.hooks,
+        }),
+        [keys.session]: list({
+            fields: assembleFields('session'),
+            db: listDb(models.session, true),
+            access: accessConfig.session,
+        }),
+        [keys.account]: list({
+            fields: assembleFields('account'),
+            db: listDb(models.account, true),
+            access: accessConfig.account,
+        }),
+        [keys.verification]: list({
+            fields: assembleFields('verification'),
+            db: listDb(models.verification, true),
+            access: accessConfig.verification,
+        }),
     };
     if (models.rateLimit && keys.rateLimit) {
-        lists[keys.rateLimit] = createRateLimitList(models.rateLimit, accessConfig.rateLimit);
+        lists[keys.rateLimit] = list({
+            fields: assembleFields('rateLimit'),
+            db: listDb(models.rateLimit, false),
+            access: accessConfig.rateLimit,
+        });
+    }
+    const baseKeysPresent = new Set(['user', 'session', 'account', 'verification']);
+    if (models.rateLimit)
+        baseKeysPresent.add('rateLimit');
+    for (const modelKey of Object.keys(tables)) {
+        if (baseKeysPresent.has(modelKey))
+            continue;
+        const listKey = registry.get(modelKey);
+        if (!listKey)
+            continue; // unreachable: buildModelRegistry registers every table key
+        const physicalName = tables[modelKey].modelName;
+        const timestamps = hasSymmetricTimestamps(tables[modelKey].fields);
+        const mapNeeded = listKey !== physicalName;
+        lists[listKey] = list({
+            fields: assembleFields(modelKey),
+            ...(timestamps || mapNeeded
+                ? {
+                    db: {
+                        ...(timestamps ? { timestamps: true } : {}),
+                        ...(mapNeeded ? { map: physicalName } : {}),
+                    },
+                }
+                : {}),
+        });
     }
     return { keys, lists };
 }