Enterprise FizzBuzz Platform v1.0.0

1. Overview
2. Role Hierarchy
3. Permission Model
4. Token Authentication
5. Trust-Mode Authentication
6. Authorization Middleware
7. Access Denied Response Specification
8. Configuration
9. Compliance

The Enterprise FizzBuzz Platform implements a comprehensive Role-Based Access Control (RBAC) system to govern access to FizzBuzz evaluation operations. The ability to compute n % 3 is a privilege, not a right, and the authorization framework enforces this principle at every layer of the middleware pipeline.

The system is implemented in enterprise_fizzbuzz/infrastructure/auth.py and relies on domain models defined in enterprise_fizzbuzz/domain/models.py. It provides:

• A five-tier role hierarchy with permission inheritance
• Granular permission strings scoped to numeric ranges and actions
• HMAC-SHA256 token-based authentication
• A trust-mode bypass for development and testing
• A 47-field access denied response body (the field count is asserted at runtime)
• Middleware-based authorization enforcement at pipeline priority -10

The RBAC module references four custom exceptions from enterprise_fizzbuzz/domain/exceptions.py:

The platform defines five roles in the FizzBuzzRole enum (enterprise_fizzbuzz/domain/models.py). Each role inherits all permissions from its parent in the hierarchy, which is maintained by the RoleRegistry class (enterprise_fizzbuzz/infrastructure/auth.py).

ANONYMOUS
  └── FIZZ_READER
        ├── BUZZ_ADMIN
        │     └── FIZZBUZZ_SUPERUSER
        └── NUMBER_AUDITOR

The RoleRegistry._HIERARCHY dict maps each role to its parent:

These are the permissions granted directly to each role, not including inherited permissions. Defined in RoleRegistry._DIRECT_PERMISSIONS.

ANONYMOUS

• numbers:1:read

FIZZ_READER

• numbers:fizz:read
• numbers:1-50:evaluate

BUZZ_ADMIN

• numbers:buzz:read
• numbers:buzz:configure
• numbers:1-100:evaluate

FIZZBUZZ_SUPERUSER

• numbers:*:evaluate
• numbers:*:read
• numbers:*:configure

NUMBER_AUDITOR

• numbers:*:audit
• numbers:*:read

The RoleRegistry.get_effective_permissions() method walks up the hierarchy collecting all permissions from each ancestor. The effective permission set for each role:

When access is denied, the RoleRegistry.get_suggested_upgrade_path() method recommends the next role in the hierarchy. Every denial is also a sales opportunity.

All permissions follow the format resource:range_spec:action, parsed by the PermissionParser class.

The range_spec segment supports the following formats, resolved by PermissionParser._range_contains_number():

The PermissionParser.matches() method determines whether a granted permission covers a required permission. The rules:

1. Resource must match exactly. A numbers grant does not cover a hypothetical strings requirement.
2. Action must match exactly. An evaluate grant does not satisfy a read requirement.
3. Range matching follows containment logic:
   • A wildcard * grant covers any required range.
   • If the required range is *, only a wildcard grant can satisfy it.
   • If the required range resolves to a single number, the grant is checked using _range_contains_number().
   • For non-numeric required ranges, only an exact match satisfies the requirement.

The following actions are used in the current permission model:

Enterprise FizzBuzz Platform tokens use the format:

EFP.<base64url_payload>.<hmac_sha256_hex>

This is, as the source code notes, "suspiciously similar to JWT but legally distinct enough to avoid licensing fees."

The token payload contains exactly nine fields, defined in FizzBuzzTokenEngine.generate_token():

The FizzBuzzTokenEngine._CLEARANCE_LEVELS dict maps each role to a (fizz_clearance, buzz_clearance) tuple:

The favorite_prime field is populated from the following curated list:

2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47

Selection is random. The platform makes no representations about the suitability of any particular prime for any particular user. The inclusion of 47 in this list is, of course, not a coincidence.

To generate a token programmatically:

from enterprise_fizzbuzz.infrastructure.auth import FizzBuzzTokenEngine
from enterprise_fizzbuzz.domain.models import FizzBuzzRole

token = FizzBuzzTokenEngine.generate_token(
    user="alice",
    role=FizzBuzzRole.BUZZ_ADMIN,
    secret="your-signing-secret",
    ttl_seconds=3600,              # optional, defaults to 3600
    issuer="enterprise-fizzbuzz-platform",  # optional
)

The payload JSON is serialized with separators=(",", ":") and sort_keys=True to ensure deterministic output. The base64url encoding strips trailing = padding.

