toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-ops/skills/project/openai-usage-token-issue/SKILL.md

5.5 KiB
Raw Blame History

name version description
openai-usage-token-issue 1.0.0 OpenAI-compatible usage metering용 IOP token을 principal_ref/internal alias에 연결해 발급하는 운영 절차

openai-usage-token-issue

목적

OpenAI-compatible 사용량 metering에 쓸 IOP bearer token을 발급하고, raw token 없이 token_ref, token hash, principal_ref, 내부 alias 매핑만 운영 기록에 남긴다. IOP는 사용자/테넌트 source of truth를 소유하지 않고, 외부 principal id 또는 내부 운영 id를 참조값으로만 다룬다.

언제 호출할지

  • OpenAI-compatible 호출 사용량을 특정 principal_ref 또는 내부 alias로 귀속할 IOP token을 새로 발급할 때
  • dev/dev-corp 운영자가 Grafana 사용량 label에 노출될 token_ref, principal_alias를 준비할 때
  • raw bearer token을 tracked 파일이나 최종 보고에 남기지 않고 1회 전달해야 할 때

입력

  • principal_ref: 외부 사용자/테넌트 프로젝트 또는 운영 시스템의 principal 참조값 (필수)
  • principal_alias: Grafana에 노출할 내부 alias. 없으면 principal_ref에서 secret이 아닌 짧은 별칭을 정한다. (선택)
  • token_ref: metric label과 설정에 쓸 안정 token 참조값. 한 principal_ref가 여러 앱/통합을 운영하면 앱/통합/용도별로 서로 다른 token_ref를 발급한다. 없으면 token hash prefix로 만든다. (선택)
  • output_path: raw token 없이 매핑 기록을 저장할 비공개/운영 전용 파일 경로. tracked docs/config에 쓰지 않는다. (선택)

먼저 확인할 것

  • principal_ref가 secret, raw email, provider token, provider identity가 아니라 외부 시스템 참조값인지 확인한다.
  • raw token을 tracked docs/, agent-roadmap/, agent-spec/, configs/, git diff, shell history, 최종 보고에 남기지 않을 전달 경로를 정한다.
  • token_ref와 principal_alias가 낮은 cardinality label로 안전한 값인지 확인한다.
  • 같은 principal_ref에 여러 앱/통합용 token이 필요한 경우 각 token의 앱/통합/용도 구분이 token_ref에 반영되는지 확인한다.
  • 기존 token을 회전하는 경우 기존 token_ref를 재사용할지 새 token_ref를 만들지 운영 정책을 확인한다.

실행 절차

  1. 입력 정규화

    • principal_ref 앞뒤 공백을 제거한다.
    • principal_alias는 공백을 -로 바꾸고, 운영자가 식별할 수 있는 짧은 ASCII alias로 둔다.
    • token_ref를 직접 받지 않았으면 생성할 token hash의 앞 16자를 사용해 ioptok_<hash-prefix> 형식으로 만든다.

  2. raw token 생성

    • 현재 shell에서 set +x를 확인한다.
    • 아래 형태의 고엔트로피 token을 생성한다. 실제 출력은 operator에게 1회만 전달한다.
set +x
umask 077
raw_token="iop_$(openssl rand -base64 36 | tr '+/' '-_' | tr -d '=')"
token_hash="$(printf '%s' "$raw_token" | sha256sum | awk '{print $1}')"
token_ref="${token_ref:-ioptok_${token_hash:0:16}}"
  1. 매핑 기록 작성
    • raw token은 파일에 쓰지 않는다.
    • 운영 기록에는 아래 필드만 남긴다.
token_ref: "<token_ref>"
principal_ref: "<principal_ref>"
principal_alias: "<principal_alias>"
token_hash_sha256: "<token_hash>"
status: active

  1. raw token 1회 전달

    • raw token은 operator-only 채널로 한 번만 전달한다.
    • 채팅 최종 보고, git diff, tracked 문서, 검증 출력에는 raw token을 쓰지 않는다.

  2. 누출 확인

    • 저장소 안에 raw token이 남지 않았는지 조용한 검색으로 확인한다. 실패 시 출력에 raw token이 찍히지 않게 한다.
if rg -q -F "$raw_token" agent-ops agent-roadmap agent-spec agent-contract docs configs apps packages proto; then
  echo "raw token leak detected in tracked workspace paths"
  exit 1
fi
echo "raw token not found in tracked workspace paths"
  1. 결과 보고
    • token_ref, principal_ref, principal_alias, 매핑 기록 위치, raw token 전달 여부만 보고한다.
    • raw token과 전체 token hash는 보고하지 않는다.

실행 결과 검증

  • raw token이 operator에게 1회만 전달되었는가
  • tracked 파일에는 raw token이 없고, token_ref, principal_ref, principal_alias, hash만 남았는가
  • rg -q -F "$raw_token" ... 누출 확인이 실패하지 않았는가
  • 최종 보고에 raw token, provider token, provider identity, raw prompt/response가 포함되지 않았는가
  • 검증 실패 시: raw token을 폐기하고 새 token을 발급한다. 누출된 tracked 파일은 수정한 뒤 다시 누출 확인을 실행한다.

출력 형식

OpenAI usage token issue
- token_ref: <token_ref>
- principal_ref: <principal_ref>
- principal_alias: <principal_alias>
- mapping_record: <path or operator-private store>
- raw_token_delivered_once: <yes|no>
- leak_check: <pass|fail>
- notes: raw token omitted from report

금지 사항

  • raw token을 tracked 파일, 최종 보고, 로그, metric label, Grafana dashboard, shell trace에 남기지 않는다.
  • metadata.user, provider token, provider identity를 사용자 식별 source로 쓰지 않는다.
  • request_id, session_id, raw token, raw prompt, raw response 같은 high-cardinality 또는 secret 값을 metric label 후보로 만들지 않는다.
  • 사용자 CRUD, tenant/org source of truth, token 제한 enforcement를 이 스킬 책임으로 확장하지 않는다.