# Multi-Tenant Scope-Based Authorization

## Module
Authority

## Status
IMPLEMENTED

## Description
Multi-tenant authorization with scope-based access control integrated across modules. Tenants are isolated via tenant-scoped OAuth2 scopes and authorization policies.

## Implementation Details
- **Tenant Catalog**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Tenants/AuthorityTenantCatalog.cs` -- manages tenant registration, metadata, and tenant-scoped configuration.
- **Tenant Header Filter**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Console/TenantHeaderFilter.cs` -- extracts the tenant identifier from HTTP headers and sets the tenant context for the request.
- **Tenancy Defaults**: `src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsTenancyDefaults.cs` -- defines default tenant header name, claim types, and tenancy constants.
- **Scopes**: `src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs` -- enumerates all OAuth2 scopes (module-level, resource-level, admin) used across the platform.
- **Scope Authorization Handler**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/StellaOpsScopeAuthorizationHandler.cs` -- ASP.NET authorization handler that evaluates scope requirements against the user's token scopes.
- **Scope Requirement**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/StellaOpsScopeRequirement.cs` -- authorization requirement specifying required scopes.
- **Resource Server Policies**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/StellaOpsResourceServerPolicies.cs` -- pre-defined authorization policies for each module (Scanner, Attestor, Policy, etc.) using scope-based requirements.
- **Authorization Policy Builder Extensions**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/StellaOpsAuthorizationPolicyBuilderExtensions.cs` -- extension methods for adding scope policies: `RequireScope`, `RequireAnyScope`.
- **Resource Server Options**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/StellaOpsResourceServerOptions.cs` -- configuration for resource server authentication (Authority URL, audience, required scopes).
- **Tenant Entity**: `src/Authority/__Libraries/StellaOps.Authority.Persistence/Postgres/Models/TenantEntity.cs` -- database entity for tenants.
- **Tenant Repository**: `src/Authority/__Libraries/StellaOps.Authority.Persistence/Postgres/Repositories/TenantRepository.cs` (implements `ITenantRepository`) -- CRUD for tenant records.
- **Tests**: `src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration.Tests/`

## E2E Test Plan
- [ ] Create two tenants (tenant-a, tenant-b) via `AuthorityTenantCatalog` and verify each is persisted with isolated configuration
- [ ] Request a token with tenant-a scopes and attempt to access tenant-b resources; verify access is denied with 403
- [ ] Request a token with `scanner:read` scope and verify `StellaOpsScopeAuthorizationHandler` allows access to Scanner read endpoints but denies write endpoints
- [ ] Verify `TenantHeaderFilter` extracts the tenant ID from the `X-Tenant-Id` header and sets the correct tenant context
- [ ] Configure `StellaOpsResourceServerPolicies` for a module and verify all endpoints enforce the correct scope policies
- [ ] Request a token with admin scopes and verify it grants cross-tenant access when configured
- [ ] Verify `StellaOpsScopes` enumerations match the scopes registered in the OpenIddict server configuration