@nevermined-io/ui-widgets-server 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,89 @@
+# @nevermined-io/ui-widgets-server
+
+Server-side helper for the Nevermined UI Widgets. Mints short-lived **init tokens** that the browser SDK ([`@nevermined-io/ui-widgets`](https://www.npmjs.com/package/@nevermined-io/ui-widgets)) exchanges for an authenticated widget session.
+
+This package is intended to run **only on your backend**. It signs JWTs with your widget key secret, which must never be exposed to the browser.
+
+## Install
+
+```bash
+npm install @nevermined-io/ui-widgets-server
+# or
+pnpm add @nevermined-io/ui-widgets-server
+```
+
+Requires Node 18+ (uses Web Crypto via [`jose`](https://www.npmjs.com/package/jose)).
+
+## Quick start
+
+In your organization's backend, create an endpoint that returns a fresh init token for the currently logged-in user:
+
+```ts
+import express from 'express'
+import { createInitToken } from '@nevermined-io/ui-widgets-server'
+
+const app = express()
+
+app.get('/api/widget-init-token', async (req, res) => {
+  // Authenticate the request your normal way and resolve the user.
+  const userId = req.user.id
+
+  const initToken = await createInitToken({
+    userId,
+    orgId: process.env.NVM_ORG_ID!,
+    secretKey: process.env.NVM_WIDGET_KEY_SECRET!, // never expose to the browser
+  })
+
+  res.json({ initToken })
+})
+```
+
+Then, in the browser:
+
+```ts
+import { NeverminedWidgets } from '@nevermined-io/ui-widgets'
+
+const { initToken } = await fetch('/api/widget-init-token').then(r => r.json())
+
+const nvm = await NeverminedWidgets.initialize({
+  initToken,
+  environment: 'sandbox',
+})
+```
+
+## API
+
+### `createInitToken(options): Promise<string>`
+
+Returns a signed JWT (HS256) that the browser SDK passes to `POST /api/v1/widgets/session`. The token's audience is `nvm:widgets` and it carries the user identity (`sub`) and organization id (`orgId`) as claims.
+
+#### Options
+
+| Field        | Type     | Required | Default | Description |
+| ------------ | -------- | -------- | ------- | ----------- |
+| `userId`     | `string` | yes      | —       | Stable identifier for the end user in your system. Becomes the JWT `sub` claim. |
+| `orgId`      | `string` | yes      | —       | Your Nevermined organization id. |
+| `secretKey`  | `string` | yes      | —       | The widget key secret (`wk_...`) issued in the Nevermined dashboard. **Server-side only.** |
+| `expiresIn`  | `string` | no       | `'5m'`  | JWT lifetime — any [`jose`-compatible](https://github.com/panva/jose) duration string. The default is intentionally short: the browser exchanges the token immediately for a long-lived session. |
+
+#### Token shape
+
+```ts
+interface InitTokenPayload {
+  sub: string     // userId
+  orgId: string
+  aud: 'nvm:widgets'
+  iat: number
+  exp: number
+}
+```
+
+## Security notes
+
+- Treat `secretKey` like a database password: never inline it in client code, commit it, or send it through an unencrypted channel. If it leaks, rotate the widget key in the dashboard immediately.
+- Issue a new init token per session — they are short-lived by design. Do not cache them across users.
+- Pair this with `allowedOrigins` on the widget key so even a leaked secret can't mint sessions for arbitrary origins.
+
+## License
+
+Apache-2.0 © Nevermined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/ui-widgets-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",