@mpen/routekit 0.1.0 → 0.1.2

package/src/router/middleware/csrf.ts

@@ -1,192 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import { text } from '../response/formats/content'
-import { isLocalhost } from '../lib/host'
-import { defineMiddleware, type DeclaredMiddleware } from './define'
-import type { AnyContext, OneOrMany } from '../types'
-
-type AllowedOriginEntry = { kind: 'origin'; value: string } | { kind: 'host'; value: string }
-
-export interface CsrfOptions {
-    /**
-     * Origins that are allowed even when they are cross-site.
-     * Values may be full origins (`https://app.example.com`) or bare hosts (`app.example.com`).
-     */
-    allowedOrigins?: OneOrMany<string | URL>
-    /**
-     * Allow localhost and loopback origins for local development.
-     */
-    allowLocalhost?: boolean
-    /**
-     * Allow requests without the Origin header (useful for curl).
-     */
-    allowMissingOrigin?: boolean
-    /**
-     * Allow requests without Sec-Fetch-* headers (useful for curl).
-     */
-    allowMissingFetchMetadata?: boolean
-    /**
-     * Convenience flag that enables localhost + missing header allowances.
-     */
-    dev?: boolean
-}
-
-const fetchDestHeader = 'sec-fetch-dest'
-const fetchModeHeader = 'sec-fetch-mode'
-const fetchSiteHeader = 'sec-fetch-site'
-
-function parseOrigin(originHeader: string | null): URL | null {
-    if (!originHeader) return null
-    const trimmed = originHeader.trim()
-    if (!trimmed || trimmed === 'null') return null
-    try {
-        return new URL(trimmed)
-    } catch {
-        return null
-    }
-}
-
-function normalizeAllowedOrigins(allowed?: OneOrMany<string | URL>): AllowedOriginEntry[] {
-    if (!allowed) return []
-    const entries = Array.isArray(allowed) ? allowed : [allowed]
-    const normalized: AllowedOriginEntry[] = []
-    for (const entry of entries) {
-        if (entry instanceof URL) {
-            normalized.push({ kind: 'origin', value: entry.origin })
-            continue
-        }
-        const trimmed = entry.trim()
-        if (!trimmed) continue
-        if (trimmed.includes('://')) {
-            try {
-                normalized.push({ kind: 'origin', value: new URL(trimmed).origin })
-            } catch {
-                continue
-            }
-        } else {
-            normalized.push({ kind: 'host', value: trimmed.replace(/\/+$/, '') })
-        }
-    }
-    return normalized
-}
-
-function isOriginAllowlisted(origin: URL, allowlist: AllowedOriginEntry[]): boolean {
-    for (const entry of allowlist) {
-        if (entry.kind === 'origin') {
-            if (origin.origin === entry.value) return true
-            continue
-        }
-        if (entry.value.includes(':')) {
-            if (origin.host === entry.value) return true
-        } else if (origin.hostname === entry.value) {
-            return true
-        }
-    }
-    return false
-}
-
-function isIpAddress(hostname: string): boolean {
-    if (hostname.includes(':')) return true
-    return /^[0-9.]+$/.test(hostname)
-}
-
-function siteBase(hostname: string): string {
-    const lower = hostname.toLowerCase()
-    if (lower === 'localhost' || isIpAddress(lower)) return lower
-    const parts = lower.split('.').filter(Boolean)
-    if (parts.length <= 2) return lower
-    return parts.slice(-2).join('.')
-}
-
-function isSameSite(origin: URL, requestUrl: URL): boolean {
-    return siteBase(origin.hostname) === siteBase(requestUrl.hostname)
-}
-
-/**
- * Enforce CSRF protection using Fetch Metadata and Origin headers.
- *
- * By default, only same-site fetch() requests are allowed. Set `allowedOrigins` to permit
- * explicit cross-site origins. Enable `dev` to allow localhost and curl-style requests
- * that omit Fetch Metadata or Origin headers.
- *
- * @example
- * ```ts
- * router.use(csrf())
- * router.use(csrf({allowedOrigins: ['https://app.example.com']}))
- * router.use(csrf({dev: true}))
- * ```
- *
- * @param options - Configuration for allowed origins and dev-friendly relaxations.
- * @returns Middleware that rejects requests failing CSRF checks.
- */
-export function csrf<Ctx extends object = AnyContext>(
-    options: CsrfOptions = {},
-): DeclaredMiddleware<{}, Ctx> {
-    const allowLocalhost = options.allowLocalhost ?? options.dev ?? false
-    const allowMissingOrigin = options.allowMissingOrigin ?? options.dev ?? false
-    const allowMissingFetchMetadata = options.allowMissingFetchMetadata ?? options.dev ?? false
-    const allowedOrigins = normalizeAllowedOrigins(options.allowedOrigins)
-
-    return defineMiddleware({
-        responses: {
-            [HttpStatus.FORBIDDEN]: {
-                schema: { type: 'string' },
-                parse(value: unknown): string {
-                    if (typeof value !== 'string') {
-                        throw new TypeError('CSRF rejection responses must contain a string body.')
-                    }
-                    return value
-                },
-            },
-        },
-        async run(ctx, { next, forward, respond }) {
-            const requestUrl = ctx.request.url
-            const originHeader = ctx.request.headers.get('origin')
-            const originUrl = parseOrigin(originHeader)
-
-            const fetchDest = ctx.request.headers.get(fetchDestHeader)
-            const fetchMode = ctx.request.headers.get(fetchModeHeader)
-            const fetchSite = ctx.request.headers.get(fetchSiteHeader)
-
-            const fetchMetadataMissing = !fetchDest || !fetchMode || !fetchSite
-            if (fetchMetadataMissing && !allowMissingFetchMetadata) {
-                return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-            }
-
-            if (fetchDest && fetchDest !== 'empty') {
-                return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-            }
-            if (fetchMode && fetchMode !== 'cors' && fetchMode !== 'same-origin') {
-                return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-            }
-
-            const originIsAllowlisted = originUrl
-                ? isOriginAllowlisted(originUrl, allowedOrigins)
-                : false
-            const originIsLocalhost = originUrl
-                ? allowLocalhost && isLocalhost(originUrl.hostname)
-                : false
-            const originIsSameSite = originUrl ? isSameSite(originUrl, requestUrl) : false
-
-            if (!originUrl && !allowMissingOrigin) {
-                return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-            }
-            if (originUrl && !(originIsAllowlisted || originIsLocalhost || originIsSameSite)) {
-                return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-            }
-
-            if (fetchSite) {
-                if (fetchSite === 'same-origin' || fetchSite === 'same-site') {
-                    // ok
-                } else if (fetchSite === 'cross-site') {
-                    if (!originIsAllowlisted && !originIsLocalhost) {
-                        return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-                    }
-                } else {
-                    return respond(text('Forbidden', { status: HttpStatus.FORBIDDEN }))
-                }
-            }
-
-            return forward(await next())
-        },
-    })
-}

package/src/router/middleware/define.ts

@@ -1,249 +0,0 @@
-import { response, type RoutekitResponse } from '../response'
-import type { AnyContext, HandlerContext, HandlerResult, JsonSchema, RouteSchema } from '../types'
-import { mergeRouteSchemas } from '../lib/schema-merge'
-
-const declaredMiddlewareBrand: unique symbol = Symbol('DeclaredMiddleware')
-const middlewareActionBrand: unique symbol = Symbol('MiddlewareAction')
-
-/**
- * A response declaration owned by middleware.
- *
- * @example
- * ```ts
- * const forbidden = {
- *     schema: { type: 'string' },
- *     parse: value => String(value),
- * }
- * ```
- *
- * @typeParam Body - Parsed response body produced by the declaration.
- */
-export interface MiddlewareResponseDeclaration<Body = unknown> {
-    /**
-     * JSON Schema emitted for metadata consumers such as OpenAPI and client generation.
-     */
-    readonly schema: JsonSchema
-    /**
-     * Validate and optionally parse a locally originated response body.
-     *
-     * @param value - Body supplied through `respond(...)`.
-     * @returns The validated response body.
-     */
-    parse(value: unknown): Body
-}
-
-/**
- * Status-keyed response declarations owned by middleware.
- */
-export type MiddlewareResponseDeclarations = Partial<
-    Record<number | 'default', MiddlewareResponseDeclaration<any>>
->
-
-type DeclaredBody<Declaration> =
-    Declaration extends MiddlewareResponseDeclaration<infer Body> ? Body : never
-
-type DeclaredResponse<Declarations extends MiddlewareResponseDeclarations> = {
-    [Status in keyof Declarations]-?: NonNullable<
-        Declarations[Status]
-    > extends MiddlewareResponseDeclaration<any>
-        ? RoutekitResponse<
-              DeclaredBody<NonNullable<Declarations[Status]>>,
-              Status extends number ? Status : number
-          >
-        : never
-}[keyof Declarations]
-
-/** @internal */
-export interface MiddlewareAction {
-    readonly [middlewareActionBrand]: true
-    readonly result: HandlerResult
-}
-
-/**
- * Controls passed to a declared middleware implementation.
- *
- * @typeParam Declarations - Locally originated response declarations.
- */
-export interface MiddlewareControls<Declarations extends MiddlewareResponseDeclarations> {
-    /**
-     * Invoke downstream middleware and the route handler.
-     *
-     * @returns The downstream result before it is finalized into a Fetch response.
-     */
-    next(): Promise<HandlerResult>
-    /**
-     * Forward an unchanged or decorated downstream result.
-     *
-     * @param result - Result obtained from [`MiddlewareControls.next`]{@link MiddlewareControls#next}.
-     * @returns A middleware action accepted by the declaring factory.
-     */
-    forward(result: HandlerResult): MiddlewareAction
-    /**
-     * Return a response originated by this middleware.
-     *
-     * @param result - Logical response matching a declared body and exact status.
-     * @returns A validated terminal middleware action.
-     */
-    respond(result: DeclaredResponse<Declarations>): MiddlewareAction
-}
-
-/**
- * Callable middleware carrying schema declarations for router metadata.
- *
- * @typeParam AddedCtx - Context values made available to downstream handlers.
- * @typeParam Ctx - Context required before this middleware executes.
- */
-export interface DeclaredMiddleware<AddedCtx extends object = {}, Ctx extends object = AnyContext> {
-    readonly [declaredMiddlewareBrand]: true
-    readonly schema?: RouteSchema
-    readonly schemaAppliesTo?: (route: { readonly method?: string | readonly string[] }) => boolean;
-    (
-        ctx: HandlerContext<Ctx & AddedCtx>,
-        next: () => Promise<HandlerResult>,
-    ): Promise<HandlerResult>
-}
-
-/**
- * Options for [`defineMiddleware`]{@link defineMiddleware}.
- *
- * @typeParam AddedCtx - Context values made available to downstream handlers.
- * @typeParam Ctx - Context required before this middleware executes.
- * @typeParam Declarations - Status-keyed locally originated responses.
- */
-export interface DefineMiddlewareOptions<
-    AddedCtx extends object,
-    Ctx extends object,
-    Declarations extends MiddlewareResponseDeclarations,
-> {
-    /**
-     * Additional metadata contributed by the middleware, such as request schemas or
-     * downstream response boundary schemas.
-     */
-    schema?: RouteSchema
-    /**
-     * Limit this middleware's schema contribution to matching flattened routes.
-     *
-     * @param route - Route metadata being flattened by the router.
-     * @returns Whether this middleware's schema applies to that route.
-     */
-    schemaAppliesTo?: (route: { readonly method?: string | readonly string[] }) => boolean
-    /**
-     * Responses that this middleware may originate through `respond(...)`.
-     */
-    responses?: Declarations
-    /**
-     * Execute middleware behavior.
-     *
-     * @param ctx - Request and route context available at execution time.
-     * @param controls - Continuation, forwarding, and terminal response operations.
-     * @returns A terminal/forward action, or void to continue automatically.
-     */
-    run(
-        ctx: HandlerContext<Ctx & AddedCtx>,
-        controls: MiddlewareControls<Declarations>,
-    ): MiddlewareAction | void | Promise<MiddlewareAction | void>
-}
-
-function declarationsSchema(
-    declarations: MiddlewareResponseDeclarations | undefined,
-): RouteSchema | undefined {
-    if (!declarations) return undefined
-    const body = Object.fromEntries(
-        Object.entries(declarations).flatMap(([status, declaration]) =>
-            declaration ? [[status, declaration.schema]] : [],
-        ),
-    )
-    return Object.keys(body).length > 0 ? { response: { body } } : undefined
-}
-
-function middlewareAction(result: HandlerResult): MiddlewareAction {
-    return { [middlewareActionBrand]: true, result }
-}
-
-/**
- * Create middleware that declares and validates every response it originates.
- *
- * @example
- * ```ts
- * const auth = defineMiddleware({
- *     responses: {
- *         401: {
- *             schema: { type: 'string' },
- *             parse: value => String(value),
- *         },
- *     },
- *     run: async (_ctx, { respond }) => respond(response('Sign in', { status: 401 })),
- * })
- * ```
- *
- * @param options - Schema declarations and middleware implementation.
- * @returns Executable middleware carrying its metadata contribution.
- * @typeParam AddedCtx - Context values made available to downstream handlers.
- * @typeParam Ctx - Context required before this middleware executes.
- * @typeParam Declarations - Status-keyed locally originated responses.
- */
-export function defineMiddleware<
-    AddedCtx extends object = {},
-    Ctx extends object = AnyContext,
-    const Declarations extends MiddlewareResponseDeclarations = {},
->(options: DefineMiddlewareOptions<AddedCtx, Ctx, Declarations>): DeclaredMiddleware<AddedCtx, Ctx>
-export function defineMiddleware<
-    AddedCtx extends object = {},
-    Ctx extends object = AnyContext,
-    const Declarations extends MiddlewareResponseDeclarations = {},
->(
-    options: DefineMiddlewareOptions<AddedCtx, Ctx, Declarations>,
-): DeclaredMiddleware<AddedCtx, Ctx> {
-    const declarations = options.responses
-    const schema = mergeRouteSchemas(options.schema, declarationsSchema(declarations))
-    const middleware = async (
-        ctx: HandlerContext<Ctx & AddedCtx>,
-        next: () => Promise<HandlerResult>,
-    ): Promise<HandlerResult> => {
-        const controls: MiddlewareControls<Declarations> = {
-            next,
-            forward: middlewareAction,
-            respond(result) {
-                const declaration = declarations?.[result.status] ?? declarations?.default
-                if (!declaration) {
-                    throw new Error(
-                        `Middleware returned undeclared response status ${result.status}.`,
-                    )
-                }
-                const body = declaration.parse(result.body)
-                return middlewareAction(
-                    response(body, {
-                        status: result.status,
-                        headers: result.headers,
-                    }),
-                )
-            },
-        }
-        const action = await options.run(ctx, controls)
-        if (action === undefined) return await next()
-        if (!action[middlewareActionBrand]) {
-            throw new TypeError('Declared middleware must return respond(...) or forward(...).')
-        }
-        return action.result
-    }
-    Object.defineProperties(middleware, {
-        [declaredMiddlewareBrand]: { value: true },
-        schema: { value: schema },
-        schemaAppliesTo: { value: options.schemaAppliesTo },
-    })
-    return middleware as DeclaredMiddleware<AddedCtx, Ctx>
-}
-
-/**
- * Test whether a middleware value carries schema declarations.
- *
- * @param value - Middleware value to inspect.
- * @returns Whether `value` was created by [`defineMiddleware`]{@link defineMiddleware}.
- * @internal
- */
-export function isDeclaredMiddleware(value: unknown): value is DeclaredMiddleware<any, any> {
-    return (
-        typeof value === 'function' &&
-        (value as DeclaredMiddleware<any, any>)[declaredMiddlewareBrand] === true
-    )
-}

