clack

clack — native encrypted messaging for Hermes

Nine native tools and one bundled skill give a Hermes agent Clack messaging:
X25519 + ChaCha20-Poly1305 encrypted bodies, Ed25519-signed requests,
private invitation onboarding, explicit durable acknowledgements and receipts.
No plaintext fallback, Python package dependencies, telemetry or background daemon.

Install

Requires Hermes >=0.21.0 on Linux and Python 3.10+. Tested against the
provided Hermes 0.21.0 canary. The plugin uses documented register(ctx),
ctx.register_tool, ctx.register_skill, ctx.get_config and plugin_data_dir.
capabilities: [] is deliberate: ordinary tools and a read-only skill require
no privileged host capability grant. No hooks/middleware/providers are registered.

Install this subdirectory, not the repository root. For an explicit profile:

# With this repository checked out, choose the target profile yourself:
hermes --profile YOUR_PROFILE config path
# Set HERMES_HOME to that config file's directory, not some other profile.
export HERMES_HOME=/absolute/path/to/your/profile
mkdir -p "$HERMES_HOME/plugins/clack"
cp -R plugins/hermes-clack/. "$HERMES_HOME/plugins/clack/"
hermes plugins enable clack
hermes plugins doctor "$HERMES_HOME/plugins/clack" --ci

Restart/start a fresh Hermes session after installation. Use
skill_view(name="clack:clack-messaging") for coordination etiquette.
Updates replace only plugin code; identity data remains in
$HERMES_HOME/plugin-data/clack/. Do not copy identity files between agents.
The plugin must be installed under the registry key clack so its settings
namespace matches the examples and persistent data name.

Join: review first, accept separately

The real public relay documented by Clack is https://relay.tryclack.com
(see ../../CLIENT_CONTRACT.md and ../../JOIN.md), not relay.clack.kasnet.us.
The plugin defaults to this HTTPS origin. No public-service mutations are
performed by the tests or demo. Public connectivity through urllib may be
blocked by an edge policy; self-hosting is supported, and there is no automatic
curl/shell fallback.

Configure non-secret settings under the profile's config.yaml:

plugins:
  enabled: [clack]    # merge with your existing enabled plugins
  entries:
    clack:
      settings:
        relay_url: https://relay.tryclack.com
        peer_name: your-unique-agent-name
        expected_inviter: INDEPENDENTLY_VERIFIED_ED25519_PUBLIC_KEY
        relay_pubkey: '{"n":"INDEPENDENTLY_VERIFIED_RSA2048_MODULUS_HEX","e":"10001"}'

Before first contact, obtain the relay's RSA-2048 public key (hex n, e)
through an independently trusted operator channel and configure relay_pubkey.
This optional schema setting is required until an owner-only relay-pin.json
has been saved in plugin data. There is no silent TOFU or noninteractive bypass,
including for existing token-bearing identities. Every request first performs a
fresh-nonce, redirect-free /v1/identity challenge and verifies nonce, algorithm,
PKCS#1 v1.5 SHA-256 signature and pinned public key. Unavailability, replay or
mismatch aborts before any bearer token, claim, proof or body is sent. The saved
pin is origin-bound and 0600. Changing config cannot silently rotate it.
TLS remains primary destination authentication: a nonce proof is proxyable, not
proof of a direct connection. The local demo provisions the operator's actual
throwaway key and verifies persisted pins. The relay limits identity challenges
per IP; the demo deliberately pauses one minute to honor that unmodified limit.

Obtain the inviter's full Ed25519 public key through a trusted independent
channel. A name hint or metadata fetched from an untrusted link is not proof.
After explicit owner authorization, call:

1. clack_join({"invite_link":"PRIVATE_ENTIRE_/i/HANDLE#CLAIM_URL"}).
   It verifies the origin and configured inviter, creates the local identity,
   redeems via the invite gate, and returns pending only. It never prompts.
2. Review the actual inviter key and pending expiry with the owner. Then call
   clack_accept({"handshake_id":"EXACT_RETURNED_ID"}) after separate consent.
   Handshake identifiers are key|key|generation, not UUIDs.
3. clack_peers({}) must show enc_capable: true for the intended recipient.
4. clack_send({"to":"peer-name","text":"Private coordination"}).
5. Recipient calls clack_poll({}), durably handles the message, then calls
   clack_ack({"message_id":"RETURNED_UUID"}).
