/**
 * App surface generation — JSON-serializable attack surface from route and middleware specs.
 *
 * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`,
 * `merge_error_schemas`) live in `http/schema_helpers.ts`.
 *
 * @module
 */
import { z } from 'zod';
import type { EventSpec } from '../realtime/sse.js';
import type { MiddlewareSpec } from './middleware_spec.js';
import type { RouteSpec } from './route_spec.js';
import type { RouteAuth } from './auth_shape.js';
import type { RateLimitKey, RouteErrorSchemas } from './error_schemas.js';
import type { RpcAction } from '../actions/action_rpc.js';
import type { ActionKind } from '../actions/action_spec.js';
import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
import type { Sensitivity } from '../sensitivity.js';
/** A route in the generated attack surface (JSON-serializable). */
export interface AppSurfaceRoute {
    method: string;
    path: string;
    auth: RouteAuth;
    applicable_middleware: Array<string>;
    description: string;
    /** Whether this route mutates state (POST, PUT, DELETE, PATCH). */
    is_mutation: boolean;
    /** Whether this route's handler runs inside a database transaction. */
    transaction: boolean;
    /** Rate limit key type declared on the route spec. `null` when not rate-limited. */
    rate_limit_key: RateLimitKey | null;
    /** JSON Schema representation of the URL path params schema. `null` when no params. */
    params_schema: unknown;
    /** JSON Schema representation of the URL query params schema. `null` when no query schema. */
    query_schema: unknown;
    /** JSON Schema representation of the request body schema. `null` for no-body routes. */
    input_schema: unknown;
    /** JSON Schema representation of the success response schema. */
    output_schema: unknown;
    /** JSON Schema representations of error responses, keyed by HTTP status code. `null` when none. */
    error_schemas: Record<string, unknown> | null;
}
/** A middleware in the generated attack surface (JSON-serializable). */
export interface AppSurfaceMiddleware {
    name: string;
    path: string;
    /** JSON Schema representations of error responses, keyed by HTTP status code. `null` when none. */
    error_schemas: Record<string, unknown> | null;
}
/** An env var in the generated attack surface (JSON-serializable). */
export interface AppSurfaceEnv {
    name: string;
    description: string;
    /** Sensitivity level from `.meta({sensitivity})`. `null` when not sensitive. */
    sensitivity: Sensitivity | null;
    has_default: boolean;
    optional: boolean;
}
/** An SSE event in the generated attack surface (JSON-serializable). */
export interface AppSurfaceEvent {
    method: string;
    description: string;
    channel: string | null;
    params_schema: unknown;
}
/** A method within an RPC endpoint in the generated attack surface (JSON-serializable). */
export interface AppSurfaceRpcMethod {
    name: string;
    auth: RouteAuth;
    /** JSON Schema representation of the input schema. `null` for null-input methods. */
    input_schema: unknown;
    /** JSON Schema representation of the output schema. */
    output_schema: unknown;
    side_effects: boolean;
    description: string;
    /** Rate limit key declared on the action spec. `null` when not rate-limited. */
    rate_limit_key: RateLimitKey | null;
}
/** An RPC endpoint in the generated attack surface (JSON-serializable). */
export interface AppSurfaceRpcEndpoint {
    path: string;
    methods: Array<AppSurfaceRpcMethod>;
}
/** A method within a WebSocket endpoint in the generated attack surface (JSON-serializable). */
export interface AppSurfaceWsMethod {
    name: string;
    /** `request_response` (inbound dispatch) or `remote_notification` (server → client). */
    kind: ActionKind;
    /**
     * Per-action auth shape. `null` for `remote_notification` (server →
     * client) — notifications have no inbound dispatch and therefore no
     * auth axis. `request_response` always carries a `RouteAuth`.
     */
    auth: RouteAuth | null;
    /** JSON Schema of the input schema. `null` for nullary inputs. */
    input_schema: unknown;
    /** JSON Schema of the output schema. */
    output_schema: unknown;
    description: string;
    side_effects: boolean;
    /** Rate limit key declared on the action spec. `null` when not rate-limited. */
    rate_limit_key: RateLimitKey | null;
}
/** A WebSocket endpoint in the generated attack surface (JSON-serializable). */
export interface AppSurfaceWsEndpoint {
    path: string;
    /**
     * Upgrade-time origin allowlist, one entry per `WsEndpointSpec.allowed_origins`
     * regex stringified via `RegExp.prototype.toString()` (`'/<source>/<flags>'`).
     * Empty array when no origins were declared (any-origin); reviewers read this
     * as the exact pattern matched at the upgrade gate, not a wildcard
     * approximation. Reconstruct via `new RegExp(source, flags)` if needed.
     */
    allowed_origins: ReadonlyArray<string>;
    /**
     * Upgrade-time role gate — empty array when no `required_roles` was
     * declared (any-authenticated). Documents the coarse gate; per-action
     * `auth` on each method covers per-message authorization.
     */
    required_roles: ReadonlyArray<string>;
    methods: Array<AppSurfaceWsMethod>;
}
/** Assembly-time diagnostic collected during surface generation or server assembly. */
export interface AppSurfaceDiagnostic {
    level: 'warning' | 'info';
    category: string;
    message: string;
    source?: string;
}
/** Generated attack surface — JSON-serializable. */
export interface AppSurface {
    middleware: Array<AppSurfaceMiddleware>;
    routes: Array<AppSurfaceRoute>;
    rpc_endpoints: Array<AppSurfaceRpcEndpoint>;
    ws_endpoints: Array<AppSurfaceWsEndpoint>;
    env: Array<AppSurfaceEnv>;
    events: Array<AppSurfaceEvent>;
    diagnostics: Array<AppSurfaceDiagnostic>;
}
/**
 * The surface bundled with the source specs that produced it.
 *
 * `AppSurface` is JSON-serializable (snapshots, UI, startup logging) —
 * it's the observability layer, written to disk by `gro gen` for human
 * inspection + drift detection.
 *
 * `AppSurfaceSpec` is runtime-only — tests, introspection, attack
 * surface assertions. Both in-process and cross-process tests construct
 * an `AppSurfaceSpec` in TS via `create_test_app_surface_spec` (or a
 * consumer equivalent); the cross-process-ness lives in the transport
 * + per-test fixture, not the schema source.
 */
