DEV Community: Sergey Chin

Secure Note Manager in React - Part 2. Client-Side Login with Web Crypto and Redux

Sergey Chin — Mon, 07 Jul 2025 15:49:20 +0000

Introduction

In this second part of the series, we’ll build a simple yet secure login page — entirely without a backend. Using only browser-based cryptography, local storage, and Redux, we’ll create a seamless login experience.

Here’s what we’ll implement:

An in-memory secret key store using Redux.
Protection for the main vault page based on key presence.
A login form that authorizes the user via a master password.

The full project is available on GitHub.

You can play with the completed app here.

In-Memory Secret Key Store

To securely hold the cryptographic key during a session, we use Redux to store it in memory only. This means the key disappears when the app reloads — which is exactly what we want for handling sensitive data.

Here’s the vault slice:

import { createSlice, type PayloadAction } from "@reduxjs/toolkit";

interface VaultSliceType {
    // Stores a CryptoKey used for encryption/decryption in memory
  secretKey: CryptoKey | null;
  // Numeric toggle used to manually trigger reactivity in components
  updateTrigger: number;
}

// Function to return the initial state for the vault slice
const getInitialState = (): VaultSliceType => {
  return { 
      secretKey: null, // No key initially
      updateTrigger: 0 // Default trigger value
  };
};

// Create the Redux slice for vault state management
const vaultSlice = createSlice({
  name: "vault",
  initialState: getInitialState(),
  reducers: {
      // Action to store a new CryptoKey in state
    updateSecretKey: (state, action: PayloadAction<CryptoKey>) => {
      if (action.payload) {
        state.secretKey = action.payload;
      }
    },

    // Action to toggle the updateTrigger value (0 <-> 1)
    // Useful for manually triggering updates in subscribers (e.g., React components)
    triggerUpdate: (state) => {
      state.updateTrigger = state.updateTrigger === 0 ? 1 : 0;
    },
  },
  selectors: {
      // Selector to retrieve the trigger updates
    getUpdateTrigger: (state) => {
      return state.updateTrigger;
    },
    // Selector to retrieve the secret key
    getSecretKey: (state) => {
      return state.secretKey;
    },
  },
});

export const { updateSecretKey, triggerUpdate } = vaultSlice.actions;
export const { getSecretKey, getUpdateTrigger } = vaultSlice.selectors;
export default vaultSlice;

Why `triggerUpdate` is Needed

This is a technique to trigger reactivity in the UI when the key changes or vault data is updated. By toggling updateTrigger, we signal to React components that the vault state has changed.

Security Considerations

The CryptoKey is stored only in memory and never persisted.
Once the app reloads or closes, the key is lost by design.
This is ideal for secure, ephemeral sessions tied to a master password.

Securing Access to Vault Page

To ensure that only authenticated users can access the vault, we check whether a CryptoKey is present in Redux. If it's missing, the user is redirected to the login page.

import { useSelector } from "react-redux";
import { getSecretKey } from "@/store/slices/vaultSlice";

const VaultPage = () => {
    const secretKey = useSelector(getSecretKey);

    if (!secretKey) {
        return <Navigate to={"/auth/local-login"} />
    }

    // ...
}

We'll complete the rest of the VaultPage component in an upcoming part of this series.

Login Page

Now let’s build the login interface. This component accepts a master password, derives a CryptoKey from it using a salt, and checks whether the derived key matches the stored digest. If the match is successful, the key is stored in Redux and the user is allowed to proceed.

import { localStorageService } from "@/storage/local-storage/localStorageService";
import { triggerUpdate, updateSecretKey } from "@/store/slices/vaultSlice";
import { cryptoUtils } from "@/utils/cryptoUtils";
import { useState } from "react";
import { useDispatch, useSelector } from "react-redux";
import { useNavigate } from "react-router-dom";

// This component implements the local login flow using a master password
const LocalLoginPage = () => {
  // React state to hold the user's input
  const [masterPassword, setMasterPassword] = useState<string>("");

  // These values are read once from localStorage at render time.
  // 1. The digest (hash) of the previously derived key
  // 2. The salt that was originally used to derive the key
  const storedSecretKeyDigest = useSelector(() => localStorageService.getSecretKeyDigestBase64());
  const storedSalt = useSelector(() => localStorageService.getSecretKeySalt());

  // Redux dispatch and router navigation functions
  const dispatch = useDispatch();
  const navigate = useNavigate();

  // Handles form submission (when user clicks "Submit")
  const handleSubmit = async (e: any) => {
    e.preventDefault();

    // If a salt was previously stored, reuse it; otherwise generate a new one
    const salt = storedSalt !== null ? storedSalt : cryptoUtils.generateSalt();

    // Derive a CryptoKey from the password and salt using PBKDF2
    const secretKey = await cryptoUtils.deriveSecretKey(masterPassword, salt);

    // Export the CryptoKey to ArrayBuffer for hashing
    const secretKeyExported = await cryptoUtils.exportKey(secretKey);

    // Create a base64-encoded digest of the exported key (used for verification)
    const secretKeyHash = await cryptoUtils.digestAsBase64(secretKeyExported);

    // If a stored digest exists and doesn't match the current one, password is wrong
    if (storedSecretKeyDigest && storedSecretKeyDigest !== secretKeyHash) {
      alert("Incorrect master password");
      return;
    }

    // Save the salt and digest for future validation (not the actual key!)
    localStorageService.setSecretKeySalt(cryptoUtils.arrayBufferToBase64(salt));
    localStorageService.setSecretKeyDigest(secretKeyHash);

    // Store the derived CryptoKey in Redux state (in-memory only)
    dispatch(updateSecretKey(secretKey));

    // Trigger a Redux update so any dependent components can react
    dispatch(triggerUpdate());

    // Navigate to the vault after successful login
    navigate("/vault", { flushSync: true });
  };

  // Render the form UI
  return <>
    {/* Top navigation bar */}
    <div className="navbar bg-base-100">
      <div className="navbar-start" />
      <div className="navbar-center">
        <a className="btn btn-ghost text-xl">Local Auth</a>
      </div>
      <div className="navbar-end" />
    </div>

    {/* Main login form */}
    <div className="m-4">
      <form onSubmit={handleSubmit}>
        <fieldset className="fieldset w-full">
          <legend className="fieldset-legend text-sm">Master Password</legend>

          {/* Input for the master password */}
          <input 
            value={masterPassword}
            onChange={e => setMasterPassword(e.target.value)}
            type="password"
            className="input w-full"
            placeholder="Input password..."
            required
          />
        </fieldset>

        {/* Submit button */}
        <div className="flex">
          <div className="flex-1 px-1">
            <button className="btn btn-primary mt-5 w-full" type="submit">
              Submit
            </button>
          </div>
        </div>
      </form>
    </div>
  </>;
};

