@opengeni/api-router 3.0.1 → 3.1.2

package/dist/integrations/marketplace-plugin.d.ts

@@ -53,8 +53,8 @@ export declare function marketplacePlugin(url: string): {
         keywords: never[];
         author: {
             name: string;
-            url?: never;
             email?: never;
+            url?: never;
         };
         version: string;
         license: null;
@@ -349,9 +349,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 installation: string;
@@ -369,9 +369,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email?: never;
+            url?: never;
         };
         version: string;
         license: string;
@@ -395,9 +395,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 installation: string;
@@ -415,9 +415,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email?: never;
+            url?: never;
         };
         version: string;
         license: null;
@@ -441,9 +441,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 products?: never;
@@ -461,9 +461,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email?: never;
+            url?: never;
         };
         version: string;
         license: string;
@@ -487,9 +487,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 products?: never;
@@ -507,9 +507,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -533,9 +533,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 products?: never;
@@ -553,9 +553,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -576,9 +576,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 products?: never;
@@ -596,9 +596,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -622,9 +622,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
-                url?: never;
                 source: string;
                 path: string;
+                url?: never;
             };
             policy: {
                 products?: never;
@@ -769,9 +769,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -813,9 +813,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -896,9 +896,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -940,9 +940,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -984,9 +984,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1033,9 +1033,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1118,9 +1118,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1162,9 +1162,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1243,9 +1243,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1273,9 +1273,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1306,9 +1306,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1339,9 +1339,9 @@ export declare function marketplacePlugin(url: string): {
         category: null;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1427,9 +1427,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1471,9 +1471,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -1614,9 +1614,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1658,9 +1658,9 @@ export declare function marketplacePlugin(url: string): {
         category: null;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -1697,9 +1697,9 @@ export declare function marketplacePlugin(url: string): {
         category: null;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1741,9 +1741,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -1776,9 +1776,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -1853,9 +1853,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1897,9 +1897,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -1941,9 +1941,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: null;
         license: string;
@@ -1985,9 +1985,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: string;
@@ -2024,9 +2024,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -2235,9 +2235,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -2279,9 +2279,9 @@ export declare function marketplacePlugin(url: string): {
         category: null;
         keywords: never[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: null;
         license: null;
@@ -2369,9 +2369,9 @@ export declare function marketplacePlugin(url: string): {
         category: null;
         keywords: string[];
         author: {
-            url?: never;
             email?: never;
             name: string;
+            url?: never;
         };
         version: string;
         license: string;
@@ -2408,9 +2408,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: null;
@@ -2657,9 +2657,9 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: string[];
         author: {
-            url?: never;
             name: string;
             email: string;
+            url?: never;
         };
         version: string;
         license: string;

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

@@ -1,11 +1,39 @@
 import { type Settings } from "@opengeni/config";
-import { OAuthStartResponse, type ConnectionOwnership, type OAuthStartRequest } from "@opengeni/contracts";
+import { OAuthStartResponse, type OAuthStartRequest } from "@opengeni/contracts";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { Observability } from "@opengeni/observability";
-import { type Database } from "@opengeni/db";
+import { claimConnectOperation, finishConnectOperation, type Database } from "@opengeni/db";
 import { type McpAuthorizationServerMetadata } from "@opengeni/network";
 import { type OAuthProviderProfile } from "./oauth-profiles.js";
 export declare const oauthStateTtlMs: number;
+/**
+ * Workspace-free landing for a callback whose state names no trustworthy
+ * workspace. The web app resolves it to the viewer's current workspace
+ * integrations page and keeps the callback outcome parameters.
+ */
+export declare const INTEGRATIONS_FALLBACK_PATH = "/integrations";
+/** The web integrations page for one workspace (the Plugins surface). */
+export declare function workspaceIntegrationsPath(workspaceId: string): string;
+/**
+ * The integrations page for a workspace id read from untrusted input (a URL
+ * parameter or an unverified-age state), or null unless it is a workspace UUID.
+ * A link target only: it grants nothing.
+ */
+export declare function workspaceIntegrationsPathForUntrusted(candidate: unknown): string | null;
+/**
+ * Where a callback returns, and why, when its own signed state is unusable.
+ *
+ * A correctly signed state still names its workspace, even when it is too old
+ * or its flow rejected it, so the browser returns to that workspace's
+ * integrations page; an aged one is reported as expired. Anything unsigned,
+ * tampered, or signed with another secret returns to
+ * {@link INTEGRATIONS_FALLBACK_PATH}. Display routing only: nothing here
+ * authorizes, resumes, or replays the callback.
+ */
+export declare function oauthStateFailureReturn(settings: Settings, rawState: string | undefined, nowMs?: number): {
+    returnPath: string;
+    reason: "state_expired" | "state_invalid";
+};
 export { OFFICIAL_GMAIL_MCP_SCOPES, OFFICIAL_GMAIL_MCP_URL, OFFICIAL_SLACK_MCP_URL, } from "./oauth-profiles.js";
 export { OAUTH_MAX_RESPONSE_BYTES } from "@opengeni/network";
 type OAuthClientDeps = {
@@ -16,6 +44,8 @@ type OAuthClientDeps = {
     oauthCallbackDeadlineMs?: number | undefined;
 };
 export type OAuthStartContext = {
+    /** Server-selected dedicated adapter identity; never copied from request metadata. */
+    integrationKey?: "gmail" | "slack-personal";
     connectAttemptId?: string;
     externalContinuation?: ExternalActorContinuation;
     accountId: string;
@@ -37,21 +67,147 @@ export type OAuthCallbackResult = {
 type AuthorizationServerMetadata = McpAuthorizationServerMetadata;
 export declare const OAUTH_START_DEADLINE_MS = 15000;
 export declare const OAUTH_CALLBACK_DEADLINE_MS = 30000;
-export type OAuthStartStage = "connection_lookup" | "mcp_challenge" | "protected_resource_metadata" | "authorization_server_metadata" | "client_registration";
+export type OAuthStartStage = "connection_lookup" | "mcp_challenge" | "protected_resource_metadata" | "authorization_server_metadata" | "client_registration" | "state_persist";
+/** Policy is the outermost lock. Receipt replay still runs normal authorization,
+ * but the DB calls authorizeAcquisition only for uncommitted progress. Provider
+ * requests must happen after this transaction, never inside either wrapper. */
+export declare function claimOAuthAcquisition(db: Database, scope: Parameters<typeof claimConnectOperation>[1], input: Parameters<typeof claimConnectOperation>[2], integrationKey: string | null, acquiring?: boolean): Promise<{
+    status: "claimed";
+    attempt: import("@opengeni/contracts/connect").ConnectAttempt;
+} | {
+    status: "replayed";
+    attempt: import("@opengeni/contracts/connect").ConnectAttempt;
+}>;
+type IntegrationSourceSelection = Record<string, unknown> & {
+    id: string;
+    syncEnabled: boolean;
+    readPolicy: "allow" | "ask" | "block";
+};
+/** Compare server-bound selections, not provider classification. Removing a
+ * source, disabling sync, or narrowing its read permission acquires no authority.
+ * Generation/timestamp bookkeeping does not turn an unchanged save into setup. */
+export declare function integrationSourceSelectionRequiresAcquisition(previous: readonly IntegrationSourceSelection[], requested: readonly IntegrationSourceSelection[]): boolean;
+export declare function finishOAuthAcquisition(db: Database, scope: Parameters<typeof finishConnectOperation>[1], input: Parameters<typeof finishConnectOperation>[2], integrationKey: string | null): Promise<{
+    id: string;
+    workspaceId: string;
+    providerId: string;
+    ownership: "personal" | "workspace";
+    revision: number;
+    state: "account_selection" | "cancelled" | "complete" | "connected_but_incomplete" | "credential_input" | "expired" | "failed" | "installing" | "preview" | "provider_wait" | "ready" | "requires_user_action" | "resource_selection" | "uncertain";
+    credentialsCommitted: boolean;
+    integrationInstalled: boolean;
+    completionRequirement: "connection" | "integration" | "provider_setup";
+    nextAction: {
+        type: "authorize";
+        url: string;
+    } | {
+        type: "credentials";
+        fields: {
+            name: string;
+            label: string;
+            required: boolean;
+            secret: boolean;
+            options?: {
+                value: string;
+                label: string;
+            }[] | undefined;
+        }[];
+    } | {
+        type: "wait";
+        pollAfterMs: number;
+        userCode?: string | undefined;
+        verificationUrl?: string | undefined;
+    } | {
+        type: "select_account";
+        accounts: {
+            id: string;
+            providerId: string;
+            version?: number | undefined;
+            label: string;
+            ownership: "personal" | "workspace";
+            status: "auth_needed" | "connected" | "disabled";
+        }[];
+    } | {
+        type: "select_resources";
+        resources: {
+            id: string;
+            label: string;
+            kind: string;
+        }[];
+        cursor?: string | undefined;
+    } | {
+        type: "preview";
+        previewId: string;
+        contentHash: string;
+        operations: {
+            id: string;
+            label: string;
+            kind: string;
+        }[];
+    } | {
+        type: "none";
+    };
+    expiresAt: string;
+    account?: {
+        id: string;
+        providerId: string;
+        version?: number | undefined;
+        label: string;
+        ownership: "personal" | "workspace";
+        status: "auth_needed" | "connected" | "disabled";
+    } | undefined;
+    installationTarget?: {
+        instanceKey: string;
+        displayName: string;
+        expectedInstanceVersion?: number | undefined;
+    } | undefined;
+    source?: {
+        kind: "definition";
+        definitionId: string;
+    } | {
+        kind: "openapi";
+        url: string;
+        baseUrl?: string | undefined;
+    } | {
+        kind: "graphql";
+        endpoint: string;
+        name?: string | undefined;
+    } | {
+        kind: "auto";
+        url: string;
+        baseUrl?: string | undefined;
+    } | undefined;
+    mcpSetup?: {
+        name: string;
+        endpointUrl: string;
+        headers: ({
+            name: string;
+            value: string;
+        } | {
+            name: string;
+            secret: string;
+            prefix?: string | undefined;
+            suffix?: string | undefined;
+        })[];
+        secretFields: {
+            id: string;
+            label: string;
+        }[];
+    } | undefined;
+    mcpCapabilityId?: string | undefined;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | undefined;
+}>;
 export declare function startMcpOAuth(deps: OAuthClientDeps, context: OAuthStartContext): Promise<OAuthStartResponse>;
-/** Ownership fence for the official Gmail profile, keyed by exact MCP URL. */
-export declare function assertOfficialGmailPersonalOwnership(mcpUrl: string, ownership: ConnectionOwnership): void;
-/**
- * Slack's hosted MCP issues user tokens only. Sharing one human's grant as
- * workspace authority made every shared agent act as a named employee; the
- * OpenGeni workspace bot owns shared Slack access instead (bot-token search
- * covers public channels, files, and users).
- */
-export declare function assertHostedSlackMcpPersonalOwnership(hostedSlackMcp: boolean, ownership: ConnectionOwnership): void;
 export declare function isHostedSlackMcpTarget(providerDomain: string, mcpUrl: string): boolean;
 export declare function completeMcpOAuthCallback(deps: OAuthClientDeps, input: {
     code?: string | undefined;
     state?: string | undefined;
+    /** The provider's `error` parameter, for example `access_denied` on Cancel. */
+    error?: string | undefined;
     requestUrl: string;
 }): Promise<OAuthCallbackResult>;
 export declare function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl: string): string;
@@ -66,6 +222,8 @@ export declare function inspectMcpAuthentication(resource: string, settings: Set
     message?: string;
 }>;
 export declare function preferredOAuthSelfRegistration(as: Pick<AuthorizationServerMetadata, "clientIdMetadataDocumentSupported" | "registrationEndpoint">, clientSource: OAuthProviderProfile["clientSource"]): "cimd" | "dcr" | null;
+/** Secret-free readiness for the exact registered client used by Gmail setup. */
+export declare function gmailOAuthClientConfigured(settings: Settings): boolean;
 export declare function buildAuthorizationUrl(input: {
     endpoint: string;
     settings: Settings;
@@ -92,4 +250,5 @@ export declare function chooseMcpAuthorizeScopes(input: {
     requested: string[] | undefined;
     challenged: string[] | undefined;
     supported: string[];
+    authorizationServerScopesSupported?: string[];
 }): string[];