URD: User Management

Module	CORE-01	Version	v0.6
Status	In-progress	Date	2026-06-15

Business documentation. This URD is User Management's feature list - each feature below is one Functional Area (<AREA>). The same <AREA> keys the feature's PRDs (PRD-<AREA>-NNN) and tests (TC-<AREA>-NNN), and each feature is listed in the Delivery feature catalog. See the Feature Spine convention.

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. Feature Catalog

The feature list of this module. Each row is one feature (a Functional Area). Detail in §6. Mirrored in the Delivery feature catalog.

Feature ID	Feature	Phase	Status	Priority
AUTH	Authentication	P1	Built	High
USR	User Account	P1	Built	High
ROLE	Roles & Scoping	P1	Built	High
EMP	Employee Management	P2	In-progress	High
CUS	Customer Management	P2	In-progress	High
CFG	User Configuration	P1	Built	High

Status: live from Plane where mapped, otherwise registry-declared. Vocabulary mirrors Plane (state-group / phase).

6. Features

One sub-section per feature, in catalog order. Each feature keeps its description, requirements, and acceptance together. Priority = MoSCoW (Must / Should / Could / Won't).

AUTH - Authentication Built

Feature ID: user-management/AUTH · Phase: P1 · PRDs: - · Dev: @nx/identity

What it does for users: people create an account and sign in with a username, email, or phone plus a password; they change or reset their password and verify their email and phone via one-time codes.

Requirements

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

Acceptance

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)

USR - User Account Built

Feature ID: user-management/USR · Phase: P1 · PRDs: PRD-USR-001 · PRD-USR-002 · Dev: @nx/identity

What it does for users: each user has a unique account that can hold several identifiers (username, emails, phones), an editable profile, a language preference, and a status lifecycle - and account data is always preserved via soft-delete. Identifiers are themselves a managed resource: a user can list and add their own, each typed by a scheme, and any added identifier starts unverified.

Requirements

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
URD-USR-012	M	Each identifier declares a scheme that types it - username, email, phone number - drawn from a fixed, validated set (alongside system-issued schemes)
URD-USR-013	M	Identifiers are a managed resource: list, search, count, and single-record read, scoped to the caller's access
URD-USR-014	M	Adding an identifier always binds it to the requesting user and creates it unverified; a supplied user reference or verified flag cannot override this
URD-USR-015	S	Identifiers can be updated and removed (single or by filter) via soft-delete; identifier data is preserved
URD-USR-016	M	Every identifier operation (read / create / update / delete) is individually permission-gated and merchant-scoped

Acceptance

AC-USR-01: Account identity & lifecycle

Given	When	Then
A new account	Created	A unique system-generated ID is assigned; data is soft-deletable, never permanently deleted
A deactivated or blocked user	Attempts sign-in	Access is denied

AC-USR-02: Identifier management

Given	When	Then
A signed-in user	Lists their identifiers	Only identifiers within the caller's scope are returned, each labelled by its scheme
A user adds an identifier	Create is submitted	The identifier is owned by the requesting user and stored unverified
A create request naming another user or pre-set as verified	Submitted	The owner is still the caller and the identifier is still unverified - the request values are ignored
An identifier is removed	Delete is submitted	The row is soft-deleted and preserved, never physically removed

ROLE - Roles & Scoping Built

Feature ID: user-management/ROLE · Phase: P1 · PRDs: - · Dev: @nx/identity

What it does for users: eight fixed system roles set each user's access level and data scope; higher-priority roles see more, list/count results are filtered to the caller's scope, and no one can manage a role at or above their own priority.

Requirements

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

Acceptance

AC-ROLE-01: Role-scoped access

Given	When	Then
An Owner	Lists or counts records	Only their own organization and its merchants are returned
A user	Attempts to manage a role at or above their own priority	The action is rejected

EMP - Employee Management In-progress

Feature ID: user-management/EMP · Phase: P2 · PRDs: - · Dev: @nx/identity

What it does for users: owners create employee accounts, assign them to one or more merchants in their organization, and update or deactivate those assignments; each employee signs in with their own credentials and sees only the merchants they are assigned to.

Requirements

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

Acceptance

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

CUS - Customer Management In-progress

Feature ID: user-management/CUS · Phase: P2 · PRDs: - · Dev: @nx/identity

What it does for users: owners create and maintain customer accounts linked to their organization, and can promote an existing sale-level customer into a full user account, with identifier-conflict checks.

Requirements

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

Acceptance

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

CFG - User Configuration Built

Feature ID: user-management/CFG · Phase: P1 · PRDs: PRD-USR-001 · PRD-USR-002 · Dev: @nx/identity

What it does for users: each user gets a default set of personal settings on registration, grouped and uniquely identified by code, and can read and update their own settings - including saving a custom table view of their own columns and filters. Settings are readable as soon as a user signs in, before a merchant is selected.

Requirements

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
URD-CFG-004	M	Configurations belong to a fixed group set (system, table, integration) and are uniquely identified by code per user
URD-CFG-005	M	Configuration reads are available to any authenticated user before a merchant is selected; create / update / delete are permission-gated
URD-CFG-006	S	A user can create a custom table view from a code + display name; the system clones the base table configuration's stored layout into a new per-user view in the table group
URD-CFG-007	M	Creating a custom view rejects a duplicate (user + code + name) view and requires the referenced base table configuration to exist

Acceptance

AC-CFG-01: Default configurations

Given	When	Then
A new user	Registers	A default set of configurations is created automatically, grouped and uniquely identified by code

AC-CFG-02: Custom table view

Given	When	Then
A signed-in user, before any merchant is selected	Reads their configurations	The configurations are returned (authenticate-only, user-level)
A user, a code + display name, an existing base table layout	Saves a custom view	A new per-user view is created in the table group, cloning the base layout
A view reusing an existing (user + code + name)	Saved	Refused - the view already exists
A code with no matching base table configuration	Saved	Refused - the base table configuration does not exist

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
2026-06-04	Claude (AI pair)	Reorganize by feature (Feature Spine); each feature carries its own requirements + acceptance; constraints moved to cross-cutting CON	v0.5
2026-06-15	Product	Extend USR (identifier-management resource) + CFG (config resource, pre-merchant reads, custom views); link PRD-USR-002	v0.6