전체 문서
이 페이지 목차
HTTP API와 Web UI 계약
Go http.ServeMux가 /api/*를 등록하고 JWT/CORS middleware를 씌우며, 나머지 /는 embedded Next.js static UI를 제공한다. frontend client는 일반 fetch에 Bearer header를, native EventSource에는 query token을 사용한다. 서버의 extractToken은 HTTP method나 route를 구분하지 않아 보호 API 전반에서 query token도 fallback으로 수락한다. route 근거 client 근거
인증 계약
/api/auth/*와 /api/health는 공통 JWT middleware에서 면제된다. change-password는 경로가 면제되므로 handler 안에서 token과 기존 암호를 다시 확인한다. 나머지 256개 operation은 middleware가 JWT를 요구하며, change-password까지 합친 257개 operation에서 extractToken이 Bearer header → artex_token cookie → query token 순으로 값을 고른다. query fallback은 SSE에 제한되지 않는다. 발급 token은 HS256·7일 expiry·subject ARTEX지만, 검증 코드는 HMAC signing method 전체를 허용해 같은 key의 HS384/HS512도 수락하고 exp/sub/iss/aud를 필수 claim으로 요구하지 않는다. auth 근거
정적 UI 자체는 public이고 client-side auth route가 화면을 제어한다. 권한 경계는 API middleware다. token은 frontend에서 localStorage와 JavaScript가 쓰는 SameSite=Lax cookie에 기록된다. cookie에는 HttpOnly와 Secure가 없으므로 browser script에서 읽을 수 있고 HTTP에서도 전송될 수 있다. query token은 SSE 외의 보호 API에서도 유효하므로 URL·proxy/access log·browser history 노출 경계를 API 전체에 적용해야 한다. client 근거
Route family 지도
고정 source revision에는 method와 pattern 조합으로 구별한 HTTP operation이 261개 있다. 등록 형태는 literal 245개, finding traffic의 조합 등록 7개, side-question request ID를 포함한 동적 등록 9개다. method별로 GET 114, POST 85, DELETE 32, PUT 17, PATCH 13이다. 숫자는 http.ServeMux 등록을 정적으로 추출한 분모이며 실행 시 middleware나 handler가 성공한다는 뜻은 아니다. route source
| 독립 API 참조 | operation 수 | 다루는 영역 |
|---|---|---|
| 태스크·탐색 | 62 | task, goal, constraint, scope, archive, activity |
| Finding·traffic | 49 | finding CRUD, deepen/retest/export, evidence snapshot, traffic capture |
| Agent·tool·관리 | 82 | agent, tool, MCP, skill, asset/company, intercept, sync |
| 시스템·운영 | 68 | auth, health, settings, update, logs, chat, side question, notification |
각 operation의 path/query/header/body field, 직접 response/error variant, idempotency와 완료 경계는 요청·응답 semantic 참조가 소유한다. 27개 Next.js page subtree가 실제로 소비하는 wrapper/API/SSE/state/error 경로는 프런트엔드 소비 지도에서 역방향으로 찾는다.
아래 family 표는 탐색용 요약이다. 요청 field, 직접 status와 handler/source 위치는 위 독립 operation 참조가 소유한다.
| family | 대표 경로 | 주 상태 | 응답이 뜻하는 완료 |
|---|---|---|---|
| auth/health | /auth/*, /health |
settings/JWT key | 인증/상태 요청 처리 |
| tasks | /tasks, goals, constraints, scope, assets, control, LLM, intents |
task + exploration graph | 생성 201은 접수; engine 완료 아님 |
| archives | /task-archives, archive/restore/delete batch |
task_archives + package | queue 응답; background job 별도 |
| exploration | frontier, graph, nodes, activity, tokens | graph/activity | 현재 snapshot 또는 stream cursor |
| findings | list/group/tree/stats/export/detail/lineage/deepen/retest | graph node + standalone row | deepen/retest는 비동기 시작 상태 포함 |
| finding traffic | finding별 /traffic CRUD/order/body |
evidence snapshot/binding | POST는 snapshot+binding commit |
| traffic | /traffic, hosts, exchange, blob, delete |
SQLite/file capture | 요청한 capture 조회/삭제 |
| assets/companies/sync | asset CRUD, scope, ScopeSentry | global asset graph | import/upsert 완료 |
| agent resources | agents, tools, MCP, skills, visibility, triggers | PG config + skill FS | 설정 저장; in-flight run 교체 보장 아님 |
| intercept | rules, pending, history, tool config, judge | intercept tables/settings | decision 저장 및 대기 work 해제 |
| chat/conversation | chat, upload, conversation messages, side questions | conversation/activity/transcript | streaming/run과 HTTP accept 구분 |
| settings/ops | settings, logs, update, notify, gc, report | settings/log/update state | update apply는 202 후 restart path |
태스크 계약과 완료 경계
POST /api/tasks는 DB transaction으로 task initial state를 만든 뒤 launchTask를 호출하고 201을 즉시 반환한다. goal decomposition, admission, planner/worker 실행은 그 뒤 background 흐름이다. seed_first_intent=true이면 첫 planner round 전에 worker가 seed intent를 claim할 수 있다. 접수 근거 task DB 근거
Task 응답은 DB row의 단순 직렬화가 아니다. DTO는 persistent lifecycle과 메모리 engine의 paused/running/last-activity/in-flight/LLM readiness를 섞어 derived status를 만든다. 재시작·장애 순간에는 저장 상태와 화면 상태가 다른 층임을 고려한다. DTO 근거
| 조작 | 주요 결과 | 후속 확인 |
|---|---|---|
| pause/resume/control | engine context와 task lifecycle 변경 | task detail/status + activity |
| goal add/edit | terminal task를 다시 활성화할 수 있고 planner trigger 발생 | goal state와 새 round |
| constraint add/edit | 다음 prompt 주입 데이터 변경 | 새 run부터의 activity; 모든 outbound 강제는 아님 |
| intent message | paused intent의 detached run 또는 active work message | intent state + activity |
| rerun | blocked/exhausted/stopped를 frontier로 돌림 | open/running CAS |
| archive | persistent archive job queue | archive state/phase/progress |
History와 SSE
UI session tab은 먼저 history page를 읽어 snapshot cursor를 확보하고 /api/exploration/activity/stream?task=...&since=...를 연결한다. server는 subscribe-before-replay로 live gap을 줄이고 DB backlog를 batch로 보낸 뒤 live broadcaster를 따른다. Last-Event-ID로 reconnect하면 persisted gap을 다시 읽는다. stream 근거 UI client 근거
| stream | persistence/cursor | 비고 |
|---|---|---|
| exploration activity | PostgreSQL activity id | reconnect replay 가능, 20초 ping |
| logs | ring/live + 별도 DB history | activity cursor와 별개 |
| update | in-memory current progress | 프로세스 restart 중 연결 단절 예상, UI가 health polling |
| side question | request event stream | 해당 request lifecycle 범위 |
등록된 SSE operation은 /api/exploration/activity/stream, /api/logs/stream, /api/update/stream, /api/side-questions/{requestID}/events 네 개다. frontend는 네 경로를 모두 EventSource로 소비하며 이 client 제약 때문에 query token을 실제로 사용한다. 서버가 query token을 SSE로 제한하지 않는 별도 경계는 인증 계약을 본다. UI client Side question UI
SSE event 도착은 task success를 뜻하지 않는다. task lifecycle, goal, intent terminal state를 별도로 읽어야 한다.
Finding·evidence 계약
Finding list 응답 shape는 query에 따라 다를 수 있다. task 없이 legacy/non-paged 조회는 제한된 array, paging/filter를 쓰면 page object, task context에서는 local graph와 direct-source readonly 결과를 조합한다. client wrapper와 backend handler를 함께 봐야 한다. route 근거 client 근거
PATCH /api/exploration/findings/{id}의 status, severity, name, vulnclass 갱신은 단일 요청 전체가 하나의 transaction인 구조가 아니고 graph mirror가 best-effort인 경로가 있다. 중간 실패 시 앞선 field가 남을 수 있다. DELETE는 evidence mutation lock 아래 standalone row와 graph node/evidence를 정리한다. finding handler 근거
Finding traffic POST는 선택한 live traffic을 읽어 body를 hash/copy하고 snapshot과 ordered binding을 commit한다. 수정·순서 변경·삭제는 evidence_version optimistic concurrency를 사용하며 stale version은 409다. detail은 제한된 preview, body endpoint는 page/stream 경로를 제공한다. traffic handler 근거 증거 계약
deepen은 후속 고우선 intent를 queue하고 응답한다. retest는 별도 conversation/agent를 시작한다. 둘 다 HTTP 200/생성 응답을 실제 보안 검증 완료와 동일시하면 안 된다.
Traffic API
GET /traffic은 SQLite index의 page와 count를 가볍게 반환하고, 전체 request/response는 /traffic/exchange, 큰 body는 /traffic/blob에서 지연 로드한다. host 단일 삭제 query와 exact host batch 삭제는 의미가 다르며 /traffic/all은 capture를 비우고 index를 compact한다. 이미 finding에 bind된 evidence snapshot은 별도 저장이므로 capture 삭제와 동일하지 않다. traffic 근거
UI에서 코드로 가는 지도
| UI 경로 | 사용자 기능 | API/상태 문서 |
|---|---|---|
/function/tasks |
생성·제어·archive·restore·category | 태스크 계약 |
/function/tasks/detail |
overview, goals, constraints, scope, assets, sessions, findings | 탐색 루프 |
/function/findings / detail |
finding triage, traffic evidence, retest, deepen, export | finding 계약 |
/function/traffic |
capture 검색·상세·삭제 | traffic 계약 |
/function/assets |
asset graph·company scope | asset/scope |
/function/sync |
ScopeSentry datasource와 project/task asset import | 보조 루프 |
/system/agents |
agent config, prompt version, wrapup, trigger, visibility | runtime 조립 |
/system/tools, /system/mcp, /system/skills |
실행 능력 catalog/연결 | tool 조립 |
/system/intercept |
rule, asset block/allow, pending approval, judge | 보안 경계 |
/system/llm, /system/settings |
provider, retry, worker, proxy, capture, update | 운영 |
/system/logs, /system/notify |
관찰·delivery | 운영 점검 |
페이지 목록은 Next App Router tree에서, 실제 client method/shape는 web/src/lib/api.ts, frontend types는 web/src/lib/types.ts에서 확인된다. 위 표에 빠진 /function/commands, /function/llm-records, /function/workspace, /system/agents/detail, /system/intercept/approvals, /system/intercept/assets를 포함한 27/27 entry의 정확한 소비 관계는 화면별 계약이 소유한다. UI tree 근거 client 근거
계약을 사용할 때 주의할 점
- background 작업의 accept response와 완료 상태를 분리한다: task 201, archive queue, deepen, retest, update 202가 대표적이다.
- UI type만 권위 계약으로 쓰지 않는다. backend가 query mode에 따라 응답 shape를 바꾸는 endpoint가 있다.
- query token은 browser
EventSource를 지원하지만 서버에서 257개 operation에 유효하므로 URL 취급·access-log redaction 정책이 필요하다. - CORS middleware는
Access-Control-Allow-Origin: *와Content-Typeheader만 선언한다. cross-origin Authorization preflight가 실제로 작동하는지는 실행 검증이 필요하다. same-origin 배포 경로와 혼동하지 않는다. route 근거 - 설정/metadata API 일부는 request-wide transaction이 아니다. 자동화 client는 read-after-write와 부분 성공 처리를 고려한다.
API 분모와 확인 한계
| 분모 | 확인 | 한계 |
|---|---|---|
| 등록 operation | 261/261 | method+pattern+handler의 정적 등록 전수; runtime 호출 미실행 |
| operation 직접 목적지 | 261/261 | 네 API 참조에 안정 anchor 제공 |
| 요청 wire shape | 261/261 located | JSON request field 97, multipart 3, 직접 decoder/form read 미발견 161; shared handler의 method branch를 분리한 수이며 helper validation은 P |
| handler query key | 169 operation-key pair | direct/alias + 확인한 helper 47개; common auth query token은 별도 257-operation 계약 |
| JSON body field requiredness | 369 field | required 54 / group 15 / conditional 1 / optional 11 / direct provided-validation 69 / default·normalization 14 / U 205; U를 완료로 세지 않음 |
| 요청 body cap | 28/28 applicable operation | 16 KiB–512 MiB의 exact cap과 overflow status/body를 operation schema에 기록 |
| 직접 response schema | 36 C / 225 P / 0 U | C는 primitive/static field type까지 확인; derived/helper/opaque/nested/stream/file shape는 P; operation 전체 semantic 완료율과 별도 |
| 프런트엔드 page entry | 27/27 | static local import graph; runtime branch는 A |
| SSE frontend 소비 | 4/4 endpoint | EventSource call site 5개(두 화면이 side-question hook 공유) |
| OpenAPI/JSON Schema | 없음 | 문서 schema는 handler AST의 관찰이며 별도 versioned spec은 아님 |
| live HTTP 검증 | 미실행 | auth, status, payload, background completion은 배포 환경 대조 필요 |