@opengeni/api-router 0.14.4 → 0.15.4

package/dist/integrations/social-oauth.d.ts

@@ -0,0 +1,84 @@
+import { type Settings } from "@opengeni/config";
+import { OAuthStartResponse, type SocialConnection, type SocialOAuthProviderId, type SocialOAuthStartRequest } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+import { type Database } from "@opengeni/db";
+export declare const SOCIAL_USER_AGENT = "opengeni:social-connector:v0.1.0 (self-hosted)";
+export declare const SOCIAL_TIMEOUT_MS = 10000;
+/** Token-endpoint failure that carries enough to tell invalid_grant from a blip. */
+export declare class SocialTokenRequestError extends Error {
+    readonly status: number | null;
+    readonly oauthError: string | null;
+    constructor(message: string, status: number | null, oauthError: string | null);
+    /** True only for definitive authorization-server rejections of the grant. */
+    get definitive(): boolean;
+}
+type SocialProviderDefinition = {
+    id: SocialOAuthProviderId;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    defaultScopes: string[];
+    pkce: boolean;
+    extraAuthorizeParams: Record<string, string>;
+};
+export declare const SOCIAL_OAUTH_PROVIDERS: Record<SocialOAuthProviderId, SocialProviderDefinition>;
+export type SocialCredentialBundle = {
+    provider: SocialOAuthProviderId;
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    expiresAt?: string;
+    scope?: string;
+};
+/**
+ * Provider-transport seam (Slack-connector pattern): production always goes
+ * through pinnedFetch; tests inject an in-process provider to exercise the
+ * full callback/refresh/tool loop functionally.
+ */
+export type SocialProviderFetch = (url: string, init: RequestInit, label: string) => Promise<Response>;
+type SocialOAuthDeps = {
+    db: Database;
+    settings: Settings;
+    observability?: Observability | undefined;
+    providerFetch?: SocialProviderFetch | undefined;
+};
+export type SocialOAuthStartContext = {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    payload: SocialOAuthStartRequest;
+};
+export declare function socialOAuthClientFor(settings: Settings, provider: SocialOAuthProviderId): {
+    clientId: string;
+    clientSecret?: string | undefined;
+};
+export declare function socialOAuthRedirectUri(settings: Settings, requestUrl: string): string;
+export declare function startSocialOAuth(deps: SocialOAuthDeps, context: SocialOAuthStartContext): Promise<OAuthStartResponse>;
+export declare function completeSocialOAuthCallback(deps: SocialOAuthDeps, input: {
+    code?: string | undefined;
+    state?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+}): Promise<{
+    redirectTo: string;
+}>;
+/**
+ * Resolves a usable access token for a social connection, refreshing (and
+ * persisting the rotated bundle) when the stored token is near expiry. Marks
+ * the connection needs_reauth and throws when refresh is impossible so agents
+ * surface an actionable error instead of opaque 401s.
+ */
+export declare function freshSocialAccessToken(deps: SocialOAuthDeps, ref: {
+    workspaceId: string;
+    connectionId: string;
+}): Promise<{
+    connection: SocialConnection;
+    bundle: SocialCredentialBundle;
+}>;
+export declare function markNeedsReauth(deps: SocialOAuthDeps, ref: {
+    workspaceId: string;
+    connectionId: string;
+}): Promise<void>;
+export declare function parseSocialCredentialBundle(raw: string): SocialCredentialBundle;
+export declare function socialTokenNeedsRefresh(bundle: SocialCredentialBundle, now: Date): boolean;
+export {};

package/dist/routes/workspace-artifacts.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerWorkspaceArtifactRoutes(app: Hono, deps: ApiRouteDeps): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.14.4",
+  "version": "0.15.4",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,17 +44,17 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.3.0",
     "@opengeni/codex": "^0.2.9",
-    "@opengeni/config": "^0.7.22",
-    "@opengeni/contracts": "^0.26.1",
-    "@opengeni/core": "^0.14.4",
-    "@opengeni/db": "^0.16.2",
-    "@opengeni/documents": "^0.2.59",
-    "@opengeni/events": "^0.3.50",
-    "@opengeni/github": "^0.4.9",
+    "@opengeni/config": "^0.9.1",
+    "@opengeni/contracts": "^0.28.1",
+    "@opengeni/core": "^0.16.1",
+    "@opengeni/db": "^0.18.1",
+    "@opengeni/documents": "^0.2.63",
+    "@opengeni/events": "^0.3.54",
+    "@opengeni/github": "^0.4.13",
     "@opengeni/network": "^0.1.1",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.14.16",
