@corsenai/corsen-context 1.2.0

package/dist/index.d.mts

@@ -0,0 +1,797 @@
+import pino from 'pino';
+import { z } from 'zod';
+
+interface SitemapEntry {
+    url: string;
+    lastmod?: string;
+    changefreq?: string;
+    priority?: number;
+    title?: string;
+}
+interface PageContent {
+    url: string;
+    title: string;
+    description: string;
+    markdown: string;
+    lastModified?: string;
+    metadata: Record<string, string>;
+}
+interface SearchResult {
+    url: string;
+    title: string;
+    description: string;
+    snippet: string;
+    score: number;
+}
+interface ContentListItem {
+    url: string;
+    title: string;
+    description: string;
+    type: string;
+    lastModified?: string;
+}
+interface ContentList {
+    items: ContentListItem[];
+    total: number;
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}
+interface JSONRPCRequest {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number | null;
+}
+interface JSONRPCResponse {
+    jsonrpc: '2.0';
+    result?: unknown;
+    error?: JSONRPCError;
+    id: string | number | null;
+}
+interface JSONRPCError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface MCPResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+interface MCPCapabilities {
+    tools: MCPToolDefinition[];
+    resources: MCPResourceDefinition[];
+}
+interface ContentProvider {
+    getPages(): Promise<ContentListItem[]>;
+    getPageContent(url: string): Promise<PageContent | null>;
+    searchContent(query: string, limit: number): Promise<SearchResult[]>;
+}
+interface CacheDriver {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfter?: number;
+}
+interface RateLimitStore {
+    getTimestamps(key: string, windowStart: number): Promise<number[]>;
+    addTimestamp(key: string, timestamp: number): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Optional atomic prune + record + count. When present, the RateLimiter uses
+     * this instead of the getTimestamps()/addTimestamp() pair to avoid the
+     * check-then-add race. Returns counts that INCLUDE the current request.
+     */
+    hit?(key: string, windowStart: number, burstWindowStart: number, now: number): Promise<{
+        windowCount: number;
+        burstCount: number;
+    }>;
+}
+interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ex?: number;
+    } | 'EX', ttlSeconds?: number): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number | boolean>;
+    zadd(key: string, score: number, member: string): Promise<number>;
+    zremrangebyscore(key: string, min: number | string, max: number | string): Promise<number>;
+    zcard(key: string): Promise<number>;
+    zrangebyscore(key: string, min: number | string, max: number | string): Promise<string[]>;
+}
+interface ApiKeyRecord {
+    id: string;
+    name: string;
+    keyHash: string;
+    keySalt: string;
+    scopes: string[];
+    quotaPerDay: number;
+    requestsToday: number;
+    quotaResetAt: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revoked: boolean;
+}
+declare const CREDIT_LINE = "Powered by Corsen Context \u2022 Built by Corsen AI \u2022 github.com/CorsenAI/corsen-context";
+declare const JSONRPC_ERRORS: {
+    readonly PARSE_ERROR: {
+        readonly code: -32700;
+        readonly message: "Parse error";
+    };
+    readonly INVALID_REQUEST: {
+        readonly code: -32600;
+        readonly message: "Invalid Request";
+    };
+    readonly METHOD_NOT_FOUND: {
+        readonly code: -32601;
+        readonly message: "Method not found";
+    };
+    readonly INVALID_PARAMS: {
+        readonly code: -32602;
+        readonly message: "Invalid params";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly code: -32603;
+        readonly message: "Internal error";
+    };
+    readonly UNAUTHORIZED: {
+        readonly code: -32000;
+        readonly message: "Unauthorized";
+    };
+    readonly RATE_LIMITED: {
+        readonly code: -32000;
+        readonly message: "Rate limit exceeded";
+    };
+    readonly RESOURCE_NOT_FOUND: {
+        readonly code: -32002;
+        readonly message: "Resource not found";
+    };
+};
+declare const SECURITY_HEADERS: Record<string, string>;
+
+declare const corsenContextConfigSchema: z.ZodObject<{
+    siteUrl: z.ZodString;
+    siteName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    content: z.ZodDefault<z.ZodObject<{
+        postTypes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        excludePaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        maxPages: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        postTypes: string[];
+        excludePaths: string[];
+        maxPages: number;
+    }, {
+        postTypes?: string[] | undefined;
+        excludePaths?: string[] | undefined;
+        maxPages?: number | undefined;
+    }>>;
+    mcp: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        endpoint: z.ZodDefault<z.ZodString>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        endpoint: string;
+        tools: string[];
+    }, {
+        enabled?: boolean | undefined;
+        endpoint?: string | undefined;
+        tools?: string[] | undefined;
+    }>>;
+    static: z.ZodDefault<z.ZodObject<{
+        generateLlmsTxt: z.ZodDefault<z.ZodBoolean>;
+        includeFullContent: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        generateLlmsTxt: boolean;
+        includeFullContent: boolean;
+    }, {
+        generateLlmsTxt?: boolean | undefined;
+        includeFullContent?: boolean | undefined;
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
+        rateLimit: z.ZodDefault<z.ZodNumber>;
+        burstLimit: z.ZodDefault<z.ZodNumber>;
+        allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        trustProxy: z.ZodDefault<z.ZodBoolean>;
+        exposeVersion: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        rateLimit: number;
+        burstLimit: number;
+        allowedOrigins: string[];
+        trustProxy: boolean;
+        exposeVersion: boolean;
+        apiKey?: string | undefined;
+    }, {
+        rateLimit?: number | undefined;
+        burstLimit?: number | undefined;
+        allowedOrigins?: string[] | undefined;
+        apiKey?: string | undefined;
+        trustProxy?: boolean | undefined;
+        exposeVersion?: boolean | undefined;
+    }>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        ttl: z.ZodDefault<z.ZodNumber>;
+        driver: z.ZodDefault<z.ZodEnum<["memory", "redis"]>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        ttl: number;
+        driver: "memory" | "redis";
+    }, {
+        enabled?: boolean | undefined;
+        ttl?: number | undefined;
+        driver?: "memory" | "redis" | undefined;
+    }>>;
+    credit: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    siteUrl: string;
+    content: {
+        postTypes: string[];
+        excludePaths: string[];
+        maxPages: number;
+    };
+    mcp: {
+        enabled: boolean;
+        endpoint: string;
+        tools: string[];
+    };
+    static: {
+        generateLlmsTxt: boolean;
+        includeFullContent: boolean;
+    };
+    security: {
+        rateLimit: number;
+        burstLimit: number;
+        allowedOrigins: string[];
+        trustProxy: boolean;
+        exposeVersion: boolean;
+        apiKey?: string | undefined;
+    };
+    cache: {
+        enabled: boolean;
+        ttl: number;
+        driver: "memory" | "redis";
+    };
+    credit: boolean;
+    siteName?: string | undefined;
+    description?: string | undefined;
+}, {
+    siteUrl: string;
+    siteName?: string | undefined;
+    description?: string | undefined;
+    content?: {
+        postTypes?: string[] | undefined;
+        excludePaths?: string[] | undefined;
+        maxPages?: number | undefined;
+    } | undefined;
+    mcp?: {
+        enabled?: boolean | undefined;
+        endpoint?: string | undefined;
+        tools?: string[] | undefined;
+    } | undefined;
+    static?: {
+        generateLlmsTxt?: boolean | undefined;
+        includeFullContent?: boolean | undefined;
+    } | undefined;
+    security?: {
+        rateLimit?: number | undefined;
+        burstLimit?: number | undefined;
+        allowedOrigins?: string[] | undefined;
+        apiKey?: string | undefined;
+        trustProxy?: boolean | undefined;
+        exposeVersion?: boolean | undefined;
+    } | undefined;
+    cache?: {
+        enabled?: boolean | undefined;
+        ttl?: number | undefined;
+        driver?: "memory" | "redis" | undefined;
+    } | undefined;
+    credit?: boolean | undefined;
+}>;
+type CorsenContextConfig = z.input<typeof corsenContextConfigSchema>;
+type ResolvedConfig = z.output<typeof corsenContextConfigSchema>;
+declare function resolveConfig(input: CorsenContextConfig): ResolvedConfig;
+
+/** Current API version */
+declare const API_VERSION = "v1";
+/** Maximum JSON-RPC request body size in bytes (100 KB) */
+declare const MAX_BODY_SIZE: number;
+/** Maximum JSON nesting depth */
+declare const MAX_JSON_DEPTH = 10;
+/** Request timeout in milliseconds */
+declare const REQUEST_TIMEOUT_MS = 8000;
+declare class MCPServer {
+    private config;
+    private provider;
+    private rateLimiter;
+    private cache;
+    private log;
+    constructor(config: ResolvedConfig, provider: ContentProvider, options?: {
+        cache?: CacheDriver;
+        rateLimitStore?: RateLimitStore;
+        logger?: pino.Logger;
+    });
+    getSecurityHeaders(): Record<string, string>;
+    getCorsHeaders(origin?: string): Record<string, string>;
+    checkRateLimit(clientIp: string, apiKey?: string): Promise<{
+        allowed: boolean;
+        headers: Record<string, string>;
+    }>;
+    checkAuth(apiKeyHeader?: string): boolean;
+    handleRequest(body: unknown, clientIp?: string, apiKey?: string, options?: {
+        skipRateLimit?: boolean;
+    }): Promise<JSONRPCResponse | null>;
+    private dispatch;
+    private handleInitialize;
+    private handleListTools;
+    private handleCallTool;
+    /** Page size for resources/list cursor pagination. */
+    private static readonly RESOURCES_PAGE_SIZE;
+    private handleListResources;
+    private decodeCursor;
+    private handleReadResource;
+    private get cacheEnabled();
+    private cacheGet;
+    private cacheSet;
+    /**
+     * Drop the cached body for a single page URL. Call this from your CMS's
+     * publish/update/delete hooks so edits and unpublishes propagate before the
+     * TTL expires (otherwise stale content can be served for up to cache.ttl).
+     */
+    invalidatePage(url: string): Promise<void>;
+    /**
+     * Clear all cached MCP responses (search, page, list, sitemap). Call after
+     * bulk content changes. No-op for cache drivers without prefix enumeration
+     * (see RedisCache.clear notes).
+     */
+    clearCache(): Promise<void>;
+    searchSite(query: string, limit?: number): Promise<{} | undefined>;
+    getPageContent(uri: string): Promise<{} | null | undefined>;
+    listContent(type: string, page?: number, limit?: number): Promise<{} | undefined>;
+    getSitemap(): Promise<{} | undefined>;
+    getToolDefinitions(): MCPToolDefinition[];
+    getCapabilities(): MCPCapabilities;
+    private successResponse;
+    private errorResponse;
+}
+
+/**
+ * Single source of truth for version strings.
+ *
+ * Keep CORSEN_CONTEXT_VERSION in sync with each package.json `version` on release
+ * (the release tooling does this). serverInfo and the CLI both read from here so
+ * the version can never silently drift between what is published and what is
+ * reported over MCP.
+ */
+/** Corsen Context release version. */
+declare const CORSEN_CONTEXT_VERSION = "1.2.0";
+/** MCP protocol version implemented by this server. */
+declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+
+/** Structured logger type used across Corsen Context (Pino). */
+type Logger = pino.Logger;
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+interface LoggerOptions {
+    level?: LogLevel;
+    name?: string;
+    pretty?: boolean;
+}
+/**
+ * Create a structured logger for Corsen Context.
+ *
+ * Uses Pino for high-performance, JSON-based structured logging.
+ * Logs include: timestamp, level, module, and message + data fields.
+ *
+ * In production, pipe through `pino-pretty` for human-readable output:
+ *   node server.js | npx pino-pretty
+ */
+declare function createLogger(options?: LoggerOptions): pino.Logger;
+declare function getLogger(): pino.Logger;
+declare function setLogger(logger: pino.Logger): void;
+declare function securityLogger(parent?: pino.Logger): pino.Logger;
+declare function mcpLogger(parent?: pino.Logger): pino.Logger;
+
+/** A page for the in-memory provider — a PageContent plus an optional content type. */
+interface InMemoryPage extends PageContent {
+    type?: string;
+}
+/**
+ * Batteries-included provider backed by an in-memory array of pages.
+ *
+ * Ideal for static sites, markdown-file blogs, or tests: pass your pages and
+ * you get getPages/getPageContent plus a simple case-insensitive full-text
+ * search for free — no need to hand-write the ContentProvider interface.
+ */
+declare function createInMemoryProvider(pages: InMemoryPage[]): ContentProvider;
+/**
+ * Provider that fetches a live site's pages via its sitemap and converts each
+ * page to clean markdown on demand. SSRF-safe (uses safeFetch + isPrivateUrl).
+ * Search is unsupported (returns []) since there is no index to query.
+ */
+declare function createSitemapProvider(siteUrl: string, options?: {
+    maxPages?: number;
+}): ContentProvider;
+
+/** Minimal shape needed to build discovery artifacts. */
+interface DiscoveryConfig {
+    siteUrl: string;
+    /** MCP endpoint path or absolute URL. Defaults to `/v1/mcp`. */
+    mcpEndpoint?: string;
+    /** Optional sitemap URL to advertise in robots.txt. */
+    sitemapUrl?: string;
+}
+/**
+ * Build robots.txt lines that advertise the MCP endpoint (and sitemap) so AI
+ * agents can discover the site. Append these to your existing robots.txt.
+ */
+declare function generateRobotsTxt(config: DiscoveryConfig): string;
+/**
+ * Build the JSON document to serve at /.well-known/mcp — the standard MCP
+ * discovery endpoint.
+ */
+declare function generateWellKnownMcp(config: DiscoveryConfig): {
+    mcpEndpoint: string;
+    protocolVersion: string;
+    transport: string;
+};
+/** Build the `<link rel="mcp">` tag for the HTML head. */
+declare function mcpLinkTag(config: DiscoveryConfig): string;
+
+declare function generateLlmsTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
+declare function generateLlmsFullTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
+
+declare function parseSitemap(sitemapUrl: string, maxPages?: number): Promise<SitemapEntry[]>;
+declare function discoverSitemap(siteUrl: string): Promise<string | null>;
+
+declare function htmlToMarkdown(html: string): string;
+declare function extractMetadata(html: string): Record<string, string>;
+
+/**
+ * In-memory cache with TTL expiry, max size limit, and LRU eviction.
+ *
+ * - Entries expire after their TTL
+ * - When maxEntries is reached, the least-recently-accessed entry is evicted
+ * - Automatic periodic cleanup of expired entries
+ *
+ * For production multi-instance deployments, use RedisCache instead.
+ */
+declare class MemoryCache implements CacheDriver {
+    private store;
+    private maxEntries;
+    private cleanupTimer;
+    constructor(options?: {
+        maxEntries?: number;
+        autoCleanup?: boolean;
+    });
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Current number of entries */
+    get size(): number;
+    /** Stop automatic cleanup (for graceful shutdown or testing) */
+    destroy(): void;
+    /** Remove all expired entries */
+    cleanup(): void;
+    /** Evict the least-recently-accessed entry */
+    private evictLRU;
+}
+
+/**
+ * Redis-backed cache driver for distributed / multi-instance deployments.
+ * Compatible with ioredis, @upstash/redis, or any client implementing RedisClient.
+ *
+ * Usage:
+ *   import Redis from 'ioredis';
+ *   const redis = new Redis();
+ *   const cache = new RedisCache(redis);
+ *   const ctx = new CorsenContext(config, provider, cache);
+ */
+declare class RedisCache implements CacheDriver {
+    private redis;
+    private prefix;
+    constructor(redis: RedisClient, options?: {
+        prefix?: string;
+    });
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Redis-backed rate limit store using Sorted Sets.
+ *
+ * Each request is stored as a sorted-set member with score = timestamp; the
+ * window is pruned with ZREMRANGEBYSCORE and counted with ZCARD/ZRANGEBYSCORE.
+ * Every individual command is atomic, but the prune → add → count sequence is
+ * not wrapped in a single transaction, so under extreme concurrency the count
+ * can momentarily overshoot the limit by roughly the in-flight request count.
+ * The `hit()` path adds first and counts after (fail-safe: a rejected request
+ * still occupies a slot), which keeps the overshoot small and bounded. For a
+ * strict guarantee, back this with a client exposing an atomic script (Lua).
+ *
+ * Compatible with ioredis, @upstash/redis, or any client implementing RedisClient.
+ */
+declare class RedisRateLimitStore implements RateLimitStore {
+    private redis;
+    private prefix;
+    private windowMs;
+    constructor(redis: RedisClient, options?: {
+        prefix?: string;
+        windowMs?: number;
+    });
+    getTimestamps(key: string, windowStart: number): Promise<number[]>;
+    addTimestamp(key: string, timestamp: number): Promise<void>;
+    /**
+     * Combined add-then-count. Records the hit first, prunes the window, then
+     * returns the window and burst counts (both including the current request).
+     * Fewer round-trips than getTimestamps()+addTimestamp() and add-first so a
+     * rejected request still counts against the window.
+     */
+    hit(key: string, windowStart: number, burstWindowStart: number, now: number): Promise<{
+        windowCount: number;
+        burstCount: number;
+    }>;
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Check if an IP address is private/internal.
+ * Sync function — works on resolved IPs, not hostnames.
+ */
+declare function isPrivateIp(ip: string): boolean;
+/**
+ * Check if a URL points to a private/internal address.
+ * ASYNC — resolves DNS to prevent DNS rebinding attacks (OWASP SSRF 2026).
+ *
+ * Flow: parse URL → check hostname literally → resolve DNS → check resolved IPs.
+ */
+declare function isPrivateUrl(url: string): Promise<boolean>;
+/**
+ * Fetch a URL with SSRF protection.
+ *
+ * 1. Parse URL, reject literal localhost / private IPs.
+ * 2. Resolve DNS and verify EVERY resolved IP is public (fail-closed).
+ * 3. If undici is available, pin the connection to the vetted IP at the socket
+ *    level (keeping the hostname for TLS/SNI) so a rebind can't redirect the
+ *    request. Otherwise fetch the original URL — TLS still validates against the
+ *    real hostname, with a narrow residual rebinding window.
+ * 4. Never follow redirects (`redirect: 'error'`).
+ */
+declare function safeFetch(url: string, options?: RequestInit & {
+    timeout?: number;
+}): Promise<Response>;
+/**
+ * In-memory rate limit store. Default for development / single-instance.
+ * For production multi-instance, use RedisRateLimitStore.
+ *
+ * The store is long-lived (shared across requests), so it self-bounds: expired
+ * keys are pruned on a periodic timer and the key count is capped (oldest-first
+ * eviction). This prevents an attacker who rotates the rate-limit key — e.g. a
+ * fresh Authorization header per request — from growing the Map without bound.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private store;
+    private readonly maxKeys;
+    private cleanupTimer;
+    constructor(options?: {
+        maxKeys?: number;
+        autoCleanup?: boolean;
+    });
+    /** Number of tracked keys. */
+    get size(): number;
+    /** Stop the cleanup timer (for graceful shutdown or tests). */
+    destroy(): void;
+    /** Evict the oldest-inserted keys until under the cap (after a prune pass). */
+    private enforceCap;
+    getTimestamps(key: string, windowStart: number): Promise<number[]>;
+    addTimestamp(key: string, timestamp: number): Promise<void>;
+    /**
+     * Atomic prune + record + count. Runs synchronously (no await between the
+     * prune and the append), so concurrent requests on the same tick cannot
+     * interleave a check between another request's read and write — the TOCTOU
+     * race the split getTimestamps()/addTimestamp() path has.
+     */
+    hit(key: string, windowStart: number, burstWindowStart: number, now: number): Promise<{
+        windowCount: number;
+        burstCount: number;
+    }>;
+    cleanup(): Promise<void>;
+}
+declare class RateLimiter {
+    private store;
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly burstLimit;
+    constructor(maxRequestsPerMinute?: number, burstPerSecond?: number, store?: RateLimitStore);
+    check(key: string): Promise<RateLimitResult>;
+}
+/**
+ * Extract the real client IP from request headers.
+ *
+ * Forwarding headers (CF-Connecting-IP, X-Real-IP, X-Forwarded-For) are only
+ * honored when `trustProxy` is true — i.e. the server sits behind a reverse
+ * proxy that sets them. Otherwise they are attacker-controllable: a client can
+ * send a fresh spoofed value per request and land in a new rate-limit bucket
+ * every time, defeating the limiter. When untrusted, we key on the socket IP.
+ */
+declare function extractClientIp(headers: Record<string, string | string[] | undefined>, socketIp?: string, trustProxy?: boolean): string;
+/**
+ * Build rate limit key. Uses API key if present (more accurate), falls back to IP.
+ *
+ * The API key is run through a keyed hash (HMAC) purely to derive a stable,
+ * non-reversible bucket id — it is a store/log key, not credential storage.
+ * The fixed label keeps the id deterministic across instances so a distributed
+ * (Redis) limiter shares state for the same key.
+ */
+declare function buildRateLimitKey(clientIp: string, apiKey?: string): string;
+declare const searchParamsSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>;
+declare const getPageParamsSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uri: string;
+}, {
+    uri: string;
+}>;
+declare const listContentParamsSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodString>;
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    page: number;
+    limit: number;
+}, {
+    type?: string | undefined;
+    page?: number | undefined;
+    limit?: number | undefined;
+}>;
+declare function validateOrigin(origin: string | undefined, allowed: string[]): boolean;
+declare function validateHost(hostHeader: string | undefined, expectedHost: string): boolean;
+/**
+ * Hash an API key with SHA-256 + salt for secure storage.
+ */
+declare function hashApiKey(key: string, salt?: string): {
+    hash: string;
+    salt: string;
+};
+/**
+ * Timing-safe API key validation via the double-HMAC compare pattern.
+ *
+ * Both keys are HMAC'd with a fresh per-call random key, yielding fixed-length
+ * digests that are compared with timingSafeEqual. This leaks neither key length
+ * nor content through timing, and (unlike a bare hash) an attacker cannot
+ * precompute the digests.
+ */
+declare function validateApiKey(provided: string | undefined, expected: string | undefined): boolean;
+/**
+ * Enhanced API key validation with hashed keys, scopes, quotas, expiry.
+ * For production multi-key setups.
+ */
+declare class ApiKeyManager {
+    private keys;
+    /**
+     * Register a new API key. Returns the plain key (show to user once).
+     */
+    generateKey(options: {
+        name: string;
+        scopes?: string[];
+        quotaPerDay?: number;
+        expiresAt?: Date;
+    }): {
+        plainKey: string;
+        record: ApiKeyRecord;
+    };
+    /**
+     * Validate a provided API key against stored records.
+     * Returns the matching record or null.
+     */
+    validate(providedKey: string, requiredScope?: string): ApiKeyRecord | null;
+    /**
+     * Revoke an API key by ID.
+     */
+    revoke(keyId: string): boolean;
+    /**
+     * List all keys (without secrets).
+     */
+    listKeys(): Omit<ApiKeyRecord, 'keyHash' | 'keySalt'>[];
+    /**
+     * Load keys from external storage (e.g., Redis, database).
+     */
+    loadKeys(records: ApiKeyRecord[]): void;
+    private nextMidnight;
+}
+
+declare function resolvePublicPageUrl(input: string, config: ResolvedConfig): string | null;
+declare function isPublicListItem(item: ContentListItem, config: ResolvedConfig): boolean;
+declare function filterPublicPages(pages: ContentListItem[], config: ResolvedConfig): ContentListItem[];
+declare function isPublicPageContent(content: PageContent, config: ResolvedConfig): boolean;
+declare function filterPublicSearchResults(results: SearchResult[], config: ResolvedConfig, limit: number): SearchResult[];
+
+declare class CorsenContext {
+    private config;
+    private provider;
+    private cache;
+    private rateLimitStore;
+    constructor(userConfig: CorsenContextConfig, provider: ContentProvider, cache?: CacheDriver, rateLimitStore?: RateLimitStore);
+    generateLlmsTxt(): Promise<string>;
+    generateLlmsFullTxt(): Promise<string>;
+    createMCPServer(options?: {
+        rateLimitStore?: RateLimitStore;
+        logger?: pino.Logger;
+    }): MCPServer;
+    /** Drop the cached body for a single page URL (wire to CMS update/delete hooks). */
+    invalidatePage(url: string): Promise<void>;
+    /** Clear all cached MCP responses. Call after bulk content changes. */
+    clearCache(): Promise<void>;
+    discoverSitemap(url?: string): Promise<string | null>;
+    parseSitemap(sitemapUrl: string): Promise<SitemapEntry[]>;
+    convertToMarkdown(html: string): string;
+    extractMetadata(html: string): Record<string, string>;
+    getConfig(): {
+        siteUrl: string;
+        content: {
+            postTypes: string[];
+            excludePaths: string[];
+            maxPages: number;
+        };
+        mcp: {
+            enabled: boolean;
+            endpoint: string;
+            tools: string[];
+        };
+        static: {
+            generateLlmsTxt: boolean;
+            includeFullContent: boolean;
+        };
+        security: {
+            rateLimit: number;
+            burstLimit: number;
+            allowedOrigins: string[];
+            trustProxy: boolean;
+            exposeVersion: boolean;
+            apiKey?: string | undefined;
+        };
+        cache: {
+            enabled: boolean;
+            ttl: number;
+            driver: "memory" | "redis";
+        };
+        credit: boolean;
+        siteName?: string | undefined;
+        description?: string | undefined;
+    };
+}
+
+export { API_VERSION, ApiKeyManager, type ApiKeyRecord, CORSEN_CONTEXT_VERSION, CREDIT_LINE, type CacheDriver, type ContentList, type ContentListItem, type ContentProvider, CorsenContext, type CorsenContextConfig, type DiscoveryConfig, type InMemoryPage, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_ERRORS, type LogLevel, type Logger, type LoggerOptions, MAX_BODY_SIZE, MAX_JSON_DEPTH, type MCPCapabilities, type MCPResourceDefinition, MCPServer, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MemoryCache, MemoryRateLimitStore, type PageContent, REQUEST_TIMEOUT_MS, type RateLimitResult, type RateLimitStore, RateLimiter, RedisCache, type RedisClient, RedisRateLimitStore, type ResolvedConfig, SECURITY_HEADERS, type SearchResult, type SitemapEntry, buildRateLimitKey, corsenContextConfigSchema, createInMemoryProvider, createLogger, createSitemapProvider, discoverSitemap, extractClientIp, extractMetadata, filterPublicPages, filterPublicSearchResults, generateLlmsFullTxt, generateLlmsTxt, generateRobotsTxt, generateWellKnownMcp, getLogger, getPageParamsSchema, hashApiKey, htmlToMarkdown, isPrivateIp, isPrivateUrl, isPublicListItem, isPublicPageContent, listContentParamsSchema, mcpLinkTag, mcpLogger, parseSitemap, resolveConfig, resolvePublicPageUrl, safeFetch, searchParamsSchema, securityLogger, setLogger, validateApiKey, validateHost, validateOrigin };