cloakd.app

Architecture

cloakd.app runs as a single Docker container behind nginx on a Hetzner VPS in Frankfurt. All processing happens in-memory or in /tmp. No input files are persisted. Output files auto-delete after 1 hour.

Processing Modes

Providers & Engines

cloakd.app combines multiple specialized engines to detect and redact different types of sensitive data:

How They Connect

Pricing

Simple, transparent pricing. No hidden fees. All plans include every file type and redaction engine. EU-hosted, GDPR-compliant.

Authentication

All redaction requests require a Bearer token in the Authorization header. API keys are created via the admin endpoint using the master key.

Two types of keys

API keys are hashed with bcrypt before storage. The plaintext key is returned only once at creation time and cannot be retrieved again.

POST /v1/redact

The core endpoint. Accepts a file or text, detects and redacts all sensitive data, returns the cleaned output with a redaction report.

Option A: File Upload (multipart)

POST /v1/redact
Authorization: Bearer <api_key>
Content-Type: multipart/form-data

-- Form fields --
file:     <binary file data>
options:  '{"redact_pii": true, "redact_faces": true, "redact_financial": true, "replacement_style": "mask", "language": "en"}'

Option B: Plain Text (JSON body)

POST /v1/redact
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "text": "Contact Hans Mueller at hans@firma.de, IBAN DE89370400440532013000",
  "options": {
    "redact_pii": true,
    "redact_financial": true,
    "replacement_style": "mask",
    "language": "en"
  }
}

Options

Response (synchronous)

{
  "status": "success",
  "file_type": "text/plain",
  "redacted_file_url": null,
  "redacted_text": "Contact [PERSON] at [EMAIL_ADDRESS], IBAN [IBAN_CODE]",
  "report": {
    "total_entities_found": 3,
    "entities": [
      { "type": "PERSON", "count": 1, "risk": "high", "replacement": "[PERSON]" },
      { "type": "EMAIL_ADDRESS", "count": 1, "risk": "high", "replacement": "[EMAIL_ADDRESS]" },
      { "type": "IBAN_CODE", "count": 1, "risk": "high", "replacement": "[IBAN_CODE]" }
    ],
    "processing_time_ms": 6,
    "engines_used": ["text"]
  }
}

Response (async — video/audio)

{
  "job_id": "a1b2c3d4e5f6...",
  "status": "pending",
  "progress": null,
  "result": null,
  "error": null
}

Error Codes

GET /v1/jobs/{job_id}

Poll the status of an asynchronous redaction job (video or audio files).

{
  "job_id": "a1b2c3d4e5f6...",
  "status": "completed",      // pending | processing | completed | failed
  "progress": 100,              // 0-100
  "result": {
    "status": "success",
    "file_type": "video/mp4",
    "redacted_file_url": "/v1/files/abc123.mp4",
    "report": { ... }
  },
  "error": null
}

POST /v1/keys

Create a new API key. Requires the master API key for authentication.

POST /v1/keys
Authorization: Bearer <master_api_key>
Content-Type: application/json

{ "owner_email": "developer@company.com" }

{
  "api_key": "JeQ-0V1_V3ZhioVnb8m3bCiHQX2HD9NSRa-6GSgF97g",
  "message": "Store this key securely -- it cannot be retrieved again."
}

GET /health

{ "status": "healthy", "version": "0.1.0" }

Entity Types

cloakd.app detects these PII entity types using Microsoft Presidio + spaCy NLP:

Replacement Styles

Hans Mueller   -> [PERSON]
hans@firma.de  -> [EMAIL_ADDRESS]
DE893704...    -> [IBAN_CODE]

Hans Mueller   -> <PERSON_1>
Anna Schmidt   -> <PERSON_2>
Hans Mueller   -> <PERSON_1>

Hans Mueller   -> Thomas Weber
hans@firma.de  -> lisa@example.net
DE893704...    -> DE12500105170648489890

Supported File Types

Text & Document Redaction

Image Redaction

Video Redaction

Video is processed asynchronously. Submit the file, receive a job_id, and poll GET /v1/jobs/{job_id} for progress.

Audio Redaction

Audio is processed via the AssemblyAI API, which provides both speech-to-text and PII redaction.

AssemblyAI PII Policies

PII in audio is replaced with hash substitution in the transcript and beeped out in the audio file.

Deployment

Docker Container

• Base image: python:3.11-slim (Debian Trixie)
• System packages: libmagic, tesseract-ocr (EN + DE), OpenCV libs, ffmpeg
• Python packages: FastAPI, Presidio, spaCy, OpenCV, moviepy, AssemblyAI SDK
• spaCy models: en_core_web_lg (~560MB), de_core_news_lg (~540MB)
• RAM usage: ~758 MB

Rate Limiting

Rate limit key is the SHA256 hash of the Bearer token. Falls back to client IP if no token provided. Exceeding returns 429.

Security

HTTP Headers

Data Handling

• Input files are never persisted -- processed in-memory or /tmp, deleted immediately
• Output files auto-delete after 1 hour
• API keys are stored as bcrypt hashes -- plaintext cannot be recovered
• TLS 1.2/1.3 only, strong cipher suites
• Exploit paths (.php, .asp, .jsp, dotfiles) blocked at nginx

Environment Variables

All Endpoints