JjG\dZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z m Z ddl mZddlmZmZddlmZej(eZd ZGd d eeZe Gd d Ze GddZe GddZGddeZGddZGddZgdZ y)uAPI Gateway — control plane HTTP/gRPC gateway for external access. Provides: - REST API for agent orchestration, task submission, status queries - Authentication & authorization middleware - Request validation and rate limiting - OpenAPI schema generation ) annotationsN) AwaitableCallable) dataclassfield)Enum)AnyProtocol)uuid4 unidentifiedc eZdZdZdZdZdZdZy) HTTPMethodGETPOSTPUTPATCHDELETEN)__name__ __module__ __qualname__rrrrrM/home/oem/CyberBrain26-unified/src/cyberbrain26/control_plane/api/__init__.pyrrs C D C E FrrceZdZUdZded<ded<ded<ded<d Zded <ee Zd ed <dZ ded<dZ ded<y)RoutezAPI route definition.strpathrmethodCallable[..., Awaitable[Any]]handlernamesummarydefault_factoryz list[str]tagsTbool requires_authN int | None rate_limit) rrr__doc____annotations__r#rlistr&r(r*rrrrr'sH I  ** IGSD1D)1M4!J !rrceZdZUdZded<ded<ded<ded<d ed <ee Zded <d Zded<ed Z ded<y ) APIRequestavIncoming API request. ``client_addr`` is the caller-supplied remote address (when available) used as the rate-limit key for anonymous traffic. ``request_id`` is an opaque correlation id for the request and is deliberately never used as a rate-limit key (a per-request UUID would create a fresh empty bucket each call and make limiting ineffective). rrrrdict[str, str]headers query_paramsr bodyr$ path_paramsN str | None client_addrc*tjSN)r hexrrrzAPIRequest.Es EGKKr request_id) rrrr+r,rdictr4r6r;rrrr/r/4sN  I   I"'"=K="K",?@J@rr/cPeZdZUdZded<ded<eeZded<d Zd ed <y ) APIResponsez API response.int status_coder r3r$r0r1r"rr;N) rrrr+r,rr<r1r;rrrr>r>Hs) I#D9G^9Jrr>ceZdZdZddZy) AuthProviderz!Authentication provider protocol.c Kyw)zm Authenticate a request. Returns (user_id, claims) or (None, {}) if unauthenticated. Nr)selfrequests r authenticatezAuthProvider.authenticateTs sNrEr/returnz!tuple[str | None, dict[str, Any]])rrrr+rFrrrrBrBQs + rrBceZdZdZ dddd ddZdddddd dd Zdd Zdd Zdd Zdd Z ddZ ddZ ddZ dddZ y) APIGatewayaDHTTP API Gateway for CyberBrain26 control plane. Routes requests to registered handlers, enforces auth, validates input, and applies rate limiting. Security model ------------- The gateway is fail-closed by default: * A route with ``requires_auth=True`` is denied (HTTP 401) when no ``auth_provider`` is configured, rather than silently bypassing authentication. Anonymous access is never the implicit fallback when ``requires_auth`` is set; this closes the fail-open bypass where a gateway constructed without a provider would serve every authenticated route to anonymous callers. * Anonymous routes (``requires_auth=False``) are served only when the caller explicitly opts in via ``allow_unauthenticated=True``. This makes public access intentional and documented instead of accidental, so a forgotten provider does not silently expose routes. * Handler exception text is never returned to clients. A generic error plus an opaque ``correlation_id`` (the request id) is returned instead; exception detail is disclosed only when ``debug=True`` is explicitly set. * Rate limiting is keyed on the authenticated principal (``user_id``) or the caller-supplied ``client_addr``; it is never keyed on the per-request ``request_id``. * Rate limiting is never silently skipped. A request that carries neither a principal nor a ``client_addr`` is throttled through one documented shared ``unidentified`` bucket rather than escaping the limiter; see ``_derive_rate_limit_key``. NF)allow_unauthenticateddebugcXi|_||_||_||_||_i|_yr8)_routes_auth_provider_default_rate_limit_allow_unauthenticated_debug_rate_limit_buckets)rD auth_providerdefault_rate_limitrKrLs r__init__zAPIGateway.__init__|s6*, +#5 '<# ;= rr"T)r!r#r&r(r*c R|jd|} t||||xs>|jjd|jdj dd||xsg||xs |j } | |j | <tjd|j|| S)zRegister a route.:_/)rrr r!r#r&r(r*zRegistered route %s %s) valuerlowerstripreplacerPrNloggerinfo) rDrrr r!r#r&r(r* route_keyroutes r add_routezAPIGateway.add_routes||nAdV, VFLL..014::c?3J3J3PS3T2UV'!=T%=%=  #( Y ,fllDA rc|jd|}||jvr|j|S|jjD]>\}}|j|k7r|j |j ddd|s<|cSy)z2Find route for path/method (supports path params).rXN)r[rNitemsr _match_pathsplit)rDrrraregistered_pathrbs rrbzAPIGateway.routes||nAdV,  $<< * *'+ll&8&8&:  "OU||v% 5 5c1 =a @$G   rc|jd}|jd}t|t|k7ryt||D]\}}|jdr||k7syy)aSSimple path parameter matching. Splits both pattern and path on ``/`` and compares segment by segment. Because the segment counts must be equal and every non-parameter segment must match exactly, this avoids the prefix-matching foot-gun where ``/admin`` would erroneously match ``/administrator``. rZF{T)rhlenzip startswith)rDpatternr pattern_parts path_partsp_patp_paths rrgzAPIGateway._match_pathsm c* ZZ_ } Z 0  ; ME6$   rci}|jd}|jd}t||D]3\}}|jds|jds*|dd}|||<5|S)z+Extract path parameters from matched route.rZrk}re)rhrmrnendswith) rDrorparamsrprqrrrs param_names r_extract_path_paramszAPIGateway._extract_path_paramssq c* ZZ_   ; ,ME6$)<"1R[ %+z" , rcK|j|j|j}|stdddi|jSd}i}|j rh|j tdddi|jS|j j|d{\}}|@tdddi|jS|jstdddi|jS|j||j}|jr9|j||jstddd id d i|j S ||||j|j|jd }|jdi|d{}t|tr|j|_|Std||jS7,7B#t $r}t"j%d|jj&|jd|jd} |j(rt+|| d<td| |jcYd}~Sd}~wwxYww)zProcess an incoming request.ierrorz Not found)r@r3r;Ni UnauthorizedizRate limit exceededz Retry-After60)r@r3r1r;)rEuser_idclaimsr4zHandler error for %s %szInternal server error)r|correlation_iddetailir)rbrrr>r;r(rOrFrQ_derive_rate_limit_keyr6r*_check_rate_limitrzr isinstance Exceptionr_ exceptionr[rRr) rDrErbrrrate_keycontextresultexcr3s rhandlezAPIGateway.handlesO 7<<83g{5KX_XjXjk k#!#   ""*" #!>2&11 %)$7$7$D$DW$MMOGV" #!>2&11 ,,~."-- ..w8K8KL   D$:$:8UEUEU$V45&-"--   Z#" #88W\\R G )5==3733F&+.$+$6$6! 3VHZHZ[ [YNP4  Z   68L8Lgll [0")"4"4$D{{!$SX3TgFXFXY Y ZscBIGB*IAG G&G ,I-G IG IA5II IIIc*|rd|S|rd|StS)uDerive the rate-limit bucket key for a request. The rule lives in one place so it is auditable: the authenticated principal wins, the caller-supplied address is next, and a request that offers neither is attributed to a single shared ``unidentified`` bucket. Every key is namespaced by its kind so a principal named like an address (or vice versa) can never share quota with it. Security rationale: this helper is deliberately total — it never returns ``None`` and never reports "no key". The previous inline ``user_id or request.client_addr`` guard short-circuited the rate-limit check when both were absent, so an unauthenticated request (the ``allow_unauthenticated=True`` path) was served with no bucket at all and no limit could ever fire: fail-open, and fail-open precisely on the floodable path. Trade-off, chosen deliberately: the shared bucket means one unidentified caller can consume the unidentified quota and lock out other unidentified callers for the rest of the window (a denial-of-service on that bucket only). The alternative — having no bucket for such requests — lets one caller exhaust the process itself, and that limit is unbounded and permanent for the lifetime of the gateway. Bounding the damage to a shared quota of the anonymous path is the smaller and reversible failure; authenticated principals keep their own independent buckets and are unaffected either way. Args: user_id: Authenticated principal id, or ``None`` when the request is anonymous or unauthenticated. client_addr: Caller-supplied remote address, or ``None`` when the transport did not supply one. Returns: A non-empty, namespaced bucket key, always safe to use. z principal:zaddr:)UNIDENTIFIED_RATE_LIMIT_KEY)rDrr6s rrz!APIGateway._derive_rate_limit_key#s+H y) ) ;-( (**rc tj}|dz }||jvrg|j|<|j|}|Dcgc] }||kDs | c}|ddt||k\ry|j|ycc}w)abSimple in-memory sliding window rate limiter. ``key`` MUST be a stable bucket identifier produced by ``_derive_rate_limit_key`` (a principal, a client address, or the shared ``unidentified`` bucket). Keying on a fresh per-request UUID would create a new empty bucket every call and the limit could never trigger. <NFT)timerSrlappend)rDkeylimitnow window_startbuckettss rrzAPIGateway._check_rate_limitMsiikRx d.. .,.D $ $S )))#."(>BB,=R>q v;%  c ?s BBcHt|jjS)zList all registered routes.)r-rNvalues)rDs r list_routeszAPIGateway.list_routesasDLL'')**rc i}|jjD]}|j|vri||j<|j|j|j |j rdgigngddiddiddiddidd||j|jjj<d ||d |d dd d diidS)zGenerate OpenAPI 3.0 schema. The schema reflects only route metadata (summary, tags, security requirements). It never embeds credentials, API keys, or handler claims, so it is safe to expose publicly for documentation. bearerAuth descriptionSuccessr}z Rate limitedzInternal error)200401429500)r# operationIdr&security responsesz3.0.0)titleversionsecuritySchemeshttpbearer)typescheme)openapir`paths components) rNrrr#r!r&r(rr[r\)rDrrrrbs rgenerate_openapizAPIGateway.generate_openapies!#\\((* Ezz&$&ejj! ==$zz 494G4GlB/0R)95)>:)>:)+;<  =E%** ell00668 9  #8! 6X"F$  r)Nr) rTzAuthProvider | NonerUr?rKr'rLr'rHNone)rrrrr rr!r5r#rr&zlist[str] | Noner(r'r*r)rHr)rrrrrHz Route | None)rorrrrHr')rorrrrHr0)rEr/rHr>)rr5r6r5rHr)rrrr?rHr')rHz list[Route])zCyberBrain26 APIz1.0.0)rrrrrHzdict[str, Any])rrrr+rVrcrbrgrzrrrrrrrrrJrJ\sB.2"$> ', >*> > $ >  > >2 !%"!%/    8 & JZX(+T(+  rrJc"eZdZdZdddZddZy)SimpleAPIKeyAuthaSimple API key (bearer token) authentication for development. Security properties: * Plaintext API keys are never retained. The constructor hashes each key with SHA-256 and stores only the digest, so a memory/core dump or an accidental log of the provider cannot disclose live credentials. * Lookup is performed with ``hmac.compare_digest`` instead of a plaintext dict membership test, avoiding the timing side-channel of a plain ``dict.get`` which could leak information about which keys are valid. * Returned ``claims`` never contain the raw bearer token, preventing credential leakage into handler logs or response bodies. Known gaps (documented, intentionally not implemented): keys never expire and there is no rotation support. Production deployments should use a dedicated auth service with short-lived tokens and key rollover. Nc |xsijDcic]8\}}tj|jdj |:c}}|_ycc}}w)zBuild a provider from a plaintext ``api_key -> user_id`` mapping. Keys are hashed on construction and the plaintext input is discarded; the provider holds only SHA-256 digests internally. utf-8N)rfhashlibsha256encodedigest_keys)rD valid_keysapi_keyrs rrVzSimpleAPIKeyAuth.__init__sU&0%52$<$<$>(   NN7>>'2 3 : : %%i08Oab/w 78??A""&**"2"2"4  M3""6=9   UG,, ,Rxs B!B5$B5r8)rzdict[str, str] | NonerHrrG)rrrr+rVrFrrrrrs$  rr)rrJr/r>rBrrr)!r+ __future__rrrloggingrcollections.abcrr dataclassesrrenumrtypingr r uuidr getLoggerrr_rrrrr/r>rBrJr__all__rrrrs#  /(    8 $-d  " "  " AA A&   8 i i Z --` r