@bleedingdev/modern-js-bff-core 3.2.0-ultramodern.0

package/dist/esm/client/result.mjs

@@ -0,0 +1,19 @@
+const Err = (value)=>{
+    const err = {
+        kind: 'Err',
+        value,
+        isErr: true,
+        isOk: false
+    };
+    return err;
+};
+const Ok = (value)=>{
+    const ok = {
+        kind: 'Ok',
+        value,
+        isErr: false,
+        isOk: true
+    };
+    return ok;
+};
+export { Err, Ok };

package/dist/esm/contracts/eventContracts.mjs

@@ -0,0 +1,28 @@
+const defineEventContract = (input)=>{
+    const normalizedName = input.name.trim();
+    if (!normalizedName) throw new Error('Event contract name must be non-empty');
+    if (!Number.isFinite(input.version) || input.version <= 0) throw new Error('Event contract version must be a positive number');
+    if (!input.schemaHash || !input.schemaHash.trim()) throw new Error('Event contract schemaHash must be non-empty');
+    return {
+        name: normalizedName,
+        version: Math.floor(input.version),
+        schemaHash: input.schemaHash.trim(),
+        description: input.description
+    };
+};
+const createEventEnvelope = (contract, payload, meta)=>({
+        name: contract.name,
+        version: contract.version,
+        schemaHash: contract.schemaHash,
+        timestamp: Date.now(),
+        payload,
+        ...meta ? {
+            meta
+        } : {}
+    });
+const isEventEnvelope = (value)=>{
+    if (!value || 'object' != typeof value || Array.isArray(value)) return false;
+    const candidate = value;
+    return 'string' == typeof candidate.name && candidate.name.length > 0 && 'number' == typeof candidate.version && candidate.version > 0 && 'string' == typeof candidate.schemaHash && candidate.schemaHash.length > 0 && 'number' == typeof candidate.timestamp && Number.isFinite(candidate.timestamp) && 'payload' in candidate;
+};
+export { createEventEnvelope, defineEventContract, isEventEnvelope };

package/dist/esm/errors/http.mjs

@@ -0,0 +1,13 @@
+class HttpError extends Error {
+    constructor(status, message){
+        super(message);
+        this.status = status;
+    }
+}
+class ValidationError extends HttpError {
+    constructor(status, message){
+        super(status, message);
+        this.code = 'VALIDATION_ERROR';
+    }
+}
+export { HttpError, ValidationError };

package/dist/esm/index.mjs

@@ -0,0 +1,10 @@
+export * from "./client/index.mjs";
+export * from "./contracts/eventContracts.mjs";
+export * from "./operators/http.mjs";
+export * from "./router/index.mjs";
+export * from "./security/crossProjectPolicy.mjs";
+export * from "./security/operationContracts.mjs";
+export * from "./types.mjs";
+export { Api } from "./api.mjs";
+export { HttpError, ValidationError } from "./errors/http.mjs";
+export { HANDLER_WITH_META, INPUT_PARAMS_DECIDER, createStorage, getRelativeRuntimePath, isInputParamsDeciderHandler, isWithMetaHandler, registerPaths } from "./utils/index.mjs";

package/dist/esm/operators/http.mjs

