feat(gateway): thread authenticated user identity into presence (#111179)

steipete · web-flow · commit c684b1321333 · 2026-07-18T21:06:22.000-07:00
* feat(gateway): thread authenticated user identity into presence

* feat(gateway): regenerate Swift protocol bindings for presence user
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -947,6 +947,7 @@ public struct PresenceEntry: Codable, Sendable {
     public let roles: [String]?
     public let scopes: [String]?
     public let instanceid: String?
+    public let user: [String: AnyCodable]?
 
     public init(
         host: String? = nil,
@@ -964,7 +965,8 @@ public struct PresenceEntry: Codable, Sendable {
         deviceid: String? = nil,
         roles: [String]? = nil,
         scopes: [String]? = nil,
-        instanceid: String? = nil)
+        instanceid: String? = nil,
+        user: [String: AnyCodable]? = nil)
     {
         self.host = host
         self.ip = ip
@@ -982,6 +984,7 @@ public struct PresenceEntry: Codable, Sendable {
         self.roles = roles
         self.scopes = scopes
         self.instanceid = instanceid
+        self.user = user
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -1001,6 +1004,7 @@ public struct PresenceEntry: Codable, Sendable {
         case roles
         case scopes
         case instanceid = "instanceId"
+        case user
     }
 }
 
diff --git a/packages/gateway-protocol/src/schema/snapshot.test.ts b/packages/gateway-protocol/src/schema/snapshot.test.ts
@@ -0,0 +1,31 @@
+// Gateway Protocol snapshot schema tests cover optional presence identity.
+import { Value } from "typebox/value";
+import { describe, expect, it } from "vitest";
+import { SnapshotSchema } from "./snapshot.js";
+
+function snapshotWithPresence(presence: Record<string, unknown>) {
+  return {
+    presence: [presence],
+    health: {},
+    stateVersion: { presence: 1, health: 1 },
+    uptimeMs: 1,
+  };
+}
+
+describe("SnapshotSchema", () => {
+  it("accepts a presence user identity", () => {
+    expect(
+      Value.Check(
+        SnapshotSchema,
+        snapshotWithPresence({
+          ts: 1,
+          user: { id: "alice@example.com", email: "alice@example.com" },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("keeps presence user identity optional", () => {
+    expect(Value.Check(SnapshotSchema, snapshotWithPresence({ ts: 1 }))).toBe(true);
+  });
+});
diff --git a/packages/gateway-protocol/src/schema/snapshot.ts b/packages/gateway-protocol/src/schema/snapshot.ts
@@ -28,6 +28,15 @@ export const PresenceEntrySchema = closedObject({
   roles: Type.Optional(Type.Array(NonEmptyString)),
   scopes: Type.Optional(Type.Array(NonEmptyString)),
   instanceId: Type.Optional(NonEmptyString),
+  user: Type.Optional(
+    closedObject({
+      /** Opaque identity key: authenticated email today, durable profile id later. Clients group presence by this. */
+      id: NonEmptyString,
+      email: Type.Optional(NonEmptyString),
+      name: Type.Optional(NonEmptyString),
+      avatarUrl: Type.Optional(NonEmptyString),
+    }),
+  ),
 });
 
 /** Health snapshot is intentionally opaque because providers contribute nested shapes. */
diff --git a/src/gateway/server/ws-connection.test.ts b/src/gateway/server/ws-connection.test.ts
@@ -433,6 +433,31 @@ describe("attachGatewayWsConnectionHandler", () => {
     expect(logWsControl.warn).not.toHaveBeenCalled();
   });
 
+  it("logs the authenticated user when a connection closes", async () => {
+    const { socket, logWsControl, passed } = await connectTestWs();
+    const handlerParams = passed as {
+      setClient: (client: never) => boolean;
+    };
+
+    expect(
+      handlerParams.setClient({
+        socket,
+        connect: { client: { id: "openclaw-control-ui", mode: "ui" } },
+        connId: "conn-authenticated-user",
+        authenticatedUserId: "alice@example.com",
+        usesSharedGatewayAuth: false,
+      } as never),
+    ).toBe(true);
+
+    socket.emit("close", 1000, Buffer.from("done"));
+
+    expect(logWsControl.info).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /^authenticated user disconnected code=1000 reason=done conn=.+ user=alice@example\.com$/,
+      ),
+    );
+  });
+
   it("skips node presence disconnects for stale reconnected sockets", async () => {
     const unregister = vi.fn(() => null);
     const { socket } = attachGatewayWsForTest({
diff --git a/src/gateway/server/ws-connection.ts b/src/gateway/server/ws-connection.ts
@@ -28,7 +28,7 @@ import {
 import { clearNodeWakeState } from "../server-methods/nodes-wake-state.js";
 import type { GatewayRequestContext, GatewayRequestHandlers } from "../server-methods/types.js";
 import { formatError } from "../server-utils.js";
-import { logWs } from "../ws-log.js";
+import { formatForLog, logWs } from "../ws-log.js";
 import { getHealthVersion, incrementPresenceVersion } from "./health-state.js";
 import type { PreauthConnectionBudget } from "./preauth-connection-budget.js";
 import { broadcastPresenceSnapshot } from "./presence-events.js";
@@ -542,6 +542,11 @@ export function attachGatewayWsConnectionHandler(params: AttachGatewayWsConnecti
           `webchat disconnected code=${code} reason=${logReason || "n/a"} conn=${connId}`,
         );
       }
+      if (client?.authenticatedUserId) {
+        logWsControl.info(
+          `authenticated user disconnected code=${code} reason=${logReason || "n/a"} conn=${connId} user=${formatForLog(client.authenticatedUserId)}`,
+        );
+      }
       if (connectionKind === "gateway") {
         const context = buildRequestContext();
         context.unsubscribeAllSessionEvents(connId);
diff --git a/src/gateway/server/ws-connection/connect-session.ts b/src/gateway/server/ws-connection/connect-session.ts
@@ -1,5 +1,6 @@
 // Gateway WebSocket connect finalization attaches node/session state and sends hello-ok.
 import os from "node:os";
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { WebSocket } from "ws";
 import {
   GATEWAY_CLIENT_IDS,
@@ -105,6 +106,7 @@ export async function attachAuthenticatedGatewayConnect(
     role,
     scopes,
     device,
+    authResult,
     authMethod,
     pairingLocality,
     sessionUsesSharedGatewayAuth,
@@ -120,6 +122,7 @@ export async function attachAuthenticatedGatewayConnect(
   const clientId = connectParams.client.id;
   const instanceId = connectParams.client.instanceId;
   const presenceKey = shouldTrackPresence ? (device?.id ?? instanceId ?? connId) : undefined;
+  const authenticatedUserId = normalizeOptionalString(authResult.user);
 
   if (isClosed()) {
     await releasePendingNodePairingCleanup();
@@ -222,6 +225,7 @@ export async function attachAuthenticatedGatewayConnect(
     usesSharedGatewayAuth: sessionUsesSharedGatewayAuth,
     sharedGatewaySessionGeneration: sessionSharedGatewaySessionGeneration,
     presenceKey,
+    ...(authenticatedUserId ? { authenticatedUserId } : {}),
     clientIp: reportedClientIp,
     ...(internal ? { internal } : {}),
     ...(Object.keys(pluginSurfaceUrls).length > 0 ? { pluginSurfaceUrls } : {}),
@@ -295,6 +299,12 @@ export async function attachAuthenticatedGatewayConnect(
     auth: authMethod,
   });
 
+  if (authenticatedUserId) {
+    logWsControl.info(
+      `authenticated user connected conn=${connId} user=${formatForLog(authenticatedUserId)}`,
+    );
+  }
+
   if (isWebchatConnect(connectParams)) {
     logWsControl.info(
       `webchat connected conn=${connId} remote=${remoteAddr ?? "?"} client=${clientLabel} ${connectParams.client.mode} v${connectParams.client.version}`,
@@ -314,6 +324,9 @@ export async function attachAuthenticatedGatewayConnect(
       roles: [role],
       scopes,
       instanceId: device?.id ?? instanceId,
+      ...(authenticatedUserId
+        ? { user: { id: authenticatedUserId, email: authenticatedUserId } }
+        : {}),
       reason: "connect",
     });
     incrementPresenceVersion();
diff --git a/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts b/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts
@@ -187,6 +187,7 @@ function attachGatewayHarness(options: {
   refreshHealthSnapshot?: GatewayRequestContext["refreshHealthSnapshot"];
   requestOrigin?: string;
   requestHost?: string;
+  headers?: Record<string, string>;
   remoteAddr?: string;
   localAddr?: string;
   resolvedAuth?: ResolvedGatewayAuth;
@@ -220,12 +221,14 @@ function attachGatewayHarness(options: {
     allowTailscale: false,
   };
   const advanceHandshakePhase = vi.fn();
+  const logWsControl = createLogger();
   attachGatewayWsMessageHandler({
     socket,
     upgradeReq: {
       headers: {
         host: requestHost,
         ...(options.requestOrigin ? { origin: options.requestOrigin } : {}),
+        ...options.headers,
       },
       socket: { localAddress: localAddr, remoteAddress: remoteAddr },
     } as unknown as IncomingMessage,
@@ -259,14 +262,15 @@ function attachGatewayHarness(options: {
     originCheckMetrics: { hostHeaderFallbackAccepted: 0 },
     logGateway: createLogger() as never,
     logHealth: createLogger() as never,
-    logWsControl: createLogger() as never,
+    logWsControl: logWsControl as never,
   });
   if (onMessage === undefined) {
     throw new Error("expected websocket message handler");
   }
   const sendMessage = onMessage;
   return {
     advanceHandshakePhase,
+    logWsControl,
     send,
     socketSend,
     sendRequest: (id: string, method: string, params: Record<string, unknown> = {}) => {
@@ -529,6 +533,131 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => {
     resolveRefresh?.();
   });
 
+  it("projects trusted-proxy identity into presence and the connected client", async () => {
+    loadConfigMock.mockImplementationOnce(() => ({
+      gateway: {
+        auth: {
+          mode: "trusted-proxy",
+          trustedProxy: {
+            userHeader: "x-forwarded-user",
+            requiredHeaders: ["x-forwarded-proto"],
+          },
+        },
+        trustedProxies: ["10.0.0.1"],
+        controlUi: {
+          allowedOrigins: ["http://127.0.0.1:19001"],
+          dangerouslyDisableDeviceAuth: true,
+        },
+      },
+    }));
+    const harness = attachGatewayHarness({
+      connId: "conn-trusted-proxy-user",
+      connectNonce: "nonce-trusted-proxy-user",
+      requestHost: "gateway.example.com:18789",
+      requestOrigin: "http://127.0.0.1:19001",
+      remoteAddr: "10.0.0.1",
+      resolvedAuth: {
+        mode: "trusted-proxy",
+        allowTailscale: false,
+        trustedProxy: {
+          userHeader: "x-forwarded-user",
+          requiredHeaders: ["x-forwarded-proto"],
+        },
+      },
+      headers: {
+        "x-forwarded-user": "alice@example.com",
+        "x-forwarded-proto": "https",
+      },
+    });
+
+    harness.sendConnect("connect-trusted-proxy-user", {
+      minProtocol: PROTOCOL_VERSION,
+      maxProtocol: PROTOCOL_VERSION,
+      client: {
+        id: "openclaw-control-ui",
+        version: "dev",
+        platform: "test",
+        mode: "ui",
+      },
+      role: "operator",
+      caps: [],
+    });
+
+    await waitForFast(() => {
+      expect(harness.socketSend.mock.calls.length + harness.send.mock.calls.length).toBeGreaterThan(
+        0,
+      );
+    });
+    const trustedProxyHello = harness.socketSend.mock.calls.at(0)?.[0];
+    expect(
+      typeof trustedProxyHello === "string"
+        ? JSON.parse(trustedProxyHello)
+        : harness.send.mock.calls.at(0)?.[0],
+    ).toMatchObject({
+      ok: true,
+    });
+    await waitForFast(() => {
+      expect(upsertPresenceMock).toHaveBeenCalledWith(
+        "conn-trusted-proxy-user",
+        expect.objectContaining({
+          user: { id: "alice@example.com", email: "alice@example.com" },
+        }),
+      );
+    });
+    expect(harness.client).toMatchObject({ authenticatedUserId: "alice@example.com" });
+    expect(harness.logWsControl.info).toHaveBeenCalledWith(
+      "authenticated user connected conn=conn-trusted-proxy-user user=alice@example.com",
+    );
+  });
+
+  it("keeps token-authenticated presence free of user identity", async () => {
+    const harness = attachGatewayHarness({
+      connId: "conn-token-userless",
+      connectNonce: "nonce-token-userless",
+      requestHost: "gateway.example.com:18789",
+      requestOrigin: "http://127.0.0.1:19001",
+      remoteAddr: "203.0.113.50",
+      resolvedAuth: {
+        mode: "token",
+        token: "gateway-token",
+        allowTailscale: false,
+      },
+    });
+
+    harness.sendConnect("connect-token-userless", {
+      minProtocol: PROTOCOL_VERSION,
+      maxProtocol: PROTOCOL_VERSION,
+      client: {
+        id: "openclaw-control-ui",
+        version: "dev",
+        platform: "test",
+        mode: "ui",
+      },
+      role: "operator",
+      caps: [],
+      auth: { token: "gateway-token" },
+    });
+
+    await waitForFast(() => {
+      expect(harness.socketSend.mock.calls.length + harness.send.mock.calls.length).toBeGreaterThan(
+        0,
+      );
+    });
+    const tokenHello = harness.socketSend.mock.calls.at(0)?.[0];
+    expect(
+      typeof tokenHello === "string" ? JSON.parse(tokenHello) : harness.send.mock.calls.at(0)?.[0],
+    ).toMatchObject({
+      ok: true,
+    });
+    await waitForFast(() => {
+      expect(upsertPresenceMock).toHaveBeenCalledWith(
+        "conn-token-userless",
+        expect.not.objectContaining({ user: expect.anything() }),
+      );
+    });
+    expect(harness.client).not.toMatchObject({ authenticatedUserId: expect.anything() });
+  });
+
   it("emits a security event for rejected gateway auth", async () => {
     const close = createCloseMock();
     const harness = attachGatewayHarness({
diff --git a/src/gateway/server/ws-types.ts b/src/gateway/server/ws-types.ts
@@ -32,6 +32,7 @@ export type GatewayWsClient = PluginNodeCapabilityClient & {
   usesSharedGatewayAuth: boolean;
   sharedGatewaySessionGeneration?: string;
   presenceKey?: string;
+  authenticatedUserId?: string;
   clientIp?: string;
   internal?: {
     approvalRuntime?: boolean;
diff --git a/src/infra/system-presence.ts b/src/infra/system-presence.ts
@@ -26,6 +26,12 @@ export type SystemPresence = {
   roles?: string[];
   scopes?: string[];
   instanceId?: string;
+  user?: {
+    id: string;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+  };
   text: string;
   ts: number;
 };
