v32

OpenAPI 3.0.3AGPL-3.0-onlyraw.githubusercontent.com2026-08-0178220333.8 KB
system

POST /auth/connect.

Validates the bearer token in the Authorization header, registers the client PID, and returns a JWT session token wrapped in the canonical envelope.

Rate limiting: This endpoint has no session token yet, so rate limiting is applied by client IP address (from ConnectInfo). This is trustworthy because it comes from the TCP stack, not caller-controlled input.

NOTE on ConnectInfo: ConnectInfo<SocketAddr> reads the socket address from the TCP connection metadata, NOT from HTTP headers. In test contexts (using tower::ServiceExt::oneshot without a real TCP listener), the socket address will be a default value (typically 127.0.0.1:0 or ::1:0). The unit tests for SlidingWindowRateLimiter cover the rate limiting logic independently. IP-based rate limiting for /auth/connect works correctly in production.

IMPORTANT: ConnectInfo<SocketAddr> works ONLY when the server uses into_make_service_with_connect_info::<SocketAddr>(). In test contexts using tower::ServiceExt::oneshot, ConnectInfo may be absent. The handler uses Option<ConnectInfo<SocketAddr>> so tests work correctly. IP-based rate limiting is skipped when ConnectInfo is unavailable (test-only code path).

post/auth/connect

Request body

clientTypestring required

Client type: "gui", "cli", or "other".

pidinteger required

Client process ID. Used for PID whitelist verification in JWT middleware.

Response

JWT session token issued

tsinteger required

Server time when the response was built (unix epoch milliseconds).