wincm-cli — Secret Injection aus dem Windows Credential Manager

Sinn & Zweck

wincm löst ein alltägliches Problem: Wie bekommt eine App ihre Passwörter, API-Keys und andere Secrets, ohne sie im Klartext in eine .env-Datei oder in den Code zu schreiben?

wincm liest Secrets sicher aus dem Windows Credential Manager und stellt sie deinem Programm als Umgebungsvariablen zur Verfügung — nur für die Dauer der Ausführung, danach sind sie automatisch wieder aus dem Speicher verschwunden.

Beschreibung

wincm startet dein Programm als Kind-Prozess und gibt ihm die Secrets als process.env.* mit. Deine App braucht dadurch keine Code-Änderung und kein keytar — sie liest einfach process.env.DB_PASSWORD.

┌──────────────────────────────────────────────┐
│ wincm  (Parent-Prozess / "Wächter")           │
│                                                │
│  1. Liest .wincm.json                          │
│  2. Holt Secrets aus Windows Credential Mgr    │
│  3. Startet dein Programm als KIND-Prozess     │
│     und übergibt die Secrets als ENV:          │
│     ┌──────────────────────────────────────┐  │
│     │ node app.js                          │  │
│     │   process.env.DB_PASSWORD ✅         │  │
│     │   (kein keytar, keine Änderung)      │  │
│     └──────────────────────────────────────┘  │
│  4. Lebt nur solange das Kind lebt und         │
│     reicht dessen Exit-Code weiter.            │
└──────────────────────────────────────────────┘

Warum ist das sicher?

• Die Secrets existieren nur im Speicher des Kind-Prozesses.
• Sie landen nicht in deiner Shell-Session und nicht in der Command-History (anders als set DB_PASSWORD=... && node app.js).
• Nach dem Programmende sind sie automatisch weg.
• In der .wincm.json steht nur die Adresse des Secrets, nie der Wert — die Datei kann daher bedenkenlos ins Git.

Aufruf

wincm run -- node app.js

Alles nach -- ist der auszuführende Befehl inklusive seiner Argumente.

Installation

Es gibt zwei Wege, wincm global verfügbar zu machen. Du wählst einen davon — nicht beide kombinieren.

Variante A — npm link (für Entwicklung)

Erstellt einen Symlink vom globalen npm-Verzeichnis zu deinem lokalen Projektordner. Code-Änderungen sind dadurch sofort wirksam.

cd wincm-cli
npm install          # installiert keytar
npm link             # macht "wincm" global verfügbar

• ✅ Änderungen am Code sofort aktiv (kein Neuinstallieren)
• ❌ Verschiebst du den Projektordner, wird der Symlink ungültig → neu linken

Variante B — npm install -g (für produktiven Einsatz)

Kopiert das Package ins globale npm-Verzeichnis. Danach ist es unabhängig vom Quellordner.

npm install -g <pfad-zum-wincm-cli-ordner>

• ✅ Unabhängig vom Quellordner (darf verschoben/gelöscht werden)
• ❌ Bei Code-Änderungen musst du neu installieren

Wichtig: Nach npm install -g brauchst du KEIN npm link mehr.

Ohne Installation (direkter Aufruf)

node bin/wincm.js run -- node app.js

Deinstallation

Je nachdem, wie du installiert hast:

# Wenn per npm link installiert (im Projektordner):
cd wincm-cli
npm unlink

# ODER von überall:
npm unlink -g wincm-cli

# Wenn per npm install -g installiert:
npm uninstall -g wincm-cli

Was passiert mit deinen Secrets im Windows Credential Manager?

• ✅ Nichts. Das Deinstallieren entfernt nur den wincm-Befehl.
• ✅ Alle gespeicherten Credentials bleiben erhalten.
• ✅ Auch die evtl. gesetzte Master-PIN (wincm-cli/master-pin) bleibt liegen.

Willst du die Credentials wirklich entfernen: entweder über wincm delete SERVICE/ACCOUNT oder manuell über die Windows-Suche → „Anmeldeinformationsverwaltung" → „Windows-Anmeldeinformationen" → Einträge einzeln löschen.

Konfiguration: .wincm.json

Lege im Projektverzeichnis deiner App eine .wincm.json an:

{
  "secrets": {
    "DB_PASSWORD": "SERVICE/ACCOUNT",
    "API_KEY": "SERVICE/ACCOUNT"
  }
}

Format pro Eintrag:

"ENV_VAR": "SERVICE/ACCOUNT"
             │       │
             │       └── account im Windows Credential Manager
             └────────── service im Windows Credential Manager

Die Datei wird ausschließlich im aktuellen Verzeichnis gesucht. Alternativ kannst du mit --config <pfad> einen abweichenden Pfad angeben.

Credentials anlegen, ändern und löschen

Du hast zwei Wege, ein Credential in den Windows Credential Manager zu bringen:

1. Direkt über wincm (empfohlen):

# Passwort wird versteckt abgefragt (kein Klartext in der History)
wincm set SERVICE/ACCOUNT

# Oder Passwort direkt als Argument (Achtung: landet in der Shell-History!)
wincm set SERVICE/ACCOUNT geheim123

# Vorhandenes Credential wird beim erneuten set einfach überschrieben.

