This document provides a comprehensive overview of Arkfile's security architecture, cryptographic design, and operational security procedures.

1. Architecture Overview
2. File Encryption System
3. Authentication System
4. Session Management
5. Infrastructure Security
6. Security Operations
7. Monitoring and Alerting
8. Incident Response
9. Threat Detection

Arkfile's security model uses client-side encryption to ensure that user data remains protected from unauthorized access, including by service administrators. The system maintains strict cryptographic separation between two primary security domains: user authentication and file encryption.

This separation ensures that compromise of one system does not affect the security of the other, providing defense in depth through independent cryptographic operations.

Arkfile implements multiple layers of security:

1. Transport Layer: TLS 1.3 encryption for all communications
2. Authentication: OPAQUE password-authenticated key exchange (PAKE) with optional TOTP multi-factor authentication
3. File Encryption: AES-256-GCM with independent key derivation and multi-key support
4. Key Management: Secure key generation, storage, and rotation
5. Access Control: Role-based access with JWT token validation
6. Client-Side Security: TypeScript-based architecture with WebAssembly cryptographic operations
7. Audit Logging: Comprehensive security event tracking

┌─────────────────────────────────────────────────────────────┐
│                    ARKFILE SECURITY DOMAINS                 │
├─────────────────────────────────────────────────────────────┤
│  Authentication Domain (OPAQUE)                             │
│  ├── OPAQUE Server Private Key                              │
│  ├── User Authentication Envelopes                          │
│  └── Session Key Derivation                                 │
├─────────────────────────────────────────────────────────────┤
│  File Encryption Domain (Independent)                       │
│  ├── User-derived File Encryption Keys                      │
│  ├── AES-GCM Encrypted File Content                         │
│  └── Multi-key Envelope Support                             │
├─────────────────────────────────────────────────────────────┤
│  JWT Token Domain                                           │
│  ├── JWT Signing Keys (Rotatable)                           │
│  ├── Access Tokens                                          │
│  └── Refresh Tokens                                         │
└─────────────────────────────────────────────────────────────┘

The file encryption system uses secure key generation combined with AES-256-GCM for file encryption.

Key Generation:

• Cryptographically secure random key generation for each file
• Independent keys prevent cross-file compromise
• No password-derived keys that require salt storage
• Session-based key derivation from OPAQUE authentication

AES-256-GCM Encryption:

• 256-bit Advanced Encryption Standard
• Galois/Counter Mode for authenticated encryption
• Built-in integrity verification
• Unique initialization vectors for each operation

Version Control:

• Version bytes embedded in encryption format
• Enables future cryptographic upgrades
• Maintains compatibility with existing data

Integrity Verification:

• SHA-256 checksums computed before encryption
• Verification performed after decryption
• Detects corruption or tampering
• Additional layer beyond AES-GCM authentication

Chunked Processing:

• Files split into 16MB segments for large file handling
• Reliable transfer mechanism
• Consistent encryption key per file across all chunks
• Memory-efficient processing

Multi-Key System:

• Single file encrypted with multiple independent passwords
• File sharing without revealing primary password
• Unique encryption keys per share link
• Avoids file duplication through metadata management

Sharing Mechanism:

• Independent passwords for each share
• Expiration date controls
• Password hints for recipients
• Revocable share links

Arkfile implements OPAQUE (Oblivious Pseudorandom Functions for Key Exchange), a Password-Authenticated Key Exchange (PAKE) protocol that provides superior security properties compared to traditional password authentication.

OPAQUE Benefits:

• Passwords never transmitted to server
• Mutual authentication between client and server
• Resistance to offline dictionary attacks
• Protection against server compromise scenarios

Three-Phase Process:

1. Registration Phase:

   • Client generates cryptographic material
   • Server receives "envelope" without learning password
   • Envelope encrypted with password-derived keys

2. Authentication Phase:

   • Cryptographic handshake proves mutual authenticity
   • Client demonstrates password knowledge without revealing it
   • Server proves possession of legitimate authentication data

3. Key Exchange:

   • Secure session key establishment
   • Independent from file encryption keys
   • Ephemeral keys for forward secrecy

