`gjh-UdZddlmZddlZddlZddlZddlZddlmZddl m Z ddl m Z m Z mZmZej eZdZdZd Zd Zd ad ed <ddZed ddZGdde ZddZddZy)uQ DrainSecretProvider — shared-bearer-secret auth for the drain-control endpoint. Task 2.0b of the safe-shutdown plan, and the FIRST consumer of the generic non-interactive token-auth capability added in Task 2.0a (``supports_token`` / ``verify_token`` on the ``DashboardAuthProvider`` ABC + the route-agnostic ``token_auth`` middleware seam). What it is ---------- A service-to-service auth provider. ``nous-account-service`` (NAS) provisions a **per-agent unique** shared secret into each deployed agent's environment; this provider verifies an inbound ``Authorization`` bearer token against that secret with a constant-time compare and, on a match, vouches for the caller as the ``drain-control`` principal. It is NOT an interactive identity provider — there is no login, cookie, session, or refresh. It implements ONLY the token capability (``supports_token = True`` + ``verify_token``); the five interactive ABC methods raise ``NotImplementedError``. Why a plugin (not an ad-hoc header check on the drain route) ------------------------------------------------------------ Decisions.md Q-A: the drain credential MUST be a real auth plugin in the dashboard auth framework, not a bolt-on. Q-C: the framework widening that hosts it is generic (Task 2.0a) and this plugin is merely its first consumer. Security properties (decisions.md Q-A) -------------------------------------- * **Per-agent unique secret** — each agent gets a distinct secret; a leak's blast radius is one agent. * **Entropy gate at registration** — a weak/short/low-entropy secret fails CLOSED at load (the plugin declines to register and records a skip reason); it is never silently accepted. Bar: >= 256 bits of entropy / >= 43 url-safe-base64 chars, and the value must not be obviously structured (all-one-character, too few distinct characters). * **Constant-time compare** — ``hmac.compare_digest`` on the request path, so the endpoint is not a timing oracle. Configuration ------------- The secret is a CREDENTIAL, so it is carried via an env var (the ``.env``-is- for-secrets-only rule), provisioned by NAS at deploy time (Phase 3): HERMES_DASHBOARD_DRAIN_SECRET # the per-agent shared secret (>=43 url-safe-b64 chars) Behavioural knobs live in config.yaml (canonical surface): dashboard: drain_auth: scope: drain # capability label attached to the principal min_secret_chars: 43 # entropy bar (optional; default 43 ~= 256 bits) When ``HERMES_DASHBOARD_DRAIN_SECRET`` is unset, the plugin is a no-op (records a skip reason) — agents that don't want NAS-driven drain just don't set it. ) annotationsN)Counter)Optional)DashboardAuthProvider LoginStartSessionTokenPrincipal+g`@z/api/gateway/drainstrLAST_SKIP_REASONc|syt|}t|tfd|jD }|zS)zTotal Shannon entropy (bits) of ``value`` over its character distribution. H = len * sum(-p_i * log2(p_i)). A long string drawn from a wide alphabet scores high; a long run of one character scores ~0. gc3ZK|]"}|z tj|z z$ywN)mathlog2).0cns X/root/.hermes/venv/lib/python3.12/site-packages/plugins/dashboard_auth/drain/__init__.py z _shannon_bits..ds'H1QUdiiA..Hs(+)rlensumvalues)valuecountsper_charrs @r _shannon_bitsrZs@  U^F E AH HHHH a< min_charsc|syt||krdt|d|dStt|}|tkr d|dtdSt|}|tkrd|d d td d Sy ) aReturn a rejection reason if ``secret`` is too weak, else ``None``. Fail-closed entropy gate (decisions.md Q-A). Checks, in order: * length >= ``min_chars`` (default 43 url-safe-b64 chars ~= 256 bits), * at least ``_MIN_DISTINCT_CHARS`` distinct characters, * Shannon entropy >= ``_MIN_SHANNON_BITS`` bits. A ``None`` return means the secret passes. Any string return is a human-readable reason the caller logs + records as the skip reason. zsecret is emptyzsecret too short: z chars (need >= z]; use a >=256-bit value, e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`)zsecret has only z distinct characters (need >= z); looks structured/low-entropyzsecret entropy too low: z.0fz bits (need >= z); looks structured/repeatedN)rset_MIN_DISTINCT_CHARSr_MIN_SHANNON_BITS)secretr"distinctbitss rassess_secret_strengthr*hs   6{Y V -=i[I3 3 3v;H%%xj(F"##B D   D &tCj %%A C  r creZdZdZdZdZdZdZddddZdd Z dd Z dd Z dd Z dd Z ddZy)DrainSecretProviderz@Non-interactive shared-bearer-secret provider for drain control.z drain-secretz"Drain Control (service credential)TFdrain)scopec^t|}|td|||_|xsd|_y)Nzdrain secret rejected: r-)r* ValueError_secret_scope)selfr'r.reasons r__init__zDrainSecretProvider.__init__s:(/  6vh?@ @ &w r c|sytj|jd|jjdr#t d|j |j fSy)a Constant-time compare against the per-agent shared secret. Returns a ``drain-control`` principal on an exact match, else ``None`` (the generic seam falls through / fails closed). Uses ``hmac.compare_digest`` so a wrong token can't be recovered by timing. Nzutf-8z drain-control) principalproviderscopes)hmaccompare_digestencoder1r namer2)r3tokens r verify_tokenz DrainSecretProvider.verify_tokensW   u||G4dll6I6I'6R S!) ~  r ctd)NzTDrainSecretProvider is a non-interactive service credential; there is no login flow.NotImplementedError)r3 redirect_uris r start_loginzDrainSecretProvider.start_logins! &  r ctdNzr rUzOptional[TokenPrincipal])rCr rUr) rGr rHr rIr rCr rUr)rMr rUzOptional[Session])rQr rUr)rQr rUrV)__name__ __module__ __qualname____doc__r= display_namesupports_tokensupports_sessionr5r?rDrJrNrRrTrLr rr,r,shJ D7LN4;'&   #& 7: JM    r r,c ddlm}m}|}||ddd}t |tr|SiS#t$r"}tj d|icYd}~Sd}~wwxYw)z=256-bit secret (e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`) to enable NAS-driven drain coordination; leave it unset to disable the drain endpoint.zdashboard-auth-drain: %sNr.r-min_secret_charsr!u+HERMES_DASHBOARD_DRAIN_SECRET rejected — z2. The drain endpoint stays disabled (fail-closed).)r'r.z)DrainSecretProvider construction failed: r)register_token_routez;dashboard-auth-drain: could not register token route %s: %szWdashboard-auth-drain: registered drain service-credential provider (scope=%s, route=%s))rosenvirongetstriprfrgrmr int_DEFAULT_MIN_SECRET_CHARS TypeErrorr0r*warningr, register_dashboard_auth_provider$hermes_cli.dashboard_auth.token_authrqDRAIN_ROUTE_PATHreinfo) ctxr'rlr.r"r4r8rkrqs rregisterrs ZZ^^;R @ F F HF  J   /1AB-/G  GW-8 9 ? ? A LWE. $68QRS $Fi @F 9&B? ?  13CD&fEB ((2 M-. KK  C z ".- . FseL13CD   I c   sB D) E;E9)EE E6 E11E69 F'F""F')rr rUfloat)r'r r"rvrUz Optional[str])rUri)rUrV)rZ __future__rr:loggingrrr collectionsrtypingrhermes_cli.dashboard_authrrrr getLoggerrWrfrwr%r&r|r__annotations__rr*r,rmrrLr rrs4j#     8 $ (# &?! !"!!H@/@P8">r