@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/organization-service-accounts.ts

@@ -0,0 +1,128 @@
+import { zValidator } from "@hono/zod-validator";
+import {
+  CreateOrganizationServiceAccountRequest,
+  ListOrganizationServiceAccountsResponse,
+  OrganizationServiceAccount,
+  UpdateOrganizationServiceAccountRequest,
+  type AccessContext,
+} from "@opengeni/contracts";
+import { requireAccessContext, type ApiRouteDeps } from "@opengeni/core";
+import {
+  createOrganizationServiceAccount,
+  deleteOrganizationServiceAccount,
+  getOrganizationServiceAccount,
+  listOrganizationServiceAccounts,
+  updateOrganizationServiceAccount,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+import { requireOrganizationApiKeyControlPermission, throwServiceAccountError } from "./api-keys";
+
+/* ----------------------------------------------------------------------------
+   Service accounts: organization identities with no person behind them. They
+   hold organization API keys. Whoever may manage the organization's keys may
+   manage service accounts; only an organization administrator can make one an
+   admin. Deleting one revokes its keys at once.
+   -------------------------------------------------------------------------- */
+
+const Id = z.string().uuid();
+
+export function registerOrganizationServiceAccountRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const path = "/v1/organizations/:organizationId/service-accounts";
+
+  app.get(path, async (c) => {
+    const { organizationId } = await requireControl(c, deps);
+    c.header("cache-control", "no-store");
+    return c.json(
+      ListOrganizationServiceAccountsResponse.parse({
+        serviceAccounts: await listOrganizationServiceAccounts(deps.db, organizationId),
+      }),
+    );
+  });
+
+  app.post(path, zValidator("json", CreateOrganizationServiceAccountRequest), async (c) => {
+    const { organizationId, context } = await requireControl(c, deps);
+    const body = c.req.valid("json");
+    if (body.role === "admin") requireOrganizationAdmin(context, organizationId);
+    const created = await createOrganizationServiceAccount(deps.db, {
+      accountId: organizationId,
+      name: body.name,
+      description: body.description ?? null,
+      role: body.role,
+      createdBySubjectId: context.subjectId,
+    });
+    return c.json(OrganizationServiceAccount.parse(created), 201);
+  });
+
+  app.get(`${path}/:serviceAccountId`, async (c) => {
+    const { organizationId } = await requireControl(c, deps);
+    const found = await getOrganizationServiceAccount(deps.db, organizationId, serviceAccountId(c));
+    if (!found) throw new HTTPException(404, { message: "Service account not found" });
+    return c.json(OrganizationServiceAccount.parse(found));
+  });
+
+  app.patch(
+    `${path}/:serviceAccountId`,
+    zValidator("json", UpdateOrganizationServiceAccountRequest),
+    async (c) => {
+      const { organizationId, context } = await requireControl(c, deps);
+      const body = c.req.valid("json");
+      if (body.role === "admin") requireOrganizationAdmin(context, organizationId);
+      try {
+        return c.json(
+          OrganizationServiceAccount.parse(
+            await updateOrganizationServiceAccount(
+              deps.db,
+              organizationId,
+              serviceAccountId(c),
+              body,
+            ),
+          ),
+        );
+      } catch (error) {
+        throwServiceAccountError(error);
+        throw error;
+      }
+    },
+  );
+
+  app.delete(`${path}/:serviceAccountId`, async (c) => {
+    const { organizationId } = await requireControl(c, deps);
+    try {
+      await deleteOrganizationServiceAccount(deps.db, organizationId, serviceAccountId(c));
+    } catch (error) {
+      throwServiceAccountError(error);
+      throw error;
+    }
+    return c.body(null, 204);
+  });
+}
+
+async function requireControl(
+  c: Context,
+  deps: ApiRouteDeps,
+): Promise<{ organizationId: string; context: AccessContext }> {
+  const parsed = Id.safeParse(c.req.param("organizationId"));
+  if (!parsed.success) throw new HTTPException(404, { message: "organization not found" });
+  const organizationId = parsed.data.toLowerCase();
+  const context = await requireAccessContext(c, deps);
+  requireOrganizationApiKeyControlPermission(context, organizationId);
+  return { organizationId, context };
+}
+
+function serviceAccountId(c: Context): string {
+  const parsed = Id.safeParse(c.req.param("serviceAccountId"));
+  if (!parsed.success) throw new HTTPException(404, { message: "Service account not found" });
+  return parsed.data.toLowerCase();
+}
+
+/** Only an organization administrator can make a service account an admin. */
+function requireOrganizationAdmin(context: AccessContext, organizationId: string): void {
+  const grant = context.accountGrants.find((candidate) => candidate.accountId === organizationId);
+  if (!grant?.permissions.includes("account:admin"))
+    throw new HTTPException(403, {
+      message: "Only an organization administrator can make a service account an admin.",
+    });
+}