Protocol Security:

• Password-blind key exchange prevents server learning passwords
• Mutual authentication ensures both parties are legitimate
• Forward secrecy through ephemeral session keys
• No password-derived salts stored server-side

Resistance Properties:

• Offline dictionary attack resistance
• Server compromise protection
• Pre-computation attack immunity
• Side-channel attack mitigation

Arkfile provides optional TOTP-based multi-factor authentication as an additional security layer beyond OPAQUE. When enabled, users must complete both OPAQUE authentication and provide a valid TOTP code to access their accounts.

TOTP Security Features:

• RFC 6238 compliant implementation using HMAC-SHA1
• 30-second time windows with one-step tolerance for clock skew
• Cryptographically secure secret generation (32 bytes entropy)
• Backup codes for account recovery (10 codes, single use)
• Session key integration for enhanced security

Authentication Flow Enhancement: When TOTP is enabled, the OPAQUE login process returns a temporary token instead of full access credentials. This temporary token permits only TOTP verification operations and expires after 10 minutes if unused. Upon successful TOTP verification, the system issues full access and refresh tokens for normal operation.

Recovery Mechanisms: The system generates cryptographically secure backup codes during TOTP setup. Each backup code is a 12-character alphanumeric string that can be used once in place of a TOTP code. Used backup codes are immediately invalidated and logged as security events. Backup codes provide essential account recovery when the primary TOTP device is unavailable.

Integration Security: TOTP secrets are encrypted using the user's OPAQUE-derived session key, ensuring that TOTP data remains cryptographically bound to the user's password. This approach prevents TOTP bypass attacks even in scenarios where database access is compromised but user passwords remain secure.

Arkfile enforces different password requirements based on the authentication context. All requirements are defined in a single source of truth (crypto/password-requirements.json) and embedded at build time into both the Go server/CLI and the TypeScript client. Validation is deterministic: a password either meets the minimum length and character class requirements or it does not.

Account and Custom Password Requirements:

• Minimum 15 characters with at least 2 of 4 character classes (uppercase, lowercase, number, special character)
• Real-time validation provides immediate feedback during password creation
• Uses OPAQUE protocol providing complete zero-knowledge authentication

Share Password Requirements:

• Minimum 20 characters with at least 2 of 4 character classes (uppercase, lowercase, number, special character)
• Uses Argon2id with 128 MiB memory cost for anonymous access
• Limited attack surface affecting only shared files

Validation Approach: The system uses a straightforward, deterministic check: passwords must meet the minimum length for their context and contain characters from at least 2 of the 4 character classes (uppercase letters, lowercase letters, numbers, special characters). This approach provides clear, predictable requirements that users can easily satisfy while still ensuring strong passwords through generous minimum lengths and the memory-hard Argon2id key derivation that makes brute-force attacks impractical.

Arkfile uses the same account password for two completely independent purposes: OPAQUE authentication and file encryption key derivation. These two uses are cryptographically separated and never interact.

Account Password for Authentication (OPAQUE). The account password is used with the OPAQUE protocol to authenticate the user. OPAQUE performs a password-authenticated key exchange in which the client proves knowledge of the password without ever transmitting it. The server never learns the password at any point during registration or login. OPAQUE has its own internal key derivation and does not use Argon2id. The output of a successful OPAQUE authentication is a set of session keys used for JWT token issuance and session management.

Account Password for File Encryption (Argon2id -> Account Key). The same account password is used separately, entirely on the client side, to derive an Account Key via Argon2id. This Account Key serves as a Key Encryption Key (KEK). For each file, a cryptographically random 256-bit File Encryption Key (FEK) is generated, and the FEK is wrapped (encrypted) by the KEK using AES-256-GCM. The file data itself is encrypted with the FEK. The salt for this derivation is deterministic, computed as SHA-256("arkfile-account-key-salt:{username}"). This is safe because the Argon2id-derived key only wraps the FEK — the actual file encryption uses random FEKs with unique nonces, and the memory-hard properties of Argon2id protect the KEK even with a known salt.