# Credential wieder löschen
wincm delete SERVICE/ACCOUNT      # Aliase: del, rm

# Prüfen, ob die in der Config referenzierten Credentials existieren
wincm show

# Alle Accounts eines Service auflisten (ohne die Passwort-Werte)
wincm show SERVICE

2. Manuell über die Windows-GUI: Windows-Suche → „Anmeldeinformationsverwaltung" → „Windows-Anmeldeinformationen" → „Generische Anmeldeinformationen hinzufügen".

Egal welchen Weg du wählst — das Adress-Format in der .wincm.json bleibt immer SERVICE/ACCOUNT.

| Speicherweg | Ablage im Credential Manager | Findet wincm? | | ------------------------------------- | -------------------------------------------- | ------------- | | wincm set (via keytar) | TargetName intern: SERVICE/ACCOUNT | ✅ (direkt) | | Programmatisch (keytar.setPassword) | TargetName intern: SERVICE/ACCOUNT | ✅ (direkt) | | Manuell (Windows-GUI) | SERVICE und ACCOUNT als getrennte Felder | ✅ (Fallback) |

Wichtig für die manuelle Anlage: trage im Feld für den Benutzernamen genau den ACCOUNT-Wert ein (Groß-/Kleinschreibung und Leerzeichen werden beim Vergleich toleriert).

Benutzung

# Programm mit injizierten Secrets starten
wincm run -- node app.js
wincm run -- npm start
wincm run -- npm run dev

# Leiser Modus (keine Injection-Logs)
wincm run --quiet -- node server.js

# Andere Config-Datei (z.B. für andere Umgebung)
wincm run --config ./prod.wincm.json -- node app.js

# Anzeigen, WAS injiziert würde (ohne die Werte zu zeigen)
wincm list

# Credential anlegen/ändern (Passwort wird versteckt abgefragt)
wincm set myservice/myuser

# Credential löschen
wincm delete myservice/myuser

# Status der in der Config referenzierten Credentials prüfen
wincm show

# Alle Accounts eines Service auflisten (ohne Werte)
wincm show myservice

# Master-PIN setzen / ändern (Schutz wie bei KeePassXC)
wincm setpin

# PIN-Schutz wieder entfernen
wincm removepin

# Hilfe
wincm help

Befehlsübersicht

| Befehl | Beschreibung | | ----------- | ------------------------------------------------------------------------------------ | | run | Startet ein Programm mit injizierten Secrets (alles nach --). | | list | Zeigt (ohne Werte), welche ENV-Variablen injiziert würden. | | set | Legt ein Credential an bzw. ändert es. Ohne Passwort-Argument wird es versteckt abgefragt. | | delete | Löscht ein Credential aus dem Credential Manager. Aliase: del, rm. | | show | Ohne Argument: prüft die Config-Credentials auf Existenz. Mit SERVICE: listet dessen Accounts. | | setpin | Setzt oder ändert die Master-PIN. Danach fragt run vorher danach. | | removepin | Entfernt den PIN-Schutz wieder. | | help | Zeigt die Hilfe an. |

| Option | Beschreibung | | ------------------------ | ---------------------------------------------------- | | --config, -c <datei> | Andere Config-Datei verwenden (statt .wincm.json). | | --quiet, -q | Keine Injection-/Status-Logs ausgeben. | | --no-pin | (nur run) Abbruch, falls eine PIN gesetzt ist. |

PIN-Schutz (optional, Authentifizierung wie bei KeePassXC)

Standardmäßig ist der Zugriff bereits durch deine Windows-Anmeldung geschützt. Wenn du zusätzlich eine Master-PIN willst, richtest du sie einmalig ein:

wincm setpin

Danach fragt jeder wincm run vor dem Start nach der PIN.

• Die PIN wird nie im Klartext gespeichert, sondern als gesalzener scrypt-Hash im Windows Credential Manager.
• Der Vergleich läuft zeitkonstant.
• Nach 3 Fehlversuchen bricht das Tool ab.
• setpin (Ändern) und removepin verlangen zuerst die aktuelle PIN.

Troubleshooting

wincm wird nicht gefunden (Command not found)

• Prüfe, ob die Installation (npm link oder npm install -g) erfolgreich war.
• Bei npm link: Wurde der Projektordner verschoben? Dann ist der Symlink ungültig → im neuen Pfad erneut npm link ausführen.
• Prüfe mit npm ls -g --depth=0, ob wincm-cli gelistet ist.

„Kein Credential gefunden"

• Adresse in .wincm.json prüfen: exakt "ENV_VAR": "SERVICE/ACCOUNT".
• Bei manueller Anlage muss der ACCOUNT im Feld „Benutzername" stehen.
• Mit wincm list prüfen, welche Adressen erwartet werden.

PIN vergessen

• Ohne die aktuelle PIN lässt sich weder setpin noch removepin ausführen.
• Notausgang: Den Eintrag wincm-cli / master-pin manuell im Windows Credential Manager löschen.

keytar-Fehler bei der Installation

• keytar ist ein natives Modul und braucht ggf. Build-Tools. Bei Problemen: npm install erneut ausführen; ggf. Windows Build Tools / Python installieren.