OmniOilPersonal/openspec/changes/notify-approved-access-requests/specs/access-request-provisioning/spec.md

Delta for Access Request Provisioning

ADDED Requirements

Requirement: Approve Request Provisions Customer Access

The system SHALL convert an approved access request into real customer access by creating an operational project, creating or linking the customer admin user, binding that user to the project, and creating an activation invitation.

Scenario: Approving a pending request provisions new customer admin

• GIVEN an access request is pending
• AND no user exists with the request email
• WHEN a platform operator approves the request
• THEN the system SHALL set the request status to approved
• AND SHALL create a new edge_projects record using request-derived customer data
• AND SHALL create a user with the request email and role admin
• AND SHALL keep the user inactive until activation is completed
• AND SHALL create user_project_access for the new user and project
• AND SHALL create an activation invitation linked to the request, user, and project
• AND SHALL audit the approval and provisioning actions

Scenario: Approving an in-review request provisions access

• GIVEN an access request is in_review
• WHEN a platform operator approves the request
• THEN the system SHALL perform the same provisioning flow as for a pending request

Scenario: Approving a closed request is rejected

• GIVEN an access request is approved or rejected
• WHEN a platform operator approves the request
• THEN the system SHALL reject the action
• AND SHALL NOT create a user, project, access row, invitation, or email

Requirement: Existing User Is Linked, Not Duplicated

The system SHALL link an existing user by email to the newly created project instead of creating a duplicate account.

Scenario: Existing user email is approved again

• GIVEN a user already exists with the access request email
• WHEN a platform operator approves the request
• THEN the system SHALL NOT create a duplicate user
• AND SHALL create a new edge_projects record for the approved request
• AND SHALL create or reactivate user_project_access linking the existing user to the new project
• AND SHALL create a fresh activation invitation only if the existing user cannot currently log in
• AND SHALL audit that an existing user was linked

Scenario: Existing active user is linked

• GIVEN a user already exists with the access request email
• AND the user is active
• WHEN a platform operator approves the request
• THEN the system SHALL link the user to the new project
• AND SHALL send an access-ready notification rather than requiring password activation
• AND SHALL NOT disable or reset the existing user

Requirement: Customer Roles Remain Separated From Provider Roles

The system SHALL create or link customer-side admin users only and SHALL NOT grant provider Console roles to customers.

Scenario: Provisioned customer admin cannot access provider Console

• GIVEN an access request has been approved
• AND the request contact has been provisioned
• WHEN the provisioned user authenticates
• THEN their role SHALL be admin
• AND they SHALL NOT satisfy PlatformClaims
• AND they SHALL NOT access provider routes guarded by platform_admin or platform_operator

Requirement: Activation Invitation Uses Secure Opaque Token

The system SHALL use a high-entropy opaque activation token, store only its hash, and expire it after 7 days.

Scenario: Activation token is created securely

• GIVEN an access request approval is provisioned
• WHEN the system creates the activation invitation
• THEN it SHALL generate a random token with at least 32 bytes of entropy
• AND SHALL store only a SHA-256 hash or stronger digest of the token
• AND SHALL NOT store the raw token in the database
• AND SHALL NOT write the raw token to logs or audit metadata
• AND SHALL set expires_at to 7 days after creation

Scenario: Activation link targets customer Admin app

• GIVEN an activation invitation has been created
• WHEN the system builds the email link
• THEN the link SHALL target INVITATION_BASE_URL with path /activate
• AND the production value SHALL be https://app.omnioil.app/activate
• AND it SHALL include the raw token only as a URL parameter for the email recipient

Requirement: Activation Sets Password And Enables Login

The system SHALL let the customer admin consume a valid activation token once, set their password, and activate the account.

Scenario: Valid activation succeeds

• GIVEN an activation token exists
• AND it is not expired, consumed, or revoked
• WHEN the customer submits the token with a valid password
• THEN the system SHALL hash and store the password
• AND SHALL mark the user active
• AND SHALL mark the invitation consumed
• AND SHALL audit activation
• AND SHALL return a success response suitable for redirecting to login

Scenario: Expired activation is rejected

• GIVEN an activation token exists
• AND expires_at is in the past
• WHEN the customer submits the token with a password
• THEN the system SHALL reject activation
• AND SHALL NOT update the user's password
• AND SHALL NOT mark the user active

Scenario: Consumed activation is rejected

• GIVEN an activation token has already been consumed
• WHEN the customer submits the same token again
• THEN the system SHALL reject activation
• AND SHALL NOT update the user's password

Scenario: Revoked activation is rejected

• GIVEN an activation token has been revoked by a resend
• WHEN the customer submits that token
• THEN the system SHALL reject activation
• AND SHALL NOT update the user's password

Requirement: Approval Email Delivery Is Recoverable

The system SHALL send the activation email after durable provisioning and SHALL keep approval/provisioning state if email delivery fails.

Scenario: Email send succeeds

• GIVEN provisioning has completed
• WHEN SMTP accepts the activation email
• THEN the system SHALL store email_status = 'sent'
• AND SHALL store email_sent_at
• AND SHALL expose the sent status to Console
• AND SHALL audit email delivery

Scenario: Email send fails

• GIVEN provisioning has completed
• WHEN SMTP delivery fails
• THEN the access request SHALL remain approved
• AND the project/user/access/invitation SHALL remain persisted
• AND the system SHALL store email_status = 'failed'
• AND SHALL store a non-secret error summary
• AND SHALL expose resend from Console
• AND SHALL audit email failure

Requirement: Resend Rotates Activation Tokens

The system SHALL let provider operators resend activation invitations and SHALL invalidate previous unconsumed tokens.

Scenario: Resend invalidates previous token

• GIVEN an approved request has an unconsumed activation invitation
• WHEN a platform operator resends the invitation
• THEN the system SHALL set revoked_at on all previous unconsumed invitations for that request
• AND SHALL create a new activation token with 7-day expiration
• AND SHALL send a new activation email
• AND SHALL audit the resend

Scenario: Resend is provider-only

• GIVEN a non-provider user is authenticated
• WHEN they attempt to resend an activation invitation
• THEN the system SHALL reject the action
• AND SHALL NOT rotate tokens or send email

Requirement: Initial Trial Is Created Without Full Billing Automation

The system SHALL create an initial 7-day trial marker for the provisioned project while leaving payment enforcement to a later billing change.

Scenario: Approved project starts trial

• GIVEN an access request is approved and provisioned
• WHEN the project is created
• THEN the system SHALL record that the project starts in a 7-day trial state
• AND SHALL associate the trial with the provisioned project
• AND SHALL NOT require payment before activation

Scenario: Trial expiration does not belong to activation token

• GIVEN an activation token expires after 7 days
• AND the project trial also lasts 7 days initially
• WHEN the activation token expires
• THEN token expiration SHALL only block account activation through that token
• AND project billing/suspension enforcement SHALL be handled by billing lifecycle rules, not by token validation

Requirement: Console Shows Provisioning State

The Console SHALL show operators whether an approved request has a project, customer admin, activation invitation, and email delivery status.

Scenario: Approved request detail shows provisioning status

• GIVEN a request has been approved and provisioned
• WHEN a platform operator views the request detail
• THEN Console SHALL show the provisioned project
• AND SHALL show the customer admin email
• AND SHALL show activation email status
• AND SHALL show invitation expiration when available

Scenario: Failed email shows resend action

• GIVEN an approved request has email_status = 'failed'
• WHEN a platform operator views the request detail
• THEN Console SHALL show the failure state
• AND SHALL enable a resend action

Scenario: Sent email without expiration issue hides urgent resend

• GIVEN an approved request has email_status = 'sent'
• AND its latest invitation is not expired, consumed, or revoked
• WHEN a platform operator views the request detail
• THEN Console SHOULD not present resend as the primary action
• AND MAY expose resend as a secondary recovery action