GrebKey

Node.js SDK for validating GrebKey license keys inside your application.

Install

npm install grebkey

Quickstart

import { GrebKeyClient, GrebKeyError } from "grebkey";

const client = new GrebKeyClient({
  apiUrl: "https://your-api.example.com",
  productId: "prod_abc123"
});

try {
  const result = await client.validate("GREB-XXXX-XXXX-XXXX-XXXX");

  if (result.valid && result.machine_activated) {
    console.log("Licensed!");
  } else {
    console.log(`Not licensed: ${result.reason}`);
  }
} catch (error) {
  if (error instanceof GrebKeyError) {
    console.error(error.message);
  } else {
    console.error(error);
  }
}

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiUrl | string | required | Base URL of your GrebKey API | | productId | string | none | Restrict validation to a specific product | | cacheTtl | number | 3600 | Seconds before re-validating over the network | | gracePeriod | number | 86400 | Seconds a stale cached result may be used if the API is unreachable | | cacheDir | string | ~/.grebkey/cache | Directory used for local cache files | | timeoutMs | number | 10000 | HTTP timeout in milliseconds | | fetch | typeof fetch | global fetch | Optional override for testing or custom runtime wiring |

Public API

• new GrebKeyClient(options)
• await client.validate(key)
• await client.activate(key, { apiKey, label })
• await client.deactivate(key, { apiKey })
• await client.getFingerprint()

Validation returns a plain object with the current GrebKey response fields:

result.valid;
result.reason;
result.key_id;
result.product_id;
result.metadata;
result.max_activations;
result.current_activations;
result.remaining_activations;
result.machine_activated;
result.expires_at;
result.from_cache;

Caching and offline behavior

Each validate() call:

1. Resolves the current machine fingerprint.
2. Checks for a local cache entry scoped to the license key and fingerprint.
3. Returns the cached result immediately if it is fresher than cacheTtl.
4. Falls back to the network if the cache is stale.
5. Returns a stale cached result during a network failure when the entry is still within gracePeriod.
6. Throws GrebKeyNetworkError if no usable cached result exists.

Cache files are stored in JSON format. The raw license key is never used as the filename.

Machine fingerprinting

The SDK builds a stable fingerprint from OS-level identifiers:

• Linux: /etc/machine-id
• macOS: IOPlatformUUID from ioreg
• Windows: MachineGuid from the registry via reg query
• Fallbacks on every platform: hostname and current username

The combined value is SHA-256 hashed before use or transmission.

Error handling

import {
  GrebKeyAPIError,
  GrebKeyError,
  GrebKeyNetworkError
} from "grebkey";

try {
  await client.validate("GREB-XXXX-XXXX-XXXX-XXXX");
} catch (error) {
  if (error instanceof GrebKeyNetworkError) {
    console.error("API unreachable and no usable cache.");
  } else if (error instanceof GrebKeyAPIError) {
    console.error(error.statusCode, error.message);
  } else if (error instanceof GrebKeyError) {
    console.error("Unexpected GrebKey SDK error.");
  } else {
    throw error;
  }
}

Security warning

apiKey is for trusted server-side use only.

Do not embed gk_live_... secrets in distributed desktop apps, installers, browser bundles, or other client-side code. If you need client activation, proxy it through your own secure backend.

Docs and API reference

• Product docs: https://grebkey.efraim.us/wiki
• Generated API docs: <api_url>/docs
• OpenAPI JSON: <api_url>/openapi.json