NL Protocol Specification v1.0 -- Chapter 08: Wire Protocol, Transport & Error Handling

Status: Draft Version: 1.0.0 Date: 2026-02-08

Note: This document is a SPECIFICATION. It defines required behaviors, data formats, and protocols — not specific products or CLI commands. For implementations of this specification, see IMPLEMENTATIONS.md.

1. Introduction

Chapters 01 through 07 of the NL Protocol define what components communicate: agent identities, action requests, scope grants, audit records, delegation tokens, and revocation signals. This chapter defines how those messages are transported between components -- the wire format, transport bindings, API surface, error taxonomy, service discovery, and operational mechanisms that enable interoperability between independently developed NL-compliant implementations.

Without a wire protocol specification, two implementations that both conform to Chapters 01-07 may be unable to communicate. Implementation A might encode messages as Protocol Buffers over gRPC while Implementation B expects JSON over REST. Implementation A might return errors as HTTP 500 with plain text bodies while Implementation B expects structured error objects with machine-readable codes. This chapter eliminates such incompatibilities.

1.1 Goals

This chapter aims to:

1. Enable interoperability. Two NL-compliant systems from different vendors MUST be able to exchange messages without vendor-specific adaptation.
2. Define a canonical message format. All NL Protocol messages MUST have a single, unambiguous JSON representation.
3. Standardize error handling. Every failure mode in the protocol MUST map to a well-defined error code with consistent structure.
4. Support multiple transports. The protocol MUST work over local IPC, HTTP, and within the MCP ecosystem.
5. Enable discovery. NL-compliant systems MUST be discoverable through a well-known endpoint.

1.2 Relationship to Other Chapters

This chapter is a cross-cutting concern that touches every other chapter:

• Chapter 01 (Agent Identity): Defines the registration and identity verification API endpoints and message formats.
• Chapter 02 (Action-Based Access): Defines the action request/response wire format and the scope grant management API.
• Chapter 03 (Execution Isolation): Transport is orthogonal to isolation; the isolation boundary exists within the NL Provider regardless of transport.
• Chapter 04 (Pre-Execution Defense): Error codes for blocked actions are defined here.
• Chapter 05 (Audit Integrity): Defines the audit query API endpoint and audit export format.
• Chapter 06 (Attack Detection): Error codes for detected attacks are defined here.
• Chapter 07 (Cross-Agent Trust): Defines the delegation and revocation API endpoints and the federated transport requirements (mTLS).

2. Transport Bindings

The NL Protocol is transport-agnostic at its core: the message semantics defined in Chapters 01-07 are independent of how messages move between components. However, to ensure interoperability, this section defines standard transport bindings with specific requirements for each.

2.1 Transport Overview

+========================================================================+
|                      NL PROTOCOL TRANSPORT BINDINGS                     |
+========================================================================+
|                                                                        |
|  LOCAL (Same-Host) Transports                                          |
|  +------------------------------------------------------------------+ |
|  | Unix Domain Sockets   | RECOMMENDED for local agent-to-provider  | |
|  | stdin/stdout Pipes    | MUST for MCP-style subprocess servers    | |
|  | Local HTTP (loopback) | MAY for development and debugging        | |
|  +------------------------------------------------------------------+ |
|                                                                        |
|  Network Transports                                                    |
|  +------------------------------------------------------------------+ |
|  | HTTPS (TLS 1.2+)     | MUST for all network communication       | |
|  | mTLS                  | SHOULD for cross-organization federation | |
|  | gRPC over TLS         | MAY as an alternative to HTTP/JSON       | |
|  +------------------------------------------------------------------+ |
|                                                                        |
|  Agent Framework Integration                                           |
|  +------------------------------------------------------------------+ |
|  | MCP (stdio transport) | RECOMMENDED for AI agent ecosystems      | |
|  | MCP (SSE transport)   | MAY for web-based agent frontends        | |
|  | A2A Protocol          | MAY for inter-agent delegation messages  | |
|  +------------------------------------------------------------------+ |
|                                                                        |
+========================================================================+

2.2 Local Transport: Unix Domain Sockets

Unix domain sockets are the RECOMMENDED transport for same-host communication between an agent process and an NL Provider process.

Socket path convention:

/tmp/nl-protocol/<organization_id>/<provider_id>.sock

Or, using the XDG runtime directory when available:

$XDG_RUNTIME_DIR/nl-protocol/<provider_id>.sock

Requirements:

Handshake message:

{
  "nl_version": "1.0",
  "message_type": "handshake",
  "message_id": "msg_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-08T10:00:00.000Z",
  "payload": {
    "agent_uri": "nl://anthropic.com/claude-code/1.5.2",
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "credential": "nlk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "attestation": "eyJhbGciOiJFUzI1NiIs..."
  }
}