FizzBuzzTokenEngine.validate_token() performs validation in the following order:

1. Format check. The token must contain exactly three dot-separated segments, and the first segment must be "EFP".
2. Signature verification. The HMAC-SHA256 of the base64url payload is computed and compared against the provided signature using hmac.compare_digest() (constant-time comparison to prevent timing attacks).
3. Payload decoding. The base64url segment is padded and decoded. The resulting bytes are parsed as JSON.
4. Required fields check. The fields sub, role, iat, exp, jti, and iss must be present. (Note: fizz_clearance_level, buzz_clearance_level, and favorite_prime are not checked at validation time.)
5. Expiration check. The exp field must be greater than or equal to the current Unix timestamp.
6. Role resolution. The role field must correspond to a valid FizzBuzzRole enum member.

On success, validate_token() returns an AuthContext with trust_mode=False and the role's effective permissions resolved via RoleRegistry.get_effective_permissions().

On failure at any step, a TokenValidationError is raised with a diagnostic message that is informative, specific, and slightly judgmental.

Trust-mode authentication bypasses token verification entirely. It is activated by the --user CLI flag and is, as the source code describes it, "the 'just trust me' protocol, which is exactly as secure as it sounds."

The authentication logic in enterprise_fizzbuzz/__main__.py follows this precedence:

1. --token is present: Token-based authentication. The token is validated via FizzBuzzTokenEngine.validate_token(). If validation fails, the process exits with return code 1.
2. --user is present (no --token): Trust-mode authentication. An AuthContext is constructed directly with trust_mode=True. The role is taken from --role if provided, otherwise from the config default.
3. Neither --token nor --user, but RBAC is enabled in config: The user is set to "anonymous" with the default role. trust_mode is False.
4. RBAC is not enabled and no auth flags are provided: No AuthContext is created. The AuthorizationMiddleware is not added to the pipeline.

When trust-mode authentication is activated, the platform emits a warning to standard output:

+---------------------------------------------------------+
| WARNING: Trust-mode authentication enabled.             |
| The user's identity has not been cryptographically      |
| verified. This is the security equivalent of writing    |
| your password on a Post-It note and sticking it to     |
| your monitor. Proceed with existential dread.          |
+---------------------------------------------------------+

This warning is not suppressible. The existential dread is mandatory.

Module: enterprise_fizzbuzz/infrastructure/auth.py Interface: IMiddleware (from enterprise_fizzbuzz/domain/interfaces) Priority: -10

The AuthorizationMiddleware runs before all other middleware in the pipeline. Its priority of -10 ensures that unauthorized requests are rejected before any downstream processing occurs — there is no point in breaking a circuit if the user does not have permission to close it in the first place.

For each number processed through the pipeline, the middleware:

1. Constructs the required permission. The required permission is always numbers:<N>:evaluate, where <N> is the number being processed.

2. Checks all effective permissions. Iterates over the AuthContext.effective_permissions tuple and calls PermissionParser.matches() for each granted permission against the required permission.

3. On success:

   • Publishes an AUTHORIZATION_GRANTED event to the event bus (if available).
   • Stamps context.metadata["auth_user"] and context.metadata["auth_role"] on the processing context.
   • Passes the context to the next handler in the chain.

4. On failure:

   • Builds the 47-field access denied response via AccessDeniedResponseBuilder.build().
   • Publishes an AUTHORIZATION_DENIED event to the event bus (if available).
   • Raises InsufficientFizzPrivilegesError with the denial body attached. The exception message includes a motivational quote selected from the denial response.

When a user is denied access to a FizzBuzz evaluation, the AccessDeniedResponseBuilder.build() method constructs a response body containing exactly 47 fields. This count is enforced by a runtime assertion. It was established by the FizzBuzz Security Council in a meeting that ran 47 minutes over schedule, and the irony was not lost on anyone.

The following table lists all 47 fields in their construction order, grouped by category.

The AccessDeniedResponseBuilder.build() method includes a runtime assertion:

assert len(body) == 47, (
    f"Access denied response body has {len(body)} fields, "
    f"but exactly 47 are required. The FizzBuzz Security Council "
    f"will not be pleased."
)

Adding or removing a field without maintaining the count of 47 will result in an AssertionError. The FizzBuzz Security Council will not be pleased.

The RBAC system is configured through the following surfaces. See docs/configuration.md for complete configuration reference.

