Give each agent its own token, and stop trusting the body by davidmckayv · Pull Request #34 · CopilotKit/OpenBot

davidmckayv · 2026-08-20T04:21:30Z

Stacked on #33, which is stacked on #31. Review those first; this targets #33's branch.

What this changes

Closes the weakness #33 disclosed. /api/agent-tools/call authenticated with one deployment-wide secret and then read the Bot and the actor out of the request body. Anything holding that secret could spend any Bot's grants and write any person's name into the audit trail.

The trail is the product. A forgeable trail is worse than no trail, because it is believed.

Two credentials now, answering two different questions:

Which agent is calling. Its own token, issued per agent, stored here only as a SHA-256 hash. We issue it and only ever need to check one, so keeping the token itself would make a database dump a working credential for every registered agent.
Which Bot and which person the run is for. A short-lived assertion this deployment signs and hands to the agent at the start of a run. A token cannot carry this: it is minted once and reused for months, while the answer changes every run.

They are checked against each other. An assertion names the Bot it was issued for, and a call is refused unless that Bot is the one the presented token belongs to, so an agent cannot replay an assertion it happened to see and act as somebody else's Bot.

Taken from CopilotKit/openkai (a9b3722), renamed, with the demo and visitor pieces dropped.

Notes on the port

OpenKai added the columns to its base schema. We cannot: 0000 is already applied everywhere, so editing it means the columns never appear. They arrive as 0001_swift_morph.sql, and a test asserts that rather than asserting they are in the base.
sign/verify lived in OpenKai's visitor module, which is demo-only here. They are lifted into server/src/auth/signed-value.ts, keyed under a label derived from the deployment's encryption key so a signature here can never be confused with a credential ciphertext there.
The old shared secret still works as a fallback, so this is not a breaking change for a deployment mid-upgrade. It no longer carries the Bot or the actor.

Where it runs

New state that outlives a request? One column pair on agent_profiles, in Postgres.
What happens on the second replica? Correct on all of them. The token is looked up from the database, and the assertion is verified from the deployment's own key with an expiry inside it, so any replica can check a call served by any other. Nothing is held in memory.
Anything serialised? Nothing needs to be.
Anything fanned out to a browser? No.
New listener, port, or schedule? None.

Boundary and audit

Same path: grant, policy, audit, vendor.
The actor on the audit row now comes from the signed assertion, never from the body.
Fails closed. A deployment that cannot sign hands the agent nothing, and its tool calls are refused: a Bot that cannot prove whose run it is should not be spending anybody's grants.

A defect this also fixes

A run is offered two kinds of tool and no naming rule separates them: the Bot's grants, which execute through the policy, and the components the surface draws. The agent was running both. That invented results, so the Bot apologised for a chart the person was looking at, and an approval card answered on its behalf waited for a click that could never land. A call the surface owns now ends the run, which is how a browser tool is meant to work.

Proof

Driven in Chrome.

The old forgery path is closed. POST /api/agent-tools/call holding the deployment-wide token, naming a tool, with no run assertion: 401 Not authorised. Before this PR that call succeeded.
The honest path works. Risk Analyst, on LangGraph, answered "Week one: shadow two customer calls" from the notes server, with the tool line drawn before the answer.
Attribution is real. Audit row: mcp.call_succeeded, notes/search_notes, bot risk-analyst, actor dev-local-user. On Make LangChain the default harness, and let a framework Bot call tools back #33 that same row read actor agent.

17 unit tests on the token and the assertion, including that another agent presenting a valid assertion it did not earn is refused, that an edited Bot fails verification, and that an expired assertion is refused.

Migration verified on a clean database through the full chain, and db:generate reports no drift.

format:check, lint, typecheck clean. 683 pass, 5 skip, 0 fail across 78 files.

The base branch was changed.