export default LocalLoginPage;

Summary of The Code Above

User Enters Password

The master password is captured via a controlled input.

Key Derivation with Salt

Using PBKDF2, the app derives a CryptoKey from the password and salt. This is standard practice to make password-based cryptography secure and resistant to brute-force attacks.

Verification via Digest

If a key was already registered (a digest exists), the newly derived key is hashed and compared with the stored digest. If it doesn't match — the password is wrong.

Secure In-Memory Key Storage

If verification passes (or this is first-time login), the app saves:

The salt and digest to localStorage
The actual key to Redux state only, never persisted

Vault Access Granted

On success, the user is navigated to /vault, and any components depending on the vault state will react via Redux.

Summary

In this part, we:

Implemented an in-memory store for a CryptoKey using Redux.
Protected the vault route by checking for key presence.
Built a secure, backend-free login page using PBKDF2 and local storage.

This approach keeps the user's encryption key off disk, supports secure session-based access, and allows for a fully offline login experience.

In the next part, we’ll continue building the actual vault UI.

Custom exception handling in Spring Boot

Sergey Chin — Wed, 25 Jun 2025 06:44:42 +0000

Introduction

One of the important tasks in creating an API is to return understandable error messages. Spring Boot already has a predefined error message format, but this format is not always acceptable and our application may require a custom format.

In this tutorial, we'll configure Spring Boot's exception handling so that our backend application will respond with an error message in the following format:

{
    "guid": "DCF70619-01D8-42a9-97DC-6005F205361A",
    "errorCode": "application-specific-error-code",
    "message": "Error message",
    "statusCode": 400,
    "statusName": "BAD_REQUEST",
    "path": "/some/path",
    "method": "POST",
    "timestamp": "2022-12-06"
}

Explanation of the format:

guid — unique global identifier of the error, this field is useful for searching errors in a large log.
errorCode — an application specific error code derived from business logic rules.
message — description of an error.
statusCode — HTTP status code.
statusName — full name of the HTTP status code.
path — URI of the resource where the error occurred.
method — used HTTP method.
timestamp — timestamp of the error creation.

Implementation

As an example we will make REST API for working with city list.

After creating Spring Boot project via Spring Initializer or manually, add next classes two classes to the project: ApplicationException and ApiErrorResponse.

import lombok.AllArgsConstructor;
import lombok.Getter;
import org.springframework.http.HttpStatus;

@Getter
@AllArgsConstructor
public class ApplicationException extends RuntimeException {
    private final String errorCode;
    private final String message;
    private final HttpStatus httpStatus;
}

ApplicationException will be thrown, when exception situation occurred in the application.

import lombok.Data;
import java.time.LocalDateTime;

@Data
public class ApiErrorResponse {
    private final String guid;
    private final String errorCode;
    private final String message;
    private final Integer statusCode;
    private final String statusName;
    private final String path;
    private final String method;
    private final LocalDateTime timestamp;
}

ApiErrorResponse is DTO object for serializing to JSON response.

Next, add class ApplicationExceptionHandler that will be handling all exceptions of the application.

import io.github.sergiusac.exceptionhandling.response.ApiErrorResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import javax.servlet.http.HttpServletRequest;
import java.time.LocalDateTime;
import java.util.UUID;

@Slf4j
@RestControllerAdvice
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ApplicationExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(ApplicationException.class)
    public ResponseEntity<?> handleApplicationException(
            final ApplicationException exception, final HttpServletRequest request
    ) {
        var guid = UUID.randomUUID().toString();
        log.error(
                    String.format("Error GUID=%s; error message: %s", guid, exception.getMessage()), 
            exception
        );
        var response = new ApiErrorResponse(
                guid,
                exception.getErrorCode(),
                exception.getMessage(),
                exception.getHttpStatus().value(),
                exception.getHttpStatus().name(),
                request.getRequestURI(),
                request.getMethod(),
                LocalDateTime.now()
        );
        return new ResponseEntity<>(response, exception.getHttpStatus());
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleUnknownException(
        final Exception exception, final HttpServletRequest request
    ) {
        var guid = UUID.randomUUID().toString();
        log.error(
            String.format("Error GUID=%s; error message: %s", guid, exception.getMessage()), 
            exception
        );
        var response = new ApiErrorResponse(
                guid,
                ErrorCodes.INTERNAL_ERROR,
                "Internal server error",
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                HttpStatus.INTERNAL_SERVER_ERROR.name(),
                request.getRequestURI(),
                request.getMethod(),
                LocalDateTime.now()
        );
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }

}

We use RestControllerAdvice annotation to create component that handles exceptions globally in the application, and ExceptionHandler annotation is used to specify the exceptions.

handleApplicationException method handles all exceptions of ApplicationException class. This method creates GUID for exception, writes the exception to logs and makes error response for client.

handleUnknownException method does similar actions, but for all other exceptions.

Next, we create CityService for working with city list.

import io.github.sergiusac.exceptionhandling.exception.ApplicationException;
import io.github.sergiusac.exceptionhandling.model.City;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentSkipListSet;
import java.util.stream.Collectors;

@Service
public class CityService {

    private final Map<Long, City> cities = new ConcurrentHashMap<>() {
        {
            put(1L, new City(1L, "Paris", LocalDateTime.now(), LocalDateTime.now()));
            put(2L, new City(2L, "New-York", LocalDateTime.now(), LocalDateTime.now()));
            put(3L, new City(3L, "Barcelona", LocalDateTime.now(), LocalDateTime.now()));
        }
    };

    public List<City> getAllCities() {
        return cities.values().stream().collect(Collectors.toUnmodifiableList());
    }

    public City getCityById(final Long id) {
        var city = cities.get(id);
        if (city == null) {
            throw new ApplicationException(
                    "city-not-found",
                    String.format("City with id=%d not found", id),
                    HttpStatus.NOT_FOUND
            );
        }
        return city;
    }

}

The service has built-in list of cities and two methods for viewing the city list. Also getCityById method throws special ApplicationException, with provided information like error code, message and HTTP status.

Next, we create REST controller.

import io.github.sergiusac.exceptionhandling.service.CityService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequiredArgsConstructor
@RequestMapping("/cities")
public class CityController {

    private final CityService cityService;

    @GetMapping
    public ResponseEntity<?> getAllCities() {
        return ResponseEntity.ok(cityService.getAllCities());
    }

    @GetMapping("/{id}")
    public ResponseEntity<?> getCityById(@PathVariable final Long id) {
        return ResponseEntity.ok(cityService.getCityById(id));
    }

}

This controller just exposes two methods similar to the CityService.

After compiling and running the application, we should see the next result:

GET http://localhost:8080/cities

[
  {
    "id": 1,
    "cityName": "Paris",
    "createdAt": "2022-12-06T22:06:18.6921738",
    "updatedAt": "2022-12-06T22:06:18.6921738"
  },
  {
    "id": 2,
    "cityName": "New-York",
    "createdAt": "2022-12-06T22:06:18.6921738",
    "updatedAt": "2022-12-06T22:06:18.6921738"
  },
  {
    "id": 3,
    "cityName": "Barcelona",
    "createdAt": "2022-12-06T22:06:18.6921738",
    "updatedAt": "2022-12-06T22:06:18.6921738"
  }
]

As we can see, the first method returns valid response containing list of three cities.

But when we try to get city with unknown ID we get the next error response:

GET http://localhost:8080/cities/4

{
  "guid": "01913964-5777-4ec1-bd5e-392c5a5fecc9",
  "errorCode": "city-not-found",
  "message": "City with id=4 not found",
  "statusCode": 404,
  "statusName": "NOT_FOUND",
  "path": "/cities/4",
  "method": "GET",
  "timestamp": "2022-12-06T22:10:37.8993481"
}

And in the application log we also can see the appropriate error message:

Screenshot with logs

Conclusion

Implementing custom exception handlers made simple with Spring Boot, using RestControllerAdvice and ExceptionHandler annotations we implemented global error handling consolidated in only one component.

The provided code in this article is only for demonstrating purposes, and you should consider different aspects of your application while implementing custom exception handling logic.

Thanks for reading, good coding🤖

Spring WebFlux + DynamoDB + S3

Sergey Chin — Sun, 22 Jun 2025 14:08:06 +0000

Introduction

Disclaimer: the code presented in the article is not suitable for a production environment.

This article will cover an example of creating a simple API on Spring WebFlux to manage a list of audio tracks in DynamoDB and store audio files in AWS S3.

Setting up AWS services

Setting up IAM

To access AWS services from Java, we need a user under which the application will be authorized.

Let’s go to the IAM settings and create a user named aws-tracks-user.

Then you need to add Permission Policies — AmazonDynamoDBFullAccess and AmazonS3FullAccess. These policies are needed so that the application has access to DynamoDB and S3.

Also, in the section Security credentials → Access keys, you need to add an access key. This access key and the corresponding secret key will be used in application.properties.

Setting up DynamoDB

Let’s create a table aws_tutorials.tracks in DynamoDB, where information about tracks will be stored. In the Partition key field, specify name uid and the String type. Leave the rest of the settings by default.

Setting up S3

Let’s create a bucket called aws-tutorial-tracks, this bucket will store audio files. Also, in the Object Ownership section, select ACLs enabled so that the bucket takes into account our IAM settings for the aws-tracks-user.

Creating a Spring WebFlux Application

