@@ -0,0 +1,14 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+fix(plugin-auth): a refused enterprise OIDC sign-in names its cause
+
+Clause-②: no
+Metadata-protocol: none
+
+The SSO callback (`/sso/callback/:providerId`) used to answer every refused ID token with the same redirect, `error=invalid_provider&error_description=token_not_verified`, so an administrator could not tell a wrong audience from an expired token, a foreign issuer or a retired signing key. `error_description` now names the cause: `id_token_expired`, `id_token_not_yet_valid`, `id_token_audience_mismatch`, `id_token_issuer_mismatch`, `id_token_signing_key_unknown` or `id_token_signature_invalid`. A refusal outside those classes keeps `token_not_verified`. `error=` is unchanged. The server writes one `warn` line per refusal with `providerId`, `protocol: 'oidc'` and `cause`, and no token content or account signal. The list is exported as `SSO_OIDC_REFUSAL_CAUSES`.
+
+better-auth's own log lines now go to the `AuthManager` logger at the level better-auth chose (`error` stays `error`, `warn` stays `warn`) instead of the console. With no logger configured they still go to the console. A message that is an error object is logged as its name and message, as better-auth's console logger printed it; the vendor's further arguments pass through unchanged. The vendor's `error` line for a classified ID-token refusal is replaced by the `warn` line above.
+
+SAML refusals are unchanged: `@better-auth/sso` does not expose their cause.
@@ -288,6 +288,27 @@ caller gets **401 `UNAUTHENTICATED`** and a signed-in non-platform-admin **403
 cannot use these routes to probe which features an environment has enabled.
 </Callout>
 
+### Why an OIDC sign-in was refused
+
+When the identity provider's ID token is not accepted, the callback redirects to
+your `errorCallbackURL` (or `callbackURL`) with `error=invalid_provider`, and
+`error_description` names the cause. The server also writes one `warn` log line
+with the `providerId`, `protocol: 'oidc'` and the same `cause`. Neither carries
+any token content, and the answer does not depend on whether the account exists.
+
+| `error_description` | What to check |
+| :--- | :--- |
+| `id_token_expired` | The token's `exp` is in the past. Check the clocks of this server and the IdP. |
+| `id_token_not_yet_valid` | The token's `nbf` is in the future. Check the clocks of this server and the IdP. |
+| `id_token_audience_mismatch` | The token's `aud` is not this provider's `clientId`. Check the client ID registered here against the IdP application. |
+| `id_token_issuer_mismatch` | The token's `iss` is not this provider's `issuer`. Check the issuer URL, including any trailing path or slash. |
+| `id_token_signing_key_unknown` | No key in the IdP's JWKS matches the token's key ID, usually after the IdP rotated or retired its signing key. Check the `jwksEndpoint`. |
+| `id_token_signature_invalid` | The JWKS key does not verify the token's signature. Check that the `jwksEndpoint` belongs to the same IdP as the `issuer`. |
+| `token_not_verified` | Any other refusal of the ID token. The server log carries the detail. |
+
+The list is exported as `SSO_OIDC_REFUSAL_CAUSES` from `@objectstack/plugin-auth`.
+SAML refusals do not name their cause yet.
+
 ---
 
 ## Enterprise SSO (SAML 2.0)
 
@@ -71,6 +71,7 @@ import { PLATFORM_IDP_PROVIDER_ID, refuseImplicitAccountLink } from './implicit-
 import { isPlaceholderEmail } from './placeholder-email.js';
 import { logAfterResponseSendFailure, sendAfterResponseOnPublicDoor } from './run-after-response.js';
 import { isVisitorResendInEndpointContext } from './visitor-verification-resend.js';
+import { createBetterAuthLogSink } from './sso-oidc-refusal-cause.js';
 
 /** The path better-auth declares for the email sign-up endpoint. */
 const SIGN_UP_EMAIL_PATH = '/sign-up/email';
@@ -206,6 +207,12 @@ export async function createAuthInstance(this: AuthInstanceHost): Promise<Auth<a
     // restart), while auth emails call `getAppName()` on every send.
     appName: this.getAppName(),
 
+    // better-auth's own log lines go to this manager's logger, level for level,
+    // instead of the console. The sink is also where an enterprise OIDC
+    // callback's refused ID token is classified, because the vendor hands that
+    // error object to its logger and nowhere else (`sso-oidc-refusal-cause.ts`).
+    logger: createBetterAuthLogSink(() => this.config.logger),
+
     // Database adapter configuration
     database: await this.createDatabaseConfig(),
 
 
@@ -67,6 +67,7 @@ import { clientAddressStateEntries } from './request-client-address.js';
 import { SESSION_ERASURE_PATHS } from './session-tombstone.js';
 import { envelopeVendorAdminRefusal } from './vendor-admin-refusal-envelope.js';
 import { OAUTH_REVOKE_PATH } from './mcp-token-revocation.js';
+import { ssoOidcCallbackProviderId } from './sso-oidc-refusal-cause.js';
 
 /**
  * The `AuthManager` members the functions below read — every one of them, and
@@ -85,10 +86,11 @@ export interface RequestRoutingHost {
   resolveClientAddress: AuthManager['resolveClientAddress'];
   runSubjectErasureAtomically: AuthManager['runSubjectErasureAtomically'];
   answerOAuthTokenRevocation: AuthManager['answerOAuthTokenRevocation'];
+  runSsoOidcCallback: AuthManager['runSsoOidcCallback'];
 }
 
 /** The body of `AuthManager#handleRequest`; the method's docblock there is its contract. */
-export async function handleRequest(this: Pick<RequestRoutingHost, 'betterAuthEndpointPath' | 'getOrCreateAuth' | 'resolveClientAddress' | 'runSubjectErasureAtomically' | 'answerOAuthTokenRevocation'>, request: Request, transport?: { remoteAddress?: string }): Promise<Response> {
+export async function handleRequest(this: Pick<RequestRoutingHost, 'betterAuthEndpointPath' | 'getOrCreateAuth' | 'resolveClientAddress' | 'runSubjectErasureAtomically' | 'answerOAuthTokenRevocation' | 'runSsoOidcCallback'>, request: Request, transport?: { remoteAddress?: string }): Promise<Response> {
   // ADR-0069 D7 — the client address this request's sign-in audit stamps,
   // established ONCE, here, by the same trust rule the D5 allow-list judges
   // with (`resolveClientAddress`). Read before any rewrite below, and carried
@@ -210,6 +212,10 @@ export async function handleRequest(this: Pick<RequestRoutingHost, 'betterAuthEn
   // longer sign in. Nothing tells the operator, and there is no way back.
   const endpointPath = this.betterAuthEndpointPath(request);
 
+  // An enterprise OIDC callback runs inside the refusal scope that puts the
+  // cause of a refused ID token on the redirect (`sso-oidc-refusal-cause.ts`).
+  const ssoOidcProviderId = ssoOidcCallbackProviderId(endpointPath);
+
   // [#3653 / #14522] A SCIM protocol request (`/scim/v2/*`) runs inside
   // `scimRequestScope`, which is what makes the adapter's `transaction`
   // config open a REAL engine transaction around the vendor's provisioning
@@ -230,7 +236,9 @@ export async function handleRequest(this: Pick<RequestRoutingHost, 'betterAuthEn
         const { scimRequestScope } = await import('./scim-connection-service.js');
         return scimRequestScope.run({ scim: true }, runHandler);
       }
-    : runHandler;
+    : ssoOidcProviderId !== undefined
+      ? (): Promise<Response> => this.runSsoOidcCallback(ssoOidcProviderId, runHandler)
+      : runHandler;
   // [objectstack-ai/cloud#3606, ruling A] `/oauth2/revoke` is answered a
   // second time, AFTER the provider: the provider authenticates the client
   // and answers first, unchanged, and the MCP access token it cannot revoke
 
@@ -250,6 +250,7 @@ import { resolvePasswordHasher } from './auth-manager-password-hasher.js';
 // after-hook (cut 12) and before-hook (cut 13) are now imported there, by the
 // two arrows that moved with it.
 import { createAuthInstance, type AuthInstanceHost } from './auth-manager-auth-instance.js';
+import { runSsoOidcCallbackScope } from './sso-oidc-refusal-cause.js';
 // [#25224 cut 16] The body of `buildPluginList`; the method of the same name
 // below hands it the members it reads (`PluginListHost`). The organization
 // plugin's factory (cut 15) is now imported there, by the arrow that moved
@@ -3938,16 +3939,26 @@ export class AuthManager {
    */
   handleRequest(request: Request, transport?: { remoteAddress?: string }): Promise<Response> {
     // [#25224 cut 10] The body moved to `auth-manager-request-routing.ts` (see `RequestRoutingHost`).
-    const host: Pick<RequestRoutingHost, 'betterAuthEndpointPath' | 'getOrCreateAuth' | 'resolveClientAddress' | 'runSubjectErasureAtomically' | 'answerOAuthTokenRevocation'> = {
+    const host: Pick<RequestRoutingHost, 'betterAuthEndpointPath' | 'getOrCreateAuth' | 'resolveClientAddress' | 'runSubjectErasureAtomically' | 'answerOAuthTokenRevocation' | 'runSsoOidcCallback'> = {
       betterAuthEndpointPath: (...a) => this.betterAuthEndpointPath(...a),
       getOrCreateAuth: (...a) => this.getOrCreateAuth(...a),
       resolveClientAddress: (...a) => this.resolveClientAddress(...a),
       runSubjectErasureAtomically: (...a) => this.runSubjectErasureAtomically(...a),
       answerOAuthTokenRevocation: (...a) => this.answerOAuthTokenRevocation(...a),
+      runSsoOidcCallback: (...a) => this.runSsoOidcCallback(...a),
     };
     return handleRequest.call(host, request, transport);
   }
 
+  /**
+   * Run one enterprise OIDC callback (`/sso/callback/:providerId`) so its
+   * refusal names its cause: the redirect's `error_description` and one `warn`
+   * line on this manager's logger (`sso-oidc-refusal-cause.ts`).
+   */
+  private runSsoOidcCallback(providerId: string, run: () => Promise<Response>): Promise<Response> {
+    return runSsoOidcCallbackScope(providerId, this.config.logger, run);
+  }
+
   /**
    * [#16025] The `basePath` string this manager hands better-auth: the
    * configured value VERBATIM, or the shipped default when nothing is
 
@@ -14,6 +14,13 @@
  * this package's adapter or its logger wiring was changed for it, because a
  * per-consumer patch would leave the class open for the next logger.
  *
+ * The library's lines reach the manager's logger, through the sink plugin-auth
+ * hands `betterAuth` (`sso-oidc-refusal-cause.ts`), and the console only when
+ * no logger is configured. So "the library's carriers" below are both: the
+ * console, and the manager-logger lines the sink tags `[better-auth]`. The sink
+ * passes the vendor's arguments through as written, so the error object is
+ * the same carrier it was on the console.
+ *
  * ## How a driver error is forced, honestly
  *
  * A UNIQUE index is added to `sys_user.name` after the schema is synced, and a
@@ -350,17 +357,23 @@ for (const cell of CELLS) {
         expect(engineWarns).toContain('Update operation failed');
       });
 
+      /** Every line the auth library wrote: the console, and its lines on the manager logger. */
+      const libraryLines = (): RecordedCall[] => [
+        ...captured.console,
+        ...captured.manager.calls.filter((c) => String(c.args[0]).startsWith('[better-auth]')),
+      ];
+
       it("the library's error line and its server-error line carry no bound value", () => {
-        const errorLines = captured.console.filter((l) => l.level === 'error');
+        const errorLines = libraryLines().filter((l) => l.level === 'error');
         expect(errorLines.map((l) => format(...l.args)).some((t) => t.includes('Failed to create user'))).toBe(true);
         expect(errorLines.map((l) => format(...l.args)).some((t) => t.includes('DuplicateRecordError'))).toBe(true);
-        for (const line of captured.console) {
-          expect(renderCall(line.args).includes(S), `console.${line.level} carries the caller's value`).toBe(false);
+        for (const line of libraryLines()) {
+          expect(renderCall(line.args).includes(S), `${line.level} ${String(line.args[0])} carries the caller's value`).toBe(false);
         }
       });
 
       it("the error object's properties carry no bound value, while its class, code and diagnostic survive", () => {
-        const errors = captured.console
+        const errors = libraryLines()
           .flatMap((l) => l.args)
           .filter((a): a is Error & Record<string, unknown> => a instanceof Error);
         for (const error of errors) {
 
@@ -93,6 +93,13 @@ export * from './otp-send-guard.js';
 export * from './rate-limit-storage.js';
 export * from './secondary-storage.js';
 export * from './register-sso-provider.js';
+// The closed list of causes an enterprise OIDC callback names when it refuses
+// the IdP's ID token (`error_description` on the redirect, and the log line).
+export {
+  SSO_OIDC_REFUSAL_CAUSES,
+  SSO_OIDC_UNCLASSIFIED_REFUSAL,
+  type SsoOidcRefusalCause,
+} from './sso-oidc-refusal-cause.js';
 export * from './send-verification-email.js';
 export * from './objectql-adapter.js';
 // [#7732] ADR-0069 D4's revoke-audit trail. Exported alongside the adapter it