@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/install.ts

@@ -44,15 +44,34 @@ const BAKED_DIR = new URL("baked/", INSTALL_DIR);
 // The static text artifacts served verbatim, with their content types. Each is
 // read once at first request and memoized (committed files; immutable per deploy).
 const TEXT_ASSETS: Record<string, { file: string; contentType: string }> = {
-  "/install.sh": { file: "install.sh", contentType: "text/x-shellscript; charset=utf-8" },
-  "/install.ps1": { file: "install.ps1", contentType: "text/plain; charset=utf-8" },
-  "/uninstall.sh": { file: "uninstall.sh", contentType: "text/x-shellscript; charset=utf-8" },
+  "/install.sh": {
+    file: "install.sh",
+    contentType: "text/x-shellscript; charset=utf-8",
+  },
+  "/install.ps1": {
+    file: "install.ps1",
+    contentType: "text/plain; charset=utf-8",
+  },
+  "/uninstall.sh": {
+    file: "uninstall.sh",
+    contentType: "text/x-shellscript; charset=utf-8",
+  },
   "/opengeni-agent-minisign.pub": {
     file: "opengeni-agent-minisign.pub",
     contentType: "text/plain; charset=utf-8",
   },
 };
 
+// Non-executable resources needed to assemble a complete platform bundle. These
+// stay committed beside the installer rather than depending on a release/CDN so
+// an exact-SHA local or private deployment remains self-contained.
+const COMMITTED_BINARY_ASSETS: Record<string, { file: string; contentType: string }> = {
+  "OpenGeni-Agent.icns": {
+    file: "OpenGeni-Agent.icns",
+    contentType: "image/icns",
+  },
+};
+
 const assetCache = new Map<string, string>();
 
 async function loadAsset(file: string): Promise<string> {
@@ -73,26 +92,40 @@ async function loadAsset(file: string): Promise<string> {
 // `curl https://<this-host>/install.sh | sh` installs the exact agent that
 // matches the API it enrolls against, with NO dependency on a public CDN (which a
 // private/air-gapped deploy may not even resolve). When a public base URL is
-// configured we therefore rewrite each script's default-base-URL marker line to
-// that origin before serving. The user's OPENGENI_INSTALL_BASE_URL env override
-// still wins at run time (the scripts use `:-default`); only the built-in DEFAULT
-// changes. The marker lines are kept shape-stable in agent/install/install.{sh,ps1}.
-const DEFAULT_BASE_REWRITES: Record<string, (base: string) => { from: string; to: string }> = {
-  "install.sh": (base) => ({
-    from: 'OPENGENI_INSTALL_DEFAULT_BASE_URL="https://get.opengeni.ai"',
-    to: `OPENGENI_INSTALL_DEFAULT_BASE_URL="${base}"`,
-  }),
-  "install.ps1": (base) => ({
-    from: "$OpengeniInstallDefaultBaseUrl = 'https://get.opengeni.ai'",
-    to: `$OpengeniInstallDefaultBaseUrl = '${base}'`,
-  }),
+// configured we therefore rewrite each script's release-asset AND connection-API
+// default markers to that origin before serving. The user's
+// OPENGENI_INSTALL_BASE_URL / OPENGENI_API_URL overrides still win at run time;
+// only the built-in defaults change. The marker lines are kept shape-stable in
+// agent/install/install.{sh,ps1}.
+type DefaultRewrite = { from: string; to: string };
+
+const DEFAULT_BASE_REWRITES: Record<string, (base: string) => DefaultRewrite[]> = {
+  "install.sh": (base) => [
+    {
+      from: 'OPENGENI_INSTALL_DEFAULT_BASE_URL="https://get.opengeni.ai"',
+      to: `OPENGENI_INSTALL_DEFAULT_BASE_URL="${base}"`,
+    },
+    {
+      from: 'OPENGENI_API_DEFAULT_URL="https://app.opengeni.ai"',
+      to: `OPENGENI_API_DEFAULT_URL="${base}"`,
+    },
+  ],
+  "install.ps1": (base) => [
+    {
+      from: "$OpengeniInstallDefaultBaseUrl = 'https://get.opengeni.ai'",
+      to: `$OpengeniInstallDefaultBaseUrl = '${base}'`,
+    },
+    {
+      from: "$OpengeniApiDefaultUrl = 'https://app.opengeni.ai'",
+      to: `$OpengeniApiDefaultUrl = '${base}'`,
+    },
+  ],
 };
 
-// Rewrite a served script's default release-asset base URL to this deployment's
-// own public origin. A no-op when no public base URL is configured (the public
-// archive default stands), when the URL is not absolute http(s) (never serve a
-// script with a broken base), or when the file has no marker (script drift — fail
-// safe to serving it verbatim rather than crashing the install surface).
+// Rewrite a served script's default release-asset and connection-API URLs to this
+// deployment's own public origin. A no-op when no public base URL is configured,
+// when the URL is not absolute http(s), or when either marker is absent (script
+// drift — fail safe to serving it verbatim rather than splitting the two origins).
 function rewriteDefaultBaseUrl(
   file: string,
   body: string,
@@ -102,11 +135,11 @@ function rewriteDefaultBaseUrl(
     return body;
   }
   const base = publicBaseUrl.replace(/\/+$/, "");
-  const rule = DEFAULT_BASE_REWRITES[file]?.(base);
-  if (!rule || !body.includes(rule.from)) {
+  const rules = DEFAULT_BASE_REWRITES[file]?.(base);
+  if (!rules || rules.some((rule) => !body.includes(rule.from))) {
     return body;
   }
-  return body.replace(rule.from, rule.to);
+  return rules.reduce((rewritten, rule) => rewritten.replace(rule.from, rule.to), body);
 }
 
 // The content type for a baked release asset. The binary is an
@@ -125,18 +158,53 @@ function bakedContentType(asset: string): string {
 // BAKED_DIR is a fixed sibling, so the resolved path cannot escape the dir.
 async function readBaked(asset: string): Promise<ArrayBuffer | null> {
   const url = new URL(asset, BAKED_DIR);
-  try {
-    const info = await stat(url);
-    if (!info.isFile()) {
+  const runtime =
+    /^(?:opengeni-agent-browser|opengeni-computer-native|opengeni-browserd|opengeni-agent)-(.+?)(?:\.(?:sha256|minisig))?$/.exec(
+      asset,
+    );
+  if (runtime) {
+    const target = runtime[1]!;
+    const cohort = [
+      "opengeni-agent",
+      "opengeni-browserd",
+      "opengeni-agent-browser",
+      "opengeni-computer-native",
+    ].flatMap((component) =>
+      ["", ".sha256", ".minisig"].map((suffix) => `${component}-${target}${suffix}`),
+    );
+    const members = await Promise.all(
+      cohort.map(async (name) => {
+        try {
+          const info = await stat(new URL(name, BAKED_DIR));
+          return info.isFile() && info.size > 0 ? "complete" : "invalid";
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+          throw new HTTPException(503, { message: "baked interaction runtime is unavailable" });
+        }
+      }),
+    );
+    // A target is either wholly absent or wholly baked. A partial image cannot
+    // combine its agent with helpers or verification sidecars from an archive.
+    if (members.every((member) => member === "absent")) return null;
+    if (members.some((member) => member !== "complete")) {
+      throw new HTTPException(503, { message: "baked interaction runtime is incomplete" });
+    }
+  } else {
+    try {
+      const info = await stat(url);
+      if (!info.isFile()) return null;
+    } catch {
       return null;
     }
-  } catch {
-    return null;
   }
   // Return a standalone ArrayBuffer (a valid Response BodyInit). `readFile`'s
   // Buffer may be a view into a larger pooled allocation, so copy out the exact
   // byte range with `.slice` rather than handing over the backing store.
-  const buf = await readFile(url);
+  const buf = await readFile(url).catch(() => {
+    // Never redirect after selecting a baked cohort, even if a file becomes
+    // unreadable between the completeness check and the byte read.
+    throw new HTTPException(503, { message: "baked interaction runtime is unavailable" });
+  });
   return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
 
@@ -172,8 +240,24 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
   // otherwise 302 to the GitHub Release at `redirectUrl` (mac/windows + any
   // un-baked asset). The baked path makes the agent the API enrolls against
   // identical to the API that serves it — no version skew, no extra hop.
-  async function serveAsset(asset: string, redirectUrl: string): Promise<Response> {
-    const baked = await readBaked(asset);
+  async function serveAsset(
+    asset: string,
+    redirectUrl: string,
+    allowBaked: boolean,
+  ): Promise<Response> {
+    const committed = COMMITTED_BINARY_ASSETS[asset];
+    if (committed) {
+      const buf = await readFile(new URL(committed.file, INSTALL_DIR));
+      return new Response(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength), {
+        status: 200,
+        headers: {
+          "content-type": committed.contentType,
+          "cache-control": "public, max-age=3600",
+          "x-opengeni-agent-source": "committed",
+        },
+      });
+    }
+    const baked = allowBaked ? await readBaked(asset) : null;
     if (baked !== null) {
       return new Response(baked, {
         status: 200,
@@ -189,7 +273,10 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
     // Not baked here → the GitHub Release is the source of truth (the public
     // archive + the documented install.sh fallback). 302 so the client refetches.
-    return new Response(null, { status: 302, headers: { location: redirectUrl } });
+    return new Response(null, {
+      status: 302,
+      headers: { location: redirectUrl },
+    });
   }
 
   // `latest` → the BAKED binary if present, else the operator-selected immutable
@@ -203,7 +290,7 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!ASSET_NAME.test(asset)) {
       throw new HTTPException(400, { message: "invalid asset name" });
     }
-    return serveAsset(asset, `${releasesBase}/download/${stableAgentTag}/${asset}`);
+    return serveAsset(asset, `${releasesBase}/download/${stableAgentTag}/${asset}`, true);
   });
 
   // Signed self-update channel manifests. Each deployment exposes its own
@@ -217,10 +304,14 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     app.get(`/agent/${channel}/:manifestAsset`, (c) => {
       const manifestAsset = c.req.param("manifestAsset");
       if (manifestAsset !== "manifest.json" && manifestAsset !== "manifest.json.minisig") {
-        throw new HTTPException(404, { message: "update manifest asset not found" });
+        throw new HTTPException(404, {
+          message: "update manifest asset not found",
+        });
       }
       if (!version) {
-        throw new HTTPException(404, { message: `${channel} agent channel is not configured` });
+        throw new HTTPException(404, {
+          message: `${channel} agent channel is not configured`,
+        });
       }
       return new Response(null, {
         status: 302,
@@ -240,9 +331,13 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     // `/agent/latest/<asset>` is handled by the more specific route above; any
     // other version segment must be the `v<ver>` shape.
     if (!VERSION_SEG.test(versionSeg) || !ASSET_NAME.test(asset)) {
-      throw new HTTPException(400, { message: "invalid version or asset name" });
+      throw new HTTPException(400, {
+        message: "invalid version or asset name",
+      });
     }
-    return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`);
+    // A pinned release must never be substituted with this deployment's baked
+    // canary, even when its semver happens to match. The archive owns its bytes.
+    return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`, false);
   });
 }
 

package/src/routes/integration-facets.ts

@@ -1,10 +1,13 @@
 import {
+  assertOrganizationIntegrationAllowed,
   IntegrationFacetMutationResult,
   IntegrationFacetRemovalResult,
   IntegrationInstanceFacetsResponse,
   MutateIntegrationFacetRequest,
   UpsertIntegrationFacetRequest,
 } from "@opengeni/contracts";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import { CORE_INTEGRATION_DEFINITIONS } from "@opengeni/capabilities";
 import {
   hasPermission,
   requireAccessGrant,
@@ -13,6 +16,7 @@ import {
 } from "@opengeni/core";
 import {
   configureIntegrationFacet,
+  integrationFacetConfigureRequestDigest,
   IntegrationFacetBindingOwnershipConflictError,
   IntegrationFacetBindingVersionConflictError,
   IntegrationFacetBindingVersionRequiredError,
@@ -22,7 +26,9 @@ import {
   IntegrationFacetOperationIdempotencyError,
   listIntegrationInstanceFacets,
   removeIntegrationFacet,
+  replayCompletedIntegrationFacetOperation,
   setIntegrationFacetLifecycle,
+  type IntegrationFacetAcquisitionAuthorizer,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -31,6 +37,7 @@ import {
   browseGoogleDriveFacetSource,
   saveGoogleDriveFacetSource,
 } from "../integrations/google-drive";
+import { parseRequestJson } from "../http/request-body";
 
 export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get(
@@ -64,7 +71,7 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
         c,
         deps,
         workspaceId,
-        "workspace:admin",
+        "capabilities:manage",
       );
       const { grant } = authorization;
       try {
@@ -80,7 +87,10 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
               payload: await c.req.json(),
               canManageOrganizationDestination:
                 authorization.accountGrant?.permissions.includes("account:admin") === true,
-              canManageWorkspaceDestination: hasPermission(grant.permissions, "workspace:admin"),
+              canManageWorkspaceDestination: hasPermission(
+                grant.permissions,
+                "capabilities:manage",
+              ),
               canManagePersonalDestination:
                 authorization.contextIntegrity &&
                 authorization.authenticatedSubjectId === grant.subjectId,
@@ -120,12 +130,39 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
     "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-      const payload = UpsertIntegrationFacetRequest.parse(await c.req.json());
+      const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+      const payload = await parseRequestJson(c, UpsertIntegrationFacetRequest);
       const capabilityId = decoded(c.req.param("capabilityId"));
       const instanceKey = decoded(c.req.param("instanceKey"));
       const facetKey = decoded(c.req.param("facetKey"));
       try {
+        const replayed =
+          await replayCompletedIntegrationFacetOperation<IntegrationFacetMutationResult>(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            capabilityId,
+            instanceKey,
+            facetKey,
+            idempotencyKey: payload.idempotencyKey,
+            kind: "configure",
+            expectedRequestDigest: integrationFacetConfigureRequestDigest({
+              capabilityId,
+              instanceKey,
+              facetKey,
+              displayName: payload.displayName,
+              config: payload.config,
+              ...(payload.expectedVersion !== undefined
+                ? { expectedVersion: payload.expectedVersion }
+                : {}),
+            }),
+          });
+        if (replayed) {
+          return c.json(
+            IntegrationFacetMutationResult.parse(replayed),
+            payload.expectedVersion === undefined ? 201 : 200,
+          );
+        }
         const instance = await listIntegrationInstanceFacets(
           deps.db,
           workspaceId,
@@ -147,20 +184,30 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
         }
         return c.json(
           IntegrationFacetMutationResult.parse(
-            await configureIntegrationFacet(deps.db, {
-              accountId: grant.accountId,
-              workspaceId,
-              subjectId: grant.subjectId,
-              capabilityId,
-              instanceKey,
-              facetKey,
-              displayName: payload.displayName,
-              config: payload.config,
-              ...(payload.expectedVersion !== undefined
-                ? { expectedVersion: payload.expectedVersion }
-                : {}),
-              idempotencyKey: payload.idempotencyKey,
-            }),
+            await withOrganizationIntegrationPolicyFence(
+              deps.db,
+              { accountId: grant.accountId, workspaceId },
+              (tx, policy) =>
+                configureIntegrationFacet(tx, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  subjectId: grant.subjectId,
+                  capabilityId,
+                  instanceKey,
+                  facetKey,
+                  displayName: payload.displayName,
+                  config: payload.config,
+                  ...(payload.expectedVersion !== undefined
+                    ? { expectedVersion: payload.expectedVersion }
+                    : {}),
+                  idempotencyKey: payload.idempotencyKey,
+                  beforeAcquire: async (_db, context) =>
+                    assertOrganizationIntegrationAllowed(
+                      policy,
+                      installedFacetIntegrationKey(context),
+                    ),
+                }),
+            ),
           ),
           payload.expectedVersion === undefined ? 201 : 200,
         );
@@ -175,22 +222,32 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
       `/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/${action}`,
       async (c) => {
         const workspaceId = c.req.param("workspaceId");
-        const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-        const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+        const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+        const payload = await parseRequestJson(c, MutateIntegrationFacetRequest);
         try {
           return c.json(
             IntegrationFacetMutationResult.parse(
-              await setIntegrationFacetLifecycle(deps.db, {
-                accountId: grant.accountId,
-                workspaceId,
-                subjectId: grant.subjectId,
-                capabilityId: decoded(c.req.param("capabilityId")),
-                instanceKey: decoded(c.req.param("instanceKey")),
-                facetKey: decoded(c.req.param("facetKey")),
-                action,
-                expectedVersion: payload.expectedVersion,
-                idempotencyKey: payload.idempotencyKey,
-              }),
+              await withOrganizationIntegrationPolicyFence(
+                deps.db,
+                { accountId: grant.accountId, workspaceId },
+                (tx, policy) =>
+                  setIntegrationFacetLifecycle(tx, {
+                    accountId: grant.accountId,
+                    workspaceId,
+                    subjectId: grant.subjectId,
+                    capabilityId: decoded(c.req.param("capabilityId")),
+                    instanceKey: decoded(c.req.param("instanceKey")),
+                    facetKey: decoded(c.req.param("facetKey")),
+                    action,
+                    expectedVersion: payload.expectedVersion,
+                    idempotencyKey: payload.idempotencyKey,
+                    beforeAcquire: async (_db, context) =>
+                      assertOrganizationIntegrationAllowed(
+                        policy,
+                        installedFacetIntegrationKey(context),
+                      ),
+                  }),
+              ),
             ),
           );
         } catch (error) {
@@ -204,8 +261,8 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
     "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-      const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+      const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+      const payload = await parseRequestJson(c, MutateIntegrationFacetRequest);
       try {
         return c.json(
           IntegrationFacetRemovalResult.parse(
@@ -232,6 +289,23 @@ function decoded(value: string): string {
   return decodeURIComponent(value);
 }
 
+/** The DB context comes from the matching installed API facet and immutable
+ * server-authored version manifest, never request metadata or a provider domain.
+ */
+function installedFacetIntegrationKey(
+  context: Parameters<IntegrationFacetAcquisitionAuthorizer>[1],
+): string | null {
+  if (context.apiProtocol !== "openapi" && context.apiProtocol !== "graphql") return null;
+  if (context.definitionProvenance === "workspace") return `custom:${context.apiProtocol}`;
+  if (
+    context.definitionProvenance === "curated" &&
+    CORE_INTEGRATION_DEFINITIONS.some((definition) => definition.id === context.definitionId)
+  ) {
+    return context.definitionId;
+  }
+  return null;
+}
+
 function facetHttpError(error: unknown): HTTPException {
   if (error instanceof HTTPException) return error;
   if (error instanceof IntegrationFacetNotFoundError) {

package/src/routes/interaction-resources.ts

@@ -45,9 +45,12 @@ import {
   updateSiteAuthConnection,
 } from "@opengeni/db";
 import {
+  getManagedAuthRequestActorEpoch,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   requireAccessGrant,
+  requireFreshAccessGrant,
+  requirePermission,
   requireSessionAuthorization,
   type ApiRouteDeps,
   workflowIdForSession,
@@ -55,7 +58,11 @@ import {
 import { publishDurableSessionEvents } from "@opengeni/events";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { sseWorkspaceInteractionRevisionStream, sseWorkspaceLiveStream } from "../http/sse";
+import {
+  browserSseDeliveryOptions,
+  sseWorkspaceInteractionRevisionStream,
+  sseWorkspaceLiveStream,
+} from "../http/sse";
 import { observeInterventionMutation } from "../interaction-metrics";
 
 export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps): void {
@@ -70,7 +77,20 @@ export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps)
       nonnegativeSafeIntegerQuery(context, "controlAfter", 0),
       nonnegativeSafeIntegerQuery(context, "interactionAfter", 0),
       context.req.raw.signal,
-      { observability: deps.observability },
+      {
+        ...browserSseDeliveryOptions(context.req.query("transport")),
+        observability: deps.observability,
+        actorEpoch: getManagedAuthRequestActorEpoch(context.req.raw) ?? undefined,
+        reauthorize: async () => {
+          const freshGrant = await requireFreshAccessGrant(
+            context,
+            deps,
+            workspaceId,
+            "sessions:read",
+          );
+          requirePermission(freshGrant, "workspace:read");
+        },
+      },
     );
   });
 
@@ -83,7 +103,14 @@ export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps)
       workspaceId,
       after,
       context.req.raw.signal,
-      { observability: deps.observability },
+      {
+        ...browserSseDeliveryOptions(context.req.query("transport")),
+        observability: deps.observability,
+        actorEpoch: getManagedAuthRequestActorEpoch(context.req.raw) ?? undefined,
+        reauthorize: async () => {
+          await requireFreshAccessGrant(context, deps, workspaceId, "sessions:read");
+        },
+      },
     );
   });