Getting Started

This guide adds Ihawu to a Spring Boot application and masks a field end to end.

Add the starter. It pulls ihawu-core transitively, so it’s the only dependency you add.
- Gradle (Kotlin)
- Maven
implementation("org.ihawu:ihawu-spring-boot-starter:0.4.1")
<dependency> <groupId>org.ihawu</groupId> <artifactId>ihawu-spring-boot-starter</artifactId> <version>0.4.1</version> </dependency>
Annotate your response type and mark the sensitive fields’ resource. Declare every maskable field nullable — a masked field is either omitted (HIDE) or set to null (REDACT on a non-String), so the type has to allow that.
```
import org.ihawu.core.annotation.IhawuResource

@IhawuResource("employee")
data class EmployeeResponse(
    val id: String,
    val fullName: String,
    val email: String,
    val salary: Double?,
    val socialSecurityNumber: String?,
)
```
Masking has to respect your type contract
A masked response still has to deserialize into the type it claims to be, so the strategy you pick is constrained by how the field is declared:
- HIDE drops the field entirely. Apply it only to a nullable field — that is why salary and socialSecurityNumber are declared Double? and String? above. Hiding a non-nullable field emits JSON that its own type cannot parse.
- REDACT writes a placeholder on a String, and JSON null on any other nullable field — so a numeric or boolean field is redactable only when it is nullable, never a fake 0 or false.
The short version: declare every maskable field nullable (a String you only ever REDACT may stay non-null). On Spring Boot these rules are checked at startup — a policy that cannot be honoured fails the application context, naming the field (see the Spring Boot starter).

Define a policy. Supply the per-role rules either as a ResourcePolicyProvider bean or straight from ihawu.policies configuration — the two are equivalent.

Programmatic provider
Config properties

import org.ihawu.core.masking.MaskingStrategy
import org.ihawu.core.policy.FieldPolicy
import org.ihawu.core.policy.ResourcePolicy
import org.ihawu.spring.boot.starter.configuration.ResourcePolicyProvider
import org.springframework.context.annotation.Bean

@Bean
fun resourcePolicyProvider() =
    ResourcePolicyProvider {
        listOf(
            ResourcePolicy(
                resourceName = "employee",
                roleFieldPolicies = mapOf(
                    "MANAGER" to listOf(
                        FieldPolicy("socialSecurityNumber", MaskingStrategy.REDACT, "***-**-****"),
                    ),
                    "EMPLOYEE" to listOf(
                        FieldPolicy("salary", MaskingStrategy.HIDE),
                        FieldPolicy("socialSecurityNumber", MaskingStrategy.HIDE),
                    ),
                ),
            ),
        )
    }

# application.yml — same rules, no code
ihawu:
  policies:
    - resource: employee
      roles:
        MANAGER:
          - field: socialSecurityNumber
            strategy: REDACT
            placeholder: "***-**-****"
        EMPLOYEE:
          - field: salary
            strategy: HIDE
          - field: socialSecurityNumber
            strategy: HIDE

Call the endpoint. The same handler now returns different fields per role — a MANAGER sees a redacted SSN; an EMPLOYEE sees neither salary nor SSN; an unconfigured role sees the full record (masking is a denylist).

A runnable example

The repository ships a complete, runnable sample under samples/spring-boot-sample — a secured endpoint, three roles, and an integration test that pins each role’s masked JSON. It’s the fastest way to see Ihawu working against a live HTTP endpoint.

Next steps

Understand the model in How Ihawu Works.
Browse the full API in the Dokka reference.