UAS - User Account Service

UAS is the identity foundation of the stack. It is where a person exists, how their email is verified, how they authenticate, and how their account status is managed. If you want to answer, "Who is this person and can they authenticate right now?", UAS is the source of truth.

UAS is intentionally not a public sign-up system. Accounts are created through internal onboarding, and the only public API surface is a secure stat check that validates email and passcode. Everything else is handled through authenticated, operator-controlled actions.

Service scope and boundaries

UAS owns identity and authentication policy. It does not create sessions (that is USM) and it does not authorize access to org data (that is OFM and downstream services). Its job is to maintain the user record, enforce identity lifecycle rules, and validate credentials safely.

Implemented feature breakdown (what exists today)

• Identity records: A user record with lifecycle status and identity metadata.
• Email management: Multiple emails per user with a single primary email. Email inputs are normalized to a canonical form before use.
• Email verification: Time-limited verification tokens are issued and confirmed to verify emails.
• Passcode management: Passcodes are set and reset with strength and reuse protection.
• User lifecycle status: Users move through unverified, verified, suspended, and doomed states with strict transitions; doomed is terminal.
• Payment method metadata: Payment methods are tracked by status, with support for default selection and suspension/retirement without exposing raw token material.
• Session cap configuration: Per-user configuration for maximum active sessions that USM enforces.
• Public stat endpoint: A single public credential check that validates email and passcode without revealing whether the email exists when credentials are wrong.

How the features are implemented (behavioral breakdown)

Identity creation and verification

1. A user record is created through internal onboarding.
2. A verification token is issued for the primary email.
3. The email is verified using the token. Only verified emails are trusted for authentication.
4. Once verified, the user can be promoted to verified status through operator workflows.

Passcode lifecycle

• Passcodes are never returned in responses and are stored only in a secure, hashed form.
• A passcode set or reset updates the authentication state and is treated as a recovery event.
• Recovery is expected to revoke existing sessions through USM for safety.

User status transitions

• unverified -> verified: Operator-controlled.
• verified -> suspended: Operator-controlled for incidents or compliance pauses.
• suspended -> verified: Operator-controlled when remediation completes.
• any -> doomed: Operator-controlled; doomed is terminal.

Payment method lifecycle

• Payment methods are tracked by status and can be promoted, suspended, or retired.
• Raw token material is never exposed in public responses.

Public stat check

• The stat endpoint accepts email and passcode.
• It validates credentials and user status without revealing whether the email exists on failure.

Example use cases (extensive)

Staff onboarding at a merchant: A new staff member is created via internal onboarding. They verify their email, set a passcode, and are promoted to verified status so they can sign in. USM then issues sessions used across OFM and PVM.

Security incident response: A credential compromise is suspected. Support triggers a passcode reset, which revokes all existing sessions via USM. The user must authenticate again to regain access.

Account suspension during investigation: A user is suspended during a compliance review. They cannot authenticate while suspended. Once cleared, they are restored to verified status.

Account retirement: A contractor leaves the organization. Their account is suspended during offboarding and then doomed to permanently retire the identity once it is no longer needed.

Payment method hygiene: A user updates their default payment method, suspends a compromised method, and later retires it. No raw tokens are exposed in the process.

Session cap management: An organization tightens security by lowering a user's maximum active sessions, reducing the number of concurrent logins USM will allow.

Example scenarios and acceptance criteria

Scenario 1: Email verification and promotion

• A user verifies their primary email via a token.
• An operator promotes the user to verified status.
• Acceptance: only verified emails can authenticate; the user can create sessions after promotion.

Scenario 2: Passcode reset revokes sessions

• A user resets their passcode after a suspected compromise.
• USM revokes existing sessions.
• Acceptance: old sessions fail validation; new sessions require the new passcode.

Scenario 3: Stat endpoint anti-enumeration

• A stat check is called with an unknown email and incorrect passcode.
• The same stat check is called with a known email and incorrect passcode.
• Acceptance: responses are indistinguishable; no existence leak occurs.

Scenario 4: Suspension and doom

• A verified user is suspended and later doomed.
• Authentication attempts are made in each state.
• Acceptance: suspended users cannot authenticate; doomed is terminal.

Constraints and invariants

• UAS does not provide public sign-up or public account recovery endpoints.
• Its only public API is the stat check and it always requires a valid email and passcode.
• Any change that affects authentication is treated as recovery and is expected to revoke sessions in USM.
• Passcodes and raw payment tokens are never returned in API responses.
• Doomed is terminal and cannot be reversed.

How UAS fits with other services

USM uses UAS for credential validation and status checks when creating sessions. OFM uses UAS identities to link owners and members to organizations. Downstream services rely on USM sessions, which only exist if UAS says the identity is valid.

Implemented vs planned

Implemented: identity records, email verification, passcode management, user status lifecycle, payment method metadata, session cap configuration, and the public stat endpoint.

Planned: no additional public contract features are defined at this time. Any future changes will be additive and documented explicitly.

For exact request and response shapes, see the UAS contract pages at https://doc.g3nretailstack.com/uas/.