Authentication

@repo/auth wraps Clerk, which handles authentication, users and organizations. A Clerk organization is what a Workspace is designed to map to.

Sign-in policy

The target policy is Google OAuth alone. Google-only is not yet enforced on the live Clerk instance. Google is enabled, and email_address is still a first factor with email OTP — so /sign-in currently offers those two. password is still enabled as an account attribute, but it is not a first factor (used_for_first_factor: false, no first_factors), so it is not offered at sign-in; it still has to be turned off before the policy is settled. Treat email OTP as a live sign-in path, and password as a live credential on an account, until the table in second-brain/wiki/packages/auth.md says otherwise.

Which factors <SignIn> renders is Clerk instance configuration, not repository code: nothing in this repository can enable or disable a strategy, and the Clerk Backend API has no endpoint for it. Flipping it needs the Clerk Dashboard, or clerk config patch once the CLI holds an interactive account session. __tests__/clerk-instance-contract.test.ts fails this documentation the moment it claims more than the recorded observation supports.

Google One Tap is mounted once in AuthProvider (via DesignSystemProvider), so every screen in apps/app and apps/web can prompt automatically — except /sign-in and /sign-up, where Clerk's own component already renders a Google button and a second Google affordance would compete with it. Clerk skips the prompt when a session already exists. On the marketing site, One Tap success redirects to NEXT_PUBLIC_APP_URL so users land in the product app.

One Tap renders inside OneTapBoundary. It is mounted beside the whole application, so an unguarded throw inside Clerk's component or the Google Identity Services script would blank the page; the boundary drops the prompt and leaves the page standing.

Clerk instance requirements

1. Enable Google as an SSO connection with custom Google OAuth credentials (Clerk's shared credentials are not enough for One Tap). Outstanding — Google is enabled, but the probe below returns display_config.google_one_tap_client_id: null, which is what the connection publishes once it carries custom credentials. Until it is set, <GoogleOneTap> has no Google client ID to initialize with and the prompt does not render anywhere. The wiring in this repository is complete and inert; nothing else has to change here when the credentials land.
2. In Google Cloud, authorize JavaScript origins and redirect URIs for local hosts, NEXT_PUBLIC_APP_URL (product), and NEXT_PUBLIC_WEB_URL (marketing).
3. Disable Email, Password, Phone and Username under User & Authentication. Outstanding. Check the migration exposure in the wiki first: disabling them locks out any account whose only identity is email or password.
4. Preferred automation once the Clerk CLI is linked: clerk config schema / clerk config patch for auth_email, auth_password, auth_phone and connection_oauth_google.
5. Record the result in the contract table in second-brain/wiki/packages/auth.md in the same change, and update this page to match.

In-App

The @repo/auth package exposes an AuthProvider, however you don't need to use this directly. The DesignSystemProvider includes all relevant providers and higher-order components.

From here, you can use all the pre-built components and hooks provided by Clerk. To demonstrate this, we've added the <OrganizationSwitcher> and <UserButton> components to the sidebar, as well as built out the Sign In and Sign Up pages.

Webhooks

Clerk uses webhooks to handle authentication events and you can send these to your application. Read more about inbound authentication webhooks.

Email Templates

Clerk still sends transactional mail for organization invites and similar flows when those features are used. Sign-in itself does not use email factors. You can configure the theming of Clerk-sent emails in their dashboard.

Local Development

Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying the API Worker with development environment variables, e.g. staging-api.example.com. Then you can add this URL to your Clerk project's webhook settings.