# panva/jose architecture

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

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

## Overview

##### Project type and purpose
- This is an open‑source JavaScript/TypeScript library (not an end‑user application) named “jose.”
- Purpose: Provide JSON Web Token, Signature, Encryption, Key, and Key‑Set operations as tree‑shakeable ESM for multiple runtimes (Node.js, browsers, Deno, Bun, Cloudflare Workers, Electron, etc.).
- Key deliverables: modular APIs (jwtVerify, SignJWT, jwtDecrypt, EncryptJWT, compactSign, compactVerify, flattened‑encrypt/decrypt, general‑encrypt/decrypt, key import/export/generation, utilities, and error classes).

##### File structure
- src/ – main code, subdivided into:
- src/jwt, src/jws, src/jwe – high‑level APIs for tokens, signatures, encryption
- src/jwk, src/jwks, src/key – key import, export, generation, and key‑set management
- src/lib – core algorithm implementations and crypto helpers (AES‑KW, RSA, ECDH, PBES2, base64, etc.)
- src/util – small utilities (base64url, header decoding, error wrappers)
- src/index.ts – entry point aggregating and re‑exporting all modules
- docs/ and cookbook/ – generated API documentation organized by feature
- tap/ and test/ – runtime compatibility tests and unit tests for each feature
- GitHub workflows, tools/ – CI pipelines for build, test, release across environments
- Configuration files: tsconfig.json, typedoc.json, package.json, versionrc.json, patches/

##### README for additional insights
- Confirms zero external dependencies and broad runtime support via WebCrypto and Fetch API
- Details individual feature sections (JWT, JWE, JWS, JWK, JWKS, Utilities, Errors)
- Points to docs for each API surface, and highlights sponsored nature and version support table

##### Main components
a. Public API Layer
- High‑level classes/functions: SignJWT, EncryptJWT, jwtVerify, jwtDecrypt, compactSign, compactEncrypt, generalDecrypt, nested calls to key management and underlying crypto.
b. Module Layer
- jwt module, jws module, jwe module, jwk module, jwks module, key module, util module
c. Core Cryptographic Layer
- src/lib containing algorithm implementations and basic cryptographic utilities (AES‑GCM‑KW, RSAES, ECDH‑ES, PBES2, base64url, subtle abstraction)
d. External Runtime Adaptors
- WebCrypto API
- Fetch API for remote JWKS
- Runtime detection and shims (tap/.node.sh, tap/.deno.sh, etc.)
e. Tooling & CI
- Documentation generator (TypeDoc → docs/)
- Test runners (tap scripts for each environment, unit tests)
- Release pipeline (versionrc, GitHub Actions)

##### Relationships and interactions
- Public API Layer calls into Module Layer
- Module Layer relies on Core Cryptographic Layer and External Runtime Adaptors
- Key management modules feed keys into crypto routines
- Crypto routines produce JWE/JWS/JWT outputs or consume inputs
- Utilities support both layers (header decoding, error handling)
- CI and test runners orchestrate end‑to‑end validation across all components

##### Architectural patterns and design principles
- Modular decomposition by JOSE specification feature (Single Responsibility per folder)
- Tree‑shakeable ESM exports
- Runtime‑agnostic design via abstraction over WebCrypto and Fetch
- Layered pattern: API → Modules → Crypto Core → Platform
- Extensive test‑driven development and CI coverage

