@opengeni/api-router 3.3.0 → 3.4.0

package/src/routes/browser-sessions.ts

@@ -40,8 +40,12 @@ import {
   BrowserSessionLifecycleRequest,
   BrowserSessionListResponse,
   BrowserSessionMutationResponse,
+  type BrowserTarget,
   BrowserTargetListResponse,
   BrowserTargetState,
+  BrowserWorkingCopyAdoptionRequest,
+  BrowserWorkingCopyAdoptionResponse,
+  BrowserWorkingCopyInspection,
   CreateBrowserSessionRequest,
   ExternalAuthInteractiveRequest,
   ExternalAuthInteractiveResponse,
@@ -57,6 +61,8 @@ import {
   type BrowserActionRequest as BrowserActionRequestValue,
   type BrowserDownload as BrowserDownloadValue,
   type BrowserSession as BrowserSessionValue,
+  type BrowserWorkingCopyAdoption as BrowserWorkingCopyAdoptionValue,
+  type BrowserWorkingCopyRefusal as BrowserWorkingCopyRefusalValue,
   type FileAsset,
   type CreateBrowserSessionRequest as CreateBrowserSessionRequestValue,
   type InteractionPlacement,
@@ -143,6 +149,7 @@ import {
   verifyAuthRun,
   settleBrowserDownloadSaveFailure,
   terminalizeStaleConnectedInteractionPlacement,
+  recordAuditEvent,
   type BrowserSessionControlRecord,
   type BrowserPrivateCheckpointAuthority,
   type BrowserRevisionArtifactAuthority,
@@ -182,6 +189,9 @@ import {
   type BrowserControlScreenshotOptions,
   type BrowserControlFrame,
   type PlacementBrowserStateCaptureReceipt,
+  type PlacementBrowserWorkingCopyAdoption,
+  type PlacementBrowserWorkingCopyAuthority,
+  type PlacementBrowserWorkingCopyInspection,
   type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
   type RestorePlacementBrowserStateInput,
@@ -352,22 +362,36 @@ export function registerBrowserSessionRoutes(
     const request = await parseJsonBody(context, CreateBrowserSessionRequest);
     const startedAtMs = performance.now();
     const stages = new InteractionRouteStages("create");
-    await authorizeSourceSession(deps, grant, request.sessionId, "session.control");
+    // The replay lookup and the source session are read alongside the
+    // authorization check. A denial still wins, and neither read is used
+    // until the request is authorized; each failure surfaces where it did.
+    const [authorized, existingRead, sourceRead] = await Promise.allSettled([
+      authorizeSourceSession(deps, grant, request.sessionId, "session.control"),
+      findBrowserSessionControlRecordByOperation(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        operationId: request.operationId,
+      }),
+      requireSourceSession(deps, workspaceId, request.sessionId),
+    ]);
+    if (authorized.status === "rejected") throw authorized.reason;
     stages.mark("authorize");
     const origin = requestOrigin(context, deps.settings);
     const authority = browserAuthorityRoot(deps);
     let prepared: Awaited<ReturnType<typeof prepareBrowserSessionCreate>> | null = null;
+    // What the controller showed when it launched this browser, returned so
+    // the caller can present the opened tab without two more reads.
+    const launch: { result: Awaited<ReturnType<BrowserControlClient["createSession"]>> | null } = {
+      result: null,
+    };
 
     try {
       assertEphemeralBrowserCreateEnabled(
         request,
         deps.settings.experimentalBrowserContextPoolEnabled,
       );
-      const existing = await findBrowserSessionControlRecordByOperation(deps.db, {
-        accountId: grant.accountId,
-        workspaceId,
-        operationId: request.operationId,
-      });
+      if (existingRead.status === "rejected") throw existingRead.reason;
+      const existing = existingRead.value;
       if (existing && existing.sourceSessionId !== request.sessionId) {
         throw new BrowserSessionOperationConflictError(
           "BrowserSession create operation belongs to another source session",
@@ -401,7 +425,8 @@ export function registerBrowserSessionRoutes(
         }
       }
 
-      const sourceSession = await requireSourceSession(deps, workspaceId, request.sessionId);
+      if (sourceRead.status === "rejected") throw sourceRead.reason;
+      const sourceSession = sourceRead.value;
       stages.mark("source_session");
       const response = await withBrowserPlacement(
         sourceSession,
@@ -536,7 +561,7 @@ export function registerBrowserSessionRoutes(
                         linkedComputer !== null,
                       );
                       stages.mark("display");
-                      return await client.createSession({
+                      launch.result = await client.createSession({
                         browserSessionId: preparedSession.id,
                         controllerGeneration,
                         tokenGeneration: record.tokenGeneration,
@@ -553,6 +578,7 @@ export function registerBrowserSessionRoutes(
                         ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
                         ...(restore ? { restore } : {}),
                       });
+                      return launch.result;
                     },
                   );
                 },
@@ -614,7 +640,7 @@ export function registerBrowserSessionRoutes(
           }
         },
       );
-      const parsed = BrowserSessionMutationResponse.parse(response);
+      const parsed = BrowserSessionMutationResponse.parse(withInitialView(response, launch.result));
       observeLifecycleResult(deps.observability, startedAtMs, parsed);
       reportInteractionRouteStages(context, deps.observability, stages);
       return context.json(
@@ -2612,6 +2638,217 @@ export function registerBrowserSessionRoutes(
     },
   );
 
+  /** Run one working-copy request against an active browser's own controller
+   * generation, with the same session.control and placement authority as any
+   * browser control. The controller binds every request to the exact
+   * controller authority the copy was launched under. Never replayed. */
+  async function withPreservedWorkingCopy<T>(
+    context: Context,
+    callback: (input: {
+      grant: AccessGrant;
+      workspaceId: string;
+      browserSessionId: string;
+      client: BrowserControlClient;
+      authority: PlacementBrowserWorkingCopyAuthority;
+    }) => Promise<T>,
+  ): Promise<T> {
+    const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+      context,
+      "sessions:control",
+    );
+    return await withActiveBrowserController(
+      context,
+      grant,
+      workspaceId,
+      browserSessionId,
+      "session.control",
+      "browser.control",
+      async ({ client, record, binding, placement }) => {
+        const transport = browserRuntimeTransport(record.session, placement.transport);
+        if (
+          transport.kind !== "managed" ||
+          transport.engine !== "chromium" ||
+          transport.ephemeralPartition ||
+          browserSessionStorageMode(record.session) !== "private_profile"
+        ) {
+          throw new BrowserSessionStateError(WORKING_COPY_REFUSAL_EXPLANATIONS.unsupported_browser);
+        }
+        const tokens = deriveBrowserSessionControllerTokens({
+          rootSecret: browserAuthorityRoot(deps),
+          accountId: grant.accountId,
+          workspaceId,
+          placement: record.session.placement,
+          placementInstanceId: placement.placementInstanceId,
+          browserSessionId,
+          controllerGeneration: binding.controllerGeneration,
+          tokenGeneration: record.tokenGeneration,
+        });
+        return await callback({
+          grant,
+          workspaceId,
+          browserSessionId,
+          client,
+          authority: {
+            browserSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            tokenGeneration: record.tokenGeneration,
+            ...tokens,
+          },
+        });
+      },
+      // A missing controller session is the state being inspected; never
+      // launch anything to "recover" it here.
+      false,
+    );
+  }
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/working-copy/inspection",
+    async (context) => {
+      await parseEmptyJsonBody(context);
+      const result = await withPreservedWorkingCopy(
+        context,
+        async ({ grant, workspaceId, browserSessionId, client, authority }) => {
+          const inspection = await client.inspectWorkingCopy(authority);
+          const checkpoint = await getBrowserPrivateCheckpointAuthority(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+          }).catch(() => null);
+          return BrowserWorkingCopyInspection.parse({
+            browserSessionId,
+            controllerGeneration: authority.controllerGeneration,
+            adoptable: inspection.refusal === null && inspection.manifest !== null,
+            refusal: inspection.refusal,
+            explanation: workingCopyInspectionExplanation(
+              inspection,
+              checkpoint?.createdAt ?? null,
+            ),
+            manifest: inspection.manifest,
+            platformSupported: inspection.platformSupported,
+            profileIdentityMatches: inspection.profileIdentityMatches,
+            profileInUse: inspection.profileInUse,
+            receipt: inspection.receipt,
+            freshness: { status: "unknown", latestCheckpointAt: checkpoint?.createdAt ?? null },
+            activeAdoption: inspection.activeAdoption,
+          });
+        },
+      );
+      return context.json(result);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/working-copy/adoptions",
+    async (context) => {
+      const request = await parseJsonBody(context, BrowserWorkingCopyAdoptionRequest);
+      const result = await withPreservedWorkingCopy(
+        context,
+        async ({ grant, workspaceId, browserSessionId, client, authority }) => {
+          // Durable attribution before any effect: who selected which exact
+          // bytes as this browser's state. Freshness stays unproven.
+          await recordAuditEvent(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            action: "browserSession.working_copy.adoption_requested",
+            targetType: "browser_session",
+            targetId: browserSessionId,
+            metadata: {
+              operationId: request.operationId,
+              manifestDigest: request.manifestDigest,
+              controllerGeneration: authority.controllerGeneration,
+            },
+          });
+          const adoption = await client.adoptWorkingCopy({
+            ...authority,
+            operationId: request.operationId,
+            manifestDigest: request.manifestDigest,
+          });
+          await recordAuditEvent(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            action: "browserSession.working_copy.adoption_settled",
+            targetType: "browser_session",
+            targetId: browserSessionId,
+            metadata: {
+              operationId: adoption.operationId,
+              manifestDigest: adoption.manifestDigest,
+              controllerGeneration: adoption.controllerGeneration,
+              phase: adoption.phase,
+              failureCode: adoption.failureCode,
+            },
+          }).catch(() => undefined);
+          return BrowserWorkingCopyAdoptionResponse.parse({
+            inFlight: false,
+            adoption: publicWorkingCopyAdoption(adoption),
+            explanation: workingCopyAdoptionExplanation(false, adoption),
+          });
+        },
+      );
+      return context.json(result);
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/working-copy/adoptions/:operationId",
+    async (context) => {
+      const operationId = requireUuidParam(context, "operationId");
+      const result = await withPreservedWorkingCopy(context, async ({ client, authority }) => {
+        const status = await client.workingCopyAdoption(authority, operationId);
+        return BrowserWorkingCopyAdoptionResponse.parse({
+          inFlight: status.inFlight,
+          adoption: status.adoption ? publicWorkingCopyAdoption(status.adoption) : null,
+          explanation: workingCopyAdoptionExplanation(status.inFlight, status.adoption),
+        });
+      });
+      return context.json(result);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/working-copy/adoptions/:operationId/revert",
+    async (context) => {
+      const operationId = requireUuidParam(context, "operationId");
+      const result = await withPreservedWorkingCopy(
+        context,
+        async ({ grant, workspaceId, browserSessionId, client, authority }) => {
+          await recordAuditEvent(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            action: "browserSession.working_copy.revert_requested",
+            targetType: "browser_session",
+            targetId: browserSessionId,
+            metadata: { operationId, controllerGeneration: authority.controllerGeneration },
+          });
+          const status = await client.revertWorkingCopyAdoption({ ...authority, operationId });
+          await recordAuditEvent(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            action: "browserSession.working_copy.revert_settled",
+            targetType: "browser_session",
+            targetId: browserSessionId,
+            metadata: {
+              operationId,
+              controllerGeneration: authority.controllerGeneration,
+              phase: status.adoption?.phase ?? null,
+              failureCode: status.adoption?.failureCode ?? null,
+            },
+          }).catch(() => undefined);
+          return BrowserWorkingCopyAdoptionResponse.parse({
+            inFlight: status.inFlight,
+            adoption: status.adoption ? publicWorkingCopyAdoption(status.adoption) : null,
+            explanation: workingCopyAdoptionExplanation(status.inFlight, status.adoption),
+          });
+        },
+      );
+      return context.json(result);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/end",
     async (context) => {
@@ -4457,6 +4694,34 @@ function requireOperationGeneration(record: BrowserSessionControlRecord): string
   return generation;
 }
 
+/** Attach the controller's launch view to a create that activated exactly that
+ * launch in this request. Replays, failures and other bindings get nothing, so
+ * a caller then reads the targets and observes as before. */
+export function withInitialView<
+  T extends {
+    session: { id: string; lifecycle: string; controller: { controllerGeneration: string } | null };
+    operation: { state: string; replayed: boolean };
+  },
+>(
+  response: T,
+  launched: Awaited<ReturnType<BrowserControlClient["createSession"]>> | null,
+): T | (T & { initialView: { targets: BrowserTarget[]; observation: BrowserObservation } }) {
+  if (
+    !launched?.targets ||
+    response.operation.state !== "completed" ||
+    response.operation.replayed ||
+    response.session.lifecycle !== "active" ||
+    response.session.id !== launched.browserSessionId ||
+    response.session.controller?.controllerGeneration !== launched.controllerGeneration
+  ) {
+    return response;
+  }
+  return {
+    ...response,
+    initialView: { targets: launched.targets, observation: launched.observation },
+  };
+}
+
 async function provisionController(
   deps: ApiRouteDeps,
   grant: AccessGrant,
@@ -5376,6 +5641,91 @@ function recordAttachedBrowserUnavailable(
   }
 }
 
+const WORKING_COPY_REFUSAL_EXPLANATIONS: Record<BrowserWorkingCopyRefusalValue, string> = {
+  unsupported_platform:
+    "Adopting a working copy is supported only for browsers on Linux machines, where the controller can prove no process uses the copy. Nothing was changed.",
+  unsupported_browser:
+    "Only a managed Chromium browser with a private profile keeps a working copy that can be adopted. Nothing was changed.",
+  browser_running:
+    "The browser is running, starting or being ended on its controller, so there is no stopped working copy to adopt now. If it is running, use it normally; otherwise inspect again once it has stopped.",
+  working_copy_invalid:
+    "The browser's working directory on its machine is missing, incomplete or not a plain directory, so it cannot be adopted. Nothing was changed.",
+  receipt_not_adoptable:
+    "The working copy has no completed record of a browser launch, so it cannot be adopted. Its record and recovery state are preserved.",
+  authority_changed:
+    "The working copy was launched under a different controller authority than this browser now has, so it cannot be adopted for it. Nothing was changed.",
+  process_state_unknown:
+    "It cannot be proven that no process uses the copy's browser profile. Close any browser using it, then inspect again. Nothing was changed.",
+  adoption_not_needed:
+    "The working copy is the same directory the browser was launched in, so it needs no adoption; the browser continues from it when it is next used.",
+  adoption_unresolved:
+    "An earlier adoption for this browser has not finished. Check it with getBrowserSessionWorkingCopyAdoption and its operation id (see activeAdoption). Inspecting and checking never change it; retrying that same adoption with the same operationId and manifestDigest settles it. Do not start another.",
+};
+
+function workingCopyInspectionExplanation(
+  inspection: PlacementBrowserWorkingCopyInspection,
+  latestCheckpointAt: string | null,
+): string {
+  if (inspection.refusal) return WORKING_COPY_REFUSAL_EXPLANATIONS[inspection.refusal];
+  const manifest = inspection.manifest!;
+  return [
+    `This working copy can be adopted: ${manifest.entries} entries, ${manifest.bytes} bytes, manifest digest ${manifest.digest}.`,
+    manifest.excluded.length > 0
+      ? `Left out because the controller rebuilds them: ${manifest.excluded.join(", ")}. Everything else is in the digest.`
+      : "Every entry is in the digest.",
+    "It is not the directory the browser was launched in (it was moved, copied or restored), so the browser refuses to continue from it until it is adopted.",
+    latestCheckpointAt
+      ? `How recent its contents are is not proven; the browser's latest saved checkpoint is from ${latestCheckpointAt}.`
+      : "How recent its contents are is not proven.",
+    "Adopting selects exactly these bytes as the browser's state and is never replaced by an older checkpoint afterwards; the directory it replaces is kept.",
+    "To adopt, call adoptBrowserSessionWorkingCopy with this manifestDigest and a new operationId. If the bytes change first, the adoption is refused.",
+  ].join(" ");
+}
+
+function publicWorkingCopyAdoption(
+  adoption: PlacementBrowserWorkingCopyAdoption,
+): BrowserWorkingCopyAdoptionValue {
+  return {
+    operationId: adoption.operationId,
+    browserSessionId: adoption.browserSessionId,
+    controllerGeneration: adoption.controllerGeneration,
+    manifestDigest: adoption.manifestDigest,
+    phase: adoption.phase,
+    failureCode: adoption.failureCode,
+    retainedDirectories: adoption.retainedDirectories,
+    createdAt: adoption.createdAt,
+    updatedAt: adoption.updatedAt,
+  };
+}
+
+function workingCopyAdoptionExplanation(
+  inFlight: boolean,
+  adoption: PlacementBrowserWorkingCopyAdoption | null,
+): string {
+  const kept = adoption?.retainedDirectories.length
+    ? ` Kept on the machine for separate cleanup: ${adoption.retainedDirectories.join(", ")}.`
+    : "";
+  if (inFlight)
+    return "The adoption is still running on the controller. Check again with getBrowserSessionWorkingCopyAdoption; do not start another.";
+  if (!adoption)
+    return "The controller has no record of this adoption, which proves it changed nothing there.";
+  switch (adoption.phase) {
+    case "adopted":
+      return `Adopted. The browser continues from the copy with manifest digest ${adoption.manifestDigest} the next time it is used, and is never replaced by an older checkpoint.${kept}`;
+    case "interrupted":
+    case "failed":
+      return `The adoption stopped before the copy took the browser's place${adoption.failureCode ? ` (${adoption.failureCode})` : ""}; the browser's own directory is unchanged.${kept}`;
+    case "collision":
+      return `The adoption found the browser's directories in an unexpected state (${adoption.failureCode ?? "unknown"}) and stopped without moving or removing anything more. The browser stays unavailable until this adoption is reverted with revertBrowserSessionWorkingCopyAdoption, which puts the browser's own directory back and keeps the staged copy. If the revert refuses, the directories need a person on that machine.${kept}`;
+    case "reverting":
+      return "A revert of this adoption stopped part way and is not running. Retry revertBrowserSessionWorkingCopyAdoption with the same operationId to finish it; a retry repeats nothing already done.";
+    case "reverted":
+      return `Reverted. The browser's own directory is back in place and the staged copy was not used.${kept}`;
+    default:
+      return "The adoption stopped part way and is not running. Checking it never changes it. To finish it, retry the same adoption with the same operationId and manifestDigest under the authority that approved it; a retry repeats nothing already done. To undo it instead, revert it with revertBrowserSessionWorkingCopyAdoption. Do not start another.";
+  }
+}
+
 function browserRouteError(error: unknown): HTTPException {
   const tabDiagnosis = browserTabDiagnosisError(error);
   if (tabDiagnosis instanceof ApiHttpError) return tabDiagnosis;

package/src/routes/organization-memberships.ts

@@ -247,6 +247,18 @@ function parseId(schema: z.ZodString, value: string, label: string): string {
 
 function rethrowMembershipError(error: unknown, resourceLimitMessage?: string): never {
   const sqlState = nestedPostgresSqlState(error);
+  if (sqlState === "P0S01") {
+    throw new HTTPException(402, {
+      res: Response.json(
+        {
+          error: "seat_limit_reached",
+          message: "Organization seat limit reached. Upgrade your plan to add people.",
+          action: { type: "upgrade", href: "/billing" },
+        },
+        { status: 402 },
+      ),
+    });
+  }
   if (sqlState === "54000" && resourceLimitMessage) {
     throw new HTTPException(409, {
       message: resourceLimitMessage,

package/src/routes/sessions.ts

@@ -1004,6 +1004,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           ...(query.includeTotals ? { includeTotals: true } : {}),
           ...(query.needsYouOnly ? { needsYouOnly: true } : {}),
           ...(query.contentArchivedOnly ? { contentArchivedOnly: true } : {}),
+          ...(query.mineOnly ? { mineOnly: true } : {}),
           ...(query.includePinned === false ? { includePinned: false } : {}),
           ...(query.archivedOnly ? { archivedOnly: true } : {}),
           ...(query.sortBy ? { sortBy: query.sortBy } : {}),
@@ -5835,6 +5836,7 @@ export function sessionListQuery(
   includeTotals: boolean;
   needsYouOnly: boolean;
   contentArchivedOnly: boolean;
+  mineOnly: boolean;
   archivedOnly: boolean;
   sortBy: "updatedAt" | "createdAt" | "name" | undefined;
   archiveStatus: "active" | "archived" | "all" | undefined;
@@ -5884,17 +5886,20 @@ export function sessionListQuery(
     throw new HTTPException(400, { message: 'includePinned must be "true" or "false"' });
   }
   const includePinned = query.includePinned !== "false";
-  for (const key of ["includeTotals", "needsYouOnly", "contentArchivedOnly"]) {
+  for (const key of ["includeTotals", "needsYouOnly", "contentArchivedOnly", "mineOnly"]) {
     if (query[key] !== undefined && !["true", "false"].includes(query[key]!))
       throw new HTTPException(400, { message: `${key} must be "true" or "false"` });
   }
   const includeTotals = query.includeTotals === "true";
   const needsYouOnly = query.needsYouOnly === "true";
   const contentArchivedOnly = query.contentArchivedOnly === "true";
+  const mineOnly = query.mineOnly === "true";
   if (includeTotals && (!allowCursor || (parentSessionId !== "null" && !pinsOnly)))
     throw new HTTPException(400, { message: "includeTotals requires a root page" });
   if (needsYouOnly && !allowCursor)
     throw new HTTPException(400, { message: 'needsYouOnly requires view="page"' });
+  if (mineOnly && !allowCursor)
+    throw new HTTPException(400, { message: 'mineOnly requires view="page"' });
   if (pinsOnly && !includePinned) {
     throw new HTTPException(400, { message: "pinsOnly requires includePinned" });
   }
@@ -5990,6 +5995,7 @@ export function sessionListQuery(
   const hasPageFilters =
     needsYouOnly ||
     contentArchivedOnly ||
+    mineOnly ||
     originSiteId !== undefined ||
     channelId !== undefined ||
     createdByKind !== undefined ||
@@ -6025,6 +6031,7 @@ export function sessionListQuery(
     includeTotals,
     needsYouOnly,
     contentArchivedOnly,
+    mineOnly,
     archivedOnly,
     sortBy: sortBy.data,
     archiveStatus: archiveStatus.data,