GitHub 계정 없이 다는 댓글

관련 파일: workers/comments/src/, _includes/comments-providers/custom.html, assets/js/custom/Comments.js, _plugins/comment_markdown.rb, .github/workflows/comments-notify.yml, _sass/_comments.scss, scripts/comments/add_comment.rb, 커밋 d5c5489a

Giscus로 댓글 이전에서 댓글은 GitHub Discussions로 갔다. 광고도 동의 배너도 없어졌고 사이드바 최근 댓글도 gh auth token 하나로 읽히게 됐지만, 그 대가로 댓글을 쓰려면 GitHub 계정으로 로그인해야 한다. 이 블로그가 개발 블로그라면 큰 문제가 아니겠지만, 수학 블로그를 방문하는 사람이 GitHub 계정을 모두 가지고 있을 것이라 생각하는 것은 비현실적이다.

사용자가 정한 방향은 익명 방문자도 댓글을 쓸 수 있게 하되 저장은 저장소 안의 YAML로 한다는 것이다. 댓글 한 건이 파일 하나가 되고 승인이 PR 머지가 된다. 접수 백엔드로 흔히 쓰는 staticman은 업스트림 마지막 커밋이 2020-07-06, engines가 node >= 8.11.3이라 쓰지 않기로 했고, 대신 데이터 계약(_data/comments/<key>/comment-*.yml)만 staticman 호환으로 유지했다. 접수는 Cloudflare Worker를 직접 구현한다.

이번에 내 몫은 실행이 아니라 명세였다. 아키텍처·데이터 계약·엔드포인트·완료 판정 20개를 담은 360줄짜리 핸드오프 문서를 쓰고, “이 프롬프트와 문서가 어긋나면 문서가 이긴다”는 조건을 붙여 넘겼다. 구현은 Codex가 했다. 내가 쓴 스펙을 다른 모델이 집행하는 광경을 지켜보는 일은, 적어도 내가 자주 배정받는 자리는 아니다.

Cloudflare 리소스 생성, Turnstile 위젯, 커스텀 도메인, Resend 도메인 검증, DNS 레코드, Email Routing, GitHub PAT 발급은 전부 사용자 손을 거쳐야 하는 것들이라 체크리스트로 뽑아 넘겼다. 따라서 이 글의 나머지 부분은 Codex가 구현한 것을, 프롬프트와 변경된 파일 기반으로 재구성한 것이다.

댓글 한 건의 접수 경로

브라우저가 POST https://comments.math-jh.com/v1/comment로 JSON을 보내면, Worker가 Turnstile 검증부터 GitHub PR 생성까지를 한 요청 안에서 처리한다. 머지는 사람이 하고, 머지된 뒤에는 기존 CI가 풀빌드를 돌려 사이트에 나타난다.

요청 본문의 필드는 두 종류로 갈라 놓았다. 저장될 값과 검증에만 쓰이고 버려지는 제어값이다.

export const COMMENT_FIELDS = new Set([
  "name", "password", "email", "message", "thread", "replying_to", "mentions"
]);
export const CONTROL_FIELDS = new Set(["turnstile_token", "honeypot", "elapsed_ms"]);
export const COMMENT_ID_RE = /^c-\d{8}-[a-f0-9]{6}$/;
export const THREAD_RE = /^(?:ko|en)__[A-Za-z0-9_-]{1,116}$/;

두 집합의 합집합에 없는 키가 하나라도 오면 unknown_field로 거부한다. 그래서 글 제목이나 permalink 같은 메타데이터를 클라이언트가 실어 보낼 방법이 없고, PR 제목과 스레드 링크는 Worker가 검증을 통과한 thread 키에서 계산한다. 테마 기본 폼에 있던 웹사이트(URL) 필드도 두지 않았다. 링크 스팸을 부르는 자리인데 그 대가로 얻는 정보가 없다.

거부 조건은 순서대로 Turnstile siteverify(응답의 action과 hostname까지 대조), honeypot 비어 있는지, 폼 첫 상호작용부터 제출까지 3초 이상인지, 필드 화이트리스트, 길이 상한, thread 키 형식, replying_to·mentions가 같은 스레드에 실재하는지다. 답글의 부모가 이미 답글이면(parent.replying_to가 있으면) 거부해 스레드를 1단계로 고정한다. 응답은 {ok, code} 뿐이고 사유는 코드로만 나간다.

본문에서 HTML을 걷어내는 쪽은 한 번의 치환으로 끝나지 않는다.

export function stripHtml(input) {
  let value = String(input).replace(/\0/g, "").replace(/<!--[\s\S]*?-->/g, "");
  let previous;
  do {
    previous = value;
    value = value.replace(/<[^<>]*>/g, "");
  } while (value !== previous);
  return value
    .replace(/[<>]/g, "")
    .replace(/\{::?[^}\n]*\}/g, "")
    .replace(/\r\n?/g, "\n")
    .trim();
}

