feat: Implement JSF (JSON Signature Format) signature support by wiebe-vandendriessche · Pull Request #994 · CycloneDX/cyclonedx-python-lib

wiebe-vandendriessche · 2026-06-09T12:47:39Z

Description

Implements comprehensive JSF (JSON Signature Format) signature support for CycloneDX Python library.

Summary of Changes:

Created JsfAlgorithm enum with 14 JWA/RFC8037 algorithms (RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ED25519, ED448, HS256, HS384, HS512)
Created JsfKeyType enum for key types (EC, OKP, RSA)
Implemented JsfPublicKey class with conditional RFC-compliant validation per key type
Designed abstract JsfSignature base class with three concrete implementations:
- JsfSimpleSignature: Simple signature mode (algorithm + value + optional fields)
- JsfSignatureSigners: Multisignature mode (array of simple signatures under signers)
- JsfSignatureChain: Chain mode (array of simple signatures under chain)
Implemented _JsfSignatureSerializationHelper for JSON serialization/deserialization (ignoring xml serialization/deserialization)
Added Optional[JsfSignature] property to Bom, Component, and Service model classes (compositions, annotation, declarations also support sigantures but are not yet implemented in the Python library)
Created unit tests covering all classes
Updated models.py for snapshots of boms with signatures

Difficulties encountered:

Type-safe design prevents invalid nesting at compile time (signers/chain lists only accept JsfSimpleSignature)
Three mutually exclusive signature modes properly modeled per JSF specification
JSON-only serialization (XML methods return None through a helper _JsfSignatureSerializationHelper)
Proper public key validation (EC: crv/x/y, OKP: crv/x, RSA: n/e)

Resolves or fixes issue:
#122
#978

AI Tool Disclosure

My contribution includes AI-generated content, as disclosed below:
- AI Tools: GitHub Copilot
- LLMs and versions: Claude: Haiku 4.5, Sonnet 4.6
- Prompts: Architecture design for type-safe JSF signature implementation; test case generation for all signature modes; import optimization and linting fixes

Affirmation

My code follows the CONTRIBUTING.md guidelines

Signed-off-by: Wiebe Vandendriessche <wiebe.vandendriessche@gmail.com>

read-the-docs-community · 2026-06-09T12:48:38Z

Documentation build overview

📚 CycloneDX Python Library | 🛠️ Build #34369814 | 📁 Comparing 49f2ef2 against latest (150777e)

🔍 Preview build

17 files changed · + 3 added · ± 14 modified

+ Added

± Modified

codacy-production · 2026-06-09T12:50:40Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 101 complexity · 5 duplication

Metric Results

Complexity 101

Duplication 5

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

Signed-off-by: Wiebe Vandendriessche <146532897+wiebe-vandendriessche@users.noreply.github.com>

Signed-off-by: Wiebe Vandendriessche <wiebe.vandendriessche@gmail.com>

Signed-off-by: Wiebe Vandendriessche <146532897+wiebe-vandendriessche@users.noreply.github.com>

wiebe-vandendriessche · 2026-09-03T08:28:56Z

@jkowalleck this should be ready

Copilot

🟡 Changes recommended

The new JSF signature models allow construction/deserialization of invalid JSF structures (ambiguous modes, invalid nesting, and post-init invalid mutation) and one unit test currently encodes an invalid algorithm assignment.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements JSF (JSON Signature Format) signature support in the CycloneDX Python models, enabling signatures to be represented and serialized in JSON for CycloneDX schema versions >= 1.4.

Changes:

Added cyclonedx.model.signature module with JSF enums, public key model, three signature modes, and a JSON-only serialization helper.
Extended Bom, Component, and Service models with an optional signature field (JSON-only; omitted in XML).
Added unit tests and updated/added snapshot fixtures to cover signatures and enum/schema alignment.

File summaries

