Added support for listing permissions. Added additional tests

Signed-off-by: Kevin Stanley <stanleyk@objectcomputing.com>

Author: stanleykc

unityauth-cli/README.md

@@ -11,11 +11,12 @@ The UnityAuth CLI is a cross-platform command-line tool that enables system and
 | Feature | Status |
 |---------|--------|
 | Authentication (login/logout/token-info) | Implemented |
-| User Management (create/list/update roles) | Implemented |
+| User Management (create/list/update/update-profile) | Implemented |
 | Tenant Discovery (list/users) | Implemented |
 | Role Discovery (list) | Implemented |
+| Permissions Discovery (list) | Implemented |
 | Configuration Management | Implemented |
-| Permission Verification | Planned |
+| Service Discovery (list) | Not Available (see [Known Limitations](#known-limitations)) |
 | Batch Operations | Planned |
 
 ## Installation
@@ -125,12 +126,15 @@ unityauth
 ├── user           # User management
 │   ├── create     # Create a new user
 │   ├── list       # List users in a tenant
-│   └── update     # Update user roles
+│   ├── update     # Update user roles
+│   └── update-profile  # Update your own profile
 ├── tenant         # Tenant discovery
 │   ├── list       # List accessible tenants
 │   └── users      # List users in a tenant
-└── role           # Role discovery
-    └── list       # List available roles
+├── role           # Role discovery
+│   └── list       # List available roles
+└── permissions    # Permission discovery
+    └── list       # List your permissions for a tenant/service
 ```
 
 ## Global Options
@@ -203,6 +207,29 @@ unityauth config set timeout 60    # Set request timeout
 unityauth config edit              # Open in editor
 ```
 
+## Known Limitations
+
+### No Service Discovery API
+
+The UnityAuth backend does not expose an API endpoint to list available services. This means:
+
+- **No `service list` command**: The CLI cannot retrieve a list of services
+- **Service IDs must be known in advance**: Commands like `permissions list` require a `--service-id` that users must know beforehand
+
+**Common Service IDs:**
+
+| ID | Name | Description |
+|----|------|-------------|
+| 1 | Libre311 | Libre311 citizen request management |
+
+**Workaround:** Contact your UnityAuth administrator for the correct service ID, or query the database directly if you have access:
+
+```sql
+SELECT id, name, description FROM service WHERE status = 'ENABLED';
+```
+
+**For Backend Developers:** To enable service discovery in the CLI, implement a `GET /api/services` endpoint in the UnityAuth backend.
+
 ## Documentation
 
 - [User Guide](docs/user-guide.md) - Complete command reference

unityauth-cli/docs/user-guide.md

@@ -23,6 +23,9 @@ Complete command reference for the UnityAuth command-line interface.
   - [tenant users](#tenant-users)
 - [Role Commands](#role-commands)
   - [role list](#role-list)
+- [Permissions Commands](#permissions-commands)
+  - [permissions list](#permissions-list)
+- [Known Limitations](#known-limitations)
 - [Output Formats](#output-formats)
 - [Exit Codes](#exit-codes)
 - [Environment Variables](#environment-variables)
@@ -534,6 +537,96 @@ unityauth role list --format json | jq '.[] | select(.name == "Tenant Administra
 
 ---
 
+## Permissions Commands
+
+### permissions list
+
+List your permissions for a specific tenant and service.
+
+```
+unityauth permissions list --tenant-id TENANT_ID --service-id SERVICE_ID
+```
+
+**Required Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--tenant-id INTEGER` | Tenant ID to check permissions for |
+| `--service-id INTEGER` | Service ID to check permissions for |
+
+**Output:**
+
+Returns all permissions the authenticated user has for the specified tenant and service combination.
+
+**Examples:**
+
+```bash
+# List your permissions for tenant 1 and Libre311 service (ID: 1)
+unityauth permissions list --tenant-id 1 --service-id 1
+
+# Get JSON output
+unityauth permissions list --tenant-id 1 --service-id 1 --format json
+
+# Get CSV output
+unityauth permissions list --tenant-id 1 --service-id 1 --format csv
+```
+
+**Sample Output:**
+
+```
+┌───────────────────────────────┐
+│ Permission                    │
+├───────────────────────────────┤
+│ AUTH_SERVICE_VIEW-SYSTEM      │
+│ AUTH_SERVICE_EDIT-SYSTEM      │
+│ LIBRE311_ADMIN_VIEW-TENANT    │
+│ LIBRE311_ADMIN_EDIT-TENANT    │
+└───────────────────────────────┘
+```
+
+**Common Errors:**
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "No tenant found" | Invalid tenant ID | Check tenant ID with `tenant list` |
+| "The service does not exist" | Invalid service ID | See [Known Limitations](#known-limitations) |
+| "Tenant/Service not available" | User not authorized for this combination | Contact your administrator |
+
+---
+
+## Known Limitations
+
+### Service Discovery
+
+**There is currently no API endpoint to list available services.** The UnityAuth backend does not expose a `/api/services` endpoint, so the CLI cannot provide a `service list` command.
+
+**What this means:**
+
+- Commands that require `--service-id` (like `permissions list`) need you to know the service ID in advance
+- Service IDs are configured by database administrators and are deployment-specific
+
+**Current Services:**
+
+In most UnityAuth deployments, the following service is available:
+
+| ID | Name | Description |
+|----|------|-------------|
+| 1 | Libre311 | Libre311 citizen request management system |
+
+**Workaround:**
+
+If you don't know the service ID, contact your UnityAuth administrator or check the database directly:
+
+```sql
+SELECT id, name, description, status FROM service;
+```
+
+**For Developers:**
+
+To add a `service list` command, a new API endpoint would need to be implemented in the UnityAuth backend (e.g., `GET /api/services`).
+
+---
+
 ## Output Formats
 
 ### Table (Default)

unityauth-cli/src/unityauth_cli/cli.py

@@ -238,6 +238,7 @@ def register_commands() -> None:
     from unityauth_cli.commands.users import create, update, update_profile, list_users
     from unityauth_cli.commands.tenants import list_tenants, tenant_users
     from unityauth_cli.commands.roles import list_roles
+    from unityauth_cli.commands.permissions import list_permissions
 
     # Register authentication commands
     cli.add_command(login)
@@ -274,3 +275,11 @@ def role():
         pass
 
     role.add_command(list_roles, name='list')
+
+    # Register permissions commands
+    @cli.group()
+    def permissions():
+        """Permission discovery and verification commands."""
+        pass
+
+    permissions.add_command(list_permissions, name='list')

unityauth-cli/src/unityauth_cli/commands/permissions.py

@@ -0,0 +1,105 @@
+"""Permission commands: list, check.
+
+Handles permission discovery and verification operations.
+"""
+
+import sys
+
+import click
+
+from unityauth_cli.cli import (
+    CLIContext,
+    console,
+    error,
+    handle_error,
+    info,
+    pass_context,
+    require_auth,
+    success,
+    warning,
+)
+from unityauth_cli.client import UnityAuthAPIClient
+from unityauth_cli.formatters.table import format_table
+from unityauth_cli.formatters.json_fmt import format_json
+from unityauth_cli.formatters.csv_fmt import format_csv
+from unityauth_cli.utils.errors import AuthorizationError, ValidationError
+
+
+@click.command('list')
+@click.option('--tenant-id', required=True, type=int, help='Tenant ID to check permissions for')
+@click.option('--service-id', required=True, type=int, help='Service ID to check permissions for')
+@pass_context
+@require_auth
+def list_permissions(
+    ctx: CLIContext,
+    tenant_id: int,
+    service_id: int,
+    client: UnityAuthAPIClient,
+) -> None:
+    """List your permissions for a tenant and service.
+
+    Returns all permissions the authenticated user has for the specified
+    tenant and service combination.
+
+    \b
+    Examples:
+      unityauth permissions list --tenant-id 1 --service-id 1
+      unityauth permissions list --tenant-id 1 --service-id 1 --format json
+    """
+    try:
+        # Validate IDs
+        if tenant_id <= 0:
+            raise ValidationError("Tenant ID must be a positive integer")
+        if service_id <= 0:
+            raise ValidationError("Service ID must be a positive integer")
+
+        if ctx.verbose:
+            info(f"Fetching permissions for tenant {tenant_id}, service {service_id}...")
+
+        # Build request payload
+        payload = {
+            'tenantId': tenant_id,
+            'serviceId': service_id,
+        }
+
+        # Make POST request to get permissions
+        response = client.post('/api/principal/permissions', data=payload)
+
+        # Handle error response (Failure case)
+        if response and 'errorMessage' in response:
+            error(f"Failed to get permissions: {response['errorMessage']}")
+            sys.exit(1)
+
+        # Handle success response
+        permissions = response.get('permissions', []) if response else []
+
+        if not permissions:
+            warning("No permissions found for this tenant/service combination")
+            return
+
+        # Format and display output based on format option
+        if ctx.output_format == 'json':
+            console.print(format_json({'permissions': permissions}))
+        elif ctx.output_format == 'csv':
+            # For CSV, create a simple list format
+            headers = ['permission']
+            rows = [{'permission': perm} for perm in permissions]
+            console.print(format_csv(rows, headers))
+        else:
+            # Table format (default)
+            headers = ['Permission']
+            rows = [[perm] for perm in permissions]
+            console.print(format_table(rows, headers))
+
+        if ctx.verbose:
+            info(f"Total permissions: {len(permissions)}")
+
+    except AuthorizationError as e:
+        error(
+            str(e),
+            "You may not have access to this tenant/service combination.\n"
+            "Contact your administrator for access."
+        )
+        sys.exit(3)
+    except Exception as e:
+        handle_error(e)

unityauth-cli/tests/conftest.py

@@ -1,10 +1,12 @@
 """Shared pytest fixtures for UnityAuth CLI tests."""
 
 import pytest
+from click.testing import CliRunner
 from unittest.mock import MagicMock, patch
 
 from unityauth_cli.cli import CLIContext
 from unityauth_cli.config import Configuration
+from unityauth_cli.client import UnityAuthAPIClient
 
 
 @pytest.fixture
@@ -45,3 +47,20 @@ def mock_requests_session():
         session_instance = MagicMock()
         mock.return_value = session_instance
         yield session_instance
+
+
+@pytest.fixture
+def cli_runner():
+    """Create a Click CLI test runner."""
+    return CliRunner()
+
+
+@pytest.fixture
+def mock_api_client():
+    """Create a mock API client."""
+    client = MagicMock(spec=UnityAuthAPIClient)
+    client.get.return_value = None
+    client.post.return_value = None
+    client.patch.return_value = None
+    client.delete.return_value = None
+    return client