OpenWork Cloud-to-Desktop Handoff Architecture: Secure Session Transfer from Den API to Desktop

OpenWork uses a short-lived handoff grant exchanged via deep-link to move authenticated sessions from the cloud Den API to local desktop clients, storing the credential in desktop-bootstrap.json before exchanging it for a permanent session token.

The different-ai/openwork repository implements a secure cloud-to-desktop handoff mechanism that allows users to authenticate once in the web interface and seamlessly transfer that session to a local Electron desktop application. This architecture bridges the cloud control plane (Den API) with the desktop runtime through a cryptographically secure, one-time grant system.

Architectural Layers of the Handoff System

The handoff flow operates across three distinct logical layers, each responsible for a specific phase of the credential transfer.

Layer 1: Cloud API Grant Creation

The Den API generates a short-lived grant and returns a deep-link URL that the desktop client can consume. In evals/packages/behaviors/src/den.ts, the createDesktopHandoffGrant function initiates this by calling the /v1/auth/desktop-handoff endpoint. This creates a one-time credential that represents the user's authenticated session without exposing the actual session token.

Layer 2: Desktop Bootstrap Persistence

The desktop bootstrap layer persists the grant in desktop-bootstrap.json and manages the handoff state across application restarts. According to packages/types/src/desktop-ipc.ts, the DesktopBootstrapConfig interface defines the handoff object that stores the grant string alongside the Den base URL. The bootstrap handling logic in packages/openwork-bootstrap/bin/openwork.mjs reads this configuration on startup to detect pending handoffs.

Layer 3: Runtime Grant Exchange

The runtime exchange layer converts the temporary grant into a permanent authentication token. When the desktop application launches and detects a pending handoff, it calls /v1/auth/exchange-grant to swap the grant for a real session token. The exchangeGrant logic in packages/openwork-bootstrap/bin/openwork.mjs handles this transaction, after which the desktop activates the organization and skill context specified in the original handoff.

Step-by-Step Handoff Flow

The complete cloud-to-desktop handoff follows a six-step sequence that ensures secure, stateless credential transfer:

1. Desktop requests a handoff URL from the cloud when the user initiates the connection (e.g., clicking "Connect to Den"). The cloud endpoint returns a JSON payload containing the grant string and a deep-link URL.

2. Den returns a deep-link formatted as openwork://desktop-auth?grant=…&denBaseUrl=…. This URL encapsulates all parameters needed for the desktop to complete authentication.

3. Desktop receives the deep-link via the operating system's URL protocol handler. The Electron main process parses the incoming link and writes the handoff object into the bootstrap configuration file.

4. Bootstrap file persistence stores the grant in desktop-bootstrap.json. On the next application launch, the desktop reads this file via the getDesktopBootstrapConfig IPC command to retrieve the pending handoff.

5. Grant exchange for session token occurs when the desktop POSTs the grant to /v1/auth/exchange-grant. The Den API validates the grant against the originating session and returns a permanent authentication token.

6. Workflow activation completes the handoff. The desktop stores the token in its auth store and activates the specific organization and skill context, enabling the user to run workflows exactly as if they had signed in directly within the desktop application.

Implementation Examples

Creating a Handoff Grant (Cloud Side)

The cloud implementation uses the Den API to generate the handoff grant. This example from evals/packages/behaviors/src/den.ts (line ≈ 361) demonstrates the creation flow:

import { denApiFetch } from "@openwork/behaviors";

export async function createDesktopHandoffGrant(member) {
  const result = await denApiFetch(member, "/v1/auth/desktop-handoff", {
    method: "POST",
    headers: { Authorization: `Bearer ${member.sessionToken}` },
  });

  if (!result.response.ok || typeof result.body?.grant !== "string") {
    throw new Error(
      `Desktop handoff create failed: ${result.response.status} ${JSON.stringify(result.body)}`
    );
  }

  // `grant` is a short-lived token; `openworkUrl` contains the deep link.
  return result.body.grant;
}

Consuming the Handoff (Desktop Side)

The desktop bootstrap logic in packages/openwork-bootstrap/bin/openwork.mjs (lines ≈ 514-520) handles grant exchange and token storage:

import { desktopBridge } from "desktop-ipc";

