87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# Project Structure — Dashboard Persistent Authentication
|
|
|
|
## 목적과 범위
|
|
|
|
Issue #6의 signed persistent authentication을 기존 Dashboard page 구조와 분리하여 배치하는 규칙을 정의한다. DB schema와 MCP 구조는 변경하지 않는다.
|
|
|
|
## Source 영역
|
|
|
|
| 경로 | 책임 | 주요 공개 요소 | 금지 의존성 |
|
|
|---|---|---|---|
|
|
| `dashboard/server.py` | Streamlit ASGI app과 인증 route 조립 | `app` | DB/gateway 직접 접근 |
|
|
| `dashboard/auth_server.py` | same-origin login/logout HTTP response와 hardened cookie | `create_auth_routes()` | page view, SQLite |
|
|
| `dashboard/authentication.py` | 설정, credential 비교, token 발급·검증, Streamlit gate | `require_dashboard_authentication()` | 금융 DB/gateway |
|
|
| `dashboard/app.py` | gate 성공 후 기존 page dispatch | `main()` | token signing 세부 구현 |
|
|
| `dashboard/common.py` | 기존 DB/UI helper | 기존 API | 인증 결정 |
|
|
| `dashboard/page_views/` | 기존 금융 화면 | `page_*` | 인증 transport |
|
|
|
|
`dashboard.server:app`이 운영 진입점이다. 인증 endpoint는 Streamlit 1.58의 public ASGI `App(routes=...)` 확장 지점에 같은 process로 결합한다.
|
|
|
|
## Test 영역
|
|
|
|
| 경로 | 검증 책임 |
|
|
|---|---|
|
|
| `tests/test_dashboard_authentication.py` | 기존 credential 비교·지연·safe log |
|
|
| `tests/test_dashboard_persistent_authentication.py` | token claims, TTL, tamper, rotation, malformed input |
|
|
| `tests/test_dashboard_auth_server.py` | login/logout response, cookie 속성, same-origin, fail-closed |
|
|
| `tests/test_dashboard_authentication_app.py` | Streamlit gate, DB 이전 차단, cookie 복원·rotation |
|
|
| `tests/test_dashboard_app.py` | 인증 이후 기존 핵심 page regression |
|
|
| `scripts/persistent_auth_http_evidence.py` | 실제 loopback HTTPS cookie/reconnect/logout evidence |
|
|
|
|
Test는 synthetic DB와 test-only credential/secret만 사용하고 token·secret 원문을 출력하지 않는다.
|
|
|
|
## Config·배포·문서 영역
|
|
|
|
| 경로 | 책임 |
|
|
|---|---|
|
|
| `pyproject.toml`, `uv.lock` | `itsdangerous`, `starlette`, `uvicorn` 직접 dependency 고정 |
|
|
| `.env.example` | 세 environment 변수의 이름만 제공 |
|
|
| `docker-compose.yml` | signing secret 전달과 ASGI server command |
|
|
| `deploy/k8s/base/deployment.yaml` | Kubernetes Secret `signing-secret` 전달과 ASGI command |
|
|
| `README.md`, `deploy/k8s/README.md` | HTTPS, rotation, expiry, rate-limit, logout 제약 |
|
|
| `docs/requirements/req-001_dashboard-administrator-authentication.md` | Issue #1·#6 통합 canonical 승인 명세 |
|
|
| `docs/interface-contract.md` | HTTP/cookie/token 계약 |
|
|
| `docs/runtime-flow.md` | 발급·복원·실패·logout 순서 |
|
|
|
|
## 의존 방향
|
|
|
|
```text
|
|
browser
|
|
├─ POST /api/auth/login|logout → dashboard.auth_server
|
|
└─ Streamlit handshake cookie → dashboard.authentication
|
|
|
|
dashboard.server → dashboard.auth_server + Streamlit App(dashboard/app.py)
|
|
dashboard.app → dashboard.authentication → itsdangerous
|
|
→ (인증 성공 후) dashboard.common/page_views
|
|
```
|
|
|
|
`auth_server`와 `authentication`은 금융 DB를 import하지 않는다. Page module은 cookie와 token module을 직접 호출하지 않는다.
|
|
|
|
## 상태·데이터 배치
|
|
|
|
- Credential/signing secret: process environment에서 request/rerun 동안만 참조
|
|
- Auth token: browser의 `Secure`/`HttpOnly` cookie에만 저장
|
|
- Correlation ID: 비민감 값으로 `st.session_state`에 저장 가능
|
|
- 금융 데이터: 기존 SQLite
|
|
- Token registry/revocation table/migration: 생성하지 않음
|
|
|
|
따라서 `docs/data-model.md`는 추가하지 않는다.
|
|
|
|
## 변경 규칙
|
|
|
|
- 인증 환경변수는 `JARCA_DASHBOARD_` prefix를 사용한다.
|
|
- Cookie name은 host-only scope를 강제하는 `__Host-` prefix를 사용한다.
|
|
- Token schema/TTL/cookie attributes 변경은 REQ-001과 interface contract를 함께 변경한다.
|
|
- Secret, token, cookie header, credential 값을 source·fixture·log·문서에 기록하지 않는다.
|
|
- Streamlit private Tornado/WebSocket internals나 client-side cookie component를 사용하지 않는다.
|
|
|
|
## 검증
|
|
|
|
```text
|
|
uv run --extra dashboard --extra dev pytest
|
|
uv run --extra dashboard --extra dev ruff check dashboard tests scripts
|
|
uv run python -m compileall -q dashboard tests scripts
|
|
```
|
|
|
|
Diff에서 DB migration과 `docs/data-model.md`가 추가되지 않았는지 확인한다.
|