@@ -0,0 +1,135 @@
+import { ValidationError } from "../errors/http.mjs";
+import { HttpMetadata, HttpMethod, OperatorType, ResponseMetaType, TriggerType } from "../types.mjs";
+const validateInput = async (schema, input)=>{
+    try {
+        return await schema.parseAsync(input);
+    } catch (error) {
+        if ('name' in error && 'ZodError' === error.name) throw new ValidationError(400, error.message);
+        throw error;
+    }
+};
+const createHttpOperator = (method)=>(urlPath)=>({
+            name: method,
+            metadata ({ setMetadata }) {
+                setMetadata(OperatorType.Trigger, {
+                    type: TriggerType.Http,
+                    path: urlPath,
+                    method
+                });
+            }
+        });
+const Get = createHttpOperator(HttpMethod.Get);
+const Post = createHttpOperator(HttpMethod.Post);
+const Put = createHttpOperator(HttpMethod.Put);
+const Delete = createHttpOperator(HttpMethod.Delete);
+const Connect = createHttpOperator(HttpMethod.Connect);
+const Trace = createHttpOperator(HttpMethod.Trace);
+const Patch = createHttpOperator(HttpMethod.Patch);
+const Options = createHttpOperator(HttpMethod.Options);
+const Head = createHttpOperator(HttpMethod.Head);
+const Data = (schema)=>({
+        name: HttpMetadata.Data,
+        metadata ({ setMetadata }) {
+            setMetadata(HttpMetadata.Data, schema);
+        },
+        async validate (helper, next) {
+            const { inputs: { data } } = helper;
+            helper.inputs = {
+                ...helper.inputs,
+                data: await validateInput(schema, data)
+            };
+            return next();
+        }
+    });
+const Query = (schema)=>({
+        name: HttpMetadata.Query,
+        metadata ({ setMetadata }) {
+            setMetadata(HttpMetadata.Query, schema);
+        },
+        async validate (helper, next) {
+            const { inputs: { query } } = helper;
+            helper.inputs = {
+                ...helper.inputs,
+                query: await validateInput(schema, query)
+            };
+            return next();
+        }
+    });
+const Params = (schema)=>({
+        name: HttpMetadata.Params,
+        metadata ({ setMetadata }) {
+            setMetadata(HttpMetadata.Params, schema);
+        },
+        async validate (helper, next) {
+            const { inputs: { params } } = helper;
+            helper.inputs = {
+                ...helper.inputs,
+                params: await validateInput(schema, params)
+            };
+            return next();
+        }
+    });
+const Headers = (schema)=>({
+        name: HttpMetadata.Headers,
+        metadata ({ setMetadata }) {
+            setMetadata(HttpMetadata.Headers, schema);
+        },
+        async validate (helper, next) {
+            const { inputs: { headers } } = helper;
+            helper.inputs = {
+                ...helper.inputs,
+                headers: await validateInput(schema, headers)
+            };
+            return next();
+        }
+    });
+const setResponseMeta = (helper, type, value)=>{
+    const responseMetaData = helper.getMetadata(HttpMetadata.Response) || [];
+    helper.setMetadata(HttpMetadata.Response, [
+        ...responseMetaData,
+        {
+            type,
+            value
+        }
+    ]);
+};
+const HttpCode = (statusCode)=>({
+        name: 'HttpCode',
+        metadata (helper) {
+            setResponseMeta(helper, ResponseMetaType.StatusCode, statusCode);
+        }
+    });
+const SetHeaders = (headers)=>({
+        name: 'SetHeaders',
+        metadata (helper) {
+            setResponseMeta(helper, ResponseMetaType.Headers, headers);
+        }
+    });
+const Redirect = (url)=>({
+        name: 'Redirect',
+        metadata (helper) {
+            setResponseMeta(helper, ResponseMetaType.Redirect, url);
+        }
+    });
+const Upload = (urlPath, schema)=>({
+        name: 'Upload',
+        metadata ({ setMetadata }) {
+            setMetadata(OperatorType.Trigger, {
+                type: TriggerType.Http,
+                path: urlPath,
+                method: HttpMethod.Post,
+                action: 'upload'
+            });
+            setMetadata(HttpMetadata.Files, schema);
+        },
+        async validate (helper, next) {
+            if (!schema) return next();
+            const { inputs: { formData: files } } = helper;
+            helper.inputs = {
+                ...helper.inputs,
+                files: await validateInput(schema, files)
+            };
+            return next();
+        }
+    });
+export { Connect, Data, Delete, Get, Head, Headers, HttpCode, Options, Params, Patch, Post, Put, Query, Redirect, SetHeaders, Trace, Upload, createHttpOperator };

package/dist/esm/router/constants.mjs

@@ -0,0 +1,19 @@
+import { HttpMethod } from "../types.mjs";
+const AllHttpMethods = Object.values(HttpMethod);
+const FRAMEWORK_MODE_LAMBDA_DIR = 'lambda';
+const FRAMEWORK_MODE_APP_DIR = 'app';
+const INDEX_SUFFIX = 'index';
+const API_DIR = 'api';
+const API_FILE_RULES = [
+    '**/*.[tj]s',
+    '!**/_*',
+    '!**/_*/**/*.[tj]s',
+    '!**/*.test.js',
+    '!**/*.test.ts',
+    '!**/*.d.ts',
+    '!__test__/*.ts',
+    '!__tests__/*.ts',
+    '!node_modules/**',
+    '!bootstrap.jsx'
+];
+export { API_DIR, API_FILE_RULES, AllHttpMethods, FRAMEWORK_MODE_APP_DIR, FRAMEWORK_MODE_LAMBDA_DIR, INDEX_SUFFIX };