export interface AppSurfaceSpec {
    surface: AppSurface;
    route_specs: Array<RouteSpec>;
    middleware_specs: Array<MiddlewareSpec>;
    rpc_endpoints: Array<RpcEndpointSpec>;
    ws_endpoints: Array<WsEndpointSpec>;
}
/** An RPC endpoint definition for surface generation. */
export interface RpcEndpointSpec {
    path: string;
    actions: Array<RpcAction>;
}
/** Options for `generate_app_surface`. */
export interface GenerateAppSurfaceOptions {
    route_specs: Array<RouteSpec>;
    middleware_specs: Array<MiddlewareSpec>;
    env_schema?: z.ZodObject;
    event_specs?: Array<EventSpec>;
    rpc_endpoints?: Array<RpcEndpointSpec>;
    /**
     * Mounted WS endpoints (the same array `create_app_server.ws_endpoints`
     * auto-mounts). Each entry's actions surface into
     * `AppSurface.ws_endpoints[i].methods` for attack-surface tests +
     * startup logging.
     */
    ws_endpoints?: ReadonlyArray<WsEndpointSpec>;
}
/**
 * Collect error schemas from all middleware that applies to a route path.
 *
 * @returns merged middleware error schemas, or `null` if none
 */
export declare const collect_middleware_errors: (middleware: Array<MiddlewareSpec>, route_path: string) => RouteErrorSchemas | null;
/**
 * Convert env schema to surface entries using `.meta()` metadata.
 *
 * @param schema - Zod object schema with `.meta()` on fields
 */
export declare const env_schema_to_surface: (schema: z.ZodObject) => Array<AppSurfaceEnv>;
/**
 * Convert SSE event specs to surface entries.
 */
export declare const events_to_surface: (event_specs: Array<EventSpec>) => Array<AppSurfaceEvent>;
/**
 * Generate a JSON-serializable attack surface from middleware, route specs,
 * and optional env/event metadata.
 */
export declare const generate_app_surface: (options: GenerateAppSurfaceOptions) => AppSurface;
/**
 * Create an `AppSurfaceSpec` — the surface bundled with its source specs.
 */
export declare const create_app_surface_spec: (options: GenerateAppSurfaceOptions) => AppSurfaceSpec;
//# sourceMappingURL=surface.d.ts.map