epj\8UdZddlmZddlZddlZddlZddlmZmZddl m Z m Z ddl m Z mZddlmZddlmZdd lmZmZmZmZmZmZd Zd ed <ed dZd3dZd4dZd5dZdZ dZ!Gdde"eZ#e GddZ$Gdde Z%ej&d Z'ej&d!Z(d6d%Z)d7d'Z*d(de!d)d8d2Z+dS)9umSecret-source contract: the ABC every secret backend implements. A *secret source* resolves credentials from an external secret manager (Bitwarden Secrets Manager, 1Password, an OS keystore, a user script, ...) into environment-variable-shaped values at process startup, AFTER ``~/.hermes/.env`` has loaded and BEFORE the rest of Hermes reads ``os.environ``. Scope of the contract (deliberate, please do not widen): * **Read-only.** Sources resolve refs → values. There is no write-back ("save this key to your vault"), no arbitrary secret objects, and no mid-session secret API. If a future need for rotation/refresh appears it will arrive as a versioned optional hook — do not bolt it on. * **Startup-time, synchronous.** ``fetch()`` is called once per process (per HERMES_HOME) by the orchestrator in :mod:`agent.secret_sources.registry`, which enforces a wall-clock timeout around it. Sources must not spawn background refreshers. * **Never raises, never prompts.** ``fetch()`` returns a :class:`FetchResult` — errors go in ``result.error`` with a machine-readable :class:`ErrorKind`. Interactive auth belongs in the source's CLI ``setup`` flow, never on the startup path (non-TTY gateway/cron startup must never block on stdin). * **Sources fetch; the orchestrator applies.** A source returns the name→value mapping it *would* contribute. Precedence (mapped-beats-bulk, first-wins, ``override_existing``, protected vars), conflict warnings, provenance tracking, and the actual ``os.environ`` writes are owned by the orchestrator so no backend can get them wrong. Versioning: ``SECRET_SOURCE_API_VERSION`` gates plugin compatibility. New *optional* hooks with default implementations do not bump it; required-signature changes do, and the registry skips (with a warning) sources built against a different major version instead of crashing startup. ) annotationsN) ContextVarToken)ABCabstractmethod) dataclassfield)Enum)Path)Dict FrozenSetListMutableMappingOptionalSequencez.ContextVar[Optional[MutableMapping[str, str]]]_SOURCE_ENVIRONMENT hermes_secret_source_environment)defaultenvironMutableMapping[str, str]returnrc6t|S)zEInstall a per-fetch environment view without changing ``os.environ``.)rsetrs ?/home/thesage/.hermes/hermes-agent/agent/secret_sources/base.pyset_source_environmentr:s  " "7 + ++tokenNonec:t|dSN)rreset)rs rreset_source_environmentr$?se$$$$$rcTt}||n tjS)zDReturn the active per-fetch environment, or the process environment.)rgetosrrs rget_source_environmentr(Cs$!%%''G)77rz9rg^@g>@c6eZdZdZdZdZdZdZdZdZ dZ d Z d Z d S) ErrorKinda[Machine-readable failure taxonomy for :class:`FetchResult.error`. A fixed vocabulary keeps startup warnings and ``hermes secrets status`` uniform across backends, and lets the orchestrator implement kind-dependent policy (e.g. a future stale-cache fallback on ``NETWORK``/``TIMEOUT`` but not on ``AUTH_FAILED``) exactly once. not_configuredbinary_missing auth_failed auth_expired ref_invalidnetwork empty_valuetimeoutinternalN) __name__ __module__ __qualname____doc__NOT_CONFIGUREDBINARY_MISSING AUTH_FAILED AUTH_EXPIRED REF_INVALIDNETWORK EMPTY_VALUETIMEOUTINTERNALrrr*r*QsG&N%NK!LKGKGHHHrr*ceZdZUdZeeZded<eeZ ded<eeZ ded<eeZ ded<d Z d ed <d Z d ed <d Zded<eddZd S) FetchResultagOutcome of one source's fetch. ``secrets`` holds what the source *would* contribute; whether each var is actually applied is the orchestrator's decision. ``applied`` and ``skipped`` exist for backward compatibility with the original Bitwarden fetch-and-apply entry point and are left empty by conforming ``fetch()`` implementations. )default_factoryzDict[str, str]secretsz List[str]appliedskippedwarningsN Optional[str]errorzOptional[ErrorKind] error_kindzOptional[Path] binary_pathrboolc|jduSr")rJselfs rokzFetchResult.okzszT!!r)rrM)r4r5r6r7r dictrE__annotations__listrFrGrHrJrKrLpropertyrQrArrrCrCes$eD999G9999t444G4444t444G4444%555H5555E&*J****#'K&&&& """X"""rrCceZdZUdZeZded<dZded<dZded<dZ ded <d Z d ed <e ddZ d dZ d dZd!dZd"dZd#dZd$dZd S)% SecretSourceu[One external secret backend. Subclasses set the class attributes and implement :meth:`fetch`. Everything else has a sensible default. Attributes: name: Config-section key under ``secrets:`` in config.yaml. Lowercase ``[a-z0-9_]+``. Also the provenance label stored for every var this source supplies. label: Human-readable name used in startup messages and ``hermes secrets status`` (e.g. ``"Bitwarden Secrets Manager"``). shape: ``"mapped"`` when the user explicitly binds env-var names to refs (1Password ``env:`` map, command source) or ``"bulk"`` when the backend injects whole projects/folders of secrets implicitly (Bitwarden BSM). The orchestrator gives mapped sources precedence over bulk sources: an explicit binding is stronger intent than a project dump. scheme: Optional URI scheme this source owns for secret references (``"op"`` for ``op://...``). Must be unique across registered sources — refs may eventually appear outside the ``secrets:`` block (e.g. credential-pool ``api_key`` fields), so scheme collisions are rejected at registration time to keep that future possible. api_version: Contract version this source was built against. int api_versionstrnamelabelmappedshapeNrIschemecfgrR home_pathr rrCcdS)uResolve this source's secrets. MUST NOT raise or prompt. ``cfg`` is the source's raw config section (``secrets.``) from config.yaml — treat every field defensively, the section may be malformed. ``home_path`` is the resolved HERMES_HOME. NrA)rPrarbs rfetchzSecretSource.fetchsrrMcptt|to|dS)z'Whether the user turned this source on.enabledrM isinstancerRr&rPras r is_enabledzSecretSource.is_enableds+JsD))@cggi.@.@AAArcrtt|to|ddS)uMay this source overwrite vars that .env / the shell already set? This NEVER extends to vars claimed by another secret source in the same startup pass — cross-source overrides are a config error the orchestrator warns about, not a knob. override_existingFrgris rrlzSecretSource.override_existings0JsD))Qcgg6I5.Q.QRRRrFrozenSet[str]ctS)aEnv vars the orchestrator must never let ANY source overwrite. Typically the source's own bootstrap-auth var (e.g. ``BWS_ACCESS_TOKEN``) so a vault that contains its own access token can't clobber the credential used to reach it. ) frozensetris rprotected_env_varszSecretSource.protected_env_varss{{rfloatc t|pidt}n#ttf$r tcYSwxYw|dkr|ntS)z;Wall-clock budget the orchestrator enforces around fetch().timeout_secondsr)rqr&DEFAULT_FETCH_TIMEOUT_SECONDS TypeError ValueError)rPravals rfetch_timeout_secondsz"SecretSource.fetch_timeout_secondssi 1(9;XYYZZCC:& 1 1 10 0 0 0 1Aggss#@@s*-AAciS)zOptional description of this source's config keys. Shape: ``{key: {"description": str, "default": Any}}``. Used by setup surfaces to render config without hardcoding per-source knowledge. Purely informational. rArOs r config_schemazSecretSource.config_schemas  rkindOptional['ErrorKind']c$tjd|jdtjd|jdtjd|jdtjd|jdtjdtjd|jd i}|||d nd S) u@One-line, actionable next step for a failed fetch. Called by the startup status printer (and ``hermes secrets ... status``) right after a fetch error is surfaced, so the user sees *what to run* next to fix it — not just what broke. Sources should override this to point at their own CLI verbs (e.g. ``hermes secrets bitwarden token`` for AUTH_FAILED). Return an empty string to suppress the hint. Must never raise and must not perform I/O — it's a pure kind→string mapping on the startup path. zRun `hermes secrets z setup` to finish configuration.z" setup` to install the helper CLI.u-Credentials rejected — run `hermes secrets z setup` to re-authenticate.u,Credentials expired — run `hermes secrets uNNetwork problem reaching the secrets backend — check connectivity and retry.u#Backend was slow — raise secrets.z .timeout_seconds if this recurs.NrZ) r*r8r\r9r:r;r=r?r&)rPr{ragenerics r remediationzSecretSource.remediations  $RtyRRR  $TtyTTT  !& &&&  "&ty&&&  *  "di""") 0)-(8w{{4$$$b@r)rarRrbr rrC)rarRrrM)rarRrrm)rarRrrq)rrR)r{r|rarRrr[)r4r5r6r7SECRET_SOURCE_API_VERSIONrYrSr\r]r_r`rrdrjrlrprxrzrrArrrWrWs41K0000DNNNNEOOOOE F       ^ BBBBSSSSAAAA%A%A%A%A%A%ArrWz^[A-Za-z_][A-Za-z0-9_]*$z<\x1b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?)r\r[rMcnt|o&tt|S)z8True when ``name`` is a legal environment-variable name.)rM _ENV_NAME_REmatch)r\s ris_valid_env_namer s) :: 8$|11$77888rtextc<td|pdS)zDStrip ANSI escape sequences (whole CSI/OSC sequences, not just ESC).rZ)_ANSI_REsub)rs r scrub_ansirs <<DJB ' ''rrA) allow_env extra_envr2argv Sequence[str]rrOptional[Dict[str, str]]r2rqsubprocess.CompletedProcessc d}i}g||RD](}tj|}||||<)|r|||dd t jt||dddd|t j}n#t j $rA} ttt|d j d |d d | d} ~ wt$r@} td tt|d j d| | d} ~ wwxYw|jpd|_t!|jpd|_|S)uRun a secret-manager helper CLI with a minimal, allowlisted env. Security posture shared by every subprocess-driven backend: * argv list only — never ``shell=True``. Callers pass user-supplied reference strings AFTER a ``--`` option terminator in their argv. * The child gets ``PATH``/``HOME``/locale basics plus only the env vars named in ``allow_env`` (auth/session vars) and ``extra_env`` — never a copy of the full post-dotenv ``os.environ``, which by this point holds every credential Hermes knows about. * ``NO_COLOR=1`` is set and stderr/stdout are ANSI-scrubbed so helper diagnostics can't smuggle escape sequences into Hermes output. * stdin is ``/dev/null`` so a helper that decides to prompt fails fast instead of hanging startup. Raises ``RuntimeError`` on spawn failure or timeout (message safe to surface); returns the completed process otherwise — callers own returncode interpretation. ) PATHHOME USERPROFILE SYSTEMROOTTMPDIRTEMPLANGLC_ALLXDG_CONFIG_HOME XDG_DATA_HOMENNO_COLOR1Tzutf-8replace)envcapture_outputrencodingerrorsr2stdinrz timed out after z.0fszfailed to invoke z: rZ)r'rr&update setdefault subprocessrunrTDEVNULLTimeoutExpired RuntimeErrorr r[r\OSErrorstdoutrstderr) rrrr2 base_keeprkeyrwprocexcs rrun_secret_clirs6GIC''Y''jnnS!! ?CH 9NN:s###~ JJ $      $CQLL!!& G G G G G G     @Sa\\ 2 2 7 @ @3 @ @    +#DKT[.B//DK Ks$#3BD/&rsw"""H#""""" ))))))))########((((((((LLLLLLLLLLLLLLLL CCCC j!CTRRR,,,, %%%%::::!&#T( """"""" "2zAzAzAzAzA3zAzAzADrz566  2:U V V9999 (((( "*.0 ::::::::r