@withwiz/toolkit 0.7.1 → 0.8.0

package/dist/core/auth/password/hasher.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pluggable Password Hashing
+ *
+ * `IPasswordHasher` 추상화로 해시 백엔드를 교체 가능하게 한다.
+ * - `BcryptPasswordHasher`: 기본(bcryptjs). 하드 의존성.
+ * - `Argon2idPasswordHasher`: argon2id. `argon2` 패키지를 지연 import 하는
+ *   optional 의존성 — 설치되지 않으면 verify/hash 호출 시 명확한 에러를 던진다.
+ * - `MigratingPasswordHasher`: preferred + legacy 해셔를 조합해 레거시 해시를
+ *   검증하고(scrypt→bcrypt 등) rehash 대상 여부를 판정한다 (rehash-on-login).
+ *
+ * rehash-on-login 흐름: 로그인 시 verify() 성공 후 needsRehash(storedHash) 가
+ * true 면 preferred 스킴으로 다시 해싱해 저장한다. 평문은 로그인 시점에만
+ * 존재하므로 이 시점이 무중단 마이그레이션의 유일한 기회다.
+ */
+export interface IPasswordHasher {
+    /** 스킴 식별자 (예: 'bcrypt', 'argon2id'). 로깅/디버깅용. */
+    readonly id: string;
+    /** 이 해셔가 인식하는 해시 포맷인지 판정 (verify 위임 라우팅에 사용). */
+    identifies(hash: string): boolean;
+    /** 평문을 이 해셔의 스킴으로 해싱. */
+    hash(password: string): Promise<string>;
+    /** 평문과 해시 비교. */
+    verify(password: string, hash: string): Promise<boolean>;
+    /**
+     * 이 해시를 다시 해싱해야 하는지 판정한다.
+     * - 다른 스킴이거나(스킴 마이그레이션)
+     * - 같은 스킴이지만 파라미터가 현재 설정보다 약하면 true.
+     */
+    needsRehash(hash: string): boolean;
+}
+export interface BcryptHasherOptions {
+    /** bcrypt cost factor. 기본 12. */
+    rounds?: number;
+}
+export declare class BcryptPasswordHasher implements IPasswordHasher {
+    readonly id = "bcrypt";
+    private rounds;
+    constructor(options?: BcryptHasherOptions);
+    identifies(hash: string): boolean;
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    needsRehash(hash: string): boolean;
+}
+export interface Argon2idHasherOptions {
+    /** 메모리 비용 (KiB). 기본 19456 (= 19 MiB, OWASP 권장 하한). */
+    memoryCost?: number;
+    /** 반복 횟수. 기본 2. */
+    timeCost?: number;
+    /** 병렬성. 기본 1. */
+    parallelism?: number;
+}
+/** 테스트 전용: 지연 로드된 argon2 모듈 캐시를 초기화한다. */
+export declare function __resetArgon2Cache(): void;
+export declare class Argon2idPasswordHasher implements IPasswordHasher {
+    readonly id = "argon2id";
+    private memoryCost;
+    private timeCost;
+    private parallelism;
+    constructor(options?: Argon2idHasherOptions);
+    identifies(hash: string): boolean;
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    needsRehash(hash: string): boolean;
+}
+export interface MigratingHasherOptions {
+    /** 신규 해시 및 rehash 대상 스킴. */
+    preferred: IPasswordHasher;
+    /**
+     * 검증만 지원하는 레거시 해셔들 (예: 소비자가 구현한 scrypt 어댑터).
+     * verify 시 preferred 다음 순서로 매칭을 시도한다.
+     */
+    legacy?: IPasswordHasher[];
+}
+export declare class MigratingPasswordHasher implements IPasswordHasher {
+    private preferred;
+    private legacy;
+    constructor(options: MigratingHasherOptions);
+    get id(): string;
+    identifies(hash: string): boolean;
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    needsRehash(hash: string): boolean;
+}

