@opengeni/api-router 0.23.1 → 0.26.1

package/src/editable-artifact-websocket.ts

@@ -0,0 +1,311 @@
+import {
+  EditableArtifactDomainError,
+  EditableArtifactLiveError,
+  decodeEditableArtifactLiveClientWireFrame,
+  encodeEditableArtifactLiveServerWireFrame,
+  type EditableArtifactApplicationPort,
+  type EditableArtifactLiveClose,
+  type EditableArtifactLiveServerFrame,
+  type EditableArtifactLiveSession,
+  type EditableArtifactLiveSinkPort,
+} from "@opengeni/core";
+
+export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH = "/v1/editable-artifacts/live";
+export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v1";
+export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES = 8 * 1024 * 1024 + 64 * 1024;
+
+const MAX_QUEUED_MESSAGES = 64;
+const MAX_QUEUED_BYTES = 12 * 1024 * 1024;
+
+export type EditableArtifactWebSocketLike = Readonly<{
+  data: EditableArtifactWebSocketConnection;
+  send(data: Uint8Array, compress?: boolean): number;
+  close(code?: number, reason?: string): void;
+  readonly bufferedAmount?: number;
+  getBufferedAmount?(): number;
+}>;
+
+export type EditableArtifactWebSocketUpgradeServer = Readonly<{
+  upgrade(
+    request: Request,
+    options: Readonly<{
+      data: EditableArtifactWebSocketConnection;
+      headers: HeadersInit;
+    }>,
+  ): boolean;
+}>;
+
+export type EditableArtifactWebSocketHandler = Readonly<{
+  open(socket: EditableArtifactWebSocketLike): void;
+  message(socket: EditableArtifactWebSocketLike, message: string | Uint8Array | ArrayBuffer): void;
+  close(socket: EditableArtifactWebSocketLike): void;
+}>;
+
+export class EditableArtifactWebSocketTransport {
+  readonly websocket: EditableArtifactWebSocketHandler;
+
+  constructor(private readonly application: EditableArtifactApplicationPort | undefined) {
+    this.websocket = Object.freeze({
+      open: (socket) => socket.data.attach(socket),
+      message: (socket, message) => socket.data.receive(message),
+      close: (socket) => socket.data.transportClosed(),
+    });
+  }
+
+  handles(request: Request): boolean {
+    return new URL(request.url).pathname === EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH;
+  }
+
+  upgrade(request: Request, server: EditableArtifactWebSocketUpgradeServer): Response | undefined {
+    const url = new URL(request.url);
+    if (url.pathname !== EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH) return undefined;
+    if (request.method !== "GET") {
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: { allow: "GET" },
+      });
+    }
+    if (!this.application) return new Response("Service Unavailable", { status: 503 });
+    if (!offeredProtocol(request.headers.get("sec-websocket-protocol"))) {
+      return new Response("WebSocket protocol required", { status: 426 });
+    }
+    const connection = new EditableArtifactWebSocketConnection(this.application);
+    const upgraded = server.upgrade(request, {
+      data: connection,
+      headers: {
+        "sec-websocket-protocol": EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL,
+      },
+    });
+    return upgraded ? undefined : new Response("Bad Request", { status: 400 });
+  }
+}
+
+/** One socket, one consumed ticket, one stream epoch. */
+export class EditableArtifactWebSocketConnection implements EditableArtifactLiveSinkPort {
+  private socket: EditableArtifactWebSocketLike | null = null;
+  private session: EditableArtifactLiveSession | null = null;
+  private work: Promise<void> = Promise.resolve();
+  private queuedMessages = 0;
+  private queuedBytes = 0;
+  private terminal = false;
+
+  constructor(private readonly application: EditableArtifactApplicationPort) {}
+
+  attach(socket: EditableArtifactWebSocketLike): void {
+    if (this.socket || this.terminal) {
+      socket.close(4400, "invalid connection state");
+      return;
+    }
+    this.socket = socket;
+  }
+
+  receive(message: string | Uint8Array | ArrayBuffer): void {
+    if (this.terminal) return;
+    if (typeof message === "string") {
+      void this.fail("invalid_frame");
+      return;
+    }
+    const byteLength = message.byteLength;
+    if (
+      byteLength === 0 ||
+      byteLength > EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES ||
+      this.queuedMessages + 1 > MAX_QUEUED_MESSAGES ||
+      this.queuedBytes + byteLength > MAX_QUEUED_BYTES
+    ) {
+      void this.fail(
+        byteLength > EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES
+          ? "oversized_frame"
+          : "slow_client",
+      );
+      return;
+    }
+    const bytes =
+      message instanceof Uint8Array ? Uint8Array.from(message) : new Uint8Array(message).slice();
+    this.queuedMessages += 1;
+    this.queuedBytes += bytes.byteLength;
+    const run = this.work.then(async () => {
+      try {
+        await this.process(bytes);
+      } finally {
+        this.queuedMessages -= 1;
+        this.queuedBytes -= bytes.byteLength;
+      }
+    });
+    this.work = run.catch(async (error: unknown) => {
+      await this.handleFailure(error);
+    });
+  }
+
+  async send(frame: EditableArtifactLiveServerFrame): Promise<void> {
+    if (this.terminal || !this.socket) {
+      throw new EditableArtifactLiveError("closed", "Editable artifact socket is closed");
+    }
+    const bytes = encodeEditableArtifactLiveServerWireFrame(frame);
+    if (bytes.byteLength > EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES) {
+      throw new EditableArtifactLiveError(
+        "oversized_frame",
+        "Editable artifact server frame exceeds socket limit",
+        { requiresSnapshot: true },
+      );
+    }
+    const accepted = this.socket.send(bytes, false);
+    if (!Number.isSafeInteger(accepted) || accepted <= 0) {
+      throw new EditableArtifactLiveError("closed", "Editable artifact socket rejected frame");
+    }
+  }
+
+  bufferedBytes(): number {
+    const buffered = this.socket?.getBufferedAmount?.() ?? this.socket?.bufferedAmount ?? 0;
+    return Number.isSafeInteger(buffered) && buffered >= 0 ? buffered : Number.MAX_SAFE_INTEGER;
+  }
+
+  close(close: EditableArtifactLiveClose): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.socket?.close(closeCode(close.reason), close.reason);
+  }
+
+  transportClosed(): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    void this.session?.close("transport_error");
+  }
+
+  private async process(bytes: Uint8Array): Promise<void> {
+    if (this.terminal) return;
+    const frame = decodeEditableArtifactLiveClientWireFrame(bytes);
+    if (!this.session) {
+      if (frame.type !== "open") {
+        throw new EditableArtifactLiveError("invalid_frame", "First socket frame must be open");
+      }
+      const session = await this.application.openLive({
+        token: frame.token,
+        artifactId: frame.artifactId,
+        protocolVersion: frame.protocolVersion,
+        resume: frame.resume,
+        sink: this,
+      });
+      if (this.terminal) {
+        await session.close("transport_error");
+        return;
+      }
+      this.session = session;
+      void session.closed.then(() => {
+        if (!this.terminal)
+          this.close({
+            reason: "closed",
+            retryable: false,
+            requiresSnapshot: false,
+          });
+      });
+      return;
+    }
+    if (frame.type === "open") {
+      throw new EditableArtifactLiveError("invalid_frame", "Socket is already open");
+    }
+    if (
+      frame.artifactId !== this.session.artifactId ||
+      frame.streamEpoch !== this.session.streamEpoch
+    ) {
+      throw new EditableArtifactLiveError("stale_epoch", "Socket frame belongs to another stream");
+    }
+    if (frame.type === "applied") {
+      await this.session.acknowledge(frame);
+      return;
+    }
+    let receipt: Awaited<ReturnType<EditableArtifactLiveSession["submitIntent"]>>;
+    try {
+      receipt = await this.session.submitIntent(frame);
+    } catch (error) {
+      await this.send({
+        type: "mutationRejected",
+        protocolVersion: frame.protocolVersion,
+        artifactId: frame.artifactId,
+        streamEpoch: frame.streamEpoch,
+        requestHash: frame.requestHash,
+        ...mutationFailure(error),
+      });
+      return;
+    }
+    // Always return the exact durable canonical transaction evidence (OGACO
+    // or OGAST) on this request's socket, including idempotent unknown-outcome
+    // retries whose original fanout was already replayed and ACKed. Transaction
+    // first, mapping second: acceptance is never exposed without settle bytes.
+    await this.send({
+      type: "transaction",
+      protocolVersion: frame.protocolVersion,
+      artifactId: frame.artifactId,
+      streamEpoch: frame.streamEpoch,
+      transaction: receipt.transaction,
+    });
+    await this.send({
+      type: "mutationAccepted",
+      protocolVersion: frame.protocolVersion,
+      artifactId: frame.artifactId,
+      streamEpoch: frame.streamEpoch,
+      requestHash: receipt.requestHash,
+      clientTransactionId: receipt.clientTransactionId,
+      transactionId: receipt.transaction.transactionId,
+      startSequence: receipt.transaction.startSequence,
+      endSequence: receipt.transaction.endSequence,
+      stateHash: receipt.transaction.stateHash,
+    });
+  }
+
+  private async handleFailure(error: unknown): Promise<void> {
+    if (this.terminal) return;
+    if (error instanceof EditableArtifactLiveError) {
+      await this.fail(error.code === "invalid_ticket" ? "transport_error" : error.code);
+      return;
+    }
+    await this.fail("transport_error");
+  }
+
+  private async fail(reason: Parameters<EditableArtifactLiveSession["close"]>[0]): Promise<void> {
+    if (this.terminal) return;
+    this.terminal = true;
+    await this.session?.close(reason).catch(() => undefined);
+    this.socket?.close(closeCode(reason ?? "transport_error"), reason ?? "transport_error");
+  }
+}
+
+function mutationFailure(error: unknown): Readonly<{
+  code: "invalid_request" | "forbidden" | "conflict" | "unsupported" | "unavailable";
+  retryable: boolean;
+}> {
+  if (error instanceof EditableArtifactDomainError) {
+    if (error.code === "forbidden") return { code: "forbidden", retryable: false };
+    if (["invalid_request", "request_hash_mismatch", "invalid_undo_target"].includes(error.code)) {
+      return { code: "invalid_request", retryable: false };
+    }
+    if (error.code === "kernel_contract_violation") {
+      return { code: "unsupported", retryable: false };
+    }
+    if (["retryable_conflict", "outbox_lease_conflict"].includes(error.code)) {
+      return { code: "conflict", retryable: true };
+    }
+    return { code: "conflict", retryable: false };
+  }
+  if (error instanceof EditableArtifactLiveError && error.code === "permission_changed") {
+    return { code: "forbidden", retryable: false };
+  }
+  return { code: "unavailable", retryable: true };
+}
+
+function offeredProtocol(value: string | null): boolean {
+  return (
+    value
+      ?.split(",")
+      .map((part) => part.trim())
+      .includes(EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL) ?? false
+  );
+}
+
+function closeCode(reason: string): number {
+  if (reason === "permission_changed") return 4403;
+  if (reason === "ticket_expired" || reason === "ticket_replayed") return 4401;
+  if (reason === "protocol_mismatch") return 4406;
+  if (reason === "slow_client" || reason === "oversized_frame") return 4409;
+  if (reason === "closed") return 1000;
+  return 4400;
+}

package/src/editable-artifact-workspace-files.ts

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+
+import {
+  type EditableArtifactAgentWorkspaceFilePort,
+  type EditableArtifactDurableExportService,
+} from "@opengeni/core/editable-artifacts";
+import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
+import type { ObjectHead, ObjectStorage } from "@opengeni/storage";
+
+const UPLOAD_INTENT_TTL_MS = 60 * 60_000;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+export type EditableArtifactWorkspaceFileAdapterDependencies = Readonly<{
+  db: Database;
+  objectStorage: ObjectStorage;
+  durableExports: EditableArtifactDurableExportService;
+  now?: () => Date;
+  prepareFile?: typeof prepareGeneratedWorkspaceFile;
+  completeFile?: typeof completeFileUpload;
+}>;
+
+/**
+ * Promotes one immutable materialization into the normal workspace-file domain.
+ * The returned file ID is the only artifact export handle exposed to agents.
+ */
+export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAgentWorkspaceFilePort {
+  private readonly now: () => Date;
+  private readonly prepareFile: typeof prepareGeneratedWorkspaceFile;
+  private readonly completeFile: typeof completeFileUpload;
+
+  constructor(private readonly dependencies: EditableArtifactWorkspaceFileAdapterDependencies) {
+    this.now = dependencies.now ?? (() => new Date());
+    this.prepareFile = dependencies.prepareFile ?? prepareGeneratedWorkspaceFile;
+    this.completeFile = dependencies.completeFile ?? completeFileUpload;
+  }
+
+  async ensureMaterializationFile(
+    input: Parameters<EditableArtifactAgentWorkspaceFilePort["ensureMaterializationFile"]>[0],
+  ): ReturnType<EditableArtifactAgentWorkspaceFilePort["ensureMaterializationFile"]> {
+    throwIfAborted(input.signal);
+    const storage = this.dependencies.objectStorage;
+    if (!storage.headObject || !storage.putObjectStreamIfAbsent) {
+      throw new Error("Object storage lacks immutable streaming upload support");
+    }
+    const download = await this.dependencies.durableExports.openMaterializationDownload({
+      scope: input.scope,
+      actor: input.actor,
+      artifactId: input.artifact.id,
+      jobId: input.jobId,
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+    try {
+      const sha256 = plainSha256(download.contentHash);
+      const filename = exportFilename(input.filename, download.format);
+      const fileId = deterministicUuid(
+        `editable-artifact-export:file:${input.scope.workspaceId}:${input.artifact.id}:${input.versionId}:${input.jobId}`,
+      );
+      const uploadId = deterministicUuid(
+        `editable-artifact-export:upload:${input.scope.workspaceId}:${input.artifact.id}:${input.versionId}:${input.jobId}`,
+      );
+      const safeFilename = `artifact-${input.artifact.id}-${input.jobId}.${download.format}`;
+      const objectKey = `workspaces/${input.scope.workspaceId}/files/${fileId}/artifact-exports/${safeFilename}`;
+      const prepared = await this.prepareFile(this.dependencies.db, {
+        accountId: input.scope.accountId,
+        workspaceId: input.scope.workspaceId,
+        fileId,
+        uploadId,
+        filename,
+        safeFilename,
+        contentType: download.mimeType,
+        sizeBytes: download.byteSize,
+        sha256,
+        bucket: storage.bucket,
+        objectKey,
+        expiresAt: new Date(this.now().getTime() + UPLOAD_INTENT_TTL_MS),
+      });
+
+      let file = prepared.file;
+      if (file.status !== "ready") {
+        const existing = await storage.headObject(objectKey);
+        if (existing) {
+          assertStoredExport(existing, download.byteSize, download.mimeType, sha256);
+        } else {
+          await storage.putObjectStreamIfAbsent({
+            key: objectKey,
+            contentType: download.mimeType,
+            chunks: download.chunks(input.signal ? { signal: input.signal } : {}),
+            byteSize: download.byteSize,
+            sha256,
+            ...(input.signal ? { signal: input.signal } : {}),
+          });
+          const stored = await storage.headObject(objectKey);
+          assertStoredExport(stored, download.byteSize, download.mimeType, sha256);
+        }
+        await download.assertUnchanged(input.signal);
+        throwIfAborted(input.signal);
+        file = await this.completeFile(this.dependencies.db, input.scope.workspaceId, uploadId);
+      } else {
+        assertStoredExport(
+          await storage.headObject(objectKey),
+          download.byteSize,
+          download.mimeType,
+          sha256,
+        );
+        await download.assertUnchanged(input.signal);
+      }
+      if (
+        file.id !== fileId ||
+        file.status !== "ready" ||
+        file.filename !== filename ||
+        file.contentType !== download.mimeType ||
+        file.sizeBytes !== download.byteSize ||
+        file.sha256 !== sha256
+      ) {
+        throw new Error("Generated workspace file differs from its immutable export");
+      }
+
+      return Object.freeze({
+        fileId: file.id,
+        filename: file.filename,
+        contentType: file.contentType,
+        sizeBytes: file.sizeBytes,
+        sha256,
+        artifactId: input.artifact.id,
+        versionId: input.versionId,
+        materializationJobId: input.jobId,
+        sourceHeadSequence: input.sourceHeadSequence,
+        sourceStateHash: input.sourceStateHash,
+      });
+    } finally {
+      await download.close();
+    }
+  }
+}
+
+function assertStoredExport(
+  head: ObjectHead | null,
+  byteSize: number,
+  contentType: string,
+  sha256: string,
+): void {
+  if (
+    !head ||
+    head.ContentLength !== byteSize ||
+    head.ContentType !== contentType ||
+    head.Metadata?.sha256 !== sha256 ||
+    typeof head.VersionToken !== "string" ||
+    head.VersionToken.length < 1
+  ) {
+    throw new Error("Workspace export object differs from its durable materialization");
+  }
+}
+
+function exportFilename(value: string, format: string): string {
+  const expectedExtension = `.${format}`;
+  const normalized = value
+    .normalize("NFKC")
+    .replace(/[\\/:*?"<>|\u0000-\u001f\u007f]+/gu, "-")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, 200);
+  const stem = normalized.toLowerCase().endsWith(expectedExtension)
+    ? normalized.slice(0, -expectedExtension.length)
+    : normalized;
+  return `${stem.replace(/[. ]+$/u, "").slice(0, 190) || "artifact"}${expectedExtension}`;
+}
+
+function plainSha256(value: string): string {
+  const match = /^sha256:([0-9a-f]{64})$/u.exec(value);
+  if (!match) throw new Error("Materialized artifact content hash is invalid");
+  return match[1]!;
+}
+
+function deterministicUuid(seed: string): string {
+  const bytes = createHash("sha256").update(seed, "utf8").digest().subarray(0, 16);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  const value = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  if (!UUID_PATTERN.test(value)) throw new Error("Generated workspace file identity is invalid");
+  return value;
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw signal.reason ?? new Error("Artifact export aborted");
+}

package/src/github-browser-flow.ts

@@ -31,13 +31,42 @@ export function githubBrowserGrantClaims(
 export function continuedGitHubBrowserGrantClaims(
   payload: GitHubSignedStatePayload,
 ): Record<string, unknown> {
-  return typeof payload.browserGrantSubjectId === "string" &&
+  const browserGrant =
+    typeof payload.browserGrantSubjectId === "string" &&
     typeof payload.browserGrantExpiresAt === "number"
-    ? {
-        browserGrantSubjectId: payload.browserGrantSubjectId,
-        browserGrantExpiresAt: payload.browserGrantExpiresAt,
-      }
-    : {};
+      ? {
+          browserGrantSubjectId: payload.browserGrantSubjectId,
+          browserGrantExpiresAt: payload.browserGrantExpiresAt,
+        }
+      : {};
+  return {
+    ...browserGrant,
+    ...(typeof payload.returnPath === "string" ? { returnPath: payload.returnPath } : {}),
+  };
+}
+
+/**
+ * GitHub may return only to the session that initiated setup. This rejects
+ * absolute/protocol-relative URLs and paths for another workspace before the
+ * value is signed into provider state.
+ */
+export function githubSessionReturnPath(
+  value: string | undefined | null,
+  workspaceId: string,
+): string | null {
+  if (!value || value.length > 2048 || !value.startsWith("/") || value.startsWith("//")) {
+    return null;
+  }
+  const parsed = new URL(value, "https://opengeni.local");
+  const sessionPrefix = `/workspaces/${encodeURIComponent(workspaceId)}/sessions/`;
+  if (
+    parsed.origin !== "https://opengeni.local" ||
+    parsed.pathname.startsWith("//") ||
+    !parsed.pathname.startsWith(sessionPrefix)
+  ) {
+    return null;
+  }
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
 }
 
 export function githubBrowserGrantFromState(

package/src/http/auth.ts

@@ -49,6 +49,8 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   }
   if (
     path === "/v1/integrations/oauth/callback" ||
+    path === "/v1/integrations/provider-oauth/callback" ||
+    path === "/v1/integrations/google-drive/callback" ||
     path === "/v1/integrations/oauth/client-metadata.json" ||
     path === "/v1/integrations/slack/callback" ||
     path === "/v1/integrations/slack/events" ||

package/src/http/cors.ts

@@ -0,0 +1,3 @@
+export function allowedCorsOrigin(pattern: string, origin: string): boolean {
+  return new RegExp(`^(?:${pattern})$`).test(origin);
+}