@idp.global/sdk

Reusable TypeScript SDK for building against idp.global from both sides of the wire: browser apps that need SSO, JWT housekeeping, transfer-token handoff, and typed IdP requests; and server apps that need explicit account storage, local password auth, and optional idp.global password verification.

The package is intentionally split by runtime. Use @idp.global/sdk/browser in browser bundles and @idp.global/sdk/server in Node.js services. The root @idp.global/sdk export does not expose application APIs.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What You Get

| Runtime | Import | What it does | | --- | --- | --- | | Browser | @idp.global/sdk/browser | SSO client, JWT and refresh-token storage, login redirects, logout, transfer-token exchange, and typed request shortcuts for user, organization, billing, OIDC, and admin flows. | | Server | @idp.global/sdk/server | Smartdata-backed account store, scrypt password hashing, local/idp.global account authentication, and a server-side typed-socket client for idp.global password login. |

Install

pnpm add @idp.global/sdk

This is an ESM TypeScript package. Published builds expose declaration files and runtime JavaScript through package exports.

Browser SDK

Import the browser client from the browser subpath:

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

Create one client per app shell. The receptionBaseUrl may be the SSO origin or the full typedrequest URL; the SDK normalizes it to /typedrequest internally.

const idp = new IdpClient('https://sso.workspace.global', {
  id: 'my-app',
  name: 'My App',
  description: 'The app your users actually want to open.',
  logoUrl: 'https://app.example.com/logo.svg',
  appUrl: 'https://app.example.com/',
});

await idp.enableTypedSocket();

const loggedIn = await idp.determineLoginStatus(true);
if (loggedIn) {
  const whoIsResult = await idp.whoIs();
  console.log(whoIsResult.user);
}

When determineLoginStatus(true) cannot recover a valid JWT from browser storage, a refresh token, or a transfertoken query parameter, it redirects the user to the configured idp.global login route with your app metadata encoded as appdata.

Token Handling

The browser client stores auth state in @push.rocks/webstore using the idpglobalStore store and main database.

| Method | Purpose | | --- | --- | | setJwt(jwt) / getJwt() / deleteJwt() | Manage the current JWT. | | setRefreshToken(token) / getRefreshToken() / deleteRefreshToken() | Manage the refresh token. | | clearAuthState() | Remove both JWT and refresh token. | | getJwtData() | Decode the current JWT through @push.rocks/webjwt. | | performJwtHousekeeping() | Refresh a JWT after its refreshFrom timestamp or recover from an expired JWT through the refresh token. | | refreshJwt(refreshToken?) | Exchange a refresh token for a fresh JWT and update stored auth state. | | checkJwtPresent() | Return whether a usable JWT can be found or refreshed. |

Login With Username And Password

The browser request wrappers are typed request factories. Call enableTypedSocket() before firing them.

await idp.enableTypedSocket();

const loginResponse = await idp.requests.loginWithUserNameAndPassword.fire({
  username: '[email protected]',
  password: 'correct horse battery staple',
});

if (loginResponse.twoFaNeeded) {
  throw new Error('Two-factor authentication is required for this account.');
}

if (loginResponse.refreshToken) {
  await idp.setRefreshToken(loginResponse.refreshToken);
  await idp.refreshJwt(loginResponse.refreshToken);
}

Transfer Tokens

Transfer tokens are the handoff mechanism for moving a logged-in user between apps without exposing refresh tokens to URLs.

const transferToken = await idp.getTransferToken();
if (transferToken) {
  const target = new URL('https://another-app.example.com/');
  target.searchParams.set('transfertoken', transferToken);
  window.location.href = target.toString();
}

On the receiving app, determineLoginStatus() calls processTransferToken() as part of its normal recovery flow. You can also call processTransferToken() directly when you own the route handling.

Logout

await idp.logout();

logout() clears local auth state and, when a refresh token is available on the SSO origin, asks idp.global to revoke the session before returning the user to the original app URL when app metadata is present.

