docs/IMPLEMENTATION_VERIFICATION_AUDIT.md

# PAX-Coder Implementation Verification Audit

**Date:** 2026-08-18  
**Status:** CRITICAL GAPS IDENTIFIED  
**Scope:** Verify that implementation matches documented commercial authorization flow

---

## Executive Summary

**Documentation vs. Implementation Mismatch Detected**

The documentation claims:
> PAX-Coder source is publicly cloneable for inspection and verification. Production authorization is separate: contact, approval, applicable commercial terms, and operator-issued Node Key provisioning are required before authorized production deployment.

The implementation has:
- ✅ **Integrity verification** (verify-clone): Real, working, cryptographic (Ed25519, Blake3)
- ✅ **Authorization record structure** (authorization.json): Defined, validated by verify-node-authorization
- ✅ **Node identity generation** (generate_node_key.sh): Creates identity only, does NOT auto-authorize
- ⚠️ **Authorization record creation**: **Placeholder only; no real provisioning mechanism exists**
- ❌ **Authority signature verification**: **NOT IMPLEMENTED** (line 184-191 in pax-coder-gate: "TODO: Wire this to server public key for real verification")
- ❌ **Authority keypair**: **NOT IN REPOSITORY** (correct), but **no external authority mechanism to create signatures**
- ⚠️ **Node authorization binding**: Structure exists, but cannot be provisioned without authority

---

## Detailed Findings

### 1. SELF-GENERATED NODE KEY CANNOT BECOME AUTHORIZED ✅

**Test:** Can a locally-generated node key self-authorize?

**Finding:** YES, the code prevents self-authorization.

**Evidence:**
- `sovereign/generate_node_key.sh` (line 9): "UNAUTHRIZED (not provisioned by PAX-Coder authority)"
- `sovereign/generate_node_key.sh` (line 12-16): Documents that authorization requires "signed authorization capability" from authority
- Script generates identity (node.json, node_pk.pem) but **cannot create authorization.json**



**Status:** ✅ PASS — Self-generation is identity only.



---



### 2. VALID NODE KEY WITHOUT OPERATOR AUTHORIZATION CANNOT AUTHORIZE PRODUCTION ⚠️ PARTIAL



**Test:** Does a node with valid identity but no authorization allow protected operations?



**Finding:** Partially enforced.



**Current state:**

- `scripts/verify-node-authorization` checks authorization.json status (line 76-100)

- Fails on REQUESTED, SUSPENDED, REVOKED, EXPIRED (correct logic)

- But the authorization.json in the repo has:

  - `authorization_status`: "REQUESTED" (not ACTIVE)
  - `revocation_status`: "REVOKED" (explicitly revoked)
  - `authority_signature`: "placeholder_pending_authority_implementation" (NOT A REAL SIGNATURE)



**Problem:**

- There is **NO MECHANISM TO CREATE A REAL authorization.json**

- The one in the repo is a test fixture with status="REQUESTED" and revoked

- No script exists that creates a production-valid authorization.json with:

  - `authorization_status`: "ACTIVE"
  - Real `authority_signature` (not placeholder)
  - Future `expires_at_utc`

**Status:** ⚠️ PARTIAL — Structure exists, enforcement works for test fixture, but no real provisioning mechanism.

---

### 3. EXPIRED/REVOKED AUTHORIZATION FAILS ✅

**Test:** Does the gate deny expired or revoked authorization?

**Finding:** YES, in the test fixture.

**Evidence:**
- `scripts/verify-node-authorization` (line 102-115): Checks revocation_status, denies if REVOKED

- Line 118-127: Checks expiration_time, denies if past expires_at_utc
- `scripts/test_node_authorization.sh`: All tests pass (7/7), including expiration and revocation

**Status:** ✅ PASS — Expiration and revocation checks work correctly.

---

### 4. AUTHORIZATION BOUND TO INTENDED NODE ✅

**Test:** Can authorization.json be used with a different node's keypair?

**Finding:** NO, binding is enforced.

**Evidence:**
- `scripts/verify-node-authorization` (line 130-142): Checks that node_id in authorization.json matches node.json

