# Authentication Layer Implementation Guide

**Version**: 1.0.0
**Date**: 2025-10-09
**Status**: Production Ready

---

## Overview

A comprehensive authentication layer has been integrated into the provisioning system to secure sensitive operations. The system uses `nu_plugin_auth` for JWT authentication with MFA support, providing enterprise-grade security with graceful user experience.

---

## Key Features

### ✅ **JWT Authentication**

- RS256 asymmetric signing
- Access tokens (15 min) + refresh tokens (7 d)
- OS keyring storage (macOS Keychain, Windows Credential Manager, Linux Secret Service)

### ✅ **MFA Support**

- TOTP (Google Authenticator, Authy)
- WebAuthn/FIDO2 (YubiKey, Touch ID)
- Required for production and destructive operations

### ✅ **Security Policies**

- **Production environment**: Requires authentication + MFA
- **Destructive operations**: Requires authentication + MFA (delete, destroy)
- **Development/test**: Requires authentication, allows skip with flag
- **Check mode**: Always bypasses authentication (dry-run operations)

### ✅ **Audit Logging**

- All authenticated operations logged
- User, timestamp, operation details
- MFA verification status
- JSON format for easy parsing

### ✅ **User-Friendly Error Messages**

- Clear instructions for login/MFA
- Distinct error types (platform auth vs provider auth)
- Helpful guidance for setup

---

## Quick Start

### 1. Login to Platform

```bash
# Interactive login (password prompt)
provisioning auth login <username>

# Save credentials to keyring
provisioning auth login <username> --save

# Custom control center URL
provisioning auth login admin --url http://control.example.com:9080
```plaintext

### 2. Enroll MFA (First Time)

```bash
# Enroll TOTP (Google Authenticator)
provisioning auth mfa enroll totp

# Scan QR code with authenticator app
# Or enter secret manually
```plaintext

### 3. Verify MFA (For Sensitive Operations)

```bash
# Get 6-digit code from authenticator app
provisioning auth mfa verify --code 123456
```plaintext

### 4. Check Authentication Status

```bash
# View current authentication status
provisioning auth status

# Verify token is valid
provisioning auth verify
```plaintext

---

## Protected Operations

### Server Operations

```bash
# ✅ CREATE - Requires auth (prod: +MFA)
provisioning server create web-01                    # Auth required
provisioning server create web-01 --check            # Auth skipped (check mode)

# ❌ DELETE - Requires auth + MFA
provisioning server delete web-01                    # Auth + MFA required
provisioning server delete web-01 --check            # Auth skipped (check mode)

# 📖 READ - No auth required
provisioning server list                             # No auth required
provisioning server ssh web-01                       # No auth required
```plaintext

### Task Service Operations

```bash
# ✅ CREATE - Requires auth (prod: +MFA)
provisioning taskserv create kubernetes              # Auth required
provisioning taskserv create kubernetes --check      # Auth skipped

# ❌ DELETE - Requires auth + MFA
provisioning taskserv delete kubernetes              # Auth + MFA required

# 📖 READ - No auth required
provisioning taskserv list                           # No auth required
```plaintext

### Cluster Operations

```bash
# ✅ CREATE - Requires auth (prod: +MFA)
provisioning cluster create buildkit                 # Auth required
provisioning cluster create buildkit --check         # Auth skipped

# ❌ DELETE - Requires auth + MFA
provisioning cluster delete buildkit                 # Auth + MFA required
```plaintext

### Batch Workflows

```bash
# ✅ SUBMIT - Requires auth (prod: +MFA)
provisioning batch submit workflow.ncl               # Auth required
provisioning batch submit workflow.ncl --skip-auth   # Auth skipped (if allowed)

# 📖 READ - No auth required
provisioning batch list                              # No auth required
provisioning batch status <task-id>                  # No auth required
```plaintext

---

## Configuration

### Security Settings (`config.defaults.toml`)

```toml
[security]
require_auth = true  # Enable authentication system
require_mfa_for_production = true  # MFA for prod environment
require_mfa_for_destructive = true  # MFA for delete operations
auth_timeout = 3600  # Token timeout (1 hour)
audit_log_path = "{{paths.base}}/logs/audit.log"

[security.bypass]
allow_skip_auth = false  # Allow PROVISIONING_SKIP_AUTH env var

[plugins]
auth_enabled = true  # Enable nu_plugin_auth

[platform.control_center]
url = "http://localhost:9080"  # Control center URL
```plaintext

