auth: better-auth plugin-table credential fields (e.g. oidc-provider clientSecret, two-factor secret) aren't covered by the ADR-0036 read-deny

[borisno2]

Surfaced during review of #1013 (issue #981 / ADR-0036); filed separately rather than widening that PR's scope.

Summary

#981 / ADR-0036 shipped a field-level read deny on the six credential-bearing fields declared by the four base better-auth models: Session.token, Verification.value, Account.password/accessToken/refreshToken/idToken. The deny is implemented in deriveAuthLists (packages/auth/src/config/derive-auth-lists.ts) via a CREDENTIAL_FIELDS map keyed by BaseModelKey ('user' | 'session' | 'account' | 'verification' | 'rateLimit').

The same deriveAuthLists function also derives better-auth plugin tables (e.g. the mcp plugin's oidc-provider schema — oauthApplication, oauthAccessToken, oauthConsent — and any other better-auth plugin's own schema, per ADR-0034) through the identical scalar-field derivation path. Because CREDENTIAL_FIELDS is typed and indexed only by BaseModelKey, withCredentialAccess never matches a plugin-table model key — plugin-table credential fields are derived as plain, fully-readable text() fields, exactly the gap #981 closed for the base models.

Confirmed against better-auth's own plugin schemas (node_modules/better-auth/dist/plugins/*):

• oidc-provider (used by the mcp plugin): oauthApplication.clientSecret, oauthAccessToken.accessToken/refreshToken
• twoFactor(): twoFactor.secret, twoFactor.backupCodes

Why this matters

Plugin tables ship closed by default (ADR-0013/ADR-0034, no access passthrough), but packages/auth/CLAUDE.md documents the supported way for an app to open one: declare the list itself under the same derived key, so the plugin's field-only extend path merges in the app's own access —

lists: {
  OauthAccessToken: list({ access: { operation: { query: () => true } } }),
}

A very plausible feature (an admin screen listing connected OAuth apps, or a "manage your 2FA" page) built this way returns the live accessToken/refreshToken/secret in plaintext through context.db and the admin UI table — the same class of exposure ADR-0036's threat model (session hijack / account takeover / OAuth token replay) describes for the base models.

Why this is a separate issue from #981

#981's issue body and ADR-0036 both explicitly enumerate exactly six fields across the four base models; neither mentions plugin tables. Closing this gap needs its own design pass, since better-auth doesn't expose anything like the returned: false flag issue #981 could lean on for the base account columns (see issue #981's first comment) — plugin schemas carry no such signal, so the fix likely needs either a per-plugin credential-field allowlist (hardcoded, and who maintains it as plugins update) or a different signal entirely.

Suggested directions (not a recommendation — needs a design decision)

