sjT9 *UdZddlmZddlZddlZddlmZddlmZmZddl m Z m Z m Z m Z mZmZmZejeZedGd d Zd ed d dedddedddedddedddedddedd d!fDZd"ed#<eeZd$Zd%ZdJdKd-ZdLd0ZdMdNd5Z dMdOd7ZdPd<Z dMdQd>Z dRdBZ!dSdEZ"dMdTdGZ# dMdUdHZ$ dMdVdIZ%dS)WuK Plugin capability declarations + consent state (#64228). Unifies the scattered per-plugin trust gates (``plugins.entries..allow_*``) into one declared, diffable **capability model** with install/update-time consent. **This is NOT a sandbox.** In-process Python plugins remain trusted code — a malicious plugin can import anything, monkey-patch core, and ignore all of this. Capabilities govern the *host API surfaces* Hermes hands out (which registrations succeed, which ``ctx`` methods are live) and give the user an honest consent + audit trail. Actual isolation is a separate research track. Canonical registry ------------------ Every capability id maps 1:1 to a trust gate that **already exists** on the enforcing surface. We deliberately do not mint capability ids without an enforcing gate: =========================== ================================================== Capability id Legacy config gate (``plugins.entries..…``) =========================== ================================================== ``tools.override`` ``allow_tool_override`` ``llm.provider_override`` ``llm.allow_provider_override`` ``llm.model_override`` ``llm.allow_model_override`` ``llm.agent_id_override`` ``llm.allow_agent_id_override`` ``llm.profile_override`` ``llm.allow_profile_override`` ``llm.task_override`` ``llm.allow_task_override`` ``gateway.platform_actions`` ``allow_platform_actions`` =========================== ================================================== The legacy ``allow_*`` keys keep working verbatim (deprecated but honored): a gate is open when the legacy key is true **or** the capability is granted. Consent state ------------- Stored under the plugin's config entry:: plugins: entries: : granted_capabilities: [tools.override] capabilities_consent: hash: "" granted_at: "2026-08-12T00:00:00+00:00" The hash records *what the user saw* when they consented. When an update declares capabilities whose set hash differs, the additions stay ungranted until the user re-consents (``hermes plugins update`` surfaces the diff). Ground rule: everything defaults OFF. Any failure to read consent state (missing config, corrupt YAML, wrong types) means **not granted**. ) annotationsN) dataclass)datetimetimezone)AnyDictIterableListMappingOptionalTupleT)frozenc2eZdZUdZded<ded<ded<dS)CapabilitySpecz9One declarable capability and the legacy gate it maps to.stridzTuple[str, ...] legacy_path descriptionN)__name__ __module__ __qualname____doc____annotations__B/home/agent/.hermes/hermes-agent/hermes_cli/plugin_capabilities.pyrrAs;CC GGG!   rrci|] }|j| Sr)r).0specs r r Ns,626262  GT626262rztools.override)allow_tool_overrideuvReplace built-in tools (e.g. shell_exec, write_file) — an override can intercept everything routed through that tool)rrrzllm.provider_override)llmallow_provider_overridez^Run host-owned LLM calls against a provider other than your active one (uses your credentials)zllm.model_override)r"allow_model_overridezLChoose which model host-owned LLM calls use (spend follows the chosen model)zllm.agent_id_override)r"allow_agent_id_overridez/Attribute its LLM calls to a different agent idzllm.profile_override)r"allow_profile_overridez,Run LLM calls under a different auth profilezllm.task_override)r"allow_task_overridezDRoute its LLM calls through the host's built-in auxiliary task laneszgateway.platform_actions)allow_platform_actionszkAct on connected chat platforms as the gateway bot (add reactions, rename threads) via ctx.platform_actionszDict[str, CapabilitySpec]CAPABILITY_REGISTRYgranted_capabilitiescapabilities_consent?rawr plugin_namerreturn List[str]c  |sgSt|ttfs0td|t |jgSg}|D]}t|tstd||4|}|tvr||vr| |ktd||d tt|S)ujNormalize a manifest ``capabilities:`` value into known capability ids. Unknown ids are dropped with a warning (forward compat: a plugin built for a newer Hermes may declare ids this build doesn't know; they can never be granted here, so hiding them from the consent screen is the fail-closed choice — the plugin must degrade gracefully). uFPlugin %s: manifest 'capabilities' must be a list, got %s — ignoringz2Plugin %s: ignoring non-string capability entry %ru9Plugin %s: unknown capability %r (known: %s) — ignoringz, ) isinstancelisttupleloggerwarningtyperrstripVALID_CAPABILITY_IDSappendjoinsorted)r-r.outitemcaps rparse_declared_capabilitiesr@s  cD%= ) ) T c+    C$$$  NNDT    jjll & & &#~~ 3 NNKS$))F3G,H,H"I"I     Jr capabilities Iterable[str]cdtt|}tj|dS)z?Deterministic sha256 over a capability set (order-insensitive). zutf-8)r;r<sethashlibsha256encode hexdigest)rAcanons rcapability_set_hashrKsK IIfS..// 0 0E >%,,w// 0 0 : : < <`` or ``{}`` — never raises.Nr) load_configpluginsentries)hermes_cli.configrQgetr2rO Exception)rLrMcfgrQrSentrys r _plugin_entryrYs  ; 5 5 5 5 5 5+--%2C779%%+00;;Ar I&&,""5$//7uuR7  sA1A44 BB frozensetct||}|t}t|tst St d|DS)zReturn the set of capabilities the user has granted this plugin. Fail-closed: missing/corrupt state yields the empty set. c3K|]H}t|tr1|tv2|VIdSN)r2rr8r9rcs r z'granted_capabilities..s\ a  "#''))/C"C"C  "C"C"C"Cr)rYrU GRANTED_KEYr2r3rZ)rLrMrXr-s rr*r*sn )V , ,E ))K C c4 {{   rrXMapping[str, Any]rboolc|}|jD]/}t|tsdS||}0t |o|duS)z>True when the deprecated ``allow_*`` key for *spec* is truthy.FN)rr2r rUrc)rXrnodeparts r_legacy_gate_setrgsYD $(( 55xx~~ :: *$d**r capabilityc t|}|td||dSt ||}|t |dd||iiivrt ||dddSt||r3t ||dd |d d |j d dSt ||dd dS) aCanonical check: is *capability* live for *plugin_id*? True when EITHER: * the capability appears in ``granted_capabilities`` (consent flow), OR * the legacy ``allow_*`` config key is set (deprecated, still honored so existing configs keep working). Unknown capability ids and any failure to read state return ``False`` (ground rule 4: fail closed). Nu9capability check for unknown id %r (plugin %s) — deniedFrRrS)rMTr*zlegacy key plugins.entries..z (deprecated)z not granted) r)rUr5debugrYr*_log_capability_decisionrgr;r)rLrhrMrrXs rplugin_capability_grantedrms  " ": . .D | G     u )V , ,E))YU^`eTfHgTUUUtt$$ z4 _) _ _chht?O6P6P _ _ _   tY E=III 5rallowedevidenceNonecJtd|||rdnd|dS)zDAudit line for capability gate decisions (the ``checked_by`` trail).zecapability_check plugin=%s capability=%s decision=%s checked_by=plugin_capability_granted evidence=%sallowdenyN)r5info)rLrhrnros rrlrls9 KKo:'=wwvxrgranteddeclaredcTddlm}m}dt|D}dt|D}|}|di}t |tsi}||d<|di} t | tsi} | |d<| |i} t | tsi} | | |<| t} t | trt| ng} |D]} | | vr| | tdt| D| t<t|tjtjd d | t$<| tD]g} t&| }| }|jd d D]6}||i}t |tsi}|||<|}7d ||jd <h||t*d|d| tpd| t$dd dd S)uvPersist a consent decision for *plugin_id*. Writes ``granted_capabilities`` (union with any previously granted set), the consent record (hash of the *declared* set the user saw + UTC timestamp), and — so every existing enforcement site keeps working without changes — the corresponding legacy ``allow_*`` keys for each newly granted capability. r)rQ save_configc$g|] }|tv |Srr9r^s r z"record_consent..+s#SSS!>R9R9RA9R9R9Rrc$g|] }|tv |Srrzr^s rr{z"record_consent..,#UUU11@T;T;TQ;T;T;TrrRrSc3VK|]$}t|tr |tv |V%dSr])r2rr9r^s rr`z!record_consent..AsL   a   "#';";"; ";";";";  rseconds)timespec)hash granted_atNTz8capability_consent plugin=%s granted=%s declared_hash=%s,z(none)r )rTrQrxrOfromkeys setdefaultr2rUrar3r:r<rKrnowrutc isoformat CONSENT_KEYr)rr5rtr;)rLrurvrQrx granted_list declared_listrM plugins_cfgrSrXpreviousmergedr?rrerfchilds rrecord_consentrs;:::::::SSt}}W55SSSLUU h 7 7UUUM []]F##Ir22K k4 ( (( 'y$$Y33G gt $ $)!( I   y" - -E eT " "#" yy%%H)(D99 AT(^^^rF f   MM#     ==((   E+ $M22l8<00::I:NNE+[! * *"3'$SbS)  DOOD"--EeT** #"T DD%)T b !""K KKB388E+.//;8 k6"3B3'r Optional[str]ct||}|t}t|tsdS|d}t|t r|r|ndS)z.vr}rcg|]}|v| Srr)rr_rus rr{z(pending_capabilities..xs# 9 9 9!(8(8A(8(8(8r)rOrr*)rLrvrMrrus @rpending_capabilitiesrisNVU h 7 7UUUM"9f55G 9 9 9 9} 9 9 99rcdt||}|dS|td|DkS)zTrue when the declared set differs from what the user consented to. No stored consent at all counts as changed (never consented). NTc3,K|]}|tv |VdSr]rzr^s rr`z'declared_set_changed..s6))q$8888888))r)rrK)rLrvrMstoreds rdeclared_set_changedr{sS)V , ,F ~t ())))) r)r,)r-rr.rr/r0)rArBr/rr])rLrrMrNr/rO)rLrrMrNr/rZ)rXrbrrr/rc)rLrrhrrMrNr/rc) rLrrhrrnrcrorr/rp)rLrrurBrvrBr/rp)rLrrMrNr/r)rLrrvrBrMrNr/r0)rLrrvrBrMrNr/rc)&r __future__rrFlogging dataclassesrrrtypingrrr r r r r getLoggerrr5rr)rrZr9rarr@rKrYr*rgrmrlrrrrrrrrsN333j#"""""!!!!!!''''''''FFFFFFFFFFFFFFFFFF  8 $ $ $6262 0M     &:5     #7$     &:I   %9F   "6     )3K    W36262626666p!y!455% $ !!!!!H====      ;?"+++++/"""""J@@@@F33333+/:::::*+/r