API Reference

Public API @corelicense/node v0.5.9.

CoreLicense

Constructor

new CoreLicense(options: CoreLicenseOptions)

Lifecycle

Method	Returns	Description
`boot()`	`Promise<void>`	Initialize, sync server, fail-closed
`refresh()`	`Promise<LicenseStatus>`	Force refresh policy
`startBackgroundCheck()`	`void`	Enable sync interval
`stopBackgroundCheck()`	`void`	Disable interval

License gates

Method	Description
`requireActive()`	Throw if not active
`requireFeature(feature)`	Throw + audit if feature is off
`checkLimit(name, current)`	Throw if limit exceeded
`consumeQuota(name, amount?)`	Consume local quota
`getStatus()`	Current status
`getPolicy()`	Verified policy (null if not yet available)
`getRuntimeConfig()`	Config derived from policy

HTTP integrations

Method	Description
`express(options?)`	Express `RequestHandler`
`fastifyPlugin(options?)`	Fastify plugin

Worker / CLI

Method	Description
`guardWorker(name)`	Guard worker process
`guardCommand(name)`	Guard CLI/cron command

Deep integration

Method	Description
`bootstrap(options)`	Register modules + services
`createLicensedRegistry()`	Dedicated `LicensedModuleRegistry`
`createLicensedContainer()`	Dedicated `LicensedServiceContainer`

Events

license.on(event, handler)

Events: statusChanged | policyUpdated | licenseRevoked | licenseSuspended | offlineMode

CoreLicense only exposes on(). To unsubscribe, keep a reference to the handler and use the internal EventBus if custom wiring is needed.

LicensedModuleRegistry

Method	Description
`bootstrap(definitions, ctx)`	Bulk register
`registerLicensed(def, ctx)`	Register a single module
`has(name)`	Is module bound?
`get<T>(name)`	Get module + re-check license
`list()`	Names of registered modules

LicensedServiceContainer

Method	Description
`bootstrap(definitions, ctx)`	Bind services
`resolve<T>(name)`	Resolve + re-check license
`has(name)`	Is service bound?

Helpers

loadOptionsFromEnv(overrides?: Partial<CoreLicenseOptions>): CoreLicenseOptions
resolveApiUrl(options, cachedApiUrl?): string
parseEmbeddedApiUrl(licenseKey): string | null
registerLicensedRoutes(app, registry, routes): string[]
isLicenseError(error): boolean
formatLicenseError(error): string
isFeatureEnabled(policy, feature): boolean

Subpath exports

`@corelicense/node/express`

createExpressMiddleware(license, options?): RequestHandler

`@corelicense/node/fastify`

createFastifyPlugin(license, options?): FastifyPluginAsync
coreLicenseFastifyPlugin

`@corelicense/node/nestjs`

CoreLicenseModule.forRoot(options): DynamicModule
CoreLicenseGuard
CoreLicenseFeatureGuard
CoreLicenseExceptionFilter
RequireFeature(feature)  // decorator
REQUIRE_FEATURE_KEY

Types

`CoreLicenseOptions`

See installation.md.

`ExpressGuardOptions` / `FastifyGuardOptions`

{
  allowPaths?: string[];
  mode?: 'block' | 'limited';
}

`BootstrapResult`

{
  modules: LicensedModuleRegistry;
  services: LicensedServiceContainer;
  registeredModules: string[];
  registeredServices: string[];
  skipped: { name: string; feature: string; reason: 'feature_disabled' }[];
}

`LicenseStatus`

{
  status: 'active' | 'suspended' | 'revoked' | 'expired' | 'invalid' | 'blocked' | 'offline' | 'grace_expired' | 'limited';
  policyVersion?: string;
  expiresAt?: number;
  graceUntil?: number;
  offline?: boolean;
  // ...
}

Error codes

Every LicenseError has code, source, message, toClientPayload(), toJSON().

Code	HTTP (middleware)
`LICENSE_REVOKED`	403
`LICENSE_SUSPENDED`	403
`LICENSE_EXPIRED`	403
`LICENSE_INVALID`	403
`LICENSE_NOT_FOUND`	403
`LICENSE_NOT_STARTED`	403
`OFFLINE_GRACE_EXPIRED`	403
`FEATURE_DISABLED`	403
`MODULE_NOT_LICENSED`	403
`QUOTA_EXCEEDED`	403
`MAX_INSTANCES`	403
`INSTANCE_BLOCKED`	403
`CONFIG_MISSING_ENV`	— (boot fail)
`PRODUCT_NOT_FOUND`	— (boot fail)
`PUBLIC_KEYS_NOT_PUBLISHED`	— (boot fail)
`PUBLIC_KEYS_FETCH_FAILED`	— (boot fail)
`LICENSE_API_UNREACHABLE`	— (boot fail)
`LICENSE_API_TIMEOUT`	— (boot fail)
`POLICY_SIGNATURE_ERROR`	— (boot fail)
`BOOT_NOT_CALLED`	—
`POLICY_NOT_AVAILABLE`	— (boot fail)
`RUNTIME_CONFIG_UNAVAILABLE`	—
`POLICY_TOKEN_MISSING`	—
`POLICY_LOAD_FAILED`	—
`POLICY_PRODUCT_MISMATCH`	—
`POLICY_INSTANCE_MISMATCH`	—
`INSTANCE_ID_UNRESOLVED`	—
`PUBLIC_KEY_PINNED_MISMATCH`	—
`PUBLIC_KEYS_EMPTY`	—
`MODULE_NOT_REGISTERED`	403
`SERVICE_NOT_BOUND`	403
`RATE_LIMITED`	— (retryable)
`WORKER_NOT_ALLOWED`	—
`COMMAND_NOT_ALLOWED`	—

Full list in source: src/errors/codes.ts

formatLicenseError(error) also returns retryable and httpStatus (when available) for transport/API errors.

License Server response → SDK mapping

Client API (POST /v1/client/*) — HTTP 200, body ok: false:

Server `code`	SDK `code`	Retry?
`LICENSE_REVOKED`	`LICENSE_REVOKED`	No
`LICENSE_SUSPENDED`	`LICENSE_SUSPENDED`	No
`LICENSE_EXPIRED`	`LICENSE_EXPIRED`	No
`LICENSE_NOT_STARTED`	`LICENSE_NOT_STARTED`	No
`INVALID_PRODUCT`	`PRODUCT_NOT_FOUND`	No
`PRODUCT_NOT_FOUND`	`PRODUCT_NOT_FOUND`	No
`INVALID_LICENSE`	`LICENSE_INVALID`	No
`LICENSE_NOT_FOUND`	`LICENSE_NOT_FOUND`	No
`LICENSE_INVALID`	`LICENSE_INVALID`	No
`INSTANCE_BLOCKED`	`INSTANCE_BLOCKED`	No
`MAX_INSTANCES`	`MAX_INSTANCES`	No
`POLICY_SIGN_FAILED`	`POLICY_SIGNATURE_ERROR`	No

Public keys (GET /v1/public/products/{id}/keys) — HTTP error, body { code, message }:

Server `code` / HTTP	SDK `code`	Retry?
`PRODUCT_NOT_FOUND` / 404	`PRODUCT_NOT_FOUND`	No
`PUBLIC_KEYS_NOT_PUBLISHED` / 404	`PUBLIC_KEYS_NOT_PUBLISHED`	No
`NOT_FOUND` / 404 (legacy)	`PUBLIC_KEYS_NOT_PUBLISHED`	No
`RATE_LIMITED` / 429	`RATE_LIMITED`	Yes
5xx / 408	`PUBLIC_KEYS_FETCH_FAILED`	Yes
Other 4xx	`PUBLIC_KEYS_FETCH_FAILED`	No
Network / DNS / refused	`LICENSE_API_UNREACHABLE`	Yes
Timeout	`LICENSE_API_TIMEOUT`	Yes

License API HTTP errors (400, 502, …) — not an ok: false body:

Case	SDK `code`	Retry?
429	`RATE_LIMITED`	Yes
5xx / 408	`LICENSE_API_ERROR`	Yes
Other 4xx	`LICENSE_API_ERROR`	No
Network / DNS / refused	`LICENSE_API_UNREACHABLE`	Yes
Timeout	`LICENSE_API_TIMEOUT`	Yes

Client API (License Server)

The SDK calls these endpoints (not typically called directly from the app):

Endpoint	Description
`POST /v1/client/activate`	First activation
`POST /v1/client/check`	Periodic check
`POST /v1/client/refresh`	Force refresh
`GET /v1/public/products/{id}/keys`	Public keys

Details: Client API Reference