async function handleDesktopHandoff() {
  const cfg = await desktopBridge.getDesktopBootstrapConfig();

  if (!cfg.handoff?.grant) {
    console.log("No handoff pending");
    return;
  }

  const { grant, denBaseUrl } = cfg.handoff;
  const exchange = await fetch(`${denBaseUrl}/v1/auth/exchange-grant`, {
    method: "POST",
    body: JSON.stringify({ grant }),
    headers: { "Content-Type": "application/json" },
  });

  const { token } = await exchange.json();
  await desktopBridge.setDesktopBootstrapConfig({ /* store token, activate org */ });
}

Triggering the Flow from the UI

The web interface initiates the handoff by requesting a URL from the backend and redirecting to the deep-link:

import { useDesktopBridge } from "@/hooks";

export function ConnectButton() {
  const desktop = useDesktopBridge();

  const startHandoff = async () => {
    const handoffUrl = await fetch("/api/create-handoff").then(r => r.text());
    window.location.href = handoffUrl;
  };

  return <button onClick={startHandoff}>Connect to Den</button>;
}

Security and Error Handling

The handoff architecture implements secure by design principles. The grant is a one-time, short-lived string that can be exchanged only once, preventing replay attacks. The exchange endpoint validates the grant against the originating Den session, and if the grant is missing or already consumed, the exchange fails with a desktop_handoff_failed error. This ensures that even if the deep-link is intercepted, the credential cannot be reused after the legitimate desktop client claims it.

Key Source Files

Understanding the handoff mechanism requires familiarity with these specific files in the different-ai/openwork repository:

• packages/types/src/desktop-ipc.ts — Defines DesktopBootstrapConfig and the handoff shape that travels from cloud to desktop.
• packages/openwork-bootstrap/bin/openwork.mjs — Implements the bootstrap lifecycle, reads the handoff, and performs the grant exchange.
• evals/packages/behaviors/src/den.ts — Contains the Den API logic for creating handoff grants via /v1/auth/desktop-handoff.
• evals/runner/journeys/desktop.ts — End-to-end test suite that exercises the complete handoff round-trip.
• packages/docs/start-here/installer-delivery.mdx — Documents the openwork:// URL scheme used by installers to trigger the handoff.

Summary

• Three-layer architecture: Cloud API creates grants, Desktop Bootstrap persists them, and Runtime Exchange converts them to session tokens.
• Secure one-time grants: Short-lived, single-use grants prevent replay attacks and ensure credentials cannot be intercepted and reused.
• Deep-link protocol: Uses openwork://desktop-auth URLs to transfer parameters from browser to desktop application via the OS protocol handler.
• Bootstrap file storage: The desktop-bootstrap.json file acts as the intermediary state store between deep-link receipt and grant exchange.
• Token exchange endpoint: The /v1/auth/exchange-grant API validates and converts temporary grants into permanent authentication tokens.

Frequently Asked Questions

What is a handoff grant in OpenWork?

A handoff grant is a cryptographically secure, short-lived token generated by the Den API that represents a user's authenticated session without exposing the actual session credentials. It acts as a temporary voucher that the desktop client can exchange for a permanent authentication token, enabling secure session transfer from cloud to desktop.

How does the desktop application receive the authentication grant?

The desktop receives the grant through a deep-link URL with the openwork:// scheme. When the user clicks "Connect to Den" in the web interface, the browser redirects to this custom protocol URL, which launches the Electron desktop application and passes the grant and Den base URL as query parameters. The desktop then persists these values in desktop-bootstrap.json.

What happens if the handoff grant expires before use?

If the grant expires or has already been exchanged, the desktop's call to /v1/auth/exchange-grant returns a desktop_handoff_failed error. The application must then prompt the user to re-initiate the handoff flow from the web interface to generate a fresh grant, as each grant is strictly single-use and time-bound.

Is the cloud-to-desktop handoff mechanism secure for production use?

Yes, the mechanism is secure by design according to the OpenWork source code. The grant is one-time use only, validated against the originating Den session during exchange, and never transmitted in a reversible format. Even if the deep-link is intercepted, an attacker cannot reuse the grant after the legitimate desktop client has consumed it.

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