We will use Spring Boot 3.3.3 and Maven. The full pom.xml setup is below:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.3.3</version>
  <relativePath/> <!-- lookup parent from repository -->
 </parent>
 <groupId>com.example</groupId>
 <artifactId>aws-sound-service</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <name>aws-sound-service</name>
 <description>aws-sound-service</description>
 <properties>
  <java.version>21</java.version>
 </properties>
 <dependencyManagement>
  <dependencies>
   <dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>bom</artifactId>
    <version>2.27.22</version>
    <type>pom</type>
    <scope>import</scope>
   </dependency>
  </dependencies>
 </dependencyManagement>
 <dependencies>
  <!-- Spring dependencies -->
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter</artifactId>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-webflux</artifactId>
  </dependency>
  <!-- Depenency to work with DynamoDB -->
  <dependency>
   <groupId>software.amazon.awssdk</groupId>
   <artifactId>dynamodb</artifactId>
  </dependency>
  <!-- Depenencies to work with S3 -->
  <dependency>
   <groupId>software.amazon.awssdk</groupId>
   <artifactId>s3</artifactId>
  </dependency>
  <dependency>
   <groupId>software.amazon.awssdk</groupId>
   <artifactId>netty-nio-client</artifactId>
  </dependency>
  <!-- OpenAPI dependency -->
  <dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
   <version>2.3.0</version>
  </dependency>

  <dependency>
   <groupId>org.projectlombok</groupId>
   <artifactId>lombok</artifactId>
   <optional>true</optional>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-test</artifactId>
   <scope>test</scope>
  </dependency>
  <dependency>
   <groupId>io.projectreactor</groupId>
   <artifactId>reactor-test</artifactId>
   <scope>test</scope>
  </dependency>
 </dependencies>

 <build>
  <plugins>
   <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
     <excludes>
      <exclude>
       <groupId>org.projectlombok</groupId>
       <artifactId>lombok</artifactId>
      </exclude>
     </excludes>
    </configuration>
   </plugin>
  </plugins>
 </build>

</project>

Let’s add settings to application.properties:

spring.application.name=aws-sound-service
aws.region=<your_region>
aws.access-key=<your_access_key>
aws.secret-key=<your_secred_key>
aws.s3.track-bucket=aws-tutorial-tracks

In the aws.region parameter, specify the name of the region where the DynamoDB and S3 services are located, for example, eu-north-1. We created values for the aws.access-key and aws.secret-key parameters at the IAM setup section.

Let’s create the config for DynamoDB. In the configuration, you need to create an asynchronous client, since we use Spring WebFlux.

package com.example.awssoundservice.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import software.amazon.awssdk.auth.credentials.AwsCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

@Configuration
public class DynamoDbConfig {

    @Value("${aws.region}")
    private String region;

    @Value("${aws.access-key}")
    private String accessKey;

    @Value("${aws.secret-key}")
    private String secretKey;

    @Bean
    public DynamoDbAsyncClient dynamoDbAsyncClient() {
        return DynamoDbAsyncClient.builder()
                .region(Region.of(region))
                .credentialsProvider(StaticCredentialsProvider.create(new AwsCredentials() {
                    @Override
                    public String accessKeyId() {
                        return accessKey;
                    }

                    @Override
                    public String secretAccessKey() {
                        return secretKey;
                    }
                }))
                .build();
    }

}

And we will also create an asynchronous S3 client:

package com.example.awssoundservice.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.S3Configuration;

import java.time.Duration;

@Configuration
public class S3ClientConfig {

    @Value("${aws.region}")
    private String region;

    @Value("${aws.access-key}")
    private String accessKey;

    @Value("${aws.secret-key}")
    private String secretKey;

    @Bean
    public S3AsyncClient s3AsyncClient() {
        SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
                .writeTimeout(Duration.ZERO)
                .maxConcurrency(64)
                .build();
        S3Configuration serviceConfiguration = S3Configuration.builder()
                .checksumValidationEnabled(false)
                .chunkedEncodingEnabled(true)
                .build();
        return S3AsyncClient.builder()
                .httpClient(httpClient)
                .region(Region.of(region))
                .credentialsProvider(() -> AwsBasicCredentials.create(accessKey, secretKey))
                .serviceConfiguration(serviceConfiguration)
                .build();
    }

}

Let’s create a class that will store information about a track:

package com.example.awssoundservice.model;

import software.amazon.awssdk.services.dynamodb.model.AttributeValue;

import java.util.List;
import java.util.Map;

public record Track(
        String uid, // unique track identifier
        String name, // track name
        String fileKey, // unique track file key
        String fileUrl // URL to download the track
) {
    // Data mapping from DynamoDB values to a Track object
    public static Track from(Map<String, AttributeValue> valueMap) {
        return new Track(
                valueMap.get("uid").s(),
                valueMap.get("name").s(),
                valueMap.get("fileKey").s(),
                valueMap.get("fileUrl").s()
        );
    }

    public static List<Track> fromList(List<Map<String, AttributeValue>> valueMaps) {
        return valueMaps.stream().map(Track::from).toList();
    }

    // Data mapping from a Track object to DynamoDB values
    public Map<String, AttributeValue> toMap() {
        return Map.of(
                "uid", AttributeValue.builder().s(this.uid).build(),
                "name", AttributeValue.builder().s(this.name).build(),
                "fileKey", AttributeValue.builder().s(this.fileKey).build(),
                "fileUrl", AttributeValue.builder().s(this.fileUrl).build()
        );
    }
}

The library we use for DynamoDB represents data as a Map. The map key is the column name, the value of the column is stored in an object of the AttributeValue class. For simplicity, only the String type is used here.

Detailed information about what data can be stored in AttributeValue can be found here https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html.

We will also create a small class to represent the request to create and update a track:

package com.example.awssoundservice.request;

public record TrackCreateOrUpdateRequest(String name) {
}

We will store the list of DynamoDB table names in a separate class DynamoDbTables:

package com.example.awssoundservice.common;

public class DynamoDbTables {
    public static final String TRACKS = "aws_sound.tracks";
}

Now let’s create a service with business logic. First, let’s create methods for reading tracks:

package com.example.awssoundservice.service;

import com.example.awssoundservice.common.DynamoDbTables;
import com.example.awssoundservice.common.utils.AwsSdkUtils;
import com.example.awssoundservice.common.utils.FileUtils;
import com.example.awssoundservice.model.Track;
import com.example.awssoundservice.request.TrackCreateOrUpdateRequest;
import com.example.awssoundservice.response.FileResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.codec.multipart.FilePart;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Mono;
import software.amazon.awssdk.core.async.AsyncRequestBody;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.*;

import java.nio.ByteBuffer;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

@Slf4j
@Service
@RequiredArgsConstructor
public class TrackService {

    private final S3AsyncClient s3AsyncClient;
    private final DynamoDbAsyncClient dynamoDb;

    @Value("${aws.s3.track-bucket}")
    private String bucket;

    public Mono<Track> getById(String trackId) {
        GetItemRequest getItemRequest = GetItemRequest.builder()
                .tableName(DynamoDbTables.TRACKS)
                .key(Map.of("uid", AttributeValue.builder().s(trackId).build()))
                .build();
        CompletableFuture<GetItemResponse> future = dynamoDb.getItem(getItemRequest);
        return Mono.fromFuture(future)
                .map(getItemResponse -> {
                    AwsSdkUtils.checkSdkResponse(getItemResponse);
                    return Track.from(getItemResponse.item());
                });
    }

    public Mono<List<Track>> getAll() {
        ScanRequest scanRequest = ScanRequest.builder()
                .tableName(DynamoDbTables.TRACKS)
                .build();
        CompletableFuture<ScanResponse> future = dynamoDb.scan(scanRequest);
        return Mono.fromFuture(future)
                .map(scanResponse -> {
                    AwsSdkUtils.checkSdkResponse(scanResponse);
                    return Track.fromList(scanResponse.items());
                });
    }

}

The DynamoDB asynchronous client returns a CompletableFuture as its result. The Reactor library allows us to create Mono objects from a CompletableFuture using the Mono::fromFuture method.

Next, we implement methods for creating, updating and deleting tracks:

public Mono<Track> create(TrackCreateOrUpdateRequest request) {
    // fields fileKey and FileUrl are empty, 
    // because audio file is not uploaded yet
    Track track = new Track(
            UUID.randomUUID().toString(),
            request.name(),
            "",
            ""
    );
    PutItemRequest putItemRequest = PutItemRequest.builder()
            .tableName(DynamoDbTables.TRACKS)
            .item(track.toMap())
            .build();
    CompletableFuture<PutItemResponse> responseFuture = dynamoDb.putItem(putItemRequest);
    return Mono.fromFuture(responseFuture)
            .map(putItemResponse -> {
                AwsSdkUtils.checkSdkResponse(putItemResponse);
                return track;
            });
}

public Mono<Track> update(String trackId, TrackCreateOrUpdateRequest request) {
    Mono<Track> trackMono = this.getById(trackId);
    return trackMono.flatMap(currentTrack -> {
        Track updatedTrack = new Track(
                currentTrack.uid(),
                request.name(),
                currentTrack.fileKey(),
                currentTrack.fileUrl()
        );
        PutItemRequest putItemRequest = PutItemRequest.builder()
                .tableName(DynamoDbTables.TRACKS)
                .item(updatedTrack.toMap())
                .build();
        return Mono.fromFuture(dynamoDb.putItem(putItemRequest));
    }).flatMap(response -> {
        AwsSdkUtils.checkSdkResponse(response);
        return this.getById(trackId);
    });
}

public Mono<Track> delete(String trackId) {
    Mono<Track> trackMono = this.getById(trackId);
    DeleteItemRequest deleteItemRequest = DeleteItemRequest.builder()
            .tableName(DynamoDbTables.TRACKS)
            .key(Map.of("uid", AttributeValue.builder().s(trackId).build()))
            .build();
    CompletableFuture<DeleteItemResponse> deleteFuture = dynamoDb.deleteItem(deleteItemRequest);
    return trackMono.zipWith(Mono.fromFuture(deleteFuture))
            .map(objects -> {
                Track currentTrack = objects.getT1();
                DeleteItemResponse deleteResponse = objects.getT2();
                AwsSdkUtils.checkSdkResponse(deleteResponse);
                return currentTrack;
            });
}

Now let’s implement the method that will upload audio files to S3.

public Mono<Track> uploadTrackFile(String trackId, FilePart filePart) {
    String filename = filePart.filename();
    String fileKey = trackId + "/" + filename;
    PutObjectRequest putObjectRequest = PutObjectRequest.builder()
            .bucket(bucket)
            .key(fileKey)
            .contentType(Objects.requireNonNull(filePart.headers().getContentType()).toString())
            .build();
    // convert Flux<DataBuffer> to Mono<ByteBuffer>,
    // to send the entire file data to S3
    Mono<ByteBuffer> fileByteBuffer = FileUtils.dataBuffersToByteBuffer(filePart.content());
    return fileByteBuffer
            .flatMap(buffer -> Mono.fromFuture(
                    s3AsyncClient.putObject(putObjectRequest, AsyncRequestBody.fromByteBuffer(buffer))
            ))
            .map(putObjectResponse -> {
                AwsSdkUtils.checkSdkResponse(putObjectResponse);
                GetUrlRequest getUrlRequest = GetUrlRequest.builder().bucket(bucket).key(fileKey).build();
                String fileUrl = s3AsyncClient.utilities().getUrl(getUrlRequest).toExternalForm();
                return new FileResponse(
                        fileKey,
                        fileUrl
                );
            })
            .flatMap(fileResponse -> this.addFileInfoToTrack(trackId, fileResponse));
}

