Skip to main content
An agent served over HTTP needs to know two things about each request: may it call at all, and who is it. lousho/auth answers both. You give a route an ordered list of auth entries (jwt(), oidc(), basic(), apiToken(), anonymous() or your own function); the first entry that accepts the request returns a principal, and that principal goes into the run, where your model / instructions / tools functions and memory scopes can read it.

The auth list

Entries run in order, and each one does one of three things: When every entry skips, the request gets a 401. An empty list refuses every request. An entry that throws anything else is a bug: the request gets a 500 with a generic body, and the error is logged with console.error (never sent). The built-in helpers never throw for a bad credential: a wrong password, an expired token or a token for another audience all skip, so the next entry gets its chance (two jwt() entries for two issuers work), and a request nobody accepts ends in the same 401. A Principal is:

Helpers

All helpers are created once, at start-up, and check their options then: a helper that cannot work throws LOUSHO_AUTH_CONFIG_INVALID instead of refusing every request later.

jwt()

Accepts Authorization: Bearer <JWT> signed by the key you configure. Give exactly one key source:
What is checked:
  • The header’s alg must be one of algorithms; none is always refused, and so is a token whose header marks an extension crit.
  • The algorithm must fit the key: a public key is never used as an HMAC secret, whatever the token’s header says, and a key set never supplies an HMAC key.
  • exp is required; nbf and iat are honored. All three allow clockToleranceSec of clock skew (default 60, at most 300).
  • iss must equal one of issuer exactly (no trailing-slash tolerance), when you set issuer.
  • aud (a string or a list) must contain one of audience. audience is required; pass allowAnyAudience: true to skip that check on purpose.
  • A key set is fetched with a 5-second timeout, cached for 10 minutes, and refetched at most once every 30 seconds when a token names a kid it does not know (a failed fetch is retried on the same 30-second bound). Its URL is configuration only: the jku, x5u and jwk headers of a token are ignored.
The default principal is { id: sub, type: 'user', authenticator: 'jwt', issuer: iss, claims }; a token without sub skips.

oidc()

A jwt() whose keys come from an OpenID Connect provider. It fetches <issuer>/.well-known/openid-configuration once (or discoveryUrl), requires the document’s issuer to equal yours exactly, and uses its jwks_uri (https, or http on localhost / 127.0.0.1 / [::1] — the same rule as jwt()’s jwksUrl). Algorithms default to RS256 and ES256; HMAC is not allowed.
The principal has authenticator: 'oidc' and the provider’s iss as issuer.

basic()

HTTP Basic credentials. User names and passwords are NFC-normalized and compared in constant time, and every configured user is compared on every request, so an unknown user takes as long as a wrong password. The 401 carries WWW-Authenticate: Basic realm="<realm>", charset="UTF-8" so browsers show their login prompt.
Only use basic() over HTTPS: the password travels with every request.

apiToken() and anonymous()

apiToken(token, { id }) accepts Authorization: Bearer <token> (compared in constant time) as the service principal { id: id ?? 'api-token', type: 'service', authenticator: 'api-token' }. It is what a token string has always meant: createRouteHandler({ auth: '<token>' }) and LOUSHO_API_TOKEN are apiToken(). An empty string (auth: '', e.g. an env var that is set but blank) is refused with LOUSHO_AUTH_CONFIG_INVALID by createRouteHandler() when it is created and by serveFetch() on every request: it neither locks nor opens the routes silently. anonymous() accepts everyone as { id: 'anonymous', type: 'user', authenticator: 'anonymous' }: put it last for routes that serve signed-in and anonymous callers, and read principal.authenticator in the run.

Your own entry

Any function of the Request is an entry. Declare the challenges it answers a 401 with, or it advertises Bearer:

401, 403 and WWW-Authenticate

  • Nobody accepted the request (or an entry threw AuthError(401)): 401 with { "error": "Unauthorized" } and one WWW-Authenticate header per distinct challenge of the list, in order (Bearer for jwt, oidc, apiToken; Basic realm="..." for basic).
  • An entry threw AuthError(403): 403 with { "error": "Forbidden" }.
  • An entry failed in another way: 500 with { "error": "Internal Server Error" }.
