Stax Digital Garden

HBM-1002 - Loopback Security Boundaries and Cryptographic Handshakes

3 min read

Living Document Notice Published 2026-09-11. The evolving architecture and revisions for this dispatch live in the Stax Digital Garden.

Loopback Security Boundaries and Cryptographic Handshakes

Loopback Security Boundaries and Cryptographic Handshakes: Monochromatic ice blue phosphor P7 vector CRT macro showing interlocking cryptographic polygons and loopback handshake boundaries

Running multiple local daemons on developer workstations introduces threat vectors from unauthorized local processes. A rogue utility running under the same user account can inspect open network ports, spoof client identity strings, or harvest credentials from world-readable process lists.

Harbormaster enforces a mutual cryptographic handshake for all native modules connecting to the Knowledge Provider Protocol. Instead of relying on insecure display strings, every client module proves identity using an Ed25519 public key signature, establishing an authenticated session before obtaining capability tokens.

Handshake Lifecycle and Signature Verification

The handshake establishes identity through challenge-response mechanics over loopback HTTP:

Client Module                                     Harbormaster Gateway
     │                                                     │
     │ 1. POST /handshake/init (client_id, public_key)     │
     ├────────────────────────────────────────────────────►│
     │                                                     │ Generates 32-byte nonce
     │ 2. HTTP 200 (nonce, challenge_id)                  │
     │◄────────────────────────────────────────────────────┤
     │                                                     │
     │ 3. Signs nonce with local Ed25519 private key       │
     │                                                     │
     │ 4. POST /handshake/verify (signature, challenge_id) │
     ├────────────────────────────────────────────────────►│
     │                                                     │ Verifies signature with public key
     │ 5. HTTP 200 (scoped session token, TTL: 3600s)      │ Checks operator approval
     │◄────────────────────────────────────────────────────┤
Security DimensionPlain Local Token ModelHarbormaster Ed25519 Handshake
Client IdentityArbitrary string name (desktop-bar)Cryptographic Ed25519 public key hash
Replay ProtectionStatic header tokens vulnerable to logsEphemeral 32-byte cryptographic nonce
Token Theft ImpactStolen tokens grant indefinite accessSession tokens expire; renewal requires re-signing
DNS Rebinding DefenseIneffective if host header is unvalidatedStrict host header inspection (127.0.0.1:8765)

Cryptographic Nonce Verification in Python

Harbormaster validates signatures in constant time using cryptography.hazmat:

from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.exceptions import InvalidSignature
import secrets
import time
 
class HandshakeManager:
    def __init__(self):
        self.pending_challenges = {}
 
    def issue_challenge(self, client_id: str, public_key_bytes: bytes) -> dict:
        nonce = secrets.token_bytes(32)
        challenge_id = secrets.token_hex(16)
        self.pending_challenges[challenge_id] = {
            "client_id": client_id,
            "public_key": public_key_bytes,
            "nonce": nonce,
            "expires_at": time.time() + 60
        }
        return {"challenge_id": challenge_id, "nonce": nonce.hex()}
 
    def verify_signature(self, challenge_id: str, signature_bytes: bytes) -> bool:
        record = self.pending_challenges.pop(challenge_id, None)
        if not record or time.time() > record["expires_at"]:
            return False
 
        public_key = ed25519.Ed25519PublicKey.from_public_bytes(record["public_key"])
        try:
            public_key.verify(signature_bytes, record["nonce"])
            return True
        except InvalidSignature:
            return False

CLI Verification and Handshake Probing

Test the cryptographic verification loop from the local terminal:

# Initiate handshake challenge
curl -s -X POST http://127.0.0.1:8765/protocol/v1/handshake/init \
  -H "Content-Type: application/json" \
  -d '{"client_id":"cli-probe","public_key":"a3f8c109b8..."}'
 
# Inspect active loopback connections
ss -t -a '( dport = :8765 or sport = :8765 )'
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1002 - Loopback Security Boundaries and Cryptographic Handshakes](HBM-1002 - Loopback Security Boundaries and Cryptographic Handshakes)

Graph View