Protocols

Three protocol layers power the Weblisk platform — client-facing HTTP transports, the agent wire protocol with Ed25519 identity, and the federation protocol for cross-boundary collaboration.

Protocol Layers

Client Protocols

Blueprint-generated endpoints use standard web protocols. Every endpoint supports JSON request and response bodies, standard HTTP status codes, and content negotiation.

REST / HTTP

• GET — read resources (list + detail)
• POST — create resources or dispatch RPC calls
• PUT — replace a resource
• PATCH — partial update
• DELETE — remove a resource

WebSocket

For real-time features, servers expose a WebSocket endpoint at /ws. The message format is JSON with a type field for routing:

Server-Sent Events

For unidirectional server push, the SSE endpoint at /events streams updates. Useful for live dashboards, notifications, and progress tracking where bidirectional communication isn't needed.

Agent Wire Protocol

All agent-to-orchestrator and agent-to-agent communication uses HTTP + JSON with Ed25519 cryptographic identity. See Specification for the endpoint contracts.

Identity & Key Management

Every agent and orchestrator generates an Ed25519 key pair (RFC 8032) on first startup:

• Algorithm: Ed25519 — 32-byte public key, 64-byte private key
• Encoding: hex for protocol exchange (64 chars public, 128 chars private)
• Storage: .weblisk/keys/<name>.key (mode 0600) and .weblisk/keys/<name>.pub (mode 0644)
• Algorithm agility: the token header alg field allows future swap to post-quantum algorithms (e.g. ML-DSA / FIPS 204) with zero protocol changes

1. Check if .weblisk/keys/<name>.key exists
2. If yes: read and decode hex → Ed25519 private key → derive public key
3. If no:  generate new key pair → save both files → return

Message Signing

All protocol messages can be signed for integrity and non-repudiation:

Registration signature: agents sign their manifest with their private key. The orchestrator verifies using manifest.public_key and enforces a 300-second replay window on the timestamp.

Agent-to-agent messages: signature covers JSON.stringify({from, to, action, payload}). The receiver looks up the sender's public key from the service directory and verifies before processing.

WLT Token System

Tokens are self-contained signed claims for authentication. The verifier only needs the issuer's public key.

base64url(header) . base64url(payload) . base64url(signature)

// Header
{"alg": "Ed25519", "typ": "WLT"}

// Payload (claims)
{
  "sub": "seo",          // subject — agent name
  "iss": "orchestrator", // issuer
  "iat": 1712160000,     // issued at (Unix epoch)
  "exp": 1712246400,     // expires at (0 = no expiry)
  "cap": ["file:read", "llm:chat", "agent:message"],
  "cid": ""             // channel ID (for channel-scoped tokens)
}

Token Creation

1. Serialise header to JSON → base64url encode → headerB64
2. Serialise payload to JSON → base64url encode → payloadB64
3. signingInput = headerB64 + "." + payloadB64
4. signature = Ed25519.Sign(privateKey, bytes(signingInput))
5. token = signingInput + "." + base64url(signature)

Token Verification

1. Split token on "." → must have exactly 3 parts
2. Decode header → verify alg == "Ed25519"
3. signingInput = parts[0] + "." + parts[1]
4. Decode signature from parts[2]
5. Verify: Ed25519.Verify(issuerPublicKey, bytes(signingInput), signature)
6. Decode payload → parse claims
7. If exp > 0 and current_time > exp → token expired
8. Return claims

Token Lifetimes

Service Broadcasting

After any registration or deregistration, the orchestrator asynchronously pushes the current ServiceDirectory to every other registered agent via POST /v1/services. Failures are logged but never block. Each agent updates its internal service list (thread-safe) to enable service discovery and direct messaging.

Federation Protocol

Federation enables orchestrators to collaborate across organisational boundaries — exposing agent capabilities to partners without exposing internal systems, data, or infrastructure. Every cross-boundary interaction is governed by data contracts, trust tiers, and behavioural verification.

Federation treats data protection as a structural constraint, not a policy afterthought. Unpermitted fields physically cannot cross a boundary because the architecture strips them before transmission.

Federation Endpoints

Trust Tiers

Peering Flow

Two orchestrators establish trust through a mutual exchange:

Orchestrator A                          Orchestrator B
───────────────                         ───────────────

1. Admin initiates peering
   with B's federation_url

2. POST /v1/federation/peer ──────►
   {manifest, requested_capabilities,
    data_contracts, signature}

                                ◄────── 3. B validates:
                                           a. Verify A's signature
                                           b. Check jurisdiction
                                           c. Review capabilities
                                           d. Admin approves

                                ◄────── 4. POST /v1/federation/peer-accept
                                           {manifest, granted_capabilities,
                                            data_contracts, trust_tier,
                                            expires_at, signature}

5. A validates B's signature
6. A stores B's public key +
   granted capabilities
7. Federation link established

Trust relationships MUST have an explicit expiry (default: 90 days), are renewable without disruption, can be revoked immediately by either party, and are not transitive — A trusts B and B trusts C does NOT mean A trusts C.