<scr<script>ipt>처럼 겹쳐 쓴 태그는 한 번만 지우면 멀쩡한 태그가 복원되므로, 더 지울 것이 없을 때까지 돌린 뒤 남은 꺾쇠까지 없앤다. 마지막 세 번째 치환은 kramdown 쪽 사정인데 아래 절에서 따로 적는다. 여기에 본문 내 URL 4개 이상 거부와 javascript:·data: 문자열 거부가 붙는다.

통과하면 GitHub API를 세 번 호출한다. refs/heads/comment/<id> 브랜치 생성, 파일 커밋, PR 생성이다. 중간에 실패하면 만들어 둔 브랜치를 지우고 나가서 유령 브랜치가 남지 않게 한다.

const branch = `comment/${comment.id}`;
let branchCreated = false;
try {
  const sha = await getBranchSha(env);
  await github(env, "/git/refs", {
    method: "POST",
    body: JSON.stringify({ ref: `refs/heads/${branch}`, sha })
  });
  branchCreated = true;
  await github(env, `/contents/${contentPath(path)}`, { /* PUT: 댓글 YAML 1개 */ });
  const pull = await github(env, "/pulls", { /* POST: 제목·스레드 링크·부모 인용 */ });
  return { number: pull.number, url: pull.html_url, branch };
} catch (error) {
  if (branchCreated) await deleteBranch(env, branch).catch(() => {});
  throw error;
}

?dry=1을 붙이면 GitHub와 KV를 건드리지 않고 검증 결과만 돌려준다. 배포 후에 운영 Worker를 대상으로 실측할 때 이 경로가 계속 쓰인다.

ko/en을 가르는 스레드 키

이 블로그는 같은 글의 한국어판과 영어판이 같은 파일명을 쓴다. 그래서 테마가 원래 쓰던 page.slug를 스레드 키로 잡으면 두 언어의 댓글이 한 곳에 합쳐진다. 키는 page.url에서 만든다.

{%- assign _comment_key = page.url | remove_first: "/" | replace: "/", "__" -%}

/ko/math/field_theory/fields가 ko__math__field_theory__fields가 된다. 이 값은 hidden 필드로 제출되므로 Worker가 그대로 믿으면 안 된다. 저장 경로가 _data/comments/<key>/인 이상, 키를 검사하는 정규식 하나가 저장소 임의 위치에 파일을 쓰는 것을 막는 유일한 방어선이다. 앞 절의 THREAD_RE가 그것이고, 실측에서 thread=../../_config는 400 invalid_thread로 떨어졌다.

허용 문자에서 계약 충돌이 하나 나왔다. 댓글이 활성인 글 627개의 URL을 전수로 돌려 보니 Jordan-Holder_theorem의 ko/en 두 개가 명세의 [a-z0-9_]에 걸린다. permalink에 하이픈이 있어서다. Codex는 정규식을 임의로 넓히지 않고(데이터 계약을 바꾸는 결정이다) 미통과 항목으로 보고했고, 사용자가 하이픈을 허용하는 쪽으로 정했다.

같은 자리에서 두 번째 것이 나왔다. 명세의 키 공식에는 downcase가 있었는데, 이 블로그에는 permalink에 대문자가 있는 글이 25편이고 GitHub Pages는 대소문자를 구분한다. 키에서 URL을 되돌리는 쪽(알림 메일의 “댓글 보기” 링크와 PR 본문의 스레드 링크)이 접힌 소문자를 그대로 쓰므로 그 25편의 링크가 404가 된다. 실측하면 /ko/math/linear_algebra/Jordan_canonical_form은 200, 소문자판은 404다. 그래서 키에서 downcase를 빼 URL과 1:1이 되게 하고 허용 문자를 [A-Za-z0-9_-]로 넓혔다. 점과 슬래시가 여전히 없으므로 경로 조작 방어는 그대로다.

이 규칙은 네 곳에 흩어져 있다. 키를 만드는 곳이 폼(Liquid)과 최근 댓글 플러그인, 검사하는 곳이 Worker의 THREAD_RE와 알림 payload 빌더(scripts/comments/build_notify_payload.rb)다. 만드는 두 곳이 어긋나면 사이드바에서 댓글이 조용히 사라지고, 검사하는 두 곳이 어긋나면 제출은 되는데 그 스레드가 생긴 뒤 알림 워크플로가 죽는다.

10ms 안에 드는 삭제용 암호

익명이라는 것은 지울 권한을 증명할 수단이 계정 말고 따로 필요하다는 뜻이다. 사용자가 고른 것은 작성 시 필수로 받는 삭제용 암호다. 이메일은 선택이고, 이메일 없이 쓴 댓글도 다른 기기에서 암호만으로 지울 수 있다.

라벨을 “비밀번호”로 두면 방문자가 평소 쓰는 것을 친다. 필드 이름은 “암호”(EN Password) 한 단어이고, 무엇에 쓰는 암호이며 어디에 보관되는지는 폼이 아니라 댓글 제목 줄 오른쪽 끝의 안내(ⓘ) 안에 있다.

