roster/SENSITIVE_VARIABLES_UI_GUIDE.md

Sensitive Variables - UI User Guide

Overview

Roster now supports marking variables as sensitive to store their values securely in GNOME Keyring instead of plain text. This guide explains how to use this feature in the UI.

Features

🔒 Lock Icon Toggle

Each variable in the Environments dialog has a lock icon button:

• Unlocked (🔓 channel-insecure-symbolic) - Variable is stored in plain JSON
• Locked (🔒 channel-secure-symbolic) - Variable is stored encrypted in GNOME Keyring

Visual Indicators

1. Lock Icon Color/State

   • Inactive (gray): Non-sensitive variable
   • Active (accent color): Sensitive variable

2. Variable Name Styling

   • Regular variables: Normal text
   • Sensitive variables: Colored with accent color and bold weight

3. Value Entry Fields

   • Regular variables: Show plain text
   • Sensitive variables: Show bullets (••••••) instead of text

How to Use

Step 1: Open Environments Dialog

1. Select a project from the sidebar
2. Click the "Environments" button in the header bar
3. The dialog shows a table with:
   • Rows: Variable names
   • Columns: Environment values

Step 2: Create Variables

If you haven't already:

1. Click the "Add Variable" button (bottom-left)
2. Enter a variable name (e.g., api_key)
3. Click "Add"

Step 3: Mark Variable as Sensitive

Option A: Before Entering Values (Recommended)

1. Find the variable row in the table
2. Click the lock icon next to the variable name
3. Icon changes from 🔓 to 🔒
4. Now enter your secret values - they go directly to keyring

Option B: After Entering Values (Migration)

1. If you already entered sensitive values in plain text
2. Click the lock icon to mark as sensitive
3. Values are automatically moved from JSON to GNOME Keyring
4. JSON file now shows empty placeholders

Step 4: Enter Sensitive Values

1. Click in the value entry field for any environment
2. Type your secret value
3. You'll see bullets (••••••) instead of text
4. Value is automatically saved to GNOME Keyring

Step 5: Use in Requests

Sensitive variables work exactly like regular variables:

URL: {{base_url}}/users
Headers:
  Authorization: Bearer {{api_key}}

When you send the request, values are automatically retrieved from the keyring and substituted.

UI Walkthrough

Example: Storing a GitHub Token

Before (Insecure - in plain JSON):

Variables Table:
┌─────────────┬──────────────────┬──────────────────┐
│ Variable    │ Production       │ Development      │
├─────────────┼──────────────────┼──────────────────┤
│ base_url 🔓 │ api.github.com   │ api.dev.local    │
│ token 🔓    │ ghp_abc123...    │ ghp_dev456...    │  ← VISIBLE!
└─────────────┴──────────────────┴──────────────────┘

After (Secure - in GNOME Keyring):

Variables Table:
┌─────────────┬──────────────────┬──────────────────┐
│ Variable    │ Production       │ Development      │
├─────────────┼──────────────────┼──────────────────┤
│ base_url 🔓 │ api.github.com   │ api.dev.local    │
│ token 🔒    │ ••••••••••••     │ ••••••••••••     │  ← HIDDEN!
└─────────────┴──────────────────┴──────────────────┘

Tooltips

Hover over the lock icon to see:

• Unlocked: "Not sensitive (stored in JSON) - Click to mark as sensitive"
• Locked: "Sensitive (stored in keyring) - Click to make non-sensitive"

Making a Variable Non-Sensitive Again

If you accidentally marked a variable as sensitive:

1. Click the lock icon again (🔒 → 🔓)
2. Values are moved from keyring back to JSON
3. You can now see the values in plain text

Warning: Only do this if the variable truly doesn't contain secrets!

Viewing Secrets in GNOME Keyring

Want to verify your secrets are stored?

1. Open "Passwords and Keys" application (Seahorse)
2. Look under "Login" keyring
3. Find entries labeled: Roster: ProjectName/EnvironmentName/VariableName

Example:

Login Keyring
  └─ Roster: My API Project/Production/api_key
  └─ Roster: My API Project/Development/api_key

Best Practices

✅ DO Mark as Sensitive:

• api_key - API keys
• secret_key - Secret keys
• password - Passwords
• token - Bearer tokens, OAuth tokens
• client_secret - OAuth client secrets
• private_key - Private keys
• Any variable containing credentials

❌ DON'T Mark as Sensitive:

• base_url - API endpoints
• env - Environment names
• region - Cloud regions
• timeout - Timeout values
• version - API versions
• Any non-secret configuration

Workflow Tips

1. Create variables first, then mark as sensitive

   • Add variable
   • Click lock icon
   • Enter values (they go directly to keyring)

2. Use descriptive names

   • ✅ stripe_secret_key
   • ❌ key1

3. Group related variables

   base_url          🔓
   api_key           🔒
   api_secret        🔒
   timeout           🔓
   

4. Audit regularly

   • Check which variables are marked as sensitive
   • Ensure all secrets are locked (🔒)

Troubleshooting

Q: I clicked the lock but it didn't work

A: Check the application logs. The keyring might be locked. Unlock it with your login password.

Q: Can I see my secret values after marking as sensitive?

A: The UI shows bullets (••••••) for security. To view:

• Temporarily unlock (click 🔒 → 🔓)
• Or use "Passwords and Keys" app to view in keyring

Q: What happens if I delete a sensitive variable?

A: Both the JSON entry AND the keyring secret are deleted automatically.

Q: What happens if I rename a sensitive variable?

A: The keyring secret is automatically renamed. No data is lost.

Q: What happens if I delete an environment?

A: All keyring secrets for that environment are deleted automatically.

Q: What happens if I delete a project?

A: ALL keyring secrets for that project are deleted automatically.

Security Notes

• ✅ Secrets are encrypted with your login password
• ✅ Automatically unlocked when you log in
• ✅ Protected by OS-level security
• ✅ Same security as browser passwords, WiFi passwords, SSH keys
• ⚠️ Non-sensitive variables are still in plain JSON
• ⚠️ Mark variables as sensitive BEFORE entering secret values

Keyboard Shortcuts

• Tab: Move between value fields
• Enter: Confirm value (auto-saved)
• Escape: Close dialog

Visual Design

The UI uses the following visual cues:

1. Lock Icon State

   • Gray/inactive = Plain JSON storage
   • Colored/active = Encrypted keyring storage

2. Variable Name Color

   • Sensitive variables have accent color and bold font

3. Password Entry

   • Sensitive variable values show as bullets
   • Same UX as password fields throughout GNOME

4. Consistent with GNOME HIG

   • Follows GNOME Human Interface Guidelines
   • Familiar patterns (lock icon = security)
   • Accessible and keyboard-navigable