Skip to content

Security & Data Privacy Architecture

Field Value
Document ID DA-SEC-001
Pillar Data
Standard Alignment OWASP / ISO 27001 / UU PDP No. 27/2022
Status Active / Synchronized with Codebase
Last Updated 2026-11-21
Source of Truth compose.yaml, app/Dockerfile, app/main.py, app/dashboard.py, app/dashboard_auth.py, app/security.py, app/policy.py, app/conversation.py, app/media.py, app/identity.py, app/retrieval.py, app/ticket_flow.py, app/ticket_language.py, app/ai_settings.py, app/broadcasts.py, app/pdf_extract.py, app/management.py, app/admin_accounts.py, scripts/bootstrap.py, scripts/deploy-server.sh

Dirman Assist processes untrusted WhatsApp messages, user-uploaded screenshots, organizational PDFs, and authenticated administrative traffic. Security controls are structured across five concentric layers:

flowchart TB
    L1["1. Infrastructure & Container Isolation: UID 10001, read_only FS, cap_drop ALL, private internal network, loopback ports"]
    L2["2. Transport & Edge Controls: Traefik TLS, Strict CSP, __Host- cookies, Same-Origin, HMAC-SHA512 webhook verification"]
    L3["3. Identity, RBAC & Throttling: scrypt passwords, SHA-256 session/API tokens, CSRF tokens, 5/10m login lock, 10/m member cap"]
    L4["4. AI & Content Guardrails: Regex PII redaction, injection blocking, fixed system rules, JSON action enum, backend citation/URL checks"]
    L5["5. Privacy & Consent Governance: Opt-in broadcasts, explicit ticket consent, TTL purges (24h/30d/180d), audit trails"]
    L1 --> L2 --> L3 --> L4 --> L5

  1. Unprivileged Execution (app/Dockerfile): All application services (api, worker, dashboard, topic-worker, pdf-worker) run as non-root user service (UID 10001).
  2. Immutable Root Filesystem (compose.yaml): All application containers enforce read_only: true, tmpfs: [/tmp], cap_drop: [ALL], security_opt: [no-new-privileges:true], and pids_limit: 128 (256 on waha).
  3. Secret & Network Segregation:
    • postgres and pdf-worker attach only to private (internal: true), preventing outbound internet egress.
    • dashboard and pdf-worker set env_file: [], receiving only DATABASE_URL (and DASHBOARD_ORIGIN for dashboard). Neither container ever accesses GOOGLE_API_KEY, CLOUDFLARE_API_TOKEN, WAHA_API_KEY_PLAIN, or WEBHOOK_SECRET.
    • Host port mappings for api (127.0.0.1:18081), dashboard (127.0.0.1:18082), and waha (127.0.0.1:13000) bind strictly to loopback.
    • WAHA_DASHBOARD_ENABLED=false and WHATSAPP_SWAGGER_ENABLED=false disable WAHA’s interactive management interfaces.
    • FastAPI disables interactive OpenAPI schemas in both api and dashboard (docs_url=None, redoc_url=None, openapi_url=None).
  4. PDF Subprocess Sandboxing (app/pdf_extract.py):
    • Executed in a separate process group (start_new_session=True) under OS resource limits: RLIMIT_AS = 384 MiB, RLIMIT_FSIZE = 32 MiB, RLIMIT_CPU = 210s.
    • Parent pdf-worker enforces a 1,800-second wall-clock deadline (os.killpg(proc.pid, signal.SIGKILL) on timeout), 8 MiB stdout cap, and suppresses parser stderr (DEVNULL) so passwords or source fragments never enter logs.
  5. Protected Host Secrets (scripts/bootstrap.py, scripts/configure*.py):
    • Server-side .env, secrets/, and deployment backups are written atomically under umask 0o077 with 0o600 file permissions and never printed to stdout or committed to git.

3. Authentication, Authorization & Session Security

Section titled “3. Authentication, Authorization & Session Security”

3.1 Management Dashboard (app/dashboard_auth.py, app/dashboard.py)

