Authentication

Nefia uses multiple authentication mechanisms across different layers: OAuth for operator identity, SSH public keys for target connections, and HMAC-signed tokens for VPN enrollment. Credentials are stored securely in the OS keyring whenever possible.

Operator Login

Authenticate with your Nefia account using the nefia login command:

nefia login

Nefia uses a challenge-response flow inspired by PKCE (Proof Key for Code Exchange). Unlike approaches that spin up a local HTTP server, this works reliably in headless environments, remote shells, and containers.

Token Storage

Nefia stores authentication tokens using the platform's native secret storage:

When vpn keygen successfully stores the private key in the OS keyring, no plaintext fallback is written. The config file stores only a keyring: reference.

When no keyring is available (headless servers, containers, CI environments), Nefia falls back to an AES-256-GCM encrypted file:

JWT Tokens

Nefia uses two JWT tokens signed with HS256:

The access token payload includes:

Refresh tokens use single-use rotation: each refresh token can only be used once. When the CLI refreshes the access token, the old refresh token is revoked and a new pair is issued. This limits the window of exposure if a token is compromised.

Team Context

When you switch teams with nefia team use <slug>, the active team ID is stored in nefia.yaml. Subsequent CLI API calls send that team context in the X-Nefia-Team-Id header, and the server verifies membership on every request. API requests are scoped to the active team -- hosts, schedules, and audit logs are isolated per team.

# List your teams
nefia team list
 
# Switch to a shared team
nefia team use my-team
 
# Show current team context
nefia team

The server also supports X-Nefia-Team-Id for per-request overrides, and still falls back to the token claim or the personal team when no override is supplied.

Logout

Remove stored credentials with nefia logout:

nefia logout

This deletes the token from the OS keyring (or the encrypted fallback file). Active VPN tunnels are not affected — they use separate WireGuard keys.

SSH Key Authentication

Connections to target PCs use SSH public key authentication inside the VPN tunnel. Password authentication is disabled by default.

The SSH key pair is managed automatically during VPN enrollment. When a target is enrolled via nefia vpn invite and nefia-agent enroll, the operator's public key is registered on the target and the target's host key is recorded locally.

Host Key Verification (Trust On First Use)

Nefia uses a Trust On First Use (TOFU) model for SSH host key verification within the VPN:

• Unknown host: The key is automatically accepted and persisted to the known_hosts file. This is safe because the VPN tunnel already authenticates the peer via WireGuard.
• Known host, matching key: Connection proceeds normally.
• Known host, changed key: Connection is rejected with a warning about potential man-in-the-middle attacks.

The TOFU callback uses a RWMutex to allow concurrent reads while serializing writes. The known_hosts file is created automatically with 0600 permissions if it does not exist. The file is stored at ~/.ssh/known_hosts on all platforms, following the standard SSH directory convention.

For testing environments where host keys change frequently:

nefia exec --target test-box --insecure-skip-hostkey-check -- hostname

VPN Enrollment Tokens

Target PCs are enrolled using cryptographically signed invite tokens. Each token is signed with HMAC-SHA256, single-use (the nonce is consumed on first use), and time-limited (24 hours by default).

nefia vpn invite --name staging-box --os macos --stun
# Valid --os values: macos, linux, windows

When the operator is logged in, a cloud relay session is automatically created so agents behind NAT/CGNAT can enroll without a direct TCP connection. The agent tries direct enrollment first (10 second timeout) and falls back to the cloud relay transparently.

If a token cannot be parsed (malformed base64, invalid JSON), the error message includes the original parsing error for easier debugging.

Agent Tokens

When a target PC is enrolled via nefia vpn invite, an agent-specific API token is generated for cloud communication (endpoint reporting, token rotation). This token is separate from the operator's OAuth tokens.

Token Generation (Bootstrap Code Flow)

Agent token issuance uses a two-phase bootstrap code flow:

Token Storage

The agent stores its token using the same platform keyring as the operator CLI:

When no keyring is available (headless servers, containers), the token is encrypted with AES-256-GCM and saved to a fallback file, following the same pattern as operator credentials.

Automatic Rotation

Agent tokens have a 90-day TTL. The agent checks the remaining TTL every 24 hours. When the TTL drops below 7 days, the agent automatically rotates the token:

1. The agent calls POST /api/agent-tokens/rotate with its current token.
2. The server verifies the current token, generates a new token, and revokes the old one atomically.
3. The agent stores the new token in the keyring, replacing the previous value.

If rotation fails (network error, server unavailable), the agent retries with exponential backoff (5-minute base, 1-hour maximum). After a successful rotation, the normal 24-hour check cycle resumes. The existing token remains valid until its TTL expires.

Clipboard Copy

When generating invite tokens, use the --copy flag to copy the token to the clipboard automatically:

nefia vpn invite --name staging-box --os linux --stun --copy

This avoids exposing the token in terminal scrollback. The clipboard is used as a secure alternative to printing the full token to stdout.

HTTPS Enforcement

All agent-to-cloud communication requires HTTPS. The validateCloudAPIBase() function rejects http:// URLs at configuration load time, ensuring agent tokens and endpoint data are never transmitted over unencrypted connections.

WireGuard Key Rotation

Nefia supports manual and automatic WireGuard key rotation for the operator.

Running nefia vpn keygen when a key already exists prompts for confirmation before overwriting, since this will disconnect all enrolled peers. Use --force to skip.

Manual Rotation

nefia vpn rotate-key --grace-period 72h

This generates a new WireGuard keypair, distributes the new public key to all active peers via nefia vpn push-key, and retains the old key for the specified grace period. During the grace period, the agent accepts both the old and new keys, ensuring a smooth transition even if some agents are temporarily offline.

Automatic Rotation

Enable automatic key rotation in nefia.yaml (see Getting Started for platform-specific config file locations):

vpn:
  auto_rotate_interval: "720h"        # Rotate every 30 days
  key_rotation_grace_period: "72h"    # Accept old key for 3 days

When auto_rotate_interval is set, automatic key rotation is handled by the background scheduler started through nefia daemon run. If the agent reloads its configuration from disk during the grace period, it picks up the new key automatically.

Subscription Validation

Nefia validates your subscription to enforce device count limits:

Check your account status at any time:

nefia account

Best Practices

Related