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 type { AuditInitiator } from "@openbot/toolkit/initiator";
import {
and,
desc,
eq,
getTableColumns,
gt,
inArray,
lt,
or,
sql,
} from "drizzle-orm";
import type { PgColumn } from "drizzle-orm/pg-core";
import type { Database } from "./db/client";
import { auditEvents } from "./db/schema";
import { parsePageLimit } from "./paging";
const sensitiveKeys = new Set([
"access_token",
"accesstoken",
"api_key",
"apikey",
"authorization",
"client_secret",
"clientsecret",
"content",
"credential",
"credentials",
"document_content",
"documentcontent",
"encrypted_value",
"encryptedvalue",
"id_token",
"idtoken",
"password",
"prompt",
"refresh_token",
"refreshtoken",
"result",
"secret",
"secrets",
"token",
"tokens",
"tool_arguments",
"toolarguments",
"tool_result",
"toolresult",
]);
export const auditEventTypes = [
"configuration.changed",
"credential.created",
"credential.rotated",
/**
* A rotation the vault refused, and why.
*
* Recorded because the refusals are the interesting ones. A rotation aimed at a key other than the
* one the credential belongs to, or at a credential already revoked, is either a caller with a bug
* or somebody trying to retire a key they were not asked to retire, and neither left a trace while
* only the successes were written.
*/
"credential.rotation_refused",
"credential.revoked",
/**
* Which coworker an untagged message was routed to, and why.
*
* A channel is pinned to one coworker before its first turn, so when the person did not name one
* with `@`, something chooses. This is that choice, made visible: the row names the coworker it
* went to, whether it was an inferred match or the default it fell back to, and the coworkers it
* chose between. The message itself is not here (the payload redaction drops it either way) — a
* routing decision is a fact about where a conversation went, not a copy of what was said.
*/
"channel.routed",
"delivery.received",
"delivery.sent",
"delivery.opted_out",
"delivery.failed",
/**
* A channel was removed from every member's roster, and by whom.
*
* The removal is soft, so the row and its thread survive and `channels.deleted_at` records that it
* happened. What it cannot record is who did it: a timestamp answers "when did that conversation
* disappear" and not "who ended it for everybody in it", which is the half somebody asks about.
* `payload.mechanism` names how, so a later hard delete is distinguishable from this one.
*/
"channel.deleted",
/**
* An address this deployment declined to dial for a Bot, and why.
*
* The stored endpoint is re-checked on the way out of every run, and so is each address it
* redirects to. When one of those is refused the run fails and the person sees why, which is the
* whole of what anybody learns without this row.
*
* That is the wrong shape for the thing worth knowing. A registration is one person at one moment;
* a stored agent quietly beginning to redirect somewhere it should not is a fact about an endpoint,
* happening on every run, with nobody watching. It reads as an agent being flaky until somebody can
* count it. The row names the address and the reason, so a reader can tell an agent that moved from
* one aimed at the metadata endpoint.
*/
"agent.dial_refused",
/**
* A Bot's stream stopped producing anything and the turn was ended for it.
*
* Recorded because a Bot is somebody else's infrastructure and this is the failure it has that
* nothing else in the trail can show. Every other row here is something that happened; this one is
* the absence of anything happening, which leaves no trace of its own.
*
* It is also the sort of thing nobody notices is happening repeatedly. One hung turn reads as a
* bad afternoon and gets a shrug; the same Bot hanging twice a day for a month is a fact about an
* endpoint, and it only becomes visible when somebody can count it. The row names the Bot, how
* long its stream was silent, and how many chunks it managed first, so a reader can tell an
* endpoint that dies mid-answer from one that never answers at all.
*/
"agent.stream_stalled",
/*
* Which of a Bot's tools were put in front of the model for one run, and why those.
*
* Discovery, recorded as its own fact, because a run is now offered a subset of what the Bot holds
* and every other row here answers a question about a call that happened. This one answers "why
* did it call that", and its harder twin, "why did it not call anything" — a Bot that had the
* right tool granted, was not offered it, and answered from memory leaves no other trace at all.
* Without this row that failure is indistinguishable from a model that simply chose badly.
*
* DISCOVERY IS NOT PERMISSION, and the row is not an authorization record. Everything named here
* was already granted; being offered is what changed. A tool still goes through the grant, the
* policy and `mcp.call_succeeded` or `mcp.call_rejected` before anything happens, so this row
* never appears in place of one of those, only before it.
*
* `reason` is the part worth reading. It separates a deployment that narrowed from one that never
* declared anything and one whose selector was unreachable, which look identical from outside.
*/
"mcp.tools_discovered",
"mcp.call_succeeded",
"mcp.call_rejected",
/*
* A call this deployment permitted and the vendor did not complete.
*
* The third outcome, and the one the trail was missing. `call_rejected` is this deployment
* declining; `call_succeeded` is a vendor answering. Between them sits a call that passed every
* check here and then failed out there — a credential the vendor would not take, an API not
* enabled, a timeout — and without a row of its own it was invisible.
*
* Worse than invisible. `call_succeeded` used to be written before the network call rather than
* after, so a call that died at the vendor left a row saying it had succeeded, and the Admin page
* agreed. That is the one shape of audit bug worth going out of the way to avoid: a trail that is
* confidently wrong is more dangerous than one that is silent, because it is used to rule things
* out.
*/
"mcp.call_failed",
/*
* Something presenting itself as a Bot asked to spend a grant and was turned away at the door.
*
* The fourth outcome, and the only one that used to leave nothing behind. The three above are all
* written inside `callTool`, which is reached only after the caller has proved which Bot it is.
* A caller that fails THAT check never reaches `callTool`, so a refused callback was invisible:
* no row, no log, nothing to count.
*
* Which made the most confusing failure in the product completely silent. A Bot holding a stale
* token — the deployment's secret rotated, a container not recreated with it — has every call
* rejected at this line, returns nothing to its own model, and the model tells the person "no
* files were found". A false negative, delivered as an answer, about a Drive that has the files.
* Every place a person would look to check agreed that nothing had happened.
*
* It is a security row as much as a diagnostic one. This endpoint is how a Bot spends grants, and
* an unauthenticated caller probing it generated no evidence at all.
*
* The row deliberately does NOT name a Bot or an actor. Both arrive in the credential that just
* failed to verify, so writing them down would be recording an unproven claim in the one place
* that is supposed to be believed. What is recorded is what is known: that a call was attempted,
* which tool it named, and why it was refused.
*/
"mcp.callback_refused",
/*
* An administrator registered this deployment's OAuth client with a vendor.
*
* Recorded because it decides what every subsequent consent screen belongs to. If a client is
* replaced, every person who connects afterwards is granting access to a different registration,
* and the row is what lets somebody reading the trail line a connection up against the client that
* was current when it was made. The client id, never the secret.
*/
"mcp.oauth_client_registered",
/*
* One person's brokered account was exercised with a real call, to see whether it is really there.
*
* THE ONE EXECUTION OF AN APP'S OWN ACTION THAT HAPPENS OUTSIDE `callTool`, which is why it is
* written down on its own instead of joining the `mcp.call_*` family. Everything that surrounds a
* vendor call on the ordinary path is absent from this one: no grant is consulted, no policy is
* evaluated, no arguments are inspected, and no `mcp.call_succeeded`, `mcp.call_rejected` or
* `mcp.call_failed` row is left behind it. An action ran at a vendor and the trail's tool-call
* family says nothing about it, so this row is the whole of what is recorded.
*
* WHAT MAKES THAT SAFE IS THE SHAPE OF THE CALL RATHER THAN ANYBODY'S CARE. The action is fixed:
* the adapter picks it out of the metadata this deployment already recorded for the app, not out
* of anything a caller sent; it is sent with no arguments at all, so there is nothing for content
* inspection to have missed; and the only two callers are the connect step and a person
* re-checking their own connection. Those three properties are the protection. A later change
* that let the action, the arguments or the callers vary would not be loosening a check that is
* merely skipped here — it would be removing the reason the check can be skipped at all, and the
* one call in this deployment that reaches a vendor unexamined would start taking instructions.
*
* THE ROW NAMES A PERSON AND HAS NO BOT IN IT, which is not new on this trail and must not be
* read as such. `mcp.callback_refused` deliberately names none, and `mcp.account_connected` and
* `mcp.account_disconnected` are both filed against the person whose account it was, so code that
* reads a Bot out of every `mcp.*` payload was already wrong before this row existed. What IS new
* is a vendor action with no `mcp.call_*` row beside it: anybody reconciling this trail against
* an app's own logs has a call here to account for that the tool-call rows will never mention.
* Borrowing a Bot to make the row look uniform with its neighbours would answer that by lying —
* a call somebody made about their own account, filed against a Bot that never ran, is the
* confidently wrong kind of entry that `mcp.call_failed` exists to keep off this trail.
*/
"mcp.connection_verified",
/*
* One person connected their own account to one server.
*
* Its own row rather than a credential event, because what happened is not "a secret was stored" —
* it is a person granting a deployment continuing access to their documents, which is the kind of
* thing they are entitled to see a record of. Carries the scope the vendor actually granted.
*/
"mcp.account_connected",
/** A vendor authorization answer could not be reconciled with its pending attempt. */
"mcp.authorization_unreconciled",
/*
* One person's connector access retired, by them or on their behalf.
*
* The counterpart to the row above, and the one an auditor reaches for when asked "what happened to
* their access". `reason` distinguishes somebody disconnecting their own account from an
* administrator removing them, because those are the same effect and very different events.
*
* `vendorRevocationRequested` says whether the grant at the vendor was asked to be withdrawn as
* well. It is false for every credential this deployment holds in its own vault: removing
* somebody stops us holding a usable secret, and the grant at Google outlives it until it is
* revoked there, which nothing on that path asks for. It is true for a brokered account whose
* withdrawal Composio accepted — accepted rather than completed, because the upstream revocation
* runs as a background job with no supported way to poll it, which is why the field is named for
* the ask. Recorded rather than glossed, because a row that implied otherwise would be worse
* than no row, and this field once did exactly that: it was called `vendorRevoked` and said true
* while the grant at Google stood untouched.
*/
"mcp.account_disconnected",
/*
* One person retracted their own pending per-action authorization before it completed.
*
* The counterpart of `mcp.account_connected` on the same lifecycle: that row is the attempt
* ending in a yes, this one is the person deliberately ending it themselves. Without it, pressing
* Cancel deleted the attempt and nothing recorded who withdrew what — on a lifecycle whose whole
* point is that consent is attributable. Filed under the app's slug, as its two siblings are.
*
* NEVER THE CONSENT URL AND NEVER THE VENDOR'S HANDLE FOR THE FLOW: the first is a bearer
* capability, and neither is in the payload. `minted` says only whether a flow had been started at
* the vendor at all, which is the one fact about it a reader of the trail needs.
*/
"mcp.authorization_cancelled",
/*
* A cancelled per-action consent completed at the vendor anyway, and its grant was LEFT LIVE
* there: withdrawing it would have ended more than the cancelled consent — on Arcade a revoke ends
* the whole `(identity, auth provider)` connection, which the account already held for this app or
* shares with a sibling — or the withdrawal was asked and not confirmed. `why` says which. Calls
* are gated by the vendor's own authorization, so a Bot
* may still take the cancelled action — for a Shared app, as the team. Filed beside
* `mcp.authorization_cancelled` so the trail does not read as a clean withdrawal. `why` is this
* deployment's own phrase; nothing of the vendor's and no handle for the flow is in the payload.
*/
"mcp.cancelled_grant_left_live",
// An administrator switched a brokered app between each person's account and one shared account.
"mcp.account_mode_changed",
// A Bot's use of a Shared app needs an administrator's approval: filed by a refused call or by the
// Bot's owner.
"shared_use.requested",
// An administrator answered a request to use a Shared app through a Bot.
"shared_use.approved",
// An administrator answered a request to use a Shared app through a Bot.
"shared_use.declined",
/*
* A Bot's owner gave it a Shared app whose rule lets owners decide, and that set who may use the
* team account through the Bot (`approved_as = owner`); and that audience withdrawn, because the
* owner took the app back or an administrator stopped letting owners decide. Target the app;
* payload `bot`, `server`, and the `audience` set or `why` it went.
*/
"shared_use.owner_approved",
"shared_use.owner_withdrawn",
/*
* A person asking an administrator to switch a work app on, grant it to a Bot, or connect a
* Shared app's team account (`app_access_requests`), and what became of it: cancelled by the
* person, approved or dismissed by an administrator, or refused — a request that could not be
* filed, or an approval that could not be carried out. Target the app key; payload `request`,
* `app`, `bot`, `kind`, and for a refusal `reason`.
*/
"app_access.requested",
"app_access.cancelled",
"app_access.approved",
"app_access.dismissed",
"app_access.refused",
/*
* A Bot's owner giving one of their own apps to their own Bot, or taking it back, without an
* administrator (`plugins/owner-grants.ts`). Target the app key; payload `app`, `bot`, and the
* refs given or taken. Each ref also has its own `plugin_granted` / `plugin_revoked` row marked
* `grantedAs: owner`.
*/
"app_access.owner_granted",
"app_access.owner_revoked",
// Every action a Bot takes on its computer, allowed or refused. Both, always: a trail that records
// only what was permitted cannot answer whether the Bot tried.
"computer.action_allowed",
"computer.action_refused",
// Permitted by policy, attempted, and did not succeed. Its own type because "allowed" reads as
// "happened", and a trail that cannot tell those apart misleads exactly when it matters most.
"computer.action_failed",
// Permitted, attempted, and stopped mid-action by a person pressing Stop. Kept apart from
// `action_failed` because a stop is not an outage: a count of failures that folds in every Stop
// reports a broken computer where somebody simply changed their mind.
"computer.action_stopped",
// A person taking the wheel and giving it back. Recorded as a period rather than as keystrokes: the
// useful fact for an investigator is that a human drove this browser between these two times, and
// logging every click a person made would bury it while telling nobody anything.
"computer.help_requested",
"computer.help_cancelled",
"computer.control_taken",
"computer.control_released",
// A credential a person entered by hand. The row records that it happened, what it was called and
// which field it went in; the value is on a path this trail is not on.
"computer.secret_requested",
"computer.secret_supplied",
// A Bot asking its owner to sign it in to a website, and how that ended. Never the username, the
// password or a code: the row says which site, which request and whether a saved login was used.
"computer.sign_in_requested",
// The site accepted the password and asked for a verification code. Whether one was asked, never it.
"computer.sign_in_code_requested",
"computer.sign_in_completed",
"computer.sign_in_failed",
"computer.sign_in_cancelled",
// A login saved to, or removed from, a person's Passwords. The site and username id, never the value.
"password.saved",
"password.deleted",
// The computer itself being stopped or wiped. `reset` destroys every login the Bot had, which is
// both the recovery path and the most consequential button on the admin page, so who pressed it and
// when is exactly the sort of thing an investigator needs and nothing else records.
"computer.stopped",
"computer.reset",
// A browser's data wiped by the person working it: a Bot's, by whoever held its wheel, or the person's own. Every
// login in it goes, as with a reset, so who did it and to which browser is worth a row; the Bot's files stay.
"computer.browser_cleared",
// A computer moved onto the current image. Its files and sign-ins are kept, but a running one is
// restarted, which interrupts whatever it was doing, so who asked is worth a row.
"computer.updated",
/**
* The boundary this deployment booted with.
*
* The live policy is held in memory, so a restart returns to the configured default unless the
* saved row is loaded again. This boot event records the boundary that is actually in force, so an
* audit reader can interpret earlier policy changes against the deployment state that followed.
*
* Written on every boot rather than only when something was lost, because the trail cannot know
* what the previous process had, and "the deployment restarted with this boundary" is the fact that
* matters either way.
*/
"computer.policy_loaded",
/**
* Whether this deployment gives each Bot a computer of its own, said out loud at boot.
*
* Without a supervisor every Bot shares one browser, which is a legitimate way to run on a laptop
* and the opposite of what per-Bot isolation promises. The difference is invisible: the screens look
* identical, the trail looks identical, and a Bot acting on another Bot's session looks exactly like
* a Bot acting on its own. Nothing in the product distinguishes them, so nothing would.
*
* So the deployment states which one it is, once, where it cannot be argued with later. Same reason
* as `computer.policy_loaded`: the trail records the boundary that is actually in force.
*/
"computer.isolation_loaded",
/**
* The Bot declined something it was asked to do.
*
* Every event above records an action a Bot took, decided on by the gateway. A model that refuses
* before calling any tool takes no action, so the gateway never sees it. This event is the audit
* trail's record that the Bot was asked to do something and declined before acting.
*
* For governance, "this Bot was probed six times last week" is a question the trail answers, and a
* refusal is the evidence of the attempt.
*
* Self-reported. The Bot calls this because it was told to, so a model
* that declines and says nothing still writes nothing. It records more than zero, which is what
* there was, and it is not a control, nothing here is enforced by it.
*/
"bot.declined",
/*
* What a Bot may answer with, decided per Bot and recorded like anything else it is trusted with.
*
* A component is a capability you grant, so the trail has to answer the same questions a connector
* or a skill does: who gave this Bot this, when, and who took it away again. Publishing is here for
* the same reason, it changes what every Bot in the deployment is offered at once, which is the
* largest single change anybody can make on this surface.
*
* `component.refused` records a Bot reaching for something it does not hold. Everything else is a decision somebody made
* on purpose; this is a Bot reaching for something it does not hold. It is written by the same
* decision point the app asks before every render, so a grant revoked mid-conversation leaves a row
* rather than a component that quietly stops appearing.
*/
"component.granted",
"component.revoked",
"component.published",
"component.unpublished",
"component.draft_saved",
"component.refused",
/*
* A component reading real data, rather than being handed figures by a model.
*
* Recorded like any other tool call because that is what it is: something acting on this
* deployment's data on a Bot's behalf. `reads` names the source in a few words, so a reader can see
* what a component actually touched without opening it.
*
* `component.function_failed` is deliberately not a refusal. Nothing was forbidden, the read
* broke, and filing a broken query as a policy event teaches a reader to distrust the policy
* events that are real.
*/
"component.function_granted",
"component.function_revoked",
"component.function_called",
"component.function_refused",
"component.function_failed",
/*
* Who may use this deployment, and at what level.
*
* On the trail rather than only in the table, because the table holds the current answer and this
* is the only place that says who changed it and when. "Why does this person have admin" and "who
* removed them" are questions a table of current state cannot answer at all.
*/
"person.role_changed",
"person.access_revoked",
"person.access_restored",
/*
* An administrator took the trail out as a file. The trail is evidence, so who copied how much of
* it, under which filter, belongs on it too.
*/
"audit.exported",
/*
* Getting in, and being turned away.
*
* The trail had nothing about sign-in at all, which left two questions unanswerable. Anybody who
* could edit `INITIAL_ADMIN_EMAILS` granted themselves the administrator role on their next
* sign-in and no row anywhere said it had happened, because the floor is re-applied silently by
* design. And revoking somebody deletes their sessions, which were the only record that they had
* ever been here: after a revocation the deployment could not show that the person had signed in,
* let alone when or how often.
*
* `session.refused` is the one somebody investigating actually reaches for. A revoked person still
* holding a bookmark, or an address outside the deployment trying the front door, produces nothing
* else anywhere.
*/
"session.signed_in",
"session.refused",
"person.admin_by_configuration",
/*
* A company's own identity provider, added or taken away.
*
* Whoever holds this decides who can sign in at all, so the two ends of its life belong on the
* trail next to the roles it hands out.
*/
"identity_provider.registered",
"identity_provider.removed",
/*
* What a Bot is and what it may reach.
*
* The trail recorded every mouse movement a Bot made and could not answer "who pointed this Bot at
* that host, and when", which is the first question asked in an incident. A Bot's endpoint is
* where conversation content is sent and its callback token is a capability handed to somebody
* else's infrastructure, so the two ends of both belong here.
*
* `bot.updated` carries what changed rather than the new values: the endpoint is worth naming, and
* a key never is.
*/
"bot.created",
"bot.updated",
"bot.duplicated",
"bot.hidden",
"bot.unhidden",
"bot.pinned",
"bot.unpinned",
"bot.deleted",
"bot.callback_token_issued",
"bot.callback_token_revoked",
/*
* A Bot was asked for a computer of its own and refused it: the person does not hold "Isolated
* Bots", the Bot belongs to no person, or this deployment cannot make a second computer. The row is
* the only trace of the attempt, since nothing about the Bot changed. `payload.reason` says which.
*/
"bot.isolation_refused",
/*
* A Bot's lifecycle as one person runs it: paused, resumed, reset, how loudly it may reach them,
* a follow-up it scheduled for itself, and a delegated task somebody stopped. See agents/lifecycle.ts.
*/
"bot.paused",
"bot.resumed",
"bot.reset",
"bot.notifications_changed",
"bot.follow_up_scheduled",
"bot.follow_up_cancelled",
"bot.handoff_stopped",
/*
* One Bot handing work to another.
*
* BOTH OUTCOMES, and the refused one is the more important of the pair. A hop that happened is
* visible in the transcript anyway; a hop that was refused is invisible everywhere else, and
* "why did this Bot not ask the specialist" is a question somebody asks about an answer that came
* back thin. The refusal row names which cap or which missing grant stopped it.
*
* `agent.handoff_offered` is written when the hop is accepted and made durable, not when the other
* Bot answers. The two are minutes apart on a busy cluster, and a trail that only recorded
* completion would be silent about work that was accepted and then lost.
*/
"agent.handoff_offered",
"agent.handoff_refused",
/*
* And what became of one, which is a different question from whether it was accepted.
*
* `delivered` is the other Bot's turn being on record. `failed` is a hop that will be tried again.
* `retried` is the one worth its own name: a hop on its second attempt may already have run that
* Bot, spent a model call and posted an answer before its owner died, so a person looking at two
* similar answers can tell a duplicate from a mystery.
*/
"agent.handoff_delivered",
"agent.handoff_failed",
"agent.handoff_retried",
/*
* A Bot asking a person instead.
*
* The counterpart to the rows above, and the one that says a chain stopped on purpose. Without it
* a Bot that correctly refused to guess looks identical to one that ran out of things to try: both
* end in a sentence to the person and neither leaves a trace of the decision.
*
* `agent.escalation_failed` is a question that reached nobody. It is the row worth finding later:
* the Bot stopped, the person was never asked, and nothing else anywhere says so.
*/
"agent.escalated",
"agent.escalation_failed",
/*
* A worker's bearer secret did not check out at `/internal/routines/run`, and every routine this
* deployment has stopped firing until somebody notices.
*
* Recorded because that route answers a refusal with the exact same 401 for a missing header, a
* wrong secret, and a deployment that never configured one — deliberately, so a caller cannot tell
* those apart from the wire. Which means the wire is also the only place this trail could otherwise
* be read from, and it was told nothing. `payload.reason` carries the distinction the response
* withholds; the offered credential never does.
*/
"routines.dispatch_refused",
/** A person pressed Run now on a routine: real work, outside its schedule. */
"routines.run_requested",
/** An authenticated trigger (webhook, provider, email, Slack) queued a responsibility run. */
"responsibility.triggered",
/*
* The approval gate and the person, kept apart so a reader never mistakes one for the other.
*
* `approval.evaluated` is the gate's own verdict on an action (`payload.decidedBy: "policy"`): a
* built-in safety requirement, a custom rule, the auto-review model, or the person's default.
* `approval.person_decided` is a human pressing allow once, always, deny or done
* (`payload.decidedBy: "person"`). `approval.withdrawn` is a pending request closed without a
* decision, with its reason: approvals switched off, or a rule that now allows it.
* Rule changes and settings changes, a person's own and the team's, are on the trail for the same
* reason a grant is.
*/
"approval.evaluated",
"approval.person_decided",
"approval.withdrawn",
"approval.rule_changed",
"approval.settings_changed",
/*
* Enterprise controls (server/src/admin). Every switch an administrator flips is on the trail with
* who flipped it, because the table only holds the current answer.
*/
"capability.changed",
"enterprise.setting_changed",
// Turning SSO-required on ended the sessions made before it.
"auth.sessions_revoked",
"network_policy.changed",
"network_policy.removed",
/*
* Somebody named in INITIAL_ADMIN_EMAILS signing in with a social provider while SSO is required.
* Allowed, so a broken identity provider cannot lock the deployment out, and loud: it is the one
* sign-in that bypasses the rule.
*/
"session.break_glass",
/* SCIM 2.0: a directory creating, suspending and restoring somebody. */
"person.provisioned",
"person.deprovisioned",
"person.reprovisioned",
/* An administrator ending a member's computers, and the sweep that ends unused ones. */
"computer.terminated",
"computer.terminated_inactive",
/* A Bot connected to, or disconnected from, a Slack, Teams or SMS conversation. */
"delivery.linked",
"delivery.unlinked",
/*
* A person linking an outside account to themselves (a Slack link code, a GitHub sign-in). Target
* the link id; payload `actor` and `provider` only, never the subject, realm or credential id.
*/
"identity.linked",
/*
* A person removing their own link to an outside account (Slack, GitHub). The link and its stored
* token go here; nothing is changed at the provider.
*/
"identity.unlinked",
/*
* A removed person's linked account retired by the removal: marked `needs_reconnect`, its stored
* token (if any) revoked here. Target the link id; payload `actor` (the remover, not always a user
* id, so never `actorUserId`), `owner` (the removed person), `provider`, `reason`
* ("person_removed") and `credentialRevoked` (whether this removal revoked a live token). Never the
* subject, realm or credential id.
*/
"identity.link_retired",
/* Routines, however they were made: by a person on the screen or by a Bot through its tools. */
"routine.created",
"routine.updated",
"routine.deleted",
"routine.enabled_changed",
/* A run refused because its model is not on the team model allowlist. */
"model.refused",
/*
* A Recorder extension's bearer turned away: malformed, unknown or revoked, the person removed,
* their organization sign-in ended, or no role. Target the first 16 hex digits of the token's
* SHA-256, never the token; payload `reason` and `path`. At most one row per digest and reason a
* minute per replica, because a browser retrying a dead token would otherwise flood the trail.
*/
"recorder.bearer_refused",
/*
* A browser connected to OpenBot as the Recorder, by whom and through which extension copy. Never
* the token or the code; the label is the person's own name for the browser.
*/
"recorder.connected",
/*
* A connection refused before it was made; payload `reason`: `origin`, an origin that is not the Recorder's (payload
* `origin`, the one offered); `code`, a connect code that is unknown, expired or already used (payload `extensionId`
* and `installId`, never the code); or `too_many_codes`, the person already holding ten unused codes (payload `via`).
* A row that cannot be written is logged and the refusal stands.
*/
"recorder.connect_refused",
/*
* A connection ended; payload `via`, how it was made (as on `recorder.connected`), and `reason`: replaced (the same
* copy connected again), disconnected, revoked, signed_out (the person's sign-in here ended: payload `ending` says how,
* a sign-out, sessions ended another way, the person removed, their organization ending the session it holds a copy
* of) or expired (its lifetime ran out: the deployment ended it, payload `owner`); for a Bot's browser's connection,
* which lasts one recording, stopped (the person's Stop), ended (the recording ended without one) or not-started (the
* start it was for did not happen); for the person's own OpenBot browser's, cleared (they cleared that browser, and its
* token went with the profile). Written in the transaction that ends the connection, as `recorder.connected` is in
* the one that makes it.
*/
"recorder.revoked",
/*
* A security row: a person's sign-in here was ending (payload `ending`) and their Recorder connections could not be
* ended, after `attempts` tries (payload `error`, the database's complaint, never the query). The sign-in did not end
* either, and whoever was ending it was told: the person signing out, the administrator, the directory. Target the
* person.
*/
"recorder.sign_out_failed",
/*
* The capture pass (the runtime's trajectory/connect) turned a caller away: an id that is not a UUID, no
* Recorder bearer or one that no longer resolves, no role, the organization unable to answer, or a trajectory
* already bound to another person. Target the trajectory id; payload `reason`. At most one row per person,
* trajectory and reason a minute per replica.
*/
"recorder.trajectory_refused",
/*
* A person changed who else's Bots use the Skills learned in their own Learning space (Settings, Learning). Target
* the person; payload `from` and `to`, each `closed`, `open` or `choose`.
*/
"learning.sharing_changed",
/* A person opened one of their own learned Skills to every Bot, or closed it again. Target and payload `skill`. */
"learning.skill_opened",
"learning.skill_closed",
] as const;
export type AuditEventType = (typeof auditEventTypes)[number];
export type { AuditInitiator };
export const PERSON_INITIATOR: AuditInitiator = { kind: "person" };
/** The deployment acting as itself: at start-up, or refusing a caller it could not identify. */
export const DEPLOYMENT_INITIATOR: AuditInitiator = { kind: "deployment" };
/**
* The initiator a hop from `fromBotId` runs under.
*
* `origin` IS ALWAYS THE ROOT — what started the first run in the chain — and never another hop, so
* a check that needs to know who is steering reads one field however deep the chain is. A source
* that is itself a hop with no origin passes none on: an origin made up here would be read as fact.
*/
export function handoffInitiator(
fromBotId: string,
source: AuditInitiator | undefined,
): AuditInitiator {
const root = source ?? PERSON_INITIATOR;
if (root.kind === "handoff") {
return root.origin
? { kind: "handoff", id: fromBotId, origin: root.origin }
: { kind: "handoff", id: fromBotId };
}
return { kind: "handoff", id: fromBotId, origin: root };
}
/*
* The vocabulary, kept as the declaration of what a row's `initiator_kind` can be.
*
* It no longer screens the `initiatorKind` filter. Screening there dropped an unrecognised kind
* from the requested set, and a requested set left empty widened back into no filter at all; see
* `matchesRequested`. An unrecognised kind is now simply a kind no row carries.
*/
export const auditInitiatorKinds = [
"person",
"deployment",
"routine",
"responsibility",
"memory",
"handoff",
] as const;
export type AuditInitiatorKind = (typeof auditInitiatorKinds)[number];
export type AuditEventInput = {
eventType: AuditEventType;
targetType: string;
targetId?: string;
actorUserId?: string;
/** Omitted means a person did it. */
initiator?: AuditInitiator;
payload: Record<string, unknown>;
};
export type AuditStore = {
insert: (event: AuditEventInput) => Promise<void>;
};
export type AuditEvent = {
id: string;
actorUserId: string | null;
/** Read back as written, not narrowed to the union. */
initiatorKind: string;
initiatorId: string | null;
eventType: string;
targetType: string;
targetId: string | null;
payload: Record<string, unknown>;
createdAt: string;
};
export type AuditEventQuery = {
cursor?: string;
limit: number;
/**
* One event type, or several separated by commas.
*
* Several, because the questions people arrive with cut across the events that answer them: "was
* anything blocked" is a computer action refused, a component refused AND an MCP call rejected,
* and a filter that returns only the first quietly hides two thirds of the refusals.
*/
eventType?: string;
actorUserId?: string;
/** One kind, or several separated by commas, the way `eventType` takes several. */
initiatorKind?: string;
targetType?: string;
targetId?: string;
from?: string;
to?: string;
};
export type AuditReader = {
list: (query: AuditEventQuery) => Promise<{
events: AuditEvent[];
nextCursor?: string;
}>;
};
type AuditCursor = {
createdAt: string;
id: string;
};
function normalizedKey(key: string) {
return key.replaceAll(/[^a-zA-Z0-9]/g, "").toLowerCase();
}
function isSensitiveKey(key: string) {
return (
sensitiveKeys.has(key.toLowerCase()) ||
sensitiveKeys.has(normalizedKey(key))
);
}
export function redactAuditPayload(value: unknown): unknown {
if (Array.isArray(value)) {
return value.map(redactAuditPayload);
}
if (!value || typeof value !== "object") {
return value;
}
return Object.fromEntries(
Object.entries(value).map(([key, nestedValue]) => [
key,
isSensitiveKey(key) ? "[REDACTED]" : redactAuditPayload(nestedValue),
]),
);
}
export async function recordAuditEvent(
store: AuditStore,
event: AuditEventInput,
) {
await store.insert({
...event,
payload: redactAuditPayload(event.payload) as Record<string, unknown>,
});
}
/**
* Where code that should not hold the store writes to the trail.
*
* A sink rather than the store, so that code never touches the database. Written through
* `recordAuditEvent`, which redacts the payload the same way every other write does.
*/
export type AuditSink = {
record: (event: AuditEventInput) => Promise<void>;
};
export function auditSink(store: AuditStore): AuditSink {
return { record: (event) => recordAuditEvent(store, event) };
}
function initiatorColumns(initiator: AuditInitiator | undefined) {
if (!initiator)
return { initiatorKind: "person" as const, initiatorId: null };
if (initiator.kind === "person" || initiator.kind === "deployment") {
return { initiatorKind: initiator.kind, initiatorId: null };
}
return { initiatorKind: initiator.kind, initiatorId: initiator.id };
}
/** One row as written, handed to anything that streams the trail elsewhere. */
export type AuditTapEvent = {
eventType: string;
targetType: string;
targetId?: string;
actorUserId?: string;
initiatorKind: string;
initiatorId: string | null;
payload: Record<string, unknown>;
};
export type AuditTap = (event: AuditTapEvent) => void;
const auditTaps = new Set<AuditTap>();
/**
* Hear every row after it is written: the OpenTelemetry/SIEM exporter and Action Recording.
*
* After the insert, and only when it succeeded, so nothing is streamed that the trail does not hold.
* A tap that throws is logged and ignored: streaming a row must never fail writing it.
*/
export function addAuditTap(tap: AuditTap): () => void {
auditTaps.add(tap);
return () => auditTaps.delete(tap);
}
export function createAuditStore(database: Database): AuditStore {
return {
insert: async ({ initiator, ...event }) => {
const row = {
...event,
...initiatorColumns(initiator),
payload: redactAuditPayload(event.payload) as Record<string, unknown>,
};
await database.insert(auditEvents).values(row);
for (const tap of auditTaps) {
try {
tap(row);
} catch (error) {
console.error(
JSON.stringify({
type: "audit-tap-failed",
eventType: row.eventType,
error: String(error),
}),
);
}
}
},
};
}
function encodeCursor(cursor: AuditCursor) {
return Buffer.from(JSON.stringify(cursor)).toString("base64url");
}
export class AuditQueryError extends Error {
constructor(message: string) {
super(message);
this.name = "AuditQueryError";
}
}
/**
* The shape `audit_events.id` is, because that is what a cursor's id is compared against.
*
* Not a taste in ids: `lt(auditEvents.id, cursor.id)` is the DATABASE parsing this string, and
* anything it cannot parse is `invalid input syntax for type uuid` raised from inside the reader.
* Any version and any variant, because what the column accepts is what this must.
*/
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
/**
* A caller's page marker, read as the two values the query builder will actually bind.
*
* WHAT ARRIVES HERE IS A STRING SOMEBODY TYPED. The cast below used to say `AuditCursor` outright,
* which was a promise nobody could keep: this is `JSON.parse` over base64 out of a query parameter,
* so the fields hold whatever the caller put in them — a stale bookmark from another deployment's
* trail, a hand-edited link, a cursor from a screen that has since changed shape. It says
* `Partial<AuditCursor>` now so that the checks below are the only thing narrowing it, and it
* admits `null` and `undefined` because `JSON.parse` answers both.
*
* THE ID IS CHECKED AS A UUID AND NOT MERELY AS PRESENT, which is the whole of this function's
* history. It asked `!parsed.id`, so every truthy value passed: `"event-1"`, a number, an object.
* All three reach `lt(auditEvents.id, cursor.id)` in {@link createAuditReader}, where PostgreSQL
* answers `invalid input syntax for type uuid` — or, for the number, `operator does not exist: uuid
* < integer`. That is a `DrizzleQueryError` rather than an {@link AuditQueryError}, so it goes
* straight past the admin route's catch and leaves as a 500 with the statement and every bound
* value in its message. The route's 400 exists for exactly this: a cursor the server cannot read is
* the caller's to fix, the way a bad `from` or `to` already is. The only id a cursor can honestly
* carry is one {@link encodeCursor} wrote off a row, and that is always a uuid.
*
* AND THE TIMESTAMP IS CHECKED AS A STRING BEFORE IT IS CHECKED AS A DATE, because `Date.parse`
* stringifies whatever it is handed and the reader does not. A `createdAt` of `2020` parses as the
* YEAR 2020 and passes; `new Date(2020)` in the query builder is 2020 MILLISECONDS after 1970. The
* two readings of one field differ by fifty years, the endpoint answers 200, and the page comes
* from the wrong end of the trail with nothing saying so. A silent wrong page on the record of
* whose credential was spent on what is worse than a refusal, so the shape is settled here.
*
* WHAT IS RETURNED IS THE TWO FIELDS, rebuilt, so nothing else the caller packed into the cursor
* travels on into the query.
*/
function decodeCursor(cursor: string): AuditCursor {
try {
const parsed = JSON.parse(
Buffer.from(cursor, "base64url").toString("utf8"),
) as Partial<AuditCursor> | null | undefined;
if (
typeof parsed?.id !== "string" ||
!UUID.test(parsed.id) ||
typeof parsed.createdAt !== "string" ||
Number.isNaN(Date.parse(parsed.createdAt))
) {
throw new AuditQueryError("cursor must be a valid audit page cursor");
}
return { id: parsed.id, createdAt: parsed.createdAt };
} catch (error) {
if (error instanceof AuditQueryError) throw error;
throw new AuditQueryError("cursor must be a valid audit page cursor");
}
}
/**
* A comma-separated filter, read as the set of values it names.
*
* `undefined` means the caller did not ask, and the column goes unconstrained. `[]` means the caller
* did ask, and named nothing this trail could hold — a different answer, and the one the conditions
* below have to keep telling apart.
*
* A blank value counts as not asking, the way a blank `?limit=` still reads as the default page.
* Anything else the caller typed is an ask.
*/
function requestedValues(raw: string | undefined) {
if (raw === undefined || raw.trim() === "") return undefined;
return raw
.split(",")
.map((value) => value.trim())
.filter(Boolean);
}
/**
* The condition a requested set puts on a column, including the condition that nothing satisfies.
*
* An asked-for set that came out empty must narrow to nothing. It used to widen instead: both
* comma-separated filters collapsed an empty set into `undefined`, which `and(...)` drops, so
* `?initiatorKind=nonsense` — where the unrecognised kind was screened out of the set — answered
* the question "what did this initiator do" with every row in the trail, indistinguishable from a
* real result. On the record of whose credential was spent on what, handing back everything is the
* wrong direction to fail.
*
* A value that matches nothing answers empty rather than 400, matching how every other value
* parameter on this endpoint already behaves: `eventType`, `actorUserId`, `targetType` and
* `targetId` all take a free-form string and answer with whatever it matches, and `eventType` names
* a closed vocabulary just as `initiatorKind` does. What earns a 400 here is a value that cannot be
* read at all — `from`, `to`, `cursor` — not one that reads fine and names no row. Rejecting an
* unknown kind outright would also break `?initiatorKind=routine,nonsense`, which a caller unioning
* kinds can still expect to answer for the kind it did name.
*/
function matchesRequested(column: PgColumn, values: string[] | undefined) {
if (!values) return undefined;
const [first, ...rest] = values;
if (first === undefined) return sql`false`;
if (rest.length === 0) return eq(column, first);
return inArray(column, [first, ...rest]);
}
export function createAuditReader(database: Database): AuditReader {
return {
list: async (query) => {
const conditions = [
matchesRequested(
auditEvents.eventType,
requestedValues(query.eventType),
),
query.actorUserId
? eq(auditEvents.actorUserId, query.actorUserId)
: undefined,
matchesRequested(
auditEvents.initiatorKind,
requestedValues(query.initiatorKind),
),
query.targetType
? eq(auditEvents.targetType, query.targetType)
: undefined,
query.targetId ? eq(auditEvents.targetId, query.targetId) : undefined,
query.from
? gt(auditEvents.createdAt, new Date(query.from))
: undefined,
query.to ? lt(auditEvents.createdAt, new Date(query.to)) : undefined,
];
const cursor = query.cursor ? decodeCursor(query.cursor) : undefined;
if (cursor) {
// Bound as text and cast by PostgreSQL, not as a `Date`, which would drop the microseconds
// the cursor below carries.
const createdAt = sql`${cursor.createdAt}::timestamptz`;
conditions.push(
or(
lt(auditEvents.createdAt, createdAt),
and(
eq(auditEvents.createdAt, createdAt),
lt(auditEvents.id, cursor.id),
),
),
);
}
const rows = await database
.select({
...getTableColumns(auditEvents),
/*
* The row's own timestamp to the microsecond, for the cursor only.
*
* `created_at` keeps microseconds and a `Date` keeps milliseconds, so a cursor made from
* `createdAt` named a moment just before the row it came from. The rows the next page
* should have started with, written earlier in that same millisecond or at the same
* instant, then compared as newer than the cursor and were on no page at all.
*/
cursorCreatedAt: sql<string>`to_char(${auditEvents.createdAt} at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`,
})
.from(auditEvents)
.where(and(...conditions))
.orderBy(desc(auditEvents.createdAt), desc(auditEvents.id))
.limit(query.limit + 1);
const hasNextPage = rows.length > query.limit;
const page = rows.slice(0, query.limit);
const last = page.at(-1);
return {
events: page.map(({ cursorCreatedAt: _cursorOnly, ...event }) => ({
...event,
createdAt: event.createdAt.toISOString(),
payload: event.payload as Record<string, unknown>,
})),
nextCursor:
hasNextPage && last
? encodeCursor({
id: last.id,
createdAt: last.cursorCreatedAt,
})
: undefined,
};
},
};
}
export function auditQueryFromUrl(url: URL): AuditEventQuery {
/*
* Parsed strictly, like every other paged list. This used to trim and require `/^\d+$/`
* but fall back to 50 on anything else, so `?limit=abc`, `?limit=12abc`, `?limit=3.9`
* and `?limit=` all silently returned the default page while `?from=garbage` on the same
* endpoint answered 400. A typo in the page size is a caller error and names the parameter.
*/
const parsedLimit = parsePageLimit(url.searchParams.get("limit"), 100);
if (!parsedLimit.ok) {
throw new AuditQueryError(parsedLimit.error);
}
const limit = parsedLimit.limit ?? 50;
const optional = (name: string) => url.searchParams.get(name) ?? undefined;
const from = optional("from");
if (from !== undefined && Number.isNaN(Date.parse(from))) {
throw new AuditQueryError('Query parameter "from" must be a valid date.');
}
const to = optional("to");
if (to !== undefined && Number.isNaN(Date.parse(to))) {
throw new AuditQueryError('Query parameter "to" must be a valid date.');
}
/*
* Fail fast on a stale or hand-edited bookmark. Without this the raw string travels into
* `createAuditReader.list`, where `decodeCursor` threw a generic `Error` that escaped the
* route's `AuditQueryError` catch as a 500. A corrupt cursor is a caller error, not a server
* failure, and answers 400 like a bad `from`/`to` already does.
*/
const cursor = optional("cursor");
if (cursor !== undefined) {
decodeCursor(cursor);
}
return {
cursor,
limit,
eventType: optional("eventType"),
actorUserId: optional("actorUserId"),
initiatorKind: optional("initiatorKind"),
targetType: optional("targetType"),
targetId: optional("targetId"),
from,
to,
};
}
/**
* CSV export for the admin audit trail.
*
* The table at Admin > Audit is the only read surface, so a review that needs evidence —
* a compliance pull, an incident timeline, a count of what policy refused — has nowhere to
* take it. `GET /api/admin/audit-events?format=csv` answers the same filtered query as the
* JSON list and returns it as RFC 4180 CSV, capped so an unbounded trail cannot become an
* unbounded response. Payloads arrive here already redacted (see `redactAuditPayload`), and
* the export carries them as one JSON column rather than spreading unknown keys across
* columns a spreadsheet would then misread.
*/
export const AUDIT_EXPORT_MAX_ROWS = 5_000;
export const AUDIT_EXPORT_PAGE_SIZE = 500;
export const AUDIT_EXPORT_COLUMNS = [
"id",
"createdAt",
"eventType",
"actorUserId",
"initiatorKind",
"initiatorId",
"targetType",
"targetId",
"decisionAllowed",
"decisionRule",
"bot",
"payload",
] as const;
/**
* One CSV cell.
*
* A spreadsheet runs a cell that starts with `=`, `+`, `-` or `@` (or a tab or carriage return
* ahead of one) as a formula, and audit rows carry text people and Bots control: names, URLs,
* target IDs. Such a cell is prefixed with `'` so it opens as the text it is (OWASP's CSV injection
* guidance). JSON payloads start with `{` and timestamps and IDs with a digit or letter, so nothing
* the trail itself writes is changed.
*/
function toCsvCell(value: string): string {
const text = /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
if (
text.includes('"') ||
text.includes(",") ||
text.includes("\n") ||
text.includes("\r")
) {
return `"${text.replaceAll('"', '""')}"`;
}
return text;
}
function auditEventToCsvRow(event: AuditEvent): string {
const payload = event.payload ?? {};
const decision = (payload.decision ?? {}) as {
allowed?: unknown;
rule?: unknown;
};
const cells = [
event.id,
event.createdAt,
event.eventType,
event.actorUserId ?? "",
event.initiatorKind ?? "",
event.initiatorId ?? "",
event.targetType ?? "",
event.targetId ?? "",
typeof decision.allowed === "boolean" ? String(decision.allowed) : "",
typeof decision.rule === "string" ? decision.rule : "",
typeof payload.bot === "string" ? payload.bot : "",
JSON.stringify(payload),
];
return cells.map(toCsvCell).join(",");
}
export function auditEventsToCsv(events: AuditEvent[]): string {
const header = AUDIT_EXPORT_COLUMNS.join(",");
if (events.length === 0) return `${header}\n`;
return `${header}\n${events.map(auditEventToCsvRow).join("\n")}\n`;
}
/**
* The rows behind an export, walked page by page through the same reader the JSON list
* uses, so the CSV and the table never disagree about what a filter matches.
*
* `cursor` and `limit` are the JSON list's paging, not the export's, and are ignored here:
* the export takes everything the filters match up to `maxRows` and says whether it
* stopped early, so the caller can narrow the range instead of silently receiving a
* partial trail.
*/
export async function readAuditExportRows(
reader: AuditReader,
baseQuery: AuditEventQuery,
options?: { maxRows?: number; pageSize?: number },
): Promise<{ events: AuditEvent[]; truncated: boolean }> {
const maxRows = options?.maxRows ?? AUDIT_EXPORT_MAX_ROWS;
const pageSize = options?.pageSize ?? AUDIT_EXPORT_PAGE_SIZE;
const { cursor: _paging, limit: _limit, ...filters } = baseQuery;
const events: AuditEvent[] = [];
let cursor: string | undefined;
let truncated = false;
for (;;) {
const page = await reader.list({ ...filters, limit: pageSize, cursor });
for (const event of page.events) {
if (events.length >= maxRows) {
truncated = true;
return { events, truncated };
}
events.push(event);
}
if (!page.nextCursor) return { events, truncated };
cursor = page.nextCursor;
}
}