LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-03-30 01:06:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(security): split gateway auth suites and share safe write path checks

Browse Source
This commit is contained in:
Peter Steinberger
2026-03-02 18:06:58 +00:00
parent 602f6439bd
commit 83c8406f01
9 changed files with 1050 additions and 994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

922
src/gateway/server.auth.test.ts → src/gateway/server.auth.control-ui.suite.ts
View File

@@ -1,898 +1,33 @@
import os from "node:os";
import path from "node:path";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
import { expect, test } from "vitest";
import { WebSocket } from "ws";
import { withEnvAsync } from "../test-utils/env.js";
import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
import { buildDeviceAuthPayload } from "./device-auth.js";
import { ConnectErrorDetailCodes } from "./protocol/connect-error-details.js";
import { PROTOCOL_VERSION } from "./protocol/index.js";
import { getHandshakeTimeoutMs } from "./server-constants.js";
import {
approvePendingPairingIfNeeded,
BACKEND_GATEWAY_CLIENT,
buildDeviceAuthPayload,
connectReq,
getTrackedConnectChallengeNonce,
getFreePort,
installGatewayTestHooks,
configureTrustedProxyControlUiAuth,
CONTROL_UI_CLIENT,
ConnectErrorDetailCodes,
createSignedDevice,
ensurePairedDeviceTokenForCurrentIdentity,
GATEWAY_CLIENT_MODES,
GATEWAY_CLIENT_NAMES,
onceMessage,
openWs,
originForPort,
readConnectChallengeNonce,
restoreGatewayToken,
rpcReq,
startGatewayServer,
startRateLimitedTokenServerWithPairedDeviceToken,
startServerWithClient,
trackConnectChallengeNonce,
testTailscaleWhois,
TEST_OPERATOR_CLIENT,
testState,
TRUSTED_PROXY_CONTROL_UI_HEADERS,
withGatewayServer,
} from "./test-helpers.js";
installGatewayTestHooks({ scope: "suite" });
async function waitForWsClose(ws: WebSocket, timeoutMs: number): Promise<boolean> {
if (ws.readyState === WebSocket.CLOSED) {
return true;
}
return await new Promise((resolve) => {
const timer = setTimeout(() => resolve(ws.readyState === WebSocket.CLOSED), timeoutMs);
ws.once("close", () => {
clearTimeout(timer);
resolve(true);
});
});
}
const openWs = async (port: number, headers?: Record<string, string>) => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, headers ? { headers } : undefined);
trackConnectChallengeNonce(ws);
await new Promise<void>((resolve) => ws.once("open", resolve));
return ws;
};
const readConnectChallengeNonce = async (ws: WebSocket) => {
const cached = getTrackedConnectChallengeNonce(ws);
if (cached) {
return cached;
}
const challenge = await onceMessage<{
type?: string;
event?: string;
payload?: Record<string, unknown> | null;
}>(ws, (o) => o.type === "event" && o.event === "connect.challenge");
const nonce = (challenge.payload as { nonce?: unknown } | undefined)?.nonce;
expect(typeof nonce).toBe("string");
return String(nonce);
};
const openTailscaleWs = async (port: number) => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
headers: {
origin: "https://gateway.tailnet.ts.net",
"x-forwarded-for": "100.64.0.1",
"x-forwarded-proto": "https",
"x-forwarded-host": "gateway.tailnet.ts.net",
"tailscale-user-login": "peter",
"tailscale-user-name": "Peter",
},
});
trackConnectChallengeNonce(ws);
await new Promise<void>((resolve) => ws.once("open", resolve));
return ws;
};
const originForPort = (port: number) => `http://127.0.0.1:${port}`;
function restoreGatewayToken(prevToken: string | undefined) {
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
}
async function withRuntimeVersionEnv<T>(
env: Record<string, string | undefined>,
run: () => Promise<T>,
): Promise<T> {
return withEnvAsync(env, run);
}
const TEST_OPERATOR_CLIENT = {
id: GATEWAY_CLIENT_NAMES.TEST,
version: "1.0.0",
platform: "test",
mode: GATEWAY_CLIENT_MODES.TEST,
};
const CONTROL_UI_CLIENT = {
id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
version: "1.0.0",
platform: "web",
mode: GATEWAY_CLIENT_MODES.WEBCHAT,
};
const TRUSTED_PROXY_CONTROL_UI_HEADERS = {
origin: "https://localhost",
"x-forwarded-for": "203.0.113.10",
"x-forwarded-proto": "https",
"x-forwarded-user": "peter@example.com",
} as const;
const NODE_CLIENT = {
id: GATEWAY_CLIENT_NAMES.NODE_HOST,
version: "1.0.0",
platform: "test",
mode: GATEWAY_CLIENT_MODES.NODE,
};
const BACKEND_GATEWAY_CLIENT = {
id: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
version: "1.0.0",
platform: "node",
mode: GATEWAY_CLIENT_MODES.BACKEND,
};
async function expectHelloOkServerVersion(port: number, expectedVersion: string) {
const ws = await openWs(port);
try {
const res = await connectReq(ws);
expect(res.ok).toBe(true);
const payload = res.payload as
| {
type?: unknown;
server?: { version?: string };
}
| undefined;
expect(payload?.type).toBe("hello-ok");
expect(payload?.server?.version).toBe(expectedVersion);
} finally {
ws.close();
}
}
async function createSignedDevice(params: {
token?: string | null;
scopes: string[];
clientId: string;
clientMode: string;
role?: "operator" | "node";
identityPath?: string;
nonce: string;
signedAtMs?: number;
}) {
const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
await import("../infra/device-identity.js");
const identity = params.identityPath
? loadOrCreateDeviceIdentity(params.identityPath)
: loadOrCreateDeviceIdentity();
const signedAtMs = params.signedAtMs ?? Date.now();
const payload = buildDeviceAuthPayload({
deviceId: identity.deviceId,
clientId: params.clientId,
clientMode: params.clientMode,
role: params.role ?? "operator",
scopes: params.scopes,
signedAtMs,
token: params.token ?? null,
nonce: params.nonce,
});
return {
identity,
signedAtMs,
device: {
id: identity.deviceId,
publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
signature: signDevicePayload(identity.privateKeyPem, payload),
signedAt: signedAtMs,
nonce: params.nonce,
},
};
}
function resolveGatewayTokenOrEnv(): string {
const token =
typeof (testState.gatewayAuth as { token?: unknown } | undefined)?.token === "string"
? ((testState.gatewayAuth as { token?: string }).token ?? undefined)
: process.env.OPENCLAW_GATEWAY_TOKEN;
expect(typeof token).toBe("string");
return String(token ?? "");
}
async function approvePendingPairingIfNeeded() {
const { approveDevicePairing, listDevicePairing } = await import("../infra/device-pairing.js");
const list = await listDevicePairing();
const pending = list.pending.at(0);
expect(pending?.requestId).toBeDefined();
if (pending?.requestId) {
await approveDevicePairing(pending.requestId);
}
}
async function configureTrustedProxyControlUiAuth() {
testState.gatewayAuth = {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-forwarded-user",
requiredHeaders: ["x-forwarded-proto"],
},
};
const { writeConfigFile } = await import("../config/config.js");
await writeConfigFile({
gateway: {
trustedProxies: ["127.0.0.1"],
controlUi: {
allowedOrigins: ["https://localhost"],
},
},
// oxlint-disable-next-line typescript/no-explicit-any
} as any);
}
function isConnectResMessage(id: string) {
return (o: unknown) => {
if (!o || typeof o !== "object" || Array.isArray(o)) {
return false;
}
const rec = o as Record<string, unknown>;
return rec.type === "res" && rec.id === id;
};
}
async function sendRawConnectReq(
ws: WebSocket,
params: {
id: string;
token?: string;
device: { id: string; publicKey: string; signature: string; signedAt: number; nonce?: string };
},
) {
ws.send(
JSON.stringify({
type: "req",
id: params.id,
method: "connect",
params: {
minProtocol: PROTOCOL_VERSION,
maxProtocol: PROTOCOL_VERSION,
client: TEST_OPERATOR_CLIENT,
caps: [],
role: "operator",
auth: params.token ? { token: params.token } : undefined,
device: params.device,
},
}),
);
return onceMessage<{
type?: string;
id?: string;
ok?: boolean;
payload?: Record<string, unknown> | null;
error?: {
message?: string;
details?: {
code?: string;
reason?: string;
};
};
}>(ws, isConnectResMessage(params.id));
}
async function startRateLimitedTokenServerWithPairedDeviceToken() {
const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js");
const { getPairedDevice } = await import("../infra/device-pairing.js");
testState.gatewayAuth = {
mode: "token",
token: "secret",
rateLimit: { maxAttempts: 1, windowMs: 60_000, lockoutMs: 60_000, exemptLoopback: false },
// oxlint-disable-next-line typescript/no-explicit-any
} as any;
const { server, ws, port, prevToken } = await startServerWithClient();
const deviceIdentityPath = path.join(
os.tmpdir(),
`openclaw-auth-rate-limit-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
);
try {
const initial = await connectReq(ws, { token: "secret", deviceIdentityPath });
if (!initial.ok) {
await approvePendingPairingIfNeeded();
}
const identity = loadOrCreateDeviceIdentity(deviceIdentityPath);
const paired = await getPairedDevice(identity.deviceId);
const deviceToken = paired?.tokens?.operator?.token;
expect(paired?.deviceId).toBe(identity.deviceId);
expect(deviceToken).toBeDefined();
ws.close();
return { server, port, prevToken, deviceToken: String(deviceToken ?? ""), deviceIdentityPath };
} catch (err) {
ws.close();
await server.close();
restoreGatewayToken(prevToken);
throw err;
}
}
async function ensurePairedDeviceTokenForCurrentIdentity(ws: WebSocket): Promise<{
identity: { deviceId: string };
deviceToken: string;
deviceIdentityPath: string;
}> {
const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js");
const { getPairedDevice } = await import("../infra/device-pairing.js");
const deviceIdentityPath = path.join(
os.tmpdir(),
`openclaw-auth-device-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
);
const res = await connectReq(ws, { token: "secret", deviceIdentityPath });
if (!res.ok) {
await approvePendingPairingIfNeeded();
}
const identity = loadOrCreateDeviceIdentity(deviceIdentityPath);
const paired = await getPairedDevice(identity.deviceId);
const deviceToken = paired?.tokens?.operator?.token;
expect(paired?.deviceId).toBe(identity.deviceId);
expect(deviceToken).toBeDefined();
return {
identity: { deviceId: identity.deviceId },
deviceToken: String(deviceToken ?? ""),
deviceIdentityPath,
};
}
describe("gateway server auth/connect", () => {
describe("default auth (token)", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
test("closes silent handshakes after timeout", async () => {
vi.useRealTimers();
const prevHandshakeTimeout = process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS;
process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = "20";
try {
const ws = await openWs(port);
const handshakeTimeoutMs = getHandshakeTimeoutMs();
const closed = await waitForWsClose(ws, handshakeTimeoutMs + 500);
expect(closed).toBe(true);
} finally {
if (prevHandshakeTimeout === undefined) {
delete process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS;
} else {
process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = prevHandshakeTimeout;
}
}
});
test("connect (req) handshake returns hello-ok payload", async () => {
const { CONFIG_PATH, STATE_DIR } = await import("../config/config.js");
const ws = await openWs(port);
const res = await connectReq(ws);
expect(res.ok).toBe(true);
const payload = res.payload as
| {
type?: unknown;
snapshot?: { configPath?: string; stateDir?: string };
}
| undefined;
expect(payload?.type).toBe("hello-ok");
expect(payload?.snapshot?.configPath).toBe(CONFIG_PATH);
expect(payload?.snapshot?.stateDir).toBe(STATE_DIR);
ws.close();
});
test("connect (req) handshake resolves server version from env precedence", async () => {
for (const testCase of [
{
env: {
OPENCLAW_VERSION: " ",
OPENCLAW_SERVICE_VERSION: "2.4.6-service",
npm_package_version: "1.0.0-package",
},
expectedVersion: "2.4.6-service",
},
{
env: {
OPENCLAW_VERSION: "9.9.9-cli",
OPENCLAW_SERVICE_VERSION: "2.4.6-service",
npm_package_version: "1.0.0-package",
},
expectedVersion: "9.9.9-cli",
},
{
env: {
OPENCLAW_VERSION: " ",
OPENCLAW_SERVICE_VERSION: "\t",
npm_package_version: "1.0.0-package",
},
expectedVersion: "1.0.0-package",
},
]) {
await withRuntimeVersionEnv(testCase.env, async () =>
expectHelloOkServerVersion(port, testCase.expectedVersion),
);
}
});
test("device-less auth matrix", async () => {
const token = resolveGatewayTokenOrEnv();
const matrix: Array<{
name: string;
opts: Parameters<typeof connectReq>[1];
expectConnectOk: boolean;
expectConnectError?: string;
expectStatusOk?: boolean;
expectStatusError?: string;
}> = [
{
name: "operator + valid shared token => connected with preserved scopes",
opts: { role: "operator", token, device: null },
expectConnectOk: true,
expectStatusOk: true,
},
{
name: "node + valid shared token => rejected without device",
opts: { role: "node", token, device: null, client: NODE_CLIENT },
expectConnectOk: false,
expectConnectError: "device identity required",
},
{
name: "operator + invalid shared token => unauthorized",
opts: { role: "operator", token: "wrong", device: null },
expectConnectOk: false,
expectConnectError: "unauthorized",
},
];
for (const scenario of matrix) {
const ws = await openWs(port);
try {
const res = await connectReq(ws, scenario.opts);
expect(res.ok, scenario.name).toBe(scenario.expectConnectOk);
if (!scenario.expectConnectOk) {
expect(res.error?.message ?? "", scenario.name).toContain(
String(scenario.expectConnectError ?? ""),
);
continue;
}
if (scenario.expectStatusOk !== undefined) {
const status = await rpcReq(ws, "status");
expect(status.ok, scenario.name).toBe(scenario.expectStatusOk);
if (!scenario.expectStatusOk && scenario.expectStatusError) {
expect(status.error?.message ?? "", scenario.name).toContain(
scenario.expectStatusError,
);
}
}
} finally {
ws.close();
}
}
});
test("keeps health available but admin status restricted when scopes are empty", async () => {
const ws = await openWs(port);
try {
const res = await connectReq(ws, { scopes: [] });
expect(res.ok).toBe(true);
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(false);
expect(status.error?.message).toContain("missing scope");
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
} finally {
ws.close();
}
});
test("does not grant admin when scopes are omitted", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { randomUUID } = await import("node:crypto");
const os = await import("node:os");
const path = await import("node:path");
// Fresh identity: avoid leaking prior scopes (presence merges lists).
const { identity, device } = await createSignedDevice({
token,
scopes: [],
clientId: GATEWAY_CLIENT_NAMES.TEST,
clientMode: GATEWAY_CLIENT_MODES.TEST,
identityPath: path.join(os.tmpdir(), `openclaw-test-device-${randomUUID()}.json`),
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-no-scopes",
token,
device,
});
expect(connectRes.ok).toBe(true);
const helloOk = connectRes.payload as
| {
snapshot?: {
presence?: Array<{ deviceId?: unknown; scopes?: unknown }>;
};
}
| undefined;
const presence = helloOk?.snapshot?.presence;
expect(Array.isArray(presence)).toBe(true);
const mine = presence?.find((entry) => entry.deviceId === identity.deviceId);
expect(mine).toBeTruthy();
const presenceScopes = Array.isArray(mine?.scopes) ? mine?.scopes : [];
expect(presenceScopes).toEqual([]);
expect(presenceScopes).not.toContain("operator.admin");
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(false);
expect(status.error?.message).toContain("missing scope");
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
ws.close();
});
test("rejects device signature when scopes are omitted but signed with admin", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: GATEWAY_CLIENT_NAMES.TEST,
clientMode: GATEWAY_CLIENT_MODES.TEST,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-no-scopes-signed-admin",
token,
device,
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device signature invalid");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_INVALID,
);
expect(connectRes.error?.details?.reason).toBe("device-signature");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("sends connect challenge on open", async () => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`);
const evtPromise = onceMessage<{
type?: string;
event?: string;
payload?: Record<string, unknown> | null;
}>(ws, (o) => o.type === "event" && o.event === "connect.challenge");
await new Promise<void>((resolve) => ws.once("open", resolve));
const evt = await evtPromise;
const nonce = (evt.payload as { nonce?: unknown } | undefined)?.nonce;
expect(typeof nonce).toBe("string");
ws.close();
});
test("rejects protocol mismatch", async () => {
const ws = await openWs(port);
try {
const res = await connectReq(ws, {
minProtocol: PROTOCOL_VERSION + 1,
maxProtocol: PROTOCOL_VERSION + 2,
});
expect(res.ok).toBe(false);
} catch {
// If the server closed before we saw the frame, that's acceptable.
}
ws.close();
});
test("rejects non-connect first request", async () => {
const ws = await openWs(port);
ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
const res = await onceMessage<{ type?: string; id?: string; ok?: boolean; error?: unknown }>(
ws,
(o) => o.type === "res" && o.id === "h1",
);
expect(res.ok).toBe(false);
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("requires nonce for device auth", async () => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
headers: { host: "example.com" },
});
await new Promise<void>((resolve) => ws.once("open", resolve));
const { device } = await createSignedDevice({
token: "secret",
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce: "nonce-not-sent",
});
const { nonce: _nonce, ...deviceWithoutNonce } = device;
const res = await connectReq(ws, {
token: "secret",
device: deviceWithoutNonce,
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("must have required property 'nonce'");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("returns nonce-required detail code when nonce is blank", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-blank-nonce",
token,
device: { ...device, nonce: " " },
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device nonce required");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_REQUIRED,
);
expect(connectRes.error?.details?.reason).toBe("device-nonce-missing");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("returns nonce-mismatch detail code when nonce does not match challenge", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-wrong-nonce",
token,
device: { ...device, nonce: `${nonce}-stale` },
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device nonce mismatch");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_MISMATCH,
);
expect(connectRes.error?.details?.reason).toBe("device-nonce-mismatch");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("invalid connect params surface in response and close reason", async () => {
const ws = await openWs(port);
const closeInfoPromise = new Promise<{ code: number; reason: string }>((resolve) => {
ws.once("close", (code, reason) => resolve({ code, reason: reason.toString() }));
});
ws.send(
JSON.stringify({
type: "req",
id: "h-bad",
method: "connect",
params: {
minProtocol: PROTOCOL_VERSION,
maxProtocol: PROTOCOL_VERSION,
client: {
id: "bad-client",
version: "dev",
platform: "web",
mode: "webchat",
},
device: {
id: 123,
publicKey: "bad",
signature: "bad",
signedAt: "bad",
},
},
}),
);
const res = await onceMessage<{
ok: boolean;
error?: { message?: string };
}>(
ws,
(o) => (o as { type?: string }).type === "res" && (o as { id?: string }).id === "h-bad",
);
expect(res.ok).toBe(false);
expect(String(res.error?.message ?? "")).toContain("invalid connect params");
const closeInfo = await closeInfoPromise;
expect(closeInfo.code).toBe(1008);
expect(closeInfo.reason).toContain("invalid connect params");
});
});
describe("password auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
testState.gatewayAuth = { mode: "password", password: "secret" };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
test("accepts password auth when configured", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { password: "secret" });
expect(res.ok).toBe(true);
ws.close();
});
test("rejects invalid password", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { password: "wrong" });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("unauthorized");
ws.close();
});
});
describe("token auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
let prevToken: string | undefined;
beforeAll(async () => {
prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
});
test("rejects invalid token", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { token: "wrong" });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("unauthorized");
ws.close();
});
test("returns control ui hint when token is missing", async () => {
const ws = await openWs(port, { origin: originForPort(port) });
const res = await connectReq(ws, {
skipDefaultAuth: true,
client: {
...CONTROL_UI_CLIENT,
},
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("Control UI settings");
ws.close();
});
test("rejects control ui without device identity by default", async () => {
const ws = await openWs(port, { origin: originForPort(port) });
const res = await connectReq(ws, {
token: "secret",
device: null,
client: {
...CONTROL_UI_CLIENT,
},
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("secure context");
expect((res.error?.details as { code?: string } | undefined)?.code).toBe(
ConnectErrorDetailCodes.CONTROL_UI_DEVICE_IDENTITY_REQUIRED,
);
ws.close();
});
});
describe("explicit none auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
let prevToken: string | undefined;
beforeAll(async () => {
prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
delete process.env.OPENCLAW_GATEWAY_TOKEN;
testState.gatewayAuth = { mode: "none" };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
});
test("allows loopback connect without shared secret when mode is none", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { skipDefaultAuth: true });
expect(res.ok).toBe(true);
ws.close();
});
});
describe("tailscale auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
testState.gatewayAuth = { mode: "token", token: "secret", allowTailscale: true };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
beforeEach(() => {
testTailscaleWhois.value = { login: "peter", name: "Peter" };
});
afterEach(() => {
testTailscaleWhois.value = null;
});
test("requires device identity when only tailscale auth is available", async () => {
const ws = await openTailscaleWs(port);
const res = await connectReq(ws, { token: "dummy", device: null });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("device identity required");
ws.close();
});
test("allows shared token to skip device when tailscale auth is enabled", async () => {
const ws = await openTailscaleWs(port);
const res = await connectReq(ws, { token: "secret", device: null });
expect(res.ok).toBe(true);
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(true);
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
ws.close();
});
});
writeTrustedProxyControlUiConfig,
} from "./server.auth.shared.js";
export function registerControlUiAndPairingSuite(): void {
const trustedProxyControlUiCases: Array<{
name: string;
role: "operator" | "node";
@@ -1031,16 +166,7 @@ describe("gateway server auth/connect", () => {
allowedOrigins: ["https://localhost"],
};
testState.gatewayAuth = { mode: "token", token: "secret" };
const { writeConfigFile } = await import("../config/config.js");
await writeConfigFile({
gateway: {
trustedProxies: ["127.0.0.1"],
controlUi: {
allowedOrigins: ["https://localhost"],
},
},
// oxlint-disable-next-line typescript/no-explicit-any
} as any);
await writeTrustedProxyControlUiConfig({ allowInsecureAuth: true });
const prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
try {
@@ -1839,6 +965,4 @@ describe("gateway server auth/connect", () => {
restoreGatewayToken(prevToken);
}
});
// Remaining tests require isolated gateway state.
});
}

9
src/gateway/server.auth.control-ui.test.ts Normal file
View File

@@ -0,0 +1,9 @@
import { describe } from "vitest";
import { registerControlUiAndPairingSuite } from "./server.auth.control-ui.suite.js";
import { installGatewayTestHooks } from "./server.auth.shared.js";
installGatewayTestHooks({ scope: "suite" });
describe("gateway server auth/connect", () => {
registerControlUiAndPairingSuite();
});

415
src/gateway/server.auth.default-token.suite.ts Normal file
View File

@@ -0,0 +1,415 @@
import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
import { WebSocket } from "ws";
import {
connectReq,
ConnectErrorDetailCodes,
createSignedDevice,
expectHelloOkServerVersion,
getFreePort,
getHandshakeTimeoutMs,
GATEWAY_CLIENT_MODES,
GATEWAY_CLIENT_NAMES,
NODE_CLIENT,
onceMessage,
openWs,
PROTOCOL_VERSION,
readConnectChallengeNonce,
resolveGatewayTokenOrEnv,
rpcReq,
sendRawConnectReq,
startGatewayServer,
TEST_OPERATOR_CLIENT,
waitForWsClose,
withRuntimeVersionEnv,
} from "./server.auth.shared.js";
export function registerDefaultAuthTokenSuite(): void {
describe("default auth (token)", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
test("closes silent handshakes after timeout", async () => {
vi.useRealTimers();
const prevHandshakeTimeout = process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS;
process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = "20";
try {
const ws = await openWs(port);
const handshakeTimeoutMs = getHandshakeTimeoutMs();
const closed = await waitForWsClose(ws, handshakeTimeoutMs + 500);
expect(closed).toBe(true);
} finally {
if (prevHandshakeTimeout === undefined) {
delete process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS;
} else {
process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = prevHandshakeTimeout;
}
}
});
test("connect (req) handshake returns hello-ok payload", async () => {
const { CONFIG_PATH, STATE_DIR } = await import("../config/config.js");
const ws = await openWs(port);
const res = await connectReq(ws);
expect(res.ok).toBe(true);
const payload = res.payload as
| {
type?: unknown;
snapshot?: { configPath?: string; stateDir?: string };
}
| undefined;
expect(payload?.type).toBe("hello-ok");
expect(payload?.snapshot?.configPath).toBe(CONFIG_PATH);
expect(payload?.snapshot?.stateDir).toBe(STATE_DIR);
ws.close();
});
test("connect (req) handshake resolves server version from env precedence", async () => {
for (const testCase of [
{
env: {
OPENCLAW_VERSION: " ",
OPENCLAW_SERVICE_VERSION: "2.4.6-service",
npm_package_version: "1.0.0-package",
},
expectedVersion: "2.4.6-service",
},
{
env: {
OPENCLAW_VERSION: "9.9.9-cli",
OPENCLAW_SERVICE_VERSION: "2.4.6-service",
npm_package_version: "1.0.0-package",
},
expectedVersion: "9.9.9-cli",
},
{
env: {
OPENCLAW_VERSION: " ",
OPENCLAW_SERVICE_VERSION: "\t",
npm_package_version: "1.0.0-package",
},
expectedVersion: "1.0.0-package",
},
]) {
await withRuntimeVersionEnv(testCase.env, async () =>
expectHelloOkServerVersion(port, testCase.expectedVersion),
);
}
});
test("device-less auth matrix", async () => {
const token = resolveGatewayTokenOrEnv();
const matrix: Array<{
name: string;
opts: Parameters<typeof connectReq>[1];
expectConnectOk: boolean;
expectConnectError?: string;
expectStatusOk?: boolean;
expectStatusError?: string;
}> = [
{
name: "operator + valid shared token => connected with preserved scopes",
opts: { role: "operator", token, device: null },
expectConnectOk: true,
expectStatusOk: true,
},
{
name: "node + valid shared token => rejected without device",
opts: { role: "node", token, device: null, client: NODE_CLIENT },
expectConnectOk: false,
expectConnectError: "device identity required",
},
{
name: "operator + invalid shared token => unauthorized",
opts: { role: "operator", token: "wrong", device: null },
expectConnectOk: false,
expectConnectError: "unauthorized",
},
];
for (const scenario of matrix) {
const ws = await openWs(port);
try {
const res = await connectReq(ws, scenario.opts);
expect(res.ok, scenario.name).toBe(scenario.expectConnectOk);
if (!scenario.expectConnectOk) {
expect(res.error?.message ?? "", scenario.name).toContain(
String(scenario.expectConnectError ?? ""),
);
continue;
}
if (scenario.expectStatusOk !== undefined) {
const status = await rpcReq(ws, "status");
expect(status.ok, scenario.name).toBe(scenario.expectStatusOk);
if (!scenario.expectStatusOk && scenario.expectStatusError) {
expect(status.error?.message ?? "", scenario.name).toContain(
scenario.expectStatusError,
);
}
}
} finally {
ws.close();
}
}
});
test("keeps health available but admin status restricted when scopes are empty", async () => {
const ws = await openWs(port);
try {
const res = await connectReq(ws, { scopes: [] });
expect(res.ok).toBe(true);
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(false);
expect(status.error?.message).toContain("missing scope");
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
} finally {
ws.close();
}
});
test("does not grant admin when scopes are omitted", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { randomUUID } = await import("node:crypto");
const os = await import("node:os");
const path = await import("node:path");
// Fresh identity: avoid leaking prior scopes (presence merges lists).
const { identity, device } = await createSignedDevice({
token,
scopes: [],
clientId: GATEWAY_CLIENT_NAMES.TEST,
clientMode: GATEWAY_CLIENT_MODES.TEST,
identityPath: path.join(os.tmpdir(), `openclaw-test-device-${randomUUID()}.json`),
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-no-scopes",
token,
device,
});
expect(connectRes.ok).toBe(true);
const helloOk = connectRes.payload as
| {
snapshot?: {
presence?: Array<{ deviceId?: unknown; scopes?: unknown }>;
};
}
| undefined;
const presence = helloOk?.snapshot?.presence;
expect(Array.isArray(presence)).toBe(true);
const mine = presence?.find((entry) => entry.deviceId === identity.deviceId);
expect(mine).toBeTruthy();
const presenceScopes = Array.isArray(mine?.scopes) ? mine?.scopes : [];
expect(presenceScopes).toEqual([]);
expect(presenceScopes).not.toContain("operator.admin");
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(false);
expect(status.error?.message).toContain("missing scope");
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
ws.close();
});
test("rejects device signature when scopes are omitted but signed with admin", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: GATEWAY_CLIENT_NAMES.TEST,
clientMode: GATEWAY_CLIENT_MODES.TEST,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-no-scopes-signed-admin",
token,
device,
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device signature invalid");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_INVALID,
);
expect(connectRes.error?.details?.reason).toBe("device-signature");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("sends connect challenge on open", async () => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`);
const evtPromise = onceMessage<{
type?: string;
event?: string;
payload?: Record<string, unknown> | null;
}>(ws, (o) => o.type === "event" && o.event === "connect.challenge");
await new Promise<void>((resolve) => ws.once("open", resolve));
const evt = await evtPromise;
const nonce = (evt.payload as { nonce?: unknown } | undefined)?.nonce;
expect(typeof nonce).toBe("string");
ws.close();
});
test("rejects protocol mismatch", async () => {
const ws = await openWs(port);
try {
const res = await connectReq(ws, {
minProtocol: PROTOCOL_VERSION + 1,
maxProtocol: PROTOCOL_VERSION + 2,
});
expect(res.ok).toBe(false);
} catch {
// If the server closed before we saw the frame, that's acceptable.
}
ws.close();
});
test("rejects non-connect first request", async () => {
const ws = await openWs(port);
ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
const res = await onceMessage<{ type?: string; id?: string; ok?: boolean; error?: unknown }>(
ws,
(o) => o.type === "res" && o.id === "h1",
);
expect(res.ok).toBe(false);
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("requires nonce for device auth", async () => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
headers: { host: "example.com" },
});
await new Promise<void>((resolve) => ws.once("open", resolve));
const { device } = await createSignedDevice({
token: "secret",
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce: "nonce-not-sent",
});
const { nonce: _nonce, ...deviceWithoutNonce } = device;
const res = await connectReq(ws, {
token: "secret",
device: deviceWithoutNonce,
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("must have required property 'nonce'");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("returns nonce-required detail code when nonce is blank", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-blank-nonce",
token,
device: { ...device, nonce: " " },
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device nonce required");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_REQUIRED,
);
expect(connectRes.error?.details?.reason).toBe("device-nonce-missing");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("returns nonce-mismatch detail code when nonce does not match challenge", async () => {
const ws = await openWs(port);
const token = resolveGatewayTokenOrEnv();
const nonce = await readConnectChallengeNonce(ws);
const { device } = await createSignedDevice({
token,
scopes: ["operator.admin"],
clientId: TEST_OPERATOR_CLIENT.id,
clientMode: TEST_OPERATOR_CLIENT.mode,
nonce,
});
const connectRes = await sendRawConnectReq(ws, {
id: "c-wrong-nonce",
token,
device: { ...device, nonce: `${nonce}-stale` },
});
expect(connectRes.ok).toBe(false);
expect(connectRes.error?.message ?? "").toContain("device nonce mismatch");
expect(connectRes.error?.details?.code).toBe(
ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_MISMATCH,
);
expect(connectRes.error?.details?.reason).toBe("device-nonce-mismatch");
await new Promise<void>((resolve) => ws.once("close", () => resolve()));
});
test("invalid connect params surface in response and close reason", async () => {
const ws = await openWs(port);
const closeInfoPromise = new Promise<{ code: number; reason: string }>((resolve) => {
ws.once("close", (code, reason) => resolve({ code, reason: reason.toString() }));
});
ws.send(
JSON.stringify({
type: "req",
id: "h-bad",
method: "connect",
params: {
minProtocol: PROTOCOL_VERSION,
maxProtocol: PROTOCOL_VERSION,
client: {
id: "bad-client",
version: "dev",
platform: "web",
mode: "webchat",
},
device: {
id: 123,
publicKey: "bad",
signature: "bad",
signedAt: "bad",
},
},
}),
);
const res = await onceMessage<{
ok: boolean;
error?: { message?: string };
}>(
ws,
(o) => (o as { type?: string }).type === "res" && (o as { id?: string }).id === "h-bad",
);
expect(res.ok).toBe(false);
expect(String(res.error?.message ?? "")).toContain("invalid connect params");
const closeInfo = await closeInfoPromise;
expect(closeInfo.code).toBe(1008);
expect(closeInfo.reason).toContain("invalid connect params");
});
});
}

