@bleedingdev/modern-js-bff-core 3.5.0-ultramodern.30 → 3.5.0-ultramodern.32

package/dist/esm-node/adapter-kit/parity.mjs

@@ -1,8 +1,11 @@
 import "node:module";
 import { buildOperationContractMap } from "../security/operationContracts.mjs";
 import { HttpMethod } from "../types.mjs";
-const PARITY_REQUEST_ID = 'crm';
-const PARITY_PRODUCER_REQUEST_ID = 'crm.producer-a';
+import { createCrossProjectDenialScenarios } from "./parity-scenarios/cross-project-denial.mjs";
+import { createEnvelopeParityScenarios } from "./parity-scenarios/envelope.mjs";
+import { createOperationContextDenialScenarios, createOperationContextSuccessScenarios } from "./parity-scenarios/operation-context.mjs";
+import { createSchemaParityScenarios } from "./parity-scenarios/schema.mjs";
+import { PARITY_PRODUCER_REQUEST_ID, PARITY_REQUEST_ID, envelopeHeader } from "./parity-scenarios/shared.mjs";
 const PARITY_FIXTURE_FILENAME = 'bff-core/adapter-kit/parity-fixture.ts';
 const HANDLER_WITH_SCHEMA = 'HANDLER_WITH_SCHEMA';
 const isRecord = (value)=>Boolean(value) && 'object' == typeof value;
@@ -104,361 +107,22 @@ const getParityContracts = ()=>buildOperationContractMap({
         handlers: createParityApiHandlerInfos(),
         requestId: PARITY_REQUEST_ID
     });