package/dist/esm/router/index.mjs

@@ -0,0 +1,192 @@
+import { fs, logger } from "@modern-js/utils";
+import path from "path";
+import "reflect-metadata";
+import { HttpMethod, OperatorType, TriggerType, httpMethods } from "../types.mjs";
+import { INPUT_PARAMS_DECIDER, debug } from "../utils/index.mjs";
+import { API_FILE_RULES, FRAMEWORK_MODE_LAMBDA_DIR } from "./constants.mjs";
+import { getFiles, getPathFromFilename, requireHandlerModule, sortRoutes } from "./utils.mjs";
+export * from "./constants.mjs";
+export * from "./types.mjs";
+class ApiRouter {
+    isExistLambda() {
+        return this.existLambdaDir;
+    }
+    getLambdaDir() {
+        return this.lambdaDir;
+    }
+    isApiFile(filename) {
+        if (this.apiFiles.includes(filename)) return true;
+        return false;
+    }
+    async getSingleModuleHandlers(filename) {
+        const moduleInfo = await this.getModuleInfo(filename);
+        if (moduleInfo) return this.getModuleHandlerInfos(moduleInfo);
+        return null;
+    }
+    getHandlerInfo(filename, originFuncName, handler) {
+        const httpMethod = this.getHttpMethod(originFuncName, handler);
+        const routeName = this.getRouteName(filename, handler);
+        const action = this.getAction(handler);
+        const responseObj = {
+            handler,
+            name: originFuncName,
+            httpMethod,
+            routeName,
+            filename,
+            routePath: this.getRoutePath(this.prefix, routeName)
+        };
+        if (action) responseObj.action = action;
+        if (httpMethod && routeName) return responseObj;
+        return null;
+    }
+    getSafeRoutePath(filename, handler) {
+        this.loadApiFiles();
+        this.validateValidApifile(filename);
+        return this.getRouteName(filename, handler);
+    }
+    getRouteName(filename, handler) {
+        if (handler) {
+            const trigger = Reflect.getMetadata(OperatorType.Trigger, handler);
+            if (trigger && trigger.type === TriggerType.Http) {
+                if (!trigger.path) throw new Error(`The http trigger ${trigger.name} needs to specify a path`);
+                return trigger.path;
+            }
+        }
+        let routePath = getPathFromFilename(this.lambdaDir, filename);
+        if ('inputParams' === this.httpMethodDecider) if (routePath.endsWith('/')) routePath += `${handler?.name}`;
+        else routePath += `/${handler?.name}`;
+        return routePath;
+    }
+    getHttpMethod(originHandlerName, handler) {
+        if (handler) {
+            const trigger = Reflect.getMetadata(OperatorType.Trigger, handler);
+            if (trigger && httpMethods.includes(trigger.method)) return trigger.method;
+        }
+        if ('functionName' === this.httpMethodDecider) {
+            const upperName = originHandlerName.toUpperCase();
+            switch(upperName){
+                case 'GET':
+                    return HttpMethod.Get;
+                case 'POST':
+                    return HttpMethod.Post;
+                case 'PUT':
+                    return HttpMethod.Put;
+                case 'DELETE':
+                case 'DEL':
+                    return HttpMethod.Delete;
+                case 'CONNECT':
+                    return HttpMethod.Connect;
+                case 'TRACE':
+                    return HttpMethod.Trace;
+                case 'PATCH':
+                    return HttpMethod.Patch;
+                case 'OPTIONS':
+                    return HttpMethod.Options;
+                case 'DEFAULT':
+                    return HttpMethod.Get;
+                default:
+                    if ('test' !== process.env.NODE_ENV) logger.warn(`Only api handlers are allowd to be exported, please remove the function ${originHandlerName} from exports`);
+                    return null;
+            }
+        }
+        if (!handler) return null;
+        if ('function' == typeof handler && handler.length > 0) return HttpMethod.Post;
+        return HttpMethod.Get;
+    }
+    getAction(handler) {
+        if (handler) {
+            const trigger = Reflect.getMetadata(OperatorType.Trigger, handler);
+            if (trigger?.action) return trigger.action;
+        }
+    }
+    loadApiFiles() {
+        if (!this.existLambdaDir) return [];
+        const apiFiles = this.apiFiles = getFiles(this.lambdaDir, API_FILE_RULES);
+        return apiFiles;
+    }
+    getApiFiles() {
+        if (!this.existLambdaDir) return [];
+        if (this.apiFiles.length > 0) return this.apiFiles;
+        return this.loadApiFiles();
+    }
+    async getApiHandlers() {
+        const filenames = this.getApiFiles();
+        const moduleInfos = await this.getModuleInfos(filenames);
+        const apiHandlers = this.getHandlerInfos(moduleInfos);
+        debug('apiHandlers', apiHandlers.length, apiHandlers);
+        return apiHandlers;
+    }
+    initPrefix(prefix) {
+        if ('/' === prefix) return '';
+        return prefix || '/api';
+    }
+    validateAbsolute(filename, paramsName) {
+        if ('string' == typeof filename && !path.isAbsolute(filename)) throw new Error(`The ${paramsName} ${filename} is not a abolute path`);
+    }
+    async getModuleInfos(filenames) {
+        const moduleInfos = await Promise.all(filenames.map((filename)=>this.getModuleInfo(filename)));
+        return moduleInfos.filter(Boolean);
+    }
+    async getModuleInfo(filename) {
+        try {
+            const module = await requireHandlerModule(filename);
+            return {
+                filename,
+                module
+            };
+        } catch (err) {
+            if ('production' === process.env.NODE_ENV) {
+                const error = new Error(`Failed to load BFF module '${filename}': ${err.message}`, {
+                    cause: err
+                });
+                throw error;
+            }
+            console.error(`Failed to load BFF module '${filename}':`, err);
+            return null;
+        }
+    }
+    getHandlerInfos(moduleInfos) {
+        let apiHandlers = [];
+        moduleInfos.forEach((moduleInfo)=>{
+            const handlerInfos = this.getModuleHandlerInfos(moduleInfo);
+            if (handlerInfos) apiHandlers = apiHandlers.concat(handlerInfos);
+        });
+        const sortedHandlers = sortRoutes(apiHandlers);
+        return sortedHandlers;
+    }
+    getModuleHandlerInfos(moduleInfo) {
+        const { module, filename } = moduleInfo;
+        const { httpMethodDecider } = this;
+        return Object.entries(module).filter(([, handler])=>'function' == typeof handler).map(([key])=>{
+            const handler = module[key];
+            if ('inputParams' === httpMethodDecider) Object.assign(handler, {
+                [INPUT_PARAMS_DECIDER]: true
+            });
+            const handlerInfo = this.getHandlerInfo(filename, key, handler);
+            return handlerInfo;
+        }).filter((handlerInfo)=>Boolean(handlerInfo));
+    }
+    validateValidApifile(filename) {
+        if (!this.apiFiles.includes(filename)) throw new Error(`The ${filename} is not a valid api file.`);
+    }
+    getRoutePath(prefix, routeName) {
+        const finalRouteName = '/' === routeName ? '' : routeName;
+        if ('' === prefix && '' === finalRouteName) return '/';
+        return `${prefix}${finalRouteName}`;
+    }
+    constructor({ appDir, apiDir, lambdaDir, prefix, isBuild, httpMethodDecider = 'functionName' }){
+        this.apiFiles = [];
+        this.getExactLambdaDir = (apiDir, originLambdaDir)=>originLambdaDir || path.join(apiDir, FRAMEWORK_MODE_LAMBDA_DIR);
+        this.validateAbsolute(apiDir, 'apiDir');
+        this.validateAbsolute(lambdaDir, 'lambdaDir');
+        this.prefix = this.initPrefix(prefix);
+        this.appDir = appDir;
+        this.apiDir = apiDir;
+        this.httpMethodDecider = httpMethodDecider;
+        this.isBuild = isBuild;
+        this.lambdaDir = this.getExactLambdaDir(this.apiDir, lambdaDir);
+        this.existLambdaDir = fs.existsSync(this.lambdaDir);
+        debug("apiDir:", this.apiDir, "lambdaDir:", this.lambdaDir);
+    }
+}
+export { ApiRouter };

