# latchset/jose architecture

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

- Interactive diagram: https://gitdiagram.com/latchset/jose
- Repository: https://github.com/latchset/jose

## Overview

##### Project type and purpose
- José is a C-language implementation of the JOSE standards (JWS, JWE, JWK, JWA, JWT, etc.) and provides both a reusable library (libjose) and a command-line utility (`jose`) that exposes its functionality.

##### File structure
- Top-level directories
- cmd/     → CLI front-ends (alg, b64, jose, jwe, jwk, jws, fmt)
- lib/     → Core implementation modules (b64, cfg, io, jwe, jwk, jws, hooks, hsh, misc) and embedded crypto providers (lib/openssl, lib/zlib)
- / → Public headers for users of libjose
- tests/   → RFC-compliant test suites and vector files
- doc/     → Doxygen and man-page documentation
- Build files: `meson.build`, Meson options, GitHub Actions workflow

##### README for additional insights
- Lists the supported JOSE specs, algorithms, usage examples for key management, signing/verifying, encryption/decryption
- Emphasizes that the library is extensively tested against RFC vectors

a. Main components
1. CLI Layer – individual executables under cmd/
2. Library Layer – libjose core modules
3. Crypto Providers – OpenSSL adaptor, zlib adaptor
4. External Dependencies – jansson (JSON), OpenSSL, zlib
5. Test Harness – invokes CLI and library with RFC vectors
6. Documentation – Doxygen, man pages
b. Relationships & interactions
- CLI executables parse args → invoke high-level API in libjose
- libjose dispatches to sub-modules (b64, cfg, io, jwe, jws, jwk, misc)
- Modules call out to Crypto Providers (OpenSSL for asymmetric/symmetric crypto; zlib for compression)
- I/O module handles file/stdin/stdout; cfg module handles JSON config (via jansson)
- Tests invoke CLI and/or directly call libjose to validate against vectors
c. Architectural patterns and design principles
- Layered architecture: CLI → API → modules → providers
- Modular design: each JOSE spec in its own sub-module
- Adapter pattern: openssl and zlib integrations appear behind uniform provider interfaces
- Build & packaging: Meson build orchestrates compilation, testing, and installation
d. Relevant technologies
- C99 codebase, Meson build system, ninja, GitHub Actions
- External libs: OpenSSL, zlib, jansson

