complycore/frontend/authentication.md

# 🔐 ComplyCore Authentication & Authorization Design

**Component:** Identity & Access Management (IAM)  
**Version:** v1.0  
**Last Updated:** 2024-07-11  
**Owner:** Kell Engineering

---

## ✅ Overview

ComplyCore uses a **multi-tenant, RBAC-enforced identity system** built on PostgreSQL with Supabase Auth. All user and system access is governed by:

- **Tenant isolation** via Row-Level Security (RLS)
- **Role-Based Access Control (RBAC)** via ENUM roles
- **Session-scoped variables** (`set_config()`) instead of legacy JWT hooks
- **Support for both human users and non-person entities (NPEs)**
- **Audit logging** for access, evaluation, and data modification events

---

## 🧱 Database Entity Model

```mermaid
erDiagram
    tenants ||--o{ users : has
    tenants ||--o{ api_clients : owns
    tenants ||--o{ evaluations : owns
    users ||--o{ evaluations : creates
    users ||--o{ auth_audit_log : actor
    api_clients ||--o{ auth_audit_log : actor

    tenants {
        UUID id PK
        TEXT name
        TEXT cage_code
        TEXT sam_uid
    }

    users {
        UUID id PK
        UUID tenant_id FK
        TEXT first_name
        TEXT last_name
        TEXT email
        user_role role
    }

    api_clients {
        UUID id PK
        UUID tenant_id FK
        TEXT client_id
        TEXT client_secret
        api_scope[] scopes
    }

    evaluations {
        UUID id PK
        UUID tenant_id FK
        TEXT control_id
        TEXT status
    }

    auth_audit_log {
        UUID id PK
        UUID actor_id
        UUID tenant_id FK
        TEXT action
        TEXT result
    }
```

---

## 👤 User Roles

```mermaid
flowchart LR
  A[client_user] -->|RLS: Own tenant only| EvalTable
  B[client_admin] -->|RLS: Own tenant only + mgmt| EvalTable
  C[reviewer] -->|RLS: Read all tenants| EvalTable
  D[superadmin] -->|RLS: Full control| EvalTable & UserTable
```

| Role         | Description                     | Access Scope         |
|--------------|----------------------------------|----------------------|
| `client_user`| End user                         | Own tenant only      |
| `client_admin`| Tenant admin                    | Own tenant (plus user mgmt) |
| `reviewer`   | Internal auditor or compliance   | All tenants (read-only) |
| `superadmin` | Platform operator                | Full access to all data |

---

## 🔐 RLS Policies

| Table            | Role(s)              | Access Type     | Rule Description                          |
|------------------|----------------------|-----------------|--------------------------------------------|
| `users`          | All                  | Self only       | `id = auth.uid()`                          |
| `evaluations`    | `client_*`           | Tenant-bound    | Match tenant via `set_config()`            |
| `evaluations`    | `reviewer`           | Global read     | Unrestricted SELECT                        |
| `evaluations`    | `superadmin`         | Full access     | Unrestricted ALL w/ check                  |
| `api_clients`    | All                  | Own tenant only | `enabled=true` AND tenant match            |
| `auth_audit_log` | All                  | Tenant-bound    | Match tenant                               |

---

## 🔑 Session Variables (No JWT Custom Claims)

Instead of deprecated JWT claim injection, ComplyCore uses:

```sql
SELECT set_config('request.jwt.claim.role', user.role, true);
SELECT set_config('request.jwt.claim.tenant_id', user.tenant_id::text, true);
```

This enables per-session RLS enforcement and simplifies system-wide access control.

---

## 🛡️ NPE: Non-Person Entities (API Clients)

**Table:** `api_clients`

| Field         | Purpose                         |
|---------------|----------------------------------|
| `client_id`   | Public API token ID              |
| `client_secret` | Auth key (hashed)              |
| `tenant_id`   | Enforces scope per client        |
| `scopes[]`    | Least-privilege operations       |
| `enabled`     | Soft-delete / disable mechanism  |

**Scopes Enum:**
- `upload`
- `evaluate`
- `read_reports`
- `manage_projects`

> RLS prevents disabled clients or cross-tenant access.

---

## 📝 Audit Logging

**Table:** `auth_audit_log`

| Field         | Type       | Description                                  |
|---------------|------------|----------------------------------------------|
| `actor_id`    | UUID       | User or service account                      |
| `tenant_id`   | UUID       | Organization context                         |
| `action`      | TEXT       | Description (e.g., `login_success`)          |
| `target_table`| TEXT       | Optional: table affected                     |
| `result`      | TEXT       | `success` or `fail`                          |
| `timestamp`   | TIMESTAMP  | System-generated UTC timestamp               |

This log supports:
- Login tracking
- API usage validation
- Internal audit trail for CMMC/DFARS controls

---

## 🧠 CMMC Practice Coverage

| Practice             | Control Area          | Implementation                        |
|----------------------|-----------------------|----------------------------------------|
| AC.1.001             | Access Control        | Unique accounts (auth.users + users)  |
| AC.1.002             | Access Enforcement    | RBAC and RLS                          |
| AC.1.003             | Least Privilege       | Role + tenant-scoped access           |
| AU.2.042             | Audit Logs            | `auth_audit_log`                      |
| IA.2.078             | MFA Capable           | `mfa_enabled` flag (enforced by UI)   |
| SC.3.177             | NPE Separation        | `api_clients` with isolated scopes    |

---

## 📎 Appendices

### 🔧 Initial Setup Function

```sql
CREATE OR REPLACE FUNCTION set_claim_context()
RETURNS void
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  v_role TEXT;
  v_tenant UUID;
BEGIN
  SELECT role, tenant_id INTO v_role, v_tenant
  FROM public.users
  WHERE id = auth.uid();

  PERFORM set_config('request.jwt.claim.role', v_role, true);
  PERFORM set_config('request.jwt.claim.tenant_id', v_tenant::text, true);
END;
$$;
```

Call this at the start of every request/session to enforce scoped access.

---

## ✅ Status

| Component          | Status        | Notes                                 |
|--------------------|---------------|----------------------------------------|
| Supabase Auth      | ✅ Integrated  | Used for identity backing              |
| Postgres Tables    | ✅ Complete    | tenants, users, api_clients, audits    |
| RLS Policies       | ✅ Enforced    | All core tables                        |
| Session Claims     | ✅ Supported   | Via `set_config()`                     |
| MFA Support        | 🟡 Flagged     | Client-side UI pending                 |

---

**Maintained by:** Kell Engineering  
**Contact:** mtkell@kellengineering.com  
**Document ID:** `AUTH-DOC-001`