@idp.global/idp.global the code that runs the idp.global platform readme.md for @idp.global/idp.global 🔐 A modern, open-source Identity Provider (IdP) SaaS platform for managing user authentication, registrations, sessions, and organization-based access control. 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. Issue Reporting and Security For reporting bugs, issues, or security vulnerabilities, please visit 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/ 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: # 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 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 Prerequisites Node.js 20+ pnpm MongoDB (local or remote) SMTP server (for email verification in registration flow) Getting Started # 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: export MONGODB_URL=mongodb://localhost:27017/idp-dev export IDP_BASEURL=http://localhost:2999 export INSTANCE_NAME=idp-dev Development Routes Route Description / Welcome/landing page /login Sign in form /register New user registration /account User dashboard (requires auth) 🔑 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 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 // 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: # Login idp login # Show current user idp whoami # List organizations idp orgs # List organization members idp members --org # Invite a user idp invite --org --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: { "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 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 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 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 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. changelog.md for @idp.global/idp.global 2026-01-29 - 1.16.0 - feat(dev) add local development docs, update tswatch preset and add Playwright screenshots readme.md: added a Local Development section with prerequisites, quick-start commands, environment variables, development routes, and default development credentials + security note npmextra.json: changed @git.zone/tswatch preset from "website" to "service" and disabled the built-in server (removed port/serveDir/liveReload and set server.enabled false); removed triggerReload from website watcher .playwright-mcp: added Playwright screenshots (login-page.png, register-page.png, account-dashboard.png) for visual tests / CI 2026-01-29 - 1.15.0 - feat(build) add tsbundle/tswatch configs, update build/watch scripts, bump dependencies, and add CLI documentation Add tsbundle and tswatch configuration to npmextra.json to support bundling and a local dev server (dist_serve, liveReload, watch patterns). Update package.json build/watch scripts to use generic tsbundle/tswatch invocations (removed explicit 'website' target). Bump dependencies and devDependencies: @git.zone/tsbuild ^4.0.2 -> ^4.1.2, @git.zone/tsbundle ^2.6.3 -> ^2.8.3, @git.zone/tswatch ^2.3.13 -> ^3.0.1, @api.global/typedserver ^8.1.0 -> ^8.3.0, several @design.estate packages, @push.rocks/taskbuffer ^3.5.0 -> ^4.1.1, @types/node 25.0.3 -> 25.1.0, and other minor/patch bumps. Add a new CLI README (ts_idpcli/readme.md) with usage, commands, programmatic API examples and configuration. Update README license/Legal sections in ts_idpclient, ts_interfaces and ts_web to include license, trademark, and company information. 2025-12-22 - 1.14.1 - fix(oidc) migrate OIDC endpoints and internal handlers to use typedserver IRequestContext and update dependencies Updated route handlers in ts/index.ts to pass ctx (IRequestContext) instead of req Refactored OIDC manager handlers to accept plugins.typedserver.IRequestContext and use ctx.url, ctx.headers, ctx.formData (handleAuthorize, handleToken, handleUserInfo, handleRevoke) Bumped dependencies to support the new typedserver API: @api.global/typedserver -> ^8.1.0 Other dependency updates: @design.estate/dees-catalog ^3.4.0, @git.zone/tspublish ^1.11.0, @types/node ^25.0.3 Changing public handler method signatures is a breaking API change; recommend a major version bump 2025-12-16 - 1.14.0 - feat(docs) add package READMEs and publish metadata; update web package publish order Add comprehensive README for ts_web (web components/UI) Add README for ts_idpclient (TypeScript client) Add README for ts_interfaces (type definitions/interfaces) Add tspublish.json for ts_idpcli (@idp.global/cli) and ts_idpclient (@idp.global/client) Update ts_web/tspublish.json order from 4 to 5 2025-12-15 - 1.13.0 - feat(oidc) feat(oidc): add OIDC provider (OidcManager, endpoints, and interfaces) Add OidcManager class implementing OpenID Connect / OAuth2 server functionality (authorization codes, access/refresh tokens, user consents, PKCE support, JWKS, ID token generation, token revocation, cleanup task). Expose OIDC endpoints on the website server: /.well-known/openid-configuration, /.well-known/jwks.json, /oauth/authorize, /oauth/token, /oauth/userinfo (GET/POST), and /oauth/revoke. Integrate OidcManager into Reception: add oidcManager property and instantiate it from ts/index.ts so routes can reference it. Add TypeScript interfaces for OIDC data structures (ts_interfaces/data/loint-reception.oidc.ts) and export them from the data index. 2025-12-15 - 1.12.1 - fix(dependencies) fix(deps): bump @uptime.link/webwidget to ^1.2.6 Updated dependency @uptime.link/webwidget from ^1.2.5 to ^1.2.6 in package.json No other files changed; this is a dependency patch update 2025-12-15 - 1.12.0 - feat(interfaces) Add JWT public-key and blocklist request interfaces, publish ordering files, and update dependencies Introduce IReq_GetPublicKeyForValidation and IReq_PushPublicKeyForValidation with documentation in ts_interfaces/request/loint-reception.jwt.ts to support fetching and pushing JWT public keys for validation. Clarify IReq_PushOrGetJwtIdBlocklist to describe both GET (client requests blocklist) and PUSH (server pushes revoked JWT IDs) directions and required client handlers. Add tspublish.json ordering files for packaging: ts_interfaces (order: 1), ts (order: 2), ts_idpclient (order: 3), ts_web (order: 4). Update package.json dependencies to include @git.zone/tspublish and additional @push.rocks packages (@push.rocks/smartcli, @push.rocks/smartfile, @push.rocks/smartinteract). 2025-12-14 - 1.11.0 - feat(idpcli) Add idp CLI (IdpCli) with commands, file-based credential storage, typed request APIs; bump deps and update config Introduce a new CLI implementation under ts_idpcli: IdpCli class, runCli entrypoint and multiple commands (login, login-token, logout, whoami, orgs, orgs-create, members, invite, sessions, revoke, admin-check, admin-apps, admin-suspend, etc.). Add plugins module that exports node built-ins and common libraries (smartcli, smartinteract, smartpromise, smartrx, typedrequest, typedsocket) for the CLI. Expose many typed request accessors in classes.idprequests (authentication, registration, user/org/member management, billing, JWT/key management, admin operations). Implement file-based credential storage (~/.idp-global/credentials.json) with load/store/delete helpers to persist refresh tokens and JWTs for the CLI. Update ts/index.ts to start the website server on port 2999 (was previously started without explicit port). Bump and add dependencies/devDependencies: @api.global/typedserver -> ^7.11.1, @design.estate/dees-catalog -> ^3.3.1, @push.rocks/smartjson -> ^6.0.0; add @push.rocks/smartcli, smartfile, smartinteract; upgrade @git.zone/tsbuild to ^4.0.2 and update tsrun/tswatch versions. Rework npmextra.json: reorganized npmci and tsdoc sections, added release configuration (registries and accessLevel) and other npmci/docker mapping entries. 2025-12-07 - 1.10.0 - feat(billingplan) Add Paddle v2 checkout support and backend config endpoint; add CSP headers and bump typedserver Add getPaddleConfig typedrequest handler in BillingPlanManager to expose PADDLE_TOKEN and PADDLE_PRICE_ID from environment. Introduce IReq_GetPaddleConfig typedrequest interface. Update frontend paddlesetup to use Paddle v2: load v2 script, call Paddle.Initialize with token, open Checkout using items.priceId and customer.email, and handle checkout.completed events (store transaction_id). Attempt to obtain user email from account state or via idpClient.whoIs before starting checkout; show error if email unavailable. Add Content Security Policy securityHeaders to website server configuration to allow Paddle, ProfitWell, Sentry and related assets/connections. Bump dependency @api.global/typedserver from ^7.8.17 to ^7.10.2. 2025-12-01 - 1.9.0 - feat(account) Refactor account UI: migrate modals to promise-based show() API and improve navigation URL tracking Replace inline modal elements with programmatic / static show() calls for OrgSelectModal and CreateOrgModal; navigation now reacts to the results returned from show() and pushes appropriate URLs. Remove embedded and elements from the account template to use on-demand modal invocation. Navigation component now exposes currentPath state, listens to popstate, and watches for external URL changes (requestAnimationFrame loop) to keep UI in sync with location changes. Updated readme.hints.md with guidance for dees-catalog components and clarified dees-input-* event pattern (use RxJS Subjects, subscribe to changeSubject and access element.value). 2025-12-01 - 1.8.0 - feat(reception) Add activity logging, session metadata and org-selection UI (backend and frontend) Introduce ActivityLog and ActivityLogManager to track user actions (TActivityAction, IActivityLog) for audit/display. Export new activity interface (IActivityLog) from ts_interfaces and add type TActivityAction. Wire ActivityLogManager into Reception so activity logging is available via the typed router. Enhance LoginSession data model with deviceInfo, createdAt and lastActive fields for richer session metadata. Add getUserSessions typed handler to return detailed session list (device, browser, os, ip, createdAt, lastActive, isCurrent). Revoke session endpoint now logs a 'session_revoked' activity when a session is revoked (and blocks revoking the current session). Add request interfaces IReq_GetUserSessions and IReq_GetUserActivity to typed request definitions. Frontend: account element now includes org-select and create-org modals, OrgView route, and handlers to open modals and navigate to new org/billing pages. Frontend: organization dropdown adds a '+ Create new...' option and wiring to open the creation modal. Minor refactors and routing exports: account index exports new modal components and views updated (OrgView). 2025-12-01 - 1.7.0 - feat(admin) Add global admin functionality: backend admin APIs, model fields and UI integration Backend: Add AppManager admin endpoints (getGlobalAppStats, create/update/delete/global apps, regenerate credentials) and checkGlobalAdmin handler; enforce admin checks via verifyGlobalAdmin Data models: Add createdAt and createdByUserId to global app data; add optional isGlobalAdmin flag to user data (IUser) Typed requests: Add new request definitions in loint-reception.admin.ts and export it from request index UI: Expose Global Admin entry in account navigation (isGlobalAdmin reactive state), add /admin subroute and AdminView export Account state: Fetch whoIs() on load to populate user information for admin checks App seeding: Seed global apps with createdAt and createdByUserId metadata Docs: Story index updated to include ADM-008 Manage Global Apps and adjust priority summary 2025-12-01 - 1.6.0 - feat(apps) Add Apps subsystem: App and AppConnection models, managers, typed request handlers, web UI routes and documentation Introduce App and AppConnection SmartData models (ts/reception/classes.app.ts, ts/reception/classes.appconnection.ts) Add AppManager and AppConnectionManager with typed handlers for getGlobalApps, getAppConnections and toggleAppConnection (ts/reception/classes.appmanager.ts, ts/reception/classes.appconnectionmanager.ts) Add request and data interfaces for apps and app connections (ts_interfaces/data/loint-reception.app.ts, ts_interfaces/data/loint-reception.appconnection.ts, ts_interfaces/request/loint-reception.app.ts) Seed default global apps and support OAuth credential shape (IOAuthCredentials) in app data Wire App managers into Reception (ts/reception/classes.reception.ts) and Reception startup Update idp client types to use legacy app shape where required (IAppLegacy) and adapt typed requests (ts_idpclient/*) Expose web UI routes and navigation for organization Apps view and export the AppsView (ts_web/elements/account/*, ts_web/elements/account/views/index.ts) Add registration of new stories for Apps feature (stories/*: ORG-009, ORG-010, ORG-011, DEV-008) and update story index Adjust typed request shapes for login/transfer flows to accept IAppLegacy where transfer/app data is exchanged 2025-12-01 - 1.5.0 - feat(account) Refactor account UI styles into reusable design tokens, apply updated styles across views and fix login submit behavior Introduce accountDesignTokens and split shared styles into tokens (accountDesignTokens), cardStyles and typographyStyles while keeping a legacy default export for compatibility Apply new design tokens to account components (content, baseview, subscriptions) and switch background to use CSS variable (--background) Small UI tweaks: smoother transition easing on view container, updated icon for organization entries and adjusted spacing Add placeholder sections for Upcoming Billable Items and Past Invoices in subscriptions view Fix login prompt submit handling by disabling the submit button via its #loginSubmitButton selector and improving button text logic 2025-04-03 - 1.4.3 - fix(website) Update packageManager configuration in package.json and refine view container background styling Add 'packageManager' field in package.json to pin pnpm version Adjust background style in ts_web/views/viewcontainer.ts for improved UI consistency 2024-12-11 - 1.5.0 - feat(UI) Added 'Learn more about idp.global' button Added a new button for learning more about idp.global in the welcome component 2024-12-11 - 1.5.0 - feat(UI) Added 'Learn more about idp.global' button Added a new button for learning more about idp.global in the welcome component 2024-10-12 - 1.4.2 - fix(UI) Improve text rendering in account navigation. Fix for text alignment in the commit info section of the account navigation. Adjusted font settings for better readability. 2024-10-07 - 1.4.1 - fix(core) Bug fixes and UI enhancements Updated packages to resolve compatibility issues. Optimized the transition animations for the center container. Improved the initialization logic for navigating between views. Enhanced UI with better organization selection handling. 2024-10-07 - 1.4.0 - feat(core) Refactored plugin and request handling to use 'idpInterfaces' Switched from using 'lointReception' to 'idpInterfaces' in various TypeScript sources. Updated references to request and data interfaces across multiple modules. Improved account handling with new navigation options. 2024-10-07 - 1.3.1 - fix(account) Fix: updated cleanupViews method to correctly iterate over children. Fixed the iteration over view container children by converting it to an array before removing children. This resolves potential errors due to incorrect for-loop execution on HTMLCollection. 2024-10-06 - 1.3.0 - feat(account) Implement account and organization management features Added account management UI with organization selection Introduced organization creation and selection functionalities Implemented subscription view with Paddle setup integration 2024-10-04 - 1.2.2 - fix(core) Update dependencies and refactor registration process Updated @design.estate/dees-catalog, @design.estate/dees-domtools, and @design.estate/dees-element dependencies to their latest versions. Refactored registration process to improve validation flow. Improved user interface for login and registration prompts. Fixed issues with email and token validation during registration. 2024-10-04 - 1.2.1 - fix(core) Added logging for user email login process and fixed client URL parsing Added info logging when loginWithEmail is requested and when a user is found. Ensured reception client parses the URL correctly in IdpClient and IdpRequests classes. Updated login process flow in idp-logincontainer and idp-loginprompt elements. Improved element loading mechanism with updated state management in viewcontainer. 2024-10-01 - 1.2.0 - feat(web) Improve UI styling and add registration prompt Updated max-width of login container to improve layout consistency Added new component for user registration Improved styling for various elements including buttons and text boxes 2024-10-01 - 1.1.1 - fix(core) Corrected typos and added missing keywords. Added missing newline at the end of package.json. Revised various typos and added missing keywords. 2024-09-29 - 1.1.0 - feat(web) Implement view container and update elements Add IdpViewcontainer element for managing views Update idp-welcome element to load IdpLogincontainer element Rename wg-loginprompt and wg-logincontainer to idp-login and idp-logincontainer Fix CSS styling and references in elements Re-add idp-registration-stepper element 2024-09-29 - 1.0.0 - Initial Release Project initialization and initial documentation setup. Added README Initial project setup