package/dist/esm/router/utils.mjs

@@ -0,0 +1,41 @@
+import { compatibleRequire, globby } from "@modern-js/utils";
+import path from "path";
+import { INDEX_SUFFIX } from "./constants.mjs";
+const getFiles = (lambdaDir, rules)=>globby.sync(rules, {
+        cwd: lambdaDir,
+        gitignore: true
+    }).map((file)=>path.resolve(lambdaDir, file));
+const getPathFromFilename = (baseDir, filename)=>{
+    const relativeName = filename.substring(baseDir.length);
+    const relativePath = relativeName.split('.').slice(0, -1).join('.');
+    const nameSplit = relativePath.split(path.sep).map((item)=>{
+        if (item.length > 2) {
+            if (item.startsWith('[') && item.endsWith(']')) return `:${item.substring(1, item.length - 1)}`;
+        }
+        return item;
+    });
+    const name = nameSplit.join('/');
+    const finalName = name.endsWith(INDEX_SUFFIX) ? name.substring(0, name.length - INDEX_SUFFIX.length) : name;
+    return clearRouteName(finalName);
+};
+const clearRouteName = (routeName)=>{
+    let finalRouteName = routeName.trim();
+    if (!finalRouteName.startsWith('/')) finalRouteName = `/${finalRouteName}`;
+    if (finalRouteName.length > 1 && finalRouteName.endsWith('/')) finalRouteName = finalRouteName.substring(0, finalRouteName.length - 1);
+    return finalRouteName;
+};
+const isHandler = (input)=>input && 'function' == typeof input;
+const isFunction = (input)=>input && '[object Function]' === ({}).toString.call(input);
+const requireHandlerModule = async (modulePath)=>{
+    const module = await compatibleRequire(modulePath, false);
+    if (isFunction(module)) return {
+        default: module
+    };
+    return module;
+};
+const routeValue = (routePath)=>{
+    if (routePath.includes(':')) return 11;
+    return 1;
+};
+const sortRoutes = (apiHandlers)=>apiHandlers.sort((handlerA, handlerB)=>routeValue(handlerA.routeName) - routeValue(handlerB.routeName));
+export { getFiles, getPathFromFilename, isHandler, requireHandlerModule, sortRoutes };

