Authentication (auth)
Shared session primitives and route guards consumed by both
customer_accounts and admin_users. One of the two singular module
folders permitted by the naming conventions (alongside example).
What it owns
- Sessions —
session-service.tspersists session rows in Postgres with a Redis cache layer for hot reads; cookies signed via@fastify/cookie. - Password hashing — not this module's:
hashPassword/verifyPasswordare the platform's (@endora-commerce/platform/kernel,packages/platform/src/kernel/crypto/password-hasher.ts), argon2id with OWASP parameters (19 MiB, two passes). See the Hardware & system requirements section ofREADME.mdat the repository root. - TOTP — not this module's either: the
mfamodule'stotp.tswrapsotpauth, and its recovery codes are rows inmfa_enrolments. - Fastify plugin —
plugin.tsparses the session cookie and attachesrequest.actor = { kind, id, ... }plusrequest.adminActor. - Route guards —
requireAdmin(permission?),requireAdminAny(codes)andrequireCustomer, provided as ports from this module's composition (src/backend/index.ts) and resolved by every module that gates a route. They were Fastify decorators on the plugin once; they were turned into ports so production and the test harness run the same implementation instead of one each. The two admin guards also refuse, with 401, a session whose administrator account is no longer active (deactivated, deleted or gone), so a session row that outlived its account does not keep answering; an active account that lacks the permission is answered 403.SessionService.destroyAllForAdmin(adminUserId, { exceptSessionId? })revokes an administrator's sessions and the impersonations they started, optionally sparing one.
Last seen
Every session row carries last_seen_at: when a request last arrived with
that session's cookie. It is stamped for customer sessions and, since the
CRM's event reminders needed it, for administrator sessions too — until
then an administrator's row held the sign-in time and nothing after.
- Throttled.
SessionService.touchLastSeenwrites at most once a minute per session: every authenticated request costs one RedisSET NX EX 60, and only the first in each minute updates the row. The write is fire-and-forget, so it never delays or fails a request. - Read through a port,
AuthSessionReadPort(container nameauthSessionReadPort):lastSeenByCustomerAccount(ids, since)andlastSeenByAdminUser(ids, since)each answer the newestlastSeenAtper person among sessions seen at or aftersince. A person with no such session is absent from the answer. - An impersonation is the customer's presence. A session in which an administrator acts as a customer counts for that customer and not for the administrator.
- What it measures. An open Admin UI asks for notifications every 30 seconds, so "seen in the last few minutes" means has the Admin UI open in a browser. It does not say that anybody is looking at it.
No HTTP routes of its own
auth is a primitive module. The customer sign-in and sign-out endpoints are served by
organizations (over customer_accounts' services), the administrator's by admin_users,
and the second step of a two-step sign-in by mfa.
Extension points
- Session storage —
session-serviceis constructed with(emFactory, redis); alternative caches plug in here. - Custom actor kinds — extend the
request.actordiscriminated union and update therequireXpre-handlers; existing callers keep working because the routes only use therequireXfactory they already consume.