fix(plugin-auth): isolate optional better-auth plugin init failures from core auth (#3087)

Follow-up to #3085. In the 15.1.0 incident, @better-auth/oauth-provider
threw "Cannot set properties of undefined (setting 'modelName')" during
plugin construction, and because the better-auth instance is built
lazily per request, that single optional federation feature turned EVERY
auth endpoint (sign-up / sign-in / get-session) into a 500 — a blast
radius wildly out of proportion to the feature.

AuthManager.buildPluginList now constructs plugins in two explicit tiers:

- OPTIONAL (organization, admin, phoneNumber, magicLink, genericOAuth,
  jwt+oauthProvider as one atomic unit, sso, scim, deviceAuthorization):
  built through addOptionalPlugin(), which on failure skips the feature
  with one loud actionable console.error, records it in
  getDegradedAuthFeatures(), and leaves core email/password + session
  auth up. The feature's endpoints 404 until the operator fixes the
  underlying error and restarts.

- CORE (bearer, twoFactor, haveIBeenPwned, customSession): still fail
  hard. Skipping these would silently weaken auth — 2FA-enrolled
  accounts signing in on password alone, opted-in breached-password
  rejection vanishing, the ADR-0069 authGate (password expiry, enforced
  MFA) and positions[] disappearing from sessions. Better a hard 500
  than fail-open security.

The OIDC discovery mount in auth-plugin.ts consults the degraded set and
skips advertising /.well-known documents for an IdP whose endpoints did
not come up (previously the "Failed to register OIDC discovery routes"
path), logging why instead of sending external clients into 404s.

Regression tests run the REAL better-auth pipeline (no betterAuth mock,
a minimal in-memory IDataEngine behind the genuine ObjectQL adapter)
with the exact incident TypeError injected into oauthProvider: sign-up
and get-session return 200, the degraded feature is reported, the
console.error fires; a throwing CORE plugin (bearer) still rejects; the
degraded set resets on a healthy rebuild. Full plugin-auth suite: 457
tests pass.

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

Author: os-zhuang

.changeset/plugin-auth-optional-plugin-isolation.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+Contain the blast radius of a failing optional better-auth plugin: core email/password + session auth now stays up when an optional feature plugin throws during initialization.
+
+Previously, one throwing optional plugin (the 15.1.0 incident: `@better-auth/oauth-provider` threw `Cannot set properties of undefined (setting 'modelName')` from a 1.6/1.7 version mix) failed the whole lazily-built better-auth instance, turning EVERY auth endpoint — sign-up, sign-in, get-session — into a 500.
+
+`AuthManager.buildPluginList` now classifies plugins in two tiers. Optional feature plugins (organization, admin, phoneNumber, magicLink, genericOAuth, jwt+oauthProvider as one atomic unit, sso, scim, deviceAuthorization) are constructed through an isolation wrapper: on failure the feature is skipped with a loud actionable `console.error`, recorded in `getDegradedAuthFeatures()`, and its endpoints 404 while core auth keeps working. Security-bearing plugins (bearer, twoFactor, haveIBeenPwned, customSession with its ADR-0069 authGate) still fail hard — better a hard 500 than silently weakened auth (e.g. 2FA-enrolled accounts signing in on password alone).
+
+The OIDC discovery mount (`/.well-known/{oauth-authorization-server,openid-configuration}`) checks the degraded set and skips advertising an IdP whose endpoints did not come up, with a clear error log instead of sending external clients into 404s.

packages/plugins/plugin-auth/src/auth-manager.optional-plugin-isolation.test.ts

@@ -0,0 +1,219 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Regression tests for optional-plugin isolation in AuthManager.buildPluginList.
+//
+// The 15.1.0 incident: `@better-auth/oauth-provider` (resolved to 1.6.23 by
+// downstream installs while the workspace tested 1.7.0-rc.1) threw
+// `Cannot set properties of undefined (setting 'modelName')` during plugin
+// construction. Because the better-auth instance is built lazily per request,
+// that single optional plugin took down EVERY auth endpoint with a 500.
+//
+// Unlike auth-manager.test.ts (which mocks `better-auth` itself), this file
+// runs the REAL better-auth against its in-memory adapter and only wraps two
+// plugin factories in controllable failure switches — so "sign-up returns
+// 200" is asserted against the genuine request pipeline.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { AuthManager } from './auth-manager';
+
+const failures = vi.hoisted(() => ({ oauthProvider: false, bearer: false }));
+
+vi.mock('@better-auth/oauth-provider', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, any>>();
+  return {
+    ...actual,
+    oauthProvider: (...args: any[]) => {
+      if (failures.oauthProvider) {
+        // Byte-for-byte the 15.1.0 incident error (1.6/1.7 family mix).
+        throw new TypeError("Cannot set properties of undefined (setting 'modelName')");
+      }
+      return actual.oauthProvider(...args);
+    },
+  };
+});
+
+vi.mock('better-auth/plugins/bearer', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, any>>();
+  return {
+    ...actual,
+    bearer: (...args: any[]) => {
+      if (failures.bearer) throw new TypeError('bearer exploded (simulated)');
+      return actual.bearer(...args);
+    },
+  };
+});
+
+/**
+ * Minimal in-memory IDataEngine covering exactly the surface the ObjectQL
+ * adapter drives (insert / findOne / find / count / update / delete with the
+ * eq/$ne/$in/$gt/$gte/$lt/$lte/$regex filter shapes convertWhere produces),
+ * so the REAL sign-up pipeline can persist users/sessions/accounts.
+ */
+const createMemoryEngine = () => {
+  const tables = new Map<string, any[]>();
+  const rows = (name: string) => {
+    if (!tables.has(name)) tables.set(name, []);
+    return tables.get(name)!;
+  };
+  const eq = (a: any, b: any) =>
+    a instanceof Date || b instanceof Date
+      ? new Date(a as any).getTime() === new Date(b as any).getTime()
+      : a === b;
+  const matches = (row: any, where: Record<string, any> = {}) =>
+    Object.entries(where).every(([k, v]) => {
+      const actual = row[k];
+      if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)) {
+        if ('$ne' in v) return !eq(actual, v.$ne);
+        if ('$in' in v) return (v.$in as any[]).some((x) => eq(actual, x));
+        if ('$gt' in v) return actual > v.$gt;
+        if ('$gte' in v) return actual >= v.$gte;
+        if ('$lt' in v) return actual < v.$lt;
+        if ('$lte' in v) return actual <= v.$lte;
+        if ('$regex' in v) return new RegExp(String(v.$regex)).test(String(actual ?? ''));
+      }
+      return eq(actual, v);
+    });
+  let seq = 0;
+  return {
+    async insert(name: string, data: any) {
+      const row = { id: data.id ?? `row_${++seq}`, ...data };
+      rows(name).push(row);
+      return { ...row };
+    },
+    async findOne(name: string, q: any = {}) {
+      return rows(name).find((r) => matches(r, q.where)) ?? null;
+    },
+    async find(name: string, q: any = {}) {
+      let out = rows(name).filter((r) => matches(r, q.where));
+      const order = q.orderBy?.[0];
+      if (order) {
+        out = [...out].sort(
+          (a, b) => (a[order.field] > b[order.field] ? 1 : -1) * (order.order === 'desc' ? -1 : 1),
+        );
+      }
+      if (q.offset) out = out.slice(q.offset);
+      if (q.limit) out = out.slice(0, q.limit);
+      return out.map((r) => ({ ...r }));
+    },
+    async count(name: string, q: any = {}) {
+      return rows(name).filter((r) => matches(r, q.where)).length;
+    },
+    async update(name: string, patch: any) {
+      const row = rows(name).find((r) => r.id === patch.id);
+      if (!row) return null;
+      Object.assign(row, patch);
+      return { ...row };
+    },
+    async delete(name: string, q: any = {}) {
+      const table = rows(name);
+      const keep = table.filter((r) => !matches(r, q.where));
+      tables.set(name, keep);
+      return table.length - keep.length;
+    },
+  };
+};
+
+describe('AuthManager – optional better-auth plugin isolation', () => {
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  const makeManager = () =>
+    new AuthManager({
+      secret: 'test-secret-at-least-32-chars-long!!',
+      baseUrl: 'http://localhost:3000',
+      dataEngine: createMemoryEngine() as any,
+      plugins: { oidcProvider: true },
+    });
+
+  const signUp = (manager: AuthManager, email: string) =>
+    manager.handleRequest(
+      new Request('http://localhost:3000/api/v1/auth/sign-up/email', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          email,
+          password: 'S3cure!Passw0rd-isolation',
+          name: 'Isolation Test',
+        }),
+      }),
+    );
+
+  beforeEach(() => {
+    failures.oauthProvider = false;
+    failures.bearer = false;
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  it('healthy control: oidcProvider constructs for real and sign-up returns 200', async () => {
+    const manager = makeManager();
+    const response = await signUp(manager, 'healthy@example.com');
+
+    expect(response.status).toBe(200);
+    expect(manager.getDegradedAuthFeatures()).toEqual([]);
+  });
+
+  it('15.1.0 regression: a throwing oauthProvider is skipped and sign-up still returns 200', async () => {
+    failures.oauthProvider = true;
+    const manager = makeManager();
+
+    const response = await signUp(manager, 'degraded@example.com');
+    expect(response.status).toBe(200);
+    const body: any = await response.json();
+    expect(body?.user?.email).toBe('degraded@example.com');
+
+    // The failure is recorded (jwt + oauthProvider land atomically, so the
+    // whole oidcProvider unit is what degrades)…
+    expect(manager.getDegradedAuthFeatures()).toEqual([
+      expect.objectContaining({
+        feature: 'oidcProvider',
+        error: expect.stringContaining('modelName'),
+      }),
+    ]);
+    // …and loudly: one actionable console.error naming the feature.
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Optional auth feature "oidcProvider" failed to initialize'),
+      expect.any(TypeError),
+    );
+  });
+
+  it('get-session also survives a degraded optional plugin', async () => {
+    failures.oauthProvider = true;
+    const manager = makeManager();
+
+    const response = await manager.handleRequest(
+      new Request('http://localhost:3000/api/v1/auth/get-session'),
+    );
+    expect(response.status).toBe(200);
+  });
+
+  it('core plugin (bearer) still fails hard — no fail-open for security-bearing plugins', async () => {
+    failures.bearer = true;
+    const manager = makeManager();
+
+    await expect(signUp(manager, 'core@example.com')).rejects.toThrow(
+      'bearer exploded (simulated)',
+    );
+    // Core failures are NOT recorded as degraded features — the instance
+    // never came up at all.
+    expect(manager.getDegradedAuthFeatures()).toEqual([]);
+  });
+
+  it('degraded state resets when the instance is rebuilt with the fault gone', async () => {
+    failures.oauthProvider = true;
+    const manager = makeManager();
+    await signUp(manager, 'rebuild-a@example.com');
+    expect(manager.getDegradedAuthFeatures()).toHaveLength(1);
+
+    // Simulate the operator fixing the underlying issue + a config-driven
+    // rebuild (applyConfigPatch resets the lazy instance).
+    failures.oauthProvider = false;
+    manager.applyConfigPatch({});
+    const response = await signUp(manager, 'rebuild-b@example.com');
+
+    expect(response.status).toBe(200);
+    expect(manager.getDegradedAuthFeatures()).toEqual([]);
+  });
+});