configuring-tauri-capabilities

Tauri のケイパビリティ設定

ケイパビリティは、フロントエンドがアクセスできる API とコマンドをきめ細かく制御する、Tauri の権限管理システムです。どの権限をどのウィンドウまたは WebView に適用するかを指定し、セキュリティ境界を定義します。

ケイパビリティとは？

ケイパビリティは、権限とウィンドウ／WebView の橋渡しをします。次のことができます。

• 特定のウィンドウに付与または拒否する権限を定義します
• フロントエンドが侵害された場合の影響を最小限に抑えられます
• ウィンドウのタイトルではなくラベルに基づいてセキュリティ境界を作成します
• プラットフォームごとの対象指定（デスクトップとモバイル）に対応します

ケイパビリティファイルの場所

ケイパビリティファイルは src-tauri/capabilities/ に配置し、JSON または TOML 形式を使用します。

ケイパビリティファイルの構造

ケイパビリティファイルには次の項目が含まれます。

項目	必須	説明
identifier	はい	一意のケイパビリティ名
description	いいえ	目的の説明
windows	はい	対象となるウィンドウラベル（ワイルドカードに対応）
permissions	はい	許可／拒否する操作の配列
platforms	いいえ	対象プラットフォーム（linux、macOS、windows、iOS、android）
remote	いいえ	リモート URL アクセスの設定
$schema	いいえ	IDE サポート用の生成済みスキーマへの参照

基本的なケイパビリティの例

src-tauri/capabilities/main.json を作成します。

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default"
  ]
}

デフォルトのケイパビリティ

src-tauri/capabilities/ 内のすべてのケイパビリティは、デフォルトで自動的に有効になります。追加の設定は必要ありません。

有効にするケイパビリティを明示的に制御するには、tauri.conf.json で設定します。

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability"]
    }
  }
}

明示的に設定した場合、一覧に記載されたケイパビリティのみが適用されます。

設定方法

方法 1：個別ファイル（推奨）

ケイパビリティディレクトリに個別のケイパビリティファイルを保存します。

src-tauri/
  capabilities/
    main.json
    editor.json
    settings.json

tauri.conf.json で識別子を指定して参照します。

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability", "settings-capability"]
    }
  }
}

方法 2：インライン定義

ケイパビリティを tauri.conf.json に直接埋め込みます。

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "Capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "core:window:default"]
        }
      ]
    }
  }
}

方法 3：組み合わせ方式

ファイルベースのケイパビリティとインラインのケイパビリティを組み合わせます。

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "file-based-capability"
      ]
    }
  }
}

ウィンドウごとのケイパビリティ

ウィンドウラベルを使って、ウィンドウごとに異なる権限を割り当てます。

単一ウィンドウ

{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": ["core:window:default", "fs:default"]
}

複数の特定ウィンドウ

{
  "identifier": "editor-capability",
  "windows": ["editor", "preview"],
  "permissions": ["fs:read-files", "core:event:default"]
}

ワイルドカード（すべてのウィンドウ）

{
  "identifier": "global-capability",
  "windows": ["*"],
  "permissions": ["core:event:default"]
}

パターンマッチング

{
  "identifier": "dialog-capability",
  "windows": ["dialog-*"],
  "permissions": ["core:window:allow-close"]
}

権限の構文

権限は次の命名規則に従います。

パターン	説明
<plugin>:default	プラグインのデフォルト権限セット
<plugin>:allow-<command>	特定のコマンドを許可
<plugin>:deny-<command>	特定のコマンドを拒否

コア権限

{
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:window:allow-set-title",
    "core:window:allow-close",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default"
  ]
}

プラグインの権限

{
  "permissions": [
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "shell:allow-open",
    "dialog:allow-open",
    "dialog:allow-save",
    "http:default",
    "clipboard-manager:allow-read",
    "clipboard-manager:allow-write"
  ]
}

プラットフォーム固有のケイパビリティ

platforms 配列を使って、特定のプラットフォームを対象にします。

デスクトップ専用のケイパビリティ

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "desktop-capability",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": [
    "global-shortcut:allow-register",
    "global-shortcut:allow-unregister",
    "shell:allow-execute"
  ]
}

モバイル専用のケイパビリティ

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    "nfc:allow-scan",
    "biometric:allow-authenticate",
    "barcode-scanner:allow-scan"
  ]
}

プラットフォーム別のケイパビリティファイル

プラットフォーム固有のケイパビリティファイルを作成します。

src-tauri/capabilities/desktop.json：

{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}

src-tauri/capabilities/mobile.json：

{
  "identifier": "mobile-features",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": ["haptics:default", "biometric:default"]
}

リモート API アクセス

リモート URL に Tauri コマンドへのアクセスを許可します（注意して使用してください）。

{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "permissions": ["http:default"]
}

カスタムケイパビリティの例

権限レベルが異なる複数のウィンドウを持つアプリケーションの例です。

src-tauri/capabilities/main.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-window",
  "description": "Full access for main application window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "shell:allow-open",
    "dialog:default",
    "http:default",
    "clipboard-manager:default"
  ]
}

src-tauri/capabilities/settings.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "settings-window",
  "description": "Limited access for settings window",
  "windows": ["settings"],
  "permissions": [
    "core:window:allow-close",
    "core:event:default",
    "fs:allow-read-file",
    "fs:allow-write-file"
  ]
}

src-tauri/capabilities/preview.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "preview-window",
  "description": "Read-only access for preview window",
  "windows": ["preview"],
  "permissions": [
    "core:window:default",
    "core:event:default",
    "fs:allow-read-file"
  ]
}

セキュリティ境界

ケイパビリティは、次のリスクから保護します。

• フロントエンドが侵害された場合の影響
• 意図しないシステムインターフェースの公開
• フロントエンドからバックエンドへの権限昇格

ケイパビリティでは、次のリスクから保護できません。

• 悪意のある Rust コード
• 過度に許容的なスコープ
• WebView の脆弱性

ベストプラクティス

1. 最小権限の原則：各ウィンドウに必要な権限のみを付与します
2. ウィンドウごとに機能を分離：ウィンドウごとに個別の機能ファイルを作成します
3. わかりやすい識別子を使用：機能には明確な名前を付けます（例：main-window、editor-readonly）
4. 機能を文書化：目的を説明する記述を含めます
5. リモートアクセスを確認：リモート URL アクセスの設定を慎重に監査します
6. 権限の境界をテスト：ウィンドウが許可されていない API にアクセスできないことを確認します

スキーマのサポート

生成されたスキーマにより、IDE のオートコンプリートが利用できます。スキーマを機能ファイルで参照します：

{
  "$schema": "../gen/schemas/desktop-schema.json"
}

ビルド後に利用可能なスキーマ：

• desktop-schema.json - デスクトッププラットフォーム
• mobile-schema.json - モバイルプラットフォーム
• remote-schema.json - リモートアクセス機能

トラブルシューティング

権限拒否エラー

機能に必要な権限が含まれており、正しいウィンドウラベルを対象としていることを確認してください。

機能が適用されない

機能ファイルが src-tauri/capabilities/ にあるか、tauri.conf.json に明示的に記載されていることを確認してください。

ウィンドウラベルの不一致

機能で指定するウィンドウラベルは、Rust コードでウィンドウを作成するときに定義したラベルと一致している必要があります。ラベルでは大文字と小文字が区別されます。