@awarevue/license-verifier

Read, validate and cryptographically verify AwareVue license files in Node.js.

License files are issued from the AwareVue partner portal and downloaded as LIC-XXXXXXXX.license.json. This package reads such a file, checks its Ed25519 signature, and gives you typed access to the entitlements it grants.

npm install @awarevue/license-verifier

Requires Node.js 18 or later. No runtime dependencies. Ships ESM and CommonJS builds.

Usage

import { readLicenseFile } from '@awarevue/license-verifier';

const license = await readLicenseFile('/etc/awarevue/site.license.json', {
  publicKey: process.env.AWAREVUE_LICENSE_PUBLIC_KEY!,
});

console.log(license.licenseNumber);        // 'LIC-4KQ7T2WM'
console.log(license.accountName);          // 'Acme Security Ltd'
console.log(license.siteName);             // 'Main Office'
console.log(license.getQuantity('camera')); // 64
console.log(license.hasComponent('awarevue')); // true
console.log(license.isCareActive());       // true

readLicenseFile throws if the signature does not verify, so any license you hold afterwards is authentic. Use safeVerifyLicense if you would rather branch on a result than catch.

import { readFileSync } from 'node:fs';
import { safeVerifyLicense } from '@awarevue/license-verifier';

const result = safeVerifyLicense(JSON.parse(readFileSync(path, 'utf8')), { publicKey });

if (!result.ok) {
  console.error(`License rejected: ${result.error.message}`);
  process.exit(1);
}

Supplying the public key

The public key does not come from the license file. The file carries only a keyId naming which key signed it. Your application must supply the key from a source you trust — an environment variable, your config system, or a file you ship.

This is what makes the signature meaningful. If the key travelled inside the file, anyone could edit the entitlements, sign the result with a key of their own, and attach that key. Verification would pass and the signature would prove nothing.

The key is accepted as a PEM string, a base64-wrapped PEM string (the same form the portal backend stores in LICENSE_SIGNING_PUBLIC_KEY_BASE64), a Buffer, or a crypto.KeyObject.

To trust more than one key during a rotation, pass a map and the right key will be selected by keyId:

const license = await readLicenseFile(path, {
  publicKey: {
    'awarevue-2025-key': OLD_KEY_PEM,
    'awarevue-2026-key': NEW_KEY_PEM,
  },
});

Pass expectedKeyId to pin a single key and reject anything else.

Entitlements

Licenses grant two kinds of subject: ASSET_TYPE (physical devices such as cameras and doors) and SOFTWARE_COMPONENT (licensable software).

license.entitlements;        // every grant
license.assetTypes;          // ASSET_TYPE grants only
license.softwareComponents;  // SOFTWARE_COMPONENT grants only

license.getQuantity('camera');                    // across both types
license.getQuantity('gateway', 'ASSET_TYPE');     // disambiguated
license.hasComponent('awarevue');
license.hasAssetType('camera');

Quantities are a snapshot taken when the file was generated. If a time-boxed grant was active at that moment its quantity is included, and the file will keep reporting it after that grant lapses. Regenerate the license in the portal to get current figures.

Care coverage

Software ownership is perpetual: an expired care enrollment never revokes an entitlement. Care covers support and updates, and is the only part of a license with a validity window.

license.isCareActive();                              // now
license.isCareActive(new Date('2027-06-01'));        // at a given moment
license.careWindow;                                  // { status, reason, startDate, endDate } | null

careWindow is null when the site has no active enrollment. Boundaries are inclusive.

Errors

All errors extend LicenseError:

| Error | Meaning | | --- | --- | | LicenseFileError | Unreadable, oversized, or not valid JSON | | LicenseFormatError | Parsed, but not shaped like a license | | UnsupportedAlgorithmError | Declares an algorithm other than Ed25519 | | UnsupportedSchemaVersionError | Payload is newer than this package understands | | LicenseKeyError | Key missing, malformed, not Ed25519, or keyId not trusted | | LicenseSignatureError | Signature does not match the payload |

Scope

Verification is entirely offline: this package makes no network calls. It therefore cannot know whether a license was revoked or suspended after it was issued. If that matters, check licence status against the portal API separately.

Signing is not included. Private keys stay on the portal backend.

API

| Export | Description | | --- | --- | | readLicenseFile(path, options) | Read and verify a file, async | | readLicenseFileSync(path, options) | Read and verify a file, sync | | verifyLicenseString(json, options) | Verify license JSON held as a string | | verifyLicense(parsed, options) | Verify an already-parsed object | | safeVerifyLicense(parsed, options) | As above, returning a result instead of throwing | | License | The verified license accessor | | canonicalize(value) | The canonical JSON used to derive signed bytes |

Options: publicKey (required), expectedKeyId, and maxBytes (file readers only, default 1 MiB).

License

MIT