Key Rotation

When an orchestrator rotates its Ed25519 key pair, it signs a KeyRotation message with both the old and new keys (dual-signature proof). Peers verify both signatures, then update the stored public key after effective_at. A 24-hour grace period accepts both keys during the transition.

Data Boundary Contracts

The most critical component of federation. A data contract defines exactly what data MAY cross a trust boundary and in what form.

{
  "name": "seo-audit-v1",
  "version": "1.0.0",
  "direction": "bidirectional",

  "inbound": {
    "required":  [{"field": "html_content", "type": "text", "max_size": "1MB"}],
    "permitted": [{"field": "url"}, {"field": "language"}],
    "forbidden": ["*.customer_id", "*.email", "*.pii.*", "*.credentials.*"],
    "transformations": [{"field": "url", "action": "strip_query_params"}]
  },

  "outbound": {
    "required":  [{"field": "seo_score"}, {"field": "findings"}],
    "permitted": ["findings[*].severity", "findings[*].element", "recommendations[*].proposed"],
    "forbidden": ["*.raw_content", "*.agent_logs", "*.debug_*"]
  },

  "data_retention": {"max_hours": 24, "action": "delete", "audit_required": true},
  "jurisdiction_requirements": {"allowed": ["US", "CA", "GB", "EU"], "data_residency": "origin"},
  "signature": "<signed by contract author>"
}

Contract Enforcement

Enforcement is fail-closed — if a field is not explicitly required or permitted, it is rejected. This prevents data leakage through new fields added by updated agents.

Before sending data to a federated agent:

1. Serialise the outbound payload
2. Apply forbidden patterns — recursively walk JSON and remove matching fields
3. Apply transformations (strip_query_params, hash, redact, etc.)
4. Validate required fields are present
5. Validate remaining fields are in the permitted set
6. If any forbidden field was present, log a DATA_BOUNDARY_VIOLATION audit entry
7. Sign the sanitised payload and send

Before accepting data from a federated agent: verify signature, apply inbound forbidden patterns, validate all fields against the required/permitted sets, and reject unknown fields entirely.

Behavioural Integrity

Trust is not just about identity — it's about behaviour. When an agent registers, the orchestrator computes a behavioural fingerprint from its manifest (hash of manifest, capabilities, input/output schemas). On every re-registration or manifest update, changes are classified:

Runtime behavioural monitoring also watches for output field expansion, data volume anomalies, error rate spikes, latency anomalies, and capability creep.

Cross-Boundary Task Execution

When an orchestrator delegates a task to a peer's agent through federation:

Orchestrator A (requester)              Orchestrator B (provider)
──────────────────────                  ──────────────────────

1. Domain controller selects
   federated agent for a workflow phase

2. Build FederatedTaskRequest:
   - payload (data-contract-filtered)
   - contract_name: "seo-audit-v1"
   - signed by A's key

3. POST /v1/federation/task ──────►
                                        4. Verify A's signature
                                        5. Verify A is a trusted peer
                                        6. Verify contract_name matches
                                           a granted capability
                                        7. Apply INBOUND data contract
                                        8. Route to internal domain/agent
                                        9. Execute task
                                       10. Apply OUTBOUND data contract
                                       11. Sign result with B's key

                                ◄────── 12. Return FederatedTaskResult

13. Verify B's signature
14. Apply INBOUND data contract (on result)
15. Return sanitised result to workflow
16. Log federation audit entry (both sides)

Data Sovereignty

Every orchestrator declares its primary jurisdiction (ISO 3166-1). Before routing a federated task, the system checks the target's jurisdiction against the data contract's allowed list. Data residency mode "origin" means the receiving orchestrator MUST NOT persist cross-boundary data beyond the processing window.

Retention enforcement: cross-boundary data has an explicit lifecycle — after task completion or retention expiry, data is purged or anonymised, and the event is logged in the audit trail. Cross-boundary data MUST NOT be retained in observation stores, recommendation stores, caches, or backup systems.

Security Layers

Federation security is defence-in-depth — seven independent layers, all enforced concurrently:

No single layer is sufficient alone. Together, they make data leakage structurally impossible rather than policy-dependent.

Security Checklist

• Keys generated with cryptographically secure random source
• Private keys stored with restricted permissions (0600)
• All signatures verified before trusting data
• Token expiry checked on every verification
• Replay protection enforced (300-second window on registration)
• Public key length validated (32 bytes / 64 hex chars)
• Signature length validated (64 bytes / 128 hex chars)
• Constant-time comparison for signature verification
• Private keys never logged or exposed
• Trust relationships have explicit expiry (default 90 days)
• Data contracts enforced fail-closed (unknown fields rejected)
• Forbidden field patterns recursively applied to all JSON
• BREAKING/CRITICAL behavioural changes suspend agents from federation
• Cross-boundary data purged within retention window
• TLS 1.3 required for all federation endpoints
• Full cross-boundary audit trail on both sides