sender-id-registry-service — Migration Plan

Version: 1.0 Status: Draft Owner: Trust and Safety + Regulator Liaison + Platform Engineering Last Updated: 2026-04-21 References: SERVICE_OVERVIEW.md, _report.md, SERVICE_READINESS.md

The service is greenfield — there is no predecessor to replace. However, the platform today already allows tenants to send SMS with arbitrary alpha-IDs / short-codes with no KYC or verification. The migration is therefore a behavioural migration: moving from an unregistered, free-for-all sender-ID surface to a national-authority registry with graded enforcement.

---

1. What Is Migrating

Input	Source	Volume (estimate)	Notes
Existing sender-IDs in use by tenants today	Observed from sms-orchestrator submit logs and smpp-connector submit_sm source_addr history	1 000 – 5 000 distinct alpha-IDs across early-phase tenants	Discovered in Phase 0 inventory scan
Tenant-claimed KYC documents	Tenant legal records	1 per registered sender-ID	Collected during Phase 1
Initial restricted-pattern list	Legal + CISO authored	~100 patterns	Covers Afghan national brands, banks, MNOs, government
Notary whitelist	Legal authored	~20–50 Afghan notaries	Seeded during Phase 0
Daily regulator export baseline	Generated from populated catalog	Post-Phase 1	ATRA handshake

---

2. Migration Phases

Phase 0 — Pre-migration (Weeks -6 to 0)

Step	Owner	Output
Inventory scan of sender-IDs in use today (30-day retrospective)	SRE + Trust & Safety	reports/sender-id-inventory-baseline.csv
Restricted-pattern list v1 authored	Legal + CISO	Signed list, published in sender_id_registry.restricted_patterns
Notary whitelist v1 authored	Legal	sender_id_registry.notaries seed
Design-partner tenants identified (1 bank, 1 gov ministry, 1 e-commerce, 1 agency)	Product	Signed MoUs
Service deployed to staging with design-partner data	SRE	Staging green
Public-search UI + admin workbench UI drafted	Frontend	Design review sign-off

Phase 1 — Registration Open, Enforcement Off (30 days)

Step	Owner	Output
Tenants can submit sender-IDs; KYC review + verification workflows live	Service	Registry populated
Verify(senderId, tenantId) returns ACTIVE for any submitted sender-ID regardless of real status (observation mode)	Service	Zero enforcement downstream
Platform admin runs baseline-inventory sweep: each observed sender-ID → notify associated tenant via customer-portal banner "register by {date} or your sender-ID will be restricted"	Product	Tenant awareness + inbound registrations
Daily metrics: registrations per tenant, KYC SLA tracking, restricted-pattern rejection rate	Trust & Safety	Daily dashboard
Public search stays hidden (admin-only) during Phase 1	Service	No premature exposure

Exit criteria. 80% of active tenants have submitted at least one sender-ID with at least DOCUMENT-level verification; KYC review SLA < 5 business days at P95; no critical bug in verification workflows.

Phase 2 — Enforcement: DOCUMENT-plus verification levels (14 days)

Step	Owner	Output
Verify(senderId, tenantId) returns actual status + level	Service	Honest status
compliance-engine SENDER_ID_VERIFICATION rule (EP-CE-15) enabled per tenant on lanes P0/P1	Service	High-trust traffic now gated
Unregistered sender-IDs still allowed for P2/P3/P4 lanes (grace period)	Service	Smooth transition
Public search exposed (read-only)	Service	Citizen verification possible
Tenant-portal displays sender-ID status badge and reputation	Frontend	Self-service visibility
Daily regulator export opens (ATRA-cleared schema)	Regulator Liaison	First weekly drop to ATRA

Exit criteria. < 10 tenant escalations per day in Phase 2; regulator Liaison confirmation that ATRA acknowledges the exports; no OTP regression (P1 submit-to-DLR P95 unchanged).

Phase 3 — Full Enforcement (ongoing)

Step	Owner	Output
Unregistered sender-IDs blocked on P0/P1/P2 lanes	Service	Full gating
P3/P4 lanes: warning-then-block after 30-day grace from Phase 2 start	Service	Long-tail handled
Reputation-based auto-suspension enabled (score < 30 → SUSPENDED)	Service	Abuse self-regulates
Fraud-signal NATS consumer live	Service	Feedback loop closes
Citizen-portal complaint intake for impersonation (EP-ADMDASH-11 workflow)	Frontend	Public trust builds
Post-launch review at +30 d	Platform	Lessons learned

