# authforge-gnome-integration

Optional integration glue that surfaces the AuthForge GUI from inside
`gnome-control-center`'s **Users** panel, so administrators and end users can
reach FIDO2/U2F/TOTP enrollment from the same place they already manage
account password and login options.

## What this package ships

A single XDG `.desktop` file installed to
`/usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop`.

The file is tagged with `X-GNOME-Settings-Panel=user-accounts`, which is the
mechanism `gnome-control-center` (GNOME 46 / 47) uses to discover third-party
"helpers" for a specific settings panel. Entries with this key appear inside
the Users panel as an inline launcher rather than as a top-level app.

`NoDisplay=true` keeps the entry out of the normal application grid — the
full-fat AuthForge launcher (shipped by `authforge-gui`) already handles that
case. This overlay exists *only* to provide the in-Settings hook.

`OnlyShowIn=GNOME;` prevents KDE / Xfce / etc. from picking the entry up.
Those desktops have their own settings frameworks and their own integration
stories (out of scope for v1).

## Why a `.desktop` overlay and not a JS extension?

A GNOME Shell / `gnome-control-center` JS extension could in theory inject a
richer widget directly into the Users panel. We considered it and chose the
`.desktop` overlay instead because:

- **Cross-version stability.** The internal panel layout and JS API change
  between GNOME releases (44 → 45 → 46 → 47 all moved things). A `.desktop`
  hook is a stable freedesktop-spec mechanism that has worked unchanged for
  years.
- **Packaging simplicity.** No GJS source, no shell-extension manifest, no
  per-version compatibility matrix. Just a file in
  `/usr/share/applications/`.
- **Lowest-risk.** A miswritten extension can crash the whole shell. A
  miswritten `.desktop` file is a no-op.

JS-extension support is therefore **deferred** until upstream GNOME exposes
a stable cross-version "embed a third-party page in the Users panel" API. If
that ever lands we can ship it as a follow-up package; the `.desktop` overlay
will continue to work alongside it as a graceful-degradation fallback.

## Verifying the integration works

After installing `authforge-gnome-integration` (which depends on
`authforge-gui` and `gnome-control-center`):

1. Log out and back in (or `killall gnome-shell` on X11) to refresh the
   desktop-file cache, *or* run
   `update-desktop-database /usr/share/applications`.
2. Open **Settings** (`gnome-control-center`).
3. Navigate to **Users**.
4. Select a user account. The detail pane should now show a
   **"Configure security…"** entry alongside the existing password / autologin
   controls. Activating it launches the AuthForge GUI.

If the entry does not appear, sanity-check with:

```
desktop-file-validate /usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop
gtk-launch io.dangerousthings.AuthForge.UsersPanel
```

The first command must report no errors; the second must launch the GUI.

## Files

- `io.dangerousthings.AuthForge.UsersPanel.desktop` — the overlay entry,
  installed to `/usr/share/applications/` by the deb.