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 |
1. Defense-in-Depth & Threat Model
Section titled “1. Defense-in-Depth & Threat Model”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
2. Container, OS & Network Hardening
Section titled “2. Container, OS & Network Hardening”- Unprivileged Execution (
app/Dockerfile): All application services (api,worker,dashboard,topic-worker,pdf-worker) run as non-root userservice(UID 10001). - Immutable Root Filesystem (
compose.yaml): All application containers enforceread_only: true,tmpfs: [/tmp],cap_drop: [ALL],security_opt: [no-new-privileges:true], andpids_limit: 128(256onwaha). - Secret & Network Segregation:
postgresandpdf-workerattach only toprivate(internal: true), preventing outbound internet egress.dashboardandpdf-workersetenv_file: [], receiving onlyDATABASE_URL(andDASHBOARD_ORIGINfordashboard). Neither container ever accessesGOOGLE_API_KEY,CLOUDFLARE_API_TOKEN,WAHA_API_KEY_PLAIN, orWEBHOOK_SECRET.- Host port mappings for
api(127.0.0.1:18081),dashboard(127.0.0.1:18082), andwaha(127.0.0.1:13000) bind strictly to loopback. WAHA_DASHBOARD_ENABLED=falseandWHATSAPP_SWAGGER_ENABLED=falsedisable WAHA’s interactive management interfaces.- FastAPI disables interactive OpenAPI schemas in both
apianddashboard(docs_url=None, redoc_url=None, openapi_url=None).
- 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-workerenforces a 1,800-second wall-clock deadline (os.killpg(proc.pid, signal.SIGKILL)on timeout),8 MiBstdout cap, and suppresses parserstderr(DEVNULL) so passwords or source fragments never enter logs.
- Executed in a separate process group (
- Protected Host Secrets (
scripts/bootstrap.py,scripts/configure*.py):- Server-side
.env,secrets/, and deployment backups are written atomically underumask 0o077with0o600file permissions and never printed to stdout or committed to git.
- Server-side
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.hashstoresSHA-256digests of48-byteBearertokens (Authorization: Bearer <token>, max 512 chars). Tokens can be individually revoked viaDELETE /v1/credentials/{digest}. - RBAC & Scopes: Every API route validates both token
scopes(tickets:read,tickets:write,assist,admin) and activemembers.role(member,support,admin). - Member Isolation:
can_access()restrictsmembercallers to their own tickets and jobs.GET /v1/tickets/{tid}strips internal notes and sensitive detail keys formemberactors;GET /v1/faqstripssource_case_id. - Streamed Body & Rate Caps: Middleware enforces a strict
65,536-byte streamed payload cap (413) before parsing;rate_limit()locks themembersrow (FOR UPDATE) and limits each member to10requests/minute (429), whileenqueue()caps global active queue depth at100jobs (503).
4. Webhook, Identity & Media Security
Section titled “4. Webhook, Identity & Media Security”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:
- Enforces
<= 65,536bytes raw body size and non-emptyWEBHOOK_SECRET. - Computes
HMAC-SHA512(WEBHOOK_SECRET, raw_body)and checksx-webhook-hmacviahmac.compare_digest. - Enforces a
±300-second replay window againstevent.timestamp(milliseconds). - Restricts
session == 'default'andeventto'message'or'message.any'. - 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. - Validates
payload.id(1..300chars) andpayload.body(<= 4,000chars, allowing empty body only whenhasMedia == 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
@lididentifiers are resolved strictly through the private internalhttp://waha:3000/api/default/lids/<id>endpoint withX-Api-Key, verifying that the returnedlidmatches the sender andpnmatches[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 (../.). Onlyhttp://(waha|localhost|127.0.0.1):3000/api/files/[A-Za-z0-9_./@-]+is fetched. - Image Normalization & Decompression-Bomb Guard (
normalize_image): Enforces<= 5 MiBstreamed download,Image.MAX_IMAGE_PIXELS = 12,000,000(DecompressionBombWarningraisesMediaError), single-frame staticJPEG/PNG/WEBPonly, 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”5.1 Pre-Model & Storage Sanitization
Section titled “5.1 Pre-Model & Storage Sanitization”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 storingconversation_turns, sending prompts to AI providers, recordingticket_conversations, or rendering duty alerts.app/retrieval.py:public_text(): Strips query parameters namedtoken,key,api_key,secret,signature,sig,password,otp,access_token,authand masks/reset#URLs in retrieved KB content and saved checks.- No Raw Screenshot Transmission in History: Screenshot bytes are never stored in
conversation_turnsor replayed to subsequent turns;case_messages.media_bytesare 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”- 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. - Immutable System Boundaries (
app/ai_settings.py): Admin-editable prompt sections are validated (20–3000chars each,<= 14000total, rejectingAIza[0-9A-Za-z_-]{20,}Google API key literals), andFIXED_RULES,IMAGE_RULES,ACTION_RULES, andKNOWLEDGE_RULESare appended deterministically by the backend. All retrieved KB passages, conversation turns, and screenshots are explicitly framed as untrusted data. - Structured JSON Contract (
app/retrieval.py,app/ticket_language.py): Model output is constrained viaresponseSchemaand re-validated in Python (parse_ticket_decision) for exact field names, allowed enums (scope,action,answer_basis),1..5valid integerknowledge_ids, and<= 3000-char answers. - 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’sverified_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.
- LLMs cannot create tickets without explicit literal request (
6. Consent Governance & UU PDP No. 27/2022 Alignment
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:
- 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,30sgap,100/day,1/phone/day, explicit risk acknowledgment) mitigate workload bursts but do not guarantee immunity from WhatsApp enforcement. - 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).
7. Related Documentation
Section titled “7. Related Documentation”- ARCHITECTURE.md — Network segmentation and container isolation.
- DATA_MODEL.md — Data retention table and schema constraints.
- API_AND_INTERFACES.md — Endpoint auth, CSRF, and rate limits.
- OPERATIONS_AND_DEPLOYMENT.md — Secret provisioning, SSH pinning, and backups.
- Existing feature guides: accounts-and-cases.md, broadcasts.md, knowledge-intake.md, trusted-knowledge-publication.md, pdf-knowledge.md.