sovereign/README.md

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

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

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

Verify Existing Authorization

./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:

export PAX_NODE_KEY=$(cat sovereign/.node_sk | xxd -p | tr -d '\n')

Workflow

1. Generate Key (Once)

./generate_node_key.sh

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

2. Commit Public Files

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)

./verify_node_key.sh

Confirms all artifacts are consistent.

4. Sign Outputs

Use the private key (externally or via environment):

openssl dgst -sha256 -sign sovereign/.node_sk -out output.sig output.ptx

Verify with public key:

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:

{
  "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:

   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:

- 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)