@tesouro/embedded-components-widget-token 0.0.1

package/README.md

@@ -0,0 +1,135 @@
+# @tesouro/embedded-components-widget-token
+
+Server-side helpers for minting widget tokens used by Tesouro's embedded
+components. Mints an [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)
+token-exchange request and encrypts it as a JWE (`A256KW` + `A256GCM`) using
+your shared widget secret.
+
+> **Server-only.** This package handles your `clientSecret` and `widgetSecret`,
+> so keep it on the server and never bundle it into client code. It runs in any
+> server runtime — a Next.js Route Handler, an Express server, or a Lambda
+> handler.
+
+## Installation
+
+```bash
+yarn add @tesouro/embedded-components-widget-token
+# or
+npm install @tesouro/embedded-components-widget-token
+```
+
+## Usage
+
+### One-shot
+
+```ts
+import { createWidgetToken } from '@tesouro/embedded-components-widget-token';
+
+const { widgetToken, exp } = await createWidgetToken({
+  clientId: process.env.TESOURO_CLIENT_ID!,
+  clientSecret: process.env.TESOURO_CLIENT_SECRET!,
+  widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
+  userId: 'user_123',
+  userEmail: 'user@example.com',
+});
+```
+
+`exp` is the token's expiration time in seconds since epoch — return it to the
+client so it can refresh before expiry.
+
+### Pre-configured factory
+
+When the same credentials are reused across many requests, bind them once with
+`configureCreateWidgetToken`:
+
+```ts
+import { configureCreateWidgetToken } from '@tesouro/embedded-components-widget-token';
+
+const mintWidgetToken = configureCreateWidgetToken({
+  clientId: process.env.TESOURO_CLIENT_ID!,
+  clientSecret: process.env.TESOURO_CLIENT_SECRET!,
+  widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
+});
+
+const { widgetToken, exp } = await mintWidgetToken({
+  userId: 'user_123',
+  userEmail: 'user@example.com',
+});
+```
+
+### Next.js Route Handler
+
+```ts
+// app/api/widget-token/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { configureCreateWidgetToken } from '@tesouro/embedded-components-widget-token';
+
+const mintWidgetToken = configureCreateWidgetToken({
+  clientId: process.env.TESOURO_CLIENT_ID!,
+  clientSecret: process.env.TESOURO_CLIENT_SECRET!,
+  widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
+});
+
+export async function POST(req: NextRequest) {
+  const { userId, userEmail } = await req.json();
+  const { widgetToken, exp } = await mintWidgetToken({ userId, userEmail });
+  return NextResponse.json({ widgetToken, exp });
+}
+```
+
+## API
+
+### `createWidgetToken(params): Promise<WidgetTokenResult>`
+
+| Param                 | Type     | Required | Description                                                                                  |
+| --------------------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
+| `clientId`            | `string` | yes      | Tesouro-issued client identifier. Used as JWE `kid` and as `iss`/`client_id` in the payload. |
+| `clientSecret`        | `string` | yes      | Tesouro-issued client secret. Carried as `client_secret` inside the encrypted payload.       |
+| `widgetSecret`        | `string` | yes      | Shared symmetric key used to encrypt the JWE.                                                |
+| `userId`              | `string` | yes      | Subject (`sub`) of the inner identity token.                                                 |
+| `userEmail`           | `string` | yes      | Email claim of the inner identity token.                                                     |
+| `expirationInSeconds` | `number` | no       | Token TTL in seconds. Defaults to `DEFAULT_EXPIRATION_IN_SECONDS` (480 — 8 minutes).         |
+
+Returns:
+
+```ts
+interface WidgetTokenResult {
+  widgetToken: string; // compact-serialized JWE
+  exp: number; // expiration in seconds since epoch (UTC)
+}
+```
+
+Throws if `clientId`, `clientSecret`, or `widgetSecret` is missing or empty.
+
+### `configureCreateWidgetToken(creds)`
+
+Binds `clientId`, `clientSecret`, `widgetSecret`, and an optional default
+`expirationInSeconds`, and returns a function that only takes per-request
+`userId` / `userEmail` (and an optional per-call `expirationInSeconds` that
+overrides the bound default).
+
+### `DEFAULT_EXPIRATION_IN_SECONDS`
+
+`480` — the default token lifetime in seconds (8 minutes).
+
+## Token format
+
+`createWidgetToken` produces a JWE with the following protected header:
+
+```json
+{
+  "alg": "A256KW",
+  "enc": "A256GCM",
+  "kid": "<clientId>",
+  "typ": "JWT",
+  "cty": "JWT"
+}
+```
+
+The encrypted payload is an RFC 8693 token-exchange request whose
+`subject_token` is an unsigned identity JWT (`alg: none`) bearing the user's
+`sub`, `email`, `iss`, `aud`, `iat`, and `exp` claims.
+
+## License
+
+UNLICENSED — internal Tesouro package.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/createWidgetToken.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+import { DEFAULT_EXPIRATION_IN_SECONDS as r, configureCreateWidgetToken as t, createWidgetToken as T } from "./index2.js";
+export {
+  r as DEFAULT_EXPIRATION_IN_SECONDS,
+  t as configureCreateWidgetToken,
+  T as createWidgetToken
+};

package/dist/index2.js