Section titled “3.1 Management Dashboard (app/dashboard_auth.py, app/dashboard.py)”
Control Implementation Details
Password Storage hashlib.scrypt (n=16384, r=8, p=1, dklen=64, 16-byte random hex salt); DUMMY_HASH verified on unknown usernames to prevent timing-based account enumeration.
Session Cookies __Host-dirman_session (HttpOnly, Secure, SameSite=Strict, Path=/, 8-hour TTL). Raw 32-byte URL-safe token exists only in browser cookie; PostgreSQL stores SHA-256(token) in dashboard_sessions.
CSRF Protection Double-submit token in __Host-dirman_csrf (Secure, SameSite=Strict, non-HttpOnly) paired with X-CSRF-Token request header validated via hmac.compare_digest(SHA-256(header), session.csrf_hash) on all non-GET/HEAD/OPTIONS mutations.
Same-Origin Enforcement same_origin() rejects login, password reset, and all authenticated mutations whose Origin header does not match DASHBOARD_ORIGIN (https://assist.p3mdi.id).
Brute-Force Throttling sign_in() serializes on pg_advisory_xact_lock(902714) and enforces max 5 attempts per 10 minutes by SHA-256(client_ip) OR username. uvicorn trusts forwarded client headers only from ${DASHBOARD_TRUSTED_PROXY_IPS:-127.0.0.1}.
Password Recovery Admin-issued single-use tokens (32 bytes URL-safe), stored as SHA-256 hash in password_resets (30-minute TTL, max 5 issuances/target/hour). Delivered via /reset#TOKEN fragment, stripped immediately from URL bar via history.replaceState (management.js), never sent in HTTP path/query or logs.
Session & Reset Revocation Changing password, editing username/email/phone, disabling login, or removing admin role immediately purges dashboard_sessions and password_resets for that account.
Self & Last-Admin Guards Active admins cannot disable/demote themselves or remove/disable the last remaining active administrator (admin_accounts.py, dashboard.py, management.py).
HTTP Security Headers Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self', plus X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Cache-Control: no-store, Permissions-Policy: camera=(), microphone=(), geolocation=().

3.2 App Hub Scoped API (app/main.py, app/operator.py)

Section titled “3.2 App Hub Scoped API (app/main.py, app/operator.py)”
  • Credential Storage: credentials.hash stores SHA-256 digests of 48-byte Bearer tokens (Authorization: Bearer <token>, max 512 chars). Tokens can be individually revoked via DELETE /v1/credentials/{digest}.
  • RBAC & Scopes: Every API route validates both token scopes (tickets:read, tickets:write, assist, admin) and active members.role (member, support, admin).
  • Member Isolation: can_access() restricts member callers to their own tickets and jobs. GET /v1/tickets/{tid} strips internal notes and sensitive detail keys for member actors; GET /v1/faq strips source_case_id.
  • Streamed Body & Rate Caps: Middleware enforces a strict 65,536-byte streamed payload cap (413) before parsing; rate_limit() locks the members row (FOR UPDATE) and limits each member to 10 requests/minute (429), while enqueue() caps global active queue depth at 100 jobs (503).

4.1 WAHA Webhook Verification (app/security.py)

Section titled “4.1 WAHA Webhook Verification (app/security.py)”

POST /webhooks/waha validates every inbound event before touching business logic:

  1. Enforces <= 65,536 bytes raw body size and non-empty WEBHOOK_SECRET.
  2. Computes HMAC-SHA512(WEBHOOK_SECRET, raw_body) and checks x-webhook-hmac via hmac.compare_digest.
  3. Enforces a ±300-second replay window against event.timestamp (milliseconds).
  4. Restricts session == 'default' and event to 'message' or 'message.any'.
  5. Permits only 1-to-1 peer JIDs matching (?:[0-9]{7,16}@c\.us|[0-9]{7,25}@lid)—automatically excluding group chats (@g.us) and status broadcasts.
  6. Validates payload.id (1..300 chars) and payload.body (<= 4,000 chars, allowing empty body only when hasMedia == true).

4.2 WhatsApp Identity & Media SSRF Protection (app/identity.py, app/media.py)

Section titled “4.2 WhatsApp Identity & Media SSRF Protection (app/identity.py, app/media.py)”
  • LID Resolution: Masked WhatsApp @lid identifiers are resolved strictly through the private internal http://waha:3000/api/default/lids/<id> endpoint with X-Api-Key, verifying that the returned lid matches the sender and pn matches [0-9]{7,16}@c.us.
  • Media URL Allowlisting (canonical_media_url): Rejects arbitrary external URLs, redirects (follow_redirects=False), credentials, query strings, fragments, and path traversal (../.). Only http://(waha|localhost|127.0.0.1):3000/api/files/[A-Za-z0-9_./@-]+ is fetched.
  • Image Normalization & Decompression-Bomb Guard (normalize_image): Enforces <= 5 MiB streamed download, Image.MAX_IMAGE_PIXELS = 12,000,000 (DecompressionBombWarning raises MediaError), single-frame static JPEG/PNG/WEBP only, EXIF auto-orientation, resize to <= 1600×1600, and re-encoding to stripped JPEG (removing embedded metadata/EXIF).

5. AI Security, PII Redaction & Grounding Controls

Section titled “5. AI Security, PII Redaction & Grounding Controls”
  • app/security.py:redact() & app/conversation.py:sanitize(): Strip secret assignments (password, passwd, token, api_key, secret, otp, pin, kata sandi), /reset#<token> fragments, emails ([EMAIL]), and phone/numeric strings ([NUMBER]) before storing conversation_turns, sending prompts to AI providers, recording ticket_conversations, or rendering duty alerts.
  • app/retrieval.py:public_text(): Strips query parameters named token, key, api_key, secret, signature, sig, password, otp, access_token, auth and masks /reset# URLs in retrieved KB content and saved checks.
  • No Raw Screenshot Transmission in History: Screenshot bytes are never stored in conversation_turns or replayed to subsequent turns; case_messages.media_bytes are stored privately in PostgreSQL for 30 days solely for authenticated staff inspection in the dashboard.

5.2 Prompt Injection & Output Boundary Enforcement

Section titled “5.2 Prompt Injection & Output Boundary Enforcement”
  1. Deterministic Pre-Filters (app/policy.py): injection_attempt() catches English/Indonesian prompt-override and secret-exfiltration attempts; clearly_unrelated() rejects off-topic requests (e.g., food/recipes) before calling the AI provider.
  2. Immutable System Boundaries (app/ai_settings.py): Admin-editable prompt sections are validated (20–3000 chars each, <= 14000 total, rejecting AIza[0-9A-Za-z_-]{20,} Google API key literals), and FIXED_RULES, IMAGE_RULES, ACTION_RULES, and KNOWLEDGE_RULES are appended deterministically by the backend. All retrieved KB passages, conversation turns, and screenshots are explicitly framed as untrusted data.
  3. Structured JSON Contract (app/retrieval.py, app/ticket_language.py): Model output is constrained via responseSchema and re-validated in Python (parse_ticket_decision) for exact field names, allowed enums (scope, action, answer_basis), 1..5 valid integer knowledge_ids, and <= 3000-char answers.
  4. Backend-Owned Authorization & Citation Validation:
    • LLMs cannot create tickets without explicit literal request (creation_requested) or confirmation (confirmation), cannot read foreign members’ tickets, and cannot assign staff, change priority, or alter credentials.
    • retrieval.citations() verifies that every cited KB ID belongs to the current turn’s verified_evidence, remains published/unexpired/unmodified in PostgreSQL, and that all URLs in the generated reply appear verbatim in the cited evidence (urls(answer) <= allowed_urls).
    • Vision keyword extraction (extract_image_query) strips 4+ digit numbers, 24+ char token-like strings, and all URLs from extracted image keywords, and blocks screenshot-triggered ticket actions.

Section titled “6. Consent Governance & UU PDP No. 27/2022 Alignment”

Dirman Assist’s data handling aligns with Indonesia’s UU No. 27 Tahun 2022 tentang Pelindungan Data Pribadi (UU PDP) through technical enforcement of data protection principles:

UU PDP Principle Technical Implementation in Dirman Assist
Lawfulness & Explicit Consent (Pasal 20) Broadcasts require explicit opt-in (DAFTAR PENGUMUMAN, /SUBSCRIBE, or documented admin evidence >= 10 chars in broadcast_consent_events). Ticket creation requires explicit member request or confirmation (ticket_conversations). On-duty admin notifications require individual opt-in bound to a confirmed phone number (admin_duty).
Right to Withdraw Consent (Pasal 40) Members can immediately opt out via WhatsApp (STOP, STOP PENGUMUMAN, BERHENTI PENGUMUMAN, /STOP), committed before queueing replies so full queues never drop an unsubscribe. Admins can disable duty notifications or contributor permissions immediately.
Purpose Limitation & Data Minimization (Pasal 16) analytics_messages records only SHA-256 job_hash, timestamps, channel, outcome category, and timings—never message text, member ID, phone, email, or images. admin_duty alerts omit full descriptions and phone numbers. knowledge_documents with visibility='internal' are excluded from bot retrieval and catalogs.
Storage Limitation (Pasal 16 / Retention) Strict automated TTLs purge ticket_conversations / knowledge_intake_pending (15m), password_resets (30m), ai_config_tests (1h), dashboard_sessions (8h), conversation_turns (24h), ai_usage (7d), support_cases / case_messages / jobs / waha_sent_messages / knowledge_intake_receipts (30d), and analytics_messages (180d). jobs.question and media_url are nulled immediately upon completion.
Security & Confidentiality (Pasal 35–39) Salted scrypt passwords, SHA-256 hashed tokens/sessions, TLS via Traefik, loopback service bindings, internal network isolation for PostgreSQL and PDF extraction, and immutable audit logs (management_events, ticket_events, knowledge_intake_events, knowledge_decision_events).

Third-Party & Operational Risk Disclosures

Section titled “Third-Party & Operational Risk Disclosures”

As documented in README.md and docs/broadcasts.md:

  1. Unofficial WhatsApp Integration (WAHA): WAHA (WEBJS) is an unofficial WhatsApp Web automation client. Sending bulk announcements or high-volume replies carries inherent WhatsApp account-restriction risk. Operational limits (09.00–18.00 WIB, 30s gap, 100/day, 1/phone/day, explicit risk acknowledgment) mitigate workload bursts but do not guarantee immunity from WhatsApp enforcement.
  2. External AI Providers (Google AI Studio & Cloudflare Workers AI): Free-tier provider terms may permit provider review or model-improvement use of submitted prompts. Publish only information suitable for the intended audience; regex PII redaction (redact/sanitize) is best-effort and cannot substitute for human content review (docs/knowledge-retrieval.md).