@ddunigma/node 4.0.1 → 6.0.0

package/README.md

@@ -2,13 +2,11 @@
 
 [![npm version](https://badge.fury.io/js/@ddunigma%2Fnode.svg)](https://www.npmjs.com/package/@ddunigma/node)
 
-커스텀 charset을 사용하는 Base64 스타일 인코더/디코더 라이브러리입니다.
-
 V2 추가사항
 
 - 이제 한글 종성 결합 시스템을 활용하여 8개 기본 문자 × 8개 종성으로 64가지 조합을 만들어, 6비트를 한 글자로 표현합니다.
 
-### Credits
+## Credits
 
 - Origin implementation by:
   - [@i3ls](https://github.com/i3l3)
@@ -17,7 +15,7 @@ V2 추가사항
 
 ## Requirements
 
-- **Node.js >= 22.0.0**
+- Node.js >= 22.0.0
 
 ## Install
 
@@ -41,405 +39,65 @@ dduV1.encode("안녕하세요"); // ".우땨땨이?땨뜌.이.뜌이?이!.우우
 dduV1.decode(".우땨땨이?땨뜌.이.뜌이?이!.우우땨이?우뜌.우땨뜌이이.뜌.우땨땨!이이야"); // "안녕하세요"
 ```
 
----
+## 진입점
 
-## Binary Data
+| 진입점                   | 기능                                    | 용도                  |
+| ------------------------ | --------------------------------------- | --------------------- |
+| `@ddunigma/node`         | 인코딩 + 한글 난독화                    | Node 기본 lean        |
+| `@ddunigma/node/browser` | 인코딩 + 한글 난독화                    | 브라우저/Workers lean |
+| `@ddunigma/node/secure`  | 압축/암호화/체크섬/Web Streams + 난독화 | 배터리 필요할 때      |
+| `@ddunigma/node/core`    | 순수 인코딩/디코딩                      | 최소 번들             |
 
 ```typescript
-const ddu = new Ddu64();
-const input = new Uint8Array([0, 1, 127, 128, 255]);
-
-const encoded = ddu.encode(input);
-const bytes = ddu.decodeToUint8Array(encoded);
-const buffer = ddu.decodeToBuffer(encoded); // Node.js entry only
+import { Ddu64 as NodeDdu64 } from "@ddunigma/node";
+import { Ddu64 as BrowserDdu64 } from "@ddunigma/node/browser";
+import { Ddu64 as SecureDdu64 } from "@ddunigma/node/secure";
+import { Ddu64 as CoreDdu64 } from "@ddunigma/node/core";
 ```
 
-## Presets
-
-```typescript
-import { Ddu64, DduSetSymbol } from "@ddunigma/node";
-
-// 기본값 - 한글 종성 결합 64문자
-new Ddu64();
-
-// 구버전 호환 8문자 (아래 두 방법 모두 사용가능)
-new Ddu64({ dduSetSymbol: DduSetSymbol.DDU_V1 });
-new Ddu64(undefined, undefined, { dduSetSymbol: DduSetSymbol.DDU_V1 });
-
-// 영문+숫자 64문자 (아래 두 방법 모두 사용가능)
-new Ddu64({ dduSetSymbol: DduSetSymbol.ONECHARSET });
-new Ddu64(undefined, undefined, { dduSetSymbol: DduSetSymbol.ONECHARSET });
-```
-
-| Symbol       | 문자 수 | 설명                               |
-| ------------ | ------: | ---------------------------------- |
-| `DDU`        |      64 | 한글 기본 문자 8개 × 종성 8개 조합 |
-| `DDU_V1`     |       8 | 기존 8문자 쌍 방식 (하위 호환)     |
-| `ONECHARSET` |      64 | 영문, 숫자, 일부 특수문자          |
-
-## Custom Charset
-
-```typescript
-// 문자열로 직접 지정
-const base64Like = new Ddu64(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
-  "=",
-);
-
-// 한글 종성 조합으로 커스텀 charset 생성
-const hangulCoda = new Ddu64(["가", "나", "다", "라"], "뭐", {
-  codaChar: ["", "ㄱ", "ㄲ", "ㄷ"],
-});
-// → 가, 각, 갂, 갇, 나, 낙, 낚, 낟, 다, 닥, 닦, 닫, 라, 락, 랔, 랗 (16문자)
-```
-
-커스텀 charset의 각 심볼과 `paddingChar`는 단일 UTF-16 코드 유닛 문자여야 합니다.
-이모지처럼 surrogate pair가 필요한 문자나 여러 문자로 이루어진 심볼은 지원하지 않습니다.
-
-## CharsetBuilder
+## 한글 난독화
 
 ```typescript
-import { CharsetBuilder, Ddu64 } from "@ddunigma/node";
+import { Ddu64 } from "@ddunigma/node";
 
-// Base64에서 혼동 문자 제거 후 2의 제곱수로 맞추기
-const { charset, padding } = CharsetBuilder.base64()
-  .excludeConfusing()
-  .limitToPowerOfTwo()
-  .buildWithPadding();
-
-const ddu = new Ddu64(charset, padding);
-
-// 유니코드 범위에서 생성
-const chars = CharsetBuilder.fromUnicodeRange(0x4e00, 0x4e3f)
-  .shuffle(12345)
-  .limitToPowerOfTwo()
-  .build();
-```
-
-## Compression
-
-```typescript
-const ddu = new Ddu64({
-  compress: true, // 압축 활성화
-  compressionAlgorithm: "deflate", // "deflate" | "brotli"
-  compressionLevel: 6, // deflate: 0-9, brotli: 0-11
-});
-
-const encoded = ddu.encode("A".repeat(1000)); // 압축되어 짧아짐
+const ddu = new Ddu64({ obfuscate: true });
+const encoded = ddu.encode("재미있는 난독화");
 const decoded = ddu.decode(encoded);
 ```
 
-압축은 원본보다 작아질 때만 적용됩니다. 압축 결과가 더 크면 비압축으로 저장됩니다.
-브라우저 진입점은 `deflate-raw`를 지원하는 CompressionStream/DecompressionStream 런타임에서 압축을 사용합니다.
-브라우저 Brotli는 런타임 지원 여부를 feature detection으로 확인하며, Web API 특성상 `compressionLevel`은 적용되지 않을 수 있습니다.
+키 없는 난독화는 암호화가 아닙니다. 동일 입력은 항상 동일 출력이 되어 기밀성·변조 방지를 제공하지
+않습니다.
 
-## Encryption
+## 압축, 암호화, 체크섬
 
 ```typescript
-// SHA-256 키 파생 (기본)
+import { Ddu64 } from "@ddunigma/node/secure";
+
 const ddu = new Ddu64({
+  compress: true,
   encryptionKey: "my-secret-key",
-});
-
-const encoded = ddu.encode("secret message");
-const decoded = ddu.decode(encoded); // 같은 키로만 복호화 가능
-
-// PBKDF2 키 파생
-const dduPbkdf2 = new Ddu64({
-  encryptionKey: "user password",
   keyDerivation: {
     algorithm: "pbkdf2",
-    salt: "app-specific-salt",
-    iterations: 210_000,
-    hash: "SHA-256",
+    salt: "my-application-salt",
+    iterations: 600_000,
   },
-});
-```
-
-PBKDF2 `iterations`는 기본값이 `210_000`이며, `10_000` 미만의 양수는 `10_000`으로 보정됩니다.
-0 이하 또는 유한하지 않은 값은 기본값으로 대체됩니다.
-
-## Checksum
-
-```typescript
-const ddu = new Ddu64({ checksum: true });
-
-const encoded = ddu.encode("data"); // CRC32 체크섬 포함
-const decoded = ddu.decode(encoded); // 무결성 검증 후 반환
-```
-
-## URL-Safe
-
-```typescript
-const ddu = new Ddu64("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", "=", {
-  urlSafe: true,
-});
-
-// +→- /→_ =→. 로 자동 변환
-const encoded = ddu.encode("URL safe text");
-```
-
-## Chunking
-
-```typescript
-const ddu = new Ddu64({
-  chunkSize: 76,
-  chunkSeparator: "\n",
-});
-
-const encoded = ddu.encode("long data ".repeat(100));
-// 76자마다 줄바꿈 삽입
-```
-
-## Obfuscation (한글 난독화)
-
-```typescript
-const ddu = new Ddu64({
-  encryptionKey: "secret",
-  obfuscate: true, // 암호화 필수
-});
-
-const encoded = ddu.encode("hello");
-// 출력이 한글 음절 블록(U+AC00–U+D7A3)으로 변환됨
-```
-
-## Async (브라우저 호환)
-
-```typescript
-// 브라우저에서는 async 메서드 사용
-import { Ddu64 } from "@ddunigma/node/browser";
-
-const ddu = new Ddu64();
-const encoded = await ddu.encodeAsync("browser text");
-const decoded = await ddu.decodeAsync(encoded);
-```
-
-Node.js에서도 async 메서드를 사용할 수 있습니다. v4부터 루트 진입점(`@ddunigma/node`)은 런타임 조건형 export를 사용하므로 브라우저 번들러와 Workers 계열 런타임에서는 BrowserAdapter 경로로 해석됩니다. 명시적인 브라우저 경로가 필요하면 `@ddunigma/node/browser`를 사용하세요.
-코어 진입점(`@ddunigma/node/core`)은 기본 인코딩/디코딩만 포함하며, 압축/암호화가 필요하면 명시적으로 어댑터를 전달하세요.
-
-## Web Streams
-
-```typescript
-import { Ddu64, createReadableEncodeStream, createReadableDecodeStream } from "@ddunigma/node";
-
-const ddu = new Ddu64({
-  compress: true,
-  encryptionKey: "stream-key",
+  checksum: true,
 });
 
-const encodedStream = readableByteStream.pipeThrough(
-  createReadableEncodeStream(ddu, { compress: true }),
-);
-
-const decodedStream = encodedStream.pipeThrough(createReadableDecodeStream(ddu));
-```
-
-인코딩 스트림은 압축/암호화/체크섬이 꺼져 있고 2의 제곱수 charset일 때 청크 단위로 즉시 출력합니다.
-디코딩 스트림은 footer의 압축/암호화 메타데이터를 최종 신뢰하므로 payload를 모아 `flush`에서 처리합니다.
-
-## WASM Acceleration
-
-```typescript
-import { Ddu64, preloadWasm } from "@ddunigma/node";
-
-await preloadWasm(); // 동기 encode/decode hot path에서 WASM을 쓰려면 먼저 완료되어야 함
-
-const ddu = new Ddu64({
-  wasmThreshold: 4096, // 이 크기 이상일 때 WASM 사용
-  // wasmThreshold: Infinity, // WASM hot path 비활성화
-});
-
-const encoded = ddu.encode(new Uint8Array(1024 * 1024));
-```
-
-`encode()`/`decode()`의 동기 hot path는 이미 로드된 WASM만 사용합니다.
-`preloadWasm()`이 완료되지 않았거나 WASM을 사용할 수 없으면 JavaScript로 폴백됩니다.
-
-## Progress Callback
-
-```typescript
-const ddu = new Ddu64({ compress: true });
-
-ddu.encode("data", {
-  onProgress: ({ percent, stage }) => {
-    console.log(`${stage}: ${percent}%`);
-    // stage: start → compress → encrypt → encode → done
-  },
-});
-```
-
-## Stats
-
-```typescript
-const ddu = new Ddu64({ compress: true });
-const stats = ddu.getStats("A".repeat(1000));
-
-// { originalSize, encodedSize, compressedSize, compressionRatio, expansionRatio, charsetSize, bitLength }
-```
-
-## Size Limits
-
-```typescript
-const ddu = new Ddu64({
-  maxDecodedBytes: 10 * 1024 * 1024, // 디코딩 최대 크기 (기본 64MB)
-  maxDecompressedBytes: 50 * 1024 * 1024, // 압축해제 최대 크기 (기본 64MB)
-});
-```
-
-## Custom Errors
-
-```typescript
-import { Ddu64, Ddu64ErrorCode, isDdu64Error } from "@ddunigma/node";
-
-const ddu = new Ddu64({ checksum: true });
-
-try {
-  ddu.decode(tamperedInput);
-} catch (err) {
-  if (isDdu64Error(err) && err.code === Ddu64ErrorCode.ChecksumMismatch) {
-    // 체크섬 불일치 처리
-  }
-}
-```
-
-인코딩, 디코딩, 압축, 암호화, 체크섬, charset, 크기 제한, adapter, stream 실패는
-`Ddu64Error` 계열로 래핑됩니다. 모든 공개 진입점(`@ddunigma/node`,
-`@ddunigma/node/browser`, `@ddunigma/node/core`)에서 같은 에러 타입과
-`Ddu64ErrorCode`를 export합니다.
-
----
-
-## API
-
-### Node Entry
-
-```typescript
-class Ddu64 {
-  encode(data: string | Uint8Array, options?: DduOptions): string;
-  decode(encoded: string, options?: DduOptions): string;
-  decodeToUint8Array(encoded: string, options?: DduOptions): Uint8Array;
-  decodeToBuffer(encoded: string, options?: DduOptions): Buffer;
-
-  encodeAsync(data: string | Uint8Array, options?: DduOptions): Promise<string>;
-  decodeAsync(encoded: string, options?: DduOptions): Promise<string>;
-  decodeToUint8ArrayAsync(encoded: string, options?: DduOptions): Promise<Uint8Array>;
-  decodeToBufferAsync(encoded: string, options?: DduOptions): Promise<Buffer>;
-
-  getStats(data: string | Uint8Array, options?: DduOptions): DduEncodeStats;
-  getCharSetInfo(): CharSetInfo;
-}
-```
-
-### Browser Entry
-
-```typescript
-class Ddu64 {
-  encode(data: string | Uint8Array, options?: DduOptions): string;
-  decode(encoded: string, options?: DduOptions): string;
-  decodeToUint8Array(encoded: string, options?: DduOptions): Uint8Array;
-
-  encodeAsync(data: string | Uint8Array, options?: DduOptions): Promise<string>;
-  decodeAsync(encoded: string, options?: DduOptions): Promise<string>;
-  decodeToUint8ArrayAsync(encoded: string, options?: DduOptions): Promise<Uint8Array>;
-
-  getStats(data: string | Uint8Array, options?: DduOptions): DduEncodeStats;
-  getCharSetInfo(): CharSetInfo;
-}
-```
-
-브라우저 진입점(`@ddunigma/node/browser`)은 `Buffer` API를 노출하지 않습니다.
-
-### Core Entry
-
-```typescript
-class Ddu64 {
-  encode(data: string | Uint8Array, options?: DduOptions): string;
-  decode(encoded: string, options?: DduOptions): string;
-  decodeToUint8Array(encoded: string, options?: DduOptions): Uint8Array;
-
-  encodeAsync(data: string | Uint8Array, options?: DduOptions): Promise<string>;
-  decodeAsync(encoded: string, options?: DduOptions): Promise<string>;
-  decodeToUint8ArrayAsync(encoded: string, options?: DduOptions): Promise<Uint8Array>;
-
-  getStats(data: string | Uint8Array, options?: DduOptions): DduEncodeStats;
-  getCharSetInfo(): CharSetInfo;
-}
-```
-
-코어 진입점(`@ddunigma/node/core`)은 플랫폼 어댑터를 자동 로드하지 않습니다.
-압축 또는 암호화가 필요한 async 호출에는 `adapter`를 명시적으로 전달하세요.
-
-## Constructor Options
-
-```typescript
-// 옵션만 전달 (권장)
-new Ddu64(options?);
-
-// charset 직접 지정
-new Ddu64(dduChar, paddingChar, options?);
+const encoded = ddu.encode("보호할 데이터");
+const decoded = ddu.decode(encoded);
 ```
 
-| Option                 | Type                    | Default     | 설명                  |
-| ---------------------- | ----------------------- | ----------- | --------------------- |
-| `dduSetSymbol`         | `DduSetSymbol`          | `DDU`       | 프리셋 선택           |
-| `dduChar`              | `string \| string[]`    | -           | 커스텀 charset        |
-| `paddingChar`          | `string`                | -           | 패딩 문자             |
-| `codaChar`             | `string[]`              | -           | 종성 조합 문자        |
-| `compress`             | `boolean`               | `false`     | 압축 활성화           |
-| `compressionAlgorithm` | `"deflate" \| "brotli"` | `"deflate"` | 압축 알고리즘         |
-| `compressionLevel`     | `number`                | `6`         | 압축 레벨             |
-| `encryptionKey`        | `string`                | -           | AES-256-GCM 암호화 키 |
-| `keyDerivation`        | `KeyDerivationOptions`  | `sha256`    | 키 파생 방식          |
-| `checksum`             | `boolean`               | `false`     | CRC32 체크섬          |
-| `urlSafe`              | `boolean`               | `false`     | URL-Safe 변환         |
-| `obfuscate`            | `boolean`               | `false`     | 한글 난독화           |
-| `chunkSize`            | `number`                | -           | 청크 분할 크기        |
-| `chunkSeparator`       | `string`                | `"\n"`      | 청크 구분자           |
-| `maxDecodedBytes`      | `number`                | `67108864`  | 디코딩 크기 제한      |
-| `maxDecompressedBytes` | `number`                | `67108864`  | 압축해제 크기 제한    |
-| `wasmThreshold`        | `number`                | `4096`      | WASM 사용 임계값 (`Infinity`면 비활성화) |
-| `throwOnError`         | `boolean`               | `false`     | 초기화 에러 시 throw  |
-
-## Per-Call Options
-
-`encode`, `decode`, `encodeAsync`, `decodeAsync` 등에서 호출별로 오버라이드 가능:
-
-| Option                 | Type                    | 설명               |
-| ---------------------- | ----------------------- | ------------------ |
-| `compress`             | `boolean`               | 압축 사용 여부     |
-| `compressionAlgorithm` | `"deflate" \| "brotli"` | 압축 알고리즘      |
-| `compressionLevel`     | `number`                | 압축 레벨          |
-| `encrypt`              | `boolean`               | 암호화 사용 여부   |
-| `checksum`             | `boolean`               | 체크섬 사용 여부   |
-| `obfuscate`            | `boolean`               | 난독화 사용 여부   |
-| `chunkSize`            | `number`                | 청크 크기          |
-| `maxDecodedBytes`      | `number`                | 디코딩 크기 제한   |
-| `maxDecompressedBytes` | `number`                | 압축해제 크기 제한 |
-| `onProgress`           | `(info) => void`        | 진행률 콜백        |
-
-## Entry Points
+AES-256-GCM은 부가 기능입니다. 저엔트로피 키를 쓰면 애플리케이션 고유 `salt`와 높은
+`iterations`를 명시하세요.
 
-| Runtime / Target                | Import Path                         | 용도                                  |
-| ------------------------------- | ----------------------------------- | ------------------------------------- |
-| Node.js server/CLI              | `@ddunigma/node`                    | Node.js 전체 기능 (동기+비동기)       |
-| Browser / Vite / webpack        | `@ddunigma/node` 또는 `/browser`    | 브라우저 최적화 (BrowserAdapter 기본) |
-| Cloudflare Workers / Deno / Bun | `@ddunigma/node` 또는 `/browser`    | Node.js 내장 모듈 없는 Web API 경로   |
-| Adapter 직접 주입 최소 번들     | `@ddunigma/node/core`               | 최소 코어 (인코딩/디코딩만)           |
+## Reference
 
-루트 진입점은 v4부터 `browser`/`worker`/`workerd`/`deno`/`bun`/`node` 조건을 가진 conditional export입니다. Node.js에서는 기존처럼 `Buffer` API와 NodeAdapter를 노출하고, 브라우저 및 Workers 계열 번들러에서는 Node.js 내장 모듈 없는 BrowserAdapter 경로로 해석됩니다. 런타임 조건을 알 수 없는 ESM 환경의 기본 fallback도 browser 번들을 사용합니다.
-Node.js 런타임에서는 `node` 조건이 `index.js`/`index.cjs`를 선택하므로 기본 import로 NodeAdapter와 `decodeToBuffer()`를 사용할 수 있습니다.
-
-## Build & Test
-
-```bash
-pnpm test
-pnpm typecheck
-pnpm build
-pnpm lint
-pnpm pack:check
-pnpm bench
-```
+전체 옵션, 커스텀 charset, URL-Safe, Web Streams, `/core` 고급 사용법은
+[docs/REFERENCE.md](docs/REFERENCE.md)를 보세요.
 
-## License
+## Migration notes
 
-BSD-2-Clause
+6.0에서 압축/암호화/체크섬/Web Streams는 기본 진입점에서 `@ddunigma/node/secure`로 이동했습니다.
+WASM API(`preloadWasm`, `getWasmCodec`, `wasmThreshold`)는 제거됐습니다. 기존 wire format은 유지되어
+기존 데이터는 그대로 디코딩됩니다.

package/ROADMAP.md

@@ -0,0 +1,92 @@
+# Roadmap / 범위 결정 기록
+
+외부 리뷰에서 제기됐던 대형 항목들의 **범위 결정 기록**이다. 두 항목(④ 자기기술 KDF
+envelope, ⑤ 프레임드 스트리밍 `DDS2`) 모두 검토·시제 구현 후 **경량 인코더 정체성과의
+미스매치**를 이유로 제외했다. 핵심 원칙: 신규 **영구 wire 포맷을 추가하지 않고**, 기존
+포맷의 하위호환(기존 데이터 디코딩)을 반드시 유지한다.
+
+---
+
+## ④ 암호화 KDF envelope v5 (self-describing KDF) — ❌ 제외 (범위 밖)
+
+> 결정: **구현하지 않음.** opt-in(`encryptionVersion: 5`)으로 한 차례 구현했다가 되돌렸다.
+> 이유: 자기기술 KDF envelope는 **인코딩 유틸리티의 정체성과 미스매치**다. 새로운 영구
+> 암호화 wire 포맷을 추가하면 장기 보안 책임(salt 인증, nonce 유일성, 다운그레이드 방어,
+> KDF 알고리즘 노후화 대응)을 라이브러리가 떠안게 되는데, 이는 본 라이브러리의 핵심 가치
+> (zero-dependency 커스텀 charset 인코딩)와 맞지 않는다. 강한 키 파생이 필요한 사용처는
+> 애플리케이션 레벨에서 전용 KDF/암호화 라이브러리를 쓰는 것이 옳다.
+>
+> 현행 암호화(AES-256-GCM + PBKDF2/sha256, 호출자 지정 `salt`/`iterations`)는 유지한다.
+> 저엔트로피 키 사용 시 가이드는 README의 키 파생 섹션 참고(앱 고유 `salt` + 높은
+> `iterations` 권장). 포맷 변경 없는 문서 수준 권고다.
+
+---
+
+## ⑤ 진짜 스트리밍 (프레임드 와이어 포맷 `DDS2`) — ❌ 제외 (범위 밖, 제거됨)
+
+> 결정: **구현하지 않음(제거 완료).** opt-in(`createFramedEncodeStream`/`createFramedDecodeStream`,
+> `src/streams/FramedStreams.ts`)으로 한 차례 구현했다가 ④ v5 KDF와 같은 이유로 되돌렸다.
+> 이유: 신규 영구 스트림 wire 포맷(`DDS2`)은 **경량 인코더 정체성과 미스매치**다. 한 번
+> 릴리스하면 호환 부담이 영구이고, 프레임 nonce/AAD·절단·재정렬·교차스트림·다운그레이드
+> 방어라는 **장기 보안 책임**을 라이브러리가 떠안게 된다. 이는 핵심 가치(zero-dependency
+> 커스텀 charset 인코딩 + 경량 난독화)와 맞지 않는다. `DDS2`는 published(5.x) 전에 추가된
+> 신규 표면이라 제거해도 기존 데이터 호환에 영향이 없다.
+>
+> 대용량 데이터는 애플리케이션 레벨에서 자체 프레이밍 후 `encode`/`decode`를 프레임마다
+> 호출하거나, 전용 스트리밍/암호화 라이브러리를 쓰는 것이 옳다. 기존 비프레임 Web Streams
+> (`createReadableEncodeStream`/`createReadableDecodeStream`)는 유지한다(2의 제곱수 charset +
+> 압축/암호화/체크섬 미사용 시 청크 스트리밍, 그 외는 buffered transform).
+>
+> 용어 주의: 위 ④의 폐기된 "v5 KDF envelope"와, 코드에 현역인 "스코프 자기기술 체크섬
+> 마커(`CK`, 과거 'v5 체크섬'으로 불림)"는 **별개**다. 후자는 폐기 대상이 아니며 정상 동작한다.
+
+### (참고) 제거 시 검토했던 문제와 설계
+
+- 현재 압축/암호화/체크섬 스트림은 사실상 **전체 버퍼링**(footer가 최종 메타라 전량 축적
+  후 처리). 대용량 스트리밍에서 메모리 상한이 곧 전체 크기. → 경량 정체성 유지를 위해
+  라이브러리가 해결하지 않고 애플리케이션 레벨에 위임한다.
+- 프레임 단위 포맷(`DDS2`)은 상수 메모리를 달성하나 신규 영구 포맷 + nonce/truncation 보안
+  책임을 동반 → 비용이 가치를 초과한다고 판단해 제외.
+
+---
+
+## secure 진입점 — 전부 유지 결정 (full retention)
+
+> 결정: **`@ddunigma/node/secure`의 압축(deflate/brotli) + AES-256-GCM 암호화 + CRC32 체크섬 +
+> Web Streams를 전부 유지한다.** 위 ④ v5 KDF·⑤ DDS2를 "신규 영구 wire 포맷 추가 + 장기 보안
+> 책임"을 이유로 제외한 것과 달리, secure의 현행 기능들은 **이미 존재하는 안정된 표면**이며 신규
+> 영구 포맷을 늘리지 않는다(V4 페이로드/DDS1 스트림 헤더 불변). 따라서 분리·폐기 없이 전부
+> 유지한다.
+>
+> 진입점 구성은 4종으로 고정한다: 기본(`@ddunigma/node`, lean = 인코딩+난독화),
+> `@ddunigma/node/browser`(lean), `@ddunigma/node/secure`(배터리 풀세트),
+> `@ddunigma/node/core`(순수 인코딩). lean 진입점은 어댑터(zlib/crypto)를 정적 import하지 않아
+> 트리셰이킹되고, secure 진입점에만 배터리가 포함된다. 이 분리로 "경량 기본 + 필요 시 배터리"를
+> 동시에 만족한다.
+>
+> 비고: lean 진입점 번들 여유가 빠듯하므로(size-limit 예산 근접) **신규 기능은 secure/core
+> 쪽에 싣고 lean 경로는 가볍게 유지**한다.
+
+---
+
+## 인코딩 성능 최적화 — ✅ 완료 (출력 불변)
+
+> `encoding-perf-optimization` 스펙으로 한글/커스텀 charset hot path를 최적화했다. `bitLength 6/8`
+> 직접 매핑 언롤 융합으로 인코드 `packPow2ToString` ~40→~183 MB/s(약 4.5x), 디코드
+> `unpackPow2FromString` ~150→~420 MB/s 개선. **출력 바이트·wire format은 100% 불변**이며
+> 동치 오라클(raw `bitPackEncode`/`bitPackDecode`)·고정 벡터·property 테스트로 고정된다.
+>
+> 표준 base64 알파벳은 네이티브 fast path(`Uint8Array.toBase64`/`fromBase64`)로 계속 가속되며,
+> 한글 charset은 비-ASCII 출력 특성상 네이티브 base64 속도에 도달할 수 없다(구조적 천장). 남은
+> 속도 레버는 한계효용이 낮아 추가 최적화는 보류한다.
+
+---
+
+## 권고
+
+- 신규 **영구 wire 포맷은 추가하지 않는다**(④ v5 KDF, ⑤ DDS2 모두 제외). 기존 V4/DDS1
+  단일 페이로드 포맷이 마지막 영구 표면이며, 회귀 테스트로 디코딩 호환을 고정한다.
+- 경량 인코더 정체성에 부합하지 않는 대형 기능은 애플리케이션 레벨/전용 라이브러리로 위임한다.
+- secure 진입점의 현행 배터리(압축/암호화/체크섬/Web Streams)는 전부 유지한다(신규 영구 포맷을
+  늘리지 않으므로 ④⑤ 제외 논리와 충돌하지 않음).
+- 제거된 기능(⑤ DDS2)의 스펙 아티팩트(`.kiro/specs/dds2-true-streaming/`)는 정리했다.

package/dist/BrowserAdapter-A6RBN4N3.js

@@ -0,0 +1 @@
+export{a as BrowserAdapter}from'./chunk-6ZYMNHFT.js';import'./chunk-IZK7KCU7.js';import'./chunk-Q6SCBUV2.js';import'./chunk-EI7MMDWY.js';

package/dist/BrowserAdapter-NWASGV3D.cjs

@@ -0,0 +1 @@
+'use strict';var chunkHUUB5BUS_cjs=require('./chunk-HUUB5BUS.cjs');require('./chunk-ZTGECGM2.cjs'),require('./chunk-JY2ZPBJK.cjs'),require('./chunk-BCUBYE76.cjs');Object.defineProperty(exports,"BrowserAdapter",{enumerable:true,get:function(){return chunkHUUB5BUS_cjs.a}});

package/dist/NodeAdapter-4R7CNTHP.cjs

@@ -0,0 +1 @@
+'use strict';var chunk76X5J2OF_cjs=require('./chunk-76X5J2OF.cjs');require('./chunk-JY2ZPBJK.cjs'),require('./chunk-BCUBYE76.cjs');Object.defineProperty(exports,"NodeAdapter",{enumerable:true,get:function(){return chunk76X5J2OF_cjs.a}});

package/dist/NodeAdapter-YP22CLUP.js

@@ -0,0 +1 @@
+export{a as NodeAdapter}from'./chunk-7EPVCA2F.js';import'./chunk-Q6SCBUV2.js';import'./chunk-EI7MMDWY.js';

package/dist/ObfuscationLayer-4rCOCRWH.d.cts

@@ -0,0 +1,89 @@
+import { O as ObfuscationLayer } from './core-BsIwjJK-.cjs';
+
+/**
+ * Runtime detection helpers with no platform-specific imports.
+ *
+ * @module adapters/runtime
+ */
+/** 감지된 런타임 환경 식별자 */
+type RuntimeId = "node" | "browser" | "edge" | "deno" | "bun" | "unknown";
+/**
+ * 현재 JavaScript 런타임 환경을 감지합니다.
+ *
+ * 감지는 순수하게 globalThis 검사에 기반하며 Node.js 내장 모듈을 임포트하지 않습니다.
+ */
+declare function detectRuntime(): RuntimeId;
+
+/**
+ * 한글 음절 난독화 레이어 구현.
+ *
+ * 암호화된 charset 인코딩 문자열을 결정론적 전단사 매핑을 사용하여
+ * 자연스러운 한국어 음절 블록으로 변환합니다. 매핑은 다음을 보장합니다:
+ * - 모든 출력 문자가 유효한 한국어 음절 블록 (U+AC00–U+D7A3)
+ * - 단일 문자 빈도가 기대 균등 빈도의 3배를 초과하지 않음
+ * - 출력 길이 <= 입력 길이의 1.5배 (실제로는 1:1 매핑)
+ *
+ * 플랫폼 독립적: Node.js 임포트 없음.
+ *
+ * @module obfuscation/ObfuscationLayer
+ */
+
+/**
+ * 한글 음절 매핑을 사용하여 ObfuscationLayer 인터페이스를 구현합니다.
+ *
+ * 입력 알파벳(인코더가 사용하는 charset 문자)이 주어지면,
+ * 이 레이어는 각 문자를 결정론적으로 한글 음절에 매핑합니다.
+ * 매핑은 전단사(가역적)이며 위치에 따라 각 문자의 할당된 음절 범위를
+ * 순환하여 출력 빈도를 균등하게 분배합니다.
+ */
+declare class HangulObfuscationLayer implements ObfuscationLayer {
+    private readonly config;
+    /**
+     * 새 HangulObfuscationLayer를 생성합니다.
+     *
+     * @param alphabet - 완전한 입력 알파벳 (charset 문자 + 패딩 문자).
+     *   인코딩된 문자열에 나타날 수 있는 모든 고유 문자.
+     */
+    constructor(alphabet: string[]);
+    /**
+     * 암호화된 charset 인코딩 문자열을 한글 음절로 변환합니다.
+     *
+     * 각 입력 문자는 할당된 범위의 한글 음절에 매핑됩니다.
+     * 문자열 내 위치가 범위 내 어떤 음절을 사용할지 결정하여
+     * 균등한 빈도 분포를 보장합니다.
+     *
+     * @param input - 암호화된 charset 인코딩 문자열
+     * @returns 한글 음절 블록 문자열 (U+AC00–U+D7A3)
+     * @throws 입력에 알파벳에 없는 문자가 포함된 경우 에러
+     */
+    obfuscate(input: string): string;
+    /**
+     * 난독화를 역변환하여 원본 charset 인코딩 문자열을 복원합니다.
+     *
+     * 각 한글 음절이 어떤 문자의 범위에 속하는지 판별하여
+     * 원래 문자로 매핑합니다.
+     *
+     * @param input - 난독화된 한글 음절 문자열
+     * @returns 원본 charset 인코딩 문자열
+     * @throws 입력에 유효한 한글 음절 범위 밖의 문자가 포함되거나
+     *   알파벳 문자에 매핑되지 않는 문자가 포함된 경우 에러
+     */
+    deobfuscate(input: string): string;
+}
+/**
+ * Ddu64 인코더 출력과 호환되는 ObfuscationLayer를 생성합니다.
+ *
+ * charset/패딩 외에 footer 마커(ELYSIA/GRISEO/ENC/V3/V4)와 숫자(0-9)까지 알파벳에
+ * 포함하므로, 압축/암호화/파이프라인 마커가 붙은 실제 인코더 출력도 안전하게
+ * deobfuscate할 수 있습니다.
+ *
+ * 일반적으로는 `Ddu64`의 `obfuscate` 옵션을 쓰는 것으로 충분하며, 이 헬퍼는 인코더와
+ * 동일한 난독화 매핑을 외부에서 재현해야 할 때 사용합니다.
+ *
+ * @param charSet - 인코딩에 사용되는 charset 문자
+ * @param paddingChar - 패딩 문자
+ * @returns 인코더 호환 ObfuscationLayer 인스턴스
+ */
+declare function createEncoderObfuscationLayer(charSet: string[], paddingChar: string): ObfuscationLayer;
+
+export { HangulObfuscationLayer as H, createEncoderObfuscationLayer as c, detectRuntime as d };