Skip to content

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.

71.5 KB
Raw Blame
import { and, eq, sql } from "drizzle-orm";
import type { ApprovalGate } from "../../approvals/types";
import type { AuditStore } from "../../audit";
import type { ActionPolicy } from "../../computer/policy";
import type {
  CredentialSecretReader,
  CredentialStore,
} from "../../credentials";
import type { Database } from "../../db/client";
import { isQueryFailure, withoutStatement } from "../../db/query-failure";
import { pendingAuthorizations } from "../../db/schema";
import type { CheckPrivateShare } from "../../proactive/private-share";
import {
  BROKERED_PROFILE,
  type BrokerProvider,
  type ServerAccess,
  ServerUnresolvableError,
} from "../access";
import type {
  BrokerConnection,
  ComposioBroker,
  Decides,
  RecordedScheme,
} from "../broker";
import { type CatalogueEntry, resolveServerUrl } from "../catalogue";
import { type ListedTool, McpServerError } from "../mcp";
import type { AccountMode } from "../shared-accounts";
import type { SharedUseGate } from "../shared-use-store";

/**
 * The plugin store's model: its record types, errors, how a tool schema is stored, the token
 * exchange and the OAuth client shape. Split out of `../store.ts`; that file re-exports what it
 * always exported, so its importers did not change.
 */

/**
 * Plugins: what this deployment has added, which Bots may use it, and the one path a call takes.
 *
 * The grant and the policy are two different questions and both are asked on every call. The grant
 * answers "is this Bot allowed this tool at all", which an operator decides on the Plugins page. The
 * policy answers "is this particular call permitted right now", which is written as a rule and can
 * say things a grant cannot: not on this host, not this argument, not a write. Collapsing them would
 * mean an operator who granted a Bot a server had also, invisibly, waived every rule about it.
 */

/**
 * What a grant is a grant OF.
 *
 * `bot` is one Bot's permission to hand work to another, and it lives here rather than in a table of
 * its own on purpose: an administrator already understands "this Bot may use that", a fork's policy
 * layer already applies to grants, and reachability between Bots is the same kind of decision as
 * reachability to a vendor's tools. A second table would be a second thing to reason about and a
 * second thing for a fork to reimplement.
 */
export type PluginKind = "mcp" | "skill" | "bot";

/**
 * What an audit row about a grant is a row ABOUT.
 *
 * A mapping rather than a ternary, because a ternary quietly labelled everything that was not an MCP
 * tool a skill. Adding a third kind made that wrong rather than merely terse: a grant letting one Bot
 * address another would have been filed in the trail as a skill, which is the sort of small lie an
 * investigation trips over months later.
 */
export function grantTargetType(kind: PluginKind): string {
  if (kind === "mcp") return "mcp_tool";
  if (kind === "bot") return "agent";
  return "skill";
}

export type ToolRecord = {
  serverId: string;
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
  /** `<serverId>/<name>`. What a grant names and what the model's tool name is derived from. */
  ref: string;
  effect: "read" | "write";
  /**
   * Whether the vendor warns that this action destroys something.
   *
   * Beside {@link ToolRecord.effect} rather than folded into it: the rule engine judges reads and
   * writes and gains nothing from a third value, while a person deciding whether to switch an action
   * on is asking a different question. Recorded from the vendor's own labels, so false is an absence
   * of a claim rather than a claim of safety.
   */
  destructive: boolean;
  grantedTo: string[];
};

/**
 * A grant naming a tool this server does not currently advertise.
 *
 * Held and not offered. `listForAgent` reads the grant against the tool list, so nothing reaches a
 * model — but that is a property of what the vendor is advertising today rather than of the grant, and
 * it changes the moment the vendor advertises the name again. Google's Drive entry says so in its own
 * comment: the REST transport is one line from being swapped back to MCP, and "tool names match
 * Google's MCP server exactly, so grants survive the swap in either direction".
 *
 * So it is reported rather than pruned. A grant is the record of a decision somebody made, and the
 * refresh that would have deleted it is not a safe place to decide from: the tool list is replaced by
 * a `delete` and then an `insert`, and a vendor answering with an empty list is a success, so one bad
 * answer would revoke every grant on that server and stamp the refresh as healthy.
 */
export type WithdrawnGrant = {
  /** `<serverId>/<toolName>`, exactly as the grant is stored. */
  ref: string;
  /** The tool half, for a screen that already has the server. */
  name: string;
  grantedTo: string[];
};

export type ServerRecord = {
  id: string;
  title: string;
  logo: string | null;
  vendor: string;
  url: string;
  summary: string;
  docsUrl: string;
  /** `first-party` or `custom`. Shown wherever the server is, never inferred by a reader. */
  provenance: string;
  hasCredential: boolean;
  toolsRefreshedAt: string | null;
  lastError: string | null;
  /** What the last stored listing left out for its names; a warning, never a failure. */
  skippedTools: string[];
  addedBy: string | null;
  /**
   * Whether the catalogue entry registers its own OAuth client (RFC 7591) rather than waiting on
   * an administrator to paste one in. So the admin screen can hide the paste-a-client form where
   * there is nothing for it to collect.
   */
  dynamicClient: boolean;
  /**
   * How this server's authorization config was created, for the brokered rows that have one.
   *
   * WHAT WAS WRITTEN DOWN WHEN SOMEBODY ENABLED THE APP, NOT WHAT THE CATALOGUE PUBLISHES TODAY.
   * The catalogue is the vendor's, and an app it starts advertising under a different scheme has
   * not moved the config this deployment already created — so a reader deciding what a live
   * connection does must read this and not a fresh listing. The `authScheme` column carries the
   * same fact and the same warning about which vocabulary it holds: the vendor's own scheme
   * literals (`OAUTH2`, `DCR_OAUTH`, `API_KEY`, `NO_AUTH`, and the rest), never a
   * {@link BrokerConnection} kind.
   *
   * Null is not an older brokered row. It is a row that is not brokered at all.
   */
  authScheme: string | null;
  /**
   * Whose account a brokered app acts in: each person's own, or the one the deployment holds.
   * Null on a row that needs no account at all, and on every row that is not brokered.
   */
  accountMode: "personal" | "shared" | null;
  /**
   * Whether a Shared app's deployment-held account is connected yet.
   *
   * ALWAYS FALSE WHILE {@link accountMode} IS NOT `"shared"`, even where a deployment row happens
   * to stand at the app's url: a Personal app never acts in that account, so reporting it as
   * connected would tell the page something that changes nothing a call does.
   */
  sharedVendorConnected: boolean;
  /**
   * Who may give this app to a Bot, with the default for its account filled in: any Bot's owner
   * (`any`), or only an administrator (`admin`). See `ownerGrantsOf`.
   */
  ownerGrants: "any" | "admin";
  /** What an administrator chose, or null where the default above is in force. */
  ownerGrantsChosen: "any" | "admin" | null;
  tools: ToolRecord[];
  /**
   * Grants on tools this server no longer advertises.
   *
   * Empty for a healthy connector. Non-empty is the discrepancy an administrator should be reading
   * about, which is why it is here rather than inferred by a screen comparing two lists.
   */
  withdrawn: WithdrawnGrant[];
};

/**
 * A server row as the surfaces that only need to know where it is see it.
 *
 * Four columns of {@link ServerRecord} and none of what hangs off it, because the callers this is
 * for ask one question: which vendor is this row addressed at. The title travels with the url
 * because their refusals name it — "You already have an account connected to Linear" is the app's
 * name, which is the only one of the two a person has ever seen on a screen.
 */
export type ServerAddress = {
  id: string;
  title: string;
  url: string;
  /**
   * How this row's authorization config was created, for the brokered rows that have one.
   *
   * THE RECORDED SCHEME, NEVER A FRESH CATALOGUE READ. An app's config was created as one
   * particular scheme and every connection standing against that config depends on it, so the
   * connect path has to open the flow this column names rather than the one the catalogue
   * publishes for the app today. Re-derived from a listing instead, a vendor that starts
   * advertising a new scheme would silently move live connections onto a different flow — minting
   * a consent link against a config that holds keys, or asking for a key where a consent screen is
   * waiting.
   *
   * The same vocabulary the column holds, which the schema comment spells out: the vendor's own
   * scheme literals, never a {@link BrokerConnection} kind. Null is not an older brokered row; it
   * is a row that is not brokered.
   */
  authScheme: string | null;
  /**
   * Whose account the app this row names is used under: each person's own, or one the deployment
   * holds for everybody.
   *
   * THE APP'S, READ OFF THE ROW THAT ANSWERS FOR IT, exactly as {@link authScheme} is. Two rows may
   * name one app and only one of them decides whose account it is, so a page that drew the Shared
   * treatment off the row it opened could show one answer while every connect, grant and call
   * behind its buttons acted on the other. Null is a row that is not brokered, and also a brokered
   * row whose app has no answering row left to say.
   */
  accountMode: AccountMode | null;
};

