@opengeni/core 3.0.1 → 3.1.2

package/src/domain/scheduled-task-account-audit.ts

@@ -0,0 +1,90 @@
+import type { AccessGrant, ScheduledTaskAgentConfig } from "@opengeni/contracts";
+import { recordAuditEvent, type Database } from "@opengeni/db";
+import { isDeepStrictEqual } from "node:util";
+
+/** The audit action written whenever a schedule's account or connector choices change. */
+export const SCHEDULED_TASK_ACCOUNT_CHOICES_AUDIT_ACTION = "scheduled_task.account_choices_changed";
+
+type Choices = {
+  pinnedAccounts: { serverId: string; connectionId: string }[];
+  pinnedAccountsRequired: boolean;
+  connectors: {
+    followsWorkspaceDefaults: boolean;
+    excludedMcpServerIds: string[];
+    tools: string[];
+  };
+};
+
+function choicesOf(config: ScheduledTaskAgentConfig | null): Choices {
+  return {
+    pinnedAccounts: [...(config?.pinnedAccounts ?? [])]
+      .map(({ serverId, connectionId }) => ({ serverId, connectionId }))
+      .sort((a, b) =>
+        a.serverId === b.serverId
+          ? a.connectionId.localeCompare(b.connectionId)
+          : a.serverId.localeCompare(b.serverId),
+      ),
+    pinnedAccountsRequired: config?.pinnedAccountsRequired === true,
+    connectors: {
+      followsWorkspaceDefaults: config?.toolPolicy !== undefined,
+      excludedMcpServerIds: [...(config?.toolPolicy?.excludedMcpServerIds ?? [])].sort(),
+      tools: (config?.tools ?? [])
+        .filter((tool) => tool.kind === "mcp")
+        .map((tool) => tool.id)
+        .sort(),
+    },
+  };
+}
+
+/**
+ * What changed in a schedule's account and connector choices, as audit
+ * metadata: each changed choice with its value before and after. Only the
+ * choices are recorded (server and connection ids), never a credential or an
+ * account label. Returns null when nothing changed; a new schedule without
+ * any choice records nothing.
+ */
+export function scheduledTaskAccountChoiceChanges(
+  before: ScheduledTaskAgentConfig | null,
+  after: ScheduledTaskAgentConfig,
+): Record<string, { before: unknown; after: unknown }> | null {
+  const prior = choicesOf(before);
+  const next = choicesOf(after);
+  const changes: Record<string, { before: unknown; after: unknown }> = {};
+  for (const key of ["pinnedAccounts", "pinnedAccountsRequired", "connectors"] as const) {
+    if (!isDeepStrictEqual(prior[key], next[key]))
+      changes[key] = { before: prior[key], after: next[key] };
+  }
+  return Object.keys(changes).length > 0 ? changes : null;
+}
+
+/**
+ * Record a change to a schedule's account or connector choices in the same
+ * transaction as the change, with who made it and through which kind of
+ * caller (a person, an agent, an API key or a service).
+ */
+export async function recordScheduledTaskAccountChoiceChanges(
+  tx: Database,
+  input: {
+    grant: AccessGrant;
+    taskId: string;
+    operation: "create" | "update";
+    before: ScheduledTaskAgentConfig | null;
+    after: ScheduledTaskAgentConfig;
+  },
+): Promise<void> {
+  const changes = scheduledTaskAccountChoiceChanges(input.before, input.after);
+  if (!changes) return;
+  await recordAuditEvent(tx, {
+    accountId: input.grant.accountId,
+    workspaceId: input.grant.workspaceId,
+    subjectId: input.grant.subjectId,
+    action: SCHEDULED_TASK_ACCOUNT_CHOICES_AUDIT_ACTION,
+    targetType: "scheduled_task",
+    targetId: input.taskId,
+    metadata: {
+      operation: input.operation,
+      principalKind: input.grant.principalKind ?? null,
+      changes,
+    },
+  });
+}

package/src/domain/scheduled-task-audience.ts