File	Description
tests/test_model_signature.py	New unit tests for JSF signature/key models and polymorphic behavior.
tests/test_enums.py	Adds enum-vs-schema validation and JSON rendering cases exercising signatures.
tests/test_deserialize_xml.py	Adds XML deserialization-only test for BOMs containing JSON-only fields (signatures).
tests/_data/models.py	Adds a snapshot BOM generator including signatures and excludes it from XML roundtrip deep-compare tests.
cyclonedx/model/signature.py	Introduces JSF signature domain model + JSON-only (de)serialization helper.
cyclonedx/model/service.py	Adds `signature: Optional[JsfSignature]` to `Service` with JSON-only serialization mapping.
cyclonedx/model/component.py	Adds `signature: Optional[JsfSignature]` to `Component` with JSON-only serialization mapping.
cyclonedx/model/bom.py	Adds `signature: Optional[JsfSignature]` to `Bom` with JSON-only serialization mapping.
tests/_data/snapshots/get_bom_with_signatures-1.7.xml.bin	XML snapshot for BOM containing signatures (signatures dropped in XML).
tests/_data/snapshots/get_bom_with_signatures-1.7.json.bin	JSON snapshot for BOM containing signatures (signatures present).
tests/_data/snapshots/get_bom_with_signatures-1.6.xml.bin	XML snapshot for BOM containing signatures (signatures dropped in XML).
tests/_data/snapshots/get_bom_with_signatures-1.6.json.bin	JSON snapshot for BOM containing signatures (signatures present).
tests/_data/snapshots/get_bom_with_signatures-1.5.xml.bin	XML snapshot for BOM containing signatures (signatures dropped in XML).
tests/_data/snapshots/get_bom_with_signatures-1.5.json.bin	JSON snapshot for BOM containing signatures (signatures present).
tests/_data/snapshots/get_bom_with_signatures-1.4.xml.bin	XML snapshot for BOM containing signatures (signatures dropped in XML).
tests/_data/snapshots/get_bom_with_signatures-1.4.json.bin	JSON snapshot for BOM containing signatures (signatures present).
tests/_data/snapshots/get_bom_with_signatures-1.3.xml.bin	XML snapshot for older schema BOM (no signatures).
tests/_data/snapshots/get_bom_with_signatures-1.3.json.bin	JSON snapshot for older schema BOM (no signatures).
tests/_data/snapshots/get_bom_with_signatures-1.2.xml.bin	XML snapshot for older schema BOM (no signatures).
tests/_data/snapshots/get_bom_with_signatures-1.2.json.bin	JSON snapshot for older schema BOM (no signatures).
tests/_data/snapshots/get_bom_with_signatures-1.1.xml.bin	XML snapshot for schema 1.1 (no JSON signatures).
tests/_data/snapshots/get_bom_with_signatures-1.0.xml.bin	XML snapshot for schema 1.0 (no JSON signatures).
tests/_data/snapshots/enum_JsfOkpCurve-1.7.json.bin	JSON snapshot covering OKP curve enum rendering for schema 1.7.
tests/_data/snapshots/enum_JsfOkpCurve-1.6.json.bin	JSON snapshot covering OKP curve enum rendering for schema 1.6.
tests/_data/snapshots/enum_JsfOkpCurve-1.5.json.bin	JSON snapshot covering OKP curve enum rendering for schema 1.5.
tests/_data/snapshots/enum_JsfOkpCurve-1.4.json.bin	JSON snapshot covering OKP curve enum rendering for schema 1.4.
tests/_data/snapshots/enum_JsfKeyType-1.7.json.bin	JSON snapshot covering key type enum rendering for schema 1.7.
tests/_data/snapshots/enum_JsfKeyType-1.6.json.bin	JSON snapshot covering key type enum rendering for schema 1.6.
tests/_data/snapshots/enum_JsfKeyType-1.5.json.bin	JSON snapshot covering key type enum rendering for schema 1.5.
tests/_data/snapshots/enum_JsfKeyType-1.4.json.bin	JSON snapshot covering key type enum rendering for schema 1.4.
tests/_data/snapshots/enum_JsfEcCurve-1.7.json.bin	JSON snapshot covering EC curve enum rendering for schema 1.7.
tests/_data/snapshots/enum_JsfEcCurve-1.6.json.bin	JSON snapshot covering EC curve enum rendering for schema 1.6.
tests/_data/snapshots/enum_JsfEcCurve-1.5.json.bin	JSON snapshot covering EC curve enum rendering for schema 1.5.
tests/_data/snapshots/enum_JsfEcCurve-1.4.json.bin	JSON snapshot covering EC curve enum rendering for schema 1.4.
tests/_data/snapshots/enum_JsfAlgorithm-1.7.json.bin	JSON snapshot covering algorithm enum rendering for schema 1.7.
tests/_data/snapshots/enum_JsfAlgorithm-1.6.json.bin	JSON snapshot covering algorithm enum rendering for schema 1.6.
tests/_data/snapshots/enum_JsfAlgorithm-1.5.json.bin	JSON snapshot covering algorithm enum rendering for schema 1.5.
tests/_data/snapshots/enum_JsfAlgorithm-1.4.json.bin	JSON snapshot covering algorithm enum rendering for schema 1.4.

Review details

Files reviewed: 38/38 changed files
Comments generated: 5
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+    def __init__(
+        self, *,
+        algorithm: Union[JsfAlgorithm, str],
+        value: str,
+        key_id: Optional[str] = None,
+        public_key: Optional[JsfPublicKey] = None,
+        certificate_path: Optional[list[str]] = None,
+        excludes: Optional[list[str]] = None,
+    ) -> None:
+        if not isinstance(algorithm, JsfAlgorithm):
+            # Proprietary algorithms must be expressed as URIs per JSF spec
+            if not _urlsplit(str(algorithm)).scheme:
+                raise InvalidValueException(
+                    f'Proprietary JSF algorithm must be expressed as a URI, got {algorithm!r}'
+                )
+        self.algorithm = algorithm
+        self.value = value
+        self.key_id = key_id
+        self.public_key = public_key
+        self.certificate_path = list(certificate_path) if certificate_path else []
+        self.excludes = list(excludes) if excludes else []
+


