Session Model Documentation

Overview

The Session model manages authentication sessions for all actors in the CODITECT platform - humans, AI agents, and service accounts. It provides secure session management with JWT token families, refresh token rotation, and comprehensive audit logging. The model supports both traditional web sessions and programmatic API access patterns.

Model Structure

Session (Enhanced) Model

Core Fields

Field	Type	Description	Constraints
session_id	UUID	Unique session identifier	Primary key, auto-generated
user_id	UUID	Actor identifier (user/agent/service)	Required
tenant_id	UUID	Associated tenant	Foreign key to Tenant
token_family	UUID	Token rotation tracking	Required for refresh tokens
created_at	DateTime	Session creation time	Auto-set
last_accessed	DateTime	Last activity timestamp	Auto-updated
expires_at	DateTime	Session expiration	Required
refresh_expires_at	DateTime (Optional)	Refresh token expiry	For long-lived sessions
ip_address	String (Optional)	Client IP address	For security tracking
user_agent	String (Optional)	Browser/client identifier	For device tracking
is_active	bool	Session validity	Required, default true
actor_type	String (Optional)	Type of actor	"human", "agent", "service", "system"
actor_details	JSON (Optional)	Actor-specific metadata	Flexible structure

UserSession (Legacy) Model

Maintained for backward compatibility:

Field	Type	Description
session_id	UUID	Unique identifier
user_id	UUID	User identifier
tenant_id	UUID	Tenant identifier
refresh_token	String	Refresh token value
expires_at	DateTime	Expiration time
created_at	DateTime	Creation time
last_used	DateTime	Last usage time
ip_address	String (Optional)	Client IP
user_agent	String (Optional)	Client identifier
is_active	bool	Session validity

Actor Types

Human Sessions

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "456e7890-e89b-12d3-a456-426614174000",
  "token_family": "789e0123-e89b-12d3-a456-426614174000",
  "created_at": "2025-08-29T10:00:00Z",
  "last_accessed": "2025-08-29T10:30:00Z",
  "expires_at": "2025-08-29T11:00:00Z",
  "refresh_expires_at": "2025-09-05T10:00:00Z",
  "ip_address": "203.0.113.45",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "is_active": true,
  "actor_type": "human",
  "actor_details": null
}

Agent Sessions

{
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "user_id": "agent-123e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "456e7890-e89b-12d3-a456-426614174000",
  "token_family": "889e0123-e29b-41d4-a716-446655440000",
  "created_at": "2025-08-29T10:00:00Z",
  "last_accessed": "2025-08-29T10:45:00Z",
  "expires_at": "2025-08-29T14:00:00Z",
  "refresh_expires_at": null,
  "ip_address": "10.0.0.5",
  "user_agent": "CoditextAgent/1.0 (agent_id=test-writer-01)",
  "is_active": true,
  "actor_type": "agent",
  "actor_details": {
    "agent_type": "test_writer",
    "agent_id": "agent-123e4567-e89b-12d3-a456-426614174000",
    "instance_id": "instance-987654321",
    "capabilities": ["write_tests", "analyze_code"]
  }
}

Service Account Sessions

{
  "session_id": "770e8400-e29b-41d4-a716-446655440000",
  "user_id": "service-890e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "456e7890-e89b-12d3-a456-426614174000",
  "token_family": "990e0123-e29b-41d4-a716-446655440000",
  "created_at": "2025-08-29T00:00:00Z",
  "last_accessed": "2025-08-29T10:50:00Z",
  "expires_at": "2025-12-31T23:59:59Z",
  "refresh_expires_at": "2026-12-31T23:59:59Z",
  "ip_address": null,
  "user_agent": "GitHubIntegration/2.0",
  "is_active": true,
  "actor_type": "service",
  "actor_details": {
    "service_name": "github_integration",
    "service_id": "service-890e4567-e89b-12d3-a456-426614174000",
    "permissions": ["read_repos", "write_comments"],
    "api_version": "v2"
  }
}

