Documentation

What's new in 3.0.0

Version 3.0.0 keeps the wire format, API surface and crypto guarantees of 2.5.x: every 2.5.x client stays compatible: and focuses on the operator and self-host experience. The headline change is structural: the post-quantum primitives now live in their own audited library.

• paramant-core crypto split (M5b). Server-side ML-DSA-65 signing is now provided by paramant-core: a standalone, audit-ready Rust library (BUSL-1.1) the relay consumes through its @paramant/core NAPI binding. Client-side ML-KEM-768 still runs in the browser/SDK; the relay never holds a key. See Crypto stack.
• Cards-per-product dashboard. The user dashboard is rebuilt around per-product cards, drawing on the existing /v2/check-key, monitor and audit endpoints: no new trust surface.
• Refreshed interactive UI. Dark mode (top-right toggle), real-time status updates and a mobile-friendly layout across the dashboard.
• First-run setup wizard. A web wizard at /setup replaces hand-run admin scripts for first-time operators: admin token, TOTP enrolment and the first key from the browser (ADR R005).
• Visual admin config. /admin/settings exposes relay configuration in the panel, so common changes no longer require editing .env and restarting.
• In-browser admin CLI. /admin/cli is a web terminal for admin debugging: inspect relay state without opening an SSH session.
• Crypto-mode negotiation (ADR R006, accepted). /v2/capabilities advertises a compact core mode (2 algorithms) by default; extended algorithm sets are opt-in. See Crypto stack.
• Add-on architecture (ADR R007, draft). A specification for container-isolated integrations: storage mirrors, SIEM exporters, SSO: that work on ciphertext and metadata only, never plaintext or keys.
• Static front-end serving (ADR R011). An opt-in SERVE_FRONTEND static handler lets a single relay serve its own UI for plug-and-play self-hosting. See Self-hosting.
• Documented design decisions. Architecture Decision Records R001–R011 capture the choices behind 3.0.0: from the hotfix flow to the crypto split: in the repository under docs/adrs/.

Quick start

Send your first encrypted file in under 5 minutes. Create a free account here (TOTP protected, key visible in dashboard).

# Python
pip install paramant-sdk

# JavaScript / Node
npm install paramant-sdk

from paramant_sdk import GhostPipe

gp = GhostPipe(api_key="pgp_your_key", device="laptop-01")
gp.receive_setup()  # register this device's keys (once)

# Send: returns (blob hash, inclusion proof). Share the hash with the receiver.
hash_, proof = gp.send(open("document.pdf", "rb").read(), ttl=3600)

# Receive: burn-on-read, one download only.
data, proof = gp.receive(hash_)

Or use the direct HTTP API: no SDK needed:

# Upload encrypted blob
curl -X POST https://health.paramant.app/v2/inbound \
  -H "X-Api-Key: pgp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"hash":"sha256_of_payload","payload":"base64_5mb_blob","ttl_ms":3600000}'

# Retrieve (one-time: blob is burned after this)
curl https://health.paramant.app/v2/outbound/abc123... \
  -H "X-Api-Key: pgp_your_key" -o received.bin

Authentication

Two key types exist: they serve different roles and are never interchangeable.

Pass the pgp_ key in the X-Api-Key header or ?k= query parameter:

X-Api-Key: pgp_your_key_here
# or:
GET /v2/check-key?k=pgp_your_key_here

SDK

Two official SDKs ship the same wire-format-v1 encoder, ML-KEM-768 + ML-DSA-65 by default, and capability negotiation against /v2/capabilities. Pick whichever matches your runtime: they are byte-compatible on the wire.

Install

# Python (3.10+)
pip install paramant-sdk

# JavaScript (Node 18+)
npm install paramant-sdk

Python SDK (class-based)

from paramant_sdk import GhostPipe

gp = GhostPipe(
    api_key = "pgp_xxx",
    device  = "device-001",
    sector  = "health",     # routes to health.paramant.app
)

# Send: returns blob hash
hash_ = gp.send(open("scan.dcm", "rb").read(), ttl=3600)

# Receive: burn-on-read, returns plaintext bytes
data = gp.receive(hash_)

Use cases

PARAMANT has five sector relays: each tuned for its compliance domain. Pick the sector that matches your use case.

healthHealthcare: NEN 7510, DICOM, HL7 FHIR

Send MRI scans, referral letters, and lab results between care providers. health.paramant.app is designed for NEN 7510 compliance: encrypted in transit, RAM-only, EU jurisdiction, per-access CT log proof.

# Send DICOM scan to specialist
from paramant_sdk import GhostPipe
gp = GhostPipe(api_key="pgp_xxx", device="mri-001", sector="health")
hash_, proof = gp.send(open("scan.dcm","rb").read(), ttl=3600)

NEN 7510 compliance page →

legalLegal & Notary: eIDAS, KNB

Send signed deeds and court documents that are cryptographically gone after receipt. The CT log provides tamper-evident proof of delivery without storing content.

# Signed deed: burn-on-read, CT log entry as proof of delivery
from paramant_sdk import GhostPipe
gp = GhostPipe(api_key="pgp_xxx", device="notary-01", sector="legal")
hash_, receipt = gp.send(open("deed.pdf","rb").read())
gp.verify_receipt(receipt)  # ML-DSA-65 signed

iotIndustrial IoT: IEC 62443

PLC and sensor data relay without VPN or direct OT internet exposure. Acts as a post-quantum data diode: OT side pushes outbound only, IT side receives. Fixed 5 MB padding defeats traffic analysis.

# PLC telemetry: outbound only, no VPN, no inbound port
from paramant_sdk import GhostPipe
gp = GhostPipe(api_key="pgp_xxx", device="plc-factory-01", sector="iot")
while True:
    gp.send(read_plc_state(), ttl=60)
    time.sleep(15)

IEC 62443 compliance page →

financeFinance: NIS2, DORA, ISO 20022

ISO 20022 payment file relay with per-transaction Merkle proof for DORA audit trails. finance.paramant.app: EU jurisdiction, no US Cloud Act, no metadata retention.

# Send ISO 20022 payment file with CT proof for DORA audit
from paramant_sdk import GhostPipe
gp = GhostPipe(api_key="pgp_xxx", device="bank-nl-01", sector="finance")
hash_, receipt = gp.send(open("pacs008.xml","rb").read())
# receipt → tree_size, sha3_root, ML-DSA-65 signature

All endpoints

POST /v2/inbound

Upload an encrypted, padded blob. Stored in RAM only: never written to disk. Returns a hash used for retrieval.

Request body (JSON):
{
  "hash":    "sha256_of_padded_payload",
  "payload": "base64_encoded_5mb_blob",
  "ttl_ms":  3600000
}

200: { "ok": true, "hash": "...", "ttl_ms": 3600000 }
409: hash already exists
503: relay at capacity (memory limit)

TTL is clamped to plan maximum. The hash field is the SHA-256 of the padded payload (not the original file). The SDK computes this automatically.

GET /v2/outbound/:hash

One retrieval only. After this call the blob buffer is overwritten with random bytes and removed from RAM. There is no recovery.

GET /v2/outbound/abc123...
X-Api-Key: pgp_xxx

200: binary blob (always 5MB padded)
404: burned, expired, or never existed
403: API key mismatch

GET /v2/stream

WebSocket endpoint for real-time blob_ready push notifications. Use a one-time ticket to avoid exposing the key in the URL.

// Step 1: get a one-time WebSocket ticket (30s TTL)
const { ticket } = await fetch('https://health.paramant.app/v2/ws-ticket', {
  method: 'POST', headers: { 'X-Api-Key': 'pgp_xxx' }
}).then(r => r.json());

// Step 2: connect with ticket (API key never appears in URL)
const ws = new WebSocket(`wss://health.paramant.app/v2/stream?ticket=${ticket}`);
ws.onmessage = e => {
  const msg = JSON.parse(e.data);
  // { type: "blob_ready", hash: "...", size: 5242880, ts: "..." }
};

GET /v2/monitor

{
  "ok": true, "plan": "pro", "blobs_in_flight": 3,
  "stats": { "inbound": 42, "burned": 38, "webhooks_sent": 12 },
  "delivery": { "total": 42, "acked": 38, "success_rate": 0.905 }
}

POST /v2/webhook

{ "hash": "blob_hash", "callback_url": "https://you.com/hook" }

Relay POSTs to your callback on delivery:
{ "event": "blob_retrieved", "hash": "...", "ts": "2026-04-14T..." }

Webhooks are signed with X-Paramant-Sig (HMAC-SHA256 of the body using your API key as the secret). Reject unsigned callbacks.

GET /health

{
  "ok": true,
  "version": "3.0.0",
  "sector": "health",
  "edition": "licensed",
  "uptime_s": 3600,
  "license_expires": "2027-01-01"
}

Self-hosting: Docker Compose

Community Edition is free forever for up to 5 users. One docker compose up starts 6 containers: five sector relays and an admin panel.

# 1. Clone
git clone https://github.com/Apolloccrypt/paramant-relay
cd paramant-relay

# 2. Configure
cp .env.example .env
echo "ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env
nano .env   # set TOTP_SECRET and RESEND_API_KEY if desired

# 3. Launch
docker compose up -d

