# 세이프 키링 비밀번호 생성, 복사, 마스킹 저장, URL 아이콘 이동을 지원하는 모바일 우선 PWA 보안 키링 웹앱. ## Masterplan - **비전:** 별도 계정/서버 없이 브라우저 안에서 즉시 쓸 수 있는 개인용 비밀번호 키링. - **대상 사용자:** 모바일에서 빠르게 계정 정보를 저장하고 강한 비밀번호를 생성/복사하려는 일반 사용자. - **가치 제안:** 생성 → 복사 → 저장까지 최소 탭 수로 완료하는 한국어 UX. - **보안 방향:** 서버 전송 없이 `localStorage`에만 저장하며, 화면에서는 비밀번호를 기본 마스킹. - **배포 방향:** 빌드 없는 정적 PWA. 모든 파일은 루트에 위치하며 `./` 상대 경로만 사용. ## Tech Stack & Architecture - **Runtime:** 정적 HTML/CSS/JS, 빌드 과정 없음. - **UI Framework:** React `19.2.0` CDN import via `https://esm.sh/react@19.2.0`. - **Renderer:** ReactDOM client CDN import via `https://esm.sh/react-dom@19.2.0/client?deps=react@19.2.0`. - **Template Helper:** `htm@3.1.1` CDN import. JSX/Babel 없이 `html\`\`` 템플릿으로 React element 생성. - **Utility CSS:** Tailwind CDN은 `index.html`에서 ``로 로드. - **Custom Styling:** `main.css`의 CSS variables, 다크/라이트 테마, metallic card/button 스타일. - **PWA:** `manifest.webmanifest`만 제공. 현재 service worker/offline cache는 없음. - **Storage:** 브라우저 `localStorage`. - 계정 목록: `safe-keyring-accounts-v1` - 테마: `safe-keyring-theme-v1` - **Routing:** 실제 라우터 없음. `main.js` 초기화 시 비정상 pathname을 `./index.html#/`로 교정하고 hash가 없으면 `#/` 부여. - **File linking constraint:** `index.html`은 반드시 `./main.css`, `./main.js`, `./manifest.webmanifest`처럼 상대 경로를 사용해야 함. `/main.js`, `./src/main.js` 금지. ### Component/State Pattern `main.js` 단일 파일 앱 구조: - `App()`이 전체 UI와 상태를 소유. - 주요 상태: - `accounts`: 저장 계정 배열 - `loaded`: localStorage hydrate 완료 여부 - `toast`: 토스트 메시지 - `showForm`: 새 계정 입력 폼 표시 여부 - `visibleIds`: 카드별 비밀번호 노출 여부 map - `isDark`: 테마 상태 - `length`: 생성 비밀번호 길이, 8~20 UI 슬라이더에서 사용 - `form`: `{ service, username, url, password }` - derived state: - `score = strengthScore(form.password)` - `meta = strengthMeta(score)` - side effects: - 최초 mount: 경로 보정, 테마 로드, 계정 로드 - `isDark` 변경: ``에 `.dark` toggle 및 저장 - `accounts` 변경: `loaded` 이후 localStorage 저장 - `form.password` 비어 있으면 현재 `length`로 자동 생성 ## File Structure ```text index.html # 앱 진입점. root div, Tailwind CDN, ./main.css, ./main.js, ./manifest.webmanifest 연결 main.css # 전역 CSS variables, 다크 테마, metallic UI 클래스, 애니메이션, 스크롤바 스타일 main.js # React/htm CDN imports, password/account 로직, localStorage, 전체 App UI manifest.webmanifest # PWA 설치 메타데이터, start_url ./index.html#/, data URI SVG icons ``` ## Key Features ### 1. 계정 카드 목록 저장된 계정을 메인 화면에 카드 형태로 노출한다. 계정 데이터 모델: ```js { id: string, // `${Date.now()}-${random}` service: string, // 필수 username: string, // 필수 url: string, // normalizeUrl() 적용, 선택 password: string, // 필수, 평문 localStorage 저장 createdAt: string // ISO timestamp } ``` 요구사항: - 최신 저장 항목이 위에 오도록 `[next, ...prev]`로 추가. - 삭제 시 `deleteAccount(id)`로 배열에서 제거. - 비밀번호는 기본 마스킹 처리. - 카드별 눈 아이콘/버튼으로 `visibleIds[id]`를 토글해 노출. - 계정이 없을 때는 빈 상태 UI를 제공해야 함. ### 2. 비밀번호 생성 관련 함수: - `generatePassword(length = 14, previous = '')` - `strengthScore(password)` - `strengthMeta(score)` 요구사항: - 문자 그룹: - 소문자 `abcdefghijklmnopqrstuvwxyz` - 대문자 `ABCDEFGHIJKLMNOPQRSTUVWXYZ` - 숫자 `0123456789` - 특수문자 `!@#$%^&*()-_=+[]{};:,.?/|~` - 생성 시 각 그룹에서 최소 1자 포함 후 전체 pool로 나머지 채움. - 결과는 shuffle 처리. - 직전 비밀번호와 동일하면 재귀 생성으로 중복 방지. - 길이는 UI에서 8~20자로 조절. - 새로고침 버튼은 `refreshPassword()` 호출 후 `"새 비밀번호를 만들었어요"` 토스트 표시. - 비밀번호 강도: - 길이 8 이상: +20 - 길이 12 이상: +20 - 소문자/대문자/숫자/특수문자 각각 +15 - 최대 100 - 강도 라벨: - `<55`: `주의`, destructive red - `<80`: `양호`, yellow - `>=80`: `강력`, primary green ### 3. 저장 및 관리 관련 함수: - `loadAccounts()` - `saveAccount()` - `deleteAccount(id)` 요구사항: - 저장소는 `localStorage`만 사용. - `loadAccounts()`는 JSON parse 실패 또는 비배열 데이터면 `[]` 반환. - 저장 필수값: - 서비스명 - 아이디 - 비밀번호 - 누락 시 `"서비스명, 아이디, 비밀번호를 확인해 주세요"` 토스트. - 저장 성공 시: - 계정을 목록 맨 앞에 추가 - 폼 초기화 - 새 비밀번호 즉시 재생성 - 폼 닫기 - `"안전하게 저장했어요"` 토스트 - 삭제 성공 시 `"계정을 삭제했어요"` 토스트. > 중요: 현재 비밀번호는 암호화하지 않고 평문으로 localStorage에 저장한다. “마스킹”은 화면 표시 보안일 뿐 저장 보안이 아니다. 암호화 기능을 추가할 경우 기존 `safe-keyring-accounts-v1` 마이그레이션을 고려해야 한다. ### 4. 복사 UX 관련 함수: - `copyText(text)` 요구사항: - 우선 `navigator.clipboard.writeText()` 사용. - 실패 시 textarea + `document.execCommand('copy')` fallback 사용. - 성공/대체 성공 모두 `"복사 완료!"` 토스트 표시. - HTTPS가 아닌 환경에서는 Clipboard API가 실패할 수 있으므로 fallback을 유지해야 함. ### 5. URL 아이콘 및 이동 관련 함수: - `normalizeUrl(value)` - `getHost(url)` - `faviconFromUrl(url)` - `openUrl(url)` 요구사항: - URL 입력값에 `http://` 또는 `https://`가 없으면 `https://`를 자동 추가. - favicon URL은 Google favicon endpoint 사용: ```js https://www.google.com/s2/favicons?domain={host}&sz=64 ``` - host 추출 실패 시 favicon은 빈 문자열. - URL 이동은 새 창/탭으로 열어야 함. - URL이 없으면 `"이동할 URL이 없어요"` 토스트. ### 6. 테마 - 기본 테마는 다크. - `THEME_KEY = 'safe-keyring-theme-v1'`. - `` element에 `.dark` 클래스를 토글한다. - `main.css`는 `:root`와 `.dark` CSS variables를 모두 정의한다. ### 7. PWA `manifest.webmanifest` 요구사항: - `name`: `세이프 키링 (Safe Keyring)` - `short_name`: `Safe Keyring` - `start_url`: `./index.html#/` - `scope`: `./` - `display`: `standalone` - `orientation`: `portrait-primary` - `lang`: `ko-KR` - icons는 외부 파일이 아닌 data URI SVG. 현재 service worker가 없으므로 “설치 가능” 메타데이터는 있으나 오프라인 캐싱은 구현되어 있지 않다. ## Design Guidelines - **언어:** 모든 사용자-facing UI/메시지는 한국어. - **기본 분위기:** 모바일 우선, 다크 모드 중심, 유리/메탈릭 카드. - **컬러 토큰:** - 배경 dark: `hsl(222 47% 5%)` - primary dark: `hsl(174 92% 46%)` - card dark: `hsl(221 36% 10%)` - destructive: red 계열 `hsl(3 90% 64%)` - **CSS 방식:** - 레이아웃/간격은 Tailwind utility class 사용. - 브랜드성 있는 반복 스타일은 `main.css` 클래스 사용: - `.metal-card` - `.metal-button` - `.ghost-button` - `.input-shell` - `.range-accent` - `.toast-pop` - `.card-enter` - **Typography:** 시스템 sans-serif. 별도 웹폰트 없음. - **Responsive behavior:** - 모바일 세로 화면을 1차 타깃. - `viewport-fit=cover` 설정으로 모바일 safe area 대응 가능. - 카드/폼은 좁은 화면에서 단일 컬럼 기준. - **Animation:** - 토스트: `toastIn` 260ms - 카드 진입: `cardEnter` 360ms - **Dark mode gotcha:** `.dark`는 `body`가 아니라 `document.documentElement`에 적용된다. ## App Flow ### 초기 진입 1. `index.html` 로드. 2. Tailwind CDN과 `main.css` 로드. 3. `main.js` module 실행. 4. `App()` mount. 5. pathname이 `/foo`처럼 `index.html` 또는 `/`가 아니면 `history.replaceState(null, '', './index.html#/')`. 6. hash가 없으면 `location.replace('#/')`. 7. localStorage에서 테마 로드, 기본 dark. 8. 약 220ms 후 `loadAccounts()`로 계정 목록 hydrate. ### 새 계정 추가 1. 사용자가 상단 `새 계정 추가` 버튼 클릭. 2. 입력 폼 표시. 3. 비밀번호가 비어 있으면 자동 생성. 4. 사용자가 길이 슬라이더 조절 또는 새로고침 버튼 클릭. 5. 강도 게이지가 즉시 업데이트. 6. 복사 버튼으로 생성 비밀번호 복사 가능. 7. 서비스명/아이디/URL 입력 후 저장. 8. 저장 성공 시 목록 맨 위에 카드 추가, 폼 닫힘. ### 저장 계정 사용 1. 메인 목록에서 계정 카드 확인. 2. 비밀번호는 기본 마스킹. 3. 눈 버튼으로 해당 카드만 노출. 4. 복사 버튼으로 아이디/비밀번호 복사. 5. URL 아이콘 클릭 시 정규화된 URL을 새 창으로 열기. ### 주요 Edge Cases - localStorage 데이터가 깨진 경우: 빈 배열로 복구. - URL scheme 누락: `https://` 자동 추가. - URL host 파싱 실패: favicon 미표시. - Clipboard API 실패: textarea fallback. - 필수 입력 누락: 저장하지 않고 토스트 표시. - 비정상 경로 접근: `./index.html#/`로 내부 교정. - 동일 비밀번호 재생성: `previous`와 같으면 다시 생성. ## Conventions ### Naming - localStorage key는 상단 상수로만 관리: - `STORAGE_KEY` - `THEME_KEY` - 순수 유틸 함수는 `camelCase`: - `normalizeUrl` - `faviconFromUrl` - `generatePassword` - `strengthScore` - React 컴포넌트는 `PascalCase`: - `App` - `Icon` ### Coding Pattern - JSX를 사용하지 않는다. 모든 UI는 `htm`의 `html\`\`` 문법으로 작성한다. - React import는 npm/bundler가 아니라 CDN URL을 유지한다. - 새 의존성을 추가해야 한다면 빌드 도구가 필요한 패키지보다 CDN ESM을 우선한다. - 모든 파일은 루트에 둔다. `src/`, `public/`, `assets/` 폴더를 만들지 않는다. - HTML 참조 경로는 항상 `./`로 시작한다. ### Styling Pattern - 일회성 레이아웃은 Tailwind class. - 재사용 가능한 브랜드 스타일은 `main.css`에 클래스 추가. - 색상은 가능하면 CSS variable 기반 `hsl(var(--...))` 사용. - 다크/라이트 대응이 필요한 색상은 `:root`와 `.dark` 양쪽 토큰을 수정한다. ### Adding a New Feature 1. `main.js` 상단에 필요한 상수/유틸 함수를 추가한다. 2. 앱 전역 상태가 필요하면 `App()` 내부 `useState`로 둔다. 3. localStorage에 저장할 데이터라면 새 key를 상수로 만들고 parse 실패 fallback을 구현한다. 4. UI는 `App()`의 기존 카드/폼 구조 안에 `html\`\``로 추가한다. 5. 새 버튼은 기존 `.metal-button` 또는 `.ghost-button` 스타일을 우선 재사용한다. 6. 사용자 메시지는 `notify('한국어 메시지')`로 토스트 처리한다. 7. 외부 URL/clipboard/localStorage 등 실패 가능한 동작은 반드시 `try/catch` 또는 fallback을 둔다. ### Deployment Gotchas - `index.html`의 아래 라인은 변경 금지: ```html ``` - `/main.js`, `/main.css`, `./src/main.js`로 바꾸면 정적 배포 환경에서 404가 날 수 있다. - 현재 `_redirects` 파일은 포함되어 있지 않다. 호스팅 플랫폼에서 SPA fallback이 필요하면 별도 설정하되, 앱 파일 구조는 4개 루트 파일 원칙을 유지한다. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.