@opengeni/api-router 0.30.1 → 1.0.0

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

@@ -1,11 +1,40 @@
 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;
-export declare const OFFICIAL_SLACK_MCP_URL: "https://mcp.slack.com/mcp";
-export declare const OFFICIAL_GMAIL_MCP_URL = "https://gmailmcp.googleapis.com/mcp/v1";
-export declare const OFFICIAL_GMAIL_MCP_SCOPES: readonly ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.modify"];
+/**
+ * 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 = {
     db: Database;
@@ -15,40 +44,168 @@ 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;
     workspaceId: string;
     subjectId: string;
+    /**
+     * False for every principal that cannot own a personal Connection (API keys,
+     * the configured key, services, agent attempts). Resolved by the route from
+     * the live authenticated principal, never inferred here.
+     */
+    personalOwnershipAllowed: boolean;
     requestUrl: string;
     payload: OAuthStartRequest;
 };
 export type OAuthCallbackResult = {
     redirectTo: string;
+    exactReturn?: boolean;
 };
-type AuthorizationServerMetadata = {
-    issuer: string;
-    authorizationServer: string;
-    authorizationEndpoint: string;
-    tokenEndpoint: string;
-    registrationEndpoint?: string;
-    clientIdMetadataDocumentSupported: boolean;
-    tokenEndpointAuthMethodsSupported: string[];
-    codeChallengeMethodsSupported: string[];
-    raw: Record<string, unknown>;
-};
+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;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | undefined;
+}>;
 export declare function startMcpOAuth(deps: OAuthClientDeps, context: OAuthStartContext): Promise<OAuthStartResponse>;