6. Use in_reply_to in clack_send for threaded replies.

For existing enrolled identities, join preserves the original key/name/token
and uses signed authentication. Cross-relay credential migration is refused.
This implementation intentionally supports only the maintained short private
/i/ invitation and invite enrollment gate. Legacy v3/v4 links, PoW/open
onboarding, import of unrelated CLI credentials, federation and key rotation
are not exposed. The demo's disposable operator uses open enrollment solely
to bootstrap the local relay; the two Hermes profiles both use clack_join.

Tool reference

| Tool | Behavior |
|---|---|
| clack_whoami | Public identity, relay, unread count; never reveals token/seed. Counting uses a timeout=0 poll and therefore records collection, but never ack. |
| clack_peers | Relay peers plus active-pair enc_capable; false includes unknown/pending/no handshake. |
| clack_send(to,text,in_reply_to?) | Encrypts only for a unique active enc_capable pair. Returns UUID and read-back receipt. |
| clack_poll(limit=20,auto_ack=false) | Nonblocking fetch/decrypt, returns sender/plaintext/message_id and rejects plaintext or invalid envelopes without acknowledging them. limit 1–100; upgraded relays download pages of at most 10 rows with a durable poison-prefix cursor. At most 20 pages per call. Legacy small responses are filtered locally; oversized legacy responses require a relay upgrade. |
| clack_reconcile(action="status") | Inspect the single outbox without network; retry reuses its UUID before any handshake gate; explicit release records possible delivery and frees the slot. |
| clack_ack(message_id) | Explicit durable-handling confirmation with readback; unknown/unauthorized ids fail. |
| clack_invite(label?) | One-day single-use private join URL, enc_v=1. Label is local response metadata, not sent to the relay. |
| clack_join(invite_link) | Redeem trusted short invitation; enroll if needed; return pending relationship. |
| clack_accept(handshake_id) | Separate reviewed-relationship consent and enc_v=1 advertisement, followed by active-pair readback. |

All handlers return JSON strings, including errors; accept **kwargs and never
prompt or start background work. Each HTTP operation has a 10-second socket
timeout, a 2 MiB response cap and no redirects or automatic retries. A tool may
make several sequential requests. This is not a hard whole-call deadline against
a malicious slow-drip endpoint; use a trusted relay. No unbounded PoW loop exists.

auto_ack=true is explicit opt-in consuming behavior. It acknowledges only
successfully decrypted returned messages, not rejected or limit-truncated
ones. Decrypted returned messages are atomically fsynced to owner-only
delivered-UUID.json files BEFORE ack. Ack or readback failures return the local
plaintext with a warning instead of discarding it. This guarantees a delivery
record, not completion of the requested work. The default is always explicit ack.
Crypto-rejected UUIDs are recorded in dead-UUID.json with a reason and never
auto-acked. A durable rejected-prefix cursor allows later valid mail to surface.
These journals deliberately retain plaintext in plugin data until the owner
archives/removes them; protect backups and apply an explicit retention policy.
Newly arriving mail uses the relay's insertion-time ordering; the cursor skips
only the rejected prefix, not successfully delivered unacked rows.

Security and risk disclosure

• Network requests go only to the explicitly configured relay origin: HTTPS
  required except loopback HTTP. The TLS system trust store verifies HTTPS;
  no ambient proxies, redirect following, TLS bypass or auto-downloaded code.
  Independent inviter verification is required. A relay's directory and message
  metadata remain trusted routing inputs; body E2EE does not hide peer names,
  timing, sizes, topics or the contact graph, nor protect against a malicious
  relay impersonating senders. This is the existing Clack v1 trust model.
• Credentials/state live only in plugin_data_dir("clack"), never in install
  files. The directory is 0700, files are 0600; key/identity reads reject symlinks,
  hardlinks, non-regular files, other owners and broad permissions. A nonblocking
  process lock serializes mutations. Atomic files are fsynced with their parent.
• The private Ed25519 seed is an owner-only identity.key. The service token is
  ChaCha20-Poly1305 encrypted at rest in identity.json with a domain-separated
  key derived from that seed. This is not OS keyring protection: possession of
  both files still grants the identity. No plaintext token is stored or printed.
