Access Control & Permissions

Comprehensive guide to Torvus Security's access control model, authentication, and authorization.

---

Access Control Model

Torvus Security implements a multi-layered access control system:

������������������������������������������������
          Authentication Layer                  
  � User Authentication (Email + Password)     
  � Multi-Factor Authentication (MFA/TOTP)     
  � WebAuthn (Hardware Keys)                   
  � API Key Authentication                     
������������������������������������������������
                     
������������������������������������������������
          Authorization Layer                   
  � Role-Based Access Control (RBAC)           
  � Attribute-Based Access Control (ABAC)      
  � Resource-Level Permissions                 
  � Row-Level Security (RLS)                   
������������������������������������������������
                     
������������������������������������������������
          Audit & Monitoring Layer              
  � Access Logging                             
  � Permission Changes                         
  � Anomaly Detection                          
  � Real-Time Alerts                           
������������������������������������������������

---

Authentication

User Authentication Methods

Primary Methods:

Method	Security Level	Use Case	MFA Required
Email + Password	Medium	Standard login	Yes
WebAuthn	High	Passwordless login	Built-in
SSO (SAML/OIDC)	High	Enterprise users	Delegated to IdP
Magic Link	Medium	Temporary access	Yes (on setup)
API Key	Medium-High	Programmatic access	N/A

Multi-Factor Authentication (MFA)

Required for all accounts, MFA adds an extra security layer:

Supported MFA Methods:

1. TOTP (Time-Based One-Time Password)

   • Authenticator apps: Google Authenticator, Authy, 1Password, Bitwarden
   • 6-digit codes rotated every 30 seconds
   • Offline capability (no network required)
   • Recommended for most users

2. WebAuthn (Hardware Security Keys)

   • YubiKey, Titan Security Key, Thetis
   • Phishing-resistant authentication
   • USB, NFC, or Bluetooth
   • Recommended for high-security users

3. SMS (Text Message)

   • 6-digit code via SMS
   • Available in 190+ countries
   • Not recommended (SIM swapping risk)

MFA Setup:

1. Log in to Torvus Security
2. Go to Settings � Security � Two-Factor Authentication
3. Choose MFA method and follow setup wizard
4. Save backup codes in secure location
5. Test MFA before closing setup

MFA Recovery:

• Backup Codes: 10 single-use recovery codes generated during setup
• Account Recovery: Email-based recovery (with identity verification)
• Support Recovery: Contact support with identity proof (ID verification required)

WebAuthn (Passwordless)

What is WebAuthn?

• Web Authentication API standard
• Passwordless authentication via hardware/biometrics
• Resistant to phishing, credential stuffing, replay attacks

Supported Devices:

• Security Keys: YubiKey, Titan, Thetis, Feitian
• Platform Authenticators: Face ID, Touch ID, Windows Hello, Android Biometric
• Hybrid Authenticators: Phone as security key (via Bluetooth/QR)

Setup Process:

1. Navigate to Settings � Security � WebAuthn
2. Click Add Security Key
3. Insert key or trigger biometric prompt
4. Name your authenticator (e.g., "YubiKey 5C", "MacBook Touch ID")
5. Complete registration

Best Practices:

• Register multiple authenticators (primary + backup)
• Use hardware security keys for maximum security
• Platform authenticators for convenience
• Keep one backup key in secure location (safe, safe deposit box)

Single Sign-On (SSO)

Enterprise Feature: Centralized authentication via your identity provider.

Supported Protocols:

• SAML 2.0: Okta, Azure AD, OneLogin, Google Workspace
• OIDC (OpenID Connect): Auth0, Keycloak, AWS Cognito

Benefits:

•  Centralized user management
•  Automatic provisioning/deprovisioning
•  Compliance with corporate policies
•  Reduced password fatigue
•  Enhanced audit capabilities

SSO Setup (Admin):

1. Contact Torvus Sales for SSO enablement
2. Provide IdP metadata (XML or metadata URL)
3. Configure attribute mappings (email, name, role)
4. Test with pilot user group
5. Roll out to organization

Just-in-Time (JIT) Provisioning:

• Users auto-created on first SSO login
• Attributes synced from IdP (name, email, department)
• Role assignment based on IdP groups
• Deprovisioning on IdP account deletion