export type SkillRecord = {
  id: string;
  slug: string;
  /** Whose it is. Null means the deployment's, written by an administrator or shipped. */
  ownerUserId: string | null;
  title: string;
  summary: string;
  instructions: string;
  origin: string;
  installedBy: string | null;
  grantedTo: string[];
  /**
   * The tools this skill says it needs, as `<serverId>/<toolName>` refs.
   *
   * A declaration, not a grant: what a Bot may call is `grantedTo` on the tool side and nothing here.
   * See the comment on `skillTools` in the schema for why that separation is load-bearing.
   */
  tools: string[];
};

/**
 * Who is asking, for the surfaces where the answer depends on it.
 *
 * An administrator sees and governs the whole deployment. Everybody else sees the deployment's
 * skills and their own, and may act only on their own.
 */
export type SkillActor = { id: string; isAdmin: boolean };

/** What one Bot holds. Everything the runtime needs to offer it, and nothing it does not. */
export type GrantedPlugins = {
  tools: {
    ref: string;
    /** The name the model is offered, which is the ref with the separator a tool name allows. */
    toolName: string;
    description: string;
    inputSchema: Record<string, unknown>;
  }[];
  skills: {
    slug: string;
    title: string;
    summary: string;
    instructions: string;
    /**
     * What this skill says it needs, as refs. Never a superset of `tools` above in effect: selection
     * intersects the two, because a skill naming a tool the Bot lacks must load nothing rather than
     * make it callable.
     */
    tools: string[];
  }[];
};

export type PluginDecision =
  | { allowed: true }
  | { allowed: false; reason: string };

/**
 * What one check of somebody's brokered account spent, and what came of it.
 *
 * FOUR OUTCOMES AND NOT A PAIR OF NULLABLE FIELDS, because the fourth one is what the pair could
 * not say and its absence was destructive. `verified: false` used to cover both "the app published
 * nothing safe to try" and "it ran and the vendor refused the key", which is why the action's name
 * travels beside the verdict at all — and a THIRD thing was quietly landing in the second of those:
 * a vendor nobody could reach. `callTool` never throws, so a Composio outage, a socket that closed
 * and a package that cannot parse an answer all arrived as `isError: true` and were read as the
 * vendor rejecting the key. See {@link ActionAnswer} in `./composio` for the reading that settles
 * it, and {@link composioConnections.probeAction} for what each of these may be written down as.
 *
 * `probe` IS THE ACTION A CHECK CAN BE SHOWN TO HAVE SPENT, and it is null on both outcomes where
 * nothing can be shown — which is the whole structural point of this shape rather than a nicety.
 * That field is what the writer records in `probe_action`, and a name beside `verified: false` is
 * the accusation "it ran and the vendor refused your key". An unreachable vendor therefore has no
 * name to give the writer, and cannot make that claim even by mistake; what was attempted is
 * carried separately, for the trail and for the sentence somebody reads.
 */
export type BrokeredProbe =
  /** The app published nothing safe to call, or no row for it is left. Nothing was tried. */
  | { outcome: "nothing"; probe: null }
  /** It ran in this person's account and the vendor took the key. */
  | { outcome: "answered"; probe: string }
  /**
   * It ran in this person's account and the app answered with a failure. `sentence` is Composio's
   * own account of it.
   *
   * AND THAT IS THE WHOLE OF WHAT IT PROVES, WHICH IS WHY IT IS NOT CALLED `refused`. It was, and
   * every reader took the name at its word: the connect path DELETED the account it had made
   * seconds earlier and told the person what they entered did not work, and the re-check path
   * wrote the named-probe-beside-`verified: false` pair, which the settings page draws as "your
   * key was checked and rejected".
   *
   * NOTHING IN THE ENVELOPE SUPPORTS EITHER CLAIM. What arrives is Composio's
   * `{ data, error, successful }` — no HTTP status, no error code, nothing structured about the
   * credential — so a rate limit, a scope the key legitimately lacks for this one action, and a
   * 404 for a resource the read action happens to name are all indistinguishable here from a key
   * the vendor rejected. A person pasting a VALID key into an app that is rate-limiting had their
   * brand-new working connection revoked with a message blaming them, and that is not recoverable
   * by pressing anything: the key has to be fetched and typed again.
   *
   * SO THE TWO DESTRUCTIVE READINGS ARE GONE AND THE NAME NO LONGER INVITES THEM. The account
   * stands, the row records the check as failed with the action it was spent on, and the sentence
   * the person is shown is the app's own words rather than a verdict about their credential. If
   * Composio ever publishes a status or an error code on this envelope, telling the two apart is
   * a fifth outcome and the roster below is what will make somebody decide it everywhere.
   */
  | { outcome: "complained"; probe: string; sentence: string }
  /**
   * The vendor was not reached, or answered something nothing here can read, so NOTHING WAS
   * LEARNED — about the key, and about whether the action ran at all. `attempted` is what would
   * have been spent, which is a fact about this deployment's intent rather than about the account.
   */
  | {
      outcome: "unreachable";
      probe: null;
      attempted: string;
      sentence: string;
    };

/**
 * The four outcomes as a ROSTER, which is what anything enumerating them is checked against.
 *
 * A union is a thing a fifth member can be added to in one line with nothing anywhere failing:
 * every reader of this vocabulary asks `probed.outcome === "complained"` or `=== "unreachable"`, and a
 * chain of equality tests has no opinion about the answer it was not written for. `unreachable` is
 * itself the proof — it was added in round two and the screen that draws these outcomes went on
 * rendering it with the sentence written for a different case. See {@link Decides}.
 *
 * PINNED TO THE UNION IN BOTH DIRECTIONS. `satisfies` holds this list inside the union, so a name
 * misspelled here fails; {@link _ProbeRosterNamesTheWholeUnion} holds the union inside this list, so
 * a member added to the union and not to this roster fails. Neither direction is worth having on its
 * own: the pair is what makes the roster a restatement that cannot drift.
 *
 * SO A FIFTH OUTCOME COSTS TWO STEPS AND CANNOT SKIP EITHER. Adding it to the union fails `tsc`
 * here and at every consumer's `Decides<…>` roster; adding it here to satisfy that then fails the
 * table in `tests/composio-connection-kinds.test.ts`, which reads its rows off this list and has no
 * cell for the new name. The compiler settles what must decide and the table settles what it does.
 */
export const BROKERED_PROBE_OUTCOMES = [
  "nothing",
  "answered",
  "complained",
  "unreachable",
] as const satisfies readonly BrokeredProbe["outcome"][];

/** The other direction of {@link BROKERED_PROBE_OUTCOMES}' pin. Type-only; erased entirely. */
export type _ProbeRosterNamesTheWholeUnion = Decides<
  BrokeredProbe["outcome"],
  Record<(typeof BROKERED_PROBE_OUTCOMES)[number], string>
>;

/**
 * THE FOUR STATES A CONNECTION ROW MAY BE LEFT IN, named so the pair can be enumerated.
 *
 * `verified` and `probe_action` are one fact recorded in two columns, and
 * {@link composioConnections.probeAction} enumerates the four readings of that pair in prose. Prose
 * is what the client then modelled as three — the outage and the never-checked case share the
 * mildest pair, and the screen drew one of them with the other's sentence. This is the same four
 * with names, so a consumer that has to decide on them can be held to naming all four.
 *
 * NOT A COLUMN, NEVER WRITTEN ANYWHERE, AND NOT EXPORTED. The row carries the pair; this is the
 * reading of it, and its one job is to be the value type {@link _ProbeOutcomeLeaves} is checked
 * against.
 *
 *   `unchecked` — null probe, not verified. Nothing was tried, so nothing is known about the key.
 *   `consented` — null probe, verified. A consent connection; the vendor's own yes is the evidence.
 *   `checked`   — a named probe, verified. It ran in this account and the vendor took the key.
 *   `failed`    — a named probe, not verified. It ran and the app answered with a failure, and the
 *                 account still stands. The one state an operator has to act on.
 *
 * `failed` RATHER THAN `refuted`, AND THE RENAME IS THE FIX RATHER THAN A TIDY-UP. It was
 * `refuted` — "the vendor refused the key", described in this file as "the accusation" — and
 * nothing that writes this pair can establish that. See {@link BrokeredProbe}'s `complained`
 * member: the envelope the verdict is read out of carries no status and no error code, so the
 * pair says a check was spent and did not come back clean, and it stops there. Everything that
 * renders it says the same, in the app's own words.
 */
