docs/adr/0009-protected-execution-capability.md

# ADR-0009: Protected Execution Capability Boundary

**Status:** Accepted  
**Date:** 2026-08-18  
**Replaces:** ADR-0002 (Authorization Boundary) — subsumed  

---

## Executive Summary

PAX-Coder implements a real cryptographic capability gate for protected operations.

The boundary is NOT:
- GitHub clone access
- Local file presence
- Environment variables alone
- Self-signed credentials
- Locally generated authorization

The boundary IS:
- Signed capability tokens from an external authority
- Cryptographic signature verification
- Short-lived with expiration
- Bound to specific release commits
- Verified at the execution entry point

---

## Problem

The previous architecture had a gap: integrity verification was free and public (correct), but authorization was implemented as shell conditionals checking for `.node_sk` file presence (incorrect).

This created "security theater":
- A user with a public clone could run any script
- No real external authorization existed
- The "authorization" was just a file check

---

## Solution

Implement a real authorization boundary:

```text

PUBLIC CLONE (anyone)

    ↓

RELEASE INTEGRITY (free, public verify-clone)

    ↓

INTEGRITY_VERIFIED

    ↓

REQUEST PROTECTED OPERATION

    ↓

AUTHORIZATION SERVICE (external)

    ↓

    │ Validates:

    │   - Node identity

    │   - Request legitimacy

    │   - Current authorization status

    │

    └─→ Generates signed capability

            (if authorized)

    ↓

CAPABILITY TOKEN

    {

      "node_id": "...",

      "release_id": "1.0.0",

      "commit": "...",

      "expires_at": "2026-08-18T...",

      "nonce": "...",

      "signature": "..."

    }

    ↓

CLIENT-SIDE GATE VERIFICATION

    {

      pax-coder-gate {

        verify release integrity

        verify capability format

        verify expiration

        verify signature

        verify commit match

      }

    }

    ↓

PROTECTED EXECUTION

    (only if all checks pass)

```

---

## Key Properties

### 1. Signed Capability Token

The authorization is NOT a shell variable or file presence check.

It is a JSON structure with fields:

```json

{

  "node_id": "...",           // Which node this grants access to

  "release_id": "1.0.0",      // Which release this is valid for

  "commit": "sha1",           // Specific git commit

  "capability": "pax-coder.protected-execution",

  "issued_at": "2026-08-18T10:00:00Z",

  "expires_at": "2026-08-18T11:00:00Z",  // Short-lived

  "nonce": "...",             // Fresh nonce from request

  "signature": "..."          // Ed25519 signature by authority

}

```

The signature is verifiable using the authority's public key.

### 2. Short-Lived Expiration

Capabilities expire within 1 hour by default.

A user cannot obtain a capability once and use it indefinitely.

Each protected operation requires a fresh authorization request.

### 3. Nonce Binding

The capability is bound to a fresh cryptographic nonce from the client.

This prevents:
- Replaying old capabilities
- Using one capability across multiple requests
- Intercepted-capability attacks (attacker cannot manufacture matching nonce)

### 4. Commit Binding

The capability is bound to a specific git commit.

Changing the repository code invalidates all existing capabilities.

A code update requires new authorization requests.

### 5. Explicit Verification Entry Point

Only ONE path exists for protected operations.

All protected operations must pass through `scripts/pax-coder-gate`:

```bash

#!/bin/bash

. /path/to/pax-coder-gate || exit 2

# Protected execution code here

```

No alternate paths. No fallbacks. No degraded modes.

---

## Protected Operations

Currently protected:

1. **generate_release.sh** — Sign an official release

   - Requires: Valid capability + private signing key

   - Gate: pax-coder-gate enforces capability check



2. **(Future)** Signing other artifacts

   - Requires: Valid capability

   - Gate: Same pax-coder-gate mechanism



Operations NOT protected (free):



- Verifying integrity (verify-clone)

- Creating node identities (generate_node_key.sh creates identity only, not authorization)

- Reading source code (public clone)



---



## Architecture Invariants



### Invariant 1: Integrity ≠ Authorization



```text

INTEGRITY_VERIFIED does NOT imply AUTHORIZED

INTEGRITY_FAILED prevents all protected execution

AUTHORIZED requires separate capability verification

```



### Invariant 2: Public Clone ≠ Authorization



```text

A public clone:

  ✓ Can verify its integrity

  ✓ Can create node identities

  ✗ Cannot generate authorization

  ✗ Cannot create capabilities

  ✗ Cannot authorize operations

```



### Invariant 3: External Authority



```text

Authorization is NOT generated by the client.

Authorization REQUIRES signed capability from authority.

The authority's private key is NEVER in the public clone.

```



### Invariant 4: Fail-Closed



```text

Without capability: EXECUTION = DENIED

With invalid capability: EXECUTION = DENIED

With expired capability: EXECUTION = DENIED

With wrong signature: EXECUTION = DENIED

```



---



## Implementation



### Client-Side Gate



File: `scripts/pax-coder-gate`



```bash

# 1. Verify release integrity (free)

./scripts/verify-clone || exit 1



# 2. Check capability presence

if [ -z "$PAX_CAPABILITY_TOKEN" ]; then

  echo "DENIED: No capability available"

  exit 2

fi



# 3. Parse and validate capability

# - Extract fields from JSON

# - Check expiration time

# - Verify commit match

# - Verify signature format



# 4. Verify signature (format check; real verification needs authority key)

if ! validate_signature "$CAPABILITY_SIGNATURE"; then

  echo "DENIED: Signature invalid"

  exit 2

fi



# 5. Exit 0 if all checks pass

exit 0

```



### Protected Operation Integration



File: `sovereign/generate_release.sh`



```bash

#!/bin/bash



# Check authorization BEFORE proceeding

if ! "$SCRIPTS_DIR/pax-coder-gate"; then

  echo "AUTHORIZATION DENIED"

  exit 2

fi



# Protected execution code

echo "Signing release..."

```



### Test Suite



File: `scripts/test_protection_gate.sh`



Tests:

1. ✅ No capability → denied (exit 2)

2. ✅ Expired capability → denied

3. ✅ Invalid signature → denied

4. ✅ Wrong commit → denied

5. ✅ Modified release + valid capability → denied (integrity fails first)

6. ✅ Valid release + valid capability → authorized (exit 0)



---



## Authority Implementation (Future)



The authorization service implementation is out-of-scope for this ADR.



Expected interface:



```text

POST /authorize



Request:

{

  "node_id": "...",

  "release_id": "1.0.0",

  "commit": "...",

  "nonce": "..."

}



Response (if authorized):

{

  "capability": {

    "node_id": "...",

    "release_id": "1.0.0",

    "commit": "...",

    "expires_at": "...",

    "nonce": "...",

    "signature": "..."

  }

}



Response (if not authorized):

{

  "error": "Authorization denied",

  "reason": "Node not registered"

}

```



---



## Node Status States



### Unregistered

- Has local node identity (node.json)

- No provisioning from authority

- Cannot perform protected operations



### Provisioning Requested

- Contact sent to authority

- Awaiting authority decision

- Cannot perform protected operations yet



### Provisioned

- Authority has accepted node

- Can request authorization capabilities

- Can perform protected operations (with valid capability)



### Revoked

- Authority has revoked provisioning

- All future authorizations denied

- Cannot perform protected operations



---



## Security Properties Enforced by This ADR



✅ **Integrity verification is public**
- Anyone can verify a release
- No authorization required
- Fails if files are modified

✅ **Authorization requires external authority**
- Cannot be generated locally
- Requires signed capability
- Authority controls who gets access

✅ **Protected execution fails closed**
- Missing capability → explicit denial
- Invalid capability → explicit denial
- Expired capability → explicit denial
- No silent corruption
- No degraded mode

