Chapter 20: The Secure Tunnel

Trust is not assumed. It is verified.

By mid-2026, the PAI had twenty-plus services communicating over localhost. Each service exposed HTTP endpoints. Each service called other services. Each service transmitted sensitive data — authentication tokens, semantic memories, security alerts, intelligence reports.

But the communication was unencrypted. Services trusted each other implicitly — after all, they were all on the same machine. This implicit trust was a vulnerability.

The Moment of Intercepted Communication

It was 11:47 PM on a Thursday. The author was debugging a service-to-service communication issue when something unsettling appeared in a network monitoring tool — net-pack-parser had captured a packet containing a JWT token in plaintext. The token was being sent over HTTP, unencrypted, between two PAI services.

Any process on the machine could have intercepted it. A malicious plugin, a compromised service, a rogue script — any of them could have captured the token and used it to authenticate as that service.

“I built these tools to protect myself,” the author thought. “But they communicate in plaintext.”

This was the implicit trust problem in action. Services trusted each other because they were on the same machine. But localhost is still a network. Processes can still intercept traffic. The assumption of implicit trust was a vulnerability.

That was the moment the question formed: What if all communication was encrypted?

The Implicit Trust Problem

The security architecture had identity (jay-auth) but not transport security. Services authenticated to each other using JWT tokens, but the tokens were transmitted in plaintext over HTTP. Any process on the machine could intercept them — a malicious plugin, a compromised service, a rogue script.

This was acceptable in a controlled environment — the author’s personal Mac Studio, with no external network access, no multi-user setup, no untrusted processes. But it was not acceptable for an infrastructure that claimed to be secure. The author had spent years building enterprise security systems where every connection was encrypted. Watching their personal infrastructure communicate in plaintext was uncomfortable.

The author had built jay-auth to provide identity. They had built observability to provide visibility. But there was no equivalent for transport security. Services communicated over plain HTTP, relying on the implicit trust of localhost. This was a gap in the Zero Trust architecture. Zero Trust assumes breach — it does not trust based on network location. Localhost is still a network. Processes can still intercept traffic. The gap needed to be filled.

Before pai-tls-proxy, the author’s approach to transport security was informal and inconsistent. Some services used HTTPS. Some used HTTP. There was no unified policy — no requirement that all communication be encrypted. The author relied on the implicit trust of localhost, assuming that because all services were on the same machine, they could trust each other.

This wasn’t just uncomfortable. It was insecure. A compromised service could intercept tokens from other services. A malicious plugin could capture credentials. An untrusted process could eavesdrop on sensitive communication. The assumption of implicit trust was a vulnerability.

The choice wasn’t between encrypted and plaintext communication. It was between encrypted communication and acceptance of risk. And for someone who valued both security and peace of mind, that was an unsustainable tradeoff.

The Failed First Attempt

The first attempt at TLS was embarrassingly simple. The author configured HTTPS on each service individually — generating certificates, updating configurations, restarting services. It worked. For a moment.

Then it broke. Not dramatically — there was no crash, no error message. It just became unmanageable. Certificates expired. Configurations drifted. Some services had HTTPS, others didn’t. The author spent more time managing certificates than using the PAI.

“I built a TLS system that requires more maintenance than the services it secures,” the author noted. “That’s not security. That’s a part-time job.”

The problem wasn’t TLS — it was the assumption that each service should manage its own certificates. A centralized TLS proxy could manage certificates for all services, rather than requiring per-service configuration.

This was the first lesson in TLS architecture: centralized proxy simplifies security; distributed configuration complicates it.

The Breakthrough

The breakthrough came from recognizing that transport security was not a service feature — it was infrastructure. Just as jay-auth provided identity for all services, a TLS termination proxy could provide transport security for all services.

The author realized that what was needed was not individual HTTPS configuration for each service, but a centralized TLS proxy that:

• Terminated HTTPS connections from clients
• Forwarded HTTP connections to backend services
• Managed certificates automatically
• Required no changes to existing services