Rollback at any phase via feature flags:

• SID_ENFORCEMENT_LEVEL=OFF|DOCUMENT_PLUS|ALL
• SID_AUTO_SUSPEND_ENABLED=true|false
• Reverting restores previous behaviour; no data loss.

---

3. Sender-ID Inventory Sweep (Phase 0 detail)

3.1 Source

• 30 days of sms-orchestrator submit logs, aggregated by (tenantId, source_addr).
• Cross-referenced with smpp-connector submit_sm.source_addr for edge-case discovery.

3.2 Output

CSV reports/sender-id-inventory-baseline-{yyyymmdd}.csv:

tenant_id,sender_id_observed,type,first_seen_at,last_seen_at,message_count_30d,top_destination_prefix,unique_recipients_30d
acc_abc123,BANKOF,ALPHA,2024-11-01T06:12:00Z,2024-11-30T23:55:00Z,125834,93,45123
acc_def456,12345,SHORT,2024-11-02T08:00:00Z,2024-11-30T22:15:00Z,8213,93,3214

3.3 Tenant notification

For each row, customer-portal banner + email to tenant admin:

"You are currently using sender-ID BANKOF. Under the national sender-ID registry (effective {Phase 2 date}), this sender-ID must be registered and verified. Registration is free — please complete by {date}. After {date}, unregistered sender-IDs will be blocked on OTP/transactional lanes."

3.4 Automatic KYC-claim pre-fill

Where possible, the platform pre-fills the registration form with tenant business name and sender-ID value — the tenant only uploads the KYC document.

---

4. Restricted-Pattern Seed List v1 (sample)

Pattern	Category	Required Verification	Regulator Ref
(?i)^BANK.*|.*BANK.*	BANKING	NOTARISED + DOMAIN_DNS	ATRA-BANK-2026-01
(?i)^GOV.*|MOJ.*|MOI.*|MOFA.*	GOVERNMENT	NOTARISED + gov-PKI signature	ATRA-GOV-2026-01
(?i)^AWCC.*|ROSHAN.*|ETISALAT.*|MTN-?AF.*|SALAAM.*	MNO	NOTARISED + MNO letterhead	ATRA-MNO-2026-01
(?i)^AXFA.*|KABUL-?BANK.*|ARAIN.*|MAIWAND.*|NEW-KABUL.*	NAMED BANKS	NOTARISED + DOMAIN_DNS	ATRA-BANK-2026-02
(?i)^UNICEF.*|WHO.*|UNAMA.*|WFP.*	INT'L ORGS	NOTARISED + UN letterhead	Legal-Int-2026-01
(?i)^HEALTH.*|MOPH.*|HOSPITAL.*	HEALTHCARE	NOTARISED + MOPH letterhead	ATRA-HEALTH-2026-01
(?i)^OTP.*|CODE.*|VERIFY.*	GENERIC-VERIFY	DOCUMENT (low-risk but reserved for brand owners)	Platform policy

Full list (~100 patterns) in sender_id_registry.restricted_patterns at deploy time.

---

5. Cross-Region Bootstrap

Per ADR-0004 §14, sender_id_registry.* is control-plane data replicated multi-master:

1. Initial seed happens once (Phase 0) — restricted patterns, notaries, and empty sender-IDs table.
2. Registrations accepted in either region; logical replication mirrors within 60 s.
3. Audit chain is region-local (each region maintains its own append chain); reconciliation cron merges for audit export.
4. Reputation cron runs region-local; per-region aggregates are summed into a global reputation daily.

---

6. Regulator-Export Bootstrap

6.1 ATRA handshake

• T-30d: Regulator Liaison presents export schema draft to ATRA.
• T-14d: ATRA acknowledges schema; SFTP drop-box credentials exchanged.
• T-7d: Dry-run file transmitted; ATRA confirms parse success.
• T-0 (Phase 2 start): First live daily export.

6.2 Export schema v1 (JSON Lines)

{
  "exportId": "sid-export-2026-06-01",
  "exportedAt": "2026-06-01T04:00:00Z",
  "registryVersion": "1.0",
  "recordCount": 2314,
  "signature": "sha256:abc...=="
}
{
  "senderId": "BANKOFAF",
  "type": "ALPHA",
  "registrantOrgName": "Bank of Afghanistan",
  "verificationLevel": "NOTARISED+DOMAIN_DNS",
  "status": "ACTIVE",
  "registeredAt": "2026-05-15T10:00:00Z",
  "lastStatusChangeAt": "2026-05-15T10:00:00Z",
  "reputationScore": 92,
  "regulatorFlags": []
}

