Trust-Root Tier

Port :666 is reserved for endpoints whose compromise would undermine the security guarantees of a Microbus deployment. The framework treats :666 as a separate tier with two layers of protection: the HTTP ingress proxy unconditionally blocks all external traffic on :666, and the interservice ACL gates internal callers on a per-call-site basis.

What Lives on `:666`

Two foundational endpoints in any Microbus deployment that uses the framework’s authentication model:

access.token.core/Mint - issues new actor JWTs with arbitrary claims. Compromise lets the attacker mint a token with any actor identity and any permissions.
bearer.token.core/Mint - issues bearer tokens. Compromise lets the attacker mint user credentials.

Optional shipped services may expose their own :666 endpoints:

shell.core/Execute - runs shell commands on the host. Compromise lets the attacker execute arbitrary code in the deployment.

Application code may define additional :666 endpoints for privileged operations:

Role grants and revocations.
Privileged writes to sensitive tables.
Operations that read or modify other actors’ tokens.
Anything where an unintended caller would lead to a security incident.

Putting an endpoint on :666 is a deliberate choice with deployment cost. Do not put an endpoint on :666 because it is “important”. Put it on :666 because its compromise undermines security guarantees.

The Two Protection Layers

Layer 1 - Ingress Unconditional Block

The HTTP ingress proxy refuses to forward any inbound request on :666, regardless of:

Deployment mode (PROD, LAB, LOCAL, TESTING).
The actor’s claims.
Plane (data plane, management plane).

External traffic cannot reach a trust-root endpoint, ever. This block is hard-coded into the ingress and is not configurable.

Layer 2 - Interservice ACL on Internal Callers

Internal callers reach :666 over the bus, where the interservice ACL gates them. A microservice gets the ACL rule for a specific :666 endpoint only when its source code contains an actual call site for that endpoint. gencreds walks the source tree at deploy time, finds the call site, and emits the corresponding PUB grant in the caller’s .creds.

No call site, no permission. The framework will not invent a :666 grant from a config file or runtime registration.

The NATS subject layout reserves a separate danger segment for :666 traffic. A broad allow rule that covers safe ports (:443, :444, :417, :428) cannot accidentally subsume a trust-root grant - the segments are different.

Adding a Custom `:666` Endpoint

A handful of steps:

Declare the endpoint on port 666 in the microservice’s manifest.yaml.
Implement the handler. Treat the input as untrusted even within the bus - the ACL gates which microservices can reach you, but their compromised state could still send you malformed input.
Apply requiredClaims if the operation should be further restricted by actor identity (e.g. only callers with roles.admin).
Add the :666 call site to the upstream microservice’s source code.
Re-run gencreds to regenerate .creds for both microservices. The upstream gets a new PUB rule on the danger segment; the downstream gets a SUB rule.
Re-deploy both microservices with their new .creds.

If you skip step 5, the broker will reject the call. There is no “permissive mode” for trust-root traffic.

Auditing the Trust-Root Surface

The trust-root surface of a deployment is the set of :666 endpoints any microservice is currently authorized to call. Every active grant is in a microservice’s .creds. To enumerate the surface:

# Show Every Microservice That Holds at Least One :666 Grant.
grep -l danger *.creds

# Enumerate One Microservice's :666 Grants.
grep danger ingress_nats.creds

# Enumerate the Full Surface Across the Deployment.
for f in *.creds; do
  grep "^.*danger" "$f" | sed "s|^|$f: |"
done

Each line is one {caller, host, method, path} permission to a :666 endpoint. Review the list when performing security audits. New entries should be expected - they correspond to a code change in the caller - and any unexplained entry is a red flag.

Deployment Recommendations

Trust-root microservices benefit from being deployed in their own application bundle. The cost is one extra OS process per trust root. The gain:

A compromise in any other application cannot reach memory inside the trust root.
A compromise of the trust root is bounded to the trust root’s own permission set, not extended through shared address space.
Restart, rollout, and audit operations on the trust root are independent of the rest of the deployment.

Concretely, the recommended posture for a Microbus deployment is:

Access token service - own application.
Bearer token service (or its wrapper) - own application.
Shell service - own application, deployed only where genuinely needed.
Custom :666 services - own application unless you have an explicit reason to bundle.

See Application Bundling for the full trade-off analysis.

What This Layer Does Not Do

It does not protect against a compromised :666 microservice itself. Once an attacker is inside the access token service, they can mint anything. The protection here is to keep the attacker out of the trust root, not to limit damage from inside it.
It does not gate requiredClaims evaluation. A :666 endpoint can still impose actor-claim requirements (requiredClaims: roles.admin), and probably should - but that is a per-endpoint choice, not a tier guarantee.
It does not encrypt the message. NATS connections use TLS for transport; the trust-root tier is about who can reach the endpoint, not who can read the message in flight.