Skip to content

The open-source app everyone uses to manage agents at work

13.6 KB
Raw Blame
import { and, eq, isNull } from "drizzle-orm";
import { z } from "zod";
import { agentApiKeyScopeSchema } from "@paperclipai/shared";
import { agentApiKeys, agents, authSessions, boardApiKeys, dotAgentBindings, heartbeatRuns, mcpOauthGrants, museAgentBindings, type caseHandoffs, type issues, type Db } from "@paperclipai/db";
import { forbidden } from "../errors.js";
import { resolveDeploymentMode } from "../config-file.js";
import { isCloudManagedInstance } from "./cloud-instance.js";
import { boardAuthService } from "./board-auth.js";
import { isCurrentCloudOwnerInstanceAdmin, isCurrentCloudTenantAuthority, loadCurrentCloudOwnerAuthority, type CurrentCloudOwnerAuthority } from "./cloud-tenant-authority.js";
import { withExternalAdmissionGuard, type ExternalAdmissionTransaction } from "../modules/external-agents/index.js";
import { parseNativeExecutionInput } from "../vendor/paperclip-runner/index.js";
import { authorizeExternalBotBinding } from "./external-bot-authority.js";
import { canActorReceiveCase } from "./case-access.js";
import type { AuthorizationActor } from "./authorization.js";

type Handoff = typeof caseHandoffs.$inferSelect;
type Issue = typeof issues.$inferSelect;

// Server-owned provenance, not a cached permission decision. Never serialize
// this column into case history, events, prompts, or other public responses.
const actorContextSchema = z.object({
  schema: z.literal("paperclip.case-handoff-actor.v1"),
  actorType: z.enum(["agent", "user"]),
  actorId: z.string().min(1),
  companyId: z.string().min(1),
  source: z.enum(["local_implicit", "session", "board_key", "agent_key", "agent_jwt", "mcp_oauth", "cloud_tenant", "cloud_control"]).nullable(),
  runId: z.string().min(1).nullable(),
  keyId: z.string().min(1).nullable(),
  sessionId: z.string().min(1).nullable(),
  keyScope: agentApiKeyScopeSchema,
  onBehalfOfUserId: z.string().min(1).nullable(),
  authorizingUserId: z.string().min(1).nullable(),
}).strict();

export function caseHandoffActorContext(actor: AuthorizationActor, companyId: string): Record<string, unknown> {
  return actorContextSchema.parse({
    schema: "paperclip.case-handoff-actor.v1",
    actorType: actor.type === "agent" ? "agent" : "user",
    actorId: actor.type === "agent" ? actor.agentId : actor.userId ?? "board",
    companyId, source: actor.source === "none" ? null : actor.source ?? null,
    runId: actor.runId ?? null, keyId: actor.keyId ?? null, sessionId: actor.sessionId ?? null,
    keyScope: actor.keyScope ?? { kind: "standard" },
    onBehalfOfUserId: actor.onBehalfOfUserId ?? null,
    authorizingUserId: actor.authorizingUserId ?? null,
  });
}

/** Resolve remote authority outside the task transaction, without trusting stored privileges. */
export async function loadCaseHandoffCloudAuthority(row: Handoff): Promise<CurrentCloudOwnerAuthority | null> {
  const context = actorContextSchema.safeParse(row.actorContext);
  if (row.actorType !== "user" || !context.success || context.data.actorType !== row.actorType ||
    context.data.actorId !== row.actorId || context.data.companyId !== row.companyId || context.data.source !== "cloud_tenant") return null;
  return loadCurrentCloudOwnerAuthority(row.actorId);
}