Handshake response:

{
  "nl_version": "1.0",
  "message_type": "handshake_ack",
  "message_id": "msg_660f9511-f30c-52e5-b827-557766551111",
  "timestamp": "2026-02-08T10:00:00.050Z",
  "payload": {
    "status": "authenticated",
    "session_id": "sess_770a0622-a41d-63f6-c938-668877662222",
    "server_capabilities": {
      "nl_version": "1.0",
      "action_types": ["exec", "template", "inject_stdin", "inject_tempfile", "sdk_proxy"],
      "max_message_size_bytes": 1048576,
      "rate_limit": {
        "requests_per_minute": 120
      }
    }
  }
}

2.3 Local Transport: stdin/stdout Pipes

The stdin/stdout transport is REQUIRED for implementations that integrate with the Model Context Protocol (MCP) using the stdio transport. In this model, the NL Provider runs as a subprocess of the agent host, and communication occurs through the process's standard streams.

Requirements:

Example interaction (stdin/stdout):

--> stdin:  {"nl_version":"1.0","message_type":"action_request","message_id":"msg_001",...}\n
<-- stdout: {"nl_version":"1.0","message_type":"action_response","message_id":"msg_002",...}\n

2.4 Local Transport: HTTP over Loopback

Implementations MAY support HTTP over the loopback interface (127.0.0.1 or ::1) for local development and debugging. This binding follows the same API surface as the network HTTP binding (Section 5) but operates over unencrypted HTTP on loopback only.

Requirements:

2.5 Network Transport: HTTPS

HTTPS is the REQUIRED transport for all network communication between NL-compliant systems that are not on the same host.

Requirements:

2.6 Network Transport: mTLS

Mutual TLS (mTLS) is the RECOMMENDED transport for cross-organization federation (Chapter 07, Section 6). In mTLS, both the client and server present certificates, providing mutual authentication at the transport layer.

Requirements:

2.7 Network Transport: gRPC

Implementations MAY support gRPC as an alternative to HTTP/JSON for high-throughput or latency-sensitive deployments.

Requirements (when gRPC is supported):

2.8 MCP Integration

The Model Context Protocol (MCP) is the primary mechanism by which AI agents discover and invoke tools. NL Protocol operations SHOULD be exposed as MCP tools so that NL-compliant systems integrate naturally into the AI agent ecosystem.

MCP tool mapping:

MCP tool definition example (nl_execute_action):

{
  "name": "nl_execute_action",
  "description": "Execute an action that requires secrets. Secrets are referenced using {{nl:...}} placeholders and are NEVER returned to the agent. Only the action result is returned.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action_type": {
        "type": "string",
        "enum": ["exec", "template", "inject_stdin", "inject_tempfile", "sdk_proxy", "delegate"],
        "description": "The type of action to perform."
      },
      "template": {
        "type": "string",
        "description": "Command template with {{nl:...}} placeholders for secrets."
      },
      "context": {
        "type": "object",
        "properties": {
          "project": { "type": "string" },
          "environment": { "type": "string" }
        }
      },
      "purpose": {
        "type": "string",
        "description": "Why this action is needed. Recorded in audit trail."
      },
      "timeout_ms": {
        "type": "integer",
        "default": 30000,
        "description": "Maximum execution time in milliseconds."
      },
      "dry_run": {
        "type": "boolean",
        "default": false,
        "description": "Validate permissions without executing."
      }
    },
    "required": ["action_type", "template"]
  }
}

MCP integration requirements:

3. Message Format

3.1 Canonical Encoding

JSON is the canonical encoding for all NL Protocol messages. Every NL-compliant system MUST support JSON encoding. Systems that additionally support other encodings (Protocol Buffers, MessagePack, CBOR) MUST ensure lossless round-trip conversion to and from JSON.

Requirements:

3.2 Media Type

The NL Protocol defines a custom media type for its messages:

application/nl-protocol+json

This media type MUST be used in the Content-Type header for HTTP requests and responses carrying NL Protocol messages. Implementations MUST also accept application/json for backward compatibility, but SHOULD prefer the custom media type.

Registration details (per RFC 6838):

3.3 Message Envelope

Every NL Protocol message -- regardless of transport -- MUST be wrapped in a standard envelope:

{
  "nl_version": "1.0",
  "message_type": "<type>",
  "message_id": "<uuid-v4>",
  "timestamp": "<ISO-8601 UTC with milliseconds>",
  "payload": { }
}

Envelope field definitions:

3.4 Message Types

