docs/AUTHORITY_KEY_DEPLOYMENT.md

# 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*