Skip to slide
007 / 221

CH 01 · Anatomy of an AI Agent · 07/12

Read as one page

Real code: OpenClaw checks the caller before any agent work

Step 1 of the turn belongs to the surrounding system: decide who is calling, before any model or prompt is involved. OpenClaw runs on your own machine. Its Control UI, CLI, and TUI (a terminal interface) connect to a local server it calls the Gateway, and this function is that server's shared token or password check. Chat channels such as Telegram and Slack are a different door: the Gateway connects out to them, and those senders do not present this secret.

async function authorizeSharedSecretAuth(params: {
  method: "token" | "password";
  configuredSecret?: string;
  providedSecret?: string;
  limiter?: AuthRateLimiter;
  ip?: string;
  rateLimitScope: string;
  deferRateLimitFailure?: boolean;
  resetOnSuccess?: boolean;
}): Promise<GatewayAuthResult> {
  // ... (9 lines: fail when the gateway has no usable secret configured)
  if (!params.providedSecret) {
    // Missing credentials do not consume the wrong-credential rate limit.
    return { ok: false, reason: `${params.method}_missing` }; // [1]
  }
  if (!safeEqualSecret(params.providedSecret, params.configuredSecret)) { // [2]
    if (!params.deferRateLimitFailure) {
      await params.limiter?.recordFailureAndDelay(params.ip, params.rateLimitScope); // [3]
    }
    return { ok: false, reason: `${params.method}_mismatch` };
  }
  if (params.resetOnSuccess !== false) {
    params.limiter?.reset(params.ip, params.rateLimitScope); // [4]
  }
  return { ok: true, method: params.method }; // [5]
}

Source: openclaw/openclaw, src/gateway/auth.ts (MIT)

What to notice

  1. [1] A request with no credential is refused but not counted as a failed guess. A client that simply forgot its token should not lock itself out.
  2. [2] safeEqualSecret compares using Node's timingSafeEqual, after padding both values to the same length. A plain === can return sooner when the first characters differ, and an attacker who times many responses can recover a secret one character at a time. The padding also keeps the secret's length from leaking.
  3. [3] A wrong secret is recorded against the caller's address and a scope (a named counter, so token failures do not share a budget with device pairing). With the defaults in auth-rate-limit.ts, 10 failures inside 60 seconds lock that address out for 5 minutes. Loopback callers (connections from this same machine to itself, such as 127.0.0.1) are not locked out by default. Each of their failures waits longer instead, from 250 milliseconds, doubling up to 5 seconds. A client on the same machine that arrives through a LAN address is not exempt. deferRateLimitFailure postpones the record for a caller that still has other credentials to try.
  4. [4] When resetOnSuccess is not false (the default), a correct secret clears that scope's failure history for that address.
  5. [5] Every outcome is a returned object, not a thrown error. Failures include a reason such as token_missing or token_mismatch. Success is { ok: true, method }, with no reason.

The check for an address that is already locked out runs just before this function, in authorizeGatewayConnectCore. The naive version, if (token !== config.token) return 401, leaks timing, lets anyone guess forever, and tells you nothing when a real user gets refused.

Read it yourself: in src/gateway/auth.ts, read authorizeGatewayConnectCore and write down the order of checks a request passes before its token is compared. Then open src/gateway/auth-rate-limit.ts and read the comment on recordFailureAndDelay: why does it record failures only after checking credentials?

Finished this idea?

Your learning progress stays in this browser.