suissAI

Posted on Feb 26

FullAgenticStack WhatsApp-first: RFC-WF-0013

#agents #api #architecture #systemdesign

RFC-WF-0013

Well-Known Discovery & Interop Endpoints (WKD)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0001 (WFCS), RFC-WF-0005 (CRCD), RFC-WF-0006 (EAS), RFC-WF-0007 (OoC), RFC-WF-0011 (CATS)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies Well-Known Discovery & Interop Endpoints (WKD) for WhatsApp-first systems. WKD defines a standardized discovery mechanism (via .well-known) for locating a system’s Command Registry (CRCD), Evidence Artifact interfaces (EAS), Observability over Conversation (OoC) capabilities, and Compliance Audit (CATS) entrypoints. WKD enables portable tooling, automated audits, and ecosystem interoperability without bespoke integration per system.

Index Terms— discovery, .well-known, interoperability, capability registry, evidence query, compliance tooling, WhatsApp-first.

I. Introduction

A specification becomes an ecosystem when tools can discover and validate implementations reliably. In WhatsApp-first, auditors and developer tools need to locate:

the declared capabilities/commands (CRCD)
evidence artifacts and query interfaces (EAS)
OoC command endpoints (what to call, how to call)
compliance audit metadata (CATS)

Without a discovery standard, every implementation invents its own URLs and formats. WKD standardizes these entrypoints.

II. Scope

WKD specifies:

Required .well-known endpoints
A canonical discovery document format (wfs.json)
Minimum metadata to locate CRCD/EAS/OoC/CATS artifacts
Content types, caching rules, and versioning
Security and redaction expectations for public vs privileged discovery

WKD does not mandate authentication methods; it declares how discovery documents describe them.

III. Normative Language

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are normative.

IV. Definitions

Discovery Document: A machine-readable document that advertises interop endpoints and versions.
Interop Endpoint: An HTTP endpoint or resource path used by tools to fetch registries or query evidence.
Privileged Endpoint: An endpoint requiring authorization scopes.

V. Design Goals

WKD MUST ensure:

G1. Toolability: generic tooling can discover the system without manual config
G2. Versioned Contracts: endpoints declare spec versions and registry versions
G3. Least Disclosure: public discovery can be safely minimal; privileged expansion via auth
G4. Portability: audits and frameworks can be applied across systems consistently

VI. Required Well-Known Locations

A WKD-compliant system MUST host:

/.well-known/wfs.json — the primary discovery document
/.well-known/wfs/crcd.json — a default location for CRCD (MAY redirect)
/.well-known/wfs/eas/schema.json — a default location for EAS JSON Schema (MAY redirect)

If a system cannot host the defaults directly (e.g., multi-tenant routing), it MUST provide functional equivalents via wfs.json.

VII. Discovery Document: `/.well-known/wfs.json`

A. Content Type

The server MUST return:

Content-Type: application/json

B. Caching

The server SHOULD set cache headers appropriate for discovery:

Cache-Control: max-age=300 (recommended)
and SHOULD provide ETag for efficient tooling

C. Minimum Required Fields

The discovery document MUST include:

wfs_spec_version (SemVer)
system block (id, environment)
endpoints block with resolvable URLs for CRCD and evidence query
auth block describing how endpoints are protected (high-level)

D. Example `wfs.json`

```json id="7snxq9"
{
"wfs_spec_version": "1.0.0",
"system": {
"system_id": "acme-pharma-wos",
"environment": "staging",
"region": "sa-east-1"
},
"endpoints": {
"crcd_registry": {
"url": "/.well-known/wfs/crcd.json",
"registry_version": "1.2.0"
},
"eas_schema": {
"url": "/.well-known/wfs/eas/schema.json",
"eas_version": "1.0.0"
},
"evidence_query": {
"url": "/.well-known/wfs/evidence/query",
"methods": ["POST"],
"requires_auth": true
},
"ooc": {
"mode": "command",
"entrypoints": [
{ "channel": "whatsapp", "command_prefix": "OOC.", "requires_auth": true }
]
},
"cats": {
"manifest_version": "1.0.0",
"controls_catalog": {
"url": "/.well-known/wfs/cats/controls.json",
"requires_auth": false
}
}
},
"auth": {
"type": "bearer_or_dpop",
"scopes_model": "acsm",
"public_discovery_redacted": true
}
}




---

## VIII. Evidence Query Interop (Minimum Contract)

If `evidence_query` is present, it MUST accept a JSON body supporting at least one of:

* `command_id`
* `correlation_id`
* `artifact_id`

### A. Minimal Request



```json
{ "command_id": "..." }

B. Minimal Response

The response MUST return:

a list of EAS artifacts (or references)
pagination tokens if needed
redaction applied based on caller scope

WKD does not define the complete query language; it defines the minimum viable interop for tools.

IX. Public vs Privileged Discovery

A. Public Discovery

Systems MAY expose a redacted wfs.json publicly. If so, it MUST NOT disclose:

internal topology
sensitive service names (optional)
secret-bearing endpoints
tenant identifiers

B. Privileged Discovery

Systems MAY provide expanded discovery when authenticated, including:

additional endpoints
richer registry metadata
diagnostics endpoints

X. Multi-Tenant Considerations

For multi-tenant systems, the discovery document MUST specify how tenant scoping is applied, e.g.:

subdomain per tenant
header-based tenant routing
path prefix (/t/{tenant_id}/...)

Tooling MUST be able to resolve endpoints deterministically given a tenant context.

XI. Relationship to Other RFCs

WFCS (0001): WKD supports operational parity and audit without dashboards.
CRCD (0005): WKD exposes the registry location and version.
EAS (0006): WKD exposes schema and evidence query entrypoints.
OoC (0007): WKD advertises OoC entrypoints and command prefixes.
CATS (0011): WKD enables automated audit tooling to bootstrap.

XII. Security Considerations

Discovery increases attack surface. Implementations MUST:

avoid leaking sensitive details in public discovery
protect privileged endpoints with authorization (ACSM model)
rate-limit evidence query endpoints
ensure evidence responses apply redaction consistently

XIII. Conclusion

WKD makes WhatsApp-first implementations discoverable and interoperable. By standardizing .well-known entrypoints for CRCD, EAS, OoC, and CATS, it enables portable tooling, automated audits, and ecosystem-level reuse—turning the WhatsApp-first Specification into something implementable at scale.

References

[1] RFC-WF-0001, WhatsApp-First Compliance Core (WFCS).
[2] RFC-WF-0005, Command Registry & Capability Declaration (CRCD).
[3] RFC-WF-0006, Evidence Artifact Schema (EAS).
[4] RFC-WF-0007, Observability over Conversation (OoC).
[5] RFC-WF-0011, Compliance Audit Toolkit Spec (CATS).

Concepts and Technologies

.well-known discovery, interop endpoints, registry discovery, evidence query bootstrap, spec versioning, cacheable discovery docs, redacted public metadata, multi-tenant endpoint resolution.

DEV Community