---

Authorization

Role-Based Access Control (RBAC)

Torvus uses hierarchical RBAC with predefined roles and permissions.

User Roles

Role	Description	Typical User	Permissions
Owner	Account owner	Individual user, company founder	Full control
Admin	Account administrator	IT admin, security officer	Manage users, vaults, billing
Manager	Vault manager	Team lead, department head	Manage assigned vaults
Member	Standard user	Employee, team member	Create vaults, access assigned vaults
Guest	Limited access	Contractor, temp staff	View-only access to specific vaults
Auditor	Audit access	Compliance officer, auditor	Read-only access to logs and audit trail

Vault Roles

Granular permissions within each vault:

Vault Role	Can View	Can Upload	Can Download	Can Modify	Can Delete	Can Share	Can Configure
Vault Owner							
Collaborator					L		L
Contributor			L	L	L	L	L
Viewer		L		L	L	L	L
Recipient	=*	L	*	L	L	L	L

*= Recipients gain access only upon vault release

Permission Inheritance:

• Account-level roles apply to all vaults
• Vault-level roles override account roles
• Explicit permissions take precedence
• Deny rules override allow rules

Attribute-Based Access Control (ABAC)

Enterprise Feature: Fine-grained access control based on attributes.

Supported Attributes:

User Attributes:

• Department (Engineering, Finance, Legal)
• Location (US, EU, APAC)
• Clearance Level (Public, Internal, Confidential, Secret)
• Employment Type (Full-time, Contractor, Consultant)

Resource Attributes:

• Vault Classification (Personal, Business, Legal, Compliance)
• Data Sensitivity (Low, Medium, High, Critical)
• Compliance Tag (GDPR, HIPAA, SOX, PCI)
• Project Code (PROJECT-001, CASE-2024-123)

Environmental Attributes:

• Time of Day (Business Hours: 9am-5pm)
• IP Address (Corporate Network, VPN, Public)
• Device Type (Managed, BYOD)
• Geolocation (Office, Home, International)

Example Policy:

ALLOW access to vault
WHERE
  user.department = "Legal" AND
  user.clearance >= "Confidential" AND
  vault.classification = "Legal" AND
  request.time IN business_hours AND
  request.ip IN corporate_network

Row-Level Security (RLS)

Database-Enforced Access Control:

Torvus uses PostgreSQL Row-Level Security (RLS) policies to enforce authorization at the database level:

RLS Policies:

-- Users can only see their own vaults
CREATE POLICY user_vaults_policy ON vaults
  FOR SELECT
  USING (owner_id = current_user_id());

-- Users can only access documents in vaults they own or are shared with
CREATE POLICY user_documents_policy ON documents
  FOR SELECT
  USING (
    vault_id IN (
      SELECT id FROM vaults WHERE owner_id = current_user_id()
      UNION
      SELECT vault_id FROM vault_shares WHERE user_id = current_user_id()
    )
  );

-- Admins can see all vaults (for support)
CREATE POLICY admin_vaults_policy ON vaults
  FOR SELECT
  USING (
    current_user_role() = 'admin' OR
    owner_id = current_user_id()
  );

Benefits:

•  Defense in Depth: Authorization enforced at database level
•  No Bypass: Even direct SQL queries respect RLS
•  Performance: Database-optimized filtering
•  Auditability: Policy changes tracked in database

---

API Access Control

API Key Authentication

API Key Types:

Type	Use Case	Scope	Expiration
Personal API Key	Individual automation	User's vaults only	1 year
Service Account Key	Application integration	Specific vaults/operations	90 days (recommended)
Admin API Key	Administrative tasks	Account-wide	30 days (required rotation)
Webhook Secret	Webhook signature verification	Webhook-specific	No expiration

API Key Permissions:

{
  "key_id": "key_abc123",
  "name": "CI/CD Integration",
  "scopes": [
    "vaults:read",
    "vaults:create",
    "documents:upload",
    "documents:read"
  ],
  "vault_restrictions": ["vault_xyz789"],
  "ip_whitelist": ["192.168.1.0/24"],
  "rate_limit": 1000
}

Best Practices:

•  Minimum Scope: Grant only necessary permissions
•  Vault Restrictions: Limit to specific vaults
•  IP Whitelisting: Restrict to known IPs (if possible)
•  Regular Rotation: Rotate keys every 90 days
•  Monitoring: Review API key usage logs weekly