/** Restore identity only; the caller must run canonical authorization afresh. */
export async function restoreCaseHandoffActor(db: Db, row: Handoff, issue: Issue, sourceAuthorizer?: string, cloudAuthority?: CurrentCloudOwnerAuthority | null): Promise<AuthorizationActor> {
  const parsed = actorContextSchema.safeParse(row.actorContext);
  if (!parsed.success || parsed.data.actorType !== row.actorType || parsed.data.actorId !== row.actorId ||
    parsed.data.companyId !== row.companyId || !parsed.data.source) throw forbidden("Handoff original actor context is unavailable");
  const context = parsed.data;
  const source = context.source;
  if (!source) throw forbidden("Handoff original actor context is unavailable");
  if (row.actorType === "user") {
    if (source === "local_implicit") {
      if (isCloudManagedInstance() || resolveDeploymentMode() !== "local_trusted") throw forbidden("Handoff local board authority is unavailable");
      return { type: "board", userId: row.actorId, source: "local_implicit" };
    }
    if (!["session", "board_key", "mcp_oauth", "cloud_tenant"].includes(source)) throw forbidden("Handoff board authority is unavailable");
    if (source === "cloud_tenant") {
      if (!isCurrentCloudTenantAuthority(row.actorId, cloudAuthority)) throw forbidden("Current Cloud tenant authority is unavailable");
      if (cloudAuthority.role === "viewer") throw forbidden("Current Cloud tenant membership does not allow task assignment");
    }
    const access = await boardAuthService(db).resolveBoardAccess(row.actorId);
    if (!access.user) throw forbidden("Handoff original user is unavailable");
    if (source === "cloud_tenant" && !access.companyIds.includes(row.companyId)) throw forbidden("Handoff original user is not a current company member");
    if (source === "board_key") {
      if (!context.keyId) throw forbidden("Handoff board key context is unavailable");
      const [key] = await db.select().from(boardApiKeys).where(and(eq(boardApiKeys.id, context.keyId), eq(boardApiKeys.userId, row.actorId), isNull(boardApiKeys.revokedAt)));
      if (!key || (key.expiresAt && key.expiresAt.getTime() <= Date.now())) throw forbidden("Handoff board key was revoked or expired");
    }
    if (source === "session") {
      if (!context.sessionId) throw forbidden("Handoff board session context is unavailable");
      const [session] = await db.select().from(authSessions).where(and(eq(authSessions.id, context.sessionId), eq(authSessions.userId, row.actorId)));
      if (!session || session.expiresAt.getTime() <= Date.now()) throw forbidden("Handoff board session was revoked or expired");
    }
    // Cloud/MCP authority cannot be elevated by a local instance-admin row.
    const isInstanceAdmin = source === "cloud_tenant" ? await isCurrentCloudOwnerInstanceAdmin(db, row.actorId, cloudAuthority)
      : source !== "mcp_oauth" && access.isInstanceAdmin;
    if (source === "cloud_tenant" && !isCurrentCloudTenantAuthority(row.actorId, cloudAuthority)) throw forbidden("Current Cloud tenant authority is unavailable");
    return { type: "board", userId: row.actorId, source, companyIds: access.companyIds, isInstanceAdmin };
  }
  if (!["agent_key", "agent_jwt", "mcp_oauth"].includes(source)) throw forbidden("Handoff agent authority is unavailable");
  if ((source === "agent_jwt" && context.runId !== row.sourceRunId) ||
    (context.runId && context.runId !== sourceRunId(row, issue))) throw forbidden("Handoff actor execution identity changed");
  if (source === "agent_key" && !context.keyId) throw forbidden("Handoff agent key context is unavailable");
  if (context.keyId) {
    const [key] = await db.select().from(agentApiKeys).where(and(eq(agentApiKeys.id, context.keyId), eq(agentApiKeys.companyId, row.companyId),
      eq(agentApiKeys.agentId, row.actorId), isNull(agentApiKeys.revokedAt)));
    const currentScope = key && agentApiKeyScopeSchema.safeParse(key.scopeConfig ?? { kind: "standard" });
    // A changed scope needs a fresh intent; never silently widen a scoped key.
    if (!key || (key.responsibleUserId?.trim() || null) !== context.onBehalfOfUserId || !currentScope || !currentScope.success || JSON.stringify(currentScope.data) !== JSON.stringify(context.keyScope)) throw forbidden("Handoff agent key was revoked or its scope changed");
  }
  if (sourceAuthorizer && context.authorizingUserId && sourceAuthorizer !== context.authorizingUserId) throw forbidden("Handoff source authorizer changed");
  return { type: "agent", agentId: row.actorId, companyId: row.companyId, source,
    runId: context.runId, keyId: context.keyId, keyScope: context.keyScope,
    onBehalfOfUserId: context.onBehalfOfUserId, authorizingUserId: sourceAuthorizer ?? context.authorizingUserId };
}

function sourceRunId(row: Handoff, issue: Issue) {
  // A new task's origin retains its creator run without yielding the separate
  // intake/chat task. Later phases always use the actual outgoing task run.
  return row.sourceRunId ?? (row.destinationKind === "agent" && row.version === 1 && row.actorType === "agent" && issue.createdByAgentId === row.actorId ? issue.originRunId : null);
}

/** Call after the task lock, before case/handoff locks (the release writer locks run then handoff). */
export async function lockCaseHandoffAuthorityRun(db: Db, row: Handoff, issue: Issue) {
  const id = sourceRunId(row, issue);
  if (id) await db.select({ id: heartbeatRuns.id }).from(heartbeatRuns)
    .where(and(eq(heartbeatRuns.id, id), eq(heartbeatRuns.companyId, row.companyId))).for("share");
}

