# Super Admin Management Runbook

Super admins have elevated privileges that bypass parts of the permission pipeline. This runbook covers grant, revoke, and audit procedures.

---

## Super Admin Levels

| Level       | Pipeline Behavior                                                                                                               | Use Case                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `full`      | Skips steps 10-13 (direct grants, roles, resource scope, conditions). Step 14 (data classification) still applies when enabled. | Engineering, senior CS staff               |
| `read_only` | Same as full in Phase 1. Phase 2: RPC handler enforces read-only.                                                               | Auditors, compliance officers              |
| `support`   | Same as full in Phase 1. Phase 2: RPC handler enforces support scope.                                                           | Customer support                           |
| `product`   | Skips steps 10-13 BUT only for test tenants. Non-test tenants → denied at step 9.                                               | Product managers, QA                       |
| `analytics` | Always denied at step 9. Must use aggregation layer.                                                                            | Data analysts needing cross-tenant metrics |

**Key invariant:** Deny overrides (step 8) beat super admin. If a super admin has a deny override for a specific permission, they are DENIED regardless of their level.

---

## Granting Super Admin Access

### Prerequisites

- You must be a `full` super admin yourself
- The target user must exist (but does NOT need to be a TenantUser — super admin is cross-tenant)

### Procedure

```
GrantSuperAdmin RPC
├── userId: "<target user ID>"
├── level: FULL | READ_ONLY | SUPPORT | PRODUCT | ANALYTICS
└── grantedBy: "<your user ID>"
```

**Validation:**

- `userId` must be non-empty
- `level` must not be UNSPECIFIED
- User must not already have an active (non-revoked) grant → `AlreadyExists`

**Side effects:**

- Super admin cache invalidated: `cache.invalidateSuperAdminStatus(userId)`
- The new grant takes effect within 5 minutes (super admin cache TTL) or immediately if uncached

### Upgrading a Level

To change a super admin's level (e.g., `read_only` → `full`):

1. `RevokeSuperAdmin` the existing grant
2. `GrantSuperAdmin` with the new level

There's no `UpdateSuperAdmin` RPC — the revoke+grant pattern ensures an audit trail for every level change.

---

## Revoking Super Admin Access

### Procedure

```
RevokeSuperAdmin RPC
├── userId: "<target user ID>"
└── revokedBy: "<your user ID>"
```

**What happens:**

- Sets `revokedAt` timestamp on the active grant (soft delete — the row persists for audit)
- Sets `revokedBy` to the revoking admin's ID
- Invalidates super admin cache (synchronous)
- The user loses elevated access on the next permission check

**If no active grant exists:** Returns `NotFound`.

---

## Listing Super Admins

```
ListSuperAdmins RPC
├── page: { pageSize: 50 }
```

Returns only active (non-revoked) grants. Supports cursor-based pagination.

---

## Auditing Super Admin Activity

Super admin actions are logged via the audit writer with `isSuperAdmin: true` in the metadata. To find all super admin permission checks:

```sql
SELECT * FROM audit_logs
WHERE is_super_admin = true
ORDER BY created_at DESC
LIMIT 100;
```

To find grant/revoke history for a user:

```sql
SELECT id, level, granted_by, granted_at, revoked_at, revoked_by
FROM super_admins
WHERE user_id = '<userId>'
ORDER BY granted_at DESC;
```

---

## Troubleshooting

### User Still Has Access After Revocation

**Cause:** Super admin status cached for up to 5 minutes.

**Fix:** Wait for TTL expiry, or manually clear:

```bash
redis-cli DEL "perm:superadmin:<userId>"
```

### Duplicate Active Grants

**Should not happen** — the `GrantSuperAdmin` handler checks for existing active grants.

**If it occurs:**

```sql
-- Find duplicates
SELECT * FROM super_admins
WHERE user_id = '<userId>' AND revoked_at IS NULL;

-- The resolver uses ORDER BY granted_at DESC, so the most recent grant wins.
-- Revoke the older ones manually if needed.
```

### Product Super Admin Denied on Test Tenant

**Check:** Is `tenant.isTest` actually `true`?

```sql
SELECT id, name, is_test FROM tenants WHERE id = '<tenantId>';
```

If the tenant was not created as a test tenant, product-level super admins cannot access it by design.