app/readme.md

# @idp.global/idp.global

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, CLI, web UI, and tspublish submodules used by the hosted service. Shared public contracts live in `@idp.global/interfaces`; reusable browser/server SDK code lives in `@idp.global/sdk`.

## 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.
- 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_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` |
| `../sdk/` | Browser and server SDK published as `@idp.global/sdk` |

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

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

### Seed Development Data

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

## MFA And Passkeys

The reception backend supports real multi-factor authentication for account logins:

- TOTP enrollment with `startTotpEnrollment` and `finishTotpEnrollment`.
- Hashed one-time backup codes through `regenerateBackupCodes` and `verifyMfaChallenge`.
- WebAuthn passkey registration, revocation, passwordless login, and MFA step-up through the `startPasskey*` and `finishPasskey*` request pairs.
- Password and magic-link logins return `twoFaNeeded`, `mfaChallengeToken`, and `availableMfaMethods` instead of a refresh token when MFA is configured.

TOTP secrets are AES-GCM encrypted. Set `IDP_TOTP_ENCRYPTION_KEY` in production so encrypted credentials remain stable across deployments.

## SDK Example

Browser integrations should use the dedicated SDK browser entrypoint published by `@idp.global/sdk`.

```ts
import { IdpClient } from '@idp.global/sdk/browser';

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

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: `@idp.global/sdk/browser`
- 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.