@bleedingdev/modern-js-bff-core 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

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

@@ -1,110 +0,0 @@
-/**
- * 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 use `allowedNamespaces`, 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, ...). Requests fail closed when a namespace allowlist
- * is configured without this hook unless `allowClientAssertedNamespace` is
- * explicitly enabled. That escape hatch keeps legacy local/demo ergonomics:
- * the client-asserted namespace must match the allowlist. When the hook is
- * present, the client-asserted namespace must match the verified namespace
- * and the allowlist is checked against the verified value.
- *
- * 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";
-export type CrossProjectOperationContract = {
-    schemaHash?: string;
-    operationVersion?: number;
-    operationId?: string;
-};
-/**
- * Request facts observed by the server adapter rather than asserted by the
- * client. `routePath` is the matched route template when the router exposes
- * one (for example `/api/customers/:id`), not the client-provided detail.
- */
-export type CrossProjectRequestObservation = {
-    method: string;
-    routePath: string;
-};
-export type CrossProjectRequestTarget = {
-    method: string;
-    pathname: string;
-};
-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;
-    message: string;
-    status: number;
-};
-export interface CrossProjectPolicyConfig {
-    enabled?: boolean;
-    requireEnvelope?: boolean;
-    requireOperationContext?: boolean;
-    requireOperationContextDetails?: boolean;
-    requireOperationSchemaHash?: boolean;
-    requireOperationVersion?: boolean;
-    allowedNamespaces?: string[];
-    /**
-     * Explicit local/demo escape hatch for legacy clients that only provide
-     * client-built requestId namespaces. Defaults to false. Enabling this keeps
-     * `allowedNamespaces` advisory and must not be used as authorization.
-     */
-    allowClientAssertedNamespace?: boolean;
-    envelopeHeader?: string;
-    operationContextHeader?: string;
-    operationContextDetailHeader?: string;
-    expectedOperationContracts?: Record<string, CrossProjectOperationContract>;
-    allowUnknownOperations?: boolean;
-    denyStatus?: number;
-    /**
-     * Server-side hook binding producer namespace to 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.
-     *
-     * By default, `allowedNamespaces` requires this hook and fails closed
-     * without it. Set `allowClientAssertedNamespace` only for local/demo
-     * ergonomics where advisory client-asserted namespace checks are acceptable.
-     */
-    verifyProducerIdentity?: (headers: Record<string, unknown>) => string | undefined;
-}
-/** Serializable, fully-defaulted policy accepted by edge dispatchers. */
-export type NormalizedCrossProjectPolicy = CrossProjectPolicyConfig & {
-    enabled: boolean;
-    requireEnvelope: boolean;
-    requireOperationContext: boolean;
-    requireOperationContextDetails: boolean;
-    requireOperationSchemaHash: boolean;
-    requireOperationVersion: boolean;
-    allowUnknownOperations: boolean;
-    expectedOperationContracts: Record<string, CrossProjectOperationContract>;
-};
-/**
- * Resolves a concrete adapter request to the server-owned route template in
- * the operation contract map. Effect receives requests after its BFF mount
- * prefix has been stripped, so leading literal route segments may be mount
- * prefixes. Ambiguous matches fail closed by retaining the concrete path.
- */
-export declare const resolveCrossProjectRequestObservation: (request: CrossProjectRequestTarget, policy: Pick<CrossProjectPolicyConfig, 'expectedOperationContracts'>) => CrossProjectRequestObservation | undefined;
-export declare const evaluateCrossProjectPolicy: (headers: Record<string, unknown>, policy?: CrossProjectPolicyConfig, observedRequest?: CrossProjectRequestObservation) => CrossProjectPolicyViolation | null;

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

@@ -1,84 +0,0 @@
-import 'reflect-metadata';
-import type { ApiHandler } from '../router/types.js';
-export type OperationContractEntry = {
-    name: string;
-    httpMethod: string;
-    routePath: string;
-};
-export type OperationContractDefinition = {
-    requestId: string;
-    operationVersion: number;
-    schemaHash: string;
-    method: string;
-    routePath: string;
-    operationId: string;
-    handlerName: string;
-    filename?: string;
-};
-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[];
-/**
- * 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

@@ -1,39 +0,0 @@
-import type { CrossProjectPolicyConfig, NormalizedCrossProjectPolicy } from './crossProjectPolicy.js';
-import { type OperationContractSource } from './operationContracts.js';
-/**
- * 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 = NormalizedCrossProjectPolicy;
-/**
- * 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/dist/types/utils/alias.d.ts

@@ -1,7 +0,0 @@
-interface Paths {
-    [key: string]: string[] | string;
-}
-export declare const getRelativeRuntimePath: (appDirectory: string, serverRuntimePath: string) => string;
-export declare const createMatchPath: (paths: Paths) => (request: string) => string | null;
-export declare const registerPaths: (paths: Paths) => () => void;
-export {};