fix(plugin-auth): the issuer is the provider's to declare — Google links stop resolving under a synthesized one (#4552)

better-auth 1.7 keys every account on `(issuer, providerAccountId)`, and
`resolveOAuthAccountKey` takes the issuer the PROVIDER declares, falling back to
the synthetic `local:oauth:<id>` only for a provider that declares none. The
boot backfill synthesized that value for EVERY social provider, so a Google link
was stamped `local:oauth:google` while sign-in looked it up under
`https://accounts.google.com`.

The row went invisible: `findAccountOwnerByKey` missed it, the callback fell
through to "link this provider", and the insert collided with that very row on
the `(provider_id, account_id)` unique index — reaching the user as
`?error=unable_to_link_account` on an account that had signed in with Google
before. Seven of better-auth's built-in providers declare their own issuer
(google, apple, facebook, cognito, line, paybin, entra), so all seven were
mis-stamped; google is the one wired on the hosted control plane.

- Read the issuer off the providers better-auth INSTANTIATED
  (`authContext.socialProviders`) instead of deriving it from configured ids.
  A provider whose `accountIssuer` is a function resolves it per login (Entra
  reads the tenant `iss` off the profile) — that stays underivable at boot and
  is reported, not guessed.
- Repair, not just stamp: correcting the derivation does nothing for a database
  already stamped wrong, so the pass re-stamps rows carrying the synthetic
  issuer for a provider that declares a real one. Only that one
  wrong-by-construction value is rewritten.
- New parity gate gets its assertion from better-auth's own factory list, so a
  bump that gives another provider an issuer of its own turns red instead of
  silently mis-stamping that provider's users on the next boot. Verified to
  catch this defect: reverting the derivation reddens it, naming all six
  fixed-issuer providers.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

packages/plugins/plugin-auth/src/account-issuer-parity.test.ts