package/dist/esm/security/crossProjectPolicy.mjs

@@ -0,0 +1,94 @@
+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 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);
+    return DEFAULT_DENY_STATUS;
+};
+const readHeader = (headers, headerName)=>{
+    const lowerHeaderName = headerName.toLowerCase();
+    for (const [name, value] of Object.entries(headers || {}))if (name.toLowerCase() === lowerHeaderName) {
+        if (Array.isArray(value)) return value.length > 0 ? String(value[0]) : void 0;
+        if (null == value) return;
+        return String(value);
+    }
+};
+const extractNamespace = (requestId)=>requestId.split(/[/:.]/)[0]?.trim().toLowerCase();
+const createViolation = (reason, message, status)=>({
+        code: 'BFF_CROSS_PROJECT_POLICY_DENIED',
+        reason,
+        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);
+    if (!envelopeRaw) {
+        if (!requireEnvelope) return null;
+        return createViolation('missing_envelope', `Missing cross-project envelope header "${envelopeHeader}"`, status);
+    }
+    let envelope;
+    try {
+        const parsed = JSON.parse(envelopeRaw);
+        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);
+    }
+    const requestId = String(envelope.requestId || '').trim();
+    if (!requestId) return createViolation('missing_request_id', 'Cross-project envelope does not include a valid requestId', status);
+    const namespaces = (policy.allowedNamespaces || []).map((item)=>item.trim().toLowerCase()).filter(Boolean);
+    if (namespaces.length > 0) {
+        const namespace = extractNamespace(requestId);
+        if (!namespace || !namespaces.includes(namespace)) return createViolation('namespace_not_allowed', `Producer namespace "${namespace || 'unknown'}" is not allowed`, status);
+    }
+    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);
+        }
+    }
+    return null;
+};
+export { BFF_ENVELOPE_HEADER, BFF_OPERATION_CONTEXT_DETAIL_HEADER, BFF_OPERATION_CONTEXT_HEADER, evaluateCrossProjectPolicy };

package/dist/esm/security/operationContracts.mjs

