Clawdio

Secure P2P communication for AI agents. Noise XX handshake, XChaCha20-Poly1305 encryption, connection consent, human verification. Zero central servers.

Security Scan

The skill's stated P2P encryption purpose largely matches the code, but there are mismatches in the runtime instructions and several operational behaviors (building via npm, opening network ports, persisting keys, spawning sub-agents, and an autoAccept option) that deserve careful review before installing or allowing autonomous use.

Purpose & Capability

The code files (crypto, transport, protocol, CLI, index) align with the described P2P encrypted messaging purpose. However SKILL.md instructs building from 'projects/clawdio/' which does not match the manifest (source files are at repository root), an incoherence that could break install/run instructions or be a sign of sloppy packaging.

Instruction Scope

Runtime instructions tell operators/agents to run 'npm install' and 'npx tsc', start listeners on arbitrary ports, persist identities to disk (identityPath), and use a 'sub-agent' pattern (spawn processes). The doc also exposes an 'autoAccept' mode which accepts inbound peers automatically — this expands attack surface. These behaviors go beyond simple API calls and allow network listeners, disk writes, and process spawning, so they need explicit user consent and sandboxing.

Install Mechanism

There is no formal install spec, but SKILL.md instructs running 'npm install' which will fetch runtime dependencies from the public registry. The package.json is present in the bundle but its dependency list wasn't provided in the metadata. Running npm install at runtime can pull arbitrary packages; the mismatch in the expected path ('projects/clawdio/') vs actual layout increases risk of accidental execution of unexpected code.

Credentials

The skill requests no environment variables or credentials, which is coherent for a P2P library. However it implicitly requires network access (opening ports), filesystem access to persist identity/peer data, and the ability to spawn processes for the sub-agent pattern. These capabilities are not declared in requires.* fields and should be considered sensitive in many environments.

Persistence & Privilege

The skill is not configured with always:true, but disableModelInvocation is not set, so the model may be allowed to invoke the skill autonomously. Given the skill can start listeners and persist keys, allowing autonomous invocation without explicit user controls increases risk; consider requiring explicit user invocation or disabling model invocation for network-listening skills.

What to consider before installing

This skill appears to implement P2P encrypted messaging, but review before installing: 1) Confirm file layout and build steps (SKILL.md references 'projects/clawdio/' but code is at repo root). 2) Inspect package.json dependencies to ensure no malicious npm packages will be pulled. 3) Run the code in a sandbox or isolated environment first, since it opens network ports, writes identity files, and may spawn subprocesses. 4) Avoid enabling 'autoAccept' in production; require human consent and verification. 5) If you do not want the model to start network listeners autonomously, set disableModelInvocation:true or restrict the skill to user-invocation only. If possible, request the author to fix the path mismatch and provide an explicit install spec and a security review of the crypto usage.

Minimal secure peer-to-peer communication for AI agents. Two agents exchange a connection string, perform a Noise XX handshake, then communicate over encrypted channels. No central server required.

When to Use

• Agent-to-agent communication across machines or networks
• Secure task delegation between sub-agents on different hosts
• Any scenario requiring encrypted, authenticated P2P messaging

Setup

The Clawdio project lives at projects/clawdio/. Install dependencies and build:

cd projects/clawdio && npm install && npx tsc

Quick Start

const { Clawdio } = require('./projects/clawdio/dist/index.js');

// Create two nodes
const alice = await Clawdio.create({ port: 9090, autoAccept: true });
const bob = await Clawdio.create({ port: 9091, autoAccept: true });

// Connect (Noise XX handshake)
const aliceId = await bob.exchangeKeys(alice.getConnectionString());

// Send messages
await bob.send(aliceId, { task: "What's the weather?" });
alice.onMessage((msg, from) => console.log(msg.task));

Connection Consent (Recommended)

By default, unknown inbound peers require explicit consent:

const node = await Clawdio.create({ port: 9090 }); // autoAccept defaults to false

node.on('connectionRequest', (req) => {
  console.log(`Connection from ${req.id}`);
  console.log(`Fingerprint: ${req.fingerprint}`);
  // Accept or reject
  node.acceptPeer(req.id);  // or node.rejectPeer(req.id)
});

Outbound connections (you calling exchangeKeys) are auto-accepted. Already-trusted peers auto-reconnect.

Human Verification

For high-trust scenarios, verify peers in person:

node.setOwner('Alice');
const code = node.getVerificationCode(peerId); // "torch lemon onyx prism jade index"
// Both humans compare codes in person, then:
node.verifyPeer(peerId); // trust: 'accepted' → 'human-verified'
node.getPeerTrust(peerId); // 'human-verified'

Trust Levels

• pending — connection request received, not yet accepted
• accepted — peer accepted, encrypted communication active
• human-verified — verified via in-person code exchange

Persistent Identity

Pass identityPath to persist keys and trusted peers across restarts:

const node = await Clawdio.create({
  port: 9090,
  identityPath: '.clawdio-identity.json'
});

Sub-Agent Pattern

Spawn a sub-agent to handle Clawdio communication:

1. Main agent spawns sub-agent with task
2. Sub-agent creates Clawdio node, connects to remote peer
3. Sub-agent exchanges messages, collects results
4. Sub-agent reports back to main agent

Security Properties

• Forward secrecy (ephemeral X25519 keys)
• Mutual authentication (Noise XX)
• Replay protection (monotonic counters)
• XChaCha20-Poly1305 AEAD encryption
• Connection consent for inbound peers

API Reference

Method	Description
Clawdio.create(opts)	Create and start a node
node.exchangeKeys(connStr)	Connect to peer
node.send(peerId, msg)	Send encrypted message
node.onMessage(handler)	Listen for messages
node.acceptPeer(id)	Accept pending connection
node.rejectPeer(id)	Reject pending connection
node.setOwner(name)	Set human owner name
node.getVerificationCode(id)	Get 6-word verification code
node.verifyPeer(id)	Mark peer as human-verified
node.getPeerTrust(id)	Get trust level
node.getFingerprint(id)	Emoji fingerprint
node.getPeerStatus(id)	alive/stale/down
node.stop()	Shutdown