FWD » Documentation

# Cross-Domain FWD Spawning — Internal OIDC Variant (v2)

> **Scope**: Internal FWD server → spawned FWD client bootstrapping only. User authentication is unchanged. OIDC subset used: JWT for tokens, JWKS for key distribution.

>

> **Key design decision**: **No cookies**. Third-party cookies in cross-origin iframes are blocked by modern browsers. All session state is maintained through WebSocket + postMessage + signed URLs.

---

## 1. What Breaks Today (Cross-Domain)

| # | Interaction | Why it breaks |

|---|-------------|---------------|

| 1 | [getRemoteUri()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#267-297) appends `?token=<opaque>` | Opaque token, no expiry, no audience scoping |

| 2 | Iframe navigates to `http://other-host:port/...` | Iframe becomes cross-origin; postMessage bridge must pre-know client origin |

| 3 | Spawned client's embedded Jetty has no CORS config | REST fetches from cross-origin iframe are blocked |

| 4 | Session cookies from the client | Third-party cookies blocked in cross-origin iframes by modern browsers |

| 5 | Top-level resource URLs (e.g. PDFs for printing) | No cookie = no auth for plain browser GETs in new tabs |

| 6 | Client iframe loading resources from FWD server | Cross-origin `<script src>`, `<img src>` — can't attach auth headers to HTML tag loads |

> [!NOTE]

> The login AJAX POST ([fwd_sdk.js](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/fwd_sdk.js) → FWD server) is **not** affected — the login page is loaded via `srcdoc` (same-origin with parent).

---

## 2. Solution Overview

```mermaid

flowchart TD

    subgraph "Authentication (unchanged)"

        A[Login form / SSO] -->|credentials| B[FWD Server]

    end

    subgraph "Spawn Handover (JWT)"

        B -->|spawn process| C[FWD Client]

        C -->|clientIsReady| B

        B -->|mint JWT| D["JSON {url, jwt}"]

        D -->|iframe navigate| C

        C -->|validate JWT| E[Session established via WebSocket]

    end

    subgraph "Runtime (cookie-free)"

        E -->|WebSocket| F[Normal operation]

        F -->|reconnect needed| G[postMessage → parent → server → new JWT]

        F -->|PDF/print| H[Signed resource URL in new tab]

        F -->|JS/CSS/img from server| I["Option A: Client proxies server resources<br/>Option B: Pre-signed server URLs"]

    end

```

---

## 3. Initial Handover (JWT)

### 3.1 Flow

```mermaid

sequenceDiagram

    participant Login as Login (srcdoc iframe)

    participant Server as FWD Server

    participant Client as Spawned Client

    participant Parent as web_landing.html

    Login->>Server: POST /gui (credentials)

    Server->>Server: Authenticate + spawn

    Client-->>Server: clientIsReady(uri)

    Server->>Server: Mint JWT {iss, aud, exp, uuid}

    Server-->>Login: JSON {url, jwt, storageId}

    Login->>Parent: postMessage({origin: clientOrigin})

    Note over Parent: Pre-register iframeOrigin

    Login->>Client: navigate iframe to url?token=jwt

    Client->>Client: Validate JWT → establish WebSocket

```

### 3.2 JWT Structure

```json

{

  "iss": "https://fwd-server:8443",

  "sub": "<fwd-user-id>",

  "aud": "https://192.168.1.50:9443",

  "exp": "<+60s>",

  "iat": "<now>",

  "jti": "<unique-id>",

  "uuid": "<spawned client UUID>"

}

```

### 3.3 What Changes vs. Current

| Aspect | Current | New |

|--------|---------|-----|

| Token format | Opaque from `ServerKeyStore` | Signed JWT (RS256/EdDSA) |

| Token scope | No audience, no expiry | `aud` = client origin, `exp` = 30–120s |

| Key distribution | Full `ServerKeyStore` via RPC | Public key via [getServerData()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#315-324) RPC (or JWKS endpoint) |

| Post-handover session | Cookie / in-memory | **WebSocket = session, no cookies** |

---

## 4. Session Continuity Without Cookies

### 4.1 Normal Operation

The WebSocket connection **is** the session. No cookies needed while it's alive. This matches current FWD behavior.

### 4.2 Reconnection (WebSocket Drops)

```mermaid

sequenceDiagram

    participant Client as Client iframe (cross-origin)

    participant Parent as web_landing.html (server-origin)

    participant Server as FWD Server

    Note over Client: WebSocket connection lost

    Client->>Parent: postMessage({type: "MSG_RECONNECT_TOKEN", uuid: "..."})

    Parent->>Server: fetch("/api/reconnect-token?uuid=...") (same-origin)

    Server->>Server: Validate session still active, mint fresh JWT

    Server-->>Parent: {jwt: "<new-token>"}

    Parent->>Client: postMessage({type: "MSG_RECONNECT_TOKEN", jwt: "..."})

    Client->>Client: Reconnect WebSocket with token

```

**Why this works**:

- [web_landing.html](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/web_landing.html) is **same-origin** with the FWD server → its `fetch()` is a first-party request, no CORS issues

- The postMessage bridge is **already in place** for parent↔iframe relay

- The spawned client validates the same JWT format as the initial handover

- Only one new message type (`MSG_RECONNECT_TOKEN`) in the bridge

### 4.3 Top-Level Resource Access (PDFs, Print, Downloads)

For resources that must open in a new browser tab (no iframe, no WebSocket):

```mermaid

sequenceDiagram

    participant App as P2J App (in iframe)

    participant Client as Embedded Jetty

    participant Browser as New browser tab

    App->>Client: WebSocket: "need URL for /reports/invoice.pdf"

    Client->>Client: Mint resource-scoped JWT {res: "/reports/invoice.pdf", exp: +60s, jti: "..."}

    Client-->>App: "https://client:port/reports/invoice.pdf?access=<jwt>"

    App->>Browser: window.open(signedUrl)

    Browser->>Client: GET /reports/invoice.pdf?access=<jwt>

    Client->>Client: Validate JWT: signature ✓, expiry ✓, resource path ✓, jti not replayed ✓

    Client-->>Browser: 200 OK (PDF content)

```

**Properties**:

- Token is **resource-scoped** — [res](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebDriverHandler.java#1513-1527) claim must match the requested path

- Token is **single-use** — `jti` tracked in a short-lived in-memory set

- Token is **short-lived** — 5–30 minutes (configurable), long enough for slow connections and large resources

- Same pattern as S3 pre-signed URLs

### 4.4 Loading FWD Server Resources from the Client Iframe

When the spawned client's HTML page needs `<script>`, `<img>`, `<link>` from the FWD server (cross-origin), there are two options. Both are fully specified; the choice is a deployment-time configuration.

#### Option A — Client-Side Reverse Proxy

```mermaid

sequenceDiagram

    participant Browser as Browser (iframe)

    participant Client as Spawned Client (Embedded Jetty)

    participant Server as FWD Server

    Note over Client: At startup, client knows FWD server URL (config override)

    Browser->>Client: GET /server-res/p2j.screen.js

    Client->>Client: Check local cache

    alt Cache miss

        Client->>Server: GET /webres/p2j.screen.js (server-to-server, no CORS)

        Server-->>Client: 200 OK + resource body

        Client->>Client: Store in cache

    end

    Client-->>Browser: 200 OK + resource + Cache-Control headers

```

**Implementation details**:

- The client's HTML emits `<script src="/server-res/p2j.screen.js">` — same-origin to the client

- The embedded Jetty has a **single handler** at `/server-res/*` that:

  1. Maps the path: `/server-res/foo.js` → `<fwd-server-url>/webres/foo.js`

  2. Fetches from the FWD server using a standard HTTP client (server-to-server, no browser involvement)

  3. Caches the response in memory (with `ETag` / `Last-Modified` for revalidation)

  4. Returns the resource to the browser with appropriate `Cache-Control` headers

- FWD server URL is known at spawn time (passed via config override `client:web:server_origin`)

- **Zero CORS complexity** — the browser never makes a cross-origin request

- **Zero token management** — the server-to-server fetch can use internal auth (e.g. the spawned client's UUID)

**Pros**: No CORS on FWD server, no tokens for resources, simplest browser-side model

**Cons**: Memory/CPU overhead on spawned client for caching + proxying; doubled network bandwidth for first load

---

#### Option B — Pre-Signed Server Resource URLs

```mermaid

sequenceDiagram

    participant Client as Spawned Client (Embedded Jetty)

    participant Server as FWD Server

    participant Browser as Browser (iframe)

    Note over Client: At startup or on HTML generation

    Client->>Server: RPC: getSignedResourceUrls(["/webres/p2j.screen.js", "/webres/style.css", ...])

    Server->>Server: For each resource, mint a resource-scoped JWT

    Server-->>Client: [{path, signedUrl}, ...]

    Client->>Client: Emit HTML with signed URLs

    Client-->>Browser: HTML with signed src attributes

    Browser->>Server: GET /webres/p2j.screen.js?access=<jwt>

    Server->>Server: Validate JWT: signature ✓, exp ✓, resource path ✓

    Server-->>Browser: 200 OK + resource + CORS headers + cache headers

```

**Implementation details**:

- The client's HTML emits `<script src="https://fwd-server:8443/webres/p2j.screen.js?access=<jwt>">` — cross-origin

- The **server-side resource JWT** has a longer TTL than the handover JWT (resource tokens can live minutes to hours since they grant read-only access to static content):

  ```json

  {

    "iss": "https://fwd-server:8443",

    "aud": "https://fwd-server:8443",

    "sub": "<client-uuid>",

    "res": "/webres/p2j.screen.js",

    "exp": "<+3600s>",

    "jti": "<unique-id>"

  }

  ```

- The FWD server validates the JWT on each resource request and adds CORS headers:

  ```

  Access-Control-Allow-Origin: <client-origin>

  Access-Control-Allow-Methods: GET

  Access-Control-Allow-Credentials: false

  Cache-Control: public, max-age=3600

  ```

- The `client-origin` is encoded in the JWT (`sub` maps to `client-uuid`, server looks up the client origin)

- Browser caches resources normally via `Cache-Control`; the signed URL stays valid for the TTL

**Pros**: No proxy overhead on spawned client, leverages browser caching natively, FWD server has full control over resource access

**Cons**: CORS headers needed on FWD server, per-resource JWT management, signed URLs in HTML source

---

#### Trade-off Comparison

| | Option A (Proxy) | Option B (Signed URLs) |

|---|---|---|

| CORS on FWD server | None | Yes (scoped to client origin) |

| Token management | None | Per-resource JWTs |

| Caching | Proxy cache on client | Browser cache (native) |

| Network hops | 2 (browser→client→server) | 1 (browser→server direct) |

| Load on spawned client | Proxy + cache memory | None |

| Complexity | Low (one proxy handler) | Medium (JWT signing + CORS) |

| Resource access control | Implicit (only proxy serves) | Explicit (JWT per resource) |

> [!TIP]

> Both options can coexist. A deployment could use **Option A** by default (simplest) and fall back to **Option B** for specific resources that need direct server access or where proxy overhead is unacceptable. This is controlled via configuration.

---

## 5. postMessage Bridge Changes

The existing bridge in [web_landing.html](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/web_landing.html) needs **one new message type**:

| Message Type | Direction | Purpose |

|---|---|---|

| `MSG_RECONNECT_TOKEN` | Client → Parent | Request a fresh JWT for WebSocket reconnection |

| `MSG_RECONNECT_TOKEN` | Parent → Client | Deliver the fresh JWT |

The parent handler:

```

case 'MSG_RECONNECT_TOKEN':

    fetch('/api/reconnect-token?uuid=' + event.data.uuid)

      .then(r => r.json())

      .then(data => iframeWindow.postMessage({

          msgId: event.data.msgId,

          type: 'MSG_RECONNECT_TOKEN',

          jwt: data.jwt

      }, iframeOrigin));

    break;

```

All existing message types (`MSG_SET_KEY_VALUE`, `MSG_READ_CLIPBOARD_VALUE`, etc.) continue to work unchanged — `postMessage` is inherently cross-origin capable.

---

## 6. CORS Configuration Summary

| Component | Option A (Proxy) | Option B (Signed URLs) |

|-----------|-----------------|------------------------|

| **FWD Server** | No CORS needed. Login is same-origin (srcdoc). Reconnect-token fetch is same-origin (from parent). Server resources are proxied server-to-server. | CORS needed on resource endpoints: `Access-Control-Allow-Origin: <client-origin>`, `GET` only. Login and reconnect-token remain same-origin. |

| **Spawned Client** | No CORS needed for resources (same-origin proxy). WebSocket `Origin` header validated server-side. | Same as Option A — no additional CORS. |

> [!NOTE]

> In both options, the initial iframe navigation (`GET /index.html?token=<jwt>`) is a simple GET by the browser — it does not trigger a CORS preflight. The embedded Jetty only needs to validate the JWT, not add CORS headers for this request.

---

## 7. Component Impact

### Server Side

| File | Change |

|------|--------|

| [WebDriverHandler.java](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebDriverHandler.java) | Mint JWT in [spawnWorker()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebDriverHandler.java#775-1008) after spawn succeeds. Include `jwt` in [writeUrlInResponse()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebDriverHandler.java#1562-1600) JSON. Add `/api/reconnect-token` endpoint. |

| [WebClientSpawner.java](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java) | [getRemoteUri()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#267-297): remove opaque `?token=` appending. |

| [ServerKeyStore.java](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/ServerKeyStore.java) | Add JWT signing key pair. Add `getJwtPublicKey()` for RPC distribution. |

| **[NEW] `JwtService.java`** | `mintToken(claims)` + `validateToken(jwt, audience)`. |

### Client Side (Spawned Process)

| File | Change |

|------|--------|

| `TemporaryClientTask.doWork()` in [WebClientSpawner.java](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#L332-L471) | Receive JWT public key via [getServerData()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#315-324). Pass FWD server URL for resource proxy config. |

| **Embedded Jetty** | JWT validation filter on initial load. Signed-URL validation filter for resource GETs. **Option A**: `/server-res/*` reverse proxy handler with cache. **Option B**: update HTML template to emit signed URLs from server. WebSocket `Origin` validation. |

### Browser / JavaScript

| File | Change |

|------|--------|

| [fwd_sdk.js](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/fwd_sdk.js) | Extract `jwt` from response, append to iframe URL. |

| [web_landing.html](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/web_landing.html) | Add `MSG_RECONNECT_TOKEN` handler to postMessage bridge. |

| [p2j.screen.js](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/ui/client/gui/driver/web/res/p2j.screen.js) | Request signed URL via WebSocket before opening new tabs. Request reconnect token via postMessage on connection loss. |

### Configuration

| Key | Description | Default |

|-----|-------------|---------|

| `server:jwt:algorithm` | RS256, EdDSA, or HS256 | `RS256` |

| `server:jwt:ttl_seconds` | Handover token TTL | `60` |

| `server:jwt:resource_ttl_seconds` | Resource-scoped token TTL (top-level access) | `600` |

| `client:web:server_origin` | FWD server origin for proxy + validation | *(auto from spawn)* |

---

## 8. Implementation Roadmap

### Phase 1 — JWT Infrastructure

- Add key pair generation to `ServerKeyStore`

- Create `JwtService` with `mintToken()` / `validateToken()`

- Extend [getServerData()](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/WebClientSpawner.java#315-324) RPC to include public key

### Phase 2 — Spawn Handover

- Mint JWT in `WebDriverHandler.spawnWorker()` post-spawn

- Include `jwt` in response JSON; remove opaque `?token=`

- Update [fwd_sdk.js](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/fwd_sdk.js) to append JWT to iframe URL

- Add JWT validation filter to embedded Jetty initial load

### Phase 3 — Cookie-Free Session Support

- Add `MSG_RECONNECT_TOKEN` to postMessage bridge ([web_landing.html](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/web_landing.html))

- Add `/api/reconnect-token` endpoint to FWD server

- Update `p2j.screen.js` to request reconnect token via postMessage on WebSocket loss

- Add signed resource URL generation for top-level access (PDFs)

- Add `jti` replay detection (in-memory set with TTL)

### Phase 4 — Server Resource Access + Hardening

- **Option A**: Add `/server-res/*` reverse proxy handler to embedded Jetty (fetch + cache from FWD server). Update client HTML generation to use `/server-res/` prefix.

- **Option B**: Add `getSignedResourceUrls()` RPC endpoint to FWD server. Add JWT validation + CORS filter on server resource endpoints. Update client HTML generation to emit signed URLs.

- Add configuration to select Option A, Option B, or both

- Add WebSocket `Origin` header validation

- Key rotation support

- Integration testing with genuinely cross-domain setup (different IPs, no reverse proxy)

---

## 9. What Stays Unchanged

- User authentication (login form, SSO, external OIDC)

- OS process spawning via native tool

- [ClientDriver](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/ClientDriver.java#173-350) entry point

- WebSocket protocol between browser and spawned client

- [web_landing.html](file:///home/hc/gcd/p2j_repo/p2jtrunk/src/com/goldencode/p2j/main/web_landing.html) wrapper / iframe structure

- All existing postMessage bridge message types

- Session fork flow (adapted to use JWT, same pattern)

---

## 10. Security Summary

| Threat | Mitigation |

|--------|------------|

| JWT interception via URL | Short TTL (30–120s), single-use `jti`, audience-restricted |

| Token replay to different client | `aud` = specific client origin |

| Token replay same client | `jti` tracking with TTL-based expiry |

| Third-party cookie attacks | **No cookies used anywhere** |

| Cross-origin iframe attacks | postMessage origin validation (existing) |

| WebSocket hijacking | Server-side `Origin` header validation |

| Server resource leakage (Option A) | Proxied through authenticated client (no direct cross-origin access) |

| Server resource leakage (Option B) | Resource-scoped JWT, read-only, client-origin-restricted CORS |

| Signed URL leakage (PDFs) | Resource-scoped + short-lived + single-use |