Security

Security by design

XMDB is built with security as a core principle. From scoped tokens and least privilege access to cryptographic verification and policy-based retrieval, every layer is designed for auditability and control.

Scoped Tokens

Tokens are scoped to specific workspaces and roles. Create read-only tokens for queries, write tokens for capture, or sync tokens for replication.

Least Privilege

Role-based access control with four permission levels: admin, read, write, and sync. Grant only the permissions each client needs.

Auditability

API operations are logged. Audit bundles capture the full context of requests: inputs, results, policy decisions, and verification metadata.

Hash Chain Integrity

Events are hash-linked in per-scope chains. Any modification to historical events would break the chain, making tampering detectable.

Event Signing

Optional Ed25519 signatures on events provide cryptographic proof of origin. Verify which device or service created each memory item.

Policy Gates

Retrieval policies filter what memory is accessible. Control by source kind, age, signature requirements, and custom rules per scope.

Token Roles

Create tokens with specific permissions for different use cases.

RolePermissions
adminAll endpoints including /admin/*
read/query, /pack, /pins
write/capture, /pin, /unpin
sync/sync/push, /sync/pull

Note: /metrics is admin-only (ops/monitoring).

Remote MCP uses a separate MCP auth token from XMDB API tokens.

Auth Operations

Practical steps for issuing tokens, rotating credentials, and enforcing workspace + scope boundaries.

Read-only tokens

Issue read-only tokens for query/pack access. These tokens cannot capture, admin, or modify data.

TOKEN=$(cat ~/.config/xmdb/token)
curl -s -X POST http://127.0.0.1:8080/admin/tokens/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"w1","scope_id":"s1","role":"read","name":"readonly-client"}'

Token rotation (zero downtime)

  1. Create a new token (both active simultaneously).
  2. Test the new token and update clients.
  3. Revoke the old token after verifying.
TOKEN=$(cat ~/.config/xmdb/token)
curl -s -X POST http://127.0.0.1:8080/admin/tokens/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"w1","scope_id":"s1","role":"write","name":"lily-v2"}'
curl -s http://127.0.0.1:8080/whoami -H "Authorization: Bearer NEW_TOKEN"
echo "NEW_TOKEN" > ~/.config/xmdb/token
curl -s -X POST http://127.0.0.1:8080/admin/tokens/revoke \
  -H "Authorization: Bearer NEW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"w1","scope_id":"s1","token_id":"OLD_TOKEN_ID"}'

Scope enforcement

  1. Each request must match the token workspace and scope.
  2. Scope resolution follows query param, header, or single-scope default rules.

Retrieval Policies

Policies act as "semantic contracts" that control what memory is accessible. Configure policies per workspace or scope to filter retrieval based on:

  • Source kinds - Allow or deny by source type
  • Age limits - Exclude items older than a threshold
  • Signature requirements - Only return signed events
# Environment variables
XMDB_RETRIEVAL_ALLOW_SOURCE_KINDS="manual,slack"
XMDB_RETRIEVAL_DENY_SOURCE_KINDS="gmail"
XMDB_RETRIEVAL_MAX_AGE_SECONDS="86400"
XMDB_REQUIRE_SIGNED_EVENTS_FOR_RETRIEVAL="true"

Encrypted Sync

When syncing between nodes, events are wrapped in encrypted envelopes. Only nodes with the shared encryption key can read sync payloads. Webhook secrets are encrypted at rest and are only returned on create or rotate. Optional signer allowlists ensure only trusted devices can contribute events.

AES-256-GCM encryption
Ed25519 signatures
Signer allowlists
Push/pull cursors
Secrets at rest
Webhook SSRF protections: HTTPS enforced by default, port allowlist, blocks private/link-local/metadata IPs, DNS revalidation on delivery, redirects disabled

Federated Trust

Share memories and beliefs between agents with cryptographic provenance and fine-grained trust controls.

Trust Policies

Configure per-source trust rules. Require Merkle proofs from some agents, RFC 3161 anchors from others, reject untrusted sources entirely. Policies are evaluated by priority.

Federation Receipts

Every accepted share bundle creates a federation receipt: an audit trail of what you accepted, from whom, and why you trusted it.

Belief Provenance

Shared beliefs include the complete evidence chain: the context retrieved, the claims relied upon, the source events, Merkle proofs, and timestamps. Verify the entire reasoning chain.

Foreign Origin Tracking

Beliefs received via federation are marked with their source agent. Query which beliefs came from which agents. Full traceability across organizational boundaries.

Questions about security?

Review our documentation or reach out to discuss your security requirements.

Contact UsRead Documentation