@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/session-admin-access.ts

@@ -0,0 +1,271 @@
+import {
+  GrantSessionAdminAccessRequest,
+  OrganizationAgentAdminAccess,
+  SessionAdminAccess,
+  UpdateOrganizationAgentAdminAccessRequest,
+  type SessionAuthorizationOperation,
+} from "@opengeni/contracts";
+import {
+  requireAccessGrant,
+  requireSessionAuthorization,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  siteSessionClamp,
+  withResolvedSessionAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  getManagedUserProfilesByIds,
+  getOrganizationAgentAdminAccess,
+  getSessionAdminAccessView,
+  grantSessionAdminAccess,
+  nestedPostgresSqlState,
+  revokeSessionAdminAccess,
+  SessionAdminAccessNotAllowedError,
+  SessionAdminAccessNotOwnSessionError,
+  setOrganizationAgentAdminAccess,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+import {
+  isAgentActingAsPerson,
+  isAgentWithFullAccess,
+  requireFullAccessIfAgent,
+} from "../http/acting-person";
+import { requireOrganizationCodexHuman, requireSameOriginBrowserMutation } from "./codex";
+
+/* ----------------------------------------------------------------------------
+   Admin access for agent sessions.
+
+   An organization allows it (off by default). An owner or admin then gives
+   one of their own sessions admin access for an hour by default, a number of
+   hours they choose, or with no time limit: the agent there gets the
+   organization's actions and runs them as that person, with what they can
+   manage right now. It ends by itself when the time is up. Turning the
+   organization setting off ends every session's admin access. An agent with
+   the person's full access (such as one with admin access) can do all of
+   this as them; an agent with less can read the state and end access, never
+   start it.
+   -------------------------------------------------------------------------- */
+
+const OrganizationId = z.string().uuid();
+
+function parseOrganizationId(value: string | undefined): string {
+  const parsed = OrganizationId.safeParse(value);
+  if (!parsed.success) throw new HTTPException(404, { message: "organization not found" });
+  return parsed.data;
+}
+
+function administratorsOnly(error: unknown): never {
+  if (nestedPostgresSqlState(error) === "42501") {
+    throw new HTTPException(403, {
+      message: "Only organization owners and admins can manage admin access for sessions",
+    });
+  }
+  throw error;
+}
+
+async function authorizeSession(
+  c: Context,
+  deps: ApiRouteDeps,
+  operation: SessionAuthorizationOperation,
+) {
+  const workspaceId = c.req.param("workspaceId")!;
+  const sessionId = c.req.param("sessionId")!;
+  if (!z.string().uuid().safeParse(sessionId).success) {
+    throw new HTTPException(404, { message: "Session not found" });
+  }
+  const grant = await requireAccessGrant(
+    c,
+    deps,
+    workspaceId,
+    operation === "session.read" ? "sessions:read" : "sessions:control",
+  );
+  try {
+    const authorization = await requireSessionAuthorization(deps, grant, {
+      sessionId,
+      operation,
+      surface: "http",
+    });
+    return { grant, workspaceId, sessionId, authorization };
+  } catch (error) {
+    if (error instanceof SessionAuthorizationDeniedError) {
+      throw new HTTPException(404, { message: "Session not found" });
+    }
+    if (error instanceof SessionAuthorizationUnavailableError) {
+      throw new HTTPException(503, { message: "session authorization is unavailable" });
+    }
+    throw error;
+  }
+}
+
+async function personName(deps: ApiRouteDeps, subjectId: string): Promise<string | null> {
+  if (!subjectId.startsWith("user:")) return null;
+  const [profile] = await getManagedUserProfilesByIds(deps.db, [subjectId.slice("user:".length)]);
+  return profile?.name?.trim() || profile?.email || null;
+}
+
+export function registerSessionAdminAccessRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const organizationPath = "/v1/organizations/:organizationId/agent-admin-access";
+
+  app.get(organizationPath, async (c) => {
+    c.header("cache-control", "private, no-store");
+    const organizationId = parseOrganizationId(c.req.param("organizationId"));
+    await requireOrganizationCodexHuman(c, deps, organizationId);
+    return c.json(
+      OrganizationAgentAdminAccess.parse(
+        await getOrganizationAgentAdminAccess(deps.db, organizationId),
+      ),
+    );
+  });
+
+  app.patch(organizationPath, async (c) => {
+    requireFullAccessIfAgent(c, "Allowing admin access for sessions");
+    requireSameOriginBrowserMutation(c, deps);
+    const organizationId = parseOrganizationId(c.req.param("organizationId"));
+    const human = await requireOrganizationCodexHuman(c, deps, organizationId);
+    const parsed = UpdateOrganizationAgentAdminAccessRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) throw new HTTPException(422, { message: "invalid admin access setting" });
+    try {
+      return c.json(
+        OrganizationAgentAdminAccess.parse(
+          await setOrganizationAgentAdminAccess(deps.db, {
+            organizationId,
+            actorSubjectId: human.subjectId,
+            sessionAdminAccessAllowed: parsed.data.sessionAdminAccessAllowed,
+          }),
+        ),
+      );
+    } catch (error) {
+      administratorsOnly(error);
+    }
+  });
+
+  const sessionPath = "/v1/workspaces/:workspaceId/sessions/:sessionId/admin-access";
+
+  const view = async (
+    c: Context,
+    target: Awaited<ReturnType<typeof authorizeSession>>,
+  ): Promise<SessionAdminAccess> => {
+    const read = () =>
+      getSessionAdminAccessView(deps.db, {
+        accountId: target.grant.accountId,
+        workspaceId: target.workspaceId,
+        sessionId: target.sessionId,
+        viewerSubjectId: target.grant.subjectId,
+      });
+    const state = target.authorization
+      ? await withResolvedSessionAuthorization(target.authorization, read)
+      : await read();
+    const asThePerson =
+      (!isAgentActingAsPerson(c) || isAgentWithFullAccess(c)) &&
+      (target.grant.principalKind === undefined || target.grant.principalKind === "human_session");
+    const grantedBy = state.grant
+      ? {
+          subjectId: state.grant.grantedBySubjectId,
+          name: await personName(deps, state.grant.grantedBySubjectId),
+        }
+      : null;
+    return SessionAdminAccess.parse({
+      active: state.active,
+      grantedBy: state.active ? grantedBy : null,
+      grantedAt: state.active ? (state.grant?.grantedAt ?? null) : null,
+      expiresAt: state.active ? (state.grant?.expiresAt ?? null) : null,
+      allowed: state.allowed,
+      canGrant:
+        state.allowed && asThePerson && state.viewerIsAdministrator && state.viewerStartedSession,
+      canRevoke:
+        state.grant !== null &&
+        (state.grant.grantedBySubjectId === target.grant.subjectId || state.viewerIsAdministrator),
+    });
+  };
+
+  app.get(sessionPath, async (c) => {
+    c.header("cache-control", "private, no-store");
+    const target = await authorizeSession(c, deps, "session.read");
+    return c.json(await view(c, target));
+  });
+
+  app.put(sessionPath, async (c) => {
+    requireFullAccessIfAgent(c, "Giving a session admin access");
+    requireSameOriginBrowserMutation(c, deps);
+    const target = await authorizeSession(c, deps, "session.tool_policy.write");
+    const human = await requireOrganizationCodexHuman(c, deps, target.grant.accountId);
+    if (human.subjectId !== target.grant.subjectId) {
+      throw new HTTPException(403, { message: "Give admin access as yourself" });
+    }
+    // No body (older clients) means the default: one hour.
+    const raw = (await c.req.text().catch(() => "")).trim();
+    let input: unknown = null;
+    try {
+      input = raw ? JSON.parse(raw) : {};
+    } catch {
+      input = null;
+    }
+    const body = GrantSessionAdminAccessRequest.safeParse(input);
+    if (!body.success) {
+      throw new HTTPException(422, {
+        message:
+          "durationHours must be a whole number of hours from 1 to 720, or null for no time limit",
+      });
+    }
+    // A session a Site page started acts with that page's reach: admin
+    // access would let it act as the person across the organization.
+    const clamp = await siteSessionClamp(
+      deps.db,
+      { accountId: target.grant.accountId, workspaceId: target.workspaceId },
+      target.sessionId,
+      null,
+    );
+    if (clamp.clamped)
+      throw new HTTPException(409, {
+        message: "A session started from a Site page cannot get admin access",
+      });
+    const grant = () =>
+      grantSessionAdminAccess(deps.db, {
+        organizationId: target.grant.accountId,
+        workspaceId: target.workspaceId,
+        sessionId: target.sessionId,
+        actorSubjectId: human.subjectId,
+        durationHours: body.data.durationHours,
+      });
+    try {
+      if (target.authorization) await withResolvedSessionAuthorization(target.authorization, grant);
+      else await grant();
+    } catch (error) {
+      if (error instanceof SessionAdminAccessNotAllowedError) {
+        throw new HTTPException(409, { message: error.message });
+      }
+      if (error instanceof SessionAdminAccessNotOwnSessionError) {
+        throw new HTTPException(403, { message: error.message });
+      }
+      administratorsOnly(error);
+    }
+    return c.json(await view(c, target));
+  });
+
+  app.delete(sessionPath, async (c) => {
+    const target = await authorizeSession(c, deps, "session.tool_policy.write");
+    const current = await view(c, target);
+    if (current.canRevoke) {
+      const revoke = () =>
+        revokeSessionAdminAccess(deps.db, {
+          accountId: target.grant.accountId,
+          workspaceId: target.workspaceId,
+          sessionId: target.sessionId,
+        });
+      if (target.authorization)
+        await withResolvedSessionAuthorization(target.authorization, revoke);
+      else await revoke();
+    } else if (current.active) {
+      throw new HTTPException(403, {
+        message: "Only the person who gave admin access, or an owner or admin, can end it",
+      });
+    }
+    return c.json(await view(c, target));
+  });
+}

