import './assert_dev_env.js';
/**
 * Table-driven middleware test helpers.
 *
 * Provides mock builders for bearer auth middleware dependencies,
 * a generic test runner that iterates case tables, and a reusable
 * middleware stack factory for integration testing.
 *
 * @module
 */
import { vi } from 'vitest';
import { Hono } from 'hono';
import type { z } from 'zod';
import type { RateLimiter } from '../rate_limiter.js';
import { type RequestContext } from '../auth/request_context.js';
/** Mock configuration for bearer auth middleware test setup. */
export interface BearerAuthTestOptions {
    /** Test description. */
    name: string;
    /** Request headers. */
    headers?: Record<string, string>;
    /** Pre-set request context (simulates session already resolved). */
    pre_context?: RequestContext;
    /** What `query_validate_api_token()` returns. */
    mock_validate_result?: unknown;
    /** What `query_account_by_id()` returns. */
    mock_find_by_id_result?: unknown;
    /** What `query_actor_by_id()` returns. */
    mock_find_actor_by_id_result?: unknown;
    /** What `query_role_grant_find_active_for_actor()` returns. */
    mock_role_grants_result?: unknown;
    /** Expected HTTP status, or `'next'` if the middleware should call `next()`. */
    expected_status: number | 'next';
    /** Expected `error` field in JSON response body. */
    expected_error?: string;
    /** Zod schema to validate error response body against. Defaults to `ApiError` when `expected_error` is set. */
    expected_error_schema?: z.ZodType;
}
/** A full test case for the table-driven bearer auth runner. */
export interface BearerAuthTestCase extends BearerAuthTestOptions {
    /** Whether the request should reach token validation or be short-circuited. */
    validate_expectation: 'called' | 'not_called';
    /** If true, assert `ACCOUNT_ID_KEY` was set and `CREDENTIAL_TYPE_KEY` is `'api_token'`. */
    assert_account_set?: boolean;
    /** Expected `ACCOUNT_ID_KEY` value when `assert_account_set` is true. */
    expected_account_id?: string;
    /** If set, assert `AUTH_API_TOKEN_ID_KEY` was set to this value after a successful bearer auth. */
    expected_api_token_id?: string;
    /** If true, assert the pre-existing session `ACCOUNT_ID_KEY` and credential type are preserved. */
    assert_context_preserved?: boolean;
    /** Optional callback for custom spy assertions on the mocks bundle. */
    assert_mocks?: (mocks: BearerAuthMocks) => void;
}
/** Mocks bundle returned by `create_bearer_auth_mocks`. */
export interface BearerAuthMocks {
    mock_validate: ReturnType<typeof vi.fn>;
    mock_find_by_id: ReturnType<typeof vi.fn>;
    mock_find_actor_by_id: ReturnType<typeof vi.fn>;
    mock_find_actors_by_account: ReturnType<typeof vi.fn>;
    mock_find_active_for_actor: ReturnType<typeof vi.fn>;
}
/**
 * Create mock dependencies for `create_bearer_auth_middleware`, configured per test case.
 *
 * Configures the module-level mocks for `query_validate_api_token`,
 * `query_account_by_id`, `query_actor_by_id`, and `query_role_grant_find_active_for_actor`
 * so each test case controls return values independently.
 *
 * @returns mocks bundle with spy references
 * @mutates module-level `vi.mock` registrations for `api_token_queries`,
 *   `account_queries`, and `role_grant_queries` — each call resets and re-binds
 *   the four spies, so cases run in sequence without bleeding state.
 */
export declare const create_bearer_auth_mocks: (tc: BearerAuthTestOptions) => BearerAuthMocks;
/** Default client IP set by the proxy stub in test apps. */
export declare const TEST_CLIENT_IP = "127.0.0.1";
/**
 * Create a Hono app wired with `create_bearer_auth_middleware` using mocked deps.
 *
 * The route handler at `/api/test` returns the resolved context in the response body,
 * enabling assertions on `REQUEST_CONTEXT_KEY` and `CREDENTIAL_TYPE_KEY`.
 */
export declare const create_bearer_auth_test_app: (tc: BearerAuthTestOptions, ip_rate_limiter?: RateLimiter | null) => {
    app: Hono;
    mocks: BearerAuthMocks;
};
/**
 * Run a table of bearer auth middleware test cases.
 *
 * Generates one `test()` per case inside a `describe()` block.
 */
export declare const describe_bearer_auth_cases: (suite_name: string, cases: Array<BearerAuthTestCase>, ip_rate_limiter?: RateLimiter | null) => void;
/** Path used by the echo route in `create_test_middleware_stack_app`. */
export declare const TEST_MIDDLEWARE_PATH = "/api/test";
/** Options for `create_test_middleware_stack_app`. */
export interface TestMiddlewareStackOptions {
    /** Trusted proxy IPs. @default `['10.0.0.1']` */
    trusted_proxies?: Array<string>;
    /** Comma-separated allowed origin patterns. @default `'https://app.example.com'` */
    allowed_origins?: string;
    /** Connection IP or factory. @default first trusted proxy */
    connection_ip?: string | (() => string | undefined);
    /** Rate limiter for bearer auth. @default `null` */
    ip_rate_limiter?: RateLimiter | null;
}
/** Return type of `create_test_middleware_stack_app`. */
export interface TestMiddlewareStackApp {
    app: Hono;
    mock_validate: ReturnType<typeof vi.fn>;
    mock_find_by_id: ReturnType<typeof vi.fn>;
    mock_find_actor_by_id: ReturnType<typeof vi.fn>;
    mock_find_actors_by_account: ReturnType<typeof vi.fn>;
    mock_find_active_for_actor: ReturnType<typeof vi.fn>;
}
/**
 * Create a Hono app with real proxy + origin + bearer middleware for integration testing.
 *
 * All DB queries return undefined (no real database needed).
 * The echo route at `TEST_MIDDLEWARE_PATH` returns `{ok, client_ip, has_context}`.
 *
 * @returns the app and mock spies (reconfigure via `mockImplementation` for valid-token paths)
 * @mutates module-level `vi.mock` registrations for the four bearer-auth query
 *   modules — each call resets the spies before wiring the stack.
 */
export declare const create_test_middleware_stack_app: (options?: TestMiddlewareStackOptions) => TestMiddlewareStackApp;
//# sourceMappingURL=middleware.d.ts.map