# 4. Verify
curl http://localhost:3000/health
# → {"ok":true,"version":"3.0.0","sector":"relay"}

Container port map

Key .env variables

nginx & TLS

Use system nginx as a TLS terminator in front of the Docker containers. Certbot handles certificate renewal automatically.

# Install nginx + certbot
apt install -y nginx python3-certbot-nginx

# Obtain wildcard TLS certificates
certbot certonly --nginx -d your-domain.com \
  -d relay.your-domain.com \
  -d health.your-domain.com \
  -d finance.your-domain.com \
  -d legal.your-domain.com \
  -d iot.your-domain.com

Add an nginx server block for each subdomain that proxies to the matching container port:

server {
    listen 443 ssl;
    server_name health.your-domain.com;
    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection 'upgrade';
        proxy_set_header   Host $host;
        proxy_read_timeout 3600s;
    }
}
# Repeat for relay (:3000), finance (:3002), legal (:3003), iot (:3004)

First user

# Create your first API key
python3 deploy/paramant-admin.py add \
  --label "alice" \
  --plan  pro \
  --email alice@example.com

# Push to all relay containers
python3 deploy/paramant-admin.py sync

# Admin panel (requires ADMIN_TOKEN + TOTP if configured)
open https://your-domain.com/admin/

Community Edition enforces a hard cap of 5 users: the 6th add returns HTTP 402. Add a PLK_KEY to .env to unlock unlimited users.

Upgrade

cd /opt/paramant-relay
git pull --ff-only
docker compose up -d --build
# Named volumes (users.json, CT log, relay identity) are preserved

Admin scripts

Admin scripts ship with the relay repository. After cloning paramant-relay, the server-side admin tool lives under deploy/: run python3 deploy/paramant-admin.py [command] directly. Operator helpers (key add/revoke, first-boot setup) live under scripts/. No system-wide install package is currently provided: the SDK packages on PyPI (paramant-sdk) and npm (paramant-sdk) are the canonical client integrations.

CLI reference

# Example: send a file and wait for ACK
paramant-send --key pgp_xxx --sector health --ack scan.dcm

# Example: stream mode (process persists, receives all blobs)
paramant-stream --key pgp_xxx --sector health --forward https://pacs.hospital/api

ParamantOS: 39 operator tools

ParamantOS is a hardened Linux distribution (NixOS + Mint editions) for relay operators. All 39 tools are pre-installed.

Download ParamantOS: NixOS edition (v2.4.5) · Mint edition (v1.0-β)

Crypto stack

All encryption happens client-side. The relay never sees plaintext and never holds a private key.

Browser-side encryption runs as Rust/WASM compiled from crypto-wasm/. The WASM binary is SHA-256 verified at runtime before first use. The relay JS code has no access to decryption keys at any point.

The two halves of the stack run different builds of the same Rust crypto. ML-KEM-768 key encapsulation stays client-side (browser WASM / SDK): the relay never performs a key exchange and never holds a private key. ML-DSA-65 runs server-side for the relay identity keypair, signed delivery receipts and signed tree heads (STH), and for verifying device and receipt signatures. Since the M5b migration (2026-05-27) that server-side ML-DSA-65 is provided by paramant-core: a standalone, audit-ready Rust crypto library (BUSL-1.1) consumed by the relay through its @paramant/core NAPI binding.

Burn-on-read

After GET /v2/outbound/:hash the relay immediately overwrites the blob buffer with cryptographically random bytes and removes the entry from memory. Encrypted payload data is never written to disk at any point during the transfer.

The CT log persists cryptographic hashes (Merkle leaf hashes, tree hashes, device hashes) to disk: never payload content. Even a complete disk image of the relay server reveals no file contents.

Two-step burn: first the blob is zeroed in-place, then the Map entry is deleted. This prevents a brief window where a partial read could occur.

5 MB fixed padding (ParaShare)

ParaShare authenticated blobs are padded to exactly 5,242,880 bytes (5 MiB) with cryptographically random bytes before upload. An observer on the network cannot determine the size, type, or content of the transferred file. This is effective DPI masking for classified data flows.

Certificate Transparency log

Every transfer hash and device registration is appended to a public Merkle tree. The root hash changes with every write and is publicly verifiable. Anyone can prove a transfer occurred without learning what was transferred.

GET https://health.paramant.app/v2/ct/log?limit=100&offset=0

{
  "root": "cf7436a9efa4ee9a...",
  "entries": [
    { "index": 56, "leaf_hash": "ecb779...", "tree_hash": "cf7436...",
      "device_hash": "ce56ff...", "ts": "2026-04-14T19:07:57Z" }
  ]
}

Live CT log: paramant.app/ct-log →

W3C Decentralized Identity

