# How the Prime Agent Private Worker Transport Authenticates Sessions: A Complete Technical Guide

> Discover how the Prime Agent private worker transport authenticates sessions. Learn about secure token generation, embedding, and validation for role upgrades.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The private-framed worker transport in Prime Agent authenticates sessions by generating a cryptographically secure random token, embedding it in environment variables and frame headers, and validating it using constant-time comparison before upgrading the client’s authentication role from `"session_client"` to `"supervisor"`.**

The PrimeIntellect-ai/prime-agent codebase implements a secure transport layer for worker processes that prevents unauthorized clients from issuing privileged commands. When a supervisor spawns a worker, it establishes a trust relationship through a one-time secret token exchanged via the private-framed transport protocol. This mechanism ensures that only the supervising daemon can register peer transports or execute administrative functions on the worker.

## Token Generation and Environment Injection

Authentication begins when the supervisor initializes a new worker. In [`packages/coding-agent/src/modes/daemon/daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-mode.ts) (lines 36-40), the daemon checks for `options.worker` and extracts the pre-generated authentication token stored in `worker.authenticationToken`.

The supervisor injects this token into the worker’s process environment using the constant `DAEMON_WORKER_TOKEN_ENV` (defined as `PRIME_AGENT_INTERNAL_DAEMON_WORKER_TOKEN` in [`daemon-worker-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-worker-protocol.ts)):

```typescript
// packages/coding-agent/src/modes/daemon/daemon-mode.ts
if (options.worker) {
    const token = options.worker.authenticationToken;
    // inject the token for the newly spawned worker process
    environment[DAEMON_WORKER_TOKEN_ENV] = token;
}

```

This token is generated using `crypto.randomUUID()` or an equivalent cryptographically secure random source, ensuring sufficient entropy to prevent brute-force attacks.

## Private Frame Encoding and Transport Selection

Once the worker is spawned, the supervisor instructs the client to use the `"private-framed"` transport mechanism. This transport wraps every JSON-RPC request with a private frame that includes both the authentication token and the worker instance identifier.

The `encodePrivateFrame` function from [`packages/coding-agent/src/modes/session-worker/private-framing.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/session-worker/private-framing.ts) constructs the frame header:

```typescript
import { encodePrivateFrame } from "../session-worker/private-framing.js";

const frame = encodePrivateFrame(
    { token: clientToken, workerInstanceId: instanceId },
    JSON.stringify(request)
);
socket.write(frame);

```

The client (implemented as `DaemonSocketClient` in [`daemon-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-client.ts)) transmits these frames as JSON-L lines, where the private frame header precedes the actual payload. This ensures the token travels alongside every request without polluting the JSON-RPC message structure.

## Token Validation and Timing-Safe Authentication

When the supervisor receives a private-framed request, it instantiates `PrivateFrameDecoder` (line 3250 of [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts)) to parse and validate the incoming frame. The decoder extracts the token from the frame header and performs a constant-time comparison against the expected token stored in the worker descriptor.

```typescript
// packages/coding-agent/src/modes/session-worker/private-framing.ts
export class PrivateFrameDecoder<THeader extends object> {
    push(chunk: Uint32Array) {
        // …extract header, then:
        const received = header.token;
        if (!timingSafeEqual(Buffer.from(received), Buffer.from(this.expectedToken))) {
            throw new Error("transport rejected");
        }
        // token matches → process the payload
    }
}

```

The use of `crypto.timingSafeEqual` prevents timing side-channel attacks that could leak information about the correct token through response latency differences. If validation fails, the supervisor rejects the connection with `"Direct transport is unavailable for client‑owned workers"` or a generic transport rejection error.

## Authentication Role Escalation

Upon successful token validation, the client’s authorization context upgrades from `"session_client"` to `"supervisor"`. This role change is critical for security-sensitive operations. Code guards throughout [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts) (such as line 7224) check `client.authenticationRole !== "session_client"` before allowing privileged commands like `worker_register_peer_transport`:

```typescript
// packages/coding-agent/src/modes/daemon/daemon-mode.ts
if (client.authenticationRole !== "session_client") {
    // Allow privileged operations like worker_register_peer_transport
}

```

This role-based access control ensures that even if a malicious client connects to the worker socket, it cannot execute administrative functions without possessing the secret token that proves supervisor authority.

## Post-Authentication Security Cleanup

To minimize the attack surface, the supervisor removes the token from the worker’s environment once the worker is fully initialized and ready to accept connections. This cleanup occurs in both [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts) (line 896) and [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts) (line 6920):

```typescript
delete environment[DAEMON_WORKER_TOKEN_ENV];

```

By deleting `PRIME_AGENT_INTERNAL_DAEMON_WORKER_TOKEN` from the environment, the system prevents accidental leakage to child processes or subprocesses spawned by the worker. This defense-in-depth measure ensures the token exists only transiently during the initial handshake phase.

## Summary

- **Token Generation**: The supervisor generates a cryptographically secure random token via `crypto.randomUUID()` and stores it in `worker.authenticationToken`.
- **Environment Injection**: The token is passed to the worker process through the `PRIME_AGENT_INTERNAL_DAEMON_WORKER_TOKEN` environment variable defined in [`daemon-worker-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-worker-protocol.ts).
- **Frame Encoding**: Clients use `encodePrivateFrame` from [`private-framing.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/private-framing.ts) to wrap requests with headers containing the token and worker instance ID.
- **Constant-Time Validation**: `PrivateFrameDecoder` validates tokens using `crypto.timingSafeEqual` to prevent timing attacks.
- **Role Escalation**: Successful authentication upgrades the client from `"session_client"` to `"supervisor"`, unlocking privileged RPC methods.
- **Environment Cleanup**: The token is removed from the worker environment after initialization to prevent leakage.

## Frequently Asked Questions

### How does the private-framed transport prevent timing attacks on the authentication token?

The transport uses `crypto.timingSafeEqual` inside `PrivateFrameDecoder` (implemented in [`packages/coding-agent/src/modes/session-worker/private-framing.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/session-worker/private-framing.ts)) to compare the received token against the expected value. Unlike standard string comparison operators that return early on mismatch, `timingSafeEqual` always compares all bytes, ensuring constant-time execution regardless of how many characters match, thereby preventing attackers from inferring the token through response time analysis.

### What privileges does a client gain after successful private worker transport authentication?

Once the supervisor validates the private frame token, the client’s `authenticationRole` property upgrades from `"session_client"` to `"supervisor"`. According to the source code in [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts) (line 7224), only clients with this elevated role may execute privileged commands such as `worker_register_peer_transport`, which allows the supervisor to configure network transports for the worker instance.

### Why is the authentication token removed from the environment after the worker starts?

The supervisor deletes `PRIME_AGENT_INTERNAL_DAEMON_WORKER_TOKEN` from the worker’s environment in both [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts) and [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts) immediately after the worker signals readiness. This security cleanup prevents the token from being inherited by child processes spawned by the worker, reducing the risk of accidental exposure through process dumps, `/proc` filesystem leaks, or untrusted subprocesses.

### Can a client connect to a worker without using the private-framed transport?

No. When a supervisor spawns a worker, it explicitly configures the transport as `"private-framed"` in the client options. If a client attempts to connect without the correct private frame header or with an invalid token, the `PrivateFrameDecoder` rejects the connection with errors such as `"Direct transport is unavailable for client‑owned workers"`. This enforces that only the supervising daemon—with knowledge of the ephemeral token—can establish a privileged session.