Calling a tool back used to need one deployment-wide secret, with the Bot and the person read out of the request body. Anything holding that secret could spend any Bot's grants and write any name into the audit trail. The trail is the product, and a forgeable trail is worse than none because it is believed. Two credentials now, because they answer different questions and one cannot answer both. The token says which agent is calling. Issued per agent, held by whoever runs it, and stored here only as a hash, so a database dump is not a set of working credentials. Issuing again rotates; revoking leaves the agent able to talk and unable to reach anything outside a conversation. Null is the default, which is what a URL somebody pasted should get. The run assertion says which Bot and which person. Signed by this deployment, ten minutes long, sent in forwardedProps and handed straight back. An agent is in no position to assert who it acts for, so it carries our note instead of making a claim. They are checked against each other: an agent may only act as the Bot its token was issued for, so an assertion seen once cannot be replayed by another credentialled agent. The deployment-wide token still authenticates the Bots that ship in the box, but it no longer asserts anything. Driven end to end, not just unit tested. A registered outside agent with its own token called a granted tool and the audit row named the visitor rather than "agent". The same assertion presented with a second agent's token was refused 403, no assertion at all 401, an unknown token 401. Also fixes a latent migration bug this work uncovered. drizzle.config.ts still named computer.ts, deleted when computer use went, and did not name the policy.ts that replaced it, so action_policy looked absent and the next generated migration opened with DROP TABLE "action_policy" CASCADE. It destroys the deployment's boundary. The config now names the right file, the new columns are folded into the single baseline this repo keeps rather than a second migration, and the baseline was verified by rebuilding the database from nothing. The demo seed also refuses with an explanation when the roster has not been written yet, instead of a foreign-key error naming a constraint.

Two things the merge dropped, both found by driving it rather than by any gate. The set naming which tools this deployment runs was not built, so the filter that reads it threw `ours is not defined` and the run died before it said anything. Green typecheck, green suite, dead Bot: the variable is only reached once a model actually asks for a tool. With it back, the reason it exists matters more than the crash. A run is offered two kinds of tool that no naming rule separates: the Bot's grants, which execute through the policy and the audit trail, and the components the surface draws. A call the surface owns now ends the run, which is how a browser tool is supposed to work, the surface draws it or puts the question to a person and starts the next run with the answer. Running the loop through it instead invents a result: the Bot apologises for a chart the person is looking at, and an approval card answered on its behalf waits for a click that can never land.

The token this deployment issues an agent was minted as `okai_agt_...`, which is the other product's prefix. The prefix exists so a leaked credential can be recognised on sight, in a log or by a secret scanner, and one naming a product this is not defeats the only job it has. It is `obot_agt_` now. The panel that issues it, and the code around it, still called a Bot a teammate. That rename happened everywhere else already. Found by opening the screen. The security work these sit on was proven through the API, which is the right place to prove a refusal, and it meant nobody had looked at the thing a person actually uses to mint one.

Audited every markdown file against everything that landed today, including the work that was not mine. `docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at `4200`. #33 made `agent-langgraph` on `4201` the default precisely because the proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is watching, so following that page produced the shape the change moved away from. Three environment variables the server reads were in `.env.example` and nowhere in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34, without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`, which the container sets so one process serves both halves. Both documentation indexes had fallen behind their own directory and listed neither `deployment.md` nor `releasing.md`. `docs/development.md` gains the migration workflow the checks in #64 now enforce: never hand-edit a generated migration, write a data step with `--custom`, and what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing printed, which is the journal naming a file a rebase renamed. `drizzle-kit check` calls that state fine, because it compares schemas rather than asking whether the journal and the directory agree. The README keeps its shape: what this is, how to run it, how to deploy it, and where to read the rest.

