Skip to content

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.sql adds users.is_support BOOLEAN NOT NULL DEFAULT FALSE — a third additive authority bit beside is_admin and is_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, like is_admin: a support agent sees customers' names, phones, emails and orders. The change is audited (SUPPORT_ROLE_GRANTED / _REVOKED). is_support is optional on PUT /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/login admits is_support or is_admin accounts (the admin login keeps refusing support agents). The token carries role=support (or admin). 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 by middleware.SupportStaffOnly, which — like AdminOnly — 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/dashboard URLs redirect (307) to the support portal, and /tickets keeps its path there, so bookmarks and staff emails already sent keep working. The staff-email ticket link default (SUPPORT_ADMIN_TICKET_URL_BASE) is now https://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_portal with its own env file (support-portal.env.production, its own NEXTAUTH_SECRET), a pinned aim_edge address (SUPPORT_PORTAL_EDGE_IP), a Caddy site for support.aimstoreorg.com, and a manual deploy-support-portal workflow 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 reads is_support), then deploy-support-portal, then deploy-admin-portal. An admin portal deployed before the support portal would redirect ticket links to a host that is not serving yet. DNS support → 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 keeps lib/support.ts for 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 then rollback_095.sql — the API must stop reading is_support before the column is dropped.