@@ -0,0 +1,57 @@
+import { createHash } from "crypto";
+const DEFAULT_OPERATION_VERSION = 1;
+const createOperationEntries = (handlers)=>handlers.map((item)=>({
+            name: item.name,
+            httpMethod: String(item.httpMethod || '').toUpperCase(),
+            routePath: item.routePath
+        })).sort((a, b)=>{
+        const keyA = `${a.routePath}:${a.httpMethod}:${a.name}`;
+        const keyB = `${b.routePath}:${b.httpMethod}:${b.name}`;
+        return keyA.localeCompare(keyB);
+    });
+const createOperationSchemaHash = (operationEntries, requestId)=>createHash('sha256').update(JSON.stringify({
+        operations: operationEntries.map((item)=>({
+                name: item.name,
+                httpMethod: item.httpMethod,
+                routePath: item.routePath
+            })),
+        requestId
+    })).digest('hex');
+const buildOperationContractMap = ({ handlers, requestId })=>{
+    const normalizedRequestId = 'string' == typeof requestId && requestId.trim().length > 0 ? requestId.trim() : 'default';
+    const byModule = new Map();
+    handlers.forEach((item)=>{
+        const moduleId = 'string' == typeof item.filename && item.filename.length > 0 ? item.filename : '__anonymous__';
+        const group = byModule.get(moduleId) || [];
+        group.push({
+            name: item.name,
+            httpMethod: item.httpMethod.toUpperCase(),
+            routePath: item.routePath,
+            filename: item.filename
+        });
+        byModule.set(moduleId, group);
+    });
+    const contracts = {};
+    byModule.forEach((moduleEntries)=>{
+        const entries = createOperationEntries(moduleEntries);
+        const schemaHash = createOperationSchemaHash(entries, normalizedRequestId);
+        const filename = moduleEntries[0]?.filename;
+        entries.forEach((entry)=>{
+            const operationId = `${normalizedRequestId}:${entry.name}`;
+            const contract = {
+                requestId: normalizedRequestId,
+                operationVersion: DEFAULT_OPERATION_VERSION,
+                schemaHash,
+                method: entry.httpMethod,
+                routePath: entry.routePath,
+                operationId,
+                handlerName: entry.name,
+                filename
+            };
+            contracts[`${entry.httpMethod}:${entry.routePath}`] = contract;
+            contracts[`operation:${operationId}`] = contract;
+        });
+    });
+    return contracts;
+};
+export { DEFAULT_OPERATION_VERSION, buildOperationContractMap, createOperationEntries, createOperationSchemaHash };

package/dist/esm/types.mjs

@@ -0,0 +1,39 @@
+var types_OperatorType = /*#__PURE__*/ function(OperatorType) {
+    OperatorType[OperatorType["Trigger"] = 0] = "Trigger";
+    OperatorType[OperatorType["Middleware"] = 1] = "Middleware";
+    return OperatorType;
+}({});
+var types_TriggerType = /*#__PURE__*/ function(TriggerType) {
+    TriggerType[TriggerType["Http"] = 0] = "Http";
+    return TriggerType;
+}({});
+var types_HttpMetadata = /*#__PURE__*/ function(HttpMetadata) {
+    HttpMetadata["Method"] = "METHOD";
+    HttpMetadata["Data"] = "DATA";
+    HttpMetadata["Query"] = "QUERY";
+    HttpMetadata["Params"] = "PARAMS";
+    HttpMetadata["Headers"] = "HEADERS";
+    HttpMetadata["Response"] = "RESPONSE";
+    HttpMetadata["Files"] = "Files";
+    return HttpMetadata;
+}({});
+var types_ResponseMetaType = /*#__PURE__*/ function(ResponseMetaType) {
+    ResponseMetaType[ResponseMetaType["StatusCode"] = 0] = "StatusCode";
+    ResponseMetaType[ResponseMetaType["Redirect"] = 1] = "Redirect";
+    ResponseMetaType[ResponseMetaType["Headers"] = 2] = "Headers";
+    return ResponseMetaType;
+}({});
+var types_HttpMethod = /*#__PURE__*/ function(HttpMethod) {
+    HttpMethod["Get"] = "GET";
+    HttpMethod["Post"] = "POST";
+    HttpMethod["Put"] = "PUT";
+    HttpMethod["Delete"] = "DELETE";
+    HttpMethod["Connect"] = "CONNECT";
+    HttpMethod["Trace"] = "TRACE";
+    HttpMethod["Patch"] = "PATCH";
+    HttpMethod["Options"] = "OPTIONS";
+    HttpMethod["Head"] = "HEAD";
+    return HttpMethod;
+}({});
+const httpMethods = Object.values(types_HttpMethod);
+export { httpMethods, types_HttpMetadata as HttpMetadata, types_HttpMethod as HttpMethod, types_OperatorType as OperatorType, types_ResponseMetaType as ResponseMetaType, types_TriggerType as TriggerType };