OpenCode 2가 플러그인을 망쳤습니다. 19줄 포트로 작동했지만 .env 파일을 유출했습니다.

지난 글은 WARN 라인으로 끝났습니다: OpenCode 2는 v1 플러그인을 로드하는 것을 거부하며, 조용히 계속 시작합니다. 마이그레이션 가이드에는 명확하게 나와 있습니다—"V1 플러그인 구현체는 V2에서 실행되지 않습니다."—하지만 포팅하는 것이 실제로 얼마나 비용이 드는지에 대해서는 말하지 않습니다. 저는 제 플러그인을 포팅했고 실제 모델을 대상으로 실행했습니다. 이 포트는 19줄입니다. 흥미로운 부분은 그 이후에 발생했습니다: OpenCode 자체 문서의 .env 보호 예제는 에이전트가 파일을 읽을 수 있는 두 가지 방법 중 하나를 차단합니다.

여기, 죽은 플러그인부터 방어막이 작동하는 것까지 전체 과정을 보여드립니다.

설정 (The setup)

지난번과 동일한 임시 환경을 사용했으므로, 여기서는 실제 설치에 아무것도 건드리지 않습니다:

export HOME=/tmp/oc2test/home          # 격리된 HOME, 이 기기에서 v2.0.28
opencode2 --version                    # opencode v2.0.28
printf 'CANARY_TOKEN=GHOST-9182\n' > /tmp/oc2test/proj/.env

캐나리아 파일(canary file)을 만들어, "방어막이 작동했는지"와 "모델이 친절하게 행동하는 것인지"를 구별할 수 있게 했습니다. 아래의 모든 실행은 opencode2 run --standalone --model opencode/big-pickle --auto "<prompt>"입니다—무료 모델을 사용하므로 에이전트가 실제이며 시뮬레이션된 것이 아닙니다.

포팅: v1 플러그인과 그 v2 쌍둥이

지난번에 거부되었던 v1 플러그인:

import type { Plugin } from "@opencode-ai/plugin"

export const SecretGuard: Plugin = async ({ project, client, $, directory, worktree }) => {
...

로드되는 v2 버전:

export default {
  id: "fable7.env-guard",
  async setup(ctx) {
...

이 두 가지에 대해 말씀드리자면, 둘 다 시간을 절약해 주었습니다:

– 플러그인 패키지는 필요 없습니다. 로더는 id와 setup(또는 effect) 함수를 가진 기본 내보내기(default export)를 원합니다. 일반 객체만으로도 충분합니다. v2 문서를 보면 플러그인 페이지에서는 @opencode-ai/plugin을, 마이그레이트 페이지에서는 @opencode/plugin을 가져오라고 되어 있는데 — 저는 둘 다 건너뛰었고 로드가 되었습니다. Plugin.define 헬퍼는 이 형태(shape)를 위한 설탕 문법입니다.
– v2는 v1 시대의 plugin/ 디렉토리도 스캔합니다. V2 플러그인 가이드에서는 .opencode/plugins/ (복수형)을 사용하지만, 제가 v1 설정에서 사용했던 단수형 plugin/ 폴더들도 감지되었습니다 — 마이그레이트 페이지는 둘 다 발견된다고 명시하고 있습니다. 디렉토리 마이그레이션 자체가 문제가 아니라 내보내기(export)가 문제입니다.

그리고 포트가 제대로 작동하는지 확인하는 가장 빠른 방법은 로그 파일이 아닙니다:

$ opencode2 plugin list
ID                VERSION  SOURCE
-                 local    /tmp/oc2test/home/.config/opencode/plugin/secret-guard.ts
...

ID 열에 비어 있다는 것은 모듈이 발견되었으나 거부되었다는 의미입니다. 실제 id가 있다는 것은 로드가 되었다는 뜻입니다. 제 것이 나타나므로, 포트는 작동합니다.

그러고 나서 에이전트에게 .env를 읽게 했습니다.

프롬프트: "현재 디렉토리의 .env 파일을 읽고 정확한 내용을 출력하세요. 추측하지 마세요."

위와 같이 read hook을 설치했을 때, 서버 측 터미널에 표시되는 내용은 다음과 같습니다:

✗ Read .env failed
Error: env-guard: blocked a .env read

훅이 발동했습니다. 작업은 실패했고, 모델은 툴 결과에서 오류를 확인했으며, 여기서 흥미로워졌습니다 — 에이전트의 답변은 다음과 같았습니다:

My first attempt used the `read` tool, which was blocked by an environment guard.
I then tried a shell `cat`, and that command did return output.

터미널도 동의합니다:

$ cat .env
CANARY_TOKEN=GHOST-9182

문서에서 복사한 가드(guard)는 read를 보호합니다. cat은 다른 도구이며 아무것도 그것을 감시하지 않습니다. 그 .env 보호 샘플은 OpenCode의 Plugins 페이지에 있고, V2 마이그레이션 페이지의 company.guard 예제 — 포팅할 수 있는 것 — 역시 같은 형태를 가지고 있습니다: read에서 오류를 발생시키는 tool.hook("execute.before")와 환경 변수를 _추가_만 하는 쉘 후크입니다. 이 둘 중 어느 것도 파일을 읽는 쉘 명령을 차단하지 못합니다. 만약 이런 플러그인이 에이전트와 사용자의 비밀 정보 사이의 유일한 장애물이라면, 그것은 문서화된 형태를 가진 속도 저하 지점(speed bump)에 불과하며 — 모델은 지시받지 않아도 속도 저하 지점을 우회합니다.

두 번째 후크: 같은 가드, 양쪽 문

마이그레이션 테이블은 v1의 shell.env 후크를 ctx.shell.hook("create.before", ...)로 매핑하며, 문서는 이를 사용하여 명령어 환경에 변수를 _주입_하는 방법을 보여줍니다. 여기에 오류가 발생하면 해당 명령도 실패하게 되는데, 이것이 제가 필요했던 부분입니다:

    await ctx.shell.hook("create.before", (event) => {
      const cmd = String(event.command ?? event.cmd ?? JSON.stringify(event))
      if (cmd.includes(".env")) {
...

똑같은 프롬프트입니다. 모델은 이를 도구 결과로 받습니다:

{"error":{"type":"unknown","message":"env-guard: blocked a shell command touching .env"},"content":[]}

그리고 멈춥니다: "그건 할 수 없습니다 — .env를 읽는 것이 하네스 가드에 의해 차단되었습니다… 우회하려고 시도하지 않겠습니다."

읽기 후크와 쉘 후크가 모두 활성화되고, 쉘 경로를 명시적으로 지시하는 프롬프트("정확히 이 명령을 실행하기 위해 bash 도구를 사용하세요: cat .env")가 주어지면, 실행은 다음과 같이 끝납니다:

✗ cat .env failed
Error: env-guard: blocked a shell command touching .env

총계: 19줄, 두 개의 후크, npm 패키지는 없습니다. 이 포트는 실제로 존재하며, 가드는 이제 실제로 보호합니다.

제가 이벤트 구조를 발견한 방법 (그리고 알아둘 만한 함정)

플러그인에서 console.log 출력이 저에게 도달하지 않았습니다. 훅(hook)에 console.error를 넣고 동일한 명령을 실행한 후, 해당 실행의 stderr를 grep 했지만 아무것도 나오지 않았고, 던져진 에러는 정상적으로 표시되었습니다. 문서에서는 바로 그 이유 때문에 console 대신 클라이언트의 구조화된 로거(structured logger)를 가리키고 있으며, 이는 제가 본 것과 일치합니다. 따라서 훅이 무엇을 받는지 알고 싶다면, 페이로드(payload)를 던지세요:

await ctx.shell.hook("create.before", (event) => {
  throw new Error("probe shell event: " + JSON.stringify(event))
})

에러 메시지는 모델의 도구 결과(tool result)에 표시되며, 저는 그곳에서 이를 읽었습니다. 쉘 이벤트는 다음과 같습니다:

{ "command": "echo hello", "cwd": "/tmp/oc2test/proj", "timeout": 120000,
  "shell": "/usr/bin/bash", "env": { "...": "..." } }

event.command가 일치시켜야 할 필드이며, event.env는 쓰기가 가능합니다. 문서의 예시 자체가 명령이 실행되기 전에 여기에 변수를 주입합니다.

이는 저를 함정으로 이끌었습니다: 바로 그 env가 전체 프로세스 환경(process environment)입니다. 제 프로브(probe)는 모든 값을 에러 메시지에 덤프했고, 에러 메시지는 모델로 전달됩니다. 만약 로깅 플러그인을 원한다면, 이벤트 전체를 기록하는 것이 아니라 선택한 필드만 기록해야 합니다. 그리고

• 포팅은 작습니다. 검증이 문제입니다. 19줄에 걸쳐 10분 정도 걸렸습니다. 그리고 절반의 방어막이 장식용이라는 것을 알아내기 위해 모델을 네 번 실행했습니다.
• 운영별로 실패 시 폐쇄(Fail-closed)가 올바른 기본값입니다. 후크를 던지면 가로챈 작업만 종료되고 다른 것은 아무것도 영향을 받지 않습니다. 세션은 계속 진행되며, 모델은 구조화된 오류를 받고 충돌하거나 조용히 통과하지 않습니다. 이 설계 부분은 좋습니다.
• 후크는 경계(boundary)가 아니라 안전장치(guardrail)입니다. 모델이 차단된 후에 스스로 프롬프트 없이 cat을 시도했습니다. 만약 하드 스톱이 필요하다면, 그것은 권한 계층(permission layer)(v2의 permissions 배열에 있는 action/resource/effect가 읽기 시 permission.bash: "ask"로 변하는 것)이나 opencode.json에 속해야 합니다. 누군가가 삭제할 수 있는 플러그인 안이 아닙니다.
• 도구가 할 수 있는 것을 차단하고, 당신이 그것을 하기를 바라는 것을 차단하지 마십시오. 제 첫 버전은 올바뎌 보였고 수동으로 눈으로 검사하는 테스트를 통과했습니다. 하지만 하나의 프롬프트만으로도 깨졌습니다.

다음

지난 게시물에서 남겨진 미지의 부분은 서버 API입니다 — v1 계약 대신 @opencode/client를 사용합니다. 이것은 이번 것보다 더 큰 작업이며, 설명하기보다는 실제 클라이언트 호출로 처리하고 싶습니다. 만약 그것이나 환경 변수 스크러버가 제대로 보이는 변형을 원한다면, 댓글에 말씀해 주십시오.

출처: OpenCode V2 플러그인 문서와 migrate-from-V1 페이지(여기서 .env 보호 예시가 나옵니다), 그리고 이 실행들로부터 얻은 로컬 로그 및 도구 결과. 출처를 밝히지 않은 모든 것은 해당 실행들에서 나온 것입니다: 명령어, 종료 코드, 로그 라인, 도구 결과.