Browser API Surface

| API | Description | | --- | --- | | new IdpClient(receptionBaseUrl, appData?) | Configure an idp.global browser client. | | enableTypedSocket() / stop() | Start or stop the typed-socket connection. | | determineLoginStatus(requireLogin?) | Resolve login state from JWT, refresh token, transfer token, or optional redirect. | | statusObservable | RxJS subject that emits idp.global login status changes during refresh flows. | | whoIs() | Resolve the current user through the active JWT. | | getRolesAndOrganizations() | Fetch roles and organizations for the current user. | | createOrganization(name, slug, mode) | Check organization slug availability or manifest an organization. | | updatePaddleCheckoutId(orgId, checkoutId) | Send a Paddle checkout ID as the org payment method update. | | getTransferToken(appData?) | Exchange the current refresh token for a transfer token. | | getTransferTokenAndSwitchToLocation(url) | Create a transfer token and redirect with transfertoken attached. | | processTransferToken() | Consume a transfertoken from the current URL and refresh local auth state. | | logout() | Revoke and clear the current login flow. |

Typed Request Shortcuts

idp.requests exposes typed request factories backed by @idp.global/interfaces. The request and response payload types come from that package, so your editor can guide exact payload shapes.

| Area | Request getters | | --- | --- | | Registration and login | firstRegistration, afterRegistrationEmailClicked, setData, mobileNumberVerification, finishRegistration, loginWithUserNameAndPassword, loginWithEmail, loginWithEmailAfterToken, loginWithApiToken, resetPassword, setNewPassword, obtainDeviceId, attachDeviceId | | Tokens and OIDC | obtainJwt, obtainOneTimeToken, prepareOidcAuthorization, completeOidcAuthorization | | User profile and sessions | getUserData, setUserData, getUserSessions, revokeSession, getUserActivity | | Organizations and members | getOrganizationById, updateOrganization, deleteOrganization, getOrgRoleDefinitions, upsertOrgRoleDefinition, deleteOrgRoleDefinition, createInvitation, getOrgInvitations, getOrgMembers, cancelInvitation, resendInvitation, removeMember, updateMemberRoles, transferOwnership, getInvitationByToken, acceptInvitation, bulkCreateInvitations, updateAppRoleMappings | | Billing and validation | getBillingPlan, getPaddleConfig, getPublicKeyForValidation, pushPublicKeyForValidation, pushOrGetJwtIdBlocklist | | Global administration | suspendUser, deleteSuspendedUser, checkGlobalAdmin, getGlobalAppStats, createGlobalApp, updateGlobalApp, deleteGlobalApp, regenerateAppCredentials |

Server SDK

Import server-side primitives from the server subpath:

import {
  AccountAuthService,
  IdpGlobalServerClient,
  SmartdataAccountStore,
} from '@idp.global/sdk/server';

The server SDK is deliberately explicit: it never auto-creates accounts during authentication. Your application decides when an account exists, which auth sources it may use, and whether it is an admin or user.

Smartdata Account Store

SmartdataAccountStore persists accounts through @push.rocks/smartdata and the exported IdpSdkAccountDoc collection.

import * as smartdata from '@push.rocks/smartdata';
import { SmartdataAccountStore } from '@idp.global/sdk/server';

const smartdataDb = new smartdata.SmartdataDb({
  mongoDbUrl: process.env.MONGODB_URL!,
  mongoDbName: 'my-app',
});
await smartdataDb.init();

const accountStore = new SmartdataAccountStore({ smartdataDb });

if (!(await accountStore.hasActiveAdminAccount())) {
  await accountStore.createAccount({
    email: '[email protected]',
    name: 'Admin User',
    role: 'admin',
    authSources: ['local'],
    password: process.env.INITIAL_ADMIN_PASSWORD!,
  });
}

Account emails are trimmed and normalized to lowercase for lookups. Local passwords are hashed with Node.js crypto.scrypt, a random salt, and timing-safe verification.

| Method | Purpose | | --- | --- | | createAccount(options) | Persist an explicitly created account. Requires a password when authSources includes local. | | getAccountByEmail(email) | Find an account by normalized email. | | getAccountById(id) | Find an account by UUID. | | listAccounts() | Return all persisted accounts. | | hasActiveAdminAccount() | Return whether at least one active admin account exists. | | verifyLocalPassword(account, password) | Validate a local password for an active local account. | | updateLoginState(accountId, patch) | Update lastLoginAt, updatedAt, and optionally idpSubject. | | normalizeEmail(email) | Normalize an email exactly like the store does internally. |

Account Authentication

AccountAuthService authenticates only existing active accounts. It supports local passwords, idp.global passwords, or auto mode.

import {
  AccountAuthService,
  IdpGlobalServerClient,
  SmartdataAccountStore,
} from '@idp.global/sdk/server';

const accountStore = new SmartdataAccountStore({ smartdataDb });
const idpClient = new IdpGlobalServerClient();

const authService = new AccountAuthService({
  store: accountStore,
  idpClient,
});

const authResult = await authService.authenticate({
  email: '[email protected]',
  password: 'correct horse battery staple',
  authSource: 'auto',
});

if (!authResult) {
  throw new Error('Invalid login.');
}

console.log(authResult.account.role, authResult.authSource);

In auto mode, the service tries local auth first when the account allows local; if that fails and the account allows idp.global, it uses the configured IdpGlobalServerClient. IdpGlobalServerClient defaults to the hosted https://idp.global endpoint; pass { baseUrl } only for self-hosted or staging IdP instances. idp.global authentication is accepted only when the returned user email matches the local account email and the returned user ID matches the stored idpSubject when one is already set.

Server API Surface

| API | Description | | --- | --- | | SmartdataAccountStore | Smartdata-backed account persistence and local password verification. | | AccountAuthService | Existing-account authentication orchestration for local, idp.global, and auto. | | IdpGlobalServerClient | Typed-socket client for idp.global password login, JWT refresh, and whoIs lookup. | | PasswordHasher | Static hashPassword() and verifyPassword() helpers using scrypt:v1. | | IdpSdkAccountDoc | Smartdata document class backing persisted SDK accounts. | | setAccountDocSmartdataDb() | Configure the active Smartdata DB for IdpSdkAccountDoc. Usually handled by SmartdataAccountStore. |

Types

The server export includes these TypeScript types:

| Type | Values or purpose | | --- | --- | | TIdpAccountAuthSource | 'local' | 'idp.global' | | TIdpAccountRole | 'admin' | 'user' | | TIdpAccountStatus | 'active' | 'disabled' | | IIdpSdkAccount | Persisted account shape. | | ICreateIdpSdkAccountOptions | Input for account creation. | | IAuthenticateAccountOptions | Input for AccountAuthService.authenticate(). | | IAuthenticatedAccountResult | Successful auth result with account, auth source, and optional idp.global tokens. | | IIdpGlobalServerClientOptions | Server client configuration with optional baseUrl; defaults to https://idp.global. | | IIdpPasswordAuthResult | idp.global user, JWT, and refresh-token result. |

Runtime Notes

Use the explicit subpath imports. They keep browser bundles free of Node-only code and keep server processes free of browser storage dependencies.

import { IdpClient } from '@idp.global/sdk/browser';
import { AccountAuthService } from '@idp.global/sdk/server';

The SDK uses typed sockets and typed requests from @api.global/*, shared idp.global request contracts from @idp.global/interfaces, and focused Push Rocks utilities for URL handling, JSON/base64 encoding, observables, JWT decoding, browser storage, smartdata persistence, and promise coordination.

Testing

pnpm test

The test suite currently covers the server account store and auth service: explicit account creation, scrypt-backed local password verification, active-admin detection, and rejection of idp.global login results that do not match the persisted account email.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

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.