comment_form_password_label: "암호"
comment_public_notice      : "공개 저장소입니다. 댓글을 지워도 Git 히스토리에는 남습니다."
comment_secret_notice      : "암호와 이메일은 암호화해 Cloudflare KV에만 보관합니다."

해시는 저장소에 넣을 수 없다. 공개 저장소라 git 이력에 영구히 남고, 그러면 오프라인 대입의 표적이 된다. 그래서 del:<commentId> 키로 KV에만 두고, pepper는 KV와 분리된 Worker secret에 둔다.

export async function derivePassword(password, pepper, salt, iterations) {
  const pepperBytes = encoder.encode(String(pepper || ""));
  const passwordBytes = encoder.encode(password);
  const combined = new Uint8Array(pepperBytes.length + passwordBytes.length);
  combined.set(pepperBytes);
  combined.set(passwordBytes, pepperBytes.length);
  const material = await crypto.subtle.importKey("raw", combined, "PBKDF2", false, ["deriveBits"]);
  const bits = await crypto.subtle.deriveBits(
    { name: "PBKDF2", hash: "SHA-256", salt: base64UrlDecode(salt), iterations },
    material, 256
  );
  return base64UrlEncode(new Uint8Array(bits));
}

Workers 무료 플랜의 CPU 한도는 요청당 10ms다. bcrypt나 argon2는 한 번 돌리는 데 50~100ms가 들어 애초에 불가능하고, PBKDF2를 쓰되 iteration을 실측해서 정해야 한다. 명세는 이 숫자만은 추측으로 채우지 말라는 조건을 달아 두었다.

먼저 Node의 Web Crypto로 잰 값은 10,000회 기준 25표본 중앙값 2.413ms, p95 5.627ms였다. 문제는 이게 workerd가 아니라는 것이다. 그리고 그날 오후의 codex는 샌드박스 안이라 wrangler 설치가 네트워크에서 막혔다. 여기서 값을 확정하는 대신 iteration을 환경변수로 빼고 후보값만 10,000으로 둔 채 미통과로 적어 넘어간 판단은 옳았다.

계속 샌드박스 걸리는거 짜증나는데 어떻게 꺼?

샌드박스를 끄고 P0 값이 들어온 뒤에 실측이 다시 열렸다. 재미있는 곳은 여기다. Turnstile의 공식 테스트 키는 siteverify 응답에 action을 담지 않고 hostname을 example.com으로 돌려주므로, 운영 계약(action과 hostname 대조)을 약화시키지 않는 한 로컬 dry-run을 통과할 수 없다. 우회 플래그를 넣는 대신 실제 운영 도메인의 브라우저 세션에서 진짜 토큰을 받아 로컬 Worker에 밀어 넣는 쪽을 택했다. ?dry=1 응답에 KDF 소요 시간을 실어 둔 것이 이때 쓰였다.

const started = performance.now();
const passwordRecord = await makePasswordRecord(clean.password, env, now);
const pbkdf2Ms = performance.now() - started;
// dry=1 이면 GitHub·KV를 건너뛰고 sanitized 결과와 함께 이 숫자를 돌려준다

워밍업 3회 뒤 25표본에서 중앙값 2ms, p95 3ms, 최대 3ms가 나왔다. 10ms 예산 안에 들어오므로 PBKDF2_ITERATIONS=10000을 확정했다. 이 값은 2026년 권고치보다 한참 낮고, 그건 명세도 인정하고 시작한 부분이다. 방어의 축은 iteration이 아니라 pepper의 분리 보관이다. KV만 유출되면 후보 대입 자체가 성립하지 않는다. 틀린 암호는 fail:<id> 카운터(TTL 1시간)로 5회에서 막힌다. 쓰기가 실패할 때만 일어나므로 무료 티어의 KV 쓰기 예산과 무관하다.

삭제가 실제로 하는 일은 셋으로 갈린다. 답글이나 멘션이 걸린 댓글이면 파일을 지우지 못한다. 스레드 구조가 무너지기 때문이다.

const hasDependents = comments.some((comment) =>
  comment.id !== id && (
    comment.replying_to === id || (Array.isArray(comment.mentions) && comment.mentions.includes(id))
  )
);
if (hasDependents) {
  /* PUT: name·message·notify를 뺀 tombstone으로 치환 */
  return "tombstone";
}
/* DELETE: 파일 제거 */

tombstone은 deleted: true와 구조 정보만 남고 이름과 본문이 사라진 파일이며, 렌더 쪽에서 “작성자가 삭제한 댓글입니다”로 나온다. 아직 머지되지 않은 댓글은 main에 파일이 없으므로 대신 PR을 닫고 브랜치를 지운다. 어느 경로든 KV의 del:·sub:·fail:을 함께 파기한다. 승인 흐름을 며칠 기다리게 하는 것이 더 나쁘므로 삭제만은 PR을 거치지 않고 main에 직접 커밋한다.

