@nevermined-io/ui-widgets-server

Server-side helper for the Nevermined UI Widgets. Mints a widget session by calling the Nevermined API with your widget key secret and returns the session the browser SDK (@nevermined-io/ui-widgets) consumes directly.

This package is intended to run only on your backend. It transmits your widget key rawSecret server-to-server; the secret must never be exposed to the browser.

Install

npm install @nevermined-io/ui-widgets-server
# or
pnpm add @nevermined-io/ui-widgets-server

Requires Node 18+ (uses the global fetch).

Quick start

In your organization's backend, create an endpoint that returns a fresh widget session for the currently logged-in user:

import express from 'express'
import { createWidgetSession } from '@nevermined-io/ui-widgets-server'

const app = express()

app.get('/api/widget-session', async (req, res) => {
  // Authenticate the request your normal way and resolve the user's email.
  // The email is the canonical Nevermined identity — a user that later logs
  // into nevermined.dev directly with the same email is resolved to the
  // same Privy user, the same wallet, and the same widget profile.
  const email = req.user.email

  const session = await createWidgetSession({
    email,
    orgId: process.env.NVM_ORG_ID!,
    rawSecret: process.env.NVM_WIDGET_KEY_SECRET!, // never expose to the browser
    apiBaseUrl: 'https://api.sandbox.nevermined.app',
  })

  res.json(session)
})

Then, in the browser:

import { NeverminedWidgets } from '@nevermined-io/ui-widgets'

const session = await fetch('/api/widget-session').then((r) => r.json())

const nvm = await NeverminedWidgets.initialize({
  session,
  environment: 'sandbox',
})

API

createWidgetSession(options): Promise<WidgetSession>

POSTs { orgId, email, rawSecret } to ${apiBaseUrl}/api/v1/widgets/session and returns the session response. Forward the result verbatim to the browser SDK.

Options

| Field | Type | Required | Description | | ------------ | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | string | yes | The end user's email — the canonical Nevermined identity. A user that logs into nevermined.dev directly with the same email is resolved to the same Privy user, wallet, and profile. Trimmed and lowercased before sending. | | orgId | string | yes | Your Nevermined organization id. | | rawSecret | string | yes | The widget key secret (wk_...) issued in the Nevermined dashboard. Server-side only. F-055: the API stores only its SHA-256 hash. | | apiBaseUrl | string | yes | Nevermined API base URL — e.g. https://api.sandbox.nevermined.app. The helper appends /api/v1/widgets/session. | | fetch | typeof fetch | no | Override the global fetch (useful in tests). |

Response shape

interface WidgetSession {
  sessionToken: string
  userId: string
  userWallet: string
  apiKeyHash: string
  expiresAt: string // ISO timestamp
}

Breaking change vs < 0.6.0

• createInitToken has been removed. F-055 (#1468): the iframe-bound init JWT model required the API to store widget secrets in a reversible form. Hashed storage replaces that with a server-to-server credential exchange: the integrator backend calls the Nevermined API directly with rawSecret and forwards the session to the iframe.
• The new helper is createWidgetSession. The secretKey option is renamed rawSecret; an apiBaseUrl option is now required. The return value is the full WidgetSession object, not a JWT string.
• The browser SDK now accepts the session object directly via NeverminedWidgets.initialize({ session, environment }); the iframe no longer exchanges a token at startup.

Security notes

• Treat rawSecret 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.
• 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