@@ -0,0 +1,163 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+  socialProviderList,
+  socialProviders as socialProviderFactories,
+} from '@better-auth/core/social-providers';
+import { backfillAccountIssuer, oauthIssuerFor } from './backfill-account-issuer.js';
+
+/**
+ * Account-issuer parity gate.
+ *
+ * better-auth 1.7 keys every account on `(issuer, providerAccountId)`, and the
+ * issuer is the PROVIDER's to declare: `resolveOAuthAccountKey` takes
+ * `provider.accountIssuer` when there is one and synthesizes
+ * `local:oauth:<id>` only when there is not. A boot-time backfill that stamps a
+ * different value than sign-in looks the row up under does not merely fail to
+ * help — it hides the account and parks it on the `(provider_id, account_id)`
+ * unique slot the correct row needs, which is how a working Google login turned
+ * into `?error=unable_to_link_account`.
+ *
+ * So this gate asserts the two agree, provider by provider, against better-auth's
+ * OWN factory list. A dependency bump that gives another provider an issuer of
+ * its own (or takes one away) turns this red instead of silently mis-stamping
+ * that provider's users on the next boot.
+ */
+
+/** Enough options to construct every factory; unused keys are ignored. */
+const PROBE_OPTIONS = {
+  clientId: 'probe-client-id',
+  clientSecret: 'probe-client-secret',
+  tenantId: 'probe-tenant',
+  region: 'us-east-1',
+  userPoolId: 'pool-1',
+  domain: 'probe.example.com',
+  issuer: 'https://probe.example.com',
+} as const;
+
+interface ProbedProvider {
+  id: string;
+  accountIssuer: unknown;
+}
+
+function instantiateAll(): ProbedProvider[] {
+  const probed: ProbedProvider[] = [];
+  const broken: string[] = [];
+  for (const id of socialProviderList) {
+    const factory = (socialProviderFactories as any)[id];
+    try {
+      const provider = factory(PROBE_OPTIONS as any);
+      probed.push({ id: provider.id, accountIssuer: provider.accountIssuer });
+    } catch (e) {
+      broken.push(`${id}: ${(e as Error)?.message}`);
+    }
+  }
+  // A factory this probe can no longer construct is a provider the gate stops
+  // covering — fail loudly rather than shrink the checked set in silence.
+  expect(broken, 'social provider factories the parity probe could not construct').toEqual([]);
+  return probed;
+}
+
+/** What better-auth will key an account by, per `resolveOAuthAccountKey`. */
+function issuerBetterAuthWillUse(provider: ProbedProvider): string | 'per-login' {
+  const declared = provider.accountIssuer;
+  if (declared === undefined) return oauthIssuerFor(provider.id);
+  if (typeof declared === 'string') return declared;
+  return 'per-login';
+}
+
+/** Minimal ObjectQL stand-in — one account row, `update` patches in place. */
+function makeQl(row: Record<string, any>) {
+  const tables: Record<string, any[]> = { sys_account: [row] };
+  return {
+    tables,
+    update: async (object: string, data: any) => {
+      const target = (tables[object] ?? []).find((r) => r.id === data.id);
+      if (target) Object.assign(target, data);
+      return target;
+    },
+    find: async (object: string, query: any) => {
+      const where = query?.where ?? {};
+      return (tables[object] ?? []).filter((r) =>
+        Object.entries(where).every(([field, value]) =>
+          value === null ? r[field] == null : r[field] === value,
+        ),
+      );
+    },
+  };
+}
+
+describe('account issuer parity — the backfill stamps what sign-in looks up', () => {
+  it('covers every social provider better-auth ships', () => {
+    const probed = instantiateAll();
+    expect(probed.length).toBe(socialProviderList.length);
+  });
+
+  it('agrees with better-auth on the issuer for every provider that has a fixed one', async () => {
+    const mismatches: Array<{ provider: string; betterAuth: string; backfill: string | null }> = [];
+
+    for (const provider of instantiateAll()) {
+      const expected = issuerBetterAuthWillUse(provider);
+      if (expected === 'per-login') continue;
+
+      const ql = makeQl({
+        id: 'a1',
+        provider_id: provider.id,
+        account_id: 'subject-1',
+        issuer: null,
+      });
+      await backfillAccountIssuer(ql, { socialProviders: [provider] });
+
+      const stamped = ql.tables.sys_account[0].issuer ?? null;
+      if (stamped !== expected) {
+        mismatches.push({ provider: provider.id, betterAuth: expected, backfill: stamped });
+      }
+    }
+
+    expect(mismatches, 'providers whose backfilled issuer differs from the one sign-in resolves').toEqual([]);
+  });
+
+  it('never invents an issuer for a provider that resolves one per login', async () => {
+    for (const provider of instantiateAll()) {
+      if (issuerBetterAuthWillUse(provider) !== 'per-login') continue;
+
+      const ql = makeQl({
+        id: 'a1',
+        provider_id: provider.id,
+        account_id: 'subject-1',
+        issuer: null,
+      });
+      const res = await backfillAccountIssuer(ql, { socialProviders: [provider] });
+
+      expect(ql.tables.sys_account[0].issuer, `${provider.id} must stay unstamped`).toBeNull();
+      expect(res.unresolved).toEqual([{ providerId: provider.id, count: 1 }]);
+    }
+  });
+
+  it('repairs a synthetic stamp on every provider that declares a real issuer', async () => {
+    const declaring = instantiateAll().filter((p) => typeof p.accountIssuer === 'string');
+    // Guards the guard: if better-auth ever ships none of these, the repair
+    // case above proves nothing and this gate has quietly stopped testing.
+    expect(declaring.length).toBeGreaterThan(0);
+
+    for (const provider of declaring) {
+      const ql = makeQl({
+        id: 'a1',
+        provider_id: provider.id,
+        account_id: 'subject-1',
+        issuer: oauthIssuerFor(provider.id),
+      });
+      const res = await backfillAccountIssuer(ql, { socialProviders: [provider] });
+
+      expect(res.repaired, `${provider.id} mis-stamp should be repaired`).toBe(1);
+      expect(ql.tables.sys_account[0].issuer).toBe(provider.accountIssuer);
+    }
+  });
+
+  it('google — the provider this defect shipped on — resolves to its real issuer', () => {
+    const google = (socialProviderFactories as any).google(PROBE_OPTIONS as any);
+    expect(google.accountIssuer).toBe('https://accounts.google.com');
+    expect(oauthIssuerFor('google')).toBe('local:oauth:google');
+  });
+});

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -27,6 +27,7 @@ import {
   type AuthManagerOptions,
 } from './auth-manager.js';
 import { ensureDefaultOrganization } from './ensure-default-organization.js';
+import type { ResolvedSocialProvider } from './backfill-account-issuer.js';
 import { createTenancyService, type TenancyService } from './tenancy-service.js';
 import { backfillMemberships, type MembershipPolicy } from './reconcile-membership.js';
 import {
@@ -261,6 +262,35 @@ export class AuthPlugin implements Plugin {
     }
   }
 