package/dist/core/auth/password/hasher.js

@@ -0,0 +1,14 @@
+import {
+  Argon2idPasswordHasher,
+  BcryptPasswordHasher,
+  MigratingPasswordHasher,
+  __resetArgon2Cache
+} from "../../../chunk-ILMPKSWS.js";
+import "../../../chunk-5GWGARXI.js";
+import "../../../chunk-N3ETBM74.js";
+export {
+  Argon2idPasswordHasher,
+  BcryptPasswordHasher,
+  MigratingPasswordHasher,
+  __resetArgon2Cache
+};

package/dist/core/auth/password/index.d.ts

@@ -4,8 +4,8 @@
  * 비밀번호 검증 및 강도 측정 모듈 (프레임워크 독립적)
  */
 import { z } from 'zod';
-import type { PasswordConfig } from '@withwiz/core/auth/types';
-import { PasswordStrength, type PasswordValidationResult as BasePasswordValidationResult } from '@withwiz/core/auth/types';
+import type { PasswordConfig } from '@withwiz/toolkit/core/auth/types';
+import { PasswordStrength, type PasswordValidationResult as BasePasswordValidationResult } from '@withwiz/toolkit/core/auth/types';
 export interface PasswordValidationResult extends BasePasswordValidationResult {
     score: number;
 }