Custom Password for File Encryption (Argon2id -> Custom Key). Users may optionally provide a custom password instead of using their account key to encrypt a file. This custom password goes through the same Argon2id derivation with a different deterministic salt (SHA-256("arkfile-custom-key-salt:{username}")), producing a Custom Key (KEK) that wraps the FEK. The encrypted envelope format distinguishes account-wrapped from custom-wrapped FEKs via a key type byte (0x01 for account, 0x02 for custom), so the client knows which password to request at decryption time.

Share Password for Secure Sharing (Argon2id -> Share Key). When a user creates a share link, a separate share password is required. Unlike account and custom passwords, share passwords use a random 32-byte salt (not deterministic). The share password is processed through Argon2id to derive a Share Key, which encrypts a Share Envelope containing the FEK, a download token, and file metadata (filename, size, SHA-256 hash). The encryption uses AES-GCM with Additional Authenticated Data (AAD = share_id + file_id) to cryptographically bind the envelope to a specific share. Recipients enter the share password, derive the same key, decrypt the envelope, extract the FEK, and decrypt the file. The share password is never sent to the server.

All password-based key derivation contexts (account key, custom key, and share key) use the same unified Argon2id profile, defined as a single source of truth in crypto/argon2id-params.json and embedded at build time into both the Go server and the TypeScript client:

• Variant: Argon2id (resistant to both side-channel and GPU-based attacks)
• Memory cost: 128 MiB (131,072 KiB)
• Time cost: 4 iterations
• Parallelism: 1 thread
• Output key length: 32 bytes (256 bits)

These parameters exceed the strongest OWASP-recommended configuration for Argon2id (m=47,104 KiB / 46 MiB, t=1, p=1) as of 2026 by using significantly more memory and more iterations. Parallelism is set to 1 because the client-side key derivation runs in a browser WebAssembly context, which is single-threaded. Setting parallelism higher than 1 would not actually parallelize the computation in a browser — it would instead multiply the sequential work, increasing latency without improving security. With p=1 and t=4 at 128 MiB, the derivation is expected to take approximately 1–3 seconds in modern browsers, which is practical for interactive authentication while being extremely costly for attackers to brute-force.

ArkFile implements a Netflix/Spotify-style authentication model with enhanced security and performance characteristics:

Token Architecture:

• 30-minute access tokens: Short-lived tokens for enhanced security
• Automatic refresh at 25 minutes: Proactive token renewal before expiration
• Lazy revocation checking: Revocation only checked during token refresh for optimal performance
• Security-critical revocation: Immediate revocation for critical security scenarios
• Go/WASM client implementation: High-performance client-side token management
• Secure storage with HttpOnly, Secure, SameSite=Strict cookies

Session Security:

• Performance optimized: Normal requests don't check revocation for maximum speed
• Enhanced refresh cycle: 30-minute token lifecycle with 25-minute refresh intervals
• Stateless and scalable token validation
• Cryptographically independent from file encryption
• Session keys derived from OPAQUE authentication
• Distributed deployment support

Token Lifecycle Management:

1. Initial Authentication: 30-minute token issued after OPAQUE authentication
2. Automatic Refresh: Client automatically refreshes token at 25-minute mark
3. Lazy Revocation: Revocation checking only performed during refresh operations
4. Performance Optimization: Normal API requests skip revocation checks for speed
5. Security Edge Cases: Critical revocations processed immediately when required

Authorization Enforcement:

• Application-level access control
• Principle of least privilege
• User-specific file access only
• Comprehensive rate limiting across all endpoints

Rate Limiting Features:

• Progressive penalty system with exponential backoff (30s → 60s → 2min → 4min → 8min → 15min → 30min cap)
• Brute force attack prevention with EntityID-based privacy protection
• Anonymous request tracking without storing IP addresses
• Advanced pattern detection for abuse mitigation

User Account Security:

• Dedicated, unprivileged arkfile service account
• Single unified user/group/service definition
• Limited system access and capabilities
• Proper file permissions and ownership

Network Security:

• TLS encryption for all communications
• Strong cipher suites and security headers
• Distributed rqlite database with TLS
• Authentication required for all operations