+    def test_update(self) -> None:
+        sig = JsfSimpleSignature(algorithm=JsfAlgorithm.RS256, value='val')
+        self.assertIs(JsfAlgorithm.RS256, sig.algorithm)
+        sig.algorithm = JsfOkpCurve.ED25519
+        self.assertIs(JsfOkpCurve.ED25519, sig.algorithm)
+


wiebe-vandendriessche · 2026-09-07T08:02:29Z

Not an easy one to implement, I'll take a look at Copilots comments

jkowalleck · 2026-09-07T09:25:19Z

Not an easy one to implement, I'll take a look at Copilots comments

please take your time.
I did not even have time to manually review your valuable contribution, nor copilots review.
As usual - AI is non-authoritative and may make mistakes - since it scans your changes only, not the entirety of this repo - it does not know about previous design decisions and such ...

Even without looking into the details of the PR or AI review, I'd like to say:
It would be okay if the proposed data models would allow creation of invalid data due to not implementing some business logic.
We have a schema-based validator that should take care of formal invalids, and we would not implement a 3rd party (defacto?) standard, since the library users shall take care of this (garbage-in/garbage-out)

feat: Implement JSF (JSON Signature Format) signature support

4cac74e

Signed-off-by: Wiebe Vandendriessche <wiebe.vandendriessche@gmail.com>

wiebe-vandendriessche requested a review from a team as a code owner June 9, 2026 12:47

wiebe-vandendriessche and others added 2 commits June 12, 2026 10:45

Merge branch 'main' into feat/sig

33fbe8f

Signed-off-by: Wiebe Vandendriessche <146532897+wiebe-vandendriessche@users.noreply.github.com>

Merge branch 'main' into feat/sig

a108716

jkowalleck requested changes Jun 17, 2026

View reviewed changes

Comment thread tests/test_deserialize_xml.py Outdated

Comment thread cyclonedx/model/signature.py

wiebe-vandendriessche and others added 2 commits June 17, 2026 17:30

fix: refactor JsfKeyType and add enums and enum tests

e7d1cfd

Signed-off-by: Wiebe Vandendriessche <wiebe.vandendriessche@gmail.com>

Merge branch 'main' into feat/sig

42c0e7f

wiebe-vandendriessche requested a review from jkowalleck June 17, 2026 15:31

wiebe-vandendriessche marked this pull request as draft June 26, 2026 14:21

wiebe-vandendriessche and others added 2 commits July 13, 2026 15:44

Merge branch 'main' into feat/sig

7cc85fb

Refactor testing

9dc6c63

Signed-off-by: Wiebe Vandendriessche <wiebe.vandendriessche@gmail.com>

wiebe-vandendriessche force-pushed the feat/sig branch from 5c305ce to 9dc6c63 Compare September 3, 2026 08:25

Merge branch 'main' into feat/sig

49f2ef2

Signed-off-by: Wiebe Vandendriessche <146532897+wiebe-vandendriessche@users.noreply.github.com>

wiebe-vandendriessche marked this pull request as ready for review September 3, 2026 08:28

jkowalleck requested a lite review from Copilot September 7, 2026 07:46

Copilot started reviewing on behalf of jkowalleck September 7, 2026 07:47 View session

Copilot AI reviewed Sep 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

feat: Implement JSF (JSON Signature Format) signature support - #994

feat: Implement JSF (JSON Signature Format) signature support#994
wiebe-vandendriessche wants to merge 8 commits into
CycloneDX:mainfrom
wiebe-vandendriessche:feat/sig

wiebe-vandendriessche commented Jun 9, 2026 •

edited

Loading

Uh oh!

read-the-docs-community Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

codacy-production Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

wiebe-vandendriessche commented Sep 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wiebe-vandendriessche commented Sep 7, 2026

Uh oh!

jkowalleck commented Sep 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

wiebe-vandendriessche commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

AI Tool Disclosure

Affirmation

Uh oh!

read-the-docs-community Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

codacy-production Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

Uh oh!

Uh oh!

wiebe-vandendriessche commented Sep 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wiebe-vandendriessche commented Sep 7, 2026

Uh oh!

jkowalleck commented Sep 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wiebe-vandendriessche commented Jun 9, 2026 •

edited

Loading

read-the-docs-community Bot commented Jun 9, 2026 •

edited

Loading

codacy-production Bot commented Jun 9, 2026 •

edited

Loading