Auth — Authentication & Access Control

Security-Critical TypeScript Rate Limiting Multi-Method

What Is This & Why Does It Exist?

Without authentication, any client could connect to the Gateway and execute arbitrary agent commands. The Auth subsystem ensures that every connection is verified before it reaches internal services.

Architecture

The Auth layer is the first subsystem touched by every incoming connection. It coordinates between credential resolution, auth mode policy, rate limiting, and multiple authentication strategies.

flowchart TB
    subgraph Input
        REQ["Incoming Request
ConnectParams"]
    end

    subgraph AuthLayer["Auth Layer"]
        RESOLVE["resolveGatewayAuth()
Mode Resolution"]
        POLICY["auth-mode-policy.ts
Ambiguity Detection"]
        CRED["credentials.ts
Credential Resolution"]
        RL["AuthRateLimiter
Sliding-Window Counter"]

        subgraph Methods["Auth Methods"]
            NONE["none"]
            TOKEN["token"]
            PASS["password"]
            TAIL["tailscale"]
            DEV["device-token"]
            PROXY["trusted-proxy"]
        end
    end

    subgraph Output
        OK["GatewayAuthResult
{ok: true, method, user}"]
        FAIL["GatewayAuthResult
{ok: false, reason}"]
    end

    REQ --> RL
    RL -->|allowed| RESOLVE
    RL -->|locked out| FAIL
    RESOLVE --> POLICY
    POLICY --> CRED
    CRED --> Methods
    Methods --> OK
    Methods -->|failure| FAIL

Data Flow

Sequence of operations when authorizeGatewayConnect() processes an incoming connection request.

sequenceDiagram
    participant C as Client
    participant RL as AuthRateLimiter
    participant Resolve as resolveGatewayAuth
    participant Policy as AuthModePolicy
    participant Auth as authorizeGatewayConnect
    participant Cred as CredentialResolver

    C->>RL: check(clientIp, scope)
    alt rate limited
        RL-->>C: {allowed: false, retryAfterMs}
    end
    RL-->>Auth: {allowed: true, remaining}
    Auth->>Resolve: resolveGatewayAuth(cfg, overrides)
    Resolve->>Policy: assertExplicitGatewayAuthMode()
    Resolve-->>Auth: ResolvedGatewayAuth {mode, token, password}
    Auth->>Cred: resolveGatewayCredentialsFromConfig()
    Cred-->>Auth: {token?, password?}
    Auth->>Auth: evaluate method (none|token|password|tailscale|device-token|trusted-proxy)
    alt success
        Auth-->>C: {ok: true, method, user}
    else failure
        Auth->>RL: recordFailure(clientIp, scope)
        Auth-->>C: {ok: false, reason}
    end

Key Classes & Types

Auth Methods

Rate Limit Scopes

Code Examples

Resolving Auth Mode

import { resolveGatewayAuth, ResolvedGatewayAuth } from './auth';

const auth: ResolvedGatewayAuth = resolveGatewayAuth({
  config: openClawConfig,
  overrideMode: undefined,
  overrideToken: process.env.GATEWAY_TOKEN,
});
// auth.mode => "token" | "password" | "none" | "trusted-proxy"
// auth.modeSource => "config" | "override" | "default"

Creating a Rate Limiter

import { createAuthRateLimiter, RateLimitConfig } from './auth-rate-limit';

const config: RateLimitConfig = {
  maxAttempts: 10,
  windowMs: 60_000,
  lockoutMs: 300_000,
  exemptLoopback: true,
  pruneIntervalMs: 60_000,
};

const limiter = createAuthRateLimiter(config);
const result = limiter.check('192.168.1.100', 'default');
// result => { allowed: true, remaining: 10, retryAfterMs: 0 }

Authorizing a Connection

import { authorizeGatewayConnect, GatewayAuthResult } from './auth';

const result: GatewayAuthResult = await authorizeGatewayConnect({
  auth: resolvedAuth,
  connectAuth: { token: clientToken },
  req: incomingRequest,
  trustedProxies: ['10.0.0.0/8'],
  authSurface: 'ws-control-ui',
  rateLimiter: limiter,
  clientIp: '192.168.1.100',
  rateLimitScope: 'default',
  allowRealIpFallback: false,
  browserOriginPolicy: 'strict',
});

if (!result.ok) {
  console.error(`Auth failed: ${result.reason}`);
  if (result.rateLimited) {
    console.error(`Retry after ${result.retryAfterMs}ms`);
  }
}

Configuration

Deep-Dive Focus Pages

Directory Map

src/gateway/
├── auth.ts                     ← Core: resolveGatewayAuth, authorizeGatewayConnect, 6 auth methods
├── auth-rate-limit.ts          ← AuthRateLimiter, createAuthRateLimiter, RateLimitConfig
├── auth-mode-policy.ts         ← hasAmbiguousGatewayAuthModeConfig, assertExplicitMode
├── auth-install-policy.ts      ← shouldRequireGatewayTokenForInstall
├── auth-config-utils.ts        ← withGatewayAuthPassword, resolveGatewayPasswordSecretRef
├── credentials.ts              ← ResolvedGatewayCredentials, GatewaySecretRefUnavailableError
├── connection-auth.ts          ← resolveGatewayConnectionAuth (async credential resolution)
└── connection-details.ts       ← GatewayConnectionDetails