Key Hierarchy:

Root Security
├── OPAQUE Server Private Key (Long-term, stable)
├── JWT Signing Keys (Rotatable)
└── File Encryption Keys (User-derived)

Storage Security:

• Hardware security module (HSM) ready architecture
• Secure key generation and storage
• Automated key rotation capabilities
• Encrypted filesystem storage with proper permissions

Backup and Recovery:

• Secure backup procedures for critical keys
• Disaster recovery mechanisms
• Key integrity verification
• Strict access controls for backup materials

Key Storage Security:

# Directory structure
/opt/arkfile/etc/keys/
├── opaque/               # OPAQUE server keys (never rotated)
├── jwt/                  # JWT signing keys (rotatable)
└── backup/               # Encrypted key backups

File Permissions:

• Key directories: 700 permissions
• Private keys: 600 permissions
• Owned by arkfile user and group
• No world-readable access

Key Rotation Procedures:

# JWT key rotation (weekly)
./scripts/maintenance/rotate-jwt-keys.sh

# Emergency rotation (immediate)
./scripts/maintenance/rotate-jwt-keys.sh --force

# OPAQUE key backup (monthly)
./scripts/maintenance/backup-keys.sh

OPAQUE Protocol Security:

• Pure OPAQUE registration and authentication flow
• OPAQUE blinding prevents password transmission
• No client-side password hardening needed
• Mutual authentication with replay protection

Session Validation:

# Monitor active sessions
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/sessions

# Revoke specific session
curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/sessions/$SESSION_ID

Arkfile records security events without storing client IP addresses. Instead, each log entry contains an anonymised entity ID derived daily from a server-side HMAC key (see logging/entity_id.go). Events are written to the security_events table in the rqlite database and to structured JSON logs under /var/log/arkfile/. Administrators can stream or export these records into any external monitoring or alerting system as needed.

Critical Events (Immediate Response):

• Multiple authentication failures from single entity
• Suspicious access patterns
• Key file modifications
• Emergency procedure activations
• Database integrity failures

Warning Events (Review Within Hours):

• Rate limit violations
• JWT refresh failures
• Configuration changes
• Unusual file access patterns

Info Events (Daily Review):

• Successful authentications
• Key health checks
• System startup/shutdown
• Routine maintenance operations

Event Tracking:

• Authentication attempts with entity ID anonymization
• Rate limiting triggers and violations
• Potential abuse pattern detection
• System configuration changes
• Emergency procedure activations

Log Analysis:

# View recent critical events
rqlite -H localhost:4001 \
  "SELECT * FROM security_events WHERE severity='CRITICAL' 
   AND timestamp > datetime('now', '-24 hours');"

# Analyze authentication patterns
rqlite -H localhost:4001 \
  "SELECT entity_id, count(*) as attempts
   FROM security_events 
   WHERE event_type LIKE '%login%' 
   GROUP BY entity_id 
   HAVING attempts > 10;"

# Show critical events from the last hour
rqlite -H localhost:4001 \
  "SELECT * FROM security_events WHERE severity='CRITICAL' \
   AND timestamp > datetime('now', '-1 hour');"

Severity Levels:

1. Critical (Immediate Response):

   • Key compromise suspected
   • Active brute force attack
   • Database integrity failure
   • Authentication bypass detected

2. High (Response within 2 hours):

   • Suspicious access patterns
   • Rate limiting failures
   • Configuration tampering
   • Service availability issues

3. Medium (Response within 24 hours):

   • Policy violations
   • Unusual usage patterns
   • Performance degradation
   • Audit compliance issues

Immediate Actions:

# Stop service if compromise suspected
sudo systemctl stop arkfile

# Backup current state
./scripts/maintenance/backup-keys.sh

# Capture logs
sudo journalctl -u arkfile --since "1 hour ago" > incident-logs.txt

Assessment Phase:

# Run security audit
./scripts/maintenance/security-audit.sh

# Check file integrity
find /opt/arkfile/etc/keys -type f -exec sha256sum {} \; > file-hashes.txt