The body never says which check failed: an expired token, a bad signature and a wrong audience all get the same 401. Every auth response carries Cache-Control: no-store. Tokens and passwords are never logged.

Where it runs

oidc() and jwt({ jwksUrl }) need outbound fetch to the key set, which every listed runtime has. In a hand-written Worker, call createRouteHandler or routeAuth() yourself with any helper.

createRouteHandler

auth takes the list, one entry, a token string, or (as before) a function that returns a boolean. true accepts with the principal { id: 'anonymous', type: 'user', authenticator: 'custom' }, false is a 401. Without auth the route is open, and in production (NODE_ENV=production) it logs one warning. GET <basePath>/health is never behind auth. The accepted principal reaches every route: POST <basePath>, /chat, approvals and the useChat endpoint. See Next.js.

The node server and auth.ts

The generated server (it uses the bundle’s internal createDeployedServer()) takes the same list (or one entry). When LOUSHO_API_TOKEN is set, apiToken(LOUSHO_API_TOKEN) is appended after your entries, so an operator’s token keeps working. Channels under /channels/<name> are not behind the list: they verify their own requests. In an agent directory, put the list in auth.ts (or auth.js), next to agent.ts:
lousho build --target=node-server (or docker) bundles it, and the built server uses it (resolveAgentDir() returns it as auth; the manifest says auth: true). With an auth.ts, a token baked in with adapter.scaffold(..., { auth: { token } }) is not used; LOUSHO_API_TOKEN still is. The cloudflare-worker target serves spec files only and keeps the LOUSHO_API_TOKEN token; see Deployment. auth.ts may also export functions named authorizeSession and authorizeApproval, next to its default export. The built server uses them as the rules of Who may use a session and Who may decide an approval, and resolveAgentDir() returns them under those names. Any other value under those names fails the load (LOUSHO_AGENT_DIR_INVALID). lousho dev has no route auth, so neither the list nor these rules apply there.

Reading the principal in the run

The principal is on the run context next to sessionId and metadata. The vendor/ model prefix chooses the provider; with OpenRouter use openrouter/<vendor>/<model> (e.g. openrouter/openai/gpt-4o-mini).
principal is separate from metadata on purpose: metadata is whatever the caller sent, principal is what auth verified. A run that is resumed from its checkpoint or after an approval keeps the principal it started with. The Slack, Discord, Teams, GitHub and Telegram channels set the sender as the principal (authenticator: 'slack', 'discord', …). Tools, approval policies, permission rules and sub-agents see it too: see Principals in tools and approvals.

Security notes

  • Sessions belong to the caller that started them by default. Once route auth accepted a caller, a session id is bound to the first principal that sends it a turn (reading an id claims nothing), and any other principal gets 403 (LOUSHO_SESSION_FORBIDDEN). That record lives in memory, per agent, for the 100,000 most recently used sessions. A stored session whose owner is not on record (after a restart, on a second replica, past that cap) is refused to every principal, its owner too. With more than one instance, or a store that outlives the process, pass authorizeSession that checks ownership against your own data. See Who may use a session.
  • Cookies need CSRF protection, which the routes give by default. A POST must be JSON (415 otherwise) and must not come from another site’s page (403, LOUSHO_REQUEST_FORBIDDEN). Keep your session cookie SameSite=Lax or Strict as well. See Cross-site requests.
  • Approvals. A decision only reaches an approval of the session in the URL (another session’s approval is a 404). By default only the caller the run acts for may decide it. If an approval must come from someone else, such as a supervisor approving a customer’s refund, set authorizeApproval. Otherwise the customer can approve their own call: the approval id is in their own stream. See Who may decide an approval.
  • Errors. The session routes send an error’s name and code with a generic message. The full error (a provider’s response body, a chat template) goes to the server log (console.error) and to onEvent. Pass exposeErrors: true to send the raw message, as lousho dev does. A missing provider package (LOUSHO_PEER_MISSING) always sends its message: the SDK’s own npm install command.
  • basic() only over HTTPS; a bearer token is a password too, so terminate TLS in front of any server that is not on localhost.
  • Keep issuer and audience set for jwt(): a token minted for another of your services is otherwise accepted here.

