Skip to main content

Authorization & Access Control - Version Mapping

Shows which product versions use this domain and to what extent.

Version Matrix​

VersionScopeTables UsedKey Features
MVP.0Fullroles, permissions, role_permissions, sessions, policy_rules (inactive)Core RBAC, Google SSO, JWT sessions, 5 system roles, 30+ permissions, deny-wins semantics
MVP.1Full(no changes)Permission caching optimizations, session device tracking improvements
V1.0Full+device_name, +location (columns)Idle timeout (30min), session device management, refresh tokens (60-day), IP validation
V1.1Full+session_activity_feedSession activity log (last 10 actions), geolocation alerts, anomaly detection
V2.0Full+auth_providers, user_identities, email_verification_tokensMulti-provider auth (Microsoft, GitHub), email/password option, account linking
V3.0Fullpolicy_rules (active), +policy_cacheABAC evaluation engine, context-aware permissions, policy DSL, conflict resolution

Changes by Version​

MVP.0 - Core RBAC with Google SSO​

Scope: Full implementation of role-based access control with authentication.

Tables:

  • roles - Named permission bundles (admin, owner, channel_publisher, content_manager, viewer)
  • permissions - Atomic action registry (30+ permissions across all domains)
  • role_permissions - Junction table with allow/deny semantics
  • sessions - Server-side session tracking (PostgreSQL + Redis cache)
  • policy_rules - ABAC schema present but is_active=false (not enforced)

Features:

  • Google OAuth 2.0 with OIDC + PKCE flow
  • JWT token-based authentication (24-hour expiration)
  • 5 system roles with differentiated permissions
  • Deny-wins permission evaluation (explicit deny overrides all allows)
  • Wildcard permission support (*.action, resource.*, *.* for admin)
  • Session cookies (HttpOnly, Secure, SameSite=Lax)
  • Permission caching (Redis, 5-minute TTL)
  • Org-wide vs. Account-level membership scoping
  • Basic audit logging (denials and role changes)

System Roles:

  • admin: Full access (*.*) - organizational administrators
  • owner: Space, unit, pricing, booking, payment management; financial read; settings
  • channel_publisher: Space/unit read, channel management, booking read
  • content_manager: Space/unit/media write, availability management
  • viewer: Read-only access to all resources

Permission Categories:

  • Account management (account.*)
  • Space operations (space.{read,create,update,delete})
  • Unit operations (unit.{read,create,update,delete})
  • Media management (media.{read,write,delete})
  • Availability (availability.{read,create,update,delete})
  • Pricing (pricing.{read,create,update,delete})
  • Bookings (booking.{read,create,update,delete,manage})
  • Payments (payment.{read,create,update,delete})
  • Financials (financials.read)
  • Team management (users.{read,create,update,delete})
  • Settings (settings.{read,update})
  • Channels (channel.{read,manage})

Session Management:

  • 24-hour absolute timeout (no idle timeout in MVP)
  • Server-side storage (PostgreSQL primary, Redis cache)
  • Session limit: 10 active sessions per user (oldest auto-revoked)
  • Revocation triggers: logout, role change, privilege escalation

Security:

  • JWT signed with HS256 (minimum 256-bit secret)
  • Session token hash stored (SHA-256), not plaintext
  • PKCE flow with state parameter validation (5-minute TTL)
  • User agent binding to detect session hijacking
  • IP address logging for audit trail

Deferred:

  • ABAC policy evaluation (schema present, inactive)
  • Idle session timeout (30-minute inactivity)
  • Multi-factor authentication (MFA)
  • Session device management UI
  • Refresh token support
  • Property-level permission scoping (org/account only)

MVP.1 - Performance Optimizations​

Scope: Full - Enhanced caching and monitoring.

Changes from MVP.0:

  • Improved permission cache hit rate (target >95%)
  • Session validation optimizations
  • Enhanced device tracking

Implementation Changes:

  • Redis connection pooling improvements
  • Batch permission cache warming on login
  • Optimized SQL queries for membership lookups
  • Index tuning for session validation queries

Monitoring Additions:

  • Permission cache hit rate tracking
  • Session creation rate metrics
  • Denial rate alerting (potential attacks)
  • Session revocation reason analytics

V1.0 - Enhanced Session Management​

Scope: Full - Advanced session security and lifecycle.

Changes from MVP.1:

  • Idle timeout enforcement (30 minutes of inactivity)
  • Session device management UI
  • Refresh token support (60-day lifetime, rotated on use)
  • Enhanced IP-based validation

Schema Changes:

  • Add last_activity_at column to sessions table
  • Add device_name column (parsed from user agent)
  • Add location column (IP geolocation: city, country)

New Features:

  • View all active sessions per user
  • Revoke sessions remotely (from any device)
  • Refresh tokens stored encrypted (separate table)
  • Grace period for mobile users switching networks (5 minutes)
  • Anomaly detection: IP change beyond threshold triggers re-authentication
  • Session activity feed (last 10 actions per session)

Business Rules:

  • Idle timeout: 30 minutes since last_activity_at
  • Absolute timeout: 24 hours since issued_at (unchanged)
  • Refresh token rotation on every use (prevents replay)
  • Refresh token max lifetime: 60 days
  • Location change alerts via email/push notification

V1.1 - Session Activity & Geolocation​

Scope: Full - Enhanced observability and security.

Changes from V1.0:

  • Session activity feed table
  • Geolocation integration
  • Advanced anomaly detection

New Tables:

  • session_activity_feed - Tracks last N actions per session (action, resource, timestamp)

