How connect-link.mjs Enables Workspace Sharing and Handoff in OpenWork

The connect-link.mjs module validates cryptographically signed deep-link tokens in the Electron main process to securely transfer workspace configurations between users while preventing replay attacks through single-use JWT ID tracking.

OpenWork's collaborative workspace sharing relies on connect-link.mjs located in apps/desktop/electron/connect-link.mjs within the different-ai/openwork repository. This zero-dependency module executes the complete verification pipeline for workspace handoff URLs, ensuring that only authorized, non-reusable tokens can reconfigure the desktop application to join new organizations.

Deep Link Parsing and Token Extraction

When a user clicks an openwork://connect?token=... link, the module first isolates the transport mechanism from the URL. The extractConnectLinkToken function (lines 84-101) handles standard signed JWS tokens, while extractConnectExchange (lines 115-136) processes key-less exchange codes. Both functions normalize the route to connect and extract the payload for downstream verification.

The module supports two distinct handoff patterns:

• Signed Transport: A compact JWS token containing the complete workspace metadata
• Key-less Exchange: A temporary code requiring server resolution to retrieve signed claims

Cryptographic Verification with EdDSA

The verifyConnectLinkToken function (lines 164-226) performs rigorous validation of signed tokens. It parses the three-part compact JWS structure (header, payload, signature) and enforces the EdDSA algorithm requirement. The function checks the kid (key ID) against trusted public keys loaded via resolveConnectLinkPublicKeys from connect-link-keys.mjs, then verifies the cryptographic signature using Node.js's native createPublicKey and crypto.verify methods.

This verification occurs exclusively in the Electron main process, ensuring a malicious renderer cannot bypass signature checks or forge workspace configurations.

Claims Normalization and Security Validation

After cryptographic verification, normalizeClaims (lines 46-84) inspects the payload structure and enforces mandatory claim fields: iss (issuer), aud (audience), iat (issued at), exp (expiration), org (organization), brand, and den. The function implements strict URL validation, rejecting any non-HTTPS URLs unless explicit loopback exceptions are configured, preventing man-in-the-middle attacks through malformed base URLs.

Replay Protection via Single-Use Tokens

To prevent workspace hijacking through token reuse, createConnectLinkReplayGuard (lines 355-401) implements a persistent deduplication mechanism. The function maintains a JSON file at connect-link-seen.json in the user's data directory, storing the jti (JWT ID) of every successfully consumed link. Subsequent attempts to process a token with an existing jti are rejected, ensuring that a workspace handoff link becomes invalid immediately after first use.

Key-Less Exchange Code Resolution

For scenarios requiring shorter URLs, resolveConnectExchangeUrl (lines 322-354) handles openwork://connect?code=...&apiBaseUrl=... deep links. This function contacts the organization's server specified in apiBaseUrl, retrieves the full signed claims package, and executes the same normalization and verification pipeline used for pre-signed tokens. This hybrid approach balances URL brevity with cryptographic security by deferring trust to the organization's live API.

Desktop Bootstrap and Workspace Handoff

The final stage maps verified claims to actionable workspace configuration through desktopBootstrapFromConnectClaims (lines 306-312). This function extracts a minimal, sanitized subset of claim fields—base URLs, brand identifiers, and sign-in requirements— isolating the handoff surface from the full token payload. The resulting bootstrap object is applied to the desktop's workspace store, triggering an immediate switch to the target organization with appropriate branding and authentication rules.

Security Architecture and Trust Model

connect-link.mjs maintains a zero-dependency architecture using only Node.js built-in crypto and fs modules, making it safe to execute early in the application startup sequence before third-party dependencies load. By confining all verification logic to the trusted main process, OpenWork ensures that renderer compromises cannot intercept or modify workspace handoffs. The module's integration with connect-link-branding.mjs applies organizational visual identity only after cryptographic verification completes.

Implementation Examples

Verifying a Signed Connect Link

import { verifyConnectLinkUrl, desktopBootstrapFromConnectClaims } from "./connect-link.mjs";
import { resolveConnectLinkPublicKeys } from "./connect-link-keys.mjs";

// Load trusted public keys bundled at build time
const publicKeys = await resolveConnectLinkPublicKeys();

// Verify the deep-link passed by the OS
const result = verifyConnectLinkUrl(process.argv[2], { publicKeys });

if (!result.ok) {
  console.error("Connect link rejected:", result.message);
} else {
  // Apply verified configuration to workspace
  const bootstrap = desktopBootstrapFromConnectClaims(result.claims);
  workspaceStore.applyBootstrap(bootstrap);
}

Processing Key-Less Exchange Codes

import { resolveConnectExchangeUrl, desktopBootstrapFromConnectClaims } from "./connect-link.mjs";

const result = await resolveConnectExchangeUrl(
  "openwork://connect?code=abc123&apiBaseUrl=https://org.example.com",
  {
    mode: "preview",
    fetcher: fetch,
  }
);

if (result.ok) {
  const bootstrap = desktopBootstrapFromConnectClaims(result.claims);
  workspaceStore.applyBootstrap(bootstrap);
}

Preventing Replay Attacks

import { createConnectLinkReplayGuard } from "./connect-link.mjs";
import path from "path";

const replayGuard = createConnectLinkReplayGuard({
  filePath: path.join(app.getPath("userData"), "connect-link-seen.json"),
});

if (await replayGuard.has(result.claims.jti)) {
  console.error("Link already used");
} else {
  await replayGuard.remember(result.claims.jti);
  // Proceed with workspace handoff
}

Summary

• connect-link.mjs in apps/desktop/electron/ serves as the sole trusted verifier for OpenWork's workspace sharing deep links
• EdDSA-signed JWS tokens provide cryptographic authenticity for workspace metadata, verified against build-time public keys in connect-link-keys.mjs
• Replay protection via jti tracking in connect-link-seen.json ensures single-use links prevent unauthorized re-entry
• Dual transport modes support both direct signed tokens and key-less exchange codes resolved through organization APIs
• Main process isolation guarantees that renderer compromises cannot intercept or forge workspace handoff data

Frequently Asked Questions

What cryptographic algorithm does connect-link.mjs use for token verification?

The module exclusively uses EdDSA (Edwards-curve Digital Signature Algorithm) as specified in the JWS header. The verifyConnectLinkToken function validates the algorithm field and rejects tokens using other signing methods, ensuring that only the organization's Edwards-curve private keys can generate valid workspace handoff links.

How does OpenWork prevent connect links from being used multiple times?

OpenWork implements replay protection through the createConnectLinkReplayGuard function, which persists consumed JWT IDs (jti claims) to a local JSON file (connect-link-seen.json). Before processing any link, the module checks this registry and rejects tokens with previously recorded identifiers, ensuring that a workspace sharing link becomes permanently invalid after the first successful handoff.

What is the difference between signed tokens and exchange codes in OpenWork?

Signed tokens contain the complete workspace metadata and cryptographic signature within the URL itself, processed immediately by extractConnectLinkToken. Exchange codes are short, opaque identifiers that require the desktop client to contact the organization's server via resolveConnectExchangeUrl to retrieve the full signed claims. Exchange codes produce shorter shareable URLs while maintaining security through server-side resolution.

Where does connect-link.mjs store verified workspace configuration?

The module does not store full claim payloads directly. Instead, desktopBootstrapFromConnectClaims extracts a minimal bootstrap configuration containing base URLs, brand data, and authentication requirements. This sanitized subset is passed to the desktop's workspace store implementation, which persists the handoff configuration separately from the cryptographic verification artifacts.

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