@jeap/jeap-jwe-client

Angular client library for transparent JWE request and response protection between Angular frontends and jEAP backend services.

The library protects requests to a configured backend origin, encrypts supported request bodies as compact JWE, sends a request-local response key in JWE-Response-Key, and decrypts encrypted application/jose responses back into normal Angular HttpClient responses.

What it does

• Loads backend JWE configuration from /.well-known/jwe-configuration.
• Loads public encryption keys from the configured JWKS endpoint.
• Uses the first public JWKS key as the current request encryption key.
• Encrypts JSON request bodies with RSA-OAEP-256 and A256GCM.
• Always sends JWE-Response-Key for protected requests, including GET.
• Sets Accept: application/jose for protected requests.
• Decrypts backend responses that use alg: dir and enc: A256GCM.
• Refreshes JWKS and retries once when the backend returns JWE_UNKNOWN_KEY_ID.
• Protects only paths matching an include and no exclude pattern (aligned with the backend); leaves other paths and origins untouched.

Installation

npm install @jeap/jeap-jwe-client

jose is pulled in automatically as a bundled runtime dependency.

Minimal Angular setup

The library does not call provideHttpClient itself. The consuming application owns its HttpClient setup and must register the jeapJweInterceptor alongside provideJeapJweClient, as shown below.

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import {
  jeapJweInterceptor,
  provideJeapJweClient,
} from '@jeap/jeap-jwe-client';

export const appConfig: ApplicationConfig = {
  providers: [
    provideJeapJweClient({
      origin: 'https://api.example.ch',
    }),
    provideHttpClient(withInterceptors([jeapJweInterceptor])),
  ],
};

With this configuration the client loads:

GET https://api.example.ch/.well-known/jwe-configuration
GET https://api.example.ch/.well-known/jwks.json

The backend metadata may provide the JWKS path, the content-type allowlist, the response-key header, and the include/exclude path patterns (includedPaths/excludedPaths) that decide which requests are protected.

Documentation

Full documentation for @jeap/jeap-jwe-client is published with the jEAP documentation and on GitHub:

• jEAP documentation site: jeap-admin-ch.github.io
• Source and docs on GitHub: jeap-jwe-client/docs

Recommended reading order:

1. Getting started
2. Configuration
3. Backend contract
4. Architecture
5. Key rotation
6. Error handling
7. Testing
8. Security considerations
9. Publishing and versioning

License

This library is Open Source Software licensed under the Apache License 2.0.