2

Sensitive Variables

Pavel Baksy edited this page 2026-01-13 16:59:00 +01:00

Table of Contents

• Sensitive Variables
• Overview
• How It Works
• Storage Comparison
• Usage
• Mark Variable as Sensitive
• Enter Secret Values
• Use in Requests
• Viewing Secrets in Keyring
• Making Variables Non-Sensitive
• Security
• Automatic Cleanup
• Script Integration
• Reading Sensitive Variables
• Writing Sensitive Variables
• Troubleshooting
• Platform Notes
• Next Steps

Sensitive Variables

Sensitive variables provide secure storage for API keys, passwords, and tokens using GNOME Keyring encryption instead of plain text files.

Overview

Regular Variables are stored in plain text JSON files at ~/.local/share/cz.bugsy.roster/requests.json. This is fine for non-sensitive data like base URLs or timeout values, but dangerous for secrets.

Sensitive variables solve this by storing values encrypted in GNOME Keyring, the same secure storage used by:

• Firefox and GNOME Web for passwords
• Evolution for email credentials
• Network Manager for WiFi passwords
• SSH for key passphrases

How It Works

Storage Comparison

Regular Variable (Insecure):

File: ~/.local/share/cz.bugsy.roster/requests.json
Format: Plain text (anyone can read)
Content: "api_key": "secret-abc123-visible-to-all"

Sensitive Variable (Secure):

File: ~/.local/share/cz.bugsy.roster/requests.json
Format: Plain text
Content: "api_key": ""  (empty placeholder)

Keyring: GNOME Keyring (encrypted)
Format: Encrypted with your login password
Content: "secret-abc123-visible-to-all"  (encrypted at rest)

Usage

Mark Variable as Sensitive

Open the Environments dialog for your project.

Each variable row has a lock icon to toggle between secure/insecure storage.

Before entering secrets (recommended):

1. Create variable (e.g., api_key)
2. Click the lock icon - it changes to locked state
3. Variable name becomes bold and colored
4. Enter your secret value

After entering secrets (migration):

1. Click the lock icon on existing variable
2. Values automatically move from JSON to keyring

Enter Secret Values

Values in sensitive variables:

• Display as bullets (••••••) instead of characters
• Automatically save to GNOME Keyring (encrypted)

Use in Requests

Sensitive variables work exactly like regular variables:

GET {{base_url}}/users
Authorization: Bearer {{api_key}}

When you send the request:

1. Roster retrieves api_key from GNOME Keyring
2. Decrypts it using your login password
3. Substitutes it into the request
4. Sends the request with the real value

Viewing Secrets in Keyring

Open "Passwords and Keys" (Seahorse) and navigate to "Login" keyring. Look for entries labeled Roster: ProjectName/EnvironmentName/VariableName.

You can view, edit, or delete secrets from Seahorse (requires authentication).

Making Variables Non-Sensitive

If you marked a variable as sensitive by mistake:

1. Click the lock icon again
2. Icon changes from locked to unlocked
3. Values move from keyring back to JSON
4. You can now see values in plain text

Warning: Only do this for non-sensitive data! Once moved to JSON, the values are visible to anyone who can read your files.

Security

• Encrypted at rest with your GNOME login password
• Keyring unlocks automatically on login
• Only accessible by your user account
• Flatpak requires explicit permission

Automatic Cleanup

Roster automatically removes keyring secrets when you delete variables, environments, or projects. Renamed variables are also automatically updated in the keyring.

Script Integration

Scripts can access sensitive variables transparently:

Reading Sensitive Variables

// Preprocessing script
const apiKey = roster.getVariable('api_key');  // Retrieved from keyring
request.headers['X-API-Key'] = apiKey;
console.log('Using API key');  // DON'T log the actual value!

Writing Sensitive Variables

// Postprocessing script
const data = JSON.parse(response.body);

// If 'access_token' is marked as sensitive, it goes to keyring
roster.setVariable('access_token', data.access_token);
console.log('Saved access token to keyring');

Scripts don't need to know whether variables are sensitive - storage is handled automatically.

Troubleshooting

Keyring not unlocked:

• Ensure you're logged into GNOME (keyring unlocks automatically)
• Manual unlock: Open Seahorse, right-click "Login", select "Unlock"

Flatpak permission denied:

• Verify cz.bugsy.roster.json includes --talk-name=org.freedesktop.secrets
• Check: flatpak info --show-permissions cz.bugsy.roster

Secrets missing after reinstall:

• Keyring persists across installs - check Seahorse under "Login" keyring

Platform Notes

Both native and Flatpak installations use the same system keyring. Secrets work across install methods.

Flatpak requires D-Bus permission: --talk-name=org.freedesktop.secrets

Next Steps

• Variables - Learn about regular variables
• Scripts - Use variables in automation scripts
• API-Reference - Complete JavaScript API documentation