feat: adding identity documentation

docs/.index

@@ -2,12 +2,12 @@ nav:
   - Introduction: index.md
   - OASF: oasf
   - Agent Directory Service: dir
-  - Agent Manifest: manifest
+  - Messaging SDK: messaging
   - Identity: identity
+  - CSIT: csit
   - Semantic SDK: semantic
   - Syntactic SDK: syntactic
-  - Messaging SDK: messaging
   - Agent Workflow Server: agws
-  - CSIT: csit
+  - Agent Manifest: manifest
   - How-To Guides: how-to-guides
   - How to Contribute: contributing.md

docs/identity/.index

@@ -1,5 +1,10 @@
 nav:
- - Identity: identity.md
+ - Introduction: identity.md
  - Identifiers: identifiers.md
+ - Identifier Examples: identifier_examples.md
  - Verifiable Credentials: credentials.md
- - Flow Diagrams: flow.md
+ - Agent Badge Examples: vc_agent_badge.md
+ - MCP Server Badge Examples: vc_mcp.md
+ - Architecture Diagrams: arch_diagrams.md
+ - Sequence Flows: flow.md
+ - OpenAPI Reference: openapi.md

docs/identity/arch_diagrams.md

@@ -0,0 +1,54 @@
+# Architecture Diagrams
+
+## Generating Agent Badges
+
+![Issuing Architecture Diagram](../assets/identity/issuing.png)
+
+The above diagram depicts the process for generating and storing a verifiable Agent Badge along with a `ResolverMetadata` object associated to an agent subject. A similar process can be followed to generate a verifiable MCP Server Badge or a verifiable MAS Badge.
+
+- The top left of the image shows that an organization may have several sub-organizations, each of which may create its own Agent subjects.
+- As described in the [examples](./identifier_examples.md), each agent subject will be associated to an agent ID. More specifically, AGNTCY enables organizations to bring their own identities for their agents (for example, identities created via Okta, Duo, or A2A) as well as the capacity to generate an identity through AGNTCY, for example, using DIDs.
+- Each agent subject is required to use a schema to create an Agent definition (e.g., using an [OASF schema](../oasf/open-agentic-schema-framework.md) or an A2A [Agent Card](https://google.github.io/A2A/specification/agent-card/)). The agent ID must be included in the Agent Definition (see examples of agent IDs [here](./identifier_examples.md)).
+- Each organization or sub-organization may create public and private key pairs, and store the private keys (PrivKeys) on their wallet or vault of choice, or other means enabling secure access to the PrivKeys.
+- A PrivKey owned and managed by an organization or sub-organization is required to create a ProofValue of the agent definition. As described in detail in the [Agent Badge Examples](./identifier_examples.md), the Agent Definition, the ProofValue, and additional metadata are used to create a Verifiable Credential in the form of a verifiable Agent Badge. Also note that, specific metadata, such as a verification method, an assertion method, and a service endpoint are used to create a `ResolverMetadata` object that is associated to the ID and the verifiable Agent Badge.
+
+    !!! note
+        Embedding the PubKey in the `ResolverMetadata` object itself is optional, since the metadata supplied allows for automated access and verification of the PubKey (e.g., using a JWK as part of a JWT header).
+
+- The `ResolverMetadata` along with the verifiable Agent Badge can be stored in Identity Nodes (INs) that can operate as trust anchors. In subsequent updates to this documentation, AGNTCY shall provide more detailed recommendations about the INs, and their role and capacity to operate as decentralized trust anchors, especially, to:
+
+    - Build trust during MAS composition involving third-party Agents and MCP Servers.
+    - Link and automate the dynamic and trustworthy discovery of running Agents and MCP Servers to their corresponding AuthN and delegated AuthZ methods, including MFA in a MAS.
+
+- AGNTCY considers the possibility that organizations and their sub-organizations may register with the INs (e.g., to brand and ensure the origin of their agents). This may include means to store and bind an organization/sub-organization to a PubKey, the IDs for the various subjects that they might register (e.g., Agents and MCP Servers), their corresponding `ResolverMetadata` objects and Agent Badges, as well as additional sets of VCs for each of them.
+
+AGNTCY plans to contribute open-source code to automate the process of creating and storing `ResolverMetadata` objects, Agent Badges, and MCP Server Badges.
+
+## Verifying Agent Badges
+
+![Verification Architecture Diagram](../assets/identity/verification.png)
+
+The above diagram depicts an example process enabling the lookup, identification and use of `ResolverMetadata` as well as verifying an Agent Badge associated to an Agent subject. The example process uses AGNTCY's [Agent Discovery Service](../dir/overview.md) as the means to discover an Agent with specific skills, and automatically identify and resolve the associated Agent Badge, irrespective of the type of identity used by the owner of the Agent (e.g., an Okta, Duo, AD, DID, or A2A ID).
+
+A similar process can be followed in the case of MCP Servers or A2A Agents, but in those cases the discovery service may rely on the use of well-known addresses (URLs), or other hubs, external directories, or discovery services.
+
+The following steps summarize the process:
+
+1. An Agent Consumer may search for an Agent with given skills, e.g., using an ADS client, such as a CLI, a UI, or a headless interface in case the consumer is an agent itself.
+2. A lookup is performed using the ADS.
+3. A list of potential candidates are presented to the Agent Consumer.
+4. The Agent Consumer selects the desired Agent.
+5. This now triggers the lookup of the selected Agent's definition (e.g., a definition based on an OASF schema), which contains the Agent ID (e.g., an Okta, Duo, AD, DID, or A2A ID).
+6. The Agent definition is obtained and passed to the Resolver, which is one of the key elements of the AGNTCY's identity service.
+7. The Resolver extracts the Agent ID from the Agent definition in step (7a), and performs a lookup process in an AGNTCY's Identity Node (IN) using the Agent ID as a key (see step (7b) in the diagram above).
+8. The corresponding Agent Badge and ResolverMetadata object are now passed to the Resolver.
+9. The Resolver provides trustworthy and automated means to resolve and verify the Agent subject. To this end, the Resolver proceeds as follows:
+
+    - It uses the ResolverMetadata object to obtain the crypto method and PubKey to decrypt the ProofValue in the Agent Badge.
+    - It decrypts the ProofValue and verifies the Agent Badge integrity, since, as shown in the examples [here](../../vc/agent-badge.md), the proof type is a `"DataIntegrityProof"`. This may include the computation of a digest, and comparison with a digest obtained after decryption.
+    - It outputs the verification result and logs it.
+
+10. The Verified Agent Badge is returned to the ADS client.
+11. This is forwarded to the Agent Consumer.
+
+AGNTCY plans to contribute open-source code to automate the process of resolving and verifying Agent Badges and MCP Server Badges, leveraging `ResolverMetadata` objects.

docs/identity/credentials.md

@@ -1,35 +1,50 @@
 # Verifiable Credentials
 
-## Definitions
+AGNTCY supports various types of Verifiable Credentials (VCs). A verifiable credential is a structured and cryptographically verifiable way to express claims made by an issuer. These claims can pertain to:
 
-The [`AGNTCY`](https://agntcy.org/) supports various types of verifiable credentials, referred to as VCs. A verifiable credential is a specific way to express and present a set of claims made by an issuer, such as an agent definition (e.g., an [`OASF Definition`](https://schema.oasf.outshift.com/objects), or an [`A2A Agent Card`](https://github.com/google/A2A/blob/main/specification/json/a2a.json#AgentCard)), a deployment configuration, or an authorization claim that could be used during a MFA process.
+- Agent definitions (for example, an [OASF definition](../oasf/open-agentic-schema-framework.md) or an [A2A Agent Card](https://google.github.io/A2A/specification/agent-card/))
+- Deployment configurations
+- Authorization assertions used in processes such as Multi-Factor Authentication (MFA)
 
-### Key Verifiable Credentials (VCs)
+## Key VCs
 
-One of the key `VCs` within the [`AGNTCY`](https://agntcy.org/) is the following:
+The identity framework conceived by AGNTCY allows not only to cryptographically bind an agent ID to an issuer, a public key and a proof of provenance but also the binding of the same agent ID to different definitions of the core agent, including different schemas, versions, locators, etc., as well as additional VCs that may be used during Multi-Factor authentication and authorization (MFA) processes. The same approach applies to MCP Servers.
 
-- `Agent Badge`: An enveloped `VC`, captured in the form of a JSON-LD object, that represents a specific definition of an Agent subject in the IoA. The definition follows a given schema (e.g., an OASF definition or an A2A Agent Card schema). An Agent subject could have multiple Agent Badges, each representing a different definition of the same core Agent or Agent subject. For instance, different software versions and/or patched releases of an Agent will have different Agent Badges. The same applies if the Agent's code is available in different forms (e.g, if it can be used and composed using different types of artifacts, such as a Docker container image or a python package), or if the source code can be reached at different sites or routing locators (e.g., through github or sites like hugging face), etc. Concrete examples of an Agent Badge can be found [`here`](https://spec.identity.agntcy.org/docs/vc/agent-badge).
+Among some of the key VCs within AGNTCY are the following:
 
-<!---
-- `Agent Passport`: An enveloped `VC`, captured in the form of a JSON-LD object, that represents an Agent subject in the IoA. While an Agent subject could have "n" different Agent Badges or definitions, it will be associated to one "Agent Passport", which in turn will be associated to single Agent `ID`. Hence, there is:
+### Agent Badge
 
-  - An n:1 relationship between Agent Badges and an Agent Passport
-  - A 1:1 relationship between an Agent Passport and an Agent `ID`
-  - A common element that binds Agent Badges and an Agent Passport, which is the same Agent `ID`.
+An Agent Badge is an enveloped VC captured in the form of a JSON-LD object that represents a specific definition of an agent subject in the IoA.
 
-More specifically, the role of the "Agent Passport" is to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance, while the role of the Agent Badges is to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes. A concrete example of an Agent Passport can be found [`here`](../vc/agent-passport.md).
+The definition follows a given schema (for example, an OASF definition or an A2A Agent Card schema). An agent subject can have multiple Agent Badges, each representing a different definition of the same core agent or agent subject. For instance, different software versions and/or patched releases of an agent will have different Agent Badges.
 
--->
+The same applies if the agent's code is available in different forms (for example, if it can be used and composed using different types of artifacts, such as a Docker container image or a Python package), or if the source code can be reached at different sites or routing locators (through GitHub or sites like Hugging Face), and so on.
 
-The identity framework conceived by the `AGNTCY` allows not only to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance but also to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes.
+Examples of an Agent Badge can be found [here](./vc_agent_badge.md).
 
-<br />
+### MCP Server Badge
 
-!!! note
-    As detailed in the [`Agent Badge Examples`](https://spec.identity.agntcy.org/docs/vc/agent-badge), the combined use of an `Agent Badge` with `ResolverMetadata` objects enables the automatic and trustworthy discovery not only of the PubKey associated to the Agent issuer but also of the verification material to prove the authenticity and integrity of the Agent Badge, according to the assertionMethod defined in the `ResolverMetadata` object.
+An MCP Server Badge is an enveloped VC, captured in the form of a JSON-LD object, that represents a specific definition of an MCP Server subject in the IoA. The definition should follow a given schema (that is, a json specification following a similar approach to A2A's card but for MCP Servers). 
 
-      Furthermore, the use of Agent Badges provides a set of key properties in an IoA:
+Like in the case of an agent subject, an MCP Server can have multiple MCP Server Badges, each representing a different definition of the same core MCP Server subject. For instance, different software versions and/or patched releases of an MCP Server will have different MCP Server Badges. 
 
-      1. It addresses the problem of **Agent impersonation**, by avoiding scenarios where one organization could offer rogue Agents as if they were created by another (trusted) company.
-      2. It enables **trustworthy origination, traceability, and lineage of Agents**. Note that Agents will end up having different versions and releases (e.g., due to security patches and updates), so while a company might be using version 2.08 of Agent `ID` = X, another company might be using version 2.1 of Agent Agent `ID` = X. Knowing that there is a key vulnerability and recommended upgrade for Agent `ID` = X, version 2.08, would allow the first company to migrate to version 2.1, while inform the second company that the upgrade is not needed.
-      3. It **enables more sophisticated AuthN and AuthZ processes among agents with and without a human in the loop**, including the **capacity to build trust even before an Agent is selected and used**. In subsequent updates to this documentation, the [`AGNTCY`](https://agntcy.org/) will provide examples involving MFA and how to build trust dynamically among Agents.
+A example of an MCP Server Badge can be found [here](./vc_mcp.md).
+
+## Use Cases
+
+The combined use of Badges (VCs) and ResolverMetadata enables automated and trustworthy validation of:
+
+- Issuer public keys, via assertion methods.
+- Authenticity and integrity of credentials (Agent or MCP Server Badges).
+- Entity provenance and update lineage (especially critical for secure versioning).
+
+## Benefits of this Model
+
+- Prevents impersonation of Agents, and MCP Server resources and tools by ensuring provenance can be verified.
+- Enables secure versioning and traceability, supporting safe upgrades and patching.
+- Facilitates advanced authentication and authorization workflows, including those involving:
+    - Dynamic trust establishment
+    - Machine-to-machine negotiation (with or without human input)
+    - Pre-connection credential validation
+
+These capabilities apply equally to Agents and MCP Servers, supporting trust-aware composition and interaction across the IoA.