lifegw

lifegw (Life Gateway) is the stateless, internet-facing edge daemon of the Life Agent OS. It sits at the boundary between the public internet and the privileged lifed daemon, handling all concerns that belong at the network edge: TLS termination, identity JWT verification, capability token minting, rate limiting, and WebSocket session establishment.

lifed never touches the internet. lifegw never touches privileged state. The two daemons communicate exclusively over a Unix domain socket.

Position in the topology

Internet
    │  TLS 1.3 (rustls)
    ▼
 lifegw   ← stateless, unprivileged, horizontally scalable
    │  Unix Domain Socket
    ▼
  lifed   ← privileged, stateful, manages substrate connections
    │
    ├── chronosd    (temporal substrate)
    ├── animad      (identity substrate, via soma UDS)
    ├── lago        (event journal)
    ├── haima       (payments)
    └── vigil       (observability)

lifegw knows nothing about agents, sessions, or substrate state. It knows how to verify a JWT, mint a scoped capability token, and forward a request. That is the entirety of its job.

Public endpoints

Both URLs front the same lifegw deployment on Railway (TLS termination at Railway's edge → Caddy in-container → lifegw HTTPS on 127.0.0.1:8443). The life.broomva.tech CNAME points at Railway's edge; Let's Encrypt issues the cert on Railway's side. Use the canonical URL in client code; the Railway alias is for diagnostics.

Stack

Routes

Health

Auth bootstrap

Anima custody

Agent

The chat surface is a two-phase flow — create_session returns a server-issued sid, then the WSS upgrade attaches a stream to that session. The session id passed in the WS query string is the canonical handle for resumability.

Authentication

Tier-1: Identity JWTs

Incoming requests carry a Tier-1 JWT — an ES256 JWT issued by the Vercel identity provider (or a dev-mode HS256 token). lifegw verifies these against a JWKS endpoint:

JwksCache → fetch JWKS → verify ES256 signature → extract claims

JwksCache uses a FlightCoalescer cohort pattern — concurrent requests for a JWKS refresh coalesce into a single fetch, preventing thundering-herd cache misses. The cache is updated atomically.

Tier-2: Capability tokens

After verifying a Tier-1 JWT, lifegw can mint a Tier-2 capability token via TierUserMinter:

• Audience: anima.user-cap
• TTL: 15 minutes
• Scope: per-route (e.g. anima.user.sign_auth, anima.user.sign_wallet)
• Subject binding: claims.sub must match body.user_id on every request

TierUserMinter is a sibling of Tier2Minter (which mints service-to-service capability tokens). Both use the same KmsSigner trait, which abstracts over StaticKeystore, VaultTransit, AwsKms, and GcpKms.

WebSocket bearer auth

WebSocket connections carry their JWT via the Sec-WebSocket-Protocol: bearer.<jwt> subprotocol header. The subprotocol value is parsed by lifegw before the upgrade completes. Invalid bearer values (malformed characters, oversized tokens) are rejected with a 400 before the WebSocket handshake.

Client: Sec-WebSocket-Protocol: bearer.eyJhbGciOiJFUzI1NiJ9...
lifegw: parse → verify → upgrade → open bidi stream

Rate limiting

Token-bucket rate limiting is applied at two levels:

Rate limit responses return HTTP 429 with a Retry-After header. The token bucket parameters (capacity, refill rate) are configurable in lifegw.toml.

Chat session flow

Chat is a two-phase wire: HTTP create_session followed by a WSS upgrade attached to the returned sid. Native clients (Rust, server-to-server) authenticate via Authorization: Bearer <jwt>; browser clients authenticate via the Sec-WebSocket-Protocol: bearer.<jwt> subprotocol (browsers cannot set arbitrary headers on WebSocket constructors).

Wire envelope shapes

agent_kind enum (server-emitted):

Authentication shape per route

The pump handles:

• Heartbeats: 30-second ping/pong interval. 3 missed pongs close the connection with CloseCode::ProtocolError.
• Unknown frames: rejected immediately with CloseCode::UnsupportedFrame (close code 1003 per Spec C₃ §6.5).
• Unknown frame characters: bearer subprotocol values with control characters or non-ASCII are rejected before the upgrade.

Admin plane

lifegw exposes a Unix domain socket for privileged management operations:

/run/life/lifegw-admin.sock

Authentication uses SO_PEERCRED — the kernel verifies the connecting process's UID/GID. Only processes in the life-runtime group are admitted. This is enforced via getgrouplist with a negative cache for failed lookups. Group-lookup failures are fail-closed (admission denied, not granted).

The admin plane supports:

• JWKS cache flush (force re-fetch from provider)
• Rate limit bucket inspection
• Graceful drain (stop accepting new connections, finish active streams)
• TLS certificate hot-swap via shared CertReloader

Security properties

Configuration

lifegw is configured via lifegw.toml:

[tls]
cert_path = "/etc/life/lifegw.crt"
key_path  = "/etc/life/lifegw.key"
# CertReloader polls every 5s — certificate rotation is hot-swap, no restart required

[auth]
jwks_url = "https://your-vercel-project.vercel.app/.well-known/jwks.json"
dev_mode  = false  # true: accept HS256 dev tokens without JWKS verification

[rate_limit]
per_user_capacity = 100
per_user_refill_per_sec = 10
per_ip_capacity = 200
per_ip_refill_per_sec = 20

[lifed]
uds_path = "/run/life/lifed.sock"

[admin]
uds_path = "/run/life/lifegw-admin.sock"
group    = "life-runtime"

Relation to other subsystems