SDKs
The official Node.js and NestJS SDKs do activation, verification, check-ins, offline activation and entitlements for you.
The official SDKs implement everything in this guide — fingerprint, activation and check-in, verification, states, the clock-tamper check, offline activation and enforcement helpers — over the same client API and file format. REST integration keeps working; you can switch either way without any change on the server.
| Package | For | Install |
|---|---|---|
@portcullis-et/node | Any Node.js product (18+). Also the portcullis CLI. | npm install @portcullis-et/node |
@portcullis-et/nestjs | NestJS 10, 11 and 12 products | npm install @portcullis-et/nestjs @portcullis-et/node |
Both have zero runtime dependencies beyond Node (and Nest), ship ESM and CommonJS, and are tested against the published test vectors.
Node.js
import { Portcullis, PortcullisApiError } from "@portcullis-et/node";
const license = await Portcullis.create({
productCode: "fleet",
// Compiled into the build: the product's public keys (Products → Signing keys).
keyring: { "fleet-2026-01": "<base64url Ed25519 public key>" },
dataDir: "/var/lib/fleet/license", // persistent volume
serverUrl: "https://api.portcullis.et", // env PORTCULLIS_URL overrides it
productVersion: "2.3.0",
checkIn: { usage: async () => ({ "limit.vehicles": await countVehicles() }) },
});
license.on("warning", notifyAdmins);
license.start(); // scheduled check-ins + hourly re-evaluation
// License screen
try {
await license.activate(keyTypedByAdmin);
} catch (error) {
if (error instanceof PortcullisApiError) showError(error.code, error.message);
else throw error;
}
// Anywhere
if (!license.state.usable) enterReadOnlyMode(license.state.status);
if (license.isEnabled("module.trips")) mountTrips();
if (!license.withinLimit("limit.vehicles", vehicles + 1)) refuse("Vehicle limit reached");Air-gapped sites:
const request = await license.createActivationRequest(); // → request.text, request.fileName (.req)
await license.importLicenseFile(licTextFromDigicom); // the .lic Digicom sends backlicense.state.status is one of valid, valid_grace, not_activated, not_started,
expired, suspended, revoked, invalid or clock_tampered; usable is true for the
first two.
NestJS
@Module({
imports: [
PortcullisModule.forRoot({
productCode: "fleet",
keyring: KEYRING,
dataDir: "/var/lib/fleet/license",
serverUrl: "https://api.portcullis.et",
isGlobal: true,
globalGuards: true,
}),
],
})
export class AppModule {}
@Controller("trips")
@RequiresFeature("module.trips") // 403 FEATURE_NOT_ENABLED unless licensed
export class TripsController {}
@Controller("license")
@SkipLicenseCheck() // the license screen keeps working when the license doesn't
export class LicenseController {
constructor(private readonly license: PortcullisService) {}
}With globalGuards, an unusable license puts the API in read-only mode: reads pass,
writes get 403 LICENSE_NOT_USABLE, as the
enforcement guidelines ask. PortcullisService also has
health() for a Terminus-style health check.
CLI for operators
npx @portcullis-et/node doctor --product fleet --data-dir /var/lib/fleet/license --server https://api.portcullis.et| Command | What it does |
|---|---|
portcullis fingerprint | Print this installation's fingerprint |
portcullis request | Write an offline activation request (.req) |
portcullis import <file.lic> | Import a license file received from Digicom |
portcullis inspect <file> | Show a .lic or .req (verifies with --keyring) |
portcullis status | The stored license and its state |
portcullis doctor | Check the data directory, server reachability and clock skew |
The full API reference is in each package's README on npm:
@portcullis-et/node ·
@portcullis-et/nestjs.
Other languages
Only Node.js has an official SDK. Products in other languages integrate over the client API and must pass the test vectors.