cbc-bridge-service — Service Overview
Version: 1.0 Status: Draft Owner: Government / Emergency Last Updated: 2026-04-21 References: ADR-0004 §3, 07-epics-and-user-stories.md §6.6, 03-platform-services.md
1. Purpose
cbc-bridge-service is the platform's bridge to MNO Cell-Broadcast (CBC) functions for civil emergency alerts (earthquake, flood, security, public health, civil defence). It implements 3GPP TS 23.041 / ETSI EN 302 117 cell-broadcast protocols against MNO RAN endpoints (BSC/RNC/eNB CBC interfaces or the MNO's CBE — Cell Broadcast Entity) so that authenticated government clients can broadcast prioritised messages to every handset in a defined geographic area.
This is not an SMS-A2P service. It targets the broadcast channel and is reachable only from the platform via mTLS by authorised callers (regulator-portal-service and pre-approved government clients with national-PKI credentials). Its existence is a strategic differentiator versus Twilio/Infobip/Sinch — none of them operate national CBC.
2. Bounded Context
| Concern | In scope | Out of scope |
|---|---|---|
| 3GPP TS 23.041 Cell Broadcast Service (CBS) message formatting | ✅ | — |
| ETSI EN 302 117 Common Alerting Protocol (CAP) bridge | ✅ | — |
| MNO RAN / CBE integration per Afghan operator | ✅ | A2P SMS dispatch (owned by smpp-connector) |
| Government-PKI signature verification on broadcast requests | ✅ | Issuance of government PKI |
| Geographic targeting (Cell ID list, polygon, country, region) | ✅ | Map UI (owned by regulator-portal-service) |
| Multi-language broadcast (Pashto / Dari / Arabic / English) | ✅ | UCS-2 SMS encoding (owned by smpp-connector) |
| Broadcast acknowledgement aggregation | ✅ | Per-citizen delivery receipt (CBS does not provide this) |
| Drill / test broadcasts | ✅ | Public push notifications (owned by notification-service) |
3. Key Responsibilities
- Accept emergency-broadcast requests via gRPC
BroadcastEmergencyfrom authorised callers only (mTLS + national-PKI signature). - Translate the request into 3GPP TS 23.041 CBS message PDUs (or MNO-vendor proprietary CBE protocol where standard CBS isn't supported).
- Dispatch to all MNO CBE endpoints in parallel; aggregate per-MNO acknowledgements.
- Persist a hash-chained immutable record of every broadcast for regulator audit.
- Provide a Drill Mode that exercises the full path with a designated
Testchannel (3GPP TS 23.041 Message Identifier in the test range) so that drills are visibly distinct on subscriber handsets. - Emit
cbc.broadcast.requested.v1,cbc.broadcast.dispatched.v1,cbc.broadcast.acked.v1,cbc.broadcast.failed.v1for downstream observability.
4. Dependencies
| Direction | Dependency | Reason |
|---|---|---|
| Inbound | regulator-portal-service (gRPC mTLS) | Operator workflow for authorised broadcasts |
| Inbound | Government clients (gRPC mTLS, national PKI) | Direct emergency request from civil-defence systems |
| Inbound | auth-service JWKS | Verifies platform-JWT-tokens on REST admin surface |
| Outbound | MNO CBE endpoints (TCP / proprietary CBE protocol) | Actual broadcast dispatch |
| Outbound | NATS JetStream (cbc.* subjects) | Event emission |
| Outbound | Postgres (cbc.* schema) | Broadcast records, ack aggregation |
| Outbound | HSM (PKCS#11) | Signature verification of inbound requests using national PKI |
| Outbound | Vault | Per-MNO CBE credentials |
5. Runtime Topology
6. Key Design Decisions
- Government PKI signature mandatory — every
BroadcastEmergencycarries anX-Gov-Signatureheader signed by a recognised national-PKI cert. Verification is HSM-bound; in-process key fallback is forbidden. A failure is loud (alert + audit row). - Vendor abstraction over CBE protocols — Afghan MNOs do not all expose standard 3GPP CBE protocol. The service abstracts CBE clients per MNO behind a
CbeAdapterport:Standard3gppCbeAdapter,EricssonProprietaryCbeAdapter,HuaweiProprietaryCbeAdapter. New MNO ⇒ implement adapter. - Fail-open dispatch with per-MNO degradation — a broadcast must reach as many MNOs as possible. If one MNO CBE rejects/timeouts, others continue. Final status is
PARTIALwith per-MNO breakdown rather than blocking on the slowest MNO. Government caller is informed of partial reach. - Hash-chained immutable broadcast log — every broadcast row in
cbc.broadcastscarriesprev_hash,payload_hash, andrecord_hash; rolling chain is appended to NATScbc.audit.v1and forwarded toregulator-portal-service. Tampering is detectable. - Drill mode is first-class — drill broadcasts use 3GPP CBS Message Identifier in the test range (4370..4379) and carry an explicit "DRILL — NO ACTION REQUIRED" prefix in every language. Drill is monthly, scheduled, and verifiable.
7. Surface Inventory
| Interface | Purpose | Auth |
|---|---|---|
gRPC BroadcastEmergency(req) returns (BroadcastResponse) | Submit a broadcast | mTLS + national-PKI signature |
gRPC GetBroadcastStatus(broadcastId) returns (Status) | Poll per-MNO ack status | mTLS, caller-of-record only |
gRPC CancelBroadcast(broadcastId) returns (CancelResponse) | Cancel a pending broadcast | mTLS, caller-of-record + 2nd approver |
REST GET /v1/cbc/broadcasts | Admin list (regulator workbench) | Kong JWT, regulator.read role |
REST GET /v1/cbc/broadcasts/:id/audit | Audit-log fetch (hash-chained) | Kong JWT, regulator.audit role |
REST POST /v1/cbc/drill | Schedule a drill | Kong JWT, cbc.admin role |
HTTP /health/live /health/ready /metrics | K8s + Prometheus | None / cluster-internal |
NATS produce cbc.broadcast.requested.v1 cbc.broadcast.dispatched.v1 cbc.broadcast.acked.v1 cbc.broadcast.failed.v1 cbc.audit.v1 | Downstream | — |
8. Data Ownership
cbc schema in PostgreSQL:
cbc.broadcasts— every request, withprev_hash/record_hashchaincbc.mno_dispatches— per-broadcast per-MNO dispatch row + ackcbc.cbe_credentials_ref— pointer to Vault path (no secrets in PG)cbc.drills— scheduled drill recordscbc.signature_audit— every PKI signature verification result (success / failure)
9. Failure Modes (summary)
- All MNO CBEs unreachable → broadcast status
FAILED; PagerDuty Critical; government caller informed; manual fallback runbook (call MNO NOC desks). - HSM unavailable → signature verification fails-closed; service refuses all
BroadcastEmergencycalls; alert. - Some MNO CBEs partial-success → status
PARTIAL; per-MNO detail in response; auto-retry strategy per adapter. - MNO CBE rejects payload → log to
cbc.signature_audit; do not silently retry (regulator must investigate why valid request was refused).
10. Open Points
| ID | Question | Owner | Resolution |
|---|---|---|---|
| CBC-OPEN-001 | National-PKI authority — which CA does Ghasi trust for government PKI? | Legal + Government | TBD |
| CBC-OPEN-002 | Per-MNO CBE protocol negotiation — which MNOs run standard 3GPP CBE vs proprietary? | MNO Partnerships | TBD |
| CBC-OPEN-003 | Drill cadence — monthly platform-wide, or only on government request? | Government / NDMA | TBD |
| CBC-OPEN-004 | Fallback when CBE unreachable — does the platform auto-fall-back to high-throughput SMS A2P? (Major commercial implication.) | Platform Council | TBD |