---
name: integrate-holeauth
description: "Entry-point skill for adding holeauth authentication to an existing project. Use when: adding authentication, setting up auth, integrating holeauth, installing holeauth, adding login, adding 2FA, adding passkeys, adding RBAC, adding SSO, becoming an OIDC provider, consuming an OIDC provider, adding sessions. Asks what features are needed and routes to the right per-package skills."
argument-hint: "Optional: comma-separated plugin list to skip the multi-select (e.g. '2fa,rbac')"
domain: "authentication, authorization, holeauth, integrations, 2fa, passkeys, rbac, sso, oidc"
---

# Integrate holeauth

Dispatcher skill. Interviews the user, then loads the appropriate per-package integration skills in dependency order.

## When NOT to use

- Starting a brand-new Next.js project from scratch → use `bootstrap-nextjs-holeauth` instead.
- Building a custom holeauth plugin → use `holeauth-plugin-design`.

## Source of truth

Implementation details live in the docs. Fetch them on demand:

- Docs root: `https://docs.holeauth.dev/docs`
- Search API: `GET https://docs.holeauth.dev/api/search?q=<term>`
- Reference auth setup: `apps/playground/lib/auth.ts` in the holeauth repo.

---

## Procedure

### Step 1 — Interview

Use `vscode_askQuestions` with these questions. **Never assume defaults — always ask.**

| # | Variable | Type | Options |
|---|---|---|---|
| 1 | `framework` | radio | Next.js App Router (recommended) / Next.js Pages Router / Express / Hono / Other (bail) |
| 2 | `persistence` | radio | Drizzle Postgres / Drizzle MySQL / Drizzle SQLite / Headless (BYO adapter) |
| 3 | `usersTable` | radio | Existing application table (ask for path) / Scaffold `app_users` |
| 4 | `plugins` | multi-select | 2FA · Passkeys · RBAC · IDP server · IDP consumer · (none) |
| 5 | `trpc` | radio | Yes / No |
| 6 | `ssoProviders` | multi-select | Google · GitHub · None (these are CORE providers — not the IDP consumer) |
| 7 | `useReactUi` | radio | Yes — use `@holeauth/react-ui` headless components · No — build own UI |
| 7b | `uiStyle` (only if `useReactUi === Yes`) | radio | Tailwind CSS · CSS Modules · Inline styles (unstyled) |
| 8 | `registration` | radio | Self-serve · Invite-only · Both |
| 9 | `superuser` | radio | Seed script · Bootstrap CLI · Env-driven · Manual SQL · None |
| 10 | `basePath` | text | default `/api/auth` |
| 11 | `middleware` | radio | protectAllExcept (recommended) · refresh-only · None |

---

### Step 2 — Route to per-package skills

Run skills in this strict order. Each loaded skill inherits the answers from Step 1.

1. **Always:** `integrate-holeauth-core`
2. If `plugins` includes 2FA: `integrate-holeauth-2fa`
3. If `plugins` includes Passkeys: `integrate-holeauth-passkey`
4. If `plugins` includes RBAC: `integrate-holeauth-rbac`
5. If `plugins` includes IDP server: `integrate-holeauth-idp`
6. If `plugins` includes IDP consumer: `integrate-holeauth-idp-consumer`
7. If `trpc === Yes`: `integrate-holeauth-trpc`

If `framework` is **Express or Hono**: do NOT bail. The `integrate-holeauth-core` skill supports these frameworks. Pass the `framework` variable through and the core skill will reference the correct platform adapter and docs.

---

### Step 3 — Superuser bootstrap

Based on the `superuser` choice, write the corresponding artifact:

- **Seed script** → `scripts/seed.ts` with a `tsx` shebang that creates the first user and assigns the admin group (only valid if RBAC was selected).
- **Bootstrap CLI** → `scripts/bootstrap-admin.ts` that reads CLI args / prompts for email + password.
- **Env-driven** → `scripts/promote-from-env.ts` reading `BOOTSTRAP_ADMIN_EMAIL` on first boot.
- **Manual SQL** → emit a `docs/SUPERUSER.md` with the exact SQL.
- **None** → skip.

---

### Step 4 — Verification checklist

Print this checklist back to the user. They run the commands; you don't.

```
[ ] pnpm install completed without peer-dep warnings
[ ] Drizzle migration generated and applied (pnpm db:push or drizzle-kit push)
[ ] Auth route handler responds at <basePath>/... (e.g. GET /api/auth/.well-known/openid-configuration)
[ ] Middleware is in place and protects authenticated routes
[ ] HoleauthProvider wraps the app in the root layout
[ ] /login page exists and loads (200 — no 404)
[ ] /register page exists and loads (if registration is self-serve or both)
[ ] /(guest)/layout.tsx (or equivalent) redirects authenticated users away from guest routes
[ ] Sign-up flow completes end-to-end
[ ] Sign-in flow completes end-to-end
[ ] If 2FA selected: /2fa/verify page exists; TOTP code accepted after sign-in
[ ] If Passkeys selected: passkey register and login pages exist and work
[ ] If RBAC selected: default group auto-assigned after registration
[ ] Font set in root layout (not browser default serif)
[ ] Superuser created (if applicable)
[ ] Required env vars set: HOLEAUTH_SECRET, DATABASE_URL, APP_URL
[ ] pnpm typecheck passes
[ ] pnpm build succeeds
```

---

## Hard constraints

- **Never invent options.** If unsure, ask. Never write `defineHoleauth` directly in Next.js setups — use `createAuthHandler` from `@holeauth/nextjs-app-router`.
- **Plugin factory names:** `twofa`, `passkey`, `rbac`, `idp`. Adapter factories: `createHoleauthAdapters`, `createRbacAdapter`, `createTwoFactorAdapter`, `createPasskeyAdapter`, `createIdpAdapter` — all take `{ db, tables }`.
- **Plugins array must be `as const`** for full TypeScript inference of `auth.<pluginKey>.<method>()`.
- **`cookiePrefix` must be identical** in `createAuthHandler`, `holeauthMiddleware`, and `HoleauthProvider`.

---

## Need more detail?

```
GET https://docs.holeauth.dev/api/search?q=<topic>
```

Example queries: `account linking`, `audit log`, `refresh rotation`, `csrf`, `events`.