Version: 1.0
Status: Security Specification

This document defines the security principles and mechanisms for GopherQueue. Security is implemented at the Security Boundary layer and enforced across all external interfaces.

For service-to-service communication and programmatic access.

Header: Authorization: Bearer <api-key>

API Key Format: gq_<environment>_<random-32-bytes-base64>
Example: gq_prod_a3JpZGdlLXNlY3VyaXR5LWtleQ==

Properties:

• Keys are environment-scoped (prod, staging, dev)
• Keys are associated with a principal and role
• Keys can be revoked without affecting other keys
• Keys have optional expiration dates

For high-security deployments requiring bidirectional authentication.

Properties:

• Client presents certificate signed by trusted CA
• Certificate CN or SAN maps to principal identity
• Certificate roles encoded in custom extensions
• Supports certificate rotation without downtime

For in-process usage, authentication is implicit.

Properties:

• Library runs in same process; trust is inherited
• No network boundary; no credential transmission
• Application responsible for authorization before calling library

┌────────┐         ┌──────────────┐         ┌────────────┐
│ Client │─────────│ Auth Handler │─────────│ Auth Store │
└────────┘         └──────────────┘         └────────────┘
     │                    │                       │
     │ Request + Creds    │                       │
     ├───────────────────▶│                       │
     │                    │ Validate Credentials  │
     │                    ├──────────────────────▶│
     │                    │                       │
     │                    │ Principal + Roles     │
     │                    │◀──────────────────────┤
     │                    │                       │
     │ Authenticated Ctx  │                       │
     │◀───────────────────┤                       │

GopherQueue uses Role-Based Access Control (RBAC) with optional resource-level restrictions.

Hierarchy:

1. System-level roles grant baseline permissions
2. Resource-level rules can further restrict access
3. Deny always overrides allow

Jobs can be restricted to specific principals:

JobSubmission {
    ...
    security: {
        owner: "service-foo"        // Principal ID
        visibility: "owner"         // Only owner can view
        cancellable_by: ["owner", "operator"]
    }
}

1. Extract principal from authenticated context
2. Extract required permission from operation
3. Check system role permissions
4. If resource-specific, check resource-level rules
5. Apply deny rules
6. Return allow/deny decision

All authorization decisions are logged:

AuthorizationEvent {
    timestamp:      timestamp
    principal:      string
    action:         string
    resource:       string
    decision:       enum       // ALLOW | DENY
    reason:         string     // Why decision was made
    request_id:     string
}

For jobs containing sensitive payloads:

At-Rest Encryption:

• Job payloads encrypted before persistence
• AES-256-GCM with per-job encryption keys
• Key encryption keys rotated on configurable schedule

In-Transit Encryption:

• TLS 1.3 required for all external communication
• mTLS available for enhanced security

Application-Level Encryption:

• Applications may encrypt fields before submission
• GopherQueue provides encryption helpers but does not require their use

Job results follow the same classification as payloads:

• Confidential results are encrypted
• Results are purged according to retention policy
• Error messages are sanitized to prevent secret leakage

Sanitization Rules:
1. Payloads larger than 1KB are not logged
2. Fields matching /password|secret|token|key/i are masked
3. Confidential job types have all payload fields masked
4. Stack traces are retained; local variables are not

Submission Rate Limits:

Rate Limit Response:

HTTP 429 Too Many Requests
Retry-After: <seconds>

{
    "error": "QUOTA_EXCEEDED",
    "message": "Rate limit exceeded",
    "limit": "100/second",
    "retry_after": 1
}

Prevent queue flooding:

Per-principal resource quotas:

Quota {
    max_pending_jobs:       integer     // Max jobs in non-terminal state
    max_running_jobs:       integer     // Max concurrent executions
    max_job_priority:       enum        // Highest allowed priority
    max_execution_time:     duration    // Longest allowed timeout
    max_retention_days:     integer     // Longest result retention
}

Automated detection of abuse patterns:

┌─────────────────────────────────────────────┐
│                 EXTERNAL ZONE               │
│   (Untrusted: API clients, webhooks)        │
└─────────────────────┬───────────────────────┘
                      │ TLS Required
        ┌─────────────▼─────────────┐
        │     SECURITY BOUNDARY     │
        │  (Authentication, Authz)  │
        └─────────────┬─────────────┘
                      │
┌─────────────────────▼───────────────────────┐
│                INTERNAL ZONE                │
│   (Trusted: workers, persistence, etc.)     │
└─────────────────────────────────────────────┘

Minimum Requirements:

• TLS 1.2 (TLS 1.3 preferred)
• Strong cipher suites only
• Valid certificates (self-signed only in development)

Recommended Cipher Suites:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

For multi-zone deployments:

• API servers accept traffic from load balancer only
• Workers accept traffic from scheduler only
• Persistence accepts traffic from internal zone only
• Metrics endpoint can be isolated from main API

Workers run with minimal permissions:

• No network access (unless job requires it)
• Read-only filesystem (except temp)
• No elevated privileges
• Resource limits enforced

Events requiring investigation:

• Job records retained according to configurable policy
• Default: 30 days for completed, 90 days for failed
• Confidential jobs: 7 days or less
• Audit logs: 1 year minimum

Support for data deletion requests:

• Jobs can be purged by correlation ID
• Supports bulk deletion by principal or tag
• Deletion is permanent and logged

All security-relevant actions produce audit records:

• Authentication attempts (success and failure)
• Authorization decisions
• Configuration changes
• Data access for sensitive jobs
• Administrative actions

This security model provides defense in depth. Implementations should layer these controls and adapt to specific deployment contexts.