LibreChat/packages/api/src/pulls/settings.ts
Marco Beretta 0bc344fcb9
🔑 feat: Let Users Connect Their Own Account for Pull Request Lookups (#16989)
* feat: Let Users Connect Their Own Account for Pull Request Lookups

* fix: Refuse Cross-Tenant Pull Request Callbacks and Surface Key Failures

* fix: Keep Pull Request Grants Through Outages and Remove Them on Disconnect

A token endpoint server error is an outage even with an OAuth error body, so
it no longer deletes the grant, and a refresh outage reaches the lookup as
unavailable instead of falling back to no token. Disconnect removes every
pr_oauth row of the user, whatever app or host is configured now. A grant that
never expires extends its retention when used, and the flow, request and
retention limits are configurable. The connection routes are built in
packages/api, mounted behind the pre-auth tenant middleware in both servers,
and answer failures with stable codes.

* fix: Keep the Pull Request OAuth App Out of Overrides

A role, group, user or tenant override can no longer change or remove pullRequests.oauth, so the connect capability and the callback see the operator's app.

* fix: Read a User's Pull Request Token Only With the Feature On

* fix: Report a Malformed Stored Pull Request Grant as a Failure

* fix: Remove a User's Stored Tokens When an Administrator Deletes the User

* fix: Answer No Pull Request for a Conversation Without a Lane When the User Token Fails

* fix: Share One Grant Read Between Concurrent Callers and Report an Expired Grant Disconnected

* fix: Remove a Pull Request Grant Only on a Definite Refusal and Past Its Retention

* fix: Version Pull Request Grants and Coordinate Refresh, Refusal and Retention Through Them

* fix: Invalidate a Refused User Token and Read It Only for a Lane That Needs It

* fix: Finish a Pull Request Connection Under the User's Effective Config Behind the Login Limiter

* fix: Type the Pull Request User Token for Isolated Declarations and Settle Retention Before Answering

* fix: Bind a Pull Request Connection Flow to the Generation a Disconnect Replaces

* fix: Start a Batch's User Token Read Only Within Its Deadline

* fix: Fence Pull Request Token Reads Against a Disconnect and Report a Failed Retention Cleanup

* fix: Fence Connection Status Like Token Reads and Keep a Newer Read Joinable

* fix: Report a Pull Request Grant Without Its App and Name the Sign-In That Made It

* fix: Read a User's Unexpired Pull Request Grants Newest First

* fix: Mark the Connection Callback as an OAuth Navigation and Report a Failed Extension

* fix: Name the Pull Request Sign-In Flow on Its Landing Page

* fix: Remove a Pull Request Grant of a Replaced App When It Is Read

* fix: Keep a Replaced App's Grant Untouched and Extend Retention From Each Day's Use

* fix: Accept a Pull Request Grant Only Under the User's Current Connection Generation

* fix: Renew the Connection Generation With a Grant Still in Use

* fix: Restore the Previous Connection When a Sign-In Cannot Store Its Grant

* fix: Decide a Sign-In by What Was Stored When a Write Does Not Answer

* fix: Roll Back a Sign-In's Generation Along With a Grant It Must Remove

* fix: Refresh an Access Token a Lookup Was Refused With Before Ending the Connection

* fix: Undo a Sign-In Only for a Confirmed Fence, Not a Failed Check

* fix: Read a User Token Again When the Connection Changes Under the Read

* fix: Apply the Current Retention Again When Another Replica Changed the Grant First

* test: Answer Each Concurrent Sign-In by Its Own Code

* fix: Skip Retention Rewrites for Grants That Expire Without a Refresh Token

* fix: Retry a Token Rejection That Loses to a Concurrent Grant Write

* fix: Skip User Token Reads for Lanes Without a Commit and Reread Status After a Reconnect
2026-10-12 15:58:23 +02:00

160 lines
6.4 KiB
TypeScript

import { PULL_REQUEST_PROVIDERS } from 'librechat-data-provider';
import type { PullRequestProvider, TAgentsEndpoint } from 'librechat-data-provider';
export type PullRequestSettings = NonNullable<TAgentsEndpoint['pullRequests']>;
const TOKEN_REFERENCE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
/**
* Tried in order when `token` is not configured, so a deployment that already holds a token for
* something else gets pull requests without more setup. A token named in the config always wins,
* and one that does not resolve is reported instead of silently replaced.
*/
const TOKEN_ENV_FALLBACKS: Record<PullRequestProvider, readonly string[]> = {
github: ['GITHUB_PULL_REQUEST_TOKEN', 'GITHUB_TOKEN', 'GH_TOKEN'],
gitlab: ['GITLAB_PULL_REQUEST_TOKEN', 'GITLAB_TOKEN'],
bitbucket: ['BITBUCKET_PULL_REQUEST_TOKEN'],
};
const DEFAULT_HOSTS: Record<PullRequestProvider, string> = {
github: 'github.com',
gitlab: 'gitlab.com',
bitbucket: 'bitbucket.org',
};
/** The configured provider, GitHub when none is set, `null` for a name this server does not know. */
export function resolvePullRequestProvider(
provider: string | undefined,
): PullRequestProvider | null {
if (provider == null) return 'github';
return (PULL_REQUEST_PROVIDERS as readonly string[]).includes(provider)
? (provider as PullRequestProvider)
: null;
}
type Env = Readonly<Record<string, string | undefined>>;
/** Resolves `${NAME}` against the environment; the config never holds the token itself. */
export function resolveTokenReference(reference: string | undefined, env: Env): string | null {
const name = reference == null ? undefined : TOKEN_REFERENCE.exec(reference)?.[1];
if (name == null) return null;
return env[name]?.trim() || null;
}
const HOST = /^(?=[a-z0-9])[a-z0-9.-]*[a-z0-9](?::[0-9]{1,5})?$/;
/**
* The configured host, lowercased, or the provider's own when none is set. `null` for a value that
* is not a plain host name, and for any Bitbucket host but Cloud's: the token is then sent nowhere
* rather than to a host nobody named.
*/
export function resolvePullRequestHost(
host: string | undefined,
provider: PullRequestProvider = 'github',
): string | null {
if (host == null) return DEFAULT_HOSTS[provider];
const value = host.trim().toLowerCase();
if (value.length > 253 || !HOST.test(value)) return null;
const [name, port] = value.split(':');
const number = port == null ? null : Number(port);
if (number != null && (number < 1 || number > 65535)) return null;
/** A URL drops the https default port, so a page on `host:443` compares as `host`. */
const normalized = number == null || number === 443 ? name : `${name}:${number}`;
if (provider === 'bitbucket' && normalized !== DEFAULT_HOSTS.bitbucket) return null;
return normalized;
}
/** The configured token reference, else the first fallback variable that is set. */
export function resolvePullRequestToken(
reference: string | undefined,
env: Env,
provider: PullRequestProvider = 'github',
): string | null {
if (reference != null) return resolveTokenReference(reference, env);
for (const name of TOKEN_ENV_FALLBACKS[provider]) {
const value = env[name]?.trim();
if (value) return value;
}
return null;
}
/** A user connection the operator configured: the app users authorize, on the configured host. */
export type PullRequestOAuthConfig = {
provider: PullRequestProvider;
host: string;
clientId: string;
clientSecret: string;
scope?: string;
flowTimeoutMinutes?: number;
requestTimeoutSeconds?: number;
retentionDays?: number;
};
/**
* The OAuth app users connect their accounts through, or `null` when none is configured or its
* references do not resolve, in which case users cannot connect and only the server token is used.
*/
export function resolvePullRequestOAuth(
settings: Partial<PullRequestSettings> | null | undefined,
env: Env,
): PullRequestOAuthConfig | null {
const oauth = settings?.oauth;
if (oauth == null) return null;
const provider = resolvePullRequestProvider(settings?.provider);
if (provider == null) return null;
const host = resolvePullRequestHost(settings?.host, provider);
const clientId = resolveTokenReference(oauth.clientId, env);
const clientSecret = resolveTokenReference(oauth.clientSecret, env);
if (host == null || clientId == null || clientSecret == null) return null;
const scope = oauth.scope?.trim();
const { flowTimeoutMinutes, requestTimeoutSeconds, retentionDays } = oauth;
return {
provider,
host,
clientId,
clientSecret,
...(scope ? { scope } : {}),
...(flowTimeoutMinutes != null ? { flowTimeoutMinutes } : {}),
...(requestTimeoutSeconds != null ? { requestTimeoutSeconds } : {}),
...(retentionDays != null ? { retentionDays } : {}),
};
}
/**
* Whether pull requests can do anything on this deployment. The feature is on unless an
* administrator turns it off, and it stays dormant, advertising nothing and recording nothing,
* until there is both a token to read with and a scope of repositories to read: either a list, or
* the explicit opt-in to every repository the token can see.
*/
export function isPullRequestFeatureActive(
settings: Partial<PullRequestSettings> | null | undefined,
env: Env,
): boolean {
if (settings?.enabled === false) return false;
const provider = resolvePullRequestProvider(settings?.provider);
if (provider == null || resolvePullRequestHost(settings?.host, provider) == null) return false;
/** Users who connect their own account need no repository list: their token sees only what
* they can already see. */
if (resolvePullRequestOAuth(settings, env) != null) return true;
if (settings?.token == null && resolvePullRequestToken(undefined, env, provider) == null) {
return false;
}
return (
settings?.allowAllRepositories === true || (settings?.allowedRepositories?.length ?? 0) > 0
);
}
/**
* What a lane recorder needs from the settings: whether to record at all, and the host whose pull
* request links it keeps.
*/
export function resolvePullRequestRecording(
settings: Partial<PullRequestSettings> | null | undefined,
env: Env,
): { enabled: boolean; host?: string } {
const enabled = isPullRequestFeatureActive(settings, env);
const provider = resolvePullRequestProvider(settings?.provider);
const host =
enabled && provider != null ? resolvePullRequestHost(settings?.host, provider) : null;
return host != null ? { enabled, host } : { enabled };
}