poke-interconnect — Poke Interconnect Protocol (PIP) v1

PIP lets independent Poke instances discover each other's capabilities and exchange signed, consented, idempotent messages and data. One envelope format, one policy engine, and one security model are shared by two transports: an HTTP/JSON API and an MCP server.

The full normative spec lives in docs/PROTOCOL.md. Install name: poke-interconnect; import name: pip_protocol; CLI: pip-node.

Architecture

        Peer A                          Peer B
  ┌──────────────────┐          ┌──────────────────┐
  │ pip-node / SDK   │          │ pip-node / SDK   │
  │  ┌────────────┐  │          │  ┌────────────┐  │
  │  │   Node     │  │ envelope │  │   Node     │  │
  │  │ sign/verify│  ├─────────►│  │ verify →   │  │
  │  │ policy     │  │ receipt  │  │ policy →   │  │
  │  │ redaction  │  │◄─────────┤  │ handler    │  │
  │  └─────┬──────┘  │          │  └─────┬──────┘  │
  │  HTTP / MCP      │          │  HTTP / MCP      │
  └──────────────────┘          └──────────────────┘
       Ed25519 identity · pip:<base32(sha256(pubkey))[:26]>

Related MCP server: dsh-agent-mailbox

Quickstart

uv venv .venv && uv pip install -e .[dev]   # or: pip install poke-interconnect

# 1. generate an instance key (mode 0600)
pip-node keygen --out ./data/instance.key

# 2. configure peers and consent
cp config/policy.example.yaml config/policy.yaml   # edit peers/scopes/consents
cp config/.env.example .env                        # optional

# 3. serve
PIP_PRIVATE_KEY_FILE=./data/instance.key PIP_POLICY_FILE=./config/policy.yaml \
  pip-node serve-http                                   # HTTP on 127.0.0.1:8642
pip-node serve-mcp --transport stdio                    # MCP over stdio
pip-node serve-mcp --transport streamable-http          # MCP over HTTP

Other CLI commands: pip-node identity, pip-node sign, pip-node send (see pip-node --help). Try the in-process demo: python examples/two_nodes_demo.py.

MCP client config

See config/mcp-client.example.json:

{ "mcpServers": { "poke": {
    "command": "pip-node",
    "args": ["serve-mcp", "--transport", "stdio"],
    "env": { "PIP_PRIVATE_KEY_FILE": "./data/instance.key" } } } }

HTTP API (§8)

PIP_HTTP_BEARER_TOKEN is an optional defense-in-depth gate; it never replaces the envelope signature. X-PIP-Request-Id is echoed/generated, X-PIP-Trace-Id propagated to logs.

MCP (§9)

Tools: pip_handshake, pip_send_message, pip_exchange_data, pip_get_receipt, pip_list_capabilities (public). Every tool takes a signed envelope dict; failures return a signed error envelope in the result (never a raw exception).

Resources: pip://identity, pip://capabilities, pip://policy/scopes. Prompts: pip_compose_message(to, subject, intent), pip_request_data(dataset, purpose).

Configuration (§12)

Deployment

Container image, compose stack, TLS proxy examples, and a systemd unit live in Dockerfile, docker-compose.yml, docker/, and deploy/. See docs/DEPLOYMENT.md; quick path: ./deploy/deploy.sh up.

Security model (summary)

Ed25519 signatures over canonical JSON ("PIPv1\n" + canonical_json(env-sig)); peers pinned by public key with rotation grace; nonce + time-window replay protection; idempotency keys for effectively-once delivery; scope + consent authorization; outbound redaction before signing; size caps and per-peer token bucket rate limits. See §13 threat model and docs/SECURITY.md.

Delivery semantics

At-least-once from the sender (client retries with the same idempotency_key), effectively-once at the receiver. pip.delivery.Outbox persists pending envelopes with exponential backoff (base 2s, cap 300s, 8 attempts → dead).

Observability

Prometheus counters envelopes_received_total{type,outcome}, envelopes_sent_total, policy_denials_total{code}; histogram handler_seconds. Structured JSON logs, one line per envelope/request — never payload bodies, keys, or tokens.

Development

uv pip install -e .[dev]
ruff check . && ruff format --check . && mypy src && pytest -q

Limitations (v1)

Transport confidentiality is delegated to TLS (terminate at a reverse proxy); no metadata privacy; no Sybil resistance / peer reputation.

License

MIT — see LICENSE.