@mandujs/core 0.53.2 → 0.54.0

package/src/middleware/define.ts

@@ -1,132 +1,132 @@
-/**
- * Canonical Middleware Composition API — Phase 18.ε
- *
- * This module defines Mandu's request-level middleware contract. It is the
- * runtime analogue of Next.js `middleware.ts` and SvelteKit's `hooks.server.ts`
- * `handle` sequence: each middleware is a thin onion layer that wraps the
- * final route handler, can short-circuit by returning a Response without
- * calling `next()`, and executes in declaration order (outermost first).
- *
- * This API is intentionally **request-level**, not context-level:
- *
- *   - `filling().use(...)` / `MiddlewarePlugin` — operates on a per-route
- *     `ManduContext`. Good for inline concerns like `csrf()` / `session()`
- *     / `secure()` that a single filling chain wants to compose.
- *
- *   - `Middleware` / `compose()` (this module) — operates on the raw
- *     `Request` BEFORE route dispatch. Good for app-wide policies:
- *     auth gates, tenant resolution, rate limiting, request logging,
- *     rewrites, redirects.
- *
- * Both APIs co-exist. Bridge wrappers live alongside each individual
- * middleware module (e.g. `csrf.ts` exports `csrfMiddleware(...)`) so users
- * who want the canonical composition API for an existing middleware can
- * plug it in without boilerplate.
- *
- * @example
- * ```ts
- * import { defineMiddleware, compose } from "@mandujs/core/middleware";
- *
- * const requestId = defineMiddleware({
- *   name: "request-id",
- *   async handler(req, next) {
- *     const id = req.headers.get("x-request-id") ?? crypto.randomUUID();
- *     const res = await next();
- *     res.headers.set("x-request-id", id);
- *     return res;
- *   },
- * });
- *
- * const authGate = defineMiddleware({
- *   name: "auth-gate",
- *   match: (req) => new URL(req.url).pathname.startsWith("/admin"),
- *   async handler(req, next) {
- *     if (!req.headers.get("authorization")) {
- *       return new Response("Unauthorized", { status: 401 });
- *     }
- *     return next();
- *   },
- * });
- *
- * // In mandu.config.ts:
- * export default {
- *   middleware: [requestId, authGate],
- * } satisfies ManduConfig;
- * ```
- */
-
-/**
- * A request-level middleware. Runs BEFORE route dispatch in declaration order.
- *
- *   - `name` identifies the middleware in error messages and diagnostic traces.
- *   - `match?` is an optional filter: middleware whose `match(req)` returns
- *     `false` are skipped (the chain proceeds to the next middleware). Absent
- *     means "always match".
- *   - `handler(req, next)` does the actual work. Return a Response directly
- *     to short-circuit (downstream middleware and the route handler are
- *     skipped). Call `next()` to invoke the rest of the chain and receive
- *     its Response — at which point you may mutate headers, re-wrap the
- *     body, log, etc.
- *
- * The `req` argument is the Request the current layer sees; a middleware
- * may pass a modified Request to `next()` by calling it with a Request
- * argument (rewrite pattern). When called with no argument, `next()` uses
- * the Request passed into the handler.
- */
-export interface Middleware {
-  /** Display name used in diagnostics. Must be non-empty. */
-  name: string;
-  /**
-   * Optional route filter. When present and returns `false`, the chain
-   * skips this middleware entirely (proceeds to the next layer / final
-   * handler). When absent the middleware matches all requests.
-   *
-   * Must be synchronous and side-effect-free — `match` runs once per
-   * request per middleware and any throw short-circuits the chain with
-   * a 500 response.
-   */
-  match?: (req: Request) => boolean;
-  /**
-   * Middleware handler. Receives the current Request and a `next()` thunk
-   * that invokes the rest of the chain (or the final route handler, if
-   * this is the innermost middleware). Must return a Response.
-   *
-   * - Call `next()` to continue the chain with the same request.
-   * - Call `next(modifiedReq)` to continue with a rewritten request
-   *   (downstream middleware and the final handler see `modifiedReq`).
-   * - Return a Response directly WITHOUT calling `next()` to short-circuit.
-   */
-  handler: (
-    req: Request,
-    next: (req?: Request) => Promise<Response>
-  ) => Promise<Response>;
-}
-
-/**
- * Ergonomic helper — passes the middleware object through unchanged but
- * preserves full type inference and documents intent at the call site.
- * Mirrors Next.js `defineMiddleware()` and SvelteKit `Handle` exports.
- *
- * @throws {TypeError} when `m` is missing `name` or `handler`, or when
- *   `name` is empty. Fail-fast at definition time — we do NOT want a
- *   silent no-op layer corrupting a composition chain.
- */
-export function defineMiddleware(m: Middleware): Middleware {
-  if (!m || typeof m !== "object") {
-    throw new TypeError("[Mandu Middleware] defineMiddleware requires an object");
-  }
-  if (typeof m.name !== "string" || m.name.length === 0) {
-    throw new TypeError("[Mandu Middleware] defineMiddleware requires a non-empty `name`");
-  }
-  if (typeof m.handler !== "function") {
-    throw new TypeError(
-      `[Mandu Middleware] defineMiddleware requires a \`handler\` function (middleware "${m.name}")`
-    );
-  }
-  if (m.match !== undefined && typeof m.match !== "function") {
-    throw new TypeError(
-      `[Mandu Middleware] \`match\` must be a function when provided (middleware "${m.name}")`
-    );
-  }
-  return m;
-}
+/**
+ * Canonical Middleware Composition API — Phase 18.ε
+ *
+ * This module defines Mandu's request-level middleware contract. It is the
+ * runtime analogue of Next.js `middleware.ts` and SvelteKit's `hooks.server.ts`
+ * `handle` sequence: each middleware is a thin onion layer that wraps the
+ * final route handler, can short-circuit by returning a Response without
+ * calling `next()`, and executes in declaration order (outermost first).
+ *
+ * This API is intentionally **request-level**, not context-level:
+ *
+ *   - `filling().use(...)` / `MiddlewarePlugin` — operates on a per-route
+ *     `ManduContext`. Good for inline concerns like `csrf()` / `session()`
+ *     / `secure()` that a single filling chain wants to compose.
+ *
+ *   - `Middleware` / `compose()` (this module) — operates on the raw
+ *     `Request` BEFORE route dispatch. Good for app-wide policies:
+ *     auth gates, tenant resolution, rate limiting, request logging,
+ *     rewrites, redirects.
+ *
+ * Both APIs co-exist. Bridge wrappers live alongside each individual
+ * middleware module (e.g. `csrf.ts` exports `csrfMiddleware(...)`) so users
+ * who want the canonical composition API for an existing middleware can
+ * plug it in without boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { defineMiddleware, compose } from "@mandujs/core/middleware";
+ *
+ * const requestId = defineMiddleware({
+ *   name: "request-id",
+ *   async handler(req, next) {
+ *     const id = req.headers.get("x-request-id") ?? crypto.randomUUID();
+ *     const res = await next();
+ *     res.headers.set("x-request-id", id);
+ *     return res;
+ *   },
+ * });
+ *
+ * const authGate = defineMiddleware({
+ *   name: "auth-gate",
+ *   match: (req) => new URL(req.url).pathname.startsWith("/admin"),
+ *   async handler(req, next) {
+ *     if (!req.headers.get("authorization")) {
+ *       return new Response("Unauthorized", { status: 401 });
+ *     }
+ *     return next();
+ *   },
+ * });
+ *
+ * // In mandu.config.ts:
+ * export default {
+ *   middleware: [requestId, authGate],
+ * } satisfies ManduConfig;
+ * ```
+ */
+
+/**
+ * A request-level middleware. Runs BEFORE route dispatch in declaration order.
+ *
+ *   - `name` identifies the middleware in error messages and diagnostic traces.
+ *   - `match?` is an optional filter: middleware whose `match(req)` returns
+ *     `false` are skipped (the chain proceeds to the next middleware). Absent
+ *     means "always match".
+ *   - `handler(req, next)` does the actual work. Return a Response directly
+ *     to short-circuit (downstream middleware and the route handler are
+ *     skipped). Call `next()` to invoke the rest of the chain and receive
+ *     its Response — at which point you may mutate headers, re-wrap the
+ *     body, log, etc.
+ *
+ * The `req` argument is the Request the current layer sees; a middleware
+ * may pass a modified Request to `next()` by calling it with a Request
+ * argument (rewrite pattern). When called with no argument, `next()` uses
+ * the Request passed into the handler.
+ */
+export interface Middleware {
+  /** Display name used in diagnostics. Must be non-empty. */
+  name: string;
+  /**
+   * Optional route filter. When present and returns `false`, the chain
+   * skips this middleware entirely (proceeds to the next layer / final
+   * handler). When absent the middleware matches all requests.
+   *
+   * Must be synchronous and side-effect-free — `match` runs once per
+   * request per middleware and any throw short-circuits the chain with
+   * a 500 response.
+   */
+  match?: (req: Request) => boolean;
+  /**
+   * Middleware handler. Receives the current Request and a `next()` thunk
+   * that invokes the rest of the chain (or the final route handler, if
+   * this is the innermost middleware). Must return a Response.
+   *
+   * - Call `next()` to continue the chain with the same request.
+   * - Call `next(modifiedReq)` to continue with a rewritten request
+   *   (downstream middleware and the final handler see `modifiedReq`).
+   * - Return a Response directly WITHOUT calling `next()` to short-circuit.
+   */
+  handler: (
+    req: Request,
+    next: (req?: Request) => Promise<Response>
+  ) => Promise<Response>;
+}
+
+/**
+ * Ergonomic helper — passes the middleware object through unchanged but
+ * preserves full type inference and documents intent at the call site.
+ * Mirrors Next.js `defineMiddleware()` and SvelteKit `Handle` exports.
+ *
+ * @throws {TypeError} when `m` is missing `name` or `handler`, or when
+ *   `name` is empty. Fail-fast at definition time — we do NOT want a
+ *   silent no-op layer corrupting a composition chain.
+ */
+export function defineMiddleware(m: Middleware): Middleware {
+  if (!m || typeof m !== "object") {
+    throw new TypeError("[Mandu Middleware] defineMiddleware requires an object");
+  }
+  if (typeof m.name !== "string" || m.name.length === 0) {
+    throw new TypeError("[Mandu Middleware] defineMiddleware requires a non-empty `name`");
+  }
+  if (typeof m.handler !== "function") {
+    throw new TypeError(
+      `[Mandu Middleware] defineMiddleware requires a \`handler\` function (middleware "${m.name}")`
+    );
+  }
+  if (m.match !== undefined && typeof m.match !== "function") {
+    throw new TypeError(
+      `[Mandu Middleware] \`match\` must be a function when provided (middleware "${m.name}")`
+    );
+  }
+  return m;
+}