The following message types are defined by the NL Protocol v1.0:

+==========================================================================+
|                        NL PROTOCOL MESSAGE TYPES                          |
+==========================================================================+
|                                                                          |
|  Identity & Registration (Chapter 01)                                    |
|  +--------------------------------------------------------------------+ |
|  | handshake              | Initial connection authentication          | |
|  | handshake_ack          | Server acknowledgment of handshake        | |
|  | agent_register         | Register a new agent                      | |
|  | agent_register_ack     | Registration response with AID            | |
|  | agent_get              | Retrieve agent identity                   | |
|  | agent_get_response     | Agent identity document                   | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Action Lifecycle (Chapters 02, 03, 04)                                  |
|  +--------------------------------------------------------------------+ |
|  | action_request         | Submit an action for execution             | |
|  | action_response        | Action result (success, denied, error)     | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Delegation & Revocation (Chapter 07)                                    |
|  +--------------------------------------------------------------------+ |
|  | delegation_request     | Request a delegation token                 | |
|  | delegation_response    | Delegation token reference                 | |
|  | delegation_revoke      | Revoke a delegation token                  | |
|  | delegation_revoke_ack  | Revocation acknowledgment                  | |
|  | revocation_request     | Revoke an agent or scope                   | |
|  | revocation_response    | Revocation result                          | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Audit (Chapter 05)                                                      |
|  +--------------------------------------------------------------------+ |
|  | audit_query            | Query the audit log                        | |
|  | audit_query_response   | Audit query results                        | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Discovery & Operational (Chapter 08)                                    |
|  +--------------------------------------------------------------------+ |
|  | discovery_request      | Request server capabilities                | |
|  | discovery_response     | Server capabilities and endpoints          | |
|  | error                  | Standalone error message                   | |
|  | rotation_notification  | Secret rotation notification               | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Federation (Chapter 07)                                                 |
|  +--------------------------------------------------------------------+ |
|  | federated_action       | Cross-organization action request          | |
|  | federated_response     | Cross-organization action response         | |
|  | federation_revocation  | Cross-organization revocation propagation  | |
|  | federation_revocation_ack | Revocation propagation acknowledgment   | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
+==========================================================================+

Payload schemas: Each message type's payload schema is defined in the chapter that governs the corresponding operation. The following table maps message types to their payload schemas:

3.5 Message ID Requirements

Message IDs serve three purposes: correlation, idempotency, and replay prevention.

1. Correlation: A response message SHOULD include a correlation_id field in its payload that references the message_id of the request it responds to.

2. Idempotency: If a sender retransmits a message with the same message_id, the receiver MUST return the same response without re-executing the operation. Implementations MUST maintain an idempotency cache for at least 5 minutes.

3. Replay prevention: Receivers MUST reject messages with a message_id that has already been processed (within the idempotency window). The rejection MUST use error code NL-E802.

3.6 Timestamp Requirements

All timestamps in NL Protocol messages MUST conform to:

• ISO 8601 format with millisecond precision.
• UTC timezone (indicated by trailing Z).
• Example: "2026-02-08T10:30:00.000Z".

Implementations MUST reject messages with timestamps more than 5 minutes in the future (allowing for clock skew). Implementations SHOULD reject messages with timestamps more than 5 minutes in the past for real-time transports (not applicable to audit queries).

4. Full Message Examples

4.1 Action Request (Complete Wire Format)

{
  "nl_version": "1.0",
  "message_type": "action_request",
  "message_id": "msg_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-08T14:30:00.000Z",
  "payload": {
    "agent": {
      "agent_uri": "nl://anthropic.com/claude-code/1.5.2",
      "instance_id": "550e8400-e29b-41d4-a716-446655440000",
      "attestation": "eyJhbGciOiJFUzI1NiIs..."
    },
    "action": {
      "type": "exec",
      "template": "curl -H 'Authorization: Bearer {{nl:api/GITHUB_TOKEN}}' https://api.github.com/user",
      "context": {
        "project": "braincol",
        "environment": "development"
      },
      "purpose": "Verify GitHub API access for CI setup",
      "timeout_ms": 30000,
      "dry_run": false
    }
  }
}

4.2 Action Response (Success)

