tauri-plugin-permission-flow 0.1.40

Tauri bindings for the permission-flow macOS permission UI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Tauri Plugin permission-flow

[![CI](https://github.com/veecore/permission-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/veecore/permission-flow/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/tauri-plugin-permission-flow.svg)](https://crates.io/crates/tauri-plugin-permission-flow)
[![docs.rs](https://img.shields.io/docsrs/tauri-plugin-permission-flow)](https://docs.rs/tauri-plugin-permission-flow)

Tauri bindings for the `permission-flow` macOS permission UI.

The plugin is designed for macOS, but it compiles in cross-platform Tauri
workspaces too. Outside macOS, controller creation still succeeds, flow
commands become no-ops, and host-app status resolves to `unknown`.

![permission-flow demo](https://raw.githubusercontent.com/veecore/permission-flow/main/assets/demo-readme.gif)

## What you get

The Tauri package gives you two layers:

- `PermissionFlow`: a handle-backed controller for opening the floating
  permission guidance UI
- `authorizationState(...)` and `watchAuthorizationStatus(...)`: host-app
  status helpers for reflecting permission state in your frontend

Use the controller when you want to start the flow. Use the status helpers when
you want your UI to react to the current host app's permission state.

## Install

Add the Rust plugin in your Tauri app's `src-tauri/Cargo.toml`:

```toml
[dependencies]
tauri-plugin-permission-flow = "0.1.40"
```

Register it in your Tauri builder:

```rust
tauri::Builder::default()
    .plugin(tauri_plugin_permission_flow::init())
```

Add the JavaScript package:

```json
{
  "dependencies": {
    "@veecore/tauri-plugin-permission-flow-api": "0.1.40"
  }
}
```

Because the final macOS executable links the Swift runtime, add this to your
app's `src-tauri/build.rs`:

```rust
fn main() {
    tauri_build::build();

    if std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("macos") {
        println!("cargo:rustc-link-arg=-Wl,-rpath,/usr/lib/swift");
    }
}
```

## Quick start

```ts
import {
  Permission,
  PermissionFlow,
  suggestedHostAppPath,
  watchAuthorizationStatus,
} from '@veecore/tauri-plugin-permission-flow-api'

const flow = await PermissionFlow.create()
const appPath = await suggestedHostAppPath()

if (appPath) {
  await flow.startFlow({
    permission: Permission.Accessibility,
    appPath,
  })
}

const stopWatching = watchAuthorizationStatus(
  Permission.Accessibility,
  (state) => {
    console.log('Current host-app status:', state)
  }
)

stopWatching()
await flow.close()
```

## API shape

`startFlow` accepts:

- `permission`: one of `Permission.Accessibility`, `Permission.InputMonitoring`, `Permission.ScreenRecording`, `Permission.AppManagement`, `Permission.Bluetooth`, `Permission.DeveloperTools`, `Permission.FullDiskAccess`, or `Permission.MediaAppleMusic`
- `appPath`: the app bundle path to suggest inside the permission flow
- `useClickSourceFrame`: optional, defaults to `true`

`suggestedHostAppPath()`:

- returns a best-effort `.app` bundle path for the current launch context
- is a good default for examples, dev builds, IDE-integrated terminals, and
  bundled Tauri apps
- returns `null` when there is no meaningful host app bundle to infer

`watchAuthorizationStatus`:

- immediately publishes the current host-app status by default, even if it was already granted before your app started
- then republishes only when the status actually changes
- refreshes on window focus, on visibility changes, and on a light interval by default
- returns a cleanup function you can call when your UI unmounts

## Example app

The repo includes a tiny demo app under
`crates/tauri-plugin-permission-flow/examples/tauri-app`.

It intentionally stays minimal:

- one permission picker
- one button
- button state driven by the host-app authorization watcher

## Notes

- This plugin is intended for macOS.
- `PermissionFlow` is a Tauri resource handle. It owns one native controller on Tauri's main thread and marshals calls there internally.
- The JS wrapper now adds best-effort garbage-collection cleanup through `FinalizationRegistry`, but `close()` is still the deterministic and recommended cleanup path.
- `authorizationState(...)` and `watchAuthorizationStatus(...)` are host-app status helpers. On macOS, the public permission-status APIs used by `permission-flow` describe the current host app or host process, not an arbitrary `.app` bundle path.
- In other words, `appPath` controls which app bundle appears in the floating guidance flow, but it should not be confused with an authoritative "does that target app already have permission?" check.

## Maintainer Note

The guest package is published from GitHub Actions through npm trusted
publishing. The repository workflow lives at
`.github/workflows/publish-npm.yml`.