Trace API

POST /panopticon/trace — RP가 도구 호출 결과를 logi 판옵티콘에 보고합니다.

인증

판옵티콘은 **별도 자격증명(Panopticon PAK)**을 사용합니다. 사용자 OAuth 토큰(JWT)을 텔레메트리에 재사용하지 않아 audience 혼동을 방지합니다.

Simple mode (기본) ✓ 구현 완료

http

Authorization: Bearer pano_pak_...

PAK 해시 일치만 검증합니다. 모든 application의 기본값. (PakAuthenticator#authenticate! 참조 — panopticon_pak_secret_encrypted 컬럼 기반.)

HMAC strict mode 🔬 (roadmap)

미구현 — 설계 사양

이 섹션이 다루는 require_trace_hmac 플래그, pak_secret 발급, X-Panopticon-Signature / X-Panopticon-Timestamp 헤더 검증은 현재 코드베이스에 없습니다 (2026-05-15 audit). OauthApplication 모델에 해당 컬럼/메서드가 없고, Panopticon::TracesController 에 HMAC 분기 / 타임스탬프 tolerance 검증이 없습니다.

본문 서명 위·변조 방어를 원하면 PAK 회전 + HTTPS pinning + RP-side 로컬 buffer hash 로 우회하세요. HMAC strict mode 구현은 GitHub issues 에서 추적합니다.

application의 require_trace_hmac 플래그가 켜진 경우, 추가 헤더 필수 (계획):

http

Authorization: Bearer pano_pak_...
X-Panopticon-Signature: <hex(HMAC-SHA256("<timestamp>.<body>", pak_secret))>
X-Panopticon-Timestamp: <unix epoch seconds>

Canonical string은 "<timestamp>.<body>" (timestamp + dot + raw body). 검증:

X-Panopticon-Timestamp 와 서버 시간 차이 ≤ ±5분
HMAC-SHA256("<timestamp>.<body>", pak_secret)이 서명과 일치

샘플(Node.js):

import crypto from "node:crypto";
const ts = Math.floor(Date.now() / 1000);
const body = JSON.stringify(payload);
const sig = crypto
  .createHmac("sha256", PAK_SECRET)
  .update(`${ts}.${body}`)
  .digest("hex");
fetch("https://api.1pass.dev/panopticon/trace", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${PANOPTICON_PAK}`,
    "X-Panopticon-Signature": sig,
    "X-Panopticon-Timestamp": String(ts),
    "Content-Type": "application/json",
  },
  body,
});

페이로드 schema

jsonc

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000", // REQUIRED, RP 생성 UUID v4
  "client_id": "logi_f31b6962aef3",                    // REQUIRED, 검증용 (PAK와 일치해야 함)
  "tool": "memorize_fact",                             // REQUIRED, 호출된 도구 이름
  "scope_used": "agent:memory.write",                  // RECOMMENDED, JWT scope claim에서 사용한 값
  "status": "ok",                                      // REQUIRED, ok | error | denied | hitl_pending
  "started_at": "2026-05-09T10:11:12Z",                // REQUIRED, ISO 8601 UTC
  "duration_ms": 42,                                   // OPTIONAL, 도구 실행 시간
  "error_code": null,                                  // status=error 시 RECOMMENDED
  "user_sub": "user_xyz",                              // OPTIONAL, RP 자기보고 — logi는 검증 안 함
  "metadata": {                                        // OPTIONAL, jsonb 자유 필드 (PII 금지)
    "model": "claude-sonnet-4-6",
    "session_id": "..."
  }
}

필드 제약

필드	타입	검증
`event_id`	UUID v4 string	RFC 4122 형식 일치, application 단위 unique
`client_id`	string	PAK가 발급된 application의 client_id와 일치 (불일치 시 400)
`tool`	string	1~128자, 영숫자·`._-:`
`scope_used`	string	OauthScope NAME_PATTERN 매칭 (없으면 logged but not enforced)
`status`	enum string	`ok` / `error` / `denied` / `hitl_pending` 중 1개
`started_at`	ISO 8601 UTC	현재 시각 ±1시간 이내 (clock skew tolerance)
`duration_ms`	integer ≥ 0	최대 600000 (10분)
`metadata`	jsonb	16KB 이하, PII 포함 금지 (RP 책임)

응답

정상

HTTP	상황	Body
202 Accepted	신규 적재 성공	`{"event_id":"...","status":"accepted"}`
200 OK	동일 (`app`, `event_id`) 중복 — 무시됨	`{"event_id":"...","status":"duplicate"}`

에러

HTTP	error code	의미
400	`invalid_payload`	필수 필드 누락 / 형식 불일치
400	`client_id_mismatch`	body `client_id` ≠ PAK 소유 application
401	`invalid_pak`	PAK 서명/해시 불일치 또는 회전됨
401	`invalid_signature`	HMAC strict mode인데 서명 누락/불일치
401	`expired_timestamp`	HMAC strict mode인데 타임스탬프 ±5분 벗어남
403	`panopticon_disabled`	application의 Panopticon이 비활성
429	`rate_limited`	per-PAK throttle 초과 (기본 1000/min)
503	`service_unavailable`	logi 측 일시적 장애 — RP는 로컬 buffer 후 재전송 권장

에러 응답 형식:

json

{
  "error": "invalid_payload",
  "error_description": "event_id is missing",
  "documentation_url": "https://docs.1pass.dev/panopticon/trace-api"
}

Rate limit

기본: 1000 trace/분, PAK당 (rack-attack throttle).
application별 override: OauthApplication#trace_rate_limit_override 🔬 — 설계 사양, 현재 컬럼 없음 (2026-05-15). 모든 application 이 동일 기본값을 공유합니다.
초과 시 429 + Retry-After 헤더.
베타에서는 quota enforcement 없음 — rate limit은 1초 단위 throttle만, 월 한도는 표시만 됨.

멱등성과 재전송

logi 다운 또는 네트워크 오류 시 RP는 trace를 로컬 buffer에 쌓아두고 복구 후 같은 event_id로 재전송하세요. 서버는:

동일 (oauth_application_id, event_id) 발견 시 200 OK + status:"duplicate"
사용량 집계에 중복 카운팅 없음

user_sub 신뢰 모델 한계

user_sub는 RP 자기보고 필드입니다. logi는 이 값을 PAK 검증 외에 별도로 검증하지 않습니다. 잘못된 값이 들어오면:

Panopticon 콘솔 user 필터가 부정확해짐
HITL 승인이 잘못된 user에게 전달될 수 있음

→ RP는 user_sub를 자기 데이터베이스의 검증된 사용자 식별자로만 채워야 합니다.

페이로드 위·변조 방지

HMAC mode: 본문 위·변조 방어 — 🔬 설계 단계 (위 HMAC strict mode roadmap 참조). 현재는 TLS + PAK 회전 + RP-side 로컬 hash 로 우회.
PAK 회전 ✓ 구현 완료: 노출 의심 시 콘솔에서 즉시 회전. 회전 후 기존 PAK은 무효 (panopticon_pak_secret_encrypted 컬럼 갱신).
PII 마스킹: metadata에 사용자 입력 원본을 그대로 넣지 말고 요약·해싱 권장 (RP 책임 — logi 서버는 검증하지 않음).

정책 설정 — Trace 데이터 위에 올라가는 AI Guard 정책

Trace API ​

인증 ​

Simple mode (기본) ✓ 구현 완료 ​

HMAC strict mode 🔬 (roadmap) ​

페이로드 schema ​

필드 제약 ​

응답 ​

정상 ​

에러 ​

Rate limit ​

멱등성과 재전송 ​

user_sub 신뢰 모델 한계 ​

페이로드 위·변조 방지 ​

다음 ​