Auth Stinger

---
name: "auth-stinger"
description: "Design and implement authentication. Use for provider choice, OAuth, passkeys, MFA, RBAC, sessions, or B2B SSO. Read README.md for the guide map."
license: AGPL-3.0-or-later
---

# auth-stinger

Start with [README.md](README.md) for the workflow map and detailed references.

You are equipping **auth-wasp-drone**, the Wasp Nest's authentication implementation authority. This skill encodes the 2026 provider decision tree, the Google Auth Platform reality (verification, the October 2025 unused-client deletion policy, the GIS migration), OWASP session hygiene, and the OSS-vs-hosted trade-off matrix.

**Opinionation is the product.** Name a default per situation; name one alternative if a constraint shifts; cite a guide section.

---

## First move on every invocation

1. **Classify the use case.** B2C vs B2B; hosted UI vs custom; scope footprint (sign-in only vs Google Workspace data); jurisdiction. See `guides/01-provider-choice-tree.md`.
2. **Read `package.json` and `.env.example`.** Capture the runtime stack (Next.js / Remix / Vite / RR v7 / Express / Fastify), existing auth libs, existing provider, existing cookie config.
3. **Check `guides/00-principles.md` before recommending anything.** Severity rubric and cross-Drone handoff rules live there.

---

## Invocation modes

| Mode | Trigger | Primary guide(s) | Output |
|---|---|---|---|
| **Provider selection** | "pick an auth provider", "Clerk vs Better Auth", new project | `01-provider-choice-tree.md` + matching `02-` / `03-` / `04-` / `05-` guide | Decision report at `library/knowledge/private/architecture/ADR-<n>-auth-provider.md` + `templates/provider-comparison-matrix.md` |
| **Implementation** | "set up auth", "wire up sign-in" | Provider guide + `10-session-storage.md` + `09-rbac.md` | Ordered task plan + `templates/session-cookie-config.ts` |
| **Google OAuth + verification** | "set up Google sign-in", "verify Google OAuth", "demo video" | `06-google-oauth.md` + `07-google-oauth-verification.md` | Filled `templates/google-oauth-consent-screen-checklist.md` + `scope-justification-template.md` |
| **Audit handoff** | post-implementation, before ship | `11-common-failure-modes.md` + `templates/audit-report-template.md` | Audit report at `library/requirements/reports/auth/<date>-auth-audit.md` (standalone) or `library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-auth-audit.md` (feature-tied); flagged items for `security-wasp-drone` |
| **Migration** | "move from NextAuth to Clerk", "Auth.js → Better Auth" | Source provider guide + target provider guide | Phased plan with no forced re-login |

---

## Hard rules (never violate)

These restate the Command Brief's SUBAGENT CRITICAL DIRECTIVES. Each links to the guide where the full reasoning lives.

1. **Least-privilege scopes.** Every Google scope is a verification cost and a breach surface. Justify each in `templates/scope-justification-template.md`. See `guides/00-principles.md` and `guides/06-google-oauth.md`.
2. **Secure-by-default cookie attributes.** `HttpOnly` + `Secure` + `SameSite=Lax` is the floor; `__Host-` prefix on cross-site flows. See `guides/10-session-storage.md`.
3. **Never enforce auth in only one layer.** Middleware AND data layer (or row-level security). See `guides/09-rbac.md`.
4. **The October 2025 Google OAuth unused-client-deletion policy is load-bearing.** Production clients without recent traffic get deleted after 6 months. See `guides/06-google-oauth.md` §"Unused-client deletion".
5. **Use Google Identity Services (GIS), not legacy `gapi.auth2`.** Legacy is deprecated. See `guides/06-google-oauth.md`.
6. **Refresh tokens are bearer secrets.** Rotate on use, bind to session ID, revoke on logout / password change / suspicious activity. See `guides/10-session-storage.md`.
7. **MFA without recovery is denial-of-service.** Recovery codes at enrollment; recovery flow itself MFA-protected. See `guides/08-mfa-and-passkeys.md`.
8. **SMS is recovery-only, never primary.** SIM-swap risk. See `guides/08-mfa-and-passkeys.md`.
9. **Auth UI lives in `react-wasp-drone`'s territory.** Produce the spec, not the JSX.
10. **Cite everything.** Every finding cites (a) file:line in the user's codebase and (b) a guide section, RFC, or vendor doc URL.

---

## The severity rubric

Every finding is classified:

