Issue 1633

.github/workflows/push-trigger.yml

@@ -21,6 +21,7 @@ on:
       - 1.*
       - develop*
       - MOSIP*
+      - issue*
 
 jobs:
   build-bio-utils:

AGENTS.md

@@ -1,108 +1,31 @@
-# CLAUDE.md
+# bio-utils
 
-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
+JDK21 · Maven3.9+ · Boot 4.1.1 · parent biometrics · NO kernel-bom
+└─ mvn clean install "-Dgpg.skip=true"
+```
 
 ```
-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)
+prereq
+└─ ../commons/kernel → kernel-core 1.4.1-SNAPSHOT
+   └─ pin kernel.core.version (never parent kernel-parent alone)
 ```
 
-### 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
+```
+reactor
+├─ kernel-biometrics-api     # SPI IBioApi/V2, BIR, CbeffUtil
+│  ├─ kernel-cbeffutil-api   # CbeffImpl + XSD config
+│  └─ kernel-biosdk-provider # reflect vendor SDK V0.7–0.9
+├─ biometrics-util           # ISO19794 ↔ image (standalone)
+└─ test/                     # sample CLI — NOT in reactor
+```
 
-`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.
+```
+rules
+├─ siblings omit <version>
+├─ libs: no Boot repackage
+├─ CBEFF: javax.xml.bind 2.3.x (not Jakarta 4)
+├─ Jackson2 via spring-boot-jackson2 (not Jackson3 default)
+├─ ban: kernel-bom · kernel-logger-logback (use kernel-core)
+└─ jacoco ≥85%
+```

NOTICE

@@ -0,0 +1,105 @@
+NOTICES
+
+Copyright (c) MOSIP.
+All rights reserved.
+
+This project is MPL 2.0 (see LICENSE). Third-party versions match pom.xml and
+Spring Boot 4.1.1. Full texts and MOSIP dual-license elections: licenses/.
+
+MOSIP open-source license matrix (compatible with MPL 2.0 / Use with MOSIP):
+
+  License                          Compatible?   Use with MOSIP?   Comments
+  -------------------------------  ------------  ----------------  --------
+  BSD (2-Clause, 3-Clause)         Yes           Yes               Combine freely
+  MIT                              Yes           Yes               Combine freely
+  Apache-2.0                       Yes           Yes               Meet attribution
+  MPL-2.0                          Yes           Yes               Combine freely
+  EPL                              No            No                Incompatible with MPL
+  LGPLv3                           Yes           No                May apply to combined work
+  GPLv2                            No            No                No explicit MPL compatibility
+  GPLv3                            Yes           No                Combined work must be GPLv3
+  AGPLv3                           Yes           No                Combined work must be AGPLv3
+  Creative Commons (general)       No            No                Not for software
+  ISC                              Yes           Yes               Keep ISC + attribution
+  Python-2.0                       Yes           Yes               Comply with both licenses
+  AFL-2.0                          No            No                Conflicts with MPL
+  AFL-2.1                          Yes           Yes               Keep AFL notice + attribution
+  ODC-By-1.0                       No            No                Database license
+  CDDL-1.0                         Yes           Yes               Files keep original license
+  Unicode-DFS-2016                 Yes           Yes               Keep Unicode license + notice
+  BlueOak-1.0.0                    Yes           Yes               Keep license text/link
+  OFL-1.1                          Yes           Yes               Fonts; keep full OFL text
+  CC-BY-4.0                        —             —                 To be reviewed
+  Zlib                             Yes           Yes               Keep zlib license text
+  0BSD                             Yes           Yes               Permissive
+
+CDDL-1.1 treated as CDDL-1.0 successor. Unicode-3.0 treated as Unicode-DFS-2016
+successor. Dual-licensed jars: MOSIP elects an allowed option (never EPL, GPL,
+AGPL, LGPLv3, or Creative Commons as the product license).
+
+===========================
+MIT License (licenses/MIT.txt)
+===========
+
+- org.projectlombok:lombok (Boot-managed)
+- org.slf4j:slf4j-api (Boot-managed)
+- org.mockito:mockito-core (Boot-managed; test)
+
+===========================
+Apache-2.0 (licenses/Apache-2.0.txt)
+===========================
+
+- Spring Boot 4.1.1 / Spring Framework (Boot parent)
+- com.fasterxml.jackson.* (Jackson 2 via spring-boot-jackson2)
+- com.google.code.gson:gson 2.14.0
+- com.github.mhshams:jnbis 2.1.2
+- org.imgscalr:imgscalr-lib 4.2
+- com.squareup.okhttp:okhttp 2.7.5 (sample CLI only)
+- org.apache.commons:commons-lang3 (Boot-managed)
+- org.hibernate.validator:hibernate-validator (Boot-managed)
+- Maven build plugins (compiler, surefire, jar, source, javadoc, gpg, deploy)
+
+===========================
+BSD-3-Clause (licenses/BSD-3-Clause.txt)
+===========================
+
+- com.google.protobuf:protobuf-java 4.36.2
+- org.openpnp:opencv 4.9.0-0
+
+===========================
+BSD-3-Clause-No-Nuclear (licenses/BSD-3-Clause-No-Nuclear-License.txt)
+===========================
+
+- com.github.jai-imageio:jai-imageio-jpeg2000 1.4.0
+
+===========================
+EDL 1.0 / BSD (licenses/BSD-2-Clause.txt)
+===========================
+
+- javax.xml.bind:jaxb-api 2.3.1
+- org.glassfish.jaxb:jaxb-runtime 2.3.9
+
+===========================
+Mozilla Public License 2.0 (LICENSE)
+===========================
+
+- This repository (bio-utils modules)
+- io.mosip.kernel:kernel-core 1.4.1-SNAPSHOT (commons)
+- com.h2database:h2 (EPL-1.0 OR MPL-2.0; MOSIP elects MPL-2.0)
+
+===========================
+CDDL-1.1 (licenses/COMMON-DEVLOPMENT-AND-DISTRIBUTION-1.1.txt)
+===========
+
+- javax.activation (transitive via JAXB; CDDL-1.1 OR GPL-2.0-with-CPE;
+  MOSIP elects CDDL-1.1)
+
+===========================
+MOSIP matrix: Use = No (still on classpath — exception or replace)
+===========================
+
+- org.junit.jupiter / junit-vintage / junit:junit (EPL; test only)
+- ch.qos.logback (EPL-2.0 OR LGPL-2.1; Boot default logger)
+- org.aspectj:aspectjweaver (EPL-2.0; Boot AOP transitive)
+
+See licenses/NOTICE for the full election detail.