Node.js SDK - AuthForge

Requirements

Node.js 18.0 or later
No runtime dependencies beyond Node.js built-ins

Installation

Install from npm as @authforgecc/sdk:

npm install @authforgecc/sdk

The package ships authforge.mjs and TypeScript declarations (authforge.d.ts).

Prefer a single file in-repo? Copy authforge.mjs from GitHub. The npm package is recommended for versioning and updates.

TypeScript

Use the same import as JavaScript; types resolve from the package:

import { AuthForgeClient } from "@authforgecc/sdk";

Quick start

import { AuthForgeClient } from "@authforgecc/sdk";
import * as readline from "node:readline/promises";

const client = new AuthForgeClient({
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
});

const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const key = await rl.question("Enter license key: ");
rl.close();

if (await client.login(key)) {
    console.log("Authenticated!");
    // Your app logic here - the signed session covers the grace period
} else {
    console.error("Invalid license key.");
    process.exit(1);
}

Constructor parameters

const client = new AuthForgeClient({
    appId: "YOUR_APP_ID",                     // Required - from dashboard
    appSecret: "YOUR_APP_SECRET",             // Required for online login/validate; omit or "" for loginFromFile only
    publicKey: "YOUR_PUBLIC_KEY",             // Required - Ed25519 public key from your AuthForge dashboard (base64)
    onlineHeartbeat: false,                   // Optional - true enables periodic online check-ins (/auth/heartbeat)
    heartbeatInterval: 900,                   // Optional - background timer cadence (check-ins when online, local session checks otherwise)
    apiBaseUrl: "https://auth.authforge.cc",  // Optional
    onFailure: null,                          // Optional - callback(reason, exception)
    requestTimeout: 15,                       // Optional - HTTP timeout in seconds
    ttlSeconds: null,                         // Optional - grace period (session TTL). null = server default (24h). Clamped to [3600, 604800].
    hwidOverride: null,                       // Optional - custom identity (for example "tg:123456789")
});

`ttlSeconds` (grace period)

Requested session token lifetime in seconds for /auth/validate. This is the grace period: how long the app keeps running on the signed session without contacting AuthForge. Pass null (or omit) to accept the server default of 24 hours. The server clamps to [3600, 604800] (1 hour to 7 days). The requested TTL is preserved across heartbeat refreshes, and apps relying on the grace period alone can stretch their window up to 7 days.

Billing

Each successful login() or validateLicense() costs 1 credit (one /auth/validate debit).
The grace period is free: local session re-verification makes no network calls and consumes no credits.
Online check-ins (if enabled) cost 1 credit per 10 successful heartbeats (billed on every 10th call).
With online check-ins, revocations take effect on the next check-in regardless of interval; without them, at session expiry.

const success = await client.login(licenseKey);

Returns Promise<boolean>. It resolves to true if authentication succeeded, false otherwise. On success, the SDK starts a background timer that re-verifies the signed session locally during the grace period (and sends online check-ins if onlineHeartbeat: true).

Validate license (no session)

const result = await client.validateLicense(licenseKey);
if (result.valid) {
  console.log(result.sessionToken, result.expiresIn, result.appVariables, result.licenseVariables);
} else {
  console.error(result.code, result.error);
}

Same /auth/validate request and Ed25519 verification as login, without mutating the client’s stored session or starting the background timer. Use this for bots and repeated checks; use login when you want a long-lived session. Successful results may also include sessionExpiresAt, licenseExpiresAt (null for lifetime keys), maxHwidSlots, hwidCount, and licenseLabel when present in the signed payload; the decoded payload is always available as sessionData.

Failure callback

If authentication fails, an online check-in fails, or the session expires, the SDK calls your onFailure callback. If no callback is set (or the callback throws), the SDK exits the process.

function handleFailure(reason, exception) {
    if (reason === "login_failed") {
        console.error("Login failed - check your license key.");
        return;
    }

    if (reason === "heartbeat_failed") {
        console.error("Session check failed - saving state and shutting down.");
        saveApplicationState();
    }
}

const client = new AuthForgeClient({
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
    onFailure: handleFailure,
});

If you don’t set onFailure, the SDK terminates the process immediately on any failure. Set a callback in production for graceful shutdown.

Reading variables

After successful login, app variables and license variables are available on the client:

if (await client.login(licenseKey)) {
    // App-wide variables (set in dashboard or API)
    const appVars = client.appVariables;
    if (appVars.maintenanceMode) {
        console.log("Server is under maintenance.");
        process.exit(0);
    }

    // Per-license variables
    const plan = client.licenseVariables.plan ?? "basic";
    if (plan === "pro") {
        enableProFeatures();
    }
}

