개요와 권한

개요

Baram 플러그인은 매니페스트(baram-plugin.json)와 ESM 번들 하나(보통 dist/index.mjs)를 담은 디렉터리입니다. 번들은 activate(context) 함수를(그리고 선택적으로 deactivate()를) 내보내고, 호스트가 권한으로 통제되는 ExtensionContext 객체와 함께 activate를 호출합니다. 그 객체가 플러그인이 앱에 닿는 유일한 통로입니다.

모든 플러그인은 매니페스트에 두 티어 중 하나를 선언하며, 티어가 “권한”의 뜻을 정합니다.

• "trust": "sandboxed" — 기본값이고, 여러분이 써야 할 것입니다. 플러그인이 앱의 JavaScript에 닿지 못하는 격리된 웹뷰에서 돌고, 권한이 필요한 모든 작업이 Rust 브로커를 거쳐 플러그인에 부여된 권한과 대조됩니다. 여기서 권한 목록은 실제 경계입니다.
• "trust": "trusted" — 에디터와 같은 JavaScript 컨텍스트, Obsidian의 모델입니다. tiptapExtensions에는 필요합니다 — 살아 있는 에디터에 직접 닿아 ProseMirror 플러그인을 등록해야 하기 때문입니다. 스키마가 아닙니다 — "plugin" 기여는 스키마를 전혀 건드리지 못하고, 그것이 바로 node/mark 기여가 지원되지 않는 이유입니다(Tiptap 확장 플러그인 참조). 여기서 권한 체계는 API 관문일 뿐입니다. 플러그인이 그것을 우회할 수 있으므로, 목록은 무엇을 하려는지 알려 줄 뿐 아무것도 제한하지 않습니다. 설치할 때 정확히 그 점을 명시적으로 확인받습니다.

Tiptap 확장이나 DOM에 붙는 UI를 기여하는 경우가 아니면 sandboxed로 쓰십시오. 민감한 것을 설치하거나 만들기 전에 신뢰 모델과 보안을 보십시오.

권한

플러그인은 필요한 모든 권한을 매니페스트에 선언해야 합니다. 사용자는 설치 시점에(레지스트리 설치), 그리고 릴리스 빌드에서는 개발 폴더의 코드가 처음 돌기 전에 그것을 승인합니다. 개발 빌드는 개발 폴더를 묻지 않고 불러옵니다 (신뢰 모델과 보안 참조). 선언하지 않은 권한의 API에 닿으면 조용히 아무 일도 하지 않는 대신 분명한 오류를 던집니다 (“Plugin requires "X" capability to access …”) — 컨텍스트가 부여되지 않은 API에 대해 거부 프록시를 돌려줍니다.

권한	설명	민감도
commands	에디터 명령 등록·실행
editor	문서 내용 읽기·수정
editor:readonly	문서 내용 읽기(수정 불가)
events	에디터 이벤트 수신
extensions	에디터에 ProseMirror 플러그인 기여(trusted 티어 전용)
files	볼트 안 파일 읽기·쓰기, ctx.index와 vault:changed 포함	민감
files:readonly	볼트 안 파일 읽기(쓰기 불가), ctx.index와 vault:changed 포함
sidebar	사이드바에 패널 추가 — trusted 플러그인은 자기 DOM을 붙이고, sandboxed 플러그인은 패널을 선언
statusbar	상태바에 항목 표시
settings	설정 화면에 옵션 선언
ai	AI/LLM 기능 접근	민감
network	네트워크 요청	민감
storage	플러그인 전용 키/값 저장소 사용	민감
viewer	파일 형식별 커스텀 뷰어 등록
codeblocks	선언한 언어의 코드 블록 그리기 — 코드 블록 렌더러 참조

ai와 network가 가장 민감한 권한입니다 — 정확히 무엇을 허용하는지는 신뢰 모델과 보안을 보십시오. files와 storage도 표시해 두었습니다. 볼트·플러그인 범위로 한정돼 있고 무제한은 아니지만, 플러그인 자신의 메모리 밖 데이터(볼트 파일 / 디스크에 남는 저장소)에 닿기 때문입니다.