74 lines
6.0 KiB
Markdown
74 lines
6.0 KiB
Markdown
# Gitea authenticated access 운영 지침
|
|
|
|
이 문서는 Gitea Agent harness가 Gitea의 authoritative state를 읽고 승인된 mutation을 수행할 때 사용하는 canonical access 계약이다. 모든 agent와 skill은 특정 transport를 정본으로 취급하지 않고, 이 문서의 identity·credential·readback 조건을 충족하는 authenticated API adapter를 사용한다.
|
|
|
|
## 고정 origin과 transport
|
|
|
|
- 허용된 Gitea origin은 exact `https://gitea.jsfamily.quest`다.
|
|
- Authenticated API adapter는 전용 Gitea MCP connection 또는 release/spec/impl 등 현재 role의 credential을 사용하는 직접 Gitea REST client일 수 있다.
|
|
- MCP method 이름, REST client 구현과 command 성공은 정본이 아니다. 위 origin이 반환한 authenticated response와 fresh readback이 정본이다.
|
|
- 다른 origin, mirror API, public web page, unauthenticated response 또는 다른 role의 adapter로 fallback하지 않는다.
|
|
- Redirect는 자동 추적하지 않는다. 특히 credential을 다른 origin에 전달하지 않는다.
|
|
|
|
## Identity gate
|
|
|
|
1. 모든 workflow는 첫 authoritative read 전에 authenticated adapter로 현재 사용자를 읽는다. REST adapter는 exact `GET /api/v1/user`를 사용한다.
|
|
2. Stable numeric account ID, login과 현재 workflow role을 기록한다. Transport에 따라 login 표시가 달라도 stable account ID가 같으면 같은 identity다.
|
|
3. 예상 role identity를 확인할 수 없거나 API가 `401`, `403`, redirect, malformed response 또는 anonymous identity를 반환하면 fail-closed한다.
|
|
4. Workflow 동안 adapter와 credential source를 바꾸지 않는다. 재인증이 필요하면 현재 operation을 중단하고 snapshot부터 다시 시작한다.
|
|
|
|
## 직접 REST adapter
|
|
|
|
- Base URL은 exact `https://gitea.jsfamily.quest/api/v1`로 고정하고 TLS certificate 검증을 끄지 않는다.
|
|
- Token은 현재 role profile의 exact `$HERMES_HOME/.env`에 `GITEA_TOKEN`으로 저장하고 해당 파일의 mode를 `0600`으로 유지한다. Named profile에서는 `$HERMES_HOME`이 `~/.hermes/profiles/<profile>`이므로 같은 변수 이름을 사용해도 role별 token이 격리된다. 승인된 external secret manager를 사용하면 같은 profile scope에 `GITEA_TOKEN`으로 주입한다. 다른 profile, inherited ambient token, interactive prompt 또는 public access로 fallback하지 않는다.
|
|
- Token을 URL, command argv, Git config, remote URL, log, exception text, state, artifact 또는 repository file에 기록하지 않는다.
|
|
- Client는 token을 process 내부에서 읽어 `Authorization` header에 넣거나 보호된 file descriptor·stdin과 동등한 mechanism으로 전달한다. Secret이 shell expansion 후 argv에 나타나는 호출은 금지한다.
|
|
- Response status와 JSON shape를 검증한다. Collection endpoint는 Gitea pagination metadata에 따라 마지막 page까지 읽고 cardinality를 기록한다.
|
|
- `429`와 일시 오류는 read operation에서만 bounded retry할 수 있다. Mutation timeout·오류는 blind retry하지 않고 authoritative reconciliation을 먼저 수행한다.
|
|
|
|
## Repository와 Git
|
|
|
|
- Repository metadata, default branch와 branch full SHA는 authenticated adapter로 exact target에서 읽는다.
|
|
- Git clone/fetch/push credential은 API token을 credential-bearing URL에 넣지 않고 short-lived askpass 또는 동등한 child-process mechanism으로 전달한다.
|
|
- Git command 성공만으로 remote state를 확정하지 않는다. Fetch 후 default-branch ref를 API SHA와 비교하고, push 후 exact remote ref를 authenticated adapter로 다시 읽는다.
|
|
|
|
## Mutation과 readback
|
|
|
|
- Direct REST와 MCP에 동일한 승인 gate, exact payload, idempotency, drift 검사와 readback 규칙을 적용한다.
|
|
- Mutation 직전에 target identity, approval snapshot과 baseline을 다시 읽는다.
|
|
- 승인된 exact endpoint와 payload만 한 번 호출한다. Unstated default field에 의존하지 않는다.
|
|
- 성공 response만으로 완료를 주장하지 않는다. Exact target을 fresh readback하고 author stable account ID, payload, timestamp, commit/ref와 collection cardinality를 baseline과 비교한다.
|
|
- Timeout, malformed response 또는 connection loss 뒤에는 같은 mutation을 재호출하기 전에 complete collection을 한 번 읽어 결과를 reconciliation한다. 결과가 없거나 여러 개이거나 경쟁 mutation과 구분할 수 없으면 uncertain/partial로 중단한다.
|
|
|
|
## Credential 안전
|
|
|
|
- Credential 값은 role profile의 secret store에만 저장하고 repository, harness 문서와 workflow artifact에는 저장하지 않는다.
|
|
- Child process에 credential이 필요하면 최소 범위 environment 또는 보호된 descriptor로 전달하고 종료 시 helper와 temporary file을 제거한다.
|
|
- Credential의 존재 여부, source와 cleanup 결과만 보고하며 값을 출력하지 않는다.
|
|
- Read-only 단계에는 필요한 최소 scope를, tag push·review·Issue mutation에는 승인된 작업에 필요한 scope만 사용한다.
|
|
|
|
## Fail-closed 조건
|
|
|
|
다음 중 하나라도 발생하면 authenticated operation을 완료로 보고하지 않는다.
|
|
|
|
- 허용 origin 또는 target repository 불일치
|
|
- Authenticated stable account identity 확인 실패
|
|
- Role credential source 불명확 또는 다른 role credential 사용
|
|
- Redirect, TLS 검증 실패, `401`, `403` 또는 malformed API response
|
|
- Pagination 미완료 또는 baseline cardinality 불명확
|
|
- Mutation 결과와 fresh readback 불일치
|
|
- Credential 노출 또는 helper cleanup 결과 불확실
|
|
|
|
## 보고
|
|
|
|
완료 보고에는 adapter 종류 자체보다 다음 검증 결과를 포함한다.
|
|
|
|
- exact Gitea origin
|
|
- authenticated stable account ID와 login
|
|
- exact repository와 authoritative default branch full SHA
|
|
- 사용한 transport 종류와 role credential source의 이름만 표시한 provenance
|
|
- 수행한 mutation의 exact target과 fresh readback 결과
|
|
- pagination, drift, reconciliation과 partial/fail-closed 상태
|
|
|
|
Token 값, authorization header와 credential-bearing URL은 보고하지 않는다.
|