// save the file info (fileKey and fileUrl) to DynamoDB
private Mono<Track> addFileInfoToTrack(String trackId, FileResponse fileResponse) {
    Mono<Track> track = this.getById(trackId);
    return track.flatMap(currentTrack -> {
        Track updatedTrack = new Track(
                currentTrack.uid(),
                currentTrack.name(),
                fileResponse.fileKey(),
                fileResponse.fileUrl()
        );
        PutItemRequest putItemRequest = PutItemRequest.builder()
                .tableName(DynamoDbTables.TRACKS)
                .item(updatedTrack.toMap())
                .build();
        return Mono.fromFuture(dynamoDb.putItem(putItemRequest));
    }).flatMap(putItemResponse -> {
        AwsSdkUtils.checkSdkResponse(putItemResponse);
        return this.getById(trackId);
    });
}

In this case, we used a small utility to convert Flux to Mono. The code of the utility is below:

package com.example.awssoundservice.common.utils;

import lombok.extern.slf4j.Slf4j;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.nio.ByteBuffer;

@Slf4j
public class FileUtils {

    public static Mono<ByteBuffer> dataBuffersToByteBuffer(Flux<DataBuffer> buffers) {
        return DataBufferUtils.join(buffers).map(dataBuffer -> {
            ByteBuffer buffer = ByteBuffer.allocate(dataBuffer.readableByteCount());
            dataBuffer.toByteBuffer(buffer);
            return buffer;
        });
    }

}

Information about the uploaded file is saved in the intermediate FileResponse object.

package com.example.awssoundservice.response;

public record FileResponse (
        String fileKey,
        String fileUrl
) {
}

We also used a utility to check the response from AWS. This utility throws an exception if we receive an unsuccessful response.

package com.example.awssoundservice.common.utils;

import software.amazon.awssdk.core.SdkResponse;

import java.text.MessageFormat;

public class AwsSdkUtils {

    public static boolean isErrorSdkHttpResponse(SdkResponse sdkResponse) {
        return sdkResponse.sdkHttpResponse() == null || !sdkResponse.sdkHttpResponse().isSuccessful();
    }

    public static void checkSdkResponse(SdkResponse sdkResponse) {
        if (AwsSdkUtils.isErrorSdkHttpResponse(sdkResponse)){
            if (Objects.nonNull(sdkResponse.sdkHttpResponse())) {
                throw new IllegalStateException(
                        MessageFormat.format(
                                "{0} - {1}",
                                sdkResponse.sdkHttpResponse().statusCode(),
                                sdkResponse.sdkHttpResponse().statusText()
                        )
                );    
            } else {
                throw new IllegalStateException("Unknown error in AWS SDK");
            }
        }
    }

}

Now let’s write the REST API:

package com.example.awssoundservice.controller;

import com.example.awssoundservice.model.Track;
import com.example.awssoundservice.request.TrackCreateOrUpdateRequest;
import com.example.awssoundservice.response.GeneralResponse;
import com.example.awssoundservice.service.TrackService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.codec.multipart.FilePart;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Mono;

import java.util.List;

@RestController
@RequestMapping("/tracks")
@RequiredArgsConstructor
public class TrackController {

    private final TrackService trackService;

    @GetMapping
    public Mono<GeneralResponse<List<Track>>> getAll() {
        return trackService.getAll().map(GeneralResponse::successResponse);
    }

    @GetMapping("/{uid}")
    public Mono<GeneralResponse<Track>> getById(@PathVariable String uid) {
        return trackService.getById(uid).map(GeneralResponse::successResponse);
    }

    @PostMapping
    public Mono<GeneralResponse<Track>> create(@RequestBody TrackCreateOrUpdateRequest request) {
        return trackService.create(request).map(GeneralResponse::successResponse);
    }

    @PutMapping("/{uid}")
    public Mono<GeneralResponse<Track>> update(@PathVariable String uid, @RequestBody TrackCreateOrUpdateRequest request) {
        return trackService.update(uid, request).map(GeneralResponse::successResponse);
    }

    @DeleteMapping("/{uid}")
    public Mono<GeneralResponse<Track>> delete(@PathVariable String uid) {
        return trackService.delete(uid).map(GeneralResponse::successResponse);
    }

    @PostMapping("/{uid}/upload")
    public Mono<GeneralResponse<Track>> uploadTrackFile(
            @PathVariable String uid, @RequestPart(name = "file") Mono<FilePart> file
    ) {
        return file
                .flatMap(filePart -> trackService.uploadTrackFile(uid, filePart))
                .map(GeneralResponse::successResponse);
    }

}

The controller code is very simple, there is just one more class that wraps all responses from trackService — GeneralResponse. The code for this class is below:

package com.example.awssoundservice.response;

public record GeneralResponse<T>(
        Integer statusCode,
        String message,
        T data
) {

    public static <T> GeneralResponse<T> successResponse(T data) {
        return new GeneralResponse<>(200, "OK", data);
    }

}

A global error handler has also been added:

package com.example.awssoundservice.common;

import com.example.awssoundservice.response.GeneralResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.server.ResponseStatusException;

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<GeneralResponse<Void>> handleException(Exception ex) {
        log.error(ex.getMessage(), ex);
        return ResponseEntity.internalServerError().body(new GeneralResponse<>(
                500, ex.getMessage(), null
        ));
    }

    @ExceptionHandler(ResponseStatusException.class)
    public ResponseEntity<GeneralResponse<Void>> handleResponseStatusException(ResponseStatusException ex) {
        log.error(ex.getMessage(), ex);
        return ResponseEntity.status(ex.getStatusCode()).body(new GeneralResponse<>(
                ex.getStatusCode().value(), ex.getMessage(), null
        ));
    }

}

