Identity infrastructure for apps that need accounts, sessions, organizations, invites, admin tooling, mobile passport approvals, security alerts, and OpenID Connect in one TypeScript codebase.

This repository ships the idp.global server, browser SDK, CLI, web UI, and tspublish submodules used by the hosted service. Shared public contracts live in the sibling @idp.global/interfaces package.

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.

What It Does

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.
Supports passport-style mobile device enrollment, signed approval challenges, push registration, security alerts, and NFC/location-backed identity proof flows.
Includes a reusable browser client and a terminal CLI for common account and org workflows.

Monorepo Modules

Folder	Purpose
`ts/`	Backend service entrypoint and the core `Reception` managers
`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
`../interfaces/`	Shared request and data contracts published as `@idp.global/interfaces`

Core Backend Pieces

Reception wires the service together and starts these managers:

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.
AlertManager for passport alerts and organization/global alert rules.
AbuseProtectionManager for rate-limited sensitive flows such as OIDC token exchange.
PassportManager and PassportPushManager for trusted device enrollment, challenge approval, and push notification delivery.
OidcManager for the OIDC/OAuth provider surface.

Quick Start

Prerequisites

Node.js 20+
pnpm
MongoDB

Install

pnpm install

Required Environment

export MONGODB_URL=mongodb://localhost:27017/idp-dev
export IDP_BASEURL=http://localhost:2999
export INSTANCE_NAME=idp-dev

Optional:

SERVEZONE_PLATFORM_AUTHORIZATION
PADDLE_TOKEN
PADDLE_PRICE_ID

Build

pnpm build

Run Locally

pnpm watch

This starts the backend from ts/ and rebuilds the frontend bundle from ts_web/. The service listens on port 2999.

Seed Development Data

pnpm run seed

The seed command starts an interactive CLI that writes to the configured local database. The default demo workspace creates a global admin, an organization, demo users, and global OAuth app records.

Default development credentials if accepted unchanged:

Email: admin@idp.global
Password: idp.global

Runtime Surface

Web Routes

Route	Purpose
`/`	Welcome page
`/login`	Login flow
`/logout`	Logout flow
`/register`	Registration flow
`/finishregistration`	Multi-step registration completion
`/account`	Signed-in account area and account subroutes

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.

Passport And Mobile Approval Flow

PassportManager powers the trusted-device side of idp.global. A web session can create a passport enrollment challenge, the Swift app completes enrollment through a QR/NFC pairing payload, and later sign-in or identity checks can be approved by the paired device with signed challenge responses.

The typed request surface includes:

createPassportEnrollmentChallenge and completePassportEnrollment for pairing a trusted device.
getPassportDevices and revokePassportDevice for account-level device management.
createPassportChallenge, approvePassportChallenge, rejectPassportChallenge, and listPendingPassportChallenges for approval flows.
getPassportDashboard, listPassportAlerts, and markPassportAlertSeen for mobile app dashboards and notifications.
registerPassportPushToken for push delivery setup.

SDK Example

The browser SDK lives in ts_idpclient/ and is published as @idp.global/client.

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.

idp login
idp whoami
idp orgs
idp members --org <org-id>
idp invite --org <org-id> --email user@example.com

The CLI stores credentials in ~/.idp-global/credentials.json and reads IDP_URL to override the target server.

Shared Interfaces

The sibling @idp.global/interfaces package exports the type contracts shared across the stack:

data/* for users, orgs, roles, JWTs, sessions, devices, billing plans, apps, passport records, alerts, and OIDC payloads.
request/* for auth, registration, user, org, invitation, app, admin, billing, JWT, passport, alert, and OIDC request contracts.
tags/* for shared tag exports.

Frontend

ts_web/ is the web application bundle. It contains:

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.

Package Scripts

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

Repository Notes

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 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.

readme.md

@idp.global/idp.global