initial commit

Author: merge-simpson

.gitignore

@@ -0,0 +1,36 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/

README.md

@@ -0,0 +1,162 @@
+# About API Module
+
+## Bundled
+
+- letsdev-password-encoder-api  
+  `com.github.merge-simpson:letsdev-password-encoder-api:${version}`
+  - letsdev-password-encoder-port  
+    `com.github.merge-simpson:letsdev-password-encoder-port:${version}`
+  - letsdev-password-encoder-exception  
+    `com.github.merge-simpson:letsdev-password-encoder-exception:${version}`
+
+## Installation
+
+`build.gradle.kts`에서 다음과 같이 추가합니다. (또는 번들된 의존성을 각각 추가할 수 있습니다.)
+
+```kotlin
+repositories {
+    mavenCentral()
+    maven { url = uri("https://jitpack.io") } // added
+}
+
+dependencies {
+    implementation("com.github.merge-simpson:letsdev-password-encoder-factory:0.1.0") // added
+}
+```
+
+# Features
+
+이 모듈은 Spring Crypto 라이브러리에 의존성을 갖고 있습니다. (`org.springframework.security:spring-security-crypto`)
+
+- [Password Encoder Factory](#password-encoder-factory)
+- [Cache Password Encoder Instances And Expire Them Automatically.](#패스워드-인코더-객체-캐싱)
+
+# Password Encoder Factory
+
+제공하는 패스워드 인코더 목록은 다음과 같습니다.
+
+- bcrypt
+- argon2
+    - argon2id
+    - argon2d
+
+## 패스워드 인코더 인스턴스 생성하기
+
+팩토리는 다음처럼 두 방식으로 패스워드 인코더를 생성합니다.
+
+```java
+// 일반 패스워드 인코더 (내부에서 솔트를 자동으로 생성합니다.)
+var encoder = factory.create(option);
+
+// 커스텀 솔트를 사용하는 패스워드 인코더
+//  직접 만든 솔트를 넣을 수 있으며, 내부에서 추가적인 랜덤 솔트를 만들지 않습니다.
+var customSaltingEncoder = factory.createCustomSaltingEncoder(option);
+```
+
+- option: <<interface>> PasswordEncoderOption
+- option 인스턴스는 `PasswordEncoderType` 객체를 반환하는 `encoderType()` 메서드를 갖습니다.
+
+Examples
+
+- [Create bcrypt password encoder](#bcrypt)
+- [Create argon2id password encoder](#argon2id)
+- [Create argon2d password encoder](#argon2d)
+
+### BCrypt
+
+```java
+var factory = new PasswordEncoderFactory();
+var option = new BcryptPasswordEncoderOption(12);
+
+var bcryptPasswordEncoder = factory.create(option);
+```
+
+### Argon2id
+
+```java
+var factory = new PasswordEncoderFactory();
+var option = Argon2idPasswordEncoderOption.fromDefaultBuilder()
+        .gain(3f) // optional
+        .build();
+
+var bcryptPasswordEncoder = factory.create(option);
+```
+
+**Argon2id의 옵션들**
+
+- memoryInput: 입력한 메모리 비용
+- memory: 계산된 메모리 비용 (빌더는 이것 대신 위 파라미터를 입력하게 함.)
+    - memoryInput이 없을 때 m ≥ 93750 ÷ ((3 × t − 1) × α)  (단위: kB)
+- saltLength: 솔트 길이. 기본 값: 16 Byte
+- hashLength: 해시 길이. 기본 값: 32 Byte
+- parallelism: 병렬성. 기본값: 1
+- iterations: 반복성. t ≥ 1
+- alpha: m ≲ 64 MiB일 때 α ≈ 95% 범위를 추천. m이 충분히 크면 α를 감소시켜도 됨.
+- gain: 메모리 비용 계수(증폭비)
+
+### Argon2d
+
+```java
+var factory = new PasswordEncoderFactory();
+var option = Argon2dPasswordEncoderOption.fromDefaultBuilder()
+        .gain(3f)
+        .build();
+
+var bcryptPasswordEncoder = factory.create(option);
+```
+
+**Argon2d의 옵션은 Argon2id와 같은 항목을 같습니다.**
+
+## 패스워드 인코더 객체 캐싱
+
+패스워드 인코더 인스턴스를 캐싱합니다. ([Caffeine Cache](https://github.com/ben-manes/caffeine) 기반 팩토리)
+
+**기본 생성자를 사용한 캐시 만료 기본값**
+
+```java
+var factory = new PasswordEncoderFactory();
+```
+
+- 마지막 접근으로부터 최대 10분 동안 살아 있습니다.
+- 최대 100개를 보존합니다.
+
+**Builder 사용으로 캐시의 만료 설정을 커스텀하기**
+
+```java
+var factory = PasswordEncoderFactory.builder()
+        .expireAfterAccess(3, TimeUnit.MINUTES)
+        .maximumSize(3)
+        .removalListener((key, value, cause) ->
+                log.info("Cache entry for key {} was removed because of: {}", key, cause)
+        )
+        .build();
+```
+
+- expireAfterAccess(duration), expireAfterAccess(duration, TimeUnit)
+    - 마지막 조회로부터 해당 시간 후 만료됩니다.
+- expireAfterWrite(duration), expireAfterWrite(duration, TimeUnit)
+    - 생성으로부터 해당 시간 후 만료됩니다.
+- maximumSize: 최대 저장 개수
+- maximumWeight: 최대 저장 용량
+- removalListener((k, v, cause) -> {}): 요소 삭제 이벤트 리스너를 추가할 수 있습니다.
+
+### 메서드 간 공유되는 캐시
+
+지금 데모 버전에서 사용하는 패스워드 인코더 인스턴스는 모두
+`PasswordEncoder` 인터페이스와 `CustomSaltingPasswordEncoder`를 동시에 구현합니다.
+
+```java
+var factory = new PasswordEncoderFactory();
+var argon2IdOption = Argon2idPasswordEncoderOption.fromDefaultBuilder()
+        .gain(3f)
+        .build();
+
+// 같은 옵션을 사용하여 생성하면, 다음 두 메서드는 같은 인스턴스를 캐싱하여 반환합니다.
+var passwordEncoder = factory.create(argon2IdOption);
+var customSaltingPasswordEncoder = factory.createCustomSaltingEncoder(argon2IdOption);
+```
+
+```kotlin
+// 다음 결과를 기대할 수 있습니다.
+assertSame(passwordEncoder, customSaltingPasswordEncoder)
+```

build.gradle.kts

@@ -0,0 +1,100 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+    java
+    id("java-library")
+    id("org.springframework.boot") version "3.3.4"
+    id("io.spring.dependency-management") version "1.1.6"
+    kotlin("jvm") version "1.9.22"
+    kotlin("plugin.spring") version "1.9.22"
+    id("maven-publish")
+}
+
+group = "me.letsdev"
+version = "0.1.0"
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    mavenCentral()
+    maven { url = uri("https://jitpack.io") }
+}
+
+dependencies {
+    // instance cache
+    api("com.github.ben-manes.caffeine:caffeine:3.1.8")
+
+    // spring dependencies
+    api("org.springframework:spring-web")
+    api("org.springframework.boot:spring-boot-starter")
+    api("jakarta.annotation:jakarta.annotation-api")
+
+    // error code
+    api("com.github.merge-simpson:letsdev-password-encoder-api:0.1.0")
+
+    // spring crypto (password encoder delegator)
+    api("org.springframework.security:spring-security-crypto")
+    api("org.bouncycastle:bcprov-jdk18on:1.78.1")
+
+    // test
+    testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation(kotlin("test"))
+    testImplementation("io.kotest:kotest-runner-junit5:5.9.1")
+    testImplementation("org.jetbrains.kotlin:kotlin-reflect")
+    testImplementation("io.mockk:mockk:1.13.12")
+}
+
+tasks.withType<Test> {
+    useJUnitPlatform()
+}
+
+tasks.withType<KotlinCompile> {
+    kotlinOptions {
+        jvmTarget = "21"
+    }
+}
+
+tasks.named<BootJar>("bootJar") {
+    enabled = false
+}
+
+tasks.named<Jar>("jar") {
+    enabled = true
+    archiveClassifier.set("") // remove suffix "-plain"
+}
+
+sourceSets {
+    test {
+        java {
+            setSrcDirs(listOf("src/test/kotlin"))
+        }
+    }
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("mavenJava") {
+            from(components["java"])
+            groupId = "com.github.merge-simpson"
+            artifactId = project.name
+            version = project.version.toString()
+        }
+    }
+    repositories {
+        maven {
+            name = "localMaven"
+            url = uri("${rootProject.projectDir}/build/repos")
+        }
+    }
+}
+
+tasks.named("publishToMavenLocal").configure {
+    dependsOn("assemble")
+}

gradle/wrapper/gradle-wrapper.jar

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists