@nevermined-io/ui-widgets-server 0.4.5 → 0.4.6

package/README.md

@@ -25,11 +25,14 @@ 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
+  // 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 initToken = await createInitToken({
-    userId,
+    email,
     orgId: process.env.NVM_ORG_ID!,
     secretKey: process.env.NVM_WIDGET_KEY_SECRET!, // never expose to the browser
   })
@@ -55,13 +58,13 @@ const nvm = await NeverminedWidgets.initialize({
 
 ### `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.
+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's email (`email`, the canonical Nevermined identity) 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. |
+| `email`      | `string` | yes      | —       | The end user's email. Becomes the JWT `email` claim and 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. |
 | `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. |
@@ -70,7 +73,8 @@ Returns a signed JWT (HS256) that the browser SDK passes to `POST /api/v1/widget
 
 ```ts
 interface InitTokenPayload {
-  sub: string     // userId
+  sub: string     // mirrors `email` (legacy claim, kept for compatibility)
+  email: string   // canonical Nevermined identity
   orgId: string
   aud: 'nvm:widgets'
   iat: number
@@ -78,6 +82,10 @@ interface InitTokenPayload {
 }
 ```
 
+#### Breaking change vs `< 0.5.0`
+
+The `userId` parameter was renamed to `email` and is now required to be a real email address. The widget session API resolves the Privy user via `getByEmailAddress` and only falls back to creating a new user if no match exists; an arbitrary `userId` no longer maps to a deterministic Privy user. Update your backend integration to forward the user's email to `createInitToken` instead of an internal id.
+
 ## 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.

package/dist/create-init-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-init-token.d.ts","sourceRoot":"","sources":["../src/create-init-token.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAKxD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBtF"}
+{"version":3,"file":"create-init-token.d.ts","sourceRoot":"","sources":["../src/create-init-token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAKxD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBtF"}

package/dist/create-init-token.js

@@ -1,18 +1,21 @@
 import { SignJWT } from 'jose';
+import { normalizeEmail } from './normalize-email.js';
 const WIDGET_AUDIENCE = 'nvm:widgets';
 const DEFAULT_EXPIRES_IN = '5m';
 export async function createInitToken(options) {
-    const { userId, orgId, secretKey, expiresIn = DEFAULT_EXPIRES_IN } = options;
+    const { email, orgId, secretKey, expiresIn = DEFAULT_EXPIRES_IN } = options;
     if (!secretKey?.trim())
         throw new Error('secretKey is required');
-    if (!userId?.trim())
-        throw new Error('userId is required');
     if (!orgId?.trim())
         throw new Error('orgId is required');
+    const normalizedEmail = normalizeEmail(email);
     const secret = new TextEncoder().encode(secretKey);
-    return new SignJWT({ orgId })
+    // `sub` is set to the email so the API's existence check on the claim
+    // continues to pass without a parallel API change. The downstream
+    // identity resolution uses the explicit `email` claim, not `sub`.
+    return new SignJWT({ orgId, email: normalizedEmail })
         .setProtectedHeader({ alg: 'HS256' })
-        .setSubject(userId)
+        .setSubject(normalizedEmail)
         .setAudience(WIDGET_AUDIENCE)
         .setIssuedAt()
         .setExpirationTime(expiresIn)

package/dist/normalize-email.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validates and normalizes an email to a canonical form: trimmed and lowercased,
+ * capped at 254 chars (RFC 5321), and matched against a permissive format regex.
+ *
+ * Normalization is implicit so `Alice@Example.COM` and `alice@example.com` map
+ * to the same Nevermined identity downstream (#1520 — "one email = one user,
+ * one wallet, one widget profile"). Callers should not rely on the original
+ * case being preserved.
+ *
+ * Throws with caller-friendly messages — the SDK is the first boundary that
+ * knows the value is supposed to be an email.
+ */
+export declare function normalizeEmail(email: string | undefined): string;
+//# sourceMappingURL=normalize-email.d.ts.map

package/dist/normalize-email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-email.d.ts","sourceRoot":"","sources":["../src/normalize-email.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAahE"}

package/dist/normalize-email.js

@@ -0,0 +1,31 @@
+// Matches the regex behind <input type="email"> and what RFC 5322 implementations
+// accept in practice. Intentionally permissive — strict RFC validation belongs in
+// the integrator's auth layer, not here.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+// RFC 5321 caps email addresses at 254 chars. Enforcing here prevents a broken
+// upstream integrator from ballooning the JWT and the server-side decode path.
+const EMAIL_MAX_LENGTH = 254;
+/**
+ * Validates and normalizes an email to a canonical form: trimmed and lowercased,
+ * capped at 254 chars (RFC 5321), and matched against a permissive format regex.
+ *
+ * Normalization is implicit so `Alice@Example.COM` and `alice@example.com` map
+ * to the same Nevermined identity downstream (#1520 — "one email = one user,
+ * one wallet, one widget profile"). Callers should not rely on the original
+ * case being preserved.
+ *
+ * Throws with caller-friendly messages — the SDK is the first boundary that
+ * knows the value is supposed to be an email.
+ */
+export function normalizeEmail(email) {
+    if (!email?.trim())
+        throw new Error('email is required');
+    const normalized = email.trim().toLowerCase();
+    if (normalized.length > EMAIL_MAX_LENGTH) {
+        throw new Error(`email is too long (max ${EMAIL_MAX_LENGTH} chars per RFC 5321)`);
+    }
+    if (!EMAIL_RE.test(normalized)) {
+        throw new Error('email must be a valid email address');
+    }
+    return normalized;
+}

package/dist/types.d.ts

@@ -1,11 +1,29 @@
 export interface CreateInitTokenOptions {
-    userId: string;
+    /**
+     * The end user's email — the canonical Nevermined identity (#1520). The
+     * widget session API uses this to resolve or provision the Privy user.
+     *
+     * Validated and normalized at the SDK boundary: trimmed, lowercased, capped
+     * at 254 chars (RFC 5321), and matched against a basic format regex. The
+     * normalized value is what ends up in the JWT — callers should not rely on
+     * case being preserved.
+     */
+    email: string;
     orgId: string;
     secretKey: string;
     expiresIn?: string;
 }
 export interface InitTokenPayload {
+    /**
+     * Mirrors `email` so the widget session API's non-empty existence check on
+     * `sub` passes without a parallel API change. Do NOT read `sub` for identity
+     * downstream — read `email` instead. This claim will be dropped once the
+     * API stops reading `sub` (follow-up to #1520).
+     *
+     * @deprecated Read `email` instead. Kept temporarily for API compatibility.
+     */
     sub: string;
+    email: string;
     orgId: string;
     aud: string;
     iat: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACZ"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACZ"}

package/package.json

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