gatehouse-api/docs/zerotier-device-membership.md

# ZeroTier Device Membership

## Overview

This document covers the ZeroTier device membership model — how devices are registered, approved, activated, and deactivated on ZeroTier networks. It explains the schema design, the distinction between `active` and `approved`, the user activation flow, and audit coverage.

## Schema Design

The core model is `NetworkAccessRequest` (table: `network_access_requests`). It replaces the legacy two-table approach (`UserNetworkApproval` + `DeviceNetworkMembership`) with a single per-device, per-network row.

### `network_access_requests` table

| Column | Type | Purpose |
|---|---|---|
| `id` | UUID | Primary key |
| `organization_id` | FK -> organizations | Org scope |
| `user_id` | FK -> users | Requesting user |
| `device_id` | FK -> devices | Target device |
| `portal_network_id` | FK -> portal_networks | Target network |
| `granted_by_user_id` | FK -> users (nullable) | Approving manager |
| `grant_type` | enum | `requested` or `assigned` |
| `status` | enum | `pending`, `approved`, `rejected`, `revoked`, `suspended` |
| `active` | boolean | Currently authorized on controller? |
| `justification` | text | User's reason for requesting |
| `join_seen` | boolean | Controller observed the device join |
| `deleted_at` | timestamp (nullable) | Soft delete support |

**Unique constraint:** `(user_id, device_id, portal_network_id, deleted_at)` — ensures exactly one active record per device per network.

### Supporting models

| Model | Table | Purpose |
|---|---|---|
| `Device` | `devices` | A user-registered ZeroTier node (10-char node ID) |
| `PortalNetwork` | `portal_networks` | A managed ZeroTier network (scoped to org) |
| `ActivationSession` | `activation_sessions` | Temporary authorization window (TTL-based) |
| `ZeroTierMembership` | `zerotier_memberships` | Cache of controller-side state |
| `KillSwitchEvent` | `kill_switch_events` | Append-only audit of kill switch actions |

### Entity relationships

```
Device (1) ──> (N) NetworkAccessRequest (N) <── (1) PortalNetwork
                           │
                     (1 or 0)
                           │
                    ActivationSession
                           │
                     (1 or 0)
                           │
                   ZeroTierMembership
```

## `active` vs `approved` — the key distinction

These are orthogonal concepts:

| Concept | Represents | Set by | Persists across sessions? |
|---|---|---|---|
| **`status = approved`** | Administrative permission to use the network | Manager approval | Yes — once approved, stays approved until revoked |
| **`active = True`** | Device is currently authorized on the ZT controller | User activation | No — toggled on/off per session |

A request can be in any of these states:

| `status` | `active` | Meaning |
|---|---|---|
| `approved` | `false` | Manager said yes, but user hasn't activated yet |
| `approved` | `true` | Manager said yes, device is actively connected |
| `pending` | `false` | Awaiting manager decision |
| `rejected` / `revoked` / `suspended` | `false` | Access denied or removed |

The `active` flag is **not** a persistent grant — it's a run-time operational state tied to an `ActivationSession` with a finite TTL (default 8 hours).

## User activation flow — "turning on" ZeroTier

```
User                         API                           Service                    ZT Controller
 │                            │                              │                            │
 │  POST /orgs/<id>/approvals │                              │                            │
 ├───────────────────────────>│ request_access()             │                            │
 │                            ├──> creates NetworkAccessRequest (status=PENDING)          │
 │                            ├──> _ensure_zerotier_member()                              │
 │                            │    └──> provisions member (de-authorized) ────────────────>│
 │                            │                              │                            │
 │  <── 201 { status: pending }                              │                            │
 │                            │                              │                            │
 │  [Admin approves]          │                              │                            │
 │  POST /orgs/<id>/approvals │                              │                            │
 │  /<id>/approve             │                              │                            │
 ├───────────────────────────>│ approve_request()            │                            │
 │                            ├──> sets status=APPROVED      │                            │
 │  <── 200 { status: approved }                             │                            │
 │                            │                              │                            │
 │  POST /orgs/<id>/memberships/<id>/activate                │                            │
 │  ─────────────────────────>│ activate_request()           │                            │
 │    "turn on ZeroTier"      ├──> creates ActivationSession (TTL=8h)                    │
 │                            ├──> sets request.active=True  │                            │
 │                            ├──> _authorize_in_zerotier()  │                            │
 │                            │    └──> authorizes member ───────────────────────────────>│
 │                            │                              │                            │
 │  <── 200 { active: true, session: {...} }                 │                            │
```

### Endpoints

| Method | Path | Action |
|---|---|---|
| `POST` | `/organizations/<id>/devices` | Register a device (prerequisite) |
| `POST` | `/organizations/<id>/approvals` | Request network access |
| `POST` | `/organizations/<id>/approvals/<id>/approve` | Admin approves |
| `POST` | `/organizations/<id>/memberships/<id>/activate` | **Turn on ZeroTier** |
| `POST` | `/organizations/<id>/memberships/activate-all` | Bulk-activate all approved |
| `POST` | `/organizations/<id>/memberships/<id>/deactivate` | Turn off ZeroTier |
| `POST` | `/organizations/<id>/devices/<id>/join-network/<id>` | Direct join (open networks) |
| `POST` | `/organizations/<id>/kill-switch` | Emergency deactivation |

## Session expiry and audit

When the `ActivationSession` TTL expires, the reconciliation worker handles it:

```
Reconciliation worker (runs every 2 min)
    │
    ├── reconcile_expired_activations()
    │    └── for each expired ActivationSession:
    │         ├── _deauthorize_in_zerotier() ───> ZT controller de-authorizes member
    │         ├── sets request.active = False
    │         └── logs audit event
    │
    └── reconcile_all()
         └── for each network:
              ├── sync ZeroTierMembership cache
              └── detect/repair drift (portal vs controller state mismatch)
```

Every authorization state change is audited:

| Event | When |
|---|---|
| `zt.approval.requested` | User requests access |
| `zt.approval.granted` | Manager approves/assigns |
| `zt.approval.rejected` | Manager rejects |
| `zt.approval.revoked` | Manager revokes |
| `zt.membership.activated` | User activates (session created) |
| `zt.membership.deactivated` | User deactivates (session ended) |
| `zt.member.authorized` | ZT controller authorize call succeeds |
| `zt.member.deauthorized` | ZT controller de-authorize call succeeds |
| `zt.activation.expired` | Session expired by reconciliation worker |
| `zt.kill_switch.activated` | Admin triggers kill switch |

All audit entries are stored in the `audit_logs` table with `organization_id`, `user_id`, `resource_type`, `resource_id`, `ip_address`, and `extra_data` (JSON) for full traceability.

## Key source files

| File | Purpose |
|---|---|
| `gatehouse_app/models/zerotier/network_access_request.py` | `NetworkAccessRequest` model |
| `gatehouse_app/models/zerotier/activation_session.py` | `ActivationSession` model |
| `gatehouse_app/models/zerotier/zerotier_membership.py` | `ZeroTierMembership` model |
| `gatehouse_app/services/network_access_service.py` | Core business logic |
| `gatehouse_app/services/zerotier_reconciliation_service.py` | Reconciliation worker logic |
| `gatehouse_app/api/v1/zerotier.py` | API endpoints |
| `gatehouse_app/utils/constants.py` | Audit action enums |
| `gatehouse_app/jobs/zerotier_reconciliation_job.py` | Scheduled job entry point |
| `migrations/versions/merge_approval_membership_tables.py` | Schema migration |