@novashield352/novashield-wso2 (v2.1.0)

This is the official NovaShield SDK designed to handle integration with WSO2 Identity Server using clean architecture methodologies. It is completely agnostic to the underlying framework (Express, NestJS, FastAPI backend, etc.).

Version 2.1.0 (Developer Experience Release) introduces features to make integration faster and more robust.

🚀 What's New in v2.1.0

1. OIDC Auto Discovery: Automatically fetch configuration from /.well-known/openid-configuration. No more manual endpoint setup.
2. Config Validator: Proactive validation of your configuration fields to prevent runtime errors.
3. Debug Mode: Enable detailed, structured logging with debug: true.
4. CLI Tool: Initialize your project configuration instantly with npx novashield init.

🛡️ Core Security Features

• JWT Signature Validation (JWKS): Automatically verifies cryptographic signatures using the JWKS endpoint.
• Native PKCE Support: Built-in S256 code challenge and verifier generators.
• Custom Error Hierarchy: Specific classes like Wso2AuthenticationError and Wso2SignatureError for precise error handling.
• OIDC Compliance: Strict validation of iss (issuer) and aud (audience).

📦 Installation

npm install @novashield352/novashield-wso2
# Or via yarn
yarn add @novashield352/novashield-wso2

🏗️ Quick Start

1. Initialize Configuration

Run the following command to generate a base configuration file:

npx novashield init

2. Initialize the Client

import { NovashieldAuthClient } from "@novashield352/novashield-wso2";

const config = {
  baseUrl: "https://your-wso2.com",
  clientId: "...",
  clientSecret: "...",
  autoDiscovery: true, // Enables fetching endpoints automatically
  debug: true, // Enables verbose logging
};

const wso2Client = new NovashieldAuthClient(config, new MyUserMapper());

// NEW: Call initialize() to perform discovery
await wso2Client.initialize();

🏗️ Architectural Benefits

• Typed Generics (TUser, TPermissions): Adapt the SDK to your domain model by passing your own TypeScript interfaces.
• Dependency Injection: SOLID principles by separating User Mapping (UserMapperProvider) and Permission Resolution (PermissionProvider).
• Network Abstraction: Decouples the "dirty work" of HTTPS and Base64 from your business logic.

🚀 Advanced Usage

Step 1: Implement Providers

import { UserMapperProvider } from "@novashield352/novashield-wso2";

export class Wso2UserMapper implements UserMapperProvider<MyUserShape> {
  fromIdToken(idTokenPayload: any): MyUserShape {
    return {
      id: idTokenPayload.sub,
      email: idTokenPayload.email,
    };
  }
}

Step 2: Authentication Flow (PKCE)

// 1. Generate Redirect URL
const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);
const authUrl = wso2Client.getAuthorizationUrl("secure_state", challenge);

// 2. Process Callback
const { user, tokens } = await wso2Client.handleCallback(code, verifier);

Step 3: Server-to-Server

// Obtains an application access token with automatic caching & rotation
const token = await wso2Client.getAppAccessToken();

📋 Method Summary

| Method | Description | | ------------------------------------------ | -------------------------------------------------- | | initialize() | NEW: Performs OIDC configuration discovery. | | getAuthorizationUrl(state, challenge?) | Generates the URL to initiate the OIDC flow. | | handleCallback(code, verifier?) | Exchanges the code for tokens and user profile. | | getLogoutUrl(idTokenHint, postLogoutUri) | Generates the logout URL. | | getAppAccessToken() | Obtains an application token (Client Credentials). | | getUserInfo(accessToken) | Queries the WSO2 /scim2/Me endpoint. |

🤝 Community & Support

• Repository: JoySky352/Novashield-wso2
• License: MIT

Developed with ❤️ by the NovaShield team.