#1830 https://github.com/mosip/commons/issues/1830 Move release-1.3.x changes to develop

AGENTS.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+```bash
+# Build all modules (skip GPG signing for local dev)
+mvn clean install -Dgpg.skip=true
+
+# Build a single module
+mvn clean install -Dgpg.skip=true -pl biometrics-util
+mvn clean install -Dgpg.skip=true -pl kernel-biometrics-api
+mvn clean install -Dgpg.skip=true -pl kernel-cbeffutil-api
+mvn clean install -Dgpg.skip=true -pl kernel-biosdk-provider
+
+# Run all tests
+mvn test
+
+# Run tests for a single module
+mvn test -pl biometrics-util
+
+# Run a specific test class
+mvn test -pl biometrics-util -Dtest=FingerDecoderTest
+
+# Run with Sonar analysis
+mvn verify sonar:sonar -Psonar
+
+# Skip tests during build
+mvn clean install -Dgpg.skip=true -DskipTests
+```
+
+Java 21 is required. All modules compile with `--enable-preview` enabled. The surefire plugin passes several `--add-opens` JVM flags for tests; these are already configured in each module's pom.xml.
+
+## Architecture Overview
+
+This is a Maven multi-module project (`groupId: io.mosip.biometrics`, version `1.4.0-SNAPSHOT`) providing biometric utility libraries for the [MOSIP](https://mosip.io) ecosystem. All modules are pure library JARs published to Maven Central (Sonatype OSS).
+
+### Module Dependency Chain
+
+```
+kernel-biometrics-api         ← defines all SPIs, entities, constants, models
+       ↑
+kernel-cbeffutil-api          ← implements CbeffUtil SPI; depends on kernel-biometrics-api
+kernel-biosdk-provider        ← implements iBioProviderApi; depends on kernel-biometrics-api
+biometrics-util               ← standalone ISO↔image converters; no dependency on other modules here
+test/                         ← sample CLI apps showing library usage (not a deployed artifact)
+```
+
+### kernel-biometrics-api
+
+Defines the contracts everything else depends on:
+
+- **`IBioApi`** (`spi/`) — core SPI: `init`, `checkQuality`, `match`, `extractTemplate`, `segment`, `convertFormat` (deprecated since 1.2.1)
+- **`IBioApiV2`** extends `IBioApi` — adds `convertFormatV2` (use this instead of deprecated `convertFormat`)
+- **`CbeffUtil`** (`spi/`) — SPI for CBEFF XML operations: `createXML`, `updateXML`, `validateXML`, `getBIRDataFromXML`, `getAllBDBData`, etc.
+- **`BIR`** / **`BiometricRecord`** (`entities/`) — core data model; `BIR` = Biometric Information Record, `BiometricRecord` wraps a list of BIRs
+- **`BiometricType`** (`constant/`) — `FINGER`, `IRIS`, `FACE`
+- **`BiometricFunction`** (`constant/`) — enum of functions the SDK can perform
+- **`Response<T>`** (`model/`) — generic wrapper returned by all `IBioApi` methods; contains status code and typed payload
+- **`CbeffValidator`** (`commons/`) — static utility for XML schema validation and BIR extraction
+
+### kernel-cbeffutil-api
+
+Single implementation of the CBEFF standard:
+
+- **`CbeffImpl`** — Spring `@Component` implementing `CbeffUtil`; loads its XSD schema at startup from a config server URL (`mosip.kernel.xsdstorage-uri` + `mosip.kernel.xsdfile`)
+- **`CbeffContainerImpl`** — handles XML serialization/deserialization of BIR lists; wraps the JAXB-based container
+- **`CbeffContainerI`** — interface for the container
+
+### kernel-biosdk-provider
+
+Bridges MOSIP kernel to external biometric SDKs via reflection. Does not call SDK directly — it uses reflection to invoke SDK methods by configured class names.
+
+- **`iBioProviderApi`** (`spi/`) — internal SPI; each `BioProviderImpl_V_X_X` implements this per SDK protocol version
+- **`BioProviderImpl_V_0_7`**, **`_V_0_8`**, **`_V_0_9`** — three concrete implementations; each handles a different SDK API version. The V_0_9 variant is the most current
+- **`BioAPIFactory`** — Spring `@Component` with `@ConfigurationProperties(prefix = "mosip.biometric.sdk.providers")`; reads per-vendor per-modality config at startup, initializes providers, and builds a registry `Map<BiometricType, Map<BiometricFunction, iBioProviderApi>>`
+- Configuration keys follow the pattern: `mosip.biometric.sdk.providers.finger.<vendorId>.*`, `.iris.<vendorId>.*`, `.face.<vendorId>.*`
+- Uses H2 in-memory database and Spring Boot JPA (declared as dependencies but used by the SDK provider framework, not this library itself)
+
+### biometrics-util
+
+Standalone utility for ISO biometric format ↔ image conversion. No Spring dependency; purely functional static methods.
+
+- **ISO standards supported**: ISO 19794-4:2011 (Finger), ISO 19794-6:2011 (Iris), ISO 19794-5:2011 (Face)
+- **Decoders**: `FingerDecoder`, `IrisDecoder`, `FaceDecoder` — convert ISO binary (`byte[]`) → JPEG/PNG `byte[]` or `BufferedImage`
+- **Encoders**: `FingerEncoder`, `IrisEncoder`, `FaceEncoder` — convert image → ISO binary
+- **`CommonUtil`** — converts a Base64URL-encoded ISO biometric from one image type (JP2000, WSQ) to another (JPEG, PNG)
+- **`ConvertRequestDto`** — DTO used as input to all decoders/encoders; holds `version`, `inputBytes`, `compressionRatio` (default 95 for JPEG quality)
+- **`ISOStandardsValidator`** — validates ISO header fields across all modalities
+- **NIST parser** (`nist/parser/v2011/`) — parses NIST ITL 1-2011 XML biometric files into a rich DTO hierarchy; used by the `test/` sample apps
+- JPEG2000 support via `jai-imageio-jpeg2000`; WSQ support via `jnbis`; OpenCV via `openpnp.opencv`
+
+### test/ module
+
+Not a deployed artifact — contains standalone CLI sample applications demonstrating library usage: `BioUtilApplication` (decode/encode ISO↔image), `BioUtilConvertApplication` (convert image type within ISO), `SampleNistFileReader`, `NistDataQualityAnalyser`.
+
+## Key Design Patterns
+
+**SPI + reflection for SDK integration**: `kernel-biosdk-provider` never has a compile-time dependency on the actual biometric SDK JAR. SDK class names are passed as config properties; the provider uses reflection to call `init`, `verify`, `identify`, `extractTemplate` etc. This allows swapping SDKs without recompiling.
+
+**CBEFF XML as the canonical biometric interchange format**: All biometric data exchanged between MOSIP components flows as CBEFF XML. The `BIR` entity maps directly to ISO/IEC 19785 CBEFF structures. The XSD for validation is loaded at runtime from a config server.
+
+**`convertFormat` is deprecated**: Prefer `IBioApiV2.convertFormatV2` (returns `Response<BiometricRecord>`) over the old `IBioApi.convertFormat` (returns `BiometricRecord` directly with no error wrapping). The old method is marked `@Deprecated(since = "1.2.1", forRemoval = true)`.
+
+## Sonar Coverage Exclusions
+
+`biometrics-util` excludes from coverage: `constant/`, `exception/`, `nist/parser/v2011/`, and various ISO data model classes (e.g., `FaceBDIR`, `IrisBDIR`, `FingerBDIR`, `FeaturePoint`, `LandmarkPointType`). These are excluded because they are generated/data-only classes with no logic to test.

THIRD-PARTY-NOTICES

@@ -4,7 +4,7 @@ This project includes third-party packages that are distributed under various op
 
 ================================================================================
 Package: MOSIP Bio Utils
-Version: 1.3.0-SNAPSHOT
+Version: 1.4.0-SNAPSHOT
 License: Mozilla Public License 2.0 (Inferred from project’s official repository)
 Homepage: https://github.com/mosip/bio-utils
 ================================================================================
@@ -152,7 +152,7 @@ Homepage: https://www.h2database.com
 ================================================================================
 Package: imgscalr-lib
 License: Apache License 2.0
-Homepage: https://github.com/rkalla/imgscalr
+Homepage: https://github.com/thebuzzmedia/imgscalr
 ================================================================================
 
 ================================================================================

THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,164 @@
+THIRD-PARTY-NOTICES
+
+This project includes third-party packages that are distributed under various open-source licenses. Below is a list of packages and their associated licenses.
+
+================================================================================
+Package: MOSIP Bio Utils
+Version: 1.4.0-SNAPSHOT
+License: Mozilla Public License 2.0 (Inferred from project’s official repository)
+Homepage: https://github.com/mosip/bio-utils
+================================================================================
+
+================================================================================
+Package: Apache Maven Plugins
+(maven-compiler-plugin, maven-gpg-plugin, maven-javadoc-plugin, maven-source-plugin, maven-jar-plugin, maven-resources-plugin, maven-shade-plugin, maven-surefire-plugin, maven-war-plugin, maven-antrun-plugin, maven-dependency-plugin)
+Version:
+  - maven-compiler-plugin: 3.11.0
+  - maven-gpg-plugin: 3.2.3
+  - maven-javadoc-plugin: 3.2.0
+  - maven-source-plugin: 3.3.1
+  - maven-jar-plugin: 3.4.0
+  - maven-resources-plugin: 3.3.1
+  - maven-shade-plugin: 3.2.4
+  - maven-surefire-plugin: 3.1.2
+  - maven-war-plugin: 3.1.0
+  - maven-antrun-plugin: 3.0.0
+  - maven-dependency-plugin: 2.10
+License: Apache License 2.0
+Homepage: https://maven.apache.org/plugins/
+================================================================================
+
+================================================================================
+Package: Sonar Maven Plugin (org.sonarsource.scanner.maven:sonar-maven-plugin)
+Version: 3.7.0.1746
+License: LGPL 3.0
+Homepage: https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-maven/
+================================================================================
+
+================================================================================
+Package: Apache Commons Lang (org.apache.commons:commons-lang3)
+Version: (Not specified)
+License: Apache License 2.0 (Inferred from project’s official repository)
+Homepage: https://commons.apache.org/proper/commons-lang/
+================================================================================
+
+================================================================================
+Package: Jackson Libraries (com.fasterxml.jackson.core, com.fasterxml.jackson.dataformat, com.fasterxml.jackson.module)
+Version: (Not specified)
+License: Apache License 2.0
+Homepage: https://github.com/FasterXML/jackson
+================================================================================
+
+================================================================================
+Package: Google Protobuf (com.google.protobuf:protobuf-java)
+Version: 3.13.0, 3.16.3
+License: BSD-3-Clause (Inferred from project’s official repository)
+Homepage: https://github.com/protocolbuffers/protobuf
+================================================================================
+
+================================================================================
+Package: OpenCV (org.openpnp:opencv)
+Version: 4.5.3-4
+License: Apache License 2.0
+Homepage: https://opencv.org/
+================================================================================
+
+================================================================================
+Package: Lombok (org.projectlombok:lombok)
+Version: (Not specified)
+License: MIT License (Inferred from project’s official repository)
+Homepage: https://projectlombok.org/
+================================================================================
+
+================================================================================
+Package: Hibernate Validator (org.hibernate.validator:hibernate-validator)
+Version: (Not specified)
+License: Apache License 2.0 (Inferred from project’s official repository)
+Homepage: http://hibernate.org/validator/
+================================================================================
+
+================================================================================
+Package: JUnit (junit:junit, org.junit.vintage:junit-vintage-engine, org.junit.jupiter:junit-jupiter)
+Version: Various
+License: Eclipse Public License 1.0/2.0 (Inferred from project’s official repository)
+Homepage: https://junit.org/
+================================================================================
+
+================================================================================
+Package: Mockito (org.mockito:mockito-core, org.mockito:mockito-inline)
+Version: 3.3.3, 5.8.0
+License: MIT License (Inferred from project’s official repository)
+Homepage: https://site.mockito.org/
+================================================================================
+
+================================================================================
+Package: Powermock (org.powermock:powermock-api-mockito2, org.powermock:powermock-module-junit4)
+Version: (Not specified)
+License: Apache License 2.0 (Inferred from project’s official repository)
+Homepage: https://github.com/powermock/powermock
+================================================================================
+
+================================================================================
+Package: Bouncy Castle (org.bouncycastle:bcutil-jdk18on)
+Version: 1.78.1
+License: MIT License (Inferred from project’s official repository)
+Homepage: https://www.bouncycastle.org/
+================================================================================
+
+================================================================================
+Package: Apache POI (org.apache.poi:poi-ooxml)
+Version: 5.2.5
+License: Apache License 2.0
+Homepage: https://poi.apache.org/
+================================================================================
+
+================================================================================
+Package: Google Gson (com.google.code.gson:gson)
+Version: 2.10.1
+License: Apache License 2.0
+Homepage: https://github.com/google/gson
+================================================================================
+
+================================================================================
+Package: Spring Boot
+License: Apache License 2.0
+Homepage: https://spring.io/projects/spring-boot
+================================================================================
+
+================================================================================
+Package: SLF4J (slf4j-api, log4j12)
+License: MIT License
+Homepage: https://www.slf4j.org/
+================================================================================
+
+================================================================================
+Package: JAI ImageIO JPEG2000
+License: Dual License (JJ2000 License AND BSD 3-Clause with Nuclear Disclaimer)
+Homepage: https://github.com/jai-imageio/jai-imageio-core
+================================================================================
+
+================================================================================
+Package: JNBIS
+License: Apache License 2.0
+Homepage: https://github.com/mhshams/jnbis
+================================================================================
+
+================================================================================
+Package: H2 Database
+License: EPL-1.0 OR MPL-2.0
+Homepage: https://www.h2database.com
+================================================================================
+
+================================================================================
+Package: imgscalr-lib
+License: Apache License 2.0
+Homepage: https://github.com/thebuzzmedia/imgscalr
+================================================================================
+
+================================================================================
+Package: OkHttp (mockwebserver)
+License: Apache License 2.0
+Homepage: https://square.github.io/okhttp/
+================================================================================
+
+Full license texts and additional details for each of the above packages are available in the license/ directory of this repository. Please refer to those files or the original source of each package for complete legal terms and conditions.