agent-skill-kit 3.9.135

package/.agent/skills/auth-patterns/rules/jwt-deep.md

@@ -0,0 +1,196 @@
+---
+name: jwt-deep
+description: JWT signing, rotation, claims, refresh token patterns, JWKS endpoint
+title: "JWT Deep Dive"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: jwt, deep
+---
+
+# JWT Deep Dive
+
+> Token design, signing, rotation, and refresh patterns.
+
+---
+
+## JWT Structure
+
+```
+Header.Payload.Signature
+```
+
+| Part | Contains | Example |
+|------|----------|---------|
+| Header | Algorithm, type | `{"alg": "RS256", "typ": "JWT"}` |
+| Payload | Claims (data) | `{"sub": "user123", "exp": 1700000000}` |
+| Signature | Verification | HMAC or RSA signature |
+
+---
+
+## Signing Algorithms
+
+| Algorithm | Type | Best For |
+|-----------|------|----------|
+| `RS256` | Asymmetric (RSA) | Microservices (verify without secret) |
+| `ES256` | Asymmetric (ECDSA) | Mobile, performance-sensitive |
+| `HS256` | Symmetric (HMAC) | Monolith (single service) |
+| `EdDSA` | Asymmetric (Ed25519) | Modern, fastest asymmetric |
+
+> **Rule:** Use asymmetric for distributed systems. Symmetric only for single-service.
+
+---
+
+## Claims Best Practices
+
+### Standard Claims (use these)
+
+| Claim | Purpose | Required? |
+|-------|---------|-----------|
+| `sub` | Subject (user ID) | ✅ |
+| `iss` | Issuer | ✅ |
+| `aud` | Audience | ✅ |
+| `exp` | Expiry (Unix timestamp) | ✅ |
+| `iat` | Issued at | ✅ |
+| `jti` | JWT ID (unique) | For revocation |
+
+### Custom Claims
+
+```typescript
+// ✅ Minimal claims
+{
+  sub: "user_abc123",
+  role: "admin",        // For quick authz checks
+  org: "org_xyz",       // Multi-tenant
+  scope: "read write",  // API permissions
+}
+
+// ❌ Too much data
+{
+  sub: "user_abc123",
+  email: "user@example.com",  // PII in token
+  address: "...",              // Never store PII
+  fullProfile: {...},          // Token too large
+}
+```
+
+---
+
+## Access + Refresh Token Pattern
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│    Client    │     │  Auth Server │     │   Resource   │
+└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
+       │  Login             │                    │
+       │───────────────────>│                    │
+       │  Access (15min)    │                    │
+       │  + Refresh (7d)    │                    │
+       │<───────────────────│                    │
+       │                    │                    │
+       │  API call + Access Token                │
+       │────────────────────────────────────────>│
+       │  Response                               │
+       │<────────────────────────────────────────│
+       │                    │                    │
+       │  (Access expired)  │                    │
+       │  Refresh request   │                    │
+       │───────────────────>│                    │
+       │  New Access        │                    │
+       │  + New Refresh     │ (rotation!)        │
+       │<───────────────────│                    │
+```
+
+### Implementation
+
+```typescript
+// Token generation
+function generateTokenPair(userId: string) {
+  const accessToken = jwt.sign(
+    { sub: userId, type: 'access' },
+    ACCESS_SECRET,
+    { expiresIn: '15m', algorithm: 'RS256' }
+  );
+
+  const refreshToken = jwt.sign(
+    { sub: userId, type: 'refresh', jti: crypto.randomUUID() },
+    REFRESH_SECRET,
+    { expiresIn: '7d', algorithm: 'RS256' }
+  );
+
+  return { accessToken, refreshToken };
+}
+
+// Refresh endpoint
+async function refreshTokens(oldRefreshToken: string) {
+  const payload = jwt.verify(oldRefreshToken, REFRESH_PUBLIC_KEY);
+
+  // Check if token was already used (rotation detection)
+  const isUsed = await redis.get(`used_refresh:${payload.jti}`);
+  if (isUsed) {
+    // Token reuse detected → compromise! Revoke all user sessions
+    await revokeAllSessions(payload.sub);
+    throw new SecurityError('Refresh token reuse detected');
+  }
+
+  // Mark old token as used
+  await redis.setex(`used_refresh:${payload.jti}`, 7 * 86400, '1');
+
+  return generateTokenPair(payload.sub);
+}
+```
+
+---
+
+## Key Rotation
+
+### Why Rotate
+
+- Limit blast radius of key compromise
+- Compliance requirements (SOC 2, PCI)
+
+### JWKS Endpoint Pattern
+
+```typescript
+// /.well-known/jwks.json
+{
+  "keys": [
+    { "kid": "key-2025-01", "kty": "RSA", "use": "sig", ... },  // Current
+    { "kid": "key-2024-07", "kty": "RSA", "use": "sig", ... }   // Previous (grace period)
+  ]
+}
+```
+
+### Rotation Schedule
+
+| Environment | Frequency | Grace Period |
+|-------------|-----------|--------------|
+| Production | Every 90 days | 30 days overlap |
+| High security | Every 30 days | 14 days overlap |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|------|
+| Store JWT in localStorage | httpOnly secure cookie |
+| Long-lived access tokens | 15 min max + refresh |
+| Put PII in claims | Minimal claims, lookup from DB |
+| Same key for all environments | Per-env signing keys |
+| Skip `exp` validation | Always check expiry |
+| Trust JWT without signature check | Always verify signature |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [oauth2.md](oauth2.md) | OAuth2 flows that issue JWTs |
+| [session.md](session.md) | Stateful alternative to JWT |
+| [rbac-abac.md](rbac-abac.md) | Permission claims in JWT |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/auth-patterns/rules/mfa.md

@@ -0,0 +1,174 @@
+---
+name: mfa
+description: Multi-factor authentication — TOTP setup, backup codes, WebAuthn for MFA, recovery flows
+title: "Multi-Factor Authentication (MFA)"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: mfa
+---
+
+# Multi-Factor Authentication (MFA)
+
+> TOTP, WebAuthn, backup codes, and recovery flows.
+> **See also:** `security-scanner/auth-patterns.md` for TOTP code pattern and account lockout.
+
+---
+
+## MFA Strategy Selection
+
+| Method | Security | UX | Best For |
+|--------|----------|-----|---------|
+| TOTP (authenticator app) | ★★★★ | ★★★ | General purpose |
+| WebAuthn / Passkey | ★★★★★ | ★★★★ | Modern apps |
+| SMS OTP | ★★ | ★★★★ | Legacy, low-risk |
+| Email OTP | ★★ | ★★★ | Fallback only |
+| Hardware key (YubiKey) | ★★★★★ | ★★ | High security |
+
+> ⚠️ **SMS OTP is vulnerable to SIM swapping.** Avoid for high-value targets.
+
+---
+
+## TOTP Implementation
+
+> **Reference:** See `security-scanner/auth-patterns.md` for base TOTP code pattern.
+
+### Enhanced Setup Flow
+
+```typescript
+import { authenticator } from 'otplib';
+import qrcode from 'qrcode';
+
+async function enableMFA(userId: string) {
+  // 1. Generate secret
+  const secret = authenticator.generateSecret();
+
+  // 2. Create otpauth URI
+  const otpauthUrl = authenticator.keyuri(
+    user.email,
+    'YourApp',
+    secret
+  );
+
+  // 3. Generate QR code
+  const qrDataUrl = await qrcode.toDataURL(otpauthUrl);
+
+  // 4. Store secret (encrypted) — NOT active yet
+  await db.user.update({
+    where: { id: userId },
+    data: { mfaSecret: encrypt(secret), mfaPending: true },
+  });
+
+  // 5. Generate backup codes
+  const backupCodes = generateBackupCodes(10);
+  await storeBackupCodes(userId, backupCodes);
+
+  return { qrDataUrl, backupCodes };
+}
+
+// 6. Verify first code to activate
+async function confirmMFA(userId: string, code: string) {
+  const secret = decrypt(user.mfaSecret);
+  const isValid = authenticator.verify({ token: code, secret });
+
+  if (!isValid) throw new InvalidCodeError();
+
+  await db.user.update({
+    where: { id: userId },
+    data: { mfaEnabled: true, mfaPending: false },
+  });
+}
+```
+
+### Backup Codes
+
+```typescript
+function generateBackupCodes(count: number = 10): string[] {
+  return Array.from({ length: count }, () =>
+    crypto.randomBytes(4).toString('hex') // 8-char codes
+  );
+}
+
+async function storeBackupCodes(userId: string, codes: string[]) {
+  // Hash each code before storing
+  const hashed = codes.map(code => ({
+    userId,
+    codeHash: crypto.createHash('sha256').update(code).digest('hex'),
+    used: false,
+  }));
+  await db.backupCode.createMany({ data: hashed });
+}
+
+async function useBackupCode(userId: string, code: string): Promise<boolean> {
+  const hash = crypto.createHash('sha256').update(code).digest('hex');
+  const result = await db.backupCode.updateMany({
+    where: { userId, codeHash: hash, used: false },
+    data: { used: true, usedAt: new Date() },
+  });
+  return result.count > 0;
+}
+```
+
+---
+
+## WebAuthn / Passkey for MFA
+
+```typescript
+import { generateAuthenticationOptions, verifyAuthenticationResponse }
+  from '@simplewebauthn/server';
+
+// Challenge generation (server)
+const options = await generateAuthenticationOptions({
+  rpID: 'example.com',
+  allowCredentials: user.credentials.map(c => ({
+    id: c.credentialId,
+    type: 'public-key',
+  })),
+  userVerification: 'required',
+});
+
+// Verify response (server)
+const verification = await verifyAuthenticationResponse({
+  response: clientResponse,
+  expectedChallenge: storedChallenge,
+  expectedOrigin: 'https://example.com',
+  expectedRPID: 'example.com',
+  authenticator: storedCredential,
+});
+```
+
+---
+
+## Recovery Flow
+
+```
+User cannot access MFA device?
+├── Has backup codes → Enter backup code
+├── Has recovery email → Email verification + admin review
+├── Has trusted device → Device-based recovery
+└── None of above → Manual identity verification (support)
+```
+
+### Recovery Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Show backup codes ONCE at setup | Prevent later access |
+| Allow re-generating backup codes | When old ones run out |
+| Log all recovery events | Audit trail |
+| Rate limit recovery attempts | Prevent brute force |
+| Notify on MFA changes | Alert user to compromise |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [passkey.md](passkey.md) | Passkeys as MFA or passwordless |
+| [jwt-deep.md](jwt-deep.md) | Token lifecycle after MFA |
+| [session.md](session.md) | Session management with MFA |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/auth-patterns/rules/oauth2.md

@@ -0,0 +1,134 @@
+---
+name: oauth2
+description: OAuth 2.0 + OpenID Connect flows, PKCE, scopes, provider integration
+title: "OAuth 2.0 & OpenID Connect"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: oauth2
+---
+
+# OAuth 2.0 & OpenID Connect
+
+> Third-party login, SSO, and delegated authorization.
+
+---
+
+## OAuth 2.0 Flows
+
+### Authorization Code + PKCE (Recommended for SPA/Mobile)
+
+```
+1. Client generates code_verifier (random 43-128 chars)
+2. Client creates code_challenge = SHA256(code_verifier)
+3. Redirect to auth server with code_challenge
+4. User authenticates → redirect back with auth code
+5. Client exchanges code + code_verifier for tokens
+```
+
+```typescript
+import crypto from 'crypto';
+
+// Generate PKCE pair
+const codeVerifier = crypto.randomBytes(32).toString('base64url');
+const codeChallenge = crypto
+  .createHash('sha256')
+  .update(codeVerifier)
+  .digest('base64url');
+
+// Authorization URL
+const authUrl = new URL('https://auth.example.com/authorize');
+authUrl.searchParams.set('response_type', 'code');
+authUrl.searchParams.set('client_id', CLIENT_ID);
+authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
+authUrl.searchParams.set('scope', 'openid profile email');
+authUrl.searchParams.set('code_challenge', codeChallenge);
+authUrl.searchParams.set('code_challenge_method', 'S256');
+authUrl.searchParams.set('state', crypto.randomBytes(16).toString('hex'));
+```
+
+### Flow Selection Guide
+
+| Flow | Best For | PKCE? |
+|------|----------|-------|
+| Authorization Code + PKCE | SPA, Mobile, Server | ✅ Always |
+| Client Credentials | Machine-to-machine | N/A |
+| Device Code | TV, CLI, IoT | N/A |
+| ~~Implicit~~ | **DEPRECATED** — never use | ❌ |
+| ~~Password~~ | **DEPRECATED** — never use | ❌ |
+
+---
+
+## OpenID Connect (OIDC)
+
+OIDC = OAuth 2.0 + Identity Layer
+
+### ID Token Claims
+
+| Claim | Purpose |
+|-------|---------|
+| `sub` | Unique user identifier |
+| `iss` | Token issuer |
+| `aud` | Intended audience (your client_id) |
+| `exp` | Expiration time |
+| `iat` | Issued at |
+| `nonce` | Replay attack prevention |
+| `email` | User email (with scope) |
+| `name` | User display name (with scope) |
+
+### Scopes
+
+| Scope | Data Returned |
+|-------|---------------|
+| `openid` | Required — returns `sub` |
+| `profile` | name, picture, locale |
+| `email` | email, email_verified |
+| `offline_access` | Refresh token |
+
+---
+
+## Provider Integration
+
+### Popular Providers
+
+| Provider | Docs | Notes |
+|----------|------|-------|
+| Google | `accounts.google.com` | OIDC compliant |
+| GitHub | `github.com/login/oauth` | OAuth 2.0 only (no OIDC) |
+| Microsoft | `login.microsoftonline.com` | OIDC + Azure AD |
+| Apple | `appleid.apple.com` | Required for iOS apps |
+
+### Auth Libraries (Node.js)
+
+| Library | Use Case |
+|---------|----------|
+| `next-auth` / `Auth.js` | Next.js integration |
+| `passport` | Express middleware |
+| `arctic` | Lightweight OAuth 2.0 |
+| `lucia` | Session + OAuth (modern) |
+| `better-auth` | Full-featured (2025+) |
+
+---
+
+## Security Checklist
+
+- [ ] Always use PKCE for public clients
+- [ ] Validate `state` parameter to prevent CSRF
+- [ ] Verify ID token signature and claims (`iss`, `aud`, `exp`)
+- [ ] Use `nonce` to prevent replay attacks
+- [ ] Store tokens in httpOnly cookies, not localStorage
+- [ ] Implement token refresh before expiry
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [jwt-deep.md](jwt-deep.md) | Token lifecycle after OAuth login |
+| [session.md](session.md) | Session-based alternative |
+| [passkey.md](passkey.md) | Passwordless alternative |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134