jarca-ledger-mcp/docs/interface-contract.md

Interface Contract — Dashboard 관리자 인증

목적과 범위

Dashboard 인증 설정, login/cleanup/logout HTTP route, signed cookie와 Streamlit gate의 외부·내부 계약을 정의한다.

• 포함 범위: 환경변수, HTTPS form POST, cookie 발급·삭제, fail-closed gate
• 제외 범위: MCP 인증, OAuth/OIDC, 다중 사용자, DB session/token registry, per-token revocation
• 사용 주체: browser, Dashboard ASGI server, Streamlit app, 운영 배포

계약

auth-config — 서버 인증 설정

• 책임: 현재 configured credential과 signing secret을 server-only로 제공한다.
• 종류·프로토콜: process environment
• 호출 대상·operation: load_auth_settings()
• 버전: 2.0
• 호출 주체: Dashboard server
• 인증 방식: 없음
• 필요 권한: process secret read

입력

필드	위치	타입	필수 여부	기본값	허용 값·형식	의미	민감정보
JARCA_DASHBOARD_ADMIN_ID	environment	string	필수	없음	non-empty	configured admin identifier	민감
JARCA_DASHBOARD_ADMIN_PASSWORD	environment	string	필수	없음	non-empty	configured credential	민감
JARCA_DASHBOARD_SIGNING_SECRET	environment	string	필수	없음	UTF-8 32 byte 이상	signing input	민감

출력

필드	위치	타입	필수 여부	허용 값·형식	의미	민감정보
AuthSettings	server memory	object	성공 시 필수	current configured values	verifier input; never serialized	민감

오류

코드	분류	발생 조건	재시도 가능 여부	호출자 대응	실패 시 상태 변경
configuration_unavailable	configuration	missing/empty/read error/short secret	수정 후 가능	generic unavailable	no cookie, no DB

login — POST /api/auth/login

• 책임: same-origin HTTPS credential을 검증하고 signed cookie를 발급한다.
• 종류·프로토콜: HTTPS form POST
• 호출 대상·operation: /api/auth/login
• 버전: 1.0
• 호출 주체: browser login form
• 인증 방식: submitted credential, server-only comparison
• 필요 권한: same-origin HTTPS

입력

필드	위치	타입	필수 여부	기본값	허용 값·형식	의미	민감정보
admin_id	form body	string	필수	없음	bounded form value	submitted ID	민감
admin_password	form body	string	필수	없음	bounded form value	submitted password	민감
remember_me	form body	string	선택	off	on or absent	choose 30-day TTL	비민감
Origin	request header	URL	필수	없음	request Host와 scheme·hostname·effective port가 같은 HTTPS origin	CSRF origin 검증	비민감

출력

필드	위치	타입	필수 여부	허용 값·형식	의미	민감정보
Set-Cookie	response header	cookie	success	hardened auth cookie, redacted value	persistent auth	값은 민감
Location	response header	string	success/failure	/ or generic error path	browser navigation	비민감

발급 token은 v, sub=dashboard-admin, iat, exp, jti claim만 가진다. sub=dashboard-admin은 관리자 ID가 아닌 고정 비민감 role이고, token 값과 서명은 민감하므로 browser의 hardened cookie에만 저장한다. 성공한 login 시각에 iat와 exp를 한 번 고정하며 기본 TTL은 24시간, remember_me=on이면 30일이다. 활동, 일반 요청, rerun 또는 인증 복원은 token을 재발급하거나 두 시각을 연장하지 않는다.

오류

코드	분류	발생 조건	재시도 가능 여부	호출자 대응	실패 시 상태 변경
400	request	malformed/oversized body	수정 후 가능	resubmit valid form	no cookie
403	origin	non-HTTPS or cross-origin	수정 후 가능	use same-origin HTTPS	no cookie
invalid	authentication	ID/password mismatch	가능	generic error and delay	no cookie
unavailable	configuration	invalid server configuration	config fix 후	generic unavailable	no cookie

cleanup — GET /api/auth/cleanup

• 책임: invalid cookie를 matching scope로 삭제한 뒤 unauthenticated navigation을 완료한다.
• 종류·프로토콜: HTTPS navigation GET
• 호출 대상·operation: /api/auth/cleanup
• 버전: 1.0
• 호출 주체: same-origin browser/auth gate
• 인증 방식: same-origin HTTPS Referer; token validity 불필요
• 필요 권한: same-origin HTTPS

입력

필드	위치	타입	필수 여부	기본값	허용 값·형식	의미	민감정보
Referer	request header	URL	필수	없음	request origin과 같은 HTTPS authority	navigation origin 검증	비민감

출력

필드	위치	타입	필수 여부	허용 값·형식	의미	민감정보
Set-Cookie	response header	cookie	always	same name/path/security, Max-Age=0	delete stale cookie	값은 민감
Location	response header	string	success	/	unauthenticated page	비민감

오류

코드	분류	발생 조건	재시도 가능 여부	호출자 대응	실패 시 상태 변경
403	origin	non-HTTPS/cross-origin	가능	retry same-origin	no DB

logout — POST /api/auth/logout

• 책임: explicit logout으로 browser cookie를 삭제한다.
• 종류·프로토콜: HTTPS form POST
• 호출 대상·operation: /api/auth/logout
• 버전: 1.0
• 호출 주체: authenticated browser
• 인증 방식: same-origin HTTPS; server-side revocation 없음
• 필요 권한: same-origin HTTPS

입력

필드	위치	타입	필수 여부	기본값	허용 값·형식	의미	민감정보
none	none	none	선택	없음	no credential accepted	explicit logout	없음
Origin	request header	URL	필수	없음	request Host와 scheme·hostname·effective port가 같은 HTTPS origin	CSRF origin 검증	비민감

출력

필드	위치	타입	필수 여부	허용 값·형식	의미	민감정보
Set-Cookie	response header	cookie	always	matching deletion, Max-Age=0	remove browser cookie	값은 민감
Location	response header	string	success	/	unauthenticated page	비민감

오류

코드	분류	발생 조건	재시도 가능 여부	호출자 대응	실패 시 상태 변경
403	origin	non-HTTPS/cross-origin	가능	retry same-origin	no DB

gate — Dashboard 인증 경계

• 책임: config and cookie verification before any protected work.
• 종류·프로토콜: Python/Streamlit call
• 호출 대상·operation: require_dashboard_authentication()
• 버전: 2.0
• 호출 주체: dashboard.app.main()
• 인증 방식: current config plus signed cookie
• 필요 권한: valid token with sub=dashboard-admin

입력

필드	위치	타입	필수 여부	기본값	허용 값·형식	의미	민감정보
auth_cookie	request cookie	string	success path	absent	current configuration으로 서명을 검증할 수 있고 claim이 정확히 v, sub=dashboard-admin, iat, exp, jti인 token	browser proof	값과 서명은 민감; sub는 비민감

출력

필드	위치	타입	필수 여부	허용 값·형식	의미	민감정보
authenticated	server result	bool	always	true/false	gate decision	비민감

오류

코드	분류	발생 조건	재시도 가능 여부	호출자 대응	실패 시 상태 변경
unauthenticated	authentication	absent/invalid/expired/config failure	login 가능	cleanup then show login	no protected work

관리자 ID, password 또는 signing secret 변경은 server-only signing key binding을 바꾸므로 기존 token을 모두 무효화하고 cleanup으로 전이한다. DB session, token registry와 per-token revocation은 만들지 않는다.

호환성

• 유지할 기존 호출 방식: authenticated page query parameter, page dispatch, gateway와 MCP behavior
• 버전 변경 정책: REQ-001 revision 2.0; session-only boolean을 signed cookie로 대체
• 폐기 정책: client-side token storage, DB-backed session, per-token revocation 없음
• 재시도 계약: credential 실패는 최소 1초 지연; origin/request 오류는 수정 후 재시도
• 중복 처리 계약: login은 새 token 발급 가능; cleanup/logout deletion은 idempotent
• 순서 보장: config → cookie verify → cleanup if invalid → DB/page dispatch only if valid
• 만료 보장: login 성공 시 고정한 iat와 exp는 활동·일반 요청·rerun·복원에서 변경하거나 연장하지 않음

예시

example-login — 정상 login

• 대상 인터페이스: login

호출

POST /api/auth/login
Origin: https://dashboard.example
admin_id=<submitted>&admin_password=<submitted>&remember_me=on

결과

303 Location: /
Set-Cookie: __Host-jarca_dashboard_auth=<redacted>; Secure; HttpOnly; SameSite=Lax; Path=/; Max-Age=2592000

example-cleanup — invalid cookie cleanup

• 대상 인터페이스: cleanup

호출

GET /api/auth/cleanup
Referer: https://dashboard.example/

결과

303 Location: /
Set-Cookie: __Host-jarca_dashboard_auth=; Max-Age=0; Secure; HttpOnly; SameSite=Lax; Path=/

검증

• 정상 계약: authentication/server tests와 loopback HTTPS evidence
• 실패 계약: wrong credential, invalid configuration, cross-origin, malformed cookie tests
• 경계 계약: expiry, rotation, oversized token, same-host different-port origin tests
• 구현·스키마·예시 정합성: tests/test_dashboard_auth_server.py, tests/test_dashboard_authentication_app.py, tests/test_dashboard_persistent_authentication.py, source/document redaction search