add security considerations

10-security-considerations.md

@@ -0,0 +1,139 @@
+# ANP Security Considerations
+
+This document summarizes security guidance that cuts across the ANP
+specifications. It does not replace the protocol-specific requirements in the
+DID:WBA, Agent Description, Agent Discovery, Meta-Protocol, or Messaging
+documents. Instead, it clarifies the security boundary that implementations and
+applications should preserve when they compose these mechanisms.
+
+## 1. Security Goals and Non-Goals
+
+ANP provides protocol mechanisms for agent identity, authenticated requests,
+message integrity, secure service discovery, protocol negotiation, and optional
+end-to-end encryption profiles. In particular, DID:WBA authentication proves the
+identity associated with a DID verification method, and message signatures or
+digests protect the covered request components from tampering.
+
+Successful ANP authentication is not the same as application authorization. A
+server or receiving agent still needs to decide whether the authenticated DID is
+allowed to access a resource, invoke an operation, or act for a user. Similarly,
+ANP does not by itself guarantee task correctness, prompt-injection resistance,
+business-rule enforcement, or prevention of information loss in multi-agent
+workflows. Those decisions belong to the application, agent runtime, or
+deployment policy. ANP implementations should preserve enough authenticated
+context for those layers to make and audit the decision.
+
+## 2. Authentication and Authorization Boundary
+
+Implementations should keep identity proof separate from resource authorization:
+
+1. Verify the DID document, verification method, signature coverage, timestamp,
+   nonce, and message digest according to the relevant ANP profile.
+2. Treat successful verification as authentication of the sender or service
+   identity, not as permission to perform the requested action.
+3. Apply local authorization policy to the authenticated DID, requested
+   resource, protocol profile, and operation.
+4. Return an authentication error, such as `401 Unauthorized`, when identity
+   proof fails; return an authorization error, such as `403 Forbidden`, when the
+   DID is authenticated but lacks permission.
+
+When an operation requires user presence or other high-assurance approval, the
+application should express that policy in the agent description or runtime
+capability contract. A DID document should not be treated as proof that a human
+approved a specific action.
+
+## 3. Credential and Key Lifecycle
+
+DID:WBA already defines timestamp checks, nonce-based replay protection, DID
+document verification, and access-token handling. Implementations should also
+make the lifecycle behavior explicit:
+
+1. Use short and configurable validity windows for signatures, challenges, and
+   access tokens.
+2. Keep replay-cache entries at least as long as the accepted signature or
+   challenge window.
+3. Fail closed when a DID document cannot be resolved, a verification method is
+   removed, a key no longer satisfies the required verification relationship, or
+   an access token has expired.
+4. Version or otherwise track key material so that rotation, revocation, and DID
+   document updates are visible to authorization and audit logic.
+5. Prefer sender-constrained access tokens when a compatible profile is
+   available; otherwise, treat bearer tokens as high-value secrets and limit
+   their lifetime and scope.
+
+These items are implementation guidance. They do not require a new wire-format
+field unless a future ANP profile chooses to standardize one.
+
+## 4. Security Event Hooks
+
+ANP implementations should expose security-relevant events to the application
+or runtime layer. The specification does not need to mandate a particular
+logging backend, but implementations should make the following events observable
+to policy, monitoring, and incident-response code:
+
+1. DID resolution, DID-document verification, and verification-method mismatch.
+2. Signature, digest, timestamp, nonce, replay-cache, and access-token
+   acceptance or rejection.
+3. Protocol negotiation start, accept, reject, failure, and protocol-hash
+   mismatch.
+4. Generated or loaded protocol-handler verification failures.
+5. Authorization decisions made after successful authentication.
+6. Cross-domain or cross-protocol handoff events.
+
+Useful event fields include the source DID, destination DID, service DID if
+applicable, session or negotiation identifier, protocol profile, protocol hash,
+operation name, decision, timestamp, and error code. Applications can redact or
+aggregate these fields according to their privacy requirements.
+
+## 5. Generated Protocol Code and Negotiated Handlers
+
+The Meta-Protocol allows agents to negotiate or reuse protocol descriptions.
+Implementations should treat generated or dynamically loaded handlers as
+untrusted until verified. Recommended safeguards include:
+
+1. Bind generated handlers to the negotiated protocol identifier and protocol
+   hash.
+2. Verify signatures or provenance for reusable protocol packages when such
+   metadata is available.
+3. Run generated or third-party handler code in a least-privilege sandbox.
+4. Deny filesystem, network, credential, tool, and environment access unless
+   the application explicitly grants it.
+5. Keep the handler's allowed capabilities separate from the sender's
+   authenticated identity; authenticating the sender should not automatically
+   grant the handler new local privileges.
+
+## 6. Cross-Protocol and Bridge Deployments
+
+ANP deployments may interact with other agent protocols, tool runtimes, or
+application gateways. In these settings, the bridge component should preserve
+the security context instead of converting it into implicit authority.
+
+For example, when an ANP message leads to a call into another protocol or tool
+system, the bridge should carry forward the relevant source DID, destination
+DID, service DID, protocol hash, session or negotiation identifier, and
+authorization context. The receiving runtime should still apply its own policy
+before reading files, invoking tools, sending network requests, or acting on
+behalf of a user.
+
+This boundary is important because each protocol may verify only its local
+message format and identity proof. A composed deployment can still create an
+unsafe path if authenticated content from one side silently authorizes actions
+on the other side.
+
+## 7. Implementation Checklist
+
+Implementers should verify that their deployment:
+
+1. Separates authentication from authorization.
+2. Checks signature coverage, message digest, timestamp, nonce, and replay
+   state before accepting requests.
+3. Defines token lifetime, token scope, and key-rotation behavior.
+4. Avoids putting secrets, API keys, or bearer credentials in agent description
+   documents.
+5. Treats generated protocol handlers and third-party handler packages as
+   untrusted code until verified and sandboxed.
+6. Exposes security events to application policy and monitoring code.
+7. Preserves source identity and protocol context across bridges, gateways, and
+   cross-protocol calls.
+8. Requires explicit application policy for sensitive operations such as user
+   approval, file access, tool execution, payment, or external network access.

README.md

@@ -83,6 +83,7 @@ We are developing an open-source implementation of AgentNetworkProtocol, and its
 
 - Complete materials are available at [Extended Reading](docs/links.md)  
 - For detailed design, please read the [ANP Technical White Paper](/01-agentnetworkprotocol-technical-white-paper.md)  
+- For cross-cutting security guidance, see [ANP Security Considerations](/10-security-considerations.md)
 - Refer to the open-source implementation [AgentConnect Examples](https://github.com/agent-network-protocol/AgentConnect)
 
 ## Milestones

docs/links.md

@@ -6,6 +6,7 @@ For ease of reference, all ANP-related materials are organized by **Specificatio
 
 - [ANP Getting Started Guide](/docs/anp-getting-started-guide.md)
 - [did:wba Method Specification](/03-did-wba-method-design-specification.md)
+- [ANP Security Considerations](/10-security-considerations.md)
 - [ANP End-to-End Instant Messaging Protocol Overview](/09-ANP-end-to-end-instant-messaging-protocol-specification.md)
 - [ANP Profile 1: Core Binding](/message/01-core-binding.md)
 - [ANP Profile 2: Identity and Discovery](/message/02-identity-and-discovery.md)