{
  "nl_version": "1.0",
  "message_type": "action_response",
  "message_id": "msg_660f9511-f30c-52e5-b827-557766551111",
  "timestamp": "2026-02-08T14:30:00.250Z",
  "payload": {
    "correlation_id": "msg_550e8400-e29b-41d4-a716-446655440000",
    "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
    "action_id": "act_660f9511-f30c-52e5-b827-557766551111",
    "status": "success",
    "result": {
      "stdout": "{\"login\":\"acme-bot\",\"id\":12345}",
      "stderr": "",
      "exit_code": 0
    },
    "secrets_used": ["api/GITHUB_TOKEN"],
    "redacted": false,
    "redacted_count": 0,
    "audit_ref": "aud_770a0622-a41d-63f6-c938-668877662222",
    "timing": {
      "received_at": "2026-02-08T14:30:00.000Z",
      "resolved_at": "2026-02-08T14:30:00.050Z",
      "executed_at": "2026-02-08T14:30:00.055Z",
      "completed_at": "2026-02-08T14:30:00.250Z",
      "total_ms": 250
    }
  }
}

4.3 Action Response (Error)

{
  "nl_version": "1.0",
  "message_type": "action_response",
  "message_id": "msg_770a0622-a41d-63f6-c938-668877662222",
  "timestamp": "2026-02-08T14:30:00.050Z",
  "payload": {
    "correlation_id": "msg_550e8400-e29b-41d4-a716-446655440000",
    "status": "denied",
    "error": {
      "code": "NL-E200",
      "message": "No active Scope Grant covers secret 'production/DB_PASSWORD' for action type 'exec'.",
      "detail": {
        "secret_ref": "production/DB_PASSWORD",
        "action_type": "exec",
        "agent_scope": {
          "environments": ["development", "staging"]
        },
        "required_scope": {
          "environments": ["production"]
        }
      },
      "resolution": "Request a Scope Grant for the 'production' environment from your administrator.",
      "doc_url": "https://nlprotocol.org/docs/errors/NL-E200"
    },
    "secrets_used": [],
    "redacted": false,
    "audit_ref": "aud_880b1733-b52e-74a7-d049-779988773333"
  }
}

4.4 Delegation Request

{
  "nl_version": "1.0",
  "message_type": "delegation_request",
  "message_id": "msg_880b1733-b52e-74a7-d049-779988773333",
  "timestamp": "2026-02-08T14:35:00.000Z",
  "payload": {
    "issuer": "nl://anthropic.com/claude-code/1.5.2",
    "issuer_instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "subject": "nl://acme.corp/deploy-bot/2.1.0",
    "scope": {
      "secrets": ["k8s/DEPLOY_TOKEN"],
      "actions": ["exec"],
      "max_uses": 1,
      "resource_constraints": {
        "exec": {
          "allowed_commands": ["kubectl apply *"]
        }
      }
    },
    "ttl_seconds": 300
  }
}

4.5 Rotation Notification

{
  "nl_version": "1.0",
  "message_type": "rotation_notification",
  "message_id": "msg_990c2844-c63f-85b8-e150-880099884444",
  "timestamp": "2026-02-08T15:00:00.000Z",
  "payload": {
    "secret_ref": "api/GITHUB_TOKEN",
    "previous_version": "v3",
    "new_version": "v4",
    "rotation_id": "rot_aa0d3955-d740-96c9-f261-991100995555",
    "grace_period_ends": "2026-02-08T16:00:00.000Z",
    "reason": "scheduled_rotation"
  }
}

5. API Endpoints (HTTP/REST Binding)

For the HTTP transport binding, the NL Protocol defines a RESTful API surface. All endpoints are relative to a base URL that is advertised through the discovery mechanism (Section 7).

5.1 Base URL Convention

https://<host>:<port>/nl/v1

The version segment (v1) corresponds to the major version of the NL Protocol. When a new major version is released, a new base path (/nl/v2) MUST be used.

5.2 Endpoint Summary

+==========================================================================+
|                        NL PROTOCOL API ENDPOINTS                          |
+==========================================================================+
|                                                                          |
|  Identity & Registration                                                 |
|  +--------------------------------------------------------------------+ |
|  | POST   /nl/v1/agents/register     | Register a new agent           | |
|  | GET    /nl/v1/agents/{agent_id}    | Get agent identity document    | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Actions                                                                 |
|  +--------------------------------------------------------------------+ |
|  | POST   /nl/v1/actions              | Submit an action request       | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Delegation & Revocation                                                 |
|  +--------------------------------------------------------------------+ |
|  | POST   /nl/v1/delegations          | Create a delegation token      | |
|  | DELETE /nl/v1/delegations/{id}     | Revoke a delegation token      | |
|  | POST   /nl/v1/revocations          | Revoke an agent or scope       | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Audit                                                                   |
|  +--------------------------------------------------------------------+ |
|  | GET    /nl/v1/audit                | Query audit log                | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
|  Discovery & Health                                                      |
|  +--------------------------------------------------------------------+ |
|  | GET    /.well-known/nl-protocol    | Discovery endpoint             | |
|  | GET    /nl/v1/health               | Health check                   | |
|  +--------------------------------------------------------------------+ |
|                                                                          |
+==========================================================================+

