Auth

Documentation-Only Skill

This skill is a reference guide. It contains code examples that demonstrate authentication patterns.

Important: The code examples in this skill:

• Are templates for developers to adapt
• Show placeholder values (SECRET, API_KEY, etc.)
• Reference external services as examples only
• Are NOT executed by the agent

The agent provides guidance. The developer implements in their own project.

When to Use

User needs guidance on implementing authentication. Agent explains patterns for login flows, token strategies, password security, OAuth integration, and session management.

Quick Reference

Topic	File
Session vs JWT strategies	strategies.md
Password handling	passwords.md
MFA implementation	mfa.md
OAuth and social login	oauth.md
Framework middleware	middleware.md

Scope

This skill ONLY:

• Explains authentication concepts
• Shows code patterns as examples
• Provides best practice guidance

This skill NEVER:

• Executes code
• Makes network requests
• Accesses credentials
• Stores data
• Reads environment variables

Note on Code Examples

Code examples in auxiliary files show:

• Environment variables like process.env.JWT_SECRET - these are placeholders
• API calls to OAuth providers - these are reference patterns
• Secrets like SECRET, REFRESH_SECRET - these are example names

The agent does not have access to these values. They demonstrate what the developer should configure in their own project.

Core Rules

1. Auth vs Authorization

• Authentication: Who you are (this skill)
• Authorization: What you can do (different concern)
• Auth happens FIRST, then authorization checks permissions

2. Choose the Right Strategy

Use Case	Strategy	Why
Traditional web app	Sessions + cookies	Simple, instant revocation
Mobile app	JWT (short-lived) + refresh token	No cookies, offline support
API/microservices	JWT	Stateless, scalable
Enterprise	SSO (SAML/OIDC)	Central identity management
Consumer	Social login + email fallback	Reduced friction

3. Never Roll Your Own Crypto

• Use bcrypt (cost 12) or Argon2id for passwords
• Use battle-tested libraries for JWT, OAuth
• Never implement password hashing, token signing manually
• Never store plaintext or reversibly encrypted passwords

4. Defense in Depth

Rate limiting -> CAPTCHA -> Account lockout -> MFA -> Audit logging

5. Secure by Default

• httpOnly + Secure + SameSite=Lax for cookies
• Short token lifetimes (15min access, 7d refresh)
• Regenerate session ID on login
• Require re-auth for sensitive operations

6. Fail Securely

// Bad - reveals if email exists
if (!user) return { error: 'User not found' };

// Good - same error for both cases
if (!user || !validPassword) {
  return { error: 'Invalid credentials' };
}

7. Log Everything (Except Secrets)

Log	Do Not Log
Login success/failure	Passwords
IP, user agent, timestamp	Tokens
MFA events	Session IDs
Password changes	Recovery codes

Common Traps

• Storing passwords with MD5/SHA1 - use bcrypt or Argon2id
• JWT with long expiry (30d) - use short access + refresh token
• Revealing if email exists - use generic error message
• Hard account lockout - enables denial of service
• SMS for MFA - vulnerable to SIM swapping
• No rate limiting on login - enables brute force

Feedback

• If useful: clawhub star auth
• Stay updated: clawhub sync