regulator-portal-service — Service Overview
Version: 1.0 Status: Draft Owner: Regulator-facing + Legal Last Updated: 2026-04-21 References: ADR-0004 §3, 07-epics-and-user-stories.md §6.9, 13-security-compliance-tenancy.md
1. Purpose
regulator-portal-service is the platform's regulator-facing surface. It provides ATRA (Afghanistan Telecom Regulatory Authority) and other authorised regulators with:
- A login portal authenticated against national PKI / mTLS only.
- On-demand and scheduled access to platform reports (CDR submissions, consent audit, sender-ID registry exports, compliance reports).
- A workflow for lawful intercept (LI) requests per ETSI TS 102 232 (IRI / CC distinction), with SLA enforcement and immutable audit.
- A complaint-ingest channel for citizen complaints forwarded by ATRA.
- A SIEM-forwarding pipeline for security and compliance events to government-operated Splunk/ELK/QRadar.
- Periodic compliance attestations infrastructure (ISO 27001, ISO 27017/27018, SOC 2 Type II, GSMA AA.18).
Without this service, every regulator interaction would be ad-hoc, manual, and audit-defeating. With it, Ghasi has a defensible, automated regulator-of-record interface that other vendors lack.
2. Bounded Context
| Concern | In scope | Out of scope |
|---|---|---|
| Regulator authentication via national PKI | ✅ | National PKI issuance |
| LI request workflow + SLA enforcement | ✅ | Actual intercept implementation (delegated to MNOs / cdr-mediation-service) |
| Complaint ingest + triage workflow | ✅ | Complaint resolution (handled by Customer Success + relevant tenant) |
| Compliance attestation evidence collection | ✅ | Audit firm engagement (procurement) |
| SIEM forwarding (CEF/LEEF) | ✅ | SIEM operation (regulator-owned) |
| Regulator-portal UI | ✅ (BFF + UI) | Citizen-facing UI |
3. Key Responsibilities
- Authenticate regulator users via mTLS + national PKI (no shared passwords; cert revocation honoured).
- Maintain an LI-request workflow with state machine
RECEIVED → ACK → IN_PROGRESS → DELIVERED → CLOSEDand 24h SLA enforcement. - Accept ATRA-forwarded citizen complaints; route to triage queue in
admin-dashboard. - Stream security and compliance events (
auth.events.*,compliance.audit.v1,sender.id.*,consent.*) to configured SIEM destinations using CEF/LEEF formats. - Generate scheduled regulator reports (daily CDR submission status, monthly compliance summary, quarterly platform health).
- Maintain compliance attestation evidence catalog with currency status (
CURRENT / STALE / MISSING).
4. Dependencies
| Direction | Dependency | Reason |
|---|---|---|
| Inbound | ATRA users (Web UI via mTLS) | Regulator portal access |
| Inbound | Regulator API clients (REST mTLS) | Programmatic LI submission |
| Outbound | cdr-mediation-service | CDR submission status reads |
| Outbound | compliance-engine | Audit-log and report queries |
| Outbound | consent-ledger-service | Consent audit queries |
| Outbound | sender-id-registry-service | Registry exports |
| Outbound | analytics-service (ClickHouse cold-tier) | Long-window queries |
| Outbound | NATS (regulator.*) | Event emission for downstream reporting |
| Outbound | SIEM endpoints (Splunk HEC / Logstash / QRadar) | Event forwarding |
| Outbound | Postgres (regulator schema) | LI requests, complaints, attestations |
| Outbound | Vault | SIEM auth tokens, signing keys |
| Outbound | Object storage (s3://ghasi-regulator/ ) | Report artifacts, signed reports |
5. Runtime Topology
6. Key Design Decisions
- mTLS + national PKI ONLY — no passwords, no API keys for regulators. Cert revocation (CRL/OCSP) honoured. Failed handshake is loud (alert + audit row).
- Read-only against upstream —
regulator-portal-servicenever mutates upstream data. It assembles, signs, and serves. Mutation to compliance/consent/CDR remains owned by the respective service. - LI requests are append-only and dual-control — every state transition requires both regulator initiator and Ghasi legal/security approver. Bypass requires CISO + CTO signature.
- SIEM forwarder is at-least-once — durable NATS consumer with explicit ACK after SIEM confirms receipt. Drop > 60 s lag → alert.
- Reports are signed — every regulator report PDF is signed with a dedicated regulator-reports key (HSM-bound). Tampering detectable.
- Time-bounded report retention in service — service holds reports 90 d hot; longer term in object storage with 7-y lifecycle.
7. Surface Inventory
| Interface | Purpose | Auth |
|---|---|---|
HTTPS Web /login | Regulator portal UI login | mTLS national PKI |
REST POST /v1/regulator/li/requests | Submit LI request | mTLS regulator role |
REST GET /v1/regulator/li/requests | List own LI requests | mTLS regulator role |
REST POST /v1/regulator/complaints | Forward citizen complaint | mTLS regulator role |
REST POST /v1/regulator/reports | Generate ad-hoc report | mTLS regulator role |
REST GET /v1/regulator/reports/:id/download | Signed PDF | mTLS regulator role |
REST GET /v1/regulator/attestations | Compliance attestation status | mTLS regulator role + auditor |
HTTP /health/live, /health/ready, /metrics | K8s + Prom | None / cluster |
NATS produce regulator.report.submitted.v1, regulator.complaint.received.v1, regulator.li.transitioned.v1 | Downstream | — |
8. Data Ownership
regulator schema:
regulator.li_requests— LI workflow rows + per-state SLA timestampsregulator.li_audit— append-only state-transition logregulator.complaints— ingested complaints + triage statusregulator.attestations— control families + evidence statusregulator.scheduled_reports— schedule + last-run metadataregulator.siem_destinations— per-target config + authregulator.signing_keys_ref— Vault path pointers; HSM-held
9. Failure Modes
- mTLS handshake failure storm → alert (probing detection); cert chain auto-refresh.
- SIEM destination unreachable → buffer in NATS with alert; if buffer > 1 h, fail to disk + alert critical.
- LI SLA breach → automatic alert to Legal + CISO + Regulator-liaison.
- Report generation failure → retry 3×; if persistent → fall back to manual ticket; SLA pause.
- Signing key unavailable → block report download; reports remain pending; alert critical.
10. Open Points
| ID | Question | Owner | Resolution |
|---|---|---|---|
| REG-OPEN-001 | National-PKI issuer — which CAs does Ghasi trust for regulator users? | Legal | TBD |
| REG-OPEN-002 | LI implementation — does Ghasi intercept itself, delegate to MNOs, or both? Scope of role. | Legal + Platform Council | TBD |
| REG-OPEN-003 | Regulator-portal UI hosting region — sovereign Afghan only or also Dubai DR? | Platform Arch | TBD |
| REG-OPEN-004 | SIEM destination shape — does ATRA operate Splunk, ELK, QRadar, or other? | Regulator Liaison | TBD |