Auth

Build secure authentication with sessions, JWT, OAuth, passwordless, MFA, and SSO for web and mobile apps.

Security Scan

This is a documentation-only reference for implementing authentication patterns; its requirements and instructions are consistent with that purpose and it does not request credentials or install code.

Purpose & Capability

Name/description (authentication patterns: sessions, JWT, OAuth, MFA, SSO) matches the content: extensive example code and design guidance. No unexpected binaries, env vars, or secrets are requested by the skill metadata.

Instruction Scope

SKILL.md and auxiliary files are explicit that examples are reference-only, not executed, and that the agent should not access credentials, make network calls, or read environment variables. The examples show network calls and env-var placeholders, which is expected for a developer reference and do not indicate hidden runtime actions.

Install Mechanism

No install spec and no code files that would be written/executed on the host. Lowest-risk form (instruction-only).

Credentials

The skill declares no required environment variables or credentials. Example snippets reference placeholders like process.env.JWT_SECRET, but these are documented as developer-side placeholders and not requested by the skill itself.

Persistence & Privilege

Skill is not always-enabled and does not request persistent privileges or modify other skills/config. Model-invocation is allowed (platform default) but the skill has no autonomy-sensitive artifacts to act on.

Assessment

This is a documentation/reference skill — safe to install from a capability perspective. Important cautions: do not paste real secrets (API keys, private keys, JWT secrets) into chat when asking for help; treat code snippets as templates and review/adapt them before copying into production (verify token handling, encryption, storage and network calls). The skill itself does not request credentials or execute code, but any code you implement from the examples will run in your environment and must be secured accordingly.

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