Principals in tools and approvals

Everything that decides or acts on the caller’s behalf gets the run’s principal, frozen (a tool or a policy that assigns to it throws): A run without a principal (no route auth, send() without principal) has none in any of these places.

In a tool

The principal comes only from route auth or a channel’s verified sender, never from the request body or the model, and a tool cannot change it.

Approval policies and permission rules

Who approved

A decision can name who made it. The approved tool sees the decider as ctx.approval.by, next to ctx.approval.note:
resolve(), answer(), streamResolve() and streamAnswer() take { principal }. The approvals route (POST /chat/:sessionId/approvals/:id) passes the caller its auth list accepted; body fields cannot set it. mountChannels() passes the user who clicked as { id, type: 'user', authenticator: <channel name> }, or, for a question answered with a message, that message’s sender. Decisions made by an approve callback, or posted to /channels/<name>/approvals/:id, have no approver. The approver never becomes the run’s principal: the approved call and the rest of the run act for the caller that paused it. A credential or a grant that belongs to that caller is used only for that caller’s calls, whoever approves.

Who may use a session

By default, once route auth accepted a caller, a session belongs to the first principal that sends it a turn (principals are compared by id, type, authenticator and issuer). Another principal gets 403 (LOUSHO_SESSION_FORBIDDEN) on GET /chat/:id, POST /chat, POST <basePath> and the useChat endpoint; decisions on its approvals are left to authorizeApproval (below). Reading an id nobody has sent a turn to yet claims nothing, so a caller cannot lock a user out of a predictable id (user-42) by reading it first. A turn with an empty input is a 400 and claims nothing, and a turn that stores nothing (it failed before saving) drops its claim. A route without auth checks nothing. All callers of one apiToken() are one principal, so they share every session; a route guarded by one bearer token (auth: '<token>', the node server or the Worker with only LOUSHO_API_TOKEN) checks no owner at all. The owner is remembered in memory, per agent object, for the 100,000 most recently used sessions. A restart, a second replica, a session unused for longer, or a host that builds its agent per request forgets it. The default then fails closed: a session that is already stored (it has a transcript or an unfinished turn) but has no owner on record is refused to every principal, including the one that started it, so nobody can take over a session by getting its owner forgotten. Only a session that was never stored can be claimed again. So for anything that runs on more than one instance, or keeps sessions across restarts, check ownership yourself with authorizeSession. createRouteHandler() and the generated node server take authorizeSession, which replaces that default (in an agent directory, export it from auth.ts: see the example under Who may decide an approval). It is asked before a caller reads a session (action: 'read'), sends it a turn ('chat', also POST <basePath> and the useChat endpoint) or decides one of its approvals ('approve'). Return false for a 403 (LOUSHO_SESSION_FORBIDDEN). Deriving the id from the caller keeps the check stateless:
authorizeSession: () => true lets every authenticated caller use every session (the behavior before this default).

Cross-site requests

A browser sends cookies with requests that another site’s page makes, so with cookie-based auth a page on evil.example could otherwise start a turn or approve a call as your user. The session routes refuse that by default:
  • a POST whose Origin is not the server’s own (its Host, or the host a proxy in front reports in X-Forwarded-Host or Forwarded: host=) and not in allowedOrigins, or that the browser marked Sec-Fetch-Site: cross-site, is 403 (LOUSHO_REQUEST_FORBIDDEN). Requests without an Origin (curl, a server, another agent) are not affected;
  • a POST body must be Content-Type: application/json (415, LOUSHO_UNSUPPORTED_MEDIA_TYPE otherwise): forms and text/plain are what another site can send without a CORS preflight.
