gatehouse-api/docs/zerotier-network-lifecycle.md

# ZeroTier Network Lifecycle

## Overview

This document covers the full lifecycle of ZeroTier networks in Gatehouse — how networks are created, who can see them, how members request access, and how devices are activated and deactivated.

## Organization Membership Roles

Every user belongs to an organization via an `OrganizationMember` record. Roles determine what a user can see and do:

| Role | Can list networks? | Can see invite-only networks? | Can create/update/delete networks? | Can approve access requests? |
|---|---|---|---|---|
| `owner` | Yes | Yes | Yes | Yes |
| `admin` | Yes | Yes | Yes | Yes |
| `member` | Yes | **No** | No | No |
| `guest` | Yes | **No** | No | No |

Role checks happen via the `OrganizationMember.is_admin()` method, which returns `True` for `owner` and `admin`.

## Network Request Modes

Every `PortalNetwork` has a `request_mode` field that controls how users gain access:

| Mode | Value | Behavior |
|---|---|---|
| `open` | `"open"` | Any org member can join directly without approval |
| `approval_required` | `"approval_required"` | User requests access; a manager must approve |
| `invite_only` | `"invite_only"` | Only managers can assign access; invisible to non-admins |

## Network Listing Visibility

`GET /organizations/{org_id}/networks`

The listing endpoint applies two visibility filters:

1. **Soft-delete filter** — networks with a non-null `deleted_at` are always excluded.
2. **Active filter** — by default, only networks where `is_active = True` are returned. Pass `?include_inactive=true` to include disabled networks.
3. **Invite-only filter** — networks with `request_mode = "invite_only"` are hidden from non-admin users (`member` and `guest` roles). Admins and owners see all networks.

### Filtering logic

The filtering happens in `portal_network_service.list_networks()`:

```python
# Non-admin users cannot see invite-only networks
if user_id is not None:
    membership = OrganizationMember.query.filter(...).first()
    is_admin = membership.is_admin() if membership else False
    if not is_admin:
        q = q.filter(PortalNetwork.request_mode != NetworkRequestMode.INVITE_ONLY)
```

## Network CRUD

| Action | Endpoint | Required Role |
|---|---|---|
| List networks | `GET /organizations/{id}/networks` | Any org member (visibility restricted as above) |
| Create network | `POST /organizations/{id}/networks` | `admin` or `owner` |
| Update network | `PUT /organizations/{id}/networks/{id}` | `admin` or `owner` |
| Delete network | `DELETE /organizations/{id}/networks/{id}` | `admin` or `owner` |

## Device Registration

Before a user can access a network, they must register a device:

`POST /organizations/{org_id}/devices`

A `Device` record ties a ZeroTier node (10-char `node_id`) to a user within an org.

| Field | Purpose |
|---|---|
| `node_id` | ZeroTier 10-char node identifier |
| `device_nickname` | Human-friendly label |
| `hostname` | Optional hostname for identification |

## Network Access Request Lifecycle

The core model is `NetworkAccessRequest` (table: `network_access_requests`). Each row represents one user + one device + one network. See [zerotier-device-membership.md](zerotier-device-membership.md) for the full schema.

### Flow by request mode

**Open networks** — user calls `join_network_for_device()` directly:
1. Creates `NetworkAccessRequest` with `status=APPROVED`, `active=False`
2. Returns the request

**Approval-required networks** — user calls `request_access()`:
1. Creates `NetworkAccessRequest` with `status=PENDING`
2. Admin calls `approve_request()` → sets `status=APPROVED`
3. User calls `activate_membership()` → sets `active=True`, creates `ActivationSession`

**Invite-only networks** — only an admin can call `assign_access()`:
1. Admin creates `NetworkAccessRequest` with `status=APPROVED`, `grant_type=ASSIGNED`
2. User calls `activate_membership()` → sets `active=True`, creates `ActivationSession`

### The `active` flag

| `status` | `active` | Meaning |
|---|---|---|
| `approved` | `false` | Has permission but not currently connected |
| `approved` | `true` | Has permission and device is authorized on the controller |
| `pending` | `false` | Awaiting approval |
| `rejected` / `revoked` / `suspended` | `false` | Access denied or removed |

## Activation and Deactivation

Activation creates an `ActivationSession` with a configurable TTL (default 8 hours). The session is tied to the `active=True` state.

- `activate_membership()` — sets `active=True`, creates session, authorizes on ZeroTier controller
- `deactivate_membership()` — sets `active=False`, ends session, de-authorizes on controller
- Activation sessions expire automatically via the reconciliation worker, which sets `active=False`

### Kill switch

Admins can trigger a kill switch to deactivate all active memberships on an organization or network:

- `POST /organizations/{id}/kill-switch` — deactivates all memberships in the org
- `POST /organizations/{id}/networks/{id}/kill-switch` — deactivates all memberships on a specific network

## Reconciliation Worker

A scheduled job (runs every 2 minutes) performs:

1. **Expired activation cleanup** — finds expired `ActivationSession` records, de-authorizes in ZeroTier, sets `active=False`
2. **Drift detection** — compares portal state against ZeroTier controller state, repairs mismatches

## Key Source Files

| File | Purpose |
|---|---|
| `gatehouse_app/models/zerotier/portal_network.py` | `PortalNetwork` model (network definition + request_mode) |
| `gatehouse_app/models/zerotier/network_access_request.py` | `NetworkAccessRequest` model (per-device membership) |
| `gatehouse_app/models/zerotier/activation_session.py` | `ActivationSession` model (TTL-based sessions) |
| `gatehouse_app/models/zerotier/device.py` | `Device` model |
| `gatehouse_app/models/organization/organization_member.py` | `OrganizationMember` model (roles) |
| `gatehouse_app/services/portal_network_service.py` | Network CRUD + listing logic |
| `gatehouse_app/services/network_access_service.py` | Access request + activation logic |
| `gatehouse_app/services/zerotier_reconciliation_service.py` | Expired session + drift reconciliation |
| `gatehouse_app/api/v1/zerotier.py` | All ZeroTier API endpoints |
| `gatehouse_app/utils/constants.py` | Enums (`OrganizationRole`, `NetworkRequestMode`, etc.) |