mw-pfeddersheim-workstation/docs/product/passwords.md

# Password Management - System Guide

## Architecture

```
┌─────────────────────────────────────┐
│        Bitwarden Vault              │
│     bitwarden.jantec.xyz            │  ← Central, synced, backed up
│         (self-hosted)               │
│                ▲                     │
│          rbw CLI                    │  ← CLI access, add/list/get/search
│     (ironmikechw+bitwarden@gmail.com)│
│                ▲                     │
│    gnome-keyring (local)            │  ← D-Bus secrets API for apps
│    org.freedesktop.secrets         │  ← libsecret, secret-tool
└─────────────────────────────────────
```

## How It Works After Reboot / Login

1. **greetd/tuigreet login** → PAM auth
2. **PAM module** → `pam_gnome_keyring.so` unlocks keyring with login password
3. **gnome-keyring-daemon** starts via socket activation (systemd user service)
4. **D-Bus** `org.freedesktop.secrets` becomes available on session bus
5. **rbw** auto-unlocks via pinentry (reads passphrase from gnome-keyring)
6. **Apps** read secrets via `libsecret` / `secret-tool`:
   - `himalaya` → IMAP/SMTP passwords via `secret-tool lookup email <addr>`
   - `ssh-agent` → SSH key passphrases via `secret-tool lookup ... ssh-key <path>`
   - `git-credential-libsecret` → Git passwords via libsecret
     (github.com via `gh`, gitlab.satware.com via `glab`, **git.satware.ai via libsecret PAT**)
   - `JetBrains IDEs` → auto-detect D-Bus secrets service

## Quick Verification

```bash
# Is gnome-keyring running?
systemctl --user is-active gnome-keyring-daemon.service

# Can rbw access the vault?
rbw list | head -5
rbw get "SSH Key: id_ed25519"  # should return "SSH gitlab.satware.com"

# Can apps read secrets?
secret-tool lookup application ssh-agent service ssh ssh-key /home/mw/.ssh/id_ed25519
secret-tool lookup application git service gitlab.satware.com
secret-tool lookup server git.satware.ai protocol https user mw    # Gitea PAT (git-credential-libsecret schema)
secret-tool lookup application nextcloud service cloud.satware.com user mw
```

## Migrated Entries (from KDE Wallet)

| Category | Entries | Storage |
|----------|---------|---------|
| **SSH passphrases** | id_ed25519, id_ed25519_ja_manjaro | BW + GK |
| **SSH host passwords** | b0t@192.168.0.141 | BW + GK |
| **Git tokens** | GitLab PAT, GitHub token, Gitea PAT (git.satware.ai) | GK (BW pending) |
| **Remmina** | 5 VNC/RDP passwords | BW + GK |
| **Nextcloud** | 3 instance passwords | BW + GK |
| **Browser crypto** | Chrome, Brave, Chromium safe storage | BW + GK |
| **JetBrains** | AI token, Account token | BW (AI also in GK) |
| **QGIS** | Master password | BW + GK |

Total: ~45 entries migrated.

## Known Issues (Post-Reboot)

1. **himalaya email passwords** — Were NOT in KWallet. Need to be re-entered manually:
   ```bash
   # Run once per account after reboot
   rbw get "<entry-name>" | secret-tool store --label="IMAP <name>" email <address> application himalaya
   ```
   Accounts: `mw@satware.com`, `ja@satware.ai`, `ja.satware@gmail.com`, `ironmikechw@gmail.com`

2. **GitHub CLI token** — May need re-auth:
   ```bash
   gh auth login --hostname github.com
   gh auth git-credential store --hostname github.com  # saves to GK
   ```

## Useful Commands

```bash
# Bitwarden
rbw list                    # list all entries
rbw search <term>           # search
rbw get "<name>"            # get password (truncated display)
rbw get --full "<name>"     # get full password
rbw add "<name>"            # add new entry (opens editor)
rbw sync                    # force sync with server
rbw unlock                  # unlock vault (prompts for login password)

# Gnome-keyring
secret-tool lookup key value ...          # lookup by attributes
secret-tool search key value ...           # search
secret-tool store --label="X" key value    # store (pipe password via stdin)

# System
systemctl --user status gnome-keyring-daemon.service
systemctl --user restart gnome-keyring-daemon.service  # if D-Bus secrets missing
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `secret-tool lookup` returns empty | `systemctl --user restart gnome-keyring-daemon.service` |
| `rbw list` fails | `rbw unlock` (enter login password) |
| SSH key asks for passphrase | `secret-tool lookup application ssh-agent service ssh ssh-key /home/mw/.ssh/id_ed25519` — if empty, re-store it |
| `gh` commands fail | `gh auth login --hostname github.com` |
| himalaya auth errors | Re-enter IMAP passwords via `secret-tool store` (see Known Issues) |
| Browser safe storage issues | Browsers recreate their own Safe Storage keys on startup |

## KDE Wallet Status

- Packages still installed (`kwallet`, `kwalletmanager`) — harmless, will be removed after verification
- Data file preserved at `~/.local/share/kwalletd/kdewallet.kwl` (backup)
- PAM references already commented out
- No longer used by any application

## Gitea PAT (git.satware.ai)

- Cached in gnome-keyring via `git credential approve` (schema `org.git.Password`, attributes: `protocol=https, server=git.satware.ai, user=mw`)
- Git reads it via `credential.helper=libsecret` (global; no host-specific `store` override)
- tea reads its own copy from `~/.config/tea/config.yml` (tea has no `auth git-credential` subcommand; file hardened to `chmod 600`)
- Scopes: `write:repository`, `read:user`. Token lacks admin scope - **rotation must be done via web UI** at https://git.satware.ai/user/settings/applications
- TODO (rotate): create new PAT with `write:repository, read:user, write:admin`; store in Bitwarden entry `Gitea PAT: git.satware.ai` + keyring + tea; revoke old token via API (now possible with admin scope); update this section
- TODO (Bitwarden): create Bitwarden entry `Gitea PAT: git.satware.ai` (username `mw`, uri `https://git.satware.ai`) - blocked on rbw pinentry not supporting non-interactive password entry; create manually via `rbw add` or Bitwarden web UI
- Tracked in Gitea issue #1: https://git.satware.ai/infrastructure/mw-pfeddersheim-workstation/issues/1