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

fix(docs): refresh module readmes and add repository license file

Browse Source
This commit is contained in:
Jürgen Kunz
2026-04-20 08:15:42 +00:00
parent 2d1e6ea6e1
commit 76efcb835f
10 changed files with 511 additions and 1286 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+136 -318
View File
@@ -1,168 +1,63 @@
# @idp.global/idp.global
🔐 **A modern, open-source Identity Provider (IdP) SaaS platform** for managing user authentication, registrations, sessions, and organization-based access control.
Identity infrastructure for apps that need accounts, sessions, organizations, invites, admin tooling, and OpenID Connect in one TypeScript codebase.
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.
This repository ships the `idp.global` server, the browser/client SDK, the CLI, shared request/data interfaces, and the web UI used by the hosted service.
## 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
## What It Does
### 🔑 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
- Runs an identity provider with MongoDB-backed users, sessions, roles, organizations, invitations, API tokens, and billing plans.
- Serves a web app for login, registration, account management, org management, billing flows, and global admin views.
- Exposes typed realtime APIs over `typedrequest` and `typedsocket`.
- Implements OIDC/OAuth endpoints including discovery, JWKS, authorization, token, userinfo, and revoke.
- Includes a reusable browser client and a terminal CLI for common account and org workflows.
### 🏢 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
## Monorepo Modules
### 🔗 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`
| Folder | Purpose |
| --- | --- |
| `ts/` | Backend service entrypoint and the core `Reception` managers |
| `ts_interfaces/` | Shared request and data contracts used by server, client, CLI, and UI |
| `ts_idpclient/` | Browser-focused SDK published as `@idp.global/client` |
| `ts_idpcli/` | CLI published as `@idp.global/cli` |
| `ts_web/` | Frontend bundle with login, registration, account, org, billing, and admin views |
### 💳 Billing Integration
- **Paddle Integration**: Built-in payment processing support
- **Billing Plans**: Flexible subscription management
- **Checkout Flows**: Streamlined payment experiences
## Core Backend Pieces
### 🎨 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
`Reception` wires the service together and starts these managers:
### 📡 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
- `JwtManager` for signing, refreshing, and validating JWTs.
- `LoginSessionManager` for login state and session lifecycle.
- `RegistrationSessionManager` for multi-step sign-up flows.
- `UserManager` for user lookups and account data.
- `OrganizationManager` for org creation and membership lookup.
- `RoleManager` for org roles and permissions.
- `UserInvitationManager` for invites, membership updates, and ownership transfer.
- `ApiTokenManager` for long-lived token auth.
- `BillingPlanManager` for Paddle-backed billing data.
- `AppManager` and `AppConnectionManager` for app connections and admin app stats.
- `ActivityLogManager` for audit-style activity entries.
- `OidcManager` for the OIDC/OAuth provider surface.
## 🏗️ 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
# 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
```
### Environment Variables
| 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 |
### Docker Compose Example
```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
mongo:
image: mongo:7
volumes:
- mongo-data:/data/db
volumes:
mongo-data:
```
The server listens on port 2999 by default.
## 🛠️ Local Development
## Quick Start
### Prerequisites
- Node.js 20+
- pnpm
- MongoDB (local or remote)
- SMTP server (for email verification in registration flow)
- `pnpm`
- MongoDB
### Getting Started
### Install
```bash
# Clone the repository
git clone https://code.foss.global/idp.global/idp.global.git
cd idp.global
# Install dependencies
pnpm install
# Build the project
pnpm build
# Start development server with hot reload
pnpm watch
```
The server runs on **http://localhost:2999** with:
- 🔄 Auto-restart backend on changes (`ts/`)
- 📦 Automatic frontend bundle rebuilding (`ts_web/`)
### Environment Setup
Create environment variables for the backend:
### Required Environment
```bash
export MONGODB_URL=mongodb://localhost:27017/idp-dev
@@ -170,207 +65,130 @@ export IDP_BASEURL=http://localhost:2999
export INSTANCE_NAME=idp-dev
```
### Development Routes
Optional:
| Route | Description |
|-------|-------------|
| `/` | Welcome/landing page |
| `/login` | Sign in form |
| `/register` | New user registration |
| `/account` | User dashboard (requires auth) |
- `SERVEZONE_PLATFROM_AUTHORIZATION`
- `PADDLE_TOKEN`
- `PADDLE_PRICE_ID`
### 🔑 Default Development Credentials
For local development with the test database, use:
| Field | Value |
|-------|-------|
| **Email/Username** | `admin@idp.global` or `admin` |
| **Password** | `admin` |
This account has `isGlobalAdmin: true` for full platform access including the admin panel at `/account/admin`.
> ⚠️ **Security Note**: These credentials are for local development only. Never use default credentials in production environments.
## 📦 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 { IdpClient } from '@idp.global/idpclient';
// Initialize the client
const idpClient = new IdpClient('https://idp.global');
// 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!');
}
// 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);
```
### Organization Management
```typescript
// Create a new organization
const result = await idpClient.createOrganization('My Company', 'my-company', 'manifest');
console.log('Created:', result.resultingOrganization);
// Invite members
await idpClient.requests.createInvitation.fire({
jwt: await idpClient.getJwt(),
organizationId: 'org-id',
email: 'newmember@example.com',
roles: ['member']
});
```
### CLI Tool
The `ts_idpcli` module provides a command-line interface:
### Build
```bash
pnpm build
```
### Run Locally
```bash
pnpm watch
```
This starts the backend from `ts/` and rebuilds the frontend bundle from `ts_web/`. The service listens on port `2999`.
## Runtime Surface
### Web Routes
| Route | Purpose |
| --- | --- |
| `/` | Welcome page |
| `/login` | Login flow |
| `/register` | Registration flow |
| `/finishregistration` | Multi-step registration completion |
| `/account` | Signed-in account area |
### OIDC and OAuth Endpoints
| Route | Purpose |
| --- | --- |
| `/.well-known/openid-configuration` | Discovery document |
| `/.well-known/jwks.json` | Public signing keys |
| `/oauth/authorize` | Authorization endpoint |
| `/oauth/token` | Token exchange |
| `/oauth/userinfo` | UserInfo endpoint |
| `/oauth/revoke` | Token revocation |
Supported scopes in the OIDC manager include `openid`, `profile`, `email`, `organizations`, and `roles`.
## SDK Example
The browser SDK lives in `ts_idpclient/` and is published as `@idp.global/client`.
```ts
import { IdpClient } from '@idp.global/client';
const idpClient = new IdpClient('https://idp.global');
await idpClient.enableTypedSocket();
const isLoggedIn = await idpClient.determineLoginStatus();
if (!isLoggedIn) {
const loginResult = await idpClient.requests.loginWithUserNameAndPassword.fire({
username: 'user@example.com',
password: 'secret',
});
if (loginResult.refreshToken) {
await idpClient.refreshJwt(loginResult.refreshToken);
}
}
const whoIs = await idpClient.whoIs();
console.log(whoIs.user.data.email);
```
## CLI Example
The terminal client lives in `ts_idpcli/` and is published as `@idp.global/cli`.
```bash
# Login
idp login
# Show current user
idp whoami
# 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
The CLI stores credentials in `~/.idp-global/credentials.json` and reads `IDP_URL` to override the target server.
idp.global implements a full OpenID Connect provider. Third-party applications can use it for SSO:
## Shared Interfaces
### Discovery Document
`ts_interfaces/` exports the type contracts shared across the stack:
```
GET /.well-known/openid-configuration
```
- `data/*` for users, orgs, roles, JWTs, sessions, devices, billing plans, apps, and OIDC payloads.
- `request/*` for auth, registration, user, org, invitation, app, admin, billing, and JWT request contracts.
- `tags/*` for shared tag exports.
### Authorization Flow
## Frontend
```
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
```
`ts_web/` is the web application bundle. It contains:
### Token Exchange
- Login and registration prompts.
- A registration stepper.
- Account navigation and account views.
- Organization creation and bulk invite modals.
- Billing and Paddle setup views.
- A global admin view.
```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
## Package Scripts
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
```
| Command | Purpose |
| --- | --- |
| `pnpm build` | Build TypeScript output and frontend bundle |
| `pnpm watch` | Run backend watch mode and frontend bundle watch |
| `pnpm test` | Build and run the test suite |
### UserInfo
## Repository Notes
```
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"]
}
```
## 🛠️ Tech Stack
- **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`
## 📚 API Reference
### Request Interfaces
All API requests are type-safe. See `ts_interfaces/request/` for the complete API:
- **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`
### Data Models
See `ts_interfaces/data/` for all data structures:
- `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
- Package manager: `pnpm`
- Main backend entrypoint: `ts/index.ts`
- Frontend entrypoint: `ts_web/index.ts`
- Browser SDK entrypoint: `ts_idpclient/index.ts`
- CLI entrypoint: `ts_idpcli/index.ts`
## License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
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.
@@ -382,7 +200,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
### Company Information
Task Venture Capital GmbH
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.