@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/organization-integration-policy.ts

@@ -0,0 +1,116 @@
+import { UpdateOrganizationIntegrationPolicyRequest } from "@opengeni/contracts";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  organizationIntegrationCatalog,
+  requireAccessContext,
+  requireCanonicalLocalAccountAdministrator,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  getOrganizationIntegrationPolicy,
+  updateOrganizationIntegrationPolicy,
+} from "@opengeni/db/organization-integration-policy";
+import { nestedPostgresSqlState } from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { agentActingAsPerson } from "../http/acting-person";
+import { requireSameOriginBrowserMutation } from "./codex";
+import { managedCookieHuman } from "./supergrok";
+
+/** The database rechecks current organization membership/key authority at commit. */
+async function authorizeAdministration(
+  context: Context,
+  deps: ApiRouteDeps,
+  accountId: string,
+  mutation: boolean,
+): Promise<{ accountId: string; subjectId: string }> {
+  const access = await requireAccessContext(context, deps);
+  const service = accountScopedApiKeyWorkspaceAuthority(access);
+  if (service) {
+    if (service.accountId !== accountId || !service.permissions.includes("workspace:admin")) {
+      throw new HTTPException(403, { message: "Organization administration required" });
+    }
+    return { accountId, subjectId: access.subjectId };
+  }
+  if (deps.settings.productAccessMode === "local") {
+    const local = await requireCanonicalLocalAccountAdministrator(context, deps, accountId);
+    if (mutation) requireSameOriginBrowserMutation(context, deps);
+    return { accountId, subjectId: local.subjectId };
+  }
+  const human =
+    agentActingAsPerson(context, accountId, mutation ? "account:admin" : "account:read") ??
+    (await managedCookieHuman(context, deps));
+  if (!human || human.subjectId !== access.subjectId) {
+    throw new HTTPException(403, { message: "Organization administration required" });
+  }
+  if (mutation) requireSameOriginBrowserMutation(context, deps);
+  return { accountId, subjectId: human.subjectId };
+}
+
+async function policyResponse<T>(readOrWrite: () => Promise<T>): Promise<T> {
+  try {
+    return await readOrWrite();
+  } catch (error) {
+    if (error instanceof HTTPException) throw error;
+    const state = nestedPostgresSqlState(error);
+    if (state === "42501") {
+      throw new HTTPException(403, { message: "Organization administration required" });
+    }
+    if (state === "40001" || state === "23505") {
+      throw new HTTPException(409, {
+        message: "Integration policy changed; refresh before saving",
+      });
+    }
+    if (state === "22023") {
+      throw new HTTPException(422, { message: "Invalid integration policy" });
+    }
+    throw new HTTPException(503, { message: "Integration policy is temporarily unavailable" });
+  }
+}
+
+export function registerOrganizationIntegrationPolicyRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const path = "/v1/organizations/:organizationId/integration-policy";
+  const organizationId = (context: Context) => {
+    const parsed = z.string().uuid().safeParse(context.req.param("organizationId"));
+    if (!parsed.success) throw new HTTPException(422, { message: "Invalid organization identity" });
+    return parsed.data.toLowerCase();
+  };
+  app.get(`${path}/catalog`, async (context) => {
+    const accountId = organizationId(context);
+    // The same live administration check as policy reads, including workspace-free service access.
+    await policyResponse(() =>
+      getOrganizationIntegrationPolicy(deps.db, { accountId }, () =>
+        authorizeAdministration(context, deps, accountId, false),
+      ),
+    );
+    context.header("cache-control", "private, no-store");
+    return context.json(organizationIntegrationCatalog());
+  });
+  app.get(path, async (context) => {
+    context.header("cache-control", "private, no-store");
+    const accountId = organizationId(context);
+    return context.json(
+      await policyResponse(() =>
+        getOrganizationIntegrationPolicy(deps.db, { accountId }, () =>
+          authorizeAdministration(context, deps, accountId, false),
+        ),
+      ),
+    );
+  });
+  app.put(path, async (context) => {
+    context.header("cache-control", "private, no-store");
+    const accountId = organizationId(context);
+    const parsed = UpdateOrganizationIntegrationPolicyRequest.safeParse(
+      await context.req.json().catch(() => null),
+    );
+    if (!parsed.success) throw new HTTPException(422, { message: "Invalid integration policy" });
+    return context.json(
+      await policyResponse(() =>
+        updateOrganizationIntegrationPolicy(deps.db, { accountId }, parsed.data, () =>
+          authorizeAdministration(context, deps, accountId, true),
+        ),
+      ),
+    );
+  });
+}

package/src/routes/organization-integrations.ts

@@ -0,0 +1,326 @@
+import {
+  CreateOrganizationWebhookRequest,
+  CreateOrganizationWebhookResponse,
+  GetOrganizationCredentialProviderResponse,
+  ListOrganizationWebhookDeliveriesResponse,
+  ListOrganizationWebhooksResponse,
+  OrganizationCredentialProvider,
+  OrganizationWebhook,
+  PutOrganizationCredentialProviderRequest,
+  PutOrganizationCredentialProviderResponse,
+  RotateOrganizationCredentialProviderSecretResponse,
+  RotateOrganizationWebhookSecretResponse,
+  UpdateOrganizationWebhookRequest,
+  type AccessContext,
+} from "@opengeni/contracts";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  accessGrantAuthorizationFromContext,
+  requireAccountAdminAuthorizationStamp,
+  requireAccessContext,
+  requireCanonicalLocalAccountAdministrator,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+  isVerifiedDelegatedHumanAuthorization,
+} from "@opengeni/core";
+import {
+  createOrganizationWebhook,
+  deleteOrganizationCredentialProvider,
+  deleteOrganizationWebhook,
+  encryptEnvironmentValue,
+  getOrganizationCredentialProvider,
+  getOrganizationWebhook,
+  listOrganizationWebhookDeliveries,
+  listOrganizationWebhooks,
+  OrganizationWebhookLimitError,
+  redeliverOrganizationWebhookDelivery,
+  rotateOrganizationCredentialProviderSecret,
+  rotateOrganizationWebhookSecret,
+  updateOrganizationWebhook,
+  upsertOrganizationCredentialProvider,
+  withCredentialProviderConfigurationLock,
+  type OrganizationCredentialProviderRow,
+  type OrganizationWebhookRow,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { organizationApiKeyAccess, requireOrganizationApiKeyControlPermission } from "./api-keys";
+import { requireSameOriginBrowserMutation } from "./codex";
+import {
+  integrationBody as body,
+  integrationDeliveryProjection as deliveryProjection,
+  integrationProviderFields,
+  integrationRouteConfiguration,
+  integrationWebhookFields,
+  isIntegrationAgent,
+  newIntegrationSecret,
+} from "./workspace-integrations";
+
+/** Account administrators or verified full-access organization keys; never workspace keys. */
+export function requireOrganizationIntegrationAdmin(
+  context: AccessContext,
+  organizationId: string,
+  authorization?: AccessGrantAuthorization,
+): string {
+  if (context.workspaceGrants.some(isIntegrationAgent)) {
+    throw new HTTPException(403, {
+      message: "Agent attempts cannot manage organization integrations",
+    });
+  }
+  const grant = context.accountGrants.find(
+    (candidate) =>
+      candidate.accountId === organizationId && candidate.subjectId === context.subjectId,
+  );
+  if (!grant) {
+    throw new HTTPException(403, { message: "missing permission: account:admin" });
+  }
+  if (context.subjectId.startsWith("api_key:")) {
+    requireOrganizationApiKeyControlPermission(context, organizationId);
+    const authority = accountScopedApiKeyWorkspaceAuthority(context);
+    if (
+      !authority ||
+      authority.accountId !== organizationId ||
+      organizationApiKeyAccess(authority.permissions) !== "full"
+    ) {
+      throw new HTTPException(403, { message: "organization API key authority required" });
+    }
+  } else {
+    if (!grant.permissions.includes("account:admin"))
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    if (
+      !authorization ||
+      !(
+        authorization.canonicalManagedHumanSession ||
+        authorization.canonicalLocalHumanSession ||
+        isVerifiedDelegatedHumanAuthorization(authorization)
+      ) ||
+      authorization.grant.accountId !== organizationId ||
+      authorization.authenticatedSubjectId !== context.subjectId ||
+      context.workspaceGrants.some((candidate) => candidate.metadata?.delegated === true)
+    ) {
+      throw new HTTPException(403, { message: "Canonical organization administrator required" });
+    }
+    requireAccountAdminAuthorizationStamp(authorization);
+  }
+  return grant.subjectId;
+}
+
+function providerProjection(
+  row: OrganizationCredentialProviderRow,
+): OrganizationCredentialProvider {
+  return OrganizationCredentialProvider.parse({
+    ...integrationProviderFields(row),
+    organizationId: row.accountId,
+    workspaceFilter: row.workspaceFilter,
+  });
+}
+function webhookProjection(row: OrganizationWebhookRow): OrganizationWebhook {
+  return OrganizationWebhook.parse({
+    ...integrationWebhookFields(row),
+    organizationId: row.accountId,
+    workspaceFilter: row.workspaceFilter,
+  });
+}
+
+export function registerOrganizationIntegrationRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const scope = async (c: Context) => {
+    const id = z.string().uuid().safeParse(c.req.param("organizationId"));
+    if (!id.success) throw new HTTPException(422, { message: "invalid organization id" });
+    const context = await requireAccessContext(c, deps);
+    const accountId = id.data.toLowerCase();
+    let authorization: AccessGrantAuthorization | undefined;
+    if (!accountScopedApiKeyWorkspaceAuthority(context)) {
+      if (deps.settings.productAccessMode === "local") {
+        authorization = (await requireCanonicalLocalAccountAdministrator(c, deps, accountId))
+          .authorization;
+      } else {
+        const grant = context.workspaceGrants.find(
+          (candidate) => candidate.accountId === accountId,
+        );
+        if (grant) authorization = accessGrantAuthorizationFromContext(context, grant);
+      }
+    }
+    const subjectId = requireOrganizationIntegrationAdmin(context, accountId, authorization);
+    if (!accountScopedApiKeyWorkspaceAuthority(context) && !["GET", "HEAD"].includes(c.req.method))
+      requireSameOriginBrowserMutation(c, deps);
+    c.header("cache-control", "private, no-store");
+    return { accountId, subjectId };
+  };
+  const { requireKey, requireDeployableUrl: requireUrl } = integrationRouteConfiguration(
+    deps,
+    "organization",
+  );
+  const encrypted = (secret: string): string => encryptEnvironmentValue(requireKey(), secret);
+  const webhookId = (c: Context): string => {
+    const id = z.string().uuid().safeParse(c.req.param("webhookId"));
+    if (!id.success) throw new HTTPException(404, { message: "Webhook not found" });
+    return id.data;
+  };
+  const base = "/v1/organizations/:organizationId";
+  app.get(`${base}/credential-provider`, async (c) => {
+    const target = await scope(c);
+    const row = await getOrganizationCredentialProvider(deps.db, target);
+    return c.json(
+      GetOrganizationCredentialProviderResponse.parse({
+        provider: row ? providerProjection(row) : null,
+      }),
+    );
+  });
+  app.put(`${base}/credential-provider`, async (c) => {
+    const target = await scope(c);
+    const request = await body(c, PutOrganizationCredentialProviderRequest, 422);
+    requireUrl(request.url);
+    const {
+      row: providerRow,
+      secret: signingSecret,
+      created,
+    } = await withCredentialProviderConfigurationLock(deps.db, target, async (tx) => {
+      const existing = await getOrganizationCredentialProvider(tx, target);
+      const secret = existing ? undefined : newIntegrationSecret("ogcp");
+      const row = await upsertOrganizationCredentialProvider(tx, {
+        accountId: target.accountId,
+        url: request.url,
+        enabled: request.enabled ?? true,
+        timeoutMs: request.timeoutMs ?? 10_000,
+        workspaceFilter: request.workspaceFilter,
+        createdBySubjectId: target.subjectId,
+        ...(secret ? { secretEncrypted: encrypted(secret) } : {}),
+      });
+      return { row, secret, created: !existing };
+    });
+    return c.json(
+      PutOrganizationCredentialProviderResponse.parse({
+        provider: providerProjection(providerRow),
+        ...(signingSecret ? { secret: signingSecret } : {}),
+      }),
+      created ? 201 : 200,
+    );
+  });
+  app.delete(`${base}/credential-provider`, async (c) => {
+    await deleteOrganizationCredentialProvider(deps.db, await scope(c));
+    return c.body(null, 204);
+  });
+  app.post(`${base}/credential-provider/rotate-secret`, async (c) => {
+    const target = await scope(c);
+    const secret = newIntegrationSecret("ogcp");
+    const row = await rotateOrganizationCredentialProviderSecret(deps.db, {
+      ...target,
+      secretEncrypted: encrypted(secret),
+    });
+    if (!row) throw new HTTPException(404, { message: "Credential provider not found" });
+    return c.json(
+      RotateOrganizationCredentialProviderSecretResponse.parse({
+        provider: providerProjection(row),
+        secret,
+      }),
+    );
+  });
+  app.get(`${base}/webhooks`, async (c) => {
+    const rows = await listOrganizationWebhooks(deps.db, await scope(c));
+    return c.json(
+      ListOrganizationWebhooksResponse.parse({ webhooks: rows.map(webhookProjection) }),
+    );
+  });
+  app.post(`${base}/webhooks`, async (c) => {
+    const target = await scope(c);
+    const request = await body(c, CreateOrganizationWebhookRequest, 422);
+    requireUrl(request.url);
+    const secret = newIntegrationSecret("whsec");
+    try {
+      const row = await createOrganizationWebhook(deps.db, {
+        accountId: target.accountId,
+        url: request.url,
+        secretEncrypted: encrypted(secret),
+        eventTypes: request.eventTypes,
+        enabled: request.enabled ?? true,
+        description: request.description ?? null,
+        workspaceFilter: request.workspaceFilter,
+        createdBySubjectId: target.subjectId,
+      });
+      return c.json(
+        CreateOrganizationWebhookResponse.parse({ webhook: webhookProjection(row), secret }),
+        201,
+      );
+    } catch (error) {
+      if (error instanceof OrganizationWebhookLimitError)
+        throw new HTTPException(409, { message: error.message });
+      throw error;
+    }
+  });
+  app.get(`${base}/webhooks/:webhookId`, async (c) => {
+    const target = await scope(c);
+    const row = await getOrganizationWebhook(deps.db, {
+      accountId: target.accountId,
+      webhookId: webhookId(c),
+    });
+    if (!row) throw new HTTPException(404, { message: "Webhook not found" });
+    return c.json(webhookProjection(row));
+  });
+  app.patch(`${base}/webhooks/:webhookId`, async (c) => {
+    const target = await scope(c);
+    const request = await body(c, UpdateOrganizationWebhookRequest, 422);
+    if (request.url) requireUrl(request.url);
+    const row = await updateOrganizationWebhook(deps.db, {
+      accountId: target.accountId,
+      webhookId: webhookId(c),
+      ...(request.url !== undefined ? { url: request.url } : {}),
+      ...(request.eventTypes !== undefined ? { eventTypes: request.eventTypes } : {}),
+      ...(request.enabled !== undefined ? { enabled: request.enabled } : {}),
+      ...(request.description !== undefined ? { description: request.description } : {}),
+      ...(request.workspaceFilter !== undefined
+        ? { workspaceFilter: request.workspaceFilter }
+        : {}),
+    });
+    if (!row) throw new HTTPException(404, { message: "Webhook not found" });
+    return c.json(webhookProjection(row));
+  });
+  app.delete(`${base}/webhooks/:webhookId`, async (c) => {
+    const target = await scope(c);
+    if (!(await deleteOrganizationWebhook(deps.db, { ...target, webhookId: webhookId(c) }))) {
+      throw new HTTPException(404, { message: "Webhook not found" });
+    }
+    return c.body(null, 204);
+  });
+  app.post(`${base}/webhooks/:webhookId/rotate-secret`, async (c) => {
+    const target = await scope(c);
+    const secret = newIntegrationSecret("whsec");
+    const row = await rotateOrganizationWebhookSecret(deps.db, {
+      ...target,
+      webhookId: webhookId(c),
+      secretEncrypted: encrypted(secret),
+    });
+    if (!row) throw new HTTPException(404, { message: "Webhook not found" });
+    return c.json(
+      RotateOrganizationWebhookSecretResponse.parse({
+        webhook: webhookProjection(row),
+        secret,
+      }),
+    );
+  });
+  app.get(`${base}/webhooks/:webhookId/deliveries`, async (c) => {
+    const target = { ...(await scope(c)), webhookId: webhookId(c) };
+    if (!(await getOrganizationWebhook(deps.db, target)))
+      throw new HTTPException(404, { message: "Webhook not found" });
+    const limit = z.coerce.number().int().min(1).max(200).catch(50).parse(c.req.query("limit"));
+    const rows = await listOrganizationWebhookDeliveries(deps.db, { ...target, limit });
+    return c.json(
+      ListOrganizationWebhookDeliveriesResponse.parse({ deliveries: rows.map(deliveryProjection) }),
+    );
+  });
+  app.post(`${base}/webhooks/:webhookId/deliveries/:deliveryId/redeliver`, async (c) => {
+    const target = await scope(c);
+    const id = z.string().uuid().safeParse(c.req.param("deliveryId"));
+    if (!id.success) throw new HTTPException(404, { message: "Delivery not found" });
+    const row = await redeliverOrganizationWebhookDelivery(deps.db, {
+      ...target,
+      webhookId: webhookId(c),
+      deliveryId: id.data,
+    });
+    if (!row)
+      throw new HTTPException(409, {
+        message: "Only a delivered or failed delivery can be redelivered",
+      });
+    return c.json(deliveryProjection(row));
+  });
+}

package/src/routes/organization-mcp-connections.ts

@@ -0,0 +1,178 @@
+import { OrganizationAccessPolicy, type AccessContext } from "@opengeni/contracts";
+import {
+  getManagedUserProfilesByIds,
+  getWorkspace,
+  listOrganizationMcpConnections,
+  revokeOrganizationMcpConnection,
+  updateOrganizationMcpConnectionAccess,
+  type OrganizationMcpConnection,
+} from "@opengeni/db";
+import { hasPermission, requireAccessContext, type ApiRouteDeps } from "@opengeni/core";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireNotAgent } from "../http/acting-person";
+import { z } from "zod";
+
+import { requireSameOriginBrowserMutation } from "./codex";
+
+/* ----------------------------------------------------------------------------
+   Connected agents: outside MCP clients people signed in to the organization
+   server with. Everyone sees and manages their own; owners and admins see and
+   can disconnect everyone's. Only the person who connected an agent changes
+   what it can do, and only from the browser: an agent can never widen its own
+   access through these routes.
+   -------------------------------------------------------------------------- */
+
+const UpdateBody = z.object({ access: OrganizationAccessPolicy }).strict();
+
+export function registerOrganizationMcpConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/organizations/:organizationId/mcp-connections", async (c) => {
+    const { context, organizationId, admin } = await requireOrganizationPerson(c, deps);
+    const connections = await listOrganizationMcpConnections(deps.db, {
+      accountId: organizationId,
+      ...(admin ? {} : { subjectId: context.subjectId }),
+    });
+    c.header("cache-control", "no-store");
+    return c.json({
+      connections: await projectConnections(deps, connections),
+      canManageAll: admin,
+    });
+  });
+
+  app.patch("/v1/organizations/:organizationId/mcp-connections/:connectionId", async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const { context, organizationId } = await requireOrganizationPerson(c, deps);
+    const connection = await requireConnection(deps, organizationId, c.req.param("connectionId"));
+    if (connection.subjectId !== context.subjectId) {
+      throw new HTTPException(403, {
+        message: "Only the person who connected this agent can change what it can do.",
+      });
+    }
+    const parsed = UpdateBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid access setting" });
+    const access = parsed.data.access;
+    if (access.workspaceScope.kind === "selected") {
+      for (const workspaceId of access.workspaceScope.workspaceIds) {
+        const workspace = await getWorkspace(deps.db, workspaceId);
+        if (workspace?.accountId !== organizationId) {
+          throw new HTTPException(400, {
+            message: "a selected workspace is not in this organization",
+          });
+        }
+      }
+    }
+    await updateOrganizationMcpConnectionAccess(deps.db, {
+      accountId: organizationId,
+      connectionId: connection.id,
+      organizationAccess: access,
+    });
+    const [updated] = await projectConnections(
+      deps,
+      await listOrganizationMcpConnections(deps.db, {
+        accountId: organizationId,
+        connectionId: connection.id,
+      }),
+    );
+    if (!updated) throw new HTTPException(404, { message: "connected agent not found" });
+    return c.json(updated);
+  });
+
+  app.delete("/v1/organizations/:organizationId/mcp-connections/:connectionId", async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const { context, organizationId, admin } = await requireOrganizationPerson(c, deps);
+    const connection = await requireConnection(deps, organizationId, c.req.param("connectionId"));
+    if (connection.subjectId !== context.subjectId && !admin) {
+      throw new HTTPException(403, {
+        message: "Only the person who connected this agent, or an admin, can disconnect it.",
+      });
+    }
+    await revokeOrganizationMcpConnection(deps.db, {
+      accountId: organizationId,
+      connectionId: connection.id,
+    });
+    return c.body(null, 204);
+  });
+}
+
+/** A member of the organization, signed in in this browser. Keys and agents are refused. */
+async function requireOrganizationPerson(
+  c: Context,
+  deps: ApiRouteDeps,
+): Promise<{ context: AccessContext; organizationId: string; admin: boolean }> {
+  requireNotAgent(c, "Managing connected agents");
+  if (
+    deps.settings.productAccessMode !== "managed" ||
+    !c.req.header("cookie") ||
+    c.req.header("authorization")
+  ) {
+    throw new HTTPException(403, {
+      message: "Manage connected agents 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 requireConnection(
+  deps: ApiRouteDeps,
+  organizationId: string,
+  connectionId: string,
+): Promise<OrganizationMcpConnection> {
+  if (!z.string().uuid().safeParse(connectionId).success) {
+    throw new HTTPException(404, { message: "connected agent not found" });
+  }
+  const [connection] = await listOrganizationMcpConnections(deps.db, {
+    accountId: organizationId,
+    connectionId,
+  });
+  if (!connection) throw new HTTPException(404, { message: "connected agent not found" });
+  return connection;
+}
+
+async function projectConnections(deps: ApiRouteDeps, connections: OrganizationMcpConnection[]) {
+  const userIds = connections
+    .map((connection) => connection.subjectId)
+    .filter((subjectId) => subjectId.startsWith("user:"))
+    .map((subjectId) => subjectId.slice("user:".length));
+  const profiles = new Map(
+    (await getManagedUserProfilesByIds(deps.db, userIds)).map((profile) => [
+      `user:${profile.id}`,
+      profile,
+    ]),
+  );
+  return connections.map((connection) => {
+    const profile = profiles.get(connection.subjectId);
+    return {
+      id: connection.id,
+      clientName: connection.clientName ?? "MCP client",
+      clientHost: clientHost(connection.redirectUris),
+      actor: "user" as const,
+      connectedBy: {
+        subjectId: connection.subjectId,
+        name: profile?.name?.trim() || profile?.email || "Someone",
+      },
+      policy: connection.organizationAccess,
+      createdAt: connection.connectedAt.toISOString(),
+      lastUsedAt: connection.lastUsedAt?.toISOString() ?? null,
+      expiresAt: connection.expiresAt.toISOString(),
+      revokedAt: null,
+    };
+  });
+}
+
+function clientHost(redirectUris: string[]): string | null {
+  for (const value of redirectUris) {
+    try {
+      const url = new URL(value);
+      return url.host || url.protocol.replace(/:$/u, "");
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}