nushell-plugins/nu_plugin_auth/README.md

# 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:**
```nushell
auth login <username> [password] [--url <control-center-url>] [--save]
```

**Examples:**
```nushell
# 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:**
```nushell
auth logout [--all]
```

**Examples:**
```nushell
# Logout from current session
auth logout

# Logout from all active sessions
auth logout --all
```

### `auth verify`

Verify current authentication token.

**Syntax:**
```nushell
auth verify [--token <jwt-token>]
```

**Examples:**
```nushell
# Verify stored authentication token
auth verify

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

### `auth sessions`

List active authentication sessions.

**Syntax:**
```nushell
auth sessions [--active]
```

**Examples:**
```nushell
# List all sessions
auth sessions

# List only active sessions
auth sessions --active
```

## Installation

### Build from source

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

### Register with Nushell

```nushell
plugin add target/release/nu_plugin_auth
plugin use auth
```

### Using justfile (recommended)

```bash
# 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:

```nushell
# 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`