# Analyze recent security events
rqlite -H localhost:4001 \
  "SELECT * FROM security_events 
   WHERE timestamp > datetime('now', '-24 hours') 
   ORDER BY severity DESC, timestamp DESC;"

Containment Actions:

# Rotate JWT keys immediately
./scripts/maintenance/rotate-jwt-keys.sh --force

# Revoke all active sessions
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/revoke-all-sessions

# Enable enhanced monitoring
sudo systemctl edit arkfile
# Add: [Service] Environment="LOG_LEVEL=debug"

CRITICAL: OPAQUE Server Key Compromise

If OPAQUE server key compromise is suspected:

# WARNING: This invalidates ALL user accounts
# Only execute if absolutely certain of compromise

# 1. Immediate service shutdown
sudo systemctl stop arkfile

# 2. Backup everything
sudo tar -czf /opt/arkfile/backups/emergency-backup-$(date +%Y%m%d-%H%M%S).tar.gz \
  /opt/arkfile/var/lib /opt/arkfile/etc/keys

# 3. Generate new OPAQUE server key
./scripts/setup/03-setup-opaque-keys.sh --force

# 4. Clear all user authentication data
rqlite -H localhost:4001 \
  "DELETE FROM opaque_registrations; DELETE FROM opaque_server_keys;"

# 5. Notify all users of required re-registration
echo "ALL USERS MUST RE-REGISTER - OPAQUE KEY ROTATED DUE TO SECURITY INCIDENT"

Arkfile is pre-release software and has no formal security certifications.
The features below describe on-disk logging and in-app event tracking only.

Required Audit Events:

• All authentication attempts (success/failure)
• Key management operations
• Administrative actions
• Configuration changes
• Emergency procedures
• Data access patterns

Audit Log Retention:

• Security Events: 90 days minimum
• Authentication Logs: 1 year
• Key Management: 7 years
• Emergency Procedures: Permanent

Weekly Tasks:

# Security event review
./scripts/maintenance/security-audit.sh

# Key health verification
./scripts/maintenance/health-check.sh

# Authentication pattern analysis
rqlite -H localhost:4001 \
  "SELECT date(timestamp) as day, count(*) as attempts
   FROM security_events 
   WHERE timestamp > datetime('now', '-7 days')
   GROUP BY date(timestamp);"

Monthly Tasks:

# Comprehensive security assessment
./scripts/maintenance/security-audit.sh --comprehensive

# Key backup verification
./scripts/maintenance/backup-keys.sh --verify

# Performance security baseline
./scripts/testing/performance-benchmark.sh

Brute Force Detection:

# Monitor authentication failure patterns
rqlite -H localhost:4001 \
  "SELECT entity_id, count(*) as failures
   FROM security_events 
   WHERE event_type='opaque_login_failure'
   AND timestamp > datetime('now', '-24 hours')
   GROUP BY entity_id
   HAVING count(*) > 10;"

Credential Stuffing Detection:

# Detect rapid attempts across multiple accounts
rqlite -H localhost:4001 \
  "SELECT entity_id, count(DISTINCT username) as unique_users
   FROM security_events 
   WHERE event_type IN ('opaque_login_failure', 'opaque_login_success')
   AND timestamp > datetime('now', '-1 hour')
   GROUP BY entity_id
   HAVING unique_users > 5;"

Suspicious Access Patterns:

# Identify unusual file access patterns
rqlite -H localhost:4001 \
  "SELECT username, count(*) as file_accesses
   FROM security_events 
   WHERE event_type='file_access'
   AND timestamp > datetime('now', '-1 hour')
   GROUP BY username
   HAVING file_accesses > 100;"

Dynamic Rate Limiting:

# Adaptive rate limiting based on threat level
THREAT_LEVEL=$(rqlite -H localhost:4001 \
  "SELECT CASE 
     WHEN count(*) > 100 THEN 'HIGH'
     WHEN count(*) > 50 THEN 'MEDIUM'
     ELSE 'LOW'
   END
   FROM security_events 
   WHERE event_type='rate_limit_violation'
   AND timestamp > datetime('now', '-1 hour')")

# Adjust rate limits based on threat level
case "$THREAT_LEVEL" in
    "HIGH")   # Aggressive rate limiting
        curl -X POST http://localhost:8080/admin/rate-limit \
          -d '{"requests_per_hour": 10, "burst": 5}' ;;
    "MEDIUM") # Enhanced rate limiting  
        curl -X POST http://localhost:8080/admin/rate-limit \
          -d '{"requests_per_hour": 50, "burst": 10}' ;;
    "LOW")    # Normal rate limiting
        curl -X POST http://localhost:8080/admin/rate-limit \
          -d '{"requests_per_hour": 100, "burst": 20}' ;;
esac

Entity Blocking Automation:

# Automatic blocking for severe violations
MALICIOUS_ENTITIES=$(rqlite -H localhost:4001 \
  "SELECT entity_id FROM security_events 
   WHERE event_type='opaque_login_failure'
   AND timestamp > datetime('now', '-1 hour')
   GROUP BY entity_id
   HAVING count(*) > 50")

for entity in $MALICIOUS_ENTITIES; do
    logger "Blocking entity: $entity for excessive failures"
    # Implement entity blocking logic
done

Key Performance Indicators:

• Authentication Success Rate: >95%
• Average Response Time: <500ms
• False Positive Rate: <1%
• Mean Time to Detection: <15 minutes
• Mean Time to Response: <2 hours

Security Dashboard Generation:

# Generate security metrics report
DATE=$(date +"%Y-%m-%d")
echo "Arkfile Security Metrics Report - $DATE"

# Authentication metrics (Last 24 hours)
echo "Authentication Metrics:"
rqlite -H localhost:4001 \
  "SELECT 
    'Total Attempts: ' || count(*),
    'Successful: ' || sum(case when event_type='opaque_login_success' then 1 else 0 end),
    'Success Rate: ' || printf('%.2f%%', 
      100.0 * sum(case when event_type='opaque_login_success' then 1 else 0 end) / count(*)
    )
   FROM security_events 
   WHERE event_type IN ('opaque_login_success', 'opaque_login_failure')
   AND timestamp > datetime('now', '-24 hours');"

# Rate limiting metrics
echo "Rate Limiting Violations:"
rqlite -H localhost:4001 \
  "SELECT count(*) FROM security_events 
   WHERE event_type='rate_limit_violation'
   AND timestamp > datetime('now', '-24 hours');"

# Top security events (Last 7 days)
echo "Top Security Events:"
rqlite -H localhost:4001 \
  "SELECT event_type, count(*) as occurrences
   FROM security_events 
   WHERE timestamp > datetime('now', '-7 days')
   GROUP BY event_type
   ORDER BY count(*) DESC
   LIMIT 10;"

1. Level 1: System Administrator (Response: 30 minutes)
2. Level 2: Security Team Lead (Response: 2 hours)
3. Level 3: Security Director (Response: 4 hours)
4. Level 4: Executive Team (Response: 24 hours)

# Emergency service stop
sudo systemctl stop arkfile

# Emergency key rotation
./scripts/maintenance/rotate-jwt-keys.sh --force

# Security audit
./scripts/security-audit.sh

# Health check
curl http://localhost:8080/health

# View recent critical events
rqlite -H localhost:4001 \
  "SELECT * FROM security_events WHERE severity='CRITICAL' 
   AND timestamp > datetime('now', '-1 hour');"

• Forward Secrecy: Ephemeral session keys
• Server Impersonation Protection: OPAQUE mutual authentication
• Replay Attack Prevention: Protocol-level nonce handling
• Domain Separation: Independent cryptographic contexts

• Application Logs: sudo journalctl -u arkfile
• Security Events: rqlite database table security_events
• System Logs: /var/log/arkfile/
• Audit Logs: Comprehensive event tracking in database

This security guide should be reviewed quarterly and updated based on emerging threats, security research, and operational experience.

For setup instructions, see Setup Guide. For API integration, see API Reference.

Questions, comments or bug reports? Email arkfile [at] pm [dot] me or open an issue on GitHub.

Please avoid posting sensitive information in public issues.