A front end on another origin is listed in allowedOrigins (it also needs CORS headers, which your host adds); allowedOrigins: ['*'] turns the origin check off and requireJsonBody: false the content-type one. Entries are compared as origins: case, a trailing slash and a default port (https://app.example:443) do not matter. allowedHosts (off by default) refuses any request whose Host is not listed, against DNS rebinding of a server on a private address. All three work on createRouteHandler() and the generated node server; that server and the Cloudflare Worker read them from LOUSHO_ALLOWED_ORIGINS and LOUSHO_ALLOWED_HOSTS (comma-separated) and LOUSHO_REQUIRE_JSON_BODY=false. Behind a reverse proxy:
  • The proxy must tell the server the public host, or a browser’s same-site POST is 403: keep the original Host (nginx proxy_set_header Host $host;), or set X-Forwarded-Host (proxy_set_header X-Forwarded-Host $host;) or Forwarded: host=.... A default port in it (agent.example:443) matches an https://agent.example page. Otherwise list the public origin in allowedOrigins.
  • allowedHosts checks only the Host header the server receives, never the forwarded ones (a page that rebinds DNS can set those). Behind a proxy that rewrites Host, list the upstream name the proxy sends, not the public one.

Who may decide an approval

A decision posted to POST /chat/:sessionId/approvals/:id must name the session the approval belongs to; any other session answers 404, as for an approval that was already decided. POST <basePath>/approvals/:id (the route useLoushoAgent posts to) names no session, so it is checked against the approval’s own session. Then authorizeApproval({ principal, sessionId, approval }) decides; false is a 403 (LOUSHO_APPROVAL_FORBIDDEN). The default, callerOwnsApproval, lets only the caller the paused run acts for decide (approval.principal, compared by id, type, authenticator and issuer). A user can confirm their own call, and cannot decide another user’s. A run without a principal, or a route without auth, accepts any caller. When needsApproval means that someone else must approve, say who. Here a customer can no longer approve their own refund, and a supervisor can read any session (to see what they are approving) and decide in it:
In an agent directory built with lousho build --target=node-server (or docker), export the same rules from auth.ts. Here users file expense claims, a manager decides them, and nobody approves their own:
Alice’s paused claim in session alice-1 is then decided by POST /chat/alice-1/approvals/:id with the manager’s token (200); with alice’s own token it is a 403 (LOUSHO_APPROVAL_FORBIDDEN). Without these exports the built server keeps the defaults, so only alice could decide it. Two requests that decide the same approval get one continuation: while the winning decision’s continuation is still running (on the same server process), any other decision of that approval is a 409 (LOUSHO_APPROVAL_CONFLICT), whether it arrived at the same moment or while the decided tool was running; once that continuation has ended, a decision is a 404 (LOUSHO_APPROVAL_NOT_FOUND). A decision handled by another replica is a 404 there.

Pauses, crashes and forks

The principal is saved with the run’s checkpoints and approval snapshots, so a run resumed in another process (after a restart, agent.approvals.resolve(), agent.resume(), a session’s pending turn) acts for the same caller. A call that continues an unfinished checkpointed run must pass no principal (it then continues as the saved one) or the same one; another caller’s send(message, { sessionId, principal }) throws LOUSHO_CONFIG_INVALID, so its input never runs under someone else’s identity. Checkpoints and snapshots saved before this release have no principal and resume without one. agent.fork() / AgentExecutor.fork() copy a run’s checkpoint, principal included: the fork is the same caller’s run. A pending approval is not copied; the fork asks again. session.fork() copies only the conversation: the fork has no principal of its own, each of its turns runs with the principal its send() passes, and a pending approval stays with the original session.

Sub-agents

In-process sub-agents (the task tool and background tasks) act for the lead’s caller, also when their approval is resumed. A remote sub-agent (remoteAgent()) is not told who the caller is: the remote server’s own route auth decides its principal (for example the apiToken() service principal of the lead’s token).

What is stored and logged

The principal, claims included, is stored in checkpoints and approval records, which already hold the transcript; treat those stores as personal data. It is not added to AgentEvents (permission.decision included), OpenTelemetry spans or trace files, and error messages do not name callers.