HomeDocsSDK

@cmsx-dev/sdk

License validation SDK for Node.js, Electron, and server-side JavaScript applications. Handles API calls, machine fingerprinting, Ed25519 signature verification, and offline caching out of the box.

Ed25519 Verified
Tamper-proof responses
Auto Fingerprint
SHA-256 machine ID
Offline Mode
72h grace period

Installation

bash
npm install @cmsx-dev/sdk

Or with other package managers:

bash
pnpm add @cmsx-dev/sdk
yarn add @cmsx-dev/sdk
bun add @cmsx-dev/sdk

Quick Start

typescript
import { CMSXClient } from '@cmsx-dev/sdk'

const cmsx = new CMSXClient({
  apiKey: 'xk_xxxxxxxxxxxxx',
  licenseKey: 'XCR-XXXX-XXXX-XXXX',
  publicKey: 'ed25519_hex_64chars', // optional
})

const result = await cmsx.validate()

if (result.valid) {
  console.log('License active!')
  console.log('Config:', result.config)
} else {
  console.log('License invalid:', result.status)
  process.exit(1)
}

Configuration

The CMSXConfig interface accepts the following options:

OptionTypeDefaultDescription
apiKeystringrequiredYour API key (starts with xk_)
licenseKeystringrequiredLicense key (XCR-XXXX-XXXX-XXXX)
publicKeystring—Ed25519 public key for signature verification (hex, 64 chars)
baseUrlstringhttps://api.cmsx.devAPI base URL
gracePeriodnumber259200Seconds a cached response is trusted offline (72h)
cachePathstring~/.cache/cmsx/Custom path for the cache file (Node.js only)

Methods

validate()Promise<ValidationResponse>

Validates the license against the CMSX API. If the server is unreachable, falls back to a locally cached response (if within grace period).

typescript
const result = await cmsx.validate()

// result.valid      — boolean
// result.licenseId  — string | null
// result.productId  — string | null
// result.status     — "active" | "expired" | "revoked" | "killed" | ...
// result.config     — Record<string, string>
// result.signature  — Ed25519 base64 signature
// result.validatedAt — ISO 8601 timestamp
deactivate()Promise<void>

Deactivates this machine from the license. Decrements the activation counter on the server and removes the local cache. Call this when the user uninstalls your app.

typescript
await cmsx.deactivate()
console.log('Machine deactivated, license slot freed')
isValid()boolean

Returns the last known validation state synchronously (no network call). Useful for cache checks between validations.

typescript
if (cmsx.isValid()) {
  // proceed with the app
}
getConfig()Record<string, string>

Returns the last known config object synchronously. Use this to read feature flags or tier information set in the CMSX dashboard.

typescript
const config = cmsx.getConfig()
const tier = config['tier'] // e.g., "pro"
const maxUsers = config['max_users'] // e.g., "50"
machineIdstring

The SHA-256 machine fingerprint (read-only property). This is the unique identifier sent with each validation request.

typescript
console.log(cmsx.machineId)
// "a1b2c3d4e5f6..." (64-char hex SHA-256)

Machine Fingerprint

The SDK automatically generates a deterministic SHA-256 fingerprint from system properties:

  • hostname — OS hostname
  • platform — e.g., linux, darwin, win32
  • arch — e.g., x64, arm64
  • username — OS user running the process

The same machine always produces the same fingerprint. You can also use generateMachineId() standalone:

typescript
import { generateMachineId } from '@cmsx-dev/sdk'

const id = generateMachineId()
console.log(id) // "648a28cfd782ef38..." (64-char hex)

Signature Verification

Every valid response includes an Ed25519 signature. The SDK verifies it automatically when you provide a publicKey in the config. You can also verify manually:

typescript
import { verifySignature } from '@cmsx-dev/sdk'

const payload = {
  valid: true,
  license_id: "6c9885fc-...",
  product_id: "e51cd7a3-...",
  status: "active",
  validated_at: "2026-02-27T01:41:10.044Z",
}

const isValid = await verifySignature(
  payload,
  result.signature,    // base64 string
  'your_public_key_hex' // 64-char hex
)

if (!isValid) {
  throw new Error('Response tampered!')
}

Uses @noble/ed25519 — a pure JS, zero-dependency, audited implementation.

Offline Mode

When the API is unreachable, the SDK automatically falls back to a locally cached response. The cache is valid for the gracePeriod (default: 72 hours).

typescript
const cmsx = new CMSXClient({
  apiKey: 'xk_xxxxxxxxxxxxx',
  licenseKey: 'XCR-XXXX-XXXX-XXXX',
  gracePeriod: 86400, // 24 hours
})

// First call: hits API, caches response
await cmsx.validate()

// Later, if offline: returns cached result
// as long as it's within 24 hours
await cmsx.validate()

Cache location

By default, cached responses are stored at ~/.cache/cmsx/<key>.json. Customize with the cachePath option.

@cmsx-dev/next

Drop-in Next.js middleware for license validation. Validate your CMSX license at the edge with zero client-side code. Results are cached in an httpOnly cookie and re-validated on a configurable interval.

Zero Config
Drop-in middleware.ts
Edge Validation
Cookie-cached, httpOnly

Installation

bash
npm install @cmsx-dev/next

This package depends on @cmsx-dev/sdk and is designed for Next.js 13+ (App Router).

Quick Start

Create a middleware.ts at the root of your Next.js project:

typescript
// middleware.ts
import { withCMSX } from '@cmsx-dev/next'

export default withCMSX({
  apiKey: process.env.CMSX_API_KEY!,
  licenseKey: process.env.CMSX_LICENSE_KEY!,
  protectedRoutes: ['/dashboard/*', '/api/*'],
  onInvalid: '/license-expired',
})

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
}

Add environment variables to your .env.local:

bash
CMSX_API_KEY=xk_xxxxxxxxxxxxx
CMSX_LICENSE_KEY=XCR-XXXX-XXXX-XXXX

Configuration

The CMSXMiddlewareConfig interface:

OptionTypeDefaultDescription
apiKeystringrequiredYour CMSX API key (xk_...)
licenseKeystringrequiredThe license key to validate
publicKeystring—Ed25519 public key for verification (hex)
baseUrlstringhttps://api.cmsx.devAPI base URL
protectedRoutesstring[]["/*"]Glob patterns for protected routes
onInvalidstring403 responseRoute to redirect to when invalid
revalidateIntervalnumber300Seconds between re-validations (5 min)

Behavior

1. Route Matching

Only routes matching protectedRoutes patterns are validated. All other routes pass through.

2. Cookie Caching

After a successful validation, the result is stored in an httpOnly cookie (__cmsx_status). Subsequent requests use this cached value until it expires after revalidateInterval seconds.

3. Re-validation

When the cookie expires, the middleware calls the API again. If the license is now invalid, the user is redirected to onInvalid or receives a 403.

4. Network Errors

If the API is unreachable and a valid cached cookie exists, the request is allowed through (graceful degradation). Otherwise, the request is blocked.