6.3 Fail-safe

If ATRA SFTP unreachable for a daily export:

• Retry 3× with exponential backoff.
• Alert SidRegulatorExportFailed.
• Export file retained in S3 for manual delivery.
• No data mutation until ACK received.

---

7. Tenant Migration for Existing Sender-ID Claims

7.1 Workflow

1. Tenant sees inventory banner (§3.3).
2. Tenant clicks "Register" → pre-filled form.
3. Tenant uploads KYC document(s) and selects verification method.
4. System enters SUBMITTED state.
5. Verification completes (DNS-TXT auto, OTP auto, NOTARISED / DOCUMENT manual review).
6. Approved → ACTIVE.
7. Tenant continues traffic without interruption.

7.2 Fast-track for low-risk tenant

If tenant has ≥ 12 months of clean delivery history (no compliance blocks, no fraud hits), Trust & Safety can fast-track DOCUMENT-level approval (single-reviewer, ≤ 2 business days).

7.3 Deadline handling

Unregistered sender-IDs at Phase 2 start → warning banner + tenant email. At Phase 3 start → blocked on P0/P1/P2; tenant receives daily reminder until registered.

---

8. Downstream Consumer Migration

Consumer	Change	Timing
compliance-engine	New SENDER_ID_VERIFICATION rule type (EP-CE-15)	Phase 2
routing-engine	Last-mile veto consults Verify for P0/P1/P2	Phase 2
sms-firewall-service	Inbound MO validates Verify status	Phase 3
channel-router-service	Multi-channel Verify for sender-ID checks	Phase 2
fraud-intel-service	Publishes fraud.detected.* consumed here	Phase 0
regulator-portal-service	sender.id.* SIEM stream + regulator export relay	Phase 2
admin-dashboard	Reviewer workbench (EP-ADMDASH-11)	Phase 0
customer-portal	Registration UI + status badge + inventory banner	Phase 0

---

9. Rollback Plan

9.1 During Phase 1

• SID_ENFORCEMENT_LEVEL = OFF (already the default).
• Registrations continue; nothing enforced downstream.
• No data loss.

9.2 During Phase 2

• SID_ENFORCEMENT_LEVEL = OFF.
• Compliance-engine SENDER_ID_VERIFICATION rule disabled.
• Regulator export paused with ATRA notification.
• Tenant impact: reverts to pre-Phase-2 behaviour.

9.3 During Phase 3

• SID_ENFORCEMENT_LEVEL = DOCUMENT_PLUS (fall back to Phase 2).
• SID_AUTO_SUSPEND_ENABLED = false.
• Tenant impact: auto-suspensions paused; unregistered P2/P3/P4 allowed.

9.4 Catastrophic

• Restore latest hourly Postgres backup.
• Replay sender.id.* NATS events (7-day retention).
• Tenant impact: possible < 1 h state gap.

---

10. Success Metrics for Migration

Metric	Target	Measurement
Active tenants registered by Phase 2 exit	≥ 95%	Daily count
KYC SLA compliance (P95 review ≤ 5 business days)	100%	Weekly report
Restricted-pattern false-positive rate	< 5%	Rejection audit
Regulator-export daily delivery + ACK	100%	ATRA confirmation log
Phase-transition duration vs. plan	±5 days	Project tracker
Reputation-based auto-suspension accuracy	≥ 90% (not reversed on manual review)	Post-launch
Impersonation complaint rate post-Phase-3	< 1 per day per 1 M messages	Citizen-portal

---

11. Dependencies for Migration

• ATRA engagement on regulator export + restricted-pattern category alignment (owned by Regulator Liaison).
• Legal authorship of restricted-pattern list + notary whitelist.
• HSM provisioned for audit-hash + KYC-document DEK wrapping (ADR-0004 §11).
• Multi-region logical replication configured (ADR-0004 §14).
• compliance-engine implementation of SENDER_ID_VERIFICATION rule (EP-CE-15).
• fraud-intel-service emitting fraud.detected.* events (W1 dependency).
• Design-partner tenants onboarded (Product).

Without any of these, migration is blocked at the phase in which it is first required (called out in the phase tables above).