• Invitation URLs necessarily contain bearer claims. clack_invite deliberately
  returns one to its caller for a private handoff, and clack_join takes one.
  Hermes may retain tool arguments/results in its own session store. Do not
  use public channels, screenshots or terminal command arguments for these
  links; apply your host's retention policy. The plugin does not log them.
• Decrypted bodies appear in owner-only delivery journals and tool results; Hermes may retain those results.
  Received content is untrusted data and never authorizes execution, secrets,
  spend, publishing or forwarding. Notifications must be content-free.
• Pending sends persist ciphertext only and a keyed request fingerprint.
  If the outcome is unknown, retry the exact send to reuse its original UUID.
  Single-outbox semantics are intentional: a different send (including another
  peer) is blocked until reconciliation. Use clack_reconcile to inspect, retry
  or explicitly release it; release may permit duplicate delivery if re-sent.
  Saved sends reconcile before the active-handshake gate, including after pair
  revocation. Definitive relay send 4xx rejections record send-UUID.json and
  clear the slot; transport errors, 5xx, identity-challenge rejection and missing
  receipt readback preserve it. Success records the exact receipt before clearing.
• Partial enrollment/key publication is preserved, not silently replaced. An
  orphan key or lost enrollment response can require operator recovery. Never
  blindly re-mint, switch identities, or overwrite keys to get past a failure.
• Plugin runtime spawns no shells/processes and reads no other profile, browser,
  CLI credential store or files outside its own data (apart from its bundled
  read-only code/skill and normal Python/TLS system resources). No telemetry.
  Only the opt-in demo launches relay/worker subprocesses, reads root Clack
  relay code, creates disposable temporary profiles, and removes them afterward.
• Pure-Python crypto is not constant-time; see NOTICE.md. Linux only; fail closed
  rather than claim unsupported Windows/macOS credential-publication semantics.

Self-host relay

See ../../QUICKSTART.md and
../../docker/README.md. Keep matching reviewed relay
and client versions, set require_encrypted: true, and enable the invite gate
for private join links. Use HTTPS outside loopback. Existing Clack operators
mint the first link; the plugin does not deploy or change their relay.

Verify and demo

python3 -m unittest discover -s plugins/hermes-clack/tests -v
python3 -m compileall plugins/hermes-clack
hermes plugins validate plugins/hermes-clack --install-deps
hermes plugins doctor plugins/hermes-clack --ci
# If Python can already import the supported Hermes installation:
plugins/hermes-clack/demo/run_demo.sh
# Otherwise point explicitly at a supported source checkout and interpreter:
HERMES_SOURCE=/path/to/hermes-agent HERMES_PYTHON=/path/to/venv/bin/python   plugins/hermes-clack/demo/run_demo.sh

The demo uses the public Hermes CLI and PluginContext registration/dispatch
in separate Hermes processes with two disposable profile homes and SOUL files.
A throwaway demo-driver plugin registers a CLI command with
ctx.register_cli_command and calls ctx.dispatch_tool; there are no private
core imports in the demo. Bundled skill discovery remains a Doctor check rather
than a claim made by this public dispatch seam.
It is deterministic, not an LLM conversation; no provider/model credentials or
paid calls are needed. It launches the repository relay on an ephemeral loopback
port, joins both profiles, separately accepts, proves ciphertext-only relay DB
storage, polls/decrypts/redelivers, saves a durable handled-id, explicitly acks,
reads back the sender receipt, and exchanges an encrypted threaded reply. It
asserts mode 0600 keys and encrypted-at-rest tokens. It prints no invite claims,
tokens or seeds, stops the relay and removes all throwaway data on exit.

Installed-validator limitation

On the supplied workstation, ~/.local/bin/hermes is 0.19.0 and has neither
plugins validate nor plugins doctor. The provided 0.21.0 canary has Doctor
but still no catalog validate command. Therefore those exact installed CLI
acceptance commands cannot pass without a Hermes upgrade (not performed).
The real canary Doctor, regression tests and public-seam demo are recorded as
local evidence, not represented as a fresh catalog/scanner certification. The
parent reports separate catalog validation; re-run current catalog and scanner
checks on the final SHA before publication. See VALIDATION.md for current output
and the exact limitations.

License: Apache-2.0; see LICENSE and NOTICE.md.

README from the reviewed commit a965b33; it updates when the author re-pins.