@opengeni/api-router 0.26.1 → 0.30.1

package/src/routes/connections.ts

@@ -12,6 +12,12 @@ import {
   ApiIntegrationOAuthStartRequest,
   ConnectionResponse,
   CreateConnectionRequest,
+  FIKEN_CREDENTIAL_LABEL,
+  FIKEN_CREDENTIAL_ROLE,
+  FIKEN_PROVIDER_DOMAIN,
+  FikenInstallRequest,
+  FikenOAuthStartRequest,
+  FikenOAuthStartResponse,
   IntegrationClientMetadata,
   ListSlackInstallationBindingsResponse,
   ListConnectionsResponse,
@@ -34,13 +40,17 @@ import {
   GoogleDriveOAuthStartResponse,
 } from "@opengeni/contracts/google-drive";
 import {
+  fikenConnectionMetadata,
   hasPermission,
+  hasReservedFikenMetadata,
   hasReservedOpenGeniSlackBotMetadata,
+  isFikenConnection,
   isOpenGeniSlackBotConnection,
   openGeniSlackBotMetadata,
   requireAccessGrant,
   requireAccessGrantAuthorization,
   requireEnvironmentEncryption,
+  resolveFikenDefaultCompanySlug,
 } from "@opengeni/core";
 import {
   consumeIntegrationOAuthStateNonce,
@@ -74,7 +84,6 @@ import {
 } from "../integrations/google-drive";
 import {
   completeApiIntegrationProviderOAuth,
-  isApiIntegrationProviderOAuthState,
   startApiIntegrationProviderOAuth,
 } from "../integrations/provider-oauth";
 import {
@@ -96,6 +105,12 @@ import {
   SlackBotCredentialVerificationError,
   verifyOpenGeniSlackBotCredential,
 } from "../integrations/slack-bot";
+import {
+  completeFikenOAuthCallback,
+  fikenCredentialBundle,
+  startFikenOAuth,
+  verifyFikenApiToken,
+} from "../integrations/fiken";
 import {
   OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
@@ -152,6 +167,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
     const payload = CreateConnectionRequest.parse(await c.req.json());
     assertNotReservedSlackBotMetadata(payload.metadata);
+    assertNotReservedFikenMetadata(payload.metadata);
     assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
     const key = requireEnvironmentEncryption(settings);
     const subjectId = createConnectionSubjectId(payload, grant.subjectId);
@@ -306,6 +322,120 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   });
 
+  // Verified paste-a-token install for the first-party Fiken connector. The
+  // token is validated against Fiken (and its accessible companies discovered)
+  // before it enters encrypted storage. Workspace-owned only.
+  app.post("/v1/workspaces/:workspaceId/connections/fiken/install", async (c) => {
+    assertIntegrationsEnabled();
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const payload = FikenInstallRequest.parse(await c.req.json());
+    const key = requireEnvironmentEncryption(settings);
+    const existing = payload.connectionId
+      ? await getConnectionMetadata(db, workspaceId, payload.connectionId, null)
+      : null;
+    if (payload.connectionId && !existing) {
+      throw new HTTPException(404, { message: "connection not found" });
+    }
+    if (existing && !isFikenConnection(existing)) {
+      throw new HTTPException(422, { message: "connectionId is not a Fiken connection" });
+    }
+    const verified = await verifyFikenApiToken(payload.apiToken, deps.fikenFetch ?? fetch);
+    const previousDefault = existing
+      ? (fikenConnectionMetadata(existing.metadata)?.defaultCompanySlug ?? null)
+      : null;
+    const defaultCompanySlug = resolveFikenDefaultCompanySlug({
+      requested: payload.defaultCompanySlug ?? null,
+      previous: previousDefault,
+      companies: verified.companies,
+    });
+    if (payload.defaultCompanySlug && defaultCompanySlug !== payload.defaultCompanySlug) {
+      throw new HTTPException(422, {
+        message: `defaultCompanySlug is not among the companies this token can access: ${verified.companies
+          .map((company) => company.slug)
+          .join(", ")}`,
+      });
+    }
+    const metadata = {
+      credentialRole: FIKEN_CREDENTIAL_ROLE,
+      credentialLabel: FIKEN_CREDENTIAL_LABEL,
+      companies: verified.companies,
+      defaultCompanySlug,
+      verifiedAt: new Date().toISOString(),
+    };
+    const credentialEncrypted = encryptCredentialBundle(
+      key,
+      fikenCredentialBundle(payload.apiToken),
+    );
+    if (existing) {
+      // Rewrites the whole credential identity: a token pasted over an OAuth
+      // row must also flip kind and clear the OAuth expiry, or the broker
+      // keeps treating the api_key bundle as a refreshable oauth2 credential.
+      const updated = await updateConnection(db, {
+        workspaceId,
+        connectionId: existing.id,
+        visibleToSubjectId: null,
+        expectedVersion: existing.version,
+        kind: "api_key",
+        status: "active",
+        credentialEncrypted,
+        grantedScopes: [],
+        expiresAt: null,
+        metadata,
+        updatedBySubjectId: grant.subjectId,
+      });
+      if (!updated) {
+        throw new HTTPException(409, { message: "the Fiken connection changed; retry" });
+      }
+      return c.json(ConnectionResponse.parse({ connection: updated }));
+    }
+    const connection = await createConnection(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: null,
+      providerDomain: FIKEN_PROVIDER_DOMAIN,
+      kind: "api_key",
+      credentialEncrypted,
+      grantedScopes: [],
+      expiresAt: null,
+      metadata,
+      createdBySubjectId: grant.subjectId,
+    });
+    return c.json(ConnectionResponse.parse({ connection }), 201);
+  });
+
+  // Fiken OAuth (registered app) start. Both Fiken lanes produce the same
+  // workspace-owned connection shape; this one refreshes through the broker.
+  app.post("/v1/workspaces/:workspaceId/connections/fiken/oauth/start", async (c) => {
+    assertIntegrationsEnabled();
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const payload = FikenOAuthStartRequest.parse(await c.req.json());
+    requireEnvironmentEncryption(settings);
+    return c.json(
+      FikenOAuthStartResponse.parse(
+        await startFikenOAuth(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          requestUrl: c.req.url,
+          payload,
+        }),
+      ),
+    );
+  });
+
+  app.get("/v1/integrations/fiken/callback", async (c) => {
+    assertIntegrationsEnabled();
+    const result = await completeFikenOAuthCallback(deps, {
+      ...(c.req.query("code") ? { code: c.req.query("code") } : {}),
+      ...(c.req.query("state") ? { state: c.req.query("state") } : {}),
+      ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
+      requestUrl: c.req.url,
+    });
+    return c.redirect(result.redirectTo, 302);
+  });
+
   app.post("/v1/workspaces/:workspaceId/connections/google-drive/install", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
@@ -429,9 +559,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
       requestUrl: c.req.url,
     };
-    const result = isApiIntegrationProviderOAuthState(input.state, deps.settings)
-      ? await completeApiIntegrationProviderOAuth(deps, input)
-      : await completeGoogleDriveOAuthCallback(deps, input);
+    const result = await completeGoogleDriveOAuthCallback(deps, input);
     return c.redirect(result.redirectTo, 302);
   });
 
@@ -532,6 +660,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const { grant } = authorization;
     const payload = UpdateConnectionRequest.parse(await c.req.json());
     assertNotReservedSlackBotMetadata(payload.metadata);
+    assertNotReservedFikenMetadata(payload.metadata);
     assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
     const existing = await getConnectionMetadata(
       db,
@@ -1135,6 +1264,14 @@ function assertNotReservedSlackBotMetadata(metadata: Record<string, unknown> | u
   }
 }
 
+function assertNotReservedFikenMetadata(metadata: Record<string, unknown> | undefined): void {
+  if (hasReservedFikenMetadata(metadata)) {
+    throw new HTTPException(422, {
+      message: "Fiken connection metadata is reserved for the verified Fiken connect flows",
+    });
+  }
+}
+
 function assertNotReservedApiIntegrationOAuthMetadata(
   metadata: Record<string, unknown> | undefined,
 ): void {

package/src/routes/{integration-features.ts → integration-facets.ts}

@@ -1,9 +1,9 @@
 import {
-  IntegrationFeatureMutationResult,
-  IntegrationFeatureRemovalResult,
-  IntegrationInstanceFeaturesResponse,
-  MutateIntegrationFeatureRequest,
-  UpsertIntegrationFeatureRequest,
+  IntegrationFacetMutationResult,
+  IntegrationFacetRemovalResult,
+  IntegrationInstanceFacetsResponse,
+  MutateIntegrationFacetRequest,
+  UpsertIntegrationFacetRequest,
 } from "@opengeni/contracts";
 import {
   hasPermission,
@@ -12,52 +12,52 @@ import {
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
-  configureIntegrationFeature,
-  IntegrationFeatureBindingOwnershipConflictError,
-  IntegrationFeatureBindingVersionConflictError,
-  IntegrationFeatureBindingVersionRequiredError,
-  IntegrationFeatureConfigError,
-  IntegrationFeatureConnectionError,
-  IntegrationFeatureNotFoundError,
-  IntegrationFeatureOperationIdempotencyError,
-  listIntegrationInstanceFeatures,
-  removeIntegrationFeature,
-  setIntegrationFeatureLifecycle,
+  configureIntegrationFacet,
+  IntegrationFacetBindingOwnershipConflictError,
+  IntegrationFacetBindingVersionConflictError,
+  IntegrationFacetBindingVersionRequiredError,
+  IntegrationFacetConfigError,
+  IntegrationFacetConnectionError,
+  IntegrationFacetNotFoundError,
+  IntegrationFacetOperationIdempotencyError,
+  listIntegrationInstanceFacets,
+  removeIntegrationFacet,
+  setIntegrationFacetLifecycle,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 
 import {
-  browseGoogleDriveIntegrationSource,
-  saveGoogleDriveIntegrationSource,
+  browseGoogleDriveFacetSource,
+  saveGoogleDriveFacetSource,
 } from "../integrations/google-drive";
 
-export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps): void {
+export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get(
-    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/browse",
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/browse",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
       const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
       try {
         return c.json(
-          await browseGoogleDriveIntegrationSource(deps, {
+          await browseGoogleDriveFacetSource(deps, {
             workspaceId,
             subjectId: grant.subjectId,
             capabilityId: decoded(c.req.param("capabilityId")),
             instanceKey: decoded(c.req.param("instanceKey")),
-            featureKey: decoded(c.req.param("featureKey")),
+            facetKey: decoded(c.req.param("facetKey")),
             parentId: c.req.query("parentId") ?? "root",
             ...(c.req.query("pageToken") ? { pageToken: c.req.query("pageToken") } : {}),
           }),
         );
       } catch (error) {
-        throw featureHttpError(error);
+        throw facetHttpError(error);
       }
     },
   );
 
   app.put(
-    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/source",
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/source",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
       const authorization = await requireAccessGrantAuthorization(
@@ -69,14 +69,14 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
       const { grant } = authorization;
       try {
         return c.json(
-          IntegrationFeatureMutationResult.parse(
-            await saveGoogleDriveIntegrationSource(deps, {
+          IntegrationFacetMutationResult.parse(
+            await saveGoogleDriveFacetSource(deps, {
               accountId: grant.accountId,
               workspaceId,
               subjectId: grant.subjectId,
               capabilityId: decoded(c.req.param("capabilityId")),
               instanceKey: decoded(c.req.param("instanceKey")),
-              featureKey: decoded(c.req.param("featureKey")),
+              facetKey: decoded(c.req.param("facetKey")),
               payload: await c.req.json(),
               canManageOrganizationDestination:
                 authorization.accountGrant?.permissions.includes("account:admin") === true,
@@ -88,20 +88,20 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
           ),
         );
       } catch (error) {
-        throw featureHttpError(error);
+        throw facetHttpError(error);
       }
     },
   );
 
   app.get(
-    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features",
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
       const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
       try {
         return c.json(
-          IntegrationInstanceFeaturesResponse.parse(
-            await listIntegrationInstanceFeatures(
+          IntegrationInstanceFacetsResponse.parse(
+            await listIntegrationInstanceFacets(
               deps.db,
               workspaceId,
               grant.subjectId,
@@ -111,30 +111,30 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
           ),
         );
       } catch (error) {
-        throw featureHttpError(error);
+        throw facetHttpError(error);
       }
     },
   );
 
   app.put(
-    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey",
+    "/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 = UpsertIntegrationFeatureRequest.parse(await c.req.json());
+      const payload = UpsertIntegrationFacetRequest.parse(await c.req.json());
       const capabilityId = decoded(c.req.param("capabilityId"));
       const instanceKey = decoded(c.req.param("instanceKey"));
-      const featureKey = decoded(c.req.param("featureKey"));
+      const facetKey = decoded(c.req.param("facetKey"));
       try {
-        const instance = await listIntegrationInstanceFeatures(
+        const instance = await listIntegrationInstanceFacets(
           deps.db,
           workspaceId,
           grant.subjectId,
           capabilityId,
           instanceKey,
         );
-        const definition = instance.features.find(
-          (feature) => feature.definition.featureKey === featureKey,
+        const definition = instance.facets.find(
+          (facet) => facet.definition.facetKey === facetKey,
         )?.definition;
         if (
           definition?.kind === "knowledge_source" &&
@@ -146,14 +146,14 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
           });
         }
         return c.json(
-          IntegrationFeatureMutationResult.parse(
-            await configureIntegrationFeature(deps.db, {
+          IntegrationFacetMutationResult.parse(
+            await configureIntegrationFacet(deps.db, {
               accountId: grant.accountId,
               workspaceId,
               subjectId: grant.subjectId,
               capabilityId,
               instanceKey,
-              featureKey,
+              facetKey,
               displayName: payload.displayName,
               config: payload.config,
               ...(payload.expectedVersion !== undefined
@@ -165,28 +165,28 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
           payload.expectedVersion === undefined ? 201 : 200,
         );
       } catch (error) {
-        throw featureHttpError(error);
+        throw facetHttpError(error);
       }
     },
   );
 
   for (const action of ["pause", "resume"] as const) {
     app.post(
-      `/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/${action}`,
+      `/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 = MutateIntegrationFeatureRequest.parse(await c.req.json());
+        const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
         try {
           return c.json(
-            IntegrationFeatureMutationResult.parse(
-              await setIntegrationFeatureLifecycle(deps.db, {
+            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")),
-                featureKey: decoded(c.req.param("featureKey")),
+                facetKey: decoded(c.req.param("facetKey")),
                 action,
                 expectedVersion: payload.expectedVersion,
                 idempotencyKey: payload.idempotencyKey,
@@ -194,35 +194,35 @@ export function registerIntegrationFeatureRoutes(app: Hono, deps: ApiRouteDeps):
             ),
           );
         } catch (error) {
-          throw featureHttpError(error);
+          throw facetHttpError(error);
         }
       },
     );
   }
 
   app.delete(
-    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey",
+    "/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 = MutateIntegrationFeatureRequest.parse(await c.req.json());
+      const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
       try {
         return c.json(
-          IntegrationFeatureRemovalResult.parse(
-            await removeIntegrationFeature(deps.db, {
+          IntegrationFacetRemovalResult.parse(
+            await removeIntegrationFacet(deps.db, {
               accountId: grant.accountId,
               workspaceId,
               subjectId: grant.subjectId,
               capabilityId: decoded(c.req.param("capabilityId")),
               instanceKey: decoded(c.req.param("instanceKey")),
-              featureKey: decoded(c.req.param("featureKey")),
+              facetKey: decoded(c.req.param("facetKey")),
               expectedVersion: payload.expectedVersion,
               idempotencyKey: payload.idempotencyKey,
             }),
           ),
         );
       } catch (error) {
-        throw featureHttpError(error);
+        throw facetHttpError(error);
       }
     },
   );
@@ -232,25 +232,25 @@ function decoded(value: string): string {
   return decodeURIComponent(value);
 }
 
-function featureHttpError(error: unknown): HTTPException {
+function facetHttpError(error: unknown): HTTPException {
   if (error instanceof HTTPException) return error;
-  if (error instanceof IntegrationFeatureNotFoundError) {
+  if (error instanceof IntegrationFacetNotFoundError) {
     return new HTTPException(404, { message: error.message });
   }
   if (
-    error instanceof IntegrationFeatureBindingVersionConflictError ||
-    error instanceof IntegrationFeatureBindingVersionRequiredError ||
-    error instanceof IntegrationFeatureBindingOwnershipConflictError ||
-    error instanceof IntegrationFeatureOperationIdempotencyError
+    error instanceof IntegrationFacetBindingVersionConflictError ||
+    error instanceof IntegrationFacetBindingVersionRequiredError ||
+    error instanceof IntegrationFacetBindingOwnershipConflictError ||
+    error instanceof IntegrationFacetOperationIdempotencyError
   ) {
     return new HTTPException(409, {
       message:
-        "The Integration feature changed, is shared, or reused an idempotency key. Refresh before retrying.",
+        "The Integration facet changed, is shared, or reused an idempotency key. Refresh before retrying.",
     });
   }
   if (
-    error instanceof IntegrationFeatureConfigError ||
-    error instanceof IntegrationFeatureConnectionError
+    error instanceof IntegrationFacetConfigError ||
+    error instanceof IntegrationFacetConnectionError
   ) {
     return new HTTPException(422, { message: error.message });
   }