50_client.md

50. Client — 북마크릿·실행기·타겟 등록

책임: 타겟 페이지에 주입되어 서버 명령을 받아 실행하고 결과를 무손실 전송한다. 모듈: src/arachne/client/{bookmarklet.js, executor.js, install.html} + 타겟 등록(settings.TARGETS)

⚠️ v1(현 구현, 아래) = payload.script eval. v2 목표 = 커맨드 인터프리터(specs/16) — 클라는 TS 인터프리터(ES2017), 서버가 타입 커맨드로 통일 제어. 북마크릿은 기본적으로 v1·v2 동일(순수 로더, <script src>만) — 단 v2엔 D-csp-script-src 대응용 두 번째 형태(인라인, 로더 전체를 본문에 직접 임베딩 — 더 이상 "순수"가 아님)가 추가됐다(docs/00_ARCHITECTURE.md D-csp-script-src, specs/15 §4).

---

타겟 등록 Contract (settings.TARGETS)

JSON(환경변수 TARGETS 또는 .env). 1차 무UI — 정적 등록:

{ "example.com": { "version": 3, "script": "return {title: document.title}", "actions": [{"type":"scroll","args":{"to":"bottom"}}] } }

• 실타겟 예시(m.news.nate.com 최신뉴스)는 tests/e2e의 라이브 테스트(-m live) 참조.

북마크릿 (로더, 로직 0 — op 토큰만 박힘)

javascript:(function(){var s=document.createElement('script');
 s.src='https://<server>/agent/loader.js?op=op_a1b2c3...';document.body.appendChild(s);})();

• 설치본별로 op 토큰이 박힌 북마크릿(서버 발급, specs/15 §1). 어느 도메인서 실행해도 같은 op → 도메인 넘는 통합.
• loader.js 동작(specs/15 §4): client_id 확보(localStorage 랜덤·GA식, 지문 미사용) → POST /agent/register(op+client) → GET /agent/payload → actions/script → collect. 모든 collect 봉투에 op_id·client_id·task_id 동봉(매개).

실행기 (executor) — 무손실 + 2단계

window._aaq = window._aaq || [];          // Matomo _paq 패턴: 로드 전 버퍼링(유실 0)
// 1) actions 수행 → flush #1
for (const a of payload.actions) await runAction(a);
_aaq.push(['collect', {stage:'action', data: collectedSoFar}]);
// 2) script 실행 → flush #2
const result = await new Function('return (async()=>{'+payload.script+'})()')();
_aaq.push(['collect', {stage:'script', data: result}]);

• 실행 순서 불변: action → collect → script → collect (00_ARCHITECTURE §4.3).
• runAction 화이트리스트: scroll·click·wait·swipe(m.nate.com 랭킹 본문 스와이프, docs/80 GT-real에서 요구). swipe={args:{to,times}} — 터치 스와이프(픽스처에선 scroll로 동등 처리). 그 외 동작은 2차 확장.

CSP 무력화 전송

• 명령 수신: <script src="/agent/payload.js?..."> → _aaq.push(['payload',{...}]).
• 결과 전송: fetch PUT /api/v1/collect; 차단 시 폴백 new Image().src="/api/v1/collect.json?envelope=<urlenc>".
• 한계(이슈): GET 비콘 URL 길이 → 대용량은 청크/압축(검증 어려우면 BLOCKER 기록 후 진행).

v2 인터프리터 보안 가드 (★ 전수 리뷰 반영 — 상세 specs/16 §8)

v2 loader.v2.js(ts/loader.ts 단일 소스)는 신뢰 경계(컨트롤 서버 응답)를 하드닝한다.

• script opt-in(D-script-optin): new Function eval은 기본 차단, 로더 src ?allowScript=1에서만.
• beacon 오리진 제한(D-beacon-origin): 송출 대상은 SERVER_ORIGIN만(임의 exfil 차단).
• 난수 crypto(D-client-crypto): client_id·task_id·JSONP 콜백명 crypto.getRandomValues 우선.
• 중복 주입 가드: 자가 commands.js 로드·폴링 부작용은 1회만(__arachneV2Loaded).
• op 보간 새니타이즈(D-op-sanitize): v1 /agent/loader.js?op=는 서버가 op를 화이트리스트 정규화 후 본문 삽입(specs/15) — 반사형 인젝션 차단.
• iframe 페이지 제어(D-frame, v1.1.0): frame_extract/frame_tour는 같은 출처 상세만 iframe 로드(cross-origin 클라 즉시 거부 + 서버 422). extractItems를 iframe contentDocument root로 재사용. 최상위 문서 불변 → 로더/세션 비단절 (specs/22).

install.html (무UI 원칙)

• 최소 정적: 북마크릿 드래그 안내 한 페이지. ❌ 디자인 시스템·프리미엄 UI 금지(골드플레이팅).

Negative (하지 말 것)

• ❌ 북마크릿에 수집 로직 하드코딩(서버 동적 발행 원칙).
• ❌ runAction 화이트리스트 밖 임의 동작.
• ❌ install.html 과잉 디자인.

Golden Test 매핑

• GT-client: executor 2단계 flush 순서·_aaq 버퍼링(jsdom 또는 E2E). 전체 합류는 docs/80 GT-E2E.

클라이언트 E2E는 Phase 2(Playwright). 1차는 서버측 시드(GT-seed)로 합류 증명.