Jokkoo Node.js Server SDK

Framework-agnostic helper library for tenant Node.js backends.

Goals

• generateUserToken() — sign short-lived JWTs for end users

Install

npm install @jokkoo/nodejs-server
# or
pnpm add @jokkoo/nodejs-server
# or
yarn add @jokkoo/nodejs-server

Quick start (Express)

import express from "express"
import { generateUserToken } from "@jokkoo/nodejs-server"

const app = express()
app.use(express.json())

const signingSecret = process.env.JOKKOO_SIGNING_SECRET!
const organizationId = process.env.JOKKOO_ORGANIZATION_ID!

app.post("/auth/jokkoo-user-token", (req, res) => {
  const { userId, name, email, phone, locale } = req.body

  const token = generateUserToken({
    signingSecret,
    sub: userId,
    org: organizationId,
    name,
    email,
    phone,
    locale: locale ?? "en",
    expiresInSeconds: 3600,
  })

  res.json({ token })
})

app.listen(3000)

API reference

generateUserToken(options)

Generate a signed user_token JWT (HMAC-SHA256).

| Option | Type | Required | Description | |--------|------|----------|-------------| | signingSecret | string | yes | Tenant signing secret from the Jokkoo dashboard | | sub | string | yes | End-user id (external_user_id) | | org | string | yes | Organization id (must match the client channel org) | | name | string | yes | Display name (max 60 chars; no HTML/script) | | email | string | no | Email (max 254 chars; validated format; omit if unavailable) | | phone | string | no | Phone number (max 32 chars; omit if unavailable) | | locale | string | yes | Locale (e.g. en_US, fr; max 35 chars) | | avatar | string | no | Avatar URL (max 2048 chars; no HTML/script or javascript: URLs) | | timezone | string | no | Timezone (e.g. UTC, Africa/Dakar; max 64 chars) | | metadata | Record<string, unknown> | no | Extra metadata; string values must not contain HTML/script; defaults ipAddress / location to null if omitted | | expiresInSeconds | number | yes | Token TTL in seconds (positive integer) |

Returns a signed JWT string.

Validation

generateUserToken() validates all inputs before signing:

• Required fields (signingSecret, sub, org, name, locale, expiresInSeconds) must be present and non-blank after trim.
• Optional fields (email, phone, avatar, timezone) are omitted when null/undefined; if provided, they must be non-blank.
• Max lengths: sub/org 255, name 60, locale 35, email 254, phone 32, avatar 2048, timezone 64.
• Email format is checked when email is provided.
• HTML/script rejection: string claims and metadata string values must not contain HTML tags, angle brackets (</>), or javascript: URLs on avatar.
• Expiry: expiresInSeconds must be a positive integer.

Throws Error with a descriptive message when validation fails (e.g. "org is required", "email is invalid", "name must not contain HTML or script").

Example with optional fields

import { generateUserToken } from "@jokkoo/nodejs-server"

const token = generateUserToken({
  signingSecret: process.env.JOKKOO_SIGNING_SECRET!,
  sub: "user-42",
  org: process.env.JOKKOO_ORGANIZATION_ID!,
  name: "Amadou Diallo",
  email: "[email protected]",
  phone: "+221700000000",
  locale: "fr",
  avatar: "https://example.com/avatar.jpg",
  timezone: "Africa/Dakar",
  metadata: { plan: "premium" },
  expiresInSeconds: 3600,
})

Verifying tokens

Use jsonwebtoken (or any HS256-capable library) to verify tokens issued by this SDK:

import jwt from "jsonwebtoken"

const decoded = jwt.verify(token, signingSecret, { algorithms: ["HS256"] })
console.log(decoded.sub, decoded.org)

Notes

• The library intentionally avoids web framework dependencies so it can be used with Express, Fastify, NestJS, Koa, or plain Node.js.
• JWT signing uses the jsonwebtoken package with algorithm HS256.
• Keep your signing secret on the server only — never ship it to client apps.

Build & test

cd typescript/packages/nodejs-server
pnpm install
pnpm test
pnpm build