RysePackage.Corsario 1.0.0

Corsario

Corsario e uma biblioteca para .NET voltada a configuracao centralizada e segura de CORS em aplicacoes ASP.NET Core. O pacote encapsula o registro das politicas, a leitura das configuracoes e a validacao das combinacoes sensiveis para reduzir erros de setup e manter o comportamento consistente entre ambientes.

Objetivo

O objetivo do Corsario e simplificar a configuracao de CORS sem abrir mao de regras importantes de seguranca. Em vez de espalhar AddCors, nomes de politica e validacoes manuais por varios projetos, a biblioteca concentra esse fluxo em uma API pequena e previsivel.

O Corsario foi pensado para cenarios em que precisamos:

• habilitar ou desabilitar CORS por configuracao
• definir origens permitidas de forma centralizada
• controlar metodos e headers permitidos
• permitir credenciais com validacao de seguranca
• evitar configuracoes invalidas como AllowCredentials=true junto com AllowAnyOrigin=true
• aplicar o middleware CORS no pipeline usando a mesma convencao em diferentes APIs

Implementacao

O pacote gira em torno de dois pontos principais:

• CorsSettings, que representa a secao CorsSettings do appsettings.json
• CorsServiceExtensions, que fornece AddConfiguredCors e UseConfiguredCors

Fluxo da biblioteca:

1. a configuracao e lida a partir da secao CorsSettings
2. se o recurso estiver desabilitado, uma politica de fallback e registrada
3. se estiver habilitado, as configuracoes sao validadas
4. a politica CORS e criada com base em origens, metodos, headers e credenciais
5. o middleware pode ser aplicado no pipeline com a extensao correspondente

Regras importantes da implementacao:

• AllowCredentials=true exige origens explicitas
• AllowCredentials=true nao pode ser combinado com AllowAnyOrigin=true
• origens informadas devem ser URLs absolutas validas
• quando AllowedMethods vier vazio, a configuracao e tratada como invalida
• o cache de preflight e configurado com 10 minutos

Instalacao

.NET CLI

dotnet add package Corsario

PackageReference

<PackageReference Include="Corsario" Version="1.0.0" />

Configuracao Basica

appsettings.json

{
  "CorsSettings": {
    "Enabled": true,
    "AllowedOrigins": "https://app.rysecode.com,https://admin.rysecode.com",
    "AllowCredentials": true,
    "AllowedMethods": "GET,POST,PUT,DELETE,OPTIONS",
    "AllowedHeaders": "Content-Type,Authorization",
    "AllowAnyOrigin": false
  }
}

Program.cs

using RysePackage.Corsario.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddConfiguredCors(builder.Configuration);

var app = builder.Build();

app.UseRouting();
app.UseConfiguredCors(app.Configuration);
app.UseAuthorization();

app.MapControllers();

app.Run();

Cenarios de Uso

API com credenciais e origens explicitas

Esse e o cenario recomendado quando a aplicacao precisa aceitar cookies, autenticacao baseada em sessao ou headers protegidos em frontends conhecidos.

{
  "CorsSettings": {
    "Enabled": true,
    "AllowedOrigins": "https://app.rysecode.com,https://portal.rysecode.com",
    "AllowCredentials": true,
    "AllowedMethods": "GET,POST,PUT",
    "AllowedHeaders": "Content-Type,Authorization",
    "AllowAnyOrigin": false
  }
}

API publica sem credenciais

Quando o endpoint pode ser acessado por qualquer origem e nao depende de cookies ou credenciais cross-origin, e possivel liberar todas as origens com mais simplicidade.

{
  "CorsSettings": {
    "Enabled": true,
    "AllowedOrigins": "",
    "AllowCredentials": false,
    "AllowedMethods": "GET,OPTIONS",
    "AllowedHeaders": "Content-Type",
    "AllowAnyOrigin": true
  }
}

Wildcard de subdominios

Ao definir origens explicitas, o Corsario tambem habilita suporte a subdominios curinga por meio da configuracao de politica do ASP.NET Core.

{
  "CorsSettings": {
    "Enabled": true,
    "AllowedOrigins": "https://*.rysecode.com",
    "AllowCredentials": true,
    "AllowedMethods": "GET,POST",
    "AllowedHeaders": "Content-Type,Authorization",
    "AllowAnyOrigin": false
  }
}

Quando Usar

O Corsario e indicado para:

• APIs ASP.NET Core que desejam padronizar configuracao de CORS
• projetos com multiplos ambientes e necessidade de centralizar origens permitidas
• bibliotecas internas e templates de API que precisam de uma convencao unica
• equipes que querem reduzir erro humano em configuracoes sensiveis de CORS

Licenca

Este projeto esta licenciado sob a licenca MIT.