TenantAtlas/specs/276-support-access-governance/data-model.md

# Data Model: Enterprise Access Boundary & Support Access Governance v1

**Date**: 2026-05-05  
**Branch**: `276-support-access-governance`

## Overview

This slice adds one new workspace-owned truth: support-access grant history. Existing `audit_logs`, `BreakGlassSession`, and workspace settings remain in place. The new grant history drives support-access state, approval, expiry, and recovery gating.

## Persisted Truth

### 1. Support Access Grant

**Persistence**: New `support_access_grants` table  
**Ownership**: Workspace-owned  
**Scope**: Many historical rows per workspace, with dedupe preventing overlapping active or pending grants for the same workspace, platform actor, and scope.

| Field | Type | Nullable | Validation | Notes |
|-------|------|----------|------------|-------|
| `id` | bigint | no | primary key | Internal record id |
| `workspace_id` | bigint | no | foreign key | Primary customer scope anchor |
| `requested_by_platform_user_id` | bigint | no | foreign key | Platform actor who requested support access |
| `approved_by_user_id` | bigint | yes | foreign key | Workspace owner who approved the risky recovery path |
| `scope` | string | no | one of `audit_view`, `workspace_recovery` | Bounded v1 support scope catalog |
| `status` | string | no | one of `requested`, `active`, `denied`, `expired`, `ended` | Lifecycle state |
| `approval_mode` | string | no | one of `auto`, `owner_required`, `ownerless_waiver` | Explains why approval did or did not occur |
| `reason` | text | no | trimmed, min length 5 | Operator-supplied reason |
| `waiver_reason` | text | yes | required when `approval_mode=ownerless_waiver` | Explicit ownerless recovery waiver context |
| `ttl_minutes` | integer | no | positive integer, bounded max from config or policy | Requested active duration |
| `requested_at` | datetime | no | set on creation | Request timestamp |
| `approved_at` | datetime | yes | required when owner approval occurs | Approval timestamp |
| `starts_at` | datetime | yes | required when grant becomes active | Active timestamp |
| `expires_at` | datetime | yes | required when grant becomes active | Grant expiry |
| `ended_at` | datetime | yes | set when support access is ended manually | Manual end timestamp |
| `denied_at` | datetime | yes | set when owner denies a request | Denial timestamp |
| `created_at` | datetime | no | standard timestamp | Row creation |
| `updated_at` | datetime | no | standard timestamp | Row update |

**Write rules**:

- `workspace_id`, `requested_by_platform_user_id`, and `scope` are immutable once created.
- `requested` is the initial state for every new row.
- `audit_view` may move directly from `requested` to `active` with `approval_mode=auto`.
- `workspace_recovery` moves from `requested` to `active` only after owner approval or ownerless waiver.
- Active grants may transition to `expired` or `ended`. Requested grants may transition to `denied`.

**Dedupe rule**:

- At most one non-terminal row may exist for the same `workspace_id`, `requested_by_platform_user_id`, and `scope` while `status` is `requested` or `active`.

## Existing Persisted Truth Reused

### 2. Audit Log

**Persistence**: Existing `audit_logs` table  
**Owner**: Existing audit infrastructure

This slice reuses `audit_logs` for customer-visible history and export. Support-access events become a first-class audit action family.

### 3. Break-Glass Session

**Persistence**: Existing session-backed `BreakGlassSession`  
**Owner**: Existing system-plane emergency control

Break-glass remains session-backed and system-wide. It is not replaced by support-access grant history, but recovery gating now depends on both.

## Code-Owned Truth

### 4. Support Scope Catalog

**Persistence**: none, code-owned

| Scope | Label | Risk class | Requires owner approval? | Allows mutation? |
|-------|-------|------------|--------------------------|------------------|
| `audit_view` | Audit trail review | low | no | no |
| `workspace_recovery` | Workspace recovery | high | yes when owners exist | yes |

### 5. Approval Mode Catalog

**Persistence**: none, code-owned

| Mode | Meaning |
|------|---------|
| `auto` | Low-risk support access activated immediately |
| `owner_required` | Workspace owner must approve before activation |
| `ownerless_waiver` | No owner existed, so recovery required explicit break-glass-backed waiver |

## Derived Truth

### 6. Active Support Access Summary

**Persistence**: none, derived at runtime  
**Owner**: `SupportAccessGrantResolver`

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `workspace_id` | int | yes | Current workspace |
| `active_grant_id` | int | no | Active grant when present |
| `pending_grant_id` | int | no | Pending risky grant when present |
| `scope` | string | no | Current or pending scope |
| `scope_label` | string | no | Operator-facing scope label |
| `status` | string | yes | Current support-access state summary |
| `reason` | string | no | Active or pending reason |
| `requester_label` | string | no | Platform requester display label |
| `approval_mode` | string | no | Explains activation path |
| `approver_label` | string | no | Owner approver display label |
| `expires_at` | datetime | no | Current expiry |
| `needs_break_glass` | bool | yes | True only for `workspace_recovery` |

### 7. Support Access Export Filter

**Persistence**: none, derived at runtime  
**Owner**: existing admin audit-log page

The filter preset isolates audit actions that belong to the support-access family and remain in the active workspace scope only.

## State Transitions

| From | To | Trigger | Consequence |
|------|----|---------|-------------|
| none | `requested` | platform operator requests support access | grant becomes pending |
| `requested` | `active` | auto activation or explicit approval | support access becomes active until expiry or manual end |
| `requested` | `denied` | workspace owner denies recovery request | no active support access is granted |
| `active` | `expired` | current time passes `expires_at` | recovery and audit-view access end automatically |
| `active` | `ended` | platform operator ends support access | support access ends early |

## Boundaries Explicitly Preserved

- No tenant member impersonation, no direct customer session bridge, and no unrestricted admin browsing are introduced.
- `workspace_recovery` does not bypass break-glass and `audit_view` does not mutate customer state.
- Support-access history remains workspace-scoped even when audit rows include tenant references.