export type RecordedCheck = "unchecked" | "consented" | "checked" | "failed";

/**
 * WHICH OF THE FOUR A PROBE OUTCOME MAY EVER LEAVE BEHIND, the seam the two vocabularies meet at.
 *
 * Type-only and erased. It is a statement about {@link BrokeredProbe} rather than about any one
 * writer, and it is here because `failed` is the state the whole shape of that type exists to
 * withhold: an outcome carrying no probe name has no name to record, so it cannot reach that pair
 * even by mistake. A fifth outcome has to say which of the four it may leave behind before anything
 * compiles, which is precisely the question that went unasked when `unreachable` was added.
 *
 * THE ANSWERS ARE NARROWED TO {@link RecordedCheck} rather than left as free text, which is what
 * makes this a contract and not a comment: a state invented here that the schema's four do not
 * include fails, and so does one of the four renamed on one side of the seam only.
 */
export type _ProbeOutcomeLeaves = Decides<
  BrokeredProbe["outcome"],
  {
    nothing: "untouched";
    answered: "checked";
    complained: "failed";
    unreachable: "untouched";
  },
  RecordedCheck | "untouched"
>;

export class PluginRefusedError extends Error {
  constructor(
    message: string,
    readonly rule: string | null,
  ) {
    super(message);
    this.name = "PluginRefusedError";
  }
}

export class CatalogueEntryUnknownError extends Error {
  constructor(key: string) {
    super(`${key} is not a server this deployment will connect to.`);
    this.name = "CatalogueEntryUnknownError";
  }
}

/** A URL an administrator offered that this deployment will not point itself at. */
export class CustomServerRefusedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CustomServerRefusedError";
  }
}

/**
 * A state this deployment's own code says cannot exist, found existing.
 *
 * CRITERION. Nothing here is a vendor's doing, a credential's doing or anything a person asking can
 * act on, so no path may record one of these as though a vendor had misbehaved.
 *
 * REASON. `refreshTools` wrapped the listing, the replace and both audit writes in one `catch` that
 * copied every message into `lastError` and answered `{ tools: 0 }`. A plain `Error` is what the
 * narrowing throws in {@link createPluginStore}'s `connectionTokenFor` raise, so a row that resolved
 * to a brokered credential with no app in its url — or to a per-person credential with no
 * `user-oauth` entry — came out on the Plugins page as a sentence about the vendor, next to a
 * refresh that looked like it had merely failed. An operator reading that is sent to somebody else's
 * status page over a contradiction in our own tables.
 *
 * A class rather than a message, because telling these apart by prose is telling them apart by a
 * substring that a reword would silently change. Distinct from {@link PluginRefusedError}, which is
 * a refusal somebody CAN act on and which does belong in `lastError` — an administrator who has not
 * connected their account is the honest reason a listing did not happen.
 */
export class PluginInvariantError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "PluginInvariantError";
  }
}

/**
 * Whether a throw is this deployment contradicting itself, rather than anything anybody asked for.
 *
 * CRITERION. Every audience boundary asks THIS instead of listing classes of its own. A fault it
 * answers true for reaches an operator as its own sentence, on a surface only an operator can
 * reach, and reaches everybody else as the fact that the call did not happen — no message, no
 * column names, no instruction about a row.
 *
 * REASON. The distinction already existed and was drawn by hand, once, in each place that
 * remembered to draw it: {@link PluginRefusedError} is relayed verbatim because it is a refusal
 * the asker can act on, and everything else fell into a branch that copies `error.message`
 * onwards. {@link ServerUnresolvableError} was caught by none of them — the refresh route rethrew
 * it into the framework's default handler, which answers a bodiless 500, so the admin page said
 * "That did not work" and named nothing; `grantedTools` put its message in a model's context,
 * where a sentence telling an operator to correct a provenance column became a Bot's explanation
 * to an end user of why their tool failed. Two audiences, one refusal, neither served.
 *
 * {@link PluginInvariantError} is on the same shelf and answers true for the same reason: it is
 * this deployment finding a state its own code says cannot exist. That is not a vendor
 * misbehaving and not a person's to act on mid-call, and its own docblock has said so since it
 * was written — what it lacked was anywhere that asked.
 *
 * A PREDICATE RATHER THAN A SHARED BASE CLASS, because the two live in different modules and must
 * keep doing so: `access.ts` is a leaf that `store.ts` imports, so the shelf cannot be declared
 * once without one of them importing the other back.
 */
/**
 * The one character no PostgreSQL `text` or `jsonb` value can hold, whatever the vendor sent.
 *
 * Not a length limit and not an encoding preference: the server rejects the statement outright,
 * mid-transaction, and the rejection arrives as a query error rather than as anything about the
 * value.
 */
export const NUL = "\u0000";

/**
 * A schema this deployment cannot turn into a row, whatever the column would have said.
 *
 * Its own class so the one place that raises it and the one place that contains it are joined by
 * something other than a substring: {@link storableSchema} is the only thrower, and the `try`
 * around the call that turns a listing into rows is the only catcher. Nothing branches on the class
 * — it is recorded the way anything else a vendor's answer could not be made into would be — but
 * naming it keeps a later reader from mistaking it for a fault of this deployment's own.
 */
export class SchemaUnstorableError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "SchemaUnstorableError";
  }
}

/**
 * The same JSON value with every U+0000 gone from it — out of the strings, and out of the keys
 * above them.
 *
 * CRITERION ONE. What is removed is the CHARACTER. A string that merely SPELLS the escape — a
 * backslash and then `u0000`, which is how a JSON Schema excludes control characters and is by far
 * the commonest place those six letters legitimately appear — is handed back untouched.
 *
 * CRITERION TWO. Everything else is rebuilt identical: the same keys, the same nesting, the same
 * scalars.
 *
 * WHAT THIS REPLACED, and why walking the DATA is not a stylistic preference. The strip used to run
 * over the SERIALISED schema — `JSON.stringify(schema).replaceAll("\\u0000", "")` — which is
 * escape-blind by construction. `JSON.stringify` writes a real backslash inside a string value as
 * two of them, so a pattern such as `"[^\u0000-\u001f]"` reached the strip with its backslash
 * doubled and had the TAIL of it eaten, leaving `\-`. That is not a JSON escape, so the
 * `JSON.parse` wrapped around it threw a `SyntaxError` — from a line that sat outside BOTH `try`
 * blocks in `refreshTools`. It left as a bodiless 500 with `lastError` still holding whatever it
 * held before, and on the add path, which refreshes before it answers, it aborted the add AFTER the
 * server row and its audit row had committed.
 *
 * Serialised text cannot tell the byte from the six letters that name it; parsed data can only ever
 * hold one of them. So walking the data is what makes CRITERION ONE expressible at all.
 *
 * A SELF-REFERENTIAL VALUE IS REFUSED rather than quietly truncated, and `ancestors` holds only the
 * chain currently being descended — so one object reached twice side by side is copied twice, which
 * is what a plain JSON document does anyway. Nothing off a wire can be cyclic; a value built inside
 * this process can, and it is a value `jsonb` would refuse in any case. Refused HERE it is a
 * sentence the caller can record; left to the driver it is a statement dump.
 */
