/reports/<date>-auth-audit.md` (feature-tied); flagged items for `security-wasp-drone` | | **Account recovery** | "lost MFA device", "password reset", "support recovery", "account takeover" | `12-account-recovery.md` + pinned provider/session/MFA guides | `templates/account-recovery-evidence.md`; approved assurance policy and native differential evidence | | **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 needs usable recovery that preserves required assurance.** Establish the provider path at enrollment. Password reset or support claims must not silently remove MFA; unknown evidence means escalate, not bypass. See [guide 12](guides/12-account-recovery.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 guide map 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. - [guides/12-account-recovery.md](guides/12-account-recovery.md): recovery assurance, support authorization, provider/application separation and native proof. Use [the worksheet](templates/account-recovery-evidence.md) and [synthetic cases](examples/account-recovery-cases.md). --- ## 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.

--- 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--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/-auth-audit.md` (standalone) or `library/requirements//prd-<###>-/reports/<date>-auth-audit.md` (feature-tied); flagged items for `security-wasp-drone` | | **Account recovery** | "lost MFA device", "password reset", "support recovery", "account takeover" | `12-account-recovery.md` + pinned provider/session/MFA guides | `templates/account-recovery-evidence.md`; approved assurance policy and native differential evidence | | **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 needs usable recovery that preserves required assurance.** Establish the provider path at enrollment. Password reset or support claims must not silently remove MFA; unknown evidence means escalate, not bypass. See [guide 12](guides/12-account-recovery.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 guide map 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. - [guides/12-account-recovery.md](guides/12-account-recovery.md): recovery assurance, support authorization, provider/application separation and native proof. Use [the worksheet](templates/account-recovery-evidence.md) and [synthetic cases](examples/account-recovery-cases.md). --- ## 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.