NQj-TdZddlmZddlZddlZddlZddlmZmZddl m Z m Z ddl m Z ddlmZddlmZmZmZmZmZd Zd Zd ZGd d ee Ze GddZGddeZejdZejdZd&dZ d'dZ!ddedd(d%Z"dS))umSecret-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)ABCabstractmethod) dataclassfield)Enum)Path)Dict FrozenSetListOptionalSequenceg^@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_VALUETIMEOUTINTERNAL=/home/alina/.hermes/hermes-agent/agent/secret_sources/base.pyrr>sG&N%NK!LKGKGHHHr)rceZdZUdZeeZded<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_pathreturnboolc|jduS)N)r3selfs r*okzFetchResult.okgszT!!r))r6r7)rrrrrdictr.__annotations__listr/r0r1r3r4r5propertyr;r(r)r*r,r,Rs$eD999G9999t444G4444t444G4444%555H5555E&*J****#'K&&&& """X"""r)r,ceZdZUdZeZded<dZded<dZded<dZ ded <d Z d ed <e ddZ ddZ ddZddZddZd 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_versionstrnamelabelmappedshapeNr2schemecfgr< home_pathr r6r,cdS)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. Nr()r:rKrLs r*fetchzSecretSource.fetchsr)r7cptt|to|dS)z'Whether the user turned this source on.enabledr7 isinstancer<getr:rKs r* is_enabledzSecretSource.is_enableds+JsD))@cggi.@.@AAAr)crtt|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_existingFrQrTs r*rWzSecretSource.override_existings0JsD))Qcgg6I5.Q.QRRRr)FrozenSet[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. ) frozensetrTs r*protected_env_varszSecretSource.protected_env_varss{{r)floatc t|pidt}n#ttf$r tcYSwxYw|dkr|ntS)z;Wall-clock budget the orchestrator enforces around fetch().timeout_secondsr)r\rSDEFAULT_FETCH_TIMEOUT_SECONDS TypeError ValueError)r:rKvals r*fetch_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. r(r9s r* config_schemazSecretSource.config_schemas  r))rKr<rLr r6r,)rKr<r6r7)rKr<r6rX)rKr<r6r\)r6r<)rrrrSECRET_SOURCE_API_VERSIONrCr=rFrGrIrJrrNrUrWr[rcrer(r)r*rArAls41K0000DNNNNEOOOOE F       ^ BBBBSSSSAAAAr)rAz^[A-Za-z_][A-Za-z0-9_]*$z<\x1b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?)rFrEr6r7cnt|o&tt|S)z8True when ``name`` is a legal environment-variable name.)r7 _ENV_NAME_REmatch)rFs r*is_valid_env_namerjs) :: 8$|11$77888r)textc<td|pdS)zDStrip ANSI escape sequences (whole CSI/OSC sequences, not just ESC).rD)_ANSI_REsub)rks r* scrub_ansiros <<DJB ' ''r)r() allow_env extra_envrargv Sequence[str]rprqOptional[Dict[str, str]]rr\subprocess.CompletedProcessc d}i}g||RD](}tj|}||||<)|r|||dd t jt||dd|t j}n#t j $rA} ttt|dj d|d d | d} ~ wt$r@} td tt|dj 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_COLOR1T)envcapture_outputrkrstdinrz timed out after z.0fszfailed to invoke z: rD)osenvironrSupdate setdefault subprocessrunr>DEVNULLTimeoutExpired RuntimeErrorr rErFOSErrorstdoutrostderr) rrrprqr base_keeprkeyrbprocexcs r*run_secret_clirs6GIC''Y''jnnS!! ?CH 9NN:s###~ JJ$      $CQLL!!& G G G G G G     @Sa\\ 2 2 7 @ @3 @ @    +#DKT[.B//DK Ks$#1BD-$rs""H#""""" ########((((((((<<<<<<<<<<<<<<  !&#T( """"""" "2SSSSS3SSSvrz566  2:U V V9999 (((( "*.0 ::::::::r)