{ "name": "forge-auth", "language": "rust", "version": "0.2.0", "description": "Arsenal capability token integration for Forge agents \u2014 ANVIL Spec \u00a78.7, \u00a711.3", "manifest": "forge-rs/crates/forge-auth/Cargo.toml", "manifestSha256": "4e029538eeccd6254d775b2034b2f9fd72caa45a449f5d6c30d3900087d7382b", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/rust/forge-auth", "features": {}, "files": [ { "path": "forge-rs/crates/forge-auth/src/auth_context.rs", "sha256": "d85cda354c1529833855e97796a70baf41ba0fcf669551974d34a5aeb1d84c4c", "artifactSha256": "123b0b289f26522a5052564386f236d6d375a3128cc41a85aed4fb226ed3f03d", "url": "/reference/source/forge-rs/crates/forge-auth/src/auth_context.rs.txt", "declarations": [ { "name": "::AuthContext", "line": 87, "signature": "pub struct AuthContext {\n\n}", "documentation": "An identity-aware authorization context for a Forge agent.\n\nCombines the agent's cryptographic identity ([`ForgeAgentIdentity`]) with\nits Arsenal capability token ([`AgentCapabilityToken`]) to provide a unified\ninterface for identity-aware authorization.\n\n# Security\n\n- The private key is accessible only through the identity's signing methods.\n- The Debug implementation redacts the private key.\n- All authorization checks go through the ACT.\n\n# ANVIL Spec \u00a78.7, \u00a711.1\n\n# Examples\n\n```no_run\nuse forge_auth::auth_context::AuthContext;\nuse forge_identity::lineage::create_hmr_identity;\nuse forge_auth::local_capability::LocalCapabilityFactory;\n\nlet hmr = create_hmr_identity(\"test\", \"example\").unwrap();\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\nlet act = factory.create_dev_token(hmr.did());\n\nlet ctx = AuthContext::new(hmr, act);\nassert!(ctx.identity().lineage_depth() == 0);\n```" }, { "name": "::AuthContext::new", "line": 132, "signature": "pub fn new(identity: ForgeAgentIdentity, act: AgentCapabilityToken) -> Self;", "documentation": "Creates a new `AuthContext` from an identity and capability token.\n\n# Arguments\n\n* `identity` - The agent's OAS identity.\n* `act` - The agent's Arsenal capability token.\n\n# Returns\n\nA new `AuthContext`.\n\n# Examples\n\n```no_run\nuse forge_auth::auth_context::AuthContext;\nuse forge_identity::lineage::create_hmr_identity;\nuse forge_auth::local_capability::LocalCapabilityFactory;\n\nlet hmr = create_hmr_identity(\"test\", \"new-ctx\").unwrap();\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\nlet act = factory.create_dev_token(hmr.did());\nlet ctx = AuthContext::new(hmr, act);\n```" }, { "name": "::AuthContext::agent_did", "line": 157, "signature": "pub fn agent_did(&self) -> &str;", "documentation": "Returns the agent's OAS DID.\n\n# Examples\n\n```no_run\n# use forge_auth::auth_context::AuthContext;\n# use forge_identity::lineage::create_hmr_identity;\n# use forge_auth::local_capability::LocalCapabilityFactory;\n# let hmr = create_hmr_identity(\"test\", \"did-demo\").unwrap();\n# let factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\n# let act = factory.create_dev_token(hmr.did());\n# let ctx = AuthContext::new(hmr, act);\nassert!(ctx.agent_did().starts_with(\"did:oas:\"));\n```" }, { "name": "::AuthContext::identity", "line": 162, "signature": "pub fn identity(&self) -> &ForgeAgentIdentity;", "documentation": "Returns a reference to the agent's identity." }, { "name": "::AuthContext::act", "line": 167, "signature": "pub fn act(&self) -> &AgentCapabilityToken;", "documentation": "Returns a reference to the agent's capability token." }, { "name": "::AuthContext::lineage_depth", "line": 172, "signature": "pub fn lineage_depth(&self) -> u32;", "documentation": "Returns the agent's lineage depth." }, { "name": "::AuthContext::sign", "line": 187, "signature": "pub fn sign(&self, message: &[u8]) -> Vec;", "documentation": "Signs a message with the agent's Ed25519 key.\n\nUseful for signing audit trail entries.\n\n# Arguments\n\n* `message` - The raw bytes to sign.\n\n# Returns\n\nA 64-byte Ed25519 signature." }, { "name": "::AuthContext::authorize_tool", "line": 211, "signature": "#[instrument(skip(self), fields(agent_did = %self.identity.did(), tool = %tool_name, tier = %tool_tier))]\npub fn authorize_tool(\n &self,\n tool_name: &str,\n tool_tier: ToolTier,\n ) -> ForgeAuthResult;", "documentation": "Authorizes a tool invocation against the agent's ACT.\n\nThis is the primary tool authorization method. It checks the tool's\ntier and verifies the ACT scope if required.\n\n# Arguments\n\n* `tool_name` - The name of the tool being invoked.\n* `tool_tier` - The tool's classification tier.\n\n# Returns\n\nA [`ToolAuthorizationDecision`] indicating whether the invocation is allowed.\n\n# Errors\n\nPropagates errors from ACT verification (expired, invalid).\n\n# ANVIL Spec \u00a78.7" }, { "name": "::AuthContext::authorize_proxy_tool", "line": 243, "signature": "#[instrument(skip(self, variables), fields(agent_did = %self.identity.did(), tool = %tool_name))]\npub fn authorize_proxy_tool(\n &self,\n tool_name: &str,\n tool_tier: ToolTier,\n variables: &[String],\n ) -> ForgeAuthResult;", "documentation": "Authorizes a tool invocation that uses proxy template variables.\n\nChecks both the tool scope and proxy variable scopes.\n\n# Arguments\n\n* `tool_name` - The name of the tool being invoked.\n* `tool_tier` - The tool's classification tier.\n* `variables` - The template variable names used by the tool.\n\n# Returns\n\nA [`ToolAuthorizationDecision`].\n\n# Errors\n\nPropagates errors from ACT verification." }, { "name": "::AuthContext::create_authorized_subagent", "line": 284, "signature": "#[instrument(skip(self, requested_scopes), fields(parent_did = %self.identity.did(), child_name = %name))]\npub fn create_authorized_subagent(\n &self,\n name: &str,\n namespace: &str,\n requested_scopes: ScopeSet,\n ) -> ForgeAuthResult;", "documentation": "Creates an authorized sub-agent with derived identity and narrowed capabilities.\n\nThis is the single entry point for sub-agent creation per ANVIL Spec \u00a711.2\u201311.3.\nIt performs:\n1. Identity derivation (HKDF-SHA256) from the parent.\n2. Capability delegation with scope narrowing.\n3. Validation that child scopes are a subset of parent scopes.\n\n# Arguments\n\n* `name` - The sub-agent's identifier (e.g., `\"analyzer\"`, `\"scraper\"`).\n* `namespace` - The sub-agent's OAS namespace.\n* `requested_scopes` - The scopes requested for the child (must be a subset of parent).\n\n# Returns\n\nA new [`AuthContext`] for the sub-agent with derived identity and narrowed capabilities.\n\n# Errors\n\n- [`ForgeAuthError::CapabilityEscalation`] \u2014 if requested scopes exceed parent.\n- [`ForgeAuthError::DelegationDenied`] \u2014 if delegation constraints prevent creation.\n- Propagated identity errors via [`ForgeAuthError::IdentityError`].\n\n# ANVIL Spec \u00a711.2, \u00a711.3" } ] }, { "path": "forge-rs/crates/forge-auth/src/capability.rs", "sha256": "743cd09d7ddcae1e3ceef9bfa505b2c255bf24876de9c9fc6dd37e543fd0789d", "artifactSha256": "77f6e39de7f5329e30e277013bd6c64f768848427356467a20eb656d9e302576", "url": "/reference/source/forge-rs/crates/forge-auth/src/capability.rs.txt", "declarations": [ { "name": "::verify_act", "line": 88, "signature": "#[instrument(skip(act), fields(token_id = %act.id(), agent_id = %act.subject()))]\npub fn verify_act(act: &AgentCapabilityToken) -> ForgeAuthResult<()>;", "documentation": "Verifies that an Arsenal ACT is structurally valid and time-valid.\n\n# Security\n\n**This function does NOT verify the cryptographic signature on the token.\nIt only checks:\n\n1. **Structural validation** \u2014 non-empty scopes, valid TTL bounds, well-formed\n fields (via `AgentCapabilityToken::validate_structure`).\n2. **Time validity** \u2014 token not expired and `nbf` (not-before) has passed.\n\nCryptographic signature verification is the responsibility of the Arsenal\ncrypto layer and **must** be performed separately before any decision is\nmade to honor the ACT. Without that signature check, a forged or tampered\ntoken can satisfy this function and still be invalid -- callers that treat\n`verify_act -> Ok(())` as \"this token is authentic\" are creating a silent\nsecurity gap.\n\nThe lower-level alias [`decode_and_check_ttl`] points at this same routine\nand exists so call sites that only want the structure-and-TTL gate can\nspell that out explicitly. Production-grade callers should pair this with\nthe Arsenal verifier before honoring any scope decision.\n\n# Arguments\n\n* `act` - The Arsenal ACT to verify.\n\n# Returns\n\n`Ok(())` if the token is valid.\n\n# Errors\n\n- [`ForgeAuthError::TokenExpired`] \u2014 if the token's expiration time has passed.\n- [`ForgeAuthError::InvalidToken`] \u2014 if the token fails structural validation.\n\n# ANVIL Spec \u00a78.7.1\n\nEvery tool invocation path must verify the ACT before checking scopes.\n\n# Examples\n\n```no_run\n# use arsenal_core::token::AgentCapabilityToken;\nuse forge_auth::capability::verify_act;\n# fn example(act: &AgentCapabilityToken) -> forge_auth::error::ForgeAuthResult<()> {\nverify_act(act)?;\n// Token is valid \u2014 proceed with scope checks\n# Ok(())\n# }\n```" }, { "name": "::decode_and_check_ttl", "line": 141, "signature": "pub fn decode_and_check_ttl(act: &AgentCapabilityToken) -> ForgeAuthResult<()>;", "documentation": "Alias for [`verify_act`] that names what it actually does.\n\n`verify_act` verifies the token's structure and TTL but does NOT verify\nthe cryptographic signature -- callers reading code that says\n`verify_act(&token)?` often assume signature verification happened.\n`decode_and_check_ttl` is the same routine spelled out so the security\nposture is obvious at the call site.\n\nPair this with the Arsenal verifier before honoring any scope decision.\n\n# Examples\n\n```no_run\n# use arsenal_core::token::AgentCapabilityToken;\nuse forge_auth::capability::decode_and_check_ttl;\n# fn example(act: &AgentCapabilityToken) -> forge_auth::error::ForgeAuthResult<()> {\ndecode_and_check_ttl(act)?;\n// Token is structurally valid and not expired.\n// Signature verification still required before honoring scopes.\n# Ok(())\n# }\n```" }, { "name": "::extract_scopes", "line": 174, "signature": "pub fn extract_scopes(act: &AgentCapabilityToken) -> Vec;", "documentation": "Extracts all granted scope strings from an Arsenal ACT.\n\nReturns the scopes as a vector of `String` values in the\n`\"service:resource:action\"` format. The order is deterministic\n(sorted lexicographically, since `ScopeSet` uses `BTreeSet`).\n\nThis function does **not** validate the token. Call [`verify_act`] first\nto ensure the token is valid before relying on its scopes.\n\n# Arguments\n\n* `act` - The Arsenal ACT from which to extract scopes.\n\n# Returns\n\nA `Vec` of scope strings.\n\n# Examples\n\n```no_run\n# use arsenal_core::token::AgentCapabilityToken;\nuse forge_auth::capability::extract_scopes;\n# fn example(act: &AgentCapabilityToken) {\nlet scopes = extract_scopes(act);\nfor scope in &scopes {\n println!(\"Granted: {scope}\");\n}\n# }\n```" }, { "name": "::act_allows_scope", "line": 218, "signature": "#[instrument(skip(act), fields(token_id = %act.id(), scope = %scope))]\npub fn act_allows_scope(act: &AgentCapabilityToken, scope: &str) -> ForgeAuthResult;", "documentation": "Checks whether an Arsenal ACT grants a specific scope.\n\nThis function first verifies the token is valid (not expired, structurally\nsound), then checks if any of the token's granted scopes imply the\nrequested scope. Wildcard scopes (e.g., `\"forge:*:*\"`) will match\nspecific scopes (e.g., `\"forge:tool.search:execute\"`).\n\n# Arguments\n\n* `act` - The Arsenal ACT to check.\n* `scope` - The scope string to check in `\"service:resource:action\"` format.\n\n# Returns\n\n`Ok(true)` if the scope is granted, `Ok(false)` if not.\n\n# Errors\n\n- [`ForgeAuthError::TokenExpired`] \u2014 if the token has expired.\n- [`ForgeAuthError::InvalidToken`] \u2014 if the token is structurally invalid.\n- [`ForgeAuthError::InvalidToken`] \u2014 if the requested scope string is malformed.\n\n# ANVIL Spec \u00a78.7.2\n\nScope checking uses the Arsenal `Scope::implies` semantics, which support\nwildcard matching at each component position.\n\n# Examples\n\n```no_run\n# use arsenal_core::token::AgentCapabilityToken;\nuse forge_auth::capability::act_allows_scope;\n# fn example(act: &AgentCapabilityToken) -> forge_auth::error::ForgeAuthResult<()> {\nif act_allows_scope(act, \"forge:tool.web_search:execute\")? {\n println!(\"Web search tool is authorized\");\n}\n# Ok(())\n# }\n```" }, { "name": "::act_allows_proxy_variable", "line": 257, "signature": "#[instrument(skip(act), fields(token_id = %act.id(), variable = %variable))]\npub fn act_allows_proxy_variable(\n act: &AgentCapabilityToken,\n variable: &str,\n) -> ForgeAuthResult;", "documentation": "Checks whether an Arsenal ACT grants proxy access for a specific variable.\n\nThe proxy scope format is `\"proxy::use\"`. If the exact scope\nis not present, the function also checks for the wildcard scope `\"proxy:*:*\"`.\n\n# Arguments\n\n* `act` - The Arsenal ACT to check.\n* `variable` - The variable name to check proxy access for.\n\n# Returns\n\n`Ok(true)` if proxy access is granted, `Ok(false)` if not.\n\n# Errors\n\n- [`ForgeAuthError::TokenExpired`] \u2014 if the token has expired.\n- [`ForgeAuthError::InvalidToken`] \u2014 if the token is structurally invalid." } ] }, { "path": "forge-rs/crates/forge-auth/src/delegation.rs", "sha256": "b38368961e974545debd611ddd2da787ca8f9aba60248f9cdb70525330971d00", "artifactSha256": "ce7f717a1593a9368996c98cc62416a17b716e99d790ecb584dc90fecab37187", "url": "/reference/source/forge-rs/crates/forge-auth/src/delegation.rs.txt", "declarations": [ { "name": "::DelegationRequest", "line": 60, "signature": "#[derive(Debug)]\npub struct DelegationRequest<'a> {\n/// The parent agent's Arsenal ACT.\n\npub parent_act: &'a AgentCapabilityToken,\n/// The parent agent's OAS DID (for error messages).\n\npub parent_did: String,\n/// The child agent's Arsenal identity.\n\npub child_agent_id: AgentId,\n/// The child agent's OAS DID (for error messages).\n\npub child_did: String,\n/// The scopes requested for the child agent.\n\n///\n\n/// Must be a subset of the parent's scopes.\n\npub requested_scopes: ScopeSet\n}", "documentation": "A request to delegate capabilities from a parent agent to a child agent.\n\n# ANVIL Spec \u00a711.3\n\nThe delegation request captures all information needed to create a\nchild ACT with narrowed capabilities." }, { "name": "::delegate_capabilities", "line": 135, "signature": "#[instrument(\n skip(request),\n fields(\n parent_did = %request.parent_did,\n child_did = %request.child_did,\n requested_scope_count = request.requested_scopes.len()\n )\n)]\npub fn delegate_capabilities(\n request: &DelegationRequest<'_>,\n) -> ForgeAuthResult;", "documentation": "Delegates capabilities from a parent agent to a child agent.\n\nThis function enforces all delegation constraints defined in ANVIL Spec \u00a711.3:\n\n1. **Parent ACT validity** \u2014 The parent's token must be valid (not expired,\n structurally sound).\n2. **Scope narrowing** \u2014 The requested child scopes must be a subset of\n the parent's scopes. Any scope in `requested_scopes` that is not implied\n by the parent's scopes triggers a [`ForgeAuthError::CapabilityEscalation`].\n3. **Delegation permission** \u2014 The parent's ACT must have delegation\n constraints that allow delegation (if present).\n4. **Delegate identity** \u2014 The parent's delegation constraints must allow\n delegation to the specific child agent (or to any agent).\n5. **TTL reduction** \u2014 The child's TTL is computed as the parent's remaining\n TTL minus `min_ttl_reduction` (default: 60 seconds). If the parent's\n remaining TTL is too short, delegation is denied.\n\nOn success, returns a new **unsigned** [`AgentCapabilityToken`] for the child\nagent. The caller is responsible for signing the token via the Arsenal\ncrypto layer.\n\n# Arguments\n\n* `request` - The delegation request.\n\n# Returns\n\nA new unsigned `AgentCapabilityToken` for the child agent.\n\n# Errors\n\n- [`ForgeAuthError::TokenExpired`] \u2014 parent ACT has expired.\n- [`ForgeAuthError::InvalidToken`] \u2014 parent ACT is structurally invalid.\n- [`ForgeAuthError::CapabilityEscalation`] \u2014 child requests scope not in parent.\n- [`ForgeAuthError::DelegationDenied`] \u2014 delegation constraints prevent delegation.\n\n# ANVIL Spec \u00a711.3\n\n# Examples\n\n```no_run\n# use arsenal_core::identity::AgentId;\n# use arsenal_core::scope::{Scope, ScopeSet};\n# use arsenal_core::token::AgentCapabilityToken;\nuse forge_auth::delegation::{DelegationRequest, delegate_capabilities};\n\n# fn example(parent_act: &AgentCapabilityToken) -> forge_auth::error::ForgeAuthResult<()> {\nlet mut child_scopes = ScopeSet::new();\n// Request a subset of parent's scopes\n# Ok(())\n# }\n```" } ] }, { "path": "forge-rs/crates/forge-auth/src/error.rs", "sha256": "8b29405122d0fe1f244f03058f6f25a16ad4af73a9396cf99a3bf36754b758fa", "artifactSha256": "e0005f8c6d31ead412f4c5e57256de85c850c4698c1ae5a262a9ae54e8e2d54c", "url": "/reference/source/forge-rs/crates/forge-auth/src/error.rs.txt", "declarations": [ { "name": "::ForgeAuthResult", "line": 15, "signature": "pub type ForgeAuthResult = Result;", "documentation": "Result type alias for `forge-auth` operations." }, { "name": "::ForgeAuthError", "line": 31, "signature": "#[derive(Debug, thiserror::Error)]\npub enum ForgeAuthError {\n /// The Arsenal ACT has expired and is no longer valid.\n ///\n /// Agents must obtain a fresh token before retrying the operation.\n ///\n /// # ANVIL Spec \u00a78.7.1\n #[error(\n \"ACT '{token_id}' for agent '{agent_did}' expired at {expired_at} \u2014 obtain a fresh token\"\n )]\n TokenExpired {\n /// The unique identifier of the expired token.\n token_id: String,\n /// The DID of the agent that presented the token.\n agent_did: String,\n /// The timestamp at which the token expired (ISO 8601).\n expired_at: String,\n },\n\n /// The agent's ACT does not grant the required scope for the operation.\n ///\n /// The agent must obtain a token with the missing capability, or the\n /// operation must be re-scoped to match the agent's granted permissions.\n ///\n /// # ANVIL Spec \u00a78.7.2\n #[error(\n \"agent '{agent_did}' lacks required scope '{required_scope}' \u2014 available scopes: {available_scopes:?}\"\n )]\n InsufficientScope {\n /// The DID of the agent whose token was checked.\n agent_did: String,\n /// The scope string that was required but not granted.\n required_scope: String,\n /// The scopes that the agent's ACT actually grants.\n available_scopes: Vec,\n },\n\n /// A sub-agent delegation attempted to grant capabilities exceeding the parent's scope.\n ///\n /// Child agent capabilities must be a strict subset of the parent's. This is\n /// a security invariant that prevents privilege escalation via delegation.\n ///\n /// # ANVIL Spec \u00a711.3.1\n #[error(\n \"capability escalation denied: child '{child_did}' requested scope '{requested}' but parent '{parent_did}' only grants {available:?}\"\n )]\n CapabilityEscalation {\n /// The DID of the parent agent whose ACT was being delegated.\n parent_did: String,\n /// The DID of the child agent that would receive the delegation.\n child_did: String,\n /// The scope string that was requested but exceeds the parent's grant.\n requested: String,\n /// The scopes available in the parent's ACT.\n available: Vec,\n },\n\n /// Delegation was denied due to constraint violations in the parent's ACT.\n ///\n /// This covers cases where the parent's token does not permit delegation at all,\n /// or the target agent is not in the allowed delegates list, or the delegation\n /// depth has been exceeded.\n ///\n /// # ANVIL Spec \u00a711.3.2\n #[error(\"delegation from parent '{parent_did}' to child '{child_did}' denied: {reason}\")]\n DelegationDenied {\n /// The DID of the parent agent attempting to delegate.\n parent_did: String,\n /// The DID of the intended child agent.\n child_did: String,\n /// Human-readable reason for the denial.\n reason: String,\n },\n\n /// The ACT is structurally invalid or malformed.\n ///\n /// This indicates the token could not be validated even before checking\n /// scopes or time validity. The token may be corrupted, incorrectly\n /// constructed, or tampered with.\n ///\n /// # ANVIL Spec \u00a78.7.3\n #[error(\"invalid Arsenal ACT: {reason}\")]\n InvalidToken {\n /// Human-readable explanation of why the token is invalid.\n reason: String,\n },\n\n /// An error propagated from the underlying Arsenal SDK.\n ///\n /// This wraps errors from `arsenal-core` operations that do not map\n /// cleanly to a Forge-specific authorization error. Boxed to keep\n /// the overall enum size small.\n #[error(\"arsenal error: {0}\")]\n Arsenal(Box),\n\n /// A proxy request was denied due to insufficient proxy scopes.\n #[error(\n \"proxy access denied for variable '{variable}' \u2014 agent '{agent_did}' lacks proxy scope\"\n )]\n ProxyDenied {\n /// The DID of the agent.\n agent_did: String,\n /// The variable name that was denied.\n variable: String,\n },\n\n /// A proxy request requires consent that has not been granted.\n #[error(\"consent required for agent '{agent_did}' to access variable '{variable}'\")]\n ConsentRequired {\n /// The DID of the agent.\n agent_did: String,\n /// The variable name requiring consent.\n variable: String,\n },\n\n /// A fingerprint hash chain mismatch was detected.\n #[error(\"fingerprint mismatch for agent '{agent_did}' \u2014 possible key compromise\")]\n FingerprintMismatch {\n /// The DID of the agent with the mismatched fingerprint.\n agent_did: String,\n },\n\n /// An identity operation failed during an auth workflow.\n ///\n /// This wraps errors from `forge-identity` operations (derivation, lineage)\n /// that occur during identity-aware auth flows like sub-agent creation.\n ///\n /// # ANVIL Spec \u00a711.1\n #[error(\"identity error: {reason}\")]\n IdentityError {\n /// Human-readable description of the identity failure.\n reason: String,\n },\n}", "documentation": "Errors that can occur during Forge authorization operations.\n\nEach variant carries enough context for operators to diagnose the issue\nwithout access to internal state. Error messages never include private keys\nor raw token bytes.\n\n# ANVIL Spec Reference\n\n- `TokenExpired` \u2014 ANVIL Spec \u00a78.7.1: ACT time validity checks\n- `InsufficientScope` \u2014 ANVIL Spec \u00a78.7.2: scope matching on tool invocation\n- `CapabilityEscalation` \u2014 ANVIL Spec \u00a711.3.1: delegation scope narrowing enforcement\n- `DelegationDenied` \u2014 ANVIL Spec \u00a711.3.2: delegation constraint violations\n- `InvalidToken` \u2014 ANVIL Spec \u00a78.7.3: structural validation of ACTs" }, { "name": "::ForgeAuthError::is_expired", "line": 174, "signature": "#[must_use]\npub fn is_expired(&self) -> bool;", "documentation": "Returns `true` if the error is a token expiration." }, { "name": "::ForgeAuthError::is_insufficient_scope", "line": 180, "signature": "#[must_use]\npub fn is_insufficient_scope(&self) -> bool;", "documentation": "Returns `true` if the error is an insufficient scope." }, { "name": "::ForgeAuthError::is_capability_escalation", "line": 186, "signature": "#[must_use]\npub fn is_capability_escalation(&self) -> bool;", "documentation": "Returns `true` if the error is a capability escalation." }, { "name": "::ForgeAuthError::is_delegation_denied", "line": 192, "signature": "#[must_use]\npub fn is_delegation_denied(&self) -> bool;", "documentation": "Returns `true` if the error is a delegation denial." }, { "name": "::ForgeAuthError::is_invalid_token", "line": 198, "signature": "#[must_use]\npub fn is_invalid_token(&self) -> bool;", "documentation": "Returns `true` if the error indicates the token itself is malformed." }, { "name": "::ForgeAuthError::is_proxy_denied", "line": 204, "signature": "#[must_use]\npub fn is_proxy_denied(&self) -> bool;", "documentation": "Returns `true` if the error is a proxy denial." }, { "name": "::ForgeAuthError::is_consent_required", "line": 210, "signature": "#[must_use]\npub fn is_consent_required(&self) -> bool;", "documentation": "Returns `true` if the error requires consent." }, { "name": "::ForgeAuthError::is_fingerprint_mismatch", "line": 216, "signature": "#[must_use]\npub fn is_fingerprint_mismatch(&self) -> bool;", "documentation": "Returns `true` if the error is a fingerprint mismatch." }, { "name": "::ForgeAuthError::is_identity_error", "line": 222, "signature": "#[must_use]\npub fn is_identity_error(&self) -> bool;", "documentation": "Returns `true` if the error is an identity operation failure." }, { "name": "::ForgeAuthError::error_code", "line": 236, "signature": "#[must_use]\npub fn error_code(&self) -> &'static str;", "documentation": "Returns a short error code string suitable for telemetry and logging.\n\n# Returns\n\nA static string identifying the error category." } ] }, { "path": "forge-rs/crates/forge-auth/src/lib.rs", "sha256": "17773ed57c1688f8136da91cfe9d1c02f6182e6121dafcb3e914acfd9e2bbd4e", "artifactSha256": "82d431300eef4b940babec98d60650923d7fd4410209878c8855b268b6eb94cd", "url": "/reference/source/forge-rs/crates/forge-auth/src/lib.rs.txt", "declarations": [ { "name": "auth_context", "line": 98, "signature": "pub mod auth_context;", "documentation": "# forge-auth\n\nArsenal capability token integration for Forge agents.\n\nThis crate bridges the Forge agent runtime with the Arsenal authorization\nframework, providing:\n\n- **ACT verification** \u2014 Validate token structure and time validity\n- **Tool authorization** \u2014 Enforce three-tier tool authorization per ANVIL \u00a78.7\n- **Capability delegation** \u2014 Safely narrow scopes for sub-agents per ANVIL \u00a711.3\n- **Scope extraction** \u2014 Read granted capabilities from tokens\n\n# ANVIL Spec Reference\n\nThis crate implements requirements from the following ANVIL specification sections:\n- \u00a78.7 \u2014 Tool Authorization Gate (tool tier checks, scope matching)\n- \u00a711.3 \u2014 Capability Delegation (scope narrowing, escalation prevention)\n\n# Security Invariants\n\n1. **No capability escalation**: Child scopes are always a subset of parent scopes.\n2. **No `unsafe` code**: This crate uses `#![forbid(unsafe_code)]` at the workspace level.\n3. **No panicking**: All fallible operations return `Result`.\n4. **Actionable errors**: Every error includes agent DIDs, scope names, and reasons.\n\n# Architecture\n\n```text\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 forge-auth \u2502\n\u2502 \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 capability \u2502 \u2502 tool_auth \u2502 \u2502 delegation \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \u2502 verify_act \u2502 \u2502 authorize_ \u2502 \u2502 delegate_ \u2502 \u2502\n\u2502 \u2502 extract_ \u2502 \u2502 tool_ \u2502 \u2502 capabilities \u2502 \u2502\n\u2502 \u2502 scopes \u2502 \u2502 invocation \u2502 \u2502 \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 arsenal-core \u2502 \u2502\n\u2502 \u2502 (ACT, Scope, \u2502 \u2502\n\u2502 \u2502 Delegation) \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n# Examples\n\n## Tool Authorization (ANVIL \u00a78.7)\n\n```no_run\nuse forge_auth::prelude::*;\nuse forge_core::tool::ToolTier;\n# use arsenal_core::token::AgentCapabilityToken;\n\n# fn example(act: &AgentCapabilityToken) -> ForgeAuthResult<()> {\nlet request = ToolAuthorizationRequest {\n agent_did: \"did:oas:l1fe:agent:worker\".to_string(),\n tool_name: \"web_search\".to_string(),\n tool_tier: ToolTier::External,\n act: Some(act),\n};\nlet decision = authorize_tool_invocation(&request)?;\nif decision.is_allowed() {\n println!(\"Tool authorized\");\n}\n# Ok(())\n# }\n```\n\n## Capability Delegation (ANVIL \u00a711.3)\n\n```no_run\nuse forge_auth::prelude::*;\n# use arsenal_core::identity::AgentId;\n# use arsenal_core::scope::ScopeSet;\n# use arsenal_core::token::AgentCapabilityToken;\n\n# fn example(parent_act: &AgentCapabilityToken) -> ForgeAuthResult<()> {\nlet request = DelegationRequest {\n parent_act,\n parent_did: \"did:oas:l1fe:agent:parent\".to_string(),\n child_agent_id: AgentId::generate(),\n child_did: \"did:oas:l1fe:agent:child\".to_string(),\n requested_scopes: ScopeSet::new(),\n};\nlet child_act = delegate_capabilities(&request)?;\n# Ok(())\n# }\n```" }, { "name": "capability", "line": 99, "signature": "pub mod capability;", "documentation": "" }, { "name": "delegation", "line": 100, "signature": "pub mod delegation;", "documentation": "" }, { "name": "error", "line": 101, "signature": "pub mod error;", "documentation": "" }, { "name": "local_capability", "line": 102, "signature": "pub mod local_capability;", "documentation": "" }, { "name": "tool_auth", "line": 103, "signature": "pub mod tool_auth;", "documentation": "" }, { "name": "prelude", "line": 108, "signature": "pub mod prelude;", "documentation": "Re-exports of the most commonly used types and functions.\n\nImport `forge_auth::prelude::*` for convenient access to the primary API." }, { "name": "pub use crate::auth_context::AuthContext;", "line": 109, "signature": "pub use crate::auth_context::AuthContext;", "documentation": "" }, { "name": "pub use crate::capability::{\n act_allows_proxy_variable, act_allows_scope, extract_scopes, verify_act,\n };", "line": 110, "signature": "pub use crate::capability::{\n act_allows_proxy_variable, act_allows_scope, extract_scopes, verify_act,\n };", "documentation": "" }, { "name": "pub use crate::delegation::{delegate_capabilities, DelegationRequest};", "line": 113, "signature": "pub use crate::delegation::{delegate_capabilities, DelegationRequest};", "documentation": "" }, { "name": "pub use crate::error::{ForgeAuthError, ForgeAuthResult};", "line": 114, "signature": "pub use crate::error::{ForgeAuthError, ForgeAuthResult};", "documentation": "" }, { "name": "pub use crate::tool_auth::{\n authorize_proxy_tool_invocation, authorize_tool_invocation, ToolAuthorizationDecision,\n ToolAuthorizationRequest,\n };", "line": 115, "signature": "pub use crate::tool_auth::{\n authorize_proxy_tool_invocation, authorize_tool_invocation, ToolAuthorizationDecision,\n ToolAuthorizationRequest,\n };", "documentation": "" } ] }, { "path": "forge-rs/crates/forge-auth/src/local_capability.rs", "sha256": "91837cd3e9b282ae469d3a4a98576bc574405a8717cf4585f234a32fc7468520", "artifactSha256": "24b60414530b49975c67f469b73067b38fc2824d6ab64b7337551c5a7b8b90d1", "url": "/reference/source/forge-rs/crates/forge-auth/src/local_capability.rs.txt", "declarations": [ { "name": "::DEV_ISSUER", "line": 34, "signature": "pub const DEV_ISSUER: &str;", "documentation": "The issuer string for all local dev capability tokens.\n\nThis string is explicitly rejected by all production Arsenal validators." }, { "name": "::DEV_AUDIENCE", "line": 39, "signature": "pub const DEV_AUDIENCE: &str;", "documentation": "The audience string for all local dev capability tokens.\n\nThis string is explicitly rejected by all production Arsenal validators." }, { "name": "::DEV_TOKEN_TTL_SECONDS", "line": 42, "signature": "pub const DEV_TOKEN_TTL_SECONDS: i64;", "documentation": "The default TTL for dev capability tokens: 24 hours (86400 seconds)." }, { "name": "::LocalCapabilityFactory", "line": 60, "signature": "#[derive(Debug, Clone)]\npub struct LocalCapabilityFactory {\n\n}", "documentation": "A local-scoped capability token factory.\n\nProduces Arsenal-compatible `AgentCapabilityToken` instances that grant\nall scopes. These tokens are structurally identical to production ACTs\nbut use the `forge-dev-issuer` issuer and `forge-dev-runtime` audience\nstrings, which production validators reject.\n\n# Examples\n\n```no_run\nuse forge_auth::local_capability::LocalCapabilityFactory;\n\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\nlet act = factory.create_dev_token(\"did:forge-dev:a1b2c3d4e5f6a7b8:agent:bot\");\n```" }, { "name": "::LocalCapabilityFactory::new", "line": 81, "signature": "pub fn new(org_id: &str) -> Self;", "documentation": "Creates a new factory with a tenant ID derived from the org ID.\n\n# Arguments\n\n* `org_id` - The local org identifier (e.g., `\"forge-dev-org:local\"`).\n\n# Examples\n\n```no_run\nuse forge_auth::local_capability::LocalCapabilityFactory;\n\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\n```" }, { "name": "::LocalCapabilityFactory::with_ttl", "line": 99, "signature": "pub fn with_ttl(org_id: &str, ttl_seconds: i64) -> Self;", "documentation": "Creates a new factory with a custom TTL.\n\n# Arguments\n\n* `org_id` - The local org identifier.\n* `ttl_seconds` - The TTL in seconds for generated tokens." }, { "name": "::LocalCapabilityFactory::create_dev_token", "line": 131, "signature": "pub fn create_dev_token(&self, agent_did: &str) -> AgentCapabilityToken;", "documentation": "Creates a dev-mode capability token granting all scopes.\n\nThe token is structurally identical to a production Arsenal ACT but\nuses dev-mode issuer and audience strings that production validators\nreject.\n\n# Arguments\n\n* `agent_did` - The local dev agent's DID (e.g., `\"did:forge-dev:...:agent:bot\"`).\n\n# Returns\n\nA valid `AgentCapabilityToken` with wildcard scopes (`*:*:*`).\n\n# Examples\n\n```no_run\nuse forge_auth::local_capability::LocalCapabilityFactory;\nuse forge_auth::capability::verify_act;\n\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\nlet act = factory.create_dev_token(\"did:forge-dev:a1b2c3d4e5f6a7b8:agent:bot\");\n\n// The token is structurally valid\nassert!(verify_act(&act).is_ok());\n```" }, { "name": "::LocalCapabilityFactory::create_scoped_dev_token", "line": 216, "signature": "pub fn create_scoped_dev_token(\n &self,\n agent_did: &str,\n scope_strs: &[&str],\n ) -> ForgeAuthResult;", "documentation": "Creates a dev-mode capability token with specific scopes.\n\nThis allows developers to test authorization failures by narrowing\nthe scopes granted to an agent.\n\n# Arguments\n\n* `agent_did` - The local dev agent's DID.\n* `scope_strs` - The scope strings to grant (e.g., `[\"forge:tool.clock:execute\"]`).\n\n# Returns\n\nA valid `AgentCapabilityToken` with the specified scopes.\n\n# Errors\n\nReturns [`ForgeAuthError::InvalidToken`] if any scope string is malformed.\n\n# Examples\n\n```no_run\nuse forge_auth::local_capability::LocalCapabilityFactory;\n\nlet factory = LocalCapabilityFactory::new(\"forge-dev-org:local\");\nlet act = factory.create_scoped_dev_token(\n \"did:forge-dev:a1b2c3d4e5f6a7b8:agent:bot\",\n &[\"forge:tool.clock:execute\", \"forge:tool.search:execute\"],\n);\n```" }, { "name": "::LocalCapabilityFactory::issuer", "line": 254, "signature": "pub fn issuer(&self) -> &str;", "documentation": "Returns the issuer string used by this factory." }, { "name": "::LocalCapabilityFactory::audience", "line": 259, "signature": "pub fn audience(&self) -> &str;", "documentation": "Returns the audience string used by this factory." }, { "name": "::LocalCapabilityFactory::default_ttl_seconds", "line": 264, "signature": "pub fn default_ttl_seconds(&self) -> i64;", "documentation": "Returns the default TTL in seconds." } ] }, { "path": "forge-rs/crates/forge-auth/src/tool_auth.rs", "sha256": "2f11976a64a484f2d027bb5f49ab9f0f2878a960867ad8f9968e1dcced04fd06", "artifactSha256": "a99bbf7d702630b216a3ccf1af73d158b66b71326efce7329c1502434fc07135", "url": "/reference/source/forge-rs/crates/forge-auth/src/tool_auth.rs.txt", "declarations": [ { "name": "::ToolAuthorizationRequest", "line": 57, "signature": "#[derive(Debug)]\npub struct ToolAuthorizationRequest<'a> {\n/// The OAS DID of the agent requesting tool invocation.\n\npub agent_did: String,\n/// The name of the tool being invoked.\n\npub tool_name: String,\n/// The tier classification of the tool.\n\npub tool_tier: ToolTier,\n/// The agent's Arsenal ACT, if available.\n\n///\n\n/// When `None`, the request is processed in legacy mode (no ACT checks).\n\npub act: Option<&'a AgentCapabilityToken>\n}", "documentation": "A request to authorize a tool invocation.\n\nContains the agent's identity, the tool being invoked, its tier, and\nthe optional Arsenal ACT. When `act` is `None`, the system operates\nin legacy mode (no authorization enforcement).\n\n# ANVIL Spec \u00a78.7" }, { "name": "::ToolAuthorizationDecision", "line": 79, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum ToolAuthorizationDecision {\n /// The tool invocation is authorized.\n ///\n /// Returned for:\n /// - Tier 1 (Platform) tools \u2014 always allowed.\n /// - Tier 3 (Embedded) tools \u2014 always allowed.\n /// - Tier 2 (Host) tools \u2014 when the ACT grants the required scope.\n Allowed,\n\n /// The tool invocation is denied.\n ///\n /// Returned for Tier 2 (Host) tools when the ACT does not grant the\n /// required scope. The `reason` field provides an actionable explanation.\n Denied {\n /// Human-readable explanation of why the tool was denied.\n reason: String,\n },\n\n /// No ACT was provided \u2014 operating in legacy mode.\n ///\n /// Legacy mode allows tool execution without authorization. This mode\n /// exists for backward compatibility during the OAS integration migration.\n /// A `WARN`-level log is emitted when this mode is triggered.\n ///\n /// Legacy mode will be removed in a future major version.\n LegacyMode,\n}", "documentation": "The result of a tool authorization check.\n\n# ANVIL Spec \u00a78.7\n\nThe three variants correspond to the three possible outcomes:\n- `Allowed` \u2014 tool invocation proceeds\n- `Denied` \u2014 tool invocation is blocked with a reason\n- `LegacyMode` \u2014 no ACT was provided; tool executes without authorization" }, { "name": "::ToolAuthorizationDecision::is_allowed", "line": 112, "signature": "#[must_use]\npub fn is_allowed(&self) -> bool;", "documentation": "Returns `true` if the decision allows the tool invocation.\n\nBoth `Allowed` and `LegacyMode` permit execution." }, { "name": "::ToolAuthorizationDecision::is_denied", "line": 118, "signature": "#[must_use]\npub fn is_denied(&self) -> bool;", "documentation": "Returns `true` if the decision denies the tool invocation." }, { "name": "::ToolAuthorizationDecision::is_legacy_mode", "line": 124, "signature": "#[must_use]\npub fn is_legacy_mode(&self) -> bool;", "documentation": "Returns `true` if operating in legacy mode (no ACT)." }, { "name": "::authorize_tool_invocation", "line": 202, "signature": "#[instrument(\n skip(request),\n fields(\n agent_did = %request.agent_did,\n tool = %request.tool_name,\n tier = %request.tool_tier,\n has_act = request.act.is_some()\n )\n)]\npub fn authorize_tool_invocation(\n request: &ToolAuthorizationRequest<'_>,\n) -> ForgeAuthResult;", "documentation": "Authorizes a tool invocation per ANVIL Spec \u00a78.7.\n\nThis is the primary authorization gate for all tool invocations in the\nForge runtime. It enforces the three-tier model:\n\n- **Tier 1 (Platform)**: Always returns `Allowed`. Platform tools (clock,\n crypto, logging, random) are always available to agents.\n- **Tier 2 (Host)**: Requires an Arsenal ACT with a scope that implies\n `\"forge:tool.:execute\"`. Returns `Denied` if the scope is\n missing, or `LegacyMode` if no ACT is provided.\n- **Tier 3 (Embedded)**: Always returns `Allowed`. Embedded tools run\n inside the WASM sandbox and are scoped to the module.\n\n# Arguments\n\n* `request` - The authorization request containing agent DID, tool name,\n tier, and optional ACT.\n\n# Returns\n\nA [`ToolAuthorizationDecision`] indicating whether the invocation is allowed,\ndenied, or operating in legacy mode.\n\n# Errors\n\n- [`ForgeAuthError::TokenExpired`] \u2014 if the ACT has expired.\n- [`ForgeAuthError::InvalidToken`] \u2014 if the ACT is structurally invalid.\n\n# ANVIL Spec \u00a78.7\n\n> The runtime MUST check the agent's ACT before executing any Host tool.\n> Platform and Embedded tools bypass the ACT check.\n\n# Examples\n\n```no_run\nuse forge_auth::tool_auth::{ToolAuthorizationRequest, authorize_tool_invocation};\nuse forge_core::tool::ToolTier;\n\n// Platform tool \u2014 always allowed, no ACT needed\nlet request = ToolAuthorizationRequest {\n agent_did: \"did:oas:l1fe:agent:bot\".to_string(),\n tool_name: \"clock\".to_string(),\n tool_tier: ToolTier::Platform,\n act: None,\n};\nlet decision = authorize_tool_invocation(&request).unwrap();\nassert!(decision.is_allowed());\n```" }, { "name": "::authorize_proxy_tool_invocation", "line": 292, "signature": "#[instrument(\n skip(request, variables),\n fields(\n agent_did = %request.agent_did,\n tool = %request.tool_name,\n variable_count = variables.len()\n )\n)]\npub fn authorize_proxy_tool_invocation(\n request: &ToolAuthorizationRequest<'_>,\n variables: &[String],\n) -> ForgeAuthResult;", "documentation": "Checks whether a tool invocation that uses proxy template variables is authorized.\n\nWhen a tool uses `{{VARIABLE_NAME}}` template variables, it requires both the\ntool scope (`forge:tool.:execute`) and proxy scopes for each variable\n(`proxy::use` or `proxy:*:*`).\n\n# Arguments\n\n* `request` - The tool authorization request.\n* `variables` - The template variable names used by the tool.\n\n# Returns\n\nA [`ToolAuthorizationDecision`] indicating the authorization result.\n\n# Errors\n\nPropagates errors from ACT verification." } ] } ] }