Platform-Specific Security

This document provides detailed information about how nsyte's credential storage works on each supported platform.

Overview

nsyte automatically selects the most secure storage method available on your platform:

1. Native Keychain (preferred) - OS-managed encryption
2. Encrypted File Storage (fallback) - AES-256-GCM encryption
3. Plain JSON (emergency fallback) - Legacy compatibility with warnings

macOS

Native Keychain (Tier 1)

Implementation: macOS Keychain Services via security command
Location: User's login keychain (~/Library/Keychains/login.keychain-db)
Encryption: Apple's hardware-backed encryption with Secure Enclave when available

Requirements

• security command (included with macOS)
• User keychain access (may prompt for password/Touch ID)

Security Benefits:

• Hardware-backed encryption on modern Macs
• Integration with Touch ID/Face ID authentication
• Protected by user's login keychain password
• Automatic encryption key management

Encrypted Storage (Tier 2)

Location: ~/Library/Application Support/nsyte/secrets.enc
Encryption: AES-256-GCM with PBKDF2 key derivation

Key Derivation Input:

• System hostname
• Operating system (darwin)
• Architecture (arm64/x86_64)
• Username

Legacy Fallback (Tier 3)

Location: ~/Library/Application Support/nsyte/secrets.json
Security: Plain text with warnings

---

Windows

Native Keychain (Tier 1)

Implementation: Windows Credential Manager via cmdkey and PowerShell
Location: User's credential store (%LOCALAPPDATA%\Microsoft\Credentials\)
Encryption: Windows Data Protection API (DPAPI)

Requirements

• cmdkey command (included with Windows)
• PowerShell for credential retrieval
• User account access

Security Benefits:

• Protected by Windows DPAPI
• Tied to user account and machine
• Automatic encryption key management
• Integration with Windows Hello when available

Encrypted Storage (Tier 2)

Location: %APPDATA%\nsite\secrets.enc
Encryption: AES-256-GCM with PBKDF2 key derivation

Key Derivation Input:

• System hostname
• Operating system (windows)
• Architecture (x86_64/arm64)
• Username (%USERNAME%)

Legacy Fallback (Tier 3)

Location: %APPDATA%\nsite\secrets.json
Security: Plain text with warnings

Why nsite and not nsyte on Windows?

The Windows config directory is named nsite (and the Linux one is ~/.config/nsite/) for historical compatibility with the project's pre-rename storage layout. The macOS path uses nsyte. See src/lib/secrets/utils.ts for the source-of-truth path resolver.

---

Linux

Native Keychain (Tier 1)

Implementation: Secret Service API via secret-tool (libsecret)
Location: D-Bus secret service (usually GNOME Keyring or KDE Wallet)
Encryption: Service-specific encryption

Requirements

• secret-tool command installed
• Secret service running (GNOME Keyring, KDE Wallet, etc.)
• D-Bus session

Installation:

# Ubuntu/Debian
sudo apt install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret

# Arch Linux
sudo pacman -S libsecret

Security Benefits:

• Integration with desktop keyring services
• Protected by user session authentication
• Service-specific encryption (varies by implementation)

Encrypted Storage (Tier 2)

Location: ~/.config/nsite/secrets.enc (or $XDG_CONFIG_HOME/nsite/secrets.enc)
Encryption: AES-256-GCM with PBKDF2 key derivation

Key Derivation Input:

• System hostname
• Operating system (linux)
• Architecture (x86_64/arm64/etc.)
• Username ($USER)

Legacy Fallback (Tier 3)

Location: ~/.config/nsite/secrets.json
Security: Plain text with warnings

Why nsite and not nsyte on Linux?

The Linux config directory is named nsite (and the Windows one is %APPDATA%\nsite\) for historical compatibility with the project's pre-rename storage layout. The macOS path uses nsyte. See src/lib/secrets/utils.ts for the source-of-truth path resolver.

---

Other Platforms

For unsupported platforms, nsyte automatically falls back to encrypted file storage using the same AES-256-GCM encryption with platform-specific key derivation.

---

Security Considerations

Best Practices

1. Use Native Keychain: Always prefer native keychain when available
2. Keep Systems Updated: Ensure OS security updates are applied
3. Protect System Access: Use strong user account passwords/authentication
4. Monitor Access: Check for unexpected keychain access prompts
5. Rotate Credentials: Periodically rotate nbunksec strings

Threat Model

Protected Against:

• Casual file system access
• Basic malware file scanning
• Accidental credential exposure in backups

Not Protected Against

• Malware with keychain/credential manager access
• Physical access with user credentials
• Advanced persistent threats with system-level access
• Side-channel attacks on encryption

Migration Security

When migrating from legacy plain-text storage:

1. Secrets are read from JSON file
2. Stored using secure backend
3. Original file deleted only after successful migration
4. Process is logged for audit purposes