From 76fac095312daa0e8d581a8f3aabfd1fd4f37862 Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Thu, 1 Oct 2026 21:28:40 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=A6=AD=20test:=20Add=20Scheduled=20MCP=20?= =?UTF-8?q?Authorization=20Contract=20Fixtures=20(#16645)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: define scheduled MCP authorization contracts * test: keep scheduled MCP contracts beside executable fixtures --------- Co-authored-by: Lia --- .../authorization/conformance.helper.ts | 62 +++ .../authorization/conformance.spec.ts | 107 ++++++ .../src/schedules/authorization/contract.ts | 125 +++++++ .../authorization/fixtures.helper.ts | 352 ++++++++++++++++++ 4 files changed, 646 insertions(+) create mode 100644 packages/api/src/schedules/authorization/conformance.helper.ts create mode 100644 packages/api/src/schedules/authorization/conformance.spec.ts create mode 100644 packages/api/src/schedules/authorization/contract.ts create mode 100644 packages/api/src/schedules/authorization/fixtures.helper.ts diff --git a/packages/api/src/schedules/authorization/conformance.helper.ts b/packages/api/src/schedules/authorization/conformance.helper.ts new file mode 100644 index 0000000000..8599e70291 --- /dev/null +++ b/packages/api/src/schedules/authorization/conformance.helper.ts @@ -0,0 +1,62 @@ +import type { ScheduledMCPAuthorizationRequest, ScheduledMCPAuthorizationResult } from './contract'; +import type { AuthorizationFacts, AuthorizationFixture } from './fixtures.helper'; +import { failureFixtures } from './fixtures.helper'; + +/** Test-only adapter: supply these snapshots through an implementation's injected dependencies. */ +export type AuthorizationFixtureEvaluator = ( + request: ScheduledMCPAuthorizationRequest, + facts: AuthorizationFacts, + options: { signal: AbortSignal }, +) => Promise; + +/** Reuses the evaluator across fresh snapshots to expose stale authorization decisions. */ +export async function verifyAuthorizationFixture( + fixture: AuthorizationFixture, + evaluate: AuthorizationFixtureEvaluator, +): Promise { + for (const step of fixture.steps) { + const controller = new AbortController(); + if (step.aborted) controller.abort(); + const result = await evaluate( + structuredClone({ ...fixture.request, stage: step.stage }), + structuredClone(step.facts), + { signal: controller.signal }, + ); + const fail = (): never => { + throw new Error(`Authorization contract mismatch: ${fixture.id}/${step.stage}`); + }; + if (step.expected === 'cancelled') { + if (result.state !== 'cancelled') fail(); + continue; + } + if (step.expected !== 'authorized') { + const expected = failureFixtures[step.expected]; + if ( + result.state !== 'denied' || + result.failure.reason !== expected.reason || + result.failure.status !== expected.status || + result.failure.recovery !== expected.recovery || + result.failure.automaticReplay !== false || + Object.keys(result.failure).length !== Object.keys(expected).length + ) { + fail(); + } + continue; + } + if (result.state !== 'authorized' || step.facts.consent.state !== 'found') { + fail(); + continue; + } + const consent = step.facts.consent.consent; + if ( + result.consentId !== consent.id || + result.consentRevision !== consent.revision || + result.policyRevision !== step.facts.policyRevision || + !Number.isFinite(result.validUntilMs) || + result.validUntilMs <= step.facts.nowMs || + result.validUntilMs > consent.absoluteExpiresAtMs + ) { + fail(); + } + } +} diff --git a/packages/api/src/schedules/authorization/conformance.spec.ts b/packages/api/src/schedules/authorization/conformance.spec.ts new file mode 100644 index 0000000000..f53f8e8823 --- /dev/null +++ b/packages/api/src/schedules/authorization/conformance.spec.ts @@ -0,0 +1,107 @@ +import { scheduleMCPOutcomeSchema } from 'librechat-data-provider'; +import type { ScheduledMCPAuthorizationResult } from './contract'; +import type { AuthorizationFixture } from './fixtures.helper'; +import { authorizationFixtures, failureFixtures } from './fixtures.helper'; +import { verifyAuthorizationFixture } from './conformance.helper'; + +/** Exercises the harness, not a production authorization implementation. */ +function scriptedResults(fixture: AuthorizationFixture): ScheduledMCPAuthorizationResult[] { + return fixture.steps.map((step) => { + if (step.expected === 'cancelled') return { state: 'cancelled' }; + if (step.expected !== 'authorized') { + return { state: 'denied', failure: failureFixtures[step.expected] }; + } + if (step.facts.consent.state !== 'found') throw new Error('Invalid positive fixture'); + const consent = step.facts.consent.consent; + return { + state: 'authorized', + consentId: consent.id, + consentRevision: consent.revision, + policyRevision: step.facts.policyRevision, + validUntilMs: consent.absoluteExpiresAtMs, + }; + }); +} + +it.each(authorizationFixtures)('accepts the complete scripted contract: $id', async (fixture) => { + const results = scriptedResults(fixture); + const evaluate = jest.fn(async () => results.shift()!); + await verifyAuthorizationFixture(fixture, evaluate); + expect(evaluate.mock.calls).toHaveLength(fixture.steps.length); +}); + +it.each( + authorizationFixtures.filter((fixture) => + fixture.steps.some((step) => step.expected !== 'authorized'), + ), +)('rejects an implementation that reuses an allow decision: $id', async (fixture) => { + const evaluate = jest.fn( + async (): Promise => ({ + state: 'authorized', + consentId: 'consent-1', + consentRevision: 'consent-revision-1', + policyRevision: 'policy-1', + validUntilMs: 10_000, + }), + ); + await expect(verifyAuthorizationFixture(fixture, evaluate)).rejects.toThrow( + 'Authorization contract mismatch', + ); +}); + +it('rejects token expiry used to extend the consent deadline', async () => { + const fixture = authorizationFixtures[0]; + const result = scriptedResults(fixture)[0]; + if (result.state !== 'authorized') throw new Error('Invalid positive fixture'); + await expect( + verifyAuthorizationFixture(fixture, async () => ({ ...result, validUntilMs: 20_000 })), + ).rejects.toThrow('Authorization contract mismatch'); +}); + +it('rejects a stale policy revision', async () => { + const fixture = authorizationFixtures[0]; + const result = scriptedResults(fixture)[0]; + if (result.state !== 'authorized') throw new Error('Invalid positive fixture'); + await expect( + verifyAuthorizationFixture(fixture, async () => ({ ...result, policyRevision: 'old-policy' })), + ).rejects.toThrow('Authorization contract mismatch'); +}); + +it('does not permit automatic replay or an incompatible public failure status', () => { + for (const failure of Object.values(failureFixtures)) { + expect(failure.automaticReplay).toBe(false); + expect( + scheduleMCPOutcomeSchema.safeParse({ server: 'warehouse', status: failure.status }).success, + ).toBe(true); + } +}); + +it('requires unique vector IDs and explicit tenant bindings', () => { + expect(new Set(authorizationFixtures.map((fixture) => fixture.id)).size).toBe( + authorizationFixtures.length, + ); + for (const fixture of authorizationFixtures) { + expect(fixture.request.identity).toHaveProperty('tenantId'); + expect(fixture.steps.length).toBeGreaterThan(0); + } +}); + +it('isolates dependency snapshots from a mutating test adapter', async () => { + const fixture = authorizationFixtures[0]; + const results = scriptedResults(fixture); + await verifyAuthorizationFixture(fixture, async (request, facts) => { + Object.assign(request.identity, { agentId: 'tampered' }); + Object.assign(facts, { rbac: 'denied' }); + return results.shift()!; + }); + expect(fixture.request.identity.agentId).toBe('root-agent'); + expect(fixture.steps[0].facts.rbac).toBe('allowed'); +}); + +it('delivers cancellation to the adapter without inventing a reauth failure', async () => { + const fixture = authorizationFixtures.find((item) => item.id === 'cancelled-before-admission')!; + await verifyAuthorizationFixture(fixture, async (_request, _facts, { signal }) => { + expect(signal.aborted).toBe(true); + return { state: 'cancelled' }; + }); +}); diff --git a/packages/api/src/schedules/authorization/contract.ts b/packages/api/src/schedules/authorization/contract.ts new file mode 100644 index 0000000000..30946c9dfe --- /dev/null +++ b/packages/api/src/schedules/authorization/contract.ts @@ -0,0 +1,125 @@ +import type { ScheduleMCPOutcome } from 'librechat-data-provider'; +import type { ScheduledTokenContext } from '../context'; + +export type ScheduledMCPCredentialMode = + | 'stored_oauth' + | 'browser_bearer' + | 'renewable_obo' + | 'resource_bearer' + | 'static' + | 'anonymous'; + +/** agentId remains the enrolled root, including during child execution. */ +export interface ScheduledMCPIdentity extends Omit { + readonly tenantId: string | null; +} + +/** Resolved by trusted configuration, never by model arguments or token scopes. */ +export interface ScheduledMCPResource { + readonly serverName: string; + readonly url: string; + readonly configurationRevision: string; + readonly credentialMode: ScheduledMCPCredentialMode; + readonly issuer: string | null; + readonly audience: string | null; + readonly scopes: readonly string[]; +} + +export interface ScheduledMCPToolSelection { + readonly agentId: string; + readonly tools: readonly string[]; +} + +export interface ScheduledMCPConsent { + readonly id: string; + readonly revision: string; + readonly identity: ScheduledMCPIdentity; + readonly resource: ScheduledMCPResource; + readonly permittedTools: readonly ScheduledMCPToolSelection[]; + readonly policyRevision: string; + readonly grantedAtMs: number; + /** Fixed consent deadline; credential renewal cannot extend it. */ + readonly absoluteExpiresAtMs: number; + readonly revokedAtMs: number | null; +} + +export type ScheduledMCPFailureReason = + | 'consent_missing' + | 'consent_expired' + | 'consent_revoked' + | 'binding_mismatch' + | 'rbac_denied' + | 'tool_policy_denied' + | 'approval_required' + | 'credential_missing' + | 'credential_rejected' + | 'resource_permission_denied' + | 'provider_missing' + | 'resource_unverified' + | 'unsupported_mode' + | 'dependency_unavailable'; + +/** Safe diagnosis projected onto existing schedule statuses. */ +export interface ScheduledMCPFailure { + readonly reason: ScheduledMCPFailureReason; + readonly status: Exclude; + readonly recovery: 'authorize' | 'configure' | 'restore_permission' | 'retry_later'; + readonly automaticReplay: false; +} + +export type ScheduledMCPConsentLookupResult = + | { readonly state: 'found'; readonly consent: ScheduledMCPConsent } + | { readonly state: 'missing' } + | { readonly state: 'unavailable' }; + +export interface ScheduledMCPAuthorizationRequest { + readonly identity: ScheduledMCPIdentity; + readonly resource: ScheduledMCPResource; + readonly stage: 'activation' | 'mint' | 'invoke' | 'resume'; + readonly selection: ScheduledMCPToolSelection; +} + +/** Ephemeral observation, not a transferable grant or permission to cache an allow decision. */ +export type ScheduledMCPAuthorizationResult = + | { + readonly state: 'authorized'; + readonly consentId: string; + readonly consentRevision: string; + readonly policyRevision: string; + readonly validUntilMs: number; + } + | { readonly state: 'denied'; readonly failure: ScheduledMCPFailure } + | { readonly state: 'cancelled' }; + +export interface ScheduledMCPAuthority { + readonly lookupConsent: ( + identity: ScheduledMCPIdentity, + resource: ScheduledMCPResource, + options: { signal?: AbortSignal }, + ) => Promise; + /** Rechecks live consent, RBAC, schedule/graph binding and trusted tool policy at each stage. */ + readonly authorize: ( + request: ScheduledMCPAuthorizationRequest, + options: { signal?: AbortSignal }, + ) => Promise; +} + +export type ScheduledMCPBearerResult = + | { + readonly state: 'ready'; + readonly accessToken: string; + readonly expiresAtMs: number; + readonly issuer: string; + readonly audience: string; + readonly resourceUrl: string; + } + | { readonly state: 'denied'; readonly failure: ScheduledMCPFailure } + | { readonly state: 'cancelled' }; + +/** Resolves a resource-bound bearer after live authorization; use must reauthorize. */ +export type ScheduledMCPResourceBearerResolver = ( + request: ScheduledMCPAuthorizationRequest & { + readonly resource: ScheduledMCPResource & { readonly credentialMode: 'resource_bearer' }; + }, + options: { signal?: AbortSignal }, +) => Promise; diff --git a/packages/api/src/schedules/authorization/fixtures.helper.ts b/packages/api/src/schedules/authorization/fixtures.helper.ts new file mode 100644 index 0000000000..e59ce2371d --- /dev/null +++ b/packages/api/src/schedules/authorization/fixtures.helper.ts @@ -0,0 +1,352 @@ +import type { + ScheduledMCPConsent, + ScheduledMCPFailure, + ScheduledMCPIdentity, + ScheduledMCPResource, + ScheduledMCPConsentLookupResult, + ScheduledMCPAuthorizationRequest, +} from './contract'; + +export interface AuthorizationFacts { + readonly nowMs: number; + readonly consent: ScheduledMCPConsentLookupResult; + readonly rbac: 'allowed' | 'denied' | 'unavailable'; + readonly scheduleActive: boolean; + readonly graphAgentIds: readonly string[]; + readonly policyRevision: string; + readonly classifications: readonly { + agentId: string; + tool: string; + effect: 'read' | 'write' | 'unknown'; + source: 'host' | 'server_hint'; + }[]; + readonly approvalRequired: boolean; + readonly providerInstalled: boolean; + readonly resourceAcceptanceVerified: boolean; +} + +export interface AuthorizationStep { + readonly stage: ScheduledMCPAuthorizationRequest['stage']; + readonly facts: AuthorizationFacts; + readonly expected: 'authorized' | 'cancelled' | ScheduledMCPFailure['reason']; + readonly aborted?: boolean; +} + +export interface AuthorizationFixture { + readonly id: string; + readonly request: Omit; + readonly steps: readonly AuthorizationStep[]; +} + +const identity: ScheduledMCPIdentity = { + scheduleId: 'schedule-1', + ownerId: 'owner-1', + tenantId: 'tenant-1', + agentId: 'root-agent', + invocationMode: 'delegated', +}; +const resource: ScheduledMCPResource = { + serverName: 'warehouse', + url: 'https://warehouse.example/mcp', + configurationRevision: 'configuration-1', + credentialMode: 'resource_bearer', + issuer: 'https://issuer.example/', + audience: 'warehouse-api', + scopes: ['query.read'], +}; +const consent: ScheduledMCPConsent = { + id: 'consent-1', + revision: 'consent-revision-1', + identity, + resource, + permittedTools: [ + { agentId: 'root-agent', tools: ['query'] }, + { agentId: 'child-agent', tools: ['query'] }, + ], + policyRevision: 'policy-1', + grantedAtMs: 1_000, + absoluteExpiresAtMs: 10_000, + revokedAtMs: null, +}; +const facts: AuthorizationFacts = { + nowMs: 2_000, + consent: { state: 'found', consent }, + rbac: 'allowed', + scheduleActive: true, + graphAgentIds: ['root-agent', 'child-agent'], + policyRevision: 'policy-1', + classifications: [ + { agentId: 'root-agent', tool: 'query', effect: 'read', source: 'host' }, + { agentId: 'child-agent', tool: 'query', effect: 'read', source: 'host' }, + ], + approvalRequired: false, + providerInstalled: true, + resourceAcceptanceVerified: true, +}; +const request: AuthorizationFixture['request'] = { + identity, + resource, + selection: { agentId: 'root-agent', tools: ['query'] }, +}; +const stages: readonly AuthorizationStep['stage'][] = ['activation', 'mint', 'invoke', 'resume']; + +function fixture( + id: string, + expected: AuthorizationStep['expected'], + currentFacts: AuthorizationFacts = facts, + currentRequest: AuthorizationFixture['request'] = request, +): AuthorizationFixture { + return { + id, + request: currentRequest, + steps: stages.map((stage) => ({ stage, facts: currentFacts, expected })), + }; +} + +function changedConsent(change: Partial): AuthorizationFacts { + return { ...facts, consent: { state: 'found', consent: { ...consent, ...change } } }; +} + +export const authorizationFixtures: readonly AuthorizationFixture[] = [ + fixture('bound-root', 'authorized'), + fixture('bound-child', 'authorized', facts, { + ...request, + selection: { agentId: 'child-agent', tools: ['query'] }, + }), + fixture( + 'single-tenant', + 'authorized', + changedConsent({ identity: { ...identity, tenantId: null } }), + { + ...request, + identity: { ...identity, tenantId: null }, + }, + ), + fixture('missing-consent', 'consent_missing', { ...facts, consent: { state: 'missing' } }), + fixture('consent-store-outage', 'dependency_unavailable', { + ...facts, + consent: { state: 'unavailable' }, + }), + fixture('just-before-deadline', 'authorized', { ...facts, nowMs: 9_999 }), + fixture('expired-at-deadline', 'consent_expired', { ...facts, nowMs: 10_000 }), + fixture('expired-after-deadline', 'consent_expired', { ...facts, nowMs: 10_001 }), + fixture( + 'nonfinite-deadline', + 'binding_mismatch', + changedConsent({ absoluteExpiresAtMs: Number.NaN }), + ), + fixture( + 'deadline-before-grant', + 'binding_mismatch', + changedConsent({ absoluteExpiresAtMs: 500 }), + ), + fixture('revoked', 'consent_revoked', changedConsent({ revokedAtMs: 1_999 })), + ...(['scheduleId', 'ownerId', 'tenantId', 'agentId'] as const).map((key) => + fixture(`changed-${key}`, 'binding_mismatch', facts, { + ...request, + identity: { ...identity, [key]: 'different' }, + }), + ), + fixture('missing-tenant-is-not-a-match', 'binding_mismatch', facts, { + ...request, + identity: { ...identity, tenantId: null }, + }), + ...(['url', 'configurationRevision', 'issuer', 'audience', 'serverName'] as const).map((key) => + fixture(`changed-${key}`, 'binding_mismatch', facts, { + ...request, + resource: { ...resource, [key]: 'different' }, + }), + ), + fixture('changed-scopes', 'binding_mismatch', facts, { + ...request, + resource: { ...resource, scopes: ['query.read', 'query.write'] }, + }), + fixture('changed-mode', 'binding_mismatch', facts, { + ...request, + resource: { ...resource, credentialMode: 'renewable_obo' }, + }), + fixture('revoked-rbac', 'rbac_denied', { ...facts, rbac: 'denied' }), + fixture('rbac-store-outage', 'dependency_unavailable', { ...facts, rbac: 'unavailable' }), + fixture('inactive-schedule', 'binding_mismatch', { ...facts, scheduleActive: false }), + fixture( + 'child-no-longer-reachable', + 'binding_mismatch', + { + ...facts, + graphAgentIds: ['root-agent'], + }, + { ...request, selection: { agentId: 'child-agent', tools: ['query'] } }, + ), + fixture('changed-trusted-policy', 'binding_mismatch', { ...facts, policyRevision: 'policy-2' }), + fixture('empty-tool-selection', 'tool_policy_denied', facts, { + ...request, + selection: { agentId: 'root-agent', tools: [] }, + }), + fixture('new-tool-not-enrolled', 'tool_policy_denied', facts, { + ...request, + selection: { agentId: 'root-agent', tools: ['query', 'delete'] }, + }), + ...(['write', 'unknown'] as const).map((effect) => + fixture(`tool-effect-${effect}`, 'tool_policy_denied', { + ...facts, + classifications: [{ agentId: 'root-agent', tool: 'query', effect, source: 'host' }], + }), + ), + fixture('server-readonly-hint-is-not-authority', 'tool_policy_denied', { + ...facts, + classifications: [ + { agentId: 'root-agent', tool: 'query', effect: 'read', source: 'server_hint' }, + ], + }), + fixture('unclassified-tool', 'tool_policy_denied', { ...facts, classifications: [] }), + fixture('approval-needed-headlessly', 'approval_required', { ...facts, approvalRequired: true }), + fixture('missing-provider', 'provider_missing', { ...facts, providerInstalled: false }), + fixture('resource-not-certified', 'resource_unverified', { + ...facts, + resourceAcceptanceVerified: false, + }), + fixture( + 'browser-bearer-not-headless', + 'unsupported_mode', + changedConsent({ resource: { ...resource, credentialMode: 'browser_bearer' } }), + { ...request, resource: { ...resource, credentialMode: 'browser_bearer' } }, + ), + ...(['stored_oauth', 'renewable_obo', 'static', 'anonymous'] as const).map((credentialMode) => { + const target = { + ...resource, + credentialMode, + ...((credentialMode === 'static' || credentialMode === 'anonymous') && { + issuer: null, + audience: null, + scopes: [], + }), + }; + return fixture( + `candidate-${credentialMode}`, + 'authorized', + changedConsent({ resource: target }), + { + ...request, + resource: target, + }, + ); + }), + { + id: 'cancelled-before-admission', + request, + steps: stages.map((stage) => ({ stage, facts, expected: 'cancelled', aborted: true })), + }, + { + id: 'revocation-after-mint', + request, + steps: [ + { stage: 'mint', facts, expected: 'authorized' }, + { + stage: 'invoke', + facts: changedConsent({ revokedAtMs: 2_000 }), + expected: 'consent_revoked', + }, + { + stage: 'resume', + facts: changedConsent({ revokedAtMs: 2_000 }), + expected: 'consent_revoked', + }, + ], + }, + { + id: 'expiry-during-approval-pause', + request, + steps: [ + { stage: 'invoke', facts, expected: 'authorized' }, + { stage: 'resume', facts: { ...facts, nowMs: 10_000 }, expected: 'consent_expired' }, + ], + }, +]; + +export const failureFixtures: Readonly> = + { + consent_missing: { + reason: 'consent_missing', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + consent_expired: { + reason: 'consent_expired', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + consent_revoked: { + reason: 'consent_revoked', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + binding_mismatch: { + reason: 'binding_mismatch', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + rbac_denied: { + reason: 'rbac_denied', + status: 'mcp_permission_denied', + recovery: 'restore_permission', + automaticReplay: false, + }, + tool_policy_denied: { + reason: 'tool_policy_denied', + status: 'mcp_permission_denied', + recovery: 'configure', + automaticReplay: false, + }, + approval_required: { + reason: 'approval_required', + status: 'mcp_permission_denied', + recovery: 'configure', + automaticReplay: false, + }, + credential_missing: { + reason: 'credential_missing', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + credential_rejected: { + reason: 'credential_rejected', + status: 'mcp_reauth_required', + recovery: 'authorize', + automaticReplay: false, + }, + resource_permission_denied: { + reason: 'resource_permission_denied', + status: 'mcp_permission_denied', + recovery: 'restore_permission', + automaticReplay: false, + }, + provider_missing: { + reason: 'provider_missing', + status: 'mcp_configuration_missing', + recovery: 'configure', + automaticReplay: false, + }, + resource_unverified: { + reason: 'resource_unverified', + status: 'mcp_configuration_missing', + recovery: 'configure', + automaticReplay: false, + }, + unsupported_mode: { + reason: 'unsupported_mode', + status: 'mcp_configuration_missing', + recovery: 'configure', + automaticReplay: false, + }, + dependency_unavailable: { + reason: 'dependency_unavailable', + status: 'mcp_unavailable', + recovery: 'retry_later', + automaticReplay: false, + }, + };