@opengeni/api-router 0.30.1 → 1.0.0

package/src/integrations/social-oauth.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { parseSocialOauthClientsJson, type Settings } from "@opengeni/config";
 import {
   OAuthStartResponse,
@@ -15,6 +17,8 @@ import {
   loadSocialConnectionCredential,
   updateSocialConnectionCredential,
   upsertSocialOAuthConnection,
+  finishConnectOperation,
+  getConnectAttempt,
   type Database,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
@@ -22,11 +26,20 @@ import { OAUTH_MAX_RESPONSE_BYTES, pinnedFetch, readResponseJsonBounded } from "
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
 import { HTTPException } from "hono/http-exception";
+import {
+  personalOwnerStateAccepted,
+  personalOwnerVerifiedInState,
+  PERSONAL_CONNECTION_PRINCIPAL_MESSAGE,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import { ApiHttpError } from "../http/api-error";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 // Reddit requires a descriptive, stable User-Agent on every request (token
@@ -129,19 +142,28 @@ function socialProviderFetch(
 }
 
 export type SocialOAuthStartContext = {
+  connectAttemptId?: string;
   accountId: string;
   workspaceId: string;
   subjectId: string;
+  /**
+   * False for every principal that cannot own a personal Connection. Resolved
+   * by the route from the live authenticated principal, never inferred here.
+   */
+  personalOwnershipAllowed: boolean;
   requestUrl: string;
   payload: SocialOAuthStartRequest;
 };
 
 type SocialOAuthStatePayload = {
+  connectAttemptId?: string;
   kind: "social_oauth";
   accountId: string;
   workspaceId: string;
   subjectId: string;
   ownership: "workspace" | "personal";
+  /** Signed proof that a live managed human authorized personal ownership. */
+  personalOwnerVerified: boolean;
   provider: SocialOAuthProviderId;
   scopes: string[];
   encryptedPkceVerifier?: string;
@@ -177,9 +199,12 @@ export async function startSocialOAuth(
 ): Promise<OAuthStartResponse> {
   const { settings } = deps;
   const provider = SOCIAL_OAUTH_PROVIDERS[context.payload.provider];
+  await withOrganizationIntegrationAcquisition(deps.db, context, [provider.id], async () => {});
   const client = socialOAuthClientFor(settings, provider.id);
   const redirectUri = socialOAuthRedirectUri(settings, context.requestUrl);
-  const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
+  const returnPath = safeReturnPath(
+    context.payload.returnPath ?? workspaceIntegrationsPath(context.workspaceId),
+  );
   const scopes = uniqueScopes(context.payload.scopes) ?? provider.defaultScopes;
   const verifier = provider.pkce ? randomBytes(32).toString("base64url") : null;
   // Require the encryption key for every provider (not just PKCE ones) so a
@@ -188,10 +213,14 @@ export async function startSocialOAuth(
   const key = requireEnvironmentEncryption(settings);
   const state = createSignedState(requireIntegrationsStateSecret(settings), {
     kind: "social_oauth",
+    ...(context.connectAttemptId ? { connectAttemptId: context.connectAttemptId } : {}),
     accountId: context.accountId,
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     ownership: context.payload.ownership,
+    // Signed record that a live principal was checked; the callback has no
+    // principal of its own and enforces exactly this decision.
+    [PERSONAL_OWNER_VERIFIED_STATE_CLAIM]: context.personalOwnershipAllowed,
     provider: provider.id,
     scopes,
     ...(verifier && key ? { encryptedPkceVerifier: encryptEnvironmentValue(key, verifier) } : {}),
@@ -228,17 +257,19 @@ export async function completeSocialOAuthCallback(
     error?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const { db, settings, observability } = deps;
   let state: SocialOAuthStatePayload | null = null;
   try {
     state = readSocialOAuthState(input.state, settings);
   } catch (error) {
     logSocialOAuthFailure(observability, "state_verify", state, error);
+    const failure = oauthStateFailureReturn(settings, input.state);
     return {
-      redirectTo: callbackReturnPath("/integrations", "error", { reason: "state_invalid" }),
+      redirectTo: callbackReturnPath(failure.returnPath, "error", { reason: failure.reason }),
     };
   }
+  if (state.connectAttemptId) return completeSocialConnect(deps, state, input);
   // Provider denial / missing code: report before burning the single-use
   // nonce so a user who cancelled at the provider can retry the same flow
   // within the state TTL.
@@ -274,6 +305,13 @@ export async function completeSocialOAuthCallback(
   // the MCP OAuth client — a grant revoked inside the state TTL must not be
   // able to land a workspace credential.
   try {
+    // Only a managed human may own a personal Connection. This callback has no
+    // live principal, so it enforces the signed start-time decision; a state
+    // minted before that fence existed carries no claim and is refused, which
+    // closes the in-flight window across a rolling deploy.
+    if (!personalOwnerStateAccepted(state)) {
+      throw new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
+    }
     const grant = await getWorkspaceGrant(db, state.subjectId, state.workspaceId);
     if (
       !grant ||
@@ -292,6 +330,7 @@ export async function completeSocialOAuthCallback(
   }
   try {
     const provider = SOCIAL_OAUTH_PROVIDERS[state.provider];
+    await withOrganizationIntegrationAcquisition(db, state, [provider.id], async () => {});
     const client = socialOAuthClientFor(settings, provider.id);
     const key = requireEnvironmentEncryption(settings);
     const verifier = state.encryptedPkceVerifier
@@ -313,18 +352,31 @@ export async function completeSocialOAuthCallback(
       ...(token.scope ? { scope: token.scope } : {}),
     };
     const grantedScopes = token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes;
-    const connection = await upsertSocialOAuthConnection(db, {
-      accountId: state.accountId,
-      workspaceId: state.workspaceId,
-      subjectId: state.ownership === "personal" ? state.subjectId : null,
-      provider: provider.id,
-      accountHandle: identity.handle,
-      accountName: identity.name ?? null,
-      externalAccountId: identity.externalAccountId,
-      scopes: grantedScopes,
-      credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
-      tokenMetadata: publicTokenMetadata(bundle),
-    });
+    const acceptedState = state;
+    const connection = await withOrganizationIntegrationAcquisition(
+      db,
+      acceptedState,
+      [provider.id],
+      async (tx) => {
+        await requireConnectOwnerAuthority(
+          tx,
+          acceptedState,
+          acceptedState.ownership === "workspace" ? "workspace:admin" : "workspace:read",
+        );
+        return upsertSocialOAuthConnection(tx, {
+          accountId: acceptedState.accountId,
+          workspaceId: acceptedState.workspaceId,
+          subjectId: acceptedState.ownership === "personal" ? acceptedState.subjectId : null,
+          provider: provider.id,
+          accountHandle: identity.handle,
+          accountName: identity.name ?? null,
+          externalAccountId: identity.externalAccountId,
+          scopes: grantedScopes,
+          credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+          tokenMetadata: publicTokenMetadata(bundle),
+        });
+      },
+    );
     return {
       redirectTo: callbackReturnPath(state.returnPath, "success", {
         connectionId: connection.id,
@@ -342,6 +394,147 @@ export async function completeSocialOAuthCallback(
   }
 }
 
+/** Durable host setup keeps social credentials in their original domain. The
+ * stored origin, not the unauthenticated callback, supplies current authority. */
+async function completeSocialConnect(
+  deps: SocialOAuthDeps,
+  state: SocialOAuthStatePayload,
+  input: {
+    state?: string | undefined;
+    code?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+  },
+): Promise<{ redirectTo: string; exactReturn: true }> {
+  const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId!);
+  if (stored.attempt.providerId !== state.provider || stored.attempt.ownership !== state.ownership)
+    throw new HTTPException(400, { message: "Social connection attempt mismatch" });
+  const authorize: import("@opengeni/db").ConnectOperationAuthorization = async (
+    tx,
+    _attempt,
+    origin,
+  ) => {
+    await requireConnectOwnerAuthority(
+      tx,
+      { ...state, ...(origin ? { externalContinuation: origin } : {}) },
+      state.ownership === "workspace" ? "workspace:admin" : "workspace:read",
+      origin,
+    );
+  };
+  const operation = {
+    attemptId: state.connectAttemptId!,
+    operationId: `social:${state.nonce}`,
+    inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+    authorize,
+  };
+  try {
+    const claim = await claimOAuthAcquisition(
+      deps.db,
+      state,
+      {
+        ...operation,
+        expectedRevision: stored.attempt.revision,
+      },
+      state.provider,
+      Boolean(input.code && !input.error),
+    );
+    if (claim.status === "replayed") return { redirectTo: stored.returnUrl, exactReturn: true };
+    if (!personalOwnerStateAccepted(state))
+      throw new HTTPException(403, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
+    if (input.error || !input.code) {
+      await finishConnectOperation(deps.db, state, {
+        ...operation,
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: input.error === "access_denied" ? "cancelled" : "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: "authorization_not_completed",
+            message: "Authorization was not completed. Start a new attempt.",
+            retryable: false,
+          },
+        }),
+      });
+    } else {
+      const provider = SOCIAL_OAUTH_PROVIDERS[state.provider];
+      const key = requireEnvironmentEncryption(deps.settings);
+      const verifier = state.encryptedPkceVerifier
+        ? decryptEnvironmentValue(key, state.encryptedPkceVerifier)
+        : null;
+      const token = await socialTokenRequest(
+        deps,
+        provider,
+        socialOAuthClientFor(deps.settings, provider.id),
+        {
+          grant_type: "authorization_code",
+          code: input.code,
+          redirect_uri: socialOAuthRedirectUri(deps.settings, input.requestUrl),
+          ...(verifier ? { code_verifier: verifier } : {}),
+        },
+      );
+      const identity = await fetchSocialIdentity(deps, provider.id, token.accessToken);
+      const bundle: SocialCredentialBundle = {
+        provider: provider.id,
+        accessToken: token.accessToken,
+        tokenType: token.tokenType,
+        ...(token.refreshToken ? { refreshToken: token.refreshToken } : {}),
+        ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
+        ...(token.scope ? { scope: token.scope } : {}),
+      };
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          commit: async (tx, current) => {
+            const connection = await upsertSocialOAuthConnection(tx, {
+              accountId: state.accountId,
+              workspaceId: state.workspaceId,
+              ...(current.account
+                ? {
+                    expectedConnection: {
+                      id: current.account.id.slice("social:".length),
+                      version: current.account.version!,
+                    },
+                  }
+                : {}),
+              subjectId: state.ownership === "personal" ? state.subjectId : null,
+              provider: provider.id,
+              accountHandle: identity.handle,
+              accountName: identity.name ?? null,
+              externalAccountId: identity.externalAccountId,
+              scopes: token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes,
+              credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+              tokenMetadata: publicTokenMetadata(bundle),
+            });
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: `social:${connection.id}`,
+                providerId: provider.id,
+                version: connection.version!,
+                label: identity.handle,
+                ownership: state.ownership,
+                status: "connected",
+              },
+            };
+          },
+        },
+        state.provider,
+      );
+    }
+  } catch (error) {
+    // An uncertain exchange stays occupied: do not replay a consumed OAuth code.
+    logSocialOAuthFailure(deps.observability, "connect_callback", state, error);
+  }
+  return { redirectTo: stored.returnUrl, exactReturn: true };
+}
+
 /**
  * Resolves a usable access token for a social connection, refreshing (and
  * persisting the rotated bundle) when the stored token is near expiry. Marks
@@ -683,10 +876,15 @@ function readSocialOAuthState(
   }
   return {
     kind: "social_oauth",
+    ...(typeof payload.connectAttemptId === "string"
+      ? { connectAttemptId: payload.connectAttemptId }
+      : {}),
     accountId: requiredStateString(payload.accountId, "accountId"),
     workspaceId: requiredStateString(payload.workspaceId, "workspaceId"),
     subjectId: requiredStateString(payload.subjectId, "subjectId"),
     ownership: payload.ownership === "personal" ? "personal" : "workspace",
+    // Absent on a legacy state, which therefore cannot land a personal owner.
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     provider,
     scopes: Array.isArray(payload.scopes)
       ? payload.scopes.filter((scope): scope is string => typeof scope === "string")

package/src/interaction-agent-access.ts

@@ -0,0 +1,48 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import {
+  requireSessionAuthorization,
+  SessionAuthorizationDeniedError,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+
+type AssociatedInteractionSession = {
+  associations: ReadonlyArray<{ sessionId: string; relationship: string }>;
+};
+
+/**
+ * Apply the same source-chat authorization as get/control routes, for every
+ * caller. A later using/observing/related association never transfers ownership
+ * or makes a private interaction discoverable through another chat.
+ */
+export async function filterInteractionSessionsForGrant<T extends AssociatedInteractionSession>(
+  deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">,
+  grant: AccessGrant,
+  sessions: readonly T[],
+): Promise<T[]> {
+  const decisions = new Map<string, Promise<boolean>>();
+  const authorized = (sessionId: string): Promise<boolean> => {
+    let decision = decisions.get(sessionId);
+    if (!decision) {
+      decision = requireSessionAuthorization(deps, grant, {
+        sessionId,
+        operation: "session.read",
+        surface: "http",
+      })
+        .then(() => true)
+        .catch((error: unknown) => {
+          if (error instanceof SessionAuthorizationDeniedError) return false;
+          throw error;
+        });
+      decisions.set(sessionId, decision);
+    }
+    return decision;
+  };
+  const kept: T[] = [];
+  for (const session of sessions) {
+    const sources = session.associations.filter((entry) => entry.relationship === "created");
+    // Control-record resolution also requires exactly one creation association.
+    // Incomplete or ambiguous records cannot establish a discoverable owner.
+    if (sources.length === 1 && (await authorized(sources[0]!.sessionId))) kept.push(session);
+  }
+  return kept;
+}