nushell-plugins/nu_plugin_auth

nu_plugin_auth

Nushell plugin for provisioning platform authentication.

Overview

This plugin provides native Nushell commands for authenticating with the provisioning platform's control center. It integrates with the JWT authentication system and supports MFA workflows.

Features

• JWT Authentication - Login with username/password, receive access and refresh tokens
• MFA Support - TOTP and WebAuthn second-factor authentication
• Session Management - List and manage active authentication sessions
• Secure Token Storage - Store credentials in system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Token Verification - Verify token validity and decode claims

Commands

auth login

Login to provisioning platform with JWT authentication.

Syntax:

auth login <username> [password] [--url <control-center-url>] [--save]

Examples:

# Login with password prompt (secure)
auth login admin

# Login with password in command (less secure)
auth login admin mypassword

# Login to custom control center URL
auth login admin --url http://control.example.com:8081

# Login and save credentials to keyring
auth login admin --save

auth logout

Logout from provisioning platform (revoke tokens).

Syntax:

auth logout [--all]

Examples:

# Logout from current session
auth logout

# Logout from all active sessions
auth logout --all

auth verify

Verify current authentication token.

Syntax:

auth verify [--token <jwt-token>]

Examples:

# Verify stored authentication token
auth verify

# Verify specific token
auth verify --token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

auth sessions

List active authentication sessions.

Syntax:

auth sessions [--active]

Examples:

# List all sessions
auth sessions

# List only active sessions
auth sessions --active

Installation

Build from source

cd provisioning/core/plugins/nushell-plugins/nu_plugin_auth
cargo build --release

Register with Nushell

plugin add target/release/nu_plugin_auth
plugin use auth

Using justfile (recommended)

# From nushell-plugins directory
just install-plugin nu_plugin_auth

# Or using shortcut
just i nu_plugin_auth

Configuration

The plugin uses the following defaults:

• Control Center URL: http://localhost:8081
• Keyring Service: provisioning-platform
• Token Storage: System keyring (platform-dependent)

Override defaults using command flags:

# Use custom control center URL
auth login admin --url https://control.production.example.com

Authentication Flow

1. Login: User provides credentials → Plugin sends request to control center → Receives JWT tokens
2. Token Storage: Access and refresh tokens stored in system keyring (if --save flag used)
3. Authenticated Requests: Plugin retrieves tokens from keyring → Includes in API requests
4. Token Refresh: Automatic refresh using refresh token when access token expires
5. Logout: Revoke tokens at control center → Remove from keyring

Security Considerations

• Keyring Storage: Tokens stored in OS-provided secure storage (Keychain, Credential Manager, Secret Service)
• Password Prompts: Interactive password prompts avoid exposing passwords in shell history
• Token Expiration: Access tokens expire after 15 minutes (configurable at control center)
• Refresh Tokens: Valid for 7 days (configurable at control center)
• MFA Support: Plugin supports TOTP and WebAuthn second-factor authentication

Integration with Control Center

This plugin communicates with the provisioning platform's control center REST API:

• POST /api/auth/login - Login with credentials
• POST /api/auth/logout - Revoke tokens
• POST /api/auth/verify - Verify token validity
• GET /api/auth/sessions - List active sessions

See control center API documentation for details: provisioning/platform/control-center/README.md

Development Status

Version: 0.1.0 (Initial structure)

Implementation Progress:

• ✅ Plugin structure created (Agente 1)
• ⏳ Login command implementation (Agente 2)
• ⏳ Logout command implementation (Agente 3)
• ⏳ Verify command implementation (Agente 4)
• ⏳ Sessions command implementation (Agente 5)
• ⏳ Test suite implementation (Agente 6)

License

MIT License - See LICENSE file for details

Contributing

This plugin is part of the provisioning platform project. See main project documentation for contribution guidelines.

Related Documentation

• Control Center API: provisioning/platform/control-center/README.md
• JWT Authentication: docs/architecture/JWT_AUTH_IMPLEMENTATION.md
• MFA Implementation: docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md
• Security System: docs/architecture/ADR-009-security-system-complete.md