AtlasNuc 1.0.26

AtlasCore

Shared contracts for Atlas platform services.

Purpose

AtlasCore provides reusable, service-agnostic audit contracts so all services can publish and query audit events in a consistent format.

Install the current package:

<PackageReference Include="AtlasNuc" Version="1.0.20" />

Current shared contracts live under Audit/Contracts:

• AuditEventDto (includes ActorName and EventTimeUtc for actor identity and timestamp)
• AuditContext
• AuditQueryRequest
• UserType, ResultStatus
• AuditActionCodes (baseline/common examples)

Shared approval-service integration lives under Approval (every source service integrates with the central Atlas Approval Service through these):

• Contracts/ApprovalRequestDto — the service-to-approval request contract (processCode, sourceService, sourceEntityId, requestReference, payloadSnapshot, renderSchema, callbackUrl/eventTopic, correlationId)

• Contracts/ApprovalRequirementResult, ApprovalRequestSnapshot, ApprovalDecisionCallback

• Contracts/RenderSchema + RenderFieldTypes — dynamic approval rendering metadata

• Validation/ProcessCodeValidator — Atlas.{Service}.{Module}.{Action} naming (allows nested modules, e.g. Atlas.Customer.Profile.Email.Update)

• Idempotency/ApprovalReferenceGenerator — requestReference/correlationId helpers

• Builders/ApprovalRequestBuilder — fluent, validated request construction

• Client/IApprovalClient + AddAtlasApprovalClient(configuration) — typed client for requirement checks, idempotent request creation and status queries (config section AtlasApproval: BaseUrl, ApiKey, ForwardBearerToken, Timeout)

• Integration/IApprovalGate — one-call integration pattern: check requirement → execute immediately when disabled → otherwise submit and short-circuit pending (fail-closed when the requirement check is unavailable)

• Callbacks/IApprovalCallbackVerifier + AddAtlasApprovalCallbackVerifier(configuration) — verifies HMAC-SHA256 signed decision callbacks (X-Approval-Signature, X-Approval-Timestamp, replay window) and surfaces the DecisionId for inbox dedup (config section AtlasApprovalCallback: SigningKey, ReplayWindowMinutes)

• Callbacks/AddAtlasApprovalCallback() (on AuthenticationBuilder) — registers the ApprovalCallback authentication scheme so the callback endpoint carries a normal [Authorize(AuthenticationSchemes = ApprovalCallbackAuthenticationDefaults.Scheme)] instead of [AllowAnonymous]. The handler runs the HMAC check in the auth pipeline and stashes the verified callback on HttpContext.Items[…CallbackItemKey] so the action reads it without re-parsing or re-verifying. Chain it onto your existing AddAuthentication().AddJwtBearer(...); the default user-JWT scheme is untouched.

  builder.Services.AddAtlasApprovalCallbackVerifier(builder.Configuration);
  builder.Services.AddAuthentication(/* default JWT */)
      .AddJwtBearer(/* ... */)
      .AddAtlasApprovalCallback();   // using AtlasCore.Approval.Callbacks;
  

Shared configuration helpers live under Configuration:

• AtlasKeyVaultExtensions.AddAtlasKeyVault() — layers Azure Key Vault over the host configuration when KeyVault:Uri is set (no-op otherwise). One line per service:

  var builder = WebApplication.CreateBuilder(args);
  builder.AddAtlasKeyVault();   // using AtlasCore.Configuration;
  

  Vault secret names map nested keys with -- (e.g. JwtSettings--Key, ConnectionStrings--MySQLConnection) and override appsettings. Auth uses DefaultAzureCredential (service-principal env vars on a server, az login on a dev box).

Shared authorization artifacts live under Authorization:

• Contracts/IUserCategoryAccessor
• Contracts/ApiErrorResponse
• Filters/AdminUserFilter
• Permissions/IPermissionLookup
• Permissions/HasPermissionAttribute
• Permissions/PermissionAuthorizationRequirement
• Permissions/PermissionAuthorizationPolicyProvider
• Permissions/PermissionAuthorizationHandler
• Permissions/PermissionCodePacker
• Permissions/PermissionClaimConstants
• Permissions/ICurrentUserPermissionProvider
• Permissions/RemoteCurrentUserPermissionProvider
• Permissions/PermissionClaimConstants.PlatformAccessAllPermissionCode
• Ip/BypassIpRestrictionAttribute
• Ip/AuthorizedIpAddressMiddleware
• Encryption/EncryptedBypassIpRestrictionAttribute
• Encryption/EncryptedRequestBodyFilter
• Encryption/EncryptedResponseBodyFilter
• Encryption/IEncryptedBodyService
• Encryption/IApiResultStatusCodeResolver

