# sigstore/sigstore-java architecture

> Architecture diagram of the GitHub repository sigstore/sigstore-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigstore/sigstore-java
- Repository: https://github.com/sigstore/sigstore-java

## Overview

##### Project type and purpose
- This is a multi‐module open‐source Java client ecosystem (a “monorepo”) for the Sigstore project.
- At its heart is a core library (“sigstore-java”) offering keyless signing and verification, DSSE verification, JSON canonicalization, and a TUF client.
- Around it are: CLI tools (sigstore-cli, tuf-cli), build-tool plugins (Gradle and Maven), testkit for integration tests, example apps, and fuzzing targets.

##### File structure
- Top-level Gradle build logic under `build-logic-*`
- Sample applications under `examples/`
- Fuzzers under `fuzzing/`
- Core library under `sigstore-java/` (packages: cli, http, fulcio, rekor, oidc, tuf, dsse, encryption, json)
- CLI wrappers under `sigstore-cli/` and `tuf-cli/`
- Build-tool integrations under `sigstore-gradle/` and `sigstore-maven-plugin/`
- Test harness under `sigstore-testkit/`
- Sandbox experiments, scripts, CI configs, and metadata at root

##### README for additional insights
- Public API limited to `KeylessSigner` and `KeylessVerifier` (Java 11 minimum)
- Typical workflow: sign file → Fulcio CA (gRPC) → Rekor log (REST) → optional Timestamp (HTTP) → output a “bundle” → verify bundle against Fulcio roots, Rekor inclusion proofs, TUF metadata
- Published artifacts on Maven Central, Javadoc hosted online

##### Detail level
- Drill into the core library’s sub‐packages (fulcio, rekor, oidc, tuf, dsse, encryption, json).
- How the “bundle” payload travels from signer → Rekor → verifier.
- Build-logic and CI/packaging as separate lanes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Modules (Blue)
    subgraph "Consumer Modules"
        direction TB
        CLI["sigstore-cli"]:::consumer
        TCLI["tuf-cli"]:::consumer
        GradlePlugin["Gradle Plugin"]:::consumer
        MavenPlugin["Maven Plugin"]:::consumer
        Examples["Example Applications"]:::consumer
        Fuzzing["Fuzzing Targets"]:::consumer
    end

    %% Core Library (Green)
    subgraph "Core Library" 
        direction TB
        API["KeylessSigner / KeylessVerifier"]:::core
        fulcioPkg["Fulcio gRPC Client"]:::core
        rekorPkg["Rekor REST Client"]:::core
        oidcPkg["OIDC Client"]:::core
        tufPkg["TUF Client"]:::core
        jsonPkg["JSON Canonicalizer"]:::core
        dssePkg["DSSE Verification"]:::core
        encPkg["Encryption & Signers"]:::core
        httpPkg["HTTP & gRPC Utilities"]:::core
        tsPkg["Timestamping Client"]:::core
        trustPkg["Trust Root Provider"]:::core
    end

    %% External Services (Orange)
    subgraph "External Sigstore Services"
        direction TB
        Fulcio[(Fulcio gRPC)]:::external
        Rekor[(Rekor REST)]:::external
        TSA[(Timestamping HTTP)]:::external
        TUFRepo[(TUF HTTP)]:::external
    end

    %% Build/Test Infrastructure (Gray)
    subgraph "Build & Test Infrastructure"
        direction TB
        BuildCommons["Build Logic Commons"]:::infra
        BuildLogic["Project-wide Build Logic"]:::infra
        Testkit["Test Harness / Testkit"]:::infra
        CI["GitHub Actions"]:::infra
        Artifacts["Maven Central Publishing"]:::infra
    end

    %% Relationships
    CLI -->|"invoke API"| API
    TCLI -->|"invoke API"| API
    GradlePlugin -->|"invoke API"| API
    MavenPlugin -->|"invoke API"| API
    Examples -->|"use API"| API
    Fuzzing -->|"use API"| API

    API -->|uses| fulcioPkg
    API -->|uses| rekorPkg
    API -->|uses| oidcPkg
    API -->|uses| tufPkg
    API -->|uses| jsonPkg
    API -->|uses| dssePkg
    API -->|uses| encPkg
    API -->|uses| httpPkg
    API -->|uses| tsPkg
    API -->|uses| trustPkg

    fulcioPkg -->|gRPC calls| Fulcio
    rekorPkg -->|REST calls| Rekor
    tsPkg -->|HTTP calls| TSA
    tufPkg -->|HTTP calls| TUFRepo

    Testkit -->|"stubs endpoints"| Fulcio
    Testkit -->|"stubs endpoints"| Rekor
    Testkit -->|"stubs endpoints"| TSA
    Testkit -->|"stubs endpoints"| TUFRepo

    BuildCommons --> CI
    BuildLogic --> CI
    CI --> Testkit
    CI -->|"publishes"| Artifacts

    %% Click Events
    click API "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/"
    click fulcioPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/fulcio"
    click rekorPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/rekor"
    click oidcPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/oidc"
    click tufPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/tuf"
    click jsonPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/json/canonicalizer"
    click dssePkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/dsse"
    click encPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/encryption"
    click httpPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/http"
    click tsPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/timestamp"
    click trustPkg "https://github.com/sigstore/sigstore-java/tree/main/sigstore-java/src/main/java/dev/sigstore/trustroot"
    click CLI "https://github.com/sigstore/sigstore-java/tree/main/sigstore-cli/"
    click TCLI "https://github.com/sigstore/sigstore-java/tree/main/tuf-cli/"
    click GradlePlugin "https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle/"
    click MavenPlugin "https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin/"
    click Testkit "https://github.com/sigstore/sigstore-java/tree/main/sigstore-testkit/"
    click Examples "https://github.com/sigstore/sigstore-java/tree/main/examples/"
    click Fuzzing "https://github.com/sigstore/sigstore-java/tree/main/fuzzing/"
    click BuildCommons "https://github.com/sigstore/sigstore-java/tree/main/build-logic-commons/"
    click BuildLogic "https://github.com/sigstore/sigstore-java/tree/main/build-logic/"

    %% Styles
    classDef consumer fill:#D0E8FF,stroke:#3399FF,color:#000
    classDef core fill:#E0FFD8,stroke:#33CC33,color:#000
    classDef external fill:#FFE4B3,stroke:#FF9933,color:#000
    classDef infra fill:#F0F0F0,stroke:#999,color:#000
```
