0023 — Super Admin has full application access (one central policy)¶
Status: proposed (2026-10-14) — implemented on branch feat/super-admin-full-access; not merged, not deployed. Builds on the permission matrix of migration 060 and on ADR 0022. Nothing here changes an issuance switch: 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 deploying this change activates no automatic invoicing.
Context¶
Migration 060 split the portal into a system administrator (super_admin) and a business observer (owner), and described Super Admin as one that "administers the SYSTEM, not the books". The route groups were converted to the permission matrix, in which super_admin is authorised in Go for every key. But the handler-level role lists — the narrowing inside a handler (accounts_admin only, gst_accountant or accounts_admin, …) — were written before the role existed and were never converted. Each is a hand-written comparison, and each silently shut the newest and most privileged role out.
That is one defect, met five times:
| When | Symptom |
|---|---|
| 2026-09 | "You do not have permission" creating a purchase bill as Bootstrap Owner / Super Admin (supRequireWriter) |
| 2026-09 | the same for expenses, TDS, notes and filings (cmplWriter) |
| 2026-10 | Accounting Settings → Invoice series showed "listed and changed by an Accounts Admin only" to the signed-in Super Admin, with no way to create the series (settingsRoleIn, canManageInvoiceSeriesRole) |
| 2026-10 | the same role could not save Settings, approve a tax configuration, retry an invoice or resolve a reconciliation |
| — | the portal's own role predicates repeated the same hand-written comparisons, so the UI and the server could each be wrong in a different way |
Fixing each list individually is how the first four happened. The owner's brief asked for the structural cure: a permanent, centralised permission hierarchy, applied to the API, the navigation, the pages, the buttons, the forms and the permission configuration.
Decision¶
A Super Admin holds every application-level authority that the accounting roles hold, in addition to its own system administration (portal users, roles, the permission matrix, locks, resets, sessions). The relation lives in one place on each side and nothing else decides it:
- Server:
internal/accounting/middleware/policy.go—RoleAllowed(role, allowed...). A role named in a list passes; Super Admin passes when the list names any role it inherits; an unknown role, an empty role and an empty list are denied. The inherited set is closed:accounts_admin,accounts_staff,gst_accountant,owner,support,warehouse. - Portal:
src/lib/authz.ts—roleAllowed, the same function over the portal's role names. Every who-may rule ininvoice-ops.tsis expressed through it.
Every handler helper that used to compare roles now calls it (settingsRoleIn, supRequireWriter, cmplWriter, the reconciliation resolve, the report-transition table, RequireRole, RequireOwner, the product-tax ApproverRole). The one deliberate exception is the sample-invoice preview's audience gate, which keeps its hard-coded list (it names super_admin explicitly) because that file is pinned byte-for-byte by the compat guards and "existing invoice preview functionality remains unchanged" was a requirement; the policy guard lists it with that reason. Because the answer is given for the list, a new handler that names accounts_admin is available to Super Admin from the day it is written.
New permissions work the same way. HasRolePermission has always authorised super_admin for every key; what was missing is the other half — GET /auth/me, which tells the portal what the caller holds, listed only the rows seeded for the role. It now lists the whole catalog for Super Admin, so a permission added by a later migration is allowed by the server and shown by the portal with no second edit.
What is deliberately not inherited¶
- The Auditor's independent-assurance steps. The report workflow
Draft → Ready for Review → Auditor Reviewed → Final → Locked → Reopenedis a four-eyes control. Super Admin can take the Accounts Admin steps (prepare, finalise) but not the auditor's (review, lock, reopen): a list that names onlyauditorstill excludes it. A Super Admin that could do all of them could prepare, review, finalise and lock a statutory report alone. This matches the 2026-09 decision pinned byreport_approval_policy_test.go, which is unchanged in spirit; the policy testTestRoleClassification_CoversEveryRoleExactlyOncefails if the auditor is ever moved. If the owner wants Super Admin to hold those steps too, it is one line inpolicy.go— but it is a decision about statutory report sign-off, so it is flagged rather than assumed. (The catalog keysapprove_reportsandlock_periodare not route-enforced: Super Admin "holds" them in the permission-matrix view like every key, but the report-transition endpoint gates by role list, so it is the list - not the key - that keeps these steps with the auditor. The portal offers no report-transition buttons, so no screen promises what the server refuses.) - System administration. Portal users, the permission matrix and the commerce
is_adminaxis are not inherited by anyone; Super Admin alone holds the first two, and no portal role reaches the third. - Super Admin is a portal role.
POST /roles(authorised by the commerceusers.is_adminflag alone) now refuses to grantsuper_admin: such an account would hold the whole application without a portal login's password rotation, lockout, sessions and login-attributed audit rows. Every other role is still grantable, and a refused request changes nothing. Grants that already exist are untouched; owner action: confirm none exists (SELECT count(*) FROM accounting.role_grants WHERE role = 'super_admin' AND revoked_at IS NULLshould be 0).
What full access does not bypass¶
Holding a role never waives a rule that lives below the role check; each of these is enforced on the data, for every role, and each has a regression test run as a Super Admin:
- the issuance switches (the deployment flag and the settings gate) — a manual issue, a retry and a backfill still answer
503 ISSUANCE_DISABLED; - the settings gate cannot be switched ON through
PUT /settingsby anyone (409 ISSUANCE_GATE_CONTROLLED). Activation is the controlled procedure (docs/runbooks/invoice-issuance-activation.md). Leaving it alone and switching it OFF (the kill-switch direction) are allowed; the portal's own client already re-asserts the stored value on every save. This closes a path that Super Admin would otherwise have acquired with this change, and that Accounts Admin already had unintentionally; - a refused attempt to switch the issuance gate on is itself recorded (a
deniedaudit row naming the actor, role and request id), so an attempt leaves a trail even though nothing changed; - the seller-identity validation (a malformed GSTIN, a PAN that is not the GSTIN's own, a contradicting state are refused at save);
- the product tax approval workflow (draft → submit → approve; a rejected or overlapping configuration never becomes effective; the approver is recorded) — (since ADR 0025 the approver is a different verified person from the one who entered or last changed the values, recording a written basis, and the Super Admin is no exception);
- historical orders. (The "second account" limit described in this bullet is closed by ADR 0025 / migration 104: the rule now compares verified PEOPLE — a mobile number proven by its holder — and fails closed when either side has none; the refused attempt is recorded as a
deniedaudit row. The administrative acts named below no longer reopen it: a Super Admin's password reset or reassignment of a portal account ends that account's identity binding in the same transaction (a change of a store login's phone on file ends a store login's, and the login can then confirm only the number now on file), so a login whose password the Super Admin chose stands for nobody until whoever holds it proves a number — and the Super Admin's own number makes it the Super Admin's. What remains is a person who can obtain the code sent to a second number, the residual risk ADR 0025 states. The same change gives product tax a real maker ≠ checker rule.) Approval to backfill is still the owner's/Super Admin's to give, a run (manual issue, retry or backfill) still needs an active approval, and an excluded order is never invoiced. Because Super Admin can now both give and run, what separates the two is the PERSON, not the role: a run by the same login or user id that gave the approval — and, since ADR 0025, by the same verified person from any login — is refused (409 SEPARATION_OF_DUTIES), and the portal says so beside the run form and never offers a runner the approval it gave. This stops one account doing both. It is not a control against a Super Admin who deliberately creates a second account and runs under its own approval from there — only a Super Admin can create accounts, and creating, re-assigning and resetting them is audited, but the independence is procedural at that point (the same is true of product tax: an approver may be the configuration's creator, which the readiness page already counts as "self-approved"). The refused attempt is recorded and the owner is told in the activation runbook to use a second person; - gap-free numbering, one active series per financial year, immutable issued numbers and documents, and the audit trail. There is no route that edits or deletes an issued invoice number or a series (a test lists the route table to prove it).
Authentication and the role are never the client's word¶
The role is re-read from the database on every request (portal session → portal_users.role, commerce → role_grants). A test mints a correctly signed token whose role claim says super_admin for a staff session, sends x-role-style headers, query and body fields, demotes a Super Admin mid-session, and revokes a session: only the database's answer counts, and a demotion or revocation takes effect on the next request.
While proving this a pre-existing defect surfaced and is fixed here: when a portal session was missing, invalid or ended, resolveAccountingIdentity wrote its 401 but returned a nil error, so the caller carried on with an empty identity and its own 403 overwrote the 401. The portal signs the user out on 401 only, so an expired session read as "permission denied" instead of "sign in again" — and PASSWORD_CHANGE_REQUIRED was reduced to a bare FORBIDDEN. The resolver now reports ok=false explicitly. Unauthenticated requests are 401; an unauthorised but authenticated role is 403; both are tested through the production DualAuth in front of the router.
The Invoice Series Manager¶
The manager (ADR 0022) was complete but unreachable for Super Admin. It now opens for Accounts Admin and Super Admin from Accounting Settings → Invoice series (headed Manage Invoice Series), with direct links from Sales Invoices → Readiness (beside the failing series check and on the Series in force card) and from the Simple view's settings. It shows the current financial year's state in words (active prefix, next number, issued so far — or no active series: orders are held), every series with its status, and a create form that is offered AIM, the current financial year and as many digits as fit 16 characters — suggestions only: nothing is created or activated until the person has read the first number, its length and the yearly capacity (AIM/2026-27/ leaves four digits: 9,999 invoices a year) in a confirmation. A financial year that already has an active series is refused before the server has to (the server's 409 SERIES_ACTIVE_EXISTS remains the authority). No new business rule was added: validation, the 16-character limit, atomic gap-free numbering and the audit row are the server's, unchanged.
UI and backend agree — mechanically¶
The portal's predicates are not trusted to be right; they are checked against the server. The Go suite drives the real router with a real login per role and writes the observed answer for every portal predicate to internal/accounting/handler/testdata/authz_contract.json; src/lib/authz-contract.test.ts holds each predicate to it, plus the role classification and the permission catalog. Either side's change fails a build on the other. A static guard on each side (TestNoHandWrittenRoleComparisonsOutsideThePolicy, authz-guard.test.ts) fails if code compares a role by hand outside the policy. A route-coverage test fails if a mutating endpoint ships without a stated, tested answer for Super Admin.
Also corrected, for the same reason¶
- The dry-run / readiness tooling counted only
accounts_adminandgst_accountantas people who can run the targeted issue and backfill endpoints, so it would have reported a falseNO_APPROVER_ROLEblocker for a deployment whose only operator is a Super Admin. It now countssuper_admintoo (a test pins its list to the server's answer for every role). Its separate note that a tax configuration was approved by a role that is "not an accountant role" is unchanged: a Super Admin's approval is still the store's own system role, not a recorded accountant's decision. - The portal no longer offers "Auditor Approved" in the reconciliation dialog against the real API: the resolve endpoint answers 422 for it for every role, and a Super Admin (which holds the whole catalog) would otherwise have been shown a choice the server always refuses.
Consequences¶
- The Super Admin account (the Bootstrap Owner) can set up invoicing end to end from the portal — company profile, the series, tax-configuration approval — without a second login, which is what the activation runbook needs. It still cannot activate invoicing from the portal.
- A Super Admin is a powerful account that now holds the books as well as the system. Its use is more consequential, which is why the audit rows already carry actor login, role, request id and before/after for every write below, and why the permission matrix still cannot be edited into or out of Super Admin (
SUPER_ADMIN_IMMUTABLE). - The Settings forms are now locked for roles the server refuses (Business Owner, Accounts Staff, GST Accountant, Support, Warehouse) instead of being offered and refused on save; Auditor was already read-only.
- A role added to
AllRolesmust be classified inpolicy.go(inherited or segregated) or a test fails — neither silently inherited nor silently shut out.
Rollback¶
No migration and no data change. Revert the merge commit and redeploy the previous image and portal; every permission returns to what it was. Nothing issued, numbered or approved under this change is affected by the revert.