/**
 * Proxy-layer verification of internal control-plane / dispatch signatures.
 *
 * The proxy grants two privileges to "internal control-plane" requests before
 * they reach the renderer:
 *
 *   1. they bypass the protected-environment user-auth gate
 *      (`checkProtectedProxyAccess`), and
 *   2. their caller-supplied `x-token` is forwarded as the upstream API bearer
 *      token (`resolveProxyRequestToken`).
 *
 * Both privileges MUST be gated on a cryptographically valid signature, never
 * on mere header presence. The proxy sits at the trust boundary: any external
 * client that can reach it could otherwise set an arbitrary `x-veryfront-*-jws`
 * value and unlock the bypass and token injection for a protected environment.
 *
 * The proxy binds that trust to an exact downstream-verified method/path pair,
 * the project audience, and (once metadata is resolved) the project id. It does
 * not consume the body: authoritative body-hash verification still runs in the
 * renderer. Signature headers remain available to that downstream verifier.
 *
 * Rejections are logged with a reason so a turned-away internal caller can be
 * diagnosed from one line. The reason is never returned to the client, and
 * anonymous traffic that presented no signature header is not logged at all.
 *
 * @module proxy/control-plane-signature
 */
export interface InternalControlPlaneSignatureLogger {
    warn: (msg: string, extra?: Record<string, unknown>) => void;
}
/** Header names that may carry a control-plane / dispatch signature. */
export declare const INTERNAL_CONTROL_PLANE_SIGNATURE_HEADERS: readonly ["x-veryfront-control-plane-jws", "x-veryfront-dispatch-jws"];
export type InternalControlPlaneRouteKind = "dispatch" | "control-plane" | "reserved" | "public";
/**
 * Classify the internal namespace against routes whose handlers always perform
 * authoritative downstream JWS verification.
 *
 * `control-plane` and `reserved` differ in exactly the way that matters to a
 * caller deciding what to trust: `control-plane` names a route the runtime
 * serves through a verifying handler, `reserved` names the rest of the
 * namespace, which a project can occupy with its own routes.
 */
export declare function classifyInternalControlPlaneRequest(method: string, pathname: string): InternalControlPlaneRouteKind;
export interface InternalControlPlaneProjectBinding {
    audience: string;
    expectedProjectId?: string;
}
export interface VerifiedControlPlaneBranchBinding {
    branchId?: string;
    branchName?: string;
    defaultBranchName?: string;
}
export declare class ControlPlaneBranchBindingError extends Error {
    readonly status: 400 | 401 | 413;
    constructor(status: 400 | 401 | 413, message: string);
}
/**
 * Resolve branch identity only from a body-bound control-plane signature.
 * Caller-provided branch headers are never consulted.
 */
export declare function resolveVerifiedControlPlaneBranchBinding(req: Request, url: URL, binding: InternalControlPlaneProjectBinding): Promise<VerifiedControlPlaneBranchBinding | undefined>;
/**
 * Why a signed-internal check did not admit the request.
 *
 * "reserved" routes are internal but never admissible, so they share the silent
 * `route_not_admissible` reason with ordinary public traffic.
 */
export type InternalControlPlaneRejection = "route_not_admissible" | "missing_x_token" | "verification_key_not_configured" | "missing_signature_header" | "signature_rejected";
/**
 * Authenticate a signed internal request before a custom domain has resolved
 * to its project audience.
 *
 * This result may authorize only the project-metadata lookup needed to resolve
 * that audience. The caller must re-verify with
 * {@link isVerifiedInternalControlPlaneRequest} and the resolved project slug
 * and id before bypassing user authentication or forwarding the inbound token.
 */
export declare function isAuthenticInternalControlPlaneCandidate(req: Request, url: URL, logger?: InternalControlPlaneSignatureLogger): Promise<boolean>;
/**
 * Returns true only for internal control-plane paths carrying a caller `x-token`
 * plus a cryptographically valid, fresh control-plane/dispatch signature.
 *
 * Fails closed: an unconfigured verification key, a missing `x-token`, a
 * non-control-plane path, or an invalid/expired signature all return false.
 */
export declare function isVerifiedInternalControlPlaneRequest(req: Request, url: URL, binding: InternalControlPlaneProjectBinding, logger?: InternalControlPlaneSignatureLogger): Promise<boolean>;
//# sourceMappingURL=control-plane-signature.d.ts.map