@ddunigma/node/dist/WebStreams-BSCrvsT3.d.cts

ddunigma

import { P as PlatformAdapter, I as KeyDerivationOptions, D as Ddu64Core, a as DduSecureConstructorOptions, H as DduStreamOptions } from './core-ihIEWmI5.cjs';

/**
 * 브라우저 플랫폼 어댑터 구현.
 * 암호화 연산에 Web Crypto API(SubtleCrypto)를 사용하고
 * 압축에 CompressionStream/DecompressionStream을 사용합니다.
 *
 * 이 어댑터는 동기 암호화 또는 압축 연산을 지원하지 않습니다.
 * Brotli는 CompressionStream/DecompressionStream에서 지원되는 런타임에서만 사용할 수 있습니다.
 *
 * @module adapters/BrowserAdapter
 */

/**
 * Web API를 사용하여 PlatformAdapter를 구현하는 BrowserAdapter:
 * - AES-256-GCM 및 SHA-256을 위한 Web Crypto API(SubtleCrypto)
 * - 안전한 랜덤 바이트를 위한 crypto.getRandomValues
 * - deflate-raw 압축을 위한 CompressionStream/DecompressionStream
 * - 런타임이 지원하는 경우 Brotli 압축
 */
declare class BrowserAdapter implements PlatformAdapter {
    readonly runtime: "browser" | "edge" | "deno" | "bun";
    constructor(runtime?: "browser" | "edge" | "deno" | "bun");
    /**
     * UTF-8 키 문자열에서 SHA-256을 통해 256비트 키를 파생합니다.
     * UTF-8 인코딩된 키에 SubtleCrypto.digest('SHA-256', ...)를 사용합니다.
     */
    deriveKey(key: string, options?: KeyDerivationOptions): Promise<Uint8Array>;
    /**
     * 12바이트 IV를 사용하여 AES-256-GCM으로 데이터를 암호화합니다.
     * 와이어 포맷 반환: IV(12바이트) + authTag(16바이트) + 암호문.
     *
     * 참고: Web Crypto는 authTag를 암호문에 추가하므로,
     * 마지막 16바이트를 authTag로 추출하고 와이어 포맷에 맞게 재배치합니다.
     */
    encrypt(data: Uint8Array, keyHash: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
    /**
     * AES-256-GCM 페이로드를 복호화합니다.
     * 와이어 포맷 기대: IV(12바이트) + authTag(16바이트) + 암호문.
     * 복호화 전에 Web Crypto 형식(암호문 + authTag)으로 재구성합니다.
     */
    decrypt(data: Uint8Array, keyHash: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
    /**
     * 암호학적으로 안전한 랜덤 바이트를 생성합니다.
     */
    randomBytes(length: number): Uint8Array;
    /**
     * CompressionStream을 통해 deflate로 데이터를 압축합니다.
     * Node.js zlib.deflateRaw와의 상호운용성을 위해 'deflate-raw' 형식만 사용합니다.
     */
    deflate(data: Uint8Array, _level?: number): Promise<Uint8Array>;
    /**
     * DecompressionStream을 통해 deflate 데이터를 압축 해제합니다.
     * Node.js zlib.inflateRaw와의 상호운용성을 위해 'deflate-raw' 형식만 사용합니다.
     * maxBytes가 지정되면 제한을 적용합니다.
     */
    inflate(data: Uint8Array, maxBytes?: number): Promise<Uint8Array>;
    /**
     * CompressionStream을 통해 Brotli로 데이터를 압축합니다.
     * 브라우저 Web API는 Brotli 품질 레벨을 받지 않으므로 level 값은 무시됩니다.
     */
    brotliCompress(data: Uint8Array, _level?: number): Promise<Uint8Array>;
    /**
     * DecompressionStream을 통해 Brotli 데이터를 압축 해제합니다.
     */
    brotliDecompress(data: Uint8Array, maxBytes?: number): Promise<Uint8Array>;
    /**
     * CompressionStream에 적합한 deflate 형식을 결정합니다.
     * Node.js zlib.deflateRaw와의 상호운용성을 위해 'deflate-raw'만 사용합니다.
     */
    private getDeflateFormat;
    private writeAndReadStream;
    private readAllChunks;
}

/**
 * Browser 전용 secure Ddu64 래퍼.
 *
 * Ddu64Core를 확장하여 압축/암호화/체크섬(배터리 포함)을 지원합니다:
 * - BrowserAdapter 자동 주입 (WebCrypto/CompressionStream) → 비동기 압축/암호화/체크섬
 * - HangulObfuscationLayer 자동 주입 → 한글 난독화 사용 가능
 *
 * Node.js 내장 모듈을 정적으로 import하지 않으므로 브라우저 번들에 crypto/zlib가
 * 끌려오지 않습니다. 구 `Ddu64Browser`의 배터리 동작을 계승합니다.
 *
 * @module Ddu64SecureBrowser
 */

/**
 * Browser 전용 secure Ddu64 인코더/디코더.
 *
 * Ddu64Core를 래핑하여 자동 BrowserAdapter 주입(WebCrypto/CompressionStream 기반
 * 압축/암호화/체크섬)을 제공합니다. 동기 압축/암호화 메서드는 지원하지 않으며
 * `encodeAsync`/`decodeAsync` 계열을 사용해야 합니다.
 *
 * @example
 * ```ts
 * import { Ddu64SecureBrowser } from '@ddunigma/node/secure';
 *
 * const encoder = new Ddu64SecureBrowser(undefined, undefined, { encryptionKey: 'key' });
 * const encoded = await encoder.encodeAsync('Hello', { compress: true });
 * const decoded = await encoder.decodeAsync(encoded);
 * ```
 */
declare class Ddu64SecureBrowser extends Ddu64Core {
    constructor(dduChar?: string[] | string | DduSecureConstructorOptions, paddingChar?: string, dduOptions?: DduSecureConstructorOptions);
}

/**
 * ddunigma Web Streams API 구현.
 *
 * Web Streams API(globalThis.TransformStream)를 사용하는
 * TransformStream 기반 인코딩/디코딩 파이프라인을 제공합니다.
 * 모든 최신 브라우저와 Node.js에서 사용 가능합니다.
 *
 * 스트리밍 모드:
 * - 인코딩: 압축/암호화/체크섬 비활성화 + 2의 제곱수 charset에서 청크 단위 출력
 * - 디코딩: footer의 압축/암호화 마커를 최종 신뢰하기 위해 payload를 축적 후 처리
 *
 * 메타데이터 의미 주의:
 * 스트림 헤더의 압축 플래그(D/B/N)는 압축이 "요청"되었는지를 기록하고, 페이로드 footer는
 * 실제로 압축이 "적용"되었는지를 기록합니다. 작은/비압축성 데이터는 압축 결과가 원본보다
 * 커서 적용되지 않을 수 있으므로 헤더가 D/B여도 footer엔 압축 마커가 없을 수 있습니다.
 * 디코더는 항상 footer를 권위 있는 소스로 신뢰하므로 라운드트립은 정상이며, 헤더 플래그는
 * 어디까지나 "요청" 힌트로만 해석해야 합니다.
 *
 * 스트림 헤더 형식: [pad]DDS1[D|B|N][1|0][pad]
 * D=deflate, B=brotli, N=없음 (압축), 1/0 (암호화).
 *
 * @module streams/WebStreams
 */

/**
 * 바이너리 데이터를 charset 인코딩 문자열로 변환하는
 * Web Streams API TransformStream을 생성합니다.
 *
 * 압축/암호화/체크섬이 비활성화되고 charset이 2의 제곱수일 때 각 청크를 즉시 인코딩합니다.
 * 그 외에는 전체 데이터를 축적한 후 flush에서 처리합니다.
 *
 * 암호화 정책: 스트림 암호화 여부는 **인코더가 키를 보유했는지로만** 결정됩니다
 * (`encryptionKey` 설정 시 항상 암호화). 스트림 옵션 타입(`DduStreamOptions`)에는 `encrypt`가
 * 노출되지 않으며, 내부 옵션으로 `encrypt: false`를 주더라도 키가 있으면 무시되고 암호화됩니다.
 * 평문 스트림이 필요하면 키 없는 인코더 인스턴스를 사용하세요.
 *
 * @param encoder - 인코딩에 사용할 Ddu64Core 인스턴스
 * @param options - 인코딩 옵션 (compress, compressionAlgorithm 등)
 * @returns TransformStream<Uint8Array, string>
 */
declare function createReadableEncodeStream(encoder: Ddu64Core, options?: DduStreamOptions): TransformStream<Uint8Array, string>;
/**
 * charset 인코딩 문자열을 바이너리 데이터로 역변환하는
 * Web Streams API TransformStream을 생성합니다.
 *
 * 스트림은 DDS1 스트림 헤더를 조기 검증하되, 헤더만으로 복호화/압축해제를 비활성화하지 않습니다.
 * footer가 최종 wire metadata이므로 전체 페이로드를 축적 후 일괄 디코딩합니다.
 *
 * @param encoder - 디코딩에 사용할 Ddu64Core 인스턴스
 * @param options - 디코딩 옵션
 * @returns TransformStream<string, Uint8Array>
 */
declare function createReadableDecodeStream(encoder: Ddu64Core, options?: DduStreamOptions): TransformStream<string, Uint8Array>;

export { BrowserAdapter as B, Ddu64SecureBrowser as D, createReadableEncodeStream as a, createReadableDecodeStream as c };