### Environment-Specific Configuration

```toml
# Development
[environments.dev]
security.bypass.allow_skip_auth = true  # Allow auth bypass in dev

# Production
[environments.prod]
security.bypass.allow_skip_auth = false  # Never allow bypass
security.require_mfa_for_production = true
```plaintext

---

## Authentication Bypass (Dev/Test Only)

### Environment Variable Method

```bash
# Export environment variable (dev/test only)
export PROVISIONING_SKIP_AUTH=true

# Run operations without authentication
provisioning server create web-01

# Unset when done
unset PROVISIONING_SKIP_AUTH
```plaintext

### Per-Command Flag

```bash
# Some commands support --skip-auth flag
provisioning batch submit workflow.ncl --skip-auth
```plaintext

### Check Mode (Always Bypasses Auth)

```bash
# Check mode is always allowed without auth
provisioning server create web-01 --check
provisioning taskserv create kubernetes --check
```plaintext

⚠️ **WARNING**: Auth bypass should ONLY be used in development/testing environments. Production systems should have `security.bypass.allow_skip_auth = false`.

---

## Error Messages

### Not Authenticated

```plaintext
❌ Authentication Required

Operation: server create web-01
You must be logged in to perform this operation.

To login:
   provisioning auth login <username>

Note: Your credentials will be securely stored in the system keyring.
```plaintext

**Solution**: Run `provisioning auth login <username>`

---

### MFA Required

```plaintext
❌ MFA Verification Required

Operation: server delete web-01
Reason: destructive operation (delete/destroy)

To verify MFA:
   1. Get code from your authenticator app
   2. Run: provisioning auth mfa verify --code <6-digit-code>

Don't have MFA set up?
   Run: provisioning auth mfa enroll totp
```plaintext

**Solution**: Run `provisioning auth mfa verify --code 123456`

---

### Token Expired

```plaintext
❌ Authentication Required

Operation: server create web-02
You must be logged in to perform this operation.

Error: Token verification failed
```plaintext

**Solution**: Token expired, re-login with `provisioning auth login <username>`

---

## Audit Logging

All authenticated operations are logged to the audit log file with the following information:

```json
{
  "timestamp": "2025-10-09 14:32:15",
  "user": "admin",
  "operation": "server_create",
  "details": {
    "hostname": "web-01",
    "infra": "production",
    "environment": "prod",
    "orchestrated": false
  },
  "mfa_verified": true
}
```plaintext

### Viewing Audit Logs

```bash
# View raw audit log
cat provisioning/logs/audit.log

# Filter by user
cat provisioning/logs/audit.log | jq '. | select(.user == "admin")'

# Filter by operation type
cat provisioning/logs/audit.log | jq '. | select(.operation == "server_create")'

# Filter by date
cat provisioning/logs/audit.log | jq '. | select(.timestamp | startswith("2025-10-09"))'
```plaintext

---

## Integration with Control Center

The authentication system integrates 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
- **POST /api/mfa/enroll** - Enroll MFA device
- **POST /api/mfa/verify** - Verify MFA code

### Starting Control Center

```bash
# Start control center (required for authentication)
cd provisioning/platform/control-center
cargo run --release
```plaintext

Or use the orchestrator which includes control center:

```bash
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background
```plaintext

---

## Testing Authentication

### Manual Testing

```bash
# 1. Start control center
cd provisioning/platform/control-center
cargo run --release &

# 2. Login
provisioning auth login admin

# 3. Try creating server (should succeed if authenticated)
provisioning server create test-server --check

# 4. Logout
provisioning auth logout

# 5. Try creating server (should fail - not authenticated)
provisioning server create test-server --check
```plaintext

### Automated Testing

```bash
# Run authentication tests
nu provisioning/core/nulib/lib_provisioning/plugins/auth_test.nu
```plaintext

---

## Troubleshooting

### Plugin Not Available

**Error**: `Authentication plugin not available`

**Solution**:

1. Check plugin is built: `ls provisioning/core/plugins/nushell-plugins/nu_plugin_auth/target/release/`
2. Register plugin: `plugin add target/release/nu_plugin_auth`
3. Use plugin: `plugin use auth`
4. Verify: `which auth`

