브라우저 IDE에서 API 키와 환경 변수를 안전하게 다루기

첫 번째 규칙은 불편하지만 단순합니다. 정적 웹 앱은 비밀을 보관할 수 없습니다. 브라우저는 HTML, CSS, JavaScript를 내려받아 사용자의 기기에서 실행합니다. 누구나 DevTools를 열고 네트워크 패널을 읽고 번들을 검색하고 중단점을 설정해 변수를 검사할 수 있습니다. 코드를 축소하거나 청크로 나누거나 설정 파일에 값을 숨겨도 달라지는 것은 노력이지 결과가 아닙니다. 브라우저 IDE는 프로젝트 코드를 실행하는 샌드박스를 추가하지만, IDE 자체의 UI는 여전히 같은 오리진에서 실행되며 필요한 값을 읽어야 합니다. 샌드박스는 UI가 사용해야 하는 값의 금고가 아닙니다. 유용한 판단 기준은 간단합니다. 탭에서 실행되는 코드가 값을 사용할 수 있어야 한다면, 탭을 사용하는 사람도 그 값을 읽을 수 있다고 가정하세요. 같은 오리진에서 실행되는 스크립트도 읽을 수 있다고 가정하세요. 이것은 브라우저 개발을 위험하게 만드는 이야기가 아닙니다. 경계를 정의하는 이야기입니다. 공개 식별자는 둘 수 있지만 서버 자격 증명은 둘 수 없습니다.

Node.js 서버에서는 환경 변수를 런타임에 프로세스에서 읽습니다. Vite, Create React App, Next.js, Astro 빌드에서는 공개 환경 변수의 동작이 다릅니다. 번들러가 빌드 중에 참조를 리터럴 문자열로 바꿉니다. Vite는 VITE_ 접두사 변수를 import.meta.env를 통해 노출하고, Create React App은 REACT_APP_, Next.js는 NEXT_PUBLIC_, Astro는 PUBLIC_을 사용합니다. 접두사는 명명 규칙이지 보안 제어가 아닙니다. 값이 인라인되는 순간 그 값은 모든 방문자가 내려받는 JavaScript의 일부가 됩니다. 공개 접두사가 없는 변수는 일반적으로 클라이언트 코드에서 사용할 수 없으므로, 서버 전용 값은 정적 페이지가 아니라 서버나 서버리스 함수에서 읽어야 합니다. .env 파일은 개발과 빌드 입력이지 런타임 비밀 저장소가 아닙니다. 로컬 구성과 버전 관리 밖에 값을 두는 데는 유용하지만, 빌드 후에 값을 비공개로 만들어 주지는 않습니다.

# Safe to expose: a public endpoint
VITE_API_URL=https://api.example.com

# Never expose: keep this on a server
STRIPE_SECRET_KEY=REPLACE_WITH_SERVER_SECRET

일부 키는 공개되도록 설계되었습니다. Stripe 공개 키는 계정을 식별하고 결제 토큰을 만듭니다. 비밀 키는 실제로 돈을 움직이므로 서버에 있어야 합니다. Supabase anon 키는 행 수준 보안 정책이 올바를 때만 안전합니다. Firebase 웹 구성은 프로젝트를 식별하지만 관리자 액세스를 부여하지는 않습니다. 지도와 분석 키는 흔히 도메인이나 API로 제한됩니다. 이런 값은 브라우저로 보낼 수 있지만, 허용 오리진, API 제한, 최소 권한 역할, 할당량, 경고 같은 제한이 여전히 필요합니다. 반대 범주는 말하기 더 쉽습니다. 서비스 역할 키, 데이터베이스 비밀번호, SMTP 자격 증명, 서명 비밀, AI 공급자의 비밀 키는 정적 번들에 절대 들어가면 안 됩니다. 애플리케이션 소유의 공급자 키는 특히 위험합니다. 발견한 사람이 애플리케이션의 돈을 쓸 수 있기 때문입니다. 사용자 소유 키는 다른 경우입니다. 여전히 베어러 자격 증명이지만 사용자의 것이며, 목표는 프로젝트나 저장소가 아니라 사용자의 브라우저에 두는 것입니다.

