Version: 1.0
Date: 2026-03-21
Applies to: acp_relay.py v1.0.0+

ACP provides two optional, independent security mechanisms:

Both can be active simultaneously — they are complementary, not mutually exclusive.

What ACP does NOT provide:

• Confidentiality (messages are plaintext over WebSocket/HTTP)
• Forward secrecy
• Key exchange / key agreement protocol
• Certificate authority or PKI

For confidentiality, terminate TLS at a load balancer or reverse proxy (see §4).

When --secret <key> is configured, every outbound message is signed:

sig = HMAC-SHA256(secret_bytes, "{message_id}:{ts}").hexdigest()

The resulting hex string is appended as the sig field to the message envelope.

Inbound verification: if sig is present in a received message and a secret is configured, the relay verifies using hmac.compare_digest() (constant-time, no timing oracle). On mismatch:

• A warning is logged
• The message is not dropped (warn-only, per ACP spec §7.1)
• The message object has _sig_invalid=true set for application-level inspection

If no secret is configured, sig fields in received messages are silently ignored (backward-compatible interoperability).

ACP HMAC enforces a server-side timestamp window check when --secret is set.

• Mechanism: inbound ts field (ISO-8601 UTC) is compared to server clock. If |now - ts| > HMAC_REPLAY_WINDOW, the message is dropped (hard reject, not warn).
• Default window: 300 seconds (5 minutes) — configurable via --hmac-window <seconds>.
• Config file: key hmac-window in JSON/YAML config is also supported.
• Graceful degradation: when --secret is not set, the window check is skipped (no-op).

Example:

acp-relay --secret mysecret --hmac-window 120  # 2-minute window

Risk level: Window value should balance clock-skew tolerance vs. replay risk. For high-security deployments, use 60–120 s; for normal agent-to-agent, 300 s is sufficient.

When --identity [path] is configured, every outbound message includes an identity block:

"identity": {
  "scheme":     "ed25519",
  "public_key": "<base64url 32-byte public key>",
  "sig":        "<base64url 64-byte Ed25519 signature>"
}

Signing input: canonical JSON of the full message envelope, excluding identity.sig:

canonical = {k: v for k, v in msg.items() if k != "identity"}
payload = json.dumps(canonical, sort_keys=True, ensure_ascii=False, separators=(",",":")).encode()

The canonical form uses sort_keys=True and compact separators to ensure byte-for-byte reproducibility across implementations.

Keypair storage: ~/.acp/identity.json (auto-generated on first run, chmod 0600).

Verification: warn-only on mismatch; message is accepted even if cryptography not installed.

HMAC and Ed25519 may be active simultaneously:

acp-relay --secret "shared-key" --identity

• HMAC sig is computed first, then included in the Ed25519 signing payload
• This means Ed25519 signature covers the HMAC sig — no ordering vulnerability
• AgentCard reports both: capabilities.hmac_signing=true and capabilities.identity="ed25519"

ACP over plain HTTP/WS provides no confidentiality. For production deployments:

[Agent A] ──WebSocket──► [nginx/caddy TLS termination] ──► [Agent B :7801]
[Client]  ──HTTPS──────► [nginx/caddy TLS termination] ──► [relay :7901]

Example (Caddy):

youragent.example.com {
    reverse_proxy localhost:7901
    reverse_proxy /ws localhost:7801
}

cloudflared tunnel --url http://localhost:7901
# Provides HTTPS + certificate automatically

acp-relay --relay "acp+wss://your-worker.workers.dev/..."

This transport uses HTTPS by default. See transports.md §Binding-C.

Security questions or disclosures: open an issue at https://github.com/Kickflip73/agent-communication-protocol/issues