@rexeus/typeweaver-server 0.6.2 → 0.6.4

package/README.md

@@ -261,6 +261,35 @@ type AppState = InferState<typeof app>;
 Middleware runs for **all** requests, including 404s and 405s, so global concerns like logging and
 CORS always execute.
 
+### 📦 Built-in Middleware
+
+Ready-to-use middleware included with the server plugin.
+
+| Middleware                                                                                                          | Description                          | State           |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------- |
+| [`cors`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/cors.md)                    | CORS headers & preflight handling    | —               |
+| [`basicAuth`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/basic-auth.md)         | HTTP Basic Authentication            | `{ username }`  |
+| [`bearerAuth`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/bearer-auth.md)       | HTTP Bearer Token Authentication     | `{ token }`     |
+| [`logger`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/logger.md)                | Request/response logging with timing | —               |
+| [`secureHeaders`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/secure-headers.md) | OWASP security headers               | —               |
+| [`requestId`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/request-id.md)         | Request ID generation & propagation  | `{ requestId }` |
+| [`poweredBy`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/powered-by.md)         | `X-Powered-By` header                | —               |
+| [`scoped` / `except`](https://github.com/rexeus/typeweaver/blob/main/packages/server/docs/middleware/scoped.md)     | Path-based middleware filtering      | —               |
+
+```ts
+import { cors, logger, secureHeaders, bearerAuth, requestId } from "@rexeus/typeweaver-server";
+
+const app = new TypeweaverApp()
+  .use(cors())
+  .use(secureHeaders())
+  .use(logger())
+  .use(requestId())
+  .use(bearerAuth({ verifyToken: verify }))
+  .route(new UserRouter({ requestHandlers }));
+```
+
+Each middleware is documented in detail — click the links above.
+
 ### 🛠️ App Options
 
 `TypeweaverApp` accepts an optional options object:

package/dist/lib/Router.ts

@@ -21,7 +21,7 @@ export type RouteDefinition = {
   readonly method: HttpMethod;
   readonly path: string;
   readonly validator: IRequestValidator;
-  readonly handler: RequestHandler;
+  readonly handler: RequestHandler<any, any, any>;
   /** Reference to the router config for error handling. */
   readonly routerConfig: RouterErrorConfig;
 };

package/dist/lib/TypeweaverRouter.ts

@@ -118,7 +118,7 @@ export abstract class TypeweaverRouter<
     method: HttpMethod,
     path: string,
     validator: IRequestValidator,
-    handler: RequestHandler
+    handler: RequestHandler<any, any, any>
   ): void {
     this.routes.push({
       method,

package/dist/lib/index.ts

@@ -36,3 +36,22 @@ export {
 export { FetchApiAdapter } from "./FetchApiAdapter";
 export { nodeAdapter, type NodeAdapterOptions } from "./NodeAdapter";
 export { pathMatcher } from "./PathMatcher";
+export {
+  basicAuth,
+  type BasicAuthOptions,
+  bearerAuth,
+  type BearerAuthOptions,
+  cors,
+  type CorsOptions,
+  except,
+  logger,
+  type LogData,
+  type LoggerOptions,
+  poweredBy,
+  type PoweredByOptions,
+  requestId,
+  type RequestIdOptions,
+  scoped,
+  secureHeaders,
+  type SecureHeadersOptions,
+} from "./middleware/index";

package/dist/lib/middleware/basicAuth.ts

@@ -0,0 +1,64 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+import type { ServerContext } from "../ServerContext";
+
+export type BasicAuthOptions = {
+  readonly verifyCredentials: (
+    username: string,
+    password: string,
+    ctx: ServerContext
+  ) => boolean | Promise<boolean>;
+  readonly realm?: string;
+  readonly unauthorizedMessage?: string;
+  readonly onUnauthorized?: (ctx: ServerContext) => IHttpResponse;
+};
+
+const BASIC_PREFIX = "Basic ";
+
+export function basicAuth(options: BasicAuthOptions) {
+  const realm = options.realm ?? "Secure Area";
+  const message = options.unauthorizedMessage ?? "Unauthorized";
+
+  const defaultResponse: IHttpResponse = {
+    statusCode: 401,
+    header: { "www-authenticate": `Basic realm="${realm}"` },
+    body: { code: "UNAUTHORIZED", message },
+  };
+
+  const deny = (ctx: ServerContext): IHttpResponse =>
+    options.onUnauthorized?.(ctx) ?? defaultResponse;
+
+  return defineMiddleware<{ username: string }>(async (ctx, next) => {
+    const authorization = ctx.request.header?.["authorization"];
+    if (typeof authorization !== "string") return deny(ctx);
+
+    if (!authorization.startsWith(BASIC_PREFIX)) return deny(ctx);
+
+    const encoded = authorization.slice(BASIC_PREFIX.length);
+    if (encoded.length === 0) return deny(ctx);
+
+    let decoded: string;
+    try {
+      decoded = atob(encoded);
+    } catch {
+      return deny(ctx);
+    }
+
+    const colonIndex = decoded.indexOf(":");
+    if (colonIndex <= 0) return deny(ctx);
+
+    const username = decoded.slice(0, colonIndex);
+    const password = decoded.slice(colonIndex + 1);
+
+    let valid: boolean;
+    try {
+      valid = await options.verifyCredentials(username, password, ctx);
+    } catch {
+      return deny(ctx);
+    }
+
+    if (!valid) return deny(ctx);
+
+    return next({ username });
+  });
+}

package/dist/lib/middleware/bearerAuth.ts

@@ -0,0 +1,50 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+import type { ServerContext } from "../ServerContext";
+
+export type BearerAuthOptions = {
+  readonly verifyToken: (
+    token: string,
+    ctx: ServerContext
+  ) => boolean | Promise<boolean>;
+  readonly realm?: string;
+  readonly unauthorizedMessage?: string;
+  readonly onUnauthorized?: (ctx: ServerContext) => IHttpResponse;
+};
+
+const BEARER_PREFIX = "Bearer ";
+
+export function bearerAuth(options: BearerAuthOptions) {
+  const realm = options.realm ?? "Secure Area";
+  const message = options.unauthorizedMessage ?? "Unauthorized";
+
+  const defaultResponse: IHttpResponse = {
+    statusCode: 401,
+    header: { "www-authenticate": `Bearer realm="${realm}"` },
+    body: { code: "UNAUTHORIZED", message },
+  };
+
+  const deny = (ctx: ServerContext): IHttpResponse =>
+    options.onUnauthorized?.(ctx) ?? defaultResponse;
+
+  return defineMiddleware<{ token: string }>(async (ctx, next) => {
+    const authorization = ctx.request.header?.["authorization"];
+    if (typeof authorization !== "string") return deny(ctx);
+
+    if (!authorization.startsWith(BEARER_PREFIX)) return deny(ctx);
+
+    const token = authorization.slice(BEARER_PREFIX.length);
+    if (token.length === 0) return deny(ctx);
+
+    let valid: boolean;
+    try {
+      valid = await options.verifyToken(token, ctx);
+    } catch {
+      return deny(ctx);
+    }
+
+    if (!valid) return deny(ctx);
+
+    return next({ token });
+  });
+}

package/dist/lib/middleware/cors.ts

@@ -0,0 +1,119 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+
+export type CorsOptions = {
+  readonly origin?:
+    | string
+    | readonly string[]
+    | ((origin: string) => string | undefined);
+  readonly allowMethods?: readonly string[];
+  readonly allowHeaders?: readonly string[];
+  readonly exposeHeaders?: readonly string[];
+  readonly maxAge?: number;
+  readonly credentials?: boolean;
+};
+
+const DEFAULT_METHODS = [
+  "GET",
+  "HEAD",
+  "PUT",
+  "POST",
+  "PATCH",
+  "DELETE",
+] as const;
+
+function resolveOrigin(
+  configOrigin: CorsOptions["origin"],
+  requestOrigin: string | undefined,
+  credentials: boolean
+): string | undefined {
+  if (configOrigin === undefined || configOrigin === "*") {
+    if (credentials && requestOrigin) return requestOrigin;
+    return "*";
+  }
+
+  if (typeof configOrigin === "function") {
+    return requestOrigin ? configOrigin(requestOrigin) : undefined;
+  }
+
+  if (typeof configOrigin === "string") {
+    return configOrigin;
+  }
+
+  return requestOrigin && configOrigin.includes(requestOrigin)
+    ? requestOrigin
+    : undefined;
+}
+
+function getRequestOrigin(
+  header: Record<string, string | string[]> | undefined
+): string | undefined {
+  const origin = header?.["origin"];
+  return typeof origin === "string" ? origin : undefined;
+}
+
+export function cors(options?: CorsOptions) {
+  const credentials = options?.credentials ?? false;
+  const methods = (options?.allowMethods ?? DEFAULT_METHODS).join(", ");
+  const exposeHeaders = options?.exposeHeaders?.join(", ");
+  const maxAge = options?.maxAge?.toString();
+
+  return defineMiddleware(async (ctx, next) => {
+    const requestOrigin = getRequestOrigin(ctx.request.header);
+    const origin = resolveOrigin(options?.origin, requestOrigin, credentials);
+
+    if (origin === undefined) return next();
+
+    const corsHeaders: Record<string, string> = {
+      "access-control-allow-origin": origin,
+    };
+
+    if (credentials) {
+      corsHeaders["access-control-allow-credentials"] = "true";
+    }
+
+    if (origin !== "*") {
+      corsHeaders["vary"] = "Origin";
+    }
+
+    if (exposeHeaders) {
+      corsHeaders["access-control-expose-headers"] = exposeHeaders;
+    }
+
+    const isPreflight =
+      ctx.request.method === "OPTIONS" &&
+      ctx.request.header?.["access-control-request-method"] !== undefined;
+
+    if (isPreflight) {
+      corsHeaders["access-control-allow-methods"] = methods;
+
+      const configuredHeaders = options?.allowHeaders;
+      if (configuredHeaders && configuredHeaders.length > 0) {
+        corsHeaders["access-control-allow-headers"] =
+          configuredHeaders.join(", ");
+      } else {
+        const requestedHeaders =
+          ctx.request.header?.["access-control-request-headers"];
+        if (typeof requestedHeaders === "string") {
+          corsHeaders["access-control-allow-headers"] = requestedHeaders;
+        }
+      }
+
+      if (maxAge) {
+        corsHeaders["access-control-max-age"] = maxAge;
+      }
+
+      return {
+        statusCode: 204,
+        header: corsHeaders,
+      } satisfies IHttpResponse;
+    }
+
+    const response = await next();
+
+    return {
+      ...response,
+      header: { ...corsHeaders, ...response.header },
+    } satisfies IHttpResponse;
+  });
+}

package/dist/lib/middleware/index.ts

@@ -0,0 +1,8 @@
+export { basicAuth, type BasicAuthOptions } from "./basicAuth";
+export { bearerAuth, type BearerAuthOptions } from "./bearerAuth";
+export { cors, type CorsOptions } from "./cors";
+export { logger, type LogData, type LoggerOptions } from "./logger";
+export { poweredBy, type PoweredByOptions } from "./poweredBy";
+export { requestId, type RequestIdOptions } from "./requestId";
+export { scoped, except } from "./scoped";
+export { secureHeaders, type SecureHeadersOptions } from "./secureHeaders";

package/dist/lib/middleware/logger.ts

@@ -0,0 +1,38 @@
+import { defineMiddleware } from "../TypedMiddleware";
+
+export type LogData = {
+  readonly method: string;
+  readonly path: string;
+  readonly statusCode: number;
+  readonly durationMs: number;
+};
+
+export type LoggerOptions = {
+  readonly logFn?: (message: string) => void;
+  readonly format?: (data: LogData) => string;
+};
+
+const defaultFormat = (data: LogData): string =>
+  `${data.method} ${data.path} ${data.statusCode} ${data.durationMs}ms`;
+
+export function logger(options?: LoggerOptions) {
+  const logFn = options?.logFn ?? console.log;
+  const format = options?.format ?? defaultFormat;
+
+  return defineMiddleware(async (ctx, next) => {
+    const start = performance.now();
+    const response = await next();
+    const durationMs = Math.round(performance.now() - start);
+
+    logFn(
+      format({
+        method: ctx.request.method,
+        path: ctx.request.path,
+        statusCode: response.statusCode,
+        durationMs,
+      })
+    );
+
+    return response;
+  });
+}

package/dist/lib/middleware/poweredBy.ts

@@ -0,0 +1,19 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+
+export type PoweredByOptions = {
+  readonly name?: string;
+};
+
+export function poweredBy(options?: PoweredByOptions) {
+  const value = options?.name ?? "TypeWeaver";
+
+  return defineMiddleware(async (_ctx, next) => {
+    const response = await next();
+
+    return {
+      ...response,
+      header: { ...response.header, "x-powered-by": value },
+    } satisfies IHttpResponse;
+  });
+}

package/dist/lib/middleware/requestId.ts

@@ -0,0 +1,29 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+
+export type RequestIdOptions = {
+  readonly headerName?: string;
+  readonly generator?: () => string;
+};
+
+export function requestId(options?: RequestIdOptions) {
+  const headerName = (options?.headerName ?? "x-request-id").toLowerCase();
+  const generator = options?.generator ?? (() => crypto.randomUUID());
+
+  return defineMiddleware<{ requestId: string }>(async (ctx, next) => {
+    const existing = ctx.request.header?.[headerName];
+    const id =
+      typeof existing === "string"
+        ? existing
+        : Array.isArray(existing)
+          ? (existing[0] ?? generator())
+          : generator();
+
+    const response = await next({ requestId: id });
+
+    return {
+      ...response,
+      header: { ...response.header, [headerName]: id },
+    } satisfies IHttpResponse;
+  });
+}

package/dist/lib/middleware/scoped.ts

@@ -0,0 +1,56 @@
+import { pathMatcher } from "../PathMatcher";
+import { defineMiddleware } from "../TypedMiddleware";
+import type { TypedMiddleware } from "../TypedMiddleware";
+
+/**
+ * Restricts a middleware to only run on paths matching the given patterns.
+ *
+ * Accepts the same pattern syntax as {@link pathMatcher}: exact (`"/users"`),
+ * prefix (`"/api/*"`), and parameterized (`"/users/:id"`).
+ *
+ * Only accepts non-state middleware (`TypedMiddleware<{}, {}>`) to preserve
+ * TypeWeaver's compile-time state guarantees — skipping a state-providing
+ * middleware would leave downstream consumers with missing state.
+ *
+ * @example
+ * ```typescript
+ * app.use(scoped(["/api/*"], cors({ origin: "https://app.com" })));
+ * ```
+ */
+export function scoped(
+  paths: readonly string[],
+  middleware: TypedMiddleware<{}, {}>
+): TypedMiddleware<{}, {}> {
+  const matchers = paths.map(pathMatcher);
+
+  return defineMiddleware(async (ctx, next) => {
+    if (!matchers.some(match => match(ctx.request.path))) {
+      return next();
+    }
+    return middleware.handler(ctx, next);
+  });
+}
+
+/**
+ * Runs a middleware on all paths *except* those matching the given patterns.
+ *
+ * The inverse of {@link scoped}. Same pattern syntax and type constraint.
+ *
+ * @example
+ * ```typescript
+ * app.use(except(["/health", "/ready"], logger()));
+ * ```
+ */
+export function except(
+  paths: readonly string[],
+  middleware: TypedMiddleware<{}, {}>
+): TypedMiddleware<{}, {}> {
+  const matchers = paths.map(pathMatcher);
+
+  return defineMiddleware(async (ctx, next) => {
+    if (matchers.some(match => match(ctx.request.path))) {
+      return next();
+    }
+    return middleware.handler(ctx, next);
+  });
+}

package/dist/lib/middleware/secureHeaders.ts

@@ -0,0 +1,57 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { defineMiddleware } from "../TypedMiddleware";
+
+export type SecureHeadersOptions = {
+  readonly contentTypeOptions?: string | false;
+  readonly frameOptions?: string | false;
+  readonly strictTransportSecurity?: string | false;
+  readonly referrerPolicy?: string | false;
+  readonly xssProtection?: string | false;
+  readonly downloadOptions?: string | false;
+  readonly dnsPrefetchControl?: string | false;
+  readonly permittedCrossDomainPolicies?: string | false;
+  readonly crossOriginResourcePolicy?: string | false;
+  readonly crossOriginOpenerPolicy?: string | false;
+  readonly crossOriginEmbedderPolicy?: string | false;
+  readonly originAgentCluster?: string | false;
+};
+
+const DEFAULTS: ReadonlyArray<
+  readonly [keyof SecureHeadersOptions, string, string]
+> = [
+  ["contentTypeOptions", "x-content-type-options", "nosniff"],
+  ["frameOptions", "x-frame-options", "SAMEORIGIN"],
+  [
+    "strictTransportSecurity",
+    "strict-transport-security",
+    "max-age=15552000; includeSubDomains",
+  ],
+  ["referrerPolicy", "referrer-policy", "no-referrer"],
+  ["xssProtection", "x-xss-protection", "0"],
+  ["downloadOptions", "x-download-options", "noopen"],
+  ["dnsPrefetchControl", "x-dns-prefetch-control", "off"],
+  ["permittedCrossDomainPolicies", "x-permitted-cross-domain-policies", "none"],
+  ["crossOriginResourcePolicy", "cross-origin-resource-policy", "same-origin"],
+  ["crossOriginOpenerPolicy", "cross-origin-opener-policy", "same-origin"],
+  ["crossOriginEmbedderPolicy", "cross-origin-embedder-policy", "require-corp"],
+  ["originAgentCluster", "origin-agent-cluster", "?1"],
+];
+
+export function secureHeaders(options?: SecureHeadersOptions) {
+  const headers: Record<string, string> = {};
+
+  for (const [optionKey, headerName, defaultValue] of DEFAULTS) {
+    const value = options?.[optionKey];
+    if (value === false) continue;
+    headers[headerName] = value ?? defaultValue;
+  }
+
+  return defineMiddleware(async (_ctx, next) => {
+    const response = await next();
+
+    return {
+      ...response,
+      header: { ...headers, ...response.header },
+    } satisfies IHttpResponse;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexeus/typeweaver-server",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Generates a lightweight, dependency-free server with built-in routing and middleware from your API definitions. Powered by Typeweaver.",
   "type": "module",
   "sideEffects": false,
@@ -47,15 +47,15 @@
   },
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
-    "@rexeus/typeweaver-core": "^0.6.2",
-    "@rexeus/typeweaver-gen": "^0.6.2"
+    "@rexeus/typeweaver-gen": "^0.6.4",
+    "@rexeus/typeweaver-core": "^0.6.4"
   },
   "devDependencies": {
     "get-port": "^7.1.0",
     "test-utils": "file:../test-utils",
     "tsx": "^4.21.0",
-    "@rexeus/typeweaver-core": "^0.6.2",
-    "@rexeus/typeweaver-gen": "^0.6.2"
+    "@rexeus/typeweaver-gen": "^0.6.4",
+    "@rexeus/typeweaver-core": "^0.6.4"
   },
   "dependencies": {
     "case": "^1.6.3"