# Nexus Policy Architecture

> Build 86 — Platform Foundation POC  
> Last updated: 2026-06-05

## Purpose

Define how Nexus applies policies across platform lock, device trust, organization rules, and future Group Policy (GPO) integration. This document covers the **foundation schema and evaluation flow** — not full GPO enforcement.

## Policy layers

```mermaid
flowchart TB
    subgraph L1["Layer 1 — Platform"]
        PL[Platform Lock POC]
        PS[Safe POC mode gate]
    end

    subgraph L2["Layer 2 — Trust"]
        DT[Device Trust]
        ER[Enrollment Approval]
    end

    subgraph L3["Layer 3 — Organization"]
        OP[Org-scoped policies]
        OU[Org user/device rules]
    end

    subgraph L4["Layer 4 — Future GPO"]
        GPO[Windows GPO bridge]
        MDM[MDM / Intune sync]
    end

    L1 --> L2 --> L3 --> L4
```

| Layer | Scope | POC status | Example |
|-------|-------|------------|---------|
| **Platform lock** | All devices in safe-POC | Implemented locally | `--safe-poc`, `LockdownService` |
| **Device trust** | Per device | DB + local JSON | Trusted / Pending / Blocked |
| **Enrollment** | Registration | API MVP | Admin approve endpoint |
| **Organization** | Per org | Schema ready | `Policies.OrganizationId` |
| **GPO** | Windows + Nexus | Not started | Future `PolicyEngine` |

## Data model

**Table:** `Policies` (EF `PolicyEntity`)

| Field | Purpose |
|-------|---------|
| `Id` | Stable policy key (e.g. `policy-device-trust`) |
| `Name` | Display name |
| `Scope` | `platform`, `device`, `enrollment`, `org` |
| `IsEnabled` | Soft toggle |
| `Summary` | Human-readable description |
| `RulesJson` | Machine-readable rules (JSON) |
| `OrganizationId` | `null` = platform-wide; else org-specific |

**Seeded POC policies:**

1. `policy-platform-lock` — `{ "requireSafePoc": true }`
2. `policy-device-trust` — `{ "requiredTrustStatus": "Trusted" }`
3. `policy-enrollment-approval` — `{ "requireAdminApproval": true }`

## Evaluation flow

```mermaid
sequenceDiagram
    participant Shell as NexusShell
    participant API as Identity API
    participant PS as PolicyService
    participant DB as Database

    Shell->>API: POST /api/enrollment/register
    API->>DB: Create EnrollmentRequest (Pending)
    API->>DB: Device + Trust (Pending)

    Shell->>API: GET /api/enrollment/status/{deviceId}
    API->>PS: EvaluateForDeviceAsync()
    PS->>DB: Load enabled policies
    PS-->>API: PolicyEvaluationResult
    API-->>Shell: status + policyAllowed

    Note over API: Admin POC
    API->>DB: POST /api/enrollment/approve
    DB-->>API: Trust = Trusted, Status = Enrolled
```

### PolicyService (foundation)

**Location:** `NexusIdentity.Api/Services/PolicyService.cs`

| Method | Behavior |
|--------|----------|
| `GetPoliciesAsync(orgId?)` | Returns enabled platform + org policies |
| `EvaluateForDeviceAsync(deviceId, orgId, trustStatus)` | Runs rule checks, returns `OverallAllowed` |

**POC rule evaluation:**

- **Device trust:** Compares `trustStatus` to `requiredTrustStatus` in JSON rules.
- **Enrollment approval:** Informational at evaluation time; enforced at registration.
- **Parse errors:** Fail-open (allow) with message — POC safety default.

### Local vs remote evaluation

| Context | Evaluator | Storage |
|---------|-----------|---------|
| Shell lockdown | `LockdownService` | `lockdown.json` |
| Local trust | `NexusDeviceTrustService` | `%AppData%\Nexus\identity\trust.json` |
| Remote trust | `PolicyService` via API | PostgreSQL/SQLite |
| Control Center view | Dashboard aggregates trust counts | API read-only |

Local and remote can **diverge** in POC until sync is implemented post-approval.

## API surface

| Endpoint | Policy relevance |
|----------|------------------|
| `GET /api/control-center/policies?organizationId=` | List applicable policies |
| `GET /api/enrollment/status/{deviceId}` | Includes `policyAllowed`, `policyMessage` |
| `GET /api/control-center/dashboard` | Policy summaries + trust counts |

## POC vs production

| Area | POC (build 86) | Production |
|------|----------------|------------|
| Policy storage | EF seed rows | Admin UI + versioning |
| Evaluation | Inline `PolicyService` | Dedicated policy engine + cache |
| Enforcement | Status flags only | Block shell features, network, apps |
| GPO | Not implemented | Export/import, WMI bridge |
| Auth on approve | Open endpoint | Admin JWT + audit log |
| Org policies | Schema only | CRUD + inheritance |
| Real-time push | Poll on status | WebSocket / agent command channel |

## Extension points

1. **`RulesJson` schema** — evolve to JSON Schema validated rules (version field per policy).
2. **Policy bundles** — assign multiple policies per org/device group.
3. **Agent enforcement** — agent receives policy snapshot on heartbeat ack.
4. **Shell gating** — `NexusPlatformLockService` consults remote evaluation before unlock.
5. **GPO layer** — map Nexus policies to registry-backed Windows policies (separate sprint).

## Related docs

- [NEXUS_DEPLOYMENT_ARCHITECTURE.md](./NEXUS_DEPLOYMENT_ARCHITECTURE.md)
- [../evidence/nexus-platform-foundation/SUMMARY.md](../evidence/nexus-platform-foundation/SUMMARY.md)
