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

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 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 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 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

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 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 (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.

// 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). 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.

// 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 (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 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 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. This shared package ensures type consistency between the server routes in apps/server/src/routes/desktop-policies.ts and the desktop client, enabling safe cross-platform policy handling for custom enterprise integrations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}