🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

1. 🟠 Trusted-proxy auth bypass via loopbackUser fallback for same-host proxies

Description

authorizeTrustedProxy now supports trustedProxy.loopbackUser as a fallback identity when the configured userHeader is missing.

This introduces an authentication bypass risk in common same-host reverse proxy deployments:

• In trusted-proxy mode, the gateway trusts requests based on the TCP peer IP (req.socket.remoteAddress) being in gateway.trustedProxies.
• For same-host proxies (Caddy/nginx on the same machine), remoteAddress is typically 127.0.0.1/::1 for all proxied traffic, including requests originating from remote clients.
• With loopbackUser set, any proxied request that reaches the gateway without the user header (due to proxy misconfiguration, a non-authenticated route, header stripping bugs, or forward-auth failures) will be treated as authenticated as loopbackUser.
• This effectively turns “missing identity header” from a fail-closed condition into a fail-open condition whenever the trusted proxy hop is loopback.

Vulnerable logic:

const userFromHeader = userHeaderValue?.trim();
const loopbackUser = trustedProxyConfig.loopbackUser?.trim();
const user =
  userFromHeader && userFromHeader.length > 0
    ? userFromHeader
    : isLoopbackAddress(remoteAddr) && loopbackUser && loopbackUser.length > 0
      ? loopbackUser
      : undefined;

Impact depends on configuration, but can be severe because trusted-proxy mode controls gateway operator access.

Recommendation

Make loopbackUser apply only to direct local requests, not to requests forwarded by a reverse proxy, by basing the decision on the resolved client IP (from X-Forwarded-For / X-Real-IP) and/or absence of forwarded headers.

Minimal defense-in-depth change (fail closed for proxied traffic):

const remoteAddr = req.socket?.remoteAddress;

const forwardedFor = headerValue(req.headers["x-forwarded-for"]);
const realIp = headerValue(req.headers["x-real-ip"]);
const clientIp = resolveClientIp({
  remoteAddr,
  forwardedFor,
  realIp,
  trustedProxies,
  allowRealIpFallback: false,
});

const isDirectLoopback = isLoopbackAddress(clientIp) && !forwardedFor && !realIp;

const user = userFromHeader?.trim()
  ? userFromHeader.trim()
  : isDirectLoopback && loopbackUser?.trim()
    ? loopbackUser.trim()
    : undefined;

Additional low-cost hardening (project-pattern-aligned):

• Emit a startup/security-audit warning when loopbackUser is set and allowUsers is empty (implicit allow-all).
• Document loopbackUser in docs/gateway/trusted-proxy-auth.md and configuration-reference.md with an explicit warning: do not rely on it for requests that traverse a proxy; intended for local direct CLI traffic only.

Analyzed PR: #42388 at commit c59e0bc

_{Last updated on: 2026-03-10T17:38:52Z}

Greptile Summary

This PR introduces an optional gateway.auth.trustedProxy.loopbackUser config field as a fallback user identity in trusted-proxy mode when requests arrive from trusted loopback addresses without the configured userHeader. The feature enables local CLI/sub-agent workflows to authenticate even when they cannot set proxy-injected headers.

Key findings:

• The loopback guard (isLoopbackAddress(remoteAddr) on line 365) does not differentiate between direct CLI connections and requests proxy-forwarded through a localhost reverse proxy. In a deployment where the reverse proxy itself runs on loopback (e.g., Nginx on 127.0.0.1), proxy-forwarded requests that lack the user header will silently authenticate as loopbackUser, defeating the intended boundary between direct and proxied requests. This should be addressed by adding a forwarding-header check (e.g., via isLocalDirectRequest or a lighter check for presence of proxy headers).
• Test coverage is missing for the loopback-proxy-forwarded scenario (loopback source IP with x-forwarded-for header and no user header), which is the critical boundary that determines whether the feature remains scoped to truly direct connections. A test case should be added to explicitly define and enforce this boundary.
• Type, schema, and basic test coverage are correct; the happy-path, non-loopback rejection, and allowUsers enforcement are all properly tested.

Confidence Score: 2/5

• Do not merge until the loopback-proxy-forwarded security boundary is addressed.
• The PR introduces a real security boundary gap: the loopback fallback does not distinguish direct CLI requests from proxy-forwarded requests through a localhost reverse proxy. If a trusted proxy running on loopback sends requests without proper user headers (due to misconfiguration or compromise), those requests will authenticate as loopbackUser. While the feature itself is well-scoped and backward-compatible, the implementation of the loopback guard is too broad for deployments where the proxy runs on the same host. This gap should be closed before merging by either (1) adding a forwarding-header check to the guard, or (2) explicitly documenting and testing this behavior if it is intentional.
• src/gateway/auth.ts — loopback guard needs to check for proxy forwarding headers; src/gateway/auth.test.ts — missing test for loopback-proxy-forwarded scenario.

_{Last reviewed commit: c59e0bc}