Mehdi Akiki
Published on

Local Agent Control APIs Need Job-Scoped Authorization

Authors
  • Mehdi Akiki avatar
    Name
    Mehdi Akiki
    Twitter

Article · Through the layers

The agent's public tools are restricted. Somewhere beside them, a small control service can inspect jobs, stop them, or change their settings.

It was meant for the launcher. It listens on a local interface, so authentication felt unnecessary.

Now ask a more concrete question: can code running in the agent's environment reach that interface? If it can, the service has given a powerful client access without deciding who that client is.

The sandbox design overview treats the control service as part of the trusted application. Here we follow a request to a single harmless operation: inspect one job's status.

First draw the actual network boundary

127.0.0.1 is relative to a network namespace. An ordinary isolated container's loopback interface is not automatically the host's loopback interface. The Docker security documentation explains the separate network stacks used by its default isolation.

The answer changes with host networking, shared namespaces, sidecars, local proxies, port forwarding, and sockets mounted into the job. Write down the deployment you have, then check which control addresses it exposes.

Don't replace that investigation with a claim that every localhost service is reachable from every container. It isn't. Also don't assume the word “local” proves it is unreachable in your setup.

A Host: localhost header is even less helpful as identity. A program making an HTTP request can normally choose that header. It tells a server which host was requested; it does not establish that a trusted operator sent the request.

Separate the token from the agent

The control service needs a credential the agent cannot read, plus authorization for the requested job and action. Put that credential in the trusted launcher or broker. Passing it into the agent's environment would defeat the separation.

For a small policy demonstration, the decision can look like this:

import { timingSafeEqual } from "node:crypto";

type Grant = {
  token: string;
  jobId: string;
  actions: ReadonlySet<string>;
};

function allowed(token: string | undefined, jobId: string, action: string, grant: Grant): boolean {
  if (!token || !grant.token) return false;
  const supplied = Buffer.from(token, "utf8");
  const expected = Buffer.from(grant.token, "utf8");
  return (
    supplied.length === expected.length &&
    timingSafeEqual(supplied, expected) &&
    jobId === grant.jobId &&
    grant.actions.has(action)
  );
}

Rejecting empty tokens matters. Otherwise a missing request token and an accidentally empty configured token can become two matching empty buffers. Put that case next to the ordinary wrong-token check; a missing setting should cause a denial too.

Constant-time comparison is only one small part of handling a secret. It doesn't generate a strong token, protect its transport, expire it, or keep it out of logs.

The endpoint needs more than this comparison

The complete TypeScript example checks this decision with dummy strings. It then connects it to an in-process request handler and a fake job-inspection function. Its host field grants nothing.

The handler receives already parsed HTTP-shaped input. It extracts a bearer credential from the authorization field, accepts exactly jobId and action in the body, and checks them against a grant supplied by server configuration. The request doesn't select that trusted record. After authorization, the only supported effect is job.inspect, called with the grant's job ID.

The selfcheck sends missing and wrong credentials, another job's ID, a forbidden action, and an extra admin field. It expects no inspection calls for any of them. The allowed request returns the dummy status and records one inspection of job-a. Watching the effect list matters: a handler could otherwise return a denial after it had already read private state.

This is still an in-process handler, without an HTTP server. It doesn't exercise duplicate-header handling, transport security, proxy configuration, or reachability. Those need checks at the endpoint itself. Use the handler example to review the order of parsing, authorization, and effect; don't treat it as an authentication framework.

A real endpoint also needs strict request parsing, body-size limits, rate limits, secure credential delivery, and an explicit token lifetime. A destructive operation may need replay protection or a fresh confirmation bound to that exact operation. Error responses should not print the expected credential.

Use an established authentication mechanism where one already exists. A short token-comparison function is not a reason to invent your own identity system.

Carrying authorization through tool calls

covers identity and delegation across services. The issue here is narrower: an internal control endpoint must enforce its own job and action policy even when the network path looks local.

Fail startup if a required control credential is absent. Don't leave the service running in a permissive development mode because a production setting was misspelled.

In decision logs, keep the request ID, authenticated caller, job, action, and denial reason where appropriate; leave the secret itself out. Those records help explain whether a failed operation was an identity problem or a forbidden action without putting credentials in the logs.

A broker must check its own authority

Sometimes the agent cannot reach the control API directly but can ask a privileged broker to call it. That broker has to authorize the request too.

If it copies arbitrary job IDs or actions from a model response, it has moved the missing check to another process. Build the outgoing request from the trusted grant instead.

The README prompt-injection trace

follows an unauthorized proposal to the effect boundary and checks that no forbidden operation runs. The cause of a bad proposal should not change the control API's permission decision.

The MCP draft security guidance covers related problems with token audience, confused deputies, and session handles. It is draft guidance, and it doesn't make the toy function a conforming MCP authorization implementation.

Try the requests that should be boring denials

From an approved test job, attempt an inspection with no credential, with another job's identifier, and with a credential allowed only to inspect while requesting a setting change. Use dummy jobs and harmless actions in the test environment.

Record the deployment's network path as well as the service response. An unreachable endpoint and a reachable endpoint returning an authorization denial protect different boundaries.

When the next local service gets added, those records give the team something useful to repeat. “It only listens locally” can remain a networking fact. It should never have to carry the whole authentication design.