0025 — A verified person behind every two-person rule (maker/checker on a proven identity)¶
Status: proposed (2026-10-14) — §2.B (tax maker ≠ checker, checker ≠ verifier) is superseded by ADR 0026 (2026-10-20: one authorized, verified person may enter, check and approve a product's HSN/GST); §2.A (backfill) and the rest stand. Original status: — implemented on branch feat/issue-103-maker-checker-verified-identity (GitHub issue #103); not merged, not deployed. Builds on ADR 0022 (backfill approvals), ADR 0023 (Super Admin full access, which recorded the gap), ADR 0024 (verified tax rates). Nothing here changes an issuance switch, creates a series, approves a rate or issues an invoice: ACCOUNTING_INVOICE_ISSUANCE_ENABLED, the settings gate invoice_issuance_enabled, ACCOUNTING_JOURNAL_ENGINE_ENABLED and customer access to invoices are exactly as they were, and the migrations (104, and 105 for privileged phone recovery) are additive.
Context¶
Every separation-of-duties rule in the accounting module compared accounts. The backfill rule refused a run when the runner's portal login id or user id equalled the approver's (ADR 0022); a product tax configuration could be approved by the very account that entered it (the Product screen approved at save when the saver held an approver role — ADR 0020 called that a feature), and the verification record of ADR 0024 could only report that it could not tell whether the verifier was a different person. One person can hold several accounts: only a Super Admin creates portal accounts, and the same person may also hold a store-admin login. So one human could be both the approver and the runner of a backfill, or the maker and the checker of a tax rate, and the system would have called it independent. Nothing in the schema identified a person: accounting.portal_users has a login id, a display name and a role; public.users has a Firebase uid, a phone and an e-mail; the two are different UUID spaces with nothing linking them.
The owner's requirement (issue #103): enforce separation of duties on a stable, server-verified human identity where one exists; never infer that two accounts belong to one person; never claim independence the system cannot see; fail closed where no such identity exists and build the workflow that creates one; keep every administrative permission of the Super Admin and the Auditor-only steps; audit every refusal; keep issuance OFF.
Decision¶
1. A principal is a mobile number the person has proven (migration 104)¶
accounting.principals— one row per Indian mobile number (+91, E.164) that somebody proved by typing the six-digit code the system sent to it. The number is fixed for life: a different number is a different principal. Rows are never updated or deleted; the table cannot be truncated.accounting.principal_bindings— which account a principal proved:(account_space, account_id)where the space isportal(accounting.portal_users.id) orstore(public.users.id), with the IP, request id and time, and — for a portal account — the moment its password was last set. One live binding per account; a principal may own several accounts, and that is the point: a person's portal login and store login, or two portal logins, resolve to one principal. (Two store logins of one person do so only when one of them has no Indian mobile number on file: a store login proves the number it signs in with, and no two store accounts share a phone on file — below.) A binding is revoked, never deleted; nothing else about it ever changes.- How a binding is made. Only the account holder, from their own authenticated session, through
POST …/identity/mobile/start {mobile}andPOST …/identity/mobile/confirm {code}(accounting portal:/api/v1/accounting/identity/*for portal logins and store logins holding an accounting role grant; admin app:/api/v1/admin/identity/*for store admins). The code is six digits from the system RNG, kept only as a salted hash in Redis under a key named by the account (never by the number), for three minutes and five attempts (a six-digit hash is short: anyone who can read Redis while a challenge lives can recover the code from the stored hash and its salt in milliseconds, so Redis must be reachable only by the API — the internal network and its password, as deployed — and the at-rest hash is defence in depth, not a control against a reader of Redis) — and stored only once the SMS gateway has accepted the message, so a code is never confirmable while its send is in flight, and a send that failed leaves nothing to confirm (if its SMS still arrives, its code does not work). The limits are sliding windows of reservations, taken and given back by atomic Redis scripts, so they hold under concurrent starts, at a window's edge and when a command is retried: one start a minute per account (the cool-down, which a start the other limits refuse takes too), five starts per account in any hour, three codes per number in any 24 hours, and ten failed sends per number in any 24 hours. A start takes them in that order before anything is sent: the cool-down, then a slot in the account's window, the number's and, last, the failure window. Because the failure slot comes last, at most three starts for a number (its daily budget) hold one while their sends are in flight, so a burst of starts can never fill the failure window by itself (it is refused by the budgets). A start refused at the failure ceiling gives its account and number slots back (its minute stays taken), and an account with no starts left is answeredCODE_BUDGETeven for a paused number. A failed send gives the number its slot back — the person loses none of their three codes — but the asking account's start and the failure stay counted: the gateway reports a timeout as a failure although the provider may already have accepted the message, so failures are capped on their own. At worst a number receives three delivered and ten failed codes in 24 hours. After ten failed sends the number is paused until the oldest of them leaves the window (429 CODE_SEND_FAILURES, naming that time in IST rounded up to the next whole minute, so a person who returns at the named minute is not refused again; when the time cannot be read the message names none, never a guessed one; it also says the SMS gateway may be down), and each failed send answers503saying there is nothing to type yet and that ten failed attempts in a day pause the number for up to a day. Every start that sends a code, every send that failed and every start a budget refused is logged with the number masked and the asking account. Every script is safe to run again, because the Redis client re-sends a command whose reply was lost: a reservation, a failure slot and a consume that finds its own token already recorded answer as they did the first time, and an attempt treats a consumed challenge as absent. Confirming counts an attempt only on an existing challenge and consumes exactly the challenge it compared, atomically: the hash is marked consumed with the confirming request's token (not deleted), so a re-sent consume wins again for the same confirm and no other confirm can, and a consumed challenge can neither be confirmed nor count an attempt again until a new start replaces it. A failure slot whose send never resolved (a crash, a shutdown, a lost reply) is held for a two-minute lease; after it the slot is converted into a recorded failure, so a stale reservation cannot sit in the window for a day and pause a number early. The bookkeeping after a send — recording the failure or giving it back, storing the challenge — runs on a context that is no longer cancelled with the request (context.WithoutCancel, a five-second limit), so a redeploy that cancels in-flight requests cannot strand a slot. An attempt beyond the fifth is refused without deleting the challenge: it can never be confirmed after that (every later attempt is beyond the fifth too), and a new start replaces it. So of any number of concurrent confirms with the right code exactly one wins whenever one of them is within the five attempts — an attempt over the limit can no longer delete the challenge first — and a code proves a number for exactly the account that asked, once. The binding is then written only while the account is still in the hands that asked: the account row is locked against a concurrent handover, a portal confirm needs its session to be live still (a handover ends every session; otherwise401 PORTAL_SESSION_INVALID, nothing bound), and a store confirm is refused when the phone on file changed meanwhile (409 IDENTITY_ACCOUNT_CHANGED) or the number it proved is no longer the one on file (409 IDENTITY_NUMBER_NOT_ON_FILE). No request body names an account or a principal. The code appears in no response and no log. Numbers leave the server masked (last four digits), with one exception: while a store account is unbound, the admin app's status route returns its own phone on file — the one number that login may confirm (next bullet) — which attests nothing until a code is confirmed. Principal ids appear in readiness (the owner's enrolment comparison) and in audit rows; a number there is masked too. The limits fail closed — when Redis cannot be reached nothing is sent and nothing is confirmed (503; a code that could not be checked may be tried again while it lives) — unlike the login throttles, because nothing stands behind a binding. - A store login proves the number it signs in with. A store login is signed into with a code sent to its phone on file, so its person is whoever holds that phone. While the phone on file is an Indian mobile number, it is the only number the login may confirm: a start for any other number is refused before anything is sent or counted (
409 IDENTITY_NUMBER_NOT_ON_FILE, naming the number on file masked; if it is no longer the holder's, a Super Admin corrects the number on file first), and the confirm checks again under the account lock (above). The status routes say so in advance: the admin app'snumber_on_file_required(the screen then offers only that number) and, for a store login in the accounting portal,requiredMobileMasked. The reason is the takeover-before-enrolment path: a store session survives a change of the phone on file, so without this rule an administrator could repoint a login's phone at a handset they hold before its holder confirms a number (or between the holder's start and confirm), the holder — still signed in — would prove their own number, and the administrator would then sign in with the new phone as the holder's verified person. A store login with no Indian mobile number on file may confirm any number, and so may a portal login, which signs in with a password. The consequence: no two store accounts share a phone on file, so one person's two store logins are one person to the system only when one of them has no Indian mobile number on file; otherwise each is bound to whoever holds the phone it signs in with. - How a binding ends: a Super Admin withdraws it, with a reason — a portal account's through
POST /portal-users/:id/identity/revoke, a store account's from the admin app's Users page (POST /api/v1/admin/users/:uid/identity/revoke, Super Admin only). - …or a credential handover ends it, because whoever chose the new credential could otherwise act as the person bound to the account. A Super Admin's password reset of a portal account (
POST /portal-users/:id/reset-password) and its reassignment to a new occupant (POST /portal-users/:id/reassign) withdraw the account's binding in the same transaction (reason "password reset by a Super Admin" / "account reassigned to a new occupant", the Super Admin recorded as who withdrew it); a Highprincipal_bindingaudit row records it, and the portal-user audit row says so (identityBindingRevoked: true|false). A store login is signed into with a code sent to its phone on file, so whoever holds that phone holds the login: when the phone on file changes — by the privileged phone recovery (§Privileged phone recovery) for an admin, Super Admin, support or accounting-role login, by an administrator's edit for an ordinary account (the profile edit refuses it for a privileged one), or any other path — or the account is deleted, the database ends the store binding itself (trg_users_identity_binding_end; recorded on the binding row as withdrawn bysystem, with its reason); a rename keeps it — the trigger compares the phones trimmed and reads an empty one as none, because the admin user edit (PUT /api/v1/admin/users/:uid) writes a missing phone back as an empty one on every save. Whoever holds the account next proves their own number (for a store login, the number now on file). A withdrawal by a Super Admin or by a portal handover is audited High; the binding row is kept, revoked, whoever ended it. - Never their own. A Super Admin cannot withdraw a binding that is theirs (
SELF_IDENTITY_REVOKE, recorded asdenied; their own account cannot be reassigned at all,SELF_REASSIGN), and theirs means the person as well as the account: another account bound to the caller's own verified number is refused the same way by the revoke routes, a password reset and a reassignment, and nothing changes — otherwise a Super Admin could clear their second login's binding and re-bind it to a second SIM, one person with two principals. The person comparison needs the acting login to be bound itself; a Super Admin login with no binding of its own is compared by account only, which gains nothing beyond the second-SIM residual (§Residual risk). The holder cannot swap their own number, so a principal is a property of the account for as long as the binding lives; a start while a binding is live is refused (409 IDENTITY_ALREADY_BOUND). Moving a store login to another number is done by changing the phone number on file (an ordinary account: a Super Admin, admin app: Users → this account; a privileged login: only the two-person recovery, §Privileged phone recovery), which ends the binding itself (above); the holder then confirms the new number. A withdrawal alone would not move it, because a store login with an Indian mobile number on file may prove only that number. A portal login's binding is moved by a withdrawal. Deactivation, lock, a session revocation, a role change and the holder's own password change keep the binding (same person). - The SMS. Version 1 reuses the registered DLT login template the gateway already sends ("… is the OTP to log in to your Aim Store Account (valid for 3 mins)"); the enrolment screens say so, because the message cannot name its purpose until a dedicated template is registered (an owner action with provider lead time, §Owner decisions).
2. The rules, on principals and on accounts (fail closed)¶
Every rule compares principals and, underneath, keeps the account comparison as defence in depth (a principal is a property of an account at a moment; an account id is for good). Every refusal answers 409 with a named code and writes an accounting.audit_log row with result = 'denied' naming the actor, the role, the request id and the rule.
A. Historical backfill.
- Giving an approval requires the approver's live binding; the approval stores
approved_by_principal(immutable by the migration-100 guard, extended). Without a binding:409 IDENTITY_NOT_VERIFIED, nothing recorded. - Running under an approval — the backfill, the single-order retry and the manual issue of an order older than the sweep window — requires the runner's live binding (
IDENTITY_NOT_VERIFIED) and a principal and an account different from the approver's (SEPARATION_OF_DUTIES). An approval that carries no principal (given before this change, or by an account whose person was never verified) is unusable: "given before identity verification existed; ask the owner for a new approval" — the system never assumes independence. Two backstops hold the same line in the database: the slot reservation requiresapproved_by_principal IS NOT NULL, and the approvals guard refuses aused_countincrement on a principal-less row. GET /invoices/backfill/approvalssays, per row and per caller,identityVerifiedandusableByCaller; the screens repeat the server's answer instead of comparing login strings.
B. Product HSN/GST configuration — maker, checker, basis.
- Maker. The account that enters a configuration; its principal (
created_by_principal) is stamped at write time from the maker's own live binding, never resolved later (an account can change hands). An unbound maker can still enter a proposal, but nothing entered while the account had no verified person is ever attributed afterwards: saving it again does not adopt it. An identical save by the maker's account, now bound, is refused (409 CONFLICT: the entry was saved before a mobile number was confirmed for the login, so nobody can show who typed it) on the Product screen and in the portal alike; an approver withdraws the entry and the values are entered again by the person who checked them (whoever enters a withdrawn row becomes its maker). A save that changes a value or the supplier context by the bound maker still stamps them, because they typed it. Otherwise the approval would record as maker a person who only pressed a button on values somebody else chose. - Only the maker changes a proposal in place, and only the maker submits it. Another account's save that would change a
draftorpending_approvalproposal is refused (409, recorded asdenied): an approver who retyped someone else's values and then approved them would be approving their own entry under another name. (A different supplier-invoice context counts as a change too.) Only the maker sends a draft for approval (POST /tax-configs/:id/submitby anyone else:409, recorded asdenied), so a maker who sent a changed proposal back todraftdecides when it is ready again.updated_by/updated_by_principalrecord the last editor, who counts as a maker for the rule — and must be a verified person too: an account can change hands (§1), so an edit by an unbound account is an edit by nobody known, never "the creator", and the row cannot be approved (IDENTITY_NOT_VERIFIED,field: "editor"); there is no "save again" remedy: an approver withdraws the entry and the person who checked the values enters them again (the same rule as for an unconfirmed maker, above). The Product screen says per setting whether its last change has a verified person behind it (editor_confirmed, besidemaker_confirmed), and itscan_approve_thisrequires both, so the screen never offers an approval the server would refuse. For an unconfirmed maker or editor its note says to ask an approver to withdraw the entry and have the person who checked the values enter them again. A withdrawn (rejected) row is nobody's proposal: whoever enters its product and date next reclaims it as its new maker, by account and by verified person, and inherits nothing they did not enter. On the Product screen, which has no end-date field, the reclaimed entry is open-ended, or ends the day before an approved setting that already starts later, and the save's audit row records the end before and after; through the accounting API the caller's own end date applies, and the Product screen's classification, source and recommendation are cleared. Values changed through the accounting API likewise lose the Product screen's source and recommendation, so an approver is never shown "Recommended" beside values somebody typed. - Checker. A different verified person — different principal and different account from the maker and the last editor — approves, recording what they checked the values against (
approval_basis: at least five characters that show — control and invisible format characters such as zero-width spaces do not count, spaces between words do — and at most 300: the supplier's GST invoice, the accountant's advice, the HSN notification). Codes:IDENTITY_NOT_VERIFIED(the approver, the maker or the last editor has no binding; for the maker and the last editor the answer carriesfield: "maker"/"editor"and the message names who),SEPARATION_OF_DUTIES. The Product screen's approve-at-save is removed for everyone, Super Admin included: a save proposes; a second person approves (ADR 0020 §approval semantics is superseded on this point). An approval is bound to the values the approver saw, on both paths: beside the basis the request carries the HSN/SAC, the rate, the start and the end (absent, empty or null for no end date) — the end included, because a maker can change a proposal's end in place and a closure moves an approved setting's end, and either way the decision was not taken on those values. A row that no longer holds them when it is locked is refused as a stale view, not a rule refusal (nodeniedrow): the portal answers409 TAX_CONFIG_CHANGEDwith the row's current values, comparing them before the status, so a row its maker sent back todraftanswers that and only unchanged values on a row that is no longer pending answer422; the Product screen answers its stale409 CONFLICT("This setting was changed after you opened it…"). The two paths differ in one step. Through the accounting API a proposal is adraftuntil its maker submits it, and the maker's change of a waiting proposal's HSN/SAC, rate or end sends it back todraft, so the re-submission is visible to everyone. The Product screen has no draft step: a save waits for approval at once, and its maker's change of a waiting proposal keeps it waiting, so there the approval's binding to the values is what refuses a stale dialog. The portal approves only a proposal whose dates overlap no approved setting (422otherwise): a setting that replaces an approved one is approved on the Product screen, which ends the earlier setting the day before (§Owner decisions (b)). On both paths the APPROVE audit row records the approved values (HSN/SAC, rate, start and end —nullwhen open-ended) beside the basis and both principals, not just the status. A maker's re-send that reaches a row approved meanwhile is refused (409), never answered as if it had been saved. - Supplier invoice context. The maker may record the supplier's invoice number (at most 64 characters), date and a reference (at most 300). They are context for the record, never legal confirmation of the sales rate and never a state change: the verification step remains. The approval requests carry no supplier fields, so an approver who checked a different document says so in the basis; and the approval is bound to the tax values, not to this context or to the classification — a maker's change of either alone keeps a waiting proposal waiting (the save's audit row records it) and is frozen with the approval.
- The database holds the rule (
trg_product_tax_configs_maker_checker,BEFORE INSERT OR UPDATE): a row becomesapprovedonly with a maker principal and an approver principal; with a verified last editor whenever one is recorded (updated_bywithoutupdated_by_principalis refused); with the approver's principal differing from the maker's and from the last editor's (with no last editor recorded, the creator is the last editor, so the comparison is never vacuous); with a recorded creating and approving account, the approving one neither the creator nor the last editor; and with a written basis — at least five characters left once the surrounding spaces, control characters and invisible format characters are removed. Once approved, its values, its classification (tax category, product type, source and the recommendation shown), its people (the maker by account and principal, the last editor's principal, the approver by account and principal), its basis and its supplier-invoice context are frozen; its window end can still move (withupdated_by/updated_at, who moved it), and it can leaveapproved. A row that leavesapprovedloses everything the approval carried — the approver, the time, the approver's principal and the basis (the audit trail keeps them) — and every live verification of it is revoked (recorded as withdrawn bysystem: "the approval this verification confirmed was withdrawn"); a row that is not approved never keeps a basis. So approving it again takes a fresh approver, a fresh basis and a fresh verification. Rows approved before this migration are untouched: they stay approved under the old rule, carry no principals, are reported as such, and cannot be verified (the Verification bullet below). An approver withdraws such a row on the Product screen even after it started — provided no issued invoice rests on it; any verification on it goes with it — and the values are entered again at the original dates under the rule. Withdrawing a setting that had already started re-opens nothing: only a setting withdrawn before it started gives back the earlier window it closed; entering the values again at the original dates closes that earlier window again when no later setting exists. The Product screen never answers "unchanged" for such a row: saving its values at its own start date is refused with that procedure (409), and at a later date it is an ordinary new proposal — the route left when an issued invoice rests on it and it cannot be withdrawn. - Verification (ADR 0024, migration 102) is now an enforced independence, and a verification belongs to one approval. The verifier needs a live binding and must differ from the approver by principal and by account (
SEPARATION_OF_DUTIES); a configuration with no approver principal answers409 APPROVED_UNDER_OLD_RULE. The verifier may be the maker (owner decision (a), §Owner decisions): the maker's values were already checked by a different approver, and this step records the accountant's confirmation, which a two-person company could not otherwise record. The request names the values the verifier saw (hsnSac,gstRateBps,effectiveFrom,effectiveTo), compared under the row lock before anything else: a configuration withdrawn and entered again under the same id with other values while the dialog was open answers409 TAX_CONFIG_CHANGED(a stale view, nodeniedrow), never a verification of values the verifier did not see.verified_by_principalis required on every new verification row, and one predicate says what counts — the invoice engine (repository.TaxConfigVerifiedSQL), readiness, the portal's tax list and its filter, the dry run and the sample preview all use it: a live verification of exactly the configuration's values, carrying a verifier principal, by someone other than the configuration's approver, recorded at or after the current approval. So a configuration approved under the old rule is never verified, a verification by the approver never counts, and a verification never carries over to a later approval of the same row; besides, a row that leavesapprovedtakes its live verifications with it (the trigger above; a Product-screen withdrawal revokes them itself first, each with a High audit row naming who withdrew the setting). A live verification that does not count readsstalein the list and is withdrawn before a new one is recorded; nothing is issued on it. On a configuration approved under the old rule — every approved configuration after a rollback and roll-forward of this migration (§Migration and rollback) — Verify answersAPPROVED_UNDER_OLD_RULE: an approver withdraws it on the Product screen (any verification on it goes with it), it is entered again at the same dates, approved by a different verified person, and then verified. A principal-less verification on a configuration approved under the new rule can exist only if written past the trigger; Verify answers it409 ALREADY_VERIFIED: "this configuration has a live verification that carries no verifier principal, which the invoice engine does not use; withdraw that verification and record it again". A new verification row storesindependent = true(the rule now guarantees it), and the list servesindependentas true only for a verification that carries a verifier principal; thewhoIscross-system guess of ADR 0024 is gone.
C. Authorization is unchanged. RoleAllowed (Super Admin inherits accounts_admin, accounts_staff, gst_accountant, owner, support, warehouse; never auditor) is untouched, as are the Auditor-only report transitions and RequireSuperAdmin. A Super Admin keeps every administrative permission — creating, resetting, reassigning and locking accounts included — and cannot be both sides of a two-person rule: the rule compares people, a Super Admin is one person, and the administrative acts that could put another person's account in their hands end that account's binding (§1: a password reset, a reassignment, a store login's change of phone), so the account stands for nobody until whoever holds it proves a number (a store login, the number now on file) — and the Super Admin's own number makes it the Super Admin's. What remains is a second number whose code they can obtain (§Residual risk).
3. Readiness¶
identity_enrolment(BLOCKING): fewer than two distinct verified people stand behind the accounting accounts (portal accounts with an accounting role, store accounts holding a role grant or the admin bit). Its message says what that stops — no backfill can be run and no GST setting approved or verified until at least two different people have each confirmed their mobile number (one verified person can give a backfill approval, but someone else must run it) — and its action asks each person to confirm their number for each login they use, in the accounting portal and in the admin app (Configuration page). Readiness lists every verified person with its accounts and the last four digits of its number, so the owner can compare it with the people they enrolled: that list is the owner's, the system cannot tell whether two numbers are one person, and the control is detective there.tax_configs_self_approvedis BLOCKING while any approved configuration not shown to be approved by a different verified person (the same account, the same person, or no principal on either side — i.e. approved before the rule) still has a window reaching today; past-only windows are a warning. The invoice engine does not use such rows (they cannot be verified). The blocking message also says how many of those live rows were approved under the old rule: the readiness JSON carries that count asapprovedUnderOldRuleLive(approved, no approver principal, a window reaching today, IST) besideselfApprovedLiveand the all-timeapprovedUnderOldRule, so both numbers in the message count live rows.- The protections list gains the maker/checker trigger and the guard triggers of the two identity records (
trg_product_tax_configs_maker_checker,trg_principals_guard,trg_principal_bindings_guard), checked by name and enabled state; a dropped or disabled one blocks. Readiness does not look at the identity records' TRUNCATE guards, at the trigger that requires a verifier principal or at the trigger that ends a store binding when the phone changes; the release's post-deploy verification does (production-accounting-verifywith releaseverified-identitychecks the triggers migration 104 adds by name and enabled state; activation runbook §0).
Threat model¶
What was tried in design review (three adversarial lenses), and in two adversarial reviews of the implementation, and what holds:
| Attack | Outcome |
|---|---|
| A Super Admin creates a second portal account and runs under its own approval | Refused: the second account has no binding (IDENTITY_NOT_VERIFIED); after binding it to the same number it is the same principal (SEPARATION_OF_DUTIES); binding it to a different number needs that number's code (§residual) |
| The same person holds a portal login and a store login | Both bind to one principal (the portal login confirms the number the store login signs in with); every rule sees one person. Two store logins of one person each prove their own phone on file, so they are one person only when one of them has no Indian mobile number on file — otherwise two numbers, the second-number case of §residual, which the owner's list of verified people shows |
| An account revokes its own binding and re-binds to a second number before approving its own entry | The holder cannot revoke their own binding; a Super Admin cannot revoke, reset or reassign away their own; a reset or reassignment by another Super Admin ends it and hands the account to whoever proves a number next; underneath, the account comparison refuses the same account whatever its principal |
| A Super Admin resets a colleague's portal password, signs in with the password they chose and approves, runs or verifies as the colleague's verified person | The reset ends the colleague's binding in the same transaction (audited High; identityBindingRevoked), so the login stands for nobody until whoever holds it proves a number: the Super Admin's own number makes it the Super Admin's (SEPARATION_OF_DUTIES), another number needs that number's code (§residual). A reassignment does the same. A login bound to the Super Admin's own number is refused (SELF_IDENTITY_REVOKE) |
| An admin points a store login's phone on file at a handset they hold, signs in to that login with the code sent there and approves as its verified person | The phone change ends that login's binding in the database, whatever path changed it (trg_users_identity_binding_end), and a confirm racing the change binds nothing (IDENTITY_ACCOUNT_CHANGED). The login can then prove only the number now on file — the admin's own handset — so it stands for the admin, never for the person it was bound to. Taking over the login itself is closed by migration 105 and the privileged phone recovery (§Privileged phone recovery) |
| An ordinary admin (or any caller) edits the phone of an admin, a Super Admin, a support agent or an accounting-role holder through the profile edit, then signs in as them by SMS | 403 PRIVILEGED_PHONE_CHANGE for every caller, a Super Admin and the account itself included; nothing written; a denied High audit row (no number). Privilege is read from the target row locked FOR UPDATE in the same transaction, before and after the edit, so a forged role claim, an is_admin in the body, a stale token, or a grant racing the edit decides nothing |
| The same, as a Super Admin acting alone, or one person using two Super Admin logins, through the recovery workflow | Needs a second verified Super Admin, a different account and person, neither bound to the target's person, neither taking its own verified number as the new one: SELF_RECOVERY, SELF_APPROVAL, SAME_PERSON, TARGET_CANNOT_APPROVE, TARGET_PERSON, NEW_PHONE_IS_YOURS; the database refuses the same things whatever the application does |
| Two approvals, an approval racing a cancel or the 24-hour expiry, or a replayed request | Row locks in id order, one completion per request (the table forbids a second), an approval after expiry or cancellation refused (RECOVERY_EXPIRED, RECOVERY_CLOSED); exactly one outcome wins |
| The recovered login's old sessions keep working after the phone moves | The Redis cutoff revoke:<firebase_uid> is set to now after the commit and checked by every authenticated route (SESSION_REVOKED); with no Redis the approval does not start (503); a failed cutoff after the commit answers sessions_ended: false, writes a Critical failure audit row and logs LOUD, and the runbook's step 3 is run at once. The cutoff has one-second resolution: a token issued in the same second as the commit is not revoked |
| The new handset is simply trusted | It is not: the login's binding ended with the phone move, the holder signs in with a code sent to the NEW number, and must prove that number again (the number-on-file rule) before making, approving or verifying anything |
| A code or a full number leaks through the recovery's audit rows or logs | Audit rows and logs carry masked numbers and ids only; a code is never written anywhere |
| The same, before the login's holder confirms a number (or between the holder's start and confirm): the holder, still signed in — a store session survives a phone change — proves their own number, and the admin then signs in with the new phone as the holder's verified person | A store login proves only the number it signs in with: the holder's start for their own number is refused before anything is sent, and a confirm whose number is no longer the one on file binds nothing (IDENTITY_NUMBER_NOT_ON_FILE). Only whoever holds the phone on file can bind the login |
| A Super Admin withdraws, resets or reassigns away the binding of their own second login, then re-binds that login to a second SIM | Refused when the acting login is itself bound: never your own compares the person as well as the account, so a target bound to the caller's own verified number answers SELF_IDENTITY_REVOKE and the attempt is recorded as denied. A Super Admin login with no binding is compared by account only; the second SIM it then needs is §residual |
| A login changes hands and its new, unverified occupant edits the leaver's waiting proposal, then approves it from their own approver login | The unverified last editor blocks the approval (IDENTITY_NOT_VERIFIED, field: "editor"; the trigger refuses it too): an edit by an unbound account is by nobody known, never "the creator". Once the occupant confirms their number, approving their own edit is SEPARATION_OF_DUTIES |
| An approver edits someone else's waiting values in place, then approves them, or submits someone else's draft | The in-place save is refused, and so is the submission (both recorded as denied); the last editor counts as a maker |
| The approver approves values they never saw: the maker rewrites a waiting row while the approver's dialog is open | The approval names the values the approver read (HSN/SAC, rate, start, end); a row that differs answers TAX_CONFIG_CHANGED (portal) or the stale 409 CONFLICT (Product screen). Through the accounting API the maker's value change also returns the row to draft, so the re-submission is visible; the Product screen has no draft step, so there the binding to the values is the answer |
| A verifier's dialog is stale: the setting was withdrawn, entered again under the same id with other values and approved | The verification names the values the verifier saw; a row that differs answers TAX_CONFIG_CHANGED and nothing is recorded |
| A verification outlives the approval it confirmed: the setting is withdrawn, entered again and re-approved by its earlier verifier | Leaving approved revokes every live verification of the row (the trigger; the Product-screen withdrawal does it first, audited), and the one predicate counts a verification only when it was recorded at or after the current approval by someone other than that approval's approver |
| A legacy pending or draft row approved with no principals (regression of approve-at-save, direct SQL) | The BEFORE INSERT OR UPDATE trigger refuses any row becoming approved without the principals, a verified last editor, the account rule and a basis |
A principal, basis or approver rewritten after approval; a status flipped out of approved and back |
Frozen by the trigger; leaving approved clears the approver, the time, the principal and the basis, so coming back takes a fresh approval; the identity tables are append-only with TRUNCATE guards, ENABLE ALWAYS |
| A legacy approval consuming a slot through a path that forgot to check | reserveBackfillSlot and the approvals guard both refuse a slot without approved_by_principal |
| A client names a principal, an account or a number in a body or a header | Nothing is read from a request but the number to send a code to and the code itself; the account is the session's; the role is re-read from the database |
| A code confirmed from another account, for another number, or twice | The challenge is keyed by the account with the number inside it; an attempt is counted only on an existing challenge, an attempt beyond the fifth is refused without deleting it, and confirming consumes (marks, never deletes) exactly the challenge it compared, atomically: of concurrent confirms of the right code exactly one wins whenever one of them is within the five attempts, and a replay finds nothing |
| Guessing a code | Six digits, five attempts, three minutes, hashed at rest (a six-digit hash is short: it protects a leaked log, not a reader of Redis, which must be reachable only by the API); a code is stored only after its SMS was accepted, and a failed send stays charged to the asking account's five starts an hour; the limits fail closed |
| The gateway reports delivered codes as failed (a timeout after the provider accepted the message), so refunded sends put any number of codes on one number | A failed send gives back only the number's slot; failures are counted on their own, each slot reserved before the send — after the account's and the number's, so the starts in flight (at most three per number) can never fill the failure window themselves — so concurrent starts cannot overshoot: after ten in 24 hours the number is paused (CODE_SEND_FAILURES) before anything is sent. At worst three delivered and ten failed codes reach a number in 24 hours, and a failed send leaves nothing to confirm |
| A temporary-password portal session binds a number; a leaver confirms a code just as their login is reset or reassigned | The identity routes sit behind the data-plane resolver, which refuses a temporary-password session (PASSWORD_CHANGE_REQUIRED); a confirm locks the account row and needs its session to be live, so it binds before the handover (which then ends the binding) or not at all (PORTAL_SESSION_INVALID) |
| A verification by the approver, or of a row approved under the old rule | SEPARATION_OF_DUTIES / APPROVED_UNDER_OLD_RULE, and the one predicate counts neither |
Residual risk, stated. Any phone whose code the person can obtain for three minutes — a second SIM, a colleague's, a family member's — can become a second principal. Any portal login, and any store login with no Indian mobile number on file, may start a binding for any number (a store login with one may start only for that number), so the system will send a code to a number on request, and such an insider can keep spending a number's three codes, delaying that person's enrolment for as long as they keep at it (three codes in any 24 hours). That is bounded by the asking account's own budget (five starts an hour, one a minute; a failed send stays counted against it); a failed send costs none of the number's three, but ten failed sends in 24 hours pause the number for up to a day — a gateway outage can cause that, and an insider can hasten it during one; and the burn is visible, not silent: every start a budget refuses, the holder's included, is logged with the number masked and the asking account. Every start that sends a code is logged as well, with the masked number and the asking account (and a send the gateway failed, likewise), so the log shows which account spent a number's codes. The control raises the bar from "create a second login in the user admin" to "obtain a code sent to a second number", keeps the per-number start budget low (three a day), leaves an immutable trail (two numbers, two bindings, audit rows marking a second account bound to an existing person), and shows the owner the list of verified people. It does not, and cannot, prove that two numbers are two people; the owner's enrolment list does. A recycled number attaches its new holder to the old principal, which errs in the safe (refusing) direction. A binding has no expiry in version 1; its age is shown.
Privileged phone recovery (migration 105; the takeover is closed). The store's sign-in by SMS code finds the account BY its phone on file, and PUT /api/v1/admin/users/:uid used to let any admin set any account's phone, so whoever made that edit could sign in as another admin or Super Admin. Now:
PUT /api/v1/admin/users/:uidrefuses to change the phone of a privileged account —is_admin,is_super_admin,is_support, or a liveaccounting.role_grantsrow, before or after the same edit (granting a privilege and moving the phone in one request counts) — for every caller, a Super Admin and the account itself included:403 PRIVILEGED_PHONE_CHANGE, nothing written, a denied High audit row (actor, target, no number). The facts come from the target row lockedFOR UPDATEin the same transaction, never from the token or the request body (a forged role claim,is_adminin the body or a stale token decides nothing; a privilege grant is applied only if the caller is still a Super Admin in that transaction). A blank phone on a privileged account is "not supplied" (the phone stays); an ordinary account's phone is edited exactly as before, and the change ends that account's sessions (Redis cutoffrevoke:<firebase_uid>) as well as its binding.- A privileged login's phone moves only through a two-person recovery, Super Admin only (
accounting.privileged_phone_recoveries,POST /api/v1/admin/users/:uid/phone-recovery {new_phone, reason}, then…/:id/approveby a different verified Super Admin;…/:id/cancelby the requester, any other Super Admin or the account itself;GET …/phone-recoveryshows the open request, numbers masked). Requester and approver come only from the session. Both need a live verified-identity binding and must be different accounts and persons, neither the account being recovered nor bound to the person it is bound to; neither may choose their own verified number as the new one; the request lives 24 hours. The approval runs in one transaction that re-checks all of it from Postgres under row locks (both still Super Admins, still verified, request open and unexpired, account still privileged, new number still unused), setsusers.phone(migration 104's trigger ends the account's binding) and records High audit rows; after the commit the Redis cutoff ends every session the account had (if Redis refuses it, the response sayssessions_ended: false/SESSION_CUTOFF_FAILED, a Criticalfailureaudit row is written and the log says LOUD; with no Redis at all the approval does not start). The login then needs a code sent to the new number, and the account proves that number (the number-on-file rule) before it can make, approve or verify anything. The database refuses, whatever the application does, a self-approval, the same person on two accounts, the target taking part, an unverified or non-Super-Admin actor, an approval after expiry or cancellation, an edit of a request, a second completion, and a completion that does not carry the new number on the account. - Fresh verification and what is kept. The replacement binding needs a code sent to the new number (the same SMS infrastructure and rate limits as any enrolment), not a statement by either Super Admin. A customer account is unaffected: an admin still edits its phone through the existing endpoint. Every Super Admin business permission is unchanged; only who can move a privileged login's phone changed, and the financial two-person rules (§2) still apply to whoever holds the login afterwards.
- A sole Super Admin cannot recover another Super Admin, by design — it takes two verified people. If only one verified Super Admin exists, or none can act, the owner uses database recovery (docs/runbooks/privileged-phone-recovery.md), which REQUIRES a fresh, verified database backup first (step 0: taken, integrity-checked and hashed before anything is changed); the rule is deliberately not weakened for the "last Super Admin" case.
- Every place that writes an existing account's phone was inventoried (
TestPrivilegedPhone_OnlyTwoPlacesWriteAnExistingAccountsPhonefails if a third appears):WalletRepo.UpdateUser(refuses privileged accounts) and the recovery approval. Sign-up creates new rows only (INSERT … ON CONFLICT (phone) DO UPDATE SET firebase_uidnever writes the phone),PATCH /mewrites no phone, and the Google link, e-mail, referral and Pangali writes touch other columns.
Also outside it: a store login with no phone on file. A store login that signs in only through Google/Firebase and has no phone on file keeps its binding through every event except being given a phone or being deleted, because the database trigger watches the phone number. If control of that Google/Firebase credential passes to someone else, the new holder inherits the live binding and acts as the person bound to it without proving a number. It does not bypass the two-person rules (their own separate login is a different principal), and no phone-based route reaches such an account; closing it needs a Super Admin to withdraw the binding when the credential changes hands, and readiness lists which logins are bound.
Owner decisions taken by default (change by telling engineering; none is a runtime switch)¶
- (a) The tax rule is two-person: maker ≠ approver (absolute), verifier ≠ approver (absolute), and the verifier may be the maker. The strict three-person variant (verifier ≠ maker too) is not built: under it the owner — one person across the portal
ownerlogin and the store Super Admin account — could never enter a value, and an owner-plus-accountant company could never verify anything. - (b) Approve-at-save is gone for everyone, the owner included: an entry waits for someone else. The accountant approves on the Product screen of the admin app (with their store login) or through the accounting API; the portal's Tax verification panel offers Approve/Reject to the same roles. The portal and the accounting API approve only a proposal whose dates overlap no approved setting — a first setting, or one entered again at the dates of a withdrawn one. A setting that replaces an approved one (a new rate from a later date) is approved on the Product screen, which ends the earlier setting the day before; whoever approves such a change needs a store login that may approve there (a store Super Admin, or a store admin holding an Accounts Admin or GST Accountant grant).
- (c) The two sample configurations in production (Hoodie, Evoque: approved by their creator, unverified) stay as they are until an approver withdraws them on the Product screen and the CA's values are entered again at the original dates, approved by a second verified person and verified. Nothing is auto-approved or auto-withdrawn.
- (d) SMS: the login DLT template is reused with on-screen explanation; a dedicated "this code links login X to this number for AIM accounting approvals" template is an owner follow-up that would also allow a notification SMS to a number's existing holder when a second account binds to it.
- (e) Enrolment: the owner, at least one other accounting person (Accounts Admin or GST Accountant) and every staff member who enters GST values confirm their numbers on every login they use — in the accounting portal under Settings → Your identity, in the admin app on the Configuration page's Confirm your mobile number card. A binding is per login; the same number on two logins makes them one person — but a store login confirms the number it signs in with (its phone on file, when that is an Indian mobile number; a Super Admin corrects it first if it is no longer the person's), so one person's two store logins are one person only when one of them has no Indian mobile number on file. Until two different people have done so, nothing can be run, approved or verified — a backfill approval can be given by one verified person, but no run under it, no tax approval and no verification is possible until a second verified person exists — and readiness blocks (Verified identities). Readiness lists what the system then knows.
Consequences¶
- Until two different people have confirmed their numbers nothing can be run, approved or verified: a backfill approval can be given by one verified person, but no run under it, no tax approval and no verification is possible until a second verified person exists — by design; readiness blocks (Verified identities) until then.
- A privileged login's phone can no longer be changed by one person. Moving it takes two verified Super Admins (or the owner's database procedure), and a customer-account phone edit now also ends that customer's sessions. An ordinary admin who used the profile edit to change an admin's phone now sees
403 PRIVILEGED_PHONE_CHANGE. - A credential handover now ends the account's identity binding: after a Super Admin resets a portal password or reassigns the login, and after a store login's phone on file changes, its holder confirms their number again before anything they enter can be approved and before they approve, run or verify anything.
- The portal's
approvedByLogin-versus-session comparison and the Simple view's unfiltered approval list are replaced by the server'susableByCaller. - A store login confirms only the number it signs in with: a person whose store login carries another number on file (an old one, a shared office phone) has it corrected before they can confirm, and one person's two store logins count as one person only when one of them has no Indian mobile number on file.
producttax.Approvetakes a basis;GetStatetakes the viewer; the admin app shows who entered a row, whether they confirmed their number and whether its last change has a verified person behind it (editor_confirmed), and offers Approve only where the server would accept it (can_approve_this); the Product screen's "approved from the effective date as soon as you save" wording is gone.- Audit rows now carry principal ids in
after_state(never a full number: the binding rows carry the masked one), and refusals by the rules are recorded asdenied.
Migration and rollback¶
104_verified_identity_maker_checker.sql is additive and touches no order, invoice, payment, wallet or settings row; the one trigger it puts on public.users writes only to the identity bindings (it ends a store binding when the phone on file changes or the account is deleted; a rename, or an edit that writes a missing phone back as an empty one, is no change). It re-creates the migration-100 and migration-102 guard functions with the new columns in their frozen lists (those files are hash-pinned and cannot be edited). rollback/rollback_104.sql first restores both guard functions verbatim, then drops the triggers, the columns and the two tables: a weakening back to the account-only rules, never applied automatically. Redeploy the previous backend image first and run the script after it: a backend built with 104 reads those tables and columns on every portal page (/auth/me), the tax list, readiness and the Product screen, and fails without them. Export first, whole, accounting.principals, accounting.principal_bindings, accounting.product_tax_configs, accounting.invoice_backfill_approvals and accounting.product_tax_verifications: the script drops the record of who proved which number, the maker, approver and verifier principals, the written approval bases and the supplier-invoice context, and nothing re-links them. A later roll-forward (104 applied again) cannot bring them back: every approved configuration returns as approved under the old rule (unusable until it is withdrawn, entered again, approved and verified), every verification without its verifier principal (it no longer counts), every backfill approval without its approver principal (unusable; the owner gives a new one), and no account is bound (everyone confirms their number again). After the rollback, the post-deploy verification (production-accounting-verify) is dispatched with release scalable-numbering: its default, verified-identity, fails once 104 is no longer tracked (the script deletes its schema_migrations row), and its message says so. The round trip (apply 101–104, roll back 104–101, apply again) restores the schema exactly (tested).
105_privileged_phone_recovery.sql (privileged phone recovery, §Privileged phone recovery) is additive: one append-only table and its guard trigger, nothing else. rollback/rollback_105.sql drops it (run it before rollback_104.sql: the table references accounting.principals); redeploy the previous backend first, which brings back the open phone edit this migration closed (rolling 105 back while the new backend runs leaves a backend that cannot record a recovery: nothing moves). Export accounting.privileged_phone_recoveries first: it is audit evidence and the script drops it; applying 105 again does not bring the rows back. production-accounting-verify does not yet check 105's table or trigger by name; confirm them with the read-only query in docs/runbooks/privileged-phone-recovery.md.
What this does not do¶
- It does not switch anything on, approve the sample rows, create a series or issue an invoice.
- It does not prove that two numbers are two people, and never claims to.
- It does not change checkout, payments, the wallet, the journal, the Auditor-only steps or the Super Admin's administrative permissions.
- It does not defend against a privileged login whose holder's handset (or SIM) is taken: whoever receives the login code is the account. The recovery exists to move the login to a new handset with two independent verified people, not to detect a stolen one. A Super Admin who grants a privilege to an account should confirm its phone on file first.
- It does not bind an approval to the supplier-invoice context or the classification, only to the tax values.
- It does not add e-mail OTP, hardware MFA, binding expiry or a dedicated SMS template (follow-ups, if the owner wants them).
Testing¶
Database: the 104 triggers (approve without principals / same principal / approver = editor / unverified last editor / no basis refused; frozen once approved; leaving approved takes the approval and its verifications with it; a store login's binding ends with its phone or with the account, and survives a rename, also one that writes a missing phone back as an empty one; slot on a principal-less approval refused; verification without a principal refused; identity records append-only and TRUNCATE-refused) and the 101–104 round trip. Service and HTTP: same person through a second account refused on the backfill, the tax approval and the verification (portal and store spaces); unbound actor, maker or last editor refused, and the Product screen offering no approval the server would refuse (editor_confirmed) until the last editor confirms and saves again; forged body/header principals ignored; a code for another account or a replayed code fails, and of concurrent confirms of the right code exactly one wins whenever one is within the five attempts (an attempt over the limit never deletes the challenge); the challenge store's windows against a real Redis (the cool-down, the account and number budgets and the failed-send ceiling, taken in that order, also under concurrent starts, and a burst of starts for one number never told it is paused; nothing confirmable while a send is in flight; a failed send gives back only the number's slot); a password reset or a reassignment ends the binding, never one of the caller's own person, and a store confirm racing a change of the phone on file binds nothing; a store login proves only the number it signs in with, at the start and at the confirm, also when its phone was repointed before its holder enrolled; the approval and the verification bound to the values shown; a verification never outliving the approval it confirmed; a reclaim never inheriting an end date; only the maker changes or submits a proposal; an unconfirmed entry never adopted by saving it again; a started old-rule withdrawal re-opening nothing; the challenge store's scripts run twice (a lost reply), a consumed challenge, the failure-slot lease and a paused-until time rounded up; legacy approvals and legacy-approved rows unusable; demoted account stopped by the role gate; retry and concurrency under the new rule; every refusal audited; Super Admin's inherited permissions unchanged (authz contract); other roles unchanged; checkout and payments untouched (compat guards); issuance OFF (gates pinned). Portal and admin app: the enrolment cards, the Approve-with-basis dialog, the usable-by-caller filtering, the readiness identity card.