팩 게시하기 - Failproof AI

팩은 GitHub 릴리스에 첨부된 세 개의 파일로 구성됩니다. failproofai pack build를 실행하면 이미 가지고 있는 정책 파일로부터 세 파일 모두 생성됩니다.

1. 정책 작성하기

커스텀 정책과 동일한 API를 사용하는 파일 하나로 작성합니다. 팩에서 중요한 추가 필드가 두 가지 있습니다:

import { customPolicies, deny, allow } from "failproofai";

customPolicies.add({
  name: "block-refunds",
  description: "Refunds above the approved limit need a human",
  category: "Billing",        // groups it, and is what --category selects on
  defaultEnabled: true,       // switched on by a plain `pack add`
  match: { events: ["PreToolUse"], tools: ["Bash"] },
  fn: async (ctx) =>
    String(ctx.toolInput?.command ?? "").includes("refund")
      ? deny("Refunds need a human. Ask before running this.")
      : allow(),
});

defaultEnabled를 생략하면 기본값은 false입니다. failproofai pack add를 그냥 실행하면 표시해 둔 정책만 활성화됩니다. 처음 보는 사람의 모든 정책을 사용자 동의 없이 설치하는 건 설치 도구가 사용자 대신 결정할 일이 아닙니다.

엔트리는 완전히 독립된 하나의 파일이어야 합니다. 다이제스트 핀은 엔트리 파일에만 적용되므로, 로컬 파일을 임포트하는 팩은 다이제스트가 실제 실행 코드를 보장한다고 말할 수 없습니다. 먼저 번들링(esbuild, bun build, rollup)한 뒤 번들로부터 팩을 빌드하세요 — pack build는 지킬 수 없는 약속을 배포하는 대신 로컬 임포트가 있으면 거부합니다.

2. 릴리스 에셋 빌드하기

failproofai pack build ./policies.mjs \
  --id acme/support-agent \
  --version 1.0.0 \
  --out ./dist-pack

세 개의 파일을 생성하며, 모든 정책을 로더 자체 규칙으로 먼저 검증합니다. 따라서 설치가 절대 불가능한 팩은 여기서 실패하고, 수정할 기회가 생깁니다:

파일	설명
`failproofai-pack.json`	매니페스트: id, 버전, effect, 정책별 항목 포함
`failproofai-pack.mjs`	그대로 복사된 엔트리 파일
`SHA256SUMS`	나머지 두 파일에 대한 `<sha256> <filename>`

빌드 시 거부되는 경우: publisher/name 형식이 아닌 id, /가 포함된 정책 이름, alwaysOn을 선언하는 정책, description·category·match 누락, 아무것도 등록하지 않는 엔트리, 로컬 파일을 임포트하는 엔트리.

3. 릴리스에 파일 첨부하기

빌드 시 사용한 버전과 동일한 태그로 릴리스를 생성하고, 세 파일을 릴리스 에셋으로 첨부합니다:

gh release create 1.0.0 \
  ./dist-pack/failproofai-pack.json \
  ./dist-pack/failproofai-pack.mjs \
  ./dist-pack/SHA256SUMS

이제 누구나 설치할 수 있습니다:

failproofai pack add acme/support-agent

에셋 이름은 고정되어 있습니다 — API 호출이나 별도의 탐색 과정 없이 설치 CLI가 URL을 구성할 때 사용하는 이름이기 때문입니다.

새 버전 배포하기

새 --version으로 빌드하고, 새 릴리스에 태그를 달아 세 에셋을 다시 첨부하세요. 사용자는 동일한 pack add 명령으로 업그레이드하며, 이전에 선택한 정책 구성이 유지됩니다. 비활성화해 둔 정책은 업그레이드 후에도 비활성 상태를 유지합니다. 정책의 이름을 변경하는 것은 하위 호환성을 깨는 변경입니다. 해당 이름을 비활성화해 둔 머신은 이제 존재하지 않는 이름을 끄고 있는 셈이 되고, 새 이름은 defaultEnabled 설정에 따라 활성화 여부가 결정됩니다.

사용자가 신뢰하는 대상

SHA256SUMS는 아티팩트와 동일한 릴리스에 포함되어 있으므로, 게시한 바이트가 맞다는 것을 증명합니다 — 게시자가 누구인지는 증명하지 않습니다. 저장소에 쓰기 권한이 있는 사람은 두 파일 모두 수정할 수 있습니다. 사용자를 보호하는 것은 설치 시점에 다이제스트가 고정된다는 점입니다. 따라서 배포한 내용이 이후에 몰래 바뀌더라도 사용자에게는 영향을 미치지 않습니다. 쓰기 권한을 직접 관리하는 저장소에서 게시하고, 팩 릴리스를 패키지 배포와 동일하게 취급하세요.

적용 전 관찰하기

매니페스트에 "effect": "observe"를 선언할 수 있습니다. 해당 정책들은 실행되고 판정 결과가 기록되지만 무시됩니다 — 아무것도 차단되지 않습니다. 누군가의 작업을 방해하기 전에 실제 트래픽을 기반으로 새 규칙을 측정하는 방법입니다.

{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] }

​1. 정책 작성하기

​2. 릴리스 에셋 빌드하기

​3. 릴리스에 파일 첨부하기

​새 버전 배포하기

​사용자가 신뢰하는 대상

​적용 전 관찰하기

1. 정책 작성하기

2. 릴리스 에셋 빌드하기

3. 릴리스에 파일 첨부하기

새 버전 배포하기

사용자가 신뢰하는 대상

적용 전 관찰하기