Auth adapter: a `fields` remap colliding with another field's default key silently misresolves

[borisno2]

Context

Found during review of #1543 (test coverage for #1241's codecFor/mapped-increment gap).

The gap

packages/auth/src/adapter/index.ts's resolveField/isBigInt/toColumn/toFieldKey all resolve a name via better-auth's getDefaultFieldName (from @better-auth/core/db/adapter), which tries a direct hit first against the model's own field keys before falling back to a reverse lookup by fieldName:

let f = schema[model]?.fields[field];
if (!f) {
  const result = Object.entries(schema[model]!.fields!).find(([_, f]) => f.fieldName === field);
  ...
}

This makes the resolution ambiguous when an app's authPlugin({ <model>: { fields: {...} } }) remap sends one field's column to a string that happens to equal a different field's own (unmapped) default key in the same model — e.g.:

authPlugin({
  rateLimit: {
    enabled: true,
    storage: 'database',
    // lastRequest's physical column is now "count" — which collides with
    // the rateLimit model's own unmapped `count` field key.
    fields: { count: 'total_count', lastRequest: 'count' },
  },
})

Here, the physical column "count" hits schema[model].fields['count'] directly and resolves to the original count field instead of lastRequest. resolveField/isBigInt then check count's (non-bigint) attributes instead of lastRequest's, so incrementOne/outward silently skip the BigInt widening/narrowing a real int8 column needs — wrong values or precision loss on a remapped bigint column, with no error raised.

What to do

Pick one:

• (a) Add a generate-time check in packages/auth/src/config/derive-auth-lists.ts that rejects a fields remap whose target string equals another field's own default key in the same model, naming the model and the colliding fields.
• (b) In packages/auth/src/adapter/index.ts, avoid re-deriving the field key via getDefaultFieldName's ambiguous direct-hit-first logic — carry the field key resolved once (e.g. from sqlWhere's own resolution path) forward explicitly instead of re-resolving from a bare column string.

Acceptance criteria

• A fields remap that creates this kind of collision either fails fast at generate/config time with a clear error naming the two fields, or resolves correctly end-to-end
• A regression test drives incrementOne (or another read/write path) against a rateLimit-like model configured with a colliding remap, and asserts the correct field's attributes (in particular bigint) are used

[borisno2]

This was generated by AI during triage.

Agent Brief

Category: bug
Summary: Refuse an auth fields remap whose target collides with another field's default key in the same model, at generate time, with an error naming both fields.

Decision recorded 2026-09-14: option (a), the generate-time refusal. The issue offered (a) fail fast or (b) stop re-deriving the field key from a bare column string. (a) is chosen because the colliding configuration is pathological — deliberately mapping one field's physical column onto another field's own key — and banning it outright is cheaper and safer than teaching an ambiguous resolution to disambiguate. (b) would touch four functions on a correctness-sensitive resolution path to rescue a config nobody should write.

Note this decision is about which fix to make now, not a judgement that better-auth's direct-hit-first lookup is fine. If you find the ambiguity biting somewhere a remap collision cannot explain, stop and report it rather than widening this fix.

Current behavior

The adapter's toFieldKey resolves a physical column back to a field key through better-auth's getDefaultFieldName, which tries a direct hit against the model's own field keys first and only then falls back to a reverse lookup by fieldName. When a fields remap sends one field's column to a string equal to a different field's unmapped key in the same model, the direct hit wins and resolves to the wrong field.

Concretely, with fields: { count: 'total_count', lastRequest: 'count' } on a rateLimit-like model, the physical column "count" resolves to the original count field rather than to lastRequest. Field-attribute reads — in particular the bigint flag that drives BigInt widening and narrowing on an int8 column — then consult the wrong field's attributes, so the widening is silently skipped. The result is wrong values or precision loss on a remapped bigint column, with no error raised anywhere.

Nothing currently rejects such a remap. The existing self-collision refusal in the auth list derivation is a different case (a relation field key colliding with its own foreign-key column, #1236) and does not catch this.

Desired behavior

Deriving the auth lists refuses a configuration in which any model's fields remap target string equals another field's own default key within that same model. The refusal names the model, the field carrying the remap, its target string, and the field whose default key it collides with, so the fix is obvious from the message alone.

A remap target that collides with nothing is unaffected, including one that renames a field to a string no field uses. A field remapped to its own key is not a collision.

Key interfaces

• The auth list derivation, where a model's fields remap is read — this is where the refusal belongs, so it fires during pnpm generate rather than at request time. Match the shape and tone of the refusals the generator already raises (name the list/model, the entry, and the fix).
• The adapter's toFieldKey / toColumn / field-attribute lookups — unchanged by this fix. Once the colliding config cannot exist, their resolution is unambiguous for every config that survives derivation.

Acceptance criteria

• A fields remap whose target equals another field's own default key in the same model fails generation with an error naming the model, both fields, and the colliding string
• A non-colliding remap still generates, including one renaming a field to an unused string
• A field remapped to its own key is not treated as a collision
• A regression test drives a read/write path — incrementOne is the one the issue names — against a rateLimit-like model with a colliding remap, and demonstrates the failure is now prevented rather than silently misresolved
• A test covers the bigint case specifically, since skipped BigInt widening on an int8 column is the concrete harm and the reason this is not merely cosmetic
• The existing self-collision refusal (A to-one relation and its foreign key collide on one alias, breaking nested to-one includes #1236) is unaffected and its tests still pass
• A changeset is created via the pr-changeset skill

Out of scope

• Refactoring the adapter to carry a once-resolved field key forward. That is option (b), deliberately not chosen here.
• Changing better-auth's getDefaultFieldName behaviour or working around it in the adapter.
• Collisions across different models, which cannot arise — resolution is per model.

Context

Found during review of #1543 (test coverage for #1241's codecFor/mapped-increment gap).

---

Generated by Claude Code