idp.global/app
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add package READMEs and publish metadata; update web package publish order

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-16 12:46:42 +00:00
parent 2ad751ecba
commit 5462257398
10 changed files with 1228 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+271 -255
View File
@@ -1,312 +1,328 @@
# @idp.global/idp.global
An identity provider software managing user authentications, registrations, and sessions.
🔐 **A modern, open-source Identity Provider (IdP) SaaS platform** for managing user authentication, registrations, sessions, and organization-based access control.
## Install
Built with TypeScript and designed for modern web applications, idp.global provides a complete identity management solution that you can self-host or use as a service.
To install `@idp.global/idp.global`, you can run the following command in your terminal:
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## ✨ Features
### 🔑 Authentication & Authorization
- **Multiple Login Methods**: Email/password, email magic links, API tokens
- **JWT-Based Sessions**: Secure token management with automatic refresh
- **Two-Factor Authentication**: Enhanced security with 2FA support
- **Password Reset**: Secure password recovery flow
- **Device Management**: Track and manage authenticated devices
### 🏢 Organization Management
- **Multi-Tenant Architecture**: Support multiple organizations per user
- **Role-Based Access Control (RBAC)**: Fine-grained permissions system
- **Organization Roles**: Admin, member, and custom role support
- **Member Invitations**: Bulk invite and manage team members
- **Ownership Transfer**: Seamlessly transfer organization ownership
### 🔗 Third-Party Integration
- **OpenID Connect (OIDC) Provider**: Full OIDC compliance for third-party apps
- Discovery endpoint (`/.well-known/openid-configuration`)
- JWKS endpoint for token verification
- Authorization code flow with PKCE
- Token refresh and revocation
- **OAuth 2.0**: Standard OAuth flows for app authorization
- **Supported Scopes**: `openid`, `profile`, `email`, `organizations`, `roles`
### 💳 Billing Integration
- **Paddle Integration**: Built-in payment processing support
- **Billing Plans**: Flexible subscription management
- **Checkout Flows**: Streamlined payment experiences
### 🎨 Modern Web UI
- **Responsive Design**: Beautiful UI components built with `@design.estate/dees-catalog`
- **Account Management**: User profile, settings, and preferences
- **Organization Dashboard**: Manage members, roles, and apps
- **Admin Panel**: Global administration interface
### 📡 Real-Time Communication
- **WebSocket Support**: Real-time updates via TypedSocket
- **Typed API Requests**: Type-safe client-server communication
- **Public Key Distribution**: Automatic JWT key rotation notifications
## 🏗️ Architecture
idp.global is built as a modular TypeScript monorepo:
```
├── ts/ # Server-side code (Node.js)
│ └── reception/ # Core identity management logic
├── ts_interfaces/ # Shared TypeScript interfaces (published as @idp.global/interfaces)
├── ts_idpclient/ # Browser/Node client library (published as @idp.global/idpclient)
├── ts_idpcli/ # Command-line interface tool
└── ts_web/ # Web frontend (published as @idp.global/web)
```
### Core Managers
| Manager | Responsibility |
|---------|----------------|
| `JwtManager` | JWT generation, validation, and key management |
| `LoginSessionManager` | Session creation and authentication |
| `UserManager` | User CRUD and profile management |
| `OrganizationManager` | Organization lifecycle management |
| `RoleManager` | RBAC and permission management |
| `OidcManager` | OpenID Connect provider functionality |
| `AppManager` | OAuth client app registration |
| `BillingPlanManager` | Subscription and payment handling |
## 🚀 Quick Start
### 🐳 Docker Deployment (Recommended)
The easiest way to run idp.global is using Docker:
```bash
npm install @idp.global/idp.global
# Pull the latest image
docker pull code.foss.global/idp.global/idp.global
# Run with environment variables
docker run -d \
-p 2999:2999 \
-e MONGODB_URL=mongodb://your-mongo:27017/idp \
-e IDP_BASEURL=https://your-domain.com \
-e INSTANCE_NAME=idp.global \
code.foss.global/idp.global/idp.global
```
This will download and install the necessary dependencies along with the module to your project.
### Environment Variables
## Usage
| Variable | Description | Required |
|----------|-------------|----------|
| `MONGODB_URL` | MongoDB connection string | ✅ Yes |
| `IDP_BASEURL` | Public URL of your idp.global instance | ✅ Yes |
| `INSTANCE_NAME` | Name for this IDP instance | No (default: `idp.global`) |
| `SERVEZONE_PLATFROM_AUTHORIZATION` | ServeZone platform auth token | No |
To use `@idp.global/idp.global`, one needs to understand its key components and functionalities. Below, we'll guide you through setting up, logging in, registering, and managing users and organizations within an IDP (Identity Provider) environment using this package.
### Docker Compose Example
### Setting Up the Environment
```yaml
version: '3.8'
services:
idp:
image: code.foss.global/idp.global/idp.global
ports:
- "2999:2999"
environment:
MONGODB_URL: mongodb://mongo:27017/idp
IDP_BASEURL: https://idp.yourdomain.com
INSTANCE_NAME: my-idp
depends_on:
- mongo
First, let's set up the environment:
mongo:
image: mongo:7
volumes:
- mongo-data:/data/db
```typescript
// Import the necessary modules
import * as serviceworker from '@api.global/typedserver/web_serviceworker_client';
import * as domtools from '@design.estate/dees-domtools';
import { html, render } from '@design.estate/dees-element';
import { IdpWelcome } from './elements/idp-welcome.js';
// Define an asynchronous run function
const run = async () => {
// Set up DOM tools
const domtoolsInstance = await domtools.DomTools.setupDomTools();
domtools.elementBasic.setup();
// Configure website information
domtoolsInstance.setWebsiteInfo({
metaObject: {
title: 'idp.global',
description: 'the code that runs idp.global',
canonicalDomain: 'https://idp.global',
ldCompany: {
name: 'Task Venture Capital GmbH',
status: 'active',
contact: {
address: {
name: 'Task Venture Capital GmbH',
city: 'Grasberg',
country: 'Germany',
houseNumber: '24',
postalCode: '28879',
streetName: 'Eickedorfer Vorweide',
},
}
},
},
});
// Set up the service worker
const serviceWorker = await serviceworker.getServiceworkerClient();
// Render the main template
const mainTemplate = html`
<style>
body {
margin: 0px;
--background-accent: #303f9f;
}
</style>
<idp-welcome></idp-welcome>
`;
render(mainTemplate, document.body);
};
// Run the function
run();
volumes:
mongo-data:
```
### Using the IDP Client
The server listens on port 2999 by default.
The IDP Client is essential to communicate with the IDP server. Below is a sample of how to set up and use the IDP client:
## 📦 Published Packages
This monorepo publishes the following npm packages:
| Package | Description |
|---------|-------------|
| `@idp.global/interfaces` | TypeScript interfaces for API contracts |
| `@idp.global/idpclient` | Client library for browser and Node.js |
| `@idp.global/web` | Web UI components |
## 💻 Client Usage
### Browser Client
```typescript
import { IdpState } from './idp.state.js';
import * as plugins from './plugins.js';
import { IdpClient } from '@idp.global/idpclient';
// Instantiate IdpState which provides a singleton instance
export class IdpDemo {
private idpState = IdpState.getSingletonInstance();
// Initialize the client
const idpClient = new IdpClient('https://idp.global');
// Function to initialize and use IdpClient
public async demo() {
// Fetch the client instance
const { idpClient } = this.idpState;
// Handler for login
const handleLogin = async () => {
const response = await idpClient.requests.loginWithUserNameAndPassword.fire({
username: 'user@example.com',
password: 'password123',
});
if (response.refreshToken) {
await idpClient.storeJwt(response.jwt);
console.log("Logged in successfully, JWT stored.");
} else {
console.log("Login failed.");
}
};
// Execute login handler
await handleLogin();
}
// Enable WebSocket connection
await idpClient.enableTypedSocket();
// Check login status
const isLoggedIn = await idpClient.determineLoginStatus();
// Login with email and password
const response = await idpClient.requests.loginWithUserNameAndPassword.fire({
username: 'user@example.com',
password: 'securepassword'
});
if (response.refreshToken) {
await idpClient.refreshJwt(response.refreshToken);
console.log('✅ Login successful!');
}
// Instantiate and run demo
const demo = new IdpDemo();
demo.demo();
// Get current user info
const userInfo = await idpClient.whoIs();
console.log('User:', userInfo.user);
// Get user's organizations
const orgs = await idpClient.getRolesAndOrganizations();
console.log('Organizations:', orgs.organizations);
```
### Managing User Authentication
Several functionalities are available for managing user authentication. These include registering, logging in, and refreshing JWTs.
#### Registration Process
The registration process is typically more involved and requires steps such as email validation, setting user-specific data, and verifying OTPs for additional security.
### Organization Management
```typescript
import * as plugins from './plugins.js';
import { IdpState } from './idp.state.js';
// Create a new organization
const result = await idpClient.createOrganization('My Company', 'my-company', 'manifest');
console.log('Created:', result.resultingOrganization);
// Registration stepper element
export class IdpRegistrationStepper extends plugins.DeesElement {
private idpState = IdpState.getSingletonInstance();
// Invite members
await idpClient.requests.createInvitation.fire({
jwt: await idpClient.getJwt(),
organizationId: 'org-id',
email: 'newmember@example.com',
roles: ['member']
});
```
public async firstUpdated() {
await this.domtoolsPromise;
this.domtools.router.on(`/finishregistration`, async (routeArg) => {
const validationToken = routeArg.queryParams.validationtoken;
if (!validationToken) {
this.renderErrorMessage("Validation token not found.");
return;
}
const emailResponse = await this.validateEmail(validationToken);
if (!emailResponse.email) {
this.renderErrorMessage("Invalid validation token.");
return;
}
await this.renderRegistrationForm(emailResponse.email);
});
}
### CLI Tool
private async validateEmail(token: string) {
return await this.idpState.idpClient.requests.afterRegistrationEmailClicked.fire({
token
});
}
The `ts_idpcli` module provides a command-line interface:
private async renderRegistrationForm(email: string) {
const template = plugins.html`
<dees-form @formData="${async (event) => await this.handleFormSubmission(event, email)}">
<dees-input-text key="First Name" label="First Name" required></dees-input-text>
<dees-input-text key="Last Name" label="Last Name" required></dees-input-text>
<dees-form-submit>Next</dees-form-submit>
</dees-form>
`;
this.render(template, this.shadowRoot);
}
```bash
# Login
idp login
private async handleFormSubmission(event: FormDataEvent, email: string) {
const formData = (event.target as any).getFormData();
await this.idpState.idpClient.requests.setData.fire({
token: this.storedData.validationTokenUrlParam,
userData: {
email,
first_name: formData.FirstName,
last_name: formData.LastName,
},
});
// Proceed to the next steps as per the registration flow
}
# Show current user
idp whoami
private renderErrorMessage(message: string) {
const template = plugins.html`<div>Error: ${message}</div>`;
this.render(template, this.shadowRoot);
}
# List organizations
idp orgs
# List organization members
idp members --org <org-id>
# Invite a user
idp invite --org <org-id> --email user@example.com
```
## 🔐 OIDC Integration
idp.global implements a full OpenID Connect provider. Third-party applications can use it for SSO:
### Discovery Document
```
GET /.well-known/openid-configuration
```
### Authorization Flow
```
GET /oauth/authorize?
client_id=your-client-id&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=openid profile email organizations&
state=random-state&
code_challenge=PKCE_CHALLENGE&
code_challenge_method=S256
```
### Token Exchange
```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=your-client-id&
client_secret=your-client-secret&
code_verifier=PKCE_VERIFIER
```
### UserInfo
```
GET /oauth/userinfo
Authorization: Bearer ACCESS_TOKEN
```
Response:
```json
{
"sub": "user-id",
"name": "John Doe",
"email": "john@example.com",
"email_verified": true,
"organizations": [
{ "id": "org-1", "name": "Acme Corp", "slug": "acme", "roles": ["admin"] }
],
"roles": ["user"]
}
```
### User Management
## 🛠️ Tech Stack
Managing user data including roles, organizations, and billing plans is essential in any identity provider software.
- **Runtime**: Node.js with ES Modules
- **Language**: TypeScript (strict mode)
- **Database**: MongoDB via `@push.rocks/smartdata`
- **Web Server**: `@api.global/typedserver`
- **Real-time**: `@api.global/typedsocket` (WebSocket)
- **JWT**: `@push.rocks/smartjwt` (RS256 signing)
- **Frontend**: `@design.estate/dees-element` (Web Components)
- **Build**: `@git.zone/tsbuild` + `@git.zone/tsbundle`
#### Getting User Data
## 📚 API Reference
```typescript
import * as plugins from './plugins.js';
### Request Interfaces
const fetchUserData = async (jwt: string) => {
const user = await plugins.typedrequest.TypedRequest<plugins.lointReception.request.IReq_GetUserData>(
`/getUserData`, 'POST').fire({jwt});
console.log(user);
};
All API requests are type-safe. See `ts_interfaces/request/` for the complete API:
fetchUserData('<JWT_TOKEN_HERE>');
```
- **Authentication**: `IReq_LoginWithEmail`, `IReq_LoginWithApiToken`, `IReq_RefreshJwt`
- **Registration**: `IReq_FirstRegistration`, `IReq_FinishRegistration`
- **User Management**: `IReq_GetUserData`, `IReq_SetUserData`, `IReq_GetUserSessions`
- **Organizations**: `IReq_CreateOrganization`, `IReq_GetOrgMembers`, `IReq_CreateInvitation`
- **Apps & OAuth**: `IReq_GetGlobalApps`, `IReq_CreateGlobalApp`
- **Billing**: `IReq_GetBillingPlan`, `IReq_UpdatePaymentMethod`
#### Creating an Organization
### Data Models
```typescript
import { IdpState } from './idp.state.js';
See `ts_interfaces/data/` for all data structures:
export class OrganizationManager {
private idpState = IdpState.getSingletonInstance();
public async createOrganization(name: string, slug: string, jwt: string) {
const response = await this.idpState.idpClient.requests.createOrganization.fire({
jwt: jwt,
organizationName: name,
organizationSlug: slug,
action: 'manifest',
});
if (response.resultingOrganization) {
console.log(`Organization ${name} created successfully.`);
} else {
console.log(`Organization creation failed.`);
}
}
}
// Usage
const organizationManager = new OrganizationManager();
organizationManager.createOrganization('Dev Org', 'dev-org', '<JWT_TOKEN_HERE>');
```
### Managing JWTs
The `@idp.global/idp.global` package involves managing JSON Web Tokens (JWTs) for session handling and security.
#### Refreshing JWTs
```typescript
import { IdpClient } from './idp.client.js';
export const refreshJwt = async (client: IdpClient) => {
const currentJwt = await client.getJwt();
if (!currentJwt) return null;
const response = await client.requests.refreshJwt.fire({
refreshToken: currentJwt.data.refreshToken
});
if (response.jwt) {
await client.storeJwt(response.jwt);
console.log("JWT refreshed and stored.");
return response.jwt;
} else {
console.log("JWT refresh failed.");
return null;
}
};
// Usage
const idpClient = new IdpClient('https://reception.lossless.one/typedrequest');
refreshJwt(idpClient);
```
### Handling Authentication Tokens
Handling tokens (JWTs, refresh tokens, transfer tokens) securely is crucial for maintaining session integrity.
#### Exchanging Refresh Token for Transfer Token
```typescript
import { IdpClient } from './idp.client.js';
const getTransferToken = async (client: IdpClient) => {
const refreshToken = await client.getJwt().data.refreshToken;
const response = await client.requests.obtainOneTimeToken.fire({
refreshToken
});
if(response.transferToken) {
console.log("Obtained Transfer Token: ", response.transferToken);
return response.transferToken;
} else {
console.log("Failed to obtain Transfer Token.");
return null;
}
};
// Usage
const idpClient = new IdpClient('https://reception.lossless.one/typedrequest');
getTransferToken(idpClient);
```
This comprehensive guide should help you understand the detailed setup and usage of the `@idp.global/idp.global` module effectively.
- `IUser` - User profile and credentials
- `IOrganization` - Organization entity
- `IRole` - User roles within organizations
- `IJwt` - JWT token structure
- `IApp` - OAuth application definitions
- `IOidcAccessToken`, `IAuthorizationCode` - OIDC tokens
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.