lucia-auth

name	lucia-auth
description	Implement authentication following Lucia Auth best practices. Use when users ask to "add auth", "implement authentication", "setup login", "add sessions", "implement OAuth", "add 2FA/MFA", "password hashing", or reference "lucia auth" or "copenhagen book" patterns.

Lucia Auth

Implements secure authentication following the patterns from Lucia Auth and The Copenhagen Book.

How It Works

1. Identify what type of authentication the user needs
2. Read the relevant reference documentation
3. Use the provided templates as a starting point
4. Adapt the templates to the user's framework and database

Decision Tree

When a user asks for authentication, determine which components they need:

Basic Auth (Username/Password)

• Read: references/copenhagen-book/password-authentication.md
• Read: references/copenhagen-book/sessions.md
• Read: references/lucia/sessions-basic.md
• Templates: assets/password-utils.ts, assets/session-manager.ts, assets/session-schema.sql

OAuth (Social Login)

• Read: references/copenhagen-book/oauth.md
• Read: references/lucia/tutorial-github-oauth.md or tutorial-google-oauth.md
• Templates: assets/oauth-handler.ts

Email Verification

• Read: references/copenhagen-book/email-verification.md
• Templates: assets/email-verification.ts

Multi-Factor Authentication (MFA/2FA)

• Read: references/copenhagen-book/mfa.md
• For TOTP: Templates: assets/totp-mfa.ts
• For WebAuthn: Read: references/copenhagen-book/webauthn.md

Session Management Only

• Read: references/lucia/sessions-overview.md
• Read: references/lucia/sessions-basic.md
• Read: references/lucia/sessions-inactivity-timeout.md
• Templates: assets/session-manager.ts

Security Concerns

• CSRF: Read: references/copenhagen-book/csrf.md
• Rate Limiting: Read: references/lucia/rate-limit-token-bucket.md
• Password Reset: Read: references/copenhagen-book/password-reset.md

Key Security Principles

Always follow these principles when implementing auth:

Passwords

• Hash with Argon2id (or Scrypt/Bcrypt as fallbacks)
• Minimum 8 characters, no artificial maximum under 64
• Check against haveibeenpwned for compromised passwords
• Use constant-time comparison

Sessions

• Generate IDs with 120+ bits of entropy using crypto.getRandomValues()
• Store secret hash, not the raw secret
• Set HttpOnly, Secure, SameSite=Lax cookies
• Implement sliding expiration for user-friendly apps
• Invalidate all sessions on password change

OAuth

• Always use PKCE (code_challenge with S256)
• Store state in HttpOnly cookies
• Verify state on callback
• Link accounts by verified email only

General

• Never trust client-provided data
• Implement rate limiting on all auth endpoints
• Use generic error messages ("Incorrect username or password")
• Verify CSRF tokens on state-changing operations

Template Usage

The templates in assets/ are framework-agnostic TypeScript. When using them:

1. Adapt the database interface to match the user's ORM/driver
2. Adjust cookie handling for the user's framework
3. Keep the core security logic unchanged
4. Add any framework-specific middleware

When to Read Full References

Read the full reference documentation when:

• The user has specific questions about security tradeoffs
• Implementing edge cases (stateless tokens, sudo mode, etc.)
• The user explicitly asks about best practices
• You need to understand the "why" behind a pattern

Example Scenarios

User asks: "Add authentication to my Express app"

1. Ask if they need OAuth, password auth, or both
2. Read relevant references based on their choice
3. Create session table migration
4. Implement password hashing with assets/password-utils.ts
5. Implement session management with assets/session-manager.ts
6. Add login/logout/register routes
7. Add session middleware

User asks: "Add Google OAuth"

1. Read references/copenhagen-book/oauth.md
2. Use assets/oauth-handler.ts as base
3. Create routes: GET /auth/google, GET /auth/google/callback
4. Implement user creation/linking on callback
5. Create session after successful OAuth

User asks: "Add 2FA to existing auth"

1. Read references/copenhagen-book/mfa.md
2. Use assets/totp-mfa.ts
3. Add TOTP secret column to user table
4. Create setup flow (generate secret, show QR, verify)
5. Add 2FA check to login flow
6. Generate and store hashed recovery codes

Updating Resources

The reference documentation can be updated by running:

./scripts/fetch-resources.sh

Check references/VERSION.md for current source versions.