# Sovereign Node Key System

This directory contains the cryptographic authorization infrastructure for PAX-Coder.

## What This Is

The Sovereign Node Key system provides:

1. **Ed25519 Node Authorization** — cryptographic identity with authorization for protected operations
2. **Node Authorization Record** — external authority-signed proof that this node is authorized
3. **Repository Commitment** — SHA-256 hash of the repository state at key generation time
4. **Prior-Art Timestamp** — tamper-evident record that this work existed at a particular git commit
5. **Authorization Verification** — tools to verify node authorization status
6. **Verification Scripts** — tools to independently verify integrity and authorization

## How to Use

### Step 1: Generate a New Node

```bash
cd pax-coder/sovereign
./generate_node_key.sh
```

This creates:
- `node.json` — Public identity manifest
- `node_pk.pem` — Public key (PEM format)
- `manifest.json` — Repository file list with hashes
- `prior_art.json` — Prior-art timestamp record
- `verification.json` — Cryptographic verification record
- `.node_sk` — **PRIVATE KEY** (never committed, permissions 400)

### Step 2: Request Authorization

Contact PAX-Coder at:
- Email: jessica@collectivekitty.com
- Form: https://snapkittywest.com/pax-coder/request

Provide your `node.json` (public identity only). Do NOT share `.node_sk`.

### Step 3: Receive Authorization Record

After approval and provisioning, you receive:
- `authorization.json` — Authority-signed authorization record for your node

The authorization record contains:
- Your node ID and public key
- Authorization status (ACTIVE, REQUESTED, SUSPENDED, REVOKED, EXPIRED)
- Authorization scope (what operations you can perform)
- Issue/expiration dates
- Authority signature

### Step 4: Verify Authorization

```bash
./verify_node_key.sh     # Verify node identity integrity
../scripts/verify-node-authorization  # Verify authorization status
```

### Verify Existing Authorization

```bash
./verify_node_key.sh     # Verify node key integrity
../scripts/verify-node-authorization  # Verify authorization status
```

Checks (node key):
- All public files are present and valid JSON
- Private key has correct permissions
- Git commit exists in repository
- Repository commitment hash is correct

Checks (authorization):
- Authorization record exists
- Authorization status is ACTIVE
- Authorization has not expired
- Node ID matches
- Revocation status is not REVOKED

## Security Model

### What This Proves

✓ **Node Identity** — Cryptographic identity of the node (Ed25519 public key)
✓ **Node Authorization** — External authority has approved this node for protected operations
✓ **Authorization Status** — Node is ACTIVE, REQUESTED, SUSPENDED, REVOKED, or EXPIRED
✓ **Authorization Scope** — What protected operations this node is authorized to perform
✓ **Integrity** — Repository state at a specific git commit  
✓ **Timestamp** — Work existed no later than this UTC time  
✓ **Authenticity** — Outputs are signed with a specific Ed25519 key  
✓ **Non-repudiation** — Holder of the private key can sign artifacts

### What This Does NOT Prove

✗ **Alone without authorization record** — Node identity alone does not prove authority
✗ **Legal ownership** — No embedded legal claims  
✗ **Blockchain confirmation** — Timestamp is local only (unconfirmed)  
✗ **Work quality** — Only proves authorization and existence, not correctness or usefulness

### Public vs. Private

**Never commit to git:**
- `.node_sk` (private key file)
- Any file containing the private key material
- Passwords or passphrases

**Safe to commit:**
- `node.json` (public identity)
- `node_pk.pem` (public key)
- `manifest.json` (repository fingerprint)
- `prior_art.json` (prior-art record)
- `verification.json` (cryptographic metadata)

## Files

### node.json

Public identity manifest. Contains:
- `node_id` — Unique identifier
- `algorithm` — "Ed25519"
- `public_key_hex` — Public key in hex format
- `created_at_utc` — ISO 8601 timestamp
- `repository` — GitHub repo path
- `git_commit` — Commit hash at generation time
- `version` — System version

### manifest.json

Repository state snapshot. Contains:
- `files` — Object mapping each tracked file to its SHA-256 hash
- `generated_at_utc` — When manifest was created
- `git_commit` — Which commit this reflects

### prior_art.json

Prior-art timestamp record. Contains:
- `artifact` — "PAX-Coder"
- `repository` — GitHub path
- `git_commit` — Commit hash
- `repository_sha256` — Hash of the manifest
- `node_id` — Node that signed it
- `created_at_utc` — UTC timestamp
- `status` — "UNCONFIRMED" (or "BITCOIN-CONFIRMED" if anchored)

### verification.json

Cryptographic record. Contains:
- `node_id` — Node identifier
- `algorithm` — "Ed25519"
- `repository_commitment_algorithm` — "SHA-256"
- `repository_commitment` — The actual commitment hash
- `git_commit` — Which commit
- `manifest_file` — Path to manifest
- `verification_timestamp` — When verified

### .node_sk

**PRIVATE KEY FILE** — Never commit, share, or upload.

File permissions: 400 (owner read-only)

Stored locally for signing operations:
```bash
export PAX_NODE_KEY=$(cat sovereign/.node_sk | xxd -p | tr -d '\n')
```

## Workflow

### 1. Generate Key (Once)

```bash
./generate_node_key.sh
```

Outputs all files. Private key is generated once and kept secure.

### 2. Commit Public Files

```bash
git add sovereign/node.json sovereign/manifest.json sovereign/prior_art.json sovereign/verification.json
git commit -m "Add Sovereign Node Key public identity"
```

**DO NOT** commit `.node_sk`.

### 3. Verify (Any time)

```bash
./verify_node_key.sh
```

Confirms all artifacts are consistent.

### 4. Sign Outputs

Use the private key (externally or via environment):
```bash
openssl dgst -sha256 -sign sovereign/.node_sk -out output.sig output.ptx
```

Verify with public key:
```bash
openssl dgst -sha256 -verify <(openssl pkey -in sovereign/node_pk.pem -pubin -outform DER) -signature output.sig output.ptx
```

## Key Rotation

To rotate to a new key:

1. Generate new key in a new subdirectory (e.g., `sovereign/v2/`)
2. Record the old public key in a rotation record
3. Sign the rotation record with the old key
4. Commit new key and rotation record
5. Keep old private key in secure archive (not in git)

Example rotation record:
```json
{
  "old_node_id": "pax-coder-1234567890",
  "new_node_id": "pax-coder-1234567999",
  "rotation_reason": "scheduled rotation",
  "rotation_timestamp": "2026-08-18T00:00:00Z",
  "signature_by_old_key": "..."
}
```

## Verification for Others

To verify this artifact (without the private key):

1. Clone the repository
2. Run `./sovereign/verify_node_key.sh`
3. Check that all files are present and valid
4. Compare the git commit hash with the timestamp
5. Verify the repository commitment by spot-checking a few files:
   ```bash
   sha256sum sovereign/node.json  # Should match value in manifest.json
   ```
6. Confirm the node's public key (from `node.json`) against any signatures

## CI/CD Integration

Add to `.github/workflows/security.yml`:

```yaml
- name: Check for private key material
  run: |
    if grep -r "BEGIN.*PRIVATE\|-----END.*PRIVATE" sovereign/ --include="*.json"; then
      echo "ERROR: Private key material in public files"
      exit 1
    fi

- name: Verify node key integrity
  run: |
    cd sovereign
    bash verify_node_key.sh
```

## Questions?

- **What does this prove?** See "Security Model" section above.
- **Is this blockchain-based?** No, it's local + optional Bitcoin anchoring. See `prior_art.json` status.
- **Can I use a different algorithm?** Yes, but Ed25519 is recommended. Update `algorithm` field in `node.json`.
- **What if I lose the private key?** Key rotation required; new public identity generated; old key recorded.
- **Can I backup the private key?** Yes, but store encrypted in a secure vault outside git.

---

**Generated by:** PAX-Coder Sovereign Node Key System  
**License:** Same as PAX-Coder (BSL-1.1 / AGPL-3.0 / MPL-2.0)