##### Elements
- Blue for executable/CLI
- Green for library modules
- Yellow for external providers/deps
- Gray for tests/docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_jose["jose CLI"]:::cli
        CLI_b64_enc["b64 enc"]:::cli
        CLI_b64_dec["b64 dec"]:::cli
        CLI_jwe_enc["jwe enc"]:::cli
        CLI_jwe_dec["jwe dec"]:::cli
        CLI_jwe_fmt["jwe fmt"]:::cli
        CLI_jwk_gen["jwk gen"]:::cli
        CLI_jwk_pub["jwk pub"]:::cli
        CLI_jwk_eql["jwk eql"]:::cli
        CLI_jwk_exc["jwk exc"]:::cli
        CLI_jwk_thp["jwk thp"]:::cli
        CLI_jwk_use["jwk use"]:::cli
        CLI_jws_sig["jws sig"]:::cli
        CLI_jws_ver["jws ver"]:::cli
        CLI_jws_fmt["jws fmt"]:::cli
        CLI_alg["alg"]:::cli
        CLI_fmt["fmt"]:::cli
    end

    %% Library API
    LibAPI["libjose API"]:::lib

    %% Connections CLI -> API
    CLI_jose --> LibAPI
    CLI_b64_enc --> LibAPI
    CLI_b64_dec --> LibAPI
    CLI_jwe_enc --> LibAPI
    CLI_jwe_dec --> LibAPI
    CLI_jwe_fmt --> LibAPI
    CLI_jwk_gen --> LibAPI
    CLI_jwk_pub --> LibAPI
    CLI_jwk_eql --> LibAPI
    CLI_jwk_exc --> LibAPI
    CLI_jwk_thp --> LibAPI
    CLI_jwk_use --> LibAPI
    CLI_jws_sig --> LibAPI
    CLI_jws_ver --> LibAPI
    CLI_jws_fmt --> LibAPI
    CLI_alg --> LibAPI
    CLI_fmt --> LibAPI

    %% Library Modules
    subgraph "Library Modules"
        MOD_b64["b64 module"]:::lib
        MOD_cfg["cfg module"]:::lib
        MOD_io["io module"]:::lib
        MOD_jwe["JWE module"]:::lib
        MOD_jws["JWS module"]:::lib
        MOD_jwk["JWK module"]:::lib
        MOD_misc["misc module"]:::lib
        MOD_hooks["hooks module"]:::lib
        MOD_hsh["hsh module"]:::lib
    end

    %% API -> Modules
    LibAPI --> MOD_b64
    LibAPI --> MOD_cfg
    LibAPI --> MOD_io
    LibAPI --> MOD_jwe
    LibAPI --> MOD_jws
    LibAPI --> MOD_jwk
    LibAPI --> MOD_misc
    LibAPI --> MOD_hooks
    LibAPI --> MOD_hsh

    %% Crypto Providers
    subgraph "Crypto Providers"
        Prov_ssl["OpenSSL adaptor"]:::provider
        Prov_zlib["zlib adaptor"]:::provider
    end

    %% Modules -> Providers
    MOD_jwe --> Prov_ssl
    MOD_jwe --> Prov_zlib
    MOD_jws --> Prov_ssl
    MOD_jwk --> Prov_ssl
    MOD_hsh --> Prov_ssl

    %% External Dependencies
    ext_jansson["jansson (JSON)"]:::ext
    ext_build["Meson build"]:::ext

    %% Dependencies
    ext_jansson --> MOD_cfg
    ext_build -.-> LibAPI
    ext_build -.-> CLI_jose

    %% Test Harness & Documentation
    Tests["Test Harness"]:::tests
    Docs["Documentation"]:::docs

    %% Test & Docs interactions
    Tests -.-> CLI_jose
    Tests -.-> LibAPI
    ext_build --> Docs

    %% Click events for CLI
    click CLI_jose "https://github.com/latchset/jose/blob/master/cmd/jose.c"
    click CLI_b64_enc "https://github.com/latchset/jose/blob/master/cmd/b64/enc.c"
    click CLI_b64_dec "https://github.com/latchset/jose/blob/master/cmd/b64/dec.c"
    click CLI_jwe_enc "https://github.com/latchset/jose/blob/master/cmd/jwe/enc.c"
    click CLI_jwe_dec "https://github.com/latchset/jose/blob/master/cmd/jwe/dec.c"
    click CLI_jwe_fmt "https://github.com/latchset/jose/blob/master/cmd/jwe/fmt.c"
    click CLI_jwk_gen "https://github.com/latchset/jose/blob/master/cmd/jwk/gen.c"
    click CLI_jwk_pub "https://github.com/latchset/jose/blob/master/cmd/jwk/pub.c"
    click CLI_jwk_eql "https://github.com/latchset/jose/blob/master/cmd/jwk/eql.c"
    click CLI_jwk_exc "https://github.com/latchset/jose/blob/master/cmd/jwk/exc.c"
    click CLI_jwk_thp "https://github.com/latchset/jose/blob/master/cmd/jwk/thp.c"
    click CLI_jwk_use "https://github.com/latchset/jose/blob/master/cmd/jwk/use.c"
    click CLI_jws_sig "https://github.com/latchset/jose/blob/master/cmd/jws/sig.c"
    click CLI_jws_ver "https://github.com/latchset/jose/blob/master/cmd/jws/ver.c"
    click CLI_jws_fmt "https://github.com/latchset/jose/blob/master/cmd/jws/fmt.c"
    click CLI_alg "https://github.com/latchset/jose/blob/master/cmd/alg.c"
    click CLI_fmt "https://github.com/latchset/jose/blob/master/cmd/fmt.c"

    %% Click events for Library Modules
    click MOD_b64 "https://github.com/latchset/jose/blob/master/lib/b64.c"
    click MOD_cfg "https://github.com/latchset/jose/blob/master/lib/cfg.c"
    click MOD_io "https://github.com/latchset/jose/blob/master/lib/io.c"
    click MOD_jwe "https://github.com/latchset/jose/blob/master/lib/jwe.c"
    click MOD_jws "https://github.com/latchset/jose/blob/master/lib/jws.c"
    click MOD_jwk "https://github.com/latchset/jose/blob/master/lib/jwk.c"
    click MOD_misc "https://github.com/latchset/jose/blob/master/lib/misc.c"
    click MOD_hooks "https://github.com/latchset/jose/blob/master/lib/hooks.c"
    click MOD_hsh "https://github.com/latchset/jose/blob/master/lib/hsh.c"

    %% Click events for Providers
    click Prov_ssl "https://github.com/latchset/jose/tree/master/lib/openssl/"
    click Prov_zlib "https://github.com/latchset/jose/blob/master/lib/zlib/deflate.c"

    %% Click events for Tests and Docs
    click Tests "https://github.com/latchset/jose/tree/master/tests/"
    click Docs "https://github.com/latchset/jose/tree/master/doc/"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000;
    classDef lib fill:#90EE90,stroke:#000;
    classDef provider fill:#FFFFE0,stroke:#000;
    classDef ext fill:#FFD700,stroke:#000;
    classDef tests fill:#D3D3D3,stroke:#000;
    classDef docs fill:#D3D3D3,stroke:#000;
```