package/src/routes/session-artifact-associations.ts

@@ -0,0 +1,164 @@
+import {
+  fileOwnerContextForAccess,
+  requireAccessGrantAuthorization,
+  requirePermission,
+  requireSessionAuthorization,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  type ApiRouteDeps,
+  siteViewerForGrant,
+} from "@opengeni/core";
+import {
+  getGeneratedImageArtifact,
+  getGeneratedVideoArtifact,
+  getRetainedFileArtifact,
+  hasEditableArtifactSessionLink,
+  hasWorkspaceArtifactSessionLink,
+  listArtifactCatalogCandidates,
+  transactionallyAuthorizeEditableArtifactActor,
+  withRlsContext,
+  withSessionRlsActorContext,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
+import { editableArtifactActorForGrant } from "./editable-artifacts";
+
+const SessionId = z.string().uuid();
+const EditableArtifactId = z.string().regex(/^(?!0{32}$)[0-9a-f]{32}$/u);
+
+/** Exact authorized membership proof, not a paginated artifact discovery API. */
+export function registerSessionArtifactAssociationRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/artifact-associations/:artifactId",
+    async (context) => {
+      const workspaceId = context.req.param("workspaceId");
+      const sessionId = context.req.param("sessionId");
+      const artifactId = context.req.param("artifactId");
+      const requestedKind = context.req.query("kind");
+      // A UUID names a Site unless the caller asks for a retained artifact
+      // (generated image or video, or a published sandbox file) explicitly.
+      const kind = EditableArtifactId.safeParse(artifactId).success
+        ? "editable"
+        : SessionId.safeParse(artifactId).success
+          ? requestedKind === "retained"
+            ? "retained"
+            : "site"
+          : null;
+      const authorization = await requireAccessGrantAuthorization(
+        context,
+        deps,
+        workspaceId,
+        kind === "retained" ? "files:read" : "artifacts:read",
+      );
+      const grant = authorization.grant;
+      requirePermission(grant, "sessions:read");
+      if (
+        !SessionId.safeParse(sessionId).success ||
+        !kind ||
+        (requestedKind !== undefined && requestedKind !== kind)
+      ) {
+        throw new HTTPException(404, { message: "Artifact association not found" });
+      }
+      try {
+        return await withAccessGrantSessionRlsContext(deps, grant, async () => {
+          await requireSessionAuthorization(deps, grant, {
+            sessionId,
+            operation: "session.read",
+            surface: "http",
+          });
+          const scope = { accountId: grant.accountId, workspaceId };
+          const linked =
+            kind === "editable"
+              ? await hasEditableArtifactSessionLink(deps.db, scope, sessionId, artifactId)
+              : kind === "retained"
+                ? await hasRetainedArtifactSessionLink(
+                    deps,
+                    authorization,
+                    workspaceId,
+                    sessionId,
+                    artifactId.toLowerCase(),
+                  )
+                : await hasWorkspaceArtifactSessionLink(
+                    deps.db,
+                    workspaceId,
+                    await siteViewerForGrant(deps.db, grant),
+                    sessionId,
+                    artifactId,
+                  );
+          if (!linked) throw new HTTPException(404, { message: "Artifact association not found" });
+          if (kind === "editable") {
+            const decision = await withRlsContext(deps.db, scope, (tx) =>
+              transactionallyAuthorizeEditableArtifactActor(tx, {
+                scope,
+                artifactId,
+                actor: editableArtifactActorForGrant(grant, "0000000000000001"),
+                permission: "read",
+              }),
+            );
+            if (!decision.allowed) {
+              throw new HTTPException(404, { message: "Artifact association not found" });
+            }
+          }
+          context.header("cache-control", "private, no-store");
+          return context.json({ sessionId, artifactId, kind });
+        });
+      } catch (error) {
+        if (error instanceof SessionAuthorizationDeniedError) {
+          throw new HTTPException(404, { message: "Artifact association not found" });
+        }
+        if (error instanceof SessionAuthorizationUnavailableError) {
+          throw new HTTPException(503, { message: "Session authorization is unavailable" });
+        }
+        throw error;
+      }
+    },
+  );
+}
+
+/**
+ * Whether a retained artifact originated in this exact session: a generated
+ * image or video the session produced, or a sandbox file it published. Never
+ * inferred from an artifact id appearing in a message.
+ */
+async function hasRetainedArtifactSessionLink(
+  deps: ApiRouteDeps,
+  authorization: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>,
+  workspaceId: string,
+  sessionId: string,
+  artifactId: string,
+): Promise<boolean> {
+  const image = await getGeneratedImageArtifact(deps.db, workspaceId, artifactId);
+  if (image) return image.sessionId === sessionId;
+  const video = await getGeneratedVideoArtifact(deps.db, workspaceId, artifactId);
+  if (video) return !video.artifact.deletedAt && video.artifact.sessionId === sessionId;
+  const file = await getRetainedFileArtifact(deps.db, workspaceId, artifactId);
+  if (!file) return false;
+  // Publication receipts are private; the bounded catalog seam filters them
+  // by source session and this file's name, then the exact id must match.
+  const grant = authorization.grant;
+  const actor = await fileOwnerContextForAccess(deps, authorization, "files:read");
+  const candidates = await withSessionRlsActorContext(actor, () =>
+    listArtifactCatalogCandidates(
+      deps.db,
+      { accountId: grant.accountId, workspaceId },
+      {
+        query: {
+          sourceSessionId: sessionId,
+          q: file.file.filename.slice(0, 200),
+          sort: "newest",
+          status: "active",
+          limit: 100,
+        },
+        kinds: ["file", "image"],
+        siteViewer: { subjectId: null },
+        snapshotAt: new Date().toISOString(),
+        limit: 201,
+      },
+    ),
+  );
+  return candidates.some(
+    (candidate) => candidate.origin === "sandbox_file" && candidate.id === artifactId,
+  );
+}