docs(skill): keep plaintext keys out of agent recipes

[lidge-jun]

Summary

• Remove access-key creation and rotation-start from executable agent recipes because both return plaintext credentials. Preserve human-operated creation and the separately authorized commit/remove/abort paths, including approval already given for that exact action.
• Keep managed ocx connect rotate distinct. Add bounded literal recipe regressions for CLI aliases, wrappers, explicit API methods, inline examples and benign operations in the existing test-domain location.
• Carry docs(skill): keep access-key secrets out of agent sessions #3324 from 2933cc5842 and 7734e758b7 with documented detector/prose corrections. This changes agent guidance, not the human CLI or server authorization.

Track 3 manual stack, layer 3. Base: codex/track3-container-codex-home-a4b0; lower layer #3786 handles manifests. No native stack registration.

Verification

• Independent Astra high implementation/security review: PASS, zero blockers. It cross-checked the detector against actual CLI/API operation parsing and plaintext/status responses.
• git diff --cached --check passed. No local tests, typecheck, builds or suites were run, per maintainer instruction.
• Runtime validation: the cumulative exact-source CI evidence is recorded below; lower-layer tests are deferred under the explicit maintainer policy.
• Detector coverage is deliberately bounded; arbitrary scripts, dynamic invocation and implicit POST are outside its static coverage. It does not enforce runtime agent behavior.

Cumulative tested source: 9ea896737bd17085ebb8a69b3320c9cace61889e, based on dev eff908e0fb9452d5ff2952af1c5dafc1c4c35dd9.

• Cross-platform CI: all 25 jobs successful. Attempt 1 failed only the existing Windows cli-models first-child 15-second watchdog. One unchanged-head rerun of that shard completed 3,489 cases (3,465 pass, 24 skip, 0 fail); the first models case took 943 ms. The initial failure is retained; the slow phase remains unproven and no flakiness fix is claimed.
• Service lifecycle: Linux, macOS and Windows passed on the same source head.
• Documentation build: passed after checking out and asserting that exact source. Its isolated workflow-definition commit is different and is not part of this stack; no deployment occurred.
• Independent scoped code/security and integration reviews: PASS. The two earlier Windows fixture-budget changes retain production behavior and original assertions, backed by readiness controls and quota restart controls. Diagnostic workflows, instrumentation and mutations are excluded from delivery.

The maintainer explicitly authorizes dev admin integration and final-head-first validation for this manual chain: #3786 → #3788 → #3789 → #3790 → #3796 → #3802. Lower automatic tests are deferred with [skip ci], not represented as passing. No local tests, typecheck, builds or suites were run; pushes used --no-verify. Merge commits preserve source ancestry and suppress duplicate lower CI; fresh head/base/actor/review checks and resulting tree checks accompany each merge.

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.

Co-authored-by: luvs01 27862058+luvs01@users.noreply.github.com

Landing confirmed: merged into dev as 26fa36424a5417d264d77edce4edadc12620bd06. The final chain merge is f89b815090020f52089801b50f569a777bdfdc0a; its tree 846b8ffc383fc0ba99486917bdfb820a0fa432ba equals the tested cumulative source. Source ancestry and every merge were verified after fetching dev.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 078e1a10-0288-46c8-811e-8b86526174eb

📥 Commits

Reviewing files that changed from the base of the PR and between 4397079 and 1f83fc6.

📒 Files selected for processing (15)

• Dockerfile
• compose.yaml
• docs-site/src/content/docs/fr/guides/remote-hub.md
• docs-site/src/content/docs/guides/remote-hub.md
• docs-site/src/content/docs/ja/guides/remote-hub.md
• docs-site/src/content/docs/ko/guides/remote-hub.md
• docs-site/src/content/docs/ru/guides/remote-hub.md
• docs-site/src/content/docs/tr/guides/remote-hub.md
• docs-site/src/content/docs/zh-cn/guides/remote-hub.md
• skills/ocx/SKILL.md
• skills/ocx/references/03_recipes.md
• skills/ocx/references/05_remote_hub.md
• structure/02_config-and-codex-home.md
• tests/ci-workflows/skill-ocx.test.ts
• tests/service/container-bootstrap.test.ts

---

📝 Walkthrough

Walkthrough

The change separates Codex and OpenCodex Docker state, adds catalog isolation tests and deployment guidance, and introduces documentation and CI checks that restrict secret-bearing access-key operations to human-managed workflows.

Changes

Codex state separation

