configuring-tauri-scopes

Tauri コマンドのスコープ

このスキルでは、Tauri v2 アプリケーションでスコープを設定し、コマンドやリソースへのきめ細かなアクセスを制御する方法を説明します。

スコープとは？

スコープは、コマンドが実行できる特定の操作を制御する、Tauri のきめ細かな認可メカニズムです。基本的なコマンドアクセスに加えて、詳細なアクセス許可の境界として機能します。

主な特徴

• 許可スコープ：特定の操作を明示的に許可します
• 拒否スコープ：特定の操作を明示的に制限します
• 拒否が優先：両方がある場合、拒否ルールが常に優先されます
• コマンドの責任：コマンドの実装では、スコープの制限を検証し、適用する必要があります

スコープの仕組み

実行時にスコープがコマンドに渡されます。スコープとの照合と制限の適用は、コマンドの実装が担います。つまり、開発者はバイパスを防ぐために、スコープの検証を慎重に実装する必要があります。

スコープの設定場所

スコープは、次の場所にあるケイパビリティファイルで設定します。

• src-tauri/capabilities/default.json（メイン）
• src-tauri/capabilities/*.json（追加のケイパビリティファイル）

ファイルシステムのスコープ

ファイルシステムプラグインでは、アクセス可能なパスを定義するために、glob 互換のパスパターンを使用します。

ファイルシステムの基本的なスコープ設定

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Default capability for the application",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "fs:scope",
      "allow": [{ "path": "$APPDATA" }, { "path": "$APPDATA/**" }]
    }
  ]
}

コマンド固有のスコープ

グローバルなアクセスを許可するのではなく、個々のファイルシステム操作を制限します。

{
  "permissions": [
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [{ "path": "$DOCUMENT/**" }]
    },
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$HOME/notes.txt" }]
    }
  ]
}

許可スコープと拒否スコープの組み合わせ

{
  "permissions": [
    {
      "identifier": "fs:allow-rename",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.config/**" }]
    }
  ]
}

使用可能なパス変数

Tauri は、一般的なシステムディレクトリを示す変数を実行時に挿入します。

変数	説明
$APPCONFIG	アプリケーションの設定ディレクトリ
$APPDATA	アプリケーションのデータディレクトリ
$APPLOCALDATA	アプリケーションのローカルデータディレクトリ
$APPCACHE	アプリケーションのキャッシュディレクトリ
$APPLOG	アプリケーションのログディレクトリ
$AUDIO	ユーザーのオーディオディレクトリ
$CACHE	システムのキャッシュディレクトリ
$CONFIG	システムの設定ディレクトリ
$DATA	システムのデータディレクトリ
$DESKTOP	ユーザーのデスクトップディレクトリ
$DOCUMENT	ユーザーのドキュメントディレクトリ
$DOWNLOAD	ユーザーのダウンロードディレクトリ
$EXE	アプリケーションの実行ファイルディレクトリ
$HOME	ユーザーのホームディレクトリ
$PICTURE	ユーザーの画像ディレクトリ
$PUBLIC	パブリックディレクトリ
$RESOURCE	アプリケーションのリソースディレクトリ
$TEMP	一時ディレクトリ
$VIDEO	ユーザーのビデオディレクトリ

スコープパターン

スコープでは、柔軟なパス照合のために glob パターンを使用できます。

パターンの例

{
  "permissions": [
    {
      "identifier": "fs:scope",
      "allow": [
        { "path": "$APPDATA/databases/*" },
        { "path": "$DOCUMENT/**/*.txt" },
        { "path": "$HOME/project/src/**" }
      ],
      "deny": [
        { "path": "$HOME/.ssh/**" },
        { "path": "$HOME/.gnupg/**" }
      ]
    }
  ]
}

パターン構文

パターン	意味
*	パス区切り文字以外の任意の文字列に一致します
**	パス区切り文字を含む任意の文字列に一致します（再帰的）
?	任意の1文字に一致します
[abc]	角括弧内の任意の1文字に一致します

パストラバーサルの防止

Tauri はパストラバーサル攻撃を防ぎます。次のパスは許可されません。

• /usr/path/to/../file
• ../path/to/file

HTTP プラグインのスコープ

HTTP プラグインでは、ネットワークアクセスを制御するために URL パターンを使用します。

URL スコープの設定

{
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [{ "url": "https://*.tauri.app" }],
      "deny": [{ "url": "https://private.tauri.app" }]
    }
  ]
}

URL パターンの例

{
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [
        { "url": "https://api.example.com/*" },
        { "url": "https://*.cdn.example.com/**" }
      ]
    }
  ]
}

スコープを使用したカスタム権限の定義（TOML）

プラグインやカスタムコマンドでは、TOML ファイルで権限を定義します。

スコープ付きの基本的な権限

# permissions/my-permission.toml
[[permission]]
identifier = "scope-appdata-recursive"
description = "Recursive access to APPDATA folder"

[[permission.scope.allow]]
path = "$APPDATA/**"

拒否スコープ付きの権限

[[permission]]
identifier = "deny-sensitive-data"
description = "Denies access to sensitive directories"
platforms = ["linux", "macos"]

[[permission.scope.deny]]
path = "$HOME/.ssh/**"

[[permission.scope.deny]]
path = "$HOME/.gnupg/**"

権限セット

権限を組み合わせて再利用可能なセットを作成します。

[[set]]
identifier = "safe-appdata-access"
description = "Allows APPDATA access while denying sensitive folders"
permissions = ["scope-appdata-recursive", "deny-sensitive-data"]

動的スコープ（実行時の管理）

Tauri では、Rust の FsExt トレイトを使用して、実行時にスコープを変更できます。

実行時にスコープを拡張する基本的な方法

use tauri_plugin_fs::FsExt;

pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_fs::init())
        .setup(|app| {
            let scope = app.fs_scope();
            // Allow a specific directory (non-recursive)
            scope.allow_directory("/path/to/directory", false)?;
            // Check what's currently allowed
            dbg!(scope.allowed());
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

スコープ拡張用の Tauri コマンド

use tauri_plugin_fs::FsExt;

#[tauri::command]
fn expand_scope(
    app_handle: tauri::AppHandle,
    folder_path: std::path::PathBuf
) -> Result<(), String> {
    // Verify path before expanding scope
    if !folder_path.exists() {
        return Err("Path does not exist".to_string());
    }

    // true = allow inner directories recursively
    app_handle
        .fs_scope()
        .allow_directory(&folder_path, true)
        .map_err(|err| err.to_string())
}

特定のファイルを許可する

#[tauri::command]
fn allow_file(
    app_handle: tauri::AppHandle,
    file_path: std::path::PathBuf
) -> Result<(), String> {
    app_handle
        .fs_scope()
        .allow_file(&file_path)
        .map_err(|err| err.to_string())
}

セキュリティに関する警告

動的なスコープ拡張は慎重に使用してください。

• スコープを拡張する前にパスを検証してください
• 可能な場合は静的設定を優先してください
• 検証されていないユーザー入力に基づいてスコープを拡張しないでください

リモート URL のスコープ（ケイパビリティ）

アプリケーションのコマンドにアクセスできるリモート URL を制御します。

{
  "identifier": "remote-api-access",
  "description": "Allow remote access from specific domains",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.mydomain.dev", "https://app.example.com"]
  },
  "permissions": ["core:default"]
}

ケイパビリティファイルの完全な例

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Default capability for desktop application",
  "windows": ["main", "settings"],
  "platforms": ["linux", "macos", "windows"],
  "permissions": [
    "core:default",
    "core:window:allow-set-title",
    {
      "identifier": "fs:default"
    },
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [
        { "path": "$DOCUMENT/**/*.md" },
        { "path": "$DOCUMENT/**/*.txt" }
      ]
    },
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$APPDATA/notes/**" }],
      "deny": [{ "path": "$APPDATA/notes/.secret/**" }]
    },
    {
      "identifier": "http:default",
      "allow": [{ "url": "https://api.example.com/*" }]
    }
  ]
}

セキュリティのベストプラクティス

1. スコープを最小限にする：必要不可欠なパスと URL のみを許可します
2. 拒否ルールを使用する：許可されたパスの配下であっても、機密性の高いディレクトリを明示的にブロックします
3. コマンド固有のスコープを優先する：グローバルな fs:scope よりも fs:allow-read-text-file を使用します
4. 動的スコープを検証する：実行時にスコープを拡張する前に、必ずパスを検証します
5. スコープの適用状況を監査する：コマンドの開発者は、適切なスコープ検証を実装する必要があります
6. パス変数を使用する：移植性を高めるため、ハードコードされたパスよりも $APPDATA を優先します

一般的なスコープのパターン

読み取り専用のアプリケーションデータ

{
  "permissions": [
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [{ "path": "$APPDATA/**" }]
    },
    {
      "identifier": "fs:allow-exists",
      "allow": [{ "path": "$APPDATA/**" }]
    }
  ]
}

ユーザーのドキュメントへのアクセス

{
  "permissions": [
    {
      "identifier": "fs:scope",
      "allow": [{ "path": "$DOCUMENT/**" }],
      "deny": [
        { "path": "$DOCUMENT/.hidden/**" },
        { "path": "$DOCUMENT/**/*.key" }
      ]
    }
  ]
}

API のみの HTTP アクセス

{
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [
        { "url": "https://api.myapp.com/v1/*" },
        { "url": "https://cdn.myapp.com/**" }
      ],
      "deny": [
        { "url": "https://api.myapp.com/v1/admin/*" }
      ]
    }
  ]
}

トラブルシューティング

「設定されたスコープでパスが許可されていません」

このエラーは、要求されたパスが設定済みのスコープ外にあることを示します。対処方法：

1. パスを capability の許可リストに追加します
2. パス変数に誤字がないか確認します
3. グロブパターンが意図したパスに一致することを確認します
4. 拒否ルールによってパスがブロックされていないか確認します

スコープ設定のテスト

開発モードで実行して、権限をテストします：

pnpm tauri dev
# or
cargo tauri dev

必要な権限を示す権限エラーがコンソールに表示されます。

参考資料

• コマンドスコープのドキュメント
• 権限の概要
• Capabilities のリファレンス
• Filesystem プラグイン
• HTTP プラグイン