# openwallet-foundation-labs/openid-federation-ts architecture

> Architecture diagram of the GitHub repository openwallet-foundation-labs/openid-federation-ts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openwallet-foundation-labs/openid-federation-ts
- Repository: https://github.com/openwallet-foundation-labs/openid-federation-ts

## Overview

##### Project Type and Purpose
- This is a TypeScript-based, open-source library (monorepo) implementing the core of the OpenID Federation specification.
- There is no UI or server “application” per se—this is a reusable package that other services import to create, fetch, validate, and resolve OpenID Federation entity configurations and statements, manipulate metadata policies, verify JSON Web Tokens, and resolve trust chains.

##### File–Structure Analysis
- Top-level: a pnpm workspace with one package under `packages/core`.
- `packages/core/src/` is divided into modules:
- `entityConfiguration/` · create & fetch entity configurations (JWT)
- `entityStatement/` · create & fetch entity statements (JWT)
- `jsonWeb/` · JWT creation, parsing, verification, JWK management
- `metadata/` · entity metadata definitions & policy operators/merging
- `resolveTrustChains/` · trust-chain resolution and policy application
- `trustMark/` · trust mark creation and consumption
- `error/` · domain-specific error types
- `utils/` · shared utilities (fetch wrappers, encoding, schemas, validation)
- Test suites mirror these modules to validate each piece.

##### README Insights
- Reinforces that `@openid-federation/core` is the sole package — it exposes an API surface for federation flows.
- No deployment or runtime servers; the library assumes a host environment capable of HTTP fetches and cryptographic primitives.

##### Diagramming the Architecture
- Consumer Application (the host service importing the library)
- Core Library Boundary
– EntityConfiguration Module
– EntityStatement Module
– JSONWeb Module
– Metadata & Policy Operator Module
– ResolveTrustChains Module
– TrustMark Module
– Utils & Error Modules
- External Dependencies
– HTTP Endpoints (to fetch remote configurations/statements)
– Cryptographic Service (WebCrypto or Node.js crypto)
1. Consumer invokes “create” or “fetch” functions in EntityConfiguration/EntityStatement.
2. Those modules call HTTP fetch via Utils → retrieve JWT from remote endpoint.
3. JSONWeb verifies/parses the JWT using keys fetched or provided.
4. Metadata module loads the entity metadata and applies policy operators.
5. ResolveTrustChains consumes a set of statements & policies, applies merges, and outputs a resolved chain.
6. TrustMark module issues or consumes trust marks based on resolved metadata & claims.
c. Architectural Patterns
- Layered, modular design: each concern (JWT, metadata, policy, trust chains) lives in its own layer.
- Functional API surface: pure functions that compose together.
- Strategy pattern for metadata operators.
d. Key Technologies
- TypeScript (static types, module boundaries)
- Fetch API (HTTP client)
- JSON Web Token & Key (JWK) handling
- JSON Schema for policy validation
- pnpm workspace for monorepo management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer
    Consumer["Consumer Application"]:::consumer

    %% Core Library Boundary
    subgraph "Core Library" 
        direction TB
        API["Public API Surface"]:::boundary

        EC["EntityConfiguration Module"]:::fetching
        ES["EntityStatement Module"]:::fetching

        UT["Utils Module"]:::utility
        ER["Error Module"]:::utility

        JW["JSONWeb Module"]:::processing
        MD["Metadata Module"]:::processing
        OP["Metadata Policy Operator Module"]:::processing
        RTC["ResolveTrustChains Module"]:::processing
        TM["TrustMark Module"]:::processing
    end

    %% External Dependencies
    HTTP["HTTP Endpoints"]:::external
    CRYPTO["Cryptographic Service"]:::external

    %% Connections
    Consumer -->|"imports and calls"| API

    API -->|"create/fetch EC"| EC
    API -->|"create/fetch ES"| ES

    EC -->|"uses fetch"| UT
    ES -->|"uses fetch"| UT

    UT -->|"HTTP request"| HTTP
    HTTP -->|"JWT response"| EC
    HTTP -->|"JWT response"| ES

    EC -->|"JWT to parse"| JW
    ES -->|"JWT to parse"| JW

    JW -->|"verification/parsing"| CRYPTO
    JW -->|"parsed JWT"| MD
    JW -->|"error"| ER

    MD -->|"loads metadata"| OP
    OP -->|"operator result"| MD
    MD -->|"metadata with policies"| RTC
    MD -->|"validation error"| ER

    RTC -->|"trust chain"| TM
    TM -->|"trust marks/results"| Consumer

    %% Click Events
    click EC "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/entityConfiguration"
    click ES "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/entityStatement"
    click JW "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/jsonWeb"
    click MD "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/metadata"
    click OP "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/metadata/operator"
    click RTC "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/resolveTrustChains"
    click TM "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/trustMark"
    click UT "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/utils"
    click ER "https://github.com/openwallet-foundation-labs/openid-federation-ts/tree/main/packages/core/src/error"
    click API "https://github.com/openwallet-foundation-labs/openid-federation-ts/blob/main/packages/core/src/index.ts"

    %% Styles
    classDef consumer fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef boundary fill:#dddddd,stroke:#333,stroke-width:2px
    classDef fetching fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef processing fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef utility fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#FFF0F5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