We have written the application, now we can open the Swagger interface and call the endpoints (http://localhost:8080/swagger-ui.html).

Deploy to EC2

The explanation of deploying the application is quite long, so I will just leave a link to a detailed explanation of how to deploy a Spring Boot application to AWS EC2 (https://learnaws.io/blog/java-ec2-deployment).

Conclusion

We have written a simple application that integrates with AWS services — DynamoDB and S3. This application is educational and is not suitable for a production environment. To improve the code, I suggest you the following:

The low-level DynamoDB library is quite difficult to use and you have to write a lot of additional code. You can use the DynamoDB Enhanced Client library (https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html).
The file upload code is not optimized for large files and high service load. An example for uploading large files can be found in the S3 SDK documentation (https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/java_s3_code_examples.html) and adapted for Spring WebFlux.
We used ACCESS_KEY_ID and SECRET_ACCESS_KEY directly in the application, but role-based access is preferable.

The entire application code is here — https://github.com/SergiusAC/webflux-dynamodb-s3-example.

Secure Note Manager in React – Part 1: Cryptography with Web Crypto API

Sergey Chin — Sun, 22 Jun 2025 11:20:08 +0000

Introduction

There are plenty of applications for securely managing notes and passwords. I thought it would be a great learning experience to try building one myself.

In this series, I’ll walk you through building a secure note manager that:

Runs entirely in the browser
Encrypts all data on the client side
Requires no backend
Never sends any sensitive data over the network

We’ll use the following tech stack:

React – for the UI and app logic
Web Crypto API – for secure, browser-native cryptographic operations
IndexedDB – for persistent storage in the browser

In this first part, we’ll focus on building the cryptographic foundation: deriving keys from passwords, encrypting and decrypting text, and handling binary data.

The full project is available on GitHub.
You can play with the completed app here.

Project Setup

The application scaffold was created using the Vite build tool (https://vite.dev/).

Routing with React Router

Routing is configured in /src/pages/routes.tsx:

import { createBrowserRouter } from "react-router-dom";
import RootApp from "./app/RootApp";

export const router = createBrowserRouter([
  {
    path: "/",
    element: <RootApp />,
    children: []
  }
]);

RootApp is our main layout component:

import { Outlet } from "react-router-dom";

const RootApp: React.FC = () => {
  return <Outlet />;
};

export default RootApp;

Right now it doesn't do anything, but we’ll add more functionality later.

Redux Store Setup

Redux is configured in /src/store/index.ts:

import { configureStore } from "@reduxjs/toolkit";

export const store = configureStore({
  reducer: {},
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(),
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

In main.tsx, we wrap the app with the store and router providers:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import { RouterProvider } from 'react-router-dom';
import { router } from './pages/routes.tsx';
import { Provider } from 'react-redux';
import { store } from './store/index.ts';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <Provider store={store}>
      <RouterProvider router={router} />
    </Provider>
  </StrictMode>
);

Implementing Cryptography

All cryptography utilities are implemented in /src/utils/cryptoUtils.ts file.

Key Derivation with PBKDF2

To safely encrypt data, we first need to turn the user’s password into a strong cryptographic key. We use PBKDF2 for this:

async deriveSecretKey(masterPassword: string, passwordSalt: ArrayBuffer): Promise<CryptoKey> {
  const masterPasswordRawKey = await crypto.subtle.importKey(
    "raw",
    textEncoder.encode(masterPassword),
    { name: "PBKDF2" },
    false,
    ["deriveKey"]
  );

  const derivedKey = await crypto.subtle.deriveKey(
    {
      name: "PBKDF2",
      salt: passwordSalt,
      iterations: 100_000,
      hash: "SHA-256"
    },
    masterPasswordRawKey,
    { name: "AES-GCM", length: 256 },
    true,
    ["encrypt", "decrypt"]
  );

  return derivedKey;
}

Let's break down the code step by step.

async deriveSecretKey(masterPassword: string, passwordSalt: ArrayBuffer): Promise<CryptoKey>

This function takes two inputs:

masterPassword: a string entered by the user.
passwordSalt: a random value (as ArrayBuffer) that makes the key derivation more secure.

It returns a CryptoKey, which is a special object used by the browser's WebCrypto API to perform cryptographic operations like encryption and decryption.

const masterPasswordRawKey = await crypto.subtle.importKey(
  "raw", 
  textEncoder.encode(masterPassword), 
  { name: "PBKDF2" }, 
  false, 
  ["deriveKey"]
);

We import the plain password into the WebCrypto API.
textEncoder.encode(masterPassword) turns the string into bytes (needed for cryptography).
"raw" tells WebCrypto that we're importing raw binary data (not an already-formatted key).
{ name: "PBKDF2" } means we’ll use this key with the PBKDF2 algorithm (Password-Based Key Derivation Function 2).
The last two values:
- false = this key is not extractable (we can’t convert it back to bytes later).
- ["deriveKey"] = this key can only be used to derive another key.

So now, we’ve turned the plain-text password into a usable format for key derivation.

const derivedKey = await crypto.subtle.deriveKey(
  { 
    name: "PBKDF2",
    salt: passwordSalt, 
    iterations: 100000,
    hash: "SHA-256" 
  },
  masterPasswordRawKey,
  { name: "AES-GCM", length: 256 },
  true,
  ["encrypt", "decrypt"]
);

Now we use PBKDF2 to transform the raw key (password) into a strong cryptographic key.

salt: A random value that prevents attackers from using precomputed hash tables (a.k.a. rainbow tables). Each user or session should have a different salt.
iterations: 100000: This makes the function slower on purpose, which increases security by making brute-force attacks expensive.
hash: "SHA-256": The hashing algorithm used within PBKDF2. A modern and secure choice.

The rest of the parameters:

The masterPasswordRawKey we created earlier is the input.
The third argument { name: "AES-GCM", length: 256 } specifies the output key:
- We'll use the key with AES-GCM (a secure encryption algorithm).
- The key length is 256 bits, which is considered strong.
true: This key is extractable (you can export it if needed).
["encrypt", "decrypt"]: This key can be used for both encrypting and decrypting data.

So this step outputs a usable AES key derived from the user's password.

Encryption & Decryption with AES-GCM

async encryptText(key: CryptoKey, text: string): Promise<EncryptionResult> {
  const iv = crypto.getRandomValues(new Uint8Array(12)); // Random IV
  const encrypted = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    key,
    textEncoder.encode(text)
  );

  return {
    ciphertext: this.arrayBufferToBase64(encrypted),
    iv: this.arrayBufferToBase64(iv)
  };
}

This function takes in:

key: A cryptographic key (derived from the user's password)
text: The plain-text string we want to encrypt

It returns a Promise that resolves to an EncryptionResult, which includes the encrypted text and the IV (initialization vector). The IV (Initialization Vector) is like a random "salt" used just once per encryption operation. It's required for AES-GCM to ensure that even if you encrypt the same text twice, the result looks different. 12 bytes (96 bits) is the recommended size for AES-GCM.

Next we're calling the browser’s built-in encrypt function.

The algorithm is AES-GCM, using the IV we just generated.
key is the CryptoKey we previously derived from the password.
textEncoder.encode(text) turns the text string into bytes before encryption.
The result (encrypted) is an ArrayBuffer containing the ciphertext (the encrypted data).

In the end we return both the encrypted data and the IV, but they are encoded as Base64 strings. This makes it easier to save or transmit the result later, because ArrayBuffers can’t be stored directly in most formats (like JSON or local storage).

Decryption looks like this:

async decryptText(key: CryptoKey, ciphertext: string, iv: string): Promise<string> {
  const ciphertextBytes = this.base64ToArrayBuffer(ciphertext);
  const ivBytes = this.base64ToArrayBuffer(iv);

  const decrypted = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv: ivBytes },
    key,
    ciphertextBytes
  );

  return textDecoder.decode(decrypted);
}

Decodes Base64 to binary.
Decrypts the data using AES-GCM.
Returns the original plain text.

Other Cryptographic Helpers

SHA-512 Hashing

Hashing is used for comparing passwords or verifying data integrity. The next code hashes the input message using SHA-512, then encodes the result in Base64

async digestAsBase64(message: ArrayBuffer | DataView): Promise<string> {
  const digest = await crypto.subtle.digest("SHA-512", message);
  return this.arrayBufferToBase64(digest);
}

crypto.subtle.digest(...): Generates a cryptographic hash of the input.
"SHA-512": A very strong hashing algorithm (512 bits).
The result is a hash digest, which we convert to a readable format using arrayBufferToBase64.

Export Keys

async exportKey(key: CryptoKey): Promise<ArrayBuffer> {
  return await crypto.subtle.exportKey("raw", key);
}

This function exports a CryptoKey back into its raw (byte) format as an ArrayBuffer.
Useful if you want to store or transfer the key (e.g. in IndexedDB or across sessions).
'raw': We want to extract the raw binary version of the key.
key: The CryptoKey you want to export.

Salt Generation

generateSalt(): ArrayBuffer {
  return crypto.getRandomValues(new Uint8Array(16));
}

generateSaltAsBase64(): string {
  const salt = crypto.getRandomValues(new Uint8Array(16));
  return btoa(String.fromCharCode(...salt));
}

Generates a random salt (a 16-byte ArrayBuffer).
Salts make password-based key derivation stronger by making each password unique.
128 bits is a common length for salts and is generally sufficient for security.
generateSaltAsBase64() is just like generateSalt(), but it returns the result as a Base64 string. This makes it easier to store in formats like JSON or HTML attributes.

Encoding Utilities

arrayBufferToBase64(arr: ArrayBuffer): string {
  return btoa(String.fromCharCode(...new Uint8Array(arr)));
}

base64ToArrayBuffer(base64: string): ArrayBuffer {
  return Uint8Array.from(atob(base64), c => c.charCodeAt(0));
}

These two utility functions help us store and transmit binary data (like ciphertext and IVs) by converting it to/from a Base64-encoded string.

Summary

We’ve created the core of a secure browser-based note manager:

Derived AES encryption keys from user passwords
Encrypted and decrypted notes using AES-GCM
Used random salts and IVs to enhance security
Encoded binary data safely for storage

These low-level functions form the cryptographic backbone of our app.

In Part 2, we’ll put this crypto toolkit into action.

DEV Community: Sergey Chin

Secure Note Manager in React - Part 2. Client-Side Login with Web Crypto and Redux

Introduction

In-Memory Secret Key Store

Why triggerUpdate is Needed

Security Considerations

Securing Access to Vault Page

Login Page

Summary of The Code Above

Summary

Custom exception handling in Spring Boot

Introduction

Implementation

Conclusion

Spring WebFlux + DynamoDB + S3

Introduction

Setting up AWS services

Setting up IAM

Setting up DynamoDB

Setting up S3

Creating a Spring WebFlux Application

Deploy to EC2

Conclusion

Secure Note Manager in React – Part 1: Cryptography with Web Crypto API

Introduction

Project Setup

Routing with React Router

Redux Store Setup

Implementing Cryptography

Key Derivation with PBKDF2

Encryption & Decryption with AES-GCM

Other Cryptographic Helpers

SHA-512 Hashing

Export Keys

Salt Generation

Encoding Utilities

Summary

Why `triggerUpdate` is Needed