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 vaults, AWS Secrets Manager, AWS Parameter Store, Windows Credential Manager, and local user-provided prompts 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.
• ☁️ AWS Integration – Pull secrets from AWS Secrets Manager and AWS Parameter Store with JSON field extraction.
• 🪟 Windows Credential Manager – Access credentials stored in the built-in Windows vault (Windows only).
• 🧩 Secret References – A unified syntax for referencing secrets from any provider.
• 🔁 Recursive Aliases – Define reusable secret references.
• 💾 Smart Caching – Unlocked vaults and resolved secrets 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)
awssm(MyApp/DB|password)
awsps(/myapp/prod/api-key)
wincred(MyApp/DBPassword)
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)