🔤 한글 앞에 숨은 NUL 바이트: React 18 스트리밍 SSR이 태그 링크를 깨뜨린 과정

지난주 HTTP 보안 헤더 글을 발행하고 실제 사이트에서 렌더링을 확인했다. 본문, 표, 각주, Mermaid는 모두 정상이었다. 그런데 글 아래 "보안 헤더" 태그를 누르면 태그 목록이 걸러지지 않았다.

링크 주소를 바이트로 찍어 보니 /tags/?q= 와 보안 헤더 사이에 0x00 한 바이트가 끼어 있었다. 화면에는 아무것도 안 보이는 NUL 문자다. 이 글 하나의 문제가 아니었다.

다른 글의 태그에서도 같은 일이 있었다. 아래에서 ␀는 NUL 한 바이트를 뜻한다.

웹 스크␀␀래핑
웹 ␀␀개발
프롬프트 ␀인젝션
/tags/?q=␀보안 헤더

결론부터 적으면 원인은 react-dom 18.3.1의 서버 렌더러 버그다. React 쪽에서는 2023년 2월에 고쳤지만 그 수정은 19에만 들어갔다.^react-26228 18.x를 쓰는 정적 사이트 생성기는 지금도 같은 일을 겪는다.

화면은 멀쩡한데 링크만 깨지는 이유

NUL이 57개나 있었는데 화면에서 이상한 글자가 하나도 안 보였다. HTML 파서가 NUL을 만나는 위치에 따라 다르게 처리하기 때문이다. HTML 표준은 이 경우를 unexpected-null-character 파싱 오류로 정하고, 위치별 처리를 따로 적어 두었다.^{whatwg-parsing}

그래서 태그 이름 텍스트는 멀쩡하게 보이고, 같은 태그 이름이 들어간 href만 /tags/?q=�보안 헤더가 된다. 태그 페이지는 q 값과 태그 이름을 비교하므로 일치하는 태그가 없다.

React가 하이드레이션 단계에서 고쳐 줄 것 같지만 그렇지 않다. React 공식 문서는 서버 HTML과 클라이언트 렌더링 결과가 다를 때 속성 차이를 바로잡는다는 보장이 없다고 적고 있다.^{react-hydrate} 개발 모드에서 경고만 하고, 운영 빌드에서는 깨진 href가 그대로 남는다.

⚠️ 주의: 본문 텍스트에 섞인 NUL은 브라우저 화면만 봐서는 찾을 수 없다. curl로 받은 HTML을 바이트 단위로 세야 보인다.

빌드 문제인지 CDN 문제인지부터 가른다

배포된 HTML에 이상한 바이트가 있으면 범위를 먼저 좁힌다. 원본, 빌드 결과물, 배포된 응답 중 어디서 처음 생기는지 보면 된다.

GitHub Actions의 배포 artifact를 내려받아 세어 보니 HTML 안에 이미 NUL이 있었다. CDN이 아니라 빌드가 만든 것이다. NUL 바로 뒤 글자는 전부 한글이었다. 한글은 UTF-8로 3바이트이므로, 바이트를 나눠 쓰는 경계에서 뭔가 어긋나는 것으로 범위를 좁혔다.

세는 방법은 단순하다.

from pathlib import Path

# 빌드 결과물의 모든 html에서 0x00 개수를 센다
total = 0
for f in Path("public").rglob("*.html"):
    n = f.read_bytes().count(b"\x00")
    if n:
        print(f, n)
        total += n
print("NUL 합계:", total)

원인: 2048바이트 버퍼와 3바이트 한글

Gatsby 5는 정적 HTML을 만들 때 renderToPipeableStream을 쓴다.^{gatsby-static-entry} 이 함수는 출력을 문자열 하나로 모으지 않는다. 텍스트 조각을 받을 때마다 2048바이트짜리 Uint8Array에 UTF-8로 채우고, 다 차면 내보낸다.

문제는 남은 칸이 1~2바이트인데 다음 글자가 3바이트 한글일 때다. TextEncoder.encodeInto()는 글자를 반으로 쪼개 쓰지 않는다. 들어가는 데까지만 쓰고 멈춘다.^{mdn-encodeinto} 그다음 react-dom 18.3.1은 버퍼를 비우는데, 채운 만큼이 아니라 버퍼 전체를 내보낸다.

// react-dom 18.3.1 cjs/react-dom-server.node.development.js, writeStringChunk
var _textEncoder$encodeIn = textEncoder.encodeInto(stringChunk, target),
    read = _textEncoder$encodeIn.read,
    written = _textEncoder$encodeIn.written;

writtenBytes += written;

if (read < stringChunk.length) {
  // ❌ 2048바이트 전체를 내보낸다. 못 채운 1~2칸은 0으로 남아 있다
  writeToDestination(destination, currentView);
  currentView = new Uint8Array(VIEW_SIZE);
  writtenBytes = textEncoder.encodeInto(stringChunk.slice(read), currentView).written;
}

React 19의 같은 자리는 이렇게 바뀌어 있다.

// react-dom 19.0.0
read < chunk.length &&
  // ✅ 실제로 쓴 writtenBytes까지만 내보낸다
  (writeToDestination(destination, currentView.subarray(0, writtenBytes)),
  (currentView = new Uint8Array(2048)),
  (writtenBytes = textEncoder.encodeInto(chunk.slice(read), currentView).written));

버퍼 끝에서 일어나는 일을 바이트로 그리면 이렇다.

보는 3바이트라 남은 2칸에 안 들어간다. 18.3.1은 2칸이 빈 채로 버퍼 1을 통째로 내보내고, 보는 버퍼 2 맨 앞에 온전히 쓴다. 그래서 글자는 깨지지 않고 글자 앞에 NUL만 덧붙는다. 위에서 본 웹 스크␀␀래핑이 정확히 이 모양이다.

재현

react-dom을 설치하지 않고 이 로직만 떼어 Node로 돌려 볼 수 있다. ASCII를 100바이트씩 나눠 쓰고 마지막에 보안을 쓴다. 렌더러는 실제로 텍스트 노드, 속성값 같은 작은 조각을 연달아 쓰므로 조각을 나눠야 재현된다. 682자가 넘는 조각은 버퍼를 거치지 않고 바로 내보내는 다른 길로 빠진다.

const VIEW_SIZE = 2048
function makeWriter(fixed) {
  const out = []
  let view = new Uint8Array(VIEW_SIZE), written = 0
  const enc = new TextEncoder()
  function write(chunk) {
    const target = written > 0 ? view.subarray(written) : view
    const { read, written: w } = enc.encodeInto(chunk, target)
    written += w
    if (read < chunk.length) {
      out.push(fixed ? view.subarray(0, written) : view) // 18.3.1은 view 전체
      view = new Uint8Array(VIEW_SIZE)
      written = enc.encodeInto(chunk.slice(read), view).written
    }
    if (written === VIEW_SIZE) { out.push(view); view = new Uint8Array(VIEW_SIZE); written = 0 }
  }
  const end = () => Buffer.concat([...out, view.subarray(0, written)])
  return { write, end }
}

for (const pad of [2045, 2046, 2047]) {
  for (const fixed of [false, true]) {
    const w = makeWriter(fixed)
    for (let i = 0; i < pad; i += 100) w.write("a".repeat(Math.min(100, pad - i)))
    w.write("보안")
    const nul = w.end().filter(b => b === 0).length
    console.log(`ASCII ${pad}바이트 뒤 한글, ${fixed ? "19  " : "18.3"}: NUL ${nul}개`)
  }
}

남은 칸이 3바이트 이상이면 한글이 들어가므로 아무 일도 없다. 12바이트일 때만 그 수만큼 NUL이 생긴다. 4바이트인 이모지는 남은 칸이 13바이트일 때 생긴다. ASCII는 1바이트라 절대 안 생긴다. 영어 위주 사이트에서는 거의 안 보이고, 한글, 일본어, 중국어 사이트나 —, → 같은 기호를 많이 쓰는 문서에서 보이는 이유다.

왜 18에서 고쳐지지 않았나

18.3.1이 18의 마지막 판이다. 18에 머무는 한 react-dom 버전을 올려서 고칠 방법은 없다. 같은 이슈에서 React 팀의 sebmarkbage는 서버 출력과 클라이언트 렌더링이 달라지는 실제 버그라고 인정했다.^react-31134

renderToString은 버퍼를 쓰지 않고 문자열을 이어 붙이므로 이 문제가 없다. 같은 이슈에서 renderToReadableStream도 renderToString과 같은 결과를 냈다고 보고됐다.

고칠 수 있는 방법 네 가지

네 번째를 골랐다. 지워도 되는 근거는 두 가지다.

1. 덧붙은 것은 빈칸의 0뿐이다. 글자는 다음 버퍼에 온전히 들어가므로 빠진 바이트가 없다. NUL을 지우면 원래 나와야 했던 출력과 바이트 단위로 같다.
2. UTF-8에서 0x00은 U+0000일 때만 나온다. 다른 글자의 여러 바이트 중 하나로 0x00이 들어가는 일은 없다. UTF-8에서 2바이트 이상인 글자는 모든 바이트가 0x80 이상이기 때문이다.^rfc3629 HTML에서 U+0000을 일부러 쓸 일도 없다.

React 19로 올리는 것이 근본 해결이다. 막고 있는 의존성 셋은 각각 상위 버전(react-redux 9, @react-spring/web 10)이 있거나 교체할 수 있으므로, 업그레이드는 따로 진행할 일로 남겼다.

onPostBuild로 지우고 CI로 다시 본다

Gatsby의 onPostBuild는 public/ 폴더가 다 만들어진 뒤에 실행된다.^{gatsby-onpostbuild} 여기서 모든 .html을 돌며 0x00을 지운다.

// gatsby-node.js
const fs = require("fs")
const path = require("path")

function stripNulBytes(dir) {
  let files = 0
  let bytes = 0
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name)
    if (entry.isDirectory()) {
      const sub = stripNulBytes(full)
      files += sub.files
      bytes += sub.bytes
    } else if (entry.name.endsWith(".html")) {
      const buf = fs.readFileSync(full)
      if (!buf.includes(0)) continue
      const clean = buf.filter(b => b !== 0)
      fs.writeFileSync(full, clean)
      files += 1
      bytes += buf.length - clean.length
    }
  }
  return { files, bytes }
}

exports.onPostBuild = ({ reporter }) => {
  const { files, bytes } = stripNulBytes(path.join(__dirname, "public"))
  reporter.info(`NUL 바이트 제거: html ${files}개에서 ${bytes}바이트`)
}

buf.filter()는 문자열로 디코딩하지 않고 바이트 배열에서 바로 지운다. 문자열로 바꿨다가 다시 인코딩하면 원래 바이트와 달라질 여지가 생긴다.

지우는 단계가 나중에 빠지거나 바뀌면 NUL이 다시 들어온다. 그런데 본문 텍스트에 섞인 NUL은 화면에 안 보이므로 아무도 모른다. 그래서 빌드 검증 스크립트에 검사를 하나 더 넣었다. index.html만이 아니라 모든 HTML을 본다.

// scripts/verify-build-seo.js
function checkNulBytes() {
  const problems = []
  let checked = 0
  for (const file of walkAllHtml(PUBLIC_DIR)) {
    checked += 1
    const buf = fs.readFileSync(file)
    let count = 0
    for (let i = buf.indexOf(0); i !== -1; i = buf.indexOf(0, i + 1)) count += 1
    if (count > 0) problems.push(`${file}: NUL 바이트 ${count}개`)
  }
  return { checked, problems }
}

검사를 믿으려면 검사가 실패하는 것부터 봐야 한다. 고치기 전 배포본에 먼저 돌렸다.

수정 후 빌드에서 지운 양(30개, 59바이트)이 처음 센 값(29개, 57개)과 조금 다르다. 그사이 새 글이 하나 늘었고, 버퍼 경계는 HTML 전체 길이에 따라 움직이므로 어느 글자가 경계에 걸릴지는 빌드마다 바뀐다. 이 버그가 생겼다 안 생겼다 하는 것도 같은 이유다. 글 앞부분을 조금 고쳤더니 멀리 떨어진 곳의 NUL이 사라졌다는 보고도 같은 이슈에 있다.^react-31134

정리

1. React 18.1~18.3.1의 renderToPipeableStream은 한글 앞에 NUL을 끼워 넣을 수 있다. 2048바이트 버퍼에 3바이트 글자가 안 들어갈 때 버퍼 전체를 내보내기 때문이다
2. HTML 파서는 위치마다 NUL을 다르게 처리한다. 본문에서는 버려서 안 보이고, 속성값, <title>, <script>에서는 �로 바꾼다. 그래서 화면은 멀쩡하고 링크만 깨진다
3. 하이드레이션은 깨진 속성을 고쳐 주지 않는다. 서버 HTML에 들어간 href가 그대로 남는다
4. 수정은 React 19에만 있다. 18.3.1이 18의 마지막 판이다
5. NUL만 지우면 원래 출력과 같다. 덧붙은 것은 빈칸의 0뿐이고 UTF-8에서 0x00은 다른 글자 안에 나오지 않는다
6. 검사는 실패하는 것부터 확인한다. 고치기 전 산출물에 돌려 잡히는지 본 뒤 CI에 넣는다

실무 체크리스트

• React 18 스트리밍 SSR(renderToPipeableStream)을 쓰는 사이트라면 빌드 산출물 HTML의 0x00 개수를 센다
• 브라우저 화면이 아니라 curl로 받은 바이트로 확인한다. 본문 텍스트의 NUL은 화면에 안 보인다
• 이상한 바이트가 있으면 원본, 빌드 산출물, 배포 응답 순으로 어디서 처음 생기는지 가른다
• href, <title>, <meta content>, JSON-LD에 U+FFFD(�)가 있는지 본다. NUL이 바뀐 흔적이다
• 바이트를 지울 때는 문자열로 디코딩하지 말고 바이트 배열에서 지운다
• 빌드 후처리가 빠져도 알 수 있게 CI에 "NUL 0개" 검사를 넣는다. 고치기 전 산출물에서 실패하는지 먼저 본다
• React 19로 못 올리는 이유를 의존성 단위로 적어 둔다. 막는 패키지가 풀리면 후처리를 걷어낸다

다음 글은 순환 순서대로 네트워크 쪽을 다룬다. HTTP 보안 헤더 글에서 예고한 CSP Report-Only 편은 다음 보안 차례에 웹 보안 기초 시리즈로 이어진다.

참고문헌

이어서 읽기

• HTTP 보안 헤더 점검: 내 블로그 응답에는 HSTS 하나만 붙어 있었다
• Gatsby 블로그 SEO 설정 가이드: Google Search Console, sitemap, robots.txt
• 다크 모드에서 글자가 배경에 묻힌다: 예외 선택자 19개와 인라인 스타일 38개가 사라진 토큰 정리기