Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { MAX_IMAGE_BYTES } from "@openbot/shared/attachments";
import type { Hono as HonoApp, MiddlewareHandler } from "hono";
import { Hono } from "hono";
import { bodyLimit } from "hono/body-limit";
import { serveStatic } from "hono/bun";
import { enterpriseControls } from "./admin/controls";
import { createEnterpriseGate } from "./admin/gate";
import { createEnterpriseAdminRoutes } from "./admin/routes";
import {
authoriseAgentCall,
parseAgentToolCallInput,
type RunAssertion,
sameToken,
} from "./agents/callback-token";
import { computerAccessCheck } from "./agents/computer-access";
import { deploymentCanIsolate } from "./agents/isolation";
import {
type BotLifecycleServices,
createBotLifecycleRoutes,
} from "./agents/lifecycle-routes";
import type { BotAccessCheck } from "./agents/profile-policy";
import type { AgentProfileStore } from "./agents/profile-store";
import { createAgentRoutes } from "./agents/routes";
import { createApprovalRoutes } from "./approvals/routes";
import type { ApprovalService } from "./approvals/service";
import {
type AuditEventType,
type AuditInitiator,
AuditQueryError,
type AuditReader,
type AuditStore,
auditEventsToCsv,
auditQueryFromUrl,
DEPLOYMENT_INITIATOR,
readAuditExportRows,
recordAuditEvent,
} from "./audit";
import { createDevRequireUser } from "./auth/dev-actor";
import {
type AppVariables,
type AuthService,
createRequireUser,
type RoleRepository,
requireAdmin,
} from "./auth/guards";
import type { IdentityProviderStore } from "./auth/identity-provider-store";
import { desktopAuthPage } from "./auth/native-browser";
import {
type BotBrowserRouteDeps,
createBotBrowser,
} from "./browser/bot-browser";
import {
type BrowserRouteDeps,
browserConnectionRevoked,
createBrowserRoutes,
} from "./browser/routes";
import {
createAttachmentRoutes,
createChannelAttachmentRoutes,
} from "./channels/attachments";
import type { ChannelEventHub } from "./channels/events";
import { createGroupRoutes, type GroupConversations } from "./channels/group";
import { type ChannelStore, createChannelRoutes } from "./channels/routes";
import type { ThreadIdentity } from "./channels/thread-identity";
import { createThreadRoutes } from "./channels/thread-routes";
import { createThreadReader } from "./channels/thread-status";
import { createComponentRoutes } from "./components/routes";
import type { SandboxedStore } from "./components/sandboxed";
import { createSandboxedRoutes } from "./components/sandboxed-routes";
import type { ComponentStore } from "./components/store";
import type { ComputerGateway } from "./computer/gateway";
import type { PageFrameStore } from "./computer/page-frames";
import type { PolicyStore } from "./computer/policy-store";
import { createComputerRoutes } from "./computer/routes";
import { configuredAuthProviders, type DeploymentConfig } from "./config";
import {
type CredentialAdminService,
type CredentialInput,
CredentialRefusedError,
} from "./credentials";
import type { Database } from "./db/client";
import { withoutStatement } from "./db/query-failure";
import {
createDeliveryRoutes,
createDeliveryWebhookRoutes,
} from "./delivery/routes";
import { mountDesktopConnectionFailure } from "./desktop-connection-failure";
import { createTranscriptionProvider } from "./dictation/provider";
import { createDictationRoutes } from "./dictation/routes";
import type { HostAccessBroker } from "./host-access/broker";
import { createHostAccessRoutes } from "./host-access/routes";
import { identityRoutes } from "./identity/routes";
import type { IdentityStore } from "./identity/store";
import { createIntelligenceClient } from "./intelligence-client";
import {
createLearningRoutes,
type LearningAdminDependencies,
} from "./learning/routes";
import {
createPersonalLearningRoutes,
type PersonalLearningRouteDeps,
} from "./learning/sharing-routes";
import type { MemoryIngestion } from "./memory/ingestion";
import { createMemoryRoutes } from "./memory/routes";
import type { MemoryStore } from "./memory/store";
import { parsePageLimit } from "./paging";
import { createPasswordRoutes, createSignInRoutes } from "./passwords/routes";
import type { SignInService } from "./passwords/service";
import type { OnboardingStore } from "./people/onboarding";
import { createProfileRoutes, type ProfileStore } from "./people/profile";
import { MAX_PAGE, type PeopleStore } from "./people/store";
import type { BrokerProvider } from "./plugins/access";
import type { AccountModeSwitch } from "./plugins/account-mode";
import type { ComposioBroker } from "./plugins/broker";
import { createPluginRoutes } from "./plugins/routes";
import { createSharedUseRoutes } from "./plugins/shared-use-routes";
import type { SharedUseStore } from "./plugins/shared-use-store";
import {
isDeploymentFault,
PluginRefusedError,
type PluginStore,
} from "./plugins/store";
import { REFUSAL_MARKER, vendorAnswer } from "./plugins/tools";
import type { ProactiveEngine } from "./proactive/engine";
import { createProactiveRoutes } from "./proactive/routes";
import type { ProactiveStore } from "./proactive/store";
import {
type ModelProviderProxy,
mountProviderOAuthProxy,
} from "./provider-oauth";
import { createRequireRecorder } from "./recorder/guard";
import { createRecorderRoutes } from "./recorder/routes";
import type { RecorderExtensionDeps } from "./recorder/wiring";
import type { ResponsibilityBindingStore } from "./responsibilities/bindings";
import type { ResponsibilityEngine } from "./responsibilities/engine";
import { createGithubResponsibilityRoutes } from "./responsibilities/github";
import { createResponsibilityRoutes } from "./responsibilities/routes";
import type { TriggerStore } from "./responsibilities/triggers";
import type { ResponsibilityStore } from "./responsibilities/types";
import { createRoutineRoutes, type RoutineStore } from "./routines/routes";
import type { RoutineRunner } from "./routines/runner";
import type { IntentRouter } from "./routing/classify";
import { createRoutingRoutes } from "./routing/routes";
import { createCoworkerRoutingService } from "./routing/service";
import type { SelfHostBanner } from "./self-host-banner";
import { createTeamBotRoutes } from "./team-bots/routes";
import type { TeamBots } from "./team-bots/team-bots";
import type { PackageStatusReader } from "./tenant-package";
import {
INSTRUCTIONS_LIMIT,
InstructionsTooLongError,
type UserInstructionsStore,
} from "./user-instructions";
import type { UserPreferencesStore } from "./user-preferences";
import { userPreferencesRoutes } from "./user-preferences-routes";
import { createVoiceProvider } from "./voice/provider";
import { createVoiceRoutes } from "./voice/routes";
import type { VoiceSessionServices } from "./voice/session-routes";
import {
DIRECTORY_PATH as WEB_BOT_AUTH_DIRECTORY_PATH,
directoryResponse as webBotAuthDirectory,
} from "./web-bot-auth";
/**
* How much of a multipart body is boundary, headers and other fields rather than file.
*
* Generous on purpose. Measured against what the composer actually sends — one `file` part and one
* `uploadGroup` field — the framing is 360 bytes for a short filename and 614 for a 255-character
* one; a filename full of non-ASCII percent-encodes to a few times that and is still nowhere near
* this. 64 KiB is therefore an allowance no honest request can exhaust, and it raises the amount of
* memory a hostile request can pin by 0.8%, which was never the number that mattered.
*/
const MULTIPART_FRAMING_ALLOWANCE = 64 * 1024;
/**
* The ceiling on the whole POST body of a channel attachment upload.
*
* THIS IS NOT `MAX_IMAGE_BYTES`, AND THE DIFFERENCE IS THE POINT. Every other gate on this path —
* the composer's pre-check, `attachmentsConfigFor`'s `maxSize`, the handler's own 413 — measures
* THE FILE. This one measures THE ENVELOPE: `bodyLimit` runs before anything has parsed the
* multipart body, so all it can count is bytes on the wire, file and framing together.
*
* Set to `MAX_IMAGE_BYTES` exactly, those two units were silently treated as one, and the ~360
* bytes of boundary and headers wrapped around a file at the documented ceiling were enough to push
* the body over it: an 8,388,608-byte image — the exact number the composer publishes as the limit —
* was refused 413, while 8,388,308 bytes went through. A limit nobody can reach is a limit that is
* wrong, so the envelope's ceiling is the file's ceiling plus room for the envelope.
*
* The slack costs nothing it was protecting against. A body between the two numbers is still read
* into memory, and then still refused by the handler once `file.size` is a thing anybody can look
* at — which is where a text upload, whose real limit is `MAX_FILE_BYTES`, is refused too. What the
* door exists to stop is the 2GB body, and it still does.
*/
export const UPLOAD_BODY_LIMIT_BYTES =
MAX_IMAGE_BYTES + MULTIPART_FRAMING_ALLOWANCE;
/**
* One row for something an administrator did to somebody's access.
*
* The address is on the row rather than only the user id, because the id means nothing to a person
* reading the trail a year later and the user row may be gone by then.
*/
export type DeploymentToolCallInput = {
name: string;
args: Record<string, unknown>;
botId: string;
actorId: string;
initiator?: AuditInitiator;
/** Full verified scope. A caller cannot choose a different source thread, depth or lease. */
run: RunAssertion;
};
export type DeploymentToolCaller = (
input: DeploymentToolCallInput,
) => Promise<{ text: string; isError: boolean } | null>;
async function recordPersonEvent(
auditStore: AuditStore | undefined,
context: { var: AppVariables },
eventType:
| "person.role_changed"
| "person.access_revoked"
| "person.access_restored",
person: { id: string; email: string },
payload: Record<string, unknown>,
) {
if (!auditStore) return;
await recordAuditEvent(auditStore, {
eventType,
targetType: "person",
targetId: person.id,
actorUserId: context.var.actor.id,
payload: { email: person.email, ...payload },
});
}
export function createApp(
config: DeploymentConfig,
auth?: AuthService,
roleRepository?: RoleRepository,
auditReader?: AuditReader,
credentialService?: CredentialAdminService,
packageStatusReader?: PackageStatusReader,
/**
* The CopilotKit endpoint, already built by the caller.
*
* Passed in rather than constructed here so this module never imports the runtime. The runtime
* pulls in `eventsource`, which Bun cannot `require()` from a test, so importing it at module
* scope broke every server test that touches createApp even though none of them use CopilotKit.
*/
copilotHandler?: HonoApp,
/** The single governed computer module: policy, audit trail, transport, and provider lifecycle. */
computerGateway?: ComputerGateway,
/** What the gateway enforces, and what an administrator can change while running. */
computerPolicy?: PolicyStore,
/** Bots as durable objects: profile, roster, visibility. */
agentProfileStore?: AgentProfileStore,
/** The durable channels a Bot runs in. */
channelStore?: ChannelStore,
/** Live channel activity. Absent leaves the routes working, just without the socket. */
channelEvents?: ChannelEventHub,
/**
* Where a Bot's own refusal is written.
*
* Separate from `auditReader`, which only reads: this writes, and it is the one thing in the trail
* that is not decided by the gateway, a model declining before it calls anything.
*/
auditStore?: AuditStore,
/**
* Which components each Bot may answer with.
*
* Absent leaves the app working and every Bot answering in prose, which is the correct degraded
* behaviour: a deployment that cannot reach its grant table must not fall back to granting
* everything.
*/
componentStore?: ComponentStore,
/**
* The MCP servers and packaged skills this deployment has, and which Bots hold them.
*
* Absent leaves every Bot with the tools it was born with, which is the correct degraded
* behaviour: a deployment that cannot reach its grant table must offer nothing extra rather than
* fall back to offering everything.
*/
pluginStore?: PluginStore,
/**
* Components authored in the browser rather than compiled into the build.
*
* Absent leaves the compiled gallery working exactly as before, which is the correct degraded
* behaviour: the React path is the primary one and does not depend on this.
*/
sandboxedStore?: SandboxedStore,
/**
* How this deployment names the threads it mints.
*
* Absent leaves the direct Bot chat generating its own id in the browser, which works and simply
* says nothing about which deployment the conversation belongs to.
*/
threadIdentity?: ThreadIdentity,
/**
* Who has signed in, and what an administrator may do about them.
*
* Absent leaves the people screen answering 503 rather than an empty list, which is the honest
* degraded behaviour: "nobody has signed in" and "this deployment cannot tell you" are different
* answers and an administrator deciding who has access needs to know which one they are reading.
*/
peopleStore?: PeopleStore,
/**
* The enterprise identity providers this deployment has registered.
*
* Read here rather than through Better Auth's own listing route, which scopes to the person asking:
* a company's Okta tenant belongs to the deployment, not to whichever administrator pasted the
* metadata in. See identity-provider-store.ts.
*/
identityProviders?: IdentityProviderStore,
/**
* Chooses which coworker an untagged message is for, before a channel is pinned to one.
*
* Passed in already built, like the copilot handler, so this module never imports the model
* client. Absent leaves the composer's existing behaviour untouched: an untagged message goes to
* the default coworker, which is exactly the failsafe the router itself falls back to.
*/
intentRouter?: IntentRouter,
/**
* Where the frame a browsing turn ended on is kept.
*
* Appended last on purpose: these are positional, so inserting one anywhere else silently
* shifts every existing call site's arguments by one.
*
* Absent leaves the transcript working and past turns without a picture, which is the correct
* degraded behaviour: a conversation that cannot show what it saw is better than one that shows
* the wrong thing.
*/
pageFrames?: PageFrameStore,
/**
* Fires one routine run with nobody's browser open, when the worker hands one back.
*
* Appended last, like `pageFrames`: these are positional, so inserting one anywhere else silently
* shifts every existing call site's arguments by one.
*
* Absent leaves the internal `/internal/routines/run` route unmounted rather than mounted and
* refusing every call: a deployment that never built a worker has no door for it, not a locked one.
*/
routineRunner?: RoutineRunner,
/**
* A person's own standing instructions: the list, and a switch to stop one.
*
* Appended last, like `routineRunner` beside it: these are positional, so inserting one anywhere
* else silently shifts every existing call site's arguments by one.
*
* Absent leaves the routes unmounted rather than mounted and refusing every call, the same
* degraded shape every other optional store here takes: a deployment that never built the store
* has no door for this at all, not a locked one.
*/
routineStore?: RoutineStore,
/**
* Where each person is in first-run onboarding.
*
* Appended last, like everything above it: these are positional, so inserting one anywhere else
* silently shifts every existing call site's arguments by one.
*
* Absent leaves /api/me reporting no onboarding to track, which is the correct degraded
* behaviour: a deployment that cannot read the status must not lock everybody behind a gate
* nothing can finish.
*/
onboardingStore?: OnboardingStore,
/**
* One person's standing instructions, which every built-in coworker they run is told.
*
* Appended last, like everything above it: these are positional, so inserting one anywhere else
* silently shifts every existing call site's arguments by one.
*
* Absent leaves the routes answering 503 rather than "you have written none". The difference
* matters on exactly this screen: a person who cannot be told what they saved would otherwise be
* shown an empty box, and the obvious thing to do with an empty box is fill it in again.
*/
userInstructions?: UserInstructionsStore,
/**
* The database behind a channel's staged and sent files: upload, fetch, delete.
*
* Appended last, like everything above it: these are positional, so inserting one anywhere else
* silently shifts every existing call site's arguments by one.
*
* Absent leaves the routes unmounted rather than mounted and refusing every call, the same
* degraded shape every other optional store here takes: a deployment that never built the
* database has no door for this at all, not a locked one.
*/
attachmentDatabase?: Database,
/** Session-only broker for native owner-approved host folder access. */
hostAccessBroker?: HostAccessBroker,
/** Fresh desktop-only bearer token for the native host worker poll/result channel. */
desktopHostToken?: string,
/** Server-owned tools that are not MCP but use the same signed agent callback route. */
deploymentToolCaller?: DeploymentToolCaller,
/**
* The broker behind apps a person connects through Composio rather than an administrator
* registering an MCP server.
*
* Appended last, like everything above it: these are positional, so inserting one anywhere else
* silently shifts every existing call site's arguments by one.
*
* Passed in already built, like the copilot handler and the intent router, so this module never
* imports the vendor's package. Absent leaves the plugin surface reporting that no broker is
* configured, which is the correct degraded behaviour: a deployment with no Composio API key has
* no app directory to offer, rather than one that lists apps nobody can connect.
*/
composio?: { broker: ComposioBroker; provider: BrokerProvider },
/** Native model OAuth stays server-side; callers hold only a separate local bearer. */
modelProviderProxy?: ModelProviderProxy,
userPreferences?: UserPreferencesStore,
voiceSessions?: VoiceSessionServices,
learning?: LearningAdminDependencies,
coworker?: {
approvals?: ApprovalService;
/** The Recorder extension's routes and guards (recorder/wiring.ts). Absent, nothing about it is mounted. */
recorder?: RecorderExtensionDeps;
/** A person's own OpenBot browser, with the Recorder in it already connected (browser/routes.ts). Absent, nothing
* about it is mounted and the app shows no Browser button. */
browser?: Omit<BrowserRouteDeps, "requireUser" | "auditStore">;
/** A Bot's browser worked by a person: its bar and Record (browser/bot-browser.ts), under the computer routes. Absent,
* or with no computer, nothing about it is mounted. */
botBrowser?: Omit<
BotBrowserRouteDeps,
"gateway" | "auditStore" | "botName"
>;
/** Settings, Learning: who else's Bots use a person's own learned Skills. Absent, the screen has nothing to read. */
personalLearning?: PersonalLearningRouteDeps;
/**
* Shared apps: who may use an app's one team account, and the switch that makes an app Shared.
*
* A field here rather than another positional parameter. Everything from `auditReader` on is
* optional and positional, so a 37th argument is one an caller can misplace silently — the trap
* `composio` and `connect` are both commented for. One object carries both halves because every
* surface that needs one needs the other: the plugin routes switch modes and record approvals,
* the approvals inbox answers requests, and publishing or assigning a Bot re-checks what it was
* approved for. Absent, none of those surfaces exists — and nothing can turn an app Shared.
*/
shared?: { modes: AccountModeSwitch; use: SharedUseStore };
/** The private sign-in form and the Passwords vault. See passwords/service.ts. */
passwords?: SignInService;
delivery?: {
authenticated: Omit<
Parameters<typeof createDeliveryRoutes>[0],
"requireUser"
>;
webhooks: Parameters<typeof createDeliveryWebhookRoutes>[0];
};
memory?: { store: MemoryStore; ingestion: MemoryIngestion };
proactive?: { store: ProactiveStore; engine: ProactiveEngine };
responsibilities?: {
store: ResponsibilityStore;
engine: ResponsibilityEngine;
bindings: ResponsibilityBindingStore;
/** Event triggers: owner management, public signed ingress and optional SES/SNS email. */
triggers?: {
store: TriggerStore;
emailDomain: string | null;
ingressRoutes: Hono;
emailRoutes: Hono | null;
};
};
groups?: GroupConversations;
teamBots?: TeamBots;
/** Pause, reset, Activity and attention for a person's own Bots. See agents/lifecycle.ts. */
lifecycle?: BotLifecycleServices;
},
/**
* Whether to offer help self-hosting, which also hides it from a deployment that pays for
* Intelligence. Absent falls back to the operator's switch alone, so a test or a build without the
* resolver still answers from `config.selfHostBanner` rather than asking the network.
*/
selfHostBanner?: SelfHostBanner,
/** A person's own linked accounts. Absent answers 503 on /api/identity. */
identity?: IdentityStore,
/** The GitHub sign-in callback, built by the caller; mounted behind requireUser ahead of /api/identity. */
identityGithubCallback?: Hono<{ Variables: AppVariables }>,
profileStore?: ProfileStore,
) {
const app = new Hono<{ Variables: AppVariables }>();
mountDesktopConnectionFailure(app, desktopHostToken);
mountProviderOAuthProxy(app, modelProviderProxy);
app.get("/health", (context) => context.json({ status: "ok" }));
// The public key Bots' browsers sign their requests with, where Cloudflare and any other verifier
// look for it. Public by design, and absent when Web Bot Auth is off. See web-bot-auth.ts.
const webBotAuth = config.webBotAuth;
if (webBotAuth) {
app.get(WEB_BOT_AUTH_DIRECTORY_PATH, (context) =>
webBotAuthDirectory(context.req.raw, webBotAuth),
);
}
// Projected, never the raw runtime. config.runtime carries the Intelligence contract, including
// INTELLIGENCE_API_KEY and the licence token, and this endpoint is reachable by anyone. Returning
// the object wholesale would serve deployment secrets to the browser. Add fields here explicitly.
app.get("/api/capabilities", async (context) =>
context.json({
mode: config.runtime.mode,
durableHistory: config.runtime.durableHistory,
/*
* Whether a Bot may answer with an interface it wrote itself.
*
* Projected because the browser holds half of this capability. The runtime middleware turns a
* generated interface into the events that paint it, and the SDK's provider registers the tool
* that produces one; a deployment that switched the runtime half off while the browser went on
* offering the tool would have Bots writing interfaces nothing ever draws. One flag, read by
* both halves, so off means off.
*/
generativeUi: config.generativeUi,
// Whether to offer help self-hosting OpenBot. A fork running it for its own people turns it off,
// and a deployment that pays for Intelligence never sees it. See self-host-banner.ts.
selfHostBanner: selfHostBanner
? await selfHostBanner.shown()
: config.selfHostBanner,
/*
* Whether this is somebody trying OpenBot on their own machine, not an organization's
* deployment. Onboarding reads it to explain where OpenBot can run, which only the person
* evaluating it needs and an organization's employees should never be pitched.
*
* Single-user mode, not a new switch: it is already true only with no identity provider and
* no address anybody else can reach (see `singleUserAllowed` in config.ts), which is exactly
* a local trial, and an operator cannot forget to set it.
*/
localEvaluation: config.singleUser,
transcription: Boolean(config.transcription),
voice: Boolean(config.voice),
/*
* Which identity providers this deployment can sign somebody in with.
*
* Ids only, never the credentials: `configuredAuthProviders` returns names, and the clients
* and secrets behind them stay in `config.auth`, which is not projected here.
*
* Answered at runtime rather than baked into the build, because the container image is built
* once and knows nothing about the deployment that will run it. A sign-in screen compiled on a
* build machine cannot offer a provider that machine had never heard of.
*/
authProviders: configuredAuthProviders(config.auth),
/*
* Whether any enterprise identity provider has been registered.
*
* A count, not a list. The sign-in screen only needs to know whether to offer the email box
* that routes by domain; naming the providers would tell anybody who loads the page which
* companies use this deployment, which is not theirs to have before they sign in.
*/
ssoConfigured: ((await identityProviders?.list()) ?? []).length > 0,
/*
* Whether an administrator requires SSO. The screen then leads with SSO and keeps social
* sign-in only as the administrators' audited break-glass; the server refuses everybody else.
*/
ssoRequired:
enterpriseControls()?.snapshot()?.settings.ssoRequired === true,
}),
);
/*
* Registering an identity provider is an administrator's decision, not a signed-in one.
*
* Better Auth's SSO plugin guards these with `sessionMiddleware`, which asks only that somebody is
* signed in. That is the wrong bar here: registering an IdP for a domain means anybody it vouches
* for can sign in, so a plain user reaching this could mint themselves colleagues. The routes are
* mounted through this handler, so the check goes in front of it.
*/
const ADMIN_ONLY_AUTH_ROUTES = new Set([
"/api/auth/sso/register",
"/api/auth/sso/update-provider",
"/api/auth/sso/delete-provider",
]);
const AUTH_ROUTE_EVENTS: Record<string, AuditEventType | undefined> = {
"/api/auth/sso/register": "identity_provider.registered",
"/api/auth/sso/delete-provider": "identity_provider.removed",
};
app.on(["GET", "POST"], "/api/auth/*", async (context) => {
if (
context.req.method === "GET" &&
new URL(context.req.url).pathname === "/api/auth/desktop" &&
!config.organizationAuthUrl
) {
return desktopAuthPage(
context.req.raw,
configuredAuthProviders(config.auth),
);
}
if (!auth) {
return context.json(
{ error: "No identity provider is configured." },
503,
);
}
if (ADMIN_ONLY_AUTH_ROUTES.has(new URL(context.req.url).pathname)) {
const session = await auth.api.getSession({
headers: context.req.raw.headers,
// Fresh, not the cookie cache: a role changed a moment ago has to apply to this request.
query: { disableCookieCache: true },
});
const roles = session?.user
? ((await roleRepository?.rolesForUser(session.user.id)) ?? [])
: [];
if (!roles.includes("admin")) {
return context.json(
{ error: "Only an admin can change identity providers." },
403,
);
}
}
const eventType =
AUTH_ROUTE_EVENTS[new URL(context.req.url).pathname] ?? undefined;
// Read before the handler runs, because it consumes the stream: a clone taken afterwards is of
// a request whose body is already gone, and the row would name no provider.
const named =
auditStore && eventType
? ((await context.req.raw
.clone()
.json()
.catch(() => null)) as { providerId?: unknown } | null)
: null;
const answer = await auth.handler(context.req.raw);
if (auditStore && eventType && answer.ok) {
const session = await auth.api.getSession({
headers: context.req.raw.headers,
query: { disableCookieCache: true },
});
await recordAuditEvent(auditStore, {
eventType,
targetType: "identity_provider",
...(typeof named?.providerId === "string"
? { targetId: named.providerId }
: {}),
...(session?.user ? { actorUserId: session.user.id } : {}),
payload: {
...(typeof named?.providerId === "string"
? { providerId: named.providerId }
: {}),
...(session?.user?.email ? { by: session.user.email } : {}),
},
});
}
return answer;
});
const authenticationUnavailable: MiddlewareHandler<{
Variables: AppVariables;
}> = async (context) =>
context.json({ error: "No identity provider is configured." }, 503);
// One administrator, when nothing is configured to sign anybody in. Checked first, and only ever
// true when there is no provider, so a configured deployment cannot fall back to it.
const requireUser = config.singleUser
? createDevRequireUser()
: auth && roleRepository
? createRequireUser(auth, roleRepository)
: authenticationUnavailable;
// Enterprise controls: capability switches and the model allowlist in front of the routes they
// govern, the admin screen's API, and the SCIM verbs the GET/POST auth handler above does not take.
app.use("/api/*", createEnterpriseGate(requireUser));
app.route("/api/admin/enterprise", createEnterpriseAdminRoutes(requireUser));
app.on(["PUT", "PATCH", "DELETE"], "/api/auth/scim/*", (context) =>
auth
? auth.handler(context.req.raw)
: context.json({ error: "No identity provider is configured." }, 503),
);
app.route(
"/api/audio",
createDictationRoutes(
requireUser,
config.transcription
? createTranscriptionProvider(config.transcription)
: undefined,
),
);
app.route(
"/api/voice",
createVoiceRoutes(
requireUser,
config.voice ? createVoiceProvider(config.voice) : undefined,
channelStore,
agentProfileStore,
voiceSessions,
learning?.status
? async (agentId) =>
(await learning.status?.(agentId))?.configured ?? false
: undefined,
),
);
app.get("/api/me", requireUser, async (context) =>
context.json({
user: {
...context.var.actor,
...(profileStore ? await profileStore.read(context.var.actor.id) : {}),
/*
* Read here rather than in the guard, so only this route pays the extra query. Null means
* this deployment does not track onboarding, which the app reads as nothing to finish;
* a not-yet-completed status is what sends it to /onboarding.
*/
onboarding: onboardingStore
? await onboardingStore.status(context.var.actor.id)
: null,
},
}),
);
app.route("/api/me/profile", createProfileRoutes(requireUser, profileStore));
app.post("/api/me/onboarding", requireUser, async (context) => {
if (!onboardingStore) {
return context.json({ error: "Onboarding is not available." }, 503);
}
const body = (await context.req.json().catch(() => undefined)) as
| { step?: unknown; completed?: unknown }
| undefined;
if (body?.completed === true) {
await onboardingStore.complete(context.var.actor.id);
} else if (
typeof body?.step === "number" &&
Number.isInteger(body.step) &&
body.step >= 0 &&
// The column's range — the only bound the server knows, since the wizard's length is the
// app's fact rather than the deployment's.
body.step <= 2_147_483_647
) {
await onboardingStore.setStep(context.var.actor.id, body.step);
} else {
return context.json(
{ error: "Send the step to move to, or completed: true." },
400,
);
}
return context.json({
onboarding: await onboardingStore.status(context.var.actor.id),
});
});
/*
* A person's own standing instructions, read and written by the person they belong to.
*
* `requireUser` and never `requireAdmin`, and scoped to `context.var.actor.id` rather than to
* anything in the path or the body. There is deliberately no route here for reading somebody
* else's or writing on their behalf: these instructions go into a prompt that then speaks as that
* person's coworker, so a way to set them for another account would be a way to put words in
* somebody's mouth in every channel they work in. An administrator has no business here either,
* for the same reason.
*/
app.route(
"/api/settings/preferences",
userPreferencesRoutes(requireUser, userPreferences),
);
/*
* The session must match the sealed state's person, otherwise a link started by one person could
* attach another person's GitHub account (login CSRF), so the callback requires the same session
* as the rest of /api/identity; a missing session answers 401 rather than a redirect. Mounted
* before the identity router so that router never sees a GET to this path; other methods fall
* through to it and get its own 401/404.
*/
if (identityGithubCallback) {
app.use("/api/identity/github/callback", requireUser);
app.route("/api/identity/github/callback", identityGithubCallback);
}
/*
* A person's own linked accounts at outside providers (Slack, GitHub). Theirs alone: there is no
* administrator view and no linking on somebody else's behalf. A provider is offered only when
* its return path is wired: Slack needs the identity redeemer for the codes it issues, and GitHub
* needs the callback mounted above, otherwise people would be sent away and back to nothing.
*/
app.route(
"/api/identity",
identityRoutes(requireUser, identity, auditStore, {
slackLinking: Boolean(
coworker?.delivery?.webhooks.slack &&
coworker.delivery.webhooks.identity,
),
github:
identityGithubCallback && config.githubApp && config.publicUrl
? {
clientId: config.githubApp.clientId,
publicUrl: config.publicUrl,
encryptionKey: config.keyEncryptionKey,
}
: undefined,
}),
);
app.get("/api/settings/instructions", requireUser, async (context) => {
if (!userInstructions) {
return context.json(
{ error: "Standing instructions are not available." },
503,
);
}
return context.json({
// "" is what having written none looks like to a text box, and the store's null is what it
// looks like to a database. The translation happens once, here.
instructions: (await userInstructions.read(context.var.actor.id)) ?? "",
});
});
app.put("/api/settings/instructions", requireUser, async (context) => {
if (!userInstructions) {
return context.json(
{ error: "Standing instructions are not available." },
503,
);
}
const body = (await context.req.json().catch(() => undefined)) as
| { instructions?: unknown }
| undefined;
if (typeof body?.instructions !== "string") {
return context.json({ error: "Send the instructions to save." }, 400);
}
/*
* The cap is the store's rule, so the store is what enforces it and this catches the refusal
* rather than checking the length again. A second copy of `> 4000` here is a second place for
* the number to be changed in only one of them.
*/
let saved: string;
try {
saved = await userInstructions.write(
context.var.actor.id,
body.instructions,
);
} catch (error) {
if (error instanceof InstructionsTooLongError) {
return context.json({ error: error.message }, 400);
}
throw error;
}
/*
* The trail records that they changed and how long they now are, NEVER what they say.
*
* The audit table is append-only and read by administrators, and this is a person's own note
* about how they want to be spoken to. Recording the text would put it somewhere they cannot
* edit it and somebody else can read it, which is not what a preferences screen promises. The
* length is enough to answer the question a trail is for: when did this change, and to what
* extent.
*/
if (auditStore) {
await recordAuditEvent(auditStore, {
eventType: "configuration.changed",
targetType: "user_instructions",
targetId: context.var.actor.id,
actorUserId: context.var.actor.id,
payload: {
change: saved === "" ? "instructions_cleared" : "instructions_saved",
characters: saved.length,
limit: INSTRUCTIONS_LIMIT,
},
});
}
return context.json({ instructions: saved });
});
if (learning) {
app.route(
"/api/admin/learning",
createLearningRoutes(
learning,
requireUser,
[
...(config.auth?.trustedOrigins ?? []),
...(config.appUrl ? [config.appUrl] : []),
],
auditStore,
),
);
}
app.get("/api/admin/status", requireUser, (context) => {
const denied = requireAdmin(context);
return denied ?? context.json({ status: "ok" });
});
app.get("/api/admin/audit-events", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!auditReader) {
return context.json({ error: "Audit logging is not configured." }, 503);
}
try {
const url = new URL(context.req.url);
const format = url.searchParams.get("format");
if (
format !== null &&
format !== "" &&
format !== "json" &&
format !== "csv"
) {
return context.json(
{ error: 'Query parameter "format" must be "json" or "csv".' },
400,
);
}
/*
* The export answers the same filtered query as the list — `eventType`,
* `actorUserId`, `initiatorKind`, `targetType`, `targetId`, `from`, `to` — so the
* downloaded file and the table agree. Paging (`cursor`, `limit`) belongs to the
* JSON list and is ignored here; the export walks every matching page up to the
* cap in `readAuditExportRows` and names the file after the day it was pulled.
*/
if (format === "csv") {
const query = auditQueryFromUrl(url);
const { events, truncated } = await readAuditExportRows(
auditReader,
query,
);
if (auditStore) {
const { cursor: _cursor, limit: _limit, ...filters } = query;
await recordAuditEvent(auditStore, {
eventType: "audit.exported",
targetType: "audit_trail",
actorUserId: context.var.actor.id,
payload: { format: "csv", rows: events.length, truncated, filters },
});
}
const day = new Date().toISOString().slice(0, 10);
context.header("Content-Type", "text/csv; charset=utf-8");
context.header(
"Content-Disposition",
`attachment; filename="audit-events-${day}.csv"`,
);
// The row count it stopped at, so the page can say how much the file holds.
if (truncated) {
context.header("X-Audit-Export-Truncated", String(events.length));
}
return context.body(auditEventsToCsv(events));
}
return context.json(await auditReader.list(auditQueryFromUrl(url)));
} catch (error) {
if (error instanceof AuditQueryError) {
return context.json({ error: error.message }, 400);
}
throw error;
}
});
/*
* Who is here, and what they may do.
*
* Administrator-only, like every other route in this group. A plain user reading the list would
* learn every colleague's address and when they last signed in, which is not theirs to have.
*/
app.get("/api/admin/people", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!peopleStore) {
return context.json({ error: "People are not available." }, 503);
}
/*
* A page, not the deployment.
*
* `limit` is parsed strictly and clamped into range at the edge, against the same ceiling the
* store enforces, so a caller cannot ask for everybody by naming a large number and a typo
* like `12abc` is a 400 rather than a silently coerced page. `search` is what makes paging
* usable: an administrator looking for one colleague should not have to walk pages to reach
* them.
*/
const url = new URL(context.req.url);
const parsed = parsePageLimit(url.searchParams.get("limit"), MAX_PAGE);
if (!parsed.ok) {
return context.json({ error: parsed.error }, 400);
}
// An unbounded `search` becomes a `%...% ILIKE` full scan. Cap it so a multi-megabyte
// query cannot be used as a cheap denial of service against the people table.
const search = url.searchParams.get("search");
if (search !== null && search.length > 200) {
return context.json(
{ error: "A search of at most 200 characters is required." },
400,
);
}
return context.json(
await peopleStore.list({
...(url.searchParams.get("search")
? { search: url.searchParams.get("search") as string }
: {}),
...(url.searchParams.get("cursor")
? { cursor: url.searchParams.get("cursor") as string }
: {}),
...(parsed.limit !== undefined ? { limit: parsed.limit } : {}),
}),
);
});
app.post("/api/admin/people/:userId/role", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!peopleStore) {
return context.json({ error: "People are not available." }, 503);
}
const body = await context.req.json().catch(() => null);
const role = (body as { role?: unknown } | null)?.role;
if (role !== "admin" && role !== "user") {
return context.json(
{ error: "A role of admin or user is required." },
400,
);
}
const userId = context.req.param("userId");
const person = await peopleStore.find(userId);
if (!person) {
return context.json({ error: "That person is not here." }, 404);
}
/*
* The configured floor wins over the screen.
*
* Somebody named in INITIAL_ADMIN_EMAILS is promoted again at their next sign-in whatever this
* route writes, so allowing the demotion would produce a screen that lies until they come back.
* Refusing says the real thing: change the deployment's configuration.
*/
if (person.configuredAdmin && role !== "admin") {
return context.json(
{
error:
"This deployment names that address in INITIAL_ADMIN_EMAILS, so they stay an administrator. Change the configuration instead.",
},
409,
);
}
/*
* Nobody demotes themselves.
*
* An administrator who does has just locked themselves out of the screen that would undo it,
* and on a deployment with one administrator that is the whole deployment. Somebody else with
* the role can do it, which is the check that makes handover possible without making lockout
* a slip of the finger.
*/
if (context.var.actor.id === userId && role !== "admin") {
return context.json(
{ error: "You can't remove your own admin role." },
409,
);
}
if (person.role !== role) {
await peopleStore.setRole(userId, role);
await recordPersonEvent(
auditStore,
context,
"person.role_changed",
person,
{
from: person.role,
to: role,
},
);
}
return context.json({ person: await peopleStore.find(userId) });
});
app.post("/api/admin/people/:userId/access", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!peopleStore) {
return context.json({ error: "People are not available." }, 503);
}
const body = await context.req.json().catch(() => null);
const revoked = (body as { revoked?: unknown } | null)?.revoked;
if (typeof revoked !== "boolean") {
return context.json({ error: "revoked must be true or false." }, 400);
}
const userId = context.req.param("userId");
const person = await peopleStore.find(userId);
if (!person) {
return context.json({ error: "That person is not here." }, 404);
}
// The same floor, for the same reason: removing somebody the configuration names would last
// until their next sign-in and no longer.
if (person.configuredAdmin && revoked) {
return context.json(
{
error:
"This deployment names that address in INITIAL_ADMIN_EMAILS, so they cannot be removed here. Change the configuration instead.",
},
409,
);
}
// Nobody can remove themselves. An administrator who does has locked themselves out of the
// screen that would undo it.
if (revoked && context.var.actor.id === userId) {
return context.json({ error: "You cannot remove your own access." }, 409);
}
if (person.revoked !== revoked) {
if (revoked) {
await peopleStore.revoke(userId, context.var.actor.id);
} else {
await peopleStore.restore(userId);
}
await recordPersonEvent(
auditStore,
context,
revoked ? "person.access_revoked" : "person.access_restored",
person,
{},
);
}
if (revoked) {
await peopleStore.retireOwned(userId, context.var.actor.id);
}
return context.json({ person: await peopleStore.find(userId) });
});
/*
* The identity providers this deployment has registered.
*
* Not Better Auth's own `GET /sso/providers`, which answers with the ones the person asking
* registered themselves. Two administrators therefore saw two different deployments: the second
* one to open this screen found it empty and registered a provider that was already there. What is
* registered is a fact about the deployment, so every administrator sees the same list.
*/
app.get("/api/admin/identity-providers", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!identityProviders) {
return context.json(
{ error: "Identity providers are not available." },
503,
);
}
return context.json({ providers: await identityProviders.list() });
});
/*
* Remove one.
*
* Ours rather than Better Auth's `delete-provider`, which refuses unless the person asking is the
* one who registered it. That leaves a provider nobody can remove as soon as the administrator who
* set it up has left, which is the same moment somebody most needs to.
*/
app.delete(
"/api/admin/identity-providers/:providerId",
requireUser,
async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!identityProviders) {
return context.json(
{ error: "Identity providers are not available." },
503,
);
}
const providerId = context.req.param("providerId");
const removed = await identityProviders.remove(providerId);
if (!removed) {
// A screen somebody left open, or two administrators removing the same one. Saying so beats
// reporting success for something that was not there.
return context.json({ error: "There is no such provider." }, 404);
}
if (auditStore) {
await recordAuditEvent(auditStore, {
eventType: "identity_provider.removed",
targetType: "identity_provider",
targetId: providerId,
actorUserId: context.var.actor.id,
payload: { removedBy: context.var.actor.email },
});
}
return context.json({ removed: true });
},
);
app.get("/api/admin/credentials", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!credentialService) {
return context.json(
{ error: "Credential storage is not configured." },
503,
);
}
return context.json({ credentials: await credentialService.list() });
});
app.post("/api/admin/credentials", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!credentialService) {
return context.json(
{ error: "Credential storage is not configured." },
503,
);
}
const body = await context.req.json().catch(() => null);
const input = credentialInput(body, context.var.actor.id);
if (!input) {
return context.json({ error: "Credential input is invalid." }, 400);
}
return context.json(
{ credential: await credentialService.create(input) },
201,
);
});
app.post(
"/api/admin/credentials/:credentialId/rotate",
requireUser,
async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!credentialService) {
return context.json(
{ error: "Credential storage is not configured." },
503,
);
}
const body = await context.req.json().catch(() => null);
const input = credentialInput(body, context.var.actor.id);
if (!input) {
return context.json({ error: "Credential input is invalid." }, 400);
}
try {
return context.json({
credential: await credentialService.rotate({
...input,
previousCredentialId: context.req.param("credentialId"),
}),
});
} catch (error) {
if (error instanceof CredentialRefusedError) {
return context.json({ error: error.message }, error.status);
}
throw error;
}
},
);
app.post(
"/api/admin/credentials/:credentialId/revoke",
requireUser,
async (context) => {
const denied = requireAdmin(context);
if (denied) {
return denied;
}
if (!credentialService) {
return context.json(
{ error: "Credential storage is not configured." },
503,
);
}
try {
return context.json({
credential: await credentialService.revoke(
context.req.param("credentialId"),
context.var.actor.id,
),
});
} catch (error) {
// Not found or already revoked: the second click on Revoke, answered as what it is.
if (error instanceof CredentialRefusedError) {
return context.json({ error: error.message }, error.status);
}
throw error;
}
},
);
app.get("/api/admin/package", requireUser, async (context) => {
const denied = requireAdmin(context);
if (denied) return denied;
if (!packageStatusReader) {
return context.json({ error: "Tenant package is not configured." }, 503);
}
return context.json({ package: await packageStatusReader.active() });
});
/*
* Where the worker hands a routine run back. Not under /api and not behind requireUser: the
* worker is not a person with a session, it is another process on this deployment's own network,
* and the shared secret below is its whole credential.
*
* Mounted only when a runner was built, so a deployment that never stood up a worker has no door
* for this at all, rather than one that is mounted and permanently refuses.
*/
if (routineRunner) {
app.post("/internal/routines/run", async (context) => {
const offered = context.req.header("authorization");
const expected = config.workerSharedSecret
? `Bearer ${config.workerSharedSecret}`
: null;
/*
* The no-secret-configured case is refused here, before any comparison, and with the exact
* same response as a wrong secret. A deployment with no worker must not answer a guess any
* differently than a deployment with a worker and a wrong key would.
*/
if (!expected || !offered || !sameToken(offered, expected)) {
/*
* Recorded, because this is a boundary being held and every other one here leaves a row. A
* worker with a stale or missing secret used to fail here in total silence: every routine
* stopped firing and nothing anywhere said why, the same false negative `mcp.callback_refused`
* exists to catch on the sibling unauthenticated boundary above.
*
* The reason is short and lives only in the row, never on the wire: the response below stays
* byte-identical across all three causes on purpose (see the comment above), so this is the
* one place the distinction is allowed to exist. The offered credential itself is never
* recorded, not even a fragment of it.
*/
if (auditStore) {
try {
await recordAuditEvent(auditStore, {
eventType: "routines.dispatch_refused",
targetType: "worker",
initiator: DEPLOYMENT_INITIATOR,
payload: {
reason: !expected
? "unconfigured"
: !offered
? "missing-header"
: "mismatch",
note: "A worker's bearer secret did not check out, so no routine run was dispatched.",
},
});
} catch (error) {
// Never fatal: the 401 above is already decided and sent. A trail that is briefly
// unavailable is not a reason to turn a refusal into a 500.
console.error(
JSON.stringify({
type: "routine-dispatch-audit-write-failed",
error: String(error),
}),
);
}
}
return context.json({ error: "This endpoint is the worker's." }, 401);
}
const body = await context.req.json().catch(() => null);
const routineRunId = (body as { routineRunId?: unknown } | null)
?.routineRunId;
// An empty id is a string and used to answer 202 Accepted while the worker swallows the
// failure. Only a non-empty id is accepted for dispatch.
if (typeof routineRunId !== "string" || !routineRunId.trim()) {
return context.json({ error: "A routineRunId is required." }, 400);
}
/*
* Fire and answer: the consumer needs "accepted", not the outcome. The run row in
* `routine_runs` carries the outcome, and the consumer finishes the work item on this 202.
* Queue retries exist for DISPATCH failures only — a failed turn is final for this firing, and
* the fatigue rule owns it. `run()` never throws by contract; this swallow only guards against
* that contract being wrong without turning a bug there into an unhandled rejection here.
*/
void routineRunner.run(routineRunId).catch(() => {});
return context.json({ accepted: true }, 202);
});
}
// The CopilotKit runtime, behind the same session guard as every other API route. Mounted last so
// its own routing under /api/copilotkit cannot shadow an OpenBot route declared above.
if (copilotHandler) {
// Mounted at the ROOT with the handler carrying its own basePath. Mounting it at
// "/api/copilotkit" as well double-prefixes it: Hono strips the prefix before the handler sees
// the path, so every route lands at /api/copilotkit/api/copilotkit/* and /info 404s. The browser
// reports that as "Runtime info request failed with status 404" and every run fails before it
// starts, with nothing at all in the server log.
app.route("/", copilotHandler);
}
/**
* May this person act as this Bot?
*
* The store's own read path already applies `canAccessAgent`, so asking it for the Bot is the same
* question the roster and the runtime ask, rather than a second copy of the rule.
*
* A deployment with no profile store has no agents table and therefore no private Bot to protect:
* its Bots come from the tenant package and are public to everybody who can sign in. Answering yes
* there keeps that deployment working without weakening one that has owners.
*/
const canUseBot: BotAccessCheck = agentProfileStore
? async (actor, botId) =>
(await agentProfileStore.get(actor, botId)) !== null
: async () => true;
// The Bot computer. Acting on a page needs the gateway and the policy it enforces, so both arrive
// together or the routes are not mounted. An ungoverned computer is not a reduced feature. It is
// the one shape of this feature that must not exist.
if (computerGateway && computerPolicy) {
app.route(
"/api/computers",
createComputerRoutes(
computerGateway,
computerPolicy,
requireUser,
// Not `canUseBot`: a Team Bot's teammates use the Bot, not its owner's signed-in computer.
agentProfileStore ? computerAccessCheck(agentProfileStore) : canUseBot,
pageFrames,
auditReader,
coworker?.botBrowser
? createBotBrowser({
...coworker.botBrowser,
gateway: computerGateway,
...(auditStore ? { auditStore } : {}),
...(agentProfileStore
? {
botName: async (actor, botId) =>
(await agentProfileStore.get(actor, botId))?.name ?? null,
}
: {}),
})
: undefined,
),
);
}
if (hostAccessBroker) {
app.route(
"/api/host-access",
createHostAccessRoutes({
broker: hostAccessBroker,
desktopToken: desktopHostToken,
requireUser,
canUseBot,
auditStore,
botName: agentProfileStore
? async (botId, actor) =>
(await agentProfileStore.get(actor, botId))?.name ?? null
: undefined,
}),
);
}
if (agentProfileStore) {
app.route(
"/api/agents",
createAgentRoutes(
agentProfileStore,
requireUser,
// The same stance the computer uses: a laptop legitimately talks to its own services, a hosted
// deployment must not. Passed from configuration rather than defaulted here, so "hosted and
// permissive" cannot happen by forgetting something.
config.computer?.allowPrivateHosts ?? false,
// A Bot's own refusal goes in the same trail as everything else it does.
auditStore,
// Addresses this deployment named, which is how a hosted one reaches an agent on its own
// network without dropping the floor for everything else.
config.agentEndpointAllowedHosts,
/*
* What the Bot's own screen needs to show, and change, which Bots it may hand work to.
*
* Read per request rather than captured, for the reason the desk reads it per hop: a grant
* made a minute ago counts and one revoked a minute ago stops counting. Absent with no
* plugin store, which is a deployment where no Bot may address any other.
*/
pluginStore
? {
enabled:
config.handoff.maxDepth > 0 && config.handoff.maxPerRun > 0,
reachableFrom: (agentId) =>
pluginStore.botsReachableFrom(agentId),
// The same answer the write path checks, read up front so the screen can say it once.
canHandOn: (agentId) => pluginStore.agentCanHandOn(agentId),
}
: undefined,
// Whether "built-in" is a kind of coworker this deployment can actually make: the create
// path falls back to the managed Bot's endpoint, so without one it can only refuse.
config.managedAgent?.endpoint !== undefined,
// The managed Bot's address, so a coworker created without an endpoint — which creation
// stores as running at this address — can be told apart from one a person hosts.
config.managedAgent?.endpoint?.toString(),
coworker?.shared?.use,
// So testing one of our own addresses knocks with the token the run will use, rather than
// reporting a refusal for a Bot this deployment started itself.
config.managedAgent
? {
token: config.managedAgent.token,
endpoints: [
config.managedAgent.endpoint,
config.managedAgent.alsoRun,
].filter((url): url is URL => url !== undefined),
}
: undefined,
// Whether a Bot can have a computer of its own here: only where the provider makes computers.
{ available: deploymentCanIsolate(config.computer) },
),
);
// Choosing a coworker for an untagged message needs the same permission-filtered roster the
// agents routes read, so it is mounted here where that store is in scope. Only when a router was
// configured; without one the composer keeps sending untagged messages to the default.
if (intentRouter) {
app.route(
"/api/route",
createRoutingRoutes(
createCoworkerRoutingService({
store: agentProfileStore,
router: intentRouter,
auditStore,
/*
* Which vendors each coworker holds tools for, so the router weighs what a coworker can
* reach and not only what somebody wrote it was for. Only when there is a plugin store to
* ask: a deployment with no connectors routes exactly as it did.
*/
reachableSystems: pluginStore
? async (agentId) => {
const granted = await pluginStore.listForAgent(agentId);
return [
...new Set(
granted.tools.map(
(tool) =>
tool.toolName.replace(/^mcp__/, "").split("__")[0] ??
tool.toolName,
),
),
];
}
: undefined,
}),
requireUser,
),
);
}
}
if (channelStore) {
app.route(
"/api/channels",
createChannelRoutes(channelStore, requireUser, channelEvents, auditStore),
);
}
if (attachmentDatabase) {
/*
* `bodyLimit` sits in front of the upload route itself, not beside the mount below: the handler
* in channels/attachments.ts calls `file.arrayBuffer()` before it has looked at a single byte of
* size, so an unbounded body is read into memory in full before anything gets the chance to
* refuse it. A person (or an attacker) posting a 2GB body would have it buffered in RAM before
* the 413 the handler already knows how to return. `MAX_IMAGE_BYTES` is the largest thing this
* route could ever legitimately accept — a text upload is refused smaller, inside the handler,
* once the sniffed type is known — so refusing anything larger at the door costs nothing a real
* upload was ever going to use.
*
* The ceiling is `UPLOAD_BODY_LIMIT_BYTES` and not `MAX_IMAGE_BYTES` itself because THIS GATE
* MEASURES A DIFFERENT THING FROM EVERY OTHER ONE. See that constant.
*/
const channelAttachments = new Hono<{ Variables: AppVariables }>();
channelAttachments.use(
"*",
bodyLimit({
maxSize: UPLOAD_BODY_LIMIT_BYTES,
/*
* THE REFUSAL AT THE DOOR HAS TO LOOK LIKE THE HANDLER'S OWN.
*
* hono's default `onError` answers with the plain string "Payload Too Large". The composer
* (app/src/components/channels/composer/attachments.ts) reads `{ error }` off every failed
* upload and falls back to a generic `Could not upload "<name>"` when the body will not
* parse as JSON — so the default body cost the person the one sentence that would have told
* them what went wrong, on the single refusal where the reason is both knowable and
* actionable. This is the same `{ error }` shape and the same number the handler's own 413
* names, so the two paths are indistinguishable from the outside.
*
* THE FILENAME AND THE KIND ARE BOTH DELIBERATELY ABSENT, and for the same reason: nothing
* has parsed the multipart body at this point, which is the entire reason this middleware
* runs ahead of the handler. The handler's sentences can say `'notes.txt' is larger than the
* 1MB limit for files` because by then it has sniffed the bytes. This one cannot, and must
* not guess — a 9MB text file refused here as being over "the 8MB limit for images" would
* send somebody off to shrink it to 7MB, whereupon the handler would refuse it a second time
* with a different number. So the sentence names the only thing that is true of every body
* this gate rejects: none of them can be under the largest ceiling the route has.
*/
onError: (context) =>
context.json(
{
// The same rounding as `megabytes` in channels/attachments.ts, so the door and the
// handler name one limit in one voice.
error: `That upload is larger than the ${(MAX_IMAGE_BYTES / (1024 * 1024)).toFixed(0)}MB limit.`,
},
413,
),
}),
);
channelAttachments.route(
"/",
createChannelAttachmentRoutes(attachmentDatabase, requireUser),
);
app.route("/api/channels", channelAttachments);
app.route(
"/api/attachments",
createAttachmentRoutes(attachmentDatabase, requireUser),
);
}
if (routineStore) {
app.route(
"/api/routines",
createRoutineRoutes(routineStore, requireUser, {
runner: routineRunner,
auditStore,
}),
);
}
if (coworker?.delivery) {
app.route(
"/api/delivery/webhooks",
createDeliveryWebhookRoutes(coworker.delivery.webhooks),
);
app.route(
"/api/delivery",
createDeliveryRoutes({ ...coworker.delivery.authenticated, requireUser }),
);
}
if (coworker?.recorder) {
app.route(
"/api/recorder",
createRecorderRoutes({
...coworker.recorder,
// A Disconnect in Settings, Browsers reaches the person's own OpenBot browser at once.
...(coworker.browser
? { onRevoked: browserConnectionRevoked(coworker.browser) }
: {}),
requireUser,
requireRecorder: createRequireRecorder(
coworker.recorder.resolve,
coworker.recorder.onRefused,
),
auditStore,
}),
);
}
if (coworker?.browser)
app.route(
"/api/browser",
createBrowserRoutes({ ...coworker.browser, requireUser, auditStore }),
);
if (coworker?.personalLearning)
app.route(
"/api/settings/learning",
createPersonalLearningRoutes(
{ ...coworker.personalLearning, auditStore },
requireUser,
),
);
if (coworker?.lifecycle)
app.route(
"/api/bots",
createBotLifecycleRoutes(coworker.lifecycle, requireUser),
);
if (coworker?.groups)
app.route("/api/groups", createGroupRoutes(coworker.groups, requireUser));
if (coworker?.teamBots)
app.route(
"/api/team-bots",
createTeamBotRoutes(coworker.teamBots, requireUser, coworker.shared?.use),
);
/*
* BEFORE `/api/approvals`, which would otherwise take every path under it and answer 404 for
* these. Needs the trail as well as the store: approving a Bot's use of a team account is a
* decision somebody must be able to find later.
*/
if (coworker?.shared && auditStore)
app.route(
"/api/approvals/shared-use",
createSharedUseRoutes(coworker.shared.use, requireUser, auditStore),
);
if (coworker?.approvals)
app.route(
"/api/approvals",
createApprovalRoutes(coworker.approvals, requireUser),
);
if (coworker?.passwords) {
app.route(
"/api/sign-in-requests",
createSignInRoutes(
coworker.passwords,
requireUser,
// A sign-in is typed into the Bot's computer, so it answers to the same rule.
agentProfileStore ? computerAccessCheck(agentProfileStore) : canUseBot,
),
);
app.route(
"/api/passwords",
createPasswordRoutes(coworker.passwords, requireUser),
);
}
if (coworker?.proactive)
app.route(
"/api/proactive",
createProactiveRoutes(
coworker.proactive.store,
coworker.proactive.engine,
requireUser,
),
);
if (coworker?.memory)
app.route(
"/api/memory",
createMemoryRoutes(
coworker.memory.store,
coworker.memory.ingestion,
requireUser,
),
);
if (coworker?.responsibilities) {
const { store, engine, bindings } = coworker.responsibilities;
app.route(
"/api/responsibilities",
createResponsibilityRoutes(
store,
engine,
requireUser,
bindings,
coworker.responsibilities.triggers,
coworker.shared?.use,
),
);
if (coworker.responsibilities.triggers) {
app.route(
"/api/events/triggers",
coworker.responsibilities.triggers.ingressRoutes,
);
if (coworker.responsibilities.triggers.emailRoutes)
app.route(
"/api/events/email",
coworker.responsibilities.triggers.emailRoutes,
);
}
app.route(
"/api/events/github",
createGithubResponsibilityRoutes({
bindingFor: bindings.githubBindingFor,
ingest: (event) => engine.ingest(event),
}),
);
}
if (componentStore) {
app.route(
"/api/components",
createComponentRoutes(
componentStore,
requireUser,
auditStore,
canUseBot,
sandboxedStore,
),
);
}
if (pluginStore) {
app.route(
"/api/plugins",
createPluginRoutes(
pluginStore,
requireUser,
canUseBot,
{
encryptionKey: config.keyEncryptionKey,
/*
* Whether the person a consent was started for still has access, asked when the callback
* lands rather than when the flow began.
*
* The callback carries no session — identity comes from the state — so this is where the
* question gets asked at all. `find` answers both halves of it: no row means a user id that
* names nobody, and `revoked` means an administrator removed them while they were away at
* the vendor. Either way there is no live person for a fresh refresh token to belong to.
*
* No people store means this deployment cannot answer the question, so it refuses rather
* than assuming yes. It also cannot remove anybody, which is exactly why guessing here
* would be a hole nothing else closes.
*/
personHasAccess: async (userId) => {
if (!peopleStore) return false;
const person = await peopleStore.find(userId);
return person !== undefined && !person.revoked;
},
// The deployment-wide fallback a Bot may present, as a yes or no. The secret itself stays
// in config and is checked in `/api/agent-tools/call`; the surface only needs to know
// whether a Bot without its own credential has any way to call back.
botsMayCallBack: Boolean(config.agentToolToken),
publicUrl: config.publicUrl,
appUrl: config.appUrl,
},
composio,
coworker?.shared,
),
);
}
/*
* Where a framework Bot runs a tool.
*
* A Bot that runs its own loop, in its own process, is the honest shape: the run does not need a
* browser and does not stop when one closes. What it must not have is a route to a vendor that
* goes around this deployment, so it calls here and this calls the plugin store, which asks the
* same two questions it asks of everything else and writes the same audit row.
*
* Authenticated by a shared secret rather than a session, because the caller is a service and has
* no person behind it. Absent secret means the route does not exist: a deployment that has not
* configured this refuses rather than accepting anybody who can reach the port.
*/
if (pluginStore || deploymentToolCaller) {
const legacyToken = config.agentToolToken ?? "";
app.post("/api/agent-tools/call", async (context) => {
/*
* Who is calling, and on whose behalf. Two questions, two credentials.
*
* The header says which agent: its own token, issued to it, stored here only as a hash. The
* body's `run` says which Bot and which person, signed by this deployment for this run.
*
* Both are required, and they are checked against each other. This used to be one
* deployment-wide token with the Bot and the actor read straight out of the body, which meant
* anything holding that token could spend any Bot's grants and write any name into the audit
* trail. A forgeable trail is worse than no trail, because it is believed.
*/
const body = (await context.req.json().catch(() => null)) as {
name?: string;
args?: Record<string, unknown>;
run?: unknown;
} | null;
const verdict = await authoriseAgentCall({
presented: context.req.header("x-openbot-agent-token") ?? "",
run: body?.run,
encryptionKey: config.keyEncryptionKey,
legacyToken,
lookup: async (hash) =>
(await agentProfileStore?.agentForCallbackToken(hash)) ?? null,
});
if (!verdict.ok) {
/*
* Recorded, because this is a boundary being held and every other one here leaves a row.
*
* The three outcomes inside `callTool` are all written after the caller has proved which Bot
* it is. A caller that fails to prove it never reaches them, so this refusal used to leave
* nothing at all — and it is the refusal behind the product's most confusing failure: a Bot
* whose token no longer matches the deployment's has every call rejected here, returns
* nothing to its own model, and the model tells the person there were no results. A false
* negative delivered as an answer, with the trail agreeing nothing had happened.
*
* No Bot id and no actor. Both live in the credential that just failed to verify, so writing
* them down would put an unproven claim in the record. The tool name comes from the body and
* is capped for the same reason: it is untrusted input, kept because "which tool was being
* reached for" is the useful half of the question.
*/
if (auditStore) {
await recordAuditEvent(auditStore, {
eventType: "mcp.callback_refused",
targetType: "mcp_tool",
initiator: DEPLOYMENT_INITIATOR,
targetId:
typeof body?.name === "string"
? body.name.slice(0, 120)
: "unknown",
payload: {
refusal: verdict.reason,
status: verdict.status,
note: "A caller could not prove which Bot it was, so no grant was consulted.",
},
});
}
return context.json({ error: verdict.reason }, verdict.status);
}
const parsedCall = parseAgentToolCallInput(body);
if (!parsedCall.ok) {
return context.json({ error: parsedCall.error }, 400);
}
try {
const deploymentResult = await deploymentToolCaller?.({
name: parsedCall.value.ref,
args: parsedCall.value.args,
botId: verdict.botId,
actorId: verdict.actorId,
initiator: verdict.initiator,
run: verdict.run,
});
if (deploymentResult) return context.json(deploymentResult);
if (!pluginStore) {
return context.json({
text: `${REFUSAL_MARKER} That tool is not registered in this deployment.`,
isError: true,
});
}
const result = await pluginStore.callTool({
ref: parsedCall.value.ref,
args: parsedCall.value.args,
botId: verdict.botId,
// From the assertion, never the body: this is the name the audit row will carry.
actorId: verdict.actorId,
...(verdict.initiator ? { initiator: verdict.initiator } : {}),
});
// Worded by the helper the in-process door uses, so a framework Bot's model reads a vendor's
// error as the vendor's and not as a result. Neither Bot words it on its way through.
return context.json({
text: vendorAnswer(result),
isError: result.isError,
});
} catch (error) {
/*
* A refusal is an answer, not a failure: the Bot says what was blocked and carries on. The
* marker leads it so a transcript can draw a refusal without reading the wording.
*
* AND THE SAME QUESTION THE IN-PROCESS DOOR ASKS, which this one asked of nothing at all.
*
* CRITERION. Nothing on the `isDeploymentFault` shelf has its message relayed from here,
* and nothing leaving here carries a statement or a value bound to one.
*
* WHAT THIS SURFACE IS. The answer goes into the calling Bot's model as the tool result, so
* it is the widest audience an error message in this deployment reaches: a model repeats
* what it is handed — to the person asking, into whatever it writes next, and to the next
* tool it calls. `plugins/tools.ts` wraps the identical `callTool` for a Bot running in
* this process and has refused that shelf for exactly this reason since the
* `ServerRowAmbiguousError` finding; the two doors to one store disagreeing meant a query
* failure came back as `Failed query: … params: linear, usr_…` through one of them and as a
* fixed sentence through the other. Which door a Bot arrives at is a deployment topology
* decision and was never a disclosure decision.
*
* AND THROUGH {@link withoutStatement} AS WELL, because the two answer different questions
* and `isDeploymentFault` says so itself: it "settles who may be told, not what". The shelf
* decides whether this audience may hear a sentence at all; the door decides what any
* sentence is allowed to contain. Today the two overlap on a query failure and this arm can
* only be reached by something neither recognises — which is exactly the state the last two
* findings in this area were found in, one predicate apart from a leak.
*
* AND ONLY A REFUSAL CARRIES THE MARKER, which is the in-process door's third question. The
* transcript draws an answer that starts with it as a boundary holding, and the model reads
* "Refused." as "not allowed". `callTool` throws `PluginRefusedError` for that, and rethrows
* a vendor that broke after recording `mcp.call_failed`; marking every throw drew a vendor
* outage, or a fault of this deployment's own, as a policy refusing.
*/
if (error instanceof PluginRefusedError) {
return context.json({
text: `${REFUSAL_MARKER} ${withoutStatement(error)}`,
isError: true,
});
}
return context.json({
text:
error instanceof Error && !isDeploymentFault(error)
? `That tool could not be called: ${withoutStatement(error)}`
: "That tool could not be called.",
isError: true,
});
}
});
}
if (sandboxedStore) {
app.route(
"/api/sandboxed",
createSandboxedRoutes(sandboxedStore, requireUser),
);
}
if (threadIdentity) {
app.route(
"/api/threads",
createThreadRoutes(
threadIdentity,
requireUser,
// config.ts refuses to boot without the full Intelligence contract (see copilot.ts's
// header comment), so `config.runtime.intelligence` is never missing here. Built from it
// rather than assumed, though: this is the one place besides the runtime mount itself that
// needs to reach Intelligence, and it should keep working unmodified if that guarantee ever
// loosens and a deployment can legitimately have no reader to build.
createThreadReader(
createIntelligenceClient(config.runtime.intelligence),
),
),
);
}
/*
* The built app, served by the API that serves it.
*
* WHY THE SAME PROCESS. There is no CORS anywhere in this server, deliberately, so the app has to
* reach `/api` on its own origin. Two containers behind one ingress does that too, and costs a
* path rule on every deployment plus a way for the two to disagree about which host they are on.
* One process cannot disagree with itself.
*
* MOUNTED LAST, so every `/api` route above already claimed its path. The catch-all below would
* otherwise answer an unmatched `/api` call with the app's HTML, which is the failure that reads
* as "the API returned HTML" and takes an hour to place.
*
* Absent in development: Vite serves the app and proxies `/api` here, so `APP_DIST_DIR` is unset
* and none of this mounts.
*/
if (config.appDistDir) {
const root = config.appDistDir;
app.use("/*", serveStatic({ root }));
/*
* A single-page app owns its routing, so a path with no file behind it is not missing: it is a
* route the browser resolves once index.html has loaded. Without this, every deep link and every
* refresh away from `/` is a 404, which is the classic way this deployment shape breaks.
*
* Written out rather than a second `serveStatic`, whose `path` option is resolved relative to the
* working directory and silently matches nothing when handed the absolute root used above.
*
* `/api` is excluded so an unmatched API route still answers as one. Returning the app's HTML to
* a fetch that expected JSON is the failure that gets read as "the API returned HTML".
*/
app.get("*", async (context) => {
if (context.req.path.startsWith("/api")) return context.notFound();
const index = Bun.file(`${root}/index.html`);
if (!(await index.exists())) return context.notFound();
return new Response(index, {
headers: { "content-type": "text/html; charset=utf-8" },
});
});
}
return app;
}
function credentialInput(
value: unknown,
actorUserId: string,
): CredentialInput | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
const body = value as Record<string, unknown>;
/*
* An allowlist, and deliberately narrower than `CredentialKind`.
*
* `CredentialKind` is derived from the schema enum, so it now includes `mcp_oauth_client` and
* `mcp_user_token`. Neither belongs here. A user token is somebody's own grant and exists only as
* the outcome of a consent they gave; a client is registered when a connector is added. Both are
* written by the code that owns those flows, and an administrator hand-posting either would be
* creating a credential attributed to a person who never agreed to it.
*
* So this list is not out of date with the enum — do not widen it to match.
*/
if (
(body.kind !== "model" &&
body.kind !== "connector" &&
body.kind !== "mcp") ||
typeof body.provider !== "string" ||
!body.provider.trim() ||
typeof body.keyId !== "string" ||
!body.keyId.trim() ||
typeof body.plaintext !== "string" ||
!body.plaintext ||
!body.metadata ||
typeof body.metadata !== "object" ||
Array.isArray(body.metadata) ||
Object.getPrototypeOf(body.metadata) !== Object.prototype
) {
return null;
}
return {
kind: body.kind,
provider: body.provider.trim(),
keyId: body.keyId.trim(),
metadata: body.metadata as Record<string, unknown>,
plaintext: body.plaintext,
actorUserId,
};
}