http/surface.ts

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.

Declarations
#

16 declarations

view source

AppSurface
#

http/surface.ts view source

AppSurface

Generated attack surface — JSON-serializable.

`middleware`

type Array<AppSurfaceMiddleware>

`routes`

type Array<AppSurfaceRoute>

`rpc_endpoints`

type Array<AppSurfaceRpcEndpoint>

`env`

type Array<AppSurfaceEnv>

`events`

type Array<AppSurfaceEvent>

`diagnostics`

type Array<AppSurfaceDiagnostic>

AppSurfaceDiagnostic
#

http/surface.ts view source

AppSurfaceDiagnostic

Assembly-time diagnostic collected during surface generation or server assembly.

`level`

type 'warning' | 'info'

`category`

type string

`message`

type string

`source`

type string

AppSurfaceEnv
#

http/surface.ts view source

AppSurfaceEnv

An env var in the generated attack surface (JSON-serializable).

`name`

type string

`description`

type string

`sensitivity`

Sensitivity level from .meta({sensitivity}). null when not sensitive.

type Sensitivity | null

`has_default`

type boolean

`optional`

type boolean

AppSurfaceEvent
#

http/surface.ts view source

AppSurfaceEvent

An SSE event in the generated attack surface (JSON-serializable).

`method`

type string

`description`

type string

`channel`

type string | null

`params_schema`

type unknown

AppSurfaceMiddleware
#

http/surface.ts view source

AppSurfaceMiddleware

A middleware in the generated attack surface (JSON-serializable).

`name`

type string

`path`

type string

`error_schemas`

JSON Schema representations of error responses, keyed by HTTP status code. null when none.

type Record<string, unknown> | null

AppSurfaceRoute
#

http/surface.ts view source

AppSurfaceRoute

A route in the generated attack surface (JSON-serializable).

`method`

type string

`path`

type string

`auth`

type RouteAuth

`applicable_middleware`

type Array<string>

`description`

type string

`is_mutation`

Whether this route mutates state (POST, PUT, DELETE, PATCH).

type boolean

`transaction`

Whether this route's handler runs inside a database transaction.

type boolean

`rate_limit_key`

Rate limit key type declared on the route spec. null when not rate-limited.

type RateLimitKey | null

`params_schema`

JSON Schema representation of the URL path params schema. null when no params.

type unknown

`query_schema`

JSON Schema representation of the URL query params schema. null when no query schema.

type unknown

`input_schema`

JSON Schema representation of the request body schema. null for no-body routes.

type unknown

`output_schema`

JSON Schema representation of the success response schema.

type unknown

`error_schemas`

JSON Schema representations of error responses, keyed by HTTP status code. null when none.

type Record<string, unknown> | null

AppSurfaceRpcEndpoint
#

http/surface.ts view source

AppSurfaceRpcEndpoint

An RPC endpoint in the generated attack surface (JSON-serializable).

`path`

type string

`methods`

type Array<AppSurfaceRpcMethod>

AppSurfaceRpcMethod
#

http/surface.ts view source

AppSurfaceRpcMethod

A method within an RPC endpoint in the generated attack surface (JSON-serializable).

`name`

type string

`auth`

type RouteAuth

`input_schema`

JSON Schema representation of the input schema. null for null-input methods.

type unknown

`output_schema`

JSON Schema representation of the output schema.

type unknown

`side_effects`

type boolean

`description`

type string

`rate_limit_key`

Rate limit key declared on the action spec. null when not rate-limited.

type RateLimitKey | null

AppSurfaceSpec
#

http/surface.ts view source

AppSurfaceSpec

The surface bundled with the source specs that produced it.
AppSurface is JSON-serializable (snapshots, UI, startup logging).
AppSurfaceSpec is runtime-only (tests, introspection, attack surface assertions).

`surface`

type AppSurface

`route_specs`

type Array<RouteSpec>

`middleware_specs`

type Array<MiddlewareSpec>

`rpc_endpoints`

type Array<RpcEndpointSpec>

collect_middleware_errors
#

http/surface.ts view source

(middleware: MiddlewareSpec[], route_path: string): Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null

Collect error schemas from all middleware that applies to a route path.

`middleware`

type MiddlewareSpec[]

`route_path`

type string

returns

Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null

merged middleware error schemas, or null if none

create_app_surface_spec
#

http/surface.ts view source

(options: GenerateAppSurfaceOptions): AppSurfaceSpec

Create an AppSurfaceSpec — the surface bundled with its source specs.

`options`

type GenerateAppSurfaceOptions

returns

AppSurfaceSpec

env_schema_to_surface
#

http/surface.ts view source

(schema: ZodObject<$ZodLooseShape, $strip>): AppSurfaceEnv[]

Convert env schema to surface entries using .meta() metadata.

`schema`

Zod object schema with .meta() on fields

type ZodObject<$ZodLooseShape, $strip>

returns

AppSurfaceEnv[]

events_to_surface
#

http/surface.ts view source

(event_specs: EventSpec[]): AppSurfaceEvent[]

Convert SSE event specs to surface entries.

`event_specs`

type EventSpec[]

returns

AppSurfaceEvent[]

generate_app_surface
#

http/surface.ts view source

(options: GenerateAppSurfaceOptions): AppSurface

Generate a JSON-serializable attack surface from middleware, route specs,
and optional env/event metadata.

`options`

type GenerateAppSurfaceOptions

returns

AppSurface

GenerateAppSurfaceOptions
#

http/surface.ts view source

GenerateAppSurfaceOptions

Options for generate_app_surface.

`route_specs`

type Array<RouteSpec>

`middleware_specs`

type Array<MiddlewareSpec>

`env_schema`

type z.ZodObject

`event_specs`

type Array<EventSpec>

`rpc_endpoints`

type Array<RpcEndpointSpec>

RpcEndpointSpec
#

http/surface.ts view source

RpcEndpointSpec

An RPC endpoint definition for surface generation.

`path`

type string

`actions`

type Array<RpcAction>

Depends on
#

http/schema_helpers.ts