User Management Phase A In-progress

Account lifecycle, authentication, and role-scoped access for every user type - internal operators, business owners, store employees, and customers. It is the platform's foundation: every other module trusts the identity and scope this module issues.

1. Identity

Property	Value
Module ID	CORE-01
Tier	Core
Status	In-progress
Phase	P1 (auth + owner) shipped · P2 (employee + customer) in progress
Priority	HIGH
Primary users	Owner · Cashier · Employee · Customer · Internal operators (Super Admin / Admin / Operator)

2. Purpose & Scope

Included	Excluded
Sign-up, sign-in (username / email / phone + password)	OAuth / third-party login (scheme defined, no provider)
Password change + forgot-password reset	Session revocation / remote logout (stateless JWT)
Email & phone verification via OTP	Two-factor enforcement (scheme defined, not enforced)
User profile, identifiers, and per-user settings	Custom role creation → Permissions
Employee lifecycle + merchant assignment	User invitations
Customer lifecycle + promote-to-user	Multi-organization access for one user
Eight fixed roles + role-scoped data filtering	Audit / login history

3. Capabilities

Capability	What the user can do
Sign-up	Create an account with username + password; profile, identifiers, and default settings are created together
Sign-in	Authenticate with any verified identifier + password; receive a scoped session token
Change password	Verify current password, then set a new one
Forgot password	Reset a forgotten password via OTP (request → verify code → set new)
Email / phone verification	Verify an email or phone identifier with a one-time code
Link account	Add a verified email or phone to an existing account
User profile & identifiers	Maintain name, birthday, locale, and multiple emails / phones
Per-user settings	Default settings auto-created on registration; user can read / update them
Fixed roles & scoping	Eight system roles; list / count operations filtered by the caller's scope
Employee management	Owner creates, assigns to merchants, updates, deactivates, removes employees
Customer management	Owner creates / updates / soft-deletes customers; promote a sale customer to a full user
Two-factor auth	Credential scheme exists; enforcement not built
OAuth login	Credential scheme exists; login flow not built

Known gaps (status-honest): email verification on sign-up is currently disabled in code, so a fresh sign-up may not be able to sign in by email until verified through a separate flow; customer accounts are created without credentials, so they cannot sign in yet. See the developer docs for details.

4. Module Dependencies

Depends on	Why
Permissions	Roles, permissions, and policy edges that define what each user can do
Commerce	Owners and employees belong to organizations; employees and customers scope to merchants
Customer	Customer accounts feed customer relationship management

5. Backend Packages

Implementation detail lives in the developer docs - this section only maps the module to the services that power it.

Package	Role	Developer docs
@nx/identity	JWKS issuer (ES256); owns users, credentials, identifiers, roles, employees, customers, OTP	identity

Feature deep-dives: Authentication · User Management · Customer Management · RBAC · MFA & OTP.

Engineering Mapping (Feature ⇄ Package)

The horizontal axis of the Feature Spine - each business feature (<AREA> in the URD) maps to its engineering home. Reciprocal: the package docs link back here.

Feature	Dev package	Status
AUTH Authentication	@nx/identity	Built
USR User Account	@nx/identity	Built
ROLE Roles & Scoping	@nx/identity	Built
CFG User Configuration	@nx/identity	Built
EMP Employee Management	@nx/identity	In-progress
CUS Customer Management	@nx/identity	In-progress

6. Key User Flows

Sign-in

Sign-up & onboarding

Employee lifecycle

7. Roles & Permissions

Eight fixed system roles, ordered by priority. They are pre-seeded and cannot be edited or deleted. Custom roles are out of scope here - see Permissions.

Role	Type	Scope	Can	Cannot
Super Admin	Internal	System-wide	Everything; bypasses all data filters	-
Admin	Internal	System-wide	Everything; bypasses all data filters	-
Operator	Internal	System-wide	Read-focused platform operations	Mutate beyond support scope
Owner	External	Own organization	Manage own org and all its merchants, employees, customers	Touch other organizations
Cashier	External	Assigned merchants	Operate assigned merchants (same tier as Employee)	Access unassigned merchants
Employee	External	Assigned merchants	Operate only assigned merchants	Access unassigned merchants
Customer	External	Linked organization	Customer-scoped access	Operate stores
Guest	External	Global	Unauthenticated-style access	Any backend permission (lowest priority)

Rule: a user can never create, grant, or manage a role with priority equal to or higher than their own.

8. Status & Roadmap

Phase	Capabilities
P1	Sign-up / sign-in, password change & reset, email/phone OTP, profile & identifiers, per-user settings, fixed roles & scoping, Owner auto-assignment
P2	Employee lifecycle + merchant assignment, customer lifecycle + promote-to-user, full user status lifecycle, role-based data filtering
P3	Custom role creation (→ Permissions), OAuth / third-party login, two-factor enforcement, login history, session revocation, user invitations, multi-organization

9. Related Pages

• URD
• PRDs
• Permissions - roles & access control
• Commerce - organizations & merchants
• Identity developer docs