@beignet/core/dist/server/trusted-proxy.d.ts

Core framework primitives for Beignet

import type { HttpRequestLike } from "./http.js";
/**
 * Header source used to resolve a client IP after an app has explicitly opted
 * into trusting its deployment proxy or edge.
 */
export type TrustedProxyClientIpSource = "x-forwarded-for-last" | "x-forwarded-for-first" | "x-real-ip" | "cf-connecting-ip" | {
    header: string;
} | ((req: HttpRequestLike) => string | undefined);
/**
 * Trusted proxy configuration for request metadata.
 *
 * Beignet trusts no forwarding headers by default. Configure this only when
 * the app is always behind a platform or reverse proxy that strips or
 * normalizes these headers before they reach application code.
 */
export interface TrustedProxyOptions {
    /**
     * Header source for the end-user client IP. Omit or set to `false` when no
     * client-IP header should be trusted.
     */
    clientIp?: TrustedProxyClientIpSource | false;
    /**
     * Header that carries the external request protocol.
     *
     * Defaults to `x-forwarded-proto` when trusted proxy handling is enabled.
     */
    protocolHeader?: string | false;
    /**
     * Header that carries the external request host.
     *
     * Defaults to `x-forwarded-host` when trusted proxy handling is enabled.
     */
    hostHeader?: string | false;
}
/**
 * Set to `false` or omit the config to trust no forwarding headers.
 */
export type TrustedProxyConfig = false | TrustedProxyOptions;
/**
 * Request metadata after applying an explicit trusted-proxy policy.
 */
export interface TrustedRequestInfo {
    /**
     * URL as seen by the app or reconstructed from trusted proxy headers.
     */
    readonly url: Readonly<URL>;
    /**
     * External request origin.
     */
    readonly origin: string;
    /**
     * External request protocol without a trailing colon.
     */
    readonly protocol: "http" | "https";
    /**
     * External request host, including port when present.
     */
    readonly host: string;
    /**
     * Resolved client IP when a trusted client-IP source is configured.
     */
    readonly clientIp?: string;
    /**
     * Whether the server policy configured a trusted client-IP source. This can
     * be true while `clientIp` is absent when the expected header is missing.
     */
    readonly clientIpTrusted: boolean;
    /**
     * Whether forwarding headers were eligible to affect this result.
     */
    readonly trustedProxy: boolean;
}
/**
 * Resolve a client IP from a configured trusted proxy source.
 */
export declare function resolveTrustedClientIp(req: HttpRequestLike, source: TrustedProxyClientIpSource | false | undefined): string | undefined;
/**
 * Resolve request metadata using only app-visible URL data unless a trusted
 * proxy policy is explicitly configured.
 */
export declare function resolveTrustedRequest(req: HttpRequestLike, config?: TrustedProxyConfig | undefined): TrustedRequestInfo;
//# sourceMappingURL=trusted-proxy.d.ts.map