session-management

# Session Management

**Purpose:** Autonomously configure, validate, and troubleshoot Clerk session handling, JWT verification, and token management.

**Activation Triggers:**
- Session validation failures
- JWT verification errors
- Token expiration issues
- Multi-session conflicts
- Custom claims configuration
- Session refresh problems
- Authentication middleware setup
- Session security audits

**Key Resources:**
- `scripts/configure-sessions.sh` - Session configuration helper
- `scripts/setup-jwt.sh` - JWT template setup and validation
- `scripts/test-sessions.sh` - Session testing and verification
- `templates/session-config.ts` - Session configuration patterns
- `templates/jwt-verification.ts` - JWT verification middleware
- `templates/custom-claims.ts` - Custom JWT claims setup
- `templates/session-types.ts` - TypeScript type definitions
- `examples/multi-session.tsx` - Multi-session management
- `examples/session-refresh.ts` - Session refresh patterns
- `examples/session-debugging.ts` - Debugging utilities

## Session Configuration Workflow

### 1. Configure Session Settings

```bash
# Interactive session configuration
./scripts/configure-sessions.sh

# Options configured:
# - Session lifetime (default, maximum)
# - Multi-session mode (single, multi-device)
# - Refresh token strategy
# - Session activity tracking
# - Secure cookie settings
```

**What it configures:**
- ✅ Session duration and expiration
- ✅ Multi-session behavior (allow/restrict)
- ✅ Token refresh intervals
- ✅ Activity-based session extension
- ✅ Cookie security attributes (SameSite, Secure, HttpOnly)

### 2. Setup JWT Templates

```bash
# Create/update JWT templates for custom claims
./scripts/setup-jwt.sh <template-name>

# Examples:
./scripts/setup-jwt.sh default      # Standard user claims
./scripts/setup-jwt.sh hasura       # Hasura integration claims
./scripts/setup-jwt.sh supabase     # Supabase integration claims
./scripts/setup-jwt.sh custom       # Custom business logic claims
``