Atlas.Platform.AccessAll.Configure is the only platform-wide super-admin permission code. When it is present in the authenticated user's PermissionCodes claim, permission authorization succeeds for every [HasPermission(...)] requirement. Legacy packed permissions authorize exact permissions only and no longer provide an AccessAll bypass. Assignment and removal of the platform permission must be tightly controlled and audited.

Shared API controller artifacts live under Api/Controllers:

• AtlasBaseController
• IAtlasModelStateErrorFactory
• IAtlasResponseProtector
• IAtlasResponseStatusCodeResolver
• ReflectionAtlasResponseStatusCodeResolver
• AddAtlasBaseControllerSupport

Action Code Strategy (Generic + Reusable)

Do not rely on a single global enum/list for every service action.

Use this model:

1. AtlasCore keeps only common baseline action codes.
2. Each service defines its own local action catalog.
3. All action codes follow one naming convention.

Naming Convention

Use:

<Domain>.<Subdomain>.<Action>

Examples:

• Customer.Transfer.Initiated
• Admin.User.Disabled
• System.Integration.Call
• Loan.Application.Approved

Rules:

• PascalCase segments
• Dot-separated hierarchy
• Stable codes (append new, avoid renaming old)

Example: Service-Owned Action Catalog

namespace AtlasDigitalBank.Service.Audit;

public static class DigitalBankAuditActions
{
    public const string CustomerTransferInitiated = "Customer.Transfer.Initiated";
    public const string CustomerTransferCompleted = "Customer.Transfer.Completed";
    public const string AdminFeatureToggled = "Admin.Feature.Toggled";
    public const string LoanApplicationApproved = "Loan.Application.Approved";
}

Example: Publishing an Audit Event

using AtlasCore.Audit.Contracts;

var evt = new AuditEventDto
{
    UserType = UserType.Customer,
    UserId = customerId,
    ServiceName = "AtlasDigitalBank",
    ActionCode = DigitalBankAuditActions.CustomerTransferInitiated,
    ResultStatus = ResultStatus.Success,
    TargetType = "Wallet",
    TargetId = walletId,
    Context = new AuditContext
    {
        Channel = "API",
        CorrelationId = correlationId,
        AppVersion = appVersion
    }
};

Example: Querying with ATLAS Pagination Style

AuditQueryRequest follows the ATLAS request pattern:

• PageNumber
• PageSize

var query = new AuditQueryRequest
{
    UserType = UserType.Admin,
    ServiceName = "AtlasDigitalBank",
    FromUtc = DateTime.UtcNow.AddDays(-7),
    ToUtc = DateTime.UtcNow,
    PageNumber = 1,
    PageSize = 50
};

API Response Pattern

For consistency with existing ATLAS API style, list endpoints should return:

• list payload in Result
• total records in top-level Count

This avoids embedding custom paged wrapper objects in shared contracts.

Shared Admin Authorization Filter

AdminUserFilter is now reusable from AtlasCore.Authorization.Filters and checks that the current user category is AdminUser.

To use it in a service:

using AtlasCore.Authorization.Contracts;
using AtlasCore.Authorization.Filters;

public sealed class AuthUserCategoryAccessor : IUserCategoryAccessor
{
    private readonly IAuthUser _authUser;

    public AuthUserCategoryAccessor(IAuthUser authUser)
    {
        _authUser = authUser;
    }

    public string? UserCategory => _authUser.UserCategory;
}

services.AddScoped<IUserCategoryAccessor, AuthUserCategoryAccessor>();
services.AddScoped<AdminUserFilter>();

Shared Permission Authorization

AtlasCore centralizes the permission enforcement pipeline, but it does not own each service's permission catalog.

Use this split:

