# Password Management Infrastructure

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│             Bitwarden Vault ───────────╮                  │
│        bitwarden.jantec.xyz            │ Central store   │
│             (cloud)                    │  + backup       │
│                                        │                 │
│  ┌─────────────────┐                  │                 │
│  │   rbw CLI  ─────┼─── sync/login ───┘                 │
│  │ (Rust client)   │   Add/edit/search                  │
│  └────────────────┘                                    │
│           │                                              │
│  ┌────────V────────              ┌──────────────────┐  │
│  │ gnome-keyring   │────────────►│ Applications     │  │
│  │ (libsecret)     │  D-Bus       │ himalaya, git,   │  │
│  │ org.freedesktop.│  Secrets API │ SSH, browsers,   │  │
│  │ secrets         │              │ IDEs             │  │
│  └─────────────────┘              └──────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

## Components

### 1. gnome-keyring (local D-Bus secret service)

- Provides `org.freedesktop.secrets` D-Bus interface
- Started as systemd user service via socket activation
- Unlocks on login (PAM integration with greetd/tuigreet)
- Stores credentials that apps access via `libsecret` (`secret-tool`)

| Unit | Status |
|------|--------|
| `~/.config/systemd/user/gnome-keyring-daemon.socket` | enabled |
| `~/.config/systemd/user/gnome-keyring-daemon.service` | enabled |

### 2. rbw (Bitwarden CLI)

- Unofficial Bitwarden CLI written in Rust
- Connects to `https://bitwarden.jantec.xyz`
- Uses gnome-keyring as its encrypted password store (via `pinentry`)
- Manages vault: `rbw add`, `rbw get`, `rbw list`, `rbw search`, `rbw sync`

| Config | Value |
|--------|-------|
| `~/.config/rbw/config.json` | `{"email": "ironmikechw+bitwarden@gmail.com", "base_url": "https://bitwarden.jantec.xyz"}` |
| API Keys | Stored in `~/.config/rbw/` (registered via `rbw register`) |
| Vault sync | Automatic via `rbw sync` (interval: 3600s) |

### 3. SSH Key Passphrases

- Stored in gnome-keyring (libsecret) for `ssh-add` via `gnome-keyring-ssh` PAM module
- Passphrases stored under `application=ssh-agent`, `service=ssh`, `ssh-key=<path>`
- Keys migrated from KWallet: `id_ed25519`, `id_ed25519_ja_manjaro`

### 4. Git Credentials

- **Global helper**: `libsecret` (stores in gnome-keyring instead of `~/.git-credentials` plaintext)
- **GitHub**: `gh auth git-credential` helper (for github.com)
- **GitLab**: configured as `provider = generic` in `.gitconfig` for gitlab.satware.com

### 5. Application Credentials Map

| Application | Storage | Mechanism |
|-----------|---------|-----------|
| himalaya (email) | gnome-keyring + Bitwarden | `secret-tool lookup email <address>` |
| ssh-agent | gnome-keyring | D-Bus secret service |
| git (global) | gnome-keyring (`libsecret`) | `git config credential.helper libsecret` |
| GitHub CLI | Bitwarden + gnome-keyring | `rbw get "GitHub Personal Token"` + GK entry |
| GitLab | gnome-keyring | `secret-tool lookup application git service gitlab.satware.com` |
| Chrome/Brave/Chromium | gnome-keyring | Safe Storage encryption keys |
| JetBrains IDEs | gnome-keyring | D-Bus secret service auto-detection |
| Remmina | gnome-keyring + Bitwarden | VNC/RDP passwords |
| Nextcloud | gnome-keyring + Bitwarden | Instance passwords |
| QGIS | gnome-keyring + Bitwarden | Master password |

## Startup / Unlock Flow

```
1. greetd/tuigreet login → PAM auth
2. PAM → gnome-keyring PAM module (pam_gnome_keyring.so)
3. Keyring unlocked with login password
4. gnome-keyring-daemon starts (socket activation)
5. D-Bus org.freedesktop.secrets available
6. rbw login → decrypts vault via gnome-keyring
7. himalaya can read IMAP passwords via secret-tool
8. ssh-add can read SSH passphrases via GK
9. git-credential-libsecret reads Git creds via GK
```

## Migration History

- **Before**: KDE Wallet (kwalletd) — no auto-unlock under greetd, no D-Bus support for non-Plasma apps
- **After**: gnome-keyring + rbw + Bitwarden.vault → full D-Bus secret service + central vault + CLI access

## Manual Entry Required

### himalaya Email Passwords

The following email account passwords need to be stored in gnome-keyring (they were NOT in KWallet):

```bash
# Store MW account
echo "<PASSWORD>" | secret-tool store --label="IMAP MW" email mw@satware.com application himalaya

# Store JA account
echo "<PASSWORD>" | secret-tool store --label="IMAP JA" email ja@satware.ai application himalaya

# Store JA Gmail
echo "<PASSWORD>" | secret-tool store --label="IMAP JA Gmail" email ja.satware@gmail.com application himalaya

# Store Michael Gmail
echo "<PASSWORD>" | secret-tool store --label="IMAP Michael Gmail" email ironmikechw@gmail.com application himalaya
```

## Useful Commands

```bash
# Bitwarden operations
rbw list                              # list all vault entries
rbw search <term>                     # search vault
rbw get <name>                        # get password (truncates on display)
rbw get --full "GitHub Personal Token" # get full password (piped)
rbw sync                              # sync with vault
rbw add "Service Name"                # add new entry (opens $EDITOR)

# gnome-keyring operations
secret-tool lookup email mw@satware.com              # lookup by attribute
secret-tool search application ssh-agent             # search
secret-tool store --label="Test" key value           # store (pipe data)
dbus-send --session --print-reply --dest=org.freedesktop.secrets \
  /org/freedesktop/secrets/collection/default         # low-level D-Bus

# Verify startup
systemctl --user status gnome-keyring-daemon.socket
systemctl --user status gnome-keyring-daemon.service

# Quick health check
rbw unlocked && echo "BW: unlocked" || echo "BW: locked"
secret-tool lookup application ssh-agent service ssh ssh-key /home/mw/.ssh/id_ed25519 && echo "GK: SSH OK"
```

## Troubleshooting

### gnome-keyring not providing secrets on D-Bus
```bash
systemctl --user restart gnome-keyring-daemon.service
```

### rbw not unlocked
```bash
rbw unlock         # prompts for login password
rbw login          # prompts for Bitwarden password
```

### SSH keys not auto-unlocking
```bash
# Check GK entry
secret-tool lookup application ssh-agent service ssh ssh-key /home/mw/.ssh/id_ed25519
# If missing, re-add:
echo "<PASSPHRASE>" | secret-tool store --label="SSH id_ed25519" \
  application ssh-agent service ssh ssh-key /home/mw/.ssh/id_ed25519
```

### GitLab/GitHub creds not working
```bash
# Test GK
secret-tool lookup application git service gitlab.satware.com
```

### himalaya password errors
```bash
# Verify GK
secret-tool lookup email mw@satware.com
# Re-enter password from Bitwarden
rbw get "himala mw@satware.com" | secret-tool store --label="IMAP mw@satware.com" \
  email mw@satware.com application himalaya
```

## Security Note

- Bitwarden vault: self-hosted at `bitwarden.jantec.xyz`
- Local cache: gnome-keyring (encrypted, session-bound)
- No plaintext passwords in config files
- `~/.git-credentials` removed on `git config --global credential.helper store`