플러그인 접근 권한 사용

Note

본 번역에서는 Permissions / Capabilities에 주로 다음 번역어를 사용합니다.

• Permissions: “접근 권한”(액세스 허가권)
• Capabilities: “보안 수준”(보안 정도를 나타내는 권한 수준)

이 장의 목적은 플러그인 접근 권한이 어떻게 활성화 또는 비활성화되는지, 어디에 기술되어 있는지, 그리고 플러그인의 기본 접근 권한 사용 방법에 대해 더 깊이 이해하는 것입니다.

이 장을 다 읽을 때쯤이면 어떤 플러그인이든 그 접근 권한을 찾아 사용하고 기존 접근 권한을 사용자 정의하는 방법을 이해하게 될 것입니다. 아래에서 플러그인과 플러그인별 접근 권한을 사용하는 Tauri 애플리케이션의 예를 볼 수도 있습니다.

1. Tauri 애플리케이션 만들기

   Tauri 애플리케이션을 만듭니다. 이 예에서는 create-tauri-app을 실행합니다.

   Bash

   sh <(curl https://create.tauri.app/sh)

   PowerShell

   irm https://create.tauri.app/ps | iex

   Fish

   sh (curl -sSL https://create.tauri.app/sh | psub)

   npm

   npm create tauri-app@latest

   Yarn

   yarn create tauri-app

   pnpm

   pnpm create tauri-app

   deno

   deno run -A npm:create-tauri-app

   bun

   bun create tauri-app

   Cargo

   cargo install create-tauri-app --locked
   cargo create-tauri-app

   이 단계별 설명 절차에서는 pnpm을 사용하여 진행하지만, 다른 패키지 관리자도 선택할 수 있습니다. 선택한 패키지 관리자에 따라 명령을 바꿔주세요.

   Show solution

   pnpm create tauri-app

   ✔ Project name · plugin-permission-demo
   ✔ Choose which language to use for your frontend · TypeScript / JavaScript - (pnpm, yarn, npm, bun)
   ✔ Choose your package manager · pnpm
   ✔ Choose your UI template · Vanilla
   ✔ Choose your UI flavor · TypeScript
   
   Template created! To get started run:
   cd plugin-permission-demo
   pnpm install
   pnpm tauri dev

   Note

   ※ 처리 내용 참고 번역: ✔ 프로젝트 이름 … ✔ 프론트엔드에 사용할 언어 선택 … ✔ 패키지 관리자 선택 … ✔ UI 템플릿 선택 … ✔ UI 맛 선택 …

   템플릿이 생성되었습니다! 시작하려면 다음을 실행하십시오: cd (생성할 프로젝트 디렉토리 이름) pnpm install pnpm tauri dev

2. ”파일 시스템” 플러그인을 애플리케이션에 추가

   기존 플러그인을 검색하려면 여러 리소스를 사용할 수 있습니다.

   가장 쉬운 방법은 플러그인이 이미 『Tauri Guides』 문서의 “Plugins”에 있는지, 즉 Tauri가 관리하는 플러그인 세트 안에 존재하는지 확인하는 것입니다. 예를 들어, “파일 시스템(fs)” 플러그인은 Tauri Plugins 메뉴의 작업 공간(공유 영역)에 게시되어 있으며, 해당 링크의 설정 절차에 따라 자신의 프로젝트에 추가할 수 있습니다.

   또한 플러그인이 Tauri 커뮤니티의 노력으로 이루어진 것이라면 crates.io에서 거의 확실하게 찾을 수 있습니다. “tauri-plugin-<플러그인 이름>”과 같이 검색해 보십시오:

   Show solution
   Note

   아래, “파일 시스템 fs” 플러그인을 예로 들어, ① 메뉴 “Plaugins” 부분에 나열된 경우와, ② “crates.io” 사이트에서 얻는 경우의 처리 절차가 표시됩니다.

   찾고 있는 플러그인이 “작업 공간(공유 영역)“에 있는 기존 플러그인이라면 자동화된 방법을 사용할 수 있습니다:

   pnpm tauri add fs

   해당 플러그인을 “crates.io” 사이트에서 찾은 경우, 종속성을 수동으로 추가하고 플러그인을 초기화하기 위해 Tauri 빌더를 수정해야 합니다:

   cargo add tauri-plugin-fs

   플러그인 초기화를 위해 lib.rs를 수정합니다:

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   fn run() {
     tauri::Builder::default()
       .plugin(tauri_plugin_fs::init())
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
   }

3. “파일 시스템” 플러그인의 기본 접근 권한 확인

   각 플러그인에는 “기본” 접근 권한 세트가 있으며, 여기에는 적절하고 최소한의 기능과 플러그인을 즉시 그대로 사용하기 위한 접근 권한과 범위가 모두 포함되어 있습니다.

   공식적으로 유지 관리되는 플러그인의 경우, 문서에 제공된 설명이 기재되어 있습니다(예: fs default).

   커뮤니티 제작 플러그인에 대한 기본 접근 권한 설정을 알아보려면 해당 플러그인의 소스 코드를 자세히 살펴봐야 합니다. 그 내용은 your-plugin/permissions/default.toml에 정의되어 있어야 합니다.

   Show solution

   "$schema" = "schemas/schema.json"
   
     [default]
     description = """
   
     # Tauri `fs` default permissions
   
     This configuration file defines the default permissions granted to the filesystem.
   
     ### Granted Permissions
   
     This default permission set enables all read-related commands and allows access to the `$APP` folder and sub directories created in it.
     The location of the `$APP` folder depends on the operating system, where the application is run.
   
     In general the `$APP` folder needs to be manually created
     by the application at runtime, before accessing files or folders
     in it is possible.
   
     ### Denied Permissions
   
     This default permission set prevents access to critical components
     of the Tauri application by default.
     On Windows the webview data folder access is denied.
   
     """
     permissions = ["read-all", "scope-app-recursive", "deny-default"]

   Note

   [참고 번역]

   Tauri ‘fs’ 기본 접근 권한

   이 설정 파일은 “파일 시스템 fs” 플러그인에 부여되는 기본 접근 권한을 정의합니다.

   허가된 접근 권한

   이 기본 접근 “허가” 권한 세트는 모든 읽기 관련 명령을 활성화하고, “$APP” 폴더와 그 안에 생성된 하위 디렉토리에 대한 접근을 허용합니다. “$APP” 폴더의 위치는 애플리케이션이 실행되는 운영 체제에 따라 다릅니다.

   일반적으로 “$APP” 폴더 내의 파일이나 폴더에 접근하려면, 애플리케이션이 런타임에 수동으로 “$APP” 폴더를 생성해야 합니다.

   거부된 접근 권한

   이 기본 접근 “거부” 권한 세트는 기본적으로 Tauri 애플리케이션의 중요한 구성 요소에 대한 접근을 방지합니다. Windows에서는 Webview 데이터 폴더에 대한 접근이 거부됩니다.

4. 적절한 접근 권한 찾기

   4단계에서는 시스템에 대한 최소한의 접근으로 명령을 프론트엔드에 공개하는 데 필요한 접근 권한을 찾는 방법을 설명합니다.

   “fs” 플러그인에는 자동 생성된 접근 권한이 있으며, 개별 명령의 비활성화/활성화나 전역 범위의 허가/금지를 수행합니다. 접근 권한에 대한 자세한 내용은 공식 문서 또는 플러그인의 소스 코드(fs/permissions/autogenerated)를 참조하십시오.

   예를 들어, 사용자의 $HOME 폴더에 있는 텍스트 파일 “test.txt”에 대한 쓰기를 활성화하고 싶다고 가정합니다.

   이를 위해 “자동 생성된 접근 권한” 중에서 allow-write-text-file과 같이 텍스트 파일에 대한 쓰기를 허용하는 권한을 검색하고, 그런 다음 $HOME/test.txt 파일에 대한 접근을 허용하는 범위를 검색합니다.

   이러한 접근 권한을 src-tauri/tauri.conf.json의 “보안 수준 capabilities” 섹션 또는 “src-tauri/capabilities/ 폴더 내의 파일”에 추가해야 합니다. 기본적으로 src-tauri/capabilities/default.json 안에는 이미 수정 가능한 “보안 기능”이 있습니다.

   Show solution

   src-tauri/capabilities/default.json

   {
     "$schema": "../gen/schemas/desktop-schema.json",
     "identifier": "default",
     "description": "Capability for the main window",
     "windows": ["main"],
     "permissions": [
       "path:default",
       "event:default",
       "window:default",
       "app:default",
       "image:default",
       "resources:default",
       "menu:default",
       "tray:default",
       "shell:allow-open",
       "fs:default",
       "fs:allow-write-text-file"
     ]
   }

   “fs” 플러그인에는 $HOME 폴더 전체에 접근하기 위한 자동 생성된 범위만 설정되어 있으므로, 자신에게 필요한 고유한 범위를 설정해야 합니다. 이 고유한 범위는 write-text-file 명령만 활성화하고 test.txt 파일만 공개되도록 해야 합니다.

   Show solution

   src-tauri/capabilities/default.json

     {
     "$schema": "../gen/schemas/desktop-schema.json",
     "identifier": "default",
     "description": "Capability for the main window",
     "windows": [
       "main"
     ],
     "permissions": [
       "path:default",
       "event:default",
       "window:default",
       "app:default",
       "image:default",
       "resources:default",
       "menu:default",
       "tray:default",
       "shell:allow-open",
       "fs:allow-write-text-file",
       {
         "identifier": "fs:allow-write-text-file",
         "allow": [{ "path": "$HOME/test.txt" }]
       },
     ]
   }

5. 접근 권한 실습 테스트

   필요한 접근 권한을 추가한 후, 애플리케이션이 파일에 접근하여 그 내용을 쓸 수 있는지 확인합니다.

   Show solution

   애플리케이션에서 다음 스니펫을 사용하면 파일에 쓸 수 있습니다:

   src/main.ts

   import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
   
   let greetInputEl: HTMLInputElement | null;
   
   async function write(message: string) {
     await writeTextFile('test.txt', message, { baseDir: BaseDirectory.Home });
   }
   
   window.addEventListener('DOMContentLoaded', () => {
     greetInputEl = document.querySelector('#greet-input');
     document.querySelector('#greet-form')?.addEventListener('submit', (e) => {
       e.preventDefault();
       if (!greetInputEl) return;
   
       write(
         greetInputEl.value == '' ? 'No input provided' : greetInputEl.value
       );
     });
   });

   src/main.ts를 이 스니펫으로 바꾸면, 기본(플레인) Vanilla+Typescript 앱을 사용하는 경우 기본 index.html을 변경할 필요가 없습니다. 실행 중인 앱의 입력 필드에 입력하면, 전송 시 파일에 쓰여집니다.

   그럼 실제로 테스트해 봅시다:

   pnpm run tauri dev

   입력하고 “전송 Submit”을 클릭한 후, 터미널 에뮬레이터를 사용하거나 홈 폴더 내의 파일을 직접 열면 결과를 확인할 수 있습니다.

   cat $HOME/test.txt

   입력한 내용이 표시되어야 하며, 이제 Tauri 애플리케이션에서 플러그인의 접근 권한을 사용하는 방법에 대한 학습이 완료되었습니다. 🥳

   다음 오류가 발생한 경우:

   [Error] Unhandled Promise Rejection: fs.write_text_file not allowed. Permissions associated with this command: fs:allow-app-write, fs:allow-app-write-recursive, fs:allow-appcache-write, fs:allow-appcache-write-recursive, fs:allow-appconf...
   (anonymous function) (main.ts:5)

   Note

   [오류 내용 초역] 처리되지 않은 Promise 반환 “거부”: fs.write_text_file이 허용되지 않습니다. 이 명령과 관련된 접근 권한은 fs:allow-app-write, fs:allow-app-write-recursive, …입니다. (익명 함수)(main,ts:5)

   이 경우, 위의 4단계를 올바르게 실행하지 않았을 가능성이 매우 높습니다.