-const envelopeHeader = (requestId)=>JSON.stringify(void 0 === requestId ? {} : {
-        requestId
-    });
-const detailHeader = (details)=>JSON.stringify(details);
-const deniedScenario = (name, reason, headers)=>({
-        name,
-        policy: true,
-        request: {
-            method: 'get',
-            path: '/hello',
-            headers
-        },
-        expected: {
-            kind: 'denied',
-            status: 403,
-            reason
-        }
-    });
 const createAdapterParityScenarios = ()=>{
     const contracts = getParityContracts();
     const helloContract = contracts['GET:/hello'];
     const validEnvelope = envelopeHeader(PARITY_PRODUCER_REQUEST_ID);
     const validOperationId = `${PARITY_PRODUCER_REQUEST_ID}:parity`;
+    const context = {
+        helloContract,
+        validEnvelope,
+        validOperationId
+    };
     return [
-        {
-            name: 'plain handler returns object payload',
-            policy: false,
-            request: {
-                method: 'get',
-                path: '/hello'
-            },
-            expected: {
-                kind: 'payload',
-                status: 200,
-                payload: {
-                    message: 'hello'
-                }
-            }
-        },
-        {
-            name: 'plain handler returns scalar payload',
-            policy: false,
-            request: {
-                method: 'post',
-                path: '/hello'
-            },
-            expected: {
-                kind: 'payload',
-                status: 200,
-                payload: 'hello'
-            }
-        },
-        {
-            name: 'plain handler returning undefined (pinned adapter drift)',
-            policy: false,
-            request: {
-                method: 'get',
-                path: '/nothing'
-            },
-            expected: {
-                kind: 'perAdapter',
-                expectations: {
-                    express: {
-                        status: 200,
-                        payload: void 0
-                    },
-                    koa: {
-                        status: 404,
-                        payload: 'Not Found'
-                    },
-                    hono: {
-                        status: 404,
-                        payload: '404 Not Found'
-                    }
-                }
-            }
-        },
-        {
-            name: 'plain handler receives data, query and cookies',
-            policy: false,
-            request: {
-                method: 'post',
-                path: '/echo?q=z',
-                headers: {
-                    'content-type': 'application/json',
-                    cookie: 'id=666'
-                },
-                body: {
-                    a: 1
-                }
-            },
-            expected: {
-                kind: 'payload',
-                status: 200,
-                payload: {
-                    data: {
-                        a: 1
-                    },
-                    query: {
-                        q: 'z'
-                    },
-                    cookie: 'id=666'
-                }
-            }
-        },
-        {
-            name: 'plain handler receives positional route params',
-            policy: false,
-            request: {
-                method: 'get',
-                path: '/items/123?q=x'
-            },
-            expected: {
-                kind: 'payload',
-                status: 200,
-                payload: {
-                    id: '123',
-                    query: {
-                        q: 'x'
-                    }
-                }
-            }
-        },
-        {
-            name: 'schema handler success (pinned adapter drift)',
-            policy: false,
-            request: {
-                method: 'patch',
-                path: '/schema',
-                headers: {
-                    'content-type': 'application/json'
-                },
-                body: {
-                    id: 777
-                }
-            },
-            expected: {
-                kind: 'perAdapter',
-                expectations: {
-                    express: {
-                        status: 200,
-                        payload: {
-                            id: 777
-                        }
-                    },
-                    koa: {
-                        status: 200,
-                        payload: {
-                            id: 777
-                        }
-                    },
-                    hono: {
-                        status: 200,
-                        payload: {
-                            type: 'HandleSuccess',
-                            value: {
-                                id: 777
-                            }
-                        }
-                    }
-                }
-            }
-        },
-        {
-            name: 'schema handler input validation error (pinned adapter drift)',
-            policy: false,
-            request: {
-                method: 'patch',
-                path: '/schema',
-                headers: {
-                    'content-type': 'application/json'
-                },
-                body: {
-                    id: 'aaa'
-                }
-            },
-            expected: {
-                kind: 'perAdapter',
-                expectations: {
-                    express: {
-                        status: 400,
-                        payload: 'invalid input'
-                    },
-                    koa: {
-                        status: 400,
-                        payload: 'invalid input'
-                    },
-                    hono: {
-                        status: 200,
-                        payload: {
-                            type: 'InputValidationError',
-                            message: 'invalid input'
-                        }
-                    }
-                }
-            }
-        },
-        {
-            name: 'schema handler output validation error (pinned adapter drift)',
-            policy: false,
-            request: {
-                method: 'patch',
-                path: '/schema',
-                headers: {
-                    'content-type': 'application/json'
-                },
-                body: {
-                    id: 'boom'
-                }
-            },
-            expected: {
-                kind: 'perAdapter',
-                expectations: {
-                    express: {
-                        status: 500,
-                        payload: 'invalid output'
-                    },
-                    koa: {
-                        status: 500,
-                        payload: 'invalid output'
-                    },
-                    hono: {
-                        status: 200,
-                        payload: {
-                            type: 'OutputValidationError',
-                            message: 'invalid output'
-                        }
-                    }
-                }
-            }
-        },
-        {
-            name: 'policy pass with full operation context',
-            policy: true,
-            request: {
-                method: 'get',
-                path: '/hello',
-                headers: {
-                    'x-modernjs-bff-envelope': validEnvelope,
-                    'x-operation-id': validOperationId,
-                    'x-modernjs-bff-operation-context': detailHeader({
-                        requestId: PARITY_PRODUCER_REQUEST_ID,
-                        method: 'GET',
-                        routePath: '/hello',
-                        schemaHash: helloContract.schemaHash,
-                        operationVersion: helloContract.operationVersion
-                    })
-                }
-            },
-            expected: {
-                kind: 'payload',
-                status: 200,
-                payload: {
-                    message: 'hello'
-                }
-            }
-        },
-        deniedScenario('policy denies missing envelope', 'missing_envelope', {}),
-        deniedScenario('policy denies invalid envelope', 'invalid_envelope', {
-            'x-modernjs-bff-envelope': 'not-json'
-        }),
-        deniedScenario('policy denies envelope that is valid JSON but not an object', 'invalid_envelope', {
-            'x-modernjs-bff-envelope': '123'
-        }),
-        deniedScenario('policy denies missing requestId', 'missing_request_id', {
-            'x-modernjs-bff-envelope': envelopeHeader(void 0)
-        }),
-        deniedScenario('policy denies namespace outside allowlist', 'namespace_not_allowed', {
-            'x-modernjs-bff-envelope': envelopeHeader('billing.producer-z')
-        }),
-        deniedScenario('policy denies missing operation context', 'missing_operation_context', {
-            'x-modernjs-bff-envelope': validEnvelope
-        }),
-        deniedScenario('policy denies operation context mismatch', 'operation_context_mismatch', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': 'someone-else:parity'
-        }),
-        deniedScenario('policy denies missing operation context details', 'missing_operation_context_details', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId
-        }),
-        deniedScenario('policy denies JSON-array operation context details', 'invalid_operation_context_details', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': '[]'
-        }),
-        deniedScenario('policy denies invalid operation context details', 'invalid_operation_context_details', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': 'not-json'
-        }),
-        deniedScenario('policy denies detail requestId mismatch', 'operation_context_details_request_id_mismatch', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: 'crm.producer-b',
-                method: 'GET',
-                routePath: '/hello',
-                schemaHash: helloContract.schemaHash,
-                operationVersion: helloContract.operationVersion
-            })
-        }),
-        deniedScenario('policy denies missing operation schema hash', 'missing_operation_schema_hash', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: PARITY_PRODUCER_REQUEST_ID,
-                method: 'GET',
-                routePath: '/hello',
-                operationVersion: helloContract.operationVersion
-            })
-        }),
-        deniedScenario('policy denies missing operation version', 'missing_operation_version', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: PARITY_PRODUCER_REQUEST_ID,
-                method: 'GET',
-                routePath: '/hello',
-                schemaHash: helloContract.schemaHash
-            })
-        }),
-        deniedScenario('policy denies unknown operation contract', 'unknown_operation_contract', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: PARITY_PRODUCER_REQUEST_ID,
-                method: 'GET',
-                routePath: '/does-not-exist',
-                schemaHash: helloContract.schemaHash,
-                operationVersion: helloContract.operationVersion
-            })
-        }),
-        deniedScenario('policy denies operation schema hash mismatch', 'operation_schema_hash_mismatch', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: PARITY_PRODUCER_REQUEST_ID,
-                method: 'GET',
-                routePath: '/hello',
-                schemaHash: 'deadbeef',
-                operationVersion: helloContract.operationVersion
-            })
-        }),
-        deniedScenario('policy denies operation version mismatch', 'operation_version_mismatch', {
-            'x-modernjs-bff-envelope': validEnvelope,
-            'x-operation-id': validOperationId,
-            'x-modernjs-bff-operation-context': detailHeader({
-                requestId: PARITY_PRODUCER_REQUEST_ID,
-                method: 'GET',
-                routePath: '/hello',
-                schemaHash: helloContract.schemaHash,
-                operationVersion: helloContract.operationVersion + 1
-            })
-        })
+        ...createEnvelopeParityScenarios(),
+        ...createSchemaParityScenarios(),
+        ...createOperationContextSuccessScenarios(context),
+        ...createCrossProjectDenialScenarios(),
+        ...createOperationContextDenialScenarios(context)
     ];
 };
 const toParityResult = (res)=>({
@@ -466,17 +130,10 @@ const toParityResult = (res)=>({
         payload: res.type.includes('json') ? res.body : '' === res.text ? void 0 : res.text
     });
 const formatValue = (value)=>JSON.stringify(value);
-const assertParityResult = (scenario, res, adapter)=>{
+const assertParityResult = (scenario, res)=>{
     const result = toParityResult(res);
     const failures = [];
-    let { expected } = scenario;
-    if ('perAdapter' === expected.kind) {
-        if (void 0 === adapter) throw new Error(`Adapter parity scenario "${scenario.name}" pins per-adapter drift; pass the adapter id to assertParityResult.`);
-        expected = {
-            kind: 'payload',
-            ...expected.expectations[adapter]
-        };
-    }
+    const { expected } = scenario;
     if (result.status !== expected.status) failures.push(`status: expected ${expected.status}, received ${result.status}`);
     if ('payload' === expected.kind) {
         if (formatValue(result.payload) !== formatValue(expected.payload)) failures.push(`payload: expected ${formatValue(expected.payload)}, received ${formatValue(result.payload)}`);

package/dist/esm-node/security/crossProjectPolicy.mjs

@@ -3,6 +3,8 @@ const BFF_ENVELOPE_HEADER = 'x-modernjs-bff-envelope';
 const BFF_OPERATION_CONTEXT_HEADER = 'x-operation-id';
 const BFF_OPERATION_CONTEXT_DETAIL_HEADER = 'x-modernjs-bff-operation-context';
 const DEFAULT_DENY_STATUS = 403;
+const NAMESPACE_ALLOWLIST_REQUIRES_VERIFIER_MESSAGE = 'cross-project namespace allowlist requires verifyProducerIdentity in production';
+let hasWarnedAdvisoryNamespaceAllowlist = false;
 const normalizeHeaderName = (headerName, fallback)=>(headerName || fallback).trim().toLowerCase();
 const normalizeStatusCode = (statusCode)=>{
     if ('number' == typeof statusCode && Number.isFinite(statusCode) && statusCode >= 400 && statusCode <= 599) return Math.floor(statusCode);
@@ -23,22 +25,46 @@ const createViolation = (reason, message, status)=>({
         message,
         status
     });
-const evaluateCrossProjectPolicy = (headers, policy)=>{
-    if (!policy?.enabled) return null;
-    const status = normalizeStatusCode(policy.denyStatus);
-    const requireEnvelope = policy.requireEnvelope ?? true;
-    const requireOperationContext = policy.requireOperationContext ?? true;
-    const requireOperationContextDetails = policy.requireOperationContextDetails ?? true;
-    const requireOperationSchemaHash = policy.requireOperationSchemaHash ?? true;
-    const requireOperationVersion = policy.requireOperationVersion ?? true;
-    const allowUnknownOperations = policy.allowUnknownOperations ?? false;
-    const envelopeHeader = normalizeHeaderName(policy.envelopeHeader, BFF_ENVELOPE_HEADER);
-    const operationContextHeader = normalizeHeaderName(policy.operationContextHeader, BFF_OPERATION_CONTEXT_HEADER);
-    const operationContextDetailHeader = normalizeHeaderName(policy.operationContextDetailHeader, BFF_OPERATION_CONTEXT_DETAIL_HEADER);
-    const envelopeRaw = readHeader(headers, envelopeHeader);
+const isProductionMode = ()=>"u" > typeof process && process.env?.NODE_ENV === 'production';
+const warnAdvisoryNamespaceAllowlist = ()=>{
+    if (hasWarnedAdvisoryNamespaceAllowlist) return;
+    hasWarnedAdvisoryNamespaceAllowlist = true;
+    console.warn(`[Modern.js BFF] ${NAMESPACE_ALLOWLIST_REQUIRES_VERIFIER_MESSAGE}. Non-production requests will continue to evaluate allowlist against client-asserted requestId namespaces only.`);
+};
+const createCrossProjectPolicyEvaluationState = (headers, policy)=>({
+        headers,
+        policy,
+        status: normalizeStatusCode(policy.denyStatus),
+        requireEnvelope: policy.requireEnvelope ?? true,
+        requireOperationContext: policy.requireOperationContext ?? true,
+        requireOperationContextDetails: policy.requireOperationContextDetails ?? true,
+        requireOperationSchemaHash: policy.requireOperationSchemaHash ?? true,
+        requireOperationVersion: policy.requireOperationVersion ?? true,
+        allowUnknownOperations: policy.allowUnknownOperations ?? false,
+        verifyProducerIdentity: 'function' == typeof policy.verifyProducerIdentity ? policy.verifyProducerIdentity : void 0,
+        allowedNamespaces: (policy.allowedNamespaces || []).map((item)=>item.trim().toLowerCase()).filter(Boolean),
+        envelopeHeader: normalizeHeaderName(policy.envelopeHeader, BFF_ENVELOPE_HEADER),
+        operationContextHeader: normalizeHeaderName(policy.operationContextHeader, BFF_OPERATION_CONTEXT_HEADER),
+        operationContextDetailHeader: normalizeHeaderName(policy.operationContextDetailHeader, BFF_OPERATION_CONTEXT_DETAIL_HEADER),
+        requestId: '',
+        detailSchemaHash: '',
+        detailOperationVersion: void 0,
+        complete: false
+    });
+const checkNamespaceAllowlistVerifier = (state)=>{
+    if (state.allowedNamespaces.length > 0 && void 0 === state.verifyProducerIdentity) {
+        if (isProductionMode()) return createViolation('producer_identity_mismatch', NAMESPACE_ALLOWLIST_REQUIRES_VERIFIER_MESSAGE, state.status);
+        warnAdvisoryNamespaceAllowlist();
+    }
+};
+const checkEnvelopeHeader = (state)=>{
+    const envelopeRaw = readHeader(state.headers, state.envelopeHeader);
     if (!envelopeRaw) {
-        if (!requireEnvelope) return null;
-        return createViolation('missing_envelope', `Missing cross-project envelope header "${envelopeHeader}"`, status);
+        if (!state.requireEnvelope) {
+            state.complete = true;
+            return;
+        }
+        return createViolation('missing_envelope', `Missing cross-project envelope header "${state.envelopeHeader}"`, state.status);
     }
     let envelope;
     try {
@@ -46,57 +72,92 @@ const evaluateCrossProjectPolicy = (headers, policy)=>{
         if (!parsed || 'object' != typeof parsed) throw new Error('invalid envelope object');
         envelope = parsed;
     } catch (_error) {
-        return createViolation('invalid_envelope', `Invalid cross-project envelope header "${envelopeHeader}"`, status);
+        return createViolation('invalid_envelope', `Invalid cross-project envelope header "${state.envelopeHeader}"`, state.status);
     }
     const requestId = String(envelope.requestId || '').trim();
-    if (!requestId) return createViolation('missing_request_id', 'Cross-project envelope does not include a valid requestId', status);
-    const claimedNamespace = extractNamespace(requestId);
-    let effectiveNamespace = claimedNamespace;
-    if ('function' == typeof policy.verifyProducerIdentity) {
-        const verifiedNamespaceRaw = policy.verifyProducerIdentity(headers);
-        const verifiedNamespace = 'string' == typeof verifiedNamespaceRaw ? verifiedNamespaceRaw.trim().toLowerCase() : void 0;
-        if (!verifiedNamespace) return createViolation('producer_identity_mismatch', 'Producer identity could not be verified for this request', status);
-        if (verifiedNamespace !== claimedNamespace) return createViolation('producer_identity_mismatch', `Envelope namespace "${claimedNamespace || 'unknown'}" does not match verified producer identity "${verifiedNamespace}"`, status);
-        effectiveNamespace = verifiedNamespace;
+    if (!requestId) return createViolation('missing_request_id', 'Cross-project envelope does not include a valid requestId', state.status);
+    state.requestId = requestId;
+    state.claimedNamespace = extractNamespace(requestId);
+    state.effectiveNamespace = state.claimedNamespace;
+};
+const checkProducerIdentity = (state)=>{
+    if (!state.verifyProducerIdentity) return;
+    const verifiedNamespaceRaw = state.verifyProducerIdentity(state.headers);
+    const verifiedNamespace = 'string' == typeof verifiedNamespaceRaw ? verifiedNamespaceRaw.trim().toLowerCase() : void 0;
+    if (!verifiedNamespace) return createViolation('producer_identity_mismatch', 'Producer identity could not be verified for request', state.status);
+    if (verifiedNamespace !== state.claimedNamespace) return createViolation('producer_identity_mismatch', `Envelope namespace "${state.claimedNamespace || 'unknown'}" does not match verified producer identity "${verifiedNamespace}"`, state.status);
+    state.effectiveNamespace = verifiedNamespace;
+};
+const checkNamespaceAllowlist = (state)=>{
+    if (state.allowedNamespaces.length > 0) {
+        if (!state.effectiveNamespace || !state.allowedNamespaces.includes(state.effectiveNamespace)) return createViolation('namespace_not_allowed', `Producer namespace "${state.effectiveNamespace || 'unknown'}" not allowed`, state.status);
     }
-    const namespaces = (policy.allowedNamespaces || []).map((item)=>item.trim().toLowerCase()).filter(Boolean);
-    if (namespaces.length > 0) {
-        if (!effectiveNamespace || !namespaces.includes(effectiveNamespace)) return createViolation('namespace_not_allowed', `Producer namespace "${effectiveNamespace || 'unknown'}" is not allowed`, status);
+};
+const checkOperationContext = (state)=>{
+    if (!state.requireOperationContext) {
+        state.complete = true;
+        return;
     }
-    if (requireOperationContext) {
-        const operationContext = readHeader(headers, operationContextHeader);
-        if (!operationContext) return createViolation('missing_operation_context', `Missing operation context header "${operationContextHeader}"`, status);
-        if (!operationContext.startsWith(`${requestId}:`)) return createViolation('operation_context_mismatch', `Operation context header "${operationContextHeader}" does not match requestId "${requestId}"`, status);
-        const operationContextDetailsRaw = readHeader(headers, operationContextDetailHeader);
-        if (!operationContextDetailsRaw) {
-            if (requireOperationContextDetails) return createViolation('missing_operation_context_details', `Missing operation context details header "${operationContextDetailHeader}"`, status);
-            return null;
-        }
-        let operationContextDetails;
-        try {
-            const parsed = JSON.parse(operationContextDetailsRaw);
-            if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) throw new Error('invalid operation context details object');
-            operationContextDetails = parsed;
-        } catch (_error) {
-            return createViolation('invalid_operation_context_details', `Invalid operation context details header "${operationContextDetailHeader}"`, status);
-        }
-        const detailRequestId = String(operationContextDetails.requestId || '').trim();
-        if (detailRequestId && detailRequestId !== requestId) return createViolation('operation_context_details_request_id_mismatch', `Operation context details requestId "${detailRequestId}" does not match envelope requestId "${requestId}"`, status);
-        const detailSchemaHash = String(operationContextDetails.schemaHash || '').trim();
-        if (requireOperationSchemaHash && !detailSchemaHash) return createViolation('missing_operation_schema_hash', `Operation context details header "${operationContextDetailHeader}" must include schemaHash`, status);
-        const detailOperationVersion = operationContextDetails.operationVersion;
-        if (requireOperationVersion && 'number' != typeof detailOperationVersion) return createViolation('missing_operation_version', `Operation context details header "${operationContextDetailHeader}" must include operationVersion`, status);
-        const expectedContracts = policy.expectedOperationContracts;
-        if (expectedContracts && 'object' == typeof expectedContracts && Object.keys(expectedContracts).length > 0) {
-            const method = String(operationContextDetails.method || '').toUpperCase();
-            const routePath = String(operationContextDetails.routePath || '').trim();
-            const operationId = String(operationContextDetails.operationId || '').trim();
-            const expectedContract = expectedContracts[`${method}:${routePath}`] || expectedContracts[`operation:${operationId}`];
-            if (expectedContract) {
-                if (expectedContract.schemaHash && detailSchemaHash && expectedContract.schemaHash !== detailSchemaHash) return createViolation('operation_schema_hash_mismatch', `Operation schema hash mismatch for "${operationId || `${method}:${routePath}`}"`, status);
-                if ('number' == typeof expectedContract.operationVersion && 'number' == typeof detailOperationVersion && expectedContract.operationVersion !== detailOperationVersion) return createViolation('operation_version_mismatch', `Operation version mismatch for "${operationId || `${method}:${routePath}`}"`, status);
-            } else if (!allowUnknownOperations) return createViolation('unknown_operation_contract', `No expected operation contract found for operation "${operationId || `${method}:${routePath}`}"`, status);
-        }
+    const operationContext = readHeader(state.headers, state.operationContextHeader);
+    if (!operationContext) return createViolation('missing_operation_context', `Missing operation context header "${state.operationContextHeader}"`, state.status);
+    if (!operationContext.startsWith(`${state.requestId}:`)) return createViolation('operation_context_mismatch', `Operation context header "${state.operationContextHeader}" does not match requestId "${state.requestId}"`, state.status);
+    state.operationContext = operationContext;
+};
+const checkOperationContextDetails = (state)=>{
+    const operationContextDetailsRaw = readHeader(state.headers, state.operationContextDetailHeader);
+    if (!operationContextDetailsRaw) {
+        if (state.requireOperationContextDetails) return createViolation('missing_operation_context_details', `Missing operation context details header "${state.operationContextDetailHeader}"`, state.status);
+        state.complete = true;
+        return;
+    }
+    let operationContextDetails;
+    try {
+        const parsed = JSON.parse(operationContextDetailsRaw);
+        if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) throw new Error('invalid operation context details object');
+        operationContextDetails = parsed;
+    } catch (_error) {
+        return createViolation('invalid_operation_context_details', `Invalid operation context details header "${state.operationContextDetailHeader}"`, state.status);
+    }
+    const detailRequestId = String(operationContextDetails.requestId || '').trim();
+    if (detailRequestId && detailRequestId !== state.requestId) return createViolation('operation_context_details_request_id_mismatch', `Operation context details requestId "${detailRequestId}" does not match envelope requestId "${state.requestId}"`, state.status);
+    const detailOperationId = String(operationContextDetails.operationId || '').trim();
+    if (state.operationContext && detailOperationId && detailOperationId !== state.operationContext) return createViolation('operation_context_mismatch', `Operation context details operationId "${detailOperationId}" does not match operation context "${state.operationContext}"`, state.status);
+    state.operationContextDetails = operationContextDetails;
+    state.detailSchemaHash = String(operationContextDetails.schemaHash || '').trim();
+    if (state.requireOperationSchemaHash && !state.detailSchemaHash) return createViolation('missing_operation_schema_hash', `Operation context details header "${state.operationContextDetailHeader}" must include schemaHash`, state.status);
+    state.detailOperationVersion = operationContextDetails.operationVersion;
+    if (state.requireOperationVersion && 'number' != typeof state.detailOperationVersion) return createViolation('missing_operation_version', `Operation context details header "${state.operationContextDetailHeader}" must include operationVersion`, state.status);
+};
+const checkOperationContract = (state)=>{
+    if (!state.operationContextDetails) return;
+    const expectedContracts = state.policy.expectedOperationContracts;
+    if (expectedContracts && 'object' == typeof expectedContracts) {
+        const method = String(state.operationContextDetails.method || '').toUpperCase();
+        const routePath = String(state.operationContextDetails.routePath || '').trim();
+        const operationId = String(state.operationContextDetails.operationId || '').trim();
+        const expectedContract = expectedContracts[`${method}:${routePath}`] || expectedContracts[`operation:${operationId}`];
+        if (expectedContract) {
+            if (expectedContract.schemaHash && state.detailSchemaHash && expectedContract.schemaHash !== state.detailSchemaHash) return createViolation('operation_schema_hash_mismatch', `Operation schema hash mismatch for "${operationId || `${method}:${routePath}`}"`, state.status);
+            if ('number' == typeof expectedContract.operationVersion && 'number' == typeof state.detailOperationVersion && expectedContract.operationVersion !== state.detailOperationVersion) return createViolation('operation_version_mismatch', `Operation version mismatch for "${operationId || `${method}:${routePath}`}"`, state.status);
+        } else if (!state.allowUnknownOperations) return createViolation('unknown_operation_contract', `No expected operation contract found for operation "${operationId || `${method}:${routePath}`}"`, state.status);
+    }
+};
+const CROSS_PROJECT_POLICY_CHECKS = [
+    checkNamespaceAllowlistVerifier,
+    checkEnvelopeHeader,
+    checkProducerIdentity,
+    checkNamespaceAllowlist,
+    checkOperationContext,
+    checkOperationContextDetails,
+    checkOperationContract
+];
+const evaluateCrossProjectPolicy = (headers, policy)=>{
+    if (!policy?.enabled) return null;
+    const state = createCrossProjectPolicyEvaluationState(headers, policy);
+    for (const check of CROSS_PROJECT_POLICY_CHECKS){
+        const violation = check(state);
+        if (violation) return violation;
+        if (state.complete) break;
     }
     return null;
 };

package/dist/types/adapter-kit/index.d.ts

@@ -3,7 +3,7 @@ import type { ResponseMeta } from '../operators/http';
 import type { APIHandlerInfo, ApiHandler } from '../router';
 import { type CrossProjectPolicyConfig, type CrossProjectPolicyViolation } from '../security/crossProjectPolicy';
 import { HttpMethod } from '../types';
-/** Lowercase route-registration method shared by express/koa/hono routers. */
+/** Lowercase route-registration method shared by supported adapter routers. */
 export type ApiRouteMethod = Lowercase<`${HttpMethod}`>;
 /**
  * Maps an `APIHandlerInfo.httpMethod` onto the lowercase router method.
@@ -74,7 +74,7 @@ export type ApiHandlerInput = {
  * Positional invocation convention for plain function handlers: route params
  * in declaration order followed by the full input object.
  */
-export declare const buildPositionalHandlerArgs: (input: ApiHandlerInput) => unknown[];
+export declare const buildPositionalHandlerArgs: (input: ApiHandlerInput, routePath?: string) => unknown[];
 export type CrossProjectPolicyDenial = {
     status: number;
     body: {

package/dist/types/adapter-kit/parity-scenarios/cross-project-denial.d.ts

@@ -0,0 +1,2 @@
+import type { AdapterParityScenario } from './shared';
+export declare const createCrossProjectDenialScenarios: () => AdapterParityScenario[];

package/dist/types/adapter-kit/parity-scenarios/envelope.d.ts

@@ -0,0 +1,2 @@
+import type { AdapterParityScenario } from './shared';
+export declare const createEnvelopeParityScenarios: () => AdapterParityScenario[];

package/dist/types/adapter-kit/parity-scenarios/operation-context.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterParityScenario, AdapterParityScenarioContext } from './shared';
+export declare const createOperationContextSuccessScenarios: ({ helloContract, validEnvelope, validOperationId, }: AdapterParityScenarioContext) => AdapterParityScenario[];
+export declare const createOperationContextDenialScenarios: ({ helloContract, validEnvelope, validOperationId, }: AdapterParityScenarioContext) => AdapterParityScenario[];