9
src/gateway/server.auth.default-token.test.ts Normal file
View File

@@ -0,0 +1,9 @@
import { describe } from "vitest";
import { registerDefaultAuthTokenSuite } from "./server.auth.default-token.suite.js";
import { installGatewayTestHooks } from "./server.auth.shared.js";
installGatewayTestHooks({ scope: "suite" });
describe("gateway server auth/connect", () => {
registerDefaultAuthTokenSuite();
});

178
src/gateway/server.auth.modes.suite.ts Normal file
View File

@@ -0,0 +1,178 @@
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "vitest";
import {
connectReq,
CONTROL_UI_CLIENT,
ConnectErrorDetailCodes,
getFreePort,
openTailscaleWs,
openWs,
originForPort,
rpcReq,
startGatewayServer,
testState,
testTailscaleWhois,
} from "./server.auth.shared.js";
export function registerAuthModesSuite(): void {
describe("password auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
testState.gatewayAuth = { mode: "password", password: "secret" };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
test("accepts password auth when configured", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { password: "secret" });
expect(res.ok).toBe(true);
ws.close();
});
test("rejects invalid password", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { password: "wrong" });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("unauthorized");
ws.close();
});
});
describe("token auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
let prevToken: string | undefined;
beforeAll(async () => {
prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
});
test("rejects invalid token", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { token: "wrong" });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("unauthorized");
ws.close();
});
test("returns control ui hint when token is missing", async () => {
const ws = await openWs(port, { origin: originForPort(port) });
const res = await connectReq(ws, {
skipDefaultAuth: true,
client: {
...CONTROL_UI_CLIENT,
},
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("Control UI settings");
ws.close();
});
test("rejects control ui without device identity by default", async () => {
const ws = await openWs(port, { origin: originForPort(port) });
const res = await connectReq(ws, {
token: "secret",
device: null,
client: {
...CONTROL_UI_CLIENT,
},
});
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("secure context");
expect((res.error?.details as { code?: string } | undefined)?.code).toBe(
ConnectErrorDetailCodes.CONTROL_UI_DEVICE_IDENTITY_REQUIRED,
);
ws.close();
});
});
describe("explicit none auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
let prevToken: string | undefined;
beforeAll(async () => {
prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
delete process.env.OPENCLAW_GATEWAY_TOKEN;
testState.gatewayAuth = { mode: "none" };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
});
test("allows loopback connect without shared secret when mode is none", async () => {
const ws = await openWs(port);
const res = await connectReq(ws, { skipDefaultAuth: true });
expect(res.ok).toBe(true);
ws.close();
});
});
describe("tailscale auth", () => {
let server: Awaited<ReturnType<typeof startGatewayServer>>;
let port: number;
beforeAll(async () => {
testState.gatewayAuth = { mode: "token", token: "secret", allowTailscale: true };
port = await getFreePort();
server = await startGatewayServer(port);
});
afterAll(async () => {
await server.close();
});
beforeEach(() => {
testTailscaleWhois.value = { login: "peter", name: "Peter" };
});
afterEach(() => {
testTailscaleWhois.value = null;
});
test("requires device identity when only tailscale auth is available", async () => {
const ws = await openTailscaleWs(port);
const res = await connectReq(ws, { token: "dummy", device: null });
expect(res.ok).toBe(false);
expect(res.error?.message ?? "").toContain("device identity required");
ws.close();
});
test("allows shared token to skip device when tailscale auth is enabled", async () => {
const ws = await openTailscaleWs(port);
const res = await connectReq(ws, { token: "secret", device: null });
expect(res.ok).toBe(true);
const status = await rpcReq(ws, "status");
expect(status.ok).toBe(true);
const health = await rpcReq(ws, "health");
expect(health.ok).toBe(true);
ws.close();
});
});
}

9
src/gateway/server.auth.modes.test.ts Normal file
View File

@@ -0,0 +1,9 @@
import { describe } from "vitest";
import { registerAuthModesSuite } from "./server.auth.modes.suite.js";
import { installGatewayTestHooks } from "./server.auth.shared.js";
installGatewayTestHooks({ scope: "suite" });
describe("gateway server auth/connect", () => {
registerAuthModesSuite();
});

384
src/gateway/server.auth.shared.ts Normal file
View File

@@ -0,0 +1,384 @@
import os from "node:os";
import path from "node:path";
import { expect } from "vitest";
import { WebSocket } from "ws";
import { withEnvAsync } from "../test-utils/env.js";
import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
import { buildDeviceAuthPayload } from "./device-auth.js";
import { PROTOCOL_VERSION } from "./protocol/index.js";
import {
connectReq,
getTrackedConnectChallengeNonce,
getFreePort,
installGatewayTestHooks,
onceMessage,
rpcReq,
startGatewayServer,
startServerWithClient,
trackConnectChallengeNonce,
testTailscaleWhois,
testState,
withGatewayServer,
} from "./test-helpers.js";
async function waitForWsClose(ws: WebSocket, timeoutMs: number): Promise<boolean> {
if (ws.readyState === WebSocket.CLOSED) {
return true;
}
return await new Promise((resolve) => {
const timer = setTimeout(() => resolve(ws.readyState === WebSocket.CLOSED), timeoutMs);
ws.once("close", () => {
clearTimeout(timer);
resolve(true);
});
});
}
const openWs = async (port: number, headers?: Record<string, string>) => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, headers ? { headers } : undefined);
trackConnectChallengeNonce(ws);
await new Promise<void>((resolve) => ws.once("open", resolve));
return ws;
};
const readConnectChallengeNonce = async (ws: WebSocket) => {
const cached = getTrackedConnectChallengeNonce(ws);
if (cached) {
return cached;
}
const challenge = await onceMessage<{
type?: string;
event?: string;
payload?: Record<string, unknown> | null;
}>(ws, (o) => o.type === "event" && o.event === "connect.challenge");
const nonce = (challenge.payload as { nonce?: unknown } | undefined)?.nonce;
expect(typeof nonce).toBe("string");
return String(nonce);
};
const openTailscaleWs = async (port: number) => {
const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
headers: {
origin: "https://gateway.tailnet.ts.net",
"x-forwarded-for": "100.64.0.1",
"x-forwarded-proto": "https",
"x-forwarded-host": "gateway.tailnet.ts.net",
"tailscale-user-login": "peter",
"tailscale-user-name": "Peter",
},
});
trackConnectChallengeNonce(ws);
await new Promise<void>((resolve) => ws.once("open", resolve));
return ws;
};
const originForPort = (port: number) => `http://127.0.0.1:${port}`;
function restoreGatewayToken(prevToken: string | undefined) {
if (prevToken === undefined) {
delete process.env.OPENCLAW_GATEWAY_TOKEN;
} else {
process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
}
}
async function withRuntimeVersionEnv<T>(
env: Record<string, string | undefined>,
run: () => Promise<T>,
): Promise<T> {
return withEnvAsync(env, run);
}
const TEST_OPERATOR_CLIENT = {
id: GATEWAY_CLIENT_NAMES.TEST,
version: "1.0.0",
platform: "test",
mode: GATEWAY_CLIENT_MODES.TEST,
};
const CONTROL_UI_CLIENT = {
id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
version: "1.0.0",
platform: "web",
mode: GATEWAY_CLIENT_MODES.WEBCHAT,
};
const TRUSTED_PROXY_CONTROL_UI_HEADERS = {
origin: "https://localhost",
"x-forwarded-for": "203.0.113.10",
"x-forwarded-proto": "https",
"x-forwarded-user": "peter@example.com",
} as const;
const NODE_CLIENT = {
id: GATEWAY_CLIENT_NAMES.NODE_HOST,
version: "1.0.0",
platform: "test",
mode: GATEWAY_CLIENT_MODES.NODE,
};
const BACKEND_GATEWAY_CLIENT = {
id: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
version: "1.0.0",
platform: "node",
mode: GATEWAY_CLIENT_MODES.BACKEND,
};
async function expectHelloOkServerVersion(port: number, expectedVersion: string) {
const ws = await openWs(port);
try {
const res = await connectReq(ws);
expect(res.ok).toBe(true);
const payload = res.payload as
| {
type?: unknown;
server?: { version?: string };
}
| undefined;
expect(payload?.type).toBe("hello-ok");
expect(payload?.server?.version).toBe(expectedVersion);
} finally {
ws.close();
}
}
async function createSignedDevice(params: {
token?: string | null;
scopes: string[];
clientId: string;
clientMode: string;
role?: "operator" | "node";
identityPath?: string;
nonce: string;
signedAtMs?: number;
}) {
const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
await import("../infra/device-identity.js");
const identity = params.identityPath
? loadOrCreateDeviceIdentity(params.identityPath)
: loadOrCreateDeviceIdentity();
const signedAtMs = params.signedAtMs ?? Date.now();
const payload = buildDeviceAuthPayload({
deviceId: identity.deviceId,
clientId: params.clientId,
clientMode: params.clientMode,
role: params.role ?? "operator",
scopes: params.scopes,
signedAtMs,
token: params.token ?? null,
nonce: params.nonce,
});
return {
identity,
signedAtMs,
device: {
id: identity.deviceId,
publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
signature: signDevicePayload(identity.privateKeyPem, payload),
signedAt: signedAtMs,
nonce: params.nonce,
},
};
}
function resolveGatewayTokenOrEnv(): string {
const token =
typeof (testState.gatewayAuth as { token?: unknown } | undefined)?.token === "string"
? ((testState.gatewayAuth as { token?: string }).token ?? undefined)
: process.env.OPENCLAW_GATEWAY_TOKEN;
expect(typeof token).toBe("string");
return String(token ?? "");
}
async function approvePendingPairingIfNeeded() {
const { approveDevicePairing, listDevicePairing } = await import("../infra/device-pairing.js");
const list = await listDevicePairing();
const pending = list.pending.at(0);
expect(pending?.requestId).toBeDefined();
if (pending?.requestId) {
await approveDevicePairing(pending.requestId);
}
}
async function configureTrustedProxyControlUiAuth() {
testState.gatewayAuth = {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-forwarded-user",
requiredHeaders: ["x-forwarded-proto"],
},
};
await writeTrustedProxyControlUiConfig();
}
async function writeTrustedProxyControlUiConfig(params?: { allowInsecureAuth?: boolean }) {
const { writeConfigFile } = await import("../config/config.js");
await writeConfigFile({
gateway: {
trustedProxies: ["127.0.0.1"],
controlUi: {
allowedOrigins: ["https://localhost"],
...(params?.allowInsecureAuth ? { allowInsecureAuth: true } : {}),
},
},
// oxlint-disable-next-line typescript/no-explicit-any
} as any);
}
function isConnectResMessage(id: string) {
return (o: unknown) => {
if (!o || typeof o !== "object" || Array.isArray(o)) {
return false;
}
const rec = o as Record<string, unknown>;
return rec.type === "res" && rec.id === id;
};
}
async function sendRawConnectReq(
ws: WebSocket,
params: {
id: string;
token?: string;
device: { id: string; publicKey: string; signature: string; signedAt: number; nonce?: string };
},
) {
ws.send(
JSON.stringify({
type: "req",
id: params.id,
method: "connect",
params: {
minProtocol: PROTOCOL_VERSION,
maxProtocol: PROTOCOL_VERSION,
client: TEST_OPERATOR_CLIENT,
caps: [],
role: "operator",
auth: params.token ? { token: params.token } : undefined,
device: params.device,
},
}),
);
return onceMessage<{
type?: string;
id?: string;
ok?: boolean;
payload?: Record<string, unknown> | null;
error?: {
message?: string;
details?: {
code?: string;
reason?: string;
};
};
}>(ws, isConnectResMessage(params.id));
}
async function startRateLimitedTokenServerWithPairedDeviceToken() {
const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js");
const { getPairedDevice } = await import("../infra/device-pairing.js");
testState.gatewayAuth = {
mode: "token",
token: "secret",
rateLimit: { maxAttempts: 1, windowMs: 60_000, lockoutMs: 60_000, exemptLoopback: false },
// oxlint-disable-next-line typescript/no-explicit-any
} as any;
const { server, ws, port, prevToken } = await startServerWithClient();
const deviceIdentityPath = path.join(
os.tmpdir(),
`openclaw-auth-rate-limit-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
);
try {
const initial = await connectReq(ws, { token: "secret", deviceIdentityPath });
if (!initial.ok) {
await approvePendingPairingIfNeeded();
}
const identity = loadOrCreateDeviceIdentity(deviceIdentityPath);
const paired = await getPairedDevice(identity.deviceId);
const deviceToken = paired?.tokens?.operator?.token;
expect(paired?.deviceId).toBe(identity.deviceId);
expect(deviceToken).toBeDefined();
ws.close();
return { server, port, prevToken, deviceToken: String(deviceToken ?? ""), deviceIdentityPath };
} catch (err) {
ws.close();
await server.close();
restoreGatewayToken(prevToken);
throw err;
}
}
async function ensurePairedDeviceTokenForCurrentIdentity(ws: WebSocket): Promise<{
identity: { deviceId: string };
deviceToken: string;
deviceIdentityPath: string;
}> {
const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js");
const { getPairedDevice } = await import("../infra/device-pairing.js");
const deviceIdentityPath = path.join(
os.tmpdir(),
`openclaw-auth-device-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
);
const res = await connectReq(ws, { token: "secret", deviceIdentityPath });
if (!res.ok) {
await approvePendingPairingIfNeeded();
}
const identity = loadOrCreateDeviceIdentity(deviceIdentityPath);
const paired = await getPairedDevice(identity.deviceId);
const deviceToken = paired?.tokens?.operator?.token;
expect(paired?.deviceId).toBe(identity.deviceId);
expect(deviceToken).toBeDefined();
return {
identity: { deviceId: identity.deviceId },
deviceToken: String(deviceToken ?? ""),
deviceIdentityPath,
};
}
export {
approvePendingPairingIfNeeded,
BACKEND_GATEWAY_CLIENT,
buildDeviceAuthPayload,
configureTrustedProxyControlUiAuth,
connectReq,
CONTROL_UI_CLIENT,
createSignedDevice,
ensurePairedDeviceTokenForCurrentIdentity,
expectHelloOkServerVersion,
getFreePort,
getTrackedConnectChallengeNonce,
installGatewayTestHooks,
NODE_CLIENT,
onceMessage,
openTailscaleWs,
openWs,
originForPort,
readConnectChallengeNonce,
resolveGatewayTokenOrEnv,
restoreGatewayToken,
rpcReq,
sendRawConnectReq,
startGatewayServer,
startRateLimitedTokenServerWithPairedDeviceToken,
startServerWithClient,
TEST_OPERATOR_CLIENT,
trackConnectChallengeNonce,
TRUSTED_PROXY_CONTROL_UI_HEADERS,
testState,
testTailscaleWhois,
waitForWsClose,
withGatewayServer,
withRuntimeVersionEnv,
writeTrustedProxyControlUiConfig,
};
export { ConnectErrorDetailCodes } from "./protocol/connect-error-details.js";
export { getHandshakeTimeoutMs } from "./server-constants.js";
export { PROTOCOL_VERSION } from "./protocol/index.js";
export { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";

111
src/infra/archive.ts
View File

@@ -1,4 +1,3 @@
import { constants as fsConstants } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import fs from "node:fs/promises";
import path from "node:path";
@@ -11,9 +10,8 @@ import {
stripArchivePath,
validateArchiveEntryPath,
} from "./archive-path.js";
import { sameFileIdentity } from "./file-identity.js";
import { resolveOpenedFileRealPathForHandle } from "./fs-safe.js";
import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path-guards.js";
import { openWritableFileWithinRoot, SafeOpenError } from "./fs-safe.js";
import { isNotFoundPathError, isPathInside } from "./path-guards.js";
export type ArchiveKind = "tar" | "zip";
@@ -67,14 +65,6 @@ const ERROR_ARCHIVE_EXTRACTED_SIZE_EXCEEDS_LIMIT = "archive extracted size excee
const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
const TAR_SUFFIXES = [".tgz", ".tar.gz", ".tar"];
const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
const OPEN_WRITE_EXISTING_FLAGS =
fsConstants.O_WRONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
const OPEN_WRITE_CREATE_FLAGS =
fsConstants.O_WRONLY |
fsConstants.O_CREAT |
fsConstants.O_EXCL |
(SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
export function resolveArchiveKind(filePath: string): ArchiveKind | null {
const lower = filePath.toLowerCase();
@@ -288,93 +278,28 @@ type OpenZipOutputFileResult = {
};
async function openZipOutputFile(params: {
outPath: string;
relPath: string;
originalPath: string;
destinationRealDir: string;
}): Promise<OpenZipOutputFileResult> {
let ioPath = params.outPath;
try {
const resolvedRealPath = await fs.realpath(params.outPath);
if (!isPathInside(params.destinationRealDir, resolvedRealPath)) {
throw symlinkTraversalError(params.originalPath);
}
ioPath = resolvedRealPath;
return await openWritableFileWithinRoot({
rootDir: params.destinationRealDir,
relativePath: params.relPath,
mkdir: false,
mode: 0o666,
});
} catch (err) {
if (err instanceof ArchiveSecurityError) {
throw err;
}
if (!isNotFoundPathError(err)) {
throw err;
}
}
let handle: FileHandle;
let createdForWrite = false;
try {
try {
handle = await fs.open(ioPath, OPEN_WRITE_EXISTING_FLAGS, 0o666);
} catch (err) {
if (!isNotFoundPathError(err)) {
throw err;
}
handle = await fs.open(ioPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
createdForWrite = true;
}
} catch (err) {
if (isSymlinkOpenError(err)) {
if (
err instanceof SafeOpenError &&
(err.code === "invalid-path" ||
err.code === "outside-workspace" ||
err.code === "path-mismatch")
) {
throw symlinkTraversalError(params.originalPath);
}
throw err;
}
let openedRealPath: string | null = null;
try {
const stat = await handle.stat();
if (!stat.isFile()) {
throw symlinkTraversalError(params.originalPath);
}
try {
const lstat = await fs.lstat(ioPath);
if (lstat.isSymbolicLink() || !lstat.isFile()) {
throw symlinkTraversalError(params.originalPath);
}
if (!sameFileIdentity(stat, lstat)) {
throw symlinkTraversalError(params.originalPath);
}
} catch (err) {
if (!isNotFoundPathError(err)) {
throw err;
}
}
const realPath = await resolveOpenedFileRealPathForHandle(handle, ioPath);
openedRealPath = realPath;
const realStat = await fs.stat(realPath);
if (!sameFileIdentity(stat, realStat)) {
throw symlinkTraversalError(params.originalPath);
}
if (!isPathInside(params.destinationRealDir, realPath)) {
throw symlinkTraversalError(params.originalPath);
}
// Truncate only after identity + boundary checks complete.
if (!createdForWrite) {
await handle.truncate(0);
}
return {
handle,
createdForWrite,
openedRealPath: realPath,
};
} catch (err) {
if (createdForWrite && openedRealPath) {
await fs.rm(openedRealPath, { force: true }).catch(() => undefined);
}
await handle.close().catch(() => undefined);
throw err;
}
}
async function cleanupPartialRegularFile(filePath: string): Promise<void> {
@@ -467,12 +392,12 @@ async function prepareZipOutputPath(params: {
async function writeZipFileEntry(params: {
entry: ZipEntry;
outPath: string;
relPath: string;
destinationRealDir: string;
budget: ZipExtractBudget;
}): Promise<void> {
const opened = await openZipOutputFile({
outPath: params.outPath,
relPath: params.relPath,
originalPath: params.entry.name,
destinationRealDir: params.destinationRealDir,
});
@@ -558,7 +483,7 @@ async function extractZip(params: {
await writeZipFileEntry({
entry,
outPath: output.outPath,
relPath: output.relPath,
destinationRealDir,
budget,
});

7
src/infra/fs-safe.ts
View File

@@ -321,6 +321,7 @@ export async function openWritableFileWithinRoot(params: {
rootDir: string;
relativePath: string;
mkdir?: boolean;
mode?: number;
}): Promise<SafeWritableOpenResult> {
const { rootReal, rootWithSep, resolved } = await resolvePathWithinRoot(params);
try {
@@ -352,16 +353,18 @@ export async function openWritableFileWithinRoot(params: {
}
}
const fileMode = params.mode ?? 0o600;
let handle: FileHandle;
let createdForWrite = false;
try {
try {
handle = await fs.open(ioPath, OPEN_WRITE_EXISTING_FLAGS, 0o600);
handle = await fs.open(ioPath, OPEN_WRITE_EXISTING_FLAGS, fileMode);
} catch (err) {
if (!isNotFoundPathError(err)) {
throw err;
}
handle = await fs.open(ioPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
handle = await fs.open(ioPath, OPEN_WRITE_CREATE_FLAGS, fileMode);
createdForWrite = true;
}
} catch (err) {