detached a2a281e

docs(permission): add permissions documentation page

Add comprehensive documentation for the website permission system:
- Explain auto-allowed vs user-confirmed permissions
- Document the permission dialog options
- Describe origin-based storage and W3C compliance
- Add troubleshooting section
- Link from reference index
commit
a2a281e33d796cc7f23ce0e1cef6177e320dc52b
author
brice · · 2026-01-30 05:02 UTC
committer
brice · · 2026-02-07 11:58 UTC
parent
bf18ec0
signature
GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email
2 files · +89 -0
Unified
UnifiedSplit
M docs/reference/index.md +1 -0
@@ -3,6 +3,7 @@
33 ## Quick Links
44
55 - [Configuration](./configuration.md) - All config keys
6+- [Permissions](./permissions.md) - Website permission handling (mic, camera, screen sharing)
67 - [Dependencies](./dependencies.md) - System dependencies for Arch and Debian/Ubuntu
78 - [Keybindings](./keybindings.md) - All keyboard shortcuts
89 - [Troubleshooting](./troubleshooting.md) - Common issues and solutions
@@ -3,6 +3,7 @@
3 ## Quick Links3 ## Quick Links
4 4
5 - [Configuration](./configuration.md) - All config keys5 - [Configuration](./configuration.md) - All config keys
6+- [Permissions](./permissions.md) - Website permission handling (mic, camera, screen sharing)
6 - [Dependencies](./dependencies.md) - System dependencies for Arch and Debian/Ubuntu7 - [Dependencies](./dependencies.md) - System dependencies for Arch and Debian/Ubuntu
7 - [Keybindings](./keybindings.md) - All keyboard shortcuts8 - [Keybindings](./keybindings.md) - All keyboard shortcuts
8 - [Troubleshooting](./troubleshooting.md) - Common issues and solutions9 - [Troubleshooting](./troubleshooting.md) - Common issues and solutions
A docs/reference/permissions.md +88 -0
@@ -0,0 +1,88 @@
1+# Website Permissions
2+
3+Dumber handles website permission requests for media access (microphone, camera, screen sharing) following W3C standards.
4+
5+## Permission Types
6+
7+### Auto-Allowed
8+
9+These permissions are automatically granted without user interaction:
10+
11+- **Display Capture** (screen sharing) - The XDG Desktop Portal handles the UI
12+- **Device Enumeration** (listing microphones/cameras) - Low security risk
13+
14+### User-Confirmed
15+
16+These permissions require explicit user approval:
17+
18+- **Microphone** - Websites can request audio capture access
19+- **Camera** - Websites can request video capture access
20+- **Microphone + Camera** - Combined requests for both audio and video
21+
22+## Permission Dialog
23+
24+When a site requests mic/camera access, a dialog appears with four options:
25+
26+| Button | Action | Persistence |
27+|--------|--------|-------------|
28+| **Allow** | Grant permission once | Not saved |
29+| **Always Allow** | Grant and remember | Saved per origin |
30+| **Deny** | Block permission once | Not saved |
31+| **Always Deny** | Block and remember | Saved per origin |
32+
33+## How Permissions Work
34+
35+### Origin-Based Storage
36+
37+Permissions are stored per-origin, not per-page. This means:
38+
39+- `https://meet.google.com/room1` and `https://meet.google.com/room2` share the same permission
40+- `https://github.com` and `https://gist.github.com` share the same permission
41+
42+### Permission States
43+
44+- **Granted** - Permission was allowed (manually or via "Always Allow")
45+- **Denied** - Permission was blocked (manually or via "Always Deny")
46+- **Prompt** - No decision made yet, will show dialog on next request
47+
48+### W3C Compliance
49+
50+The permission system follows W3C specifications:
51+
52+- Display capture permissions are **never persisted** (always prompt via portal)
53+- Mic/camera permissions **can be persisted** with user consent
54+- Permissions are scoped to origins (scheme + host)
55+
56+## Managing Stored Permissions
57+
58+Currently, stored permissions can only be cleared by:
59+
60+1. **Site-specific reset**: The site can use `navigator.permissions.revoke()` (if supported)
61+2. **Full reset**: Remove `~/.local/share/dumber/dumber.db` (deletes all data including permissions)
62+
63+A permission management UI is planned for a future release.
64+
65+## Privacy Notes
66+
67+- Permissions are stored in your local SQLite database (`~/.local/share/dumber/dumber.db`)
68+- No permission data is sent to any server
69+- "Always Deny" is useful for blocking persistent permission requests from unwanted sites
70+- The default response is "Deny" (conservative security posture)
71+
72+## Troubleshooting
73+
74+### Permission dialog not appearing
75+
76+1. Check if the site uses HTTPS (required for media permissions)
77+2. Verify the site isn't already in your stored permissions
78+3. Check browser logs: `dumber --log-level=debug`
79+
80+### Permission keeps prompting
81+
82+- Display capture always prompts (W3C requirement)
83+- Check if database is writable: `ls -la ~/.local/share/dumber/`
84+
85+### Site says permission denied but I clicked Allow
86+
87+- Check if you clicked "Deny" or "Always Deny" previously
88+- Clear permissions by removing the database (see above)
@@ -0,0 +1,88 @@
1+# Website Permissions
2+
3+Dumber handles website permission requests for media access (microphone, camera, screen sharing) following W3C standards.
4+
5+## Permission Types
6+
7+### Auto-Allowed
8+
9+These permissions are automatically granted without user interaction:
10+
11+- **Display Capture** (screen sharing) - The XDG Desktop Portal handles the UI
12+- **Device Enumeration** (listing microphones/cameras) - Low security risk
13+
14+### User-Confirmed
15+
16+These permissions require explicit user approval:
17+
18+- **Microphone** - Websites can request audio capture access
19+- **Camera** - Websites can request video capture access
20+- **Microphone + Camera** - Combined requests for both audio and video
21+
22+## Permission Dialog
23+
24+When a site requests mic/camera access, a dialog appears with four options:
25+
26+| Button | Action | Persistence |
27+|--------|--------|-------------|
28+| **Allow** | Grant permission once | Not saved |
29+| **Always Allow** | Grant and remember | Saved per origin |
30+| **Deny** | Block permission once | Not saved |
31+| **Always Deny** | Block and remember | Saved per origin |
32+
33+## How Permissions Work
34+
35+### Origin-Based Storage
36+
37+Permissions are stored per-origin, not per-page. This means:
38+
39+- `https://meet.google.com/room1` and `https://meet.google.com/room2` share the same permission
40+- `https://github.com` and `https://gist.github.com` share the same permission
41+
42+### Permission States
43+
44+- **Granted** - Permission was allowed (manually or via "Always Allow")
45+- **Denied** - Permission was blocked (manually or via "Always Deny")
46+- **Prompt** - No decision made yet, will show dialog on next request
47+
48+### W3C Compliance
49+
50+The permission system follows W3C specifications:
51+
52+- Display capture permissions are **never persisted** (always prompt via portal)
53+- Mic/camera permissions **can be persisted** with user consent
54+- Permissions are scoped to origins (scheme + host)
55+
56+## Managing Stored Permissions
57+
58+Currently, stored permissions can only be cleared by:
59+
60+1. **Site-specific reset**: The site can use `navigator.permissions.revoke()` (if supported)
61+2. **Full reset**: Remove `~/.local/share/dumber/dumber.db` (deletes all data including permissions)
62+
63+A permission management UI is planned for a future release.
64+
65+## Privacy Notes
66+
67+- Permissions are stored in your local SQLite database (`~/.local/share/dumber/dumber.db`)
68+- No permission data is sent to any server
69+- "Always Deny" is useful for blocking persistent permission requests from unwanted sites
70+- The default response is "Deny" (conservative security posture)
71+
72+## Troubleshooting
73+
74+### Permission dialog not appearing
75+
76+1. Check if the site uses HTTPS (required for media permissions)
77+2. Verify the site isn't already in your stored permissions
78+3. Check browser logs: `dumber --log-level=debug`
79+
80+### Permission keeps prompting
81+
82+- Display capture always prompts (W3C requirement)
83+- Check if database is writable: `ls -la ~/.local/share/dumber/`
84+
85+### Site says permission denied but I clicked Allow
86+
87+- Check if you clicked "Deny" or "Always Deny" previously
88+- Clear permissions by removing the database (see above)

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 8

Tags 42

↑↓ moveenter openesc close