export function withoutNul(value: unknown, ancestors: Set<object>): unknown {
  if (typeof value === "string") return value.replaceAll(NUL, "");
  if (typeof value !== "object" || value === null) return value;
  if (ancestors.has(value)) {
    throw new SchemaUnstorableError(
      "The schema refers back to itself, so it is not a value JSON can hold.",
    );
  }

  ancestors.add(value);
  const stripped: unknown = Array.isArray(value)
    ? value.map((item) => withoutNul(item, ancestors))
    : Object.fromEntries(
        Object.entries(value).map(([key, nested]) => [
          key.replaceAll(NUL, ""),
          withoutNul(nested, ancestors),
        ]),
      );
  ancestors.delete(value);
  return stripped;
}

/**
 * {@link withoutNul} over a schema, answering in the type the column and the row builder use.
 *
 * The walk rebuilds an object as an object and a list as a list, so what comes back is the shape
 * that went in — which is the same promise the `JSON.parse(JSON.stringify(...))` round trip this
 * replaced made about everything except the escape it could not see. The narrowing says out loud
 * what the parameter type already claims.
 */
export function storableSchema(
  schema: Record<string, unknown>,
): Record<string, unknown> {
  return withoutNul(schema, new Set()) as Record<string, unknown>;
}

/**
 * What a vendor listed, as rows this database will actually take.
 *
 * CRITERION ONE. No two rows carry the same name, whatever the vendor listed.
 *
 * CRITERION TWO. No string reaching the insert contains U+0000, in a column or inside a schema —
 * and nothing else about what the vendor wrote is altered to achieve it, which is a criterion of
 * its own because the first attempt at this one failed it. See {@link storableSchema}.
 *
 * CRITERION THREE. Whatever this raises, its caller catches — see the `try` around the one call
 * site. Everything here runs OUTSIDE the vendor `try` and before the transaction's own, so a throw
 * from here left `refreshTools` unhandled: a bodiless 500, a `lastError` still holding whatever it
 * held before, and an add aborted after its server row and its audit row had already committed.
 *
 * REASON. Both of these used to abort the replace from INSIDE the transaction and OUTSIDE the
 * vendor `try` above it, so they came out of `refreshTools` as a raw `DrizzleQueryError` — whose
 * message is `Failed query: <the whole statement>` followed by `params:` and every value bound to
 * it. That reached an operator's page and the logs as a SQL dump, which is the same disclosure
 * shape as a leaked credential one layer out, and it left `lastError` holding whatever was there
 * before: stale, or null, on a refresh that had in fact failed.
 *
 * FIXED BY NOT REACHING THE DATABASE WITH IT, rather than by catching it better. A vendor that
 * names one action twice is answering about one action — `mcp_tools`' `(server_id, name)` primary
 * key says so, and the first listing is as good an answer as the second, so the duplicate is
 * dropped rather than made into an error somebody has to act on. A control character in a
 * description is not content anybody wants to keep either. What is left after this is a
 * transaction that fails for reasons that are genuinely not the vendor's, which is what the
 * comment on the replace has always claimed.
 *
 * FIRST OCCURRENCE WINS, and the order is the vendor's own. Anything else needs a rule for which
 * of two identical names is the real one, and there is no such rule.
 *
 * CRITERION FOUR. No row carries a name a model cannot be offered, and every name left out for that
 * reason comes back in `skipped`, once, spelled as the vendor listed it — so the caller can say
 * which actions were not recorded rather than leave their absence for somebody to notice.
 */
export function storableTools(
  serverId: string,
  listed: ListedTool[],
): { rows: StorableTool[]; skipped: string[] } {
  const byName = new Map<string, StorableTool>();
  const skipped = new Set<string>();

  for (const tool of listed) {
    const name = tool.name.replaceAll(NUL, "");
    /*
     * THE GUARD THAT MAKES THE OFFERED NAME OFFERABLE, placed at the one seam every transport's
     * listing passes through on its way into the database.
     *
     * A model tool name may only match `^[a-zA-Z0-9_-]+$`, and `name` is spliced into one by
     * {@link toolNameFor}. Nothing used to check: Arcade's dotted `qualified_name` was recorded
     * whole and the refusal arrived much later and somewhere else entirely — as a 400 on the model
     * request naming `tools[47]`, with no mention of the app, the action or the refresh that
     * recorded it. A person reading that has nothing to act on.
     *
     * SKIPPED AND NAMED, NOT REFUSED. This used to throw, which cost the whole listing for one
     * name: the MCP spec allows a dot in a tool name, so a custom server with a single dotted
     * action stored none of its others on an add and froze its list on every refresh after. The
     * guarantee that matters — the name never reaches a model — holds either way; what skipping
     * changes is that the rest of the app keeps working. The name comes back to the caller, which
     * says on the app's own page what was left out.
     */
    if (!OFFERABLE_TOOL_NAME.test(name)) {
      skipped.add(name);
      continue;
    }
    if (byName.has(name)) continue;
    byName.set(name, {
      serverId,
      name,
      /*
       * The vendor's spelling where the transport drew a distinction, and the same string where it
       * did not — which is the whole of what absence means here. See {@link ListedTool.vendorName}.
       */
      vendorName: (tool.vendorName ?? name).replaceAll(NUL, ""),
      /*
       * Defaulted where the COLUMN has a default, because that is what the previous mapping leaned
       * on: it passed these two straight through, so a transport handing back undefined got the
       * `""` and `{}` the schema declares. Reading a method off the value instead would turn the
       * same absence into a TypeError thrown from outside the vendor `try`. Both fields are
       * required by `McpTool` and supplied by every transport here; this keeps the tolerance the
       * insert already had rather than adding a new answer.
       */
      description: (tool.description ?? "").replaceAll(NUL, ""),
      /*
       * By walking the parsed schema rather than its serialised text, because only one of those two
       * can tell the character from the six letters that name it. See {@link storableSchema}: this
       * used to strip the escape out of `JSON.stringify`'s output, which ate the tail of every
       * legitimately-escaped backslash and left a string `JSON.parse` refused.
       */
      inputSchema: storableSchema(tool.inputSchema ?? {}),
      /*
       * What the vendor said, when the vendor said anything.
       *
       * Only Composio publishes an effect and a version, and an MCP server publishes a
       * destructive hint — see `mcp.ts`. All three stay null or false for a transport that says
       * nothing, and `classifyTool` reads null as silence rather than as a value, which is what
       * leaves Notion and Drive classified by their reviewed write list exactly as they were.
       */
      effect: tool.effect ?? null,
      destructive: tool.destructive ?? false,
      version: tool.version?.replaceAll(NUL, "") ?? null,
    });
  }

  return { rows: [...byName.values()], skipped: [...skipped] };
}

/** One row {@link storableTools} hands to the `mcp_tools` insert. */
export type StorableTool = {
  serverId: string;
  name: string;
  vendorName: string;
  description: string;
  inputSchema: Record<string, unknown>;
  effect: "read" | "write" | null;
  destructive: boolean;
  version: string | null;
};

export function isDeploymentFault(error: unknown): error is Error {
  return (
    error instanceof ServerUnresolvableError ||
    error instanceof PluginInvariantError ||
    /*
     * A query this database refused is on the shelf for the reason the other two are: it is not a
     * vendor's doing, it is not the asker's to act on, and its message is the one thing here that
     * must not travel. The replace in `refreshTools` was fixed at its own site; every other query
     * on the call path — the advertised-tool read, the connection gate, the vault read, the locked
     * credential swap — throws the same shape into a `catch` that copies `error.message` onward,
     * so answering it here is what makes the four audiences agree without four more branches.
     *
     * Callers that SHOW the sentence to an operator must still ask {@link withoutStatement} for
     * it rather than reading `.message`; this predicate settles who may be told, not what.
     */
    isQueryFailure(error)
  );
}

/** The operator-facing sentence for a fault on that shelf, with no statement in it. */
export function deploymentFaultSentence(error: Error): string {
  return withoutStatement(error);
}

/**
 * The vendor's `error` code, when a token endpoint refuses an exchange.
 *
 * {@link INVALID_CLIENT} is the one code this module ACTS on rather than reports, so it has to
 * survive as a value. It used to travel inside the sentence, which meant the recovery in
 * {@link createPluginStore}'s `refuseAndReplaceEvictedClient` hung on a substring of prose written for a
 * person to read: rewording the sentence — translating it, dropping the parenthesis — would have
 * turned self-registration off with every test still green. A field cannot be reworded by accident.
 */
export class TokenRefusedError extends McpServerError {
  constructor(
    message: string,
    readonly code: string | null,
  ) {
    super(message);
    this.name = "TokenRefusedError";
  }
}

/**
 * The vendor saying the CLIENT is the problem, rather than the grant. RFC 6749 §5.2.
 *
 * Told apart from every other refusal because it is the only one a deployment can do anything about
 * on its own: a client it issued to itself, it can issue again.
 */
export const INVALID_CLIENT = "invalid_client";

/**
 * The OAuth error code for a refresh token the vendor will no longer honour (RFC 6749 §5.2): it was
 * revoked, it expired, or the person withdrew the grant. Nothing this deployment can do brings it
 * back — only the person consenting again — so the connection is recorded as withdrawn, the state
 * every screen already reads as Reconnect.
 */
export const INVALID_GRANT = "invalid_grant";

/**
 * A transaction, as the writes in this module hand one to each other.
 *
 * Named because two writes here are one decision — a secret in the vault, and the pointer that says
 * what it is for — and the only way to say that is to run both on the same executor. `select`,
 * `insert` and `update` alone would do for {@link CredentialExecutor}; this needs `execute` too, for
 * the advisory lock that serialises the client path.
 */
export type Transaction = Parameters<Parameters<Database["transaction"]>[0]>[0];

/**
 * THE ONLY SHAPE A MODEL TOOL NAME MAY TAKE, as the model API enforces it: `^[a-zA-Z0-9_-]+$`.
 *
 * Declared here beside {@link toolNameFor}, which is the function that has to satisfy it, and
 * applied in {@link storableTools}, which is the one door every transport's listing goes through and
 * which leaves out — and reports — any name that fails it. The prefix and separator this module
 * splices in are themselves made of these characters, so a `name` that passes is an offered name
 * that passes.
 */
export const OFFERABLE_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;

/**
 * A tool name the model can actually call.
 *
 * `<server>/<tool>` is how a grant is stored, because a slash reads correctly to a person and cannot
 * appear in either half. Model tool names may not contain one, so the offered name uses `__`.
 * Converting in one place, both ways, keeps the two spellings from drifting.
 */
export const toolNameFor = (ref: string) => `mcp__${ref.replace("/", "__")}`;

export function refFromToolName(toolName: string): string | null {
  if (!toolName.startsWith("mcp__")) return null;
  const rest = toolName.slice("mcp__".length);
  const separator = rest.indexOf("__");
  if (separator <= 0) return null;
  return `${rest.slice(0, separator)}/${rest.slice(separator + 2)}`;
}

/**
 * Advertised tool names this deployment's write list does not name, where that list is the whole
 * barrier.
 *
 * WHY THIS IS WORTH A ROW. {@link classifyTool} reads an advertised name absent from `writeTools` as
 * a READ. So under-inclusion is the failure mode of that list, and it is silent: a write the vendor
 * offers and the entry forgot is offered to a model as a read, and nothing anywhere says so. Notion's
 * entry says reconciling its list against the live tool list "is required, not cosmetic" — this is
 * the mechanical half of that, so the reconciliation is somebody reading a trail rather than somebody
 * remembering.
 *
 * Only where the list stands alone. A vendor that expresses SCOPES has something behind the list: a
 * tool missing from Drive's `writeTools` still cannot write, because `drive.readonly` refuses it at
 * the vendor. Naming those would be noise in front of the one case that has no second barrier at all
 * — Notion, whose access is per-page on a consent screen and whose `scopes` are therefore empty.
 *
 * A server with no catalogue entry is not reconciled either, and the two shapes that reach here do
 * so for different reasons. A brokered app's actions are classified from the vendor's own
 * per-action label rather than from a list here, so there is no hand-written under-inclusion to
 * find. A server an administrator added by URL has neither a label nor a list, so every tool it
 * offers is already a write and there is no wrongly-permitted read to reconcile.
 *
 * Sorted, so two readings of the same listing produce the same row.
 */
export function unlistedAdvertisedTools(
  entry: CatalogueEntry | null,
  advertised: readonly string[],
): string[] {
  if (!entry || entry.writeTools.length === 0) return [];
  if (entry.auth.kind !== "user-oauth" || entry.auth.scopes.length > 0) {
    return [];
  }
  const writes = new Set(entry.writeTools);
  return advertised.filter((name) => !writes.has(name)).sort();
}

export const iso = (value: Date | string | null): string | null =>
  value === null ? null : value instanceof Date ? value.toISOString() : value;

/**
 * The two things an actor field says when the actor is not a person, and they are not the same
 * thing.
 *
 * CRITERION. A field whose purpose is to name who did something must never be written as the empty
 * string. An absent field reads as absent; `""` reads as a value, so a reader grouping the trail by
 * actor gets a person called nothing, and every count of "acts by X" is quietly wrong about them.
 *
 * `deployment` is a positive answer: nobody was asking because the deployment itself acted — a
 * shared credential, a public endpoint, a refresh it ran on its own behalf immediately after an app
 * was added. `unattributed` is the opposite, and the distinction is the whole point of having two:
 * something happened that SHOULD have had a person behind it and this deployment could not say who.
 * `identifyActor` answers `{ id: "" }` for exactly that, and the run is then refused — which is
 * precisely the moment the trail is worth reading, so it must not be the moment it goes blank.
 *
 * Neither is an address, so neither can collide with a user id: every actor written here otherwise
 * is `users.id` or the email a session resolved to.
 *
 * NOT THE SAME AXIS AS `initiator_kind`, and a row carrying both is not contradicting itself.
 * `initiator_kind` answers what set a run in motion; this field answers whose account it reached
 * and who can be named for it. So `initiator_kind: "person"` beside `actor: "unattributed"` reads
 * correctly as a person-initiated request whose person this deployment could not identify. That is
 * the honest reading, and it is the reason this is NOT recorded as `deployment`: that would assert
 * the call went out on the deployment's own credential, and it did not go out at all.
 *
 * `DEPLOYMENT_INITIATOR`'s own doc claims the case of "refusing a caller it could not identify",
 * which overlaps this one and would answer it the other way. Nothing sends it there — the tool path
 * defaults its initiator to person and `identifyActor` returns an empty id rather than a deployment
 * — so the overlap is in the prose, not in the behaviour. It is left alone deliberately rather than
 * resolved by widening either vocabulary unilaterally; whoever owns that constant should narrow its
 * sentence, or a third initiator kind should exist, and neither is this branch's call to make.
 */
export const DEPLOYMENT_ACTOR = "deployment";
export const UNATTRIBUTED_ACTOR = "unattributed";

/**
 * Whose account this call went out as, for the trail.
 *
 * Reads the resolved descriptor rather than re-deriving from the entry's auth kind. That derivation
 * had no answer for a Composio app — the entry is null, so it fell through to `deployment` for a call
 * that ran in one person's own mailbox, which is the trail being wrong about the one thing a
 * per-person connector exists for.
 *
 * A person-reached server with no actor is `unattributed` and never `deployment`: the call did not
 * go out on a shared credential, it did not go out at all, and naming the deployment would assert
 * an attribution that never happened. See {@link DEPLOYMENT_ACTOR}.
 */
export const reachedAsFor = (access: ServerAccess, actorId: string): string =>
  access.reachedAs === "person"
    ? actorId || UNATTRIBUTED_ACTOR
    : DEPLOYMENT_ACTOR;

/**
 * Where this server actually is, when the stored row and the catalogue disagree.
 *
 * `mcp_servers.url` is written once, when a server is added, by copying what the catalogue said at
 * the time. That makes it a cache of a reviewed decision — and a cache nothing invalidates. Moving
 * Google Drive from its preview MCP host to its GA REST host changed the catalogue and left every
 * deployment that had already added Drive calling the old address, with no way to tell from any
 * screen: the row looks exactly as intentional as it did the day it was written.
 *
 * So for an entry with a PINNED host, the catalogue wins. It is the reviewed source contract, and a
 * host it no longer names is a host this deployment has decided not to talk to. Editing the
 * catalogue is the act of changing where a first-party server is, and it should take effect.
 *
 * The stored value still wins for the two cases where it is the only truth: a custom server an
 * administrator added by URL, which has no entry at all, and a per-instance vendor whose `host` is
 * null because the customer's own hostname is the answer.
 */
export function effectiveUrl(
  row: { id: string; url: string },
  entry: CatalogueEntry | null,
): string {
  if (!entry || entry.host === null) return row.url;
  return resolveServerUrl(row.id)?.url ?? row.url;
}

/**
 * Trade a refresh token for a short-lived access token, at the vendor's own token endpoint.
 *
 * `tokenUrl` comes from the catalogue entry and never from a caller, for the same reason the MCP
 * host does not: this request carries the deployment's client secret and somebody's refresh token,
 * so where it goes is a reviewed decision rather than a runtime one.
 *
 * The vendor's error body is deliberately not passed through — it is written for whoever registered
 * the client, not for the person who asked a Bot a question, and it can name the client id. Its
 * `error` CODE is, though, and only that: `invalid_client` is what tells a client the vendor has
 * forgotten apart from a grant somebody withdrew, and those two have entirely different answers.
 * It goes out as a field on {@link TokenRefusedError} as well as in the sentence, because the field
 * is the copy the recovery reads.
 *
 * Exported for its own tests rather than for a caller. Every path through the store reaches it as
 * the default `exchangeRefreshToken`, and the store's own suites inject a stub in its place — which
 * leaves what this function does with a REAL vendor reply, honest or garbled, untested unless it can
 * be called directly.
 */
export async function exchangeRefreshTokenOverHttp(input: {
  tokenUrl: string;
  client: OAuthClient;
  refreshToken: string;
}): Promise<AccessToken> {
  const params = new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: input.refreshToken,
    client_id: input.client.clientId,
  });
  // A public (DCR) client proves itself without one, and some vendors refuse an unexpected empty
  // field outright. The same guard the authorization-code redemption in `oauth.ts` uses.
  if (input.client.clientSecret) {
    params.set("client_secret", input.client.clientSecret);
  }

  const response = await fetch(input.tokenUrl, {
    method: "POST",
    headers: { "content-type": "application/x-www-form-urlencoded" },
    body: params,
    /*
     * A redirect is a refusal, not a detour to be followed.
     *
     * `tokenUrl` is pinned in the catalogue because this request carries the deployment's client
     * secret and somebody's refresh token, and following a 302 would hand both to whatever address
     * the answer named. Manual leaves the 3xx as the response, which is not `ok`, so it falls into
     * the refusal below. The same guard the authorization-code redemption in `oauth.ts` uses.
     */
    redirect: "manual",
    signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
  });

  if (!response.ok) {
    /*
     * The code, when the refusal is JSON and carries one. Read defensively: a token endpoint that
     * is refusing may be refusing with an HTML error page, and a parse failure here would replace
     * the vendor's status — the one fact we do have — with a syntax error.
     */
    const refusal = (await response.json().catch(() => null)) as {
      error?: unknown;
    } | null;
    /*
     * Capped where it is read, because everything downstream of here shows it to somebody: the
     * person who asked, the model, the connector's `lastError` on the admin page, and an audit
     * payload. It is a short token in the protocol and vendor-controlled in fact, and nothing on
     * those paths is a promise about length.
     */
    const code =
      typeof refusal?.error === "string" ? refusal.error.slice(0, 64) : null;
    throw new TokenRefusedError(
      `The vendor would not renew this access (${response.status}).${code ? ` (${code})` : ""}`,
      code,
    );
  }

  /*
   * A 200 is not a promise of JSON, and this branch used to read it as one.
   *
   * The refusal above already parses defensively; the success branch did not, so a CDN interstitial
   * or a maintenance page answering 200 with HTML threw a SyntaxError from here — out through
   * `callTool`, which records the failure with the thrower's message, and the parser's message
   * quotes the body it choked on. So a vendor's HTML reached an audit payload and the person who
   * asked, as a crash rather than as the refusal every other unusable reply produces.
   */
  const body = (await response.json().catch(() => null)) as {
    access_token?: unknown;
    expires_in?: unknown;
    refresh_token?: unknown;
  } | null;
  if (!body) {
    throw new McpServerError(
      "The vendor answered this renewal with something other than a token.",
    );
  }
  if (typeof body.access_token !== "string" || !body.access_token) {
    throw new McpServerError("The vendor renewed this access with no token.");
  }
  return {
    accessToken: body.access_token,
    expiresInSeconds:
      typeof body.expires_in === "number" ? body.expires_in : undefined,
    /*
     * Only when the vendor sent one, and only a non-empty one.
     *
     * A rotating vendor replies with a new refresh token and invalidates the one it was shown; a
     * vendor that does not rotate sends none. Reading an absent or empty field as a rotation would
     * repoint a working connection at nothing.
     */
    refreshToken:
      typeof body.refresh_token === "string" && body.refresh_token
        ? body.refresh_token
        : undefined,
  };
}

/** How long a vendor's token endpoint gets. Shorter than a call: it is one round trip, or nothing. */
export const TOKEN_TIMEOUT_MS = 10_000;

/**
 * The deployment's OAuth client for one vendor, as it is held in the vault.
 *
 * Both halves live in the encrypted value rather than the id sitting in `metadata` and the secret
 * here. One read gets a usable client, which keeps {@link CredentialSecretReader} the only vault
 * interface this module needs. The id is also copied into `metadata` for the credentials page to
 * show — a deliberate duplication of something that is not a secret, so that a screen listing what
 * the deployment holds does not have to decrypt anything to name it.
 */
export type OAuthClient = { clientId: string; clientSecret: string };

/**
 * Whether a value read back out of the vault is a client this deployment can actually present.
 *
 * Guarding the parse is only half of the question. `JSON.parse` answers for SYNTAX, and the
 * `as OAuthClient` cast behind it answers for nothing at all — so a row holding
 * `{"client_id":"","client_secret":""}`, which is what a hand-repair or a half-written row leaves,
 * parses cleanly and yields a client whose `clientId` is `undefined`.
 *
 * SHAPE AND SYNTAX ARE ONE CONCERN, which is why all three readers ask this beside their parse
 * rather than only around it: either way the deployment holds a client it cannot use, and the
 * operator's signal has to survive both. `unusableClient` is that signal, and it is deliberately
 * distinct from `noClient`'s holding none.
 *
 * The shape half earns the check by ending WORSE than the syntax half beside it. An `undefined`
 * client id is sent to the vendor, the vendor answers `invalid_client`, and
 * {@link refuseAndReplaceEvictedClient} reads that as the vendor having disowned our registration —
 * so a corrupt LOCAL row replaces the deployment-wide client every existing consent was granted
 * against, and reports it as the vendor's doing rather than naming the credential that broke.
 *
 * The id has to be there; the secret only has to be a string. A public client registered
 * dynamically proves itself with PKCE and is stored with an empty secret ON PURPOSE —
 * `registerDynamicClient` checks the id exactly this way and defaults the secret to `""` — so
 * demanding a non-empty secret here would refuse every self-registering entry in the catalogue.
 */
export function isUsableClient(value: unknown): value is OAuthClient {
  if (typeof value !== "object" || value === null) return false;
  const { clientId, clientSecret } = value as Partial<OAuthClient>;
  return (
    typeof clientId === "string" &&
    clientId !== "" &&
    typeof clientSecret === "string"
  );
}

/**
 * The client and when the vault row holding it was written.
 *
 * The date is not about the client: it is how long ago this deployment last introduced itself, which
 * is the one thing that distinguishes a client the vendor has evicted from one a re-registration
 * minted moments ago. Null only for a row that has since disappeared, which the read refuses first.
 */
export type StoredClient = { client: OAuthClient; registeredAt: Date | null };

/**
 * How long a freshly stored OAuth client is left alone after `invalid_client`.
 *
 * Re-registering once per refusal is right for one call and wrong for a deployment: a vendor that is
 * simply down answers every exchange `invalid_client`, and every tool call anywhere then mints a
 * client of its own, because each of them is the first refusal IT has seen. A client younger than
 * this was already the product of a re-registration, so registering again inside the window is
 * amplification rather than recovery — the honest answer is the vendor's refusal, unedited.
 */
export const CLIENT_REREGISTRATION_BACKOFF_MS = 5 * 60_000;

/**
 * The names that read as "tell me who this key belongs to".
 *
 * A PREFERENCE AND NOT THE RULE. What makes an action safe to probe with is decided by
 * {@link createPluginStore}'s `probeActionFor` on the vendor's own labels; this is only which of the
 * safe ones to reach for first. An identity call is the cheapest request an app has and the one
 * whose failure most clearly means "this key is wrong" rather than "that record does not exist" —
 * but sampling fifteen key-based apps in the live catalogue, only four publish one, so a chooser
 * that INSISTED on this shape would refuse to probe most of the apps this deployment offers.
 *
 * Anchored at the end, because these are suffixes of a prefixed action name — `STRIPE_GET_ME`,
 * `LINEAR_GET_ME` — and an unanchored match would take `SLACK_PROFILE_SET` for an identity read.
 */
export const IDENTITY_ACTION =
  /(_GET_ME|_PROFILE|_CURRENT_USER|_USER_INFO|_WHOAMI)$/;

/**
 * Every broker's id namespace, reserved together. See {@link BROKERED_PROFILE} in `./access` for
 * what a profile holds and why it lives there; this is only the list this file reserves off it.
 */
export const BROKERED_ID_PREFIXES = Object.values(BROKERED_PROFILE);

/**
 * Every broker's screen name, reserved together, for the reason {@link BROKERED_ID_PREFIXES} is.
 *
 * THE KEYS, NOT A SECOND LITERAL LIST. `/admin/plugins/composio` is the app directory's own page and
 * `/admin/plugins/arcade` is the Arcade one, and a static route is matched ahead of
 * `/admin/plugins/$key` on both — so a server sitting at either id would be listed and then open
 * somebody else's page instead of its own. Spelled as its own list, this reservation would be the
 * one somebody adds a broker to {@link BROKERED_PROFILE} without adding to.
 */
export const BROKERED_SCREEN_NAMES = Object.entries(BROKERED_PROFILE);

/** What a vendor's token endpoint gave back for a refresh token. */
export type AccessToken = {
  accessToken: string;
  expiresInSeconds?: number;
  /**
   * The refresh token to present next time, from a vendor that rotates.
   *
   * Absent from Google's replies and present in every one of Notion's. When it is here it is the
   * only one that still works — the token just spent is dead at the vendor — so it has to be
   * persisted before the access token beside it is used for anything.
   */
  refreshToken?: string;
};

export type PluginStoreOptions = {
  approvalGate?: ApprovalGate;
  /**
   * The owner's permission before a connector call sends content to other people.
   * See plugins/share-target.ts and proactive/private-share.ts. Absent asks nothing.
   */
  privateShareCheck?: CheckPrivateShare;
  /** Who may steer a run that uses a Shared app's account. Absent, every shared call is refused. */
  sharedUse?: SharedUseGate;
  database: Database;
  auditStore: AuditStore;
  /**
   * The vault, read and write.
   *
   * Writing is here rather than left to the browser posting `/api/admin/credentials` first. An OAuth
   * client belongs to the server registration and a refresh token belongs to a connection, so both
   * are written by the code that owns those acts — otherwise the first of two calls can succeed and
   * the second fail, leaving a secret in the vault that nothing points at and nobody knows to revoke.
   *
   * `revoke` is part of it because a key holds at most one live credential now. `removeServer`
   * retires the server's token, and the two write paths here replace rather than add, so re-adding a
   * server or re-authorizing a connection does not meet its own leftover on
   * `credentials_active_key_idx`.
   */
  credentials: CredentialSecretReader & CredentialStore;
  encryptionKey: string;
  /** Read at call time, never captured, so a policy changed a moment ago applies to this call. */
  policy: () => ActionPolicy;
  /**
   * Speaking MCP to the vendor. Defaults to the real client.
   *
   * Injected so a test can assert what a call was about to go out with. Whose credential is chosen
   * is the security property of this module, and asserting it otherwise needs a vendor to be
   * reachable, which means the property most worth testing would be the one thing never tested.
   */
  callVendor?: (
    connection: {
      url: string;
      token?: string;
      actorId?: string;
      botId?: string;
    },
    toolName: string,
    args: Record<string, unknown>,
    /** `accountGone` as `McpCallResult` carries it: the vendor lost the account this call ran in. */
  ) => Promise<{ text: string; isError: boolean; accountGone?: true }>;
  /** Trading a refresh token for a short-lived access token. Defaults to a real HTTP exchange. */
  exchangeRefreshToken?: (input: {
    tokenUrl: string;
    client: OAuthClient;
    refreshToken: string;
  }) => Promise<AccessToken>;
  /** RFC 7591 self-registration, for entries whose clientRegistration is dynamic. */
  registerClient?: (input: {
    registrationUrl: string;
    redirectUri: string;
  }) => Promise<OAuthClient | null>;
  /**
   * Composio the broker, absent on a deployment that has not configured one.
   *
   * OPTIONAL BECAUSE ITS ABSENCE IS A STATE RATHER THAN A MISCONFIGURATION. An unset
   * `COMPOSIO_API_KEY` is the documented default: where it is unset there is nothing to connect,
   * nothing to grant and no brokered tool for a Bot to call, and what is left on screen is one row
   * that goes nowhere under More apps on the admin Plugins page. So the store is constructible
   * without one and every path that needs one says so by raising {@link BrokerUnconfiguredError}.
   * A required field would make every caller that never enables an app — the routes, the tests
   * above — invent a broker to get a store.
   */
  broker?: ComposioBroker;
  /**
   * Which broker this deployment runs, which is the slice of `brokered_connections` this store
   * reads and the word its connection writer stamps on every row it mints.
   *
   * THE ONE PLACE THE VENDOR IS NAMED. Every read of `brokered_connections` below and the insert in
   * {@link createPluginStore}'s `recordBrokeredConnection` used to spell `composio` for themselves —
   * eleven comparisons that were each correct while there was one broker and each silently wrong on
   * the day there were two. They now all read this. A deployment running Arcade whose store was
   * still filtering on `composio` would not fail: it would read an empty slice, write rows nobody
   * reads back, and leave the "the other provider holds rows" refusal permanently unfired while the
   * offboarding sweep swept the wrong table slice. That is the failure this field exists to make
   * impossible to reach by accident.
   *
   * REQUIRED, UNLIKE `broker` ABOVE, BECAUSE FORGETTING IT HAS NO SYMPTOM. An absent `broker` says
   * one true thing — this deployment has not configured one — and every path that needs it raises.
   * An absent provider would have had to be guessed, and the only guess available was `composio`:
   * an Arcade deployment built by forgetting this field would then read and write the COMPOSIO slice
   * of `brokered_connections`, hand its own rows back through a composio filter, and APPEAR TO WORK.
   * Spec D3's "the other provider holds rows" refusal would never fire, because nothing would ever
   * be filed under the other name, and the offboarding sweep would sweep a slice that is not this
   * deployment's. Nothing goes red. There is no error to raise later, so the compiler asks now.
   *
   * SO THERE IS NO DEFAULT ANYWHERE — not here, not in {@link createPluginStore}, not in a test
   * helper. A function that cannot reach the provider takes it as a parameter; a second answer to
   * "which provider" is a second thing that can be wrong while agreeing with nothing. `activeProvider`
   * in `./broker` decides it from configuration at the one deployment boundary that knows.
   */
  brokerProvider: BrokerProvider;
  /** Where the vendor sends people back; needed to (re)register a dynamic client. */
  redirectUri?: string;
  /**
   * What this deployment calls itself (`DEPLOYMENT_ID`, else the tenant package id). The prefix of
   * a shared account's vendor identity, read only when an app is switched to Shared.
   */
  deploymentId?: string;
};

/** One in-flight Arcade authorization attempt, as the table stores it. */
export type PendingAuthorization = typeof pendingAuthorizations.$inferSelect;

/**
 * WHY A BROKERED ACCOUNT'S ROW WENT, as the trail spells it, and a closed set rather than free
 * text for the reason {@link PluginStore.disconnectBrokered} gives: a reader asking the trail
 * WHICH of these happened can be answered only if it is the same word every time.
 *
 * ONE SET ACROSS EVERY WRITER OF `mcp.account_disconnected`, so that `clearEndedSiblings` — which
 * writes for all of them — takes the word rather than re-deciding it. Each writer still narrows
 * this to the words IT may use; nothing takes the whole union as its own input.
 */
export type BrokeredDisconnectReason =
  /** The person disconnected their own account. */
  | "self"
  /** The person was removed from the People screen; {@link PluginStore.retireConnectionsFor}. */
  | "person_removed"
  /** An administrator disconnected the deployment's account for a Shared app. */
  | "admin"
  /** The app was switched between Personal and Shared, retiring the old mode's accounts. */
  | "mode_switched"
  /** A consent's context moved on and the verifier withdrew the retired identity's app. */
  | "context_changed"
  /** The app itself was removed; {@link PluginStore.removeServer}. */
  | "mcp_server_removed";

/** One app's connection, as far as sibling-finding needs to know it. */
export type ConnectionFootprint = {
  /** The toolkit, spelled as the vendor spells it. Compared exactly, never case-folded. */
  app: string;
  /** The identity the connection is held under at the vendor. */
  vendorUserId: string;
  /**
   * The vendor's own AUTH PROVIDER the connection is held under (`google`), not the broker's name.
   *
   * NAMED `authProvider` AND NEVER `providerId`, because `provider` in this file means the BROKER —
   * `brokered_connections.provider` is read a few lines below this one — and that collision has
   * already been paid for once in an audit payload. See {@link ConnectedAppBroker.authProviderOf},
   * which is where this value comes from and which is likewise not the toolkit name.
   */
  authProvider: string;
};

/**
 * The apps that share `of`'s connection, which are the apps sharing BOTH its vendor identity AND
 * its AUTH PROVIDER. NEVER THE PROVIDER ALONE (spec D26).
 *
 * REASON. An Arcade connection is keyed `(user_id, provider_id)`, and this deployment holds MANY
 * vendor identities: each person's own, PLUS ONE RANDOM IDENTITY PER SHARED APP, minted by
 * `mintDeploymentVendorUserId`. So shared Gmail and shared Slack, both using Google, do NOT share
 * a connection: their `user_id`s differ. A computation keyed on `provider_id` alone would warn
 * about apps that WILL NOT BE TOUCHED, which trains people to dismiss the warning that matters.
 * Silently ending two connections when somebody asked to end one is the failure to avoid.
 *
 * The auth provider is compared case-insensitively, as the adapter's `connectionsFor` does; the app
 * name is not, because Arcade toolkit case is never normalised. The answer never contains `of`
 * itself, and is sorted so two callers see the same list. This function ACTS ON NOTHING.
 */
export function connectionSiblings(
  of: ConnectionFootprint,
  among: readonly ConnectionFootprint[],
): string[] {
  const provider = of.authProvider.toLowerCase();
  const found = new Set<string>();
  for (const other of among) {
    if (other.app === of.app) continue;
    if (other.vendorUserId !== of.vendorUserId) continue;
    if (other.authProvider.toLowerCase() !== provider) continue;
    found.add(other.app);
  }
  return [...found].sort();
}

/** Raw `execute` rows are snake_case and carry timestamps as whatever the driver decoded. */
export function pendingAuthorizationFromRow(
  row: Record<string, unknown>,
): PendingAuthorization {
  const when = (v: unknown) =>
    v === null || v === undefined ? null : new Date(v as string | Date);
  return {
    actorId: row.actor_id as string,
    serverId: row.server_id as string,
    action: row.action as string,
    holder: row.holder as PendingAuthorization["holder"],
    userId: (row.user_id as string | null) ?? null,
    vendorUserId: row.vendor_user_id as string,
    authId: (row.auth_id as string | null) ?? null,
    createdAt: when(row.created_at) as Date,
    completedAt: when(row.completed_at),
    outcome: (row.outcome as PendingAuthorization["outcome"]) ?? null,
  };
}

/**
 * The instant a caller names an authorization attempt by, as a `Date`, or a refusal naming the
 * field.
 *
 * THE DECLARED TYPE IS `Date` AND THE VALUE IS NOT ALWAYS ONE. `PendingAuthorization.createdAt` is
 * typed `Date` and is one while it stays in this process, but an attempt that has been through
 * JSON — serialised into a job, a cache or a cross-process hop and parsed back — carries an ISO
 * STRING under a `Date` annotation. Handed to drizzle, that string reaches
 * `PgTimestamp.mapToDriverValue`, which calls `.toISOString()` on it and raises
 * `TypeError: value.toISOString is not a function` from inside the driver: a failure that names
 * neither the field nor the caller. An ISO string names the same instant perfectly well, so it is
 * accepted; anything that names NO instant is refused HERE, where the message can say what was
 * wrong, rather than running as a query that silently matches nothing.
 */
function attemptInstant(createdAt: Date | string): Date {
  const instant =
    createdAt instanceof Date
      ? createdAt
      : typeof createdAt === "string"
        ? new Date(createdAt)
        : new Date(Number.NaN);
  if (Number.isNaN(instant.getTime())) {
    throw new Error(
      `An authorization attempt's created_at must be a Date or an ISO timestamp, not ${JSON.stringify(createdAt) ?? String(createdAt)}.`,
    );
  }
  return instant;
}

/**
 * The condition that names ONE actor's attempt by the `created_at` a caller holds.
 *
 * MATCHED AT MILLISECOND PRECISION ON BOTH SIDES, BECAUSE THE TWO SIDES DO NOT CARRY THE SAME ONE.
 * `created_at` is a `timestamptz`, which PostgreSQL keeps to the MICROSECOND, and the `Date` the
 * driver hands back carries MILLISECONDS. A row stored at `…13.407577` is read back as
 * `…13.407Z`, and an exact `=` against that `Date` matches NOTHING — so the mint writes no
 * `auth_id`, and per {@link pendingAuthorizations}, "an attempt holding null can never complete":
 * a silently dead attempt that waits out its fifteen minutes.
 *
 * {@link createPluginStore}'s `claimAuthorizationAttempt` writes `date_trunc('milliseconds', now())`
 * for exactly this reason, but THAT ONLY HOLDS FOR THE ONE WRITER THAT REMEMBERS. The column's
 * default is `now()` at full precision, which is what drizzle's inferred insert type invites any
 * other writer — a fixture, a backfill, a future route — to take. Truncating the COLUMN in the
 * comparison holds whatever wrote the row, which is why the invariant lives here rather than in
 * the schema: it needs no migration and no writer's cooperation.
 *
 * TRUNCATING CAN NEVER MATCH A DIFFERENT ROW: `actor_id` is the table's PRIMARY KEY, so there is at
 * most one attempt per actor and `created_at` is the staleness guard on that one row, never a
 * selector among several. It still refuses a value naming an OLDER attempt, which is what stops a
 * late discard from deleting the replacement that took the key.
 */
export function attemptNamed(actorId: string, createdAt: Date | string) {
  return and(
    eq(pendingAuthorizations.actorId, actorId),
    sql`date_trunc('milliseconds', ${pendingAuthorizations.createdAt}) = ${attemptInstant(createdAt).toISOString()}::timestamptz`,
  );
}

/**
 * The literal recorded on the row, which is the scheme a later call must keep using.
 *
 * TYPED AS {@link RecordedScheme} RATHER THAN `string`, so that what this writes and what
 * {@link schemeKind} recognises are held to one set by the compiler. A literal spelled here that
 * the reader does not know would be read as `unreadable` — a key app that connects nobody, or a
 * consent app no confirm can verify — and nothing but this annotation would say so.
 */
export function schemeFor(connection: BrokerConnection): RecordedScheme | null {
  switch (connection.kind) {
    case "consent":
      return "OAUTH2";
    case "self-registering":
      return "DCR_OAUTH";
    case "fields":
      return connection.authScheme;
    case "no-auth":
      return "NO_AUTH";
    case "unsupported":
      return null;
  }
}

/**
 * Optional arguments the model filled in with an empty string, removed.
 *
 * A model handed a schema with many optional fields tends to fill them all, and where it has no
 * value it writes "". Vendors reject that: an empty string is not a channel id, not a timestamp and
 * not a cursor, so the call fails with a validation error that reads to the person as the tool being
 * broken.
 *
 * Only optional fields, and only empty strings. A required field left empty is the model getting it
 * wrong, and the vendor should say so rather than have us hide it. Anything other than "" is a value
 * the model meant, including false and 0.
 */
export function withoutEmptyOptionals(
  args: Record<string, unknown>,
  schema: Record<string, unknown> | undefined,
): Record<string, unknown> {
  const required = new Set(
    Array.isArray(schema?.required) ? (schema.required as string[]) : [],
  );
  return Object.fromEntries(
    Object.entries(args).filter(
      ([key, value]) => required.has(key) || value !== "",
    ),
  );
}