- Fails if IDs don't match (exit 2)

- Cannot use node B's private key with node A's authorization



**Status:** ✅ PASS — Node binding is verified.



---



### 5. AUTHORIZATION SCOPE IS ENFORCED ⚠️ PLACEHOLDER



**Test:** Are different authorization scopes enforced with different capabilities?



**Finding:** Scope field exists but is NOT enforced in protected operations.



**Evidence:**

- `sovereign/authorization.json` (line 6): Has `"authorization_scope": "protected-execution"`
- `scripts/verify-node-authorization` (line 55): Extracts scope but only logs it
- `scripts/pax-coder-gate` (line 108-135): Does NOT check scope at all
- No capability mechanism validates scope against operation

**Problem:** Scope exists in authorization record but is not enforced anywhere.

**Status:** ⚠️ PARTIAL — Structure exists, enforcement missing.

---

### 6. PRIVATE SIGNING AUTHORITY IS NOT IN REPOSITORY ✅

**Test:** Is the authority's private key exposed?

**Finding:** NO, correctly not in repository.

**Evidence:**
- `sovereign/authorization.json`: Contains only `node_public_key_hex` (public)
- Authority signature is a placeholder string
- No `.authority_sk`, `.auth_private_key`, or similar files in repo
- Authority would be external (not in codebase)

**Status:** ✅ PASS — Authority key correctly kept external.

---

### 7. VERIFIER IS NOT ACCEPTING LOCAL CONFIG AS AUTHORITY ⚠️ PARTIAL

**Test:** Is the verifier trusting locally-provided authorization values?

**Finding:** Yes, partially. The authorization.json is **read from the local repository**.

**Current implementation:**
- `scripts/verify-node-authorization` (line 24): Reads `sovereign/authorization.json` from local filesystem
- Uses that JSON's status field directly (line 54)
- No cryptographic verification of the authority_signature (line 11: placeholder)



**Problem:**

