{"id":"d5b532d6-1a9c-4973-8f5c-bfb1308d95d6","shortId":"MkKmVZ","kind":"skill","title":"Auth Flow Planner","tagline":"Designs a secure authentication and authorization flow for any application, covering login, sessions, roles, and edge cases.","description":"# Auth Flow Planner\n\n## What this skill does\n\nThis 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.\n\nUse this when starting a new application, when auditing an existing auth system, or when extending your auth with new features (OAuth, MFA, roles).\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/auth-flow-planner/SKILL.md` in your project root.\n\nThen ask:\n- *\"Use the Auth Flow Planner skill to design auth for our SaaS app.\"*\n- *\"Plan the authentication system for a multi-tenant API using the Auth Flow Planner skill.\"*\n\nProvide context about:\n- Application type (web app, mobile app, API-only, SaaS)\n- User types (end users, admins, API consumers)\n- Required features (social login, MFA, teams/orgs, API keys)\n- Tech stack (language, framework, existing auth libraries)\n- Compliance requirements if any (HIPAA, SOC2, GDPR)\n\n### Cursor\n\nAdd the instructions below to your `.cursorrules` or paste them into the Cursor AI pane with your application context.\n\n### Codex\n\nProvide the application context and ask Codex to follow the instructions below to produce the auth design.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to plan an authentication flow, follow these steps:\n\n### Step 1 — Understand requirements\n\nGather:\n- What user types need to authenticate?\n- What needs to be protected (API routes, pages, data scopes)?\n- What auth methods are needed (email/password, OAuth, magic link, API key, MFA)?\n- What session approach: stateless JWT, stateful sessions (DB/Redis), or both?\n- Are there multiple roles or permission levels?\n- Are there multi-tenant concerns (organizations, workspaces)?\n\nIf any of this is unclear, state your assumptions and proceed.\n\n### Step 2 — Choose and justify the session strategy\n\nRecommend one of:\n\n**Stateless JWT** — Good for: API-only services, microservices, when you can't or don't want to maintain session state.\n- Access token: short-lived (15 min), stored in memory (web) or secure storage (mobile)\n- Refresh token: longer-lived (7–30 days), stored in HttpOnly cookie (web) or secure storage (mobile)\n- Revocation requires a blocklist for the refresh token\n\n**Stateful sessions (server-side)** — Good for: traditional web apps, when you need instant revocation, when security > scalability.\n- Session ID in HttpOnly cookie\n- Session data stored in DB or Redis\n- Easy to revoke; requires session store\n\n**Hybrid (recommended for most SaaS)** — Short-lived JWT for requests, refresh token stored in session table for revocation control.\n\n### Step 3 — Design each flow\n\nFor each of the following flows, produce:\n- A numbered step-by-step description\n- The HTTP endpoints involved (method, path, request body, response)\n- What is stored and where\n- Security considerations\n\n**Required flows to cover:**\n1. User registration\n2. Email verification\n3. Login (email/password)\n4. Authenticated request (how the access token is validated)\n5. Token refresh\n6. Logout\n7. Password reset request\n8. Password reset completion\n9. OAuth login (if applicable)\n10. API key authentication (if applicable)\n\n### Step 4 — Design the RBAC model\n\nIf roles are required:\n- Define the roles and what each can do\n- Where role is stored (user record, JWT claim, permission table)\n- How authorization checks are applied (middleware, policy layer, row-level)\n\n### Step 5 — Security checklist\n\nFor every flow, verify these protections are designed in:\n\n**Brute force protection**\n- Rate limit login attempts per IP (e.g., 5 attempts per 15 minutes)\n- Rate limit password reset requests per email\n\n**Token security**\n- Access tokens expire quickly (15 minutes recommended)\n- Refresh tokens are one-time-use (rotation) or carefully protected\n- Tokens are never stored in localStorage (XSS risk)\n- Refresh tokens in HttpOnly, Secure, SameSite=Strict cookies\n\n**CSRF protection**\n- If using cookies for session/refresh token: require CSRF token or use SameSite=Strict\n\n**Password storage**\n- bcrypt, scrypt, or Argon2 — never MD5/SHA1/unsalted hashes\n- Minimum cost factor appropriate for the hardware\n\n**Session fixation**\n- Issue a new session ID / refresh token after each login\n\n**Sensitive operations**\n- Re-authentication required for: changing email, changing password, deleting account, viewing billing info\n\n### Step 6 — Format the output\n\n```markdown\n# Auth Flow Design — [Application Name]\n\n## Strategy Summary\n[2–3 sentences on chosen session approach and why]\n\n## User Roles\n| Role | Permissions |\n|------|-------------|\n| [Role] | [What they can do] |\n\n## Flows\n\n### [Flow Name]\n**Purpose**: [What this flow achieves]\n\n**Steps**:\n1. [Step 1]\n2. [Step 2]\n...\n\n**Endpoints**:\n- `POST /api/auth/[action]` — Request: `{ field }` — Response: `{ field }`\n\n**Security notes**: [Any specific considerations]\n\n---\n\n[Repeat for each flow]\n\n## Data Models\n\n### users table\n| Column | Type | Notes |\n|--------|------|-------|\n| id | uuid | Primary key |\n| email | text | Unique, indexed |\n| password_hash | text | bcrypt |\n| ...\n\n### sessions / refresh_tokens table\n[If stateful]\n\n## Security Checklist\n- [ ] Rate limiting on login endpoint\n- [ ] Refresh token rotation\n- [ ] HttpOnly cookies for refresh token\n- [ ] CSRF protection\n- [ ] bcrypt for password hashing\n- [ ] Re-auth for sensitive operations\n```\n\n## Example\n\n**Input to Agent:**\n> \"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.\"\n\n**Output from Agent:**\n\n> # Auth Flow Design — SaaS App\n>\n> ## Strategy Summary\n> 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.\n>\n> ## User Roles\n>\n> | Role | Permissions |\n> |------|-------------|\n> | Owner | Full access to org settings, billing, member management, all features |\n> | Admin | Manage members, all features, no billing access |\n> | Member | Access to product features, no admin settings |\n>\n> ## Flows\n>\n> ### 1. Registration (Email/Password)\n>\n> **Steps**:\n> 1. User submits email + password via `POST /api/auth/register`\n> 2. Server validates: email format, password strength (min 8 chars), email not already registered\n> 3. Hash password with bcrypt (cost factor 12)\n> 4. Create `users` record with `email_verified: false`\n> 5. Create initial `organizations` record, set user as Owner\n> 6. Send verification email with a signed token (valid 24h)\n> 7. Return `{ message: \"Check your email to verify your account\" }` — do not auto-login before verification\n>\n> **Endpoints**: `POST /api/auth/register` — `{ email, password, orgName }` → `{ message }`\n>\n> **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).\n>\n> ### 2. Login\n>\n> **Steps**:\n> 1. User submits email + password via `POST /api/auth/login`\n> 2. Server looks up user by email; if not found, return generic error (no enumeration)\n> 3. Verify password with bcrypt; if wrong, increment failed attempt counter\n> 4. After 5 failed attempts from same IP in 15 min, return 429 with `retryAfter`\n> 5. Check `email_verified: true`; if not, return 403 with \"Please verify your email\"\n> 6. Generate access JWT (15 min expiry, payload: `{ userId, orgId, role }`)\n> 7. Generate refresh token (random 64-byte hex), store in `refresh_tokens` table with expiry 30 days\n> 8. Set refresh token in HttpOnly, Secure, SameSite=Strict cookie\n> 9. Return access token in response body\n>\n> **Endpoints**: `POST /api/auth/login` — `{ email, password }` → `{ accessToken, user }`\n\n## Notes\n\n- This skill designs the auth system. Implementation is a separate step — use this document as the spec.\n- If you have an existing auth system, describe it and ask the skill to identify gaps rather than design from scratch.\n- Never roll your own crypto primitives. Use established libraries: `bcrypt`, `jsonwebtoken`, `passport`, `lucia`, `better-auth`, or a managed service like Auth0, Clerk, or Supabase Auth.","tags":["auth","flow","planner","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor","llm"],"capabilities":["skill","source-notysoty","skill-auth-flow-planner","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-cline","topic-cursor","topic-llm","topic-llm-skills","topic-skills"],"categories":["openagentskills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Notysoty/openagentskills/auth-flow-planner","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Notysoty/openagentskills","source_repo":"https://github.com/Notysoty/openagentskills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (8,631 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:20.545Z","embedding":null,"createdAt":"2026-05-18T13:20:40.931Z","updatedAt":"2026-05-18T19:13:20.545Z","lastSeenAt":"2026-05-18T19:13:20.545Z","tsv":"'/api/auth':754 '/api/auth/login':1064,1167 '/api/auth/register':951,1020 '/express':848 '1':260,495,746,748,940,944,1057 '10':531 '12':973 '15':365,602,617,876,1100,1124 '2':329,498,719,749,751,952,1054,1065 '24h':1000 '3':457,501,720,966,1080 '30':381,1146 '4':504,538,974,1091 '403':1114 '429':1103 '5':513,577,599,982,1030,1093,1106 '6':516,707,991,1120 '64':1136 '7':380,518,1001,1131 '8':522,960,1148 '9':526,1158 'access':56,360,509,613,914,930,932,1122,1160 'accesstoken':1170 'account':702,1010 'achiev':744 'action':755 'add':206 'admin':180,843,923,937 'agent':248,824,862 'agents/skills/auth-flow-planner/skill.md':127 'ai':219 'allow':895 'alreadi':964,1043 'api':156,173,181,189,275,289,344,532 'api-on':172,343 'app':146,169,171,409,835,867 'appli':569 'applic':13,39,99,166,223,228,530,536,715 'approach':294,725,871 'appropri':674 'argon2':667 'ask':133,231,250,1200 'assumpt':325 'attempt':595,600,1089,1095 'audit':101 'auth':1,21,104,110,136,142,159,196,241,281,712,817,827,863,1177,1195,1226,1236 'auth0':1232 'authent':7,33,149,254,269,505,534,694,879 'author':9,35,566 'auto':1014 'auto-login':1013 'backend':849 'base':55 'bcrypt':664,787,811,970,1084,1220 'belong':857 'better':1225 'better-auth':1224 'bill':704,918,929 'blocklist':395 'bodi':482,1164 'brute':67,589 'build':831 'byte':1137 'care':629 'case':20,62 'chang':697,699 'char':961 'check':567,1004,1107 'checklist':579,795 'choos':330 'chosen':723 'claim':562 'claud':120 'clerk':1233 'cline':122 'code':121 'codex':225,232 'column':773 'complet':32,525 'complianc':198 'concern':314 'concurr':65 'consider':86,490,764 'consum':182 'context':164,224,229 'control':57,455 'cooki':386,422,646,651,805,893,1157 'copi':123 'cost':672,971 'counter':1090 'cover':14,41,494 'creat':975,983 'crypto':1215 'csrf':647,656,809 'cursor':205,218 'cursorrul':212 'data':82,278,424,769 'databas':887 'day':382,1147 'db':427 'db/redis':299 'deactiv':900 'defin':547 'definit':81 'delet':701 'deliv':890 'describ':1197 'descript':474 'design':4,30,75,141,242,458,539,587,714,865,1175,1208 'detail':74 'diagram':79 'document':76,1186 'e.g':598 'easi':430 'edg':19,61 'either':1049 'email':499,610,698,780,947,955,962,979,994,1006,1021,1041,1060,1071,1108,1119,1168 'email/password':285,503,837,942 'end':178 'endpoint':80,477,752,800,1018,1165 'engin':92 'enumer':1053,1079 'error':1077 'establish':1218 'everi':581 'exampl':821 'exist':103,195,1194 'expir':63,615 'expiri':1126,1145 'extend':108 'factor':673,972 'fail':1088,1094 'fals':981 'featur':113,184,922,927,935 'field':757,759 'file':125 'fixat':679 'flow':2,10,22,36,78,137,160,255,460,466,492,582,713,737,738,743,768,828,864,939 'follow':234,256,465 'forc':68,590 'format':708,956 'found':1074 'framework':194 'frontend':851 'full':43,913 'gap':1205 'gather':263 'gdpr':204 'generat':1121,1132 'generic':1076 'good':341,405 'googl':839 'hand':89 'hardwar':677 'hash':670,785,814,967 'hex':1138 'hipaa':202 'hour':1035 'http':476 'httpon':385,421,642,804,892,1153 'hybrid':436,870 'id':419,684,776 'identifi':1204 'implement':1179 'import':898 'increment':1087 'index':783 'info':705 'initi':984 'input':822 'instant':413,896 'instruct':208,236,245 'involv':478 'ip':597,1033,1098 'issu':680 'jsonwebtoken':1221 'justifi':332 'jwt':296,340,444,561,1123 'jwts':875 'keep':904 'key':190,290,533,779 'languag':193 'layer':572 'level':308,575 'librari':197,1219 'lifecycl':44 'like':1231 'limit':593,605,797,1028 'link':288 'live':364,379,443,874 'localstorag':636 'login':15,46,186,502,528,594,689,799,838,1015,1055 'logout':517 'longer':378 'longer-liv':377 'look':1067 'lucia':1223 'magic':287 'maintain':357 'manag':48,920,924,1229 'markdown':711 'md5/sha1/unsalted':669 'member':845,902,919,925,931 'memori':369 'messag':1003,1024,1048 'method':282,479 'mfa':115,187,291,853 'microservic':347 'middlewar':570 'min':366,877,959,1101,1125 'minimum':671 'minut':603,618 'mobil':170,374,391 'model':83,542,770 'multi':154,312 'multi-ten':153,311 'multipl':304 'name':716,739 'need':267,271,284,412 'never':633,668,1211 'new':98,112,682 'node.js':847 'node.js/express':846 'note':761,775,1026,1172 'number':469 'oauth':114,286,527,840 'one':337,624 'one-time-us':623 'oper':691,820 'org':916 'organ':315,859,985 'orgid':1129 'orgnam':1023 'output':71,710,860 'owner':912,990 'page':277 'pane':220 'passport':1222 'password':51,519,523,606,662,700,784,813,948,957,968,1022,1061,1082,1169 'past':214 'path':480 'payload':1127 'per':596,601,609,1032,1034 'permiss':307,563,731,911 'plan':147,252 'planner':3,23,138,161,829 'pleas':1116 'polici':571 'post':753,950,1019,1063,1166 'prevent':1052 'primari':778 'primit':1216 'proceed':327 'produc':239,467 'product':934 'project':130 'prompt':244 'protect':69,274,585,591,630,648,810 'provid':163,226 'purpos':740 'quick':616 'random':1135 'rate':592,604,796,1027 'rather':1206 'rbac':541 're':693,816 're-auth':815 're-authent':692 'react':850 'readi':87 'recommend':336,437,619 'record':560,977,986 'redi':429 'refresh':50,375,398,447,515,620,639,685,789,801,807,882,1133,1141,1150 'regist':965,1044 'registr':45,497,941,1031 'repeat':765 'request':446,481,506,521,608,756,880,905 'requir':183,199,262,393,433,491,546,655,695 'reset':52,520,524,607 'respons':483,758,1163 'retryaft':1105 'return':1002,1045,1075,1102,1113,1159 'reveal':1038 'revoc':392,414,454,897 'revok':432 'risk':638 'role':17,54,116,305,544,549,556,729,730,732,842,909,910,1130 'role-bas':53 'roll':1212 'root':131 'rotat':627,803 'rout':276 'row':574 'row-level':573 'saa':145,175,440,833,866 'samesit':644,660,1155 'scalabl':417 'scope':279 'scratch':1210 'scrypt':665 'secur':6,85,372,389,416,489,578,612,643,760,794,1025,1154 'send':992 'sensit':690,819 'sentenc':721 'separ':1182 'server':403,953,1066 'server-sid':402 'servic':346,1230 'session':16,47,66,293,298,334,358,401,418,423,434,451,678,683,724,788 'session/refresh':653 'set':917,938,987,1149 'short':363,442,873 'short-liv':362,441,872 'side':404 'sign':997 'skill':26,29,139,162,830,1174,1202 'skill-auth-flow-planner' 'soc2':203 'social':185 'source-notysoty' 'spec':1189 'specif':763 'stack':192 'start':96 'state':297,323,359,400,793 'stateless':295,339,907 'step':258,259,328,456,471,473,537,576,706,745,747,750,943,1056,1183 'step-by-step':470 'storag':373,390,663 'store':367,383,425,435,449,486,558,634,884,1139 'strategi':335,717,868 'strength':958 'strict':645,661,1156 'submit':946,1059 'summari':718,869 'supabas':1235 'system':105,150,1178,1196 'tabl':452,564,772,791,888,1143 'team':901 'teams/orgs':188 'tech':191 'tenant':155,313 'text':781,786 'time':625 'token':49,64,361,376,399,448,510,514,611,614,621,631,640,654,657,686,790,802,808,883,998,1134,1142,1151,1161 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'tradit':407 'true':1110 'two':841 'type':167,177,266,774 'unclear':322 'understand':261 'uniqu':782 'use':93,119,134,157,626,650,659,825,1184,1217 'user':176,179,265,496,559,728,771,856,908,945,976,988,1058,1069,1171 'userid':1128 'uuid':777 'valid':512,906,954,999 'verif':500,993,1017 'verifi':583,980,1008,1081,1109,1117 'via':891,949,1062 'view':703 'want':355 'way':1050 'web':168,370,387,408,834 'whether':1039 'workspac':316 'wrong':1086 'xss':637","prices":[{"id":"26d46410-9887-4f63-bb3e-5da7ae0a39ef","listingId":"d5b532d6-1a9c-4973-8f5c-bfb1308d95d6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Notysoty","category":"openagentskills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:40.931Z"}],"sources":[{"listingId":"d5b532d6-1a9c-4973-8f5c-bfb1308d95d6","source":"github","sourceId":"Notysoty/openagentskills/auth-flow-planner","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/auth-flow-planner","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:40.931Z","lastSeenAt":"2026-05-18T19:13:20.545Z"}],"details":{"listingId":"d5b532d6-1a9c-4973-8f5c-bfb1308d95d6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"auth-flow-planner","github":{"repo":"Notysoty/openagentskills","stars":8,"topics":["agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills","skills"],"license":"mit","html_url":"https://github.com/Notysoty/openagentskills","pushed_at":"2026-03-28T06:50:19Z","description":"A  community-driven library of reusable AI agent skills for Claude Code, Cursor, Codex, Cline, and more.","skill_md_sha":"5ecf2099d46b915bdde21cca85938b21255f0989","skill_md_path":"skills/auth-flow-planner/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/auth-flow-planner"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Auth Flow Planner","description":"Designs a secure authentication and authorization flow for any application, covering login, sessions, roles, and edge cases."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/auth-flow-planner"},"updatedAt":"2026-05-18T19:13:20.545Z"}}