From b0dc39412f2e7440f5b4d5934fbda057df77c958 Mon Sep 17 00:00:00 2001
From: Nick Taylor <nick@nickyt.co>
Date: Sun, 25 Jan 2026 05:57:18 +0000
Subject: [PATCH] feat(gateway): add trusted-proxy auth mode types and schema

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 src/config/types.gateway.ts | 32 +++++++++++++++++++++++++++++++-
 src/config/zod-schema.ts    | 12 +++++++++++-
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/config/types.gateway.ts b/src/config/types.gateway.ts
index 61c0d6f06..38b23e0a4 100644
--- a/src/config/types.gateway.ts
+++ b/src/config/types.gateway.ts
@@ -55,7 +55,32 @@ export type GatewayControlUiConfig = {
   allowInsecureAuth?: boolean;
 };
 
-export type GatewayAuthMode = "token" | "password";
+export type GatewayAuthMode = "token" | "password" | "trusted-proxy";
+
+/**
+ * Configuration for trusted reverse proxy authentication.
+ * Used when Clawdbot runs behind an identity-aware proxy (Pomerium, Caddy + OAuth, etc.)
+ * that handles authentication and passes user identity via headers.
+ */
+export type GatewayTrustedProxyConfig = {
+  /**
+   * Header name containing the authenticated user identity (required).
+   * Common values: "x-forwarded-user", "x-remote-user", "x-pomerium-claim-email"
+   */
+  userHeader: string;
+  /**
+   * Additional headers that MUST be present for the request to be trusted.
+   * Use this to verify the request actually came through the proxy.
+   * Example: ["x-forwarded-proto", "x-forwarded-host"]
+   */
+  requiredHeaders?: string[];
+  /**
+   * Optional allowlist of user identities that can access the gateway.
+   * If empty or omitted, all authenticated users from the proxy are allowed.
+   * Example: ["nick@example.com", "admin@company.org"]
+   */
+  allowUsers?: string[];
+};
 
 export type GatewayAuthConfig = {
   /** Authentication mode for Gateway connections. Defaults to token when set. */
@@ -66,6 +91,11 @@ export type GatewayAuthConfig = {
   password?: string;
   /** Allow Tailscale identity headers when serve mode is enabled. */
   allowTailscale?: boolean;
+  /**
+   * Configuration for trusted-proxy auth mode.
+   * Required when mode is "trusted-proxy".
+   */
+  trustedProxy?: GatewayTrustedProxyConfig;
 };
 
 export type GatewayTailscaleMode = "off" | "serve" | "funnel";
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index b3d157355..b29987400 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -318,10 +318,20 @@ export const ClawdbotSchema = z
           .optional(),
         auth: z
           .object({
-            mode: z.union([z.literal("token"), z.literal("password")]).optional(),
+            mode: z
+              .union([z.literal("token"), z.literal("password"), z.literal("trusted-proxy")])
+              .optional(),
             token: z.string().optional(),
             password: z.string().optional(),
             allowTailscale: z.boolean().optional(),
+            trustedProxy: z
+              .object({
+                userHeader: z.string().min(1, "userHeader is required for trusted-proxy mode"),
+                requiredHeaders: z.array(z.string()).optional(),
+                allowUsers: z.array(z.string()).optional(),
+              })
+              .strict()
+              .optional(),
           })
           .strict()
           .optional(),