app/readme.md

# @idp.global/idp.global

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

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.

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

## 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.
- `OidcManager` for the OIDC/OAuth provider surface.

## Quick Start

### Prerequisites

- Node.js 20+
- `pnpm`
- MongoDB

### Install

```bash
pnpm install
```

### Required Environment

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

Optional:

- `SERVEZONE_PLATFROM_AUTHORIZATION`
- `PADDLE_TOKEN`
- `PADDLE_PRICE_ID`

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

`ts_interfaces/` exports the type contracts shared across the stack:

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

## 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](./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.