diff --git a/README.md b/README.md index 9e06408..0d9f2dc 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Every agent in the catalog is uniquely identified by a domain-anchored, RFC 8141 urn:ai::: ``` * **`urn:ai`**: Ecosystem prefix. -* **``**: Verifiable FQDN representing the publisher (e.g., `acme.com`), establishing a decentralized trust anchor. +* **``**: Verifiable FQDN representing the publisher (e.g., `example.com`), establishing a decentralized trust anchor. * **``**: Optional hierarchical grouping (e.g., `finance:trading`). * **``**: Unique terminal short name (e.g., `assistant`). diff --git a/adr/0003-urn-placeholder-rfc2606-alignment.md b/adr/0003-urn-placeholder-rfc2606-alignment.md index 2bb881a..69cf326 100644 --- a/adr/0003-urn-placeholder-rfc2606-alignment.md +++ b/adr/0003-urn-placeholder-rfc2606-alignment.md @@ -34,7 +34,7 @@ We aligned all local-development placeholder recommendations in `spec/urn-naming This placeholder architecture establishes a clear security boundary based on the development lifecycle phase: * **Syntax-Only Validation (Scenario A & B — Default)**: For standard local development, there is **no active cryptographic identity verification** happening. The placeholder domains (`*.localhost`, `example.com`) are enforced strictly to satisfy standard syntax validation rules and maintain architectural consistency with production files. -* **Workload Verification (Scenario C — Advanced Enterprise)**: If an enterprise developer is testing their production zero-trust security mesh (like SPIFFE/SPIRE or mTLS) inside a local Kubernetes/Istio cluster on their laptop, they use their **real domain** (e.g., `acme.com`) as the URN publisher. This allows their local zero-trust mesh to actively validate their test certificates against the URN namespace before pushing to production. +* **Workload Verification (Scenario C — Advanced Enterprise)**: If an enterprise developer is testing their production zero-trust security mesh (like SPIFFE/SPIRE or mTLS) inside a local Kubernetes/Istio cluster on their laptop, they use their **real domain** (e.g., `example.com`) as the URN publisher. This allows their local zero-trust mesh to actively validate their test certificates against the URN namespace before pushing to production. This two-tier approach keeps local testing extremely lightweight and zero-friction, while providing a seamless path for heavy-duty enterprise security integration. diff --git a/conformance/examples/ai-catalog.json b/conformance/examples/ai-catalog.json index 692caf1..69670b2 100644 --- a/conformance/examples/ai-catalog.json +++ b/conformance/examples/ai-catalog.json @@ -2,14 +2,14 @@ "specVersion": "1.0", "host": { "displayName": "Acme Enterprise AI Test Host", - "identifier": "did:web:acme.com" + "identifier": "did:web:example.com" }, "entries": [ { - "identifier": "urn:ai:acme.com:agent:assistant", + "identifier": "urn:ai:example.com:agent:assistant", "displayName": "Corporate Assistant (A2A)", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/agents/assistant.json", + "url": "https://api.example.com/agents/assistant.json", "description": "General-purpose corporate A2A assistant for internal workflows.", "representativeQueries": [ "help me draft an email to the security working group", @@ -17,10 +17,10 @@ ] }, { - "identifier": "urn:ai:acme.com:server:weather", + "identifier": "urn:ai:example.com:server:weather", "displayName": "Weather Data Node", "type": "application/mcp-server+json", - "url": "https://api.acme.com/mcp/weather.json", + "url": "https://api.example.com/mcp/weather.json", "capabilities": ["WeatherTool", "ForecastTool"], "description": "Enterprise weather MCP server for live telemetry.", "representativeQueries": [ @@ -29,10 +29,10 @@ ] }, { - "identifier": "urn:ai:acme.com:catalog:engineering", + "identifier": "urn:ai:example.com:catalog:engineering", "displayName": "Engineering Sub-Catalog Reference", "type": "application/ai-catalog+json", - "url": "https://acme.com/catalogs/engineering.json", + "url": "https://example.com/catalogs/engineering.json", "description": "Nested catalog containing CI/CD and internal deployment agents." } ] diff --git a/conformance/examples/registry-server.py b/conformance/examples/registry-server.py index 552db33..0bf013d 100755 --- a/conformance/examples/registry-server.py +++ b/conformance/examples/registry-server.py @@ -17,10 +17,10 @@ # Mock catalog database seeded from spec/examples/ai-catalog.json MOCK_CATALOG_ENTRIES = [ { - "identifier": "urn:ai:acme.com:agent:assistant", + "identifier": "urn:ai:example.com:agent:assistant", "displayName": "Corporate Assistant (A2A)", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/agents/assistant.json", + "url": "https://api.example.com/agents/assistant.json", "description": "General-purpose corporate A2A assistant for internal workflows.", "representativeQueries": [ "help me draft an email to the security working group", @@ -28,10 +28,10 @@ ] }, { - "identifier": "urn:ai:acme.com:server:weather", + "identifier": "urn:ai:example.com:server:weather", "displayName": "Weather Data Node", "type": "application/mcp-server+json", - "url": "https://api.acme.com/mcp/weather.json", + "url": "https://api.example.com/mcp/weather.json", "capabilities": ["WeatherTool", "ForecastTool"], "description": "Enterprise weather MCP server for live telemetry.", "representativeQueries": [ @@ -40,10 +40,10 @@ ] }, { - "identifier": "urn:ai:acme.com:catalog:engineering", + "identifier": "urn:ai:example.com:catalog:engineering", "displayName": "Engineering Sub-Catalog Reference", "type": "application/ai-catalog+json", - "url": "https://acme.com/catalogs/engineering.json", + "url": "https://example.com/catalogs/engineering.json", "description": "Nested catalog containing CI/CD and internal deployment agents." } ] diff --git a/spec/agentfinder.md b/spec/agentfinder.md index 015d054..ed61f9a 100644 --- a/spec/agentfinder.md +++ b/spec/agentfinder.md @@ -69,14 +69,14 @@ A manifest file hosted at /.well-known/ai-catalog.json lists the available artif "specVersion": "1.0", "host": { "displayName": "Acme Enterprise AI", - "identifier": "did:web:acme.com" + "identifier": "did:web:example.com" }, "entries": [ { - "identifier": "urn:ai:acme.com:agent:assistant", + "identifier": "urn:ai:example.com:agent:assistant", "displayName": "Corporate Assistant (A2A)", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/agents/assistant.json", + "url": "https://api.example.com/agents/assistant.json", "description": "General-purpose corporate A2A assistant.", "representativeQueries": [ "help me draft an email to the security working group", @@ -84,10 +84,10 @@ A manifest file hosted at /.well-known/ai-catalog.json lists the available artif ] }, { - "identifier": "urn:ai:acme.com:server:weather", + "identifier": "urn:ai:example.com:server:weather", "displayName": "Weather Data Node", "type": "application/mcp-server+json", - "url": "https://api.acme.com/mcp/weather.json", + "url": "https://api.example.com/mcp/weather.json", "capabilities": ["WeatherTool", "ForecastTool"], "description": "Enterprise weather MCP server for live telemetry.", "representativeQueries": [ @@ -96,7 +96,7 @@ A manifest file hosted at /.well-known/ai-catalog.json lists the available artif ] }, { - "identifier": "urn:ai:acme.com:plugin:finance-suite", + "identifier": "urn:ai:example.com:plugin:finance-suite", "displayName": "Finance Tool Bundle", "type": "application/ai-catalog+json", "description": "A static nested bundle containing an A2A agent and its required market dataset.", @@ -105,49 +105,49 @@ A manifest file hosted at /.well-known/ai-catalog.json lists the available artif "specVersion": "1.0", "entries": [ { - "identifier": "urn:ai:acme.com:finance:a2a", + "identifier": "urn:ai:example.com:finance:a2a", "displayName": "Finance Trading Agent", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/agents/finance-trader.json" + "url": "https://api.example.com/agents/finance-trader.json" }, { - "identifier": "urn:ai:acme.com:market:2026", + "identifier": "urn:ai:example.com:market:2026", "displayName": "Market Dataset 2026", "type": "application/parquet", - "url": "https://data.acme.com/market-2026.parquet" + "url": "https://data.example.com/market-2026.parquet" } ] } }, { - "identifier": "urn:ai:acme.com:registry:global", + "identifier": "urn:ai:example.com:registry:global", "displayName": "Acme Global Agent Registry", "type": "application/ai-registry+json", - "url": "https://registry.acme.com/api/v1/", + "url": "https://registry.example.com/api/v1/", "description": "Dynamic REST API search interface to discover all approved enterprise agents.", "tags": ["registry", "search", "dynamic"], "trustManifest": { - "identity": "spiffe://acme.com/registry/global", + "identity": "spiffe://example.com/registry/global", "identityType": "spiffe", "attestations": [ { "type": "SPIFFE-X509", - "uri": "https://acme.com/.well-known/spiffe/jwks", + "uri": "https://example.com/.well-known/spiffe/jwks", "mediaType": "application/json" }, { "type": "SOC2-Type2", - "uri": "https://trust.acme.com/reports/soc2.pdf", + "uri": "https://trust.example.com/reports/soc2.pdf", "mediaType": "application/pdf" } ] } }, { - "identifier": "urn:ai:acme.com:catalog:engineering", + "identifier": "urn:ai:example.com:catalog:engineering", "displayName": "Engineering Department Catalogs", "type": "application/ai-catalog+json", - "url": "https://acme.com/catalogs/engineering.json", + "url": "https://example.com/catalogs/engineering.json", "description": "Sub-catalogs containing CI/CD and internal deployment agents." } ] @@ -196,7 +196,7 @@ urn:ai::: * **urn**: Mandatory prefix indicating a Uniform Resource Name. * **ai**: The Namespace Identifier (NID), designating the AI artifact and agent discovery ecosystem. -* **\**: The Namespace Specific String (NSS) root. MUST be a fully qualified domain name (FQDN) representing the publisher or host organization (e.g., acme.com, github.com). This domain acts as the organizational trust anchor and MUST be verifiable against the cryptographic workload identity in the trustManifest. +* **\**: The Namespace Specific String (NSS) root. MUST be a fully qualified domain name (FQDN) representing the publisher or host organization (e.g., example.com, github.com). This domain acts as the organizational trust anchor and MUST be verifiable against the cryptographic workload identity in the trustManifest. * **\**: Optional hierarchical segments separated by : (e.g., finance:trading, weather:telemetry). Allows publishers to categorize capabilities by department, team, or product line without altering infrastructure routing. * **\**: Mandatory terminal segment representing the specific, logical short name of the agent or tool (e.g., assistant, pptx-creator). @@ -301,32 +301,32 @@ Using trustManifest for compliance, published in a manifest. "specVersion": "1.0", "host": { "displayName": "Acme Enterprise AI", - "identifier": "did:web:acme.com" + "identifier": "did:web:example.com" }, "entries": [ { - "identifier": "urn:ai:acme.com:travel:concierge", + "identifier": "urn:ai:example.com:travel:concierge", "displayName": "Travel Concierge", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/travel/concierge.json", + "url": "https://api.example.com/travel/concierge.json", "description": "AI-powered travel planning", "trustManifest": { - "identity": "spiffe://acme.com/travel/concierge", + "identity": "spiffe://example.com/travel/concierge", "identityType": "spiffe", "attestations": [ { "type": "SPIFFE-X509", - "uri": "https://acme.com/.well-known/spiffe/jwks", + "uri": "https://example.com/.well-known/spiffe/jwks", "mediaType": "application/json" }, { "type": "SOC2-Type2", - "uri": "https://trust.acme.com/reports/soc2.pdf", + "uri": "https://trust.example.com/reports/soc2.pdf", "mediaType": "application/pdf" }, { "type": "GDPR", - "uri": "https://trust.acme.com/compliance/gdpr", + "uri": "https://trust.example.com/compliance/gdpr", "mediaType": "text/html" } ] @@ -473,12 +473,12 @@ The response returns standard catalog entries with additional relevance scores, { "results": [ { - "identifier": "urn:ai:acme.com:agent:assistant", + "identifier": "urn:ai:example.com:agent:assistant", "displayName": "Corporate Assistant (A2A)", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/agents/assistant.json", + "url": "https://api.example.com/agents/assistant.json", "score": 95, - "source": "https://registry.acme.com/api/v1/" + "source": "https://registry.example.com/api/v1/" }, { "identifier": "urn:ai:example.com:weather-server", @@ -565,7 +565,7 @@ Each element of `resultType.facets`: }, "publisher": { "buckets": [ - { "value": "acme.com", "count": 412 } + { "value": "example.com", "count": 412 } ] } } @@ -626,7 +626,7 @@ This gives the client full control over the federation topology without requirin { "results": [ { - "identifier": "urn:ai:acme.com:agent:expense", + "identifier": "urn:ai:example.com:agent:expense", "displayName": "Corporate Expenses", "type": "application/a2a-agent-card+json", "url": "https://internal.corp/agents/expense.json", diff --git a/spec/schemas/agentfinder.openapi.yaml b/spec/schemas/agentfinder.openapi.yaml index f25149a..f4a4c19 100644 --- a/spec/schemas/agentfinder.openapi.yaml +++ b/spec/schemas/agentfinder.openapi.yaml @@ -278,7 +278,7 @@ components: type: string format: uri description: The URL endpoint of the registry where this entry was indexed. - example: "https://registry.acme.com/api/v1/" + example: "https://registry.example.com/api/v1/" RegistryReferral: type: object diff --git a/spec/urn-naming-guide.md b/spec/urn-naming-guide.md index 4dea5af..b9f2017 100644 --- a/spec/urn-naming-guide.md +++ b/spec/urn-naming-guide.md @@ -25,7 +25,7 @@ When running and testing agents locally, developers may be tempted to structure Using `'localhost'` as the URN publisher is not allowed for the following reasons: -1. **Decentralized Trust and Verification**: Under the Agent Finder identity model, the `` segment of a URN must be a Fully Qualified Domain Name (FQDN). Registries and orchestrators extract this domain (e.g., `acme.com`) and cross-reference it against cryptographic attestations (like SPIFFE SVIDs or DIDs) within the `trustManifest` to verify authority. Since `localhost` is not a publicly resolvable, cryptographically verifiable domain, it breaks the decentralized trust model. +1. **Decentralized Trust and Verification**: Under the Agent Finder identity model, the `` segment of a URN must be a Fully Qualified Domain Name (FQDN). Registries and orchestrators extract this domain (e.g., `example.com`) and cross-reference it against cryptographic attestations (like SPIFFE SVIDs or DIDs) within the `trustManifest` to verify authority. Since `localhost` is not a publicly resolvable, cryptographically verifiable domain, it breaks the decentralized trust model. 2. **Namespace Collisions**: In a federated registry system, namespaces must be globally unique to avoid collisions. If multiple developers register their local agents using the `localhost` publisher, naming conflicts will occur as soon as those catalogs are merged or indexed. 3. **Nomenclature Instability**: The fact that an agent is currently running on localhost is a transient deployment detail. The URN represents the permanent contract; physical endpoint addresses belong in the operational transport configurations. @@ -83,12 +83,12 @@ Since domain names are already globally unique via the DNS root, anchoring your --- ### Scenario C: Enterprise Developers or Developers with a Verified Domain -For developers inside an enterprise or those who own a custom domain (e.g., `acme.com`), they should use their real FQDN as the URN publisher even when developing and running locally. +For developers inside an enterprise or those who own a custom domain (e.g., `example.com`), they should use their real FQDN as the URN publisher even when developing and running locally. This ensures that the URN remains completely identical between their local development, staging, and production catalogs, avoiding the need to rewrite downstream orchestration rules or client references. * **Guidance**: - * **URN (Identity)**: Use the real FQDN (e.g., `urn:ai:acme.com:finance:tax-agent`). + * **URN (Identity)**: Use the real FQDN (e.g., `urn:ai:example.com:finance:tax-agent`). * **Physical Endpoint**: Point to `localhost` in the local development manifest, and to the production gateway or API host in the production manifest. #### Local Manifest Example (`ai-catalog-local.json`): @@ -97,11 +97,11 @@ This ensures that the URN remains completely identical between their local devel "specVersion": "1.0", "host": { "displayName": "Acme Finance Local Dev", - "identifier": "did:web:dev.acme.com" + "identifier": "did:web:dev.example.com" }, "entries": [ { - "identifier": "urn:ai:acme.com:finance:tax-agent", + "identifier": "urn:ai:example.com:finance:tax-agent", "displayName": "Corporate Tax Assistant", "type": "application/a2a-agent-card+json", "url": "http://localhost:8000/agents/tax-assistant", @@ -111,28 +111,28 @@ This ensures that the URN remains completely identical between their local devel } ``` -#### Production Manifest Example (`ai-catalog.json` hosted at `https://acme.com/.well-known/ai-catalog.json`): +#### Production Manifest Example (`ai-catalog.json` hosted at `https://example.com/.well-known/ai-catalog.json`): ```json { "specVersion": "1.0", "host": { "displayName": "Acme Corporation", - "identifier": "did:web:acme.com" + "identifier": "did:web:example.com" }, "entries": [ { - "identifier": "urn:ai:acme.com:finance:tax-agent", + "identifier": "urn:ai:example.com:finance:tax-agent", "displayName": "Corporate Tax Assistant", "type": "application/a2a-agent-card+json", - "url": "https://api.acme.com/finance/tax-assistant", + "url": "https://api.example.com/finance/tax-assistant", "description": "Official Corporate Tax Assistant with production identity verification.", "trustManifest": { - "identity": "spiffe://acme.com/finance/tax-agent", + "identity": "spiffe://example.com/finance/tax-agent", "identityType": "spiffe", "attestations": [ { "type": "SOC2-Type2", - "uri": "https://trust.acme.com/soc2.pdf" + "uri": "https://trust.example.com/soc2.pdf" } ] }