- If an attacker modifies `sovereign/authorization.json` to set `authorization_status: ACTIVE`, the gate would allow it
- The `authority_signature` is not verified (it's just a string check for format in pax-coder-gate line 199)
- Real implementation would need:
  1. Authority's **public key** hardcoded or fetched securely
  2. Ed25519 signature verification of the entire authorization.json
  3. Rejection if signature doesn't match

**Status:** ⚠️ ISSUE — Local file is trusted. Signature verification is TODO.

---

## The Provisioning Flow Gap

**Documented flow:**
```

CONTACT

  ↓

APPROVAL

  ↓

COMMERCIAL AGREEMENT

  ↓

NODE PROVISIONING

  ↓

OPERATOR-SIGNED AUTHORIZATION

  ↓

PROTECTED OPERATION

```

**Actual implementation:**
```

CONTACT

  ↓ (documented in CONTACT.md)

APPROVAL

  ↓ (no code, manual process)

COMMERCIAL AGREEMENT

  ↓ (no code, manual process)

NODE PROVISIONING

  ↓ (no code to create authorization.json)

???

  ↓ (no script to sign authorization.json with authority key)

OPERATOR-SIGNED AUTHORIZATION

  ↓ (would require real Ed25519 signature)

LOCAL authorization.json with ACTIVE + valid signature

  ↓ (current code trusts status field, doesn't verify signature)

PROTECTED OPERATION

```

**Missing:**
1. **Script to create authorization.json** (currently only a test fixture with status="REQUESTED")
2. **Authority key** (would be external, not in repo — correct)
3. **Signing mechanism** to create real Ed25519 signatures over authorization.json
4. **Signature verification in pax-coder-gate** (currently just format check, see line 184-191: "TODO: Wire this to server public key")

---

## What Works ✅

1. **Integrity verification (verify-clone)** — Cryptographically sound
2. **Node identity generation** — Cannot self-authorize
3. **Authorization structure** — Correctly defined
4. **Status validation** — ACTIVE/REQUESTED/SUSPENDED/REVOKED/EXPIRED states work
5. **Expiration checking** — Works correctly
6. **Revocation checking** — Works correctly
7. **Node binding** — Verified against identity
8. **Test suite** — All 7 node authorization tests pass, all 6 gate tests pass
9. **Authority key separation** — Correctly external

---

## What Doesn't Work ❌

1. **Authority signature verification** — Not implemented (TODO in code)
2. **Authorization record provisioning** — No script to create real signed authorizations
3. **Scope enforcement** — Scope field exists but not checked
4. **Authority key integration** — Would need to wire external authority into gate

---

## Implications

### Current State: Theater + Placeholder

The gate currently:
- ✅ Verifies integrity (real)
- ⚠️ Reads authorization status (trusts local JSON, no signature check)
- ⚠️ Accepts capability tokens (format-checks hex, doesn't verify signature)
- ✅ Enforces node binding (real)
- ✅ Checks expiration (real)

**A user could:**
1. Clone the repo
2. Edit `sovereign/authorization.json` to set `authorization_status: "ACTIVE"`
3. The gate would now allow protected operations (because signature is not verified)

**This is NOT a security boundary yet.**

### Why This Matters

The documentation promises:
> operator-issued Node Key provisioning are required before authorized production deployment

The implementation provides:
> A placeholder authorization.json that can be locally modified (no signature verification)

**Gap:** Production authorization is documented but not cryptographically enforced.

---

## To Close the Gap

Three steps required:

### 1. Authority Provisioning Mechanism

Create a script (run by authority, not in repo):
```bash

# authority-sign-authorization.sh (on secure server only, NOT in public repo)

#

# Input:

#   - node_public_key_hex

#   - commercial_agreement_id

#   - tier (Individual/Commercial/Enterprise)

#   - expires_at_utc

#

# Output:

#   - authorization.json with real Ed25519 signature

#   - authority_signature = Ed25519_sign(authority_private_key, blake3(authorization_json))

```

### 2. Authority Public Key Hardcoding

Add to `docs/adr/0010` or pax-coder-gate:
```bash

# Public key of signing authority (Ed25519)

AUTHORITY_PUBLIC_KEY="base64_encoded_authority_public_key_hex"

```

This is safe to hardcode (only verification, not signing).

### 3. Signature Verification in Gate

Replace TODO at line 184-191:
```bash

# Verify capability signature using authority public key

if ! verify_ed25519_signature \

    "$AUTHORITY_PUBLIC_KEY" \

    "$CAPABILITY_JSON" \

    "$CAPABILITY_SIGNATURE"; then

  echo "DENIED: Capability signature invalid (failed verification)"

  exit 2

fi

```

---

## Recommendation

**Do NOT ship this as production authorization yet.**

The documentation is sound, but the implementation has a critical gap:
- Authority signatures are **not verified**
- Local authorization.json file **can be modified without detection**
- This is a placeholder gate, not a real one

**Before shipping:**
1. Create authority-provisioning mechanism (external script)
2. Add authority public key to gate
3. Implement Ed25519 signature verification
4. Re-run all tests with real signed authorizations
5. Document the external authority workflow

Until these steps are done, the gate is:
- ✅ Correct for **integrity verification**
- ⚠️ Incomplete for **production authorization**

---

## Test Outcomes

**Current test suite results:**
```

test_node_authorization.sh     7/7 ✓

test_protection_gate.sh        6/6 ✓

```

**These tests use a placeholder authorization.json.** They verify the *logic* but not the *security*.

**To verify security, would need:**
1. Test with real Ed25519-signed authorization.json
2. Test that locally-modified authorization.json is rejected
3. Test that tampered capability signatures fail
4. Test that authority public key verification works

These tests don't exist yet.

---

**Status:** IMPLEMENTATION COMPLETE FOR STRUCTURE; AUTHORITY VERIFICATION INCOMPLETE  
**Next:** Implement authority key integration and signature verification  
**Date:** 2026-08-18  
**ADR Reference:** ADR-0009 (Protected Execution Capability), ADR-0010 (Public/Authorization Separation)

---

*Bel Esprit D'Accord Irrevocable Trust · SnapKitty West · Evidence or Silence — 2026*