fix(plugin-auth): fail an unlink closed, bind explicit links to their user, clear records on user delete

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018zT8d8NpiQ1ExhuNd5TxY6

Author: claude

.changeset/21846-implicit-account-linking-ownership.md

@@ -1,13 +1,23 @@
 ---
-'@objectstack/plugin-auth': patch
+'@objectstack/plugin-auth': minor
 ---
 
-Implicit account linking on external sign-in (OAuth, OIDC, SSO) now requires the library's standard local-ownership condition: an external identity links implicitly to an existing local user only when that local user's email is verified. The platform's own identity provider (`objectstack-cloud`) keeps its documented exception, and a user's unlink is honoured.
+fix(plugin-auth)!: implicit account linking on external sign-in requires the library's standard local-ownership condition; the platform identity provider keeps its documented exception; an unlink is honoured
 
-Clause-②: no
+Clause-②: no (narrowing)
 
-- **Local ownership.** An external sign-in whose email matches an existing local user whose email is not verified is refused with `error=account_not_linked`. That is the same code better-auth's own refusal produces. No link is written and the local user stays unverified. A verified local user links as before.
-- **Platform identity provider.** `objectstack-cloud` still links to an unverified local user, because it seeds the environment owner's row without a mailbox round-trip.
-- **Unlink is honoured.** After a user unlinks a provider, an implicit sign-in through that provider no longer links the identity again, for any provider. An explicit, signed-in link from account settings (`/link-social`) is still allowed and ends the refusal.
-- **Operator override.** `account.accountLinking.requireLocalEmailVerified` is now read as follows. Unset (the default) means the rules above. `true` applies the strict check to every provider, including `objectstack-cloud`. `false` turns off only the local-verification check and keeps the unlink rule.
+<!-- adr-0087: not-required (no-migration-prescription) No authorable key, export or config field is removed or renamed: the change narrows when an external sign-in links implicitly to an existing local user, and nothing an author wrote needs rewriting. The one config key it reads, account.accountLinking.requireLocalEmailVerified, keeps its name and gains an explicit opt-out meaning. -->
+
+**BREAKING for deployments that relied on external sign-in (OAuth, OIDC, SSO) linking implicitly to a local user whose email is not verified.**
+
+**What changed.**
+
+- An external sign-in links implicitly to an existing local user only when that local user's email is verified. Otherwise the sign-in is refused with `error=account_not_linked`, the same code better-auth's own refusal produces. No link is written and the local user stays unverified. A verified local user links as before.
+- The platform's own identity provider (`objectstack-cloud`) keeps its documented exception and still links to an unverified local user, because it seeds the environment owner's row without a mailbox round-trip.
+- After a user unlinks a provider, an implicit sign-in through it no longer links the identity again, for any provider. An explicit, signed-in link from account settings (`/link-social`) is still allowed and ends the refusal. If the unlink cannot be recorded, the unlink itself is refused and the provider stays linked. Deleting a user removes the user's unlink records.
+- `account.accountLinking.requireLocalEmailVerified` now reads as follows. Unset (the default) means the rules above. `true` applies the strict check to every provider, including `objectstack-cloud`. `false` turns off only the local-verification check and keeps the unlink rule.
+
+**What to do after upgrading.**
+
+- A user refused this way signs in with their existing method, then links the provider from account settings, or verifies their email first.
 - To let unverified local users link implicitly again, set `account.accountLinking.requireLocalEmailVerified: false`. Before you do, read the library's warning about account takeover.

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

@@ -33,7 +33,9 @@ import { shouldStampOwnerVerifiedAtCreation } from './walled-owner-operator-stam
 import {
   PLATFORM_IDP_PROVIDER_ID,
   clearUnlinkTombstone,
+  clearUserUnlinkTombstones,
   recordUnlinkTombstone,
+  type LinkingInternalAdapter,
   refuseImplicitAccountLink,
 } from './implicit-account-linking.js';
 import type { IDataEngine } from '@objectstack/core';
@@ -1605,6 +1607,7 @@ export class AuthManager {
         validateUserInfo: async (data: any, ctx: any) =>
           (await refuseImplicitAccountLink(data, ctx, {
             requireLocalEmailVerified: this.implicitLinkRequiresLocalEmailVerified(),
+            resolveAdapter: () => this.linkingAdapter(),
             logInfo: (m, meta) => this.config.logger?.info?.(m, meta),
           })) ?? this.validateAudienceAdmission(data, ctx),
       },
@@ -4496,6 +4499,21 @@ export class AuthManager {
     return (this.config as any)?.account?.accountLinking?.requireLocalEmailVerified !== false;
   }
 
+  /**
+   * better-auth's internal adapter read off the auth instance — the store for
+   * the implicit-linking hooks when a call carries no endpoint context (a
+   * server-side `auth.api.*` call or an internal-adapter write).
+   */
+  private async linkingAdapter(): Promise<LinkingInternalAdapter | undefined> {
+    try {
+      const auth: any = await this.getOrCreateAuth();
+      const context = await auth?.$context;
+      return context?.internalAdapter as LinkingInternalAdapter | undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   /** OAuth providerIds that are OPERATOR-REGISTERED identity authorities (enterprise `oidcProviders`, incl. the cloud platform IdP). */
   private enterpriseOAuthProviderIds(): ReadonlySet<string> {
     const ids = new Set<string>();
@@ -7352,19 +7370,22 @@ export class AuthManager {
     // rule 3). While the record stands an implicit link is refused, so a link
     // that lands here is an explicit one. Failure to clear is functional (the
     // user sees a refusal on their next implicit sign-in and can re-link), so
-    // it is reported at `warn` and never fails the link.
+    // it is reported at `warn` and never fails the link. It runs FIRST, ahead
+    // of the identity-source stamp, so a stamp failure can never leave a
+    // landed link still refused.
+    const resolveLinkingAdapter = () => this.linkingAdapter();
     const clearUnlink = async (account: any, ctx: any) => {
       try {
-        await clearUnlinkTombstone(account, ctx);
+        await clearUnlinkTombstone(account, ctx, resolveLinkingAdapter);
       } catch (e) {
         this.config.logger?.warn?.('[auth] could not clear the unlink record after a link', {
           error: (e as Error)?.message,
         });
       }
     };
     const stamp = async (account: any, ctx: any) => {
-      await this.stampIdentitySource(account, ctx);
       await clearUnlink(account, ctx);
+      await this.stampIdentitySource(account, ctx);
     };
     const hostAccountAfter = (host as any)?.account?.create?.after;
     const after = hostAccountAfter
@@ -7375,26 +7396,52 @@ export class AuthManager {
       : stamp;
 
     // A user's unlink is recorded so the provider cannot re-link implicitly
-    // (implicit-account-linking.ts, rule 3). A record that does not land
-    // leaves the unlink answering 200 while the provider still re-links on
-    // the next sign-in — the protection the user asked for is silently
-    // absent — so the failure is reported at `error`, once per unlink.
-    const hostAccountDeleteAfter = (host as any)?.account?.delete?.after;
-    const accountDeleteAfter = async (account: any, ctx: any) => {
-      const result = hostAccountDeleteAfter ? await hostAccountDeleteAfter(account, ctx) : undefined;
+    // (implicit-account-linking.ts, rule 3) — BEFORE the account row goes, so
+    // that a record which cannot be written aborts the unlink: a throw from a
+    // `delete.before` hook propagates out of better-auth's delete, the unlink
+    // answers an error and the identity stays linked. Fail closed: an unlink
+    // that answered success without its record would leave the provider free
+    // to re-link on the next sign-in. Reported at `error`, once per refusal.
+    // A host `delete.before` runs first; its `false` (abort) is honoured
+    // before anything is recorded.
+    const hostAccountDeleteBefore = (host as any)?.account?.delete?.before;
+    const accountDeleteBefore = async (account: any, ctx: any) => {
+      const result = hostAccountDeleteBefore ? await hostAccountDeleteBefore(account, ctx) : undefined;
+      if (result === false) return false;
       try {
-        await recordUnlinkTombstone(account, ctx);
+        await recordUnlinkTombstone(account, ctx, resolveLinkingAdapter);
       } catch (e) {
         this.audienceLogError(
-          '[auth] unlink record NOT written: the provider can still re-link this account implicitly ' +
-            'on its next sign-in although the unlink answered success. Check the auth store ' +
-            '(sys_verification) is writable, then have the user unlink again.',
+          '[auth] unlink refused: its record could not be written, so the provider stays linked. ' +
+            'Without the record the provider could re-link this account implicitly on its next sign-in. ' +
+            'Check the auth store (sys_verification) is writable, then unlink again.',
           { providerId: account?.providerId, error: (e as Error)?.message },
         );
+        throw e;
       }
       return result;
     };
 
+    // A deleted user leaves no unlink record behind (implicit-account-linking.ts).
+    // A record that outlives its user is inert — a new user never has the
+    // deleted user's id — so a failure is reported at `warn` and never fails
+    // the deletion.
+    const clearUserUnlinks = async (user: any, ctx: any) => {
+      try {
+        await clearUserUnlinkTombstones(user, ctx, resolveLinkingAdapter);
+      } catch (e) {
+        this.config.logger?.warn?.('[auth] could not clear the unlink record of a deleted user', {
+          error: (e as Error)?.message,
+        });
+      }
+    };
+    const hostUserDeleteAfter = (host as any)?.user?.delete?.after;
+    const userDeleteAfter = async (user: any, ctx: any) => {
+      const result = hostUserDeleteAfter ? await hostUserDeleteAfter(user, ctx) : undefined;
+      await clearUserUnlinks(user, ctx);
+      return result;
+    };
+
     // ADR-0093 D9 — default active-org on session create. Without it, a user
     // with memberships logs in with `activeOrganizationId = null`: better-auth
     // org endpoints can't resolve an active org (single-org invite dead-end)
@@ -7600,7 +7647,7 @@ export class AuthManager {
         },
         delete: {
           ...((host as any)?.account?.delete ?? {}),
-          after: accountDeleteAfter,
+          before: accountDeleteBefore,
         },
       },
       user: {
@@ -7610,6 +7657,10 @@ export class AuthManager {
           before: userBefore,
           after: userAfter,
         },
+        delete: {
+          ...((host as any)?.user?.delete ?? {}),
+          after: userDeleteAfter,
+        },
       },
       session: {
         ...((host as any)?.session ?? {}),