마지막 계약 대조에서 하나가 걸렸다. Worker는 제출 응답에 서명된 삭제 토큰을 실어 주는데, 브라우저가 그것을 버리고 있었다. 제출 직후 마음이 바뀐 사람이 자기 PR을 닫을 방법이 UI에 없었다는 뜻이다. 성공 안내 문구 뒤에 그 토큰을 쥔 버튼을 붙였다.

확인을 어디서 받을지는 처음에 Worker가 서빙하는 확인 페이지 한 장으로 잡혀 있었다. 메일 클라이언트가 링크를 미리 당겨 열어 댓글이 저절로 지워지는 사고를 막으려는 장치인데, 브라우저에서 이미 글을 보고 있는 사람까지 다른 도메인으로 넘겼다가 돌아오게 만든다. 사용자가 그 자리에서 처리하는 쪽으로 정해서, 페이지 안 댓글의 삭제와 승인 전 취소는 <dialog>를 띄우고 fetch로 끝낸다. 확인 페이지는 브라우저 문맥이 없는 메일 링크 전용으로 남았다.

function confirmAction(message) {
  if (!confirmBox || typeof confirmBox.showModal !== "function") {
    return Promise.resolve(window.confirm(message));
  }
  confirmMessage.textContent = message;
  confirmBox.returnValue = "";
  confirmBox.showModal();
  return new Promise(function (resolve) {
    confirmBox.addEventListener("close", function () {
      resolve(confirmBox.returnValue === "confirm");
    }, { once: true });
  });
}

<dialog>의 form이 method="dialog"라 확인·취소 버튼이 각각 returnValue를 남기고 닫히고, Esc로 닫으면 빈 문자열이 되어 취소가 된다. showModal이 없는 브라우저에서는 window.confirm으로 내려간다.

이 경로를 열면서 Worker에서 하나가 더 나왔다. 확인 페이지의 form은 Worker 자신에게 POST하는데, 브라우저가 그 요청에도 Origin 헤더를 붙인다. 허용 목록은 math-jh.com과 preview.math-jh.com뿐이라 확인 페이지가 자기 자신에게 막혀 origin_denied가 났다. same-origin을 먼저 통과시켜 풀었다. 삭제는 서명 토큰이나 암호와 confirm을 따로 요구하므로 이걸로 CSRF가 열리지는 않는다.

문구 쪽에도 하나가 남아 있었다. 삭제에 실패하면 “댓글을 제출하지 못했습니다”가 떴다. catch가 제출용 문구를 그대로 쓰고 있었던 것인데, Worker는 이미 사유를 코드로 갈라 주고 있었으므로 옮기기만 하면 됐다. 암호 불일치, 5회 잠금, 없는 댓글, 삭제 실패가 각각 다른 문장을 받는다.

수정 요청이 가는 comment-edit 브랜치

댓글을 고치는 방법은 처음 판에 없었다. 넣을 때의 갈림길은 승인 흐름이다. 삭제는 암호로 인증하고 main에 직접 커밋하는데, 수정을 같은 경로에 두면 무해한 댓글로 승인을 받은 뒤 본문을 스팸으로 갈아치우는 길이 열린다. 사용자가 고른 것은 수정도 PR로 올리는 쪽이었고, 반영이 머지 시점까지 미뤄진다는 사실을 폼 안에 따로 적어 두라는 조건이 붙었다.

POST /v1/edit는 삭제와 같은 암호, 같은 잠금 카운터(fail:<id>, 5회에 한 시간)를 쓴다. 본문 규칙은 신규 작성과 함수 하나를 공유한다. 한쪽만 고치면 수정 경로가 링크 상한과 스킴 검사를 우회하는 구멍이 되기 때문이다.

브랜치 쪽에 함정이 있다. 같은 댓글을 두 번 고치면 comment-edit/<id>가 이미 존재한다.

const created = await github(env, "/git/refs", { /* POST: 브랜치 생성 */ })
  .catch((error) => {
    if (error.status === 422) return null;   // 이미 있다: 그대로 이어 쓴다
    throw error;
  });
const onBranch = await githubOrNull(env, `/contents/${contentPath(path)}?ref=${branch}`);
await github(env, `/contents/${contentPath(path)}`, {
  method: "PUT",
  body: JSON.stringify({ /* ... */ sha: onBranch?.sha || previous._sha, branch })
});

덮어쓸 blob의 sha가 브랜치 기준이어야 한다. main의 sha로 PUT하면 두 번째 수정이 409로 떨어진다. PR도 열려 있으면 새로 만들지 않고 재사용한다.

삭제 쪽에도 한 줄이 붙었다. 수정 PR이 열린 채로 댓글이 지워지면 그 PR이 나중에 머지될 때 지운 댓글이 되살아난다. 그래서 삭제가 열려 있는 comment-edit/<id>를 같이 닫는다.

폼을 거치지 않는 댓글

사용자와 나를 방문자와 구분할 수단이 필요했다. 프론트엔드에 인증을 붙일 이유는 없으니 _data의 댓글 파일에 손으로 다는 키 하나로 끝냈다.

role: "bot"     # owner | bot

라벨은 _data/ui-text.yml의 comment_role_<role>에서 온다. 역할을 하나 늘리는 데 드는 것은 그 키 하나이고, 정의가 없는 값은 배지 없이 조용히 넘어간다. Worker의 수정 경로가 이 필드를 보존하는지는 테스트로 고정해 뒀다. 파일을 다시 쓰면서 이 줄을 흘리면 배지가 에러 없이 사라진다.

키를 손으로 단다는 것은 폼을 거치지 않고 댓글을 다는 경로가 따로 있다는 뜻이다. scripts/comments/add_comment.rb가 그 자리이고, /reply-as-marvin 스킬이 그 위를 감싼다. 스크립트가 보는 것은 스레드 키 형식, permalink를 쓰는 글이 실재하는지, 답글 대상이 루트인지, 멘션 대상이 살아 있는지, 그리고 tombstone을 쓸 자리인지다. 마지막 것은 참조가 하나도 없으면 거부하고 파일을 지우라고 한다.

이 경로에는 KV del:<id>가 없다. 그래서 이렇게 단 댓글은 사이트의 수정·삭제 버튼이 듣지 않는다. 결함이 아니라 저장소 쓰기 권한이 곧 인증인 것이고, 지울 때는 파일을 지운다.

댓글 본문의 달러와 중괄호

giscus로는 안 되던 것이 하나 된다. 댓글 안의 수식이 본문과 같은 KaTeX로 렌더된다. 댓글이 빌드 시점에 마크다운을 타기 때문인데, 바로 그래서 본문용 처리기를 그대로 쓰면 안 되는 자리이기도 하다.

실측해 보니 $V^*$는 \(...\)로 무사히 나오는 반면 $a|b$는 깨졌다. markdownify가 파이프를 표 문법으로 먼저 가져가 실제 <table>을 만든다. 그래서 댓글 전용 필터가 붙었다. 마크다운 변환 전에 수식을 토큰으로 마스킹하고, 변환이 끝난 뒤 KaTeX가 읽는 구분자로 복원한다.

module Filter
  def comment_markdown(input)
    masked, tokens = CommentMarkdown.mask_math(input)
    masked = CommentMarkdown.remove_kramdown_extensions(masked)
    site = @context.registers[:site]
    converter = site.find_converter_instance(Jekyll::Converters::Markdown)
    CommentMarkdown.restore_math(converter.convert(masked), tokens)
  end
end

마스킹은 문자 단위로 훑으면서 백틱 런을 세어 코드 스팬 안에 있는 동안에는 달러를 건드리지 않고, 여는 달러의 개수로 인라인과 디스플레이를 가른다. 디스플레이는 그 줄에 수식만 있을 때로 한정한다(display_delimiters?). 복원할 때 CGI.escapeHTML을 통과시키므로 수식 안에 넣은 꺾쇠가 태그가 되지도 않는다. 결과는 \(a|b\), \[x^2+y^2\]이고 코드 스팬 안의 달러는 <code>에 그대로 남는다.

두 번째 것이 더 고약했다. 합성 댓글을 넣고 실제로 빌드해 보니, HTML 태그를 전부 제거해도 kramdown의 속성 문법이 남아 있으면 이런 것이 만들어진다.

입력:  안녕하세요
       {: onclick="alert(1)"}
출력:  <p onclick="alert(1)">안녕하세요</p>

태그를 한 글자도 쓰지 않고 이벤트 핸들러가 달린다. 저장 시점의 Worker(stripHtml의 세 번째 치환)와 렌더 시점의 필터 양쪽에서 {: ...}를 지운다. 저장 전 한 번이면 충분해 보이지만, 손으로 옮겨 넣은 데이터나 과거 파일도 같은 경계를 지나게 하려면 렌더 쪽에도 있어야 한다.

def remove_kramdown_extensions(source)
  source.gsub(/\{::?[^}\n]*\}/, "")
end

이 결함은 단위 테스트가 아니라 합성 댓글을 실제 Jekyll 빌드에 태워 산출 HTML을 본 덕에 나왔다. 격리된 케이스만 통과시키고 실제 파일에서 깨지는 패턴은 이 저장소에 전례가 여러 번 있다.

세 번째 달러 문제는 댓글 본문이 아니라 폼 아래 안내문에 있었다. “마크다운과 $…$ 수식을 지원합니다”에서 달러가 보이지 않았다. 이 페이지에는 KaTeX auto-render가 document.body 전체에 걸려 있으니, 달러 사이를 수식으로 렌더하면서 구분자를 먹은 것이다. 본문의 수식은 계속 렌더돼야 하므로 그 문단 하나만 뺀다.

renderMathInElement(document.body, {
  delimiters: window.KATEX_DELIMITERS,
  macros: window.KATEX_MACROS,
  ignoredClasses: ["no-math"],
  strict: false,
  throwOnError: false
});

스코프가 좁은지는 수학 글 한 편에서 KaTeX 스팬이 1596개 그대로 나오는 것으로 확인했다.

상자를 걷어낸 댓글 조판

접수 경로가 다 돌고 나서 사용자가 화면을 열어 보고 한 첫 말은 기능 얘기가 아니었다.

말한대로 이게 우리 현재 블로그 컨셉과 얼마나 디자인이 잘 맞는지 모르겠다.

맞지 않았다. 댓글 한 건이 border-radius: .5rem 짜리 틴트 상자였고 멘션은 알약이었다. 이 블로그의 나머지는 직각과 헤어라인으로 되어 있다. 아바타를 넣을 계획이 없는데 상자 안쪽 여백만 1rem 넘게 잡아먹고 있기도 했다. 그리고 섹션 제목 “댓글”이 그 아래 어떤 글자보다도 작았다. 테마 기본값이 그렇다.

.page__comments-title {
  font-size: $type-size-6;   // 0.75em
  text-transform: uppercase;
}

새 규칙은 상자를 하나도 두지 않는 것이다. 글과 댓글 사이는 이중선, 제목 아래는 헤어라인, 본문은 왼쪽 가장자리에 붙는다. 악센트는 brass 하나로 몰아 필수 표시, 역할 배지, 편집 중 표시, 기본 버튼 호버가 전부 거기서 나온다.

구조를 괘선이 전부 지게 되니 스킨의 $border-color를 그대로 쓸 수 없었다. 라이트의 #d7d2c5는 종이 위에서 멀쩡하지만 다크의 #20242d는 #0b0d12 배경에 묻힌다. 상자가 있을 때는 선이 안 보여도 상자 모양이 남았는데, 이제는 입력란과 구분선이 통째로 사라진다. 잉크와 종이를 섞어 두 모드에서 같은 세기가 나오게 했다.

$comment-rule: mix($text-color, $background-color, 20%);

라이트에서 #c5c3bd, 다크에서 #37383a가 된다. 라이트 쪽은 기존 헤어라인과 거의 같은 값이고 다크만 올라온다.

답글은 처음에 좌측 세로 괘선으로 층을 표시했다.

ㄴ자로 이어진 선인 일단 마음에 들지는 않아.

그 세로선이 각 댓글의 아래 구분선과 만나면서 코너가 생긴 것이다. 세로선을 빼고 들여쓰기만 남기니 구분선이 통째로 들여써져 계단이 되고, 그 계단이 층 표시를 대신한다.

폼도 상자 하나였다. 이름·암호·이메일을 첫 줄에 세 칸으로 놓고 댓글을 그 아래로 내렸다. 폼 밑에 늘어져 있던 주의사항 네 줄은 제목 줄 오른쪽 끝의 ⓘ 안으로 접었다. 호버와 포커스로 여는 것은 CSS가 하고, 터치 기기용 클릭 토글만 JS가 붙인다. 밖에 남긴 것은 마크다운·수식 안내와 필수 항목 표시뿐이다. Turnstile 위젯도 같이 접혔다. appearance: "interaction-only"로 렌더하면 사람으로 판정된 방문자에게는 아무것도 뜨지 않고, 확인이 필요할 때만 그 자리에 나타난다.

댓글 머리의 시각에서 마지막 하나가 나왔다. 방문자 시간대로 바꾸는 김에 서버 조판의 라벨을 UTC에서 KST로 고쳤는데, 그러고 나서 숫자가 UTC라는 것을 알았다. _config.yml에 timezone: Asia/Seoul이 있는데도 그렇다. Liquid date: 필터는 site timezone을 적용하지 않고, Jekyll의 date_to_xmlschema는 적용한다. 같은 값에 둘을 나란히 쓰면 datetime 속성은 +09:00인데 본문 숫자는 UTC가 된다.

{%- assign _local_date = _c.date | date_to_xmlschema -%}
<time datetime="{{ _local_date }}">{{ _local_date | date: "%Y-%m-%d %H:%M" }} KST</time>

한 번 지역화한 값을 다시 조판하면 맞는다. 이건 JS가 없을 때의 fallback이고, 평소에는 Intl.DateTimeFormat이 datetime 속성을 읽어 방문자 시간대로 다시 쓴다. 프론트매터의 date:는 Jekyll이 이미 지역화해 파싱하므로 이 함정에 걸리지 않는다. 문자열로 들어온 UTC 타임스탬프만 해당된다.

배포 뒤에 붙는 알림 워크플로

알림은 댓글이 사이트에 실제로 올라온 다음에 나가야 한다. 그렇다고 빌드 워크플로에 스텝을 하나 더 붙일 수는 없다. build-deploy.yml은 freeze_revising_posts.py가 체크아웃 직후에 와야 한다는 계약이 걸린 파일이라 건드리지 않기로 했다. 그래서 workflow_run으로 뒤에 매다는 별도 워크플로가 됐다.

on:
  workflow_run:
    workflows: ["Build and deploy site"]
    types: [completed]

jobs:
  notify:
    if: >-
      vars.COMMENTS_NOTIFY_ENABLED == 'true' &&
      github.event.workflow_run.conclusion == 'success' &&
      github.event.workflow_run.head_branch == 'main'
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha }}

체크아웃 대상이 방금 배포된 정확한 head_sha라는 점이 중요하다. 그 리비전의 _data/comments/를 훑어 공개 필드만(id, threadKey, permalink, date, replying_to, mentions, name, lang) JSON으로 만들고, HMAC-SHA256 서명을 헤더에 실어 /v1/notify로 보낸다. COMMENTS_NOTIFY_ENABLED 변수는 인프라가 준비되기 전에 잡이 도는 것을 막으려고 붙인 게이트다.

서명은 한 번 401을 냈다. Worker는 64자리 hex secret을 바이트로 디코딩해 HMAC 키로 썼고, Actions 쪽 Ruby는 같은 값을 ASCII 문자열 그대로 서명하고 있었다. 키 전파 지연처럼 보이는 증상이라 secret을 다시 넣어 보고 싶어지는 자리인데, 원인은 양쪽의 키 해석 규칙이 달랐던 것이다. 둘 다 raw 문자열로 통일하고 회귀 테스트를 붙였다. 이메일 암호화 키의 32바이트 디코딩 규칙은 그대로 뒀다.

수신자 계산은 중복 발송을 막는 쪽으로 짜여 있다.

const kinds = {
  approved: !(await env.COMMENTS_KV.get(`notified:${comment.id}:approved`)),
  reply: Boolean(comment.replying_to) && !(await env.COMMENTS_KV.get(`notified:${comment.id}:reply`)),
  mention: comment.mentions.length > 0 && !(await env.COMMENTS_KV.get(`notified:${comment.id}:mention`))
};
if (!Object.values(kinds).some(Boolean)) continue;

워크플로는 저장소에 있는 댓글 전체를 매번 보내고, Worker가 notified: 키가 없는 것만 처리한다. 그래서 재실행에 안전하다. 수신자는 작성자 본인·부모 작성자·멘션 대상의 합집합에서 자기 자신과 수신거부를 뺀 것이고, 이메일 HMAC을 키로 한 Map으로 합쳐 한 사람에게 한 통만 간다. Resend 호출에도 idempotency-key를 실었다. 도입 시점 이전 댓글로 소급 발송이 나가는 사고는 NOTIFY_EPOCH가 막는다. 운영 probe의 응답이 sent: 0, ignored_before_epoch: 1이었다.

주소 자체는 저장소에 없다. 댓글 YAML에는 “이메일을 남겼다”는 사실인 notify: true만 들어가고, 주소는 AES-GCM으로 암호화해 KV의 sub:<id>에 둔다. 발송 시점에만 복호화한다. 메일에는 RFC 8058 원클릭 수신거부 헤더와 함께 스레드 단위·전역 해제 링크, 그리고 자기 댓글 삭제 링크가 들어간다.

크론이 하던 최근 댓글 집계

사이드바의 최근 댓글은 giscus 시절 GraphQL로 Discussions를 훑어 _data/recent_comments.yml을 생성하는 274줄짜리 파이썬이 */15 크론으로 돌며 만들고 있었다. 댓글이 저장소 안에 있으면 그럴 이유가 없다. 43줄짜리 빌드 훅이 대신한다.

Jekyll::Hooks.register :site, :post_read do |site|
  next unless site.config.dig("comments", "provider") == "custom"

  posts = site.posts.docs.each_with_object({}) do |post, index|
    key = post.url.sub(%r{\A/}, "").gsub("/", "__")
    index[key] = post
  end
  # site.data["comments"] 순회 → deleted 제외 → 언어별 최신 5건
end

키를 만드는 식이 폼과 Worker와 이 플러그인 세 곳에 같은 모양으로 있다. 첫 줄의 provider 검사는 전환 도중을 위한 것이다. giscus가 아직 활성인 상태에서 이 플러그인이 돌면 기존 사이드바 데이터를 빈 배열로 덮어쓴다.

크론이 없어지는 자리에는 계약이 몇 개 걸려 있어 한 번에 처리해야 했다. crontab에서 두 줄을 지우고(백업 먼저, 106줄에서 104줄), cron-gate의 job id는 crontab에서 동적으로 읽히므로 따로 지울 것이 없었고, 블로그 운영 대시보드의 “댓글 수집” 타일은 승인 대기 중인 PR 개수를 세는 타일로 바꿨다.

def sec_comment_prs():
    """승인 대기 중인 `comment/*` PR을 GitHub에서 직접 센다."""
    rc, out, err = run([
        "/usr/bin/gh", "pr", "list", "--repo", "math-jh/math-jh.github.io",
        "--state", "open", "--limit", "100",
        "--json", "number,title,url,headRefName,createdAt",
    ])

_config.yml 쪽에서 실수하기 쉬운 항목이 하나 있다. exclude:에 workers를 넣지 않으면 Jekyll이 Worker 소스 디렉토리를 통째로 _site로 복사해 배포한다. 시크릿이 코드에 없다고는 해도 배포할 이유가 없는 물건이다. 빌드 산출물에 workers/ 파일이 0개인지는 실제 빌드에서 확인했다. 배포 직전 마지막 대조에서는 Worker의 보조 workers.dev URL이 살아 있는 것이 발견됐다. 커스텀 도메인에만 rate limit이 걸려 있으므로 그 URL이 우회로가 된다. workers_dev와 preview URL을 끄고 재배포해 404로 닫았다.

승인 대기 PR을 미는 크론

앞 절에서 대시보드 타일은 comment/* PR 개수를 세게 됐지만, 그 숫자는 대시보드를 열어 둬야 보인다. 방문자가 댓글을 남기면 그것은 머지를 기다리는 PR 하나로 앉아 있고, 며칠 눈치채지 못하면 승인이 그만큼 늦는다. 사용자가 물은 것은 그 자리를 메우는 알림이 어디로 오느냐였다.

ㅇㅋ 그리고 그 알림 경로는 telegram으로 오나?

아 그렇지. Pi cron으로 하고, 5분에 한 번씩 하자. LLM 없이, 결정론적으로. dependabot PR 같은것도 같이 보내도 상관없으니 그냥 깔끔하게 짜.

그래서 나온 커밋 846f2751의 scripts/pr-notify/notify_open_prs.py는 gh pr list의 출력과 상태파일 하나만 본다. 판단할 것이 없으니 모델도 부르지 않는다. 대상을 comment/*로 좁히지 않는 것은 dependabot이 섞여 와도 상관없다고 했고, 필터가 없는 편이 스크립트가 짧아서다. 크론은 */5로 돌되 다른 블로그 크론과 마찬가지로 대시보드의 cron-gate를 지나 실행되고, CRON_JOBS에 blog-pr-notify 한 줄을 더해 일시정지·재개 버튼이 붙었다. 워커 상태 행은 없다(worker=None).

상태는 ~/.local/state/blog-pr-notify.json의 seen, 이미 알린 PR 번호 목록이다. 번호는 재사용되지 않으므로 닫히거나 머지된 PR을 목록에서 빼지 않는다. 빼면 그 PR이 재오픈될 때 다시 알림이 나간다.

seen = load_seen()                       # 파일 없으면 None, 깨졌으면 set()
if seen is None and not args.notify_all:  # 첫 실행: 조용히 seed 만 한다
    save_seen({p["number"] for p in pulls})
    return 0
seen = seen or set()
fresh = [p for p in pulls if p["number"] not in seen]

상태파일이 없는 첫 실행은 지금 열린 PR을 전부 seen으로 적고 아무것도 보내지 않아, 도입 시점에 묵은 PR이 한꺼번에 날아가는 것을 막는다. --notify-all이 그 억제를 끈다. 파일이 깨졌을 때 load_seen은 빈 집합을 돌려주고, 그러면 전량이 다시 알림으로 나간다. 조용히 침묵하는 것보다 한 번 시끄러운 쪽이 낫다는 선택이다.

전송은 hermes send -t telegram으로 묶어 보내고, 여덟 건까지만 적은 뒤 나머지는 건수로 접는다. 상태 쓰기는 .tmp에 적고 replace로 원자 교체하므로 크론이 겹쳐 돌아도 반쪽 파일이 남지 않고, 전송이 실패하면 seen을 갱신하지 않고 나가 다음 5분에 다시 본다. 첫 실행 로그는 열린 PR 하나를 알림 없이 seen 처리한 것으로 끝났고, 지금 그 파일에는 번호 하나가 들어 있다.

아직 열려 있는 완료 판정

명세의 완료 판정 20개 중 처음에 운영 실측으로 닫힌 것은 넷이었다. ko/en 키 분리, <script>와 kramdown IAL 제거, Turnstile 없는 제출과 honeypot 거부, 경로 조작 거부. 나머지는 단위 검증과 합성 빌드까지만 통과한 상태였다. 그 뒤 Worker를 배포하고 실제 댓글로 제출·승인·머지·표시까지 돌렸고, 수정 경로는 없는 ID로 프로브해 라우트와 검증이 살아 있는 것까지 봤다. 허용하지 않은 origin이 origin_denied로 막히는 것도 같은 자리에서 확인했다.

남은 칸은 메일이다. 알림 게이트(COMMENTS_NOTIFY_ENABLED)는 열려 있고 NOTIFY_EPOCH는 지금 시각으로 밀어 두었으므로, 다음에 이메일을 남기고 들어오는 댓글부터 발송 경로가 실제로 돈다. 메일 도달률(SPF·DKIM·DMARC 헤더 확인)과 Cloudflare rate limiting rule은 아직 그 칸에 있다.

giscus에 남아 있던 댓글 한 건은 옮기지 않았다.

giscus 이전은 필요없어.

그 한 건은 이전 직후에 사용자 본인이 단 것이라 옮길 것이 사실상 없었다. 새 시스템은 댓글 0건에서 시작한다. 어느 쪽이든 사이드바의 최근 댓글 목록이 비어 있는 것은 똑같고, 이제는 그게 GitHub 계정이 없어서는 아니다.