@opengeni/api-router 0.23.1 → 0.26.1

package/src/browser-state-authority.ts

@@ -0,0 +1,236 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from "node:crypto";
+import { BROWSER_PROFILE_ARTIFACT_FORMAT } from "@opengeni/contracts";
+
+const ROOT_KEY_BYTES = 32;
+const DATA_KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const WRAPPED_PREFIX = "ogbk1";
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+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}$/iu;
+
+export type BrowserStateOperationScope = {
+  accountId: string;
+  workspaceId: string;
+  browserSessionId: string;
+  operationId: string;
+  objectKey: string;
+};
+
+export type BrowserStateArtifactScope = {
+  accountId: string;
+  workspaceId: string;
+  objectKey: string;
+  artifactDigest: string;
+  contentDigest: string;
+};
+
+/** Deterministic only within one idempotent publication operation. This lets a
+ * control-plane retry present browserd with exactly the same secret authority
+ * without storing a plaintext key or placing it in an operation row. */
+export function deriveBrowserStateDataKey(
+  rootKey: Uint8Array,
+  scopeInput: BrowserStateOperationScope,
+): Buffer {
+  const scope = operationScope(scopeInput);
+  return createHmac("sha256", root(rootKey))
+    .update("opengeni.browser-state.data-key.v1\0", "utf8")
+    .update(canonicalJson(scope), "utf8")
+    .digest();
+}
+
+/** Associated data for the encrypted profile object. It is reproducible from
+ * durable non-secret artifact authority during restore. */
+export function browserStateArtifactAad(
+  scopeInput: Pick<BrowserStateArtifactScope, "accountId" | "workspaceId" | "objectKey">,
+): Buffer {
+  const scope = baseArtifactScope(scopeInput);
+  return Buffer.from(`opengeni.browser-state.artifact-aad.v1\0${canonicalJson(scope)}`, "utf8");
+}
+
+/** Wrap a 32-byte artifact data key under the operator-held root key. The
+ * ciphertext is bound to workspace, object, and both integrity digests. */
+export function wrapBrowserStateDataKey(
+  rootKey: Uint8Array,
+  dataKeyInput: Uint8Array,
+  scopeInput: BrowserStateArtifactScope,
+): string {
+  const dataKey = exactKey(dataKeyInput, "browser state data key");
+  const scope = artifactScope(scopeInput);
+  const iv = randomBytes(IV_BYTES);
+  const wrappingKey = browserStateWrappingKey(rootKey, scope);
+  try {
+    const cipher = createCipheriv("aes-256-gcm", wrappingKey, iv);
+    cipher.setAAD(wrapAad(scope));
+    const ciphertext = Buffer.concat([cipher.update(dataKey), cipher.final()]);
+    const payload = Buffer.concat([ciphertext, cipher.getAuthTag()]);
+    return `${WRAPPED_PREFIX}:${iv.toString("base64")}:${payload.toString("base64")}`;
+  } finally {
+    wrappingKey.fill(0);
+  }
+}
+
+export function unwrapBrowserStateDataKey(
+  rootKey: Uint8Array,
+  wrapped: string,
+  scopeInput: BrowserStateArtifactScope,
+): Buffer {
+  const scope = artifactScope(scopeInput);
+  const parts = wrapped.split(":");
+  if (parts.length !== 3 || parts[0] !== WRAPPED_PREFIX) {
+    throw new Error("browser state data-key envelope is unsupported");
+  }
+  const iv = canonicalBase64(parts[1]!, IV_BYTES, "browser state data-key envelope");
+  const payload = canonicalBase64(
+    parts[2]!,
+    DATA_KEY_BYTES + TAG_BYTES,
+    "browser state data-key envelope",
+  );
+  const ciphertext = payload.subarray(0, DATA_KEY_BYTES);
+  const tag = payload.subarray(DATA_KEY_BYTES);
+  const wrappingKey = browserStateWrappingKey(rootKey, scope);
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", wrappingKey, iv);
+    decipher.setAAD(wrapAad(scope));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    throw new Error("browser state data-key decryption failed");
+  } finally {
+    wrappingKey.fill(0);
+  }
+}
+
+export function browserStateObjectKey(workspaceIdInput: string, operationIdInput: string): string {
+  const workspaceId = uuid(workspaceIdInput, "workspace id");
+  const operationId = uuid(operationIdInput, "browser state operation id");
+  return `workspaces/${workspaceId}/browser-state/revisions/${operationId}/chromium-profile.ogbs`;
+}
+
+export function browserStateManifestDigest(manifest: unknown): string {
+  return createHash("sha256").update(canonicalJson(manifest), "utf8").digest("hex");
+}
+
+function operationScope(input: BrowserStateOperationScope) {
+  const base = baseArtifactScope(input);
+  return {
+    ...base,
+    browserSessionId: uuid(input.browserSessionId, "browser session id"),
+    operationId: uuid(input.operationId, "browser state operation id"),
+  };
+}
+
+function artifactScope(input: BrowserStateArtifactScope) {
+  return {
+    ...baseArtifactScope(input),
+    artifactDigest: sha256(input.artifactDigest, "browser state artifact digest"),
+    contentDigest: sha256(input.contentDigest, "browser state content digest"),
+  };
+}
+
+function baseArtifactScope(
+  input: Pick<BrowserStateArtifactScope, "accountId" | "workspaceId" | "objectKey">,
+) {
+  const workspaceId = uuid(input.workspaceId, "workspace id");
+  const objectKey = browserStateObjectKeyValue(input.objectKey, workspaceId);
+  return {
+    version: 1,
+    accountId: uuid(input.accountId, "account id"),
+    workspaceId,
+    objectKey,
+    format: BROWSER_PROFILE_ARTIFACT_FORMAT,
+  };
+}
+
+function wrapAad(scope: ReturnType<typeof artifactScope>): Buffer {
+  return Buffer.from(`opengeni.browser-state.data-key-wrap.v1\0${canonicalJson(scope)}`, "utf8");
+}
+
+function browserStateWrappingKey(
+  rootKey: Uint8Array,
+  scope: ReturnType<typeof artifactScope>,
+): Buffer {
+  return createHmac("sha256", root(rootKey))
+    .update("opengeni.browser-state.wrapping-key.v1\0", "utf8")
+    .update(canonicalJson(scope), "utf8")
+    .digest();
+}
+
+function browserStateObjectKeyValue(value: string, workspaceId: string): string {
+  if (
+    typeof value !== "string" ||
+    Buffer.byteLength(value) > 2_048 ||
+    !new RegExp(
+      `^workspaces/${workspaceId}/browser-state/[A-Za-z0-9._=-]+(?:/[A-Za-z0-9._=-]+)*$`,
+      "u",
+    ).test(value)
+  ) {
+    throw new Error("browser state object key is invalid");
+  }
+  return value;
+}
+
+function root(value: Uint8Array): Buffer {
+  return exactKey(value, "browser state root key");
+}
+
+function exactKey(value: Uint8Array, label: string): Buffer {
+  if (!(value instanceof Uint8Array) || value.byteLength !== ROOT_KEY_BYTES) {
+    throw new Error(`${label} must be exactly ${ROOT_KEY_BYTES} bytes`);
+  }
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+
+function uuid(value: string, label: string): string {
+  if (typeof value !== "string" || !UUID_PATTERN.test(value)) {
+    throw new Error(`${label} must be a UUID`);
+  }
+  return value.toLowerCase();
+}
+
+function sha256(value: string, label: string): string {
+  if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
+    throw new Error(`${label} is invalid`);
+  }
+  return value;
+}
+
+function canonicalBase64(value: string, length: number, label: string): Buffer {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
+    throw new Error(`${label} is unsupported`);
+  }
+  const decoded = Buffer.from(value, "base64");
+  if (decoded.byteLength !== length || decoded.toString("base64") !== value) {
+    decoded.fill(0);
+    throw new Error(`${label} is unsupported`);
+  }
+  return decoded;
+}
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (typeof value === "object") {
+    const input = value as Record<string, unknown>;
+    const output: Record<string, unknown> = {};
+    for (const key of Object.keys(input).sort()) {
+      if (input[key] === undefined) {
+        throw new Error("canonical JSON cannot contain undefined");
+      }
+      output[key] = canonicalValue(input[key]);
+    }
+    return output;
+  }
+  throw new Error("value cannot be represented as canonical JSON");
+}

