sender-id-registry-service — Service Overview
Version: 1.0 Status: Draft Owner: Trust & Safety + Regulator-facing Last Updated: 2026-04-21 References: ADR-0004 §3, 07-epics-and-user-stories.md §6.3, 13-security-compliance-tenancy.md
1. Purpose
sender-id-registry-service is the platform's national authority for SMS sender-ID (alpha-ID and short-code) registration, KYC, verification, suspension, and reputation scoring. It exposes a public registry queryable by tenants, regulators, and citizens, and feeds gating decisions into compliance-engine, sms-firewall-service, and routing-engine.
The service is the platform's bid to become the sender-ID registry that ATRA eventually adopts as the national authority — analogous to India's DLT or KSA's CITC registry. This is a strategic play to lock in regulatory primacy and remove a major class of impersonation fraud.
2. Bounded Context
| Concern | In scope | Out of scope |
|---|---|---|
| Sender-ID registration with KYC | ✅ | Citizen ID issuance |
| Verification (DNS-TXT / OTP / notarised document) | ✅ | National-PKI authority issuance |
| Suspension, rotation, regulator export, public search | ✅ | Sender-ID deletion (audit-immortal) |
| Reputation scoring per sender-ID | ✅ | Tenant compliance score (owned by compliance-engine) |
| Cross-feeding of compliance + fraud signals into reputation | ✅ | Detection of those signals |
3. Key Responsibilities
- Accept tenant submissions for sender-IDs (alpha-IDs 1–11 chars, short-codes 4–6 digits, long codes E.164).
- Capture KYC of the registrant (commercial license / national ID / regulator letter / notarised authority); document hash + S3 ref retained.
- Verify the registrant's claim via one of: DNS-TXT challenge (for domain-affiliated alpha-IDs), OTP to registrant phone, or notarised document review.
- Maintain registry state machine:
SUBMITTED → KYC_REVIEW → VERIFIED → ACTIVE → SUSPENDED → REVOKED. - Publish
Verify(senderId, tenantId)gRPC consumed bycompliance-engineSENDER_ID rule androuting-enginelast-mile veto. - Compute reputation score per sender-ID daily from compliance hits, complaint rate, fraud signals, and DLR delivery patterns.
- Public search API for citizens: "Who registered sender-ID
BANK-XYZ?" with verification level disclosed.
4. Dependencies
| Direction | Dependency | Reason |
|---|---|---|
| Inbound | Tenant API (REST + customer portal) | Sender-ID submission |
| Inbound | admin-dashboard (T&S workbench) | Approval workflow |
| Inbound | compliance-engine (gRPC Verify) | Per-message SENDER_ID rule |
| Inbound | routing-engine (gRPC Verify) | Last-mile veto |
| Inbound | sms-firewall-service (gRPC Verify) | Inbound MT firewall check |
| Inbound | Citizen-facing public search REST | Verification disclosure |
| Inbound | regulator-portal-service | Registry export |
| Outbound | NATS (sender.id.*) | State change events |
| Outbound | compliance-engine (consume reputation) | Reputation feeds compliance scoring |
| Outbound | fraud-intel-service (consume signals) | Fraud signals feed reputation |
| Outbound | Postgres (sender_id_registry schema) | Registry state |
| Outbound | Redis (sid:verify:{senderId}:{tenantId}) | Hot-cache |
| Outbound | Vault | Document-encryption keys |
| Outbound | Object storage | KYC document files |
5. Runtime Topology
6. Key Design Decisions
- Verification level is first-class — every sender-ID carries
verificationLevel∈{ NONE, OTP, DOCUMENT, NOTARISED, DOMAIN_DNS }. Compliance treatment varies by level (e.g., banks claimingBANK-XYZmust beNOTARISED+DOMAIN_DNS). - Public registry by default — sender-IDs are public records. KYC documents are NOT public; only registrant org name + verification level + status are visible.
- Audit-immortal — sender-IDs are never deleted, only
REVOKED. Re-registration requires re-verification. - Reputation is a derived score — computed daily from compliance hits, complaint rate, fraud signals, DLR patterns. Range 0–100. Drives auto-suspension threshold.
- Restricted-name protection — names matching national-banking, government, MNO patterns require
NOTARISEDverification AND regulator letter.
7. Surface Inventory
| Interface | Purpose | Auth |
|---|---|---|
REST POST /v1/sender-ids | Tenant submits sender-ID for registration | Kong JWT (tenant) |
REST PATCH /v1/sender-ids/:id/verification | Tenant submits verification artifact | Kong JWT (tenant) |
REST GET /v1/sender-ids/public/search?q= | Citizen public search | None (public) |
REST POST /v1/admin/sender-ids/:id/decision | T&S approves/rejects | Kong JWT (T&S role) |
REST POST /v1/admin/sender-ids/:id/suspend | Suspend with reason | Kong JWT (T&S role) |
REST GET /v1/admin/sender-ids/export | Regulator export | mTLS regulator role |
gRPC Verify(senderId, tenantId) → VerifyResponse | Per-message check; P95 ≤ 5 ms | Service mesh mTLS |
gRPC GetReputation(senderId) | Reputation lookup | Service mesh mTLS |
HTTP /health/live, /health/ready, /metrics | K8s + Prom | None / cluster |
NATS produce sender.id.registered.v1, sender.id.suspended.v1, sender.id.revoked.v1, sender.id.reputation.changed.v1, sender.id.regulator.exported.v1 | Downstream | — |
NATS consume compliance.message.blocked.v1, compliance.message.held.v1, fraud.detected.* | Reputation inputs | — |
8. Data Ownership
sender_id_registry schema:
sender_id_registry.sender_ids— registry rows with state machinesender_id_registry.kyc_documents— pointers to S3 + hash + verification resultsender_id_registry.verifications— verification attempts logsender_id_registry.reputation_history— daily reputation snapshotssender_id_registry.restricted_patterns— regex of restricted-name patternssender_id_registry.audit— append-only state-transition log
9. Failure Modes
- Verification storm (e.g., automated abuse) → rate-limit per registrant + per source IP; tarpit.
- DNS-TXT verification target unreachable → retry policy; manual review fallback.
- Reputation scorer cron failure → alert; previous reputation persists; manual re-trigger.
- Public search abuse (scraping) → cache-then-block: response cached 60 s; >100 RPS from one IP → tarpit.
10. Open Points
| ID | Question | Owner | Resolution |
|---|---|---|---|
| SID-OPEN-001 | National-banking pattern list — who maintains the protected-name list? | Legal + Banks | TBD |
| SID-OPEN-002 | Notarised document acceptance — which notaries does Ghasi recognise? | Legal | TBD |
| SID-OPEN-003 | Regulator export schedule — daily, weekly, monthly? | Regulator Liaison | TBD |
| SID-OPEN-004 | Public search rate-limit policy — what's the citizen-protection threshold? | T&S Council | TBD |