@bleedingdev/modern-js-bff-core 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

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

@@ -1,6 +1,85 @@
 import "node:module";
 import { createHash } from "crypto";
+import "reflect-metadata";
+import { HttpMetadata } from "../types.mjs";
+import { __webpack_require__ } from "../rslib-runtime.mjs";
+import * as __rspack_external_zod from "zod";
+__webpack_require__.add({
+    zod (module) {
+        module.exports = __rspack_external_zod;
+    }
+});
 const DEFAULT_OPERATION_VERSION = 1;
+const deriveOperationVersion = (packageVersion)=>{
+    if ('string' != typeof packageVersion) return DEFAULT_OPERATION_VERSION;
+    const match = packageVersion.trim().match(/^v?(\d+)\./);
+    if (!match) return DEFAULT_OPERATION_VERSION;
+    const major = Number.parseInt(match[1], 10);
+    return Number.isInteger(major) && major >= 0 ? major : DEFAULT_OPERATION_VERSION;
+};
+const stableStringify = (value)=>{
+    if (Array.isArray(value)) return `[${value.map((item)=>stableStringify(item)).join(',')}]`;
+    if (value && 'object' == typeof value) {
+        const entries = Object.entries(value).filter(([, entryValue])=>void 0 !== entryValue).sort(([a], [b])=>a.localeCompare(b)).map(([key, entryValue])=>`${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+};
+const sha256 = (text)=>createHash('sha256').update(text).digest('hex');
+let cachedZodToJSONSchema;
+const resolveZodToJSONSchema = ()=>{
+    if (void 0 !== cachedZodToJSONSchema) return cachedZodToJSONSchema;
+    try {
+        const zod = __webpack_require__("zod");
+        const candidate = zod?.toJSONSchema ?? zod?.z?.toJSONSchema;
+        cachedZodToJSONSchema = 'function' == typeof candidate ? candidate : null;
+    } catch  {
+        cachedZodToJSONSchema = null;
+    }
+    return cachedZodToJSONSchema;
+};
+const INPUT_SCHEMA_METADATA_KEYS = [
+    HttpMetadata.Data,
+    HttpMetadata.Query,
+    HttpMetadata.Params,
+    HttpMetadata.Headers,
+    HttpMetadata.Files
+];
+const serializeSchema = (schema)=>{
+    const toJSONSchema = resolveZodToJSONSchema();
+    if (toJSONSchema) try {
+        return toJSONSchema(schema, {
+            io: 'input',
+            unrepresentable: 'any'
+        });
+    } catch  {}
+    return {
+        __unserializableSchema: true
+    };
+};
+const serializeOperationSchemas = (handler)=>{
+    if ('function' != typeof handler) return;
+    const serialized = {};
+    for (const metadataKey of INPUT_SCHEMA_METADATA_KEYS){
+        let schema;
+        try {
+            schema = Reflect.getMetadata(metadataKey, handler);
+        } catch  {
+            schema = void 0;
+        }
+        if (null != schema) serialized[metadataKey] = serializeSchema(schema);
+    }
+    return Object.keys(serialized).length > 0 ? serialized : void 0;
+};
+const createOperationContractHash = (operation, requestId)=>sha256(stableStringify({
+        httpMethod: String(operation.httpMethod || '').toUpperCase(),
+        name: operation.name,
+        requestId,
+        routePath: operation.routePath,
+        ...operation.schemas ? {
+            schemas: operation.schemas
+        } : {}
+    }));
 const createOperationEntries = (handlers)=>handlers.map((item)=>({
             name: item.name,
             httpMethod: String(item.httpMethod || '').toUpperCase(),
@@ -10,49 +89,44 @@ const createOperationEntries = (handlers)=>handlers.map((item)=>({
         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
-            })),
+const createOperationSchemaHash = (operationEntries, requestId)=>sha256(stableStringify({
+        operations: [
+            ...operationEntries
+        ].map((item)=>({
+                hash: item.schemaHash ?? createOperationContractHash({
+                    name: item.name,
+                    httpMethod: item.httpMethod,
+                    routePath: item.routePath
+                }, requestId)
+            })).sort((a, b)=>a.hash.localeCompare(b.hash)),
         requestId
-    })).digest('hex');
-const buildOperationContractMap = ({ handlers, requestId })=>{
+    }));
+const buildOperationContractMap = ({ handlers, requestId, operationVersion })=>{
     const normalizedRequestId = 'string' == typeof requestId && requestId.trim().length > 0 ? requestId.trim() : 'default';
-    const byModule = new Map();
+    const normalizedOperationVersion = 'number' == typeof operationVersion && Number.isInteger(operationVersion) ? operationVersion : DEFAULT_OPERATION_VERSION;
+    const contracts = {};
     handlers.forEach((item)=>{
-        const moduleId = 'string' == typeof item.filename && item.filename.length > 0 ? item.filename : '__anonymous__';
-        const group = byModule.get(moduleId) || [];
-        group.push({
+        const httpMethod = String(item.httpMethod || '').toUpperCase();
+        const schemaHash = createOperationContractHash({
             name: item.name,
-            httpMethod: item.httpMethod.toUpperCase(),
+            httpMethod,
+            routePath: item.routePath,
+            schemas: serializeOperationSchemas(item.handler)
+        }, normalizedRequestId);
+        const operationId = `${normalizedRequestId}:${item.name}`;
+        const contract = {
+            requestId: normalizedRequestId,
+            operationVersion: normalizedOperationVersion,
+            schemaHash,
+            method: httpMethod,
             routePath: item.routePath,
+            operationId,
+            handlerName: item.name,
             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;
-        });
+        };
+        contracts[`${httpMethod}:${item.routePath}`] = contract;
+        contracts[`operation:${operationId}`] = contract;
     });
     return contracts;
 };
-export { DEFAULT_OPERATION_VERSION, buildOperationContractMap, createOperationEntries, createOperationSchemaHash };
+export { DEFAULT_OPERATION_VERSION, buildOperationContractMap, createOperationContractHash, createOperationEntries, createOperationSchemaHash, deriveOperationVersion, serializeOperationSchemas };

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

@@ -0,0 +1,28 @@
+import "node:module";
+import { buildOperationContractMap } from "./operationContracts.mjs";
+const resolveCrossProjectPolicy = (input)=>{
+    const { crossProjectPolicy, handlers, requestId, isCrossProjectServer, operationVersion } = input;
+    if (!crossProjectPolicy && !isCrossProjectServer) return;
+    const policy = crossProjectPolicy ?? {};
+    const effectiveRequestId = 'string' == typeof requestId && requestId.trim().length > 0 ? requestId : 'default';
+    const generatedContracts = buildOperationContractMap({
+        handlers,
+        requestId: effectiveRequestId,
+        operationVersion
+    });
+    return {
+        ...policy,
+        enabled: policy.enabled ?? Boolean(isCrossProjectServer),
+        requireEnvelope: policy.requireEnvelope ?? true,
+        requireOperationContext: policy.requireOperationContext ?? true,
+        requireOperationContextDetails: policy.requireOperationContextDetails ?? true,
+        requireOperationSchemaHash: policy.requireOperationSchemaHash ?? true,
+        requireOperationVersion: policy.requireOperationVersion ?? true,
+        allowUnknownOperations: policy.allowUnknownOperations ?? false,
+        expectedOperationContracts: {
+            ...policy.expectedOperationContracts ?? {},
+            ...generatedContracts
+        }
+    };
+};
+export { resolveCrossProjectPolicy };

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

@@ -0,0 +1,90 @@
+import 'reflect-metadata';
+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. */
+export type ApiRouteMethod = Lowercase<`${HttpMethod}`>;
+/**
+ * Maps an `APIHandlerInfo.httpMethod` onto the lowercase router method.
+ * Unknown methods fail fast with a descriptive error instead of the
+ * `app[method] is not a function` TypeError the adapters used to throw.
+ */
+export declare const toApiRouteMethod: (httpMethod: APIHandlerInfo['httpMethod']) => ApiRouteMethod;
+/** Route middlewares attached by BFF operators via reflect metadata. */
+export declare const getRouteMiddlewares: <Middleware = unknown>(handler: ApiHandler) => Middleware[];
+export type ApiRoutePlanEntry<Middleware = unknown> = {
+    method: ApiRouteMethod;
+    routePath: string;
+    handler: ApiHandler;
+    middlewares: Middleware[];
+};
+/**
+ * Computes the framework-agnostic registration plan for a set of API
+ * handlers: registration order, lowercase route method and operator
+ * middlewares. Adapters only translate each entry into framework calls.
+ */
+export declare const planApiRoutes: <Middleware = unknown>(handlerInfos: APIHandlerInfo[]) => ApiRoutePlanEntry<Middleware>[];
+/**
+ * Marker used by `@modern-js/bff-runtime` schema handlers. Re-declared here
+ * (value-compatible) so adapters do not need a runtime dependency on
+ * `@modern-js/bff-runtime` just to detect the handler mode.
+ */
+export declare const HANDLER_WITH_SCHEMA = "HANDLER_WITH_SCHEMA";
+export declare const isSchemaApiHandler: (handler: unknown) => boolean;
+export type ApiHandlerMode = 'meta' | 'schema' | 'inputParamsDecider' | 'plain';
+/**
+ * Detects how an API handler expects to be invoked. The probe order (meta →
+ * schema → input-params-decider → plain) is shared by every adapter.
+ *
+ * Adapters call this once at route-registration time, not per request:
+ * meta/schema markers are attached by decorators at module load, so a handler
+ * marked after registration would not be picked up.
+ */
+export declare const getApiHandlerMode: (handler: ApiHandler) => ApiHandlerMode;
+/** Result envelope produced by `@modern-js/bff-runtime` schema handlers. */
+export type SchemaHandlerResult = {
+    type: 'HandleSuccess';
+    value: unknown;
+} | {
+    type: 'InputValidationError' | 'OutputValidationError';
+    message: unknown;
+};
+export type SchemaHandlerHttpOutcome = {
+    success: boolean;
+    status: number;
+    body: unknown;
+};
+/**
+ * Maps a schema-handler result onto the HTTP outcome both adapters must
+ * produce: 200/value on success, 400/message on input validation errors and
+ * 500/message for any other failure.
+ */
+export declare const mapSchemaHandlerResult: (result: SchemaHandlerResult) => SchemaHandlerHttpOutcome;
+/**
+ * Reads the response metadata (headers/redirect/status) attached to a meta
+ * handler. Returns an empty list when no metadata is present so adapters can
+ * iterate unconditionally.
+ */
+export declare const getResponseMetaList: (handler: ApiHandler) => ResponseMeta[];
+export type ApiHandlerInput = {
+    params: Record<string, unknown>;
+} & Record<string, unknown>;
+/**
+ * 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 type CrossProjectPolicyDenial = {
+    status: number;
+    body: {
+        code: CrossProjectPolicyViolation['code'];
+        reason: CrossProjectPolicyViolation['reason'];
+        message: string;
+    };
+};
+/**
+ * Evaluates the cross-project policy for a request and, on violation,
+ * returns the exact HTTP status and JSON body every adapter must send.
+ */
+export declare const checkCrossProjectPolicy: (headers: Record<string, unknown>, policy: CrossProjectPolicyConfig | undefined) => CrossProjectPolicyDenial | null;

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

@@ -0,0 +1,102 @@
+import type { APIHandlerInfo } from '../router';
+import type { CrossProjectPolicyViolationReason } from '../security/crossProjectPolicy';
+/**
+ * Adapter parity (conformance) kit.
+ *
+ * One shared table of scenarios executed against every BFF server adapter
+ * in its own test harness. Each scenario asserts the adapters produce
+ * identical observable results: HTTP status, payload value and
+ * policy-rejection reason.
+ *
+ * The express/koa adapters were removed from the fork, and this is internal
+ * test support rather than a package subpath. Their expectations are retained
+ * in the per-adapter drift pins as documentation of the historical behavior.
+ * The live executable consumer of this table is the hono lane test
+ * (`@modern-js/plugin-bff` runs it against `createHonoRoutes` plus the
+ * cross-project policy middleware), while bff-core tests validate the table
+ * shape and assertion helpers.
+ *
+ * Transport details intentionally NOT asserted: express serialized scalar
+ * bodies as JSON while koa sent `text/plain`; {@link toParityResult}
+ * normalizes both to the decoded payload value before comparison.
+ *
+ * Intentionally OUT OF SCOPE (known, accepted adapter drift — do not add
+ * scenarios without deciding the drift first):
+ * - operator route-middlewares: express applied them, koa ignored them;
+ * - multipart/form-data: payload shapes differ per body parser;
+ * - undefined-returning plain handlers are pinned via a per-adapter
+ *   scenario below: express ended the response 200/empty, koa served its
+ *   stock 404 ("Not Found"), hono serves its stock "404 Not Found";
+ * - farrow schema-mode handlers are pinned per-adapter below: express/koa
+ *   unwrapped the result envelope (200/400/500), the hono lane has no
+ *   schema-mode unwrapping and passes the raw envelope through.
+ */
+export declare const PARITY_REQUEST_ID = "crm";
+export declare const PARITY_PRODUCER_REQUEST_ID = "crm.producer-a";
+/**
+ * Handler fixtures registered in both adapters before running the table.
+ */
+export declare const createParityApiHandlerInfos: () => APIHandlerInfo[];
+/**
+ * `bff` config slice for the policy-enabled parity server. All `require*`
+ * switches stay at their strict defaults.
+ */
+export declare const createParityBffConfig: () => {
+    requestId: string;
+    crossProjectPolicy: {
+        enabled: boolean;
+        allowedNamespaces: string[];
+    };
+};
+export type ParityAdapterId = 'express' | 'koa' | 'hono';
+export type ParityExpectation = {
+    kind: 'payload';
+    status: number;
+    payload: unknown;
+} | {
+    kind: 'denied';
+    status: number;
+    reason: CrossProjectPolicyViolationReason;
+} | {
+    /** Pinned, intentional adapter drift: each adapter has its own expectation. */
+    kind: 'perAdapter';
+    expectations: Record<ParityAdapterId, {
+        status: number;
+        payload: unknown;
+    }>;
+};
+export type AdapterParityScenario = {
+    name: string;
+    /** Run against the policy-enabled server instead of the open one. */
+    policy: boolean;
+    request: {
+        method: 'get' | 'post' | 'patch';
+        path: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    expected: ParityExpectation;
+};
+export declare const createAdapterParityScenarios: () => AdapterParityScenario[];
+/** Structural slice of a supertest response used for normalization. */
+export type ParityHttpResponse = {
+    status: number;
+    /** Content-type mime, e.g. `application/json`. */
+    type: string;
+    body: unknown;
+    text: string;
+};
+export type AdapterParityResult = {
+    status: number;
+    payload: unknown;
+};
+/**
+ * Normalizes a raw HTTP response to the observable payload value so JSON
+ * (express) and text (koa) encodings of the same scalar compare equal.
+ */
+export declare const toParityResult: (res: ParityHttpResponse) => AdapterParityResult;
+/**
+ * Framework-agnostic assertion: throws a descriptive error when the adapter
+ * response deviates from the scenario expectation.
+ */
+export declare const assertParityResult: (scenario: AdapterParityScenario, res: ParityHttpResponse, adapter?: ParityAdapterId) => void;

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './adapter-kit';
 export { Api } from './api';
 export * from './client';
 export type * from './compatible';
@@ -7,5 +8,6 @@ export * from './operators/http';
 export * from './router';
 export * from './security/crossProjectPolicy';
 export * from './security/operationContracts';
+export * from './security/resolveCrossProjectPolicy';
 export * from './types';
 export { createStorage, getRelativeRuntimePath, HANDLER_WITH_META, INPUT_PARAMS_DECIDER, isInputParamsDeciderHandler, isWithMetaHandler, registerPaths, } from './utils';

package/dist/types/security/crossProjectPolicy.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Cross-project BFF policy evaluator.
+ *
+ * THREAT MODEL — read before relying on this module:
+ *
+ * Every header this evaluator inspects (envelope, operation id, operation
+ * context details) is constructed by the CLIENT from public, open-source
+ * formats. Without an out-of-band identity binding the checks below are a
+ * version-skew and misconfiguration gate, not an authentication or
+ * authorization boundary: any caller can echo an allowed `requestId` and a
+ * matching operation context.
+ *
+ * To turn `allowedNamespaces` into a real control, supply
+ * {@link CrossProjectPolicyConfig.verifyProducerIdentity}: a server-side
+ * hook that derives the producer namespace from a VERIFIED channel (mTLS
+ * peer identity, gateway-authenticated JWT claims, service-mesh headers
+ * stripped at the edge, ...). When the hook is present, the client-asserted
+ * namespace must match the verified namespace and the allowlist is checked
+ * against the verified value — the envelope is no longer trusted for the
+ * authorization decision.
+ *
+ * Client-side counterparts in `@modern-js/create-request` (identity binding,
+ * operation contract validation) are developer-experience aids that fail
+ * fast in well-behaved clients; they protect nothing against a malicious
+ * caller.
+ */
 export declare const BFF_ENVELOPE_HEADER = "x-modernjs-bff-envelope";
 export declare const BFF_OPERATION_CONTEXT_HEADER = "x-operation-id";
 export declare const BFF_OPERATION_CONTEXT_DETAIL_HEADER = "x-modernjs-bff-operation-context";
@@ -5,7 +31,7 @@ export type CrossProjectOperationContract = {
     schemaHash?: string;
     operationVersion?: number;
 };
-export type CrossProjectPolicyViolationReason = 'missing_envelope' | 'invalid_envelope' | 'missing_request_id' | 'namespace_not_allowed' | 'missing_operation_context' | 'operation_context_mismatch' | 'missing_operation_context_details' | 'invalid_operation_context_details' | 'operation_context_details_request_id_mismatch' | 'missing_operation_schema_hash' | 'missing_operation_version' | 'unknown_operation_contract' | 'operation_schema_hash_mismatch' | 'operation_version_mismatch';
+export type CrossProjectPolicyViolationReason = 'missing_envelope' | 'invalid_envelope' | 'missing_request_id' | 'namespace_not_allowed' | 'missing_operation_context' | 'operation_context_mismatch' | 'missing_operation_context_details' | 'invalid_operation_context_details' | 'operation_context_details_request_id_mismatch' | 'missing_operation_schema_hash' | 'missing_operation_version' | 'unknown_operation_contract' | 'operation_schema_hash_mismatch' | 'operation_version_mismatch' | 'producer_identity_mismatch';
 export type CrossProjectPolicyViolation = {
     code: 'BFF_CROSS_PROJECT_POLICY_DENIED';
     reason: CrossProjectPolicyViolationReason;
@@ -26,5 +52,18 @@ export interface CrossProjectPolicyConfig {
     expectedOperationContracts?: Record<string, CrossProjectOperationContract>;
     allowUnknownOperations?: boolean;
     denyStatus?: number;
+    /**
+     * Server-side hook binding the producer namespace to a VERIFIED identity
+     * channel (mTLS peer, gateway-authenticated JWT, mesh identity headers).
+     *
+     * When provided, the namespace asserted by the client envelope must match
+     * the namespace returned by this hook, and `allowedNamespaces` is checked
+     * against the verified value instead of the client-asserted one. Returning
+     * `undefined` (identity could not be verified) denies the request.
+     *
+     * Without this hook the namespace checks are advisory only — see the
+     * module-level threat model.
+     */
+    verifyProducerIdentity?: (headers: Record<string, unknown>) => string | undefined;
 }
 export declare const evaluateCrossProjectPolicy: (headers: Record<string, unknown>, policy?: CrossProjectPolicyConfig) => CrossProjectPolicyViolation | null;

package/dist/types/security/operationContracts.d.ts

@@ -1,4 +1,5 @@
-import type { APIHandlerInfo } from '../router/types';
+import 'reflect-metadata';
+import type { ApiHandler } from '../router/types';
 export type OperationContractEntry = {
     name: string;
     httpMethod: string;
@@ -16,13 +17,68 @@ export type OperationContractDefinition = {
 };
 export type OperationContractMap = Record<string, OperationContractDefinition>;
 export declare const DEFAULT_OPERATION_VERSION = 1;
+/**
+ * Derives the operation version from a producer package version: the semver
+ * major is the contract version, so consumers regenerated against an older
+ * producer major fail the `operation_version_mismatch` gate instead of
+ * silently calling an incompatible API.
+ *
+ * Falls back to {@link DEFAULT_OPERATION_VERSION} when no parseable version
+ * is available.
+ */
+export declare const deriveOperationVersion: (packageVersion?: unknown) => number;
+/**
+ * Serializes the zod input schemas attached to an operator-decorated handler
+ * (`Data`/`Query`/`Params`/`Headers`/`Upload` metadata) into JSON-schema
+ * documents. Returns `undefined` for handlers without schema metadata
+ * (plain handlers, farrow schema-mode handlers).
+ */
+export declare const serializeOperationSchemas: (handler: ApiHandler | undefined) => Record<string, unknown> | undefined;
+export type OperationContractHashInput = OperationContractEntry & {
+    /** Serialized schema documents; omit for schema-less operations. */
+    schemas?: Record<string, unknown> | undefined;
+};
+/**
+ * Per-operation contract hash. The hash covers the operation identity
+ * (name, method, route, producer requestId) plus the serialized input
+ * schemas, so:
+ *
+ * - changing an input schema changes the hash of exactly that operation;
+ * - reordering routes or adding unrelated operations never rotates the hash
+ *   of other operations (each operation is hashed independently).
+ */
+export declare const createOperationContractHash: (operation: OperationContractHashInput, requestId: string) => string;
 export declare const createOperationEntries: (handlers: Array<{
     name: string;
     httpMethod: string;
     routePath: string;
 }>) => OperationContractEntry[];
-export declare const createOperationSchemaHash: (operationEntries: OperationContractEntry[], requestId: string) => string;
-export declare const buildOperationContractMap: ({ handlers, requestId, }: {
-    handlers: APIHandlerInfo[];
+/**
+ * Aggregate hash over a set of per-operation contract hashes. Used for the
+ * module-level `operationSchemaHash` manifest export; stable across route
+ * reordering because the per-operation hashes are sorted before hashing.
+ */
+export declare const createOperationSchemaHash: (operationEntries: Array<OperationContractEntry & {
+    schemaHash?: string;
+}>, requestId: string) => string;
+export type OperationContractSource = {
+    name: string;
+    httpMethod: string;
+    routePath: string;
+    filename?: string;
+    /**
+     * Optional handler function used to serialize schema metadata. Sources
+     * without a handler (e.g. reflected Effect HttpApi endpoints) hash the
+     * route identity only.
+     */
+    handler?: ApiHandler;
+};
+export declare const buildOperationContractMap: ({ handlers, requestId, operationVersion, }: {
+    handlers: OperationContractSource[];
     requestId?: string;
+    /**
+     * Producer contract version, usually `deriveOperationVersion(pkg.version)`.
+     * Defaults to {@link DEFAULT_OPERATION_VERSION}.
+     */
+    operationVersion?: number;
 }) => OperationContractMap;

package/dist/types/security/resolveCrossProjectPolicy.d.ts

@@ -0,0 +1,48 @@
+import type { CrossProjectOperationContract, CrossProjectPolicyConfig } from './crossProjectPolicy';
+import { type OperationContractSource } from './operationContracts';
+/**
+ * Runtime input collected by BFF server adapters (hono/effect/...) before
+ * the cross-project policy can be enforced.
+ *
+ * `crossProjectPolicy` accepts the raw `bff.crossProjectPolicy` user config —
+ * `BffCrossProjectPolicyUserConfig` is a structural subset of
+ * `CrossProjectPolicyConfig`, so no casts are required at the call site.
+ */
+export interface ResolveCrossProjectPolicyInput {
+    crossProjectPolicy?: CrossProjectPolicyConfig;
+    /** Registered API handlers used to derive the operation-contract map. */
+    handlers: OperationContractSource[];
+    /** Logical producer ID (`bff.requestId`). */
+    requestId?: string;
+    /** Marker injected by generated cross-project SDK plugins. */
+    isCrossProjectServer?: boolean;
+    /**
+     * Producer contract version (usually derived from the producer
+     * package.json major via `deriveOperationVersion`).
+     */
+    operationVersion?: number;
+}
+/**
+ * Fully-defaulted policy returned by {@link resolveCrossProjectPolicy}.
+ */
+export type ResolvedCrossProjectPolicy = CrossProjectPolicyConfig & {
+    enabled: boolean;
+    requireEnvelope: boolean;
+    requireOperationContext: boolean;
+    requireOperationContextDetails: boolean;
+    requireOperationSchemaHash: boolean;
+    requireOperationVersion: boolean;
+    allowUnknownOperations: boolean;
+    expectedOperationContracts: Record<string, CrossProjectOperationContract>;
+};
+/**
+ * Normalizes the user-facing cross-project policy config into the evaluator
+ * input shared by every BFF server adapter:
+ *
+ * - returns `undefined` when neither a policy nor the cross-project server
+ *   marker is present (policy middleware must not be installed);
+ * - applies the documented defaults for all `require*` switches;
+ * - merges generated operation contracts (derived from the registered
+ *   handlers) over any user-provided `expectedOperationContracts`.
+ */
+export declare const resolveCrossProjectPolicy: (input: ResolveCrossProjectPolicyInput) => ResolvedCrossProjectPolicy | undefined;

package/package.json

@@ -17,12 +17,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.12",
+  "version": "3.2.0-ultramodern.121",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
+      "modern:source": "./src/index.ts",
       "node": {
         "import": "./dist/esm-node/index.mjs",
         "require": "./dist/cjs/index.js"
@@ -31,21 +32,22 @@
     }
   },
   "dependencies": {
-    "@swc/helpers": "^0.5.21",
+    "@swc/helpers": "^0.5.23",
     "koa-compose": "^4.1.0",
     "reflect-metadata": "^0.2.2",
-    "type-fest": "5.6.0",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.12"
+    "type-fest": "5.7.0",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.121"
   },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
+    "@rslib/core": "0.22.0",
     "@types/koa-compose": "^3.2.9",
-    "@types/node": "^25.8.0",
-    "@typescript/native-preview": "7.0.0-dev.20260516.1",
+    "@types/node": "^25.9.3",
+    "@typescript/native-preview": "7.0.0-dev.20260610.1",
     "tsconfig-paths": "^4.2.0",
     "zod": "^4.4.3",
-    "@scripts/rstest-config": "2.66.0",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.12"
+    "@modern-js/bff-runtime": "npm:@bleedingdev/modern-js-bff-runtime@3.2.0-ultramodern.121",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.121",
+    "@scripts/rstest-config": "2.66.0"
   },
   "peerDependencies": {
     "tsconfig-paths": "^4.2.0",
@@ -62,7 +64,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build",
+    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\"",
     "test": "rstest --passWithNoTests"
   }
 }