@idp.global/sdk 1.2.0 → 1.3.0

package/changelog.md

@@ -4,6 +4,16 @@
 
 
 
+
+## 2026-05-18 - 1.3.0
+
+### Features
+
+- publish @idp.global/interfaces dependency and expand SDK usage documentation (docs,deps)
+  - replace the local file-based @idp.global/interfaces dependency with the published ^1.0.1 package
+  - refresh development tooling versions in package.json
+  - rewrite the README with detailed browser and server SDK installation, API, and usage guidance
+
 ## 2026-05-13 - 1.2.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@idp.global/sdk',
-    version: '1.2.0',
+    version: '1.3.0',
     description: 'Reusable browser and server SDK for idp.global authentication.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxpQkFBaUI7SUFDdkIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLGdFQUFnRTtDQUM5RSxDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idp.global/sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "private": false,
   "description": "Reusable browser and server SDK for idp.global authentication.",
   "type": "module",
@@ -16,7 +16,7 @@
   "dependencies": {
     "@api.global/typedrequest": "^3.3.0",
     "@api.global/typedsocket": "^4.1.2",
-    "@idp.global/interfaces": "file:../interfaces",
+    "@idp.global/interfaces": "^1.0.1",
     "@push.rocks/smartdata": "^7.1.7",
     "@push.rocks/smartjson": "^6.0.1",
     "@push.rocks/smartpromise": "^4.2.4",
@@ -27,12 +27,12 @@
     "@push.rocks/webstore": "^2.0.22"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsdoc": "^2.0.3",
-    "@git.zone/tsrun": "^2.0.3",
-    "@git.zone/tstest": "^3.6.3",
+    "@git.zone/tsbuild": "^4.4.1",
+    "@git.zone/tsdoc": "^2.0.5",
+    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tstest": "^3.6.6",
     "@push.rocks/smartdb": "^2.10.0",
-    "@types/node": "^25.6.0"
+    "@types/node": "^25.9.0"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -1,10 +1,300 @@
 # @idp.global/sdk
 
-Reusable SDK for idp.global browser clients and server-side account authentication.
+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.
 
-Use explicit runtime exports:
+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.
 
-- `@idp.global/sdk/browser`
-- `@idp.global/sdk/server`
+## Issue Reporting and Security
 
-The server account store never creates accounts automatically. Consumers must explicitly create persisted accounts.
+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 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
+
+```bash
+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:
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+await idp.enableTypedSocket();
+
+const loginResponse = await idp.requests.loginWithUserNameAndPassword.fire({
+  username: 'developer@example.com',
+  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.
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+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.
+
+```ts
+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: 'admin@example.com',
+    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.
+
+```ts
+import {
+  AccountAuthService,
+  IdpGlobalServerClient,
+  SmartdataAccountStore,
+} from '@idp.global/sdk/server';
+
+const accountStore = new SmartdataAccountStore({ smartdataDb });
+const idpClient = new IdpGlobalServerClient({
+  baseUrl: 'https://sso.workspace.global',
+});
+
+const authService = new AccountAuthService({
+  store: accountStore,
+  idpClient,
+});
+
+const authResult = await authService.authenticate({
+  email: 'admin@example.com',
+  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`. 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 `baseUrl`. |
+| `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.
+
+```ts
+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
+
+```bash
+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](./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<br>
+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.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '1.2.0',
+  version: '1.3.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }