| # Authority Key Deployment Guide | |
| **Purpose:** Instructions for authority operators to sign capabilities and provision nodes. | |
| **Audience:** PAX-Coder Authority Operator (not public) | |
| --- | |
| ## 1. Authority Setup (One-Time) | |
| ### 1.1 Generate Authority Keypair | |
| **Location:** Authority server (secure environment) | |
| ```bash | |
| cd pax-coder | |
| bash sovereign/generate_authority_key.sh | |
| ``` | |
| **Output:** | |
| - `sovereign/authority_sk.pem` — Private key (KEEP SECURE) | |
| - `sovereign/authority_pk.pem` — Public key (distribute to nodes) | |
| **Security:** | |
| ```bash | |
| # Verify file permissions | |
| ls -la sovereign/authority_sk.pem # Should be 600 | |
| ls -la sovereign/authority_pk.pem # Should be 644 | |
| ``` | |
| ### 1.2 Distribute Authority Public Key | |
| **File:** `sovereign/authority_pk.pem` | |
| Distribute to all nodes that will verify authorizations: | |
| ```bash | |
| # Copy to known location on all nodes | |
| cp sovereign/authority_pk.pem /etc/authority/pax-coder-authority-pk.pem | |
| ``` | |
| Or bake into deployment image: | |
| ```bash | |
| # In Docker image or VM template | |
| COPY sovereign/authority_pk.pem /etc/authority/pax-coder-authority-pk.pem | |
| ``` | |
| **Do NOT commit authority_pk.pem to public repositories.** | |
| --- | |
| ## 2. Create Authorization Records | |
| ### 2.1 Authorization Request Flow | |
| ``` | |
| Developer/Customer | |
| ↓ (Request) | |
| Authority Operator | |
| ↓ (Review) | |
| Authorization Database | |
| ↓ (Create) | |
| authorization.json template | |
| ↓ (Sign) | |
| Signed Capability | |
| ↓ (Deliver) | |
| Developer/Customer | |
| ``` | |
| ### 2.2 Create Capability Record | |
| **Filename:** `capability_NODE_ID.json` | |
| ```json | |
| { | |
| "node_id": "pax-coder-prod-12345", | |
| "release_id": "1.0.0", | |
| "commit": "abc123def456789abc123def456789abc123def4", | |
| "nonce": "nonce-2026-08-18-unique", | |
| "expires_at": "2026-12-31T23:59:59Z" | |
| } | |
| ``` | |
| **Fields:** | |
| | Field | Purpose | Example | | |
| |-------|---------|---------| | |
| | `node_id` | Unique node identifier | `pax-coder-prod-12345` | | |
| | `release_id` | Allowed release version | `1.0.0` | | |
| | `commit` | Exact git commit hash | `abc123...` | | |
| | `nonce` | One-time use identifier | Date + random | | |
| | `expires_at` | Expiration time (UTC) | ISO 8601 | | |
| ### 2.3 Sign Capability | |
| **Command:** | |
| ```bash | |
| bash sovereign/sign_capability.sh capability_NODE_ID.json | |
| ``` | |
| **Output:** | |
| ``` | |
| {"commit":"abc123...","expires_at":"2026-12-31T23:59:59Z",...}|b640c7a4f0af55c7abba64c8e444d39b0bd44431aabffeb814cd519b87e6352aaf0c63cbcb94bad1ae23ac52f1288dea7c0aa815158f76221cee56da9aad520a | |
| ``` | |
| Format: `CANONICAL_JSON|SIGNATURE_HEX` | |
| **Signature:** 128 hex characters (64 bytes Ed25519) | |
| ### 2.4 Deliver to Node | |
| **Send via secure channel:** | |
| ```bash | |
| # Option 1: Email or secure message | |
| PAX_CAPABILITY_TOKEN="$(bash sovereign/sign_capability.sh capability_NODE_ID.json)" | |
| echo $PAX_CAPABILITY_TOKEN > /tmp/capability.txt | |
| # Send /tmp/capability.txt to node operator (encrypted) | |
| # Option 2: API endpoint | |
| curl -X POST https://authority.example.com/provision \ | |
| -H "Authorization: Bearer $AUTH_TOKEN" \ | |
| -d '{ | |
| "node_id": "pax-coder-prod-12345", | |
| "capability": "'$PAX_CAPABILITY_TOKEN'" | |
| }' | |
| # Option 3: Kubernetes secret | |
| kubectl create secret generic pax-capability-prod-12345 \ | |
| --from-literal=token="$PAX_CAPABILITY_TOKEN" | |
| ``` | |
| --- | |
| ## 3. Node Installation | |
| ### 3.1 Deploy Authority Public Key | |
| **Automated (Terraform):** | |
| ```hcl | |
| resource "local_file" "authority_pk" { | |
| content = file("${path.module}/sovereign/authority_pk.pem") | |
| filename = "/etc/authority/pax-coder-authority-pk.pem" | |
| } | |
| ``` | |
| **Manual:** | |
| ```bash | |
| mkdir -p /etc/authority | |
| cp authority_pk.pem /etc/authority/pax-coder-authority-pk.pem | |
| chmod 644 /etc/authority/pax-coder-authority-pk.pem | |
| ``` | |
| ### 3.2 Set Capability Token | |
| **Environment Variable:** | |
| ```bash | |
| export PAX_CAPABILITY_TOKEN="$(cat /path/to/capability.txt)" | |
| ``` | |
| **File:** | |
| ```bash | |
| mkdir -p pax-coder/sovereign | |
| echo "$PAX_CAPABILITY_TOKEN" > pax-coder/sovereign/.capability | |
| chmod 600 pax-coder/sovereign/.capability | |
| ``` | |
| **Kubernetes Secret:** | |
| ```bash | |
| kubectl create secret generic pax-capability \ | |
| --from-file=capability=/path/to/capability.txt \ | |
| -n pax-system | |
| # Mount in pod | |
| volumeMounts: | |
| - name: pax-capability | |
| mountPath: /opt/pax/sovereign/.capability | |
| subPath: capability | |
| volumes: | |
| - name: pax-capability | |
| secret: | |
| secretName: pax-capability | |
| ``` | |
| ### 3.3 Verify Setup | |
| **Test gate:** | |
| ```bash | |
| cd pax-coder | |
| bash scripts/pax-coder-gate | |
| ``` | |
| **Expected output:** | |
| ``` | |
| PAX-CODER PROTECTED EXECUTION GATE | |
| [1/5] Verifying release integrity... | |
| ✓ Release integrity verified | |
| [2/5] Verifying node authorization status... | |
| ✓ Node authorization verified | |
| [3/5] Checking for capability... | |
| ✓ Capability token found | |
| [4/5] Parsing capability... | |
| ✓ Capability parsed | |
| [5/5] Validating capability... | |
| ✓ Commit matches | |
| ✓ Capability not expired | |
| ✓ Node ID matches | |
| [6/6] Verifying capability signature... | |
| ✓ Signature verified (cryptographic validation) | |
| STATUS: AUTHORIZATION_GRANTED | |
| Node pax-coder-prod-12345 is authorized for: | |
| Scope: protected-execution | |
| ``` | |
| --- | |
| ## 4. Authority Operations | |
| ### 4.1 Rotate Authority Keys | |
| **When:** Compromise suspected, key expires, policy change | |
| **Steps:** | |
| 1. Generate new authority keypair: | |
| ```bash | |
| bash sovereign/generate_authority_key.sh | |
| ``` | |
| 2. Distribute new authority_pk.pem to all nodes | |
| 3. Continue signing with new authority_sk.pem | |
| 4. Mark old capabilities as REVOKED (if managed in database) | |
| **Old capabilities:** Will fail verification once authority_pk.pem is updated | |
| ### 4.2 Revoke Capability | |
| **Option 1: Expiration (Automatic)** | |
| Capabilities expire at `expires_at` timestamp. | |
| **Option 2: Revocation (Operational)** | |
| If compromise or revocation needed before expiration: | |
| 1. Update authorization database | |
| 2. Add to revocation list | |
| 3. Gate checks against revocation list (if implemented) | |
| Current gate does not check revocation list; implement if needed. | |
| ### 4.3 Audit Trail | |
| **Maintain log:** | |
| ``` | |
| Date | Node ID | Action | Signature | |
| 2026-08-18 | pax-coder-12345 | PROVISION | b640c7a4... | |
| 2026-08-20 | pax-coder-12345 | REVOKE | (reason: compromise) | |
| 2026-08-21 | pax-coder-12346 | PROVISION | f8a6008c... | |
| ``` | |
| --- | |
| ## 5. Security Best Practices | |
| ### 5.1 Private Key Protection | |
| ```bash | |
| # Generate on secure server, NEVER transfer | |
| authority_sk.pem → KEEP ONLY ON AUTHORITY SERVER | |
| # Backup encrypted | |
| openssl enc -aes-256-cbc -in authority_sk.pem -out authority_sk.pem.enc | |
| # Verify file permissions | |
| ls -la sovereign/authority_sk.pem # Must be 600 | |
| stat -c "%a" sovereign/authority_sk.pem # Should print 600 | |
| ``` | |
| ### 5.2 Public Key Distribution | |
| ```bash | |
| # Safe to distribute, verify integrity: | |
| # Use signed manifest or checksum | |
| sha256sum sovereign/authority_pk.pem > authority_pk.sha256 | |
| gpg --sign authority_pk.sha256 # Sign with operator key | |
| # Nodes verify before deployment: | |
| gpg --verify authority_pk.sha256.gpg | |
| sha256sum -c authority_pk.sha256 | |
| ``` | |
| ### 5.3 Secure Channels | |
| - Use TLS for capability delivery | |
| - Sign capabilities with operator signature (GPG) | |
| - Encrypt in transit | |
| - Audit who can provision | |
| ### 5.4 Monitoring | |
| ```bash | |
| # Log all capability issuances: | |
| bash sovereign/sign_capability.sh capability_$NODE.json 2>&1 | \ | |
| tee -a /var/log/pax-authority.log | |
| # Alert on failures: | |
| # - Failed signature operations | |
| # - Missing authority_sk | |
| # - Unauthorized sign requests | |
| ``` | |
| --- | |
| ## 6. Troubleshooting | |
| ### Issue: "Authority public key not found" | |
| **Solution:** Deploy authority_pk.pem to node: | |
| ```bash | |
| mkdir -p /etc/authority | |
| cp sovereign/authority_pk.pem /etc/authority/pax-coder-authority-pk.pem | |
| ``` | |
| ### Issue: "Signature verification failed" | |
| **Possible causes:** | |
| 1. Wrong authority_pk.pem (mismatched keypair) | |
| 2. Capability modified after signing | |
| 3. Gate using node_pk.pem instead of authority_pk.pem | |
| **Verify:** | |
| ```bash | |
| # Check gate is using correct key: | |
| grep "AUTHORITY_PUBLIC_KEY_FILE" scripts/pax-coder-gate | |
| # Should show: authority_pk.pem (not node_pk.pem) | |
| # Test capability locally: | |
| bash sovereign/sign_capability.sh test_cap.json | |
| # Output should be: JSON|SIGNATURE_HEX | |
| ``` | |
| ### Issue: "Node ID mismatch" | |
| **Cause:** Capability for wrong node | |
| **Solution:** Create new capability with correct node_id: | |
| ```bash | |
| # Verify local node ID: | |
| cat sovereign/node.json | grep node_id | |
| # Create capability with matching node_id: | |
| cat > capability_$NODE_ID.json << EOF | |
| { | |
| "node_id": "$(cat sovereign/node.json | grep -o '"node_id":"[^"]*"' | cut -d'"' -f4)", | |
| ... | |
| } | |
| EOF | |
| ``` | |
| --- | |
| ## 7. Testing | |
| ### 7.1 Test Authority Signatures | |
| ```bash | |
| # Run comprehensive test suite: | |
| bash scripts/test_authority_key_separation.sh | |
| # Expected: 8/8 tests pass | |
| ``` | |
| ### 7.2 Manual Verification | |
| ```bash | |
| # Create test capability | |
| cat > test_cap.json << EOF | |
| { | |
| "node_id": "test-node", | |
| "release_id": "1.0.0", | |
| "commit": "abc123def456789abc123def456789abc123def4", | |
| "nonce": "test-nonce", | |
| "expires_at": "2026-12-31T23:59:59Z" | |
| } | |
| EOF | |
| # Sign it | |
| SIGNED=$(bash sovereign/sign_capability.sh test_cap.json) | |
| # Verify signature (extract components) | |
| JSON_PART=$(echo "$SIGNED" | cut -d'|' -f1) | |
| SIG_PART=$(echo "$SIGNED" | cut -d'|' -f2) | |
| # Verify with openssl | |
| echo -n "$JSON_PART" > /tmp/msg.bin | |
| printf '%s' "$(printf '%s' "$SIG_PART" | xxd -r -p)" > /tmp/sig.bin | |
| openssl pkeyutl -verify -inkey sovereign/authority_pk.pem \ | |
| -pubin -sigfile /tmp/sig.bin \ | |
| -in /tmp/msg.bin | |
| # Should output: "Signature Verified Successfully" | |
| ``` | |
| --- | |
| ## 8. Reference | |
| ### Files | |
| - `sovereign/authority_sk.pem` — Authority private key (secure server) | |
| - `sovereign/authority_pk.pem` — Authority public key (distribute) | |
| - `sovereign/sign_capability.sh` — Signing utility | |
| - `scripts/pax-coder-gate` — Gate that verifies authorizations | |
| - `scripts/test_authority_key_separation.sh` — Test suite | |
| ### Commands | |
| - Generate keys: `bash sovereign/generate_authority_key.sh` | |
| - Sign capability: `bash sovereign/sign_capability.sh <file.json>` | |
| - Test gate: `bash scripts/test_authority_key_separation.sh` | |
| - Verify clone: `bash scripts/verify-clone` | |
| ### Related Documentation | |
| - [ADR-0010: Public Repository vs. Production Authorization Separation](./adr/0010-public-repository-authorization-separation.md) | |
| - [ADR-0009: Protected Execution Capability Gate](./adr/0009-protected-execution-capability.md) | |
| - [Authority Key Separation Audit](./AUTHORITY_KEY_SEPARATION_AUDIT.md) | |
| --- | |
| *Bel Esprit D'Accord Irrevocable Trust · SnapKitty West · Evidence or Silence — 2026* | |