@opengeni/api-router 0.14.4 → 0.15.1

package/src/mcp/server.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   CreateScheduledTaskRequest,
   DEFAULT_FIRST_PARTY_MCP_TOOLS,
@@ -24,6 +25,8 @@ import {
   type SessionAuthorizationSurface,
   type Session,
   UpdateScheduledTaskRequest,
+  normalizeWorkspaceArtifactSlug,
+  WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES,
 } from "@opengeni/contracts";
 import {
   correctWorkspaceMemory,
@@ -70,6 +73,12 @@ import {
   upsertSessionGoalWithEvent,
   RigChangeAlreadyVerifyingError,
   RigChangeTransitionError,
+  createWorkspaceArtifact,
+  getWorkspaceArtifact,
+  getWorkspaceArtifactContentRef,
+  listWorkspaceArtifacts,
+  publishWorkspaceArtifactVersion,
+  rollbackWorkspaceArtifact,
 } from "@opengeni/db";
 import { appendAndPublishEvents, publishDurableSessionEvents } from "@opengeni/events";
 import {
@@ -237,6 +246,11 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   slack_bot_file_content: { allOf: ["connections:read"] },
   slack_bot_post_message: { allOf: ["connections:read"] },
   slack_bot_delete_message: { allOf: ["connections:read"] },
+  artifacts_list: { sessionRequired: true, allOf: ["artifacts:read"] },
+  artifacts_get_source: { sessionRequired: true, allOf: ["artifacts:read"] },
+  artifacts_create: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  artifacts_publish: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  artifacts_rollback: { sessionRequired: true, allOf: ["artifacts:publish"] },
 } satisfies Record<FirstPartyMcpToolName, FirstPartyToolAuthorization>;
 
 const FIRST_PARTY_MCP_TOOL_NAME_SET = new Set<string>(FIRST_PARTY_MCP_TOOL_NAMES);
@@ -378,6 +392,9 @@ export function buildOpenGeniMcpServer(
   if (!toolspaceMode && sessionId !== null && preferenceAttemptClaims(grant) !== null) {
     registerPreferenceRegistryTools(server, deps, grant, json);
   }
+  if (!toolspaceMode && sessionId !== null && preferenceAttemptClaims(grant) !== null) {
+    registerWorkspaceArtifactTools(server, deps, grant, sessionId, json);
+  }
 
   // Fleet tools (M7 bring-your-own-compute): list / attach / swap / run_on /
   // provision over the session's Modal box + the workspace's enrolled machines.
@@ -1282,6 +1299,198 @@ async function authorizeFirstPartySession(
   });
 }
 
+function registerWorkspaceArtifactTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+  json: JsonResult,
+): void {
+  const attempt = () => {
+    const claims = preferenceAttemptClaims(grant);
+    if (!claims) throw new Error("Exact signed artifact attempt authority is required.");
+    return claims;
+  };
+  const authorize = async () => {
+    await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+  };
+  const prepare = (html: string) => {
+    if (!deps.objectStorage) throw new Error("Object storage is not configured");
+    const bytes = new TextEncoder().encode(html);
+    if (bytes.byteLength < 1 || bytes.byteLength > WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES) {
+      throw new Error(
+        `Artifact HTML must be 1-${WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES} UTF-8 bytes`,
+      );
+    }
+    const contentSha256 = createHash("sha256").update(bytes).digest("hex");
+    const contentKey = `workspaces/${grant.workspaceId}/workspace-artifacts/blobs/${contentSha256}.html`;
+    return {
+      contentKey,
+      contentSha256,
+      sizeBytes: bytes.byteLength,
+      persistContent: async () => {
+        await deps.objectStorage!.putObject({
+          key: contentKey,
+          contentType: "text/html; charset=utf-8",
+          body: bytes,
+          sha256: contentSha256,
+        });
+      },
+    };
+  };
+  const provenance = (
+    idempotencyKey: string,
+    sourceToolName: "artifacts_create" | "artifacts_publish" | "artifacts_rollback",
+  ) => {
+    const claims = attempt();
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      operationKey: `attempt:${createHash("sha256")
+        .update(
+          `${claims.sessionId}:${claims.turnId}:${claims.attemptId}:${claims.executionGeneration}:${idempotencyKey}`,
+        )
+        .digest("hex")}`,
+      actorSubjectId: grant.subjectId,
+      sourceSessionId: claims.sessionId,
+      sourceTurnId: claims.turnId,
+      sourceAttemptId: claims.attemptId,
+      sourceExecutionGeneration: claims.executionGeneration,
+      sourceToolName,
+    };
+  };
+
+  server.registerTool(
+    "artifacts_list",
+    {
+      description:
+        "List the generic published artifacts in this workspace and their current versions.",
+      inputSchema: {},
+    },
+    async () => {
+      await authorize();
+      return json(await listWorkspaceArtifacts(deps.db, grant.workspaceId));
+    },
+  );
+
+  server.registerTool(
+    "artifacts_get_source",
+    {
+      description:
+        "Read an artifact's metadata and exact HTML source. Omit versionId for the current version.",
+      inputSchema: {
+        artifactId: z4.string().uuid(),
+        versionId: z4.string().uuid().optional(),
+      },
+    },
+    async ({ artifactId, versionId }) => {
+      await authorize();
+      if (!deps.objectStorage) throw new Error("Object storage is not configured");
+      const [detail, ref] = await Promise.all([
+        getWorkspaceArtifact(deps.db, grant.workspaceId, artifactId),
+        getWorkspaceArtifactContentRef(deps.db, grant.workspaceId, artifactId, versionId),
+      ]);
+      const object = await deps.objectStorage.getObjectBytes(ref.contentKey);
+      if (!object) throw new Error("Artifact content is unavailable");
+      const actualHash = createHash("sha256").update(object.bytes).digest("hex");
+      if (actualHash !== ref.version.contentSha256)
+        throw new Error("Artifact content failed integrity verification");
+      return json({ detail, version: ref.version, html: new TextDecoder().decode(object.bytes) });
+    },
+  );
+
+  server.registerTool(
+    "artifacts_create",
+    {
+      description:
+        "Create and publish a generic static workspace artifact from a complete, self-contained HTML document with inline CSS. JavaScript and active or navigation-capable markup do not render in the MVP.",
+      inputSchema: {
+        title: z4.string().min(1).max(120),
+        description: z4.string().max(2000).nullable().optional(),
+        slug: z4
+          .string()
+          .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/)
+          .max(96)
+          .optional(),
+        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+        idempotencyKey: z4.string().min(1).max(200),
+      },
+    },
+    async ({ title, description, slug, html, idempotencyKey }) => {
+      await authorize();
+      const artifactId = crypto.randomUUID();
+      const slugBase = slug ?? (normalizeWorkspaceArtifactSlug(title) || "artifact");
+      const resolvedSlug = slug ?? `${slugBase.slice(0, 87)}-${artifactId.slice(0, 8)}`;
+      return json(
+        await createWorkspaceArtifact(deps.db, {
+          artifactId,
+          slug: resolvedSlug,
+          title,
+          description: description ?? null,
+          ...prepare(html),
+          ...provenance(idempotencyKey, "artifacts_create"),
+        }),
+      );
+    },
+  );
+
+  server.registerTool(
+    "artifacts_publish",
+    {
+      description:
+        "Publish a new immutable static HTML/CSS version. JavaScript and active or navigation-capable markup do not render in the MVP. First read the current source and pass its version id for optimistic concurrency.",
+      inputSchema: {
+        artifactId: z4.string().uuid(),
+        expectedCurrentVersionId: z4.string().uuid(),
+        title: z4.string().min(1).max(120).optional(),
+        description: z4.string().max(2000).nullable().optional(),
+        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+        idempotencyKey: z4.string().min(1).max(200),
+      },
+    },
+    async ({ artifactId, expectedCurrentVersionId, title, description, html, idempotencyKey }) => {
+      await authorize();
+      return json(
+        await publishWorkspaceArtifactVersion(deps.db, {
+          artifactId,
+          expectedCurrentVersionId,
+          ...(title !== undefined ? { title } : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...prepare(html),
+          ...provenance(idempotencyKey, "artifacts_publish"),
+        }),
+      );
+    },
+  );
+
+  server.registerTool(
+    "artifacts_rollback",
+    {
+      description:
+        "Promote an existing immutable artifact version back to current without rewriting history.",
+      inputSchema: {
+        artifactId: z4.string().uuid(),
+        versionId: z4.string().uuid(),
+        expectedCurrentVersionId: z4.string().uuid(),
+        reason: z4.string().min(1).max(4096),
+        idempotencyKey: z4.string().min(1).max(200),
+      },
+    },
+    async ({ artifactId, versionId, expectedCurrentVersionId, reason, idempotencyKey }) => {
+      await authorize();
+      return json(
+        await rollbackWorkspaceArtifact(deps.db, {
+          artifactId,
+          versionId,
+          expectedCurrentVersionId,
+          reason,
+          ...provenance(idempotencyKey, "artifacts_rollback"),
+        }),
+      );
+    },
+  );
+}
+
 function preferenceAttemptClaims(grant: AccessGrant): {
   sessionId: string;
   turnId: string;

package/src/routes/sessions.ts

@@ -296,16 +296,14 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     ),
   });
 
-  // A host-bound deployment has one fail-closed authorization seam for every
-  // HTTP session surface. Register it before the routes so a newly added path
-  // cannot accidentally inherit workspace access without an explicit operation
-  // classification. The long-lived event stream performs its own initial check
-  // and bounded reauthorization below.
+  // Every deployment has one fail-closed authorization seam for every HTTP
+  // session surface. The core boundary always enforces durable OpenGeni-owned
+  // private-session rules; an embedding host port can add narrower policy.
+  // Register it before the routes so a newly added path cannot accidentally
+  // inherit workspace access without an explicit operation classification. The
+  // long-lived event stream performs its own initial check and bounded
+  // reauthorization below.
   const authorizeSessionHttp: MiddlewareHandler = async (c, next) => {
-    if (!deps.sessionAuthorization) {
-      await next();
-      return;
-    }
     const workspaceId = c.req.param("workspaceId") ?? "";
     const sessionId = c.req.param("sessionId") ?? "";
     const operation = sessionAuthorizationOperationForHttp(
@@ -320,6 +318,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!operation) {
       throw sessionAuthorizationHttpError(new SessionAuthorizationUnavailableError());
     }
+    if (operation === "session.codex_account.write" && !deps.sessionAuthorization) {
+      await next();
+      return;
+    }
     const grant = await requireAccessGrant(c, deps, workspaceId);
     try {
       const authorization = await requireSessionAuthorization(deps, grant, {
@@ -587,7 +589,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // account id isn't in the workspace.
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/codex-account", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     const body = (await c.req.json()) as { target?: string };
     const target = typeof body.target === "string" ? body.target : "";
@@ -596,6 +598,17 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         message: 'target is required ("auto" or an account id)',
       });
     }
+    if (!deps.sessionAuthorization) {
+      try {
+        await requireSessionAuthorization(deps, grant, {
+          sessionId,
+          operation: "session.codex_account.write",
+          surface: "http",
+        });
+      } catch (error) {
+        throw sessionAuthorizationHttpError(error);
+      }
+    }
     const pinned = target === "auto" ? null : target;
     const mutation = await withCodexCapacityMutation(
       db,

package/src/routes/workspace-artifacts.ts

@@ -0,0 +1,274 @@
+import { createHash } from "node:crypto";
+import {
+  CreateWorkspaceArtifactRequest,
+  PublishWorkspaceArtifactVersionRequest,
+  RollbackWorkspaceArtifactRequest,
+  WorkspaceArtifactContentResponse,
+  WorkspaceArtifactDetailResponse,
+  WorkspaceArtifactListQuery,
+  WorkspaceArtifactListResponse,
+  WorkspaceArtifactMutationResponse,
+  normalizeWorkspaceArtifactSlug,
+} from "@opengeni/contracts";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  createWorkspaceArtifact,
+  getWorkspaceArtifact,
+  getWorkspaceArtifactContentRef,
+  listWorkspaceArtifacts,
+  publishWorkspaceArtifactVersion,
+  rollbackWorkspaceArtifact,
+  WorkspaceArtifactConflictError,
+  WorkspaceArtifactNotFoundError,
+  WorkspaceArtifactOperationError,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const ArtifactId = z.string().uuid();
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+async function body<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid artifact request" });
+  return parsed.data;
+}
+
+function artifactId(context: Context): string {
+  const parsed = ArtifactId.safeParse(context.req.param("artifactId"));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid artifact id" });
+  return parsed.data;
+}
+
+function errorResponse(context: Context, error: unknown): Response {
+  if (error instanceof WorkspaceArtifactNotFoundError) {
+    return context.json({ code: "WORKSPACE_ARTIFACT_NOT_FOUND", message: error.message }, 404);
+  }
+  if (error instanceof WorkspaceArtifactConflictError) {
+    return context.json(
+      {
+        code: "WORKSPACE_ARTIFACT_CONFLICT",
+        message: error.message,
+        currentVersionId: error.currentVersionId,
+      },
+      409,
+    );
+  }
+  if (error instanceof WorkspaceArtifactOperationError) {
+    return context.json(
+      { code: "INVALID_WORKSPACE_ARTIFACT_OPERATION", message: error.message },
+      422,
+    );
+  }
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "23505") {
+    return context.json(
+      { code: "WORKSPACE_ARTIFACT_CONFLICT", message: "Artifact slug or operation already exists" },
+      409,
+    );
+  }
+  throw error;
+}
+
+function contentMetadata(workspaceId: string, html: string) {
+  const bytes = encoder.encode(html);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  return {
+    bytes,
+    contentSha256: sha256,
+    sizeBytes: bytes.byteLength,
+    contentKey: `workspaces/${workspaceId}/workspace-artifacts/blobs/${sha256}.html`,
+  };
+}
+
+function prepareHtml(deps: ApiRouteDeps, workspaceId: string, html: string) {
+  if (!deps.objectStorage)
+    throw new HTTPException(503, { message: "Object storage is not configured" });
+  const content = contentMetadata(workspaceId, html);
+  return {
+    ...content,
+    persistContent: async () => {
+      await deps.objectStorage!.putObject({
+        key: content.contentKey,
+        contentType: "text/html; charset=utf-8",
+        body: content.bytes,
+        sha256: content.contentSha256,
+      });
+    },
+  };
+}
+
+function provenance(subjectId: string, idempotencyKey: string) {
+  return {
+    operationKey: `subject:${createHash("sha256").update(`${subjectId}:${idempotencyKey}`).digest("hex")}`,
+    actorSubjectId: subjectId,
+    sourceSessionId: null,
+    sourceTurnId: null,
+    sourceAttemptId: null,
+    sourceExecutionGeneration: null,
+    sourceToolName: null,
+  };
+}
+
+export function registerWorkspaceArtifactRoutes(app: Hono, deps: ApiRouteDeps): void {
+  // `published-artifacts` deliberately avoids the existing `/artifacts/:id`
+  // retained-output API. The product route remains simply `/artifacts`.
+  const base = "/v1/workspaces/:workspaceId/published-artifacts";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
+    const query = WorkspaceArtifactListQuery.safeParse({
+      limit: context.req.query("limit"),
+      cursor: context.req.query("cursor"),
+    });
+    if (!query.success) throw new HTTPException(422, { message: "Invalid artifact list query" });
+    try {
+      return context.json(
+        WorkspaceArtifactListResponse.parse(
+          await listWorkspaceArtifacts(deps.db, workspaceId, {
+            limit: query.data.limit,
+            ...(query.data.cursor ? { cursor: query.data.cursor } : {}),
+          }),
+        ),
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+
+  app.post(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:publish");
+    const request = await body(context, CreateWorkspaceArtifactRequest);
+    const id = crypto.randomUUID();
+    const slugBase = request.slug ?? (normalizeWorkspaceArtifactSlug(request.title) || "artifact");
+    const slug = request.slug ?? `${slugBase.slice(0, 87)}-${id.slice(0, 8)}`;
+    const content = prepareHtml(deps, workspaceId, request.html);
+    try {
+      return context.json(
+        WorkspaceArtifactMutationResponse.parse(
+          await createWorkspaceArtifact(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            artifactId: id,
+            slug,
+            title: request.title,
+            description: request.description ?? null,
+            ...content,
+            ...provenance(grant.subjectId, request.idempotencyKey),
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+
+  app.get(`${base}/:artifactId`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
+    try {
+      return context.json(
+        WorkspaceArtifactDetailResponse.parse(
+          await getWorkspaceArtifact(deps.db, workspaceId, artifactId(context)),
+        ),
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+
+  app.get(`${base}/:artifactId/content`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
+    if (!deps.objectStorage)
+      throw new HTTPException(503, { message: "Object storage is not configured" });
+    const parsedVersion = context.req.query("versionId");
+    if (parsedVersion && !ArtifactId.safeParse(parsedVersion).success) {
+      throw new HTTPException(422, { message: "Invalid artifact version id" });
+    }
+    try {
+      const ref = await getWorkspaceArtifactContentRef(
+        deps.db,
+        workspaceId,
+        artifactId(context),
+        parsedVersion,
+      );
+      const object = await deps.objectStorage.getObjectBytes(ref.contentKey);
+      if (!object) throw new HTTPException(503, { message: "Artifact content is unavailable" });
+      const actualHash = createHash("sha256").update(object.bytes).digest("hex");
+      if (actualHash !== ref.version.contentSha256) {
+        throw new HTTPException(503, { message: "Artifact content failed integrity verification" });
+      }
+      let html: string;
+      try {
+        html = decoder.decode(object.bytes);
+      } catch {
+        throw new HTTPException(503, { message: "Artifact content is not valid UTF-8" });
+      }
+      return context.json(
+        WorkspaceArtifactContentResponse.parse({
+          artifactId: ref.artifactId,
+          versionId: ref.version.id,
+          contentType: "text/html",
+          contentSha256: ref.version.contentSha256,
+          html,
+        }),
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+
+  app.post(`${base}/:artifactId/versions`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:publish");
+    const request = await body(context, PublishWorkspaceArtifactVersionRequest);
+    const id = artifactId(context);
+    const content = prepareHtml(deps, workspaceId, request.html);
+    try {
+      return context.json(
+        WorkspaceArtifactMutationResponse.parse(
+          await publishWorkspaceArtifactVersion(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            artifactId: id,
+            expectedCurrentVersionId: request.expectedCurrentVersionId,
+            ...(request.title !== undefined ? { title: request.title } : {}),
+            ...(request.description !== undefined ? { description: request.description } : {}),
+            ...content,
+            ...provenance(grant.subjectId, request.idempotencyKey),
+          }),
+        ),
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+
+  app.post(`${base}/:artifactId/rollback`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:publish");
+    const request = await body(context, RollbackWorkspaceArtifactRequest);
+    try {
+      return context.json(
+        WorkspaceArtifactMutationResponse.parse(
+          await rollbackWorkspaceArtifact(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            artifactId: artifactId(context),
+            versionId: request.versionId,
+            expectedCurrentVersionId: request.expectedCurrentVersionId,
+            reason: request.reason,
+            ...provenance(grant.subjectId, request.idempotencyKey),
+          }),
+        ),
+      );
+    } catch (error) {
+      return errorResponse(context, error);
+    }
+  });
+}