File size: 4,656 Bytes
ef6eb55 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | # ADR-0002: Authorization Boundary
**Status:** Accepted
**Date:** 2026-08-18
**Author:** SNAPKITTYWEST PAX-Coder Security Team
---
## Context
A public clone can verify integrity independently. However, some operations may require authorization:
- Accessing private proof-kernel secrets
- Signing attestations
- Modifying WORM-sealed records
- Publishing authorized artifacts
Authorization must NOT be enforceable by commenting out a Python conditional.
## Decision
Implement authorization as a separate capability that:
1. **Requires externally held secrets or server validation** — Not derived from client-side checks
2. **Fails closed** — Unauthorized execution produces an explicit error, not silent degradation
3. **Never corrupts state** — Authorization failure means "operation unavailable," not "output is garbage"
4. **Uses challenge/response** — Server validates authorization, not client
## Architecture
```
INTEGRITY_VERIFIED
↓
Request Protected Operation
↓
┌───────────────────────────────────┐
│ Authorization Boundary │
│ ├─ Node ID │
│ ├─ Release identity │
│ ├─ Server challenge (nonce) │
│ └─ Authorization protocol │
└───────────────────────────────────┘
↓
Authorization Service
│
├─ Validate authorization
├─ Check credentials
├─ Verify nonce
└─ Issue capability
↓
Short-lived Capability
↓
Protected Operation Available
```
## Rules
```yaml
rules:
- authorization MUST NOT depend solely on client-side conditionals
- authorization MUST NOT depend on machine fingerprint as cryptographic proof
- authorization MUST NOT embed private keys in the public repository
- authorization MUST NOT embed server secrets in the public clone
- unauthorized protected operations MUST fail closed with clear error
- authorization MUST use fresh nonces for replay protection
- authorization MUST use short-lived tokens
- authorization response MUST be cryptographically signed (if server-provided)
- authorization state MUST NOT be represented by silent corruption
```
## Implementation Strategy
### Phase 1: Integrity-Only (Now)
```
INTEGRITY_VERIFIED
↓
Protected operation: NOT AVAILABLE
↓
PAX-CODER AUTHORIZATION REQUIRED
Exit with clear error
```
### Phase 2: Authorization Service (Future)
When authorization service exists:
```
INTEGRITY_VERIFIED
↓
Request capability from authorization service
├─ Node ID
├─ Release identity
├─ Nonce
└─ TLS
↓
Authorization service validates
↓
Issue short-lived token
↓
Protected operation executes
↓
Token expires (e.g., 1 hour)
```
## Failure States
```
INTEGRITY_VERIFIED + NO_AUTHORIZATION
→ PAX-CODER AUTHORIZATION REQUIRED
→ Protected capability unavailable
INTEGRITY_VERIFIED + EXPIRED_AUTHORIZATION
→ Authorization expired
→ Re-authenticate
INTEGRITY_VERIFIED + INVALID_AUTHORIZATION
→ Authorization validation failed
→ Protected capability unavailable
INTEGRITY_FAILED
→ Skip authorization entirely
→ Fail with integrity error
```
## What This Does NOT Guarantee
- Modification is impossible (it is possible; just detectable)
- User cannot bypass authorization (they can modify code; just not manufacture capability)
- Protection is absolute (it's protection from casual misuse, not sophisticated attackers)
## Tests Required
- `test_unauthorized_denied`: Protected operation fails without authorization
- `test_authorization_required_error`: Clear error message when authorization missing
- `test_no_silent_corruption`: Unauthorized state does not silently corrupt output
- `test_capability_required`: Modifying Python check does not grant authorization
- `test_nonce_replay`: Replayed nonce rejected
- `test_token_expiration`: Expired token rejected
## Consequences
- Public clone cannot execute protected operations without external validation
- Authorization failure is explicit and non-recoverable
- Authorization is never represented by corrupted state
- Documentation must explain what operations require authorization
---
**Related ADRs:**
- ADR-0001: Public Clone Integrity
- ADR-0003: Fail-Closed Enforcement
- ADR-0004: Private Key Separation
|