package/src/codemode.ts

@@ -0,0 +1,186 @@
+import {
+  codemodeDispatchSubject,
+  decodeCodemodeDispatchAck,
+  encodeCodemodeDispatchRequest,
+} from "@opengeni/codemode";
+import {
+  CODEMODE_DISPATCH_TIMEOUT_MS,
+  CodemodeCallRequest,
+  CodemodeCallSubmission,
+  type AccessGrant,
+  type AttemptToolCatalog,
+  type CodemodeCallSubmission as CodemodeCallSubmissionValue,
+  type CodemodeOperation,
+} from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { hasPermission, requireSessionAuthorization } from "@opengeni/core";
+import {
+  getActiveSessionTurnForExecution,
+  getAttemptToolCatalog,
+  getCodemodeOperation,
+  submitCodemodeOperation,
+} from "@opengeni/db";
+
+export type CodemodeGrantAuthority = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+  subjectId: string;
+};
+
+export class CodemodeAuthorityError extends Error {
+  readonly code = "codemode_authority_invalid";
+
+  constructor() {
+    super("Codemode bearer is not bound to an active execution attempt");
+    this.name = "CodemodeAuthorityError";
+  }
+}
+
+export function codemodeAuthorityForGrant(grant: AccessGrant): CodemodeGrantAuthority | null {
+  const metadata = grant.metadata;
+  if (
+    grant.principalKind !== "agent_attempt" ||
+    metadata?.delegated !== true ||
+    typeof metadata.sessionId !== "string" ||
+    typeof metadata.turnId !== "string" ||
+    typeof metadata.attemptId !== "string" ||
+    typeof metadata.executionGeneration !== "number" ||
+    !Number.isInteger(metadata.executionGeneration) ||
+    metadata.executionGeneration < 1
+  ) {
+    return null;
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    sessionId: metadata.sessionId,
+    turnId: metadata.turnId,
+    attemptId: metadata.attemptId,
+    executionGeneration: metadata.executionGeneration,
+    subjectId: grant.subjectId,
+  };
+}
+
+export function isCodemodeGrant(grant: AccessGrant): boolean {
+  return (
+    hasPermission(grant.permissions, "codemode:call") && codemodeAuthorityForGrant(grant) !== null
+  );
+}
+
+export async function requireActiveCodemodeCatalog(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+): Promise<{ authority: CodemodeGrantAuthority; catalog: AttemptToolCatalog }> {
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+  const authority = codemodeAuthorityForGrant(grant)!;
+  await requireSessionAuthorization(deps, grant, {
+    sessionId: authority.sessionId,
+    operation: "session.codemode.call",
+    surface: "codemode",
+  });
+  const active = await getActiveSessionTurnForExecution(
+    deps.db,
+    authority.workspaceId,
+    authority.sessionId,
+  );
+  if (
+    !active ||
+    active.status !== "running" ||
+    active.id !== authority.turnId ||
+    active.activeAttemptId !== authority.attemptId ||
+    active.executionGeneration !== authority.executionGeneration
+  ) {
+    throw new CodemodeAuthorityError();
+  }
+  const catalog = await getAttemptToolCatalog(deps.db, {
+    accountId: authority.accountId,
+    workspaceId: authority.workspaceId,
+    attemptId: authority.attemptId,
+  });
+  if (
+    !catalog ||
+    catalog.accountId !== authority.accountId ||
+    catalog.workspaceId !== authority.workspaceId ||
+    catalog.sessionId !== authority.sessionId ||
+    catalog.turnId !== authority.turnId ||
+    catalog.attemptId !== authority.attemptId ||
+    catalog.executionGeneration !== authority.executionGeneration
+  ) {
+    throw new CodemodeAuthorityError();
+  }
+  return { authority, catalog };
+}
+
+export async function submitAndDispatchCodemodeCall(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  rawRequest: unknown,
+): Promise<CodemodeCallSubmissionValue> {
+  const request = CodemodeCallRequest.parse(rawRequest);
+  const { authority, catalog } = await requireActiveCodemodeCatalog(deps, grant);
+  const submitted = await submitCodemodeOperation(deps.db, {
+    ...authority,
+    call: {
+      ...request,
+      caller: { kind: "codemode", subjectId: authority.subjectId },
+    },
+    callLimit: deps.settings.codemodeMaxCallsPerTurn,
+  });
+  let operation = submitted.operation;
+  let dispatch: CodemodeCallSubmissionValue["dispatch"] = terminal(operation)
+    ? "terminal"
+    : operation.state === "running"
+      ? "already_running"
+      : "unavailable";
+  if (operation.state === "queued") {
+    try {
+      const reply = await deps.bus.request(
+        codemodeDispatchSubject(authority.workspaceId, authority.attemptId),
+        encodeCodemodeDispatchRequest({
+          version: 1,
+          operationId: operation.operationId,
+          catalogDigest: catalog.digest,
+        }),
+        { timeoutMs: CODEMODE_DISPATCH_TIMEOUT_MS },
+      );
+      dispatch = decodeCodemodeDispatchAck(reply.data).status;
+    } catch {
+      dispatch = "unavailable";
+    }
+    operation =
+      (await getCodemodeOperation(deps.db, {
+        accountId: authority.accountId,
+        workspaceId: authority.workspaceId,
+        attemptId: authority.attemptId,
+        operationId: operation.operationId,
+      })) ?? operation;
+    if (terminal(operation)) dispatch = "terminal";
+    else if (operation.state === "running" && dispatch === "unavailable") {
+      dispatch = "already_running";
+    }
+  }
+  return CodemodeCallSubmission.parse({ operation, dispatch });
+}
+
+export async function readCodemodeOperation(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  operationId: string,
+): Promise<CodemodeOperation | null> {
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+  const authority = codemodeAuthorityForGrant(grant)!;
+  return await getCodemodeOperation(deps.db, {
+    accountId: authority.accountId,
+    workspaceId: authority.workspaceId,
+    attemptId: authority.attemptId,
+    operationId,
+  });
+}
+
+function terminal(operation: CodemodeOperation): boolean {
+  return ["completed", "failed", "outcome_unknown", "cancelled"].includes(operation.state);
+}