5.3 Endpoint Specifications

5.3.1 POST /nl/v1/agents/register

Register a new agent with the NL-compliant system.

5.3.2 GET /nl/v1/agents/{agent_id}

Retrieve the Agent Identity Document for a registered agent.

5.3.3 POST /nl/v1/actions

Submit an action request for execution.

5.3.4 POST /nl/v1/delegations

Create a delegation token.

5.3.5 DELETE /nl/v1/delegations/{token_id}

Revoke a delegation token.

5.3.6 GET /nl/v1/audit

Query the audit log.

5.3.7 POST /nl/v1/revocations

Revoke an agent or scope.

5.3.8 GET /.well-known/nl-protocol

Discovery endpoint. See Section 7 for full specification.

5.3.9 GET /nl/v1/health

Health check endpoint for load balancers and monitoring.

5.4 Common HTTP Headers

All HTTP requests to the NL Protocol API MUST include:

All HTTP responses from the NL Protocol API MUST include:

6. Error Handling

6.1 Design Principles

Error handling in the NL Protocol follows three principles:

1. Structured and machine-readable. Every error response MUST be a valid JSON object with a consistent schema. Agents and automation MUST be able to parse and act on error responses programmatically.

2. Informative and educational. Error responses MUST include a human-readable message, a machine-readable code, and a resolution suggestion. Following the design philosophy of Chapter 04 (Pre-Execution Defense): "Educate, do not merely block."

3. No secret leakage. Error responses MUST NOT contain secret values, even when the error is related to secret resolution or access. Error messages MUST reference secrets by name or path, NEVER by value.

6.2 Error Response Format

All error responses MUST conform to the following structure, which is inspired by RFC 7807 (Problem Details for HTTP APIs):

{
  "error": {
    "code": "NL-EXXX",
    "message": "Human-readable error description.",
    "detail": {
    },
    "resolution": "Suggested action to resolve the error.",
    "doc_url": "https://nlprotocol.org/docs/errors/NL-EXXX"
  }
}

Error object field definitions:

When an error occurs within an action response, the error object is embedded in the action response payload (as shown in Chapter 02, Section 7.4). When an error occurs outside of an action context (e.g., malformed request, authentication failure), the error is returned as a standalone message with message_type: "error".

6.3 Error Code Taxonomy

The NL Protocol defines a hierarchical error code taxonomy. Error codes are organized by category, with each category corresponding to a protocol layer.

+==========================================================================+
|                    NL PROTOCOL ERROR CODE TAXONOMY                        |
+==========================================================================+
|                                                                          |
|  NL-E1xx  Authentication & Identity Errors        (Chapter 01)           |
|  NL-E2xx  Authorization & Scope Errors            (Chapter 02)           |
|  NL-E3xx  Action Execution Errors                 (Chapters 02, 03)      |
|  NL-E4xx  Defense & Interception Errors           (Chapter 04)           |
|  NL-E5xx  Audit Errors                            (Chapter 05)           |
|  NL-E6xx  Detection & Threat Errors               (Chapter 06)           |
|  NL-E7xx  Federation & Delegation Errors          (Chapter 07)           |
|  NL-E8xx  Transport & Protocol Errors             (Chapter 08)           |
|                                                                          |
+==========================================================================+

6.4 NL-E1xx: Authentication & Identity Errors

6.5 NL-E2xx: Authorization & Scope Errors

6.6 NL-E3xx: Action Execution Errors

6.7 NL-E4xx: Defense & Interception Errors

6.8 NL-E5xx: Audit Errors

6.9 NL-E6xx: Detection & Threat Errors

6.10 NL-E7xx: Federation & Delegation Errors

6.11 NL-E8xx: Transport & Protocol Errors

7. Discovery Protocol

7.1 Purpose

The discovery protocol enables agents and other NL-compliant systems to discover the capabilities, endpoints, and configuration of an NL Provider without prior knowledge of its specific implementation. This follows the pattern established by RFC 8615 (Well-Known URIs).

7.2 Well-Known URL

Every NL-compliant system that exposes an HTTP transport MUST serve a discovery document at:

GET /.well-known/nl-protocol

The discovery document MUST be served without authentication. It MUST NOT contain secret values or sensitive configuration details.

Discovery document schema:

{
  "nl_protocol": {
    "versions": ["1.0"],
    "preferred_version": "1.0"
  },
  "provider": {
    "name": "Braincol NL Provider",
    "vendor": "braincol.com",
    "version": "0.1.0",
    "documentation_url": "https://docs.braincol.com/nl-protocol"
  },
  "endpoints": {
    "base_url": "https://nl.braincol.com/nl/v1",
    "actions": "/nl/v1/actions",
    "agents_register": "/nl/v1/agents/register",
    "agents_get": "/nl/v1/agents/{agent_id}",
    "delegations": "/nl/v1/delegations",
    "delegations_revoke": "/nl/v1/delegations/{token_id}",
    "revocations": "/nl/v1/revocations",
    "audit": "/nl/v1/audit",
    "health": "/nl/v1/health"
  },
  "capabilities": {
    "conformance_level": "standard",
    "supported_levels": [1, 2, 3, 4, 5],
    "action_types": ["exec", "template", "inject_stdin", "inject_tempfile", "sdk_proxy"],
    "trust_levels": ["L0", "L1", "L2"],
    "credential_types": ["api_key", "bearer_token"],
    "max_message_size_bytes": 1048576,
    "max_timeout_ms": 600000,
    "supports_delegation": true,
    "supports_federation": false,
    "supports_dry_run": true,
    "supports_batch_actions": false
  },
  "security": {
    "jwks_uri": "https://nl.braincol.com/.well-known/nl-protocol/jwks.json",
    "attestation_issuers": [
      {
        "issuer": "anthropic.com",
        "jwks_uri": "https://anthropic.com/.well-known/nl-protocol/jwks.json"
      },
      {
        "issuer": "openai.com",
        "jwks_uri": "https://openai.com/.well-known/nl-protocol/jwks.json"
      }
    ],
    "rate_limiting": {
      "enabled": true,
      "default_requests_per_minute": 120
    }
  },
  "federation": {
    "enabled": false,
    "trust_domain": "nl://braincol.com",
    "partners": []
  }
}

7.3 Discovery Document Field Definitions

7.4 Discovery Caching

Discovery documents SHOULD be cached by clients. The server SHOULD include appropriate HTTP caching headers:

Cache-Control: public, max-age=3600
ETag: "v1-2026020801"

Clients SHOULD refresh the discovery document:

• At least once per hour during active operation.
• Immediately when an NL-E801 (version mismatch) error is received.
• Immediately when a connection to a new NL Provider is established.

8. Secret Rotation & Versioning

8.1 Secret Version Syntax

The NL Protocol supports versioned secret references to enable safe rotation. The version suffix is appended to the standard placeholder syntax:

{{nl:path/SECRET_NAME@version}}

Version formats:

Requirements:

8.2 Rotation Protocol

Secret rotation follows a defined protocol to ensure continuity of service:

+==============================================================================+
|                       SECRET ROTATION LIFECYCLE                               |
+==============================================================================+
|                                                                              |
|  Phase 1: NEW VERSION CREATED                                                |
|  +------------------------------------------------------------------------+  |
|  | - New secret value is stored as version v(N+1)                         |  |
|  | - @latest now resolves to v(N+1)                                       |  |
|  | - @previous resolves to v(N)                                           |  |
|  | - v(N) remains accessible by explicit reference (@v<N>)                |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  Phase 2: NOTIFICATION                                                       |
|  +------------------------------------------------------------------------+  |
|  | - rotation_notification message is sent to all subscribed agents        |  |
|  | - Notification includes: secret_ref, previous_version, new_version,    |  |
|  |   grace_period_ends                                                     |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  Phase 3: GRACE PERIOD                                                       |
|  +------------------------------------------------------------------------+  |
|  | - Both v(N) and v(N+1) are accessible                                  |  |
|  | - Agents using @latest automatically get v(N+1)                         |  |
|  | - Agents using @v<N> explicitly still get the old value                 |  |
|  | - RECOMMENDED grace period: 1 hour (configurable)                       |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  Phase 4: OLD VERSION DEPRECATED                                             |
|  +------------------------------------------------------------------------+  |
|  | - v(N) is marked as deprecated                                         |  |
|  | - Access to v(N) is still possible but generates a WARNING audit entry  |  |
|  | - RECOMMENDED deprecation period: 24 hours after grace period           |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  Phase 5: OLD VERSION REMOVED                                                |
|  +------------------------------------------------------------------------+  |
|  | - v(N) is removed from the secret store                                |  |
|  | - Access attempts for v(N) return NL-E302 (Secret Not Found)           |  |
|  | - Removal is recorded in the audit trail                               |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
+==============================================================================+

8.3 Rotation Notification Delivery

Rotation notifications can be delivered through two models:

Webhook (push) model:

The NL Provider sends a rotation_notification message to registered webhook endpoints when a secret is rotated.

