plugins & architecture

7 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Better Auth is a framework-agnostic authentication framework for TypeScript

Better Auth is a framework-agnostic authentication and authorization framework for TypeScript. It provides a comprehensive set of features out of the box and includes a plugin ecosystem for adding advanced functionalities.

Better Auth supports advanced features including 2FA and multi-tenant support

Better Auth provides built-in support for features such as two-factor authentication (2FA) and multi-tenant support through its plugin ecosystem, allowing developers to add complex functionalities with minimal code.

OAuth Popup plugin purpose and use case

The OAuth Popup plugin enables popup-based OAuth sign-in where the OAuth flow runs in a popup and the completion page posts the session token back to the opener. This allows an app to sign in inside a cross-site iframe where its auth cookie is partitioned. The plugin pairs with the bearer plugin. For a normal top-level app, the redirect flow (signIn.social) is preferred; use the popup when a top-level redirect is not possible, such as in embedded or iframe scenarios.

OAuth Popup server setup with bearer plugin

To set up OAuth Popup on the server, import betterAuth, bearer, and oauthPopup from better-auth/plugins. Call betterAuth with plugins array containing oauthPopup() and bearer(), and set trustedOrigins to include the opener app origin(s). The bearer plugin is required for the OAuth Popup plugin to function.

OAuth Popup client setup

To set up OAuth Popup on the client, import createAuthClient and oauthPopupClient. Create the auth client with baseURL set to the auth origin and include oauthPopupClient() in the plugins array.

OAuth Popup requirements

OAuth Popup requires: (1) the bearer plugin on the server, since an embedded app authenticates with the handed-back token via Authorization: Bearer because its cookie is partitioned; (2) trustedOrigins configuration that includes the app (opener) origin so the popup only posts the token to a trusted origin; (3) COOP headers configured correctly on the top-level page that opens the popup (Cross-Origin-Opener-Policy: same-origin-allow-popups if COOP is set at all) and the auth API must not send a swap-triggering COOP on the callback (for example, disable it in security-headers middleware). COOP does not apply inside an iframe.

OAuth Popup security considerations

The session token is posted to the opener via postMessage, which is pinned to a trusted origin, and stored in localStorage only when embedded. The token should be treated like any bearer token: XSS on the app origin can read it. Keep session lifetimes short and the app free of XSS vulnerabilities.

Give your agent this brain