---

### Control Center Not Running

**Error**: `Cannot connect to control center`

**Solution**:

1. Start control center: `cd provisioning/platform/control-center && cargo run --release`
2. Or use orchestrator: `cd provisioning/platform/orchestrator && ./scripts/start-orchestrator.nu --background`
3. Check URL is correct in config: `provisioning config get platform.control_center.url`

---

### MFA Not Working

**Error**: `Invalid MFA code`

**Solutions**:

- Ensure time is synchronized (TOTP codes are time-based)
- Code expires every 30 seconds, get fresh code
- Verify you're using the correct authenticator app entry
- Re-enroll if needed: `provisioning auth mfa enroll totp`

---

### Keyring Access Issues

**Error**: `Keyring storage unavailable`

**macOS**: Grant Keychain access to Terminal/iTerm2 in System Preferences → Security & Privacy

**Linux**: Ensure `gnome-keyring` or `kwallet` is running

**Windows**: Check Windows Credential Manager is accessible

---

## Architecture

### Authentication Flow

```plaintext
┌─────────────┐
│ User Command│
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│ Infrastructure Command Handler  │
│ (infrastructure.nu)             │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Auth Check                       │
│ - Determine operation type       │
│ - Check if auth required         │
│ - Check environment (prod/dev)   │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Auth Plugin Wrapper              │
│ (auth.nu)                        │
│ - Call plugin or HTTP fallback   │
│ - Verify token validity          │
│ - Check MFA if required          │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ nu_plugin_auth                   │
│ - JWT verification (RS256)       │
│ - Keyring token storage          │
│ - MFA verification               │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Control Center API               │
│ - /api/auth/verify               │
│ - /api/mfa/verify                │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Operation Execution              │
│ (servers/create.nu, etc.)        │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Audit Logging                    │
│ - Log to audit.log               │
│ - Include user, timestamp, MFA   │
└─────────────────────────────────┘
```plaintext

### File Structure

```plaintext
provisioning/
├── config/
│   └── config.defaults.toml           # Security configuration
├── core/nulib/
│   ├── lib_provisioning/plugins/
│   │   └── auth.nu                    # Auth wrapper (550 lines)
│   ├── servers/
│   │   └── create.nu                  # Server ops with auth
│   ├── workflows/
│   │   └── batch.nu                   # Batch workflows with auth
│   └── main_provisioning/commands/
│       └── infrastructure.nu          # Infrastructure commands with auth
├── core/plugins/nushell-plugins/
│   └── nu_plugin_auth/                # Native Rust plugin
│       ├── src/
│       │   ├── main.rs                # Plugin implementation
│       │   └── helpers.rs             # Helper functions
│       └── README.md                  # Plugin documentation
├── platform/control-center/           # Control Center (Rust)
│   └── src/auth/                      # JWT auth implementation
└── logs/
    └── audit.log                       # Audit trail
```plaintext

---

## Related Documentation

- **Security System Overview**: `docs/architecture/ADR-009-security-system-complete.md`
- **JWT Authentication**: `docs/architecture/JWT_AUTH_IMPLEMENTATION.md`
- **MFA Implementation**: `docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md`
- **Plugin README**: `provisioning/core/plugins/nushell-plugins/nu_plugin_auth/README.md`
- **Control Center**: `provisioning/platform/control-center/README.md`

---

## Summary of Changes

| File | Changes | Lines Added |
|------|---------|-------------|
| `lib_provisioning/plugins/auth.nu` | Added security policy enforcement functions | +260 |
| `config/config.defaults.toml` | Added security configuration section | +19 |
| `servers/create.nu` | Added auth check for server creation | +25 |
| `workflows/batch.nu` | Added auth check for batch workflow submission | +43 |
| `main_provisioning/commands/infrastructure.nu` | Added auth checks for all infrastructure commands | +90 |
| `lib_provisioning/providers/interface.nu` | Added authentication guidelines for providers | +65 |
| **Total** | **6 files modified** | **~500 lines** |

---

## Best Practices

### For Users

1. **Always login**: Keep your session active to avoid interruptions
2. **Use keyring**: Save credentials with `--save` flag for persistence
3. **Enable MFA**: Use MFA for production operations
4. **Check mode first**: Always test with `--check` before actual operations
5. **Monitor audit logs**: Review audit logs regularly for security

