/**
 * HTTP transport for mailpouch (remote / self-host mode).
 *
 * Spec reference: https://modelcontextprotocol.io/specification/2025-11-25
 *
 * Auth supports two modes that can be mixed on the same listener:
 *
 *   1. **Static bearer token** — programmatic use. The user configures
 *      `remoteBearerToken` in the settings file and clients present it
 *      as `Authorization: Bearer <token>`. This is the minimal deployment
 *      (me-on-my-phone talking to my laptop's Bridge over a trusted
 *      tunnel). Token is compared with timingSafeEqual.
 *
 *   2. **OAuth 2.1 + PKCE** — spec-compliant mode. When `oauthEnabled`
 *      is true the server also mounts the RFC 8414 authorization-server
 *      metadata, RFC 9728 protected-resource metadata, RFC 7591 Dynamic
 *      Client Registration endpoint, and the authorize/token/revoke
 *      endpoints. MCP hosts register themselves and obtain tokens via a
 *      human-in-the-loop consent screen gated on the admin password.
 *
 * Every unauthenticated path is rate-limited per IP. The authed /mcp
 * endpoint is rate-limited per token key so a compromised token can't
 * DoS Bridge.
 *
 * Requests without a valid credential get 401 with a `WWW-Authenticate`
 * header per RFC 6750.
 */
import { type IncomingMessage } from "http";
import type { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
import type { AgentGrantStore } from "../agents/grant-store.js";
export interface HttpTransportOptions {
    /** MCP server instance to wire the transport into. */
    server: McpServer;
    /** Bind host. Default 127.0.0.1 (localhost-only). Use 0.0.0.0 for LAN exposure. */
    host?: string;
    /** Port to listen on. */
    port: number;
    /** Shared bearer token the client must send in Authorization: Bearer ... */
    bearerToken: string;
    /** Path where the MCP endpoint lives. Default /mcp. */
    path?: string;
    /** Optional TLS cert/key paths for HTTPS. If omitted, serves over plain HTTP. */
    tlsCertPath?: string;
    tlsKeyPath?: string;
    /** Enable OAuth 2.1 authorization-server endpoints alongside the static bearer. */
    oauthEnabled?: boolean;
    /** Admin password required to complete the consent step. Required when oauthEnabled=true. */
    oauthAdminPassword?: string;
    /** Externally-visible issuer URL. When omitted we derive it from the bind host/port. */
    oauthIssuer?: string;
    /** Requests per second per client for rate limiting (default 20). */
    rateLimitPerSecond?: number;
    /** Burst size (default 40). */
    rateLimitBurst?: number;
    /**
     * Optional grant store to wire into DCR + authed tool calls. When set,
     * each new DCR client gets a pending AgentGrant, and the caller-context
     * dispatched to the MCP handler carries the client_id so the tool
     * dispatcher can consult per-agent permissions. When omitted, the
     * transport behaves as before (bearer-only, no per-agent gating).
     */
    agentGrants?: AgentGrantStore;
}
export interface HttpTransportHandle {
    /** URL of the MCP endpoint (http[s]://host:port/mcp). */
    url: string;
    /** OAuth issuer URL, present when OAuth is enabled. */
    issuer?: string;
    /** Stop accepting new connections and close existing ones. */
    close: () => Promise<void>;
}
/**
 * Return the caller IP. Trusts `X-Forwarded-For` ONLY when the direct
 * peer is loopback — matches the comment in oauth-handlers.ts and makes
 * the `ipPins` grant condition usable behind a local reverse proxy
 * (Caddy, nginx, Cloudflare Tunnel).
 *
 * XFF is comma-separated "client, proxy1, proxy2, …"; we take the
 * left-most token (the original client). When any parse step fails or
 * the direct peer is not loopback, fall back to the socket address —
 * never fail open to an attacker-controlled header.
 */
export declare function clientIp(req: IncomingMessage): string;
/**
 * Start the HTTP MCP server. Resolves to a handle you can close on shutdown.
 */
export declare function startHttpTransport(opts: HttpTransportOptions): Promise<HttpTransportHandle>;
//# sourceMappingURL=http.d.ts.map