nushell-plugins/nu_plugin_auth/QUICK_REFERENCE.md

# nu_plugin_auth Quick Reference

**Version**: 0.1.0
**Status**: Login/Logout Commands Implemented

---

## Installation

```nushell
# Build plugin
cargo build --release -p nu_plugin_auth

# Register with Nushell
plugin add target/release/nu_plugin_auth
plugin use nu_plugin_auth
```

---

## Login Command

### Basic Usage
```nushell
# Interactive login (password prompt)
auth login admin

# Login with password
auth login admin mypassword

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

# Custom Control Center URL
auth login admin --url http://control.example.com:8081
```

### Flags
| Flag | Short | Type | Description | Default |
|------|-------|------|-------------|---------|
| `--url` | - | String | Control Center URL | `http://localhost:8081` |
| `--save` | - | Switch | Save tokens to keyring | `false` |

### Output
```nushell
{
  success: true,
  user: {
    id: "user-123",
    username: "admin",
    email: "admin@example.com",
    roles: ["admin", "developer"]
  },
  expires_in: 900,
  token_saved: true
}
```

---

## Logout Command

### Basic Usage
```nushell
# Logout current user
auth logout

# Logout specific user
auth logout --user admin

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

### Flags
| Flag | Short | Type | Description | Default |
|------|-------|------|-------------|---------|
| `--user` | `-u` | String | Username | Current system user |
| `--url` | - | String | Control Center URL | `http://localhost:8081` |
| `--all` | `-a` | Switch | Logout all sessions | `false` |

### Output
```nushell
{
  success: true,
  message: "Logged out successfully",
  user: "admin"
}
```

---

## MFA Commands (Bonus)

### TOTP Enrollment
```nushell
# Enroll in TOTP
auth mfa enroll totp

# Enroll for specific user
auth mfa enroll totp --user alice
```

**Output**: QR code in terminal + secret + backup codes

### TOTP Verification
```nushell
# Verify TOTP code
auth mfa verify --code 123456

# Verify for specific user
auth mfa verify --code 123456 --user alice
```

### WebAuthn Enrollment
```nushell
# Enroll WebAuthn (YubiKey, Touch ID)
auth mfa enroll webauthn
```

---

## Security Features

- ✅ **OS Keyring**: Secure credential storage (Keychain, libsecret, Credential Manager)
- ✅ **No Echo**: Password input not visible in terminal
- ✅ **HTTPS**: TLS with rustls (no OpenSSL)
- ✅ **JWT Tokens**: RS256-signed access + refresh tokens
- ✅ **Token Revocation**: Server-side blacklist on logout

---

## Error Handling

```nushell
# No active session
auth logout
# Error: No active session: No token found

# Invalid credentials
auth login baduser wrongpass
# Error: Login failed: HTTP 401 - Invalid credentials

# Network error
auth login admin --url http://invalid:8081
# Error: HTTP request failed: connection refused
```

---

## Platform Support

| Platform | Credential Storage |
|----------|-------------------|
| macOS | Keychain |
| Linux | Secret Service (libsecret/gnome-keyring) |
| Windows | Credential Manager |

---

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/login` | POST | Authenticate and get tokens |
| `/auth/logout` | POST | Revoke access token |
| `/auth/verify` | GET | Verify token validity |
| `/auth/sessions` | GET | List active sessions |
| `/mfa/enroll/{type}` | POST | Enroll in MFA |
| `/mfa/verify` | POST | Verify MFA code |

---

## Workflow Examples

### Standard Login/Logout
```nushell
# Login
auth login admin --save

# Do work...

# Logout
auth logout
```

### Multiple Users
```nushell
# Login as different users
auth login alice --save
auth login bob --save

# Logout specific user
auth logout --user alice
```

### CI/CD Integration
```nushell
# Non-interactive login
let token = auth login $env.CI_USER $env.CI_PASS | get user.id

# Use token for operations...

# Cleanup
auth logout --user $env.CI_USER
```

---

## Troubleshooting

### "No token found" error
**Cause**: No active session or keyring not accessible
**Fix**: Login again with `--save` flag

### "HTTP request failed"
**Cause**: Control Center not running or wrong URL
**Fix**: Check Control Center status and `--url` flag

### "Login failed: HTTP 401"
**Cause**: Invalid credentials
**Fix**: Verify username and password

### Keyring access denied
**Cause**: OS permission issue
**Fix**: Grant keychain/keyring access to plugin binary

---

## Development

### Build Commands
```bash
# Check code
cargo check -p nu_plugin_auth

# Build debug
cargo build -p nu_plugin_auth

# Build release
cargo build --release -p nu_plugin_auth

# Run tests
cargo test -p nu_plugin_auth
```

### Plugin Location
- Source: `provisioning/core/plugins/nushell-plugins/nu_plugin_auth/`
- Binary: `target/release/nu_plugin_auth`

---

## Related Commands (Future)

- `auth verify` - Verify current token
- `auth sessions` - List all sessions
- `auth whoami` - Show current user
- `auth refresh` - Refresh expired token

---

**Last Updated**: 2025-10-09
**Documentation**: See `LOGIN_LOGOUT_IMPLEMENTATION.md` for complete details