Introduction to the redacted-compiler-plugin
redacted-compiler-plugin is a versatile multiplatform compiler plugin for Kotlin that specializes in generating redacted toString() implementations. Its functionality is inspired by the auto-value-redacted extension for AutoValue, streamlining the secure representation of data objects by redacting sensitive information.
Usage
To use the plugin, developers need to incorporate the Gradle plugin into their projects. They will define a @Redacted annotation and apply it to any properties they desire to hide. For example:
@Retention(SOURCE)
@Target(PROPERTY)
annotation class Redacted
data class User(val name: String, @Redacted val phoneNumber: String)
In this example, when the toString() method is invoked, the output will obscure the phoneNumber property:
User(name=Bob, phoneNumber=██)
If the @Redacted annotation is applied at the class level, the whole class will produce a single masked output:
@Retention(SOURCE)
@Target(CLASS)
annotation class Redacted
@Redacted
data class SensitiveData(val ssn: String, val birthday: String)
SensitiveData(██)
Installation
Installation involves applying the plugin through Gradle:
plugins {
id("dev.zacsweers.redacted") version <version>
}
The default setup introduces a multiplatform -annotations artifact that includes a ready-to-use @Redacted annotation, making it easy to start redacting data immediately. Developers can also tweak the plugin through the redacted extension:
redacted {
redactedAnnotation = "dev/zacsweers/redacted/annotations/Redacted" // Default
unredactedAnnotation = "dev/zacsweers/redacted/annotations/Unredacted" // Default
enabled = true // Default
replacementString = "██" // Default
}
Supported Platforms
The redacted-compiler-plugin supports all multiplatform project types, with the annotations artifact available for common JVM, JS, and native targets.
Caveats
Developers should note a couple of caveats:
- Kotlin compiler plugins are not stable APIs, and while the compiled outputs are stable, using them with newer versions of Kotlin might present stability issues.
- Currently, there is no IDE support for the plugin (see issue #8 on GitHub).
Advanced Usage
For scenarios where redacting every field is preferable with selective opt-outs, the plugin offers advanced capabilities:
Class Redaction: Ideal for classes with many fields requiring redaction:
@Redacted
data class User(@Unredacted val name: String, val phoneNumber: String, val ssn: String)
User(name=Bob, phoneNumber=██, ssn=██)
Supertype Redaction: Useful for enforcing redacted inputs in APIs by applying @Redacted to a parent interface:
@Redacted
interface RedactedObject
data class User(@Unredacted val name: String, val phoneNumber: String, val ssn: String) : RedactedObject
User(name=Bob, phoneNumber=██, ssn=██)
This plugin effectively enhances data security in software applications by redacting sensitive information, offering a robust solution for Kotlin developers. Its flexible configuration options and multiplatform support make it a valuable tool for improving data privacy across different environments.