Token Management

Token Family System

Token families enable secure refresh token rotation:

1. Initial authentication creates a token family
2. Each refresh generates new tokens within the family
3. Old tokens in family are invalidated
4. Prevents replay attacks

BlacklistedToken Model

Field	Type	Description
token_jti	String	JWT ID (jti claim)
blacklisted_at	DateTime	When token was blacklisted
expires_at	DateTime	Natural expiration time
reason	BlacklistReason	Why token was blacklisted

BlacklistReason Enum

enum BlacklistReason {
    UserLogout,           // User initiated logout
    AdminRevocation,      // Admin revoked session
    SecurityConcern,      // Suspicious activity
    RefreshTokenRotation  // Part of rotation
}

Session Activity Tracking

SessionActivity Model

Field	Type	Description
activity_id	UUID	Unique activity identifier
session_id	UUID	Related session
user_id	UUID	Actor identifier
activity_type	SessionActivityType	Type of activity
timestamp	DateTime	When it occurred
ip_address	String (Optional)	Client IP
details	JSON (Optional)	Additional context

SessionActivityType Enum

enum SessionActivityType {
    Created,    // Session created
    Refreshed,  // Token refreshed
    Accessed,   // Session used
    Revoked,    // Session revoked
    Expired     // Session expired
}

Database Schema

Primary Storage Patterns

# Active sessions
Key: /{tenant_id}/sessions/{session_id}
Value: JSON serialized Session

# User sessions (legacy)
Key: /{tenant_id}/user_sessions/{session_id}
Value: JSON serialized UserSession

# Blacklisted tokens
Key: /{tenant_id}/blacklisted_tokens/{token_jti}
Value: JSON serialized BlacklistedToken

# Session activities
Key: /{tenant_id}/session_activities/{session_id}/{timestamp}:{activity_id}
Value: JSON serialized SessionActivity

Secondary Indexes

# Sessions by user
/{tenant_id}/sessions_by_user/{user_id} -> [session_ids]

# Sessions by token family
/{tenant_id}/sessions_by_family/{token_family} -> [session_ids]

# Active sessions
/{tenant_id}/active_sessions -> [session_ids]

# Sessions by actor type
/{tenant_id}/sessions_by_actor_type/{actor_type} -> [session_ids]

Session Lifecycle

Creation Flow

1. Authentication successful
2. Generate token_family UUID
3. Create Session record
4. Generate JWT with session_id
5. Optional: Generate refresh token
6. Log SessionActivity (Created)

Refresh Flow

1. Validate refresh token
2. Check token family
3. Create new tokens
4. Blacklist old tokens
5. Update session last_accessed
6. Log SessionActivity (Refreshed)

Revocation Flow

1. Mark session as inactive
2. Blacklist all tokens in family
3. Log SessionActivity (Revoked)
4. Optional: Notify user

Security Features

Token Security

• Short-lived Access Tokens: Default 1 hour
• Long-lived Refresh Tokens: Default 7 days
• Token Rotation: New tokens on each refresh
• Family Tracking: Detect token reuse

Session Security

• IP Validation: Optional IP binding
• Device Tracking: User agent fingerprinting
• Concurrent Limits: Max sessions per user
• Idle Timeout: Auto-expire inactive sessions

Audit Trail

• All session events logged
• IP address tracking
• Suspicious activity detection
• Compliance reporting support

API Endpoints

Session Management

• POST /api/auth/login - Create session
• POST /api/auth/refresh - Refresh tokens
• POST /api/auth/logout - End session
• GET /api/sessions - List user's sessions
• DELETE /api/sessions/{session_id} - Revoke specific session

Session Information

• GET /api/sessions/current - Get current session
• GET /api/sessions/{session_id} - Get session details
• GET /api/sessions/{session_id}/activity - Session activity log

Administrative

• GET /api/admin/sessions?user_id={id} - Admin view sessions
• POST /api/admin/sessions/{session_id}/revoke - Admin revoke
• GET /api/admin/sessions/active-count - Active session metrics

Related Code

Source Files

• Models: /src/models/session.rs
• Repository: /src/db/repositories/session_repository.rs
• JWT Service: /src/auth/jwt.rs
• API Handlers: /src/api/handlers/auth_handlers.rs
• Tests: /src/models/tests/session_tests.rs

Key Methods

impl Session {
    fn new(user_id: Uuid, tenant_id: Uuid, token_family: Uuid, duration_seconds: i64) -> Self
    fn new_for_agent(agent_id: Uuid, ...) -> Self
    fn new_for_service(service_id: Uuid, ...) -> Self
    fn with_metadata(self, ip_address: Option<String>, user_agent: Option<String>) -> Self
    fn is_expired(&self) -> bool
    fn refresh(&mut self)
    fn revoke(&mut self)
}

Use Cases

Web Application Login

// User provides credentials
let user = authenticate_user(email, password)?;

// Create session
let session = Session::new(
    user.user_id,
    user.tenant_id,
    Uuid::new_v4(), // token_family
    3600 // 1 hour
).with_metadata(
    Some(client_ip),
    Some(user_agent)
);

// Generate tokens
let access_token = jwt_service.create_access_token(&session)?;
let refresh_token = jwt_service.create_refresh_token(&session)?;

Agent Authentication

// Agent requests session
let session = Session::new_for_agent(
    agent_config.agent_id,
    agent_config.tenant_id,
    Uuid::new_v4(),
    14400, // 4 hours
    agent_config.agent_type.to_string()
);

// Limited duration, no refresh
let token = jwt_service.create_agent_token(&session)?;

Service Account

// Long-lived service session
let session = Session::new_for_service(
    service_account.id,
    tenant_id,
    Uuid::new_v4(),
    31536000, // 1 year
    "github_integration".to_string()
);

Session Limits

Per Actor Type

Actor Type	Max Concurrent	Access Token TTL	Refresh Token TTL
Human	5 sessions	1 hour	7 days
Agent	10 sessions	4 hours	None
Service	3 sessions	24 hours	1 year
System	Unlimited	1 hour	None

Rate Limits

• Login attempts: 5 per minute
• Token refresh: 10 per minute
• Session creation: 20 per hour

Monitoring & Analytics

Metrics

• Active sessions by type
• Average session duration
• Token refresh frequency
• Failed authentication attempts
• Concurrent session peaks

Alerts

• Unusual login patterns
• Multiple failed attempts
• Token family abuse
• Session limit exceeded
• Geographic anomalies

Compliance

Data Retention

• Active session data: Duration of session
• Session activity logs: 90 days
• Blacklisted tokens: Until natural expiry
• Audit logs: 7 years

Privacy

• IP addresses hashed after 30 days
• User agents anonymized
• Session data encrypted at rest
• GDPR right to deletion supported

Best Practices

Security

1. Always use HTTPS for token transmission
2. Store tokens in secure storage only
3. Implement CSRF protection
4. Monitor for suspicious patterns
5. Regular security audits

Performance

1. Cache active sessions in memory
2. Batch activity log writes
3. Periodic cleanup of expired data
4. Index optimization for lookups

Future Enhancements

Advanced Features

1. Multi-factor Sessions: MFA requirement tracking
2. Geofencing: Location-based restrictions
3. Device Trust: Trusted device management
4. Session Delegation: Temporary permission grants

Integration Improvements

1. SSO Support: SAML/OIDC integration
2. Session Sharing: Cross-service sessions
3. Mobile SDK: Native app session management
4. WebAuthn: Passwordless authentication

Analytics Enhancements

1. Behavior Analysis: ML-based anomaly detection
2. Risk Scoring: Real-time session risk assessment
3. Compliance Reporting: Automated audit reports
4. Session Insights: Usage pattern analysis

---

Last Updated: 2025-08-29 Version: 1.0