support_backend/specs/010-identity-auth/spec.md

Feature Specification: Identity and Authentication

Feature Branch: 010-identity-auth

Created: 2026-09-07

Status: Draft

Input: User description: "supporthub-web's admin/agent role-gating (its own Phase 1, 001-agent-admin-ui) has no real backend to build on: fastify.authenticate is a complete no-op stub, and the existing identity/auth scaffold's login endpoint accepts an email alone with no password and returns the raw user record, never a session. Build minimal, real agent/admin authentication in supporthub-api first, as a prerequisite for the frontend feature."

User Scenarios & Testing (mandatory)

User Story 1 - An agent or admin logs in and receives a session (Priority: P1)

A user with a SupportHub-issued account (never a SaaS-delegated identity — this is SupportHub's own staff, per Constitution Principle I's "support org structure" being SupportHub's own authority) logs in with their email and password and receives a session token that authorizes their subsequent requests.

Why this priority: Every other story in this feature, and the entire admin/agent-facing half of supporthub-web, has nothing to build on without this.

Independent Test: Log in with a seeded account's correct credentials; confirm a session token is returned and a subsequent authenticated request using it succeeds.

Acceptance Scenarios:

1. Given a user account with a set password, When they submit the correct email and password, Then they receive a session token and their own id/email/name/role.
2. Given a user account, When they submit an incorrect password, Then the request is rejected with no session token issued — the rejection message MUST NOT reveal whether the email itself was valid (never "wrong password" vs "no such user" as distinguishable responses).
3. Given no account exists for a submitted email, When login is attempted, Then it is rejected with the same indistinguishable-from-wrong-password response as Scenario 2.

---

User Story 2 - Protected routes require a valid session; admin-only routes require the admin role (Priority: P1)

Every existing /admin/* route (and any other route already gated by the fastify.authenticate stub across features 002-009) actually rejects a request with no valid session, and every route that should be admin-only actually rejects a valid session whose role isn't ADMIN.

Why this priority: This is the entire point of the feature — without it, User Story 1 issues a token that nothing on the backend actually checks, which is no better than the current no-op stub.

Independent Test: Call an existing admin route (e.g. creating a team) with no Authorization header, with an expired/malformed token, with a valid agent-role token, and with a valid admin-role token; confirm exactly the last one succeeds.

Acceptance Scenarios:

1. Given a request with no Authorization header, When it hits a route gated by fastify.authenticate, Then it's rejected as unauthorized.
2. Given a request with a malformed, expired, or tampered token, When it hits a gated route, Then it's rejected as unauthorized — never silently treated as anonymous/no-op the way the current stub does.
3. Given a valid session for a user whose role is AGENT, When it hits a route that requires the ADMIN role specifically, Then it's rejected as forbidden, distinct from the unauthorized case above.
4. Given a valid session for a user whose role is ADMIN, When it hits any route gated by either fastify.authenticate or an admin-only requirement, Then it succeeds.

---

User Story 3 - An authenticated user can identify themselves (Priority: P2)

A logged-in user can ask "who am I" and get back their own identity and role, without needing to decode their own session token client-side.

Why this priority: Depends on User Story 1. supporthub-web's role-gating (rendering the admin portal only for admins) needs a reliable way to know the current session's role after the token is already held — decoding a JWT's claims client-side is a reasonable fallback, but a real endpoint is what lets that identity be revalidated against current server-side state (e.g. a deactivated account) rather than trusting a possibly-stale token's own claims forever.

Independent Test: Log in, then call the "who am I" endpoint with the resulting session; confirm it returns the same identity and role as the login response, and that it's rejected under the same conditions as User Story 2.

Acceptance Scenarios:

1. Given a valid session, When the identity endpoint is called, Then it returns the current id/email/name/role for that session.
2. Given a session for an account that has since been deactivated, When the identity endpoint (or any gated route) is called, Then it's rejected — a session's validity is re-checked against current account state, not just the token's own unexpired signature.

---

User Story 4 - An admin creates additional agent/admin accounts (Priority: P2)

An admin creates a new user account (agent or admin role) with an initial password, since there is no public self-signup for SupportHub's own staff accounts.

Why this priority: Depends on User Story 2 (admin-only gating). Without this, the only way to add a second real account is a direct database write — fine for the one seeded bootstrap admin, not for onboarding a real team.

Independent Test: As an admin, create a new agent account with a password; confirm the new account can immediately log in (User Story 1) with those credentials.

Acceptance Scenarios:

1. Given an authenticated admin, When they create a new account with an email, name, role, and initial password, Then it's created and can log in immediately.
2. Given a non-admin session, When they attempt to create an account, Then it's rejected as forbidden (User Story 2's own guarantee, exercised here specifically).
3. Given an email already in use by an existing account, When account creation is attempted, Then it's rejected — never a second account silently sharing one email.

---

User Story 5 - A user logs out (Priority: P3)

A logged-in user can end their own session explicitly, rather than only ever waiting for it to expire.

Why this priority: Lowest priority — a short-lived token that simply expires already bounds the exposure of a lost/leftover session; an explicit logout is a UX nicety layered on top, not a security-critical gap the way User Stories 1-2 are.

Independent Test: Log in, log out, then attempt to use the same token again; confirm it's now rejected.

Acceptance Scenarios:

1. Given a valid session, When the user logs out, Then that specific token is rejected on any subsequent use, even though it hasn't yet expired.

---

Edge Cases

• What happens to a session already issued to a user whose password is changed or whose account is deactivated? Out of scope for this feature to build a full revocation-on-every-write mechanism (Assumptions) — User Story 3's re-check-on-identity-call is the only server-side re-validation this feature guarantees; a short token lifetime (Assumptions) bounds the rest.
• What happens if two login attempts for the same account happen concurrently with different passwords (e.g. a credential-stuffing attempt racing a real login)? Each is evaluated independently against the stored password hash — no shared mutable state between them, so no new concurrency concern is introduced.
• What happens to the two demo accounts the seed script already creates (admin@supporthub.internal, agent@supporthub.internal) which currently have no password? This feature MUST give them real, seeded passwords (documented for local/dev use only) so the existing seed script keeps producing an immediately-usable bootstrap admin — never account IDs that exist but can never actually log in.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST let a user log in with email and password, returning a session token and their own identity (id/email/name/role) on success.
• FR-002: A login attempt with an incorrect password or an unrecognized email MUST be rejected with an indistinguishable response — the system MUST NOT reveal whether a submitted email corresponds to an existing account.
• FR-003: Passwords MUST be stored only as a salted hash, never in plaintext or in any reversible form.
• FR-004: fastify.authenticate MUST reject a request with a missing, malformed, expired, or otherwise invalid session token — it MUST NOT pass a request through as anonymous/no-op the way the current stub does.
• FR-005: The system MUST provide a way to require a specific role (at minimum, ADMIN) on a route, distinct from and layered on top of fastify.authenticate's own valid-session check, returning a distinguishable forbidden (not unauthorized) response when the role requirement fails.
• FR-006: Every existing route currently gated by fastify.authenticate (across 002-009's own admin/read surfaces) MUST continue to work for a valid session and MUST now actually reject an invalid one — this feature does not change which routes are gated, only makes the gate real.
• FR-007: The system MUST provide an endpoint that returns the current session's own identity and role, re-validated against current account state (not solely the token's own claims).
• FR-008: The system MUST let an authenticated admin create a new account (email, name, role, initial password), rejecting a duplicate email.
• FR-009: The system MUST let a user invalidate their own current session token before its natural expiry.
• FR-010: The two existing seeded demo accounts MUST be given real, working passwords as part of this feature, documented as local/development credentials.

Key Entities

• User: A SupportHub staff identity — email, name, role (ADMIN/AGENT), and (new in this feature) a securely hashed password. Distinct from Agent (the routing/skills/team-membership profile an AGENT-role User has) and from a SaaS-delegated customer identity, which this feature does not touch.
• Session: The short-lived, server-issued proof that a User authenticated successfully, carrying their id, email, and role; revocable before its natural expiry (User Story 5).

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of requests to a fastify.authenticate-gated route with no valid session are rejected, verified across every module's existing admin routes (002-009), not just this feature's own new endpoints.
• SC-002: 100% of admin-only actions are rejected for a valid non-admin session, verified for at least one action from each module that has one.
• SC-003: 0% of login rejections reveal whether the submitted email corresponds to an existing account, verified by comparing the exact response for both cases.
• SC-004: 100% of passwords are stored only as a hash — verified by inspecting the stored representation directly, never as a value that could be reversed to the original password.
• SC-005: An admin can create a working new account and have it log in successfully within the same test run, with no manual database step.

Assumptions

• No password-reset/forgot-password flow is built in this feature — an admin can create a new account (User Story 4), but resetting an existing one's forgotten password is out of scope; the smallest viable fix today is an admin recreating the account or a direct operational fix, not a self-service flow.
• Session tokens are short-lived JWTs with a fixed expiry, not a server-side session store per token — logout (User Story 5) is implemented via a revocation check (a denylist of logged-out-early tokens), not full server-side session tracking; this keeps token validation fast (no DB round trip on every request) while still making explicit logout meaningfully different from "wait for expiry." The exact expiry duration and revocation mechanism are research.md decisions, not fixed here.
• No account self-registration — every account is created either by the seed script (the two bootstrap demo accounts) or by an existing admin (User Story 4); there is no public sign-up endpoint, consistent with these being SupportHub's own staff accounts, never a SaaS-delegated customer identity.
• This feature does not add a password-strength policy, MFA, or rate-limiting specifically for login attempts beyond what 002's existing generic rate-limit infrastructure might already cover incidentally — those are real hardening concerns explicitly named in docs/10-implementation-roadmap.md's own Phase 11 ("security hardening pass"), not this feature's job to anticipate.
• The CUSTOMER value already defined on UserRole is never assigned by this feature — no code path in this feature creates a User with role: CUSTOMER; per Constitution Principle I, customer identity remains exclusively SaaS-delegated (002's inbound trust boundary), never a local User row. The enum value's continued existence is a pre-existing scaffold detail this feature doesn't need to remove to stay correct.