@@ -0,0 +1,249 @@
+import type {
+  AccessGrant,
+  PrivateScheduledTaskSummary,
+  ScheduledTask,
+  SessionVisibility,
+} from "@opengeni/contracts";
+import {
+  getPrivateSessionCreatePolicy,
+  getScheduledTask,
+  getVisibleSessionTenancyVisibility,
+  listPrivateScheduledTaskSummaries,
+  pausePrivateScheduledTask,
+  scheduledTaskViewerSubject,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { hasPermission } from "../access";
+import { assertNotSiteClampedAgent } from "../site-agent-clamp";
+import {
+  privacyDeploymentLimits,
+  resolveOrganizationPrivacy,
+  type PrivacySettings,
+} from "../application/organization-privacy";
+import { creationInitiatorForGrant } from "./sessions";
+
+/**
+ * Who is reading schedules: the person (or the person an agent acts for),
+ * whether they administer the workspace, and whether, as an admin, they see
+ * that other people's Only me schedules exist. The organization can turn that
+ * last part off; a deployment can require it.
+ */
+export type ScheduledTaskViewer = {
+  subjectId: string | null;
+  admin: boolean;
+  seesPrivateSummaries: boolean;
+};
+
+/**
+ * `full`: everything. `summary`: an admin's view of someone else's Only me
+ * schedule (owner, cadence, cost) and pause. `none`: indistinguishable from a
+ * schedule that does not exist.
+ */
+export type ScheduledTaskAccess = "full" | "summary" | "none";
+
+export async function scheduledTaskViewerForGrant(
+  db: Database,
+  grant: AccessGrant,
+  settings: PrivacySettings,
+): Promise<ScheduledTaskViewer> {
+  const { subjectId } = await scheduledTaskFullViewerForGrant(db, grant);
+  const admin = hasPermission(grant.permissions, "workspace:admin", grant.permissionMode);
+  return {
+    subjectId,
+    admin,
+    seesPrivateSummaries:
+      admin &&
+      (await resolveOrganizationPrivacy({ db, settings }, grant.accountId))
+        .adminsSeePrivateSchedules,
+  };
+}
+
+/**
+ * The viewer for a check that only asks "may they see it in full?". Summary
+ * access never matters there, so it needs no organization setting.
+ */
+async function scheduledTaskFullViewerForGrant(
+  db: Database,
+  grant: AccessGrant,
+): Promise<ScheduledTaskViewer> {
+  const creator = creationInitiatorForGrant(grant);
+  const subjectId = await scheduledTaskViewerSubject(db, {
+    workspaceId: grant.workspaceId,
+    ...(creator.initiator ? { createdBy: creator.initiator } : {}),
+    ...(creator.context ? { createdByContext: creator.context } : {}),
+    createdByActor: creator.actor ?? null,
+  });
+  return { subjectId, admin: false, seesPrivateSummaries: false };
+}
+
+export function scheduledTaskAccess(
+  viewer: ScheduledTaskViewer,
+  task: Pick<ScheduledTask, "visibility" | "ownerSubjectId">,
+): ScheduledTaskAccess {
+  if (task.visibility !== "private") return "full";
+  if (viewer.subjectId !== null && task.ownerSubjectId === viewer.subjectId) return "full";
+  return viewer.seesPrivateSummaries ? "summary" : "none";
+}
+
+function scheduledTaskNotFound(): HTTPException {
+  return new HTTPException(404, { message: "scheduled task not found" });
+}
+
+/** A schedule this caller may see in full; anything else is a plain 404. */
+export async function requireVisibleScheduledTask(
+  db: Database,
+  grant: AccessGrant,
+  taskId: string,
+  viewer?: ScheduledTaskViewer,
+): Promise<ScheduledTask> {
+  const task = await getScheduledTask(db, grant.workspaceId, taskId);
+  if (!task) throw scheduledTaskNotFound();
+  const resolved = viewer ?? (await scheduledTaskFullViewerForGrant(db, grant));
+  if (scheduledTaskAccess(resolved, task) !== "full") throw scheduledTaskNotFound();
+  return task;
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** An admin's summary of someone else's Only me schedule, or null. */
+export async function privateScheduledTaskSummaryForAdmin(
+  db: Database,
+  grant: AccessGrant,
+  taskId: string,
+  viewer: ScheduledTaskViewer,
+): Promise<PrivateScheduledTaskSummary | null> {
+  if (!viewer.seesPrivateSummaries || !UUID_PATTERN.test(taskId)) return null;
+  const [summary] = await listPrivateScheduledTaskSummaries(db, {
+    workspaceId: grant.workspaceId,
+    excludeOwnerSubjectId: viewer.subjectId,
+    taskId,
+  });
+  return summary ?? null;
+}
+
+/**
+ * A schedule this caller may pause: one they see in full, or, for an admin,
+ * someone else's Only me schedule, which they only ever see as a summary. That
+ * schedule often posts into a chat the admin cannot see, so it is read through
+ * the summary and never loaded in full.
+ */
+export async function requirePausableScheduledTask(
+  db: Database,
+  grant: AccessGrant,
+  taskId: string,
+  viewer: ScheduledTaskViewer,
+): Promise<
+  | { access: "full"; task: ScheduledTask }
+  | { access: "summary"; summary: PrivateScheduledTaskSummary }
+> {
+  const resolved = viewer;
+  const task = await getScheduledTask(db, grant.workspaceId, taskId);
+  if (task && scheduledTaskAccess(resolved, task) === "full") return { access: "full", task };
+  const summary = await privateScheduledTaskSummaryForAdmin(db, grant, taskId, resolved);
+  if (!summary) throw scheduledTaskNotFound();
+  return { access: "summary", summary };
+}
+
+/**
+ * Pause someone else's Only me schedule as a workspace admin and return its
+ * refreshed summary. Only its owner can change, run or resume it.
+ */
+export async function pausePrivateScheduledTaskAsAdmin(
+  db: Database,
+  grant: AccessGrant,
+  taskId: string,
+  viewer: ScheduledTaskViewer,
+): Promise<PrivateScheduledTaskSummary> {
+  await assertNotSiteClampedAgent(db, grant, "schedules");
+  if (!viewer.seesPrivateSummaries) throw scheduledTaskNotFound();
+  const paused = await pausePrivateScheduledTask(db, {
+    workspaceId: grant.workspaceId,
+    taskId,
+    excludeOwnerSubjectId: viewer.subjectId,
+  });
+  const summary = paused
+    ? await privateScheduledTaskSummaryForAdmin(db, grant, taskId, viewer)
+    : null;
+  if (!summary) throw scheduledTaskNotFound();
+  return summary;
+}
+
+export const SCHEDULED_TASK_PRIVATE_TARGET_MESSAGE =
+  "This schedule posts into an Only me chat, so it is Only me too.";
+export const SCHEDULED_TASK_PRIVATE_OWNER_MESSAGE = "Only a person can have an Only me schedule.";
+export const SCHEDULED_TASK_PRIVATE_DISABLED_MESSAGE =
+  "Only me schedules are turned off for this organization.";
+
+/**
+ * Whether this person may start something new as Only me in this workspace: a
+ * chat, a schedule or a Site. In their Personal workspace, whenever the
+ * platform offers private sessions; elsewhere, when the organization allows
+ * Only me and the deployment does not turn it off.
+ */
+export async function mayStartOnlyMe(
+  db: Database,
+  settings: PrivacySettings,
+  workspaceId: string,
+  subjectId: string,
+): Promise<boolean> {
+  const policy = await getPrivateSessionCreatePolicy(db, {
+    workspaceId,
+    actorSubjectId: subjectId,
+  }).catch(() => null);
+  return policy
+    ? policy.personalWorkspace
+      ? policy.platformAvailable
+      : policy.organizationEnabled && privacyDeploymentLimits(settings).onlyMeAllowed
+    : false;
+}
+
+/**
+ * The audience to store for a created or edited schedule. A schedule that
+ * posts into an Only me chat, or writes to its owner's personal knowledge, is
+ * always Only me. Choosing Only me needs a human owner who may create Only me
+ * chats in this workspace.
+ */
+export async function resolveScheduledTaskVisibility(input: {
+  db: Database;
+  settings: PrivacySettings;
+  grant: AccessGrant;
+  requested: SessionVisibility | undefined;
+  current: Pick<ScheduledTask, "visibility"> | null;
+  targetSessionId: string | null;
+  personalKnowledge: boolean;
+  ownerSubjectId: string | null;
+}): Promise<"user_private" | "workspace_shared"> {
+  const targetPrivate =
+    input.targetSessionId !== null &&
+    (await getVisibleSessionTenancyVisibility(
+      input.db,
+      input.grant.workspaceId,
+      input.targetSessionId,
+    )) === "user_private";
+  const forced = targetPrivate || input.personalKnowledge;
+  if (forced && input.requested === "workspace")
+    throw new HTTPException(422, {
+      message: targetPrivate
+        ? SCHEDULED_TASK_PRIVATE_TARGET_MESSAGE
+        : "This schedule saves to your personal knowledge, so it is Only me.",
+    });
+  const wanted = forced ? "private" : (input.requested ?? input.current?.visibility ?? "workspace");
+  if (wanted === "workspace") return "workspace_shared";
+  if (!input.ownerSubjectId)
+    throw new HTTPException(422, { message: SCHEDULED_TASK_PRIVATE_OWNER_MESSAGE });
+  // Narrowing an existing Only me schedule never needs a fresh permission; a
+  // newly private one needs the organization to allow Only me.
+  if (input.current?.visibility !== "private" && !forced) {
+    if (
+      !(await mayStartOnlyMe(
+        input.db,
+        input.settings,
+        input.grant.workspaceId,
+        input.ownerSubjectId,
+      ))
+    )
+      throw new HTTPException(403, { message: SCHEDULED_TASK_PRIVATE_DISABLED_MESSAGE });
+  }
+  return "user_private";
+}