This was the pai-tls-proxy project.

What Was Built

The capabilities that emerged from the pai-tls-proxy project didn’t arrive all at once. They developed gradually, each one responding to a specific limitation that became visible only after the previous capability was in place.

Certificate Management came first — the basic ability to issue and distribute TLS certificates. This was the threshold capability: without it, there was no encrypted transport. But early certificate management was naive — manual generation, manual distribution, manual rotation. It worked, but it was unsustainable.

Route Configuration emerged from the realization that per-service HTTPS was too complex. Managing certificates for fifteen services was error-prone and time-consuming. A centralized proxy could handle routing for all services, rather than requiring per-service configuration.

Automatic Reload came after the first certificate expiry complaint. The author had been woken at 2 AM because a service certificate had expired and the proxy hadn’t reloaded. Automatic reload on config change became a requirement, not a nice-to-have.

Logging emerged from the observation that encrypted traffic was invisible. The author could see that connections were happening, but couldn’t audit who was connecting, when, and with what certificate. Logging all TLS connections became essential for security monitoring.

// pai-tls-proxy — First TLS attempt (September 2026)
// Note: This was NOT the final architecture.
// The centralized proxy was added later.
// The automatic rotation was added after the first expiry complaint.

// First attempt: Per-service HTTPS
// Failed: Certificate management was unsustainable
// Each service needed its own cert, config, restart
async function enableTLS(service: Service): Promise<void> {
  const cert = await generateCertificate(service.name);
  await updateServiceConfig(service, { tls: cert });
  await restartService(service);
}

// Second attempt: Manual proxy
// Worked: Centralized
// Problem: No auto-reload, no auto-rotation
class ManualProxy {
  async start(): Promise<void> {
    // Manually configure each route
    // Manually reload when certs change
    // Manually rotate when certs expire
  }
}

// Final approach: Centralized TLS proxy
// Required: Auto-reload, auto-rotation, zero-service-changes
// Result: Transparent security for all services
class TLSPROXY {
  async start(config: ProxyConfig): Promise<void> {
    for (const route of config.services) {
      const cert = await loadCertificate(route.cert);
      const key = await loadPrivateKey(route.key);
      
      const server = createServer({ cert, key }, async (req, res) => {
        const backend = await resolveBackend(route.backend);
        await forward(req, res, backend);
      });
      
      server.listen(route.listen);
    }
  }
  
  // Auto-reload on config change
  // Auto-rotate when cert expires
}

The Architecture

pai-tls-proxy was designed as a two-layer system:

The Port Mapping Convention

Every PAI service followed a consistent port convention that made the proxy configuration deterministic:

The 10000 + PORT offset was a deliberate design choice — it kept internal ports in a range that was unlikely to conflict with system services while remaining easy to remember and configure. The proxy configuration file simply mapped each public port to its corresponding backend port.

The Zero Trust Triad in Practice

The three pillars of the Zero Trust architecture worked together in a specific sequence:

Client Request (HTTPS)
    ↓
1. pai-tls-proxy terminates TLS
   ├─ Verifies client certificate (mTLS)
   ├─ Checks certificate against jay-auth CRL
   └─ Extracts client identity from certificate
    ↓
2. jay-auth validates JWT token
   ├─ Verifies signature with public key
   ├─ Checks expiration
   ├─ Validates scopes match required permissions
   └─ Returns authenticated identity
    ↓
3. Backend service processes request
   ├─ Receives authenticated identity in headers
   ├─ Logs action with identity for audit
   └─ Returns response
    ↓
4. Memory system records interaction
   ├─ Stores relevant context from conversation
   ├─ Extracts facts and preferences
   └─ Makes context available for future interactions

This sequence ensured that every request was authenticated (who are you?), authorized (what are you allowed to do?), and contextualized (what do we already know about you?). No step could be skipped — each built on the previous one.

