Privileged phone recovery (GitHub issue #103, migration 105)¶
A store login is signed into with a code sent to the phone on file, and the account is found by that phone. Whoever controls
that phone controls the login. So the phone of a privileged account — is_admin, is_super_admin, is_support, or an
accounting role grant held now or ever — is not an ordinary profile field any more. (A revoked grant still shields the phone:
revoking is open to every admin, so revoke, repoint, grant again must not work. The phone is compared after trimming all Unicode
whitespace once, for the comparison and the write, so a space-padded copy of the stored number is no change and is not written.)
What changed¶
| Route | Behaviour |
|---|---|
PUT /api/v1/admin/users/:uid |
Changing the phone of a privileged account is refused for everyone (403 PRIVILEGED_PHONE_CHANGE), a Super Admin and the account itself included. Ordinary (customer) accounts are edited as before and their sessions end with the phone. |
POST /api/v1/admin/users/:uid/phone-recovery {new_phone, reason} |
A verified Super Admin asks to move a privileged login to a new number. |
GET /api/v1/admin/users/:uid/phone-recovery |
The open request (masked numbers only). |
POST /api/v1/admin/users/:uid/phone-recovery/:id/approve |
A different verified Super Admin (a different person) approves; the move runs at once. |
POST /api/v1/admin/users/:uid/phone-recovery/:id/cancel {reason} |
The requester, any other Super Admin, or the account itself cancels. |
Normal recovery (two people)¶
- (Only when more than one Super Admin exists. With one Super Admin, skip to the emergency procedure below: it is the only way.) The account holder tells two Super Admins, out of band, that the handset is lost and which new number to use.
- Super Admin A (who has confirmed their own number: admin app → Configuration → Confirm your mobile number) requests the recovery with the new number and a reason (10 to 300 characters).
- Super Admin B (a different person, with their own confirmed number) approves within 24 hours.
- The login's old sessions end, its identity binding ends, and the holder signs in with a code sent to the new number, then confirms that number again before approving or checking anything.
Rules the server enforces (and the database backs up): requester and approver are different accounts and different persons; neither is 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 new number must not belong to another account; a request lives 24 hours; one open request per account.
A sole Super Admin cannot recover another Super Admin — by design¶
The recovery needs two verified people. If only one verified Super Admin exists (or none can act), nobody can move another Super Admin's phone through the application. That is deliberate: the "last Super Admin" case must not become a one-person shortcut. The owner then recovers through the database, with the procedure below (step 0, a verified backup, comes first). Do it on the VPS, as the owner, and keep the output.
Step 0 — a verified database backup first. Do not start without one. This changes who can sign in as a privileged account; if it is done wrongly the only way back is a restore. On the VPS:
# 0. Take a fresh backup, then PROVE it is usable before touching anything (a zero-byte or truncated file is not a backup).
BACKUP="/opt/aim-store/backups/pre-phone-recovery-$(date +%Y%m%d-%H%M%S).sql.gz"
PGU=$(sed -n "s/^POSTGRES_USER=//p" /opt/aim-store/deploy/.env.production)
PGD=$(sed -n "s/^POSTGRES_DB=//p" /opt/aim-store/deploy/.env.production)
docker exec aim_postgres pg_dump -U "$PGU" -d "$PGD" | gzip > "$BACKUP"
ls -lh "$BACKUP" # must be well over a few kilobytes
gzip -t "$BACKUP" && echo "archive intact" # must print: archive intact
zcat "$BACKUP" | grep -c "^COPY public.users " # must print 1
sha256sum "$BACKUP" | tee "$BACKUP.sha256" # keep this line with the notes of the recovery
If any of the three checks fails, stop and fix the backup first. Record the file name, size and hash in your notes, with the reason for the recovery and who authorised it (the owner, in person). Only then continue with step 1.
-- 1. Look (read-only): the account, its current phone, who is bound to it.
SELECT u.id, u.firebase_uid, u.is_admin, u.is_super_admin, u.is_support, u.phone
FROM users u WHERE u.firebase_uid = '<the account''s firebase uid>';
-- 2. Move it. The trigger from migration 104 ends the account's identity binding in the same transaction.
BEGIN;
UPDATE users SET phone = '+91XXXXXXXXXX', updated_at = NOW() WHERE firebase_uid = '<the account''s firebase uid>';
INSERT INTO accounting.audit_log (actor_role, action, severity, entity_type, entity_id, note, result)
VALUES ('owner', 'UPDATE', 'High', 'user_phone', '<users.id>',
'phone of a privileged account moved by database recovery by the owner; reason: <why>', NULL);
COMMIT;
# 3. End the account's signed-in sessions (the cutoff is a unix time; tokens issued before it are refused).
redis-cli SET "revoke:<the account's firebase uid>" "$(date +%s)" EX 3456000
Afterwards the holder signs in with a code sent to the new number and confirms it again in the admin app.
If the approval answers sessions_ended: false (SESSION_CUTOFF_FAILED)¶
The phone moved but Redis refused the revocation cutoff: the audit trail has a Critical failure row for the request. Run step 3
above for the account at once. Until then the old sessions still work (they belong to the old handset).
Reading the trail¶
accounting.audit_log, entity_type IN ('privileged_phone_recovery', 'user_phone'): CREATE (request), APPROVE, UPDATE
(cancel, or the phone move), and every refusal as result = 'denied' (High). Numbers are masked (+91 •••••• 1234); a code is
never written. accounting.privileged_phone_recoveries keeps every request (rows are never deleted).
Who should be able to recover whom¶
A single Super Admin is a supported configuration. The Super Admin confirms their number (admin app, Configuration, Confirm your mobile number); for the independent tax approver see the activation runbook. If more than one Super Admin exists, each must be a different person: two logins of one person count as one. The readiness probe lists the verified people. A recovery request, its approval and any refusal are in the audit trail; nothing here switches invoicing, the journal engine or customer invoice access.
Read-only check that migration 105 is in place (run on the VPS, nothing is changed):
SELECT to_regclass('accounting.privileged_phone_recoveries') IS NOT NULL AS table_present,
(SELECT count(*) FROM pg_trigger WHERE tgrelid = to_regclass('accounting.privileged_phone_recoveries') AND NOT tgisinternal) AS triggers;
Rollback¶
scripts/postgres/rollback/rollback_105.sql drops the table. Redeploy the previous backend first; note that the previous
backend has the open PUT phone edit (the takeover this fixes). Export the table before dropping it.