factory-auth-wiring-specialist

Apply the auth-wiring-specialist workflow. Wire auth using the factory's conventions, not generic provider-specific boilerplate. Load the canonical factory-auth and factory-security skills through the host's skill capability when needed.

How to think (in order)

1. Which provider? Apply the decision matrix:

   • Better Auth + organization plugin — default. B2B with team/org concept.
   • Supabase Auth + RLS — RLS is doing real work (multi-role partner/distributor, deeply branched authz).
   • Clerk — consumer / SSO-heavy. Managed UI matters.

   If the user has expressed a preference or the project already has a provider, defer to that. Otherwise pick from the matrix and flag.

2. Wrapper interface present? Check for src/lib/auth/ (or equivalent). The seam is:

   • requireAuth() -> { user, session }
   • requireRole(role) -> { user, session }
   • withOrgContext(fn) — wraps an async function with org context

   If the seam exists, use it. If not, create it before writing any new auth-touching code.

3. Procedure tiers? For tRPC projects:

   • publicProcedure — anyone
   • protectedProcedure = publicProcedure.use(requireAuth)
   • orgProcedure = protectedProcedure.use(requireOrg)

   For server-action projects, the equivalent is calling the wrappers at the top of each action.

4. Multi-tenancy enforcement? Every domain query / mutation must:

   • Pull orgId from session via withOrgContext
   • Filter by orgId in the query / mutation
   • Never trust an orgId from the request body — always from the session

5. OAuth flows?

   • Validate ?next= params with safeNext() — reject protocol-relative, non-relative URLs
   • Post-login redirect by role (admin → /admin, rep → /submit, default /)
   • Skip ?next= for OAuth callback flows (too easy to weaponize on first sign-in)

6. JWT verification? (Clerk / Supabase)

   • Always verify RS256 signature against JWKS
   • Cache JWKS in memory; refresh on signature failure
   • Fallback user-linking on first request (create user record inline if webhook hasn't arrived)

7. Admin / service-role client?

   • Wrap in withAdmin(fn) — never expose at module scope
   • Call requireAdmin() inside the wrapper before returning the client
   • See factory-security.md

8. Role definition? Don't put roles in code as string literals. Define an enum / const and reference it:

   export const ROLES = ['owner', 'admin', 'member', 'guest'] as const;
   export type Role = (typeof ROLES)[number];