Tauri 2 desktop app, least privilege

# AGENTS.md: Tauri 2 desktop app

Tauri 2 app: a web frontend (in `src/`) and a Rust core (in `src-tauri/`). The frontend is untrusted; the Rust side
decides what it may do.

## Commands
- Dev: `npm run tauri dev` (or the project's package manager). Build: `npm run tauri build`.
- Rust checks, from `src-tauri/`: `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`.
- Frontend checks: the project's lint, type-check and test scripts.
- Permissions check after any change to capabilities or `tauri.conf.json`:
  `node <skills dir>/tauri-permissions/scripts/check-capabilities.mjs src-tauri`.

## Security model
- Capabilities in `src-tauri/capabilities/` grant permissions to named windows. Grant the minimum; use the
  `tauri-permissions` skill for any change.
- Never `"windows": ["*"]` on a capability that grants file system, shell or HTTP access. Name the windows.
- File system and HTTP permissions always carry a scope (`allow` paths such as `$APPDATA/**`, or exact URLs).
- No `shell:allow-execute` or `shell:allow-spawn` unless the human asks; prefer `shell:allow-open` or the opener plugin.
- Keep a Content Security Policy in `app.security.csp`. Never set it to null to make something load.
- Remote URLs (`remote.urls`) get no command access unless the human approves each one.

## Commands (Rust)
- `#[tauri::command]` functions validate every argument. Paths from the frontend are resolved and checked against an
  allowed base directory before use. Return `Result<T, String>` or a serialisable error type, never panic.
- Long work runs async or on a background thread; the UI must not freeze.
- Secrets live in the Rust side or the OS keychain, never in frontend code or `localStorage`.

## Changes
- Adding a plugin: `npm run tauri add <plugin>`, then grant only the permissions you use and justify each in the report.
- Do not upgrade Tauri, plugins or the webview target as part of another change.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `tauri-permissions`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Tauri 2 desktop app, least privilege" v1.0.0 — https://loadout.jnw-it.com/loadouts/tauri-desktop-app/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `tauri-permissions`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Tauri 2 desktop app, least privilege" v1.0.0 — https://loadout.jnw-it.com/loadouts/tauri-desktop-app/ -->

---
name: tauri-permissions
description: Add or change Tauri 2 capabilities with least privilege (named windows, scoped fs and http permissions, no broad shell access, CSP kept) and run the capability check. Use when a feature needs a new plugin or permission.
---

# Tauri permissions

1. Name the exact API the feature needs (for example "read one JSON file in the app data folder").
2. Find the narrowest permission for it in the plugin's permission list (in `src-tauri/gen/schemas/` after a build, or
   the plugin docs). Prefer a single `allow-<command>` permission to a plugin's `default` set.
3. Add it to a capability file for the named window, with a scope:

       { "identifier": "fs:allow-read-text-file", "allow": [{ "path": "$APPDATA/settings.json" }] }

4. Do not widen an existing capability's windows. If another window needs it, add a second capability.
5. Run the check: `node scripts/check-capabilities.mjs src-tauri`. It fails on wildcard windows with sensitive
   permissions, unscoped fs or http permissions, shell execute or spawn, remote URLs with commands, and a missing or
   null CSP. Fix every finding, or explain to the human why it is needed and get approval.
6. Run the app and use the feature once. Report the permissions added and why each is needed.

#!/usr/bin/env node
// Least-privilege check for Tauri 2 capabilities. Usage: node check-capabilities.mjs <src-tauri dir>
// Exit 1 with one line per finding; exit 0 and "ok" when clean. Reads JSON capability files and tauri.conf.json only.
import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] ?? "src-tauri";
const findings = [];
const SENSITIVE = /^(fs|shell|http|process|sql|store|websocket|upload):/;
const NEEDS_SCOPE = /^(fs|http):/;
const SHELL_EXEC = /^shell:(allow-execute|allow-spawn|allow-stdin-write|default)$/;

const readJson = (p) => {
  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (e) { findings.push(`${p}: not valid JSON (${e.message})`); return null; }
};

const conf = readJson(path.join(root, "tauri.conf.json"));
const inline = conf?.app?.security?.capabilities?.filter((c) => typeof c === "object") ?? [];
if (conf && !conf.app?.security?.csp) findings.push("tauri.conf.json: app.security.csp is missing or null; keep a Content Security Policy");

const capDir = path.join(root, "capabilities");
const files = fs.existsSync(capDir) ? fs.readdirSync(capDir).filter((f) => f.endsWith(".json")) : [];
const caps = [
  ...files.map((f) => ({ where: `capabilities/${f}`, cap: readJson(path.join(capDir, f)) })),
  ...inline.map((c, i) => ({ where: `tauri.conf.json capability #${i + 1}`, cap: c })),
].filter((x) => x.cap);

for (const { where, cap } of caps) {
  const perms = (cap.permissions ?? []).map((p) => (typeof p === "string" ? { identifier: p } : p));
  const wildcard = (cap.windows ?? []).includes("*") || (cap.webviews ?? []).includes("*");
  for (const p of perms) {
    const id = p.identifier ?? "";
    if (wildcard && SENSITIVE.test(id)) findings.push(`${where}: ${id} granted to every window ("*"); name the windows`);
    if (SHELL_EXEC.test(id)) findings.push(`${where}: ${id} lets the frontend run programs; use shell:allow-open or the opener plugin`);
    const scoped = (p.allow ?? []).length > 0;
    const isScopeOnly = /:scope/.test(id);
    if (NEEDS_SCOPE.test(id) && !scoped && !isScopeOnly) findings.push(`${where}: ${id} has no "allow" scope; limit it to the paths or URLs you need`);
  }
  if (cap.remote?.urls?.length && perms.length) findings.push(`${where}: remote URLs ${cap.remote.urls.join(", ")} get ${perms.length} permission(s); needs explicit approval`);
}

if (findings.length) {
  for (const f of findings) console.log(`finding: ${f}`);
  console.log(`${findings.length} finding(s) in ${caps.length} capability set(s)`);
  process.exit(1);
}
console.log(`ok: ${caps.length} capability set(s), least privilege`);