GB Coder의 AI 패널은 bring-your-own-key 방식입니다. 키 관리자는 기본적으로 공급자 키를 메모리에 보관합니다. localStorage에는 쓰지 않습니다. 사용자가 명시적으로 선택한 경우에만 sessionStorage에 저장하며, 이때 값은 현재 탭으로 제한되고 일반적으로 탭을 닫으면 지워집니다. 사용자가 키를 지우면 메모리와 세션 저장소에서 제거됩니다. 관리자는 각 키를 승인된 엔드포인트 오리진에 묶고, 아웃바운드 게이트가 자격 증명이 승인되지 않은 대상으로 전송되지 않는지 확인합니다. 공급자 오류는 가림 처리 계층을 거치며, 메시지가 UI나 로그에 도달하기 전에 키 패턴과 활성 키를 제거합니다. 사용자 지정 공급자 메타데이터는 localStorage에 저장되지만, 비밀로 표시된 헤더는 저장 전에 지워지며 다시 입력해야 합니다. 요청은 브라우저에서 공급자 엔드포인트로 직접 전송되며, GB Coder가 LadeStack 서버를 통해 키를 프록시하지 않습니다. 이런 조치는 우발적 저장과 오리진 간 유출을 줄입니다. 하지만 기본 규칙은 바뀌지 않습니다. 같은 오리진에서 실행될 수 있는 스크립트는 페이지가 읽을 수 있는 것을 읽을 수 있습니다. 민감한 작업에는 깨끗한 프로필을 사용하고 신뢰할 수 없는 확장 프로그램을 설치하지 마세요.

비밀은 프로젝트 트리 밖에 두세요. .env와 로컬 변형을 .gitignore에 추가하고, 자리 표시자 이름만 담은 .env.example을 커밋하세요. Vite를 쓰는 프로젝트라면 모든 VITE_ 변수가 프로덕션 번들에 인라인된다는 점을 기억하세요. 로컬 개발에서 편리했던 값도 프로덕션 빌드에 사용되는 순간 공개됩니다. 배포 전에 생성된 자산에서 키 패턴을 검사하고, 발견되면 경고가 아니라 사고로 취급하세요. GitHub 비밀 스캔과 푸시 보호는 알려진 토큰 형식 일부를 잡을 수 있지만, 안전망일 뿐 저장소 밖에 값을 두는 일을 대신하지는 않습니다. 브라우저 IDE의 ZIP 내보내기에는 프로젝트 파일이 포함됩니다. .env 파일이 프로젝트 안에 있으면 백업과 함께 이동합니다. 백업은 암호화된 금고가 아닙니다. 내보내기는 비공개 장소에 보관하고 더 이상 필요 없는 오래된 사본은 삭제하세요. 스크린샷, 이슈 보고서, 채팅 메시지도 마찬가지입니다. 그중 하나에 붙여넣은 키는 이미 브라우저를 떠난 것입니다.

# .gitignore
.env
.env.local
.env.*.local

GitHub 개인 액세스 토큰과 배포 토큰은 보기보다 강력합니다. repository와 workflow 범위를 가진 클래식 토큰은 비공개 코드를 읽고 파일을 변경하고 릴리스를 시작할 수 있습니다. 단일 저장소, 명시적 권한 목록, 만료일이 있는 fine-grained 토큰을 선호하세요. 토큰에는 작업에 필요한 권한만 부여하세요. 동기화에는 contents 읽기와 쓰기만 있으면 되고 administration이나 billing은 필요 없습니다. 기기나 용도별로 별도 토큰을 만들고 작업이 끝나면 폐기하세요. Vercel이나 Netlify의 배포 토큰은 프로젝트를 게시, 교체, 삭제할 수 있습니다. 공급자가 프로젝트나 팀 범위를 지원하면 사용하고, 만료를 지원하면 설정하세요. 토큰은 필요할 때만 배포 패널에 붙여넣고 프로젝트 파일에 저장하지 마세요. CI에서는 커밋된 .env 대신 저장소나 조직 비밀을 사용하고, 포크에서 온 pull request에는 일반적으로 비밀이 전달되지 않는다는 점을 기억하세요. 스크린샷에 찍혔거나 채팅에서 공유되었거나 공개 저장소에 커밋된 토큰은 1초 뒤에 삭제했더라도 침해된 것으로 취급해야 합니다.

AI 공급자 키는 청구서가 붙은 베어러 자격 증명입니다. 가진 사람은 누구나 요청을 보내고 할당량을 소비하며 비용을 발생시킬 수 있습니다. 프로젝트 범위로 제한된 키를 사용하고, 공급자가 제공하면 지출 한도를 설정하고, 조직의 마스터 키 대신 실험용 별도 키를 사용하세요. 특히 기기를 공유하거나 새 확장 프로그램을 설치한 뒤에는 사용량을 정기적으로 확인하세요. Ollama, LM Studio, vLLM 같은 로컬 공급자는 클라우드 키가 필요 없지만, 엔드포인트는 여전히 기기 위의 서비스입니다. 데모를 돌리기 위해 로컬 엔드포인트를 공용 인터넷에 노출하지 마세요. 사용자 지정 공급자가 프록시를 가리키면 프록시가 키를 볼 수 있습니다. 자신이 관리하고 이해하는 프록시만 사용하세요. 프롬프트 인젝션도 관련 위험입니다. 파일, 웹 페이지, 붙여넣은 오류 메시지에는 어시스턴트를 겨냥한 지시가 들어 있을 수 있습니다. 비밀은 프롬프트 밖에 두고, 어시스턴트가 읽도록 허용한 파일에도 넣지 마세요. 대화에 키가 나타나면 로테이션하세요.