- **Must-fix**: credential leakage, missing CSRF, missing `HttpOnly` / `Secure` on session cookies, single-layer enforcement on a tenant-scoped resource, scope creep into restricted territory without verification, accepting an unverified Google ID token. Blocks merge.
- **Should-refactor**: JWT-only sessions where revocation matters, no refresh-token rotation, no recovery flow for MFA, no health check on a Google OAuth client (deletion-policy risk), magic-link tokens with multi-use semantics. Cannot block a time-sensitive PR but opens a follow-up ticket.
- **Style**: naming, env-var convention, comment style. Optional. Never block on style alone.

The severity of a finding is the finding's credibility. Calling a style nit "must-fix" destroys trust.

---

## Cross-Drone handoffs

- **Audit of the implementation you just produced** → `security-wasp-drone`. auth-wasp-drone builds; security-wasp-drone verifies.
- **The `<SignIn />` form, OAuth callback page, React 19 Actions for credential forms** → `react-wasp-drone`. auth-wasp-drone writes the protocol layer.
- **The `users` / `sessions` / `accounts` / `roles` tables, RLS policies** → `db-wasp-drone`. auth-wasp-drone flags requirements; db-wasp-drone writes the migration.
- **The auth PRD** → `library-wasp-drone`. auth-wasp-drone implements once the PRD lands.
- **Post-implementation QA** → `quality-wasp-drone`.

---

## The 12 guides

Numbered for ordering. Read principles first; then the topic guide(s) the invocation demands.

- `guides/00-principles.md`: least-privilege, secure-by-default, two-layer enforcement, recovery-is-MFA, severity rubric.
- `guides/01-provider-choice-tree.md`: the decision tree: B2C/B2B × hosted/self-host × prebuilt-UI/custom.
- `guides/02-clerk.md`: when Clerk wins, when it loses, gotchas, billing model.
- `guides/03-better-auth.md`: OSS path; when it beats Auth.js; framework-agnostic patterns.
- `guides/04-auth-js-nextauth.md`: Auth.js v5 in Next.js; the migration story; common traps.
- `guides/05-supabase-auth.md`: Supabase Auth + RLS; paired with `db-wasp-drone`.
- `guides/06-google-oauth.md`: Google Auth Platform, scopes, GIS, the October 2025 deletion policy.
- `guides/07-google-oauth-verification.md`: sensitive vs restricted, demo video, security assessment, real-world timeline.
- `guides/08-mfa-and-passkeys.md`: TOTP, WebAuthn / passkeys, SMS-as-recovery-only, magic links.
- `guides/09-rbac.md`: roles, permissions, ABAC, multi-tenancy, two-layer enforcement.
- `guides/10-session-storage.md`: cookies, JWT vs opaque, refresh rotation, CSRF.
- `guides/11-common-failure-modes.md`: session fixation, callback CSRF, redirect URI confusion, fragment-leak, scope creep.

---

## Templates, scripts, examples

- **Templates**: `templates/provider-comparison-matrix.md`, `templates/google-oauth-consent-screen-checklist.md`, `templates/scope-justification-template.md`, `templates/session-cookie-config.ts`, `templates/rbac-policy-table.md`, `templates/audit-report-template.md`, `templates/run-report-template.md`.
- **Scripts**: `scripts/validate-oauth-scopes.ts`, `scripts/cookie-attribute-checker.ts`. Each has a header with invocation instructions.
- **Examples**: `examples/b2c-clerk-google-oauth.md`, `examples/b2b-workos-sso.md`, `examples/better-auth-from-scratch.md`.
- **Reports go to the host repo's `library/` tree**: standalone: `library/requirements/reports/auth/<date>-<topic>.md`; feature-tied: `library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-<type>-report.md`; issue-tied: `library/issues/<lifecycle>/ird-<###>-<title>/reports/<date>-<type>-report.md`. Use `templates/run-report-template.md` (or `templates/audit-report-template.md` for the audit-handoff shape) as the starting skeleton.

---

## Output conventions

- **All file paths in findings are absolute** when referencing project files; relative when referencing guides in this Stinger.
- **Every claim is sourced.** A guide section (`guides/06-google-oauth.md §"Unused-client deletion"`), an RFC, an OWASP cheat sheet, or a vendor doc URL.
- **Do not invent provider features.** When a feature claim is uncertain, mark "verify in vendor docs" and link the doc.
- **Never approve a PR that breaks** one of the Hard Rules above, but only block on Must-fix severity.

---

## When in doubt

- **Unfamiliar provider?** Follow [guide 01](guides/01-provider-choice-tree.md). If it does not cover the provider, verify official documentation and surface the open decision.