package/src/router/middleware/index.ts

@@ -1,34 +0,0 @@
-export { requestIdCtx } from './request-id-ctx'
-export type { RequestIdCtxOptions } from './request-id-ctx'
-export { requestLogger } from './request-logger'
-export type { RequestLoggerOptions } from './request-logger'
-export {
-    formatRoutekitTerminalLogRecord,
-    transformRoutekitJsonLogRecord,
-} from './request-logger-format'
-export { defineMiddleware } from './define'
-export type {
-    DeclaredMiddleware,
-    DefineMiddlewareOptions,
-    MiddlewareControls,
-    MiddlewareResponseDeclaration,
-    MiddlewareResponseDeclarations,
-} from './define'
-export { bodyLimit } from './body-limit'
-export { startTimeCtx } from './start-time-ctx'
-export { acceptCtx } from './accept-ctx'
-export { cors } from './cors'
-export { rateLimit } from './rate-limit'
-export type { HttpMethod } from '@mpen/http'
-export type {
-    AsnClass,
-    AsnRecord,
-    EndpointLimit,
-    FixedWindowCounter,
-    MethodLimit,
-    RateBucket,
-    RateLimitIdentityInput,
-    RateLimitOptions,
-    RateLimitStorage,
-} from './rate-limit'
-export type { CorsOptions } from './cors'