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

> Discover how connect-link.mjs securely shares and hands off OpenWork workspaces. Learn about JWT token validation and replay attack prevention for seamless collaboration.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: internals
- Published: 2026-08-17

---

**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`](https://github.com/different-ai/openwork/blob/main/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

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

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

```javascript
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.