@withwiz/toolkit 0.1.0

package/dist/middleware/auth.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 인증 미들웨어
+ *
+ * - JWT 토큰 검증
+ * - Access Token 블랙리스트 체크
+ * - 사용자 정보 context에 추가
+ * - 인증 실패 시 401 에러
+ *
+ * 완전 독립적 패키지:
+ * @withwiz/auth/core/jwt를 사용하여 비즈니스 로직에 의존하지 않음
+ */
+import type { TApiMiddleware } from "./types";
+/**
+ * Access Token 블랙리스트 체커 인터페이스
+ * src/lib/services/auth/refreshTokenService에서 구현체 주입
+ */
+export interface IAccessTokenBlacklistChecker {
+    isAccessTokenRevoked(token: string): Promise<boolean>;
+}
+declare global {
+    var __accessTokenBlacklistChecker: IAccessTokenBlacklistChecker | undefined;
+}
+/**
+ * Access Token 블랙리스트 체커 설정
+ * 애플리케이션 시작 시 refreshTokenService를 주입
+ */
+export declare function setAccessTokenBlacklistChecker(checker: IAccessTokenBlacklistChecker): void;
+/**
+ * Auth Middleware 명시적 초기화
+ *
+ * instrumentation.ts에서 서버 시작 시 호출하여 JWT Manager를 미리 초기화합니다.
+ *
+ * @returns {boolean} 초기화 성공 여부
+ *
+ * @example
+ * ```typescript
+ * // instrumentation.ts
+ * import { initializeAuthMiddleware } from '@withwiz/middleware/auth';
+ *
+ * export async function register() {
+ *   initializeAuthMiddleware();
+ * }
+ * ```
+ */
+export declare function initializeAuthMiddleware(): boolean;
+/**
+ * 인증 미들웨어
+ *
+ * Authorization 헤더에서 JWT 토큰을 추출하고 검증합니다.
+ * 검증된 사용자 정보를 context.user에 추가합니다.
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(authMiddleware);
+ * ```
+ */
+export declare const authMiddleware: TApiMiddleware;
+/**
+ * 선택적 인증 미들웨어
+ *
+ * Authorization 헤더가 있으면 JWT 토큰을 검증하고 context.user를 설정합니다.
+ * 토큰이 없거나 유효하지 않아도 에러를 발생시키지 않고 계속 진행합니다.
+ * 공개 API이지만 로그인 사용자를 선택적으로 인식해야 하는 경우에 사용합니다.
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(optionalAuthMiddleware);
+ * // context.user가 설정되면 로그인 사용자, 아니면 비로그인
+ * ```
+ */
+export declare const optionalAuthMiddleware: TApiMiddleware;
+/**
+ * 관리자 권한 검증 미들웨어
+ *
+ * authMiddleware 이후에 실행되어야 합니다.
+ * context.user가 없거나 role이 admin이 아니면 403 에러를 발생시킵니다.
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(authMiddleware)
+ *   .use(adminMiddleware);
+ * ```
+ */
+export declare const adminMiddleware: TApiMiddleware;

package/dist/middleware/auth.js

@@ -0,0 +1,20 @@
+import {
+  adminMiddleware,
+  authMiddleware,
+  initializeAuthMiddleware,
+  optionalAuthMiddleware,
+  setAccessTokenBlacklistChecker
+} from "../chunk-UXQRU3EM.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-T3LJYAMO.js";
+import "../chunk-AIH3F7JV.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  adminMiddleware,
+  authMiddleware,
+  initializeAuthMiddleware,
+  optionalAuthMiddleware,
+  setAccessTokenBlacklistChecker
+};

package/dist/middleware/cors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CORS 미들웨어
+ *
+ * Cross-Origin Resource Sharing 헤더를 설정합니다.
+ */
+import type { TApiMiddleware } from './types';
+/**
+ * CORS 미들웨어
+ *
+ * - Origin 검증 및 CORS 헤더 설정
+ * - OPTIONS preflight 요청 처리
+ * - 크레덴셜 허용 설정
+ */
+export declare const corsMiddleware: TApiMiddleware;
+/**
+ * CORS 설정 검증 및 초기화
+ *
+ * instrumentation.ts에서 서버 시작 시 호출하여 CORS 설정을 검증하고 로그를 출력합니다.
+ *
+ * @example
+ * ```typescript
+ * // instrumentation.ts
+ * import { validateCorsConfiguration } from '@withwiz/middleware/cors';
+ *
+ * export async function register() {
+ *   validateCorsConfiguration();
+ * }
+ * ```
+ */
+export declare function validateCorsConfiguration(): void;

package/dist/middleware/cors.js

@@ -0,0 +1,10 @@
+import {
+  corsMiddleware,
+  validateCorsConfiguration
+} from "../chunk-FOKAATUQ.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  corsMiddleware,
+  validateCorsConfiguration
+};

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 에러 핸들러 미들웨어
+ *
+ * - 모든 에러를 잡아서 표준 형식의 JSON 응답으로 변환
+ * - AppError를 감지하여 적절한 HTTP 상태 코드 반환
+ * - ZodError를 감지하여 400 Bad Request 반환
+ * - 다중 언어 메시지 지원
+ */
+import type { TApiMiddleware } from './types';
+/**
+ * 에러 핸들러 미들웨어
+ *
+ * 체인의 최상위에 배치하여 모든 에러를 캐치합니다.
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(errorHandlerMiddleware)  // 가장 먼저
+ *   .use(initRequestMiddleware)
+ *   .use(authMiddleware);
+ * ```
+ */
+export declare const errorHandlerMiddleware: TApiMiddleware;

package/dist/middleware/error-handler.js

@@ -0,0 +1,13 @@
+import {
+  errorHandlerMiddleware
+} from "../chunk-TMVS4F7E.js";
+import "../chunk-EEUBKZV4.js";
+import "../chunk-N4YGR5WH.js";
+import "../chunk-KXAWBFJN.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  errorHandlerMiddleware
+};

package/dist/middleware/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * API 미들웨어 시스템
+ *
+ * 통합 에러 처리 시스템의 API 레이어
+ */
+export type { IApiContext, IUser, TApiHandler, TApiMiddleware, IMiddlewareChainOptions, } from './types';
+export { MiddlewareChain } from './middleware-chain';
+export { initRequestMiddleware } from './init-request';
+export { authMiddleware, optionalAuthMiddleware, adminMiddleware, initializeAuthMiddleware, setAccessTokenBlacklistChecker } from './auth';
+export type { IAccessTokenBlacklistChecker } from './auth';
+export { rateLimitMiddleware, createRateLimitMiddleware, setRateLimitAdapter } from './rate-limit';
+export { errorHandlerMiddleware } from './error-handler';
+export { responseLoggerMiddleware } from './response-logger';
+export { corsMiddleware, validateCorsConfiguration } from './cors';
+export { securityMiddleware, validateSecurityConfiguration } from './security';
+export { withPublicApi, withAuthApi, withAdminApi, withOptionalAuthApi, withCustomApi, } from './wrappers';

package/dist/middleware/index.js

@@ -0,0 +1,72 @@
+import {
+  withAdminApi,
+  withAuthApi,
+  withCustomApi,
+  withOptionalAuthApi,
+  withPublicApi
+} from "../chunk-SLG26KHZ.js";
+import {
+  MiddlewareChain
+} from "../chunk-4ODT3Q4A.js";
+import {
+  createRateLimitMiddleware,
+  rateLimitMiddleware,
+  setRateLimitAdapter
+} from "../chunk-H5I5GWAA.js";
+import {
+  responseLoggerMiddleware
+} from "../chunk-KAWVMIRJ.js";
+import {
+  securityMiddleware,
+  validateSecurityConfiguration
+} from "../chunk-WSQMXMTL.js";
+import {
+  adminMiddleware,
+  authMiddleware,
+  initializeAuthMiddleware,
+  optionalAuthMiddleware,
+  setAccessTokenBlacklistChecker
+} from "../chunk-UXQRU3EM.js";
+import {
+  corsMiddleware,
+  validateCorsConfiguration
+} from "../chunk-FOKAATUQ.js";
+import {
+  errorHandlerMiddleware
+} from "../chunk-TMVS4F7E.js";
+import {
+  initRequestMiddleware
+} from "../chunk-62Q7DN5G.js";
+import "../chunk-XHZ5L4FO.js";
+import "../chunk-EEUBKZV4.js";
+import "../chunk-N4YGR5WH.js";
+import "../chunk-KXAWBFJN.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-T3LJYAMO.js";
+import "../chunk-AIH3F7JV.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  MiddlewareChain,
+  adminMiddleware,
+  authMiddleware,
+  corsMiddleware,
+  createRateLimitMiddleware,
+  errorHandlerMiddleware,
+  initRequestMiddleware,
+  initializeAuthMiddleware,
+  optionalAuthMiddleware,
+  rateLimitMiddleware,
+  responseLoggerMiddleware,
+  securityMiddleware,
+  setAccessTokenBlacklistChecker,
+  setRateLimitAdapter,
+  validateCorsConfiguration,
+  validateSecurityConfiguration,
+  withAdminApi,
+  withAuthApi,
+  withCustomApi,
+  withOptionalAuthApi,
+  withPublicApi
+};

package/dist/middleware/init-request.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 요청 초기화 미들웨어
+ *
+ * - requestId 생성
+ * - locale 감지
+ * - startTime 설정
+ */
+import type { TApiMiddleware } from './types';
+/**
+ * 요청 초기화 미들웨어
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(initRequestMiddleware);
+ * ```
+ */
+export declare const initRequestMiddleware: TApiMiddleware;

package/dist/middleware/init-request.js

@@ -0,0 +1,8 @@
+import {
+  initRequestMiddleware
+} from "../chunk-62Q7DN5G.js";
+import "../chunk-XHZ5L4FO.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  initRequestMiddleware
+};

package/dist/middleware/middleware-chain.d.ts

@@ -0,0 +1,53 @@
+/**
+ * API 미들웨어 체인
+ *
+ * Express.js 스타일의 미들웨어 체인을 Next.js API에서 사용
+ */
+import type { NextResponse } from 'next/server';
+import type { IApiContext, TApiHandler, TApiMiddleware, IMiddlewareChainOptions } from './types';
+/**
+ * 미들웨어 체인 클래스
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(errorHandlerMiddleware)
+ *   .use(initRequestMiddleware)
+ *   .use(rateLimitMiddleware);
+ *
+ * const handler = async (ctx: IApiContext) => {
+ *   return NextResponse.json({ data: 'Hello' });
+ * };
+ *
+ * return await chain.execute(context, handler);
+ * ```
+ */
+export declare class MiddlewareChain {
+    private middlewares;
+    private options;
+    constructor(options?: IMiddlewareChainOptions);
+    /**
+     * 미들웨어 추가
+     */
+    use(middleware: TApiMiddleware): this;
+    /**
+     * 체인 실행
+     *
+     * @param context - API 컨텍스트
+     * @param handler - 최종 핸들러 함수
+     * @param props - Next.js 동적 라우트 파라미터 (params 등)
+     */
+    execute(context: IApiContext, handler: TApiHandler, props?: unknown): Promise<NextResponse>;
+    /**
+     * 타임아웃 처리
+     */
+    private withTimeout;
+    /**
+     * 미들웨어 개수 반환
+     */
+    get length(): number;
+    /**
+     * 체인 초기화
+     */
+    clear(): void;
+}

package/dist/middleware/middleware-chain.js

@@ -0,0 +1,8 @@
+import {
+  MiddlewareChain
+} from "../chunk-4ODT3Q4A.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  MiddlewareChain
+};

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Rate Limit 미들웨어
+ *
+ * - IP 기반 Rate Limiting
+ * - Redis + In-Memory Fallback
+ * - 초과 시 429 에러
+ *
+ * 의존성 주입 패턴 사용:
+ * 외부에서 Rate Limit 어댑터를 설정해야 합니다.
+ */
+import type { TApiMiddleware } from "./types";
+/**
+ * Rate Limiter 인터페이스
+ */
+export interface IRateLimiter {
+    check: (identifier: string) => Promise<{
+        success: boolean;
+        remaining: number;
+        resetIn: number;
+    }>;
+    config: {
+        limit: number;
+    };
+}
+/**
+ * Rate Limit 어댑터 인터페이스
+ */
+export interface IRateLimitAdapter {
+    rateLimiters: Record<string, IRateLimiter>;
+    extractClientIp: (headers: Headers) => string;
+    /** Rate Limiting 활성화 여부 (옵셔널, 미설정 시 기본 활성화) */
+    isEnabled?: (type?: string) => Promise<boolean>;
+}
+/**
+ * Rate Limit 어댑터 설정
+ * @param adapter - Rate Limit 어댑터 구현체
+ *
+ * @example
+ * ```typescript
+ * import { setRateLimitAdapter } from '@withwiz/middleware/rate-limit';
+ * // 프로젝트에서 구현한 Rate Limit 유틸리티를 import하세요
+ * import { rateLimiters, extractClientIp } from '<your-project>/rateLimiter';
+ *
+ * setRateLimitAdapter({ rateLimiters, extractClientIp });
+ * ```
+ */
+export declare function setRateLimitAdapter(adapter: IRateLimitAdapter): void;
+/**
+ * 기본 Rate Limit 타입 (범용)
+ */
+export type TRateLimitType = "api" | "auth" | "admin";
+/**
+ * 확장 가능한 Rate Limit 타입
+ * URL Shortener 서비스 특화 타입은 extensions/url-shortener/rate-limit-types.ts에 정의
+ */
+export type TExtendedRateLimitType = TRateLimitType | string;
+/**
+ * Rate Limit 미들웨어 팩토리
+ *
+ * @param type - Rate limit 타입 ('api', 'auth', 'admin' 등)
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(createRateLimitMiddleware('api'));
+ * ```
+ */
+export declare function createRateLimitMiddleware(type: TExtendedRateLimitType): TApiMiddleware;
+/**
+ * 사전 정의된 Rate Limit 미들웨어 (범용)
+ *
+ * 서비스 특화 미들웨어 (redirect, createLink 등)는
+ * 프로젝트에서 직접 createRateLimitMiddleware를 사용하여 생성하세요.
+ */
+export declare const rateLimitMiddleware: {
+    /** API Rate Limit (분당 120회) */
+    api: TApiMiddleware;
+    /** 인증 Rate Limit (시간당 40회) */
+    auth: TApiMiddleware;
+    /** 관리자 Rate Limit (분당 200회) */
+    admin: TApiMiddleware;
+};

package/dist/middleware/rate-limit.js

@@ -0,0 +1,14 @@
+import {
+  createRateLimitMiddleware,
+  rateLimitMiddleware,
+  setRateLimitAdapter
+} from "../chunk-H5I5GWAA.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  createRateLimitMiddleware,
+  rateLimitMiddleware,
+  setRateLimitAdapter
+};

package/dist/middleware/response-logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 응답 로거 미들웨어
+ *
+ * - 요청/응답 정보 로깅
+ * - 응답 시간 측정
+ * - Rate limit 헤더 추가
+ */
+import type { TApiMiddleware } from './types';
+/**
+ * 응답 로거 미들웨어
+ *
+ * 요청 처리 시작부터 끝까지의 정보를 로깅합니다.
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(errorHandlerMiddleware)
+ *   .use(initRequestMiddleware)
+ *   .use(responseLoggerMiddleware);
+ * ```
+ */
+export declare const responseLoggerMiddleware: TApiMiddleware;

package/dist/middleware/response-logger.js

@@ -0,0 +1,8 @@
+import {
+  responseLoggerMiddleware
+} from "../chunk-KAWVMIRJ.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  responseLoggerMiddleware
+};

package/dist/middleware/security.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 보안 미들웨어
+ *
+ * - TRACE/TRACK HTTP 메서드 차단
+ * - Content-Type 검증
+ * - 보안 헤더 강화
+ */
+import type { TApiMiddleware } from './types';
+/**
+ * 보안 미들웨어
+ *
+ * - TRACE/TRACK 메서드 차단 (405 Method Not Allowed)
+ * - POST/PUT/PATCH 요청의 Content-Type 검증
+ * - 보안 헤더 추가
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(errorHandlerMiddleware)
+ *   .use(securityMiddleware)  // CORS 전에 배치
+ *   .use(corsMiddleware)
+ *   .use(initRequestMiddleware);
+ * ```
+ */
+export declare const securityMiddleware: TApiMiddleware;
+/**
+ * 보안 미들웨어 설정 검증
+ *
+ * 서버 시작 시 호출하여 보안 설정을 로깅합니다.
+ */
+export declare function validateSecurityConfiguration(): void;

package/dist/middleware/security.js

@@ -0,0 +1,9 @@
+import {
+  securityMiddleware,
+  validateSecurityConfiguration
+} from "../chunk-WSQMXMTL.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  securityMiddleware,
+  validateSecurityConfiguration
+};

package/dist/middleware/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * API 미들웨어 타입 정의
+ */
+import type { NextRequest, NextResponse } from 'next/server';
+import type { TLocale } from '@withwiz/error/messages';
+/**
+ * 사용자 정보 (JWT 토큰에서 추출)
+ */
+export interface IUser {
+    id: string;
+    email: string;
+    name?: string;
+    role: 'USER' | 'ADMIN';
+}
+/**
+ * API 컨텍스트
+ * - 요청 전반에 걸쳐 공유되는 정보
+ */
+export interface IApiContext {
+    request: NextRequest;
+    user?: IUser;
+    locale: TLocale;
+    requestId: string;
+    startTime: number;
+    metadata: Record<string, unknown>;
+}
+/**
+ * API 핸들러 함수
+ * - 실제 비즈니스 로직을 처리하는 함수
+ * - props는 Next.js dynamic route params를 지원
+ */
+export type TApiHandler = (context: IApiContext, props?: any) => Promise<NextResponse> | NextResponse;
+/**
+ * API 미들웨어 함수
+ * - 체인에서 실행되는 미들웨어
+ * - next()를 호출하여 다음 미들웨어로 전달
+ */
+export type TApiMiddleware = (context: IApiContext, next: () => Promise<NextResponse>) => Promise<NextResponse>;
+/**
+ * 미들웨어 체인 옵션
+ */
+export interface IMiddlewareChainOptions {
+    continueOnError?: boolean;
+    timeout?: number;
+}

package/dist/middleware/wrappers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * API 래퍼 함수
+ *
+ * 미들웨어 체인을 조합하여 API 핸들러를 래핑합니다.
+ */
+import type { NextRequest } from 'next/server';
+import type { TApiHandler } from './types';
+import { MiddlewareChain } from './middleware-chain';
+/**
+ * 공개 API 래퍼
+ *
+ * - 인증 불필요
+ * - Rate limit: API (분당 120회)
+ * - 에러 핸들링, 로깅 포함
+ *
+ * @example
+ * ```typescript
+ * export const GET = withPublicApi(async (ctx) => {
+ *   return NextResponse.json({ message: 'Hello' });
+ * });
+ * ```
+ */
+export declare function withPublicApi(handler: TApiHandler): (request: NextRequest, props?: unknown) => Promise<import("next/server").NextResponse<unknown>>;
+/**
+ * 인증 필수 API 래퍼
+ *
+ * - JWT 인증 필수
+ * - Rate limit: API (분당 120회)
+ * - 에러 핸들링, 로깅 포함
+ *
+ * @example
+ * ```typescript
+ * export const GET = withAuthApi(async (ctx) => {
+ *   const userId = ctx.user!.id;
+ *   return NextResponse.json({ userId });
+ * });
+ * ```
+ */
+export declare function withAuthApi(handler: TApiHandler): (request: NextRequest, props?: unknown) => Promise<import("next/server").NextResponse<unknown>>;
+/**
+ * 관리자 전용 API 래퍼
+ *
+ * - JWT 인증 + 관리자 권한 필수
+ * - Rate limit: Admin (분당 200회)
+ * - 에러 핸들링, 로깅 포함
+ *
+ * @example
+ * ```typescript
+ * export const GET = withAdminApi(async (ctx) => {
+ *   // ctx.user.role === 'admin' 보장됨
+ *   return NextResponse.json({ users: [...] });
+ * });
+ * ```
+ */
+export declare function withAdminApi(handler: TApiHandler): (request: NextRequest, props?: unknown) => Promise<import("next/server").NextResponse<unknown>>;
+/**
+ * 선택적 인증 API 래퍼
+ *
+ * - 인증 선택적 (로그인 시 context.user 설정, 비로그인 시 무시)
+ * - Rate limit: API (분당 120회)
+ * - 에러 핸들링, 로깅 포함
+ *
+ * @example
+ * ```typescript
+ * export const POST = withOptionalAuthApi(async (ctx) => {
+ *   const userId = ctx.user?.id; // 로그인 시 존재, 비로그인 시 undefined
+ *   return NextResponse.json({ userId });
+ * });
+ * ```
+ */
+export declare function withOptionalAuthApi(handler: TApiHandler): (request: NextRequest, props?: unknown) => Promise<import("next/server").NextResponse<unknown>>;
+/**
+ * 커스텀 미들웨어 체인 API 래퍼
+ *
+ * 사용자 정의 미들웨어 체인을 적용할 수 있습니다.
+ *
+ * @example
+ * ```typescript
+ * export const GET = withCustomApi(
+ *   async (ctx) => {
+ *     return NextResponse.json({ data: 'custom' });
+ *   },
+ *   (chain) => chain
+ *     .use(errorHandlerMiddleware)
+ *     .use(initRequestMiddleware)
+ *     .use(rateLimitMiddleware.createLink)
+ *     .use(responseLoggerMiddleware)
+ * );
+ * ```
+ */
+export declare function withCustomApi(handler: TApiHandler, configureChain: (chain: MiddlewareChain) => MiddlewareChain): (request: NextRequest, props?: unknown) => Promise<import("next/server").NextResponse<unknown>>;