POST https://agent-service.example.com/nl/webhooks
Content-Type: application/nl-protocol+json
X-NL-Signature: sha256=<HMAC-SHA256 of request body using webhook secret>

{
  "nl_version": "1.0",
  "message_type": "rotation_notification",
  "message_id": "msg_990c2844-c63f-85b8-e150-880099884444",
  "timestamp": "2026-02-08T15:00:00.000Z",
  "payload": {
    "secret_ref": "api/GITHUB_TOKEN",
    "previous_version": "v3",
    "new_version": "v4",
    "rotation_id": "rot_aa0d3955-d740-96c9-f261-991100995555",
    "grace_period_ends": "2026-02-08T16:00:00.000Z",
    "reason": "scheduled_rotation"
  }
}

Polling model:

Agents or agent services poll the NL Provider for rotation events:

GET /nl/v1/rotations?since=2026-02-08T14:00:00.000Z&secrets=api/*
Authorization: Bearer <credential>

Requirements:

8.4 Rotation Audit Requirements

Every phase of the rotation lifecycle MUST produce an audit entry:

9. Rate Limiting & Backpressure

9.1 Purpose

Rate limiting protects NL-compliant systems from abuse, denial of service, and resource exhaustion. Rate limits are enforced at multiple granularities: per agent, per scope grant, and per source IP.

9.2 Rate Limit Headers

All HTTP responses SHOULD include the following rate limit headers:

9.3 Rate Limit Response (429)

When a rate limit is exceeded, the server MUST respond with HTTP status 429 Too Many Requests and the following body:

{
  "error": {
    "code": "NL-E202",
    "message": "Rate limit exceeded. Maximum 120 requests per minute for this agent.",
    "detail": {
      "limit": 120,
      "window_seconds": 60,
      "reset_at": "2026-02-08T14:31:00.000Z",
      "retry_after_seconds": 15,
      "scope": "per_agent"
    },
    "resolution": "Wait 15 seconds before retrying. Consider batching actions if supported."
  }
}

The response MUST also include the Retry-After HTTP header:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-NL-RateLimit-Limit: 120
X-NL-RateLimit-Remaining: 0
X-NL-RateLimit-Reset: 1738936260
Content-Type: application/nl-protocol+json

9.4 Rate Limit Granularity

9.5 Backpressure Signaling

When an NL Provider is experiencing high load but has not yet reached hard rate limits, it SHOULD signal backpressure to clients:

HTTP/1.1 200 OK
X-NL-RateLimit-Remaining: 5
X-NL-Backpressure: true
X-NL-Suggested-Delay-Ms: 500

Clients that receive X-NL-Backpressure: true SHOULD introduce a delay of at least X-NL-Suggested-Delay-Ms milliseconds before the next request. Clients MUST NOT be required to honor backpressure signals, but implementations that do not honor them MAY be subject to hard rate limiting.

10. Conformance Requirements

The following conformance requirements apply to implementations of this chapter. Each requirement is identified by a unique ID and specifies a compliance level using RFC 2119 language.

11. Security Considerations

11.1 Transport Security

All NL Protocol communication over a network MUST be encrypted using TLS 1.2 or higher. Plaintext HTTP MUST NOT be used for non-loopback connections. This requirement applies to all transport bindings: HTTPS, mTLS, gRPC, and WebSocket.

For local transports (Unix domain sockets, stdin/stdout pipes), encryption is not required because communication does not traverse a network. However, Unix domain socket permissions MUST be set to restrict access to authorized processes only (Section 2.2).

11.2 Replay Protection

NL Protocol messages include both a message_id and a timestamp. Together, these provide replay protection:

1. Message ID uniqueness: Each message MUST have a unique message_id. Receivers MUST maintain a set of recently seen message IDs (minimum retention: 5 minutes) and MUST reject duplicates with error NL-E802.

2. Timestamp freshness: Messages with timestamps more than 5 minutes in the future or past MUST be rejected with error NL-E805.

3. Attestation nonce: Attestation JWTs include a jti (JWT ID) that provides additional replay protection at the identity level (Chapter 01, Section 8.3).

REPLAY PROTECTION LAYERS:

  Layer 1: Transport (TLS)
  +---------------------------------------------------------------+
  | TLS protects against network-level replay by encrypting and   |
  | authenticating each connection with fresh session keys.       |
  +---------------------------------------------------------------+

  Layer 2: Message ID
  +---------------------------------------------------------------+
  | Each message has a unique message_id. The receiver maintains  |
  | a rolling window of seen IDs and rejects duplicates.          |
  +---------------------------------------------------------------+

  Layer 3: Timestamp
  +---------------------------------------------------------------+
  | Messages must be fresh (within 5-minute window). Stale        |
  | messages are rejected even if their message_id is novel.      |
  +---------------------------------------------------------------+

  Layer 4: Attestation JTI (for identity-level operations)
  +---------------------------------------------------------------+
  | Attestation JWTs include a jti claim that is tracked          |
  | independently for the JWT's lifetime.                         |
  +---------------------------------------------------------------+

11.3 Message Integrity

For HTTP transports, TLS provides message integrity at the transport layer. For higher assurance, implementations SHOULD sign critical messages (delegation tokens, revocation requests, federation messages) using JWS (RFC 7515). The signature covers the canonical JSON (RFC 8785) representation of the message payload.

For the Unix domain socket and stdin/stdout transports, message integrity relies on the OS-level guarantee that local IPC is not subject to man-in-the-middle attacks. However, implementations SHOULD still validate message structure and reject malformed messages.

11.4 Credential Security in Transit

Agent credentials MUST be transmitted only over encrypted channels. For HTTP transport, the credential is carried in the Authorization: Bearer header, which is protected by TLS. For stdin/stdout transport, the credential is passed via environment variable at process startup, which does not traverse a network.

Credentials MUST NOT be included in:

• URL query strings (which may be logged by proxies and web servers).
• Message payloads (except during the handshake for Unix domain sockets).
• Log messages or diagnostic output.

11.5 Error Message Information Disclosure

Error messages MUST NOT reveal information that could aid an attacker:

1. Error messages MUST NOT contain secret values.
2. Error messages MUST NOT reveal the internal structure of the secret store (e.g., file paths, database table names).
3. Error messages MUST NOT reveal which specific validation step failed in a way that enables enumeration attacks (e.g., "agent not found" vs. "password incorrect" -- both should return NL-E100).
4. The detail object in error responses MUST be limited to information that the requester is authorized to see based on their authenticated identity.

11.6 Denial of Service Mitigation

Rate limiting (Section 9) is the primary defense against denial of service. Additional mitigations:

1. Message size limits: Implementations MUST reject messages exceeding the configured maximum size (default: 1 MiB) with error NL-E803.
2. Connection limits: Implementations SHOULD limit the number of concurrent connections per agent and per source IP.
3. Timeout enforcement: All operations MUST have timeouts. Idle connections SHOULD be closed after a configurable period (RECOMMENDED: 5 minutes).
4. Slowloris protection: HTTP servers SHOULD enforce minimum data rates on incoming requests to prevent slow-read attacks.

11.7 Federation Security

Cross-organization federation introduces additional security considerations:

1. mTLS authentication: Federation partners MUST authenticate using mTLS (Section 2.6). This provides mutual authentication at the transport layer.
2. Request signing: Federated action requests SHOULD be signed by the requesting NL Provider's key for non-repudiation.
3. Rate limiting: Federation endpoints SHOULD have separate, more restrictive rate limits than local endpoints.
4. Response validation: Responses from federation partners MUST be validated for well-formedness and MUST be subject to output sanitization before returning to the requesting agent.

12. References

Normative References

• RFC 2119 -- Key words for use in RFCs to Indicate Requirement Levels
• RFC 7515 -- JSON Web Signature (JWS)
• RFC 7519 -- JSON Web Token (JWT)
• RFC 7807 -- Problem Details for HTTP APIs
• RFC 8259 -- The JavaScript Object Notation (JSON) Data Interchange Format
• RFC 8615 -- Well-Known Uniform Resource Identifiers (URIs)
• RFC 8785 -- JSON Canonicalization Scheme (JCS)
• RFC 6838 -- Media Type Specifications and Registration Procedures
• RFC 6839 -- Additional Media Type Structured Syntax Suffixes

Informative References

• Model Context Protocol -- Anthropic's protocol for agent-tool interaction
• gRPC -- A high-performance, open-source universal RPC framework
• NDJSON -- Newline Delimited JSON specification
• A2A Protocol -- Google's Agent-to-Agent protocol

NL Protocol References

• 00-overview.md -- NL Protocol Overview
• 01-agent-identity.md -- Level 1: Agent Identity
• 02-action-based-access.md -- Level 2: Action-Based Access
• 03-execution-isolation.md -- Level 3: Execution Isolation
• 04-pre-execution-defense.md -- Level 4: Pre-Execution Defense
• 05-audit-integrity.md -- Level 5: Audit Integrity
• 06-attack-detection.md -- Level 6: Attack Detection & Response
• 07-cross-agent-trust.md -- Level 7: Cross-Agent Trust & Federation

Copyright 2026 Braincol. This specification is licensed under CC BY 4.0.