-    "@opengeni/storage": "^0.2.46",
+    "@opengeni/runtime": "^0.15.3",
+    "@opengeni/storage": "^0.2.50",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -27,6 +27,7 @@ import { createObjectStorage } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
+import { compress } from "hono/compress";
 import { cors } from "hono/cors";
 import { HTTPException } from "hono/http-exception";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
@@ -68,11 +69,13 @@ import { registerSocialRoutes } from "./routes/social";
 import { registerWorkspaceRoutes } from "./routes/workspaces";
 import { registerWorkspaceInstructionPolicyRoutes } from "./routes/workspace-instruction-policies";
 import { registerWorkspaceStateRoutes } from "./routes/workspace-state";
+import { registerWorkspaceArtifactRoutes } from "./routes/workspace-artifacts";
 import { registerPreferenceRegistryRoutes } from "./routes/preference-registry";
 import { registerInsightsRoutes } from "./routes/insights";
 import { registerTranscriptionRoutes } from "./routes/transcriptions";
 import { projectClientModel } from "./model-catalog";
 import { createTranscriptionService } from "./transcription/service";
+import { registerSlackInteractionRoutes } from "./integrations/slack-interactions";
 
 export type {
   ApiRouteDeps,
@@ -104,6 +107,13 @@ export function apiRequestBodyLimitBytes(settings: { voiceInputMaxSizeBytes: num
 const API_PUBLIC_ERROR_MESSAGE_MAX_BYTES = 512;
 
 export function createApp(deps: AppDependencies): Hono {
+  return createAppComposition(deps).app;
+}
+
+export function createAppComposition(deps: AppDependencies): {
+  app: Hono;
+  routeDeps: ApiRouteDeps;
+} {
   const managedAuth = deps.managedAuth ?? createManagedAuth(deps.settings, deps.db);
   const objectStorage =
     deps.objectStorage === undefined ? createObjectStorage(deps.settings) : deps.objectStorage;
@@ -186,28 +196,34 @@ export function createApp(deps: AppDependencies): Hono {
     await next();
   });
 
-  app.use(
-    "*",
-    cors({
-      credentials: true,
-      allowHeaders: [
-        "Accept",
-        "Authorization",
-        "Content-Type",
-        "X-OpenGeni-Access-Key",
-        "X-OpenGeni-Api-Contract",
-        "X-OpenGeni-Correlation-Id",
-        "X-OpenGeni-Subject",
-      ],
-      exposeHeaders: ["X-OpenGeni-Api-Contract", "X-OpenGeni-Correlation-Id"],
-      origin: (origin) => {
-        if (!origin) {
-          return null;
-        }
-        return allowedCorsOrigin(deps.settings.corsAllowOriginRegex, origin) ? origin : null;
-      },
-    }),
-  );
+  const corsHeaders = {
+    allowHeaders: [
+      "Accept",
+      "Authorization",
+      "Content-Type",
+      "X-OpenGeni-Access-Key",
+      "X-OpenGeni-Api-Contract",
+      "X-OpenGeni-Correlation-Id",
+      "X-OpenGeni-Subject",
+    ],
+    exposeHeaders: ["X-OpenGeni-Api-Contract", "X-OpenGeni-Correlation-Id"],
+  };
+  const publicApiCors = cors({ ...corsHeaders, credentials: false, origin: "*" });
+  const credentialedCors = cors({
+    ...corsHeaders,
+    credentials: true,
+    origin: (origin) =>
+      allowedCorsOrigin(deps.settings.corsAllowOriginRegex, origin) ? origin : null,
+  });
+
+  app.use("*", (c, next) => {
+    const origin = c.req.header("origin");
+    const middleware =
+      origin && allowedCorsOrigin(deps.settings.corsAllowOriginRegex, origin)
+        ? credentialedCors
+        : publicApiCors;
+    return middleware(c, next);
+  });
 
   app.use(
     "*",
@@ -218,6 +234,20 @@ export function createApp(deps: AppDependencies): Hono {
     }),
   );
 
+  // Large catalog, capture, and session-list responses are on the browser's
+  // critical path. Compress JSON at the API boundary while leaving SSE and
+  // other streaming transports byte-for-byte unchanged.
+  const compressJson = compress({
+    encoding: "gzip",
+    contentTypeFilter: /^application\/json(?:;|$)/i,
+  });
+  app.use("/v1/*", async (c, next) => {
+    await compressJson(c, next);
+    if (/^application\/json(?:;|$)/i.test(c.res.headers.get("content-type") ?? "")) {
+      c.res.headers.set("vary", appendVary(c.res.headers.get("vary"), "Accept-Encoding"));
+    }
+  });
+
   app.use("*", async (c, next) => {
     const url = new URL(c.req.url);
     const route = routeLabel(url.pathname);
@@ -377,6 +407,7 @@ export function createApp(deps: AppDependencies): Hono {
         },
         productAccessMode: deps.settings.productAccessMode,
         auth: clientAuthConfig(deps.settings),
+        analytics: clientAnalyticsConfig(deps.settings),
         // Channel-A structured services (P4.4) ride exec/readFile/createEditor,
         // available on every real backend; `none` has no box so they are all off.
         // Per-session availability is still negotiated on /stream-capabilities.
@@ -392,7 +423,9 @@ export function createApp(deps: AppDependencies): Hono {
       boundedRequest = await boundedMcpRequest(c.req.raw);
     } catch (error) {
       if (error instanceof McpPayloadTooLargeError) {
-        throw new HTTPException(413, { message: "MCP request body exceeds the safety limit" });
+        throw new HTTPException(413, {
+          message: "MCP request body exceeds the safety limit",
+        });
       }
       throw error;
     }
@@ -414,7 +447,9 @@ export function createApp(deps: AppDependencies): Hono {
           throw new HTTPException(404, { message: "session not found" });
         }
         if (error instanceof SessionAuthorizationUnavailableError) {
-          throw new HTTPException(503, { message: "session authorization is unavailable" });
+          throw new HTTPException(503, {
+            message: "session authorization is unavailable",
+          });
         }
         throw error;
       }
@@ -422,10 +457,15 @@ export function createApp(deps: AppDependencies): Hono {
     let toolspace: Awaited<ReturnType<typeof prepareToolspaceMcpSurface>> = null;
     if (toolspaceGrant) {
       try {
-        toolspace = await prepareToolspaceMcpSurface({ deps: routeDeps, grant });
+        toolspace = await prepareToolspaceMcpSurface({
+          deps: routeDeps,
+          grant,
+        });
       } catch (error) {
         if (error instanceof McpPayloadTooLargeError) {
-          throw new HTTPException(413, { message: "MCP tool list exceeds the safety limit" });
+          throw new HTTPException(413, {
+            message: "MCP tool list exceeds the safety limit",
+          });
         }
         throw error;
       }
@@ -458,6 +498,7 @@ export function createApp(deps: AppDependencies): Hono {
   registerInsightsRoutes(app, routeDeps);
   registerWorkspaceInstructionPolicyRoutes(app, routeDeps);
   registerWorkspaceStateRoutes(app, routeDeps);
+  registerWorkspaceArtifactRoutes(app, routeDeps);
   registerPreferenceRegistryRoutes(app, routeDeps);
   registerSocialRoutes(app, routeDeps);
   registerConnectionRoutes(app, routeDeps);
@@ -472,6 +513,7 @@ export function createApp(deps: AppDependencies): Hono {
   registerScheduledTaskRoutes(app, routeDeps);
   registerCodexRoutes(app, routeDeps);
   registerTranscriptionRoutes(app, routeDeps);
+  registerSlackInteractionRoutes(app, routeDeps);
 
   app.notFound((c) => {
     if (!new URL(c.req.url).pathname.startsWith("/v1/")) return c.text("Not Found", 404);
@@ -513,7 +555,18 @@ export function createApp(deps: AppDependencies): Hono {
     return c.json(envelope, status as ContentfulStatusCode);
   });
 
-  return app;
+  return { app, routeDeps };
+}
+
+export function appendVary(current: string | null, value: string): string {
+  const values = (current ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (!values.some((entry) => entry.toLowerCase() === value.toLowerCase())) {
+    values.push(value);
+  }
+  return values.join(", ");
 }
 
 async function requireMcpAccessGrant(
@@ -559,6 +612,31 @@ function clientAuthConfig(settings: AppDependencies["settings"]) {
   return { mode: "none" as const };
 }
 
+function clientAnalyticsConfig(settings: AppDependencies["settings"]) {
+  if (!settings.analyticsEnabled) {
+    return { consentRequired: true, providers: {} };
+  }
+  return {
+    consentRequired: settings.analyticsConsentRequired,
+    providers: {
+      ...(settings.analyticsReoClientId
+        ? { reo: { clientId: settings.analyticsReoClientId } }
+        : {}),
+      ...(settings.analyticsPosthogProjectKey && settings.analyticsPosthogHost
+        ? {
+            posthog: {
+              projectKey: settings.analyticsPosthogProjectKey,
+              host: settings.analyticsPosthogHost,
+            },
+          }
+        : {}),
+      ...(settings.analyticsGa4MeasurementId
+        ? { ga4: { measurementId: settings.analyticsGa4MeasurementId } }
+        : {}),
+    },
+  };
+}
+
 function structuredServicesHint(backend: string): {
   fileSystem: boolean;
   git: boolean;
@@ -694,7 +772,9 @@ async function runReadinessChecks<const Checks extends Readonly<Record<string, R
       }
     }),
   );
-  const result = Object.fromEntries(entries) as { [Name in keyof Checks]: ReadinessCheckResult };
+  const result = Object.fromEntries(entries) as {
+    [Name in keyof Checks]: ReadinessCheckResult;
+  };
   return {
     ok: Object.values(result).every((check) => check.ok),
     checks: result,
@@ -1055,6 +1135,10 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/integrations\/slack\/callback$/,
     label: "/v1/integrations/slack/callback",
   },
+  {
+    pattern: /^\/v1\/social\/oauth\/callback$/,
+    label: "/v1/social/oauth/callback",
+  },
   {
     pattern: /^\/v1\/enrollments\/device\/start$/,
     label: "/v1/enrollments/device/start",
@@ -1122,6 +1206,9 @@ export function isApiContractProtectedMutation(method: string, pathname: string)
     pathname.startsWith("/v1/auth/") ||
     pathname.startsWith("/v1/webhooks/") ||
     pathname.startsWith("/v1/integrations/oauth/") ||
+    pathname === "/v1/integrations/slack/events" ||
+    pathname === "/v1/integrations/slack/commands" ||
+    pathname === "/v1/integrations/slack/interactions" ||
     pathname.startsWith("/v1/github/") ||
     pathname === "/v1/enrollments/device/start" ||
     pathname === "/v1/enrollments/device/poll" ||

package/src/http/auth.ts

@@ -50,10 +50,18 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (
     path === "/v1/integrations/oauth/callback" ||
     path === "/v1/integrations/oauth/client-metadata.json" ||
-    path === "/v1/integrations/slack/callback"
+    path === "/v1/integrations/slack/callback" ||
+    path === "/v1/integrations/slack/events" ||
+    path === "/v1/integrations/slack/commands" ||
+    path === "/v1/integrations/slack/interactions"
   ) {
     return true;
   }
+  // Social OAuth (X / Reddit) browser redirect: exact path only, protected by
+  // signed single-use state plus a callback-time grant recheck.
+  if (path === "/v1/social/oauth/callback") {
+    return true;
+  }
   // Catalog logos are rendered via bare <img> tags, which carry no credentials;
   // the images are public vendor logos, digest-keyed by content, and the route
   // itself enforces the catalog-assets/ prefix lock and extension whitelist.

package/src/index.ts

@@ -30,10 +30,11 @@ import {
   WorkflowExecutionAlreadyStartedError,
 } from "@temporalio/client";
 import type { ScheduleOptions, ScheduleSpec, ScheduleUpdateOptions } from "@temporalio/client";
-import { createApp, type DocumentIndexClient, type SessionWorkflowClient } from "./app";
+import { createAppComposition, type DocumentIndexClient, type SessionWorkflowClient } from "./app";
 import { observabilityEventLogger } from "./observability";
 import { startAuthCalloutResponder } from "./sandbox/auth-callout";
 import { startHelloIngestion, startMetricsIngestion } from "./sandbox/metrics-ingestion";
+import { startSlackInteractionPump } from "./integrations/slack-interactions";
 
 /**
  * A REJECT_DUPLICATE start collides on the deterministic workflowId when the
@@ -310,7 +311,7 @@ export async function startApi() {
     await dbClient.close();
     throw new Error("OpenGeni API startup dependencies were not initialized");
   }
-  const app = createApp({
+  const { app, routeDeps } = createAppComposition({
     settings,
     db: dbClient.db,
     bus,
@@ -327,6 +328,9 @@ export async function startApi() {
     idleTimeout: 255,
     fetch: app.fetch,
   });
+  const stopSlackInteractionPump = settings.slackSigningSecret
+    ? startSlackInteractionPump(routeDeps)
+    : undefined;
   // M10 — start the metrics-ingestion consumer (agent heartbeats → DB last-sample
   // + downsampled series), gated on the selfhosted flag. A no-op when disabled.
   let stopMetricsIngestion: (() => void) | undefined;
@@ -342,8 +346,16 @@ export async function startApi() {
   // user), separate from the privileged control-plane bus.
   let authCalloutResponder: ResponderConnection | undefined;
   if (settings.sandboxSelfhostedEnabled) {
-    stopMetricsIngestion = startMetricsIngestion({ db: dbClient.db, bus, observability });
-    stopHelloIngestion = startHelloIngestion({ db: dbClient.db, bus, observability });
+    stopMetricsIngestion = startMetricsIngestion({
+      db: dbClient.db,
+      bus,
+      observability,
+    });
+    stopHelloIngestion = startHelloIngestion({
+      db: dbClient.db,
+      bus,
+      observability,
+    });
     observability.info("OpenGeni machine-metrics + hello ingestion consumers started", {});
 
     const callout = resolveNatsCalloutConfig(settings);
@@ -375,6 +387,7 @@ export async function startApi() {
     server,
     close: async () => {
       server.stop(true);
+      stopSlackInteractionPump?.();
       stopMetricsIngestion?.();
       stopHelloIngestion?.();
       await Promise.allSettled([

package/src/integrations/oauth-client.ts

@@ -5,6 +5,7 @@ import { parseIntegrationsOauthClientsJson, type Settings } from "@opengeni/conf
 import {
   OPENGENI_PERSONAL_SLACK_MCP_URL,
   OAuthStartResponse,
+  selectCanonicalPersonalSlackConnection,
   type OAuthStartRequest,
 } from "@opengeni/contracts";
 import { hasPermission, requireEnvironmentEncryption } from "@opengeni/core";
@@ -161,6 +162,8 @@ export async function startMcpOAuth(
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     providerDomain,
+    mcpUrl,
+    personalSlack,
     connectionId: context.payload.connectionId,
   });
   if (context.payload.connectionId && !existing) {
@@ -847,6 +850,8 @@ async function existingOAuthConnectionForStart(
     workspaceId: string;
     subjectId: string;
     providerDomain: string;
+    mcpUrl: string;
+    personalSlack: boolean;
     connectionId?: string | undefined;
   },
 ) {
@@ -859,20 +864,23 @@ async function existingOAuthConnectionForStart(
     );
     return connection?.subjectId === input.subjectId &&
       connection.kind === "oauth2" &&
-      connection.providerDomain === input.providerDomain
+      connection.providerDomain === input.providerDomain &&
+      (!input.personalSlack || connection.metadata.mcpUrl === input.mcpUrl)
       ? connection
       : null;
   }
   const visible = await listConnectionsMetadata(db, input.workspaceId, input.subjectId);
-  return (
-    visible.find(
-      (connection) =>
-        connection.subjectId === input.subjectId &&
-        connection.kind === "oauth2" &&
-        connection.status === "active" &&
-        connection.providerDomain === input.providerDomain,
-    ) ?? null
+  const matching = visible.filter(
+    (connection) =>
+      connection.subjectId === input.subjectId &&
+      connection.kind === "oauth2" &&
+      connection.providerDomain === input.providerDomain &&
+      (!input.personalSlack || connection.metadata.mcpUrl === input.mcpUrl),
   );
+  if (input.personalSlack) {
+    return selectCanonicalPersonalSlackConnection(matching);
+  }
+  return matching.find((connection) => connection.status === "active") ?? null;
 }
 
 function buildAuthorizationUrl(input: {
@@ -1300,6 +1308,13 @@ function callbackReturnPath(
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
+  // Defense in depth: a `//host` pathname becomes a protocol-relative absolute
+  // Location — an open redirect from the unauthenticated callback.
+  if (url.pathname.startsWith("//")) {
+    const fallback = new URL("/integrations", "https://opengeni.local");
+    fallback.search = url.search;
+    return `${fallback.pathname}${fallback.search}`;
+  }
   return `${url.pathname}${url.search}${url.hash}`;
 }
 
@@ -1357,7 +1372,9 @@ function safeReturnPath(value: string): string {
     throw new HTTPException(400, { message: "OAuth returnPath must be a relative path" });
   }
   const parsed = new URL(value, "https://opengeni.local");
-  if (parsed.origin !== "https://opengeni.local") {
+  // `..` segments can normalize back into a `//host` prefix, which browsers
+  // resolve as a protocol-relative absolute URL. Reject the NORMALIZED path.
+  if (parsed.origin !== "https://opengeni.local" || parsed.pathname.startsWith("//")) {
     throw new HTTPException(400, { message: "OAuth returnPath must be a relative path" });
   }
   return `${parsed.pathname}${parsed.search}${parsed.hash}`;