##### Essential elements
- Component names and grouping by functionality
- Annotations for external dependencies (WebCrypto, Fetch)
- CI & documentation flows to indicate maintainability aspects

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        API_Index["index.ts"]:::publicApi
    end

    %% Module Layer
    subgraph "Module Layer"
        direction TB
        %% JWT Module
        subgraph "JWT Module" 
            direction TB
            JWT_Sign["SignJWT"]:::modules
            JWT_Verify["jwtVerify"]:::modules
            JWT_Encrypt["EncryptJWT"]:::modules
            JWT_Decrypt["jwtDecrypt"]:::modules
            JWT_Unsecured["UnsecuredJWT"]:::modules
        end
        %% JWS Module
        subgraph "JWS Module"
            direction TB
            JWS_Compact_Sign["compactSign"]:::modules
            JWS_Compact_Verify["compactVerify"]:::modules
            JWS_Flattened_Sign["FlattenedSign"]:::modules
            JWS_Flattened_Verify["FlattenedVerify"]:::modules
            JWS_General_Sign["GeneralSign"]:::modules
            JWS_General_Verify["GeneralVerify"]:::modules
        end
        %% JWE Module
        subgraph "JWE Module"
            direction TB
            JWE_Compact_Encrypt["CompactEncrypt"]:::modules
            JWE_Compact_Decrypt["CompactDecrypt"]:::modules
            JWE_Flattened_Encrypt["FlattenedEncrypt"]:::modules
            JWE_Flattened_Decrypt["FlattenedDecrypt"]:::modules
            JWE_General_Encrypt["GeneralEncrypt"]:::modules
            JWE_General_Decrypt["GeneralDecrypt"]:::modules
        end
        %% JWK & JWKS & Key & Util
        subgraph "JWK Module"
            direction TB
            JWK_Embedded["Embedded JWK"]:::modules
            JWK_Thumbprint["JWK Thumbprint"]:::modules
        end
        subgraph "JWKS Module"
            direction TB
            JWKS_Local["createLocalJWKSet"]:::modules
            JWKS_Remote["createRemoteJWKSet"]:::modules
        end
        subgraph "Key Module"
            direction TB
            Key_Export["export (JWK/SPKI/PKCS8)"]:::modules
            Key_GenPair["generateKeyPair"]:::modules
            Key_GenSecret["generateSecret"]:::modules
            Key_Import["import keys"]:::modules
        end
        subgraph "Utilities"
            direction TB
            Util_Base64["base64url"]:::modules
            Util_DecodeJWT["decode_jwt"]:::modules
            Util_DecodeHeader["decode_protected_header"]:::modules
            Util_Errors["errors"]:::modules
        end
    end

    %% Core Cryptographic Layer
    subgraph "Core Cryptographic Layer"
        direction TB
        Core_AESGCMKW["aesgcmkw"]:::core
        Core_RSAES["rsaes"]:::core
        Core_ECDHES["ecdhes"]:::core
        Core_PBES2["pbes2kw"]:::core
        Core_EncryptKM["encrypt_key_management"]:::core
        Core_DecryptKM["decrypt_key_management"]:::core
        Core_Sign["sign"]:::core
        Core_Verify["verify"]:::core
        Core_Base64["base64"]:::core
        Core_CryptoKey["crypto_key"]:::core
    end

    %% External Runtime Adaptors
    subgraph "External Runtime Adaptors"
        direction TB
        Runtime_Node[".node.sh / run-node.ts"]:::runtime
        Runtime_Deno[".deno.sh / run-deno.ts"]:::runtime
        Runtime_Bun[".bun.sh / run-bun.ts"]:::runtime
        Runtime_Electron[".electron.sh / run-electron.ts"]:::runtime
        Runtime_Browser[".browser.ts / run-browser.ts"]:::runtime
        Runtime_Edge["run-edge-runtime.ts"]:::runtime
        Runtime_Workerd["run-workerd.ts"]:::runtime
    end

    %% Tooling & CI
    subgraph "Tooling & CI"
        direction TB
        CI_Build[".github/workflows/build.yml"]:::tooling
        CI_Test[".github/workflows/test.yml"]:::tooling
        CI_Release[".github/workflows/release.yml"]:::tooling
        CI_Lock[".github/workflows/lock.yml"]:::tooling
        CI_Retry[".github/workflows/retry.yml"]:::tooling
        Tools_PreBump["tools/prebump.cjs"]:::tooling
        Tools_PostBump["tools/postbump.cjs"]:::tooling
        Tools_Publish["tools/publish.cjs"]:::tooling
        Tools_ReleaseNotes["tools/release-notes.cjs"]:::tooling
    end

    %% Relationships
    API_Index -->|"calls"| JWT_Sign
    API_Index -->|"calls"| JWT_Verify
    API_Index -->|"calls"| JWT_Encrypt
    API_Index -->|"calls"| JWT_Decrypt
    API_Index -->|"calls"| JWT_Unsecured

    API_Index -->|"calls"| JWS_Compact_Sign
    API_Index -->|"calls"| JWS_Compact_Verify
    API_Index -->|"calls"| JWS_Flattened_Sign
    API_Index -->|"calls"| JWS_Flattened_Verify
    API_Index -->|"calls"| JWS_General_Sign
    API_Index -->|"calls"| JWS_General_Verify

    API_Index -->|"calls"| JWE_Compact_Encrypt
    API_Index -->|"calls"| JWE_Compact_Decrypt
    API_Index -->|"calls"| JWE_Flattened_Encrypt
    API_Index -->|"calls"| JWE_Flattened_Decrypt
    API_Index -->|"calls"| JWE_General_Encrypt
    API_Index -->|"calls"| JWE_General_Decrypt

    API_Index -->|"uses"| JWK_Embedded
    API_Index -->|"uses"| JWK_Thumbprint
    API_Index -->|"uses"| JWKS_Local
    API_Index -->|"uses"| JWKS_Remote

    API_Index -->|"uses"| Key_Export
    API_Index -->|"uses"| Key_GenPair
    API_Index -->|"uses"| Key_GenSecret
    API_Index -->|"uses"| Key_Import

    %% Modules to Core
    JWT_Sign -->|"crypto"| Core_Sign
    JWT_Verify -->|"crypto"| Core_Verify
    JWT_Encrypt -->|"crypto"| Core_EncryptKM
    JWT_Decrypt -->|"crypto"| Core_DecryptKM

    JWS_Compact_Sign -->|"crypto"| Core_Sign
    JWS_Compact_Verify -->|"crypto"| Core_Verify

    JWE_Compact_Encrypt -->|"crypto"| Core_EncryptKM
    JWE_Compact_Decrypt -->|"crypto"| Core_DecryptKM

    Key_Export -->|"uses"| Core_CryptoKey
    Key_Import -->|"uses"| Core_CryptoKey

    %% Modules to Util
    JWT_Verify -->|"util"| Util_DecodeJWT
    JWT_Verify -->|"util"| Util_Errors

    Util_Base64 -->|"support"| Core_Base64

    %% Modules to Runtime Adaptors
    JWKS_Remote -->|"fetch"| Runtime_Browser
    JWKS_Remote -->|"fetch"| Runtime_Node

    %% CI & Tooling flows
    CI_Build -->|"build docs"| Tools_Publish
    CI_Test -->|"run tests"| Runtime_Node
    CI_Test -->|"run tests"| Runtime_Deno
    CI_Test -->|"run tests"| Runtime_Bun
    CI_Test -->|"run tests"| Runtime_Electron
    CI_Test -->|"run tests"| Runtime_Browser

    %% Styling
    classDef publicApi fill:#e0f7e9,stroke:#2ca02c,color:#000
    classDef modules fill:#e7f0fd,stroke:#1f77b4,color:#000
    classDef core fill:#ffe6cc,stroke:#ff7f0e,color:#000
    classDef runtime fill:#f3e6ff,stroke:#9467bd,color:#000
    classDef tooling fill:#f2f2f2,stroke:#7f7f7f,color:#000

    %% Click events
    click API_Index "https://github.com/panva/jose/blob/main/src/index.ts"
    click JWT_Sign "https://github.com/panva/jose/blob/main/src/jwt/sign.ts"
    click JWT_Verify "https://github.com/panva/jose/blob/main/src/jwt/verify.ts"
    click JWT_Encrypt "https://github.com/panva/jose/blob/main/src/jwt/encrypt.ts"
    click JWT_Decrypt "https://github.com/panva/jose/blob/main/src/jwt/decrypt.ts"
    click JWT_Unsecured "https://github.com/panva/jose/blob/main/src/jwt/unsecured.ts"

    click JWS_Compact_Sign "https://github.com/panva/jose/blob/main/src/jws/compact/sign.ts"
    click JWS_Compact_Verify "https://github.com/panva/jose/blob/main/src/jws/compact/verify.ts"
    click JWS_Flattened_Sign "https://github.com/panva/jose/blob/main/src/jws/flattened/sign.ts"
    click JWS_Flattened_Verify "https://github.com/panva/jose/blob/main/src/jws/flattened/verify.ts"
    click JWS_General_Sign "https://github.com/panva/jose/blob/main/src/jws/general/sign.ts"
    click JWS_General_Verify "https://github.com/panva/jose/blob/main/src/jws/general/verify.ts"

    click JWE_Compact_Encrypt "https://github.com/panva/jose/blob/main/src/jwe/compact/encrypt.ts"
    click JWE_Compact_Decrypt "https://github.com/panva/jose/blob/main/src/jwe/compact/decrypt.ts"
    click JWE_Flattened_Encrypt "https://github.com/panva/jose/blob/main/src/jwe/flattened/encrypt.ts"
    click JWE_Flattened_Decrypt "https://github.com/panva/jose/blob/main/src/jwe/flattened/decrypt.ts"
    click JWE_General_Encrypt "https://github.com/panva/jose/blob/main/src/jwe/general/encrypt.ts"
    click JWE_General_Decrypt "https://github.com/panva/jose/blob/main/src/jwe/general/decrypt.ts"

    click JWK_Embedded "https://github.com/panva/jose/blob/main/src/jwk/embedded.ts"
    click JWK_Thumbprint "https://github.com/panva/jose/blob/main/src/jwk/thumbprint.ts"

    click JWKS_Local "https://github.com/panva/jose/blob/main/src/jwks/local.ts"
    click JWKS_Remote "https://github.com/panva/jose/blob/main/src/jwks/remote.ts"

    click Key_Export "https://github.com/panva/jose/blob/main/src/key/export.ts"
    click Key_GenPair "https://github.com/panva/jose/blob/main/src/key/generate_key_pair.ts"
    click Key_GenSecret "https://github.com/panva/jose/blob/main/src/key/generate_secret.ts"
    click Key_Import "https://github.com/panva/jose/blob/main/src/key/import.ts"
```
