🦭 test: Add Scheduled MCP Authorization Contract Fixtures (#16645)

* docs: define scheduled MCP authorization contracts

* test: keep scheduled MCP contracts beside executable fixtures

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-10-01 21:28:40 -04:00 • committed by GitHub
parent 4d27facffe
commit 76fac09531
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 646 additions and 0 deletions

View file

@ -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<ScheduledMCPAuthorizationResult>;
/** Reuses the evaluator across fresh snapshots to expose stale authorization decisions. */
export async function verifyAuthorizationFixture(
fixture: AuthorizationFixture,
evaluate: AuthorizationFixtureEvaluator,
): Promise<void> {
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();
}
}
}

View file

@ -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<ScheduledMCPAuthorizationResult> => ({
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' };
});
});

View file

@ -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<ScheduledTokenContext, 'tenantId'> {
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<ScheduleMCPOutcome['status'], 'ready'>;
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<ScheduledMCPConsentLookupResult>;
/** Rechecks live consent, RBAC, schedule/graph binding and trusted tool policy at each stage. */
readonly authorize: (
request: ScheduledMCPAuthorizationRequest,
options: { signal?: AbortSignal },
) => Promise<ScheduledMCPAuthorizationResult>;
}
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<ScheduledMCPBearerResult>;

View file

@ -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<ScheduledMCPAuthorizationRequest, 'stage'>;
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<ScheduledMCPConsent>): 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<Record<ScheduledMCPFailure['reason'], ScheduledMCPFailure>> =
{
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,
},
};