# How Enterprise Desktop Policies Are Enforced in OpenWork: A Server-Driven Governance Architecture

> Discover how OpenWork enforces enterprise desktop policies using a server-driven governance architecture. Learn about Zod schema validation and runtime action blocking.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: architecture
- Published: 2026-07-31

---

**OpenWork enforces enterprise desktop policies through a centralized, server-driven mechanism that validates definitions with Zod schemas, merges multiple policy sources into a deterministic effective configuration, and blocks unauthorized actions at runtime in the Electron desktop client.**

Enterprise desktop policies in the [different-ai/openwork](https://github.com/different-ai/openwork) repository provide organizations with granular control over desktop functionality, ensuring compliance with security and governance requirements. The system implements a layered enforcement pipeline that combines cloud-based policy management in the Den service with client-side runtime checks. Administrators define restrictions centrally, while the desktop application respects those boundaries through strict schema validation and algorithmic policy merging.

## Policy Catalog and Centralized Definitions

All possible enterprise desktop policies are declared in a single source of truth. The constant `desktopPolicyDefinitions` in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) serves as the master registry, listing each policy’s `id`, human-readable description, `userNotice` text, and default boolean value.

When administrators configure restrictions, they select from this catalog, ensuring that only predefined, typed policies can be applied across the organization. This prevents arbitrary configuration drift and maintains type safety throughout the enforcement pipeline.

## Schema Validation and Data Normalization

Before policies persist to the database or reach the client, they undergo strict validation using Zod schemas. The `desktopPolicyValueSchema` and `desktopPolicyDocumentSchema` types in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) define the exact shape of policy objects.

Three key normalization functions ensure data integrity when loading JSON from storage:

- **`normalizeDesktopPolicyValue`** – Coerces raw database values into typed policy values
- **`normalizeDefaultDesktopPolicyValue`** – Handles the default policy template specifically
- **`normalizeDesktopPolicyDocument`** – Validates and transforms entire policy documents

```typescript
import { 
  normalizeDesktopPolicyDocument,
  calculateEffectiveDesktopPolicy 
} from 'packages/types/src/den/desktop-policies';

// Fetch raw policy JSON from the database
const rawDocument = await fetchOrganizationPolicies(orgId);

// Normalize into a typed DesktopPolicyDocument
const policyDoc = normalizeDesktopPolicyDocument(rawDocument);

```

## Cloud Storage and API Retrieval

Policies are persisted in the Den (cloud) service and exposed via the REST API endpoint **`/v1/desktop-policies`**. The server-side route handler in [`apps/server/src/routes/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/desktop-policies.ts) processes requests by retrieving the organization's default policy and any specifically assigned policies.

The desktop client fetches this configuration during initialization and caches it locally. The response includes the complete policy set necessary for the client to calculate which features remain accessible to the end user.

## Effective Policy Calculation Algorithm

Once the raw policies load into the desktop client, the function `calculateEffectiveDesktopPolicy` merges multiple policy sources into a single "effective" configuration. As implemented in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) (lines 258-284), the algorithm follows these deterministic rules:

1. **Empty State**: If the organization has no policies defined, all feature flags default to `true` (permissive by default).
2. **Baseline Overlay**: When policies exist, the algorithm starts with an "all false" baseline.
3. **Layered Application**: It first applies the default organization policy, then overlays each assigned policy in sequence.
4. **OR Logic**: A feature flag becomes `true` only if any policy explicitly sets it to `true`.

```typescript
// Effective policy calculation
const effectivePolicy = calculateEffectiveDesktopPolicy({
  defaultPolicy,
  assignedPolicies: [teamPolicy, securityPolicy]
});

// Result: allowCustomProviders is true if ANY policy enabled it
if (effectivePolicy.allowCustomProviders) {
  renderCustomProviderSettings();
}

```

## Client-Side Enforcement and UI Gating

The Electron desktop application reads the effective policy through the **OpenWork config store** ([`runtime-opencode-config-store.ts`](https://github.com/different-ai/openwork/blob/main/runtime-opencode-config-store.ts)). Throughout the UI and feature modules, code checks boolean flags using **allow-style naming conventions** such as `allowCustomProviders` and `allowManageExtensions`.

When a flag evaluates to `false`, the corresponding UI element hides or the operation blocks, and the user sees the human-readable `userNotice` string defined in the original policy catalog. This ensures consistent messaging across all enforcement points.

```typescript
// Runtime enforcement example
const config = getOpenWorkConfig();

if (!config.allowManageExtensions) {
  showPolicyNotice(config.userNotice);
  return; // Block extension management
}

// Proceed with extension management
openExtensionManager();

```

## Onboarding Prompt Configuration

Some policies carry optional onboarding prompts to guide users through restricted environments. The helper **`selectEffectiveOnboardingPromptConfig`** in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) (lines 332-363) selects the highest-priority, most-recent prompt configuration from the set of assigned policies.

If multiple policies define onboarding flows, the function applies intelligent precedence rules, falling back to the default policy configuration only when no specific prompts are assigned.

## Live Policy Updates Without Restart

Administrators modify policies through the OpenWork Den UI or direct API calls. When a change occurs, the server emits a **config-reload event** that the desktop client listens for via its persistent connection. This forces an immediate re-fetch of the `/v1/desktop-policies` endpoint and re-calculation of the effective policy.

The client applies these updates dynamically, hiding or showing UI elements in real-time without requiring the user to restart the application, ensuring immediate compliance with new governance requirements.

## Summary

- **Policy Catalog**: All enterprise desktop policies are defined centrally in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) with strict typing and user notices.
- **Schema Safety**: Zod schemas and normalization functions ensure only valid policy data reaches the client.
- **Cloud API**: The Den service exposes policies via `/v1/desktop-policies` for client retrieval.
- **Deterministic Merging**: `calculateEffectiveDesktopPolicy` uses an OR-based overlay algorithm to resolve multiple policy sources.
- **Runtime Enforcement**: The Electron client checks allow-style flags (e.g., `allowCustomProviders`) before rendering UI or executing operations.
- **Dynamic Updates**: Config-reload events enable policy enforcement changes without application restarts.

## Frequently Asked Questions

### How does OpenWork handle conflicting policy definitions?

OpenWork resolves conflicts through its deterministic merging algorithm. The `calculateEffectiveDesktopPolicy` function starts with a restrictive "all false" baseline when policies exist, then overlays the default policy followed by assigned policies. A feature is permitted only if explicitly set to `true` in any policy, effectively implementing permissive OR-logic where any grant overrides denial.

### What happens if the desktop client cannot reach the policy server?

If the client cannot fetch fresh policies from `/v1/desktop-policies`, it relies on cached configuration from previous sessions stored in the OpenWork config store. The system defaults to `true` (permissive) only when no policies have ever been loaded for the organization; otherwise, it maintains the last known effective policy until connectivity restores.

### Can individual users override enterprise desktop policies?

No. Policy enforcement occurs server-side during the calculation phase and is read-only within the desktop client. The [`runtime-opencode-config-store.ts`](https://github.com/different-ai/openwork/blob/main/runtime-opencode-config-store.ts) provides read access only, and the TypeScript types prevent mutation of the effective policy object after calculation. Only administrators with appropriate Den service permissions can modify policies through the authorized API endpoints.

### Where are the policy schemas defined for custom integrations?

All policy type definitions, Zod schemas, and normalization utilities reside in [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts). This shared package ensures type consistency between the server routes in [`apps/server/src/routes/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/desktop-policies.ts) and the desktop client, enabling safe cross-platform policy handling for custom enterprise integrations.