### For Developers

1. **Check auth early**: Verify authentication before expensive operations
2. **Log operations**: Always log authenticated operations for audit
3. **Clear error messages**: Provide helpful guidance for auth failures
4. **Respect check mode**: Always skip auth in check/dry-run mode
5. **Test both paths**: Test with and without authentication

### For Operators

1. **Production hardening**: Set `allow_skip_auth = false` in production
2. **MFA enforcement**: Require MFA for all production environments
3. **Monitor audit logs**: Set up log monitoring and alerts
4. **Token rotation**: Configure short token timeouts (15 min default)
5. **Backup authentication**: Ensure multiple admins have MFA enrolled

---

## License

MIT License - See LICENSE file for details

---

## Quick Reference

**Version**: 1.0.0
**Last Updated**: 2025-10-09

---

### Quick Commands

#### Login

```bash
provisioning auth login <username>              # Interactive password
provisioning auth login <username> --save       # Save to keyring
```plaintext

#### MFA

```bash
provisioning auth mfa enroll totp               # Enroll TOTP
provisioning auth mfa verify --code 123456      # Verify code
```plaintext

#### Status

```bash
provisioning auth status                        # Show auth status
provisioning auth verify                        # Verify token
```plaintext

#### Logout

```bash
provisioning auth logout                        # Logout current session
provisioning auth logout --all                  # Logout all sessions
```plaintext

---

### Protected Operations

| Operation | Auth | MFA (Prod) | MFA (Delete) | Check Mode |
|-----------|------|------------|--------------|------------|
| `server create` | ✅ | ✅ | ❌ | Skip |
| `server delete` | ✅ | ✅ | ✅ | Skip |
| `server list` | ❌ | ❌ | ❌ | - |
| `taskserv create` | ✅ | ✅ | ❌ | Skip |
| `taskserv delete` | ✅ | ✅ | ✅ | Skip |
| `cluster create` | ✅ | ✅ | ❌ | Skip |
| `cluster delete` | ✅ | ✅ | ✅ | Skip |
| `batch submit` | ✅ | ✅ | ❌ | - |

---

### Bypass Authentication (Dev/Test Only)

#### Environment Variable

```bash
export PROVISIONING_SKIP_AUTH=true
provisioning server create test
unset PROVISIONING_SKIP_AUTH
```plaintext

#### Check Mode (Always Allowed)

```bash
provisioning server create prod --check
provisioning taskserv delete k8s --check
```plaintext

#### Config Flag

```toml
[security.bypass]
allow_skip_auth = true  # Only in dev/test
```plaintext

---

### Configuration

#### Security Settings

```toml
[security]
require_auth = true
require_mfa_for_production = true
require_mfa_for_destructive = true
auth_timeout = 3600

[security.bypass]
allow_skip_auth = false  # true in dev only

[plugins]
auth_enabled = true

[platform.control_center]
url = "http://localhost:3000"
```plaintext

---

### Error Messages

#### Not Authenticated

```plaintext
❌ Authentication Required
Operation: server create web-01
To login: provisioning auth login <username>
```plaintext

**Fix**: `provisioning auth login <username>`

#### MFA Required

```plaintext
❌ MFA Verification Required
Operation: server delete web-01
Reason: destructive operation
```plaintext

**Fix**: `provisioning auth mfa verify --code <code>`

#### Token Expired

```plaintext
Error: Token verification failed
```plaintext

**Fix**: Re-login: `provisioning auth login <username>`

---

### Troubleshooting

| Error | Solution |
|-------|----------|
| Plugin not available | `plugin add target/release/nu_plugin_auth` |
| Control center offline | Start: `cd provisioning/platform/control-center && cargo run` |
| Invalid MFA code | Get fresh code (expires in 30s) |
| Token expired | Re-login: `provisioning auth login <username>` |
| Keyring access denied | Grant app access in system settings |

---

### Audit Logs

```bash
# View audit log
cat provisioning/logs/audit.log

# Filter by user
cat provisioning/logs/audit.log | jq '. | select(.user == "admin")'

# Filter by operation
cat provisioning/logs/audit.log | jq '. | select(.operation == "server_create")'
```plaintext

---

### CI/CD Integration

#### Option 1: Skip Auth (Dev/Test Only)