TLS Layer. Terminated HTTPS connections, verified client certificates (mTLS), decrypted traffic.

Forwarding Layer. Forwarded decrypted HTTP traffic to backend services, preserving headers and cookies.

Client (HTTPS) → pai-tls-proxy → Service (HTTP)
     ↓                   ↓              ↓
  TLS terminated    Route lookup   Backend called

The proxy was stateless — it did not store data, process requests, or maintain state. It only terminated TLS and forwarded traffic. This made it simple, reliable, and easy to debug.

The Integration

pai-tls-proxy integrated with all PAI services:

jay-auth. Issued certificates for each service. The CA root certificate was distributed to client devices and trusted.

All PAI services. Services continued to run on HTTP (internal ports). The proxy handled TLS termination, so services did not need to be modified.

Client devices. Browsers and API clients connected via HTTPS to the proxy. The PAI root CA was trusted in the macOS keychain, so certificates were validated automatically.

Browser → https://saim.local:4400 → pai-tls-proxy → http://127.0.0.1:14400 (jay-gentic)
           ↑ TLS terminated by proxy
           ↓ Certificate signed by jay-auth CA

The integration was seamless for clients — they connected to the same URLs they always had, but now over HTTPS. The proxy handled the TLS termination and forwarded to the backend services over HTTP. Services didn’t need to know about TLS at all.

The Zero Trust Triad

With pai-tls-proxy, the PAI completed its Zero Trust triad:

Identity (jay-auth). Every service and user has a verified identity.

Transport (pai-tls-proxy). Every connection is encrypted and authenticated.

Context (memory-system). Every interaction has persistent context.

        ┌─────────────────┐
        │   Zero Trust    │
        │   Architecture  │
        └─────────────────┘
              /    |    \
             /     |     \
            /      |      \
    Identity   Transport  Context
   (jay-auth) (pai-tls-  (memory-
               proxy)    system)

This triad ensured that:

• Only authenticated entities could access services
• All communication was encrypted and authenticated
• All interactions had persistent context

The Impact

pai-tls-proxy was a milestone in the PAI’s evolution toward trusted infrastructure. It demonstrated that:

Transport security is infrastructure. Just as identity and observability are foundational, so is encrypted transport.

Centralization simplifies security. A single proxy handles TLS for all services, rather than requiring each service to configure HTTPS individually.

Zero Trust is practical. The PAI demonstrated that Zero Trust principles — verify explicitly, assume breach, least privilege — can be implemented at personal scale.

Certificates should be managed. Manual certificate management is error-prone. Automated issuance and rotation are essential.

The first time someone else experienced pai-tls-proxy’s encrypted communication, it was accidental. A colleague was visiting, and the author had left a browser open with the ARC interface running. The colleague typed a message, and the response appeared — but something was different. The URL showed “https://” and the browser displayed a secure connection indicator.

“Is this… encrypted?” the colleague asked.

“Yes.”

“All of it?”

“Yes. Every service-to-service communication is encrypted. Every token is transmitted over TLS. Every connection is authenticated.”

The colleague watched as the interface continued — chatting with the PAI, receiving responses, requesting voice narration. The entire exchange was encrypted end-to-end.

“Does it… feel different?”

“Yes. Before, communication was plaintext. Now it’s encrypted. You can’t tell the difference, but it’s more secure.”

The colleague didn’t ask to use it. They didn’t need to. The demonstration was sufficient. But the look on their face — the realization that a system could be both convenient and secure — was the validation the author hadn’t known they needed.

The Lesson

Trust is not assumed. It is verified. Every connection should be encrypted, every entity should be authenticated, every access should be authorized.

The pai-tls-proxy project teaches us that:

1. Transport security is infrastructure. It is not a feature — it is a foundation.

2. Centralization simplifies security. A single proxy is easier to manage than individual configurations.

3. Zero Trust is practical. These principles work at any scale — enterprise or personal.

4. Automation is essential. Manual certificate management does not scale.

5. Iteration beats design. The final architecture emerged from failed attempts, not upfront planning.

Code Snippets

Route Configuration

// pai-tls-proxy — Service route configuration
{
  "services": [
    {
      "name": "jay-gentic",
      "listen": ":4400",
      "backend": "127.0.0.1:14400",
      "cert": "~/.jay-auth/certs/jay-gentic/cert.pem",
      "key": "~/.jay-auth/certs/jay-gentic/key.pem",
      "mtls": true
    },
    {
      "name": "voice-server",
      "listen": ":8888",
      "backend": "127.0.0.1:18888",
      "cert": "~/.jay-auth/certs/voice-server/cert.pem",
      "key": "~/.jay-auth/certs/voice-server/key.pem",
      "mtls": false
    }
  ]
}

Certificate Auto-Rotation

// pai-tls-proxy — Automatic certificate rotation
async function rotateCertificates(): Promise<void> {
  const config = await loadConfig();
  
  for (const route of config.services) {
    const cert = await loadCertificate(route.cert);
    if (cert.expiresInDays < 7) {
      const newCert = await jayAuth.issueCertificate({
        commonName: route.name,
        service: route.name,
        sans: [route.name + '.local'],
        ttlHours: 8760
      });
      
      await writeCertificate(route.cert, newCert.certificatePem);
      await writeKey(route.key, newCert.privateKeyPem);
      await reloadProxy();
    }
  }
}

Course Corrections

The pai-tls-proxy project evolved through a series of course corrections, each one documented in git history:

The progression from per-service HTTPS to centralized proxy to automated certificate management to cross-service HTTPS migration shows how the architecture evolved in response to real constraints. Each commit addressed a specific limitation visible only after the previous capability was in place.

Chapter Closing

The chapters ahead will show you how pai-tls-proxy became the foundation for the PAI’s security architecture — how centralized TLS, automatic certificate management, and Zero Trust principles transformed the infrastructure from plaintext to encrypted. But before that evolution, there was another question forming.

If the PAI can communicate securely, what should it understand about its adversaries?

The answer would require more than secure transport. It would require threat intelligence — a system that could track adversaries, map their tactics, and anticipate their moves. It would require awareness.

The next chapter will explore that question — and the breakthrough that gave the PAI threat awareness.

Chapter Summary

Chapter 20 documents the construction of pai-tls-proxy, the centralized TLS termination proxy that completed the PAI’s Zero Trust triad: identity (jay-auth), transport (pai-tls-proxy), and context (memory-system). The chapter opens with the moment of intercepted communication — a JWT token captured in plaintext by net-pack-parser — that revealed the vulnerability of implicit trust on localhost. The first TLS attempt (per-service HTTPS) failed due to unsustainable certificate management, leading to the centralized proxy architecture. The four key capabilities — certificate management, route configuration, automatic reload, and logging — emerged gradually through iteration rather than upfront design. The two-layer architecture (TLS layer for termination and mTLS verification, forwarding layer for HTTP traffic) made the proxy stateless, simple, reliable, and easy to debug. The chapter includes the actual git history timeline showing the evolution from initial implementation (be659e1, Sep 2) through cross-service HTTPS migration (Sep 3-4) to certificate expiry fixes (a544c36, Sep 19). The chapter establishes that trust is not assumed — it is verified. Every connection should be encrypted, every entity authenticated, every access authorized. Transport security is infrastructure, not a feature. Centralization simplifies security: a single proxy is easier to manage than individual configurations. Zero Trust is practical — these principles work at any scale. Automation is essential: manual certificate management does not scale. Iteration beats design: the final architecture emerged from failed attempts, not upfront planning.

Key Technical Facts

Narrative Threads to Carry Forward

• Transport security as infrastructure
• Centralization simplifies security
• Zero Trust is practical
• Automation is essential
• Iteration beats design
• The PAI completing its security foundation
• The shift from plaintext to encrypted communication
• The question of threat awareness (leading to Chapter 21)