Enhanced Features:

  • Real-time session activity log (visible in account settings)
  • Geolocation alerts on unexpected location changes
  • Impossible travel detection (e.g., US to EU in 1 hour)
  • Device fingerprinting (browser + OS + timezone)
  • Security event notifications (new device login, location change)

Security Improvements:

  • Machine learning-based anomaly scoring
  • Automatic session revocation on high-risk events
  • Security timeline per user (all authentication events)
  • Two-factor authentication prompts on suspicious activity

V2.0 - Multi-Provider Authentication​

Scope: Full - Support for additional identity providers.

Changes from V1.1:

  • Microsoft Azure AD / Entra ID OIDC integration
  • GitHub OAuth integration
  • Email/password authentication with email verification
  • Multi-provider account linking

New Tables:

  • auth_providers - Configured authentication providers per org
  • user_identities - Provider-specific user profiles (one user, multiple identities)
  • email_verification_tokens - Email verification workflow

Schema Changes:

  • Add email_verified and email_verified_at columns to users table
  • Add password_hash column to users table (nullable, bcrypt)

Enhanced Features:

  • Provider selection at login (dropdown: Google, Microsoft, GitHub, Email)
  • Account linking UI (connect multiple providers to one account)
  • Email verification flow for email/password signups
  • Provider-specific token storage (encrypted refresh tokens per provider)
  • Fallback authentication (if primary provider unavailable)

Business Rules:

  • User email remains primary identity (unique across providers)
  • First authentication method becomes primary
  • Account linking requires re-authentication
  • Provider tokens encrypted at rest (AES-256)
  • Email verification required before account activation

Authentication Flow:

  • Each provider has dedicated callback endpoint
  • Unified user record after successful authentication
  • Provider tokens stored in user_identities table
  • Session creation identical across all providers

V3.0 - Attribute-Based Access Control (ABAC)​

Scope: Full - Context-aware permission evaluation.

Changes from V2.0:

  • PolicyRule evaluation engine activated
  • Context-aware permissions (channel, region, time, IP range)
  • Policy management UI
  • Policy DSL for complex conditional rules

Schema Changes:

  • Set policy_rules.is_active = true by default for new policies
  • Add policy_cache table for evaluation result caching

New Tables:

  • policy_cache - Redis-backed evaluation results (5-minute TTL)
  • policy_evaluation_logs - Audit trail for policy decisions

Enhanced Features:

  • Visual policy builder (drag-and-drop rule creation)
  • Policy priority and conflict resolution (higher priority = evaluated first)
  • Condition DSL supporting:
    • Time-based rules (business hours, weekends, holidays)
    • Location-based rules (IP ranges, countries, regions)
    • Channel-based rules (restrict actions per distribution channel)
    • Resource attribute matching (property type, tier, status)
  • Policy testing sandbox (preview impact before activation)
  • Policy compliance reports (which policies apply to which users)

Permission Evaluation Flow:

  1. Check RBAC role permissions (deny-wins)
  2. If RBAC allows, evaluate ABAC policies (higher priority first)
  3. ABAC policies can override RBAC decisions
  4. Cache evaluation result (5-minute TTL)
  5. Log decision to audit trail

Example Policy Use Cases:

  • Restrict booking creation to business hours (9am-5pm EST)
  • Block pricing changes outside manager's region
  • Require additional approval for high-value bookings
  • Limit channel publishing to specific user groups
  • Geo-fence financial operations to specific countries

Business Rules:

  • Policies evaluated after RBAC (can override but not bypass)
  • Higher priority policies evaluated first (1-1000, default 100)
  • Conflicting policies: most restrictive wins (deny > allow)
  • Policy changes invalidate permission cache immediately
  • Inactive policies stored but not evaluated

Performance:

  • Policy evaluation target: <20ms per request
  • Cache hit rate target: >90%
  • Maximum policies per org: 1000
  • Maximum conditions per policy: 10

Operational Notes​

MVP.0 Performance Targets​

  • Permission check (cached): <10ms
  • Permission check (cache miss): <50ms
  • Session validation (Redis): <5ms
  • Session validation (PostgreSQL fallback): <20ms
  • Login flow end-to-end: <2 seconds

Monitoring Requirements​

  • Permission cache hit rate (target >95%)
  • Session creation rate and concurrent sessions
  • High denial rate alerts (potential attack or misconfiguration)
  • Session revocation reason tracking (manual vs. automatic)
  • Failed login attempts per user/IP

Cache Management​

  • Session cache TTL: 24 hours (matches session expiration)
  • Permission cache TTL: 5 minutes (invalidated on role changes)
  • PKCE state TTL: 5 minutes (one-time use)
  • Redis memory sizing: plan for 10k concurrent sessions + 50k cached permissions

Cleanup Jobs​

  • Daily: Delete expired sessions older than 7 days
  • Weekly: Archive revoked sessions to cold storage
  • Monthly: Rotate JWT signing keys (with 7-day grace period)
  • Hourly: Clean up expired PKCE state keys

Audit Requirements​

  • Log all access denials (user, resource, action, timestamp, reason)
  • Log all role changes (old role, new role, changed by, reason)
  • Log all session revocations (reason, metadata)
  • Retain audit logs for 7 years (compliance)

Scaling Considerations​

  • Sessions table grows with active users (prune aggressively)
  • Role_permissions is read-heavy, write-rare (cache aggressively)
  • Policy_rules evaluation is CPU-intensive (V3.0 requires optimization)
  • Consider read replicas for session validation at scale