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 순서

의존 방향

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를 사용하지 않는다.

검증

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가 추가되지 않았는지 확인한다.

4.3 KiB Raw Blame History