The RBAC module declares compliance with the following frameworks, as documented in the module docstring and the access denied response:

These compliance claims have not been independently audited. The platform's legal counsel has advised that compliance with FizzBuzz-RBAC-v2 is self-certifying, on the grounds that no external auditor has agreed to review it.

The containerization layer implements defense-in-depth security controls at every tier of the container stack. These controls ensure that the isolation, integrity, and auditability guarantees of the platform extend from the application layer down through the container runtime to the kernel resource boundaries.

FizzImage (enterprise_fizzbuzz/infrastructure/fizzimage.py) scans every container image against a simulated CVE database before the image enters the FizzRegistry. The scanning pipeline:

1. Dependency extraction: AST-based analysis identifies all Python imports in the image's module tree, building a complete dependency graph.
2. CVE matching: Each dependency is checked against known vulnerabilities in the simulated CVE database. Matches produce a severity-scored finding (CRITICAL, HIGH, MEDIUM, LOW).
3. Policy enforcement: Images with CRITICAL vulnerabilities are rejected from the registry. HIGH vulnerabilities generate a warning but permit publication. MEDIUM and LOW findings are logged for audit.
4. Continuous re-scanning: The FizzImage catalog periodically re-scans published images when the CVE database is updated, flagging newly discovered vulnerabilities in previously clean images.

FizzDeploy (enterprise_fizzbuzz/infrastructure/fizzdeploy.py) enforces a mandatory scan gate in its deployment pipeline. The SCAN stage must pass before the SIGN stage can proceed. Deployments referencing unscanned images are rejected.

FizzOCI (enterprise_fizzbuzz/infrastructure/fizzoci.py) enforces non-root execution by default. During container creation:

1. The OCI runtime configuration (config.json) specifies the container's UID and GID. The platform default maps the container process to a non-privileged user.
2. FizzNS (enterprise_fizzbuzz/infrastructure/fizzns.py) configures USER namespace mappings so that UID 0 inside the container maps to an unprivileged UID on the host. This provides root-like behavior within the container's isolated view while preventing privilege escalation to the host.
3. FizzOverlay (enterprise_fizzbuzz/infrastructure/fizzoverlay.py) sets the upper (writable) layer permissions to the mapped non-root UID, preventing unauthorized writes to the container filesystem from other processes.

FizzOCI applies seccomp (secure computing mode) syscall filtering during container creation. The seccomp profile:

1. Operates in whitelist mode: only explicitly permitted system calls are allowed. All others return EPERM.
2. The default profile permits the minimal set of syscalls required for Python process execution, including read, write, open, close, mmap, brk, futex, and clock_gettime.
3. Dangerous syscalls are blocked: mount, umount, ptrace, reboot, init_module, delete_module, sethostname, and pivot_root are denied by default.
4. Custom seccomp profiles can be specified per container in the OCI runtime configuration for subsystems with specialized syscall requirements.

FizzCNI (enterprise_fizzbuzz/infrastructure/fizzcni.py) implements network policy enforcement via label-based microsegmentation:

1. Default deny: Containers without an explicit network policy receive no inbound connectivity from other containers. Outbound traffic to the compose network is permitted by default.
2. Label selectors: Network policies match containers by labels (e.g., group=security, tier=data). A policy specifying allow: { from: { group: core } } permits inbound traffic only from containers labeled group=core.
3. Port-level rules: Policies can restrict allowed ports. A container exposing port 8080 can have a policy that only permits inbound connections on that port from specific label groups.
4. Policy evaluation order: Policies are evaluated in specificity order. A container-specific policy overrides a namespace-wide policy. Conflicting policies result in the most restrictive rule being applied.

FizzOCI integrates with the platform's capability security system (fizzcap.py) to enforce the principle of least privilege at the Linux capability level:

1. During container creation, FizzOCI drops all Linux capabilities except those explicitly required by the container's workload.
2. The default capability set retains only CAP_NET_BIND_SERVICE (for containers that bind to privileged ports) and CAP_SETUID/CAP_SETGID (for user namespace setup). All other capabilities, including CAP_SYS_ADMIN, CAP_NET_RAW, and CAP_SYS_PTRACE, are dropped.
3. Containers requesting elevated capabilities must declare them in the OCI runtime configuration. FizzDeploy's security review stage flags any deployment manifest that requests capabilities beyond the default set.

Every security-relevant container operation is recorded in the audit trail:

The audit trail is accessible through FizzContainerOps' structured log aggregation system, supporting both real-time monitoring and post-incident forensic analysis.