auth-ops

Files (9)

• SKILL.md
• .gitkeep · assets/
• authorization.md · references/
• better-auth.md · references/
• cloudflare-access.md · references/
• implementation.md · references/
• jwt-sessions.md · references/
• oauth2-oidc.md · references/
• .gitkeep · scripts/

SKILL.md (first lines)

# Auth Operations

Comprehensive authentication and authorization patterns for secure application development across languages and frameworks.

## Authentication Method Decision Tree

Use this tree to select the right authentication strategy for your use case.

```
What are you building?
│
├─ Traditional web application (server-rendered)?
│  └─ Session-based authentication
│     ├─ Server stores session data (Redis/DB)
│     ├─ Session ID in httpOnly cookie
│     └─ Best for: monoliths, SSR apps, admin panels
│
├─ API consumed by multiple clients?
│  └─ JWT (JSON Web Tokens)
│     ├─ Stateless, self-contained tokens
│     ├─ Access token (short-lived) + refresh token (long-lived)
│     └─ Best for: microservices, mobile apps, SPAs via BFF
│
├─ Service-to-service communication?
│  └─ API keys or Client Credentials (OAuth2)
│     ├─ API keys: simple, scoped, rotatable
│     ├─ Client Credentials: OAuth2 standard, token-based
│     └─ Best for: internal services, third-party integrations
│
├─ Third-party login (Google, GitHub, etc.)?
│  └─ OAuth2 / OpenID Connect
│     ├─ Authorization Code + PKCE for web/mobile
│     ├─ Delegate identity to trusted providers
│     └─ Best for: consumer apps, social login
│
├─ Passwordless authentication?
│  └─ Passkeys (WebAuthn) or Magic Links
│     ├─ Passkeys: phishing-resistant, biometric/hardware
│     ├─ Magic links: email-based, time-limited
│     └─ Best for: high-security, modern UX
│
└─ Internal tool / staff app with an existing IdP?
   └─ Identity-aware proxy (Cloudflare Access)
      ├─ Authn enforced at the edge, before your origin
      ├─ Origin verifies the proxy's signed JWT (never a bare header)
      └─ Best for: admin panels, partner portals, not consumer signup
```

## JWT Quick Reference

### Structure

```
Header.Payload.Signature

Header:  { "alg": "RS256", "typ": "JWT" }
Payload: { "iss": "auth.example.com", "sub": "user_123", ... }
Signature: RSASHA256(base64(header) + "." + base64(payload), privateKey)
```

### Common Claims

| Claim | Name | Purpose | Example |
|-------|------|---------|---------|
| `iss` | Issuer | Who issued the token | `"auth.example.com"` |
| `sub` | Subject | Who the token represents | `"user_123"` |
| `exp` | Expiration | When the token expires | `1700000000` (Unix timestamp) |
| `iat` | Issued At | When the token was created | `1699999100` |
| `aud` | Audience | Intended recipient(s) | `"api.example.com"` |
| `jti` | JWT ID | Unique token identifier | `"a1b2c3d4"` (for revocation) |
| `nbf` | Not Before | Token not valid before this time | `1699999100` |

### Signing Algorithms

| Algorithm | Type | Key | Use When |
|-----------|------|-----|----------|
| **RS256** | Asymmetric (RSA) | Public/private key pair | Distributed systems, multiple verifiers |
| **ES256** | Asymmetric (ECDSA) | Public/private key pair | Same as RS256, smaller keys/signatures |
| **HS256** | Symmetric (HMAC) | Shared secret | Single service, simple setups |

**Rule of thumb:** Use asymmetric (RS256/ES256) when the token issuer and verifier are different services. Use HS256 only when a single service both creates and verifies tokens.

### Access + Refresh Token Pattern

```
┌──────────┐                    ┌──────────┐
│  Client   │─── login ────────>│  Auth    │
│           │<── access (15m) ──│  Server  │
│           │<── refresh (7d) ──│          │
│           │                   └──────────┘
│           │─── API call ─────>┌──────────┐
│           │    (access token) │ Resource │
│           │<── response ──────│  Server  │
│           │                   └──────────┘
│           │─── access expired │          │
│           │─── refresh ──────>│  Auth    │
│           │<── new access ────│  Server  │
│           │<── new refresh ───│  (rotate)│
└──────────┘                    └──────────┘
```

- **Access token:** Short-lived (5-15 minutes), used for API calls
- **Refresh token:** Long-lived (7-30 days), used to get new access tokens
- **Rotation:** Issue a new refresh token with each use, invalidate the old one
- **Family detection:** Track refresh token lineage; if a revoked token is reused, invalidate the entire family

## OAuth2 Flow Decision Tree

```
What type of client?
│
├─ Web app with backend (Next.js, Rails, Django)?
│  └─ Authorization Code + PKCE
│     ├─ Redirect user to authorization server
│     ├─ Receive code at callback URL
│     ├─ Exchange code for tokens server-side
│     └─ PKCE prevents code interception attacks
│
├─ SPA (React, Vue) without backend?

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods