Files

henryor cdf684daff docs(sdd): define provisionamiento de solicitudes aprobadas

2026-05-09 07:52:27 -05:00

14 KiB

Raw Blame History

Design: Provision Approved Access Requests

Technical Approach

Turn approval into a durable provisioning transaction followed by a recoverable email side effect. The backend owns all state transitions: approve request, create edge_projects, create/link customer admin, create user_project_access, create subscriptions(status='trial'), create activation invitation hash, then attempt SMTP delivery. Console reflects provisioning/email state; Admin owns /activate because customers must never land in provider Console.

Current State

access_requests has review fields but no provisioning linkage.
approve_access_request only updates status='approved' and writes audit.
Customer identity/access currently uses users, roles, edge_projects, and user_project_access.
Customer admin role is admin; provider Console roles are platform_admin and platform_operator.
frontend-admin routes include /login and /setup, but no /activate.
frontend-admin apiClient bypasses /auth/login, /auth/register, /auth/request-access, /auth/refresh, and /auth/setup; activation endpoints must be added to the bypass list.
subscriptions already supports status='trial' and trial_ends_at, but get_or_create_subscription() currently auto-creates missing subscriptions as active. Approval must create a trial subscription before billing usage reads it.
notifier.rs already sends SMTP email for alarms via lettre and SMTP_* env vars.

Architecture Decisions

ID	Decision	Rationale	Alternative Rejected
ADR-1	Approval auto-creates an `edge_projects` row.	User chose automatic provisioning; current schema has no tenant table.	Approval modal requiring operator-selected project.
ADR-2	Request contact becomes/links to customer role `admin`.	Customer must enter `frontend-admin`; provider roles are internal only.	Creating `platform_admin` from customer request.
ADR-3	Existing email links existing user to the new project.	Prevent duplicate accounts and preserve active users.	Blocking approval on duplicate email.
ADR-4	New users are inserted inactive until activation.	Avoid temporary passwords and email credential leaks.	Sending generated password by email.
ADR-5	Activation token is opaque and hash-only at rest.	Simple revocation and no JWT leakage.	JWT invitation token.
ADR-6	Activation lives at `app.omnioil.app/activate`.	Customer app owns customer account activation.	Console or landing activation.
ADR-7	SMTP failure does not rollback provisioning.	Approval/provisioning is durable; email is recoverable.	Transaction rollback on SMTP failure.
ADR-8	Resend revokes unconsumed prior tokens.	Prevent multiple valid links in the wild.	Multiple parallel valid tokens.
ADR-9	Approved projects start with 7-day trial subscription.	Existing billing table supports trial; payment enforcement is later.	Implement full billing/payments now.

Data Model

Migration

Add provisioning linkage to access_requests:

ALTER TABLE access_requests
    ADD COLUMN provisioned_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
    ADD COLUMN provisioned_project_id UUID REFERENCES edge_projects(id) ON DELETE SET NULL,
    ADD COLUMN provisioned_at TIMESTAMPTZ;

Create activation invitations:

CREATE TABLE access_request_invitations (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    access_request_id UUID NOT NULL REFERENCES access_requests(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    project_id UUID REFERENCES edge_projects(id) ON DELETE SET NULL,
    token_hash TEXT NOT NULL UNIQUE,
    email_status VARCHAR(30) NOT NULL DEFAULT 'pending'
        CHECK (email_status IN ('pending', 'sent', 'failed')),
    email_sent_at TIMESTAMPTZ,
    email_error TEXT,
    expires_at TIMESTAMPTZ NOT NULL,
    consumed_at TIMESTAMPTZ,
    revoked_at TIMESTAMPTZ,
    revoked_reason TEXT,
    created_by UUID REFERENCES users(id) ON DELETE SET NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_access_request_invitations_request_latest
    ON access_request_invitations(access_request_id, created_at DESC);

CREATE INDEX idx_access_request_invitations_token_hash
    ON access_request_invitations(token_hash)
    WHERE consumed_at IS NULL AND revoked_at IS NULL;

No activation_status column is added initially. Pending activation is represented by users.is_active = false plus an unconsumed invitation. This keeps schema churn low.

Project Defaults

The request form does not collect all edge_projects required fields. Approval uses deterministic defaults:

`edge_projects` field	Source
`name`	Sanitized `access_requests.company`; if conflict, append short request id suffix.
`client`	`access_requests.company`
`operator_name`	`access_requests.company`
`contract_number`	`PENDING-{access_request.id short}`
`description`	`message` or `Access request from {full_name}`
`metadata`	JSON with `source='access_request'`, request id, nit, contact, phone, position.

The project remains operationally minimal. Assets/devices/variables are out of scope.

Trial Subscription

Inside the approval transaction, insert:

INSERT INTO subscriptions (project_id, tier, status, trial_ends_at, notes)
VALUES ($project_id, 'starter', 'trial', NOW() + INTERVAL '7 days', 'Created from approved access request')
ON CONFLICT (project_id) DO NOTHING;

Because get_or_create_subscription() currently creates active subscriptions by default, approval must create the trial row before any billing read path touches the project.

Token Design

Generate 32 random bytes with a cryptographically secure RNG.
Encode raw token as base64url without padding for the email link.
Store hex(SHA-256(raw_token)) or equivalent stable SHA-256 digest in token_hash.
Never log the raw token.
Never return raw token from API except internally to the email construction path.
expires_at = now + 7 days.
consumed_at marks successful activation.
revoked_at/revoked_reason marks resend invalidation.

Activation validation checks token hash, then rejects if expired, consumed, revoked, request not approved, or user/project no longer exists.

Backend Design

New Modules

handlers/invitations.rs: public activation endpoint and provider resend endpoint, unless keeping access-request resend in handlers/access_requests.rs is simpler.
mailer.rs: generic SMTP helper with send_email(to, subject, body) reused by alarm notifier later or wrapped for approval emails.
access_request_provisioning.rs or private functions in access_requests.rs: provisioning transaction helpers.

Endpoint Changes

Method	Path	Auth	Purpose
`POST`	`/api/platform/access-requests/{id}/approve`	`PlatformClaims`	Approve, provision, create trial, create/send activation.
`POST`	`/api/platform/access-requests/{id}/invitation/resend`	`PlatformClaims`	Revoke previous unconsumed tokens, create/send new activation token.
`POST`	`/api/auth/invitations/activate`	Public	Validate token, set password, activate user.
`GET`	`/api/auth/invitations/validate?token=...`	Public	Optional but recommended for frontend preflight display.

Approval Transaction

BEGIN
  lock access_requests row FOR UPDATE
  require status IN ('pending', 'in_review')
  create edge_projects from request data
  find existing user by lower(email)
  if user exists:
    use existing user id
    do not change password or is_active
  else:
    create user role=admin, is_active=false, password_hash=random unusable hash
  insert/reactivate user_project_access user/project project_role='owner'
  insert subscriptions project_id status='trial' trial_ends_at=now+7d
  update access_requests status='approved', provisioned_user_id, provisioned_project_id, reviewed_by, reviewed_at, provisioned_at
  revoke any older unconsumed invitations for request
  create invitation row with token_hash, expires_at=now+7d
  audit approval/provisioning records
COMMIT
send email if user is inactive/pending activation
or send access-ready notification if existing active user
update latest invitation email_status sent/failed
audit email sent/failed
return approved row with provisioning/invitation summary

Use a generated unusable password hash for inactive users because users.password_hash is currently NOT NULL. Design implementation should prefer a random high-entropy value hashed with the existing Argon2 helper, not a fixed sentinel.

Existing User Handling

Existing active user: link project; send “access ready” email; do not create activation token requirement for login. An invitation row may still be created for email tracking, but activation should not be required.
Existing inactive user: link project; create activation invitation so they can set password/activate.
Existing platform role user with same email: block approval with a conflict unless design explicitly supports dual customer/provider identity. Default: block and surface operator error. This avoids accidentally granting customer access to provider identity.

Resend Flow

BEGIN
  lock request row
  require request status='approved'
  require provisioned_user_id exists
  revoke unconsumed invitations for request
  create new invitation with token_hash expires_at=now+7d
  audit resend
COMMIT
send activation/access email
update email_status sent/failed

If the linked user is already active, resend sends access-ready notification rather than password activation.

Activation Flow

POST /api/auth/invitations/activate
body: { token, password }

hash token
BEGIN
  select invitation + user + request FOR UPDATE
  require not expired, not consumed, not revoked
  require request.status='approved'
  hash submitted password
  update users set password_hash, is_active=true, updated_at=NOW()
  update invitation consumed_at=NOW()
  audit activation
COMMIT
return { status: 'activated' }

Password validation should reuse existing policy, but raise the floor to at least 8 characters if compatible with current frontend schemas. Do not auto-login after activation in this change; redirect to /login.

Frontend Design

Console

Extend AccessRequest type with provisioning fields:
- provisioned_user_id
- provisioned_project_id
- provisioned_at
- invitation_email_status
- invitation_email_sent_at
- invitation_expires_at
- invitation_consumed_at
Detail panel shows project/admin/invitation status after approval.
Approve button can remain single-click because product decision is automatic project creation.
If approval fails due project name conflict edge case not handled by suffix, show backend error toast.
Show resend as primary only when email failed or invitation expired/unconsumed; secondary otherwise.

Admin Activation

Add route /activate before protected app routes.
Add features/auth/pages/ActivatePage.tsx.
Add activateInvitationApi and optional validateInvitationApi.
Add /auth/invitations to AUTH_BYPASS_ENDPOINTS.
Page states:
- loading token validation
- invalid/expired/revoked token
- password form
- success with link to /login
Do not store activation token in global auth state.

Email Design

Activation Email

Subject: Tu acceso a OmniOil fue aprobado

Body includes:

Company name.
Activation link.
Expiration: 7 days.
Security note: link is single-use and no password was sent.
Support contact.

Existing Active User Email

Subject: Nuevo proyecto habilitado en OmniOil