/.well-known/ 그 정체는? 웹 표준의 숨은 약속 장소 이야기

주소창에 숨어 있는 ‘약속된 장소’ /.well-known/

혹시 웹사이트 주소 뒤에 /.well-known/security.txt 같은 경로가 붙은 걸 본 적 있으세요? HTTPS 인증서를 발급받을 때 /.well-known/acme-challenge/... 같은 게 잠깐 만들어지기도 하고요. 이 /.well-known/이라는 폴더, 도대체 뭐길래 여기저기서 튀어나오는 걸까요? 마침 웹 표준 쪽에서 오래 일해온 마크 노팅엄(Mark Nottingham)이 “잘 알려진 URI를 새로 정의하고 싶다면 이런 걸 고민하라”는 글을 정리했는데, 이걸 핑계 삼아 개념부터 차근차근 풀어볼게요.

‘Well-Known URI’가 뭐냐면

이게 뭐냐면, 웹에서 미리 약속해둔 ‘고정된 위치’예요. RFC 8615라는 표준에 정의돼 있는데, 핵심은 이래요. 어떤 사이트에 대한 정보(메타데이터)를 찾고 싶을 때, 매번 “그 정보 어디 있어요?” 하고 물어보는 대신 “무조건 https://도메인/.well-known/이름으로 가면 있다”고 못 박아두는 거예요.

비유하자면 이래요. 처음 방문한 건물에서 화장실을 찾을 때, 안내 데스크에 물어보지 않아도 “보통 1층 엘리베이터 옆”이라는 암묵적 약속이 있으면 바로 찾아가잖아요. well-known URI가 딱 그 역할이에요. 기계(브라우저, 서버, 봇)끼리 “이런 정보는 무조건 여기에 둔다”고 합의해두면, 서로 헤매지 않고 정보를 주고받을 수 있어요.

실제로 우리가 매일 쓰는 것들이 여기에 깔려 있어요. 로그인할 때 쓰는 OpenID Connect는 /.well-known/openid-configuration에서 설정 정보를 읽어오고, Let's Encrypt 같은 무료 인증서 발급은 /.well-known/acme-challenge/로 “이 도메인이 진짜 네 거 맞아?”를 검증해요. 보안 취약점 제보 연락처를 알리는 security.txt, 앱과 웹을 연결하는 assetlinks.json도 다 여기 살고요.

새로 하나 정의하려면 뭘 고민해야 하나

노팅엄 글의 핵심은 “아무나 마음대로 /.well-known/ 밑에 이름을 만들면 난장판이 된다”는 거예요. 그래서 몇 가지 원칙을 짚어요.

첫째, IANA에 등록하라는 거예요. IANA는 인터넷의 각종 이름과 번호를 관리하는 공식 기관인데, 여기에 등록 안 하고 멋대로 이름을 쓰면 나중에 다른 사람이 같은 이름을 다른 용도로 써서 충돌이 날 수 있어요. 둘째, 꼭 필요할 때만 쓰라는 거예요. well-known URI는 ‘사이트 전체에 대한 정보’를 둘 자리지, 특정 사용자나 특정 페이지에 딸린 정보를 두는 곳이 아니에요. 그런 건 일반 API 경로를 쓰는 게 맞죠. 셋째, 보안과 권한을 생각하래요. 이 경로는 누구나 예측할 수 있는 공개된 위치라서, 민감한 정보를 그냥 두면 안 되고, 또 서브디렉터리에 사용자 콘텐츠를 올릴 수 있는 사이트라면 누가 /.well-known/을 흉내 내 위조하지 못하게 막아야 해요.

업계 맥락에서 보면

well-known URI는 ‘분산된 웹에서 어떻게 표준 합의를 이룰까’라는 큰 흐름의 일부예요. 중앙 서버 한 곳이 모든 걸 통제하는 게 아니라, 각자 자기 도메인을 운영하면서도 “이런 정보는 여기 둔다”는 공통 규칙만 지키면 서로 연동되는 거죠. 최근 뜨는 연합형 SNS(마스토돈 같은 페디버스)도 /.well-known/webfinger로 “이 사용자가 어느 서버에 있나”를 찾아내요. 즉, 거대 플랫폼 없이도 서비스끼리 연결되게 해주는 접착제 같은 역할이에요.

한국 개발자에게 주는 시사점

실무에서 의외로 마주칠 일이 많아요. HTTPS 인증서 자동 갱신이 안 될 때 /.well-known/acme-challenge/ 경로가 막혀 있는 게 원인인 경우가 흔하거든요(Nginx 설정에서 이 경로만 예외 처리해줘야 할 때가 많아요). 모바일 앱 딥링크를 붙일 때도 /.well-known/ 밑에 검증 파일을 올려야 하고요. 그리고 만약 사내에서 여러 서비스가 공유할 메타데이터 표준을 만든다면, 아무 경로나 쓰지 말고 well-known 패턴과 등록 원칙을 따르는 게 나중에 혼란을 줄여줘요. ‘예측 가능한 고정 위치’라는 설계 철학 자체가 API를 만들 때도 두고두고 참고할 만하죠.

마무리

/.well-known/은 ‘기계끼리 헤매지 않게 미리 정해둔 약속 장소’라는 한마디로 정리돼요. 여러분은 그동안 무심코 지나쳤던 이 경로, 어떤 서비스에서 마주쳐 보셨나요?