/**
 * CSRF protection middleware for the server module.
 *
 * Implements the OWASP double-submit-cookie pattern. A per-client secret is
 * stored in a cookie; the matching token must be echoed back in a request header
 * (or form field) on state-changing requests. When a server `secret` is
 * supplied the token is HMAC-signed (signed double-submit), which additionally
 * defends against cookie injection from a sibling subdomain.
 *
 * Pairs with the `security` module: CSRF guards request *integrity* while
 * `sanitizeHtml()` / Trusted Types guard *output*. Use both for defense in depth.
 *
 * @module bquery/server
 */
import type { ServerCookieOptions, ServerContext, ServerMiddleware } from './types';
/** Options for the {@link csrf} middleware. */
export interface CsrfOptions {
    /**
     * Optional signing secret(s). When provided, tokens are HMAC-signed (signed
     * double-submit). Pass an array to rotate secrets. When omitted, plain
     * double-submit is used (token equals the cookie secret).
     */
    secret?: string | readonly string[];
    /** Cookie name holding the per-client secret. Default `'bq.csrf'`. */
    cookieName?: string;
    /** Request header carrying the token. Default `'x-csrf-token'`. */
    headerName?: string;
    /** Form/JSON body field carrying the token when no header is present. Default `'_csrf'`. */
    fieldName?: string;
    /**
     * Cookie attributes. Defaults to `{ sameSite: 'lax', path: '/' }`. The cookie
     * is readable by client JS by default (plain double-submit); set
     * `httpOnly: true` only when you deliver the token out-of-band (signed mode).
     */
    cookie?: ServerCookieOptions;
    /** HTTP methods that skip verification. Default `['GET', 'HEAD', 'OPTIONS']`. */
    ignoreMethods?: string[];
    /** Custom token extractor, tried before the header and field lookups. */
    getToken?: (ctx: ServerContext) => string | null | undefined | Promise<string | null | undefined>;
}
/**
 * Read the CSRF token issued for the current request, suitable for embedding in
 * a form field, `<meta>` tag, or JSON payload. Returns `null` when the
 * {@link csrf} middleware has not run for this request.
 *
 * @example
 * ```ts
 * app.get('/form', (ctx) =>
 *   ctx.html(`<input type="hidden" name="_csrf" value="${csrfToken(ctx)}">`)
 * );
 * ```
 */
export declare const csrfToken: (ctx: ServerContext) => string | null;
/**
 * Middleware that enforces CSRF protection via the double-submit-cookie pattern.
 *
 * Safe requests (GET/HEAD/OPTIONS by default) mint a per-client secret cookie
 * and expose the matching token through {@link csrfToken}. State-changing
 * requests must echo that token back in the `x-csrf-token` header or a `_csrf`
 * body field, or they are rejected with `403`.
 *
 * @example
 * ```ts
 * import { createServer, csrf } from '@bquery/bquery/server';
 *
 * const app = createServer();
 * app.use(csrf({ secret: process.env.SECRET! }));
 * ```
 */
export declare const csrf: (options?: CsrfOptions) => ServerMiddleware;
//# sourceMappingURL=csrf.d.ts.map