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

@@ -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";

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(),