Auth Flow Planner — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Auth Flow Planner (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
This skill designs a complete authentication and authorization flow for any application. It covers the full lifecycle: registration, login, session management, token refresh, password reset, role-based access control, and all the edge cases (expired tokens, concurrent sessions, brute force protection). The output is a detailed design document with flow diagrams, endpoint definitions, data models, and security considerations — ready to hand off to engineering.
Use this when starting a new application, when auditing an existing auth system, or when extending your auth with new features (OAuth, MFA, roles).
Copy this file to .agents/skills/auth-flow-planner/SKILL.md in your project root.
Then ask:
Provide context about:
Add the instructions below to your .cursorrules or paste them into the Cursor AI pane with your application context.
Provide the application context and ask Codex to follow the instructions below to produce the auth design.
When asked to plan an authentication flow, follow these steps:
Gather:
If any of this is unclear, state your assumptions and proceed.
Recommend one of:
Stateless JWT — Good for: API-only services, microservices, when you can't or don't want to maintain session state.
Stateful sessions (server-side) — Good for: traditional web apps, when you need instant revocation, when security > scalability.
Hybrid (recommended for most SaaS) — Short-lived JWT for requests, refresh token stored in session table for revocation control.
For each of the following flows, produce:
Required flows to cover:
If roles are required:
For every flow, verify these protections are designed in:
Brute force protection
Token security
CSRF protection
Password storage
Session fixation
Sensitive operations
# Auth Flow Design — [Application Name]
## Strategy Summary
[2–3 sentences on chosen session approach and why]
## User Roles
| Role | Permissions |
|------|-------------|
| [Role] | [What they can do] |
## Flows
### [Flow Name]
**Purpose**: [What this flow achieves]
**Steps**:
1. [Step 1]
2. [Step 2]
...
**Endpoints**:
- `POST /api/auth/[action]` — Request: `{ field }` — Response: `{ field }`
**Security notes**: [Any specific considerations]
---
[Repeat for each flow]
## Data Models
### users table
| Column | Type | Notes |
|--------|------|-------|
| id | uuid | Primary key |
| email | text | Unique, indexed |
| password_hash | text | bcrypt |
| ...
### sessions / refresh_tokens table
[If stateful]
## Security Checklist
- [ ] Rate limiting on login endpoint
- [ ] Refresh token rotation
- [ ] HttpOnly cookies for refresh token
- [ ] CSRF protection
- [ ] bcrypt for password hashing
- [ ] Re-auth for sensitive operationsInput to Agent:
"Use the Auth Flow Planner skill. Building a SaaS web app with: email/password login, Google OAuth, two roles (admin and member), Node.js/Express backend, React frontend. No MFA for now. Users belong to organizations."
Output from Agent:
# Auth Flow Design — SaaS App
>
## Strategy Summary Hybrid approach: short-lived JWTs (15 min) for authenticated requests, with refresh tokens stored in a database table and delivered via HttpOnly cookie. This allows instant revocation (important for deactivating team members) while keeping request validation stateless.
>
## User Roles
>
| Role | Permissions | |------|-------------| | Owner | Full access to org settings, billing, member management, all features | | Admin | Manage members, all features, no billing access | | Member | Access to product features, no admin settings |
>
## Flows
>
### 1. Registration (Email/Password)
>
Steps: 1. User submits email + password viaPOST /api/auth/register2. Server validates: email format, password strength (min 8 chars), email not already registered 3. Hash password with bcrypt (cost factor 12) 4. Createusersrecord withemail_verified: false5. Create initialorganizationsrecord, set user as Owner 6. Send verification email with a signed token (valid 24h) 7. Return{ message: "Check your email to verify your account" }— do not auto-login before verification
>
Endpoints:POST /api/auth/register—{ email, password, orgName }→{ message }
>
Security notes: Rate limit to 5 registrations per IP per hour. Do not reveal whether an email is already registered (return the same message either way to prevent enumeration).
>
### 2. Login
>
Steps: 1. User submits email + password viaPOST /api/auth/login2. Server looks up user by email; if not found, return generic error (no enumeration) 3. Verify password with bcrypt; if wrong, increment failed attempt counter 4. After 5 failed attempts from same IP in 15 min, return 429 withretryAfter5. Checkemail_verified: true; if not, return 403 with "Please verify your email" 6. Generate access JWT (15 min expiry, payload:{ userId, orgId, role }) 7. Generate refresh token (random 64-byte hex), store inrefresh_tokenstable with expiry 30 days 8. Set refresh token in HttpOnly, Secure, SameSite=Strict cookie 9. Return access token in response body
>
Endpoints:POST /api/auth/login—{ email, password }→{ accessToken, user }
bcrypt, jsonwebtoken, passport, lucia, better-auth, or a managed service like Auth0, Clerk, or Supabase Auth.~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.