-export declare function assertOfficialGmailPersonalOwnership(mcpUrl: string, 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;
 export declare function requireIntegrationsStateSecret(settings: Settings): string;
+/** The hosted-Slack profile's origin pins, kept exported for its tests. */
 export declare function assertSlackAuthorizationServer(as: AuthorizationServerMetadata): void;
+/** The official-Gmail profile's origin pins, kept exported for its tests. */
 export declare function assertGoogleAuthorizationServer(as: AuthorizationServerMetadata): void;
+/** Inspect without credentials, registration, or running tools. */
+export declare function inspectMcpAuthentication(resource: string, settings: Settings): Promise<{
+    kind: "oauth2" | "none" | "unknown";
+    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;
@@ -59,6 +216,8 @@ export declare function buildAuthorizationUrl(input: {
     verifier: string;
     scopes: string[];
     resourceParameterSupported: boolean;
+    /** Profile-declared extra authorize parameters, applied last. */
+    extraParams?: Readonly<Record<string, string>> | undefined;
 }): string;
 export type OAuthPublicErrorFields = {
     errorClass: "OAuthOperationError";
@@ -73,4 +232,5 @@ export declare function chooseMcpAuthorizeScopes(input: {
     requested: string[] | undefined;
     challenged: string[] | undefined;
     supported: string[];
+    authorizationServerScopesSupported?: string[];
 }): string[];

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

@@ -0,0 +1,222 @@
+import { type ConnectionOwnership } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import { z } from "zod";
+/**
+ * Provider OAuth quirks as data.
+ *
+ * Some providers do not support DCR or CIMD and need a pre-registered client
+ * with pinned metadata; some issue personal tokens only; some reject RFC 8707's
+ * `resource` parameter. Each used to be a hand-written branch set inside
+ * `oauth-client.ts`; every quirk is now a field on an `OAuthProviderProfile`.
+ * The flow reads exactly one resolved profile and contains no provider-name
+ * conditional.
+ *
+ * Profiles come from two layers:
+ *
+ * 1. Built-in profiles pin known authorization servers and protocol quirks.
+ *    Ownership defaults guide setup; users may choose personal or workspace.
+ *    Authorization-server pins never depend on catalog import state.
+ * 2. A validated `oauthProfile` object on a global catalog row (curated
+ *    overlay -> importer -> `capability_catalog_items.metadata`). A catalog
+ *    profile applies only when no built-in matches, and it can only narrow the
+ *    default behavior, never loosen a built-in fence.
+ */
+export declare const OFFICIAL_SLACK_MCP_URL: "https://mcp.slack.com/mcp";
+export declare const OFFICIAL_GMAIL_MCP_URL = "https://gmailmcp.googleapis.com/mcp/v1";
+export declare const OFFICIAL_GMAIL_MCP_SCOPES: readonly ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.modify"];
+/** The slice of discovered authorization-server metadata the pins constrain. */
+export type PinnableAuthorizationServer = {
+    issuer: string;
+    authorizationServer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+};
+export type AuthorizationServerPins = {
+    /** Origins `issuer` and `authorizationServer` must both belong to. */
+    issuerOrigins: readonly string[];
+    /** Origins the authorization endpoint must belong to. */
+    authorizationEndpointOrigins: readonly string[];
+    /** Origins the token endpoint must belong to. */
+    tokenEndpointOrigins: readonly string[];
+    /** Exact 422 message when a pin fails. */
+    message: string;
+    /** Skip enforcement in a local test environment (loopback fixtures). */
+    skipInLocalTest: boolean;
+};
+export type OAuthProviderProfile = {
+    /** Stable identity for guards, logs, and tests. */
+    key: string;
+    /** Built-in matching; catalog profiles match their own row's exact mcpUrl. */
+    match: {
+        mcpUrls?: readonly string[];
+        providerDomains?: readonly string[];
+    };
+    /**
+     * Canonical provider identity forced when the profile matches by URL, so a
+     * caller cannot relabel a pinned resource under another domain.
+     */
+    canonicalProviderDomain?: string;
+    /** Reject a caller-supplied manual OAuth client (deployment-managed only). */
+    rejectCallerOAuthClient?: {
+        message: string;
+    };
+    /** The payload's explicit providerDomain must canonicalize to this domain. */
+    requireProviderDomain?: {
+        domain: string;
+        message: string;
+    };
+    /** Outside a local test environment, the start URL must be exactly this. */
+    requireExactMcpUrl?: {
+        url: string;
+        message: string;
+    };
+    /** Deployment-managed client credentials must be configured (503 otherwise). */
+    requireDeploymentClient?: {
+        key: DeploymentManagedClientKey;
+        message: string;
+    };
+    /** Suggested ownership; explicit choices remain subject to requiredOwnership. */
+    defaultOwnership?: ConnectionOwnership;
+    /** Built-in-only ownership restriction, including old reconnect/callback state. */
+    requiredOwnership?: {
+        ownership: ConnectionOwnership;
+        message: string;
+    };
+    /** Bind reconnect/dedupe to the exact mcpUrl, not just the provider domain. */
+    exactMcpBinding: boolean;
+    /** How an existing connection is chosen for reconnect coalescing. */
+    connectionSelection: "canonical_personal" | "first_active";
+    /** Post-discovery authorization-server origin pins. */
+    authorizationServer?: AuthorizationServerPins;
+    /**
+     * Post-discovery identity check: the resolved providerDomain must equal this
+     * domain (the reserved-authorization-server guard shares its message).
+     */
+    postDiscoveryProviderDomain?: {
+        domain: string;
+        message: string;
+    };
+    /**
+     * Client registration preference. `dcr` or `cimd` forces that advertised
+     * self-registration mechanism after operator/deployment clients. Without an
+     * explicit preference, DCR wins when both mechanisms are advertised.
+     */
+    clientSource?: "deployment_managed" | "cimd" | "dcr";
+    /** Send RFC 8707 `resource` on authorize and token requests. */
+    sendResourceParameter: boolean;
+    /** Extra authorize-URL query parameters (e.g. offline-consent opts). */
+    extraAuthorizeParams?: Readonly<Record<string, string>>;
+    /** Exact scope override; the caller can never widen past it. */
+    requestedScopes?: readonly string[];
+    /** Reviewed local bridge grant normalization and token verification. Catalog profiles cannot supply code. */
+    normalizeGrantedScopes?: (scopes: readonly string[] | string) => string[];
+    reportedScopesRequired?: boolean;
+    /** Built-in durable API bridges may refuse a new grant without offline access. */
+    freshRefreshTokenRequired?: boolean;
+    /** The reviewed bridge exposes one tool contract, not a partial-scope variant. */
+    fullRequestedScopesRequired?: boolean;
+    /** Built-in web OAuth clients must use a configured secret and provider-supported authentication. */
+    confidentialClientRequired?: boolean;
+    /** Built-in API bridge discovery; catalog metadata cannot redirect this seam. */
+    providerOAuthDiscovery?: {
+        issuer: string;
+        metadataUrl: string;
+    };
+    localToolVerification?: {
+        url: string;
+        method?: "GET" | "POST";
+        /** An API bridge may require a verified account before accepting a grant. */
+        required?: boolean;
+        /** Distinguish a rejected OAuth grant from a temporary verification failure. */
+        isRejectedGrant?: (payload: Record<string, unknown>) => boolean;
+        validateIdentity: (payload: Record<string, unknown>) => Record<string, string>;
+        toolsForScopes: (scopes: readonly string[]) => Array<{
+            name: string;
+            description?: string;
+        }>;
+    };
+};
+export declare const DEFAULT_OAUTH_PROFILE: OAuthProviderProfile;
+/** Exact built-in profile by its stable key; throws on an unknown key. */
+export declare function builtInOAuthProfileByKey(key: string): OAuthProviderProfile;
+export type DeploymentManagedClientKey = "slack";
+/**
+ * Pre-registered deployment clients resolved from dedicated settings, keyed by
+ * the authorization-server origins they serve. Consulted before the operator
+ * clients JSON so a deployment-managed provider can never be shadowed.
+ */
+export declare const DEPLOYMENT_MANAGED_CLIENTS: readonly {
+    key: DeploymentManagedClientKey;
+    issuerOrigins: readonly string[];
+    resolve: (settings: Settings) => {
+        clientId: string;
+        clientSecret: string;
+        tokenEndpointAuthMethod: "client_secret_post";
+    } | null;
+}[];
+export declare function deploymentManagedClientFor(settings: Settings, key: DeploymentManagedClientKey): ReturnType<(typeof DEPLOYMENT_MANAGED_CLIENTS)[number]["resolve"]>;
+/** Built-in profile for a start target, or null when only the default applies. */
+export declare function builtInOAuthProfileFor(input: {
+    mcpUrl: string;
+    providerDomain?: string | undefined;
+}): OAuthProviderProfile | null;
+/** Ownership an omitted request defaults to under a profile. */
+export declare function defaultOwnershipFor(profile: OAuthProviderProfile): ConnectionOwnership;
+/** Enforces a profile's authorization-server origin pins with its exact message. */
+export declare function assertAuthorizationServerPins(as: PinnableAuthorizationServer, pins: Pick<AuthorizationServerPins, "issuerOrigins" | "authorizationEndpointOrigins" | "tokenEndpointOrigins" | "message">): void;
+/**
+ * Reserved-authorization-server guard: a discovered identity claimed by one
+ * profile is rejected on every other flow with that guard's exact message.
+ */
+export declare function assertAuthorizationServerNotReserved(as: PinnableAuthorizationServer, profile: OAuthProviderProfile): void;
+/**
+ * Catalog-row profile: the declarative subset a curated row may carry. It can
+ * only narrow the default flow; the fields that grant authority (deployment
+ * client settings, reserved-server membership) are built-in-only by
+ * construction because the schema cannot express them.
+ */
+/**
+ * Authorize-URL parameters owned by the OAuth client itself. A profile's
+ * `extraAuthorizeParams` may never name one: overriding `scope` or `resource`
+ * would widen the grant past the recorded contract, and the rest carry the
+ * PKCE/state security machinery. Enforced in this schema, in the curation
+ * parser, and defensively again in `buildAuthorizationUrl`.
+ */
+export declare const RESERVED_AUTHORIZE_PARAMS: ReadonlySet<string>;
+export declare const catalogOAuthProfileSchema: z.ZodObject<{
+    clientSource: z.ZodOptional<z.ZodEnum<{
+        cimd: "cimd";
+        dcr: "dcr";
+        deployment_managed: "deployment_managed";
+    }>>;
+    exactMcpUrl: z.ZodOptional<z.ZodString>;
+    pinnedIssuerOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pinnedEndpointOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sendResourceParameter: z.ZodOptional<z.ZodBoolean>;
+    defaultOwnership: z.ZodOptional<z.ZodEnum<{
+        personal: "personal";
+        workspace: "workspace";
+    }>>;
+    requestedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extraAuthorizeParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type CatalogOAuthProfile = z.infer<typeof catalogOAuthProfileSchema>;
+/**
+ * Canonical catalog lookup key for an MCP URL, mirroring the importer's
+ * `canonicalMcpUrl` (`scripts/catalog-curation.ts`): no fragment, lowercase
+ * host, default ports stripped, trailing slashes collapsed. Without this, a
+ * trailing-slash or uppercase-host variant of a profiled URL would miss the
+ * row and silently fall back to the default profile.
+ */
+export declare function catalogMcpUrlKey(value: string): string;
+/**
+ * Applies a validated catalog profile over the default profile for a row with
+ * no built-in. `deployment_managed` from catalog data resolves through the
+ * operator clients JSON (issuer-keyed) only; named settings-backed clients
+ * remain built-in-only.
+ *
+ * A present-but-invalid profile fails closed with a 422: the row's operator
+ * declared constraints, and silently degrading to the default profile would
+ * drop an origin pin on a JSON typo.
+ */
+export declare function oauthProfileFromCatalog(mcpUrl: string, raw: unknown): OAuthProviderProfile;

package/dist/integrations/oauth-return-path.d.ts

@@ -0,0 +1 @@
+export declare function safeReturnPath(value: string): string;

package/dist/integrations/personal-github-repositories.d.ts

@@ -0,0 +1,84 @@
+import { type PersonalGitHubRepository as PersonalGitHubRepositoryContract, type PersonalGitHubRepositorySelectionInput } from "@opengeni/contracts/personal-github";
+import { type GitHubRepositoryBranchesResponse as GitHubRepositoryBranchesResponseContract, type ListGitHubRepositoryBranchesQuery } from "@opengeni/contracts/github-repository-contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { getConnectionMetadata, type PersonalGitHubRepositorySelectionState as DbPersonalGitHubRepositorySelectionState } from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+export type PersonalGitHubRepositoryConnection = NonNullable<Awaited<ReturnType<typeof getConnectionMetadata>>>;
+type PersonalGitHubRepositoryProviderOperation = "repositories_list" | "repository_branches_list" | "repository_verify";
+type ExpectedPersonalGitHubRepositoryAuthority = {
+    selectionGeneration: number;
+    repositoryId: string;
+    fullName: string;
+};
+type PersonalGitHubProviderJsonOptions = {
+    operation: PersonalGitHubRepositoryProviderOperation;
+    expectedRepositoryAuthority?: ExpectedPersonalGitHubRepositoryAuthority;
+    responseLabel?: string;
+    responseMaxBytes?: number;
+};
+export type PersonalGitHubRepositoryBranchServices = {
+    requireConnection: typeof requirePersonalGitHubRepositoryConnection;
+    getSelectionState: (deps: ApiRouteDeps, input: {
+        accountId: string;
+        originWorkspaceId: string;
+        subjectId: string;
+        connectionId: string;
+    }) => Promise<DbPersonalGitHubRepositorySelectionState | null>;
+    providerJson: (input: {
+        deps: ApiRouteDeps;
+        connection: PersonalGitHubRepositoryConnection;
+        subjectId: string;
+        url: URL;
+        expectedConnectionAuthorityGeneration: number;
+        options: PersonalGitHubProviderJsonOptions;
+    }) => Promise<unknown>;
+};
+export type PersonalGitHubRepositoryProviderErrorCode = "connection_changed" | "connection_inactive" | "invalid_provider_response" | "provider_denied" | "provider_rate_limited" | "provider_unavailable" | "repository_archived" | "repository_not_found" | "repository_not_selected" | "repository_read_denied" | "repository_selection_changed" | "repository_write_denied";
+export declare class PersonalGitHubRepositoryProviderError extends Error {
+    readonly code: PersonalGitHubRepositoryProviderErrorCode;
+    constructor(code: PersonalGitHubRepositoryProviderErrorCode);
+}
+export declare function requirePersonalGitHubRepositoryConnection(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+}): Promise<PersonalGitHubRepositoryConnection>;
+export declare function listLivePersonalGitHubRepositories(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    accountId: string;
+    subjectId: string;
+    connectionId: string;
+    expectedConnectionAuthorityGeneration: number;
+    page: number;
+    limit: number;
+}): Promise<{
+    repositories: PersonalGitHubRepositoryContract[];
+    nextPage: number | null;
+}>;
+export declare function listLivePersonalGitHubRepositoryBranches(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    accountId: string;
+    subjectId: string;
+    connectionId: string;
+    repositoryId: string;
+    query: ListGitHubRepositoryBranchesQuery;
+}, services?: PersonalGitHubRepositoryBranchServices): Promise<GitHubRepositoryBranchesResponseContract>;
+/** Serial by design: one bounded provider request and one authority check at a time. */
+export declare function verifyLivePersonalGitHubRepositories(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    accountId: string;
+    subjectId: string;
+    connectionId: string;
+    expectedConnectionAuthorityGeneration: number;
+    repositories: PersonalGitHubRepositorySelectionInput[];
+}): Promise<Array<PersonalGitHubRepositoryContract & {
+    selectedAccess: "read" | "write";
+}>>;
+export declare function personalGitHubRepositoryProviderHttpError(error: PersonalGitHubRepositoryProviderError): HTTPException;
+/** Keep provider integer lexemes exact before repository IDs become bigint-backed strings. */
+export declare function parsePersonalGitHubProviderJson(value: string): unknown;
+export declare function personalGitHubRepositoryCanRead(permissions: PersonalGitHubRepositoryContract["permissions"]): boolean;
+export declare function personalGitHubRepositoryCanWrite(permissions: PersonalGitHubRepositoryContract["permissions"]): boolean;
+export declare function parsePersonalGitHubRepository(value: unknown): PersonalGitHubRepositoryContract;
+export {};

package/dist/integrations/personal-github.d.ts

@@ -0,0 +1,42 @@
+import { type Settings } from "@opengeni/config";
+import { type PersonalGitHubDisconnectRequest } from "@opengeni/contracts/personal-github";
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+export declare function personalGitHubClientMarker(clientId: string): string;
+export declare function requirePersonalGitHubOAuthSettings(settings: Settings): {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    oauthEnvironment: string;
+    oauthClientMarker: string;
+};
+export declare function listPersonalGitHubConnections(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+}): Promise<import("@opengeni/db").ConnectionMetadataWithVerification[]>;
+export declare function disconnectPersonalGitHub(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    payload: PersonalGitHubDisconnectRequest;
+}): Promise<import("@opengeni/db").ConnectionMetadataWithVerification | null>;
+export declare function startPersonalGitHubOAuth(deps: ApiRouteDeps, input: {
+    access: AccessGrantAuthorization;
+    workspaceId: string;
+    connectionId?: string;
+    returnPath?: string;
+    connectAttemptId?: string;
+}): Promise<{
+    authorizationUrl: string;
+    expiresAt: string;
+}>;
+export declare function completePersonalGitHubOAuthCallback(deps: ApiRouteDeps, input: {
+    code?: string;
+    state?: string;
+    error?: string;
+    requestUrl: string;
+}): Promise<{
+    redirectTo: string;
+    exactReturn?: boolean;
+}>;
+export declare function personalGitHubReviewUrl(settings: Settings): string | null;
+export declare const PERSONAL_GITHUB_CONNECTION_PRINCIPAL_MESSAGE: string;

