---
name: openai-usage-token-issue
version: 1.0.0
description: 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회만 전달한다.

```bash
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}}"
```

3. **매핑 기록 작성**
   - raw token은 파일에 쓰지 않는다.
   - 운영 기록에는 아래 필드만 남긴다.

```yaml
token_ref: "<token_ref>"
principal_ref: "<principal_ref>"
principal_alias: "<principal_alias>"
token_hash_sha256: "<token_hash>"
status: active
```

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

5. **누출 확인**
   - 저장소 안에 raw token이 남지 않았는지 조용한 검색으로 확인한다. 실패 시 출력에 raw token이 찍히지 않게 한다.

```bash
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"
```

6. **결과 보고**
   - `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 파일은 수정한 뒤 다시 누출 확인을 실행한다.

## 출력 형식

```text
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를 이 스킬 책임으로 확장하지 않는다.
