URD: User Management

Module	CORE-01	Version	v0.4
Status	In-progress	Date	2026-05-29

1. Purpose

Define what User Management must do for users: how they create accounts, authenticate, and manage profiles, and how business owners manage employees and customers within their organizations. It is the platform's foundation — every other module trusts the identity and scope issued here.

2. Scope

Included	Excluded
Account creation (sign-up) and authentication (sign-in)	Custom role creation → Permissions
Password management (change, forgot / reset)	OAuth / OAuth2 login flow
OTP verification for email and phone; link account	Session management and remote revocation
Eight fixed system roles and role-based access	User invitation system
Employee lifecycle (create, assign, deactivate, remove)	Audit / login history
Customer lifecycle (create, update, soft-delete, promote)	Multi-organization access for one user
User profile, identifier, and per-user configuration management	Two-factor enforcement

3. Definitions

Term	Definition
User	An authenticated identity — internal (operator) or external (owner, employee, customer).
Credential	A secret used to authenticate — a hashed password today; 2FA / OAuth schemes are defined but not enforced.
Identifier	A login value tied to a user — username, email, or phone. Each is globally unique within its type.
User Profile	Personal info attached to a user — name, birthday, locale, contact details. One per user.
User Configuration	A per-user key-value setting, grouped by code. A default set is created on registration.
Role	A classification that determines access level and data scope. Eight fixed roles exist.
Owner	The user who creates a business during onboarding; has full access to their organization.
Cashier	A merchant-level staff role for cashiers, scoped to specific merchants (same tier as Employee).
Employee	A staff member scoped to specific merchants within an organization.
Customer	An end-customer linked to an organization; can be promoted from sale-level data to a full user.
Guest	An unauthenticated-style global role with no backend permissions; lowest priority.
OTP	A one-time code delivered via email or SMS for identifier verification or password reset.
Session Token (JWT)	Issued on sign-in; carries user ID, roles, organization IDs, and merchant IDs for stateless authorization.

4. Conceptual Model

Conceptual only — full schema lives in the developer domain model.

5. Functional Requirements

One table per functional area. <AREA> codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).

5.1 Authentication (AUTH)

ID	P	Requirement
URD-AUTH-001	M	User can sign up with a username and password
URD-AUTH-002	M	Sign-up creates account, profile, identifiers, and default settings in one operation
URD-AUTH-003	M	If any part of sign-up fails, nothing is created (all-or-nothing)
URD-AUTH-004	M	User can sign in with any verified identifier (username / email / phone) + password
URD-AUTH-005	M	Successful sign-in returns a session token carrying roles and organization / merchant scope
URD-AUTH-006	M	Passwords are securely hashed before storage and never stored in plain text
URD-AUTH-007	M	User can change their password (current password verified first)
URD-AUTH-008	M	User can verify their email via OTP (request → receive code → submit)
URD-AUTH-009	M	User can verify their phone via OTP (same flow)
URD-AUTH-010	M	User can reset a forgotten password (request → verify code → set new password)
URD-AUTH-011	S	User can add (link) a verified email or phone to an authenticated account
URD-AUTH-012	S	System records the last sign-in timestamp
URD-AUTH-013	C	Two-factor authentication is enforced Planned
URD-AUTH-014	C	OAuth / third-party login is supported Planned

5.2 User Account (USR)

ID	P	Requirement
URD-USR-001	M	Each user has a unique system-generated ID
URD-USR-002	M	A user can have multiple identifiers (username, emails, phones)
URD-USR-003	M	Each identifier is globally unique within its type
URD-USR-004	M	Username is required and automatically considered verified
URD-USR-005	M	Email and phone identifiers start unverified and require OTP to verify
URD-USR-006	M	User can view and update their own profile (name, birthday, locale, contacts)
URD-USR-007	M	Authorized users can change a user's status (activate, deactivate, block, archive)
URD-USR-008	M	Deactivated and blocked users cannot sign in
URD-USR-009	M	User data is always preserved — accounts are never permanently deleted (soft-delete)
URD-USR-010	S	User can set a language / locale preference
URD-USR-011	C	ARCHIVED is a terminal status and cannot be reactivated

5.3 Roles & Scoping (ROLE)

ID	P	Requirement
URD-ROLE-001	M	System provides eight fixed roles: Super Admin, Admin, Operator, Owner, Cashier, Employee, Customer, Guest
URD-ROLE-002	M	Roles have a priority hierarchy; higher priority means broader access
URD-ROLE-003	M	Super Admin and Admin bypass all data filtering
URD-ROLE-004	M	Owner sees only their own organization and its merchants
URD-ROLE-005	M	Employee / Cashier see only merchants they are assigned to
URD-ROLE-006	M	List and count operations are filtered by the requesting user's scope
URD-ROLE-007	M	Users cannot manage roles equal to or higher than their own priority
URD-ROLE-008	M	Owner role is automatically assigned during sign-up

5.4 Employee Management (EMP)

ID	P	Requirement
URD-EMP-001	M	Owner can create employee accounts
URD-EMP-002	M	Employee is linked to an organization and one or more merchants
URD-EMP-003	M	Employee can access only merchants they are assigned to
URD-EMP-004	M	Employee can sign in with their own credentials
URD-EMP-005	M	Data queries for an employee are filtered by their merchant assignments
URD-EMP-006	M	Owner can update employee merchant assignments (replaces all previous assignments)
URD-EMP-007	M	Owner can deactivate or remove an employee account
URD-EMP-008	M	System validates that the owner actually owns the organization and all listed merchants

5.5 Customer Management (CUS)

ID	P	Requirement
URD-CUS-001	M	Owner can create customer accounts
URD-CUS-002	M	Customer is linked to an organization and receives the Customer role automatically
URD-CUS-003	M	Customer profile includes name and contact details
URD-CUS-004	M	Customer information can be updated and soft-deleted
URD-CUS-005	S	A sale-level customer can be promoted to a full user account
URD-CUS-006	S	Promotion checks for identifier conflicts before creating the user

5.6 User Configuration (CFG)

ID	P	Requirement
URD-CFG-001	M	Default configurations are created automatically when a user registers
URD-CFG-002	M	Configurations are grouped and uniquely identified by code per user
URD-CFG-003	S	User can view and update their own configurations

6. Acceptance Criteria

AC-AUTH-01: Sign-in

Given	When	Then
Valid credentials, verified identifier	User signs in	Session token issued with roles and scope
Invalid password	User signs in	Authentication rejected
Unverified identifier	User signs in	Sign-in rejected — identifier not verified
Deactivated / blocked user	User signs in	Access denied
Successful sign-in	—	Last sign-in timestamp updated

AC-AUTH-02: Sign-up

Given	When	Then
New username + password + profile	User signs up	Account created with Owner role
Username already exists	User signs up	Conflict error
Successful registration	—	Default settings auto-created
Any step fails	—	Entire registration rolls back

AC-AUTH-03: OTP verification

Given	When	Then
Unverified email or phone	User requests OTP	Code delivered, session token returned
Valid session + correct code	User submits	Identifier marked verified
Expired code	User submits	Error — code expired
Too many attempts	User retries	Error — max attempts exceeded

AC-AUTH-04: Forgot password

Given	When	Then
User forgot password	Requests reset	Reset session created
Valid reset code	User verifies	Session confirmed
Verified session	User sets new password	Password updated (hashed)

AC-EMP-01: Employee creation

Given	When	Then
Owner	Creates employee with merchant list	Account created with Employee role, linked to org + merchants
Owner does not own the organization	Creates employee	Forbidden
Merchant not under owner's organization	Included in list	Validation error

AC-EMP-02: Merchant reassignment

Given	When	Then
Existing employee	Owner updates assignments	Previous assignments replaced with new ones
—	—	Employee sees only the new merchants

AC-CUS-01: Customer promotion

Given	When	Then
Sale-level customer	Promotion triggered	Full user created with Customer role
Identifier conflict	Promotion attempted	Blocked with conflict error

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	Passwords must be securely hashed; plain-text storage is forbidden
C-02	The eight fixed roles are pre-seeded and cannot be modified or deleted
C-03	Role priority is enforced — no user can manage a role at their level or above
C-04	Account creation is atomic — partial creation is not allowed
C-05	All records use soft-delete — physical deletion is never performed
C-06	Each identifier type is globally unique (one email belongs to only one user)
C-07	Employees must be linked to both an organization and at least one merchant
C-08	Session tokens are stateless — permission changes take effect on next sign-in
C-09	All operations except sign-in / sign-up require authentication

Non-Goals

• Custom role creation and dynamic permission management → Permissions
• OAuth / OAuth2 third-party login flow
• Session management and remote revocation
• User invitation via email or phone
• Login history and audit logging
• Multi-organization access for a single user
• MFA enforcement policies

8. Version History

Date	Author	Description	Ver
2026-02-26	P. Do — Product Owner	Initial user stories	v0.1
2026-04-16	Product	Restructured into URD with requirement IDs	v0.3
2026-05-29	Product	Migrated to module-docs convention; corrected status (BLOCKED, no IDSAFE), added link-account + status-honest gaps	v0.4