Uso de permisos de plugins

El objetivo de este ejercicio es comprender mejor cómo se pueden habilitar o deshabilitar los permisos de plugins, dónde se describen y cómo usar los permisos por defecto de los plugins.

Al final tendrás la capacidad de encontrar y utilizar los permisos de plugins arbitrarios y entender cómo personalizar los permisos existentes. Tendrás una aplicación Tauri de ejemplo donde se utilizan un plugin y permisos específicos del plugin.

1. Crear la aplicación Tauri

   Crea tu aplicación Tauri. En nuestro ejemplo facilitaremos 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

   Continuaremos en esta explicación paso a paso con pnpm, pero puedes elegir otro gestor de paquetes y reemplazarlo en los comandos en consecuencia.

   Mostrar solución

   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

2. Añadir el plugin file-system a tu aplicación

   Para buscar plugins existentes puedes utilizar múltiples recursos.

   La forma más directa sería verificar si tu plugin ya se encuentra en la sección de Plugins de la documentación y por lo tanto forma parte del conjunto de plugins mantenidos por Tauri. El plugin Filesystem forma parte del espacio de trabajo de plugins de Tauri y puedes añadirlo a tu proyecto siguiendo las instrucciones.

   Si el plugin forma parte del esfuerzo de la comunidad, lo más probable es que puedas encontrarlo en crates.io al buscar tauri-plugin-<nombre de tu plugin>.

   Mostrar solución

   Si es un plugin existente de nuestro espacio de trabajo, puedes usar la forma automatizada:

   pnpm tauri add fs

   Si lo has encontrado en crates.io debes añadirlo manualmente como una dependencia y modificar el constructor de Tauri para inicializar el plugin:

   cargo add tauri-plugin-fs

   Modifica lib.rs para inicializar el plugin:

   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. Entender los permisos por defecto del plugin fs

   Cada plugin tiene un conjunto de permisos por defecto, el cual contiene todos los permisos y alcances (scopes) para usar el plugin desde el primer momento con un conjunto mínimo razonable de funcionalidades.

   En el caso de los plugins mantenidos oficialmente, puedes encontrar una descripción procesada en la documentación (p. ej. fs default).

   En caso de que estés averiguando esto para un plugin de la comunidad, necesitas revisar el código fuente del plugin. Esto debería estar definido en your-plugin/permissions/default.toml.

   Mostrar solución

   "$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"]

4. Encontrar los permisos adecuados

   Este paso consiste en encontrar los permisos que necesitas para que tus comandos queden expuestos al frontend con el acceso mínimo a tu sistema.

   El plugin fs tiene permisos autogenerados que deshabilitarán o habilitarán comandos individuales y permitirán o deshabilitarán alcances globales.

   Estos se pueden encontrar en la documentación o en el código fuente del plugin (fs/permissions/autogenerated).

   Supongamos que queremos habilitar la escritura en un archivo de texto test.txt ubicado en la carpeta $HOME del usuario.

   Para esto buscaríamos en los permisos autogenerados un permiso para habilitar la escritura en archivos de texto como allow-write-text-file y luego un alcance que nos permita acceder al archivo $HOME/test.txt.

   Necesitamos añadir estos a nuestra sección de capabilities en nuestro src-tauri/tauri.conf.json o en un archivo en la carpeta src-tauri/capabilities/. Por defecto ya hay una capacidad en src-tauri/capabilities/default.json que podemos modificar.

   Mostrar solución

   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",
     ]
   }

   Dado que en el plugin fs solo hay alcances autogenerados para acceder a toda la carpeta $HOME, necesitamos configurar nuestro propio alcance. Este alcance solo debe estar habilitado para el comando write-text-file y solo debe exponer nuestro archivo test.txt.

   Mostrar solución

   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. Probar los permisos en la práctica

   Después de añadir el permiso necesario, queremos confirmar que nuestra aplicación puede acceder al archivo y escribir su contenido.

   Mostrar solución

   Podemos usar este fragmento en nuestra aplicación para escribir en el archivo:

   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);
   
     });
   });

   Reemplazar el src/main.ts con este fragmento significa que no necesitamos modificar el index.html por defecto, al usar la app plain Vanilla+TypeScript. Cualquier texto introducido en el campo de entrada de la aplicación en ejecución se escribirá en el archivo al enviar.

   Probemos ahora en la práctica:

   pnpm run tauri dev

   Después de escribir en el campo de entrada y hacer clic en “Submit”, podemos verificar mediante nuestro emulador de terminal o abriendo manualmente el archivo en tu carpeta personal.

   cat $HOME/test.txt

   Debería mostrarse tu texto introducido y habrás terminado de aprender sobre el uso de permisos de plugins en aplicaciones Tauri. 🥳

   Si encontraste este error:

   [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)

   Entonces es muy probable que no hayas seguido adecuadamente las instrucciones anteriores.