Devices can register a W3C DID backed by ML-DSA-65 and ECDH keys. Once registered, subsequent requests are signed: no API key in the header.

POST /v2/did/register
{ "device_id": "mri-001", "ecdh_pub": "base64...", "dsa_pub": "base64..." }

{ "did": "did:paramant:abc123...", "ct_index": 42 }

# Authenticate with DID:
X-DID: did:paramant:abc123...
X-DID-Signature: base64_request_signed_with_dsa_key

Team management

# Create an API key (admin script)
python3 scripts/paramant-admin.py add \
  --label "scanner-room-3" --plan pro --email admin@hospital.nl

# Sync to all relay containers
python3 scripts/paramant-admin.py sync

# Revoke a key immediately
python3 scripts/paramant-admin.py revoke --label "scanner-room-3"
python3 scripts/paramant-admin.py sync

Key changes are zero-downtime: the relay hot-reloads users.json on sync without restart. Revoked keys receive WebSocket close code 4401 within seconds.

Retention policy

Relay sectors

All sector nodes run identical Ghost Pipe relay software. Sectors are routing domains: they provide traffic isolation and sector-specific compliance documentation. The crypto stack and API surface are identical.

Security: threat model

The relay is untrusted by design. Security does not depend on trusting the operator.

The threat model assumes network-level attackers, compromised relay operators, and post-quantum adversaries. Encryption uses a hybrid scheme (ML-KEM-768 + ECDH P-256) so that breaking either primitive is not sufficient: both must be broken simultaneously.

Jurisdiction

Managed relay infrastructure runs exclusively on Hetzner Nuremberg, Germany. EU/GDPR jurisdiction applies. No US Cloud Act jurisdiction: Hetzner is a German company with no US parent. No metadata leaves the EU.

Security audits

All findings are publicly documented in SECURITY.md. To report a vulnerability: privacy@paramant.app.

Compliance: NIS2 / DORA

NIS2 (EU 2022/2555) applies to operators of essential services in the EU. PARAMANT supports NIS2 compliance through:

• Post-quantum encryption (future-proof cryptographic resilience)
• Merkle CT log: tamper-evident audit trail for every transfer
• EU-only infrastructure (Hetzner DE): no data leaves EU jurisdiction
• Burn-on-read: minimises data retention exposure
• Zero-downtime key revocation: immediate incident response capability

DORA (EU 2022/2554) applies to financial entities. The finance.paramant.app sector is designed with DORA in mind: per-transaction Merkle proof, no US Cloud Act jurisdiction, ISO 20022 compatible.

View full NIS2 compliance documentation →

NEN 7510 (Healthcare)

NEN 7510 is the Dutch standard for information security in healthcare. The health.paramant.app sector is designed for NEN 7510 compliance:

• Encrypted in transit and at rest (technically: RAM only, never disk)
• Access logging via CT log: cryptographic proof of every access event
• Device identity registration (DID): traceable per-device access
• Key-based access control: per-user API keys with revocation
• Hetzner DE: EU GDPR jurisdiction, suitable for patient data routing

View full NEN 7510 compliance documentation →

IEC 62443 (Industrial / OT)

IEC 62443 is the international standard for operational technology security. The iot.paramant.app sector supports IEC 62443 deployments:

• Acts as a quantum-safe data diode: PLCs/sensors push data without opening inbound ports
• No VPN, no certificates on OT side: works with Raspberry Pi and any Linux device
• Fixed 5MB padding: traffic analysis cannot distinguish heartbeats from payloads
• Network segmentation: OT side connects outbound only; IT side receives inbound only
• ML-DSA-65 device signatures: cryptographic device authentication

View full IEC 62443 compliance documentation →

Operator scripts

Self-host operators get a set of command-line helpers under scripts/ in the paramant-relay repo. SSH into your relay host and run them from the repo root. For most of these there is an in-browser equivalent at /admin/cli (admin login required).

• Keys. scripts/paramant-key-add.sh: provision an API key.
• Signing. scripts/paramant-sign: ParaSign CLI: sign a document (ML-DSA-65, client-side) and notarise it into a .psign envelope, or verify one. See ADR R017.
• Deploy safety. scripts/post-deploy-verify.sh: post-deploy smoke test (exit 2 on critical failure); scripts/rollback-3.0.0.sh: roll back to the previously-built relay image.
• Backups. scripts/backup-users-json.sh: age-encrypted backup of relay key metadata (already wired into cron, 03:15 daily; decrypt only in tmpfs).

# on the relay host, from the repo root
./scripts/paramant-key-add.sh "customer-acme" pro ops@acme.example
./scripts/post-deploy-verify.sh https://paramant.app

Frequently asked questions