@ddunigma/node 2.0.2 → 2.1.1

package/dist/mjs/encoders/Ddu64.js

@@ -1,7 +1,8 @@
-import { deflateSync, inflateSync } from "zlib";
+import { deflateSync } from "zlib";
 import { BaseDdu } from "../base/BaseDdu.js";
 import { DduSetSymbol, dduDefaultConstructorOptions, } from "../types/index.js";
 import { getCharSet } from "../charSets/index.js";
+import { deriveKey, encryptAes256Gcm, decryptAes256Gcm, inflateWithLimit as inflateWithLimitUtil, } from "../utils/crypto.js";
 // ============================================================================
 // 상수 정의
 // ============================================================================
@@ -13,10 +14,56 @@ const MAX_FAST_BITS = 16;
 const BYTE_MASK = 0xff;
 /** 압축 데이터 식별 마커 */
 const COMPRESS_MARKER = "ELYSIA";
+/** 체크섬 마커 */
+const CHECKSUM_MARKER = "CHK";
+/** 암호화 마커 */
+const ENCRYPT_MARKER = "ENC";
 /** 기본 최대 디코딩 바이트 수 (64MB) */
 const DEFAULT_MAX_DECODED_BYTES = 64 * 1024 * 1024;
 /** 기본 최대 압축해제 바이트 수 (64MB) */
 const DEFAULT_MAX_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+/** CRC32 룩업 테이블 (바이트 단위 연산으로 비트 루프 대비 4~8배 빠름) */
+const CRC32_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+        }
+        table[i] = crc;
+    }
+    return table;
+})();
+/** URL-Safe 문자 매핑 */
+const URL_SAFE_MAP = {
+    "+": "-",
+    "/": "_",
+    "=": ".",
+};
+/** URL-Safe 역방향 매핑 */
+const URL_SAFE_REVERSE_MAP = {
+    "-": "+",
+    "_": "/",
+    ".": "=",
+};
+/** 인코딩 진행률 단계별 퍼센트 */
+const ENCODE_PROGRESS = {
+    START: 0,
+    ENCRYPT: 15,
+    CHECKSUM: 20,
+    COMPRESS: 40,
+    ENCODE: 50,
+    DONE: 100,
+};
+/** 디코딩 진행률 단계별 퍼센트 */
+const DECODE_PROGRESS = {
+    START: 0,
+    DECODE: 20,
+    DECOMPRESS: 50,
+    CHECKSUM: 70,
+    DECRYPT: 85,
+    DONE: 100,
+};
 // ============================================================================
 // Ddu64 클래스
 // ============================================================================
@@ -73,6 +120,18 @@ export class Ddu64 extends BaseDdu {
     fastAsciiLookup = null;
     /** ASCII 룩업 사용 여부 */
     useAsciiLookup = false;
+    /** URL-Safe 모드 여부 */
+    urlSafe;
+    /** 암호화 키 해시 (AES-256용 32바이트) */
+    encryptionKeyHash;
+    /** 기본 체크섬 사용 여부 */
+    defaultChecksum;
+    /** 기본 청크 크기 */
+    defaultChunkSize;
+    /** 기본 청크 구분자 */
+    defaultChunkSeparator;
+    /** 기본 압축 레벨 (1~9) */
+    defaultCompressionLevel;
     // --------------------------------------------------------------------------
     // 생성자
     // --------------------------------------------------------------------------
@@ -96,7 +155,8 @@ export class Ddu64 extends BaseDdu {
      */
     constructor(dduChar, paddingChar, dduOptions) {
         super();
-        const shouldThrow = dduOptions?.useBuildErrorReturn ?? false;
+        // throwOnError 우선, useBuildErrorReturn은 하위 호환
+        const shouldThrow = dduOptions?.throwOnError ?? dduOptions?.useBuildErrorReturn ?? false;
         // charset 초기화
         const initial = this.resolveInitialCharSet(dduChar, paddingChar, dduOptions, shouldThrow);
         const normalized = this.normalizeCharSet(initial, shouldThrow, dduOptions);
@@ -149,6 +209,18 @@ export class Ddu64 extends BaseDdu {
         if (this.charLength === 1 && !this.isPredefinedCharSet) {
             this.validateCombinationDuplicates(this.dduChar, this.paddingChar, dduLength);
         }
+        // 새로운 옵션들 초기화
+        const requestUrlSafe = dduOptions?.urlSafe ?? false;
+        this.urlSafe = requestUrlSafe
+            ? this.isUrlSafeCompatible(this.dduChar, this.paddingChar, shouldThrow)
+            : false;
+        this.encryptionKeyHash = dduOptions?.encryptionKey
+            ? deriveKey(dduOptions.encryptionKey)
+            : undefined;
+        this.defaultChecksum = dduOptions?.checksum ?? false;
+        this.defaultChunkSize = dduOptions?.chunkSize;
+        this.defaultChunkSeparator = dduOptions?.chunkSeparator ?? "\n";
+        this.defaultCompressionLevel = Math.min(9, Math.max(1, Math.floor(dduOptions?.compressionLevel ?? 6)));
     }
     // --------------------------------------------------------------------------
     // 공개 메서드
@@ -159,32 +231,92 @@ export class Ddu64 extends BaseDdu {
      * @param input - 인코딩할 문자열 또는 Buffer
      * @param options - 인코딩 옵션
      * @param options.compress - 압축 사용 여부 (기본값: 생성자 설정)
+     * @param options.checksum - 체크섬 추가 여부
+     * @param options.chunkSize - 청크 분할 크기
+     * @param options.chunkSeparator - 청크 구분자
+     * @param options.onProgress - 진행률 콜백
      * @returns 인코딩된 문자열
      *
      * @example
      * encoder.encode("Hello World!");
      * encoder.encode(buffer, { compress: true });
+     * encoder.encode(data, { checksum: true, chunkSize: 76 });
      */
     encode(input, options) {
+        return this.encodeInternal(input, options).encoded;
+    }
+    /**
+     * 인코딩 핵심 로직. encode()와 getStats()가 공유합니다.
+     * 압축 크기 등 메타데이터도 함께 반환하여 중복 deflateSync 호출을 방지합니다.
+     */
+    encodeInternal(input, options) {
         const shouldCompress = options?.compress ?? this.defaultCompress;
-        const originalBuffer = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
-        // 비압축 인코딩
-        if (!shouldCompress) {
-            return this.effectiveBitLength <= MAX_FAST_BITS
-                ? this.encodeFast(originalBuffer, false)
-                : this.encodeBigInt(originalBuffer, false);
+        const shouldChecksum = options?.checksum ?? this.defaultChecksum;
+        const chunkSize = options?.chunkSize ?? this.defaultChunkSize;
+        const chunkSeparator = options?.chunkSeparator ?? this.defaultChunkSeparator;
+        const onProgress = options?.onProgress;
+        let workingBuffer = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
+        const totalBytes = workingBuffer.length;
+        // 진행률 콜백 호출 (시작)
+        if (onProgress) {
+            onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.START, stage: "start" });
+        }
+        // 암호화 처리
+        let isEncrypted = false;
+        if (this.encryptionKeyHash) {
+            workingBuffer = this.encryptData(workingBuffer);
+            isEncrypted = true;
+            if (onProgress) {
+                onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.ENCRYPT, stage: "encrypt" });
+            }
+        }
+        // 체크섬 계산
+        let checksum = "";
+        if (shouldChecksum) {
+            checksum = this.calculateCRC32(workingBuffer);
+            if (onProgress) {
+                onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.CHECKSUM, stage: "checksum" });
+            }
         }
-        // 압축 시도
-        const compressedBuffer = deflateSync(originalBuffer, { level: 9 });
-        // 압축 효과가 없으면 원본 사용
-        if (compressedBuffer.length >= originalBuffer.length) {
-            return this.effectiveBitLength <= MAX_FAST_BITS
-                ? this.encodeFast(originalBuffer, false)
-                : this.encodeBigInt(originalBuffer, false);
+        // 압축 처리
+        let useCompression = false;
+        let compressedSize;
+        if (shouldCompress) {
+            const level = options?.compressionLevel ?? this.defaultCompressionLevel;
+            const compressedBuffer = deflateSync(workingBuffer, { level: Math.min(9, Math.max(1, level)) });
+            compressedSize = compressedBuffer.length;
+            if (compressedBuffer.length < workingBuffer.length) {
+                workingBuffer = compressedBuffer;
+                useCompression = true;
+            }
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(totalBytes * 0.4), totalBytes, percent: ENCODE_PROGRESS.COMPRESS, stage: "compress" });
+            }
+        }
+        // 인코딩 수행
+        if (onProgress) {
+            onProgress({ processedBytes: Math.floor(totalBytes * 0.5), totalBytes, percent: ENCODE_PROGRESS.ENCODE, stage: "encode" });
+        }
+        let result = this.effectiveBitLength <= MAX_FAST_BITS
+            ? this.encodeFast(workingBuffer, useCompression, isEncrypted)
+            : this.encodeBigInt(workingBuffer, useCompression, isEncrypted);
+        // 체크섬 추가
+        if (shouldChecksum && checksum) {
+            result = result + CHECKSUM_MARKER + checksum;
+        }
+        // URL-Safe 변환
+        if (this.urlSafe) {
+            result = this.toUrlSafe(result);
         }
-        return this.effectiveBitLength <= MAX_FAST_BITS
-            ? this.encodeFast(compressedBuffer, true)
-            : this.encodeBigInt(compressedBuffer, true);
+        // 청크 분할
+        if (chunkSize && chunkSize > 0) {
+            result = this.splitIntoChunks(result, chunkSize, chunkSeparator);
+        }
+        // 진행률 콜백 호출 (완료)
+        if (onProgress) {
+            onProgress({ processedBytes: totalBytes, totalBytes, percent: ENCODE_PROGRESS.DONE, stage: "done" });
+        }
+        return { encoded: result, compressedSize };
     }
     /**
      * 인코딩된 문자열을 Buffer로 디코딩합니다.
@@ -193,14 +325,37 @@ export class Ddu64 extends BaseDdu {
      * @param options - 디코딩 옵션
      * @param options.maxDecodedBytes - 최대 디코딩 바이트 수
      * @param options.maxDecompressedBytes - 최대 압축해제 바이트 수
+     * @param options.onProgress - 진행률 콜백
      * @returns 디코딩된 Buffer
      *
      * @throws 잘못된 문자가 포함된 경우
      * @throws 패딩 형식이 잘못된 경우
      * @throws 크기 제한 초과 시
+     * @throws 체크섬 불일치 시
      */
     decodeToBuffer(input, options) {
-        const { cleanedInput, paddingBits, isCompressed } = this.parseFooter(input);
+        const shouldChecksum = options?.checksum ?? this.defaultChecksum;
+        const onProgress = options?.onProgress;
+        let workingInput = input;
+        const inputLength = input.length;
+        // 진행률 콜백 호출 (시작)
+        if (onProgress) {
+            onProgress({ processedBytes: 0, totalBytes: inputLength, percent: DECODE_PROGRESS.START, stage: "start" });
+        }
+        // 청크 제거 (줄바꿈 등 구분자 제거)
+        workingInput = this.removeChunks(workingInput);
+        // URL-Safe 역변환
+        if (this.urlSafe) {
+            workingInput = this.fromUrlSafe(workingInput);
+        }
+        // 체크섬 추출 (체크섬이 활성화된 경우에만 수행하여 오탐지 방지)
+        let extractedChecksum = null;
+        if (shouldChecksum) {
+            const result = this.extractChecksum(workingInput);
+            extractedChecksum = result.checksum;
+            workingInput = result.data;
+        }
+        const { cleanedInput, paddingBits, isCompressed, isEncrypted } = this.parseFooter(workingInput);
         this.assertEncodedInputAligned(cleanedInput);
         // 디코딩 크기 검증
         const maxDecodedBytes = this.normalizeLimit(options?.maxDecodedBytes, this.defaultMaxDecodedBytes, true, "maxDecodedBytes");
@@ -209,14 +364,42 @@ export class Ddu64 extends BaseDdu {
             throw new Error(`[Ddu64 decode] Decoded output exceeds limit. Estimated: ${estimatedDecodedBytes} bytes, Limit: ${maxDecodedBytes} bytes`);
         }
         // 디코딩 수행
-        const decoded = this.effectiveBitLength <= MAX_FAST_BITS
+        if (onProgress) {
+            onProgress({ processedBytes: Math.floor(inputLength * 0.2), totalBytes: inputLength, percent: DECODE_PROGRESS.DECODE, stage: "decode" });
+        }
+        let decoded = this.effectiveBitLength <= MAX_FAST_BITS
             ? this.decodeFast(cleanedInput, paddingBits)
             : this.decodeBigInt(cleanedInput, paddingBits);
-        if (!isCompressed)
-            return decoded;
         // 압축 해제
-        const maxDecompressedBytes = this.normalizeLimit(options?.maxDecompressedBytes, this.defaultMaxDecompressedBytes, true, "maxDecompressedBytes");
-        return this.inflateWithLimit(decoded, maxDecompressedBytes);
+        if (isCompressed) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.5), totalBytes: inputLength, percent: DECODE_PROGRESS.DECOMPRESS, stage: "decompress" });
+            }
+            const maxDecompressedBytes = this.normalizeLimit(options?.maxDecompressedBytes, this.defaultMaxDecompressedBytes, true, "maxDecompressedBytes");
+            decoded = this.inflateWithLimit(decoded, maxDecompressedBytes);
+        }
+        // 체크섬 검증
+        if (extractedChecksum) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.7), totalBytes: inputLength, percent: DECODE_PROGRESS.CHECKSUM, stage: "checksum" });
+            }
+            const calculatedChecksum = this.calculateCRC32(decoded);
+            if (calculatedChecksum !== extractedChecksum) {
+                throw new Error(`[Ddu64 decode] Checksum mismatch. Expected: ${extractedChecksum}, Got: ${calculatedChecksum}`);
+            }
+        }
+        // 복호화
+        if (isEncrypted && this.encryptionKeyHash) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.85), totalBytes: inputLength, percent: DECODE_PROGRESS.DECRYPT, stage: "decrypt" });
+            }
+            decoded = this.decryptData(decoded);
+        }
+        // 진행률 콜백 호출 (완료)
+        if (onProgress) {
+            onProgress({ processedBytes: inputLength, totalBytes: inputLength, percent: DECODE_PROGRESS.DONE, stage: "done" });
+        }
+        return decoded;
     }
     /**
      * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
@@ -246,8 +429,205 @@ export class Ddu64 extends BaseDdu {
             defaultCompress: this.defaultCompress,
             defaultMaxDecodedBytes: this.defaultMaxDecodedBytes,
             defaultMaxDecompressedBytes: this.defaultMaxDecompressedBytes,
+            urlSafe: this.urlSafe,
+            hasEncryptionKey: !!this.encryptionKeyHash,
+            defaultChecksum: this.defaultChecksum,
+            defaultChunkSize: this.defaultChunkSize,
+        };
+    }
+    /**
+     * 인코딩 통계 정보를 반환합니다.
+     *
+     * @param input - 분석할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 통계 정보 객체
+     */
+    getStats(input, options) {
+        const shouldCompress = options?.compress ?? this.defaultCompress;
+        const originalBuffer = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
+        const originalSize = originalBuffer.length;
+        // encodeInternal을 통해 인코딩과 압축 크기를 한 번에 얻어 중복 deflateSync 방지
+        const { encoded, compressedSize } = this.encodeInternal(input, options);
+        const encodedSize = encoded.length;
+        const expansionRatio = originalSize > 0 ? encodedSize / originalSize : 0;
+        const compressionRatio = shouldCompress && compressedSize !== undefined && originalSize > 0
+            ? compressedSize / originalSize
+            : undefined;
+        return {
+            originalSize,
+            encodedSize,
+            compressedSize,
+            compressionRatio,
+            expansionRatio,
+            charsetSize: this.dduChar.length,
+            bitLength: this.bitLength,
         };
     }
+    /**
+     * 비동기 인코딩을 수행합니다.
+     *
+     * 내부적으로 동기 encode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 호출자가 즉시 블로킹되지 않도록 보장하지만, 인코딩 자체는 단일 동기 작업으로
+     * 수행되므로 대용량 데이터(수 MB 이상) 처리 시 이벤트 루프가 블로킹될 수 있습니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createEncodeStream) 사용을 권장합니다.
+     *
+     * @param input - 인코딩할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열 Promise
+     */
+    async encodeAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.encode(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    /**
+     * 비동기 디코딩을 수행합니다.
+     *
+     * 내부적으로 동기 decode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열 Promise
+     */
+    async decodeAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.decode(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    /**
+     * 비동기 디코딩을 Buffer로 수행합니다.
+     *
+     * 내부적으로 동기 decodeToBuffer()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer Promise
+     */
+    async decodeToBufferAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.decodeToBuffer(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    // --------------------------------------------------------------------------
+    // URL-Safe 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 문자열을 URL-Safe 형식으로 변환합니다.
+     * 단일 정규식 패스로 처리하여 split/join 3회 반복 대비 메모리/속도 개선
+     */
+    toUrlSafe(input) {
+        return input.replace(/[+/=]/g, (c) => URL_SAFE_MAP[c]);
+    }
+    /**
+     * URL-Safe 형식에서 원래 형식으로 복원합니다.
+     */
+    fromUrlSafe(input) {
+        return input.replace(/[-_.]/g, (c) => URL_SAFE_REVERSE_MAP[c]);
+    }
+    // --------------------------------------------------------------------------
+    // 체크섬 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * CRC32 체크섬을 계산합니다. (룩업 테이블 사용)
+     */
+    calculateCRC32(data) {
+        let crc = 0xffffffff;
+        for (let i = 0; i < data.length; i++) {
+            crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ data[i]) & 0xff];
+        }
+        return ((crc ^ 0xffffffff) >>> 0).toString(16).padStart(8, "0");
+    }
+    /**
+     * 인코딩된 문자열에서 체크섬을 추출합니다.
+     */
+    extractChecksum(input) {
+        const markerIndex = input.lastIndexOf(CHECKSUM_MARKER);
+        if (markerIndex === -1) {
+            return { data: input, checksum: null };
+        }
+        const checksum = input.slice(markerIndex + CHECKSUM_MARKER.length);
+        if (checksum.length !== 8 || !/^[0-9a-f]+$/i.test(checksum)) {
+            return { data: input, checksum: null };
+        }
+        return {
+            data: input.slice(0, markerIndex),
+            checksum: checksum.toLowerCase(),
+        };
+    }
+    // --------------------------------------------------------------------------
+    // 청크 분할 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 문자열을 청크로 분할합니다.
+     */
+    splitIntoChunks(input, chunkSize, separator) {
+        if (chunkSize <= 0)
+            return input;
+        const chunks = [];
+        for (let i = 0; i < input.length; i += chunkSize) {
+            chunks.push(input.slice(i, i + chunkSize));
+        }
+        return chunks.join(separator);
+    }
+    /**
+     * 청크 구분자를 제거합니다.
+     * 줄바꿈(\r, \n)과 인스턴스에 설정된 청크 구분자만 제거합니다.
+     * 공백/탭 등은 charset에 포함될 수 있으므로 제거하지 않습니다.
+     */
+    removeChunks(input) {
+        // 줄바꿈 문자(\r, \n)는 항상 제거 (기본 구분자 및 일반적 라인 구분)
+        let result = input.replace(/[\r\n]/g, "");
+        // 커스텀 구분자가 줄바꿈이 아닌 경우 추가로 제거
+        const sep = this.defaultChunkSeparator;
+        if (sep && sep !== "\n" && sep !== "\r\n" && sep !== "\r") {
+            result = result.split(sep).join("");
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // 암호화 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 데이터를 AES-256-GCM으로 암호화합니다.
+     */
+    encryptData(data) {
+        if (!this.encryptionKeyHash) {
+            throw new Error("[Ddu64 encrypt] Encryption key is not set");
+        }
+        return encryptAes256Gcm(data, this.encryptionKeyHash);
+    }
+    /**
+     * AES-256-GCM으로 암호화된 데이터를 복호화합니다.
+     */
+    decryptData(data) {
+        if (!this.encryptionKeyHash) {
+            throw new Error("[Ddu64 decrypt] Encryption key is not set");
+        }
+        return decryptAes256Gcm(data, this.encryptionKeyHash);
+    }
     // --------------------------------------------------------------------------
     // 유틸리티 메서드
     // --------------------------------------------------------------------------
@@ -304,143 +684,85 @@ export class Ddu64 extends BaseDdu {
      * 크기 제한을 적용하여 압축을 해제합니다.
      */
     inflateWithLimit(data, maxBytes) {
-        if (maxBytes === Number.POSITIVE_INFINITY)
-            return inflateSync(data);
-        try {
-            return inflateSync(data, { maxOutputLength: maxBytes });
-        }
-        catch (e) {
-            const msg = String(e?.message ?? "");
-            const code = String(e?.code ?? "");
-            // maxOutputLength 미지원 시 fallback
-            if (msg.toLowerCase().includes("maxoutputlength") ||
-                msg.toLowerCase().includes("unknown option") ||
-                code === "ERR_INVALID_ARG_VALUE") {
-                const inflated = inflateSync(data);
-                if (inflated.length > maxBytes) {
-                    throw new Error(`[Ddu64 decode] Decompressed data exceeds limit. Size: ${inflated.length} bytes, Limit: ${maxBytes} bytes`);
-                }
-                return inflated;
-            }
-            // 출력 제한 초과
-            if (code === "ERR_BUFFER_TOO_LARGE" ||
-                msg.toLowerCase().includes("output length") ||
-                msg.toLowerCase().includes("buffer too large")) {
-                throw new Error(`[Ddu64 decode] Decompressed data exceeds limit. Limit: ${maxBytes} bytes`);
-            }
-            throw e;
-        }
+        return inflateWithLimitUtil(data, maxBytes, "Ddu64 decode");
     }
     // --------------------------------------------------------------------------
     // 푸터 파싱
     // --------------------------------------------------------------------------
     /**
      * 인코딩된 문자열의 푸터(패딩 정보)를 파싱합니다.
+     *
+     * 푸터 형식: {encodedData}{paddingChar}[ELYSIA][ENC]{digits}
+     * 끝에서부터 역순으로 파싱하여 paddingChar가 숫자인 경우도 안전하게 처리합니다.
      */
     parseFooter(input) {
         const inputLen = input.length;
         const pad = this.paddingChar;
         const padLen = pad.length;
+        const noFooter = { cleanedInput: input, paddingBits: 0, isCompressed: false, isEncrypted: false };
         if (inputLen < padLen)
-            return { cleanedInput: input, paddingBits: 0, isCompressed: false };
-        const markerLen = COMPRESS_MARKER.length;
+            return noFooter;
         const maxPaddingBits = Math.max(0, this.effectiveBitLength - 1);
         const maxDigits = maxPaddingBits.toString().length;
-        // 인덱스 기반 문자열 비교
-        const matchesAt = (str, pattern, start) => {
-            const pLen = pattern.length;
-            if (start < 0 || start + pLen > str.length)
-                return false;
-            for (let i = 0; i < pLen; i++) {
-                if (str.charCodeAt(start + i) !== pattern.charCodeAt(i))
-                    return false;
-            }
-            return true;
-        };
-        const isDigitCode = (code) => code >= 48 && code <= 57;
-        // 푸터 패턴 탐색
+        // 끝에서부터 역순 파싱: digits → ENC → ELYSIA → paddingChar
         for (let digitCount = Math.min(maxDigits, inputLen); digitCount >= 1; digitCount--) {
             const digitsStart = inputLen - digitCount;
-            const firstCode = input.charCodeAt(digitsStart);
-            if (!isDigitCode(firstCode))
-                continue;
+            // 1) trailing digits 확인
             let allDigits = true;
-            for (let i = digitsStart + 1; i < inputLen; i++) {
-                if (!isDigitCode(input.charCodeAt(i))) {
+            for (let i = digitsStart; i < inputLen; i++) {
+                const c = input.charCodeAt(i);
+                if (c < 48 || c > 57) {
                     allDigits = false;
                     break;
                 }
             }
             if (!allDigits)
                 continue;
-            const digitSuffix = input.substring(digitsStart);
-            const paddingBits = parseInt(digitSuffix, 10);
+            const digitStr = input.substring(digitsStart);
+            const paddingBits = parseInt(digitStr, 10);
             if (Number.isNaN(paddingBits) ||
                 paddingBits < 0 ||
                 paddingBits >= this.effectiveBitLength ||
-                digitSuffix !== paddingBits.toString())
+                digitStr !== paddingBits.toString())
                 continue;
-            // 압축 푸터: pad + marker + digits
-            if (digitsStart >= padLen + markerLen) {
-                const markerStart = digitsStart - markerLen;
-                const padStart = markerStart - padLen;
-                if (matchesAt(input, COMPRESS_MARKER, markerStart) &&
-                    matchesAt(input, pad, padStart)) {
-                    if (padStart % this.charLength !== 0) {
-                        throw new Error(`[Ddu64 decode] Invalid padding format. Misaligned padding marker`);
-                    }
-                    return {
-                        cleanedInput: input.substring(0, padStart),
-                        paddingBits,
-                        isCompressed: true,
-                    };
-                }
+            // 2) digits 앞에서 마커들 역순 확인
+            let pos = digitsStart;
+            let isEncrypted = false;
+            let isCompressed = false;
+            if (pos >= ENCRYPT_MARKER.length && input.substring(pos - ENCRYPT_MARKER.length, pos) === ENCRYPT_MARKER) {
+                isEncrypted = true;
+                pos -= ENCRYPT_MARKER.length;
+            }
+            if (pos >= COMPRESS_MARKER.length && input.substring(pos - COMPRESS_MARKER.length, pos) === COMPRESS_MARKER) {
+                isCompressed = true;
+                pos -= COMPRESS_MARKER.length;
             }
-            // 일반 푸터: pad + digits
-            const padStart = digitsStart - padLen;
-            if (padStart >= 0 && matchesAt(input, pad, padStart)) {
+            // 3) 마커 앞에서 padding 문자 확인
+            const padStart = pos - padLen;
+            if (padStart >= 0 && input.substring(padStart, pos) === pad) {
                 if (padStart % this.charLength !== 0) {
                     throw new Error(`[Ddu64 decode] Invalid padding format. Misaligned padding marker`);
                 }
                 return {
                     cleanedInput: input.substring(0, padStart),
                     paddingBits,
-                    isCompressed: false,
+                    isCompressed,
+                    isEncrypted,
                 };
             }
         }
-        // Fallback: lastIndexOf 기반
+        // Fallback: 역순 탐색이 유효한 패딩을 찾지 못한 경우,
+        // padding 문자가 존재하지만 tail이 잘못된 형식인지 확인하여 에러 보고
         const lastPadIdx = input.lastIndexOf(pad);
         if (lastPadIdx >= 0 && lastPadIdx % this.charLength === 0) {
             const tailStart = lastPadIdx + padLen;
             if (tailStart >= inputLen) {
                 throw new Error(`[Ddu64 decode] Invalid padding format. Missing padding length`);
             }
-            let tail = input.substring(tailStart);
-            const hasMarker = tail.length >= markerLen && matchesAt(tail, COMPRESS_MARKER, 0);
-            if (hasMarker) {
-                tail = tail.substring(markerLen);
-                if (!tail) {
-                    throw new Error(`[Ddu64 decode] Invalid padding format. Missing padding length`);
-                }
-            }
-            const paddingBits = parseInt(tail, 10);
-            if (Number.isNaN(paddingBits) ||
-                tail !== paddingBits.toString() ||
-                paddingBits < 0 ||
-                paddingBits >= this.effectiveBitLength) {
-                throw new Error(`[Ddu64 decode] Invalid padding format. Got: "${tail}"`);
-            }
-            const isCompressed = input
-                .slice(lastPadIdx + padLen)
-                .startsWith(COMPRESS_MARKER);
-            return {
-                cleanedInput: input.substring(0, lastPadIdx),
-                paddingBits,
-                isCompressed,
-            };
+            const tail = input.substring(tailStart);
+            throw new Error(`[Ddu64 decode] Invalid padding format. Got: "${tail}"`);
         }
-        return { cleanedInput: input, paddingBits: 0, isCompressed: false };
+        return noFooter;
     }
     // --------------------------------------------------------------------------
     // 인코딩 (Fast 모드 - 16비트 이하)
@@ -448,7 +770,7 @@ export class Ddu64 extends BaseDdu {
     /**
      * 일반 정수 연산을 사용한 빠른 인코딩
      */
-    encodeFast(bufferInput, compress) {
+    encodeFast(bufferInput, compress, encrypt) {
         const inputLen = bufferInput.length;
         if (inputLen === 0)
             return "";
@@ -503,13 +825,11 @@ export class Ddu64 extends BaseDdu {
                 resultParts[resultIdx++] = dduChar[index - div * dduLength];
             }
             resultParts[resultIdx++] = paddingChar;
-            resultParts[resultIdx++] = compress
-                ? COMPRESS_MARKER + paddingBits.toString()
-                : paddingBits.toString();
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + paddingBits.toString();
         }
-        else if (compress) {
+        else if (compress || encrypt) {
             resultParts[resultIdx++] = paddingChar;
-            resultParts[resultIdx++] = COMPRESS_MARKER + "0";
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + "0";
         }
         resultParts.length = resultIdx;
         return resultParts.join("");
@@ -579,8 +899,40 @@ export class Ddu64 extends BaseDdu {
                 }
             }
         }
+        else if (this.useAsciiLookup && this.fastAsciiLookup && charLength === 1) {
+            // 가변 길이 charset - ASCII 최적화 경로
+            const asciiLookup = this.fastAsciiLookup;
+            const maxVal = this.maxBinaryValue;
+            for (let i = 0; i < inputLen; i += chunkSize) {
+                const code1 = cleanedInput.charCodeAt(i);
+                const code2 = cleanedInput.charCodeAt(i + 1);
+                const v1 = code1 < 128 ? asciiLookup[code1] : -1;
+                const v2 = code2 < 128 ? asciiLookup[code2] : -1;
+                if (v1 < 0) {
+                    throw new Error(`[Ddu64 decode] Invalid character "${cleanedInput[i]}" at ${i}`);
+                }
+                if (v2 < 0) {
+                    throw new Error(`[Ddu64 decode] Invalid character "${cleanedInput[i + 1]}" at ${i + charLength}`);
+                }
+                const value = v1 * dduLength + v2;
+                if (value >= maxVal) {
+                    throw new Error(`[Ddu64 decode] Value ${value} exceeds range`);
+                }
+                accumulator = (accumulator << bitLength) | value;
+                accumulatorBits += bitLength;
+                if (i + chunkSize >= inputLen && paddingBits > 0) {
+                    accumulator >>= paddingBits;
+                    accumulatorBits -= paddingBits;
+                }
+                while (accumulatorBits >= BYTE_BITS) {
+                    accumulatorBits -= BYTE_BITS;
+                    buffer[bufIdx++] = (accumulator >> accumulatorBits) & BYTE_MASK;
+                    accumulator &= (1 << accumulatorBits) - 1;
+                }
+            }
+        }
         else {
-            // 가변 길이 charset
+            // 가변 길이 charset - 일반 룩업 경로
             const lookup = this.dduBinaryLookup;
             for (let i = 0; i < inputLen; i += chunkSize) {
                 const c1 = cleanedInput.slice(i, i + charLength);
@@ -618,7 +970,7 @@ export class Ddu64 extends BaseDdu {
     /**
      * BigInt를 사용한 대형 비트 인코딩
      */
-    encodeBigInt(bufferInput, compress) {
+    encodeBigInt(bufferInput, compress, encrypt) {
         const inputLen = bufferInput.length;
         if (inputLen === 0)
             return "";
@@ -673,13 +1025,11 @@ export class Ddu64 extends BaseDdu {
                 resultParts[resultIdx++] = dduChar[index - div * dduLength];
             }
             resultParts[resultIdx++] = this.paddingChar;
-            resultParts[resultIdx++] = compress
-                ? COMPRESS_MARKER + paddingBits.toString()
-                : paddingBits.toString();
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + paddingBits.toString();
         }
-        else if (compress) {
+        else if (compress || encrypt) {
             resultParts[resultIdx++] = this.paddingChar;
-            resultParts[resultIdx++] = COMPRESS_MARKER + "0";
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + "0";
         }
         resultParts.length = resultIdx;
         return resultParts.join("");
@@ -764,55 +1114,58 @@ export class Ddu64 extends BaseDdu {
      * Charset을 정규화합니다.
      */
     normalizeCharSet(current, shouldThrow, dduOptions) {
-        let state = { ...current };
-        let retryCount = 0;
-        const maxRetries = 3;
-        while (retryCount < maxRetries) {
+        // 1차 시도: 주어진 charset으로 정규화
+        // 실패 시 1회만 fallback 시도 (동일 fallback을 반복해도 결과는 동일)
+        const attempts = [current, null];
+        for (const attempt of attempts) {
+            const state = attempt ? { ...attempt } : this.getFallbackCharSet(dduOptions);
             try {
                 // 중복 문자 제거
-                const uniqueChars = Array.from(new Set(state.charSet));
-                if (uniqueChars.length !== state.charSet.length) {
+                let charSet = state.charSet;
+                let requiredLength = state.requiredLength;
+                const uniqueChars = Array.from(new Set(charSet));
+                if (uniqueChars.length !== charSet.length) {
                     if (shouldThrow) {
-                        const duplicates = state.charSet.filter((c, i) => state.charSet.indexOf(c) !== i);
+                        const duplicates = charSet.filter((c, i) => charSet.indexOf(c) !== i);
                         throw new Error(`[Ddu64 normalizeCharSet] Character set contains duplicate characters: [${[...new Set(duplicates)].join(", ")}]`);
                     }
-                    state.charSet = uniqueChars;
+                    charSet = uniqueChars;
                     if (!state.isPredefined)
-                        state.requiredLength = state.charSet.length;
+                        requiredLength = charSet.length;
                 }
                 // 문자 수 검증
-                if (state.charSet.length < state.requiredLength) {
-                    throw new Error(`[Ddu64 normalizeCharSet] Insufficient characters. Required: ${state.requiredLength}, Has: ${state.charSet.length}`);
+                if (charSet.length < requiredLength) {
+                    throw new Error(`[Ddu64 normalizeCharSet] Insufficient characters. Required: ${requiredLength}, Has: ${charSet.length}`);
                 }
-                if (state.requiredLength < 2) {
+                if (requiredLength < 2) {
                     throw new Error(`[Ddu64 normalizeCharSet] At least 2 unique characters required.`);
                 }
-                if (state.charSet.length === 0) {
+                if (charSet.length === 0) {
                     throw new Error(`[Ddu64 normalizeCharSet] Empty charset.`);
                 }
                 // 문자 길이 일관성 검증
-                const charLength = state.charSet[0].length;
-                const invalidChar = state.charSet.find((c) => c.length !== charLength);
+                const charLength = charSet[0].length;
+                const invalidChar = charSet.find((c) => c.length !== charLength);
                 if (invalidChar) {
                     if (shouldThrow) {
                         throw new Error(`[Ddu64 normalizeCharSet] Inconsistent char length. Expected ${charLength}, found "${invalidChar}" (${invalidChar.length})`);
                     }
-                    throw new Error("internal retry");
+                    continue; // fallback으로 재시도
                 }
                 // 패딩 검증
                 if (state.padding.length !== charLength) {
                     throw new Error(`[Ddu64 normalizeCharSet] Padding length mismatch. Expected ${charLength}, got ${state.padding.length}`);
                 }
-                if (state.charSet.includes(state.padding)) {
+                if (charSet.includes(state.padding)) {
                     if (shouldThrow) {
                         throw new Error(`[Ddu64 normalizeCharSet] Padding character "${state.padding}" conflicts with charset.`);
                     }
-                    state.charSet = state.charSet.filter((c) => c !== state.padding);
+                    charSet = charSet.filter((c) => c !== state.padding);
                 }
                 // 불필요한 배열 복사 방지
-                const finalSet = state.charSet.length === state.requiredLength
-                    ? state.charSet
-                    : state.charSet.slice(0, state.requiredLength);
+                const finalSet = charSet.length === requiredLength
+                    ? charSet
+                    : charSet.slice(0, requiredLength);
                 return {
                     charSet: finalSet,
                     padding: state.padding,
@@ -821,13 +1174,12 @@ export class Ddu64 extends BaseDdu {
                 };
             }
             catch (e) {
-                if (shouldThrow && !e.message.includes("internal retry"))
+                if (shouldThrow)
                     throw e;
-                state = this.getFallbackCharSet(dduOptions);
-                retryCount++;
+                // fallback 시도로 continue
             }
         }
-        // 최종 fallback
+        // 최종 fallback (이론상 도달 불가, 방어 코드)
         const fallback = this.getFallbackCharSet(dduOptions);
         return {
             charSet: fallback.charSet.slice(0, fallback.requiredLength),
@@ -933,6 +1285,33 @@ export class Ddu64 extends BaseDdu {
             throw new Error(`CharSet with symbol ${symbol} not found`);
         return cs;
     }
+    /**
+     * URL-Safe 모드 시 charset/padding이 역변환 대상 문자를 포함하지 않는지 검증합니다.
+     * 역변환 대상 문자("-", "_", ".")가 charset이나 padding에 있으면
+     * fromUrlSafe 시 해당 문자가 "+", "/", "="로 변환되어 데이터가 손상됩니다.
+     *
+     * @returns URL-Safe 모드를 활성화해도 안전한 경우 true
+     */
+    isUrlSafeCompatible(charSet, paddingChar, shouldThrow) {
+        const conflictChars = Object.keys(URL_SAFE_REVERSE_MAP); // ["-", "_", "."]
+        for (const ch of conflictChars) {
+            for (const c of charSet) {
+                if (c.includes(ch)) {
+                    const msg = `[Ddu64 Constructor] URL-Safe mode conflict: charset character "${c}" contains "${ch}" which would be transformed to "${URL_SAFE_REVERSE_MAP[ch]}" during decoding.`;
+                    if (shouldThrow)
+                        throw new Error(msg);
+                    return false;
+                }
+            }
+            if (paddingChar.includes(ch)) {
+                const msg = `[Ddu64 Constructor] URL-Safe mode conflict: padding character "${paddingChar}" contains "${ch}" which would be transformed to "${URL_SAFE_REVERSE_MAP[ch]}" during decoding.`;
+                if (shouldThrow)
+                    throw new Error(msg);
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * 커스텀 charset의 조합 중복을 검증합니다.
      */