0018 — Support portal and the Support role¶
Status: accepted (2026-09-30). Builds on 0016 (the support desk) and 0006 (the admin portal pattern).
Context¶
ADR 0016 put the whole support desk in the admin portal, behind
middleware.AdminOnly, so anyone who answers tickets had to be a full admin
(users.is_admin): catalogue, orders, refunds, gateways, wallet edits, user
deletion requests. The store now wants support staff who handle tickets and
nothing else, in their own portal at support.aimstoreorg.com, next to the
admin (admin.) and accounting (accounts.) portals.
Decision¶
- A Support role. Tracked migration
095_support_role.sqladdsusers.is_support BOOLEAN NOT NULL DEFAULT FALSE— a third additive authority bit besideis_adminandis_super_admin(the same "a boolean, not a role table" reasoning as 072). No existing user gains it. It is granted in the admin portal (Users → Edit → Role: Customer / Support agent / Admin), and granting or revoking it needs a Super Admin, likeis_admin: a support agent sees customers' names, phones, emails and orders. The change is audited (SUPPORT_ROLE_GRANTED/_REVOKED).is_supportis optional onPUT /admin/users/:uid(absent = unchanged), so an older portal build cannot revoke it by omission. - Its own login and token role.
POST /api/v1/auth/support/loginadmitsis_supportoris_adminaccounts (the admin login keeps refusing support agents). The token carriesrole=support(oradmin). Other login paths never mint the support claim, so a support agent's app token cannot reach the desk API. - Its own API group.
/api/v1/support-desk/*, gated bymiddleware.SupportStaffOnly, which — likeAdminOnly— re-reads the flags from the database on every request, so a demoted agent loses access on their next click. It exposes exactly what the ticket queue and the dashboard need, reusing the admin handlers: the queue, create, detail, patch, status, reply and resolve; the dashboard, agent list, customer lookup and a customer's orders (the order picker); and read-only topics, templates, resolution codes and settings. Every configuration write (topics, FAQs, templates, codes, settings, email retry) stays on/api/v1/admin/*, and so does anything that moves money. The/admin/tickets*and/admin/support/*routes are unchanged. - Agents are admins or support agents. The assignee picker, the
dashboard's agent table and assignment validation accept both
(
is_admin OR is_support). - A separate portal,
aim-store-support(Next.js 14, port 3004), built like the admin portal: NextAuth credentials, the API token only in the encrypted httpOnly cookie, a server-side proxy. The proxy forwards only/api/v1/support-desk/*and refuses dot segments and encoded slashes, so an admin signed in here (whose token is a full admin token) still cannot use this portal to reach/api/v1/admin/*. Links into the admin portal (customer profile, Email log, support settings) are shown to admins only. - The screens moved, not copied. The support dashboard and the ticket
queue/detail pages were removed from the admin portal. Its old
/tickets,/tickets/*and/support/dashboardURLs redirect (307) to the support portal, and/ticketskeeps its path there, so bookmarks and staff emails already sent keep working. The staff-email ticket link default (SUPPORT_ADMIN_TICKET_URL_BASE) is nowhttps://support.aimstoreorg.com/tickets, and 095 rewords the four seeded staff email templates' "Open it in the admin portal:" line to "support portal" — only where that exact seeded sentence is still present, so a template an admin has rewritten is left alone. - Deploy as one more service on the single VPS (ADR 0004/0005):
support_portal/aim_support_portalwith its own env file (support-portal.env.production, its ownNEXTAUTH_SECRET), a pinnedaim_edgeaddress (SUPPORT_PORTAL_EDGE_IP), a Caddy site forsupport.aimstoreorg.com, and a manualdeploy-support-portalworkflow that provisions the env file and address idempotently on first run (deploy/provision-support-portal.sh). No CORS change: the browser only talks to the portal's own origin.
Consequences¶
- Rollout order:
deploy-backend(applies 095 — the support login readsis_support), thendeploy-support-portal, thendeploy-admin-portal. An admin portal deployed before the support portal would redirect ticket links to a host that is not serving yet. DNSsupport→ the VPS must exist first so Caddy can issue the certificate. - Support agents cannot see a customer's full profile, wallet or order actions; a ticket needing a refund or cancellation is handed to an admin, who does it on the Orders page as before (support never moves money).
- The ticket rules (
lib/support.ts,lib/support-tickets.ts) now live in the support portal; the admin portal keepslib/support.tsfor its configuration screens, so the shared template/placeholder rules exist in both portals and must be changed in both. - Rolling back: redeploy the previous admin portal image (its ticket pages
return), stop
support_portal, and only thenrollback_095.sql— the API must stop readingis_supportbefore the column is dropped.