1. Extend CREDENTIAL_FIELDS (or an equivalent registry) to cover known plugin tables the stack already has first-class support for (the mcp plugin's oidc-provider tables today), keyed the same way — by better-auth model/field key, surviving modelName/column remaps.
2. A convention-based heuristic — e.g. deny read on any plugin-table scalar field better-auth itself never returns from its own client-facing endpoints — if such a signal can be found or approximated.
3. Give plugin-table authors (or the authPlugin config) a declarative way to mark a field as a credential at the point a plugin is registered, so the stack doesn't need to hardcode knowledge of every better-auth plugin's schema.

Verification performed

• Read derive-auth-lists.ts's CREDENTIAL_FIELDS/withCredentialAccess/BaseModelKey and confirmed the type/lookup only ever matches the five base model keys.
• Read the plugin-table derivation loop in the same file and confirmed it derives plugin-table scalar fields through the exact same buildScalarField/withCredentialAccess call as base models — so the fix, if pursued, plugs into an already-shared path rather than needing a new one.
• Read better-auth's own oidc-provider and two-factor plugin schema source to confirm the named fields exist and are plain string columns with no returned: false (or equivalent) flag.

Related

• auth: derived auth lists store live credentials in plain text() fields with no redaction and no field-level access seam #981 — the base-model deny this issue generalizes (closed by fix(auth): ship plugin-derived credential fields read-denied #1013)
• ADR-0036 — the decision record this issue's scope sits just outside of
• ADR-0034 — plugin tables derive through the same registry as base models (the mechanism this gap rides on)

[borisno2]

This was generated by AI during triage.

Verification

The gap is confirmed by reading the derivation: CREDENTIAL_FIELDS is indexed as Partial<Record<BaseModelKey, …>> while withCredentialAccess is called identically for plugin-table fields (both the plain-scalar branch and the FK-to-non-id branch), so the lookup silently misses and every plugin-table column derives fully readable. The existing credential tests assert only the six base fields.

Three corrections to the issue body, verified against the versions this repo actually pins (better-auth@1.7.1, @better-auth/mcp@1.7.1, @better-auth/oauth-provider@1.7.1):

1. The named fields don't exist under these versions. In 1.7 the oidc-provider schema moved out to @better-auth/oauth-provider, and the models/fields are oauthClient.clientSecret, oauthAccessToken.token, oauthRefreshToken.token — not oauthApplication.clientSecret / oauthAccessToken.accessToken/refreshToken. (Also present: oauthConsent, oauthClientAssertion, oauthResource, oauthClientResource.) That a rename landed inside one minor release is itself the argument against a hardcoded-only registry.
2. returned: false does exist in plugin schemas — just not usefully. twoFactor.secret and twoFactor.backupCodes carry it, but so does twoFactor.userId, which is an identifier. The oauth-provider tables carry it nowhere, and better-auth strips the base account credentials via an explicit destructure in its own output filter rather than the flag. So it is both noisy and incomplete as a signal.
3. Severity under 1.7 defaults is inverted from the body's emphasis. oauth-provider defaults to storeTokens: "hashed" and storeClientSecret: "hashed" ("encrypted" when disableJwtPlugin), so the OAuth columns leak hashes. twoFactor.secret/backupCodes are stored encrypted — reversible with the app secret, and the closest thing here to a live credential.

Also checked: no better-auth plugin in 1.7.1 adds a credential column onto a base model (admin adds banned/role/impersonatedBy, anonymous isAnonymous, and phone-number/username/two-factor/last-login-method likewise add identifiers), so no base-model seed entries are needed.

Agent Brief

Category: bug
Summary: Generalise the ADR-0036 credential read-deny from the base auth models to better-auth plugin tables, and give apps a declarative way to mark credential fields the stack doesn't know about

Current behavior:
deriveAuthLists denies field-level read on six credential fields across the four base better-auth models. The credential registry it consults is typed and indexed by the five base model keys only, so the same deny never applies to a field on a better-auth plugin table — even though plugin-table fields are derived through the identical code path. An application that opens a plugin-derived list the documented way (declaring the list itself under the derived key, so the auth plugin's field-only extend merges in) gets every credential column on that table back in full.

Desired behavior:
The deny applies to credential-bearing fields on plugin tables exactly as it does on base models: keyed by better-auth's own model and field keys, so it survives modelName and column remapping. The stack seeds the set for the better-auth plugins it has first-class support for, and an application can mark additional fields on plugins the stack has never seen.

Key interfaces:

• The credential registry currently keyed by the base-model-key union should be widened to accept any better-auth model key. The function that applies the deny already takes a string model key — only the index type narrows it, so this is the bulk of the fix.
• Seed entries to add, using better-auth 1.7 names: oauthClient.clientSecret, oauthAccessToken.token, oauthRefreshToken.token, twoFactor.secret, twoFactor.backupCodes.
• A new authPlugin option — credentialFields, shaped Record<string, string[]>, keyed by better-auth model key (not the derived list key), naming better-auth field keys (not mapped column names). It is strictly additive: it can mark further fields as credentials, and can never unmark a stack-seeded one. It carries TSDoc as a public config surface.
• The deny must be applied uniformly regardless of how the value is stored at rest. Do not condition it on better-auth's storeTokens/storeClientSecret modes, and do not derive it from returned: false.
• Derivation must throw when a registry or config entry names a field that is absent from a model that is being derived. An entry naming a model that isn't derived at all (a plugin the app doesn't use) stays a silent no-op.

Acceptance criteria:

• With the mcp/oauth-provider better-auth plugin registered, the derived lists for oauthClient, oauthAccessToken and oauthRefreshToken each carry a field-level read access function returning false on clientSecret, token and token respectively
• With twoFactor() registered, the derived two-factor list denies read on secret and backupCodes
• Identifying fields on those same tables (e.g. oauthClient.name/uri/clientId, oauthAccessToken.scopes/expiresAt, twoFactor.verified) remain access-less — twoFactor.userId stays open despite carrying returned: false upstream
• The six existing base-model denies are unchanged, and their existing tests still pass
• The deny survives a plugin-table modelName remap and a credential field's column remap, asserted the same way the base-model remap test does
• authPlugin({ credentialFields: … }) marks an additional field on a synthetic plugin's table as read-denied
• credentialFields cannot unmark a seeded field — an entry that omits or empties a seeded model's field list leaves the seeded deny standing
• Derivation throws, naming the model and field, when an entry names a missing field on a model that is derived; an entry for a model that isn't derived is a no-op
• An application that declares a plugin-derived list and redeclares a credential field key under it still gets the derived, read-denied field — asserted explicitly, since this currently holds only as a side effect of the extend merge order
• Coverage assertions run against real twoFactor() and mcp plugin instances; the credentialFields and throw-on-missing-field paths run against a synthetic plugin schema
• ADR-0036 is amended to state the rule over plugin tables, with a cross-reference added from ADR-0034
• The auth package's agent doc no longer presents the credential set as a closed list of six base fields; the docs-site auth/config reference documents credentialFields
• A minor changeset names each newly denied field explicitly (oauthClient.clientSecret, oauthAccessToken.token, oauthRefreshToken.token, twoFactor.secret, twoFactor.backupCodes), following the ADR-0036 precedent that the version number won't signal the behaviour change on its own

Out of scope:

• The admin UI's default-column curation, which excludes a hardcoded set of field names rather than consulting field access — a real defect, tracked separately
• Any heuristic that infers credential-ness from better-auth's returned: false flag
• Any seam for re-opening a denied field; sudo() remains the documented path, per ADR-0036's deferral
• Any change to the six base-model denies, or to which fields they cover
• Adding operation-level access passthrough for plugin tables (ADR-0034 deliberately has none)

---

Generated by Claude Code