* Sign in with Google, Microsoft or Okta, whichever a deployment has One identity provider was a decision somebody else already made. A company running this has Google or Entra or Okta and is not going to acquire another, so any one of the three turns sign-in on, several turn on several, and the sign-in screen draws a button per provider in a fixed order. Google and Entra are named providers Better Auth knows the endpoints of. Okta is not one place, so it goes through the generic OAuth plugin against its issuer, and the plugin is only registered when Okta is configured. They converge at the browser: one `signIn.social({ provider })` for all three, so the app does not know which kind it is asking for and a deployment can gain one without a rebuild. The provider list moved from the build to `/api/capabilities`. It used to be compiled into the bundle from the build machine's environment, which was survivable until the container: one image, built once, knowing nothing about the deployment that runs it, would have offered a sign-in screen that had never heard of the provider the operator configured. Nothing configured now means one administrator without a flag, so a fresh clone reaches the product without registering an OAuth client first. The lock moved from a flag to `NODE_ENV`: somewhere other people can reach, an unconfigured deployment refuses to start and names what to configure, because a public URL where every visitor is an administrator is silent and looks like it works. `OPENBOT_SINGLE_USER=true` is how somebody says they meant it. Two defects found by signing in for real rather than reading the code. Better Auth 1.7 requires an `issuer` on every account and this schema, written against 1.6, had no such column. The adapter rendered `where ( = $1 ...)` with an empty column name and the callback failed with an internal error. Migration 0002 adds it as three statements rather than the one Drizzle generates, because `ADD COLUMN ... NOT NULL` with no default fails outright on a table that already has rows, and Google's rows are backfilled with Google's real issuer so they still match at the next sign-in. `server/package.json` also asked for `^1.6.27` while 1.7.1 was what resolved, leaving three copies of the adapter installed. Pinned to what actually runs. * Make the administrator list mean something after the first sign-in Two ways a deployment could end up with nobody who can administer it, and no way back from either. `INITIAL_ADMIN_EMAILS` was optional. Configure sign-in without it and everybody arrives as a plain user, nobody sees the admin screens, and nobody can promote anyone, because the role is written from that list and no route anywhere changes one. `.env.example` ships it commented out, so copying the example and adding a provider was enough to do it. Sign-in now refuses to start without it. The role was also written once, in the create hook. Adding yourself to the list after you had already signed in did nothing at all: the row said `user`, for ever. It is now reconciled on every sign-in, which also means an address taken off the list loses `admin` next time it signs in. `user_roles` is a set and the guard takes `admin` if any row says so, so reconciling deletes the rows that should not be there rather than only inserting one, both inside a transaction: between the two a request on another process would find no role at all and be refused with a 403 that reads as a permissions bug. Driven on the real path rather than reasoned about: the same account went admin, then user with the address removed, then admin again with it restored. The middle step is what the old hook could not do. * Make the administrator list a floor, and put each provider's mark on its button The list and an admin screen have to be able to disagree without one silently undoing the other. So `INITIAL_ADMIN_EMAILS` is a floor: an address it names is made an administrator at every sign-in and cannot be demoted, which is the way back in when the last administrator demotes themselves by accident. Everybody else is left exactly as they are, because their role is the admin screen's to decide and a sign-in that rewrote it would make that screen lie the moment they came back. That is a change from an hour ago, when sign-in rewrote every role from the list and would have reverted any promotion made in a screen that does not exist yet. The buttons now carry each provider's own mark, drawn inline rather than fetched: this is the one page somebody reaches before they have a session, so a mark that arrives over the network is one that can be missing exactly when the page has to look trustworthy, and it asks nothing of a third party from an unauthenticated page. Google's guidelines require the standard colour G at its own aspect ratio and require their button be at least as prominent as any other sign-in option, so all three are the same size and weight and none of them is the loud one. Okta's is monochrome, which their guidelines allow: it is not a consumer button anybody recognises by colour, it is whichever Okta the company uses, and it stays legible in both themes without a second asset. * Let an administrator decide who else is one An environment variable was the only way to grant the administrator role, and no route anywhere changed one. That is not how a company runs a deployment: the people who need access arrive after the deployment does. So a People screen. Everybody who has signed in, the providers they came through, when they were last here, and two decisions per row. Removing somebody is both halves or it is theatre. The deny list stops the next sign-in and deleting their sessions stops the current one, because otherwise a removed person keeps working until their cookie happens to expire, which can be days. It is keyed on the email address rather than the user id: deleting the row is not removal, since the next sign-in through the provider creates it again with a fresh id and no memory of having been removed. Three refusals, all enforced on the server and only mirrored in the browser. Nobody may demote themselves or remove their own access, because either locks them out of the screen that would undo it, and on a deployment with one administrator that is the whole deployment. And somebody named in INITIAL_ADMIN_EMAILS may be neither, because the floor promotes them again at their next sign-in and the screen would be lying until then. Every change writes a row. The table holds the current answer; the trail is the only thing that can say who changed it and when. Found by driving it: people who had never signed in sorted above people who just had, because Postgres puts nulls first on a descending order. On a real deployment that is the whole first screen given to people who have never used it. * Take a company's own identity provider, by SAML or OIDC The three configured providers cover a company that uses Google, Entra or Okta. They do not cover a company that runs its own identity provider, which is most of the ones that ask, and which cannot be configured up front because the deployment is built before it knows whose IdP it will trust. So they are registered while running. An administrator pastes the metadata their identity team supplied and the provider is stored against an email domain. Somebody signing in types their address, and the part after the @ decides which provider they are handed to, so a company mid-merger can run two at once. No password is asked for and none is checked here. Registering, changing and removing one is administrator-only. Better Auth guards those routes with `sessionMiddleware`, which asks only that somebody is signed in, and that is the wrong bar: registering a provider for a domain means anybody it vouches for can sign in, so a plain user reaching it could mint themselves colleagues. The gate sits in front of the handler and is tested. The sign-in screen grows the email box only when a provider is registered, and the capability that says so is a boolean rather than a list: naming them would tell anybody who loads the page which companies use this deployment. Driven end to end. A registered SAML provider produces a real signed SAMLRequest redirect for an address at its domain and a 404 for one that is not, the same delete call answers 403 signed out and 200 as an administrator, and the sign-in screen adds and drops the email box as the last provider comes and goes. * Find an address for somebody arriving from Entra, whatever claim it is in The sign-in flow really is the same for all three: authorization code with PKCE, discovery, an ID token. Google and Entra run through the same function. The claims inside that token are where they stop agreeing. Entra does not always send `email`. Microsoft return it only when the profile carries an email attribute, and a multi-tenant application may receive no optional claims at all, because an external user's token is minted by their own tenant and does not inherit this application's claim configuration. `common`, the default tenant here, is multi-tenant. Better Auth maps `email` straight through with no fallback, so on those deployments it arrives undefined. That is worse here than in most products, because every authorization decision OpenBot makes about a person is keyed on their address: INITIAL_ADMIN_EMAILS, the role, the deny list and the People screen all read it. Somebody would sign in successfully, match no administrator, and land as a plain user with nothing on any screen explaining why. So `upn` first, then `preferred_username`, and only if it looks like an address: the OIDC spec explicitly does not promise that claim is one. If none of the three is there, nothing is returned and Better Auth refuses the sign-in, which is a better answer than quietly admitting somebody the deployment cannot recognise. The reason is logged with the claims that did arrive. Found by reading the provider Microsoft-side rather than by testing, since there are no Entra credentials here yet. * Generate the schema steps, and write only the data step The issuer migration was one file I had edited by hand after Drizzle generated it, because the generated `ADD COLUMN ... NOT NULL` fails outright on a table that already has rows. Editing a generated file is the wrong fix: it leaves a file that no longer matches what the generator produced. It is three steps instead, and only the middle one is written: 0002 generated the column, nullable, and the two new tables 0003 custom the backfill 0004 generated the column made required `drizzle-kit generate --custom` is Drizzle's own mechanism for this, and their documentation names data seeding as the reason it exists. A generator diffs schema against schema, so "the rows whose provider is Google get Google's issuer" cannot come out of one: it is not in the schema. The generatable alternative is a column default, and it is wrong rather than merely inelegant. Every existing Google account would take the placeholder, stop matching `https://accounts.google.com` at that person's next sign-in, and Better Auth would create them a second account. Driven both ways with `drizzle-kit migrate` itself rather than by hand: from empty, and against a database already holding Google, credential and Microsoft accounts, where the three rows come out with Google's real issuer and the synthetic form for the rest. Worth knowing for the check that landed in #64: `drizzle-kit check` reports "Everything's fine" when a journal entry names a migration file that does not exist, which is a state a rebase can produce. It cost an hour here. The drift probe does not catch it either, since both look at schemas rather than at whether the journal and the directory agree. * Say what sign-in does, everywhere it is documented The configuration reference still described Google as the only provider and described `INITIAL_ADMIN_EMAILS` as optional, which is now a start-up failure. It carries all three providers, what each needs, the callback URL to register, and why the administrator list is required. The architecture notes gain the parts a reader cannot infer from the code: that one resolver answers both questions a run asks about a person, that the configured list is a floor rather than a one-off, that registering an identity provider is administrator-only where the upstream plugin asks only for a session, and that removing somebody denies the address rather than deleting the row, since deleting it is not removal. Two lines in the README's feature list, because sign-in and deciding who gets in are now things the product does rather than things it lacks. The generated Drizzle snapshots are formatted, which is what the committed ones already were: `drizzle-kit generate` writes them without a trailing newline and the format check refuses that. * Bring the docs up to what is actually merged Audited every markdown file against everything that landed today, including the work that was not mine. `docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at `4200`. #33 made `agent-langgraph` on `4201` the default precisely because the proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is watching, so following that page produced the shape the change moved away from. Three environment variables the server reads were in `.env.example` and nowhere in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34, without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`, which the container sets so one process serves both halves. Both documentation indexes had fallen behind their own directory and listed neither `deployment.md` nor `releasing.md`. `docs/development.md` gains the migration workflow the checks in #64 now enforce: never hand-edit a generated migration, write a data step with `--custom`, and what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing printed, which is the journal naming a file a rebase renamed. `drizzle-kit check` calls that state fine, because it compares schemas rather than asking whether the journal and the directory agree. The README keeps its shape: what this is, how to run it, how to deploy it, and where to read the rest. * Tell the image check it meant to run without sign-in The check boots the container with no identity provider, and the image sets NODE_ENV=production, where that combination now refuses to start rather than serve a deployment on which every visitor is an administrator. So the check has to declare it, which is what the flag is for. It was passing `OPENBOT_DEV_NO_AUTH=1`, which the code has never accepted: both the old flag and the new one compare against the exact string "true". It did nothing, and nothing noticed, because before this branch a deployment with no provider still started and answered on an unauthenticated route. The refusal turned a silent no-op into a visible failure, which is the check working. Reproduced locally with the same command the job runs: answers on /api/capabilities in four seconds, nothing respawning after fifteen, and the `eventsource` import error that appeared in the failing log is absent, since it was the crash loop rather than a fault of its own. * Put the upgrade note where somebody upgrading will find it Two configurations that start today refuse to after this, and both were buried mid-paragraph in Added and Changed. They are four lines at the top of Unreleased now, saying what to set rather than what used to happen. Rebased onto #68, which took the deployment's environment away from a Bot's shell. Checked on the running computer rather than trusting the tests: `GOOGLE_OAUTH_CLIENT_SECRET`, which this branch introduces, is absent from a command's environment without anybody having added it to a list. That is the allowlist earning its shape.

davidmckayv requested review from MikeRyanDev, guidovizoso and tylerslaton as code owners August 20, 2026 04:21

guidovizoso previously approved these changes Aug 20, 2026

View reviewed changes

davidmckayv force-pushed the feat/langchain-default branch from aae75d5 to 7e9e0bd Compare August 20, 2026 16:14

davidmckayv force-pushed the feat/agent-callback-tokens branch from e8e5173 to b014b2a Compare August 20, 2026 16:14

Base automatically changed from feat/langchain-default to main August 20, 2026 16:16

davidmckayv added 3 commits August 20, 2026 09:16

davidmckayv force-pushed the feat/agent-callback-tokens branch from b014b2a to 13c1b9a Compare August 20, 2026 16:17

davidmckayv enabled auto-merge (squash) August 20, 2026 16:18

davidmckayv merged commit 3ccd16f into main Aug 20, 2026
3 checks passed

davidmckayv deleted the feat/agent-callback-tokens branch August 20, 2026 16:19

This was referenced Aug 20, 2026

agent-bot and agent-langgraph accept unauthenticated /ag-ui runs #50

Closed

Require a token on every call from the server to a Bot #52

Merged

Navigation Menu

Uh oh!

Give each agent its own token, and stop trusting the body - #34

Give each agent its own token, and stop trusting the body#34
davidmckayv merged 3 commits into
mainfrom
feat/agent-callback-tokens

davidmckayv commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

davidmckayv commented Aug 20, 2026

What this changes

Notes on the port

Where it runs

Boundary and audit

A defect this also fixes

Proof

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants