Enterprise Activation Flows in OpenWork: Implementation and Security Architecture

OpenWork uses a three-layer activation system involving a client-side UI gate, desktop bootstrap storage, and server-side origin validation to securely unlock enterprise installations via one-time administrator-distributed links.

The different-ai/openwork repository supports both cloud and enterprise distribution flavors, with the latter requiring a controlled activation mechanism. Enterprise activation flows in OpenWork ensure that only authorized users can access the workspace through a cryptographically secured redemption process that validates the activation origin against the configured cloud MCP endpoint.

Three-Layer Activation Architecture

The enterprise activation system splits responsibilities across the client interface, desktop bootstrap configuration, and server-side validation layers.

Client-Side UI Gate

The EnterpriseActivationGate component enforces the activation requirement before rendering the main workspace. Located in apps/app/src/react-app/domains/cloud/enterprise-activation-gate.tsx, this gate reads the desktop bootstrap configuration and checks enterpriseActivationRequired() to determine whether to display the activation page or the wrapped application children.

Once the useEnterpriseActivationRequired() hook detects a valid activation record in the bootstrap, the gate unlocks and renders the normal workspace interface.

Desktop Bootstrap Storage

The activation record persists in the desktop bootstrap JSON, which stores the activationUrl, activationExpiresAt timestamp, and the Den origin reference. The Zod schema defining these fields lives in packages/install-config/src/index.ts.

When an administrator redeems the activation URL, the desktop helper in ee/apps/den-api/src/desktop-connect-grants.ts builds the activation link (/activate?code=…) and writes the record to the bootstrap configuration, including the timestamp when activatedAt was completed.

Server-Side Origin Validation

Before allowing MCP (Model Context Protocol) calls, the server validates that the activation URL's origin matches the OpenWork Cloud MCP origin. The function enterpriseDenOrigin in apps/server/src/enterprise-den-origin.ts extracts the enterpriseActivation record, verifies that activatedAt exists, confirms the URL is a well-formed HTTPS origin, and returns the exact Den origin.

This prevents malicious activation URLs from unlocking the application. If origins diverge, diagnostics in agent-context-diagnostics.ts surface warnings advising administrators to add the origin to OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

Step-by-Step Activation Flow

The complete enterprise activation process follows five distinct stages:

1. Installation – When an enterprise admin installs the desktop, the Den backend returns an activationUrl and activationExpiresAt timestamp stored in the bootstrap configuration.

2. Distribution – The administrator shares the one-time link with end users through secure channels such as email or internal portals.

3. Link Redemption – The desktop application receives the request, validates the cryptographic code, writes the activation record into the bootstrap JSON, and records the activatedAt timestamp.

4. UI Unlock – The useEnterpriseActivationRequired() hook reads the updated bootstrap, verifies the activation record, and signals EnterpriseActivationGate to render the main workspace instead of the gated activation page.

5. Runtime Security – All subsequent MCP calls undergo origin verification. The system allows connections only if the stored activation origin matches OPENWORK_CLOUD_MCP_ORIGIN, blocking requests from unauthorized sources.

Implementation Examples

Wrap the application root with the activation gate to enforce enterprise validation:

// 1️⃣ Guard the whole app with the activation gate
import { EnterpriseActivationGate } from "./domains/cloud/enterprise-activation-gate";

export default function App() {
  return (
    <EnterpriseActivationGate>
      <MainWorkspace />
    </EnterpriseActivationGate>
  );
}

Generate and persist activation URLs on the Den backend:

// 2️⃣ Generate an activation URL (run on the Den side)
import { readDesktopDistributionInfo } from "@/app/lib/desktop";

export async function createEnterpriseActivation(
  orgId: string,
  webUrl: string,
) {
  const code = crypto.randomUUID();
  const activationUrl = new URL("/activate", webUrl);
  activationUrl.searchParams.set("code", code);
  // Store the URL/expiry in the desktop bootstrap JSON
  await writeBootstrap({
    enterpriseActivation: {
      activationUrl: activationUrl.toString(),
      activationExpiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
    },
  });
  return activationUrl.toString();
}

Validate activation origins server-side before processing MCP requests:

// 3️⃣ Server‑side origin validation (simplified)
import { exactEnterpriseOrigin } from "@/app/lib/enterprise-den-origin";

export function verifyActivationOrigin(bootstrap: any) {
  const origin = exactEnterpriseOrigin(bootstrap.enterpriseActivation);
  if (!origin) throw new Error("Invalid activation record");
  // Compare with the configured cloud MCP origin
  if (origin !== process.env.OPENWORK_CLOUD_MCP_ORIGIN) {
    throw new Error("Activation origin does not match cloud MCP");
  }
  return true;
}

Summary

• EnterpriseActivationGate in enterprise-activation-gate.tsx controls UI access based on bootstrap activation state.
• Activation records containing activationUrl and activationExpiresAt persist in the desktop bootstrap JSON defined in install-config/src/index.ts.
• One-time links are generated in desktop-connect-grants.ts and redeemed during the desktop installation process.
• Origin validation via enterpriseDenOrigin in enterprise-den-origin.ts ensures MCP connections originate from trusted enterprise Den sources.
• Diagnostic tools help administrators troubleshoot origin mismatches by checking against OPENWORK_CLOUD_MCP_ORIGIN.

Frequently Asked Questions

What triggers the enterprise activation requirement in OpenWork?

The activation requirement triggers when the desktop bootstrap configuration contains an enterpriseActivation object with activationUrl and activationExpiresAt fields. The EnterpriseActivationGate component detects these fields via enterpriseActivationRequired() and renders the gated activation screen until the user redeems a valid activation link.

How is the activation URL generated and secured?

The Den backend generates a cryptographically random UUID code in desktop-connect-grants.ts, constructs an HTTPS URL with the code as a query parameter, and stores the URL and expiration timestamp in the desktop bootstrap. The URL expires after a configured duration (default 15 minutes), and the server validates the origin against the enterprise tenant's allowed MCP origin before unlocking the application.

What happens if the activation origin doesn't match the cloud MCP origin?

If the stored activation origin in the bootstrap diverges from OPENWORK_CLOUD_MCP_ORIGIN, the enterpriseDenOrigin validation fails and blocks MCP calls. The diagnostics layer in agent-context-diagnostics.ts surfaces a warning to the administrator, who must either correct the origin configuration or add the origin to the OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS environment variable to establish trust.

Where is the activation state persisted in an enterprise installation?

The activation state persists in the desktop bootstrap JSON file, defined by the Zod schema in packages/install-config/src/index.ts. This file stores the activationUrl, activationExpiresAt, and activatedAt timestamp. The EnterpriseActivationGate reads this bootstrap configuration to determine whether to display the activation page or the main workspace.

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