Skip to main content

sender-id-registry-service — Jira-Ready Epics & User Stories

Status: populated Owner: Trust & Safety + Regulator-facing Last updated: 2026-04-21 Service prefix: SID Scope: National sender-ID registry: registration with KYC; verification (DNS-TXT / OTP / notarised / document); suspension/rotation/revoke; public search; reputation scoring (cross-fed from compliance + fraud). Per ADR-0004 §3 and 07-epics-and-user-stories.md §6.3.

Epic Summary​

Epic IDTitleStoriesPoints
EP-SID-01Sender-ID Registration with KYCUS-SID-001 – US-SID-00519
EP-SID-02Verification (DNS-TXT / OTP / Notarised / Document)US-SID-006 – US-SID-01019
EP-SID-03Suspension, Rotation, Regulator Export, Public SearchUS-SID-011 – US-SID-01622
EP-SID-04Sender-ID Reputation ScoringUS-SID-017 – US-SID-02017
Total20 stories77

EP-SID-01 · Sender-ID Registration with KYC​

US-SID-001 · Submit sender-ID with KYC​

Type: Feature | Points: 5

Description: As a tenant developer, I need to submit a sender-ID for registration with KYC document upload so I can use a brand-recognised sender-ID.

Acceptance Criteria:

  • POST /v1/sender-ids accepts { value, type (alpha|short|long), category, registrantOrgName, kycDocs[] }
  • Validates value shape: alpha 1–11 alphanumeric; short 4–6 digits; long E.164
  • Restricted-name patterns (US-SID-005) require additional fields
  • State SUBMITTED; row in sender_id_registry.sender_ids
  • KYC docs stored as encrypted blobs in S3; hashes recorded
  • sender.id.submitted.v1 published

US-SID-002 · KYC review queue and reviewer assignment​

Type: Feature | Points: 3

Description: As a T&S reviewer, I need a queue of pending registrations sorted by submission date so I process them in order and meet SLA.

Acceptance Criteria:

  • Queue accessible via admin-dashboard (per EP-ADMDASH-11)
  • SLA countdown per row (default 5 business days); breach flag
  • Round-robin or self-claim reviewer assignment
  • Reviewer can request more info via REQUEST_INFO; tenant notified

US-SID-003 · KYC document inline viewing (audit-logged)​

Type: Feature | Points: 3

Description: As a T&S reviewer, I need to view uploaded KYC documents inline with watermark so I do not need to download files.

Acceptance Criteria:

  • Documents fetched from S3 via signed URL (15-min expiry)
  • Watermark "GHASI INTERNAL — DO NOT DISTRIBUTE" applied
  • View action audit-logged in sender_id_registry.audit
  • PDF + image (jpg/png/heic) supported

US-SID-004 · Approve / Reject / Request-Info workflow​

Type: Feature | Points: 3

Description: As a T&S reviewer, I need approve/reject/request-info actions with mandatory reason so decisions are auditable.

Acceptance Criteria:

  • Three actions; reason mandatory
  • APPROVED → KYC_APPROVED; sender.id.kyc_approved.v1; tenant notified
  • REJECTED → REJECTED; sender.id.rejected.v1; reason shown
  • REQUEST_INFO → tenant notified with checklist

US-SID-005 · Restricted-name pattern enforcement​

Type: Feature | Points: 5

Description: As a T&S engineer, I need submissions matching restricted-name patterns (banks, government, MNOs) to require additional verification so impersonation is structurally blocked.

Acceptance Criteria:

  • sender_id_registry.restricted_patterns (regex, category, requiredVerificationLevel, regulatorRef)
  • Submission matching pattern requires NOTARISED AND a regulator-letter document
  • Patterns auditable; admin-only CRUD
  • Default seed: BANK*, GOV*, MOJ*, AWCC*, ROSHAN*, ETISALAT*, MTN*, SALAAM*

EP-SID-02 · Verification (DNS-TXT / OTP / Notarised / Document)​

US-SID-006 · DNS-TXT verification challenge​

Type: Feature | Points: 5

Description: As a tenant developer, I need to verify a domain-affiliated sender-ID via DNS-TXT record so verification is automatic and DNS-rooted.

Acceptance Criteria:

  • System generates _ghasi-sid-verify.{domain} TXT challenge
  • Tenant publishes record; clicks Verify
  • System resolves DNS, matches hash; success → verificationLevel: DOMAIN_DNS
  • Failure → retry up to 5 times in 24 h before manual fallback

US-SID-007 · OTP verification to registrant phone​

Type: Feature | Points: 3

Description: As a tenant registrant, I need to receive an OTP at the registered phone to verify ownership.

Acceptance Criteria:

  • OTP sent via channel-router (lane=P1) to registrant MSISDN
  • 6-digit code; TTL 5 min; max 3 attempts
  • Success → verificationLevel: OTP
  • Rate-limit: 3 OTPs per registrant per hour

US-SID-008 · Notarised document verification​

Type: Feature | Points: 5

Description: As a T&S reviewer, I need to accept a notarised document as verification artifact for high-trust sender-IDs so banks and government are properly verified.

Acceptance Criteria:

  • Notarised PDF uploaded; reviewer manually verifies notary identity (whitelist)
  • On approval → verificationLevel: NOTARISED
  • Notary verification step is dual-control (two reviewers)
  • Audit row written

US-SID-009 · Document verification (basic)​

Type: Feature | Points: 3

Description: As a T&S reviewer, I need to accept ordinary commercial-licence documents as basic verification for standard sender-IDs.

Acceptance Criteria:

  • Commercial licence + national ID required
  • Reviewer marks verificationLevel: DOCUMENT on approval
  • Default for non-restricted-name registrations

US-SID-010 · Verification level surfaced to compliance + routing​

Type: Feature | Points: 3

Description: As compliance-engine / routing-engine, I need verificationLevel in Verify response so I can apply level-based gating.

Acceptance Criteria:

  • Verify(senderId, tenantId) returns { status, verificationLevel, lastVerifiedAt }
  • compliance-engine uses level in SENDER_ID rule (P0 lane requires NOTARISED+DOMAIN_DNS)
  • Cache hot via Redis (TTL 300 s)

EP-SID-03 · Suspension, Rotation, Regulator Export, Public Search​

US-SID-011 · Suspend sender-ID (manual)​

Type: Feature | Points: 3

Description: As a T&S admin, I need to suspend a sender-ID with mandatory reason so active abuse is stopped immediately.

Acceptance Criteria:

  • POST /v1/admin/sender-ids/:id/suspend with reason; audit-logged
  • State SUSPENDED; sender.id.suspended.v1 published
  • compliance + routing within 30 s reflect suspension (cache invalidation)

US-SID-012 · Auto-suspend on reputation breach​

Type: Feature | Points: 3

Description: As a T&S engineer, I need sender-IDs auto-suspended when reputation drops below 30 so high-abuse senders are stopped without manual delay.

Acceptance Criteria:

  • Reputation < 30 → auto-suspend; reason LOW_REPUTATION
  • Tenant notified in customer portal
  • T&S can override + restore with audit trail

US-SID-013 · Re-activate suspended sender-ID​

Type: Feature | Points: 3

Description: As a T&S admin, I need to re-activate a suspended sender-ID after tenant remediation so genuine recoveries are possible.

Acceptance Criteria:

  • Re-activation requires reason + tenant remediation evidence link
  • State → ACTIVE; sender.id.reactivated.v1 published
  • Reputation reset to neutral 50 with 30-d probation flag

US-SID-014 · Revoke sender-ID (final, audit-immortal)​

Type: Feature | Points: 3

Description: As a T&S admin, I need to revoke a sender-ID permanently for severe abuse so the same sender-ID cannot be re-registered without re-verification.

Acceptance Criteria:

  • POST /v1/admin/sender-ids/:id/revoke with reason
  • State REVOKED; immutable; sender-ID name reserved for 12 months
  • Re-registration after 12-m blackout requires new KYC + new verification
  • sender.id.revoked.v1 published

US-SID-015 · Public search​

Type: Feature | Points: 5

Description: As a citizen, I want to search "Who registered sender-ID BANK-XYZ?" so I can verify legitimacy of unsolicited messages.

Acceptance Criteria:

  • GET /v1/sender-ids/public/search?q={value} returns { value, registrantOrgName, verificationLevel, status, registeredAt }
  • KYC document content NOT exposed
  • Rate-limit: 100 RPS per IP; tarpit beyond
  • Caching: 60 s edge cache; 5 min hot cache

US-SID-016 · Regulator export (daily/on-demand)​

Type: Feature | Points: 5

Description: As regulator-portal-service, I need to export the full registry to ATRA on schedule and on-demand so the regulator has a current authoritative list.

Acceptance Criteria:

  • Cron daily 04:00 generates JSON Lines export to S3
  • GET /v1/admin/sender-ids/export returns latest export signed URL
  • Export includes: senderId, registrant, verificationLevel, status, dates
  • PII (KYC) not included
  • sender.id.regulator.exported.v1 published per export

EP-SID-04 · Sender-ID Reputation Scoring (cross-fed from compliance + fraud)​

US-SID-017 · Reputation score computation (daily cron)​

Type: Feature | Points: 8

Description: As a T&S engineer, I need reputation per sender-ID computed daily based on compliance hits, complaints, fraud signals, DLR patterns so suspension/boost decisions have data.

Acceptance Criteria:

  • Cron 00:30 UTC reads from compliance + fraud + DLR aggregates
  • Formula: 100 - (complianceHits×2 + complaints×5 + fraudHits×10 + (1-deliveryRate)×30); clamped 0..100
  • Stored in sender_id_registry.reputation_history with daily snapshot
  • sender.id.reputation.changed.v1 published when crossing thresholds (30, 50, 70, 90)

US-SID-018 · Reputation lookup API​

Type: Feature | Points: 3

Description: As compliance-engine / fraud-intel-service, I need to query current reputation per sender-ID so reputation drives policy.

Acceptance Criteria:

  • gRPC GetReputation(senderId) → { score, lastComputedAt, trend90d }
  • P95 ≤ 5 ms (Redis hot cache)
  • Tenant view available in customer portal

US-SID-019 · Reputation history visualisation​

Type: Feature | Points: 3

Description: As a T&S reviewer, I want to see reputation history (90 d) for any sender-ID so trend analysis informs suspension.

Acceptance Criteria:

  • GET /v1/admin/sender-ids/:id/reputation/history?days=90
  • Time-series response
  • UI panel in admin-dashboard (per EP-ADMDASH-11)

US-SID-020 · Cross-feed of fraud signals into reputation​

Type: Feature | Points: 3

Description: As a T&S engineer, I need to subscribe to fraud.detected.* and reduce reputation accordingly so fraud signals materially impact sender-ID standing.

Acceptance Criteria:

  • NATS consumer for fraud.detected.* and compliance.message.blocked.v1
  • Per-event reputation delta applied within 60 s
  • Audit row in sender_id_registry.reputation_history per delta event