Grace period and online check-ins

By default, the app runs through the grace period after activation: the SDK re-verifies the signed session locally, makes no network calls, and stops when the session expires. Opt in to online check-ins for fast revocation and concurrent-use detection:

// Default: activate online, then run through the grace period (24h by default)
const client = new AuthForgeClient({
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
    ttlSeconds: 259200, // Optional: extend the grace period to 3 days (clamped to 1h-7d)
});

// Strict policy: periodic online check-ins for fast revocation
const strictClient = new AuthForgeClient({
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
    onlineHeartbeat: true,
    heartbeatInterval: 900, // 15 minutes (default)
});

See Online Check-ins for a detailed comparison.

Offline license files (`.authforge`)

For machines that never connect to the internet, the operator mints a signed offline license file in the dashboard or Developer API (1 credit). The SDK verifies it locally with your public key and the machine HWID; no network, no check-ins, and online login() is untouched. Omit appSecret so the air-gapped binary does not contain the App Secret.

const client = new AuthForgeClient({ appId: "APP_ID", publicKey: "PUBLIC_KEY" });

// Step 1 (customer machine): write an activation request the operator drops into the mint dialog.
client.writeActivationRequest("./machine.authforge-request");

// Step 2 (customer machine, after you deliver the file): path or armored text.
if (client.loginFromFile("./license.authforge")) {
  console.log("Offline license valid until", client.getOfflineLicense().expiresAt ?? "forever");
  console.log(client.getLicenseVariables());
}

Failures call onFailure("offline_login_failed", new Error(code)) and return false (never process.exit). Codes, in check order: bad_armor, bad_signature, unsupported_version, malformed_payload, wrong_app, expired, hwid_mismatch. client.verifyLicenseFile(pathOrText) and the exported verifyLicenseFile({ file, appId, publicKey, hwid }) run the same checks without touching state. Issued files cannot be revoked remotely; they stay valid until their own expiry. createActivationRequest() / writeActivationRequest(path) produce the .authforge-request the operator uploads; hostname is omitted unless includeMachineName: true. See Activation requests.

Migrating from `heartbeatMode`

heartbeatMode: "LOCAL" / "SERVER" is deprecated but still accepted:

heartbeatMode: "LOCAL": remove the option; the grace period is now the default.
heartbeatMode: "SERVER": use onlineHeartbeat: true instead.

Full example

import { AuthForgeClient } from "@authforgecc/sdk";
import * as readline from "node:readline/promises";

function saveState() {
    console.log("Saving application state...");
    // Your save logic here
}

const client = new AuthForgeClient({
    appId: "YOUR_APP_ID",
    appSecret: "YOUR_APP_SECRET",
    publicKey: "YOUR_PUBLIC_KEY",
    onlineHeartbeat: true, // Optional strict policy: check in every 15 minutes
    heartbeatInterval: 900,
    onFailure: (reason, exception) => {
        console.error(`Auth failure: ${reason}`);
        if (exception) {
            console.error(`Detail: ${exception.message ?? exception}`);
        }
        saveState();
        process.exit(1);
    },
});

const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const key = await rl.question("Enter license key: ");
rl.close();

if (!(await client.login(key))) {
    console.error("Invalid license key.");
    process.exit(1);
}

console.log("Licensed and running!");

const minVersion = client.appVariables.minVersion;
if (minVersion && APP_VERSION < minVersion) {
    console.error(`Please update to version ${minVersion} or later.`);
    process.exit(1);
}

process.on("SIGINT", () => {
    saveState();
    process.exit(0);
});

setInterval(() => {
    // Your app logic here
}, 1000);

GitHub

Full source, changelog, and issues: AuthForgeCC/authforge-node

​Requirements

​Installation

​TypeScript

​Quick start

​Constructor parameters

​ttlSeconds (grace period)

​Billing

​Login

​Validate license (no session)

​Failure callback

​Reading variables

​Grace period and online check-ins

​Offline license files (.authforge)

​Migrating from heartbeatMode

​Full example

​GitHub

Requirements

Installation

TypeScript

Quick start

Constructor parameters

`ttlSeconds` (grace period)

Billing

Login

Validate license (no session)

Failure callback

Reading variables

Grace period and online check-ins

Offline license files (`.authforge`)

Migrating from `heartbeatMode`

Full example

GitHub