The session plane lets a session authority register per-session surrogates with the proxy. The
authority is the process that starts agent sessions: openab-pty's runtime, or openab on ECS.
Each surrogate is a random token that the authority puts in one child process environment. The
proxy stores only sha256(surrogate), so a registered session can be revoked without changing
the caller key or the real credential.
This document is normative for Phase 1 on Kubernetes. The same calls are reused on ECS over HTTPS in a later phase.
- Kubernetes: HTTP/1.1 with JSON bodies over the Unix socket
/run/auth-proxy-session/session.sock. The socket sits in thesession-planevolume, which only the proxy and the runtime container mount. The agent container does not mount it. - The socket is created with mode 0660 in a setgid directory owned by UID 1001 and group 1002, so the socket's group is 1002. Only the proxy (UID 1001) and the runtime (UID 1002) can connect. The agent (UID 1000) is in neither group, and no mount shows it the path.
- The admin socket is a separate socket that only the proxy mounts, and it does not serve these calls.
- The runtime serves the agent over its own socket,
/run/auth-proxy-agent/runtime.sock. The agent never calls the session socket. See "Agent-runtime socket" below. - Every call except
helloandGET /v1/hello/challengecarriesAuthorization: Bearer <authority-token>.
| Call | Body | Success | Failure |
|---|---|---|---|
GET /v1/hello/challenge (Kubernetes only) |
none | 200 {nonce, ttl_secs}. nonce is 64 lowercase hex, usable once, for 30 s. |
none. The call writes an audit line with no nonce. |
POST /v1/hello (Kubernetes only) |
{identity, nonce, proof}, where identity names an identity in the config and proof is the Ed25519 signature described under "Hello proof" |
201 {authority_token, lease_secs} |
the hello error table under "Hello proof"; 503 broker_unavailable |
POST /v1/sessions |
{session, generation, surrogate_sha256, credentials: [id]} |
201 {lease_secs} |
401 bad token; 400 invalid field; 403 credential_not_granted; 403 session_expired; 409 same session and generation already registered with another hash; 429 over max_sessions; 503 broker_unavailable |
POST /v1/renew |
{sessions: [{session, generation}]} |
200 {lease_secs, unknown: [...]} |
401 |
DELETE /v1/sessions/{session}/{generation} |
none | 204 (also when unknown) |
401 |
PUT /v1/sessions (resync) |
full list as in POST /v1/sessions |
200 {registered, dropped, expired: [{session, generation}]}; sessions not in the list are revoked; expired lists the listed keys skipped because their absolute expiry has passed |
401, 400 (whole request rejected, nothing applied), 503 broker_unavailable (nothing applied) |
The expired field is additive. The proxy writes it only when the list is not empty, so a resync
response with nothing expired has the older shape exactly. An older client denies unknown fields,
so it fails to decode a resync response that names an expired key. The rollout order below covers
this case.
| Status and code | Meaning | Registered? | Client action |
|---|---|---|---|
403 session_expired |
The session key (identity, session, generation) was recorded before, and its absolute TTL has passed. The absolute TTL is a fixed 12 h default in this release (DEFAULT_ABSOLUTE_TTL_SECS in ap-broker); there is no config key for it yet. The stored expiry survives a proxy restart, so a restart does not reset it. |
No. The surrogate stays unknown. | Do not retry this key. A new generation is a new key with its own absolute TTL, so the authority decides whether to start one. |
503 broker_unavailable |
The proxy could not write the session expiry store, so it could not record the key's absolute expiry. The proxy fails closed: nothing is recorded and no session is accepted. | No. Nothing changes. | Retry later, after the store is writable again. The same request is safe to resend. |
A 503 whose body says unavailable (no broker_ prefix) is a different condition: the registry
lock is poisoned. It is not a store failure, and it is not the code above.
- Upgrade the proxy first. With nothing expired, its responses keep the older shape, so clients
that do not know
expiredkeep working. - Upgrade every client that decodes resync responses (the openab-pty runtime and any other authority).
- Only after step 2, enable expiry-driven resync. Until then, a resync that names an expired key can break an older client.
- The hello proof needs the proxy and the runtime shim together. A proxy with the gate refuses a
hello with no proof, so a client that does not sign cannot start an authority. Deploy the proxy
and
ap-runtime-shimin the same pod revision.
Every field is checked before anything is applied. Any failure returns 400 and changes nothing.
session: 1 to 128 characters from[A-Za-z0-9._:-]. This fits openab-pty names and openab thread keys.generation: a u64.surrogate_sha256: exactly 64 lowercase hex characters.credentials: 1 to 16 ids. Each id must be defined in the config and granted to the identity. An id that is defined but not granted returns403 credential_not_granted.- Request bodies over 1 MiB return
413. - A resync list is validated in full before anything is applied. A partly invalid list registers nothing, and the response names the failing entry.
The proxy keeps one absolute-expiry record per session key in a file named
session-expiry.v1. The pod keeps this file on its own durable volume, separate from the
authority token hashes. The proxy takes its location from --expiry-store. Without the flag the
file sits in the token directory. Records are never removed (see docs/design/phase1.md). The
proxy refuses to start when the file is missing, and deploy/k8s/pod.yaml creates it once in an
init container without truncating an existing file.
On Kubernetes the runtime calls hello before it binds its agent socket, and it gets an authority
token back.
- The authority holds a lease of 90 s. It renews the lease, and every live session, with one
renewcall every 30 s. - The proxy keeps only the sha256 of the authority token, in its private volume. It can check the token after a proxy restart without holding the token itself. The authority keeps the token only in memory.
- While the lease is live, another
helloreturns409 authority_active. - When the lease lapses, the proxy revokes every session that the old authority registered, and
then it accepts a new
hello. - Only a
hellothat carries a valid proof can take the lease. The proof is described next.
The runtime holds an Ed25519 seed. The proxy holds only the public key. A process without the seed cannot take the authority, even during a lease lapse.
-
Keys. The runtime's seed is standard base64 of 32 bytes, in Secret
auth-proxy-runtime-key, keyruntime_ed25519.seed. The runtime container mounts it read-only, and no other container does. The proxy's identity config holds the public key asruntime_pubkey(standard base64 of 32 bytes). The public key is not a secret. A malformed key stops the proxy at startup. -
Flow.
GET /v1/hello/challengereturns a nonce. The runtime signs the hello message below and posts{identity, nonce, proof}, whereproofis the standard base64 of the 64-byte signature."auth-proxy hello v1\n" || u32_be(len(identity)) || identity || "\n" || nonce -
Nonces. 32 bytes from the OS RNG, as 64 lowercase hex. Each nonce works once and expires after 30 s. At most 64 are outstanding, and the oldest is evicted first. Nonces live in memory, so a proxy restart clears them.
-
Checks, in order. The first failure returns, and nothing after it runs.
Step Failure Status and code body shape; nonce, when present, is 64 lowercase hexwrong types, unknown fields, or a bad nonce 400 invalid_bodyidentity is in the config not in the config 400 identity_unknownidentity has a runtime_pubkeynone configured 403 runtime_key_missingproofis presentno proof. A body with only identitystops here.401 proof_missingnonceis present, issued, unexpired and unusedmissing, unknown, expired or spent. The entry is removed on lookup. 401 nonce_invalidproofis 64 bytes and verifies strictly over the messagewrong key, wrong identity, or wrong nonce 401 proof_invalidlease a live lease holds the identity 409 authority_activeA refusal before the nonce check does not spend the nonce, so the same nonce works with a proof. The audit line for
hellocarries the identity and the result. It never carries the proof, the nonce or the token. -
What the proof does not cover. A process inside the runtime container can still sign, since the seed is in that container's memory. The runtime container runs only
ap-runtime-shim, so this residual is limited to that one image. The proof stops the agent container and any other container in the pod. The decision record isdocs/design/runtime-split.md.
On ECS there is no hello. The authority token is set in the proxy config as its hash.
Kubernetes only. The runtime container serves this socket. The agent container mounts it, and the proxy does not. It is the only interface the agent has to the session plane.
- Transport: HTTP/1.1 with JSON bodies over
/run/auth-proxy-agent/runtime.sock. The socket is owned by UID 1002, group 1000, mode 0660. The agent sends no identity and no token. The runtime serves one identity, from its own--identityargument. - Bodies are capped at 1 MiB (
413 body_too_large).
| Operation | Request | Success | Failure |
|---|---|---|---|
| register | POST /v1/session with {session, generation, credentials} |
201 {surrogate}. The runtime makes the surrogate (aps_ plus 64 lowercase hex) and sends the proxy its digest only. |
400 invalid_body; 400 invalid_field with field; 403 credential_not_granted; 403 session_expired; 409 conflict; 409 revoke_pending; 429 too_many_sessions; 503 broker_unavailable |
| revoke | DELETE /v1/session/{session}/{generation} |
204. A key the runtime did not register also gets 204, with no proxy call. |
400 invalid_field with field; 503 broker_unavailable |
| status | GET /v1/status |
200 {identity, authority: "live", sessions: [{session, generation}]} |
none beyond 404 and 405 |
- The proxy's refusal codes pass through unchanged.
revoke_pendingis returned while an earlier end of the same key is still unconfirmed. - Every other path returns
404 unknown_operation. That includes/v1/helloand/v1/hello/challenge, which are the proxy's paths and never the agent's. A listed path with a different method returns405 method_not_allowed. - The runtime binds
runtime.sockonly after itshellosucceeds, so the socket never answers before the authority exists.
- A session is revoked when it ends: on exit, kill, restart, absolute TTL, or eviction by the authority.
- A process that outlives its session is refused on its next request.
- Every call writes an audit line with the session id, the generation, a short hash prefix and the result. An audit line never contains a surrogate, the caller key, a nonce, a proof or a token.
- The design's Q1-B table lists the
hellobody as{}. The implementation requires{identity, nonce, proof}, and{identity}alone is refused with401 proof_missing. The matrix driver andap-clientsend the full body. This document uses the implemented body. The design copy atdocs/design/phase1.mdis unchanged, and it still names the old session socket path and the old hello body. - The
400 identity_unknownrow is added. It is returned for a name not in the config.