eq null never matches absent optional fields — breaks @better-auth/oauth-provider refresh-token rotation (every refresh grant returns 400 invalid_grant)

Versions

• @convex-dev/better-auth 0.12.4 (bug also present in 0.12.5 and on main @ c628916)
• better-auth / @better-auth/oauth-provider 1.6.22 (same behavior in 1.6.23 / main)
• Reproduced end-to-end against a dev Convex deployment on 2026-07-03 (local component install, local: { schema })

Summary

The adapter's where-filter implements eq as strict equality:

https://github.com/get-convex/better-auth/blob/c628916b451a6b4cff0f5464f134475464b1a6da/src/client/adapter-utils.ts#L344-L347

case undefined:
case "eq": {
  return value === w.value;
}

For a Convex document that has never had the field written, value is undefined, so a { operator: "eq", value: null } where never matches (undefined === null → false).

Every first-party better-auth adapter treats "unset optional field" as matching eq null:

• SQL adapters (Kysely/Drizzle/Prisma): an optional column that was never written is NULL, and the generated WHERE revoked IS NULL matches.
• MongoDB: { revoked: null } matches documents where the field is missing as well as explicitly null.

So plugins are written against a de-facto contract of "never-set == null", and the Convex adapter is the only one that diverges. That divergence is now user-visible:

Concrete breakage: oauth-provider refresh rotation

@better-auth/oauth-provider creates oauthRefreshToken rows without a revoked key (newRow in createRefreshToken), then guards rotation with a compare-and-swap:

https://github.com/better-auth/better-auth/blob/7f510cef533d432cc2ea8c23126a8db7617ede2a/packages/oauth-provider/src/token.ts#L385-L395

const won = await ctx.context.adapter.incrementOne<{ id: string }>({
  model: "oauthRefreshToken",
  where: [
    { field: "id", value: originalRefresh.id },
    { field: "revoked", operator: "eq", value: null },
  ],
  increment: {},
  set: { revoked: new Date(iat * 1000) },
});
if (!won) throw new APIError("BAD_REQUEST", { error: "invalid_grant", ... });

This adapter has no native incrementOne, so @better-auth/core's fallback runs findMany({ where, limit: 1 }) with that where (dist/db/adapter/factory.mjs). The revoked eq null leg goes through the strict-equality filter above, the freshly created row (no revoked field) never matches, findMany returns [], the fallback returns null, and the plugin throws.

Net effect: with this adapter, every single refresh_token grant fails with 400 invalid_grant / "invalid refresh token" — offline_access is unusable.

Repro

Adapter-level (minimal)

Inside any Convex function with the component adapter:

const adapter = /* betterAuthComponent adapter */;
const row = await adapter.create({
  model: "oauthRefreshToken",
  data: { token: "t", clientId: "c", userId: "u", scopes: ["openid"],
          createdAt: new Date(), expiresAt: new Date(Date.now() + 86400_000) },
  // note: no `revoked` key — exactly what the oauth-provider plugin writes
});

const found = await adapter.findMany({
  model: "oauthRefreshToken",
  where: [
    { field: "id", value: row.id },
    { field: "revoked", operator: "eq", value: null },
  ],
  limit: 1,
});
// expected (per SQL/Mongo adapter behavior): [row]
// actual: []

End-to-end

1. Configure @better-auth/oauth-provider with this component.
2. Run authorize + PKCE, exchange the code at /oauth2/token with offline_access → get refresh_token. ✅
3. POST grant_type=refresh_token → 400 invalid_grant "invalid refresh token" on the very first refresh. ❌ (expected: 200 with a rotated pair)

Suggested fixes

1. Null/undefined coalescing for eq/ne null in the where filter — e.g.

   case "eq":
     return w.value === null
       ? value === null || value === undefined
       : value === w.value;

   (and the mirrored change for ne). This matches the semantics of every other first-party adapter. Note the index-prefilter path (indexEqFields → q.eq(field, value)) has the same missing-vs-null caveat if a null-valued eq where is ever pushed into an index range.

2. A native incrementOne on the adapter would additionally make the oauth-provider's rotation CAS genuinely atomic and skip core's findMany+updateMany fallback (two round-trips through the component). Convex mutations are transactional, so read-check-patch inside one mutation is already a correct CAS — it just needs the null-vs-undefined comparison handled there too.

Either of (1) alone fixes the refresh grant; (2) is the better long-term shape.

Workaround (for anyone hitting this today)

Wrap the component adapter so oauthRefreshToken rows are created with an explicit revoked: null:

const adapterWithExplicitRefreshRevocation = (ctx: GenericCtx<DataModel>) => {
  const factory = authComponent.adapter(ctx);
  return ((options) => {
    const adapter = factory(options);
    const create: typeof adapter.create = async (args) => {
      if (args.model !== "oauthRefreshToken" || "revoked" in args.data) return adapter.create(args);
      return adapter.create({ ...args, data: { ...args.data, revoked: null } });
    };
    return { ...adapter, create };
  }) satisfies ReturnType<typeof authComponent.adapter>;
};
// betterAuth({ database: adapterWithExplicitRefreshRevocation(ctx), ... })

I'm also filing a cross-issue on better-auth suggesting the plugin write revoked: null explicitly at creation as defense-in-depth for document-store adapters (link to follow in a comment), but the adapter-side semantics seem like the root divergence — any plugin using the same "create without field, later match eq null" pattern (device-authorization does this with userId) breaks the same way on this adapter only.