공유 컴퓨터나 실습실 기기에는 다른 절차가 필요합니다. 비공개 브라우저 프로필을 사용하고, 세션 저장을 선택하지 말고, 끝나면 탭을 닫으세요. 브라우저가 키 저장을 제안하면 거절하세요. 남아 있다고 의심되면 사이트 저장소를 지우세요. 브라우저 확장 프로그램도 경계의 일부입니다. 넓은 호스트 권한을 가진 확장 프로그램은 흔히 페이지 내용이나 저장소를 읽을 수 있고, 설치 후에 악성 업데이트가 도착할 수도 있습니다. 자격 증명을 다루는 작업에는 최소한의 프로필을 사용하세요. 이 맥락에서 전형적인 웹 위험은 크로스 사이트 스크립팅입니다. 공격자가 IDE 오리진에서 스크립트를 실행할 수 있으면, 그 스크립트는 localStorage와 sessionStorage를 읽고 페이지가 열려 있는 동안 요청을 보낼 수 있습니다. 의존성을 최신으로 유지하고 신뢰할 수 없는 타사 스크립트를 피하며, 배포된 사이트에 콘텐츠 보안 정책을 고려하세요. 클립보드 관리자와 화면 공유 도구도 복사하고 표시하는 것을 봅니다. 키를 옮긴 뒤 클립보드를 지우고, 공급자 설정 패널을 열기 전에 공유를 일시 중지하세요.

유출된 키에 대한 신뢰할 수 있는 대응은 로테이션뿐입니다. 먼저 폐기하는 것이 중요합니다. 새 키를 준비하는 동안 이전 키가 유효하면 노출은 계속됩니다. 새 키는 필요한 최소 범위로 만들고, 애플리케이션이나 브라우저 설정을 업데이트하고, 값이 빌드에 포함되어 있었다면 다시 배포한 뒤 이전 키가 거부되는지 확인하세요. 그다음 공급자의 사용량과 감사 로그에서 예상하지 못한 활동을 확인하세요. 키가 Git에 커밋되었다면 파일을 삭제하는 것만으로는 부족합니다. 값은 기록에 남습니다. 먼저 로테이션한 뒤 git filter-repo나 BFG 같은 도구로 기록을 다시 쓰고, 팀의 동의를 얻어 force-push하고, 협업자에게 다시 클론하도록 요청하세요. 호스팅 플랫폼은 오래된 빌드를 캐시할 수 있으므로 이전 값이 오래된 번들에서 제공되지 않도록 하세요. 키를 AI 채팅, 지원 티켓, 스크린샷에 붙여넣었다면 보관된 것으로 가정하고 로테이션하세요. 마지막으로 무슨 일이 있었는지 기록하고, 문제를 잡았을 수 있는 검사를 추가하고, 다음 키의 수명을 줄이세요.

프로젝트가 브라우저를 떠나기 전에 이 순서를 사용하세요. 첫째, 각 값을 분류합니다. 공개 식별자, 사용자 자격 증명, 서버 비밀 중 하나입니다. 둘째, 서버 비밀을 정적 번들 밖에 두고 서버리스 함수나 API 뒤로 옮깁니다. 셋째, 공개 접두사가 필요한 값만 노출하고 배포 전에 빌드된 자산을 검사합니다. 넷째, .env 파일을 Git 밖에 두고 .env.example을 커밋하며 비밀 스캔을 활성화합니다. 다섯째, GitHub와 호스팅용으로 범위가 제한되고 만료되는 토큰을 용도별로 하나씩 만듭니다. 여섯째, GB Coder에서는 신뢰할 수 있는 기기가 아니라면 키를 메모리에 두고, 트레이드오프를 이해할 때만 세션 저장을 선택합니다. 일곱째, 키를 프롬프트, 이슈, 스크린샷, 프로젝트 파일에 절대 붙여넣지 않습니다. 여덟째, 조금이라도 의심되면 로테이션하고 교체 전에 폐기합니다. 아홉째, 공유 기기에서는 깨끗한 브라우저 프로필을 사용합니다. 열째, 필요해지기 전에 유출 대응 계획을 적어 둡니다. 브라우저를 사적인 금고가 아니라 공개 클라이언트로 취급하면 브라우저 IDE에서도 자격 증명을 책임 있게 관리할 수 있습니다.