# Security policy

## Supported versions

Security fixes are applied to the latest published release and the default branch. Older snapshots are not supported.

## Report a vulnerability

Please do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/kontextmind/kxm/security/advisories/new) and include:

- affected version or commit;
- impact and realistic attack scenario;
- minimal reproduction steps;
- any proposed mitigation;
- whether the issue is already public.

Do not include real credentials, private prompts, personal data, or unrelated repository contents. You should receive an acknowledgement through GitHub's advisory workflow. Public disclosure should wait until a fix and release plan are agreed.

## Security model

The current hub provides:

- an administrative bearer token and optional per-project bearer tokens;
- ephemeral per-agent keys for agent-specific operations;
- project-scoped discovery and message visibility;
- loopback binding by default;
- refusal to bind beyond localhost without a token;
- bounded request bodies, message content, and hop counts;
- per-agent request rate limiting and stable request IDs;
- security response headers and generic public responses for internal errors;
- SHA-256 HMAC verification and stable-delivery deduplication for webhook workflows;
- attempt-bound peer-message provenance, unique-producer quorum, and explicit admin-only degradation for configured workflow requirements;
- structured hub logs that omit prompt and reply bodies.

It does not currently provide:

- per-user roles or external identity-provider integration;
- durable encrypted storage;
- end-to-end message encryption;
- public-internet hardening;
- distributed denial-of-service protection;
- guarantees that peer-provided content is safe or correct.

Peer quorum proves that the hub observed durable replies from the configured
producer identities for one exact workflow run, stage, requirement, and
attempt. It does not prove truth, response quality, model identity, independent
inference, non-collusion, or human approval. A project-token holder can register
a new agent or reclaim an offline agent name and its durable ID in that project,
so every holder of one shared project credential belongs to the same fully
trusted provenance domain.

Authentication does not make a mesh message trustworthy. Agents must retain their normal permission, tool, filesystem, and secret-handling controls.

## Operator responsibilities

- Keep the hub on loopback whenever possible.
- Use a long random token and load it from a secret manager or protected environment.
- Use distinct project tokens when different teams share one hub.
- Reserve a distinct administrative token for admin routes; give agents only their explicit project token. Never give a workflow callback or peer the admin token.
- Protect and back up `.kxm/state/kxm.db` because it contains messages and agent credentials.
- Protect `.kxm/logs`; raw long-lived Pi process logs can contain model output, tool output, paths, and other sensitive operational data.
- Keep secrets out of tracked `.kxm/config` and `.kxm/assets`; runtime logs, generated assets, and state must remain uncommitted.
- Store webhook secrets in dedicated environment variables through `secretEnv`; do not commit them in workflow JSON.
- Use a separate `signalSecretEnv` for callbacks and never put credentials, private prompts, or sensitive incident details in a degradation reason.
- Review every quorum degradation as a security-relevant decision. It must be declared by policy, limited to the current attempt, and followed by enough verified replies to meet the approved minimum.
- Enforce read-only reviewer and single-writer coordinator roles with `KXM_WORKER_TOOLS`; prompt instructions do not remove shell, edit, or write capabilities.
- Treat verified evidence snapshots as sensitive metadata. They omit message bodies but retain agent names/IDs, workflow scope, timestamps, and content hashes beyond normal terminal-message retention.
- Restrict webhook ingress by TLS, network policy, and provider configuration even when signatures are enabled.
- Put TLS and network access controls in front of any non-loopback deployment.
- Rotate the token after suspected disclosure.
- Never expose the hub directly to the public internet.
- Keep Node.js, Pi, Claude Code, and this package updated.