package/dist/integrations/pr-review-provider.d.ts

@@ -0,0 +1,22 @@
+import type { PrReviewProvider } from "@opengeni/contracts";
+import { type FetchLike, type OutboundNetworkSettings } from "@opengeni/network";
+export declare class PrReviewProviderRepositoryError extends Error {
+    readonly reason: "denied" | "identity_mismatch" | "unavailable";
+    constructor(reason: "denied" | "identity_mismatch" | "unavailable", message: string);
+}
+export type VerifiedPrReviewProviderRepository = {
+    repositoryUri: string;
+    repositoryFullName: string;
+    providerRepositoryId: string;
+    projectId: string;
+};
+export declare function verifyPrReviewProviderRepository(input: {
+    provider: Exclude<PrReviewProvider, "github">;
+    providerBaseUrl: string;
+    providerRepositoryId: string;
+    projectId?: string;
+    token: string;
+    username: string | null;
+    settings: OutboundNetworkSettings;
+    fetchImpl?: FetchLike;
+}): Promise<VerifiedPrReviewProviderRepository>;

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

@@ -1,9 +1,20 @@
-import { OAuthStartResponse, type ApiIntegrationOAuthStartRequest } from "@opengeni/contracts";
+import { type IntegrationDefinition } from "@opengeni/capabilities";
+import { type Settings } from "@opengeni/config";
+import { OAuthStartResponse, type ApiIntegrationOAuthStartRequest, type ConnectionOwnership } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 export declare function startApiIntegrationProviderOAuth(deps: ApiRouteDeps, input: {
     accountId: string;
     workspaceId: string;
     subjectId: string;
+    /**
+     * False for every principal that cannot own a personal Connection (API
+     * keys, the configured key, services, agent attempts). Resolved by the
+     * route from the live authenticated principal, never inferred here.
+     */
+    personalOwnershipAllowed: boolean;
+    externalContinuation?: ExternalActorContinuation;
+    connectAttemptId?: string;
     requestUrl: string;
     payload: ApiIntegrationOAuthStartRequest;
 }): Promise<OAuthStartResponse>;
@@ -14,4 +25,11 @@ export declare function completeApiIntegrationProviderOAuth(deps: ApiRouteDeps,
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
+/** Configuration readiness only: consent and installation are still separate. */
+export declare function curatedOAuthReadiness(settings: Settings, definition: IntegrationDefinition): {
+    configured: boolean;
+    ownership: ConnectionOwnership[];
+};
+export declare function isApiIntegrationProviderOAuthState(value: string | undefined, settings: Settings): boolean;