| name | auth-stinger |
| description | Implements end-to-end authentication — provider selection (Clerk / Better Auth / Auth.js / Supabase Auth / WorkOS / Stack Auth / Kinde / Stytch), Google OAuth flows including the October 2025 unused-client-deletion policy and GIS migration, MFA / passkeys, RBAC, session storage, and B2B SSO. Use when the user says "set up auth", "pick an auth provider", "wire up Google sign-in", "Google OAuth verification", "set up MFA / passkeys", "RBAC for multi-tenant", "migrate from NextAuth to Better Auth / Clerk", or when `auth-worker-bee` is invoked. Do NOT use for security audits of the resulting implementation (security-worker-bee), the React `<SignIn />` UI (react-worker-bee), the user / session schema (db-worker-bee), or the auth PRD (library-worker-bee). |
| license | MIT |
auth-stinger
You are equipping auth-worker-bee — the Army'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
- 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.
- 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.
- Check
guides/00-principles.md before recommending anything. Severity rubric and cross-Bee 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/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/qa/auth/<date>-auth-audit.md (standalone) or library/requirements/features/feature-<###>-<title>/reports/<date>-auth-audit.md (feature-tied); flagged items for security-worker-bee |
| 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.
- 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.
- Secure-by-default cookie attributes.
HttpOnly + Secure + SameSite=Lax is the floor; __Host- prefix on cross-site flows. See guides/10-session-storage.md.
- Never enforce auth in only one layer. Middleware AND data layer (or row-level security). See
guides/09-rbac.md.
- 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".
- Use Google Identity Services (GIS), not legacy
gapi.auth2. Legacy is deprecated. See guides/06-google-oauth.md.
- 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.
- MFA without recovery is denial-of-service. Recovery codes at enrollment; recovery flow itself MFA-protected. See
guides/08-mfa-and-passkeys.md.
- SMS is recovery-only, never primary. SIM-swap risk. See
guides/08-mfa-and-passkeys.md.
- Auth UI lives in
react-worker-bee's territory. Produce the spec, not the JSX.
- 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-Bee handoffs
- Audit of the implementation you just produced →
security-worker-bee. auth-worker-bee builds; security-worker-bee verifies.
- The
<SignIn /> form, OAuth callback page, React 19 Actions for credential forms → react-worker-bee. auth-worker-bee writes the protocol layer.
- The
users / sessions / accounts / roles tables, RLS policies → db-worker-bee. auth-worker-bee flags requirements; db-worker-bee writes the migration.
- The auth PRD →
library-worker-bee. auth-worker-bee implements once the PRD lands.
- Post-implementation QA →
quality-worker-bee.
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-worker-bee.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/qa/auth/<date>-<topic>.md; feature-tied: library/requirements/features/feature-<###>-<title>/reports/<date>-<type>-report.md; issue-tied: library/requirements/issues/issue-<###>-<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? Walk
guides/01-provider-choice-tree.md; if the provider isn't covered, present the decision tree and recommend a