✅ **Capabilities are time-bound**
- Expire within 1 hour
- Fresh capability required per operation
- Prevents indefinite reuse

✅ **Capabilities are commit-bound**
- Tied to specific git commit
- Repository updates invalidate capabilities
- Prevents execution on modified code

---

## Security Properties NOT Enforced

❌ **Cannot prevent determined modification**
- User controls execution environment
- Binary modification is possible
- Reverse engineering is possible

What we DO achieve:
- Modification is detectable (integrity fails)
- Modification requires more effort (not trivial)

❌ **Cannot prevent client-side bypass**
- User could edit pax-coder-gate
- But: Modified gate would fail signature verification
- And: Would have to manually invoke protected operation

What we DO achieve:
- Tampering is obvious
- Automated tools are blocked

---

## Decisions Made

### Decision 1: External Authority Only

**Rejected:** Client-side self-authorization (shell conditionals, local keys)  
**Accepted:** External authority with signed capabilities

**Rationale:** Software on a user-controlled machine cannot enforce authorization. Only external authority can.

### Decision 2: Short-Lived Capabilities

**Rejected:** Long-lived tokens, persistent authorization  
**Accepted:** 1-hour expiration, fresh capability per operation

**Rationale:** Reduces window of capability misuse. Compromised capability expires quickly.

### Decision 3: Commit Binding

**Rejected:** Authorization valid for any code version  
**Accepted:** Capability tied to specific release commit

**Rationale:** Prevents using old capability on new code. Authorization is release-specific.

### Decision 4: Fail-Closed Behavior

**Rejected:** Degraded mode, silent fallback, corrupted output  
**Accepted:** Explicit error, no execution without authorization

**Rationale:** Impossible to accidentally run protected code unauthorized. Error is clear.

---

## Consequences

### Positive

✅ Real authorization boundary exists
✅ Cannot fake authorization locally
✅ Cannot accidentally execute without authority consent
✅ Time-bound reduces reuse window
✅ Clear separation: integrity vs authorization

### Negative / Tradeoffs

❌ Requires external authorization service
❌ More complex than shell conditionals
❌ Operational overhead: managing capabilities, revocation

### Mitigation

- Authorization service can be simple (even email-based initially)
- Short expiration reduces operational burden
- Clear audit trail of capability grants

---

## Testing

All test cases pass:

```

✅ VALID RELEASE + VALID CAPABILITY     → AUTHORIZED

✅ VALID RELEASE + NO CAPABILITY        → DENIED (exit 2)

✅ VALID RELEASE + EXPIRED CAPABILITY   → DENIED (exit 2)

✅ VALID RELEASE + INVALID SIGNATURE    → DENIED (exit 2)

✅ VALID RELEASE + WRONG COMMIT         → DENIED (exit 2)

✅ MODIFIED RELEASE + VALID CAPABILITY  → DENIED (exit 1, integrity fails)

```

---

## References

- ADR-0001: Public Clone Integrity (integrity verification)
- ADR-0002: Authorization Boundary (subsumed by this ADR)
- ADR-0003: Fail-Closed Enforcement (exit codes, explicit errors)
- ADR-0004: Private Key Separation (private signing key never in clone)
- ADR-0006: Server Challenge Protocol (future authorization service design)
- ADR-0007: Codex Security Preservation (CI validation)

---

## Related Files

- `scripts/pax-coder-gate` — Authoritative verification entry point
- `scripts/verify-pax-coder` — Security status report
- `scripts/test_protection_gate.sh` — Test suite
- `sovereign/generate_release.sh` — Protected operation (signs releases)
- `sovereign/generate_node_key.sh` — Unprotected (creates identities only)

---

**Status:** Accepted and implemented  
**Date:** 2026-08-18  
**Commit:** 59abfa0 (removal of fake gate) + d4e52da (real gate implementation)