package/src/routes/organization-sessions.ts

@@ -7,6 +7,7 @@ import {
 } from "@opengeni/contracts";
 import {
   accountScopedApiKeyWorkspaceAuthority,
+  organizationWorkspaceInScope,
   hasPermission,
   requireAccessContext,
   requireAccessGrantAuthorization,
@@ -14,6 +15,7 @@ import {
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   type ApiRouteDeps,
+  isVerifiedDelegatedHumanAuthorization,
 } from "@opengeni/core";
 import {
   decodeSessionListCursor,
@@ -26,6 +28,7 @@ import {
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
+import { loadCodexSessionPointerProjection } from "../codex-session-pointers";
 
 /**
  * Upper bound on the workspace page reads one request performs. The
@@ -161,9 +164,13 @@ export function registerOrganizationSessionRoutes(app: Hono, deps: ApiRouteDeps)
     // Personal workspaces are excluded by the inventory itself; the stable id
     // order is what makes the `{ workspaceId, cursor }` continuation resumable
     // even when a workspace is created or deleted between pages.
-    const workspaces = (await listSharedWorkspacesForAccount(deps.db, organizationId)).sort(
-      compareWorkspaceIds,
-    );
+    const authority = accountScopedApiKeyWorkspaceAuthority(context);
+    const workspaces = (await listSharedWorkspacesForAccount(deps.db, organizationId))
+      .filter(
+        (workspace) =>
+          !authority || organizationWorkspaceInScope(authority.workspaceScope, workspace.id),
+      )
+      .sort(compareWorkspaceIds);
     let index = 0;
     let innerCursor: string | null = null;
     let pinnedOffset = 0;
@@ -201,7 +208,14 @@ export function registerOrganizationSessionRoutes(app: Hono, deps: ApiRouteDeps)
         pinnedOffset = 0;
         continue;
       }
-      sessions.push(...page.sessions);
+      // The Codex pointers by the organization's cutover disposition, exactly
+      // as the workspace session routes show them.
+      const codexPointers = await loadCodexSessionPointerProjection(
+        deps.db,
+        workspace.id,
+        page.sessions,
+      );
+      sessions.push(...page.sessions.map(codexPointers));
       if (page.nextPinnedOffset !== null) {
         // The page ended inside this workspace's pinned prefix.
         innerCursor = null;
@@ -298,7 +312,9 @@ async function listWorkspaceSessionPage(
           ? { scopeSubjectId: input.query.scopeSubjectId }
           : {}),
         ...(authorizationScope ? { authorizationScope } : {}),
-        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
+        personalWorkspaceOwnerException:
+          authorization.canonicalManagedHumanSession ||
+          isVerifiedDelegatedHumanAuthorization(authorization),
       });
     const withStatus = (rows: Session[]) =>
       input.query.status ? rows.filter((session) => session.status === input.query.status) : rows;

package/src/routes/personal-api-keys.ts

@@ -0,0 +1,184 @@
+import {
+  CreatePersonalApiKeyRequest,
+  CreatePersonalApiKeyResponse,
+  ListPersonalApiKeysResponse,
+  PersonalApiKey,
+  type AccessContext,
+} from "@opengeni/contracts";
+import {
+  createPersonalApiKey,
+  getManagedUserProfilesByIds,
+  listPersonalApiKeys,
+  PersonalApiKeyLimitExceededError,
+  PersonalApiKeyWorkspaceScopeError,
+  revokePersonalApiKey,
+  type PersonalApiKeyRecord,
+} from "@opengeni/db";
+import {
+  hasPermission,
+  PERSONAL_API_KEY_TOKEN_PREFIX,
+  requireAccessContext,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+import { isAgentActingAsPerson, requireFullAccessIfAgent } from "../http/acting-person";
+import { requireSameOriginBrowserMutation } from "./codex";
+
+/* ----------------------------------------------------------------------------
+   Personal API keys: keys that act as the person who created them. A script
+   or agent holding one does what that person can do in this organization,
+   capped by the key's access setting, and shows up as them. Every request
+   rechecks the person's live access, so a removed or narrowed role applies at
+   once; leaving the organization revokes the keys.
+
+   Everyone manages their own; owners and admins also see everyone's and can
+   revoke them. An agent acting as the person can do this only with their full
+   access, so a limited agent or key can never mint a broader one.
+   -------------------------------------------------------------------------- */
+
+export function registerPersonalApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/organizations/:organizationId/personal-api-keys", async (c) => {
+    const { context, organizationId, admin } = await requireOrganizationPerson(c, deps, false);
+    const keys = await listPersonalApiKeys(deps.db, {
+      accountId: organizationId,
+      ...(admin ? {} : { ownerSubjectId: context.subjectId }),
+    });
+    c.header("cache-control", "no-store");
+    return c.json(
+      ListPersonalApiKeysResponse.parse({
+        apiKeys: await projectKeys(deps, keys),
+        canManageAll: admin,
+      }),
+    );
+  });
+
+  app.post("/v1/organizations/:organizationId/personal-api-keys", async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const { context, organizationId } = await requireOrganizationPerson(c, deps, true);
+    const parsed = CreatePersonalApiKeyRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, {
+        message: parsed.error.issues[0]?.message ?? "invalid personal API key",
+      });
+    }
+    const body = parsed.data;
+    const expiresAt = body.expiresAt ? new Date(body.expiresAt) : null;
+    if (expiresAt && expiresAt.getTime() <= Date.now()) {
+      throw new HTTPException(400, { message: "Choose an expiry date in the future." });
+    }
+    const token = generatePersonalApiKeyToken();
+    try {
+      const apiKey = await createPersonalApiKey(deps.db, {
+        accountId: organizationId,
+        ownerSubjectId: context.subjectId,
+        name: body.name,
+        description: body.description ?? null,
+        prefix: token.slice(0, 14),
+        keyHash: await sha256Hex(token),
+        access: body.access,
+        expiresAt,
+      });
+      const [projected] = await projectKeys(deps, [apiKey]);
+      c.header("cache-control", "no-store");
+      return c.json(CreatePersonalApiKeyResponse.parse({ apiKey: projected, token }), 201);
+    } catch (error) {
+      if (error instanceof PersonalApiKeyWorkspaceScopeError)
+        throw new HTTPException(400, { message: error.message });
+      if (error instanceof PersonalApiKeyLimitExceededError)
+        throw new HTTPException(429, { message: error.message });
+      throw error;
+    }
+  });
+
+  app.delete("/v1/organizations/:organizationId/personal-api-keys/:apiKeyId", async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const { context, organizationId, admin } = await requireOrganizationPerson(c, deps, true);
+    const apiKeyId = c.req.param("apiKeyId");
+    if (!z.string().uuid().safeParse(apiKeyId).success) {
+      throw new HTTPException(404, { message: "API key not found" });
+    }
+    const [existing] = await listPersonalApiKeys(deps.db, { accountId: organizationId, apiKeyId });
+    if (!existing || (existing.ownerSubjectId !== context.subjectId && !admin)) {
+      throw new HTTPException(404, { message: "API key not found" });
+    }
+    await revokePersonalApiKey(deps.db, { accountId: organizationId, apiKeyId });
+    return c.body(null, 204);
+  });
+}
+
+/**
+ * A member of the organization signed in in this browser, or an agent (or
+ * personal key) acting as them. Changes need the person's full access.
+ */
+async function requireOrganizationPerson(
+  c: Context,
+  deps: ApiRouteDeps,
+  mutation: boolean,
+): Promise<{ context: AccessContext; organizationId: string; admin: boolean }> {
+  if (deps.settings.productAccessMode !== "managed") {
+    throw new HTTPException(404, { message: "Personal API keys need Opengeni sign-in." });
+  }
+  if (isAgentActingAsPerson(c)) {
+    if (mutation) requireFullAccessIfAgent(c, "Managing personal API keys");
+  } else if (!c.req.header("cookie") || c.req.header("authorization")) {
+    throw new HTTPException(403, {
+      message: "Manage personal API keys in the Opengeni app in your browser.",
+    });
+  }
+  const context = await requireAccessContext(c, deps);
+  const organizationId = c.req.param("organizationId") ?? "";
+  const grant = context.accountGrants.find((each) => each.accountId === organizationId);
+  if (context.mode !== "managed" || !context.subjectId.startsWith("user:") || !grant) {
+    throw new HTTPException(404, { message: "organization not found" });
+  }
+  return { context, organizationId, admin: hasPermission(grant.permissions, "account:admin") };
+}
+
+async function projectKeys(
+  deps: ApiRouteDeps,
+  keys: PersonalApiKeyRecord[],
+): Promise<PersonalApiKey[]> {
+  const userIds = [...new Set(keys.map((key) => key.ownerSubjectId.slice("user:".length)))];
+  const profiles = new Map(
+    (await getManagedUserProfilesByIds(deps.db, userIds)).map((profile) => [
+      `user:${profile.id}`,
+      profile,
+    ]),
+  );
+  return keys.map((key) => {
+    const profile = profiles.get(key.ownerSubjectId);
+    return PersonalApiKey.parse({
+      id: key.id,
+      organizationId: key.accountId,
+      name: key.name,
+      description: key.description,
+      prefix: key.prefix,
+      access: key.access,
+      owner: {
+        subjectId: key.ownerSubjectId,
+        name: profile?.name?.trim() || profile?.email || "Someone",
+      },
+      expiresAt: key.expiresAt?.toISOString() ?? null,
+      lastUsedAt: key.lastUsedAt?.toISOString() ?? null,
+      createdAt: key.createdAt.toISOString(),
+    });
+  });
+}
+
+function generatePersonalApiKeyToken(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `${PERSONAL_API_KEY_TOKEN_PREFIX}${Array.from(bytes)
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("")}`;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/routes/personal-github-git-broker.ts

@@ -549,7 +549,7 @@ async function fetchLiveGitHubJson(
       headers: {
         accept: "application/vnd.github+json",
         authorization,
-        "user-agent": "OpenGeni",
+        "user-agent": "Opengeni",
         "x-github-api-version": GITHUB_API_VERSION,
       },
       signal: AbortSignal.timeout(10_000),
@@ -776,7 +776,7 @@ function brokerError(status: 401 | 403 | 404 | 502, message: string): Response {
     "x-content-type-options": "nosniff",
   });
   if (status === 401) {
-    headers.set("www-authenticate", 'Basic realm="OpenGeni Git broker", charset="UTF-8"');
+    headers.set("www-authenticate", 'Basic realm="Opengeni Git broker", charset="UTF-8"');
   }
   return new Response(`${message}\n`, {
     status,

package/src/routes/personal-github.ts

@@ -46,6 +46,7 @@ import {
   requirePersonalGitHubRepositoryConnection,
   verifyLivePersonalGitHubRepositories,
 } from "../integrations/personal-github-repositories";
+import { parseRequestBody, parseRequestJson } from "../http/request-body";
 
 export function registerPersonalGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/connections/github", async (c) => {
@@ -69,7 +70,10 @@ export function registerPersonalGitHubRoutes(app: Hono, deps: ApiRouteDeps): voi
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
     requireLegacyOAuthActor(access);
     assertPersonalConnectionOwnerPrincipal(access, "My GitHub account");
-    const payload = PersonalGitHubOAuthStartRequest.parse(await c.req.json().catch(() => ({})));
+    const payload = parseRequestBody(
+      PersonalGitHubOAuthStartRequest,
+      await c.req.json().catch(() => ({})),
+    );
     return c.json(
       await startPersonalGitHubOAuth(deps, {
         access,
@@ -85,7 +89,8 @@ export function registerPersonalGitHubRoutes(app: Hono, deps: ApiRouteDeps): voi
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
     requireLegacyOAuthActor(access);
     assertPersonalConnectionOwnerPrincipal(access, "My GitHub account");
-    const payload = PersonalGitHubOAuthStartRequest.omit({ connectionId: true }).parse(
+    const payload = parseRequestBody(
+      PersonalGitHubOAuthStartRequest.omit({ connectionId: true }),
       await c.req.json().catch(() => ({})),
     );
     return c.json(
@@ -168,7 +173,7 @@ export function registerPersonalGitHubRoutes(app: Hono, deps: ApiRouteDeps): voi
         subjectId: access.grant.subjectId,
         connectionId,
       });
-      const request = ReplacePersonalGitHubRepositorySelectionsRequest.parse(await c.req.json());
+      const request = await parseRequestJson(c, ReplacePersonalGitHubRepositorySelectionsRequest);
       try {
         const current = await loadRepositorySelectionState(deps, access.grant, connection);
         assertRepositoryConnectionAuthorityFence(current, request);
@@ -249,7 +254,7 @@ export function registerPersonalGitHubRoutes(app: Hono, deps: ApiRouteDeps): voi
         subjectId: access.grant.subjectId,
         connectionId,
       });
-      const request = VerifyPersonalGitHubRepositorySelectionsRequest.parse(await c.req.json());
+      const request = await parseRequestJson(c, VerifyPersonalGitHubRepositorySelectionsRequest);
       try {
         const current = await loadRepositorySelectionState(deps, access.grant, connection);
         assertRepositoryConnectionAuthorityFence(current, request);

package/src/routes/plugins.ts

@@ -1,7 +1,12 @@
 import pluginSnapshot from "../../../../data/catalog/plugins-snapshot.json";
 import { marketplacePlugin } from "../integrations/marketplace-plugin";
 import { mcpEndpointIdentity } from "@opengeni/contracts";
-import { buildCapabilityCatalog, createCatalogItem } from "@opengeni/core";
+import {
+  buildCapabilityCatalog,
+  createCatalogItem,
+  integrationSourceForOrganizationPolicy,
+} from "@opengeni/core";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
 import { createHash } from "node:crypto";
 
 import {
@@ -43,6 +48,7 @@ import {
   getConnectionMetadata,
   getInstalledPluginPackage,
   getPluginPackageUninstallPreview,
+  PluginUninstallPreviewChangedError,
   integrationBindingKey,
   installApiIntegration,
   installPluginMcpReference,
@@ -66,6 +72,7 @@ import {
   type ResolvedApiIntegrationPreview,
 } from "../integrations/api-integrations";
 import { createGitHubSkillSourceClient } from "../integrations/github-skill-source";
+import { parseRequestJson } from "../http/request-body";
 
 const MAX_PLUGIN_MANIFEST_BYTES = 1024 * 1024;
 
@@ -182,7 +189,7 @@ export function registerPluginRoutes(
   app.post("/v1/workspaces/:workspaceId/plugins/preview", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-    const payload = PreviewPluginRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, PreviewPluginRequest);
     const resolved = await resolvePluginPackage({
       deps,
       github,
@@ -205,7 +212,7 @@ export function registerPluginRoutes(
       "capabilities:manage",
     );
     const { grant } = access;
-    const payload = InstallPluginRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, InstallPluginRequest);
     const resolved = await resolvePluginPackage({
       skillActor: () => skillInstallerActor(access),
       deps,
@@ -344,9 +351,14 @@ export function registerPluginRoutes(
 
   app.get("/v1/workspaces/:workspaceId/plugins/:pluginKey/uninstall-preview", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
     const pluginKey = decodeURIComponent(c.req.param("pluginKey"));
-    const preview = await getPluginPackageUninstallPreview(deps.db, workspaceId, pluginKey);
+    const preview = await getPluginPackageUninstallPreview(
+      deps.db,
+      workspaceId,
+      pluginKey,
+      grant.subjectId,
+    );
     return c.json(PluginUninstallPreview.parse({ pluginKey, ...preview }));
   });
 
@@ -361,7 +373,7 @@ export function registerPluginRoutes(
     const { grant } = access;
     const skillActor = skillRemovalActor(access);
     const pluginKey = decodeURIComponent(c.req.param("pluginKey"));
-    const payload = UninstallPluginRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, UninstallPluginRequest);
     try {
       return c.json(
         UninstallPluginResult.parse({
@@ -373,11 +385,33 @@ export function registerPluginRoutes(
             subjectId: grant.subjectId,
             pluginKey,
             expectedInstallationVersion: payload.expectedInstallationVersion,
+            ...(payload.expectedPreviewToken
+              ? { expectedPreviewToken: payload.expectedPreviewToken }
+              : {}),
             idempotencyKey: payload.idempotencyKey,
           })),
         }),
       );
     } catch (error) {
+      if (error instanceof PluginUninstallPreviewChangedError) {
+        const preview = error.preview ?? {
+          pluginKey,
+          ...(await getPluginPackageUninstallPreview(
+            deps.db,
+            workspaceId,
+            pluginKey,
+            grant.subjectId,
+          )),
+        };
+        return c.json(
+          {
+            code: error.code,
+            message: error.message,
+            preview: PluginUninstallPreview.parse(preview),
+          },
+          409,
+        );
+      }
       throw pluginMutationHttpError(error);
     }
   });
@@ -499,6 +533,11 @@ async function resolvePluginPackage(input: {
       continue;
     }
     if (component.kind === "integration") {
+      const source = await withOrganizationIntegrationPolicyFence(
+        input.deps.db,
+        input,
+        async (_tx, policy) => integrationSourceForOrganizationPolicy(policy, component.source),
+      );
       const requestedBinding = input.bindings[component.key];
       const connection = await optionalConnection(
         input.deps,
@@ -507,7 +546,7 @@ async function resolvePluginPackage(input: {
         requestedBinding?.connectionId,
       );
       const resolved = await resolveApiIntegrationPreview({
-        source: component.source,
+        source,
         connection: connectionDescriptor(connection),
         transport: input.transport,
         authority: {