@@ -32,7 +32,7 @@ export declare class PasswordValidator {
     /**
      * Zod 스키마 생성
      */
-    createZodSchema(): z.ZodString;
+    createZodSchema(): z.ZodType<string>;
     /**
      * 비밀번호 힌트 생성
      */
@@ -62,10 +62,12 @@ export declare class PasswordHasher {
  * 기본 비밀번호 스키마 (기존 코드 호환성)
  * 최소 8자, 숫자 포함
  */
-export declare const defaultPasswordSchema: z.ZodString;
+export declare const defaultPasswordSchema: z.ZodEffects<z.ZodString, string, string>;
 /**
  * 강력한 비밀번호 스키마 (기존 코드 호환성)
  * 최소 12자, 대소문자, 숫자, 특수문자 포함
  */
-export declare const strongPasswordSchema: z.ZodString;
-export type { PasswordConfig, PasswordStrength } from '@withwiz/core/auth/types';
+export declare const strongPasswordSchema: z.ZodEffects<z.ZodString, string, string>;
+export { BcryptPasswordHasher, Argon2idPasswordHasher, MigratingPasswordHasher, } from '@withwiz/toolkit/core/auth/password/hasher';
+export type { IPasswordHasher, BcryptHasherOptions, Argon2idHasherOptions, MigratingHasherOptions, } from '@withwiz/toolkit/core/auth/password/hasher';
+export type { PasswordConfig, PasswordStrength } from '@withwiz/toolkit/core/auth/types';

package/dist/core/auth/password/index.js

@@ -3,10 +3,19 @@ import {
   PasswordValidator,
   defaultPasswordSchema,
   strongPasswordSchema
-} from "../../../chunk-MNYVAEXK.js";
+} from "../../../chunk-4ROIPF33.js";
+import {
+  Argon2idPasswordHasher,
+  BcryptPasswordHasher,
+  MigratingPasswordHasher
+} from "../../../chunk-ILMPKSWS.js";
 import "../../../chunk-GH3U4WRE.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-5GWGARXI.js";
+import "../../../chunk-N3ETBM74.js";
 export {
+  Argon2idPasswordHasher,
+  BcryptPasswordHasher,
+  MigratingPasswordHasher,
   PasswordHasher,
   PasswordValidator,
   defaultPasswordSchema,

package/dist/core/auth/services/email-verification.service.d.ts

@@ -1,4 +1,4 @@
-import type { UserRepository, EmailTokenRepository, EmailSender, Logger } from '../types';
+import type { UserRepository, EmailTokenRepository, EmailSender, Logger } from '@withwiz/toolkit/core/auth/types';
 export interface EmailVerificationServiceConfig {
     userRepository: UserRepository;
     emailTokenRepository: EmailTokenRepository;

package/dist/core/auth/services/email-verification.service.js

@@ -1,10 +1,10 @@
 import {
   EmailVerificationService
-} from "../../../chunk-AQZPGOEZ.js";
-import "../../../chunk-D73ZJQMX.js";
+} from "../../../chunk-VWKZMGPJ.js";
+import "../../../chunk-ZZABL54F.js";
 import "../../../chunk-GH3U4WRE.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   EmailVerificationService
 };

package/dist/core/auth/services/index.d.ts

@@ -1,12 +1,13 @@
-export { LoginService } from './login.service';
-export type { LoginServiceConfig, LoginResult } from './login.service';
-export { RegisterService } from './register.service';
-export type { RegisterServiceConfig, RegisterInput, RegisterResult } from './register.service';
-export { OAuthCallbackService } from './oauth-callback.service';
-export type { OAuthCallbackServiceConfig, OAuthCallbackInput, OAuthCallbackResult } from './oauth-callback.service';
-export { TokenRefreshService } from './token-refresh.service';
-export type { TokenRefreshServiceConfig, RefreshResult } from './token-refresh.service';
-export { PasswordResetService } from './password-reset.service';
-export type { PasswordResetServiceConfig } from './password-reset.service';
-export { EmailVerificationService } from './email-verification.service';
-export type { EmailVerificationServiceConfig } from './email-verification.service';
+export { LoginService } from '@withwiz/toolkit/core/auth/services/login.service';
+export type { LoginServiceConfig, LoginResult } from '@withwiz/toolkit/core/auth/services/login.service';
+export { RegisterService } from '@withwiz/toolkit/core/auth/services/register.service';
+export type { RegisterServiceConfig, RegisterInput, RegisterResult } from '@withwiz/toolkit/core/auth/services/register.service';
+export { OAuthCallbackService } from '@withwiz/toolkit/core/auth/services/oauth-callback.service';
+export type { OAuthCallbackServiceConfig, OAuthCallbackInput, OAuthCallbackResult } from '@withwiz/toolkit/core/auth/services/oauth-callback.service';
+export { TokenRefreshService } from '@withwiz/toolkit/core/auth/services/token-refresh.service';
+export type { TokenRefreshServiceConfig, RefreshResult } from '@withwiz/toolkit/core/auth/services/token-refresh.service';
+export type { IRefreshTokenStore, RefreshTokenRecord } from '@withwiz/toolkit/core/auth/services/refresh-token-store';
+export { PasswordResetService } from '@withwiz/toolkit/core/auth/services/password-reset.service';
+export type { PasswordResetServiceConfig } from '@withwiz/toolkit/core/auth/services/password-reset.service';
+export { EmailVerificationService } from '@withwiz/toolkit/core/auth/services/email-verification.service';
+export type { EmailVerificationServiceConfig } from '@withwiz/toolkit/core/auth/services/email-verification.service';

package/dist/core/auth/services/index.js

@@ -1,31 +1,31 @@
 import {
   LoginService
-} from "../../../chunk-B5VRZ2VJ.js";
-import {
-  RegisterService
-} from "../../../chunk-LUIYCIF7.js";
+} from "../../../chunk-TNDEYJEL.js";
 import {
   EmailVerificationService
-} from "../../../chunk-AQZPGOEZ.js";
-import {
-  PasswordResetService
-} from "../../../chunk-N5VOFGF3.js";
+} from "../../../chunk-VWKZMGPJ.js";
 import {
   OAuthCallbackService
-} from "../../../chunk-BBE4RXR7.js";
+} from "../../../chunk-MTZXWVW3.js";
 import {
   TokenRefreshService
-} from "../../../chunk-ARXUKGZI.js";
-import "../../../chunk-D73ZJQMX.js";
+} from "../../../chunk-XAGPZLRK.js";
+import {
+  RegisterService
+} from "../../../chunk-Y4ME3Q5K.js";
+import {
+  PasswordResetService
+} from "../../../chunk-75UDFONR.js";
+import "../../../chunk-LWHLB2Y6.js";
+import "../../../chunk-ZZABL54F.js";
 import "../../../chunk-GH3U4WRE.js";
-import "../../../chunk-2PFSRVVD.js";
-import "../../../chunk-RJGYONRO.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-KYAHURXN.js";
-import "../../../chunk-2SIBG5BG.js";
+import "../../../chunk-PRPMEHRE.js";
+import "../../../chunk-N3TCQ5BF.js";
+import "../../../chunk-7YWUKMZD.js";
 import "../../../chunk-6J2EJVND.js";
 import "../../../chunk-F3R3UYBF.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   EmailVerificationService,
   LoginService,

package/dist/core/auth/services/login.service.d.ts

@@ -1,18 +1,32 @@
-import type { UserRepository, BaseUser, TokenPair, Logger } from '../types';
+import type { UserRepository, BaseUser, TokenPair, Logger } from '@withwiz/toolkit/core/auth/types';
+import type { IPasswordHasher } from '@withwiz/toolkit/core/auth/password/hasher';
 export interface LoginServiceConfig {
     userRepository: UserRepository;
     jwtSecret: string;
     accessTokenExpiry?: string;
     refreshTokenExpiry?: string;
+    /**
+     * 비밀번호 검증/재해시에 사용할 pluggable 해셔.
+     * 미지정 시 bcryptjs.compare 로 폴백한다 (하위 호환).
+     * `MigratingPasswordHasher` 를 주입하면 레거시 해시(scrypt 등)를 검증하고
+     * needsRehash 시 LoginResult.rehashedPassword 로 신규 해시를 반환한다.
+     */
+    passwordHasher?: IPasswordHasher;
     logger?: Logger;
 }
 export interface LoginResult {
     user: BaseUser;
     tokens: TokenPair;
+    /**
+     * storedHash 가 재해시 대상일 때(rehash-on-login)에만 채워진다.
+     * 소비자는 이 값을 사용자 레코드에 저장해 무중단 해시 마이그레이션을 수행한다.
+     */
+    rehashedPassword?: string;
 }
 export declare class LoginService {
     private jwtService;
     private userRepo;
+    private passwordHasher?;
     private logger;
     constructor(config: LoginServiceConfig);
     login(email: string, password: string, storedHash: string): Promise<LoginResult>;

package/dist/core/auth/services/login.service.js

@@ -1,14 +1,14 @@
 import {
   LoginService
-} from "../../../chunk-B5VRZ2VJ.js";
-import "../../../chunk-2PFSRVVD.js";
-import "../../../chunk-RJGYONRO.js";
+} from "../../../chunk-TNDEYJEL.js";
+import "../../../chunk-LWHLB2Y6.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-KYAHURXN.js";
-import "../../../chunk-2SIBG5BG.js";
+import "../../../chunk-PRPMEHRE.js";
+import "../../../chunk-N3TCQ5BF.js";
+import "../../../chunk-7YWUKMZD.js";
 import "../../../chunk-6J2EJVND.js";
 import "../../../chunk-F3R3UYBF.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   LoginService
 };

package/dist/core/auth/services/oauth-callback.service.d.ts

@@ -1,4 +1,4 @@
-import type { UserRepository, OAuthAccountRepository, BaseUser, TokenPair, Logger } from '../types';
+import type { UserRepository, OAuthAccountRepository, BaseUser, TokenPair, Logger } from '@withwiz/toolkit/core/auth/types';
 export interface OAuthCallbackServiceConfig {
     userRepository: UserRepository;
     oauthAccountRepository: OAuthAccountRepository;
@@ -15,6 +15,12 @@ export interface OAuthCallbackInput {
     image: string | null;
     accessToken: string;
     refreshToken?: string;
+    /**
+     * provider 가 이 이메일을 검증했는지 여부. 기존 로컬 계정에 OAuth 를
+     * 연결할 때 반드시 true 여야 한다(미검증/부재 시 계정 탈취 방지를 위해 차단).
+     * OAuthUserInfo.emailVerified 를 그대로 전달할 것.
+     */
+    emailVerified?: boolean;
 }
 export interface OAuthCallbackResult {
     user: BaseUser;

package/dist/core/auth/services/oauth-callback.service.js

@@ -1,14 +1,14 @@
 import {
   OAuthCallbackService
-} from "../../../chunk-BBE4RXR7.js";
-import "../../../chunk-2PFSRVVD.js";
-import "../../../chunk-RJGYONRO.js";
+} from "../../../chunk-MTZXWVW3.js";
+import "../../../chunk-LWHLB2Y6.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-KYAHURXN.js";
-import "../../../chunk-2SIBG5BG.js";
+import "../../../chunk-PRPMEHRE.js";
+import "../../../chunk-N3TCQ5BF.js";
+import "../../../chunk-7YWUKMZD.js";
 import "../../../chunk-6J2EJVND.js";
 import "../../../chunk-F3R3UYBF.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   OAuthCallbackService
 };

package/dist/core/auth/services/password-reset.service.d.ts

@@ -1,4 +1,4 @@
-import type { UserRepository, EmailTokenRepository, EmailSender, Logger } from '../types';
+import type { UserRepository, EmailTokenRepository, EmailSender, Logger } from '@withwiz/toolkit/core/auth/types';
 export interface PasswordResetServiceConfig {
     userRepository: UserRepository;
     emailTokenRepository: EmailTokenRepository;

package/dist/core/auth/services/password-reset.service.js

@@ -1,10 +1,10 @@
 import {
   PasswordResetService
-} from "../../../chunk-N5VOFGF3.js";
-import "../../../chunk-D73ZJQMX.js";
+} from "../../../chunk-75UDFONR.js";
+import "../../../chunk-ZZABL54F.js";
 import "../../../chunk-GH3U4WRE.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   PasswordResetService
 };

package/dist/core/auth/services/refresh-token-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Refresh Token Store (rotation + reuse detection)
+ *
+ * stateful refresh 토큰 추적 추상화. 구현은 소비자 몫(Redis/DB/메모리).
+ *
+ * 모델:
+ * - 각 refresh 토큰은 고유 `jti` 를 가지며 회전 계보(`familyId`)에 속한다.
+ * - 로그인 시 새 family 가 생성되고, 회전할 때마다 같은 family 안에서 새 jti 가
+ *   발급되며 구 jti 는 used 로 표시된다.
+ * - 이미 used 인 jti 가 다시 제출되면(=회전된 토큰 재사용) 탈취로 간주하고
+ *   family 전체를 무효화한다(reuse detection).
+ * - 로그아웃은 family 무효화로 즉시 stateful 무효화를 제공한다.
+ *
+ * reuse detection 에 필수인 것은 `isUsed`/`markUsed`/`isFamilyRevoked`/
+ * `revokeFamily` 네 개다. `register` 는 TTL·감사 목적의 선택적 훅이다.
+ */
+export interface RefreshTokenRecord {
+    jti: string;
+    familyId: string;
+    userId: string;
+    /** 토큰 만료 시각 — store TTL 설정에 사용 가능. */
+    expiresAt?: Date;
+}
+export interface IRefreshTokenStore {
+    /** 이 jti 가 이미 회전(소비)되었는지 여부. */
+    isUsed(jti: string): Promise<boolean>;
+    /** 회전 시 구 jti 를 소비 처리한다. meta 로 TTL/계보 정보를 함께 줄 수 있다. */
+    markUsed(jti: string, meta?: {
+        familyId: string;
+        userId: string;
+        expiresAt?: Date;
+    }): Promise<void>;
+    /** family 전체가 무효화되었는지 여부. */
+    isFamilyRevoked(familyId: string): Promise<boolean>;
+    /** family 전체 무효화 (reuse 탐지 / 로그아웃). */
+    revokeFamily(familyId: string): Promise<void>;
+    /** (선택) 새 refresh 발급 기록 — store TTL/감사용. */
+    register?(record: RefreshTokenRecord): Promise<void>;
+}

package/dist/core/auth/services/register.service.d.ts

@@ -1,4 +1,4 @@
-import type { UserRepository, EmailTokenRepository, EmailSender, BaseUser, Logger } from '../types';
+import type { UserRepository, EmailTokenRepository, EmailSender, BaseUser, Logger } from '@withwiz/toolkit/core/auth/types';
 export interface RegisterServiceConfig {
     userRepository: UserRepository;
     emailTokenRepository: EmailTokenRepository;

package/dist/core/auth/services/register.service.js

@@ -1,10 +1,10 @@
 import {
   RegisterService
-} from "../../../chunk-LUIYCIF7.js";
-import "../../../chunk-D73ZJQMX.js";
+} from "../../../chunk-Y4ME3Q5K.js";
+import "../../../chunk-ZZABL54F.js";
 import "../../../chunk-GH3U4WRE.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   RegisterService
 };

package/dist/core/auth/services/token-refresh.service.d.ts

@@ -1,14 +1,29 @@
-import type { UserRepository, Logger } from '../types';
+import type { UserRepository, Logger } from '@withwiz/toolkit/core/auth/types';
+import type { IRefreshTokenStore } from '@withwiz/toolkit/core/auth/services/refresh-token-store';
 export interface TokenRefreshServiceConfig {
     userRepository: UserRepository;
     jwtSecret: string;
     accessTokenExpiry?: string;
     refreshTokenExpiry?: string;
     isTokenBlacklisted?: (token: string) => Promise<boolean>;
+    /**
+     * 주입 시 refresh 토큰 회전(rotation) + 재사용 탐지(reuse detection)를 활성화한다.
+     * - 회전: refresh 마다 새 refresh 를 발급하고 구 jti 를 used 로 표시한다.
+     * - 재사용 탐지: 이미 used 인 jti 재제출 → family 전체 무효화(탈취 대응).
+     * 미주입 시 0.8 이전과 동일하게 access 토큰만 재발급한다(하위 호환).
+     *
+     * 주의: 동시 요청 경쟁을 막으려면 store 의 isUsed→markUsed 는 원자적이어야 한다.
+     */
+    refreshTokenStore?: IRefreshTokenStore;
     logger?: Logger;
 }
 export interface RefreshResult {
     accessToken: string;
+    /**
+     * 회전이 일어난 경우(store 주입 시)에만 채워진다. 소비자는 이 값으로 기존
+     * refresh 토큰(쿠키 등)을 교체해야 한다.
+     */
+    refreshToken?: string;
     user: {
         id: string;
         email: string;
@@ -19,7 +34,18 @@ export declare class TokenRefreshService {
     private userRepo;
     private jwtService;
     private isTokenBlacklisted?;
+    private store?;
     private logger;
     constructor(config: TokenRefreshServiceConfig);
     refresh(refreshToken: string): Promise<RefreshResult>;
+    /**
+     * family 전체를 즉시 무효화한다 (stateful 로그아웃 / 탈취 대응).
+     * store 미주입 시 동작하지 않는다.
+     */
+    revokeFamily(familyId: string): Promise<void>;
+    /**
+     * refresh 토큰을 검증해 그 family 를 무효화한다 (로그아웃 핸들러용).
+     * 토큰에 familyId 가 없으면(레거시) 무효화할 family 가 없으므로 무시한다.
+     */
+    revokeByToken(refreshToken: string): Promise<void>;
 }

package/dist/core/auth/services/token-refresh.service.js

@@ -1,14 +1,14 @@
 import {
   TokenRefreshService
-} from "../../../chunk-ARXUKGZI.js";
-import "../../../chunk-2PFSRVVD.js";
-import "../../../chunk-RJGYONRO.js";
+} from "../../../chunk-XAGPZLRK.js";
+import "../../../chunk-LWHLB2Y6.js";
 import "../../../chunk-5GWGARXI.js";
-import "../../../chunk-KYAHURXN.js";
-import "../../../chunk-2SIBG5BG.js";
+import "../../../chunk-PRPMEHRE.js";
+import "../../../chunk-N3TCQ5BF.js";
+import "../../../chunk-7YWUKMZD.js";
 import "../../../chunk-6J2EJVND.js";
 import "../../../chunk-F3R3UYBF.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   TokenRefreshService
 };

package/dist/core/auth/token-delivery.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 토큰 전달 전략 — tokenDelivery 모드(cookie/header/hybrid)별 구현체.
+ *
+ * 분기 대신 주입: 미들웨어·핸들러는 모드 문자열을 직접 비교하지 않고
+ * getTokenDeliveryStrategy() 가 돌려주는 구현체의 메서드를 호출한다.
+ * oauth-callback 은 redirect 응답 특성상 전략 비적용(항상 쿠키).
+ */
+import type { TokenDelivery } from '@withwiz/toolkit/core/auth/config';
+import type { TokenPair } from '@withwiz/toolkit/core/auth/types';
+import type { CookieOptions } from '@withwiz/toolkit/core/auth/jwt/cookie';
+/** cookies/headers/json 만 구조적으로 요구 — NextRequest 미의존 (core 티어 규칙) */
+export interface TokenSource {
+    cookies: {
+        get(name: string): {
+            value: string;
+        } | undefined;
+    };
+    headers: {
+        get(name: string): string | null;
+    };
+    json?(): Promise<unknown>;
+}
+/** setTokenCookies 가 요구하는 최소 Response 형태 */
+interface CookieSettableResponse {
+    cookies: {
+        set(name: string, value: string, options?: Record<string, unknown>): void;
+    };
+}
+export interface TokenDeliveryStrategy {
+    /** access token 추출. Authorization 헤더 파싱은 호출측 JWT 구현에 위임 */
+    extractAccessToken(source: TokenSource, parseHeader: (header: string | null) => string | null): string | null;
+    /** refresh token 추출 (header/hybrid 는 body { refreshToken } 허용) */
+    extractRefreshToken(source: TokenSource): Promise<string | undefined>;
+    /** 응답 body 에 토큰 조각 포함 여부 결정 — cookie 모드는 body 그대로 */
+    buildTokenResponse(body: Record<string, unknown>, fragment: Record<string, unknown>): Record<string, unknown>;
+    /** 토큰 쿠키 설정 — header 모드는 no-op */
+    attachCookies<T extends CookieSettableResponse>(response: T, tokens: TokenPair, options?: CookieOptions): T;
+}
+/**
+ * tokenDelivery 모드 해석.
+ * 우선순위: 옵션 > 전역 AuthConfig > 'hybrid'
+ * 요청 시점에 호출할 것 — 핸들러 팩토리는 initialize() 이전에 실행될 수 있다.
+ */
+export declare function resolveTokenDelivery(optionValue?: TokenDelivery): TokenDelivery;
+/** 해석된 모드의 전략 구현체 반환 */
+export declare function getTokenDeliveryStrategy(optionValue?: TokenDelivery): TokenDeliveryStrategy;
+export {};

package/dist/core/auth/token-delivery.js

@@ -0,0 +1,14 @@
+import {
+  getTokenDeliveryStrategy,
+  resolveTokenDelivery
+} from "../../chunk-63EKUOJH.js";
+import "../../chunk-PRPMEHRE.js";
+import "../../chunk-N3TCQ5BF.js";
+import "../../chunk-7YWUKMZD.js";
+import "../../chunk-6J2EJVND.js";
+import "../../chunk-F3R3UYBF.js";
+import "../../chunk-N3ETBM74.js";
+export {
+  getTokenDeliveryStrategy,
+  resolveTokenDelivery
+};

package/dist/core/auth/types/index.d.ts

@@ -10,11 +10,22 @@ export interface Logger {
     warn(message: string, meta?: any): void;
     error(message: string, meta?: any): void;
 }
-export interface JWTPayload {
+/**
+ * JWT 페이로드.
+ *
+ * `role`은 평범한 `string`이며 toolkit은 고정 role enum을 소유하지 않는다.
+ * 소비자가 자체 역할 어휘(union/enum)를 가지면 타입 인자로 좁힐 수 있다.
+ *
+ * @example
+ * type AppRole = 'USER' | 'EDITOR' | 'ADMIN';
+ * const payload = await jwt.verifyAccessToken<AppRole>(token);
+ * payload.role; // 'USER' | 'EDITOR' | 'ADMIN'
+ */
+export interface JWTPayload<TRole extends string = string> {
     id: string;
     userId: string;
     email: string;
-    role: string;
+    role: TRole;
     emailVerified?: Date | null;
     tokenType?: 'access' | 'refresh';
     iat?: number;
@@ -24,11 +35,34 @@ export interface TokenPair {
     accessToken: string;
     refreshToken: string;
 }
+/** 대칭 HMAC 알고리즘 — 단일 secret 으로 발급·검증. */
+export type SymmetricJWTAlgorithm = 'HS256' | 'HS384' | 'HS512';
+/** 비대칭 알고리즘 — privateKey 로 발급, publicKey/JWKS 로 검증. */
+export type AsymmetricJWTAlgorithm = 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512' | 'EdDSA';
+export type JWTAlgorithm = SymmetricJWTAlgorithm | AsymmetricJWTAlgorithm;
+/**
+ * JWT 설정.
+ *
+ * - HS 계열(대칭): `secret`(>= 32자) 필수. 발급·검증 동일 키.
+ * - RS·ES·EdDSA 계열(비대칭): 발급에는 `privateKey`(PEM PKCS#8), 검증에는
+ *   `publicKey`(PEM SPKI) 또는 `jwksUri`(원격 JWKS) 필요. 발급/검증을 분리한
+ *   서비스에서는 한쪽만 설정한다(검증 전용 서비스는 privateKey 생략).
+ *
+ * 보안: 검증 시 알고리즘 allowlist 를 `algorithm` 한 개로 고정해 alg confusion
+ * (예: RS256 토큰을 HS256 으로 검증시켜 공개키를 HMAC 비밀로 악용)을 차단한다.
+ */
 export interface JWTConfig {
-    secret: string;
+    algorithm: JWTAlgorithm;
     accessTokenExpiry: string;
     refreshTokenExpiry: string;
-    algorithm: 'HS256' | 'HS384' | 'HS512';
+    /** HS* 대칭키 (>= 32자). */
+    secret?: string;
+    /** 비대칭 발급용 개인키 (PEM PKCS#8). */
+    privateKey?: string;
+    /** 비대칭 검증용 공개키 (PEM SPKI). `jwksUri` 와 택일. */
+    publicKey?: string;
+    /** 비대칭 검증용 원격 JWKS endpoint. `publicKey` 와 택일. */
+    jwksUri?: string;
 }
 export declare const OAUTH_PROVIDERS: {
     readonly GOOGLE: "google";

package/dist/core/auth/types/index.js

@@ -3,7 +3,7 @@ import {
   PasswordStrength,
   TokenType
 } from "../../../chunk-GH3U4WRE.js";
-import "../../../chunk-ORMEWXMH.js";
+import "../../../chunk-N3ETBM74.js";
 export {
   OAUTH_PROVIDERS,
   PasswordStrength,