+  /**
+   * The social providers better-auth built for this runtime, straight off its
+   * own context — each one carrying the `accountIssuer` it will key its
+   * accounts by. Read rather than reconstructed: reconstructing it from the
+   * configured ids is exactly the guess that mis-stamped Google links.
+   *
+   * Returns `undefined` when the instance cannot be reached (auth not built
+   * yet, or a host-supplied instance that exposes no context) — the backfill
+   * then falls back to the id-derived issuers and reports what it cannot
+   * resolve, which is the pre-existing behaviour, not a new failure.
+   */
+  private async resolveInstantiatedSocialProviders(
+    ctx: PluginContext,
+  ): Promise<ResolvedSocialProvider[] | undefined> {
+    try {
+      const auth = await this.authManager?.getAuthInstance();
+      const context = await (auth as any)?.$context;
+      const providers = context?.socialProviders;
+      if (!Array.isArray(providers)) return undefined;
+      return providers.filter((p: any) => typeof p?.id === 'string' && p.id);
+    } catch (e) {
+      ctx.logger.warn?.(
+        '[auth] could not read better-auth\'s instantiated social providers — account issuers fall back to the id-derived values',
+        { error: (e as Error)?.message },
+      );
+      return undefined;
+    }
+  }
+
   async init(ctx: PluginContext): Promise<void> {
     ctx.logger.info('Initializing Auth Plugin...');
 
@@ -684,14 +714,21 @@ export class AuthPlugin implements Plugin {
     // better-auth 1.7 resolves every account by (issuer, providerAccountId).
     // Rows written before the upgrade have no issuer and are therefore
     // invisible to sign-in, so stamp them once at boot. Idempotent: a database
-    // whose rows already carry an issuer costs one empty query.
+    // whose rows already carry the right issuer costs one empty query.
+    //
+    // The providers are handed over as better-auth INSTANTIATED them, because
+    // the issuer is theirs to declare and only they know it — Google names
+    // `https://accounts.google.com`, GitHub names nothing and takes the
+    // synthetic fallback. Deriving it from the configured ids instead is what
+    // stamped Google links with a value sign-in never looks them up under.
     ctx.hook('kernel:ready', async () => {
       try {
         const ql = ctx.getService<IDataEngine>('objectql');
         if (!ql) return;
         const { backfillAccountIssuer } = await import('./backfill-account-issuer.js');
         await backfillAccountIssuer(ql, {
           logger: ctx.logger,
+          socialProviders: await this.resolveInstantiatedSocialProviders(ctx),
           socialProviderIds: Object.keys(this.configuredSocialProviders ?? {}),
           oidcProviderIssuers: Object.fromEntries(
             (this.options.oidcProviders ?? [])

packages/plugins/plugin-auth/src/backfill-account-issuer.test.ts

@@ -48,7 +48,7 @@ describe('backfillAccountIssuer (better-auth 1.7 account identity)', () => {
     expect(CREDENTIAL_ISSUER).toBe('local:credential');
   });
 
-  it('stamps configured social providers with the synthetic local:oauth issuer', async () => {
+  it('stamps a provider that declares no issuer with the synthetic local:oauth one', async () => {
     const ql = makeQl({
       sys_account: [{ id: 'a1', provider_id: 'github', account_id: '4242', issuer: null }],
     });
@@ -60,6 +60,36 @@ describe('backfillAccountIssuer (better-auth 1.7 account identity)', () => {
     expect(oauthIssuerFor('github')).toBe('local:oauth:github');
   });
 
+  it('stamps a provider that declares its own issuer with THAT issuer', async () => {
+    const ql = makeQl({
+      sys_account: [{ id: 'a1', provider_id: 'google', account_id: 'sub-1', issuer: null }],
+    });
+
+    const res = await backfillAccountIssuer(ql, {
+      socialProviders: [{ id: 'google', accountIssuer: 'https://accounts.google.com' }],
+    });
+
+    expect(res.stamped).toBe(1);
+    expect(ql.tables.sys_account[0].issuer).toBe('https://accounts.google.com');
+  });
+
+  it('leaves a per-login issuer underivable rather than synthesizing one', async () => {
+    // Microsoft Entra reads the tenant's `iss` off each login's profile, so
+    // there is no boot-time answer — and a guess would be the whole bug.
+    const ql = makeQl({
+      sys_account: [{ id: 'a1', provider_id: 'microsoft', account_id: 'oid-1', issuer: null }],
+    });
+
+    const res = await backfillAccountIssuer(ql, {
+      socialProviders: [{ id: 'microsoft', accountIssuer: ({ profile }: any) => profile.iss }],
+      socialProviderIds: ['microsoft'],
+    });
+
+    expect(res).toMatchObject({ scanned: 1, stamped: 0, repaired: 0 });
+    expect(res.unresolved).toEqual([{ providerId: 'microsoft', count: 1 }]);
+    expect(ql.tables.sys_account[0].issuer).toBeNull();
+  });
+
   it('uses the registered SSO provider\'s real issuer for federated accounts', async () => {
     const ql = makeQl({
       sys_account: [{ id: 'a1', provider_id: 'okta-prod', account_id: '00u1', issuer: null }],
@@ -145,3 +175,96 @@ describe('backfillAccountIssuer (better-auth 1.7 account identity)', () => {
     await expect(backfillAccountIssuer({} as any)).resolves.toMatchObject({ scanned: 0, stamped: 0 });
   });
 });
+
+/**
+ * The shipped defect: an earlier pass stamped `local:oauth:google` on links
+ * better-auth resolves under `https://accounts.google.com`. The row went
+ * invisible at sign-in, the callback fell through to "link this provider", and
+ * the insert hit the `(provider_id, account_id)` unique index the invisible row
+ * was holding — `?error=unable_to_link_account`.
+ */
+describe('backfillAccountIssuer — repairing a mis-stamped synthetic issuer', () => {
+  it('re-stamps a synthetic issuer with the one its provider declares', async () => {
+    const log = logger();
+    const ql = makeQl({
+      sys_account: [
+        { id: 'a1', provider_id: 'google', account_id: 'sub-1', issuer: 'local:oauth:google' },
+      ],
+    });
+
+    const res = await backfillAccountIssuer(ql, {
+      logger: log,
+      socialProviders: [{ id: 'google', accountIssuer: 'https://accounts.google.com' }],
+    });
+
+    expect(res).toMatchObject({ scanned: 1, stamped: 0, repaired: 1, unresolved: [] });
+    expect(ql.tables.sys_account[0].issuer).toBe('https://accounts.google.com');
+    expect(log.info).toHaveBeenCalled();
+  });
+
+  it('is idempotent — the repaired row is not touched again', async () => {
+    const ql = makeQl({
+      sys_account: [
+        { id: 'a1', provider_id: 'google', account_id: 'sub-1', issuer: 'local:oauth:google' },
+      ],
+    });
+    const opts = { socialProviders: [{ id: 'google', accountIssuer: 'https://accounts.google.com' }] };
+
+    await backfillAccountIssuer(ql, opts);
+    ql.update.mockClear();
+    const second = await backfillAccountIssuer(ql, opts);
+
+    expect(second).toMatchObject({ scanned: 0, repaired: 0 });
+    expect(ql.update).not.toHaveBeenCalled();
+  });
+
+  it('leaves the synthetic issuer alone when it IS what the provider mints', async () => {
+    const ql = makeQl({
+      sys_account: [
+        { id: 'a1', provider_id: 'github', account_id: '4242', issuer: 'local:oauth:github' },
+      ],
+    });
+
+    const res = await backfillAccountIssuer(ql, { socialProviders: [{ id: 'github' }] });
+
+    expect(res).toMatchObject({ scanned: 0, stamped: 0, repaired: 0 });
+    expect(ql.tables.sys_account[0].issuer).toBe('local:oauth:github');
+  });
+
+  it('rewrites ONLY the synthetic value — a row already holding a real issuer stands', async () => {
+    const ql = makeQl({
+      sys_account: [
+        { id: 'a1', provider_id: 'google', account_id: 'sub-1', issuer: 'https://accounts.google.com' },
+        { id: 'a2', provider_id: 'google', account_id: 'sub-2', issuer: 'https://some-other.example' },
+      ],
+    });
+
+    const res = await backfillAccountIssuer(ql, {
+      socialProviders: [{ id: 'google', accountIssuer: 'https://accounts.google.com' }],
+    });
+
+    expect(res).toMatchObject({ scanned: 0, repaired: 0 });
+    expect(ql.tables.sys_account[1].issuer).toBe('https://some-other.example');
+  });
+
+  it('reports a repair the database refuses instead of counting it', async () => {
+    // A duplicate row can already occupy (issuer, account_id) on a deployment
+    // that acquired one before the unique index existed.
+    const log = logger();
+    const ql = makeQl({
+      sys_account: [
+        { id: 'a1', provider_id: 'google', account_id: 'sub-1', issuer: 'local:oauth:google' },
+      ],
+    });
+    ql.update.mockRejectedValueOnce(new Error('unique constraint'));
+
+    const res = await backfillAccountIssuer(ql, {
+      logger: log,
+      socialProviders: [{ id: 'google', accountIssuer: 'https://accounts.google.com' }],
+    });
+
+    expect(res).toMatchObject({ scanned: 1, repaired: 0 });
+    expect(res.unresolved).toEqual([{ providerId: 'google', count: 1 }]);
+    expect(log.warn).toHaveBeenCalled();
+  });
+});