Crate stellar_agent_toolsets_runtime 

Capability→tool matrix, gated resolver, and four-part enforcement for installed toolsets.

This crate is the toolset isolation boundary for the Stellar agent wallet. It provides:

• matrix::grants_for_capability — the static Capability → &[&'static str] UNGATED allowlist of trusted tool names a capability grants.
• GATED_MATRIX_ENTRIES — the SEPARATE gated tier for signing-adjacent capabilities.
• SIGNING_DENYLIST — the explicit by-name denylist of signing/key/policy tools that are NEVER grantable regardless of declared capabilities.
• ToolsetRuntimeError — closed-set typed refusal variants.
• check_toolset_action — the four-part enforcement function (ungated).
• resolve_toolset_sign_payment_gated — the GATED resolver entry point; a distinct entry point from resolve_toolset_and_check, NOT a route_to_matrix_tool arm.
• list_pinned_toolsets — enumerate installed toolsets + their declared actions.

Security guarantees

Signing isolation is STRUCTURAL: the ungated capability→tool matrix (matrix::grants_for_capability) contains no signing/key/policy tool regardless of any capability declaration. Even a toolset declaring every capability cannot reach a signing tool via the ungated path. This is the isolation boundary between the toolset guest code and the wallet’s signing infrastructure.

Gated signing path: stellar_pay_commit is reachable ONLY through resolve_toolset_sign_payment_gated, which requires BOTH:

1. The four-part check (toolset declared sign-payment; the gated action resolves; tool ∈ allowed_tools).
2. A current, matching first-invoke grant in the ToolsetGrantStore.

A DispatchOutcome::Allow from the policy engine is OVERRIDDEN to RequireApproval for all toolset-routed payments (unconditional per-action approval).

Primary consumers

The MCP server crate consumes stellar_toolset_list, stellar_toolset_invoke, and the gated stellar_toolset_invoke path routing to stellar_pay_commit. The CLI crate consumes toolset list and toolset run <name> <action>.

What this crate does NOT do

• Per-action attestation verification gate — performed by the consumer (CLI/MCP) layer, not this crate. This crate DOES build HMAC-attested grants via record_first_invoke_grant; the verification of those grants on each action invocation is the consumer’s responsibility.
• Dynamic tool registration — explicitly out of scope.

Re-exports

pub use error::ToolsetRuntimeError;

pub use matrix::GATED_MATRIX_ENTRIES;

pub use matrix::SIGN_PAYMENT_GATED_TOOLS;

pub use matrix::SIGNING_DENYLIST;

pub use matrix::gated_grants_for_capability;

pub use matrix::resolve_action;

Modules

error

Closed-set typed error variants for toolset capability enforcement.

matrix

Capability→tool matrix, gated capability→tool matrix, and explicit signing denylist.

Structs

GatedInvokeParams

Parameters for the gated toolset resolve + first-invoke gate check.

ToolsetListEntry

A single installed-toolset entry as returned by list_pinned_toolsets.

Enums

GatedResolveOutcome

Result of the gated toolset resolver.

Functions

check_toolset_action

Four-part enforcement check for a toolset action.

list_pinned_toolsets

Reads all pinned toolset installs from toolsets_root and returns their ToolsetListEntry records.

read_pin

Re-export stellar_agent_toolsets_install::read_pin as a crate-level convenience so MCP/CLI consumers can read pins without adding a direct dep on stellar-agent-toolsets-install. Reads and parses the pin record for package from toolsets_root.

record_first_invoke_grant

Records a confirmed first-invoke grant after the operator approves a ToolsetFirstInvokeGate pending approval.

resolve_gated_action

Resolves a gated action string to a (&'static str, Capability) pair via the CLOSED gated matrix lookup.

resolve_toolset_and_check

Resolves and validates a toolset from its pin record, then runs the four-part enforcement check.

resolve_toolset_sign_payment_gated

The GATED resolver for toolset-routed sign-payment invocations.

validate_package_name

Re-export stellar_agent_toolsets_install::validate_package_name so callers can pre-validate toolset names before calling resolve_toolset_and_check. Validates a package name against the [a-z0-9-] rule.

Type Aliases

GrantStorePathOverride

Optional override for the grant store path passed to record_first_invoke_grant.