Layer / File(s)	Summary
Runtime storage and deployment contracts Dockerfile, compose.yaml, structure/02_config-and-codex-home.md, tests/service/container-bootstrap.test.ts	The runtime sets CODEX_HOME, creates separate owner-only directories, and mounts ocx-state and codex-state independently. Deployment tests verify the container contract.
Catalog loading and home isolation tests/service/container-bootstrap.test.ts	Tests cover Codex catalog loading, custom and relative paths, malformed JSON, repeated reads, and unchanged authentication stores.
Deployment and rollback documentation docs-site/src/content/docs/guides/remote-hub.md, docs-site/src/content/docs/*/guides/remote-hub.md	The guides document separate state volumes, catalog creation and persistence, migration limits, rollback mappings, and destructive volume removal.

Secret-command policy

Layer / File(s)	Summary
Secret operation policy and rotation workflow skills/ocx/SKILL.md, skills/ocx/references/03_recipes.md, skills/ocx/references/05_remote_hub.md	The documentation prohibits agent-initiated secret-returning access-key operations and defines human-managed rotation, approval, commit, removal, and abort steps.
Secret-command detection tests tests/ci-workflows/skill-ocx.test.ts	CI tests detect secret-bearing CLI commands and management requests across aliases, wrappers, continuations, and platforms. They also verify approval-boundary wording and reject unsafe recipes.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant OCXSkill
  participant KeyAPI
  Operator->>OCXSkill: Request access-key rotation
  OCXSkill->>Operator: Direct secret-returning step to a human terminal
  Operator->>KeyAPI: Create key or start rotation
  KeyAPI-->>Operator: Return plaintext secret
  Operator->>OCXSkill: Provide non-secret status or approval
  OCXSkill->>KeyAPI: Commit, remove, or abort with authority

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/track3-agent-key-recipes-a4b0

---

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]

리뷰 · 우선순위 46 / 80

지금 dev의 skills/ocx/references/03_recipes.md 레시피 5는 에이전트에게 ocx access key create … --json을 그대로 실행하라고 적혀 있습니다. create/rotation-start 응답에는 한 번만 나오는 plaintext 데이터면 키가 들어 있어서, 에이전트 트랜스크립트·도구 로그에 비밀이 남을 수 있습니다. 사람용 CLI나 서버 인가를 바꾸는 PR이 아니라, ocx 스킬 문서와 회귀 테스트만 고쳐서 그 안내를 없앱니다. #3324에서 다뤘던 “에이전트 레시피에 평문 키 흘리지 않기”를 다시 문서·감지기 쪽으로 정리한 층입니다.

skills/ocx/SKILL.md에 Secret-bearing commands 절이 생기고, create/rotation-start와 /api/keys, /api/keys/rotate POST를 에이전트 세션 밖으로 보냅니다. 설정 확인과 폐기(revocation) 승인을 分け 적었고, 이미 같은 ID에 대한 명시 승인이 있으면 다시 묻지 말라고 했습니다. 레시피 5 제목도 “키를 노출하지 않고 로테이션 준비”로 바뀌고, 에이전트가 해도 되는 것은 rotate commit / rotate abort / remove(별도 승인)와 list 확인뿐입니다. 05_remote_hub.md는 관리형 ocx connect rotate와 raw access-key 경로를 구분합니다. tests/ci-workflows/skill-ocx.test.ts는 펜스·인라인 코드 안의 리터럴 명령을 정규식으로 훑어, create/start는 잡고 commit/abort·connect rotate·무해한 list/remove는 통과시킵니다.

base는 #3788 브랜치라 Track 3 맨 위 층입니다. 런타임/프록시 동작은 HEAD와 같고, 점수 자체는 문서·가드 레일이라 중간입니다. 그래도 에이전트가 ocx 스킬을 그대로 따라 할 때 비밀이 새는 실수 비용이 커서, 스택에 묶여 있다면 같이 올리는 편이 맞습니다. 감지기 한계(동적 호출, 암시적 POST, 임의 스크립트)는 PR이 이미 적어 두었고, 테스트 주석에도 “에이전트 런타임 행동을 증명하지 않는다”고 되어 있습니다.

skills/ocx/references/03_recipes.md 레시피 5 - HEAD의 create rotated --json 예시가 평문 키를 에이전트에게 권한다. 이 PR이 그 실행 가능한 예시를 제거한다.
skills/ocx/SKILL.md Secret-bearing commands - create/start 금지와 폐기 승인 분리가 명확하다. 사람 터미널로 넘기라는 문장이 핵심이다.
tests/ci-workflows/skill-ocx.test.ts - 정적 리터럴 감지기라 우회는 가능하다. 문서 회귀용 early warning으로 보는 게 맞다.
05_remote_hub.md - ocx connect rotate를 raw /api/keys와 섞지 말라는 한 단락이 운영 혼선을 줄인다.
Track 3 의존 - 이 층만 따로 dev에 체리픽해도 파일 충돌은 적을 수 있지만, 스택 정본이면 #3786→#3788 다음에 올리는 게 이력상 깔끔하다.

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

• 스킬만 급한지, Track 3 전체 CI 통과 후 한꺼번에 올릴지
• 감지기 false positive(예: 금지 문장 안 인라인 코드)를 지금 더 줄일지, 문서 규약으로 둘지
• Co-authored docs(skill): keep access-key secrets out of agent sessions #3324 계보를 CREDITS/머지 메시지에 어떻게 남길지

너의 추천
Track 3 꼭대기로 #3788 다음에 머지. 런타임 리스크는 없고, HEAD 레시피의 평문 키 권고를 끊는 문서 가드라서 같이 가져가는 편이 좋다. 단독으로 급하면 skills/tests만 dev에 올려도 된다. types/config 분할 무효 대상 아님.

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T20:21:16.487154Z	1f83fc6	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.