(Gjh-UdZddlmZddlZddlZddlZddlZddlmZddl m Z ddl m Z m Z mZmZejeZdZdZd Zd Zd ad ed <ddZedddZGdde Zd dZd!dZdS)"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_REASONvaluereturnfloatc|sdSt|}t|tfd|D }|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. gc3RK|]!}|z tj|z zV"dSN)mathlog2).0cns K/home/rurouni/.hermes/hermes-agent/plugins/dashboard_auth/drain/__init__.py z _shannon_bits..ds:HH1QUdiA...HHHHHH)rlensumvalues)rcountsper_charrs @r _shannon_bitsr"Zs_ s U^^F E AHHHH HHHHHHH a<r min_charssecretr$int Optional[str]c|sdSt||krdt|d|dStt|}|tkrd|dtdSt|}|tkrd|d d td d Sd S) 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)r%r$distinctbitss rassess_secret_strengthr.hs !   6{{Y 3V 3 3i 3 3 3 3v;;H%%% Dx D D" D D D   D  Ct @ C C B C C C  4rc`eZdZdZdZdZdZdZddd d Zd!dZ d"dZ d#dZ d$dZ d%dZ d&dZdS)'DrainSecretProviderz@Non-interactive shared-bearer-secret provider for drain control.z drain-secretz"Drain Control (service credential)TFdrain)scoper%r r2rNoneclt|}|td|||_|pd|_dS)Nzdrain secret rejected: r1)r. ValueError_secret_scope)selfr%r2reasons r__init__zDrainSecretProvider.__init__sE(//  ?v??@@ @ &w rtokenOptional[TokenPrincipal]c|sdStj|d|jdrt d|j|jfSdS)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_digestencoder6r namer7)r8r;s r verify_tokenz DrainSecretProvider.verify_tokenso 4  u||G44dl6I6I'6R6R S S !) ~  tr redirect_urirc td)NzTDrainSecretProvider is a non-interactive service credential; there is no login flow.NotImplementedError)r8rFs r start_loginzDrainSecretProvider.start_logins! &   rcodestate code_verifierrc tdNz=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: %sNr2r1min_secret_charsr#u+HERMES_DASHBOARD_DRAIN_SECRET rejected — z2. The drain endpoint stays disabled (fail-closed).)r%r2z)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))rosenvirongetstriprlrmrrr r&_DEFAULT_MIN_SECRET_CHARS TypeErrorr5r.warningr0 register_dashboard_auth_provider$hermes_cli.dashboard_auth.token_authrvDRAIN_ROUTE_PATHrkinfo) ctxr%rqr2r$r9r?rprvs rregisterrse Z^^;R @ @ F F H HF  J   /1ABBB-//G  GW--8 9 9 ? ? A A LWE. $68QRRSS z "...- .$Fi @ @ @F  ?& ? ? ?  13CDDD&fEBBB LsLL13CDDD ((222 MMMMMM-....     I c          KK  sB#(C C'&C'&D88 E2%E--E2 F"" G,!GG)rr rr)r%r r$r&rr')rrc)rr3)r_ __future__rrAloggingrrw collectionsrtypingrhermes_cli.dashboard_authrrrr getLoggerr\rlr{r*r+rr__annotations__r"r.r0rrrrTrrrs444j#"""""    8 $ $ (    &?!!!!!!H@@@@@/@@@P8888">>>>>>r