Staff Identity & Access (Invites)

The Staff Identity & Access system manages the onboarding and credential recovery for clinic personnel. It employs a token-based invitation workflow to ensure staff members securely set their own passwords and enroll in Multi-Factor Authentication (MFA) via TOTP.

This system differentiates between two primary invite purposes: join for new staff onboarding and reset for administrative credential resets. All invites are time-limited, single-use, and bound to specific organizational roles.

Architecture and Data Model

The system stores invitation data in the staff_invites table. Security is enforced through PostgreSQL Row-Level Security (RLS), ensuring that clinic admins can only manage invites within their own organization.

Database Schema

The staff_invites table tracks the lifecycle of an invitation, including its association with a user, their role, and the state of acceptance or revocation.

Security Constraints

• Token Hashing: The system never stores plain-text tokens. It generates a 32-byte secure random token and stores its SHA-256 hash.
• Token Delivery: Plain tokens are passed to the client via URL fragments (e.g., /invite#token), which prevents them from being sent to the server in request logs or Referer headers.
• TTL: Invites expire automatically after 72 hours.
• Isolation: RLS policies (tenant_isolation) restrict INSERT and UPDATE operations to the dhc_app role within the current organization.

Sources: service.ts:39, service.ts:108, migration.sql:31-35

Invitation Lifecycle

1. Creation and Issuance

Clinic admins initiate the workflow by providing an identifier (email or Indian mobile number) and a role. The service validates the identifier, ensures the person does not already hold the active role, and marks any previous open invites for that user/role combination as revoked.

2. Inspection and Acceptance

When a user opens an invite link, the frontend InviteFlow component reads the token from the URL fragment and calls the inspect endpoint to display organization details and the invite purpose.

Sources: invites.ts:46-77, invite-flow.tsx:49-105

3. Credential Setup Flow

The system enforces specific logic depending on whether the user is new to the platform or an existing staff member at another clinic.

Administrative Actions

Authenticator Resets

Clinic admins can reset a staff member's credentials if the staff member only works at their clinic. This process:

1. Clears the user's passwordHash and mfaSecret.
2. Revokes all active staff sessions for that user.
3. Issues a new invite link with the purpose reset.

If a staff member works at multiple clinics, a clinic admin is prevented from performing the reset. This must be handled via the Platform Support service to prevent unauthorized cross-clinic access.

Sources: staff/service.ts:63-138, support/service.ts:28-60

Revocation

Admins may revoke a pending invite at any time. Revocation updates the revoked_at timestamp in the staff_invites table and changes the related membership status to revoked. Once revoked, the invite token is immediately invalidated for inspection or acceptance.

Sources: service.ts:140-165, routes.ts:44-47

Technical Specifications

Input Validation

• Identifiers: Must be a valid email address or a normalized Indian mobile number (+91 prefix).
• Passwords: New passwords must meet the MIN_PASSWORD_LENGTH (12 characters).
• TOTP: Codes must be exactly 6 digits.

Sources: service.ts:340-353, invites.ts:14-16, invite-flow.tsx:32

Audit Logging

Significant identity events are recorded in the audit log, including:

• staff.invite.created
• staff.invite.accepted
• staff.authenticator.reset
• auth.mfa.enrolled

Sources: service.ts:100-107, service.ts:258-266, staff/service.ts:114-121

Summary

The Staff Identity & Access system provides a secure, auditable, and multi-tenant aware framework for managing clinic personnel. By leveraging token-based invites and mandatory MFA enrollment, the system ensures that sensitive clinical data access is restricted to verified users who have established secure credentials.