Auth Implementation

---
name: auth-implementation
description: |
  Trigger when the user asks to add authentication, wire up sign-in, implement
  session management, or set up auth providers. Phrases: "add auth", "sign-in",
  "login flow", "session management", "OAuth", "Clerk", "Auth.js", "magic link".
allowed-tools:
  - Bash(npm install *)
  - Bash(pnpm add *)
  - Read
  - Write
  - Edit
  - Grep
---

# Auth Implementation

Add an authentication layer to a web app with the right provider choice for
the stack. Covers provider selection, middleware, session storage, and
protected-route patterns.

## Prerequisites

- Framework identified (Next.js, Remix, Express, etc.)
- Database or session store available if self-hosted

## Steps

1. **Pick the provider.** Quick decision rule:
   - Greenfield with fast ship requirement: **Clerk** (hosted, UI included)
   - Self-hosted requirement: **Auth.js / NextAuth** (framework-agnostic)
   - Already using Supabase or Convex: use their built-in auth
   - Enterprise SSO required: **WorkOS** or **Ory**

   Surface the tradeoff explicitly before installing anything.

2. **Install the SDK.** For Clerk in Next.js:

   ```bash
   pnpm add @clerk/nextjs
   ```

3. **Wire environment variables.** Create `.env.local` entries with clear
   comments:

   ```
   # Get these from clerk.com dashboard
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
   CLERK_SECRET_KEY=sk_test_...
   ```

4. **Add middleware.** For Clerk Next.js:

   ```ts
   // middleware.ts
   import { clerkMiddleware } from "@clerk/nextjs/server";
   export default clerkMiddleware();
   export const config = {
     matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
   };
   ```

5. **Wrap the app.** Add `<ClerkProvider>` at the root layout level.

6. **Build the sign-in/up pages.** Use `<SignIn />` and `<SignUp />` from the
   provider. Place at `/sign-in` and `/sign-up`.

7. **Protect routes.** Use the provider's server-side helper:

   ```ts
   import { auth } from "@clerk/nextjs/server";
   const { userId } = await auth();
   if (!userId) redirect("/sign-in");
   ```

8. **Document the flow.** Add an "Auth" section to the README covering:
   - Which provider is in use and why
   - Required env vars and where to get them
   - How to add a new protected route

## Common failure modes

- Missing env var in production only. Surface explicit error instead of
  silent redirect. See `isAuthBypassed()` pattern for dev/prod env safety.
- Middleware matcher too aggressive, blocking `_next/` static assets.
- Webhook signature not verified when creating user in your DB.

## Output

- SDK installed and configured
- Middleware active
- Sign-in/up pages render
- At least one protected route verified with a manual test
- README updated with auth section