/** Recheck the persisted origin without requiring a live outgoing execution. */
export async function assertCaseHandoffSourceAuthority(db: Db, row: Handoff, issue: Issue): Promise<string | undefined> {
  let sourceAuthorizer: string | undefined;
  const id = sourceRunId(row, issue);
  const [run] = id ? await db.select().from(heartbeatRuns).where(and(eq(heartbeatRuns.id, id), eq(heartbeatRuns.companyId, row.companyId))) : [];
  if (id && (!run || (row.actorType === "agent" && run.agentId !== row.actorId) || (row.sourceRunId && run.agentId !== row.fromAgentId))) throw forbidden("Handoff source authority is unavailable");
  const raw = run?.runnerProfileJson?.nativeExecutionInput as Record<string, unknown> | undefined;
  const provider = raw?.provider as Record<string, unknown> | undefined;
  if (run && (["openai_dot_mcp", "grok_bot_mcp", "muse_external"].includes(run.driverKind ?? "") || ["openai_dot", "grok_bot", "muse"].includes(String(provider?.kind)))) {
    let execution: ReturnType<typeof parseNativeExecutionInput>;
    try { execution = parseNativeExecutionInput(raw); } catch { throw forbidden("Pinned handoff source authority is unavailable"); }
    if (execution.binding.companyId !== row.companyId || execution.binding.agentId !== run.agentId || execution.binding.runId !== run.id ||
      execution.binding.issueId !== (run.nativeIssueId ?? run.issueId ?? run.contextSnapshot?.issueId)) throw forbidden("Pinned handoff source identity changed");
    await withExternalAdmissionGuard(db as unknown as ExternalAdmissionTransaction, row.companyId, run.agentId, async () => {
      if (execution.schema === "paperclip.native-execution-input.v8") {
        const { museRunnerBroker } = await import("./muse-runner-broker.js");
        sourceAuthorizer = await museRunnerBroker(db).authorizingUserIdForBinding(execution.provider.binding);
      } else if (execution.schema === "paperclip.native-execution-input.v6") {
        const ref = execution.provider.binding;
        const [binding] = await db.select().from(dotAgentBindings).where(and(eq(dotAgentBindings.id, ref.bindingId), eq(dotAgentBindings.companyId, row.companyId),
          eq(dotAgentBindings.agentId, run.agentId), eq(dotAgentBindings.generation, ref.bindingGeneration), isNull(dotAgentBindings.revokedAt)));
        const [grant] = binding?.grantId ? await db.select().from(mcpOauthGrants).where(and(eq(mcpOauthGrants.id, binding.grantId), isNull(mcpOauthGrants.revokedAt))) : [];
        if (!binding || !grant) throw forbidden("Handoff source connection was revoked");
        const current = await authorizeExternalBotBinding(db, { grant, actor: { type: "agent", agentId: binding.agentId, companyId: binding.companyId },
          company: { id: binding.companyId, name: "", issuePrefix: "", status: "active" } }, { provider: execution.provider.kind });
        if (current.id !== binding.id || current.generation !== ref.bindingGeneration) throw forbidden("Handoff source connection was replaced");
      } else throw forbidden("Pinned external handoff authority is unavailable");
    });
  }
  return sourceAuthorizer;
}

/** Recheck persistent connection authority after source execution has settled. */
export async function assertCaseHandoffDispatchAuthority(db: Db, row: Handoff, issue: Issue, caseRow: { id: string; companyId: string }) {
  if (row.destinationKind !== "agent" || !row.toAgentId) throw forbidden("Agent handoff requires a recipient");
  const sourceAuthorizer = await assertCaseHandoffSourceAuthority(db, row, issue);
  let recipientAuthorizer: string | undefined;
  const [recipient] = await db.select({ config: agents.adapterConfig }).from(agents).where(and(eq(agents.id, row.toAgentId), eq(agents.companyId, row.companyId)));
  if (recipient?.config.provider === "muse") {
    const bindingId = recipient.config.museBindingId;
    if (typeof bindingId !== "string") throw forbidden("Recipient external authorizer is unavailable");
    const [binding] = await db.select().from(museAgentBindings).where(and(eq(museAgentBindings.id, bindingId), eq(museAgentBindings.companyId, row.companyId),
      eq(museAgentBindings.agentId, row.toAgentId), isNull(museAgentBindings.revokedAt)));
    if (!binding) throw forbidden("Recipient external authorizer is unavailable");
    const { museRunnerBroker } = await import("./muse-runner-broker.js");
    recipientAuthorizer = await museRunnerBroker(db).authorizingUserIdForBinding({ companyId: row.companyId, agentId: row.toAgentId, bindingId, bindingGeneration: binding.generation }, { allowPaused: true });
  }
  const authorizers = [...new Set([sourceAuthorizer, recipientAuthorizer].filter((value): value is string => !!value))];
  for (const authorizer of authorizers.length ? authorizers : [undefined]) {
    const actor: AuthorizationActor = { type: "agent", agentId: row.toAgentId, companyId: row.companyId,
      onBehalfOfUserId: row.responsibleUserId, authorizingUserId: authorizer };
    if (!(await canActorReceiveCase(db, actor, caseRow, issue.id, row.toAgentId))) throw forbidden("Recipient or authorizer cannot access the case");
  }
  return sourceAuthorizer;
}