npm better-auth 1.8.0-beta.11
v1.8.0-beta.11

one hour ago

Important

Action required

  • If you use requireMcpAuth without an issuer option and verify tokens against keys fetched from a URL (jwksUrl or the JWT plugin's jwks.remoteUrl), make sure tokens carry the discovery issuer, or pass issuer explicitly. (#12714)

  • If you verify OAuth provider tokens outside Better Auth against a pinned jwt.issuer or base URL, switch to the discovery issuer, and accept both values until JWT access tokens issued before the upgrade expire. (#12714)

  • If you throw from customTokenResponseFields or an extensions[].claims.idToken contributor to refuse tokens, move that check to beforeTokenIssuance. (#12663)

  • If you use CIBA, run npx auth@latest migrate, or npx auth@latest generate and apply the schema with your ORM, before you upgrade to add the new approvedViaConsent column on the cibaRequest model. (#12801)

  • If you have OAuth resources with an empty stored allowedScopes that relied on denying every scope, set disabled: true on each (or give it real scopes) before the first 1.8 process starts, and remove any config allowedScopes: [], which now fails at startup. (#12743)

  • If you use CIBA with approvalPage, record each decision with auth.api.completeCibaRequest, and if your code extends CibaOptions with interface, use an intersection type instead. If your sendNotification uses url as a string, check it for undefined. (#12712)

  • If you use CIBA, run npx auth@latest migrate with the built-in Kysely adapter, or run npx auth@latest generate and apply the schema with your ORM, to add the actor column to cibaRequest before you upgrade. (#12712)

  • feat(ciba)!: require client authentication; 401 for invalid_client (#12712)

    CIBA deployments can now read a pending request on their own approval page with the new server-only auth.api.getCibaRequest({ body: { requestId, userId } }). It returns what to show the user (client, scopes, resources, binding message, ACR values, authorization details, actor, and expiry), or null when completeCibaRequest would refuse the request as unknown, such as a decided or expired request or one for another user, and when the client no longer exists. sendNotification now also receives the requested resources.

  • If your client handles /oauth2/bc-authorize errors, expect status 401 with invalid_client instead of 400, including when the request has no client_id. (#12712)

  • If you set allowPublicClients, remove it and register those clients with a secret or with private_key_jwt. (#12712)

  • If you use the OAuth provider, run npx auth@latest migrate, or generate and apply the schema, to add the accessTokenFormat column to oauthResource before deploying, or every request will fail the schema check. (#12656)

  • If a relying party sits on an internal network and its public-looking name resolves to a private address, list its exact origin in trustedOrigins to keep delivering logout tokens to it. (#12697)

  • If you use CIBA ping mode with a client whose notification endpoint resolves to a private or internal address, list that endpoint's origin in trustedOrigins at initialization to keep receiving pings. (#12690)

  • If you use a custom jwt.sign in the JWT plugin, make it apply its header argument, which carries typ: at+jwt, or the provider will reject its access tokens. (#12667)

  • If a client reads name or picture from UserInfo and expects an empty string, handle the missing key, or return the claim from customUserInfoClaims. (#12803)

  • feat(mcp)!: pass requireMcpAuth handlers the sub the token carries (#12672)

    requireMcpAuth passes the handler the sub the access token carries, as in 1.7, instead of the internal user ID that 1.8.0-beta.10 passed. For a client with subject_type: "pairwise", an opaque token's sub is now its pairwise subject, as at /oauth2/introspect, and a JWT's sub is the pairwise subject when the provider sets accessTokenSubject: "pairwise". Other tokens keep the user ID.

    Breaking for 1.8.0-beta.10 users: beta.10 passed the user ID even for pairwise tokens. An MCP handler that looks users up by sub for pairwise clients must now map the pairwise subject itself, or keep those clients on subject_type: "public".

  • If your clients rotate private_key_jwt keys, keep the jwks_uri reachable, publish the new key and wait 5 minutes before signing with it. (#12700)

  • If you want a user's OAuth tokens to stay valid across a password reset, set revokeGrantsOnPasswordReset: false. (#12738)

  • If you rely on getOAuthConsent or getOAuthConsents returning only the last approval, or on the consent page appearing again for previously approved access, update that code; consents now accumulate everything the user approved and did not take back. (#12798)

better-auth

Features

  • Added tokenEndpoint, userInfoEndpoint, and jwksEndpoint overrides to social providers so you can point them at a local OAuth emulator or sandbox (#12746)
  • Added prepareDeviceCodeRedemption so custom device code issuers can run a final check before the code is spent (#12663)
  • Added an onPasswordReset plugin hook that runs after a password reset, including for users with no live session (#12738)

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

❗ Breaking Changes

  • Changed the OAuth consent page to add each approval to the user's stored consent instead of replacing it (#12798)
  • Changed the OAuth provider to refetch a client's jwks_uri for an unknown key at most once every 60 seconds (#12700)
  • Changed UserInfo to omit the name and picture claims when the user's name or image is an empty string (#12803)
  • Changed the OAuth provider to accept JWT access tokens only when their header has typ: at+jwt (#12667)
  • Fixed back-channel logout to skip delivery to a backchannel_logout_uri whose host resolves to a non-public address (#12697)
  • Changed OAuth resource allowedScopes to a single storable contract, where an empty stored list now allows every requested scope instead of denying all (#12743)
  • Fixed OAuth provider tokens to carry the same iss as the discovery issuer, so clients and the end-session endpoint accept them (#12714)

Features

  • Added serverContext to provider.issueAuthorizationCode() so plugin endpoints can store values with a code and read them back when it is redeemed (#12676)
  • Added a beforeTokenIssuance option that lets you refuse token issuance for any grant before any token is stored (#12663)
  • Changed customTokenResponseFields and extensions[].claims.idToken contributors to run after the DPoP check and beforeTokenIssuance (#12663)
  • Added a beforeAuthorization option to run a policy on each authorization request, such as requiring a new sign-in or refusing the request (#12657)
  • Added an amr option to provider.issueAuthorizationCode() so plugin endpoints can report the authentication methods they verified (#12654)
  • Added provider.validateAuthorizationRequest() so plugin endpoints can reject an invalid OAuth authorization request before the user signs in (#12654)
  • Added support for a function-valued accessTokenExpiresIn to set access token lifetime per user grant, capped by the new accessTokenMaxExpiresIn (#12740)
  • Added an idToken: false option to issueTokens so extension grants can skip the ID token while keeping the openid scope (#12665)
  • Added tokenResponseFields so OAuth provider extensions can add their own fields to the token response (#12664)
  • Added grantId to claim callbacks and customTokenResponseFields so apps can tell separate authorizations apart across refreshes (#12662)
  • Changed refresh token replay to revoke only the affected grant instead of every refresh token the client holds for the user (#12754)
  • Added an onTokenRevoked option that reports revoked grants and access tokens so you can notify resource servers or keep an audit log (#12678)
  • Improved provider.issueAuthorizationCode() to reuse same-request authenticateClient() and verifyDpopProof() results instead of rejecting them as replayed (#12759)
  • Added revocation of a user's OAuth access and refresh tokens, including offline_access grants, on password reset when emailAndPassword.revokeSessionsOnPasswordReset is enabled (#12738)
  • Added a per-resource accessTokenFormat: "opaque" option so protected resources can receive opaque access tokens instead of JWTs (#12656)
  • Changed OAuth authorization requests without scope to use the intersection of the client's registered scopes and clientRegistrationDefaultScopes (#12742)

Bug Fixes

  • Fixed revoked sessions being able to approve or deny interaction requests, such as CIBA requests or OAuth device codes, while session.cookieCache still served them (#12690)
  • Fixed device codes to be rejected with invalid_grant when the user's stored consent was deleted or narrowed after approval (#12790)
  • Fixed authorization codes to be rejected with invalid_grant when the user's stored consent was deleted or narrowed after the code was issued (#12737)
  • Fixed the OAuth provider token endpoint to exchange authorization codes that carry no scopes instead of rejecting them with invalid_scope (#12741)
  • Fixed concurrent matching refresh requests to get the same rotated response instead of invalid_grant when refreshTokenReuseInterval is set (#12739)
  • Fixed deleting an OAuth consent to also revoke the access and refresh tokens issued under it (#12736)

For detailed changes, see CHANGELOG

@better-auth/ciba

❗ Breaking Changes

  • Added a CIBA approvalPage option so requests are approved only on your own page or app, and /oauth2/authorize no longer approves them (#12712)
  • Added CIBA delegated access tokens that name the user as sub and an actor as the act claim, using the new resolveActor option (#12712)
  • feat(ciba)!: require client authentication; 401 for invalid_client (#12712)
  • Changed CIBA /oauth2/bc-authorize to answer invalid_client with status 401 and a WWW-Authenticate challenge instead of 400 (#12712)
  • Removed the CIBA allowPublicClients option, so clients using token_endpoint_auth_method: "none" are now always rejected with invalid_client (#12712)

Bug Fixes

  • Fixed CIBA requests approved from a link so they can no longer be redeemed after the user deletes or narrows the stored consent (#12801)
  • Fixed CIBA ping mode to re-check the notification endpoint's host and skip the ping when it resolves to a non-public address (#12690)
  • Fixed CIBA ping notifications so providers running on Cloudflare Workers can deliver them to clients (#12690)

For detailed changes, see CHANGELOG

@better-auth/mcp

❗ Breaking Changes

  • feat(mcp)!: pass requireMcpAuth handlers the sub the token carries (#12672)
  • Changed requireMcpAuth to expect the OAuth provider's discovery issuer by default, which follows a custom jwt.issuer (#12714)

For detailed changes, see CHANGELOG

@better-auth/cimd

Features

  • Added createCimdMetadataResolver so runtimes that build the auth instance per request can share one CIMD metadata cache, fetch limits, and in-flight fetches (#12745)

Bug Fixes

  • Fixed CIMD so a flood of refused client_id URLs no longer exhausts the metadata fetch budget and makes allowed clients fail with temporarily_unavailable (#12744)

For detailed changes, see CHANGELOG

@better-auth/core

Features

  • Added tokenEndpoint, userInfoEndpoint, and jwksEndpoint overrides to social providers so you can point them at a local OAuth emulator or sandbox (#12746)
  • Added an onPasswordReset plugin hook that runs after a password reset, including for users with no live session (#12738)

For detailed changes, see CHANGELOG

Contributors

Thanks to everyone who contributed to this release:

@alfaroukhesham, @cursoragent, @Garv978, @GautamBytes, @ghazy2001, @grant0417, @gustavovalverde, @kaiizer777, @Lakshya0604, @PrabalParihar, @risi-au, @vjymisal0, @waleed-mirza

Full changelog: v1.8.0-beta.10...v1.8.0-beta.11

Don't miss a new better-auth release

NewReleases is sending notifications on new releases.