AtlasNuc 1.0.17

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.

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 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/PermissionClaimConstants.PlatformAccessAllPermissionCode
• Ip/BypassIpRestrictionAttribute
• Ip/AuthorizedIpAddressMiddleware
• Encryption/EncryptedBypassIpRestrictionAttribute
• Encryption/EncryptedRequestBodyFilter
• Encryption/EncryptedResponseBodyFilter
• Encryption/IEncryptedBodyService
• Encryption/IApiResultStatusCodeResolver

Atlas.Platform.AccessAll.Configure is the platform-wide super-admin permission code. When it is present in the authenticated user's PermissionCodes claim, permission authorization succeeds for every [HasPermission(...)] requirement. Assignment and removal of this permission must be tightly controlled and audited.

Shared API controller artifacts live under Api/Controllers:

• AtlasBaseController
• IAtlasModelStateErrorFactory
• IAtlasResponseProtector
• IAtlasResponseStatusCodeResolver
• 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 packed-permission helpers.
• Each service owns the permission names/codes it wants to expose to admin users.
• Admin assignment can stay centralized in one authority service, as long as issued tokens use the same packed permission claim.

Service-Owned Permission Catalog

Each service can keep its own enum or constants:

namespace AtlasDigitalBank.Utilities.Permission;

public enum PermissionEnums : short
{
    AccessAll = 1,
    CanUploadBatchTransaction = 2,
    CanPostBatchTransaction = 3
}

Service Lookup Adapter

The service supplies a lookup that maps policy names to permission codes:

using AtlasCore.Authorization.Permissions;

namespace AtlasDigitalBank.Utilities.Permission;

public sealed class AtlasPermissionLookup : IPermissionLookup
{
    public short? AccessAllPermissionCode => (short)PermissionEnums.AccessAll;

    public bool TryResolvePermission(string permissionName, out short permissionCode)
    {
        if (Enum.TryParse(permissionName, ignoreCase: true, out PermissionEnums permission))
        {
            permissionCode = (short)permission;
            return true;
        }

        permissionCode = default;
        return false;
    }
}

Service Registration

Register the shared authorization pipeline once:

using AtlasCore.Authorization.Permissions;

services.AddAtlasPermissionAuthorization<AtlasPermissionLookup>();

Controller Usage

Services can keep their local wrapper attribute for enum ergonomics:

using AtlasCore.Authorization.Permissions;

namespace AtlasDigitalBank.Utilities.Permission;

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

Then controller usage stays unchanged:

[HasPermission(PermissionEnums.CanUploadBatchTransaction)]
public IActionResult UploadBatch()
{
    // ...
}

Packing JWT Permission Claims

Use the shared helper when issuing tokens:

using AtlasCore.Authorization.Permissions;

var packedPermissions = PermissionCodePacker.PackPermissionsIntoString(
    userPermissions.Select(permission => (short)permission));

Write the value into the shared claim name:

new Claim(PermissionClaimConstants.PackedPermissionClaimType, packedPermissions)

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);
    }
}

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.9 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.