package/src/middleware/jwt.ts

@@ -1,134 +1,134 @@
-/**
- * JWT Middleware Plugin
- * filling.use(jwt({ secret: process.env.JWT_SECRET }))
- */
-
-import type { ManduContext } from "../filling/context";
-
-export interface JwtMiddlewareOptions {
-  /** JWT 시크릿 키 */
-  secret: string;
-  /** 허용할 알고리즘 (기본: ["HS256"]) */
-  algorithms?: ("HS256" | "HS384" | "HS512")[];
-  /** 토큰 추출 위치 (기본: Authorization 헤더) */
-  extractFrom?: "header" | "cookie";
-  /** 쿠키 이름 (extractFrom: "cookie" 일 때) */
-  cookieName?: string;
-  /** ctx.set()에 저장할 키 (기본: "user") */
-  storeAs?: string;
-}
-
-/**
- * JWT 인증 미들웨어
- *
- * @example
- * ```typescript
- * import { jwt } from "@mandujs/core/middleware";
- *
- * export default Mandu.filling()
- *   .use(jwt({ secret: process.env.JWT_SECRET! }))
- *   .get((ctx) => {
- *     const user = ctx.get("user");
- *     return ctx.ok({ user });
- *   });
- * ```
- */
-export function jwt(options: JwtMiddlewareOptions) {
-  const { secret, algorithms = ["HS256"], extractFrom = "header", cookieName = "token", storeAs = "user" } = options;
-
-  return async (ctx: ManduContext): Promise<Response | void> => {
-    let token: string | null = null;
-
-    if (extractFrom === "header") {
-      const auth = ctx.headers.get("Authorization");
-      if (auth?.startsWith("Bearer ")) {
-        token = auth.slice(7);
-      }
-    } else {
-      token = ctx.cookies.get(cookieName) ?? null;
-    }
-
-    if (!token) {
-      return ctx.unauthorized("Missing authentication token");
-    }
-
-    // 토큰 크기 제한 (메모리 소모 공격 방지)
-    if (token.length > 8192) {
-      return ctx.unauthorized("Token too large");
-    }
-
-    try {
-      // Bun native JWT verification
-      const payload = await verifyJwtToken(token, secret, algorithms);
-      ctx.set(storeAs, payload);
-    } catch {
-      return ctx.unauthorized("Invalid or expired token");
-    }
-  };
-}
-
-const ALG_MAP: Record<string, string> = {
-  HS256: "SHA-256",
-  HS384: "SHA-384",
-  HS512: "SHA-512",
-};
-
-/** JWT 검증 (Bun crypto 기반, HS256/HS384/HS512 지원) */
-async function verifyJwtToken(
-  token: string,
-  secret: string,
-  allowedAlgorithms: string[]
-): Promise<Record<string, unknown>> {
-  const parts = token.split(".");
-  if (parts.length !== 3) throw new Error("Invalid JWT format");
-
-  const [headerB64, payloadB64, signatureB64] = parts;
-
-  // 헤더에서 알고리즘 확인
-  const header = JSON.parse(atob(headerB64.replace(/-/g, "+").replace(/_/g, "/")));
-  const alg = header.alg as string;
-  if (!allowedAlgorithms.includes(alg)) {
-    throw new Error(`Algorithm "${alg}" not allowed. Allowed: ${allowedAlgorithms.join(", ")}`);
-  }
-
-  const hash = ALG_MAP[alg];
-  if (!hash) throw new Error(`Unsupported algorithm: ${alg}`);
-
-  // 서명 검증
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash },
-    false,
-    ["verify"]
-  );
-
-  const data = encoder.encode(`${headerB64}.${payloadB64}`);
-  const signature = base64UrlDecode(signatureB64);
-
-  const valid = await crypto.subtle.verify("HMAC", key, signature as BufferSource, data);
-  if (!valid) throw new Error("Invalid signature");
-
-  // 페이로드 디코딩
-  const payload = JSON.parse(atob(payloadB64.replace(/-/g, "+").replace(/_/g, "/")));
-
-  // 만료 확인
-  if (payload.exp && payload.exp * 1000 < Date.now()) {
-    throw new Error("Token expired");
-  }
-
-  // nbf (not-before) 확인 — 아직 유효하지 않은 토큰 거부
-  if (payload.nbf && payload.nbf * 1000 > Date.now()) {
-    throw new Error("Token not yet valid");
-  }
-
-  return payload;
-}
-
-function base64UrlDecode(str: string): Uint8Array {
-  const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
-  const binary = atob(padded);
-  return Uint8Array.from(binary, c => c.charCodeAt(0));
-}
+/**
+ * JWT Middleware Plugin
+ * filling.use(jwt({ secret: process.env.JWT_SECRET }))
+ */
+
+import type { ManduContext } from "../filling/context";
+
+export interface JwtMiddlewareOptions {
+  /** JWT 시크릿 키 */
+  secret: string;
+  /** 허용할 알고리즘 (기본: ["HS256"]) */
+  algorithms?: ("HS256" | "HS384" | "HS512")[];
+  /** 토큰 추출 위치 (기본: Authorization 헤더) */
+  extractFrom?: "header" | "cookie";
+  /** 쿠키 이름 (extractFrom: "cookie" 일 때) */
+  cookieName?: string;
+  /** ctx.set()에 저장할 키 (기본: "user") */
+  storeAs?: string;
+}
+
+/**
+ * JWT 인증 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { jwt } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(jwt({ secret: process.env.JWT_SECRET! }))
+ *   .get((ctx) => {
+ *     const user = ctx.get("user");
+ *     return ctx.ok({ user });
+ *   });
+ * ```
+ */
+export function jwt(options: JwtMiddlewareOptions) {
+  const { secret, algorithms = ["HS256"], extractFrom = "header", cookieName = "token", storeAs = "user" } = options;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    let token: string | null = null;
+
+    if (extractFrom === "header") {
+      const auth = ctx.headers.get("Authorization");
+      if (auth?.startsWith("Bearer ")) {
+        token = auth.slice(7);
+      }
+    } else {
+      token = ctx.cookies.get(cookieName) ?? null;
+    }
+
+    if (!token) {
+      return ctx.unauthorized("Missing authentication token");
+    }
+
+    // 토큰 크기 제한 (메모리 소모 공격 방지)
+    if (token.length > 8192) {
+      return ctx.unauthorized("Token too large");
+    }
+
+    try {
+      // Bun native JWT verification
+      const payload = await verifyJwtToken(token, secret, algorithms);
+      ctx.set(storeAs, payload);
+    } catch {
+      return ctx.unauthorized("Invalid or expired token");
+    }
+  };
+}
+
+const ALG_MAP: Record<string, string> = {
+  HS256: "SHA-256",
+  HS384: "SHA-384",
+  HS512: "SHA-512",
+};
+
+/** JWT 검증 (Bun crypto 기반, HS256/HS384/HS512 지원) */
+async function verifyJwtToken(
+  token: string,
+  secret: string,
+  allowedAlgorithms: string[]
+): Promise<Record<string, unknown>> {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("Invalid JWT format");
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // 헤더에서 알고리즘 확인
+  const header = JSON.parse(atob(headerB64.replace(/-/g, "+").replace(/_/g, "/")));
+  const alg = header.alg as string;
+  if (!allowedAlgorithms.includes(alg)) {
+    throw new Error(`Algorithm "${alg}" not allowed. Allowed: ${allowedAlgorithms.join(", ")}`);
+  }
+
+  const hash = ALG_MAP[alg];
+  if (!hash) throw new Error(`Unsupported algorithm: ${alg}`);
+
+  // 서명 검증
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash },
+    false,
+    ["verify"]
+  );
+
+  const data = encoder.encode(`${headerB64}.${payloadB64}`);
+  const signature = base64UrlDecode(signatureB64);
+
+  const valid = await crypto.subtle.verify("HMAC", key, signature as BufferSource, data);
+  if (!valid) throw new Error("Invalid signature");
+
+  // 페이로드 디코딩
+  const payload = JSON.parse(atob(payloadB64.replace(/-/g, "+").replace(/_/g, "/")));
+
+  // 만료 확인
+  if (payload.exp && payload.exp * 1000 < Date.now()) {
+    throw new Error("Token expired");
+  }
+
+  // nbf (not-before) 확인 — 아직 유효하지 않은 토큰 거부
+  if (payload.nbf && payload.nbf * 1000 > Date.now()) {
+    throw new Error("Token not yet valid");
+  }
+
+  return payload;
+}
+
+function base64UrlDecode(str: string): Uint8Array {
+  const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  return Uint8Array.from(binary, c => c.charCodeAt(0));
+}

package/src/middleware/logger.ts

@@ -1,58 +1,58 @@
-/**
- * Logger Middleware Plugin
- * filling.use(logger())
- */
-
-import type { MiddlewarePlugin } from "../filling/filling";
-import type { ManduContext } from "../filling/context";
-
-export interface LoggerMiddlewareOptions {
-  /** 로그 포맷 (기본: "short") */
-  format?: "short" | "detailed";
-  /** 커스텀 로거 (기본: console.log) */
-  log?: (message: string) => void;
-  /** 느린 요청 경고 임계값 (ms, 기본: 3000) */
-  slowThreshold?: number;
-}
-
-/**
- * 요청/응답 로깅 미들웨어
- *
- * @example
- * ```typescript
- * import { logger } from "@mandujs/core/middleware";
- *
- * export default Mandu.filling()
- *   .use(logger({ format: "detailed", slowThreshold: 1000 }))
- *   .get((ctx) => ctx.ok({ data: "logged" }));
- * ```
- */
-export function logger(options?: LoggerMiddlewareOptions): MiddlewarePlugin {
-  const format = options?.format ?? "short";
-  const log = options?.log ?? console.log;
-  const slowThreshold = options?.slowThreshold ?? 3000;
-
-  return {
-    beforeHandle: async (ctx: ManduContext): Promise<void> => {
-      ctx.set("_logger_start", Date.now());
-    },
-    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
-      const start = ctx.get<number>("_logger_start");
-      if (start === undefined) return response;
-
-      const duration = Date.now() - start;
-      const method = ctx.request.method;
-      const pathname = new URL(ctx.request.url).pathname;
-      const status = response.status;
-      const slow = duration > slowThreshold ? " ⚠️ SLOW" : "";
-
-      if (format === "detailed") {
-        log(`${method} ${pathname} → ${status} (${duration}ms)${slow}`);
-      } else {
-        log(`${method} ${pathname} ${status} ${duration}ms${slow}`);
-      }
-
-      return response;
-    },
-  };
-}
+/**
+ * Logger Middleware Plugin
+ * filling.use(logger())
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+
+export interface LoggerMiddlewareOptions {
+  /** 로그 포맷 (기본: "short") */
+  format?: "short" | "detailed";
+  /** 커스텀 로거 (기본: console.log) */
+  log?: (message: string) => void;
+  /** 느린 요청 경고 임계값 (ms, 기본: 3000) */
+  slowThreshold?: number;
+}
+
+/**
+ * 요청/응답 로깅 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { logger } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(logger({ format: "detailed", slowThreshold: 1000 }))
+ *   .get((ctx) => ctx.ok({ data: "logged" }));
+ * ```
+ */
+export function logger(options?: LoggerMiddlewareOptions): MiddlewarePlugin {
+  const format = options?.format ?? "short";
+  const log = options?.log ?? console.log;
+  const slowThreshold = options?.slowThreshold ?? 3000;
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<void> => {
+      ctx.set("_logger_start", Date.now());
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      const start = ctx.get<number>("_logger_start");
+      if (start === undefined) return response;
+
+      const duration = Date.now() - start;
+      const method = ctx.request.method;
+      const pathname = new URL(ctx.request.url).pathname;
+      const status = response.status;
+      const slow = duration > slowThreshold ? " ⚠️ SLOW" : "";
+
+      if (format === "detailed") {
+        log(`${method} ${pathname} → ${status} (${duration}ms)${slow}`);
+      } else {
+        log(`${method} ${pathname} ${status} ${duration}ms${slow}`);
+      }
+
+      return response;
+    },
+  };
+}

package/src/middleware/oauth/__tests__/oauth.test.ts

@@ -21,7 +21,7 @@ import {
 } from "../index";
 import { session, saveSession } from "../../session";
 import type {
-  Session} from "../../../filling/session";
+  Session} from "../../../filling/session";
 import {
   createCookieSessionStorage,
   type SessionStorage,