desktopsecrets

README

🔐 DesktopSecrets

DesktopSecrets is a lightweight, secure utility that centralizes secret management for developers and power users on the desktop. It integrates with KeePass and local user-provided secrets to make retrieving credentials simple, scriptable, and safe, while minimizing repeated password prompts through configurable caching. Designed for workflows that require environment templating and command-line automation, DesktopSecrets helps you keep sensitive data out of source files and streamline local development and deployment tasks.

---

✨ Features

• 🔑 KeePass Integration – Retrieve secrets from KeePass vaults using flexible path and wildcard matching.
• 🧩 Secret References – A unified syntax for referencing secrets from any provider.
• 🔁 Recursive Aliases – Define reusable secret references.
• 💾 Smart Caching – Unlocked vaults stay accessible for a configurable duration.
• ⚙️ Easy Configuration – GUI settings menu in the taskbar icon and simple YAML files.

---

🔌 Secret References

A Secret Reference is an expression that resolves to a secret value.
Examples:

keepass(C:\Vaults\cloud.kdbx|/AWS/Prod/api-key)
user(Enter API key)

Aliases expand recursively into other secret references.

---

🔑 KeePass Provider

The KeePass provider retrieves secrets from .kdbx vaults.
It supports:

• absolute paths
• wildcard paths (* = one level, ** = any depth)
• escaped slashes (\/)
• attribute selection
• chaining

Basic Format

SECRET_NAME=keepass(VAULT|ENTRY)

• VAULT – Path to a KeePass database file (or alias)
• ENTRY – Title or path pattern

Entry Lookup Rules

1. Bare titles

If the entry does not start with /, it is treated as:

**/<title>

Example:

keepass(vault.kdbx|api-key)

Searches for any entry named api-key anywhere in the tree.

2. Absolute paths

keepass(vault.kdbx|/AWS/Prod/api-key)

Matches exactly that path.

3. Wildcards

• * matches one group level
• ** matches zero or more group levels

Examples:

keepass(vault.kdbx|/AWS/*/api-key)
keepass(vault.kdbx|/AWS/**/api-key)

4. Escaped slashes

keepass(vault.kdbx|/AWS/Prod/My\/Key)

Matches an entry titled My/Key.

5. Attribute selection

keepass(vault.kdbx|/AWS/Prod/api-key|UserName)
keepass(vault.kdbx|/AWS/Prod/api-key|URL)
keepass(vault.kdbx|/AWS/Prod/api-key|Notes)
keepass(vault.kdbx|/AWS/Prod/api-key|customField)

Attribute names are case-sensitive. If omitted, the default attribute is the Password.

---

👤 User Provider

Prompts the user to manually enter a secret value.

SECRET_NAME=user(Title shown in prompt)

---

☁️ AWS Provider

Retrieves secrets from AWS Secrets Manager (awssm) and AWS Parameter Store (awsps).

Uses the standard AWS credential chain — no extra configuration needed:

• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN env vars
• ~/.aws/credentials + ~/.aws/config (respects AWS_PROFILE, AWS_DEFAULT_REGION)
• IAM instance roles, ECS task roles, Web Identity tokens

Resolved values are cached in-memory for the configured TTL (same as KeePass).

AWS Secrets Manager

# Raw string secret
API_KEY=awssm(MyApp/ApiKey)

# JSON field extraction
DB_USER=awssm(MyApp/DB|username)
DB_PASS=awssm(MyApp/DB|password)

AWS Parameter Store

SecureString parameters are always decrypted automatically.

# Parameter value
API_KEY=awsps(/myapp/prod/api-key)

# JSON field extraction
DB_HOST=awsps(/myapp/prod/db|host)

---

🪟 Windows Credential Manager Provider (Windows only)

Retrieves secrets from the Windows Credential Manager — the built-in credential store accessible via Control Panel › Credential Manager.

Create entries with cmdkey or the GUI:

cmdkey /generic:"MyApp/DBPassword" /user:"myuser" /pass:"mysecret"

Format

SECRET_NAME=wincred(TARGET)              # password field (default)
SECRET_NAME=wincred(TARGET|password)     # password field (explicit)
SECRET_NAME=wincred(TARGET|username)     # username field

• TARGET — The credential target name used when storing the credential
• Field — password (default) or username

Example

DB_PASSWORD=wincred(MyApp/DBPassword)
DB_USER=wincred(MyApp/DBPassword|username)

No master password or TTL needed — access is transparent as long as you are logged into Windows.

---

🔁 Aliases

Aliases are defined in aliases.yaml.

Example:

cloud: 
  file: C:\Vaults\cloud.kdbx 
  master: keepass(&personal|Cloud Master Password)
personal: C:\Vaults\personal.kdbx

Usage:

MAPS_API_KEY=keepass(&cloud|/Google/Prod/api-key) 
CLAUDE_API_KEY=keepass(&personal|Claude Code API key)

---

🔗 Chaining

KeePass vaults can be unlocked using secrets retrieved from other providers.

Example:

SECRET=keepass(VAULT_A[keepass(VAULT_B|MasterPassword)]|/Prod/api-key)

This:

1. Resolves the inner secret reference
2. Uses it as the master password for VAULT_A
3. Retrieves the final entry

Chaining works with all lookup modes, including wildcards and aliases.

---

🚀 Commands

📄 tplenv

Resolves secrets inside one or more .env.tpl files.

Example:

DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET=keepass($USERPROFILE\Credentials.kdbx|api-key)
LOG_LEVEL=debug

tplenv prints the fully resolved environment.
Use tplenv run to execute a command with resolved variables injected.

---

🛠️ getsec

Resolves a single secret reference passed directly as an argument.

Example:

getsec "API_SECRET=keepass($USERPROFILE\Credentials.kdbx|api-key)"

---

⚙️ Configuration

Settings are accessible via the taskbar icon.

Default Configuration Locations

• macOS: ~/Library/Application Support/desktop-secrets
• Linux: $XDG_CONFIG_HOME/desktop-secrets or ~/.config/desktop-secrets
• Windows: %APPDATA%\desktop-secrets

Environment Overrides

• DESKTOP_SECRETS_CONFIG_FILE
• DESKTOP_SECRETS_ALIASES_FILE
• DESKTOP_SECRETS_KEYFILES_FILE

---

🛠️ Build

Prerequisites

• Go installed and configured

Build from Source

Windows:

go build -o tplenv.exe ./cmd/tplenv
go build -o getsec.exe ./cmd/getsec

Linux:

go build -o tplenv ./cmd/tplenv
go build -o getsec ./cmd/getsec

Usage as library

go get github.com/it-atelier-gn/desktop-secrets

import (
  "os"
  desktopsecrets "github.com/it-atelier-gn/desktop-secrets"
)

func main() {
  // Required: allows this binary to be re-launched as the secrets daemon.
  if desktopsecrets.Init() {
    os.Exit(0)
  }

  secret, err := desktopsecrets.ResolveSecret("user(DB Password)")
  if err != nil {
    panic(err)
  }
  println(secret)
}

Documentation

Index

• func Init() bool
• func ResolveSecret(ref string) (string, error)

Functions

func Init

func Init() bool

Init checks if the process was launched as a daemon and runs it if so. Library users must call this at the top of main() and return if it returns true.

func ResolveSecret

func ResolveSecret(ref string) (string, error)