Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jkunz
|
1532c9704b | ||
|
jkunz
|
76efcb835f |
@@ -1,5 +1,12 @@
|
||||
# Changelog
|
||||
|
||||
## 2026-04-20 - 1.17.1 - fix(docs)
|
||||
refresh module readmes and add repository license file
|
||||
|
||||
- rewrite the root, backend, web, client, CLI, and interfaces README content to focus on current module responsibilities and usage
|
||||
- standardize README license references to the lowercase license file path
|
||||
- add the repository MIT license file
|
||||
|
||||
## 2026-04-20 - 1.17.0 - feat(auth)
|
||||
harden authentication with argon2 passwords and rotating hashed refresh tokens
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Task Venture Capital GmbH
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@idp.global/idp.global",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "An identity provider software managing user authentications, registrations, and sessions.",
|
||||
"main": "dist_ts/index.js",
|
||||
"typings": "dist_ts/index.d.ts",
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@idp.global/idp.global',
|
||||
version: '1.17.0',
|
||||
version: '1.17.1',
|
||||
description: 'An identity provider software managing user authentications, registrations, and sessions.'
|
||||
}
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
# `ts/` Backend Module
|
||||
|
||||
The `ts/` folder contains the server runtime for `idp.global`: startup, website server wiring, typed routes, OIDC endpoints, and the core `Reception` managers.
|
||||
|
||||
## 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 Lives Here
|
||||
|
||||
- `index.ts` boots the service, loads env vars, starts the website server, and mounts OIDC endpoints.
|
||||
- `reception/classes.reception.ts` creates the service container and initializes all managers.
|
||||
- `reception/` contains the domain logic for users, sessions, orgs, roles, invites, apps, billing, and OIDC.
|
||||
- `plugins.ts` centralizes external imports used by the backend.
|
||||
|
||||
## Startup Behavior
|
||||
|
||||
The backend startup in `ts/index.ts` does four main things:
|
||||
|
||||
1. Loads runtime configuration from `.nogit` and the working directory.
|
||||
2. Creates a `UtilityWebsiteServer` that serves the built frontend.
|
||||
3. Registers OIDC endpoints such as discovery, JWKS, authorize, token, userinfo, and revoke.
|
||||
4. Creates and starts `Reception`, then starts HTTP serving on port `2999`.
|
||||
|
||||
## 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`
|
||||
|
||||
## Key Managers
|
||||
|
||||
| Class | Responsibility |
|
||||
| --- | --- |
|
||||
| `JwtManager` | JWT issuance, validation, and key rotation support |
|
||||
| `LoginSessionManager` | Session creation, refresh, logout, and session metadata |
|
||||
| `RegistrationSessionManager` | Registration flow state |
|
||||
| `UserManager` | User-centric queries and mutations |
|
||||
| `OrganizationManager` | Organization creation and access checks |
|
||||
| `RoleManager` | Role and permission management |
|
||||
| `UserInvitationManager` | Invitations, member updates, and ownership transfer |
|
||||
| `BillingPlanManager` | Billing plan state and Paddle config endpoint |
|
||||
| `AppManager` | Global app administration |
|
||||
| `AppConnectionManager` | App connection tracking |
|
||||
| `ActivityLogManager` | User activity logging |
|
||||
| `OidcManager` | OIDC discovery, auth code flow, token exchange, userinfo, revoke |
|
||||
|
||||
## Local Development
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm watch
|
||||
```
|
||||
|
||||
The watch setup runs the backend from `ts/` and rebuilds the frontend bundle from `ts_web/`.
|
||||
|
||||
## 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.
|
||||
+48
-132
@@ -1,181 +1,97 @@
|
||||
# @idp.global/cli
|
||||
|
||||
Command-line interface for interacting with the idp.global Identity Provider. A Node.js CLI tool that provides authentication, user management, and organization administration from the terminal.
|
||||
Terminal client for `idp.global`.
|
||||
|
||||
## Overview
|
||||
It wraps the same typed backend used by the web app and SDK, but stores credentials on disk so you can inspect accounts, sessions, orgs, and admin state from the shell.
|
||||
|
||||
The IdpCli module provides a complete command-line interface for managing your idp.global account and organizations. It uses file-based credential storage and WebSocket connections for real-time communication with the IdP server.
|
||||
## Issue Reporting and Security
|
||||
|
||||
## Installation
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install -g @idp.global/cli
|
||||
# or
|
||||
pnpm add -g @idp.global/cli
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Login with email and password
|
||||
idp login
|
||||
|
||||
# Check current user
|
||||
idp whoami
|
||||
|
||||
# List your organizations
|
||||
idp orgs
|
||||
|
||||
# Logout
|
||||
idp logout
|
||||
idp sessions
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Authentication
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp login` | Interactive login with email and password |
|
||||
| `idp login-token` | Login with an API token |
|
||||
| `idp logout` | Clear stored credentials and end session |
|
||||
|
||||
### User Information
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp whoami` | Display current user information |
|
||||
| `idp sessions` | List all active sessions |
|
||||
| `idp revoke --session <id>` | Revoke a specific session |
|
||||
|
||||
### Organization Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp orgs` | List all organizations you belong to |
|
||||
| `idp orgs-create` | Create a new organization (interactive) |
|
||||
| `idp members --org <id>` | List members of an organization |
|
||||
| `idp invite --org <id> --email <email>` | Invite a user to an organization |
|
||||
|
||||
### Admin Commands (Global Admins Only)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp admin-check` | Check if you are a global admin |
|
||||
| `idp admin-apps` | List all global apps with connection stats |
|
||||
| `idp admin-suspend --user <id>` | Suspend a user account |
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `idp login` | Prompt for email and password |
|
||||
| `idp login-token` | Prompt for an API token |
|
||||
| `idp logout` | Remove local credentials and try server-side logout |
|
||||
| `idp whoami` | Print the current user |
|
||||
| `idp sessions` | List active sessions |
|
||||
| `idp revoke --session <session-id>` | Revoke a session |
|
||||
| `idp orgs` | List organizations for the current user |
|
||||
| `idp orgs-create` | Interactively create an organization |
|
||||
| `idp members --org <org-id>` | List members for an organization |
|
||||
| `idp invite --org <org-id> --email user@example.com` | Invite a member |
|
||||
| `idp admin-check` | Check global admin status |
|
||||
| `idp admin-apps` | List global app stats |
|
||||
| `idp admin-suspend --user <user-id>` | Suspend a user |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
The CLI reads `IDP_URL` and defaults to `https://idp.global`.
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `IDP_URL` | Override the IdP server URL | `https://idp.global` |
|
||||
```bash
|
||||
IDP_URL=http://localhost:2999 idp whoami
|
||||
```
|
||||
|
||||
### Credential Storage
|
||||
Credentials are stored in:
|
||||
|
||||
Credentials are stored in `~/.idp-global/credentials.json`. This file contains your refresh token and JWT for persistent authentication across CLI sessions.
|
||||
```text
|
||||
~/.idp-global/credentials.json
|
||||
```
|
||||
|
||||
## Programmatic Usage
|
||||
|
||||
You can also use the IdpCli class programmatically:
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import { IdpCli } from '@idp.global/cli';
|
||||
|
||||
const cli = new IdpCli({
|
||||
idpBaseUrl: 'https://idp.global',
|
||||
configDir: '/custom/config/path', // optional
|
||||
idpBaseUrl: 'http://localhost:2999',
|
||||
});
|
||||
|
||||
// Login
|
||||
await cli.loginWithPassword('user@example.com', 'password');
|
||||
await cli.loginWithPassword('user@example.com', 'secret');
|
||||
|
||||
// Get current user
|
||||
const user = await cli.whoami();
|
||||
console.log('Logged in as:', user.data.name);
|
||||
const me = await cli.whoami();
|
||||
const orgs = await cli.getOrganizations();
|
||||
|
||||
// Get organizations
|
||||
const { organizations, roles } = await cli.getOrganizations();
|
||||
for (const org of organizations) {
|
||||
console.log(`- ${org.data.name} (${org.id})`);
|
||||
}
|
||||
console.log(me?.data?.email);
|
||||
console.log(orgs?.organizations.length);
|
||||
|
||||
// Disconnect when done
|
||||
await cli.disconnect();
|
||||
```
|
||||
|
||||
### IdpCli Class Methods
|
||||
## What The Class Exposes
|
||||
|
||||
**Authentication:**
|
||||
- `loginWithPassword(email, password)` - Login with credentials
|
||||
- `loginWithApiToken(token)` - Login with API token
|
||||
- `refreshJwt()` - Refresh the current JWT
|
||||
- `logout()` - Clear credentials and end session
|
||||
- `loginWithPassword()` and `loginWithApiToken()`
|
||||
- `refreshJwt()` and `logout()`
|
||||
- `whoami()`, `getSessions()`, and `revokeSession()`
|
||||
- `getOrganizations()`, `createOrganization()`, `getOrgMembers()`, and `inviteMember()`
|
||||
- `checkGlobalAdmin()`, `getGlobalAppStats()`, and `suspendUser()`
|
||||
|
||||
**User:**
|
||||
- `whoami()` - Get current user info
|
||||
- `getSessions()` - Get active sessions
|
||||
- `revokeSession(sessionId)` - Revoke a session
|
||||
## Implementation Notes
|
||||
|
||||
**Organizations:**
|
||||
- `getOrganizations()` - List user's organizations
|
||||
- `createOrganization(name, slug, mode)` - Create new organization
|
||||
- `getOrgMembers(orgId)` - Get organization members
|
||||
- `inviteMember(orgId, email, roles)` - Invite a user
|
||||
|
||||
**Admin:**
|
||||
- `checkGlobalAdmin()` - Check admin status
|
||||
- `getGlobalAppStats()` - Get app statistics
|
||||
- `suspendUser(userId)` - Suspend a user
|
||||
|
||||
## Examples
|
||||
|
||||
### Create an Organization
|
||||
|
||||
```bash
|
||||
$ idp orgs-create
|
||||
Organization Name: My Company
|
||||
Organization Slug: my-company
|
||||
|
||||
Organization created successfully!
|
||||
ID: org_abc123
|
||||
Name: My Company
|
||||
```
|
||||
|
||||
### Invite Team Members
|
||||
|
||||
```bash
|
||||
$ idp invite --org org_abc123 --email colleague@example.com
|
||||
Invitation sent to colleague@example.com
|
||||
```
|
||||
|
||||
### View Active Sessions
|
||||
|
||||
```bash
|
||||
$ idp sessions
|
||||
|
||||
Active Sessions:
|
||||
- sess_xyz789
|
||||
Device: MacBook Pro
|
||||
Browser: Chrome
|
||||
OS: macOS
|
||||
Last Active: 1/29/2025, 2:30:00 PM
|
||||
Current: Yes
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@api.global/typedrequest` - Type-safe API requests
|
||||
- `@api.global/typedsocket` - WebSocket communication
|
||||
- `@push.rocks/smartcli` - CLI framework
|
||||
- `@push.rocks/smartinteract` - Interactive prompts
|
||||
- `@idp.global/interfaces` - TypeScript interfaces
|
||||
- The CLI connects to the backend websocket surface at `/typedrequest`.
|
||||
- It uses file-based credentials instead of browser storage.
|
||||
- `orgs-create` first checks availability, then creates the organization.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
+77
-310
@@ -1,71 +1,61 @@
|
||||
# @idp.global/idpclient
|
||||
# @idp.global/client
|
||||
|
||||
A TypeScript client library for integrating with the idp.global Identity Provider. Works in both browser and Node.js environments.
|
||||
Browser-facing TypeScript client for talking to an `idp.global` server over `typedrequest` and `typedsocket`.
|
||||
|
||||
## Overview
|
||||
It handles login state, refresh tokens, JWT housekeeping, cross-app transfer tokens, and direct access to the typed request surface.
|
||||
|
||||
The IdpClient provides a complete API for authentication, session management, and organization operations. It uses WebSocket connections via TypedSocket for real-time, type-safe communication with the IdP server.
|
||||
## Issue Reporting and Security
|
||||
|
||||
## Installation
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @idp.global/idpclient
|
||||
# or
|
||||
pnpm add @idp.global/idpclient
|
||||
pnpm add @idp.global/client
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { IdpClient } from '@idp.global/idpclient';
|
||||
```ts
|
||||
import { IdpClient } from '@idp.global/client';
|
||||
|
||||
// Initialize the client
|
||||
const idpClient = new IdpClient('https://idp.global');
|
||||
|
||||
// Enable WebSocket connection
|
||||
await idpClient.enableTypedSocket();
|
||||
|
||||
// Check login status
|
||||
const isLoggedIn = await idpClient.determineLoginStatus();
|
||||
const loggedIn = await idpClient.determineLoginStatus();
|
||||
|
||||
if (isLoggedIn) {
|
||||
const userInfo = await idpClient.whoIs();
|
||||
console.log('Logged in as:', userInfo.user.data.name);
|
||||
}
|
||||
```
|
||||
|
||||
## Core Features
|
||||
|
||||
### Authentication
|
||||
|
||||
#### Password Login
|
||||
|
||||
```typescript
|
||||
const response = await idpClient.requests.loginWithUserNameAndPassword.fire({
|
||||
if (!loggedIn) {
|
||||
const loginResult = await idpClient.requests.loginWithUserNameAndPassword.fire({
|
||||
username: 'user@example.com',
|
||||
password: 'securepassword',
|
||||
});
|
||||
password: 'secret',
|
||||
});
|
||||
|
||||
if (response.refreshToken) {
|
||||
await idpClient.refreshJwt(response.refreshToken);
|
||||
console.log('Login successful!');
|
||||
} else if (response.twoFaNeeded) {
|
||||
console.log('2FA verification required');
|
||||
if (loginResult.refreshToken) {
|
||||
await idpClient.refreshJwt(loginResult.refreshToken);
|
||||
}
|
||||
}
|
||||
|
||||
const whoIs = await idpClient.whoIs();
|
||||
console.log(whoIs.user.data.email);
|
||||
```
|
||||
|
||||
#### Magic Link Login
|
||||
## What The Client Handles
|
||||
|
||||
```typescript
|
||||
// Request magic link
|
||||
await idpClient.requests.loginWithEmail.fire({
|
||||
email: 'user@example.com',
|
||||
});
|
||||
- Normalizes the base URL to the server's `/typedrequest` endpoint.
|
||||
- Stores JWT and refresh token state in a browser `WebStore`.
|
||||
- Refreshes expiring JWTs via `performJwtHousekeeping()`.
|
||||
- Redirects to `/login` when `determineLoginStatus(true)` is used.
|
||||
- Exchanges refresh tokens for cross-app transfer tokens.
|
||||
- Exposes the low-level typed requests through `idpClient.requests`.
|
||||
|
||||
// After clicking the email link
|
||||
const result = await idpClient.requests.loginWithEmailAfterToken.fire({
|
||||
email: 'user@example.com',
|
||||
token: 'token-from-email-link',
|
||||
## Common Flows
|
||||
|
||||
### Password Login
|
||||
|
||||
```ts
|
||||
const result = await idpClient.requests.loginWithUserNameAndPassword.fire({
|
||||
username: 'user@example.com',
|
||||
password: 'secret',
|
||||
});
|
||||
|
||||
if (result.refreshToken) {
|
||||
@@ -73,303 +63,80 @@ if (result.refreshToken) {
|
||||
}
|
||||
```
|
||||
|
||||
#### API Token Login
|
||||
### Magic Link Login
|
||||
|
||||
```typescript
|
||||
const result = await idpClient.requests.loginWithApiToken.fire({
|
||||
apiToken: 'your-api-token',
|
||||
```ts
|
||||
await idpClient.requests.loginWithEmail.fire({
|
||||
email: 'user@example.com',
|
||||
});
|
||||
|
||||
if (result.jwt) {
|
||||
await idpClient.setJwt(result.jwt);
|
||||
}
|
||||
const result = await idpClient.requests.loginWithEmailAfterToken.fire({
|
||||
email: 'user@example.com',
|
||||
token: 'token-from-email',
|
||||
});
|
||||
|
||||
await idpClient.refreshJwt(result.refreshToken);
|
||||
```
|
||||
|
||||
### Session Management
|
||||
### Session and Identity
|
||||
|
||||
```typescript
|
||||
// Get current JWT
|
||||
const jwt = await idpClient.getJwt();
|
||||
|
||||
// Get parsed JWT data
|
||||
const jwtData = await idpClient.getJwtData();
|
||||
console.log('User ID:', jwtData.id);
|
||||
|
||||
// Refresh JWT (automatic housekeeping)
|
||||
```ts
|
||||
await idpClient.performJwtHousekeeping();
|
||||
|
||||
// Manual refresh
|
||||
await idpClient.refreshJwt();
|
||||
const jwt = await idpClient.getJwt();
|
||||
const jwtData = await idpClient.getJwtData();
|
||||
const whoIs = await idpClient.whoIs();
|
||||
|
||||
// Logout
|
||||
await idpClient.logout();
|
||||
console.log(jwtData.id, whoIs.user.data.username);
|
||||
```
|
||||
|
||||
### User Information
|
||||
### Organizations
|
||||
|
||||
```typescript
|
||||
// Get current user details
|
||||
const whoIsResponse = await idpClient.whoIs();
|
||||
console.log('Name:', whoIsResponse.user.data.name);
|
||||
console.log('Email:', whoIsResponse.user.data.email);
|
||||
```ts
|
||||
const rolesAndOrganizations = await idpClient.getRolesAndOrganizations();
|
||||
|
||||
// Get user data
|
||||
const userData = await idpClient.requests.getUserData.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
userId: jwtData.id,
|
||||
});
|
||||
|
||||
// Update user data
|
||||
await idpClient.requests.setUserData.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
userId: jwtData.id,
|
||||
name: 'New Name',
|
||||
});
|
||||
```
|
||||
|
||||
### Organization Management
|
||||
|
||||
```typescript
|
||||
// Get user's organizations and roles
|
||||
const orgsAndRoles = await idpClient.getRolesAndOrganizations();
|
||||
console.log('Organizations:', orgsAndRoles.organizations);
|
||||
console.log('Roles:', orgsAndRoles.roles);
|
||||
|
||||
// Create a new organization
|
||||
const result = await idpClient.createOrganization(
|
||||
'My Company', // name
|
||||
'my-company', // slug
|
||||
'manifest' // mode: 'checkAvailability' or 'manifest'
|
||||
const created = await idpClient.createOrganization(
|
||||
'Acme',
|
||||
'acme',
|
||||
'manifest'
|
||||
);
|
||||
|
||||
if (result.resultingOrganization) {
|
||||
console.log('Created:', result.resultingOrganization.id);
|
||||
}
|
||||
|
||||
// Get organization details
|
||||
const orgDetails = await idpClient.requests.getOrganizationById.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
});
|
||||
```
|
||||
|
||||
### Member & Invitation Management
|
||||
|
||||
```typescript
|
||||
// Get organization members
|
||||
const members = await idpClient.requests.getOrgMembers.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
});
|
||||
|
||||
// Invite a new member
|
||||
await idpClient.requests.createInvitation.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
email: 'newmember@example.com',
|
||||
roles: ['member'],
|
||||
});
|
||||
|
||||
// Bulk invite members
|
||||
await idpClient.requests.bulkCreateInvitations.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
invitations: [
|
||||
{ email: 'user1@example.com', roles: ['member'] },
|
||||
{ email: 'user2@example.com', roles: ['admin'] },
|
||||
],
|
||||
});
|
||||
|
||||
// Accept an invitation
|
||||
await idpClient.requests.acceptInvitation.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
invitationToken: 'token-from-invite-email',
|
||||
});
|
||||
|
||||
// Remove a member
|
||||
await idpClient.requests.removeMember.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
userId: 'user-id',
|
||||
});
|
||||
|
||||
// Transfer ownership
|
||||
await idpClient.requests.transferOwnership.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
newOwnerId: 'new-owner-user-id',
|
||||
organizationId: created.resultingOrganization.id,
|
||||
});
|
||||
```
|
||||
|
||||
### Password Management
|
||||
### Cross-App Transfer
|
||||
|
||||
```typescript
|
||||
// Request password reset
|
||||
await idpClient.requests.resetPassword.fire({
|
||||
email: 'user@example.com',
|
||||
});
|
||||
|
||||
// Set new password (with token from email)
|
||||
await idpClient.requests.setNewPassword.fire({
|
||||
email: 'user@example.com',
|
||||
tokenArg: 'reset-token',
|
||||
newPassword: 'newsecurepassword',
|
||||
});
|
||||
|
||||
// Change password (when logged in)
|
||||
await idpClient.requests.setNewPassword.fire({
|
||||
email: 'user@example.com',
|
||||
oldPassword: 'currentpassword',
|
||||
newPassword: 'newsecurepassword',
|
||||
});
|
||||
```
|
||||
|
||||
### Session & Device Management
|
||||
|
||||
```typescript
|
||||
// Get active sessions
|
||||
const sessions = await idpClient.requests.getUserSessions.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
userId: jwtData.id,
|
||||
});
|
||||
|
||||
// Revoke a session
|
||||
await idpClient.requests.revokeSession.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
sessionId: 'session-id',
|
||||
});
|
||||
|
||||
// Get device ID
|
||||
const deviceInfo = await idpClient.requests.obtainDeviceId.fire({});
|
||||
|
||||
// Attach device to session
|
||||
await idpClient.requests.attachDeviceId.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
deviceId: deviceInfo.deviceId.id,
|
||||
});
|
||||
```
|
||||
|
||||
### Cross-Domain Authentication
|
||||
|
||||
```typescript
|
||||
// Get transfer token for SSO between apps
|
||||
```ts
|
||||
const transferToken = await idpClient.getTransferToken();
|
||||
|
||||
// Switch to another app with authentication
|
||||
await idpClient.getTransferTokenAndSwitchToLocation('https://app.example.com/');
|
||||
|
||||
// Process incoming transfer token (in target app)
|
||||
const success = await idpClient.processTransferToken();
|
||||
if (success) {
|
||||
console.log('Cross-domain login successful');
|
||||
}
|
||||
```
|
||||
|
||||
### Billing Integration
|
||||
## Typed Request Surface
|
||||
|
||||
```typescript
|
||||
// Get billing plan for an organization
|
||||
const billingPlan = await idpClient.requests.getBillingPlan.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
organizationId: 'org-id',
|
||||
});
|
||||
`IdpRequests` exposes typed request getters for:
|
||||
|
||||
// Get Paddle configuration
|
||||
const paddleConfig = await idpClient.requests.getPaddleConfig.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
});
|
||||
- authentication
|
||||
- registration
|
||||
- user/session queries
|
||||
- org and invitation management
|
||||
- billing requests
|
||||
- JWT validation key requests
|
||||
- admin requests
|
||||
|
||||
// Update payment method
|
||||
await idpClient.updatePaddleCheckoutId('org-id', 'checkout-id');
|
||||
```
|
||||
Use these when you want full control instead of the higher-level helper methods on `IdpClient`.
|
||||
|
||||
### Admin Operations (Global Admins Only)
|
||||
## Important Runtime Notes
|
||||
|
||||
```typescript
|
||||
// Check if user is global admin
|
||||
const isAdmin = await idpClient.requests.checkGlobalAdmin.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
});
|
||||
|
||||
// Get platform statistics
|
||||
const stats = await idpClient.requests.getGlobalAppStats.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
});
|
||||
|
||||
// Create a global app
|
||||
await idpClient.requests.createGlobalApp.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
name: 'My App',
|
||||
description: 'App description',
|
||||
});
|
||||
|
||||
// Suspend a user
|
||||
await idpClient.requests.suspendUser.fire({
|
||||
jwt: await idpClient.getJwt(),
|
||||
userId: 'user-id',
|
||||
});
|
||||
```
|
||||
|
||||
## Reactive Subscriptions
|
||||
|
||||
The client provides RxJS subjects for reactive updates:
|
||||
|
||||
```typescript
|
||||
// Subscribe to login status changes
|
||||
idpClient.statusObservable.subscribe((status) => {
|
||||
console.log('Login status changed:', status);
|
||||
});
|
||||
|
||||
// Subscribe to roles updates
|
||||
idpClient.rolesReplaySubject.subscribe((roles) => {
|
||||
console.log('Roles updated:', roles);
|
||||
});
|
||||
|
||||
// Subscribe to organizations updates
|
||||
idpClient.organizationsReplaySubject.subscribe((orgs) => {
|
||||
console.log('Organizations updated:', orgs);
|
||||
});
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### IdpClient Class
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `enableTypedSocket()` | Initialize WebSocket connection |
|
||||
| `determineLoginStatus(requireLogin?)` | Check if user is logged in |
|
||||
| `getJwt()` | Get stored JWT string |
|
||||
| `getJwtData()` | Get parsed JWT data |
|
||||
| `setJwt(jwt)` | Store JWT |
|
||||
| `deleteJwt()` | Remove stored JWT |
|
||||
| `refreshJwt(refreshToken?)` | Refresh the JWT |
|
||||
| `performJwtHousekeeping()` | Auto-refresh JWT if needed |
|
||||
| `logout()` | End session and redirect |
|
||||
| `whoIs()` | Get current user info |
|
||||
| `getRolesAndOrganizations()` | Get user's orgs and roles |
|
||||
| `createOrganization(name, slug, mode)` | Create new organization |
|
||||
| `getTransferToken(appData?)` | Get SSO transfer token |
|
||||
| `processTransferToken()` | Process incoming transfer token |
|
||||
| `stop()` | Close WebSocket connection |
|
||||
|
||||
### IdpRequests Class
|
||||
|
||||
Access via `idpClient.requests.*`:
|
||||
|
||||
**Authentication**: `loginWithUserNameAndPassword`, `loginWithEmail`, `loginWithEmailAfterToken`, `loginWithApiToken`, `resetPassword`, `setNewPassword`
|
||||
|
||||
**User**: `getUserData`, `setUserData`, `getUserSessions`, `revokeSession`, `getUserActivity`
|
||||
|
||||
**Organization**: `getOrganizationById`, `updateOrganization`, `createInvitation`, `bulkCreateInvitations`, `getOrgMembers`, `getOrgInvitations`, `acceptInvitation`, `cancelInvitation`, `resendInvitation`, `removeMember`, `updateMemberRoles`, `transferOwnership`
|
||||
|
||||
**Billing**: `getBillingPlan`, `getPaddleConfig`
|
||||
|
||||
**Admin**: `checkGlobalAdmin`, `getGlobalAppStats`, `createGlobalApp`, `updateGlobalApp`, `deleteGlobalApp`, `suspendUser`, `deleteSuspendedUser`
|
||||
- The default fallback `appData` uses `window.location`, so this package is primarily browser-oriented.
|
||||
- The client expects the backend `typedrequest` websocket surface to be reachable.
|
||||
- Auth state is persisted in browser storage under the `idpglobalStore` store name.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
+75
-276
@@ -1,315 +1,114 @@
|
||||
# @idp.global/interfaces
|
||||
|
||||
TypeScript interfaces and type definitions for the idp.global Identity Provider platform.
|
||||
Shared TypeScript contracts for the `idp.global` backend, browser client, CLI, and frontend.
|
||||
|
||||
## Overview
|
||||
Use this package when you want typed request/response payloads and shared data models for users, sessions, organizations, apps, billing, and OIDC.
|
||||
|
||||
This package provides the complete type system for idp.global, including data models, API request/response interfaces, and OIDC definitions. Use this package when building applications that integrate with idp.global or when you need type-safe interactions with the IdP API.
|
||||
## Issue Reporting and Security
|
||||
|
||||
## Installation
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @idp.global/interfaces
|
||||
# or
|
||||
pnpm add @idp.global/interfaces
|
||||
```
|
||||
|
||||
## Usage
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import { data, request, tags } from '@idp.global/interfaces';
|
||||
|
||||
// Data interfaces
|
||||
const user: data.IUser = {
|
||||
id: 'user_123',
|
||||
data: {
|
||||
name: 'John Doe',
|
||||
username: 'johndoe',
|
||||
email: 'john@example.com',
|
||||
status: 'active',
|
||||
connectedOrgs: ['org_1', 'org_2'],
|
||||
},
|
||||
const loginRequest: request.IReq_LoginWithEmailOrUsernameAndPassword['request'] = {
|
||||
username: 'user@example.com',
|
||||
password: 'secret',
|
||||
};
|
||||
|
||||
// Organization interface
|
||||
const org: data.IOrganization = {
|
||||
const organization: data.IOrganization = {
|
||||
id: 'org_1',
|
||||
data: {
|
||||
name: 'Acme Corp',
|
||||
name: 'Acme',
|
||||
slug: 'acme',
|
||||
billingPlanId: 'plan_free',
|
||||
roleIds: ['role_admin', 'role_member'],
|
||||
roleIds: [],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Package Structure
|
||||
## Exports
|
||||
|
||||
```
|
||||
ts_interfaces/
|
||||
├── data/ # Data model interfaces
|
||||
│ ├── loint-reception.user.ts # User profiles
|
||||
│ ├── loint-reception.organization.ts # Organizations
|
||||
│ ├── loint-reception.role.ts # RBAC roles
|
||||
│ ├── loint-reception.app.ts # OAuth applications
|
||||
│ ├── loint-reception.oidc.ts # OIDC tokens & flows
|
||||
│ ├── loint-reception.jwt.ts # JWT structures
|
||||
│ ├── loint-reception.loginsession.ts # Login sessions
|
||||
│ ├── loint-reception.billingplan.ts # Billing plans
|
||||
│ ├── loint-reception.device.ts # Device management
|
||||
│ ├── loint-reception.activity.ts # Activity logs
|
||||
│ ├── loint-reception.userinvitation.ts # Invitations
|
||||
│ └── loint-reception.appconnection.ts # App connections
|
||||
├── request/ # API request/response interfaces
|
||||
│ ├── loint-reception.login.ts # Authentication
|
||||
│ ├── loint-reception.registration.ts # User registration
|
||||
│ ├── loint-reception.user.ts # User management
|
||||
│ ├── loint-reception.organization.ts # Org management
|
||||
│ ├── loint-reception.jwt.ts # JWT operations
|
||||
│ ├── loint-reception.apitoken.ts # API tokens
|
||||
│ ├── loint-reception.app.ts # App management
|
||||
│ ├── loint-reception.billingplan.ts # Billing
|
||||
│ └── loint-reception.admin.ts # Admin operations
|
||||
└── tags/ # Tag definitions
|
||||
### `data`
|
||||
|
||||
The `data` export includes types for:
|
||||
|
||||
- users
|
||||
- organizations
|
||||
- roles
|
||||
- JWT payloads
|
||||
- login sessions
|
||||
- devices
|
||||
- activity logs
|
||||
- apps and app connections
|
||||
- billing plans and Paddle checkout data
|
||||
- OIDC data structures
|
||||
- invitations
|
||||
|
||||
### `request`
|
||||
|
||||
The `request` export includes typed request contracts for:
|
||||
|
||||
- login, logout, refresh, password reset, and device attachment
|
||||
- registration flow requests
|
||||
- user and session queries
|
||||
- organization CRUD-style requests
|
||||
- invitations and membership changes
|
||||
- app and admin actions
|
||||
- billing and JWT validation support
|
||||
|
||||
### `tags`
|
||||
|
||||
Shared tag exports live under `tags/`.
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `data/index.ts` | Re-exports all shared data interfaces |
|
||||
| `request/index.ts` | Re-exports all typed request contracts |
|
||||
| `tags/index.ts` | Re-exports shared tags |
|
||||
|
||||
## Examples
|
||||
|
||||
### Login Contract
|
||||
|
||||
```ts
|
||||
type TLogin = request.IReq_LoginWithEmailOrUsernameAndPassword;
|
||||
|
||||
const payload: TLogin['request'] = {
|
||||
username: 'user@example.com',
|
||||
password: 'secret',
|
||||
};
|
||||
```
|
||||
|
||||
## Data Interfaces
|
||||
### Session Contract
|
||||
|
||||
### User (`IUser`)
|
||||
|
||||
```typescript
|
||||
interface IUser {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
username: string;
|
||||
email: string;
|
||||
mobileNumber?: string;
|
||||
password?: string; // Only during initial setting
|
||||
passwordHash?: string; // For validation
|
||||
status: 'new' | 'active' | 'deleted' | 'suspended';
|
||||
connectedOrgs: string[]; // Organization IDs
|
||||
isGlobalAdmin?: boolean; // Platform admin flag
|
||||
};
|
||||
}
|
||||
```ts
|
||||
type TSessions = request.IReq_GetUserSessions['response']['sessions'];
|
||||
```
|
||||
|
||||
### Organization (`IOrganization`)
|
||||
### OIDC Contract
|
||||
|
||||
```typescript
|
||||
interface IOrganization {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
slug: string;
|
||||
billingPlanId: string;
|
||||
roleIds: string[];
|
||||
};
|
||||
}
|
||||
```ts
|
||||
type TUserInfo = data.IUserInfoResponse;
|
||||
```
|
||||
|
||||
### Role (`IRole`)
|
||||
## Scope
|
||||
|
||||
```typescript
|
||||
interface IRole {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
organizationId: string;
|
||||
userId: string;
|
||||
permissions: string[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth Application Types
|
||||
|
||||
```typescript
|
||||
// Global platform apps (maintained by platform admins)
|
||||
interface IGlobalApp {
|
||||
id: string;
|
||||
type: 'globalApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
iconBase64?: string;
|
||||
oauthCredentials?: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
|
||||
// Partner apps (third-party integrations)
|
||||
interface IPartnerApp {
|
||||
id: string;
|
||||
type: 'partnerApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
ownerOrganizationId: string;
|
||||
oauthCredentials?: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
|
||||
// Custom OIDC clients
|
||||
interface ICustomOidcApp {
|
||||
id: string;
|
||||
type: 'customOidcApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
ownerOrganizationId: string;
|
||||
oauthCredentials: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth Credentials
|
||||
|
||||
```typescript
|
||||
interface IOAuthCredentials {
|
||||
clientId: string;
|
||||
clientSecretHash: string;
|
||||
redirectUris: string[];
|
||||
scopes: string[];
|
||||
grantTypes: ('authorization_code' | 'refresh_token' | 'client_credentials')[];
|
||||
}
|
||||
```
|
||||
|
||||
## OIDC Interfaces
|
||||
|
||||
### Authorization Code
|
||||
|
||||
```typescript
|
||||
interface IAuthorizationCode {
|
||||
code: string;
|
||||
clientId: string;
|
||||
userId: string;
|
||||
scopes: string[];
|
||||
redirectUri: string;
|
||||
codeChallenge?: string;
|
||||
codeChallengeMethod?: 'S256';
|
||||
expiresAt: number;
|
||||
used: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Token Response
|
||||
|
||||
```typescript
|
||||
interface ITokenResponse {
|
||||
access_token: string;
|
||||
token_type: 'Bearer';
|
||||
expires_in: number;
|
||||
refresh_token?: string;
|
||||
id_token?: string;
|
||||
scope: string;
|
||||
}
|
||||
```
|
||||
|
||||
### UserInfo Response
|
||||
|
||||
```typescript
|
||||
interface IUserInfoResponse {
|
||||
sub: string;
|
||||
name?: string;
|
||||
preferred_username?: string;
|
||||
email?: string;
|
||||
email_verified?: boolean;
|
||||
organizations?: Array<{
|
||||
id: string;
|
||||
name: string;
|
||||
slug: string;
|
||||
roles: string[];
|
||||
}>;
|
||||
roles?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### ID Token Claims
|
||||
|
||||
```typescript
|
||||
interface IIdTokenClaims {
|
||||
iss: string; // Issuer
|
||||
sub: string; // Subject (user ID)
|
||||
aud: string; // Audience (client ID)
|
||||
exp: number; // Expiration time
|
||||
iat: number; // Issued at
|
||||
nonce?: string; // Replay protection
|
||||
name?: string;
|
||||
email?: string;
|
||||
email_verified?: boolean;
|
||||
organizations?: Array<{...}>;
|
||||
roles?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
## Request Interfaces
|
||||
|
||||
All API requests follow the TypedRequest pattern:
|
||||
|
||||
```typescript
|
||||
interface IReq_LoginWithEmailOrUsernameAndPassword {
|
||||
method: 'loginWithEmailOrUsernameAndPassword';
|
||||
request: {
|
||||
username: string;
|
||||
password: string;
|
||||
};
|
||||
response: {
|
||||
refreshToken?: string;
|
||||
twoFaNeeded: boolean;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Authentication Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_LoginWithEmailOrUsernameAndPassword` | `loginWithEmailOrUsernameAndPassword` | Password login |
|
||||
| `IReq_LoginWithEmail` | `loginWithEmail` | Magic link request |
|
||||
| `IReq_LoginWithEmailAfterEmailTokenAquired` | `loginWithEmailAfterEmailTokenAquired` | Magic link verification |
|
||||
| `IReq_LoginWithApiToken` | `loginWithApiToken` | API token login |
|
||||
| `IReq_RefreshJwt` | `refreshJwt` | Refresh access token |
|
||||
| `ILogoutRequest` | `logout` | End session |
|
||||
|
||||
### User Management Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetUserData` | `getUserData` | Get current user |
|
||||
| `IReq_SetUserData` | `setUserData` | Update user profile |
|
||||
| `IReq_GetUserSessions` | `getUserSessions` | List active sessions |
|
||||
| `IReq_ResetPassword` | `resetPassword` | Request password reset |
|
||||
| `IReq_SetNewPassword` | `setNewPassword` | Set new password |
|
||||
|
||||
### Organization Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_CreateOrganization` | `createOrganization` | Create new org |
|
||||
| `IReq_GetOrgMembers` | `getOrgMembers` | List org members |
|
||||
| `IReq_CreateInvitation` | `createInvitation` | Invite user |
|
||||
| `IReq_AcceptInvitation` | `acceptInvitation` | Accept invite |
|
||||
|
||||
### JWT Operations
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetPublicKeyForValidation` | `getPublicKeyForValidation` | Get JWT public key |
|
||||
| `IReq_GetJwtIdBlocklist` | `getJwtIdBlocklist` | Get revoked token IDs |
|
||||
|
||||
## Supported OIDC Scopes
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `openid` | Required for OIDC flows |
|
||||
| `profile` | User's name and username |
|
||||
| `email` | User's email address |
|
||||
| `organizations` | User's organization memberships |
|
||||
| `roles` | User's roles within organizations |
|
||||
This package is intentionally contract-only. It does not open sockets, store auth state, or perform HTTP/websocket communication by itself.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@idp.global/idp.global',
|
||||
version: '1.17.0',
|
||||
version: '1.17.1',
|
||||
description: 'An identity provider software managing user authentications, registrations, and sessions.'
|
||||
}
|
||||
|
||||
+54
-244
@@ -1,259 +1,69 @@
|
||||
# @idp.global/web
|
||||
# `ts_web/` Web App Module
|
||||
|
||||
Web Components and UI elements for the idp.global Identity Provider platform. Built with `@design.estate/dees-element` and the dees-catalog component library.
|
||||
The `ts_web/` folder contains the frontend for `idp.global`: login, registration, account management, org management, billing, and admin UI.
|
||||
|
||||
## Overview
|
||||
It is built with `@design.estate/dees-element`, `@design.estate/dees-domtools`, and the shared `idp.global` client and interface packages.
|
||||
|
||||
This package provides the complete web interface for idp.global, including authentication flows, account management, and organization administration. All components are built as Web Components using the Lit-based `dees-element` framework.
|
||||
## Issue Reporting and Security
|
||||
|
||||
## Installation
|
||||
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 Lives Here
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `index.ts` | Frontend entrypoint and initial render |
|
||||
| `views/viewcontainer.ts` | View switching for welcome, login, register, finishregistration, and account |
|
||||
| `elements/` | Web components for prompts, layout, and account UI |
|
||||
| `elements/account/views/` | Account subviews including org, apps, subscriptions, paddle setup, and admin |
|
||||
| `states/` | App-level and account-level state containers |
|
||||
|
||||
## UI Surface
|
||||
|
||||
The module currently includes:
|
||||
|
||||
- a welcome page
|
||||
- login and registration prompts
|
||||
- a multi-step registration flow
|
||||
- an account area with navigation
|
||||
- organization selection and creation flows
|
||||
- bulk member invitation UI
|
||||
- app and subscription views
|
||||
- a global admin view
|
||||
|
||||
## Routing
|
||||
|
||||
`IdpViewcontainer` switches between these frontend states:
|
||||
|
||||
| View | Route |
|
||||
| --- | --- |
|
||||
| `welcome` | `/` |
|
||||
| `login` | `/login` |
|
||||
| `register` | `/register` |
|
||||
| `finishregistration` | `/finishregistration` |
|
||||
| `account` | `/account` |
|
||||
|
||||
## Build And Run
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
npm install @idp.global/web
|
||||
# or
|
||||
pnpm add @idp.global/web
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
ts_web/
|
||||
├── index.ts # Application entry point
|
||||
├── plugins.ts # Plugin imports
|
||||
├── views/
|
||||
│ ├── viewcontainer.ts # Main view router
|
||||
│ └── index.ts
|
||||
├── elements/ # Web Components
|
||||
│ ├── idp-loginprompt.ts # Login form
|
||||
│ ├── idp-registerprompt.ts # Registration form
|
||||
│ ├── idp-registration-stepper.ts # Multi-step registration
|
||||
│ ├── idp-centercontainer.ts # Centered layout container
|
||||
│ ├── idp-transfermanager.ts # SSO transfer handling
|
||||
│ ├── idp-welcome.ts # Welcome/landing page
|
||||
│ └── account/ # Account dashboard components
|
||||
│ ├── content.ts # Main account layout
|
||||
│ ├── navigation.ts # Sidebar navigation
|
||||
│ ├── org-select-modal.ts # Organization switcher
|
||||
│ ├── create-org-modal.ts # Create organization dialog
|
||||
│ ├── bulk-invite-modal.ts # Bulk member invite dialog
|
||||
│ └── views/ # Account sub-views
|
||||
│ ├── baseview.ts # Base view class
|
||||
│ ├── usersview.ts # User profile view
|
||||
│ ├── orgview.ts # Organization details
|
||||
│ ├── orgsetup.ts # Organization setup
|
||||
│ ├── appsview.ts # Connected apps
|
||||
│ ├── adminview.ts # Global admin panel
|
||||
│ ├── subscriptions.ts # Billing subscriptions
|
||||
│ └── paddlesetup.ts # Payment setup
|
||||
└── states/
|
||||
├── idp.state.ts # Main application state
|
||||
└── accountstate.ts # Account dashboard state
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### Authentication Components
|
||||
|
||||
#### `<idp-loginprompt>`
|
||||
|
||||
Login form supporting password and magic link authentication.
|
||||
|
||||
```html
|
||||
<idp-loginprompt></idp-loginprompt>
|
||||
```
|
||||
|
||||
Features:
|
||||
- Email/username + password login
|
||||
- Magic link (passwordless) authentication
|
||||
- Automatic button text based on password presence
|
||||
- Form validation and error handling
|
||||
- Redirect to registration
|
||||
|
||||
#### `<idp-registerprompt>`
|
||||
|
||||
Initial registration form for new users.
|
||||
|
||||
```html
|
||||
<idp-registerprompt></idp-registerprompt>
|
||||
```
|
||||
|
||||
#### `<idp-registration-stepper>`
|
||||
|
||||
Multi-step registration wizard for completing user profile.
|
||||
|
||||
```html
|
||||
<idp-registration-stepper></idp-registration-stepper>
|
||||
```
|
||||
|
||||
Steps include:
|
||||
- Profile information
|
||||
- Email verification
|
||||
- Mobile verification (optional)
|
||||
- Password setup
|
||||
|
||||
### Layout Components
|
||||
|
||||
#### `<idp-viewcontainer>`
|
||||
|
||||
Main view container that handles routing between views.
|
||||
|
||||
```html
|
||||
<idp-viewcontainer></idp-viewcontainer>
|
||||
```
|
||||
|
||||
Supported views:
|
||||
- `welcome` - Landing page
|
||||
- `login` - Login form
|
||||
- `register` - Registration form
|
||||
- `finishregistration` - Registration stepper
|
||||
- `account` - Account dashboard
|
||||
|
||||
#### `<idp-centercontainer>`
|
||||
|
||||
Centered container with animation support for forms.
|
||||
|
||||
```html
|
||||
<idp-centercontainer>
|
||||
<h2>Your Content</h2>
|
||||
<form>...</form>
|
||||
</idp-centercontainer>
|
||||
```
|
||||
|
||||
Methods:
|
||||
- `show()` - Animate container into view
|
||||
- `hide()` - Animate container out of view
|
||||
|
||||
### Account Dashboard Components
|
||||
|
||||
#### `<idp-account-content>`
|
||||
|
||||
Main account dashboard layout with navigation.
|
||||
|
||||
```html
|
||||
<idp-account-content></idp-account-content>
|
||||
```
|
||||
|
||||
#### Navigation Views
|
||||
|
||||
| Component | Route | Description |
|
||||
|-----------|-------|-------------|
|
||||
| `<idp-usersview>` | `/account/users` | User profile management |
|
||||
| `<idp-orgview>` | `/account/org` | Organization details |
|
||||
| `<idp-orgsetup>` | `/account/orgsetup` | Organization configuration |
|
||||
| `<idp-appsview>` | `/account/apps` | Connected applications |
|
||||
| `<idp-adminview>` | `/account/admin` | Global admin panel |
|
||||
| `<idp-subscriptions>` | `/account/subscriptions` | Billing management |
|
||||
| `<idp-paddlesetup>` | `/account/paddle` | Payment method setup |
|
||||
|
||||
### Modal Components
|
||||
|
||||
#### `<idp-org-select-modal>`
|
||||
|
||||
Organization switcher modal for users with multiple organizations.
|
||||
|
||||
#### `<idp-create-org-modal>`
|
||||
|
||||
Dialog for creating new organizations with slug validation.
|
||||
|
||||
#### `<idp-bulk-invite-modal>`
|
||||
|
||||
Bulk invitation dialog for inviting multiple members at once.
|
||||
|
||||
## State Management
|
||||
|
||||
### IdpState
|
||||
|
||||
Central application state using `@push.rocks/smartstate`.
|
||||
|
||||
```typescript
|
||||
import { IdpState } from '@idp.global/web';
|
||||
|
||||
const idpState = await IdpState.getSingletonInstance();
|
||||
|
||||
// Access IdP client
|
||||
const isLoggedIn = await idpState.idpClient.determineLoginStatus();
|
||||
|
||||
// Access router
|
||||
idpState.domtools.router.pushUrl('/login');
|
||||
|
||||
// Subscribe to view changes
|
||||
idpState.mainStatePart.select(s => s.view).subscribe(view => {
|
||||
console.log('Current view:', view);
|
||||
});
|
||||
```
|
||||
|
||||
### AccountState
|
||||
|
||||
State for the account dashboard section.
|
||||
|
||||
```typescript
|
||||
import { AccountState } from '@idp.global/web';
|
||||
|
||||
const accountState = await AccountState.getSingletonInstance();
|
||||
|
||||
// Access current organization
|
||||
const currentOrg = accountState.currentOrganization;
|
||||
|
||||
// Access user roles
|
||||
const roles = accountState.userRoles;
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
Components use CSS custom properties for theming:
|
||||
|
||||
```css
|
||||
:host {
|
||||
--foreground: hsl(0 0% 98%);
|
||||
--muted-foreground: hsl(240 5% 64.9%);
|
||||
--background-accent: #303f9f;
|
||||
}
|
||||
```
|
||||
|
||||
All components include:
|
||||
- Dark mode by default
|
||||
- Geist Sans font family
|
||||
- Smooth animations
|
||||
- Responsive layouts
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@design.estate/dees-element` - Web Component base class
|
||||
- `@design.estate/dees-catalog` - UI component library
|
||||
- `@design.estate/dees-domtools` - DOM utilities and routing
|
||||
- `@idp.global/idpclient` - IdP client library
|
||||
- `@idp.global/interfaces` - TypeScript interfaces
|
||||
- `@push.rocks/smartstate` - State management
|
||||
- `@uptime.link/webwidget` - Status widget
|
||||
|
||||
## Views and Routes
|
||||
|
||||
| Route | View | Component |
|
||||
|-------|------|-----------|
|
||||
| `/` | `welcome` | `IdpWelcome` |
|
||||
| `/login` | `login` | `IdpLoginPrompt` |
|
||||
| `/register` | `register` | `IdpRegistrationPrompt` |
|
||||
| `/finishregistration` | `finishregistration` | `IdpRegistrationStepper` |
|
||||
| `/account` | `account` | `IdpAccountContent` |
|
||||
| `/logout` | - | Logout handler |
|
||||
|
||||
## Building
|
||||
|
||||
The web module is bundled using `@git.zone/tsbundle`:
|
||||
|
||||
```bash
|
||||
# Development with hot reload
|
||||
pnpm watch
|
||||
|
||||
# Production build
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm watch
|
||||
```
|
||||
|
||||
The bundled output is served from `dist_ts_web/` by the TypedServer.
|
||||
`pnpm watch` rebuilds the frontend bundle from `ts_web/index.ts` into `dist_serve/bundle.js` while the backend serves the app.
|
||||
|
||||
## Notes
|
||||
|
||||
- The app metadata in `ts_web/index.ts` identifies the site as `idp.global`.
|
||||
- The frontend uses the shared client package for auth state and backend communication.
|
||||
- Account-related UI is split into reusable elements plus state containers in `states/`.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user