```bash
export PROVISIONING_SKIP_AUTH=true
provisioning server create ci-server
```plaintext

#### Option 2: Check Mode

```bash
provisioning server create ci-server --check
```plaintext

#### Option 3: Service Account (Future)

```bash
export PROVISIONING_AUTH_TOKEN="<token>"
provisioning server create ci-server
```plaintext

---

### Performance

| Operation | Auth Overhead |
|-----------|---------------|
| Server create | ~20 ms |
| Taskserv create | ~20 ms |
| Batch submit | ~20 ms |
| Check mode | 0 ms (skipped) |

---

### Related Docs

- **Full Guide**: `docs/user/AUTHENTICATION_LAYER_GUIDE.md`
- **Implementation**: `AUTHENTICATION_LAYER_IMPLEMENTATION_SUMMARY.md`
- **Security ADR**: `docs/architecture/ADR-009-security-system-complete.md`

---

**Quick Help**: `provisioning help auth` or `provisioning auth --help`

---

**Last Updated**: 2025-10-09
**Maintained By**: Security Team

---

## Setup Guide

### Complete Authentication Setup Guide

Current Settings (from your config)

```plaintext
[security]
require_auth = true                    # ✅ Auth is REQUIRED
allow_skip_auth = false                # ❌ Cannot skip with env var
auth_timeout = 3600                    # Token valid for 1 hour

[platform.control_center]
url = "http://localhost:3000"          # Control Center endpoint
```plaintext

### STEP 1: Start Control Center

The Control Center is the authentication backend:

```bash
# Check if it's already running
curl http://localhost:3000/health

# If not running, start it
cd /Users/Akasha/project-provisioning/provisioning/platform/control-center
cargo run --release &

# Wait for it to start (may take 30-60 seconds)
sleep 30
curl http://localhost:3000/health
```plaintext

Expected Output:

```json
{"status": "healthy"}
```plaintext

### STEP 2: Find Default Credentials

Check for default user setup:

```bash
# Look for initialization scripts
ls -la /Users/Akasha/project-provisioning/provisioning/platform/control-center/

# Check for README or setup instructions
cat /Users/Akasha/project-provisioning/provisioning/platform/control-center/README.md

# Or check for default config
cat /Users/Akasha/project-provisioning/provisioning/platform/control-center/config.toml 2>/dev/null || echo "Config not found"
```plaintext

### STEP 3: Log In

Once you have credentials (usually admin / password from setup):

```bash
# Interactive login - will prompt for password
provisioning auth login

# Or with username
provisioning auth login admin

# Verify you're logged in
provisioning auth status
```plaintext

Expected Success Output:

```plaintext
✓ Login successful!

User:       admin
Role:       admin
Expires:    2025-10-22T14:30:00Z
MFA:        false

Session active and ready
```plaintext

### STEP 4: Now Create Your Server

Once authenticated:

```bash
# Try server creation again
provisioning server create sgoyol --check

# Or with full details
provisioning server create sgoyol --infra workspace_librecloud --check
```plaintext

### 🛠️ Alternative: Skip Auth for Development

If you want to bypass authentication temporarily for testing:

#### Option A: Edit config to allow skip

```bash
# You would need to parse and modify TOML - easier to do next option
```plaintext

#### Option B: Use environment variable (if allowed by config)

```bash
export PROVISIONING_SKIP_AUTH=true
provisioning server create sgoyol
unset PROVISIONING_SKIP_AUTH
```plaintext

#### Option C: Use check mode (always works, no auth needed)

```bash
provisioning server create sgoyol --check
```plaintext

#### Option D: Modify config.defaults.toml (permanent for dev)

Edit: `provisioning/config/config.defaults.toml`

Change line 193 to:

```toml
allow_skip_auth = true
```plaintext

### 🔍 Troubleshooting

| Problem                    | Solution                                                            |
|----------------------------|---------------------------------------------------------------------|
| Control Center won't start | Check port 3000 not in use: `lsof -i :3000`                           |
| "No token found" error     | Login with: `provisioning auth login`                                 |
| Login fails                | Verify Control Center is running: `curl http://localhost:3000/health` |
| Token expired              | Re-login: `provisioning auth login`                                   |
| Plugin not available       | Using HTTP fallback - this is OK, works without plugin              |
