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 schema_helpers.ts.

Declarations
#

13 declarations

view source

AppSurface
#

http/surface.ts view source

AppSurface

Generated attack surface — JSON-serializable.

middleware

type Array<AppSurfaceMiddleware>

routes

type Array<AppSurfaceRoute>

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

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

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

route_specs

type Array<RouteSpec>

middleware_specs

type Array<MiddlewareSpec>

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

the middleware specs

type MiddlewareSpec[]

route_path

the route path to match against

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
#

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[]

array of env surface entries

events_to_surface
#

http/surface.ts view source

(event_specs: SseEventSpec[]): AppSurfaceEvent[]

Convert SSE event specs to surface entries.

event_specs

event specs to convert

type SseEventSpec[]

returns

AppSurfaceEvent[]

array of event surface entries

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

the surface generation options

returns

AppSurface

the attack surface

GenerateAppSurfaceOptions
#

http/surface.ts view source

GenerateAppSurfaceOptions

route_specs

type Array<RouteSpec>

middleware_specs

type Array<MiddlewareSpec>

env_schema

type z.ZodObject

event_specs

type Array<SseEventSpec>

Depends on
#

Imported by
#