package/src/editable-artifact-live-hints.ts

@@ -0,0 +1,64 @@
+import {
+  decodeEditableArtifactBrokerHint,
+  editableArtifactLiveHintSubject,
+  type EditableArtifactLiveHintPort,
+} from "@opengeni/core";
+import type { EventBus, OpStreamConnection } from "@opengeni/events";
+
+/**
+ * Uses the API's existing resilient NATS connection. Hints carry no operation
+ * bytes; every callback causes a durable DB head read and contiguous gap-fill.
+ */
+export class EventBusEditableArtifactLiveHints implements EditableArtifactLiveHintPort {
+  constructor(private readonly bus: Pick<EventBus, "getOpStreamConnection">) {}
+
+  async subscribe(
+    input: Parameters<EditableArtifactLiveHintPort["subscribe"]>[0],
+  ): Promise<() => void> {
+    const connection = this.bus.getOpStreamConnection?.();
+    if (!connection) throw new Error("Event bus has no artifact hint subscription transport");
+    const subject = editableArtifactLiveHintSubject(input.scope, input.artifactId);
+    const subscription = connection.subscribe(subject);
+    let active = true;
+    try {
+      await requireFlushBarrier(connection);
+    } catch (error) {
+      subscription.unsubscribe();
+      throw error;
+    }
+    void (async () => {
+      try {
+        for await (const message of subscription) {
+          if (!active) return;
+          try {
+            const hint = decodeEditableArtifactBrokerHint(message.data, {
+              scope: input.scope,
+              artifactId: input.artifactId,
+            });
+            input.onHint({
+              artifactId: input.artifactId,
+              headSequence: hint.headSequence,
+            });
+          } catch {
+            // Broker input is advisory and untrusted. Drop poison; periodic
+            // durable reconciliation remains authoritative.
+          }
+        }
+      } catch {
+        if (active) input.onReconnect();
+      }
+    })();
+    return () => {
+      if (!active) return;
+      active = false;
+      subscription.unsubscribe();
+    };
+  }
+}
+
+async function requireFlushBarrier(connection: OpStreamConnection): Promise<void> {
+  if (!connection.flush) {
+    throw new Error("Artifact hint subscription transport lacks a flush barrier");
+  }
+  await connection.flush();
+}