@@ -0,0 +1,82 @@
+import d from "crypto";
+import { EncryptJWT as y } from "jose";
+const k = 480;
+async function T({
+  clientId: e,
+  clientSecret: o,
+  widgetSecret: r,
+  userId: i,
+  userEmail: s,
+  organizationReference: a,
+  expirationInSeconds: c = k
+}) {
+  if (!r || !e || !o)
+    throw new Error(
+      "Missing required parameters for widget token generation: clientId, clientSecret, and widgetSecret are required"
+    );
+  const t = Math.floor(Date.now() / 1e3), n = t + c, u = new TextEncoder().encode(r), f = {
+    sub: i,
+    // Subject (user identifier)
+    email: s,
+    // Email claim
+    aud: "tesouro",
+    // Audience
+    iss: e,
+    // Issuer
+    exp: n,
+    // Expiration
+    iat: t
+    // Issued at
+  }, g = Buffer.from(JSON.stringify({ alg: "none", typ: "JWT" })).toString(
+    "base64url"
+  ) + "." + Buffer.from(JSON.stringify(f)).toString("base64url") + ".", p = {
+    aud: "tesouro",
+    client_id: e,
+    client_secret: o,
+    exp: n,
+    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+    iat: t,
+    iss: e,
+    jti: d.randomUUID(),
+    ...a ? { organization_reference: a } : {},
+    subject_token: g,
+    subject_token_type: "urn:ietf:params:oauth:token-type:access_token"
+  };
+  return { widgetToken: await new y(p).setProtectedHeader({
+    alg: "A256KW",
+    enc: "A256GCM",
+    kid: e,
+    typ: "JWT",
+    cty: "JWT"
+  }).encrypt(u), exp: n };
+}
+function b({
+  clientId: e,
+  clientSecret: o,
+  widgetSecret: r,
+  organizationReference: i,
+  expirationInSeconds: s
+}) {
+  return ({
+    userId: a,
+    userEmail: c,
+    // Defaults to the partner-config value bound at configure time. A per-call
+    // override supports partners whose single client serves multiple
+    // organizations; it must still be resolved server-side, never from the browser.
+    organizationReference: t = i,
+    expirationInSeconds: n = s
+  }) => T({
+    clientId: e,
+    clientSecret: o,
+    widgetSecret: r,
+    userId: a,
+    userEmail: c,
+    organizationReference: t,
+    expirationInSeconds: n
+  });
+}
+export {
+  k as DEFAULT_EXPIRATION_IN_SECONDS,
+  b as configureCreateWidgetToken,
+  T as createWidgetToken
+};

package/dist/lib/createWidgetToken.d.ts

@@ -0,0 +1,26 @@
+export declare const DEFAULT_EXPIRATION_IN_SECONDS = 480;
+export interface CreateWidgetTokenParams {
+    clientId: string;
+    clientSecret: string;
+    widgetSecret: string;
+    userId: string;
+    userEmail: string;
+    /**
+     * The partner's stable, opaque identifier for the business/organization
+     * (SMB grouping) the applicant belongs to. Minted into the outer JWE payload
+     * as `organization_reference` so the widget proxy can call
+     * embedded-banking/v1/application-status to drive widget visibility.
+     *
+     * MUST be resolved server-side from the partner's organization config — never
+     * accept this value from the browser.
+     */
+    organizationReference?: string;
+    expirationInSeconds?: number;
+}
+export interface WidgetTokenResult {
+    widgetToken: string;
+    exp: number;
+}
+export declare function createWidgetToken({ clientId, clientSecret, widgetSecret, userId, userEmail, organizationReference, expirationInSeconds, }: CreateWidgetTokenParams): Promise<WidgetTokenResult>;
+export declare function configureCreateWidgetToken({ clientId, clientSecret, widgetSecret, organizationReference: defaultOrganizationReference, expirationInSeconds: defaultExpiration, }: Pick<CreateWidgetTokenParams, 'clientId' | 'clientSecret' | 'widgetSecret' | 'organizationReference' | 'expirationInSeconds'>): ({ userId, userEmail, organizationReference, expirationInSeconds, }: Pick<CreateWidgetTokenParams, "userId" | "userEmail" | "organizationReference" | "expirationInSeconds">) => Promise<WidgetTokenResult>;
+//# sourceMappingURL=createWidgetToken.d.ts.map

package/dist/lib/createWidgetToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWidgetToken.d.ts","sourceRoot":"","sources":["../../src/lib/createWidgetToken.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,iBAAiB,CAAC,EACtC,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,mBAAmD,GACpD,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6DtD;AAED,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,qBAAqB,EAAE,4BAA4B,EACnD,mBAAmB,EAAE,iBAAiB,GACvC,EAAE,IAAI,CACL,uBAAuB,EACrB,UAAU,GACV,cAAc,GACd,cAAc,GACd,uBAAuB,GACvB,qBAAqB,CACxB,IACS,oEAQL,IAAI,CACL,uBAAuB,EACvB,QAAQ,GAAG,WAAW,GAAG,uBAAuB,GAAG,qBAAqB,CACzE,gCAUF"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@tesouro/embedded-components-widget-token",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tesourohq/Tesouro.Payments.Frontends.git",
+    "directory": "packages/embedded-components-widget-token"
+  },
+  "homepage": "https://github.com/tesourohq/Tesouro.Payments.Frontends/tree/main/packages/embedded-components-widget-token#readme",
+  "bugs": {
+    "url": "https://github.com/tesourohq/Tesouro.Payments.Frontends/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "jose": "^6.1.3"
+  },
+  "nx": {
+    "name": "embedded-components-widget-token",
+    "tags": [
+      "type:feature",
+      "server-only"
+    ],
+    "targets": {
+      "verify-publish": {
+        "executor": "nx:run-commands",
+        "dependsOn": [
+          "build"
+        ],
+        "inputs": [
+          "default",
+          "{workspaceRoot}/tools/publishable-package/**"
+        ],
+        "options": {
+          "command": "node tools/publishable-package/verify-publish.mjs --config {projectRoot}/publish.config.mjs"
+        }
+      }
+    }
+  }
+}