xa.service

FastAPI service for xa.

build_api(...) returns a mountable FastAPI app that reimplements the edualc route surface on top of the xa primitives. The service is deliberately a function (not a module that imports-and-runs) so it can be embedded into larger hosts (enlace / tw_platform) or launched standalone via xa serve.

FastAPI is an optional dependency. Import xa.service only when you have installed xa[service] (pulls in fastapi + uvicorn).

Module Attributes

RC_ENABLE_TIMEOUT_SEC

How long POST /sessions/{id}/remote-control waits for claude to write its bridge id after the command is sent.

Functions

allow_all()	No-op auth dependency.
build_api(*[, auth, events_store, ...])	Return a FastAPI app exposing xa's session + archive surface.
make_basic_auth(username, password)	Build a FastAPI dependency that enforces HTTP Basic auth.

Classes

Captcha(*, key[, ttl_sec])

Stateless 4-letter captcha with an HMAC-signed token.

class xa.service.Captcha(*, key, ttl_sec=120)

Bases: object

Stateless 4-letter captcha with an HMAC-signed token.

The signing key never leaves the server. Tokens are b64(CHALLENGE.EXPIRY).SIG where SIG = HMAC-SHA256(key, payload). Multi-worker safe; no server-side state. Pass one instance of this class to build_api() to enable captcha-gated deletes.

issue()

Return (token, challenge, ttl_sec).

Return type:

tuple[str, str, int]

xa.service.RC_ENABLE_TIMEOUT_SEC = 15.0

How long POST /sessions/{id}/remote-control waits for claude to write its bridge id after the command is sent. The TUI acks well before the session file is rewritten, so a bare read would always miss.

xa.service.allow_all()

No-op auth dependency. Useful when the service is behind an external auth layer (enlace, reverse-proxy mTLS) that already gated the request.

FastAPI inspects the signature to decide what to inject; keep this nullary so it isn’t treated as query-parameter binding.

Return type:

str

xa.service.build_api(*, auth=<function allow_all>, events_store=None, pane_store=None, captcha=None, claude_home=PosixPath('/home/runner/.claude'), claude_bin='claude', session_prefix='xa-', title='xa', version='0.1', include_webui=False, default_folder=None)

Return a FastAPI app exposing xa’s session + archive surface.

The caller composes this app into whatever process they have: mount under /api/xa/ inside enlace, or run standalone via uvicorn.

xa.service.make_basic_auth(username, password)

Build a FastAPI dependency that enforces HTTP Basic auth.

Returns a callable suitable for Depends(...). Uses secrets.compare_digest to avoid timing leaks.

Return type:

Callable[..., Any]