AgentOS v2 Security Mitigations (SCR-03)

Introduced in: v1.0.449

Background

The AgentOS People Portal v2 REST API requires the platform API key to be supplied as an ?api_key= URL query parameter. This is a vendor-imposed constraint — header-based authentication (Authorization: Bearer) is not supported on v2 endpoints.

Because query parameters appear in server access logs, CDN logs, and Vercel function log drains, this creates a risk that the master API key could be inadvertently captured in observability tooling (SCR-03). Two server-side controls have been added to src/lib/agentos/client.ts to mitigate this.

---

Mitigations

1. API key log redaction — redactApiKey()

The exported redactApiKey() function removes the value of any api_key query parameter from a URL string before that string is used in a log message, error object, or exception trace.

import { redactApiKey } from "@/lib/agentos/client";

redactApiKey("https://live-api.letmc.com/v2/path?api_key=SECRET&foo=bar");
// → "https://live-api.letmc.com/v2/path?api_key=[REDACTED]&foo=bar"

How it is applied internally:

• The raw, credential-bearing URL (requestUrl) is constructed in a private method (buildV2Url) and passed directly to fetch(). It is never stored beyond that scope.
• All other code paths (error construction, logging) receive safeUrl, which is the output of redactApiKey(requestUrl).
• AgentosApiClientError.path is contractually guaranteed to always contain the redacted URL.

Edge cases handled:

Input	Output
?api_key=SECRET (sole parameter)	?api_key=[REDACTED]
?api_key=SECRET&foo=bar (first parameter)	?api_key=[REDACTED]&foo=bar
?foo=bar&api_key=SECRET&baz=qux (mid-query)	?foo=bar&api_key=[REDACTED]&baz=qux
No api_key present	URL returned unchanged
Empty string	Empty string returned
Plain path with no query string	Path returned unchanged
Multiple api_key occurrences (defensive)	All occurrences redacted

---

2. SSRF guard — validateOutboundUrl()

The platform's existing SSRF guard (src/lib/ssrf-guard.ts) is applied to all AgentOS outbound requests at two points.

Module initialisation (cold-start)

When the client.ts module first loads, AGENTOS_API_BASE_URL is validated against the SSRF guard:

try {
  validateOutboundUrl(BASE_URL);
} catch (err) {
  if (err instanceof SsrfBlockedError) {
    throw new Error(
      `[AgentOS] AGENTOS_API_BASE_URL is blocked by SSRF guard: ${err.message}. ` +
      `Check your environment configuration.`,
    );
  }
  throw err;
}

A misconfigured AGENTOS_API_BASE_URL (e.g. pointing at an internal/private address) will cause the module to throw at cold-start — before any user request is in flight and before the API key is ever appended to a URL.

Per-request (before credential attachment)

Inside buildV2Url(), the base URL is validated before api_key= is appended:

// SSRF guard runs on the credential-free base URL
validateOutboundUrl(this.buildUrl(path));

// api_key is only appended after the guard passes
const url = `${base}${separator}api_key=${getApiKey()}`;

This ordering ensures the API key value cannot appear in a SsrfBlockedError message even if the guard fires at runtime.

---

Authentication summary by API version

API Version	Auth mechanism	SSRF guard	Log redaction
v4 endpoints	Authorization: Bearer header	Module-level (base URL)	Not required (key not in URL)
v2 People Portal endpoints	?api_key= query parameter	Module-level + per-request	redactApiKey() applied before all logs and errors

---

Residual risk

The ?api_key= mechanism remains in place because it is mandated by the vendor. The key may still appear in transport-layer access logs between the Vercel edge and the AgentOS origin server. This residual risk is documented in the ROPA under AgentOS Integration — v2 query-param auth.

Recommended additional mitigations

1. Vercel Log Drain — Configure a log drain filter to redact api_key=* patterns at the infrastructure level.
2. Vendor header auth — Request that AgentOS add Authorization: Bearer support to v2 endpoints.
3. IP allowlist — Work with AgentOS to restrict the API key to Vercel's known egress IP range.

---

Environment variables

Variable	Purpose
AGENTOS_API_KEY	Master API key for the AgentOS People Portal. Required for all requests.
AGENTOS_API_BASE_URL	Base URL for all AgentOS API calls. Defaults to https://live-api.letmc.com. Must pass SSRF validation.