Documentation
¶
Overview ¶
Package auth handles inbound caller authentication for codex-app-gateway.
Phase 1 uses an HMAC-signed token of the form
<workspace_id>.<thread_id>.<hex-hmac-sha256>
where the HMAC covers `<workspace_id>\0<thread_id>` keyed by a deployment-shared secret. This matches the wstoken / internal-API pattern used elsewhere in agentserver and avoids pulling a JWT lib just for phase 1. Phase 2 can swap in a JWT impl behind the same `Authenticator` interface.
Package auth implements inbound bearer-token verification.
Phase 2 default is RemoteVerifier: each ws connect POSTs the supplied bearer to agentserver's /api/internal/codex/tokens/verify, which owns the codex_remote_tokens table and applies bcrypt + expiry + revocation policy. This couples the gateway to agentserver's lifecycle but keeps the gateway stateless.
HMACAuthenticator stays in the package as a break-glass / local-test implementation but is no longer used in chart-deployed pods.
Index ¶
- Variables
- func ExtractBearer(r *http.Request) (string, bool)
- type Authenticator
- type HMAC
- type Identity
- type RemoteVerifier
- func (v *RemoteVerifier) CloseSession(ctx context.Context, sessionID string) error
- func (v *RemoteVerifier) OpenSession(ctx context.Context, token, clientIP, clientUA, codexVersion, osStr string) (Identity, string, error)
- func (v *RemoteVerifier) UpdateSessionMeta(ctx context.Context, sessionID, clientUA, codexVersion, osStr string) error
- func (v *RemoteVerifier) Verify(ctx context.Context, token string) (Identity, error)
- type SessionMetaUpdater
- type SessionTracker
Constants ¶
This section is empty.
Variables ¶
ErrUnauthorized is returned by Verify when agentserver responds 401. Distinguishable so handlers can map directly to HTTP 401 without leaking other error reasons (network failure → 500, etc.).
Functions ¶
Types ¶
type Authenticator ¶
Authenticator is the seam for inbound auth. Phase-1 impl is HMAC.
type HMAC ¶
type HMAC struct {
// contains filtered or unexported fields
}
HMAC is the phase-1 Authenticator.
func NewHMAC ¶
NewHMAC returns a phase-1 Authenticator. The secret must be non-empty for tokens to verify; an empty secret will still mint and verify against itself but represents a deployment misconfiguration.
func (*HMAC) Mint ¶
Mint produces a token for `(workspaceID, threadID)`. Useful for tests and CLI tools; production callers receive tokens from agentserver.
func (*HMAC) Verify ¶
Verify parses and HMAC-verifies a token.
Token format: <workspace_id>.<thread_id>.<hex-hmac>
Expects exactly 3 dot-separated parts. The legacy threadID portion (parts[1]) is intentionally discarded — Phase 2 carries identity via the UserID field populated by RemoteVerifier, not by the token payload.
type RemoteVerifier ¶ added in v0.50.7
type RemoteVerifier struct {
// contains filtered or unexported fields
}
RemoteVerifier delegates token verification to agentserver's internal API.
func NewRemoteVerifier ¶ added in v0.50.7
func NewRemoteVerifier(baseURL, bearer string) *RemoteVerifier
NewRemoteVerifier constructs a verifier targeting agentserver's internal HTTP API. baseURL is the http base (e.g. "http://release-agentserver.namespace.svc:8080"); bearer is the value of INTERNAL_API_SECRET used as the X-Internal-Secret header.
func (*RemoteVerifier) CloseSession ¶ added in v0.62.3
func (v *RemoteVerifier) CloseSession(ctx context.Context, sessionID string) error
CloseSession stamps disconnected_at on the row. Best-effort — callers invoke from a deferred goroutine with a short bg ctx so the ws close path is never blocked on it. Implements auth.SessionTracker.
func (*RemoteVerifier) OpenSession ¶ added in v0.62.3
func (v *RemoteVerifier) OpenSession(ctx context.Context, token, clientIP, clientUA, codexVersion, osStr string) (Identity, string, error)
OpenSession verifies the token AND inserts a browser-session row in codex_browser_sessions, returning the session id so the caller can close it on ws disconnect. Implements auth.SessionTracker.
If agentserver doesn't expose session-open (404 on rolling deploys where CXG ships before agentserver, or against test stubs), falls back to plain Verify so codex --remote keeps working — sessions just aren't tracked in codex_browser_sessions until agentserver catches up.
func (*RemoteVerifier) UpdateSessionMeta ¶ added in v0.64.1
func (v *RemoteVerifier) UpdateSessionMeta(ctx context.Context, sessionID, clientUA, codexVersion, osStr string) error
UpdateSessionMeta calls agentserver's session-update endpoint to backfill client_ua / codex_version / os on the row inserted at OpenSession time. Implements auth.SessionMetaUpdater. A 404/405 response (agentserver older than this client) is treated as a silent no-op so rolling deploys don't error.
type SessionMetaUpdater ¶ added in v0.64.1
type SessionMetaUpdater interface {
UpdateSessionMeta(ctx context.Context, sessionID, clientUA, codexVersion, osStr string) error
}
SessionMetaUpdater is an optional capability for backfilling client-info columns on the session row after the ws was already opened. codex 0.132's ws upgrade carries no User-Agent, but the first JSON-RPC frame is `initialize` and includes clientInfo (name + version). The handler snoops that frame and calls this method to fill the dashboard columns.
type SessionTracker ¶ added in v0.62.3
type SessionTracker interface {
OpenSession(ctx context.Context, token, clientIP, clientUA, codexVersion, osStr string) (Identity, string, error)
CloseSession(ctx context.Context, sessionID string) error
}
SessionTracker is an optional capability for Authenticator implementations that also record per-connection sessions (RemoteVerifier does, HMAC does not). The handler in CXG type-asserts and prefers OpenSession when available so the Browsers panel can show live online state + client info.
Source Files