OAuth 2.0 (Third-Party Apps)

Authorization Code Flow with PKCE:

�������������                                  �������������
   User                                          Torvus     
                                                  OAuth     
�������������                                  �������������
                                                        
        1. Initiate Login                              
       ������������������������������������������������>
                                                        
        2. Redirect to Torvus Login                    
       <������������������������������������������������$
                                                        
        3. User Authenticates & Approves                
       ������������������������������������������������>
                                                        
        4. Authorization Code (with PKCE)              
       <������������������������������������������������$
                                                        
�������������                                  �������������
Third-Party   5. Exchange Code for Token         Torvus     
     App     ���������������������������������>   OAuth     
                                                            
              6. Access Token + Refresh Token               
             <���������������������������������$             
�������������                                  �������������

OAuth Scopes:

• vaults:read: Read vault metadata
• vaults:write: Create and modify vaults
• documents:read: Download documents
• documents:write: Upload documents
• recipients:manage: Add/remove recipients
• policies:manage: Configure policies
• profile:read: Read user profile

Token Lifetimes:

• Access Token: 1 hour (short-lived)
• Refresh Token: 30 days (long-lived)
• Authorization Code: 10 minutes (single-use)

---

Permission Management

Granting Permissions

Account-Level Permissions (Admin Only):

1. Navigate to Settings � Team � Members
2. Click Invite Member
3. Enter email and select role:
   • Admin (full control)
   • Manager (manage vaults)
   • Member (standard access)
   • Guest (limited access)
   • Auditor (read-only logs)
4. Set optional restrictions:
   • IP whitelist
   • Time-based access (temporary)
   • Vault access limitations
5. Send invitation

Vault-Level Permissions (Vault Owner):

1. Open vault � Settings � Sharing
2. Click Add Collaborator
3. Select user and role:
   • Vault Owner (full control)
   • Collaborator (edit access)
   • Contributor (upload only)
   • Viewer (read only)
4. Set optional expiration date
5. Save changes

Revoking Permissions

Immediate Revocation:

• Remove user from account/vault
• User loses access instantly
• Active sessions terminated
• API keys invalidated
• Audit log entry created

Temporary Suspension:

• Suspend user account (retain data)
• All access blocked
• Can be unsuspended later
• Useful for investigations

Offboarding Process (Enterprise):

1. HR initiates offboarding in IdP (e.g., Okta)
2. SSO integration triggers Torvus deprovisioning
3. User account suspended automatically
4. Vault ownership transferred to manager
5. API keys revoked
6. Access logs archived
7. Account deleted after retention period

---

Access Policies

Conditional Access

Conditions for Access:

Time-Based Access:

{
  "policy": "business_hours_only",
  "conditions": {
    "time": {
      "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "hours": "09:00-17:00",
      "timezone": "America/New_York"
    }
  },
  "action": "deny_outside_hours"
}

Location-Based Access:

{
  "policy": "corporate_network_only",
  "conditions": {
    "ip_ranges": ["192.168.0.0/16", "10.0.0.0/8"],
    "countries": ["US", "GB", "CA"],
    "vpn_required": true
  },
  "action": "require_mfa_outside_network"
}

Device-Based Access:

{
  "policy": "managed_devices_only",
  "conditions": {
    "device_compliance": "managed",
    "os_version": ">=iOS 15 OR >=macOS 12",
    "disk_encryption": "required"
  },
  "action": "deny_unmanaged_devices"
}

Break Glass Access

Emergency Access Override (Enterprise):

Use Cases:

• Security incident response
• Vault owner incapacitated
• Critical business continuity
• Legal/compliance requirements

Break Glass Procedure:

1. Request: Authorized personnel request break glass access
2. Approval: Requires 2-person approval (4-eyes principle)
3. Activation: Time-limited access granted (1-24 hours)
4. Monitoring: All actions logged and monitored in real-time
5. Review: Post-incident review and audit
6. Revocation: Access automatically revoked after time limit

Audit Trail:

{
  "event": "break_glass_access",
  "requester": "john.doe@company.com",
  "approvers": ["jane.smith@company.com", "bob.jones@company.com"],
  "reason": "CEO incapacitated - access to business continuity vault",
  "duration": "4 hours",
  "vault_id": "vault_emergency_001",
  "actions_taken": [
    {"timestamp": "2025-10-08T14:30:00Z", "action": "vault_access"},
    {"timestamp": "2025-10-08T14:35:00Z", "action": "document_download", "document": "succession_plan.pdf"},
    {"timestamp": "2025-10-08T14:40:00Z", "action": "recipient_notify"}
  ],
  "revoked_at": "2025-10-08T18:30:00Z"
}

---

Audit & Monitoring

Access Logs

What's Logged:

•  User login/logout
•  MFA successes/failures
•  Permission changes
•  Vault access
•  Document downloads
•  API key usage
•  SSO authentication
•  Failed access attempts

Log Format:

{
  "timestamp": "2025-10-08T14:23:45Z",
  "event_type": "vault_access",
  "user_id": "user_abc123",
  "user_email": "john.doe@example.com",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "vault_id": "vault_xyz789",
  "action": "view_documents",
  "result": "success",
  "mfa_method": "totp",
  "session_id": "session_def456"
}

Log Retention: 7 years (compliance requirement)

Real-Time Alerts

Alert Triggers:

• =� Failed login attempts (5+ in 10 minutes)
• =� MFA bypass attempts
• =� Permission elevation
• =� Unusual access patterns (geolocation, time)
• =� Bulk document downloads
• =� API key compromise indicators
• =� Break glass access activation

Alert Channels:

• Email notifications
• SMS alerts (critical only)
• Webhook to SIEM (Splunk, Datadog)
• Slack/Teams integration
• PagerDuty integration

Anomaly Detection

Machine Learning-Based Detection:

• Unusual login times (user typically logs in 9-5, now logging in at 3 AM)
• Unusual locations (user in US, login from Russia)
• Unusual download patterns (bulk downloads of all documents)
• Unusual permission requests (user suddenly requesting admin access)

Automated Responses:

1. Low Risk: Log event, no action
2. Medium Risk: Require MFA re-authentication
3. High Risk: Suspend session, require security review
4. Critical: Auto-suspend account, notify security team

---

Best Practices

For Vault Owners

1.  Enable MFA: Use TOTP or WebAuthn
2.  Review Permissions Quarterly: Ensure users have appropriate access
3.  Use Vault Roles: Don't grant account-level access unnecessarily
4.  Set Expiration Dates: Use time-limited access for temporary collaborators
5.  Monitor Access Logs: Review audit logs monthly

For Administrators

1.  Principle of Least Privilege: Grant minimum necessary permissions
2.  Regular Access Reviews: Quarterly review of all user permissions
3.  SSO Integration: Use corporate SSO for centralized control
4.  Conditional Access Policies: Implement time/location-based restrictions
5.  Automated Deprovisioning: Integrate with HR systems for offboarding

For Developers

1.  API Key Scoping: Request only necessary scopes
2.  Key Rotation: Rotate API keys every 90 days
3.  Secure Storage: Store keys in secret managers (AWS Secrets Manager, Vault)
4.  IP Whitelisting: Restrict API keys to known IP ranges
5.  Monitor Usage: Review API key usage logs weekly

---

FAQ

Q: Can I share a vault with someone outside my organization? A: Yes, you can add any email address as a vault recipient or collaborator. External users will need to create a free Torvus account to access shared vaults.

Q: What happens if I remove a collaborator? A: They immediately lose access to the vault. Active sessions are terminated, and they can no longer view or download documents.

Q: Can I see who accessed my vault? A: Yes, go to Vault � Activity to see all access logs including user, timestamp, IP address, and actions taken.

Q: How do I reset my MFA if I lose my device? A: Use backup codes provided during MFA setup. If you lost backup codes, contact support with identity verification (government ID required).

Q: Can administrators access my private vaults? A: Account administrators cannot access your vaults unless you explicitly grant them permission. Torvus staff also cannot access vault contents without legal process.

---

Related Documentation

• Security Architecture: Overall security design
• Encryption & Data Protection: How data is encrypted
• Compliance: SOC 2, ISO 27001, GDPR, CCPA
• Security Best Practices: Security recommendations

---

Last Updated: October 8, 2025