• AtlasCore owns the policy provider, authorization handler, claim constants, and optional remote permission provider.
• Each service owns its atomic permission-code catalog and local legacy lookup.
• Admin assignment is centralized in ATLAS using the same string codes issued in the PermissionCodes claim.
• Legacy packed permissions authorize exact mapped permissions only. They do not provide an AccessAll bypass.
• Atlas.Platform.AccessAll.Configure is the only JWT global permission bypass.

Service-Owned Permission Catalog

Each service should use atomic string constants:

namespace AtlasWallet.Services.Authorization;

public static class WalletPermissionCodes
{
    public const string SavingsReportRead = "Atlas.Wallet.SavingsReport.Read";
    public const string SavingsReportExport = "Atlas.Wallet.SavingsReport.Export";
}

Legacy Lookup Adapter

The lookup is retained only for exact legacy packed-permission compatibility:

using AtlasCore.Authorization.Permissions;

namespace AtlasWallet.Services.Authorization;

public sealed class AtlasPermissionLookup : IPermissionLookup
{
    private static readonly IReadOnlyDictionary<string, short> Codes =
        new Dictionary<string, short>(StringComparer.OrdinalIgnoreCase)
        {
            [WalletPermissionCodes.SavingsReportRead] = 1001,
            [WalletPermissionCodes.SavingsReportExport] = 1002
        };

    public bool TryResolvePermission(string permissionName, out short permissionCode)
    {
        return Codes.TryGetValue(permissionName, out permissionCode);
    }
}

Service Registration

Register the shared authorization pipeline once:

using AtlasCore.Authorization.Permissions;

services.AddAtlasPermissionAuthorization<AtlasPermissionLookup>();

Controller Usage

Services can keep a local wrapper attribute:

using AtlasCore.Authorization.Permissions;

namespace AtlasWallet.Services.Authorization;

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, Inherited = false)]
public sealed class HasPermissionAttribute : AtlasCore.Authorization.Permissions.HasPermissionAttribute
{
    public HasPermissionAttribute(string permissionCode)
        : base(permissionCode)
    {
    }
}

Then controller usage stays unchanged:

[HasPermission(WalletPermissionCodes.SavingsReportExport)]
public IActionResult ExportSavingsReport()
{
    // ...
}

JWT Permission Claims

Issue atomic permission codes in the shared PermissionCodes claim:

new Claim(
    PermissionClaimConstants.PermissionCodesClaimType,
    string.Join(PermissionClaimConstants.PermissionCodesSeparator, permissionCodes))

For Super Admin, issue:

new Claim(
    PermissionClaimConstants.PermissionCodesClaimType,
    PermissionClaimConstants.PlatformAccessAllPermissionCode)

Legacy packed claims remain supported for exact permissions only:

var packedPermissions = PermissionCodePacker.PackPermissionsIntoString(legacyPermissionCodes);
new Claim(PermissionClaimConstants.PackedPermissionClaimType, packedPermissions);

Optional Remote Permission Validation

Services that require current centralized permissions rather than JWT-only authorization can register the remote provider:

services.AddAtlasPermissionAuthorization<AtlasPermissionLookup>();
services.AddAtlasRemotePermissionProvider(configuration);

Configuration:

{
  "AtlasPermissions": {
    "BaseUrl": "https://atlas-api.example.com/",
    "SnapshotPath": "api/Permission/me",
    "Timeout": "00:00:03"
  }
}

Shared IP Restriction + Encrypted Request/Response Filters

AtlasCore also centralizes the common API authorization pattern used by services that need:

• IP safelist enforcement
• per-action IP bypass metadata
• encrypted request-body decryption
• encrypted response-body wrapping

Service Adapter

Each service owns its encryption implementation and adapts it to IEncryptedBodyService:

using AtlasCore.Authorization.Encryption;

public sealed class ServiceEncryptedBodyService : IEncryptedBodyService
{
    private readonly EncryptionBodyHelper _encryptionBodyHelper;

    public ServiceEncryptedBodyService(EncryptionBodyHelper encryptionBodyHelper)
    {
        _encryptionBodyHelper = encryptionBodyHelper;
    }

    public string DecryptString(string encryptedText)
    {
        return _encryptionBodyHelper.DecryptString(encryptedText);
    }

    public string EncryptResponseData(object response)
    {
        return _encryptionBodyHelper.EncryptResponseData(response);
    }
}

Shared Base Controller

Use AtlasBaseController to standardize model-state errors, success/error HTTP status handling, and optional response protection without coupling AtlasNuc to a service-specific ApiResult type.

Register the shared controller support:

using AtlasCore.Api.Controllers;

services.AddAtlasBaseControllerSupport<ServiceModelStateErrorFactory>();

For encrypted/protected responses:

services.AddAtlasBaseControllerSupport<
    ServiceModelStateErrorFactory,
    ServiceResponseProtector>();

Controller usage:

public sealed class SavingsController(
    IAtlasModelStateErrorFactory modelStateErrorFactory,
    IAtlasResponseProtector responseProtector,
    IAtlasResponseStatusCodeResolver statusCodeResolver)
    : AtlasBaseController(modelStateErrorFactory, responseProtector, statusCodeResolver)
{
    [HttpGet]
    public IActionResult Get()
    {
        return Response(service.Get());
    }
}

Service Registration

using AtlasCore.Authorization.Encryption;

services.AddAtlasEncryptedAuthorization<ServiceEncryptedBodyService, DefaultApiResultStatusCodeResolver>(options =>
{
    options.DecryptRequests = true;
    options.EncryptResponses = true;
});

EncryptResponses is configurable so services can keep environment-specific behavior, for example encrypt only in release builds.

Middleware

using AtlasCore.Authorization.Ip;

var allowedIpAddress = app.Configuration["AllowedIPAddress"];
var allowedRequestPaths = app.Configuration["AllowedApiRequest"] ?? string.Empty;

app.UseMiddleware<AuthorizedIpAddressMiddleware>(allowedIpAddress, allowedRequestPaths);

Controller Usage

Use one attribute instead of stacking IP bypass, decrypt, and encrypt filters:

using AtlasCore.Authorization.Encryption;

[HttpPost("admin/terminate")]
[EncryptedBypassIpRestriction]
public Task<IActionResult> AdminTerminate([FromBody] BreakSavingsDto model)
{
    // ...
}

To allow only specific IPs for a bypassed endpoint:

[EncryptedBypassIpRestriction("10.0.0.5", "10.0.1.0/24")]

RabbitMQ Ingress Contract (Shared)

Use the shared messaging contracts under AtlasCore.Audit.Messaging to standardize producer and consumer behavior across services.

Shared types:

• AuditIngressEnvelope
• AuditIngressHeaders
• AuditIngressOptions
• AuditIngressValidationCode
• AuditIngressValidationResult

Producer Example

using System.Text;
using System.Text.Json;
using AtlasCore.Audit.Contracts;
using AtlasCore.Audit.Messaging;

var evt = new AuditEventDto
{
    EventId = Guid.NewGuid().ToString("N"),
    EventTimeUtc = DateTime.UtcNow,
    UserType = UserType.Customer,
    UserId = "cus-001",
    ServiceName = "ATLAS",
    ActionCode = "Transfer.Initiated",
    ResultStatus = ResultStatus.Success
};

var envelope = new AuditIngressEnvelope
{
    SchemaVersion = "1.0",
    Event = evt
};

var body = Encoding.UTF8.GetBytes(JsonSerializer.Serialize(envelope));
var props = channel.CreateBasicProperties();
props.Persistent = true;
props.MessageId = evt.EventId;
props.Headers = new Dictionary<string, object>
{
    [AuditIngressHeaders.EventType] = Encoding.UTF8.GetBytes(AuditIngressHeaders.DefaultEventType),
    [AuditIngressHeaders.ServiceName] = Encoding.UTF8.GetBytes(evt.ServiceName),
    [AuditIngressHeaders.SchemaVersion] = Encoding.UTF8.GetBytes(envelope.SchemaVersion)
};

channel.BasicPublish("atlas_audit_exchange", "atlas.customer.transfer", props, body);

Consumer Behavior

Consumers should validate:

1. Payload can be deserialized to AuditIngressEnvelope
2. schemaVersion matches expected version
3. Required headers are present and valid
4. Required AuditEventDto fields are present

When validation fails, reject-route with deterministic code using AuditIngressValidationCode (for example: reject.payload-invalid-json).

Rollout Guidance

1. Add AtlasNuc 1.0.20 in producer and consumer services.
2. Start with AllowLegacyPayload=true only during migration.
3. Disable legacy mode after all producers publish AuditIngressEnvelope with required headers.