0027 — KARAT 24 customer KYC: a provider-ready gate, with trading still off¶
Status: accepted for implementation (2026-10-30). Prepares customer KYC for KARAT 24 digital Gold and Silver BUY and SELL so that an approved KYC provider can be connected later with minimal change. It does not enable trading, connect a provider, verify anyone or touch any balance. Every KARAT24_* trading flag stays as it is (off in production).
Context¶
The KARAT 24 BUY/SELL pipeline exists and is flag-gated, but nothing in it checked who the customer is. The audit (2026-10-29, findings F-21 to F-23) recorded that no KYC, PAN, bank-verification or PMLA control exists, and that custody, settlement and payout arrangements are unresolved. KYC is one of several independent prerequisites; this change builds the KYC part only.
Decision¶
Scope (locked by the owner)¶
- KYC applies only to a customer taking part in KARAT 24 BUY or SELL. Registration, login, browsing, cart, ordinary orders, order tracking and support never read or require it (a source-level test fails the build if a non-KARAT-24 handler references the KYC package or gate).
- One shared profile per customer for Gold and Silver. The gate is metal-agnostic.
The gate¶
KYCGate.Enforce runs on the server in CreateQuote (both sides), CreateBuyOrder, SELL CreateReservation and SELL Confirm. It reads the stored profile and derives the status at request time (kyc.Overall): VERIFIED only when every required check is VERIFIED, the verification carries a provider reference and a verification instant, and it has not expired. Anything else answers 403 KYC_REQUIRED with the status. A store error answers 503 (never allow). No request field can satisfy it: there is no "kyc_verified" input, and a source-level test forbids one.
KYC verified is one input. It does not enable trading: the feature flags, a current rate, custody/inventory, settlement and payout remain separate checks, and a test proves a verified customer is still refused while BUY is off.
The configuration is fail-safe: the zero value means KYC is mandatory and every check is required. KARAT24_KYC_REQUIRED=false is honoured only outside APP_ENV=production.
Provider-agnostic seam (internal/kyc)¶
A Provider interface — InitiateVerification, VerifyPAN, InitiateAuthorizedIdentityVerification, VerifyBankAccount, GetVerificationStatus, HandleProviderWebhook, RetryVerification. Production uses DisabledProvider, which fails every call closed; NewProvider is where a real adapter is selected once a contract exists. A scriptable mock lives in internal/kyc/kyctest for automated tests only: it is not selectable by configuration, and a test fails the build if routes.go or cmd/api imports it. No fake KYC record can be created in production.
What is stored (migration 116)¶
karat24_kyc_profiles (one row per user), karat24_kyc_consents, karat24_kyc_events, karat24_kyc_access_log. Additive; no existing table or row changes.
- No Aadhaar number, OTP, biometric or document image — and Aadhaar is not collected at all. Identity verification is a provider-hosted, consent-based redirect; AIM learns only the outcome. A request carrying an Aadhaar-shaped field is refused (
AADHAAR_NOT_ACCEPTED). - PAN and bank account numbers are passed to the provider in memory and never stored or logged; only the mask (
XXXXX1234F,XXXXXXXX9012) is kept. Because nothing sensitive is retained, no column needs field-level encryption. - No manual verification. A
VERIFIEDcheck must carry the provider reference and verification instant (aCHECKconstraint), and the only code that sets a check toVERIFIEDis applying a provider result. The staff API has GET routes only. - Replay protection. Webhooks are authenticated (HMAC-SHA256 over
timestamp.body, constant-time compare, ±5 min window), recorded once underUNIQUE (provider, event_id), and a latePENDINGcan never undo a final result. The raw body is not stored — only its SHA-256. - Audit. Consents, provider events and every staff read are append-only (triggers refuse update, delete and truncate). A staff read is written to the access log before data is returned.
- Retention.
retain_untilis recorded fromKARAT24_KYC_RETENTION_DAYS; no job deletes anything because the retention period is a legal decision not yet taken. A customer with a profile cannot be hard-deleted (same policy as the rest of KARAT 24 history).
Surfaces¶
- Customer API:
GET /karat24/kyc,POST /karat24/kyc/{consent,pan,bank,identity,retry}; publicPOST /karat24/kyc/webhook(503 while no provider/secret is configured). Writes answer503 KYC_PROVIDER_UNAVAILABLEuntil a provider is connected. - Admin portal: KARAT 24 KYC (read-only; masked data, provider reference, timestamps, failure reasons, review queue). It cannot verify, reject or edit anyone.
- App (source only):
app/karat24/kyc.tsxplus helpers; the buy and sell screens route to it when the server answersKYC_REQUIRED. The Gold/Silver single-page structure and the Home | Products | Account navigation are unchanged. No Android release is made for this work; an app update is required when a provider is connected and KARAT 24 is opened to customers.
What this does not decide (owner, counsel, provider)¶
KYC being ready is not permission to trade. Still required before any live KARAT 24 trading:
- Legal structure and regulatory position of offering digital Gold/Silver (regulatory counsel; the audit's L-01).
- KYC / AML obligations — whether AIM is a reporting entity, the exact checks required, and the retention period (L-04, L-06).
- Custody and inventory — a vault/custody arrangement, supplier and insurance evidence, verified inventory (the inventory subsystem exists but is empty and makes no title claim).
- Settlement and payout — an approved payment rail for BUY and a payout provider with beneficiary verification for SELL (none is approved; payout is disabled).
- Customer terms and disclosures, and the consent text the KYC consent version refers to.
- GST and accounting treatment of metal transactions (CA; the audit's F-23).
Information needed from the future KYC provider¶
Name and contract; sandbox and production base URLs; authentication scheme and API key issuance (kept in the server env only); the list of APIs (PAN verification incl. name match, bank penny-drop or reverse-penny-drop, identity verification — which Aadhaar-based or DigiLocker flow they are authorised to run and under what UIDAI licence); redirect and return-URL rules; webhook event catalogue, signature algorithm and header names, timestamp and retry policy, source IPs; status vocabulary and its mapping to ours; error and rate-limit behaviour; data they return (masked or full) and how long they retain it; consent artefact requirements; SLA, support contacts, DPDP data-processing agreement, and their statement of what is legally required for a digital-gold structure. If their webhook scheme differs from the default, it is implemented inside their adapter's HandleProviderWebhook.
Rollback¶
scripts/postgres/rollback/rollback_116.sql drops the four tables (export first — consents, events and access log are audit evidence). Redeploy the previous backend image first: this backend reads karat24_kyc_profiles on every KARAT 24 quote and order and in the customer-delete guard.