@opengeni/api-router 0.30.1 → 2.1.0-canary.0

package/src/routes/environments.ts

@@ -5,8 +5,6 @@ import {
   VariableSetVariableName,
 } from "@opengeni/contracts";
 import {
-  countActiveSessionsUsingVariableSet,
-  countScheduledTasksUsingVariableSet,
   countVariableSets,
   createVariableSet,
   decryptVariableSetValue,
@@ -18,10 +16,16 @@ import {
   readVariableSetSecretAtomically,
   setVariableSetVariable,
   updateVariableSet,
+  VariableSetAttachedError,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant, requireLiteralPermission, requirePermission } from "@opengeni/core";
+import {
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  requireLiteralPermission,
+  requirePermission,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   assertAllowedVariableSetVariableName,
@@ -45,15 +49,35 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
       const grant = await requireAccessGrant(c, deps, workspaceId);
       requirePermission(grant, "variable-sets:list");
       requirePermission(grant, "secrets:list");
-      return c.json(await listVariableSets(db, workspaceId));
+      return c.json(
+        await listVariableSets(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+        }),
+      );
     });
 
     app.post(`${prefix}`, async (c) => {
       const workspaceId = c.req.param("workspaceId")!;
-      const grant = await requireAccessGrant(c, deps, workspaceId);
+      const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+      const grant = authorization.grant;
       requirePermission(grant, "variable-sets:write");
       const key = requireVariableSetEncryption(settings);
       const payload = CreateVariableSetRequest.parse(await c.req.json());
+      if (prefix.endsWith("/environments") && payload.scope !== "workspace") {
+        throw new HTTPException(422, {
+          message: "the legacy environments route only creates workspace-scoped variable sets",
+        });
+      }
+      if (
+        payload.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") !== true
+      ) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
+        });
+      }
       if (payload.variables.length > 0) {
         requirePermission(grant, "secrets:write");
       }
@@ -73,12 +97,17 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
         }
         variableNames.add(variable.name);
       }
-      if ((await countVariableSets(db, workspaceId)) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
+      const access = {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+      };
+      if ((await countVariableSets(db, access, payload.scope)) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
         throw new HTTPException(422, {
           message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
         });
       }
-      if (await getVariableSetByName(db, workspaceId, name)) {
+      if (await getVariableSetByName(db, access, name, payload.scope)) {
         throw new HTTPException(409, {
           message: `variable set name is already in use: ${name}`,
         });
@@ -88,6 +117,9 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
       const created = await createVariableSet(db, {
         accountId: grant.accountId,
         workspaceId,
+        scope: payload.scope,
+        subjectId: grant.subjectId,
+        allowOrganization: payload.scope === "organization",
         name,
         description: payload.description ?? null,
         variables: payload.variables.map((variable) => ({
@@ -108,7 +140,7 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
       const grant = await requireAccessGrant(c, deps, workspaceId);
       requirePermission(grant, "variable-sets:read");
       requirePermission(grant, "secrets:list");
-      return c.json(await requireVariableSetForApi(db, workspaceId, c.req.param("variableSetId")!));
+      return c.json(await requireVariableSetForApi(db, grant, c.req.param("variableSetId")!));
     });
 
     if (prefix.endsWith("/variable-sets")) {
@@ -139,27 +171,47 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
 
     app.patch(`${prefix}/:variableSetId`, async (c) => {
       const workspaceId = c.req.param("workspaceId")!;
-      const grant = await requireAccessGrant(c, deps, workspaceId);
+      const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+      const grant = authorization.grant;
       requirePermission(grant, "variable-sets:write");
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")!,
-      );
+      const variableSet = await requireVariableSetForApi(db, grant, c.req.param("variableSetId")!);
+      const allowOrganization =
+        variableSet.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") === true;
+      if (variableSet.scope === "organization" && !allowOrganization) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
+        });
+      }
       const payload = UpdateVariableSetRequest.parse(await c.req.json());
       const name = payload.name !== undefined ? trimmedVariableSetName(payload.name) : undefined;
       if (name !== undefined && name !== variableSet.name) {
-        const existing = await getVariableSetByName(db, workspaceId, name);
+        const existing = await getVariableSetByName(
+          db,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+          },
+          name,
+          variableSet.scope,
+        );
         if (existing && existing.id !== variableSet.id) {
           throw new HTTPException(409, {
             message: `variable set name is already in use: ${name}`,
           });
         }
       }
-      const updated = await updateVariableSet(db, workspaceId, variableSet.id, {
-        ...(name !== undefined ? { name } : {}),
-        ...(payload.description !== undefined ? { description: payload.description } : {}),
-      });
+      const updated = await updateVariableSet(
+        db,
+        { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+        variableSet.id,
+        {
+          ...(name !== undefined ? { name } : {}),
+          ...(payload.description !== undefined ? { description: payload.description } : {}),
+          allowOrganization,
+        },
+      );
       await recordVariableSetAuditEvent(db, {
         grant,
         action: "variable_set.updated",
@@ -170,35 +222,36 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
 
     app.delete(`${prefix}/:variableSetId`, async (c) => {
       const workspaceId = c.req.param("workspaceId")!;
-      const grant = await requireAccessGrant(c, deps, workspaceId);
+      const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+      const grant = authorization.grant;
       requirePermission(grant, "variable-sets:write");
       requirePermission(grant, "secrets:write");
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")!,
-      );
-      const attachedTasks = await countScheduledTasksUsingVariableSet(
-        db,
-        workspaceId,
-        variableSet.id,
-      );
-      if (attachedTasks > 0) {
-        throw new HTTPException(409, {
-          message: `variable set is attached to ${attachedTasks} scheduled task(s); detach first`,
+      const variableSet = await requireVariableSetForApi(db, grant, c.req.param("variableSetId")!);
+      const allowOrganization =
+        variableSet.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") === true;
+      if (variableSet.scope === "organization" && !allowOrganization) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
         });
       }
-      const activeSessions = await countActiveSessionsUsingVariableSet(
-        db,
-        workspaceId,
-        variableSet.id,
-      );
-      if (activeSessions > 0) {
-        throw new HTTPException(409, {
-          message: `variable set is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first`,
-        });
+      try {
+        await deleteVariableSet(
+          db,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+          },
+          variableSet.id,
+          { allowOrganization },
+        );
+      } catch (error) {
+        if (error instanceof VariableSetAttachedError) {
+          throw new HTTPException(409, { message: error.message });
+        }
+        throw error;
       }
-      await deleteVariableSet(db, workspaceId, variableSet.id);
       await recordVariableSetAuditEvent(db, {
         grant,
         action: "variable_set.deleted",
@@ -209,16 +262,21 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
 
     app.put(`${prefix}/:variableSetId/variables/:name`, async (c) => {
       const workspaceId = c.req.param("workspaceId")!;
-      const grant = await requireAccessGrant(c, deps, workspaceId);
+      const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+      const grant = authorization.grant;
       requirePermission(grant, "variable-sets:write");
       requirePermission(grant, "secrets:write");
       const key = requireVariableSetEncryption(settings);
       const name = parseVariableName(c.req.param("name")!);
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")!,
-      );
+      const variableSet = await requireVariableSetForApi(db, grant, c.req.param("variableSetId")!);
+      const allowOrganization =
+        variableSet.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") === true;
+      if (variableSet.scope === "organization" && !allowOrganization) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
+        });
+      }
       const payload = SetVariableSetVariableRequest.parse(await c.req.json());
       const exists = variableSet.variables.some((variable) => variable.name === name);
       if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
@@ -229,9 +287,11 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
       const metadata = await setVariableSetVariable(db, {
         accountId: grant.accountId,
         workspaceId,
+        subjectId: grant.subjectId,
         variableSetId: variableSet.id,
         name,
         valueEncrypted: encryptVariableSetValue(key, payload.value),
+        allowOrganization,
       });
       await recordVariableSetAuditEvent(db, {
         grant,
@@ -244,16 +304,28 @@ export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
 
     app.delete(`${prefix}/:variableSetId/variables/:name`, async (c) => {
       const workspaceId = c.req.param("workspaceId")!;
-      const grant = await requireAccessGrant(c, deps, workspaceId);
+      const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+      const grant = authorization.grant;
       requirePermission(grant, "variable-sets:write");
       requirePermission(grant, "secrets:write");
       const name = parseVariableName(c.req.param("name")!);
-      const variableSet = await requireVariableSetForApi(
-        db,
+      const variableSet = await requireVariableSetForApi(db, grant, c.req.param("variableSetId")!);
+      const allowOrganization =
+        variableSet.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") === true;
+      if (variableSet.scope === "organization" && !allowOrganization) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
+        });
+      }
+      const deleted = await deleteVariableSetVariable(db, {
+        accountId: grant.accountId,
         workspaceId,
-        c.req.param("variableSetId")!,
-      );
-      const deleted = await deleteVariableSetVariable(db, workspaceId, variableSet.id, name);
+        subjectId: grant.subjectId,
+        variableSetId: variableSet.id,
+        name,
+        allowOrganization,
+      });
       if (!deleted) {
         throw new HTTPException(404, {
           message: "variable set variable not found",

package/src/routes/files.ts

@@ -23,10 +23,12 @@ import {
   createFileUpload,
   getFileUpload,
   getGeneratedImageArtifact,
+  recordAuditEvent,
   getGeneratedVideoArtifact,
+  getFilesForSubject,
   getRetainedFileArtifact,
   getRetainedScreenshotArtifact,
-  requireFile,
+  requireFileForSubject,
   type RetainedFileArtifact,
   type GeneratedImageArtifact,
   type GeneratedVideoArtifact,
@@ -34,9 +36,14 @@ import {
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant } from "@opengeni/core";
+import {
+  requireAccessGrant,
+  requireLiveAgentAttemptAuthorization,
+  SessionAuthorizationDeniedError,
+} from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { buildFilesMcpServer } from "../mcp/files";
 
@@ -95,6 +102,23 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       objectKey,
       expiresAt: signed.expiresAt,
     });
+    // Every principal-facing signed URL issuance is a
+    // metadata-only audit fact. Awaited before the URL leaves the platform:
+    // no recorded fact, no bearer capability. Never the URL or object key.
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_upload.issued",
+      targetType: "workspace_file",
+      targetId: fileId,
+      metadata: {
+        fileId,
+        contentType: payload.contentType,
+        sizeBytes: payload.sizeBytes,
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       CreateFileUploadResponse.parse({
         fileId: upload.file.id,
@@ -226,11 +250,13 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       const file = await rejectAndCleanObject(409, "file upload has expired", "expired");
       return c.json(CompleteFileUploadResponse.parse({ file }));
     }
-    const head = await objectStorage.headFile(upload.file).catch((error) => {
-      throw new HTTPException(409, {
-        message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}`,
-      });
+    const head = await retryWhileMissing(async () => {
+      if (!(await objectStorage.fileExists(upload.file))) return null;
+      return await objectStorage.headFile(upload.file);
     });
+    if (!head) {
+      throw new HTTPException(409, { message: "uploaded object is not available" });
+    }
     if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
       const file = await rejectAndCleanObject(
         422,
@@ -265,8 +291,13 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
-    const file = await requireFile(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await requireFileForSubject(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      fileId: c.req.param("fileId"),
+    }).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }
@@ -275,9 +306,14 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getWorkspaceArtifact(db, workspaceId, artifactId);
+    const artifact = await getWorkspaceArtifact(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: await fileAuthoritySubjectIdForGrant(deps, grant),
+      artifactId,
+    });
     if (!artifact) {
       return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
@@ -286,9 +322,14 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getWorkspaceArtifact(db, workspaceId, artifactId);
+    const artifact = await getWorkspaceArtifact(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: await fileAuthoritySubjectIdForGrant(deps, grant),
+      artifactId,
+    });
     if (!artifact) {
       return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
@@ -304,7 +345,7 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.post("/v1/workspaces/:workspaceId/artifacts/:artifactId/playback-source", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     if (!objectStorage) {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
@@ -317,10 +358,26 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(409, { message: `generated video is ${retained.file.status}` });
     }
     const file = generatedVideoFileAsset(retained.file);
-    if (!(await objectStorage.fileExists(file))) {
+    const videoPresent = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!videoPresent) {
       throw new HTTPException(410, { message: "generated video bytes are unavailable" });
     }
     const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_url.issued",
+      targetType: "retained_artifact",
+      targetId: artifactId,
+      metadata: {
+        artifactId,
+        kind: "video_playback",
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       VideoArtifactPlaybackSource.parse({
         schemaVersion: 1,
@@ -378,20 +435,44 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     if (!objectStorage) {
       throw new HTTPException(503, {
         message: "object storage is not configured",
       });
     }
-    const file = await requireFile(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    const file = await requireFileForSubject(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      fileId: c.req.param("fileId"),
+    }).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }
     if (file.status !== "ready") {
       throw new HTTPException(409, { message: `file is ${file.status}` });
     }
+    const present = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!present) {
+      throw new HTTPException(410, { message: "file bytes are unavailable" });
+    }
     const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_url.issued",
+      targetType: "workspace_file",
+      targetId: file.id,
+      metadata: {
+        fileId: file.id,
+        kind: "download",
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       FileDownloadUrlResponse.parse({
         url: signed.url,
@@ -455,16 +536,21 @@ async function serveRetainedArtifactContent(
     ...(range.contentRange ? { "Content-Range": range.contentRange } : {}),
   };
   if (range.kind === "empty") {
-    if (!(await objectStorage.fileExists(file))) {
+    const present = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!present) {
       return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
     }
     return c.body(null, 200, headers);
   }
 
-  const bytes = await objectStorage.getFileRange(file, {
-    start: range.start,
-    end: range.end,
-  });
+  const bytes = await retryWhileMissing(async () =>
+    objectStorage.getFileRange(file, {
+      start: range.start,
+      end: range.end,
+    }),
+  );
   if (!bytes) {
     return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
   }
@@ -537,14 +623,18 @@ function retainedArtifactMetadata(artifact: RetainedFileArtifact): RetainedArtif
 
 async function getWorkspaceArtifact(
   db: ApiRouteDeps["db"],
-  workspaceId: string,
-  artifactId: string,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string | null;
+    artifactId: string;
+  },
 ): Promise<{ file: RetainedFileArtifact["file"]; metadata: RetainedArtifactMetadata } | null> {
-  const generated = await getGeneratedImageArtifact(db, workspaceId, artifactId);
+  const generated = await getGeneratedImageArtifact(db, input.workspaceId, input.artifactId);
   if (generated) {
     return { file: generated.file, metadata: retainedGeneratedImageMetadata(generated) };
   }
-  const generatedVideo = await getGeneratedVideoArtifact(db, workspaceId, artifactId);
+  const generatedVideo = await getGeneratedVideoArtifact(db, input.workspaceId, input.artifactId);
   if (generatedVideo && !generatedVideo.artifact.deletedAt) {
     const file = generatedVideoFileAsset(generatedVideo.file);
     return {
@@ -555,8 +645,43 @@ async function getWorkspaceArtifact(
       }),
     };
   }
-  const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
-  return artifact ? { file: artifact.file, metadata: retainedArtifactMetadata(artifact) } : null;
+  const artifact = await getRetainedFileArtifact(db, input.workspaceId, input.artifactId);
+  if (!artifact) return null;
+  const [authorizedFile] = await getFilesForSubject(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    fileIds: [artifact.file.id],
+  });
+  if (!authorizedFile) return null;
+  const authorizedArtifact = { ...artifact, file: authorizedFile };
+  return {
+    file: authorizedFile,
+    metadata: retainedArtifactMetadata(authorizedArtifact),
+  };
+}
+
+/** Human and stable service grants already carry their immutable subject.
+ * Agent tokens carry only a technical worker subject, so resolve the exact
+ * live attempt and use the initiating human frozen on its durable turn. */
+export async function fileAuthoritySubjectIdForGrant(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: import("@opengeni/contracts").AccessGrant,
+): Promise<string | null> {
+  if (grant.principalKind !== "agent_attempt") return grant.subjectId;
+  const sessionId = grant.metadata?.["sessionId"];
+  if (typeof sessionId !== "string") {
+    throw new HTTPException(404, { message: "file not found" });
+  }
+  try {
+    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return actor.initiatingHumanSubjectId;
+  } catch (error) {
+    if (error instanceof SessionAuthorizationDeniedError) {
+      throw new HTTPException(404, { message: "file not found", cause: error });
+    }
+    throw error;
+  }
 }
 
 function generatedVideoFileAsset(