@open-everywhere/core 0.1.0

package/agent/access/credential-grant-broker.ts

@@ -0,0 +1,359 @@
+// The execute of every per-grant mounted tool. A granted tool mounts on the grant row's existence and refuses on its state, so a revoked grant's tool stays mounted and refuses, and mode, expiry and state are re-read on every call.
+
+import {
+  credentialGrantDisclosureLine,
+  credentialGrantRefusalMessage,
+  credentialGrantStateRefusal,
+  grantAuditResource,
+  GrantUndispatchedError,
+  quotedPurpose,
+  type CredentialGrantRefusal,
+  type CredentialGrantRow,
+} from "../operational/credential-grant-rows.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { connectorTransportSpec } from "../connections/connector-transport.js";
+import { isCredentialGrantConnector } from "./credential-grant.js";
+import { auditGrant, type GrantAuditStamps } from "./credential-grant-flow.js";
+import {
+  GrantBorrowTransportAlreadyRegisteredError,
+  grantBorrowTransport,
+  registerGrantBorrowTransport,
+} from "./grant-borrow-transport-registry.internal.js";
+import {
+  GrantRoomNoticeAlreadyRegisteredError,
+  grantRoomNotice,
+  registerGrantRoomNotice,
+} from "./grant-room-notice-registry.internal.js";
+import { grantOwnerSubject, type GrantOwnerSubject } from "./credential-grant-owner.js";
+import { grantScopeAdmits } from "./credential-grant-scope.js";
+import { currentJobWakePosture } from "./job-session-state.js";
+import { haltScopeFor, resolveHalt, resolveHaltUnaddressed, type HaltScope } from "./halt.js";
+import { surfaceKeyOf, tenantKeyOf } from "./resolver.js";
+
+/** One borrowed vendor MCP tool call. The model's input stays unmerged here: the transport merges the grant's frozen arguments over it, so the frozen half wins beside the fence that enforces the pin. */
+export interface GrantBorrowCall {
+  /** The vendor tool, in the vendor's exact bytes — `grant.mcpTool`, never the mounted name. */
+  readonly mcpTool: string;
+  /** What the MODEL supplied this call. Untrusted; every frozen key is overwritten downstream. */
+  readonly input: Readonly<Record<string, unknown>>;
+}
+
+/** A transport must not re-decide the boundary: every state, scope and requester check has run and the once-mode burn is spent before it is called. Only a GrantUndispatchedError asks for that burn back, and a transport must never reason about whether it is given. */
+export type GrantBorrowTransport = (call: GrantBorrowCall, grant: CredentialGrantRow, owner: GrantOwnerSubject) => Promise<unknown>;
+
+/** The registry lives off the published export map, and it refuses a second registration for one connector: the first transport stays in force and the second call throws. */
+export { GrantBorrowTransportAlreadyRegisteredError, grantBorrowTransport, registerGrantBorrowTransport };
+
+/** The port that puts the host-authored acting-as-owner line in the conversation, not only in the model's result. */
+export type GrantRoomNotice = (line: string, grant: CredentialGrantRow) => Promise<GrantRoomNoticeOutcome>;
+
+export type GrantRoomNoticeOutcome = { readonly posted: true } | { readonly posted: false; readonly reason: GrantRoomSilence };
+
+/** Why the room did not see the line: the call ran outside the mount's room-context wrap, the surface takes no mid-turn post, or the post was attempted and threw. */
+export type GrantRoomSilence = "no_room_context" | "no_post_arm" | "post_failed";
+
+/** The two silences the port produces rather than an arm: nothing is registered on the port, or the registered arm threw instead of reporting. */
+export type GrantRoomSilenceAtPort = "port_unarmed" | "arm_threw";
+
+/** The registry lives off the published export map, and the port refuses a second registration: core's shipped arm stays in force and the second call throws. */
+export { GrantRoomNoticeAlreadyRegisteredError, registerGrantRoomNotice };
+
+// Three refunds per grant row per turn, so a once-mode row can be spent four times in one turn and then stays spent. The count lives on the row beside the burn it bounds, and a call with no readable turn id never rolls it.
+const REFUND_CAP_PER_TURN = 3;
+
+export const GRANT_REFUND_CAP_PER_TURN = REFUND_CAP_PER_TURN;
+
+/** Everything the broker needs about the calling turn, resolved by the mount before it calls in. */
+export interface GrantCallContext extends GrantAuditStamps {
+  /** The CHAT this call is happening in — this eve session's own id. A `once` or `session` grant must
+   *  be bound to exactly this, or the call refuses. */
+  readonly scopeKey: string;
+  /**
+   * THE ROOM'S DOMAIN-SHAPED SEAT KEY (OPE-1950) — the second key a `standing` grant may be bound to,
+   * which is what lets one survive the rotation that retires {@link scopeKey}. Absent in a room whose
+   * domain does not window, and absent from every caller that resolves no room, which leaves the
+   * backstop on the exact-session rule alone.
+   *
+   * 🔴 IT WIDENS ONE MODE. `grantScopeAdmits` gates the domain arm on `mode === "standing"`, so a
+   * once- or session-mode row is unreachable through this key however it was spelled.
+   */
+  readonly domainScopeKey?: string;
+  /**
+   * The single verified human this turn, AS A PRINCIPAL KEY (OPE-1090) — the same grammar
+   * `grant.ownerPrincipalId` carries, so the `grant.used` row names both principals joinably in
+   * one row (design §8.1). The mount composes it through `identity/principal-key.ts`'s own
+   * composer; `undefined` when no single human is verified this turn.
+   */
+  readonly requesterPrincipalId: string | undefined;
+  /**
+   * The eve TURN this call runs in — `identity/binding.ts currentTurnId`, which the mount already
+   * reads for the requester verdict. It keys the per-turn refund cap and nothing else.
+   *
+   * `undefined` is not an error and never widens the cap: a claim with no turn id never rolls the
+   * row's count, so the allowance becomes per row for the row's whole life instead of per turn. The
+   * store statement owns that rule — see `OperationalStore.claimCredentialGrantRefund`.
+   */
+  readonly turnId?: string;
+  readonly nowMs: number;
+}
+
+/** The halt address comes from the audit stamps' room, never from ctx.scopeKey: that key is an eve session id, and reading it as an address silently dropped the domain, surface and workspace halt axes. */
+export function grantCallHaltScope(ctx: GrantCallContext): HaltScope {
+  const roomKey =
+    ctx.surface === undefined || ctx.surface === ""
+      ? tenantKeyOf({ platform: ctx.platform, workspace: ctx.workspace })
+      : surfaceKeyOf({ platform: ctx.platform, workspace: ctx.workspace, channel: ctx.surface });
+  return haltScopeFor({
+    org: ctx.org,
+    scopeKey: roomKey,
+    ...(ctx.requesterPrincipalId !== undefined ? { principalKey: ctx.requesterPrincipalId } : {}),
+  });
+}
+
+/** The placeholder the mount writes into every partition field when `resolvePartition` throws
+ *  (tools/grant_tools.ts). It is a literal there, so it is a literal here — matched, never guessed. */
+const UNRESOLVED_PARTITION = "unknown";
+
+/** True when the mount could not read the room, so the derived address is a placeholder. Such a call asks the unaddressed halt question instead, because a halt must have no gap an unreadable room opens. */
+export function grantCallRoomUnresolved(ctx: GrantCallContext): boolean {
+  return (
+    ctx.org === UNRESOLVED_PARTITION ||
+    ctx.platform === UNRESOLVED_PARTITION ||
+    ctx.workspace === UNRESOLVED_PARTITION ||
+    ctx.surface === undefined ||
+    ctx.surface === ""
+  );
+}
+
+export const HALT_UNRESOLVED_ROOM_NOTE =
+  "This deployment could not resolve which conversation this call is running in, so the halt was applied to be safe: a halt anywhere in this organisation stops a call whose room cannot be read.";
+
+/** What the model gets back. Both shapes carry the boundary in words. */
+export type GrantCallResult =
+  | { readonly ok: true; readonly disclosure: string; readonly result: unknown }
+  | { readonly ok: false; readonly refused: CredentialGrantRefusal; readonly message: string };
+
+/** The order is load-bearing: read the row fresh, refuse an unattended wake, then state, scope and requester, then resolve the transport and the owner, then burn before the vendor call and audit before it. Only a GrantUndispatchedError refunds the burn, capped per grant row per turn. */
+export async function runGrantedCall(grantId: string, input: Readonly<Record<string, unknown>>, ctx: GrantCallContext): Promise<GrantCallResult> {
+  const store = getOperationalStore();
+  const nowIso = new Date(ctx.nowMs).toISOString();
+  const grant = await store.getCredentialGrant(ctx.org, grantId);
+  if (grant === null) {
+    // Rows are never deleted, so a vanished row is treated as revoked rather than given a permissive branch. The placeholder shape only has to be honest.
+    const shape = { connector: "", mcpTool: undefined, ownerSlug: "the owner", resource: "", verb: "that tool" };
+    await auditGrant(ctx, "grant.refused", ctx.requesterPrincipalId, { gate: "revoked", grantId });
+    return { message: credentialGrantRefusalMessage(shape, "revoked"), ok: false, refused: "revoked" };
+  }
+  /** `note` appends one host-authored clause to the shared copy — for a refusal whose REASON needs a
+   *  word about how it was decided, never for a caller's free text. */
+  const refuse = async (reason: CredentialGrantRefusal, note?: string): Promise<GrantCallResult> => {
+    await auditGrant(ctx, "grant.refused", ctx.requesterPrincipalId, {
+      gate: reason,
+      grantId: grant.id,
+      owner: grant.ownerPrincipalId,
+      verb: grant.verb,
+    });
+    const message = credentialGrantRefusalMessage(grant, reason);
+    return { message: note === undefined ? message : `${message} ${note}`, ok: false, refused: reason };
+  };
+
+  // The grant plane's own execute backstop for an unattended wake; the primary control is the tool's absence at the model-call seam. It runs first because nobody-in-the-room is prior to the row's state, and the posture read fails soft.
+  if (currentJobWakePosture() === "restricted") return refuse("unattended_wake");
+
+  // The break-glass halt sits after the room question and before every question about the row: a halt is not a property of the grant, so the refusal must not read as an expiry. It fails closed on a room it cannot read.
+  const roomUnresolved = grantCallRoomUnresolved(ctx);
+  const haltState = roomUnresolved ? await resolveHaltUnaddressed(ctx.org) : await resolveHalt(grantCallHaltScope(ctx));
+  if (haltState.halted) {
+    return refuse("halted", roomUnresolved ? HALT_UNRESOLVED_ROOM_NOTE : undefined);
+  }
+
+  const stateRefusal = credentialGrantStateRefusal(grant, nowIso);
+  if (stateRefusal !== undefined) return refuse(stateRefusal);
+  // L0 as an EXECUTE BACKSTOP, not only as a mount rule. The resolver already mounts a grant's tool
+  // only where its scope admits it, but a replayed turn rebuilds the tool from persisted metadata, so
+  // the check has to hold at the call too.
+  // 🔴 THIS IS THE BACKSTOP'S OWN COPY OF THE RULE, NOT THE ONLY ONE. The mount and the own-account
+  // gate read `credential-grant-reach.ts` `credentialGrantsInReach`, whose half lives in SQL — see
+  // `grantScopeAdmits`'s own docblock for what differs and why. A change to what a seat may reach
+  // moves both.
+  if (!grantScopeAdmits(grant, ctx.scopeKey, ctx.domainScopeKey)) return refuse("out_of_scope");
+  if (ctx.requesterPrincipalId === undefined) return refuse("unverified_requester");
+
+  // A row that names no vendor tool is not a legal grant row. Only a row an older build persisted can reach here, and it refuses by name before the burn.
+  const mcpTool = grant.mcpTool;
+  if (mcpTool === undefined) return refuse("no_lent_tool");
+
+  // A grant row outlives the reviewed connector list that admitted it, so the list is re-read at dispatch. It runs before the transport lookup and the burn, so the refusal resolves, dials and spends nothing.
+  if (!isCredentialGrantConnector(grant.connector)) return refuse("connector_delisted");
+
+  const path = resolveBorrowPath(grant, mcpTool);
+  if (path === undefined) return refuse("no_transport");
+
+  // WHOSE ROW THIS CALL WILL SPEND, resolved BEFORE the burn for the same reason the transport is:
+  // a once-mode grant must not be spent by a call this deployment could never have sent. It is a
+  // REFUSAL and never a fallback — see credential-grant-owner.ts for why there is no weaker subject
+  // to try.
+  const owner = await grantOwnerSubject(ctx.org, grant.connector, grant.ownerPrincipalId);
+  if (owner === undefined) return refuse("owner_unresolvable");
+
+  // THE BURN, and the stamp that lets it be undone. `burnedAt` is non-undefined exactly when THIS
+  // call won the CAS on a once-mode row, and it is what `refundCredentialGrant` is keyed on — see
+  // step 7 below and the store's own contract.
+  let burnedAt: string | undefined;
+  if (grant.mode === "once") {
+    const burned = await store.burnCredentialGrant(ctx.org, grant.id, nowIso);
+    if (burned === null) return refuse("burned");
+    burnedAt = nowIso;
+  }
+
+  // AFTER THE BURN, deliberately: the audit digest describes a call this deployment has already
+  // committed to making.
+  const send = path.prepare(input);
+  const disclosure = credentialGrantDisclosureLine(grant, ctx.nowMs);
+  // ONE ROW, BOTH PRINCIPALS. The requester drove the act and the owner's credential paid for it,
+  // and that pair is the property this whole plane buys — so it is a single row rather than a join
+  // across two. IDS AND NAMES ONLY: the composed request is recorded as a coarse digest, never as
+  // the vendor request, and the output is never recorded at all.
+  await auditGrant(ctx, "grant.used", ctx.requesterPrincipalId, {
+    connector: grant.connector,
+    grantId: grant.id,
+    mode: grant.mode,
+    owner: grant.ownerPrincipalId,
+    purpose: quotedPurpose(grant.purpose),
+    requester: ctx.requesterPrincipalId,
+    // 🔴 NAMES, NEVER THE FROZEN VALUES. A borrow's `resource` column is a display label composed
+    // from the frozen ARGUMENTS, which are model-authored; the audit contract on this plane is ids
+    // and names only. See `grantAuditResource`.
+    resource: grantAuditResource(grant),
+    scopeDigest: send.scopeDigest,
+    // OPE-1950: TWO SCOPES, AND THEY ARE DIFFERENT QUESTIONS. `scopeKey` is what the GRANT is bound
+    // to — identical on every call of one row, and for a standing grant it is the room's domain key
+    // rather than a session id that no longer exists. `callerScopeKey` is the SESSION that made THIS
+    // call. Before the widening the two were always equal, so one field answered both; a standing
+    // grant is now spent by many sessions over 30 days, and an operator tracing a misuse needs the
+    // one that moves.
+    scopeKey: grant.scopeKey,
+    callerScopeKey: ctx.scopeKey,
+    tier: grant.tier,
+    verb: grant.verb,
+  });
+  // Only a GrantUndispatchedError refunds the burn; every other throw keeps it, because none can tell a delivered call from a lost one. A refund restores the owner's approval, not the vendor session, and the throw still reaches the model.
+  let result: unknown;
+  try {
+    result = await send.run(owner);
+  } catch (err) {
+    if (burnedAt !== undefined && err instanceof GrantUndispatchedError) {
+      // The claim runs before the refund, so a capped attempt writes no refund at all, and the claim is never revisited afterwards. A claim that throws refunds nothing and still writes its closing audit row: the row stays spent.
+      let claimed = false;
+      let unclaimable = false;
+      try {
+        claimed = await store.claimCredentialGrantRefund(ctx.org, grant.id, ctx.turnId, REFUND_CAP_PER_TURN);
+      } catch (claimErr) {
+        unclaimable = true;
+        console.log(`[open-everywhere:grant] grant ${grant.id}: the undispatched-call refund could not be CLAIMED, so the approval stays spent: ${String(claimErr)}`);
+      }
+      try {
+        const refunded = claimed ? await store.refundCredentialGrant(ctx.org, grant.id, burnedAt) : false;
+        // The closing row for a call that never went out; refunded false means the owner revoked while it was in flight. Three gate names, because they are three different jobs for a reader: undispatched, refund_capped (the allowance is spent) and refund_unclaimed (the store could not count).
+        await auditGrant(ctx, "grant.refused", ctx.requesterPrincipalId, {
+          connector: grant.connector,
+          gate: claimed ? "undispatched" : unclaimable ? "refund_unclaimed" : "refund_capped",
+          grantId: grant.id,
+          mode: grant.mode,
+          owner: grant.ownerPrincipalId,
+          refunded,
+          requester: ctx.requesterPrincipalId,
+          resource: grantAuditResource(grant),
+          verb: grant.verb,
+        });
+      } catch (refundErr) {
+        // The grant stays burned, which is the fail-closed direction, and the original refusal is
+        // what reaches the model. Logged rather than swallowed silently: an operator needs to know
+        // an owner's one-shot approval was spent on a call that never ran. Which half failed is
+        // named, because the two are different events — a refund that could not be written, and a
+        // turn that ran out of refunds and then could not write its own closing row. A claim that
+        // could not be counted logs above and still reaches this write.
+        console.log(
+          `[open-everywhere:grant] grant ${grant.id}: the undispatched-call ${claimed ? "refund" : "refund cap row"} could not be written: ${String(refundErr)}`,
+        );
+      }
+    }
+    throw err;
+  }
+  // The vendor call has already run, so a disclosure that never reached the room is audited rather than refused. Every silence gets a row, and the disclosure still reaches the model in the result.
+  const notice = grantRoomNotice();
+  if (notice === undefined) {
+    await auditUndisclosedCall(ctx, grant, "port_unarmed");
+  } else {
+    try {
+      const outcome = await notice(disclosure, grant);
+      if (!outcome.posted) await auditUndisclosedCall(ctx, grant, outcome.reason);
+    } catch (noticeErr) {
+      await auditUndisclosedCall(ctx, grant, "arm_threw", noticeErr);
+    }
+  }
+  return { disclosure, ok: true, result };
+}
+
+/** One granted call whose acting-as-owner line did not reach the room, the counterpart of grant.used. Ids, names and an Error name only, never the disclosure line, and a lost row never fails the call. */
+async function auditUndisclosedCall(
+  stamps: GrantAuditStamps,
+  grant: CredentialGrantRow,
+  gate: GrantRoomSilence | GrantRoomSilenceAtPort,
+  err?: unknown,
+): Promise<void> {
+  await auditGrant(stamps, "grant.undisclosed", grant.ownerPrincipalId, {
+    connector: grant.connector,
+    gate,
+    grantId: grant.id,
+    mode: grant.mode,
+    owner: grant.ownerPrincipalId,
+    requester: grant.requesterPrincipalId,
+    resource: grantAuditResource(grant),
+    verb: grant.verb,
+    ...(err === undefined ? {} : { error: err instanceof Error ? err.name : "unknown" }),
+  });
+}
+
+/** Resolving happens before the burn, because a once-mode grant must not be spent by a deployment that could never have sent the call; composing and digesting happen after it. */
+interface GrantSendPath {
+  prepare(input: Readonly<Record<string, unknown>>): GrantSend;
+}
+
+interface GrantSend {
+  readonly scopeDigest: string;
+  run(owner: GrantOwnerSubject): Promise<unknown>;
+}
+
+/** The row names the tool and freezes the arguments, so nothing is composed here. A missing connection spec or a missing borrow transport both mean this deployment cannot send, and the grant stays valid. */
+function resolveBorrowPath(grant: CredentialGrantRow, mcpTool: string): GrantSendPath | undefined {
+  const spec = connectorTransportSpec(grant.connector);
+  if (spec === undefined) return undefined;
+  const transport = grantBorrowTransport(grant.connector);
+  if (transport === undefined) return undefined;
+  return {
+    prepare: (input) => ({
+      run: async (owner) => await transport({ input, mcpTool }, grant, owner),
+      scopeDigest: borrowScopeDigest(spec.directUrl, mcpTool, input, grant.frozenArgs ?? {}),
+    }),
+  };
+}
+
+/** A coarse, non-reversible description of one borrowed call. Keys, never values: the digest shows that two calls had the same shape and cannot be used to reconstruct one. */
+export function borrowScopeDigest(
+  directUrl: string,
+  mcpTool: string,
+  input: Readonly<Record<string, unknown>>,
+  frozenArgs: Readonly<Record<string, unknown>>,
+): string {
+  let host = "unparseable";
+  try {
+    host = new URL(directUrl).host;
+  } catch {
+    /* keep "unparseable" — a connection with a bad URL is still worth an honest row */
+  }
+  const keys = [...new Set([...Object.keys(input), ...Object.keys(frozenArgs)])].sort().join(",");
+  // The vendor tool name is MODEL-AUTHORED at ask time, so it rides the same quoted-data discipline
+  // a model-authored purpose does before it lands in an audit row.
+  return `mcp ${host} tools/call ${quotedPurpose(mcpTool)} keys:${keys}`;
+}