feat(usage): read connected hub usage scoped to the enrolled client key

[lidge-jun]

Summary

Connected ocx usage reads the hub data plane using the enrolled client key, instead of calling a missing local management endpoint. The hub returns only that authenticated key's numeric totals and provider/model/day rows; account attribution, raw entries and other clients' records are excluded.

The bounded response retains range/surface/provider/model/custom-window options and explicit incomplete-history metadata. Invalid connections, changed token ownership, unsupported hubs and read failures are reported without local fallback. Addresses #4205.

Manual chain: #4357 (readable totals) → this PR (client-scoped read). Base is codex/260912-60plus-operations-totals; this layer uses its aggregate metadata contract. No native stack is registered. Merge decisions belong to the parent coordination task.

Verification

• Local suites of every size, typecheck, build and install: NOT RUN by explicit maintainer instruction.
• git diff --check: passed. Independent design and implementation-entry audits passed; independent security/source implementation review passed at3565b90 and the two-test follow-up bf369d9.
• Added actual route tests for two-key isolation, loopback authentication, rejected query identities, custom windows, and revocation during aggregation; client/CLI tests cover response stripping, bounded reads, redirects, errors, ownership changes and standalone compatibility.
• Final cumulative tip GitHub-hosted Cross-platform CI is pending; no old head is counted as current verification.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults; independent source audit passed, hosted execution remains pending.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 52 / 80

이 PR은 connected 클라이언트의 ocx usage가 없는 로컬 management endpoint를 치지 않고, hub data plane /v1/usage를 enrolled client key로만 읽게 합니다 (#4205). draft이고 base가 dev가 아니라 codex/260912-60plus-operations-totals (#4357 readable totals 체인)입니다. 현재 dev HEAD 81f6cd591에는 이 hub usage 라우트가 아직 없습니다. #4371 Cline이나 #4352 OAuth callback 퇴직과는 다른 operations/remote 축입니다.

서버 src/server/hub-usage.ts는 configured data key만 받고, hub role이 아니면 404, origin 검사, query allowlist, 읽기 중 key 변경 재검증, cache-control: no-store, 응답 크기 상한을 둡니다. aggregate는 기존 getFilteredUsageAggregate에 apiKeyId로 걸되, trim이 다른 key로 바뀌지 않게 keyId 형태를 거부합니다. DTO는 src/remote/hub-usage.ts zod 스키마로 account 라벨·raw entry·management 필드를 떨어뜨립니다. 클라이언트 fetchHubUsage는 HTTPS/loopback, bounded body, 401/403/404 메시지 구분, local fallback 금지를 지킵니다. CLI observe.ts는 connected일 때 token fingerprint가 connection과 같은지 확인하고, 읽기 중 connection drift면 재시도를 요구합니다.

테스트가 CLI·client·server·attribution 쪽으로 꽤 있습니다. 설계상 “계정 합계를 클라이언트에 새지 않는다”는 점이 분명합니다. 다만 stacked base라서 지금 dev에 단독 머지할 수 없고, CI도 UNSTABLE입니다. #4372 remote dashboard 스택과도 hub/client 경계가 이웃합니다.

현재 dev snapshot 기준으로 accounts eligibility/reset은 #4352 이후에도 남아 있고, operations/hub usage는 그 옆 레일입니다. 클라이언트에 계정 attribution을 안 주는 설계는 hub 다테넌트에서 필수에 가깝습니다. 다만 enrolled key 스코프 읽기가 totals 부모의 aggregate 메타 계약에 기대므로, 부모 없이 tip만 리베이스하면 스키마/필터 의미가 어긋날 수 있습니다.

경로 auth-cors - /v1/usage를 dedicated x-api-key만 받고 bearer는 rejected로 둔 선택이 기존 data-plane 규칙과 일치하는지 한 번 대조하세요.

경로 range 파싱 - 쿼리에서 1d를 허용하는 분기가 보이는데, 스키마 range enum은 today/7d/30d/all입니다. totals 부모 계약과 어긋나면 클라이언트/허브가 서로 다른 범위를 말할 수 있습니다.

스택 - 부모 #4357이 dev에 없으면 이 tip만 리베이스하지 말고 체인으로 가져오세요. types.ts/config.ts split과는 직접 겹침이 적어 보이지만 server/index 접점은 큽니다.

메인테이너의 판단이 필요한 지점

• operations-totals → client-usage 체인을 언제 dev에 올릴지
• hub가 아닌 runtimeRole에서 404를 유지할지
• #4372와 usage endpoint 문서/가이드 중복

너의 추천
draft 유지. 부모 totals가 dev에 착지한 뒤 CI 녹색으로 승격하세요. 지금 점수 구간(45–58) 안의 중간값이고, 보안 경계(키 스코프·redaction·no-store)는 방향이 맞습니다.

이 댓글은 grok-bot이 작성했습니다