@carchalabs/seal-hwid 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bugra Omer Aydemir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @carchalabs/seal-hwid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node-API layer over the `seal_hwid` native core (`../hwid`), for Node.js and Electron. One `.node` file per platform; Node-API is ABI-stable, and napi-rs looks up the Node-API functions in the host process at load time, so the same file loads in Node and in Electron.
+
+```js
+const { collect, version } = require('@carchalabs/seal-hwid');
+const { vm, components, notes } = collect('your-product-key');
+// components: [{ kind: 'uuid' | 'board' | 'disk' | 'mac' | 'os' | 'cpu' | 'gpu', hash: '<64 hex>' }]
+```
+
+Only kinds, hashes, the VM flag and diagnostic notes reach JavaScript, never raw serials. If no native module exists for the platform, `require` throws (`code: 'HWID_UNAVAILABLE'`) instead of falling back.
+
+## Lease verification
+
+The module also verifies Carcha Seal leases (`../lease`, the `seal_lease` crate) with the same rules, order and failure reasons as `verifyLease` in `@carchalabs/seal-core`. The Ed25519 public keys it trusts are compiled in, so a lease signed with another key cannot be made to pass by changing a file or a setting.
+
+```js
+const { verifyLease, leaseKeyIds } = require('@carchalabs/seal-hwid');
+verifyLease(token, { product, fingerprintHash, now, graceSeconds }); // { ok, reason?, kid? }
+leaseKeyIds(); // ids of the compiled-in keys (keyId in @carchalabs/seal-core)
+decryptFeature(token, { product, fingerprintHash, now }, licenseKey, 'pro', data); // { ok, data?, reason? }
+```
+
+`devicePublicKey('licensekit:<product>')` returns this machine's X25519 public key (base64url), derived from its hardware; the SDK sends it so the server wraps feature keys for this machine only, and `decryptFeature` derives the matching secret itself (it never reaches JavaScript). A test build with `--features test-device-secret` (CI only) takes the secret as a sixth argument so the shared vectors can run through this layer.
+
+`decryptFeature` verifies the lease first, then unwraps the feature's content key from the lease (claim `fk`) for this license key and device and decrypts data encrypted for the feature; the key never reaches JavaScript.
+
+The published build trusts the hosted service's current and next keys (`../quickstart/public-keys`). A self-hosted server's operator builds with their own: `SEAL_LEASE_PUBLIC_KEYS=<base64 SPKI>,<base64 SPKI> npm run build` (the PEM bodies, comma-separated). The Electron SDK uses this verifier next to its JavaScript one when the compiled-in keys include every key the app was given; a different answer from the two is treated as a modified license.
+
+Both verifiers are tested against the same vectors: `../lease/tests/vectors.json`, leases signed by @carchalabs/seal-core with a throwaway key and the result core gives for each (`node ../lease/tests/make-vectors.js` regenerates them). The Rust crate (`cargo test` in `../lease`), core's own tests and this module (a build that trusts the vectors' key, in CI) must all give those results.
+
+## Packages
+
+Published as napi-rs lays out prebuilt modules: the main package holds the loader, and each target is its own package listed as an exact-version optional dependency, with `os`/`cpu` (and `libc`) so npm installs only the one for the machine. Nothing is compiled or downloaded at install time.
+
+| Target | Package | Built on |
+| --- | --- | --- |
+| macOS arm64 | `@carchalabs/seal-hwid-darwin-arm64` | `macos-latest` |
+| macOS x64 | `@carchalabs/seal-hwid-darwin-x64` | `macos-15-intel` (GitHub's Intel macOS runners end in fall 2027) |
+| Windows x64 | `@carchalabs/seal-hwid-win32-x64-msvc` | `windows-latest` |
+| Linux x64 (glibc) | `@carchalabs/seal-hwid-linux-x64-gnu` | `ubuntu-22.04` |
+
+Other platforms (Linux musl or arm64, Windows arm64) have no module yet: `require` throws `HWID_UNAVAILABLE`. CI (`.github/workflows/hwid-node.yml`) builds each target on its own runner, runs the tests there, installs the main and platform package from tarballs the way users get them, and uploads the platform package.
+
+In Electron the `.node` file must sit outside the app's asar archive (Electron loads native modules with `process.dlopen`); electron-builder unpacks native modules automatically.
+
+```
+npm run build   # cargo build --release, then seal-hwid.<target>.node next to index.js (loaded first)
+npm test        # Node tests
+node scripts/build.js --npm   # also copies it into npm/<target>/ (CI)
+npx electron test/electron-check.js   # loads it in Electron (with electron installed)
+```

package/index.d.ts

@@ -0,0 +1,72 @@
+export type ComponentKind = 'uuid' | 'board' | 'disk' | 'mac' | 'os' | 'cpu' | 'gpu';
+
+export interface Component {
+  kind: ComponentKind;
+  /** Lowercase hex HMAC-SHA256 of the component, keyed by the product. */
+  hash: string;
+}
+
+export interface Collected {
+  /** Version of the result shape. */
+  format: number;
+  /** True when a hypervisor was detected (best effort). */
+  vm: boolean;
+  components: Component[];
+  /** Why kinds are missing: the failing call and its error code, never a value. */
+  notes: string[];
+}
+
+/** Reads this machine's components and hashes each with the product key. */
+export function collect(key: string | Buffer): Collected;
+
+export interface LeaseCheck {
+  product: string;
+  fingerprintHash: string;
+  /** Seconds since the Unix epoch; default: now. */
+  now?: number;
+  graceSeconds?: number;
+  leewaySeconds?: number;
+  issuer?: string;
+}
+
+export interface LeaseVerdict {
+  ok: boolean;
+  /** The failure reason, as @carchalabs/seal-core names it; absent when ok. */
+  reason?: string;
+  /** Id of the key that signed the lease; present when ok. */
+  kid?: string;
+}
+
+/**
+ * Verifies a lease with the public keys compiled into this build and the same rules,
+ * order and reasons as verifyLease in @carchalabs/seal-core.
+ */
+export function verifyLease(token: string, check: LeaseCheck): LeaseVerdict;
+
+export interface FeatureDecrypt {
+  ok: boolean;
+  /** The plaintext; present when ok. */
+  data?: Buffer;
+  /** A lease failure reason, 'not_licensed' or 'decrypt_failed'; absent when ok. */
+  reason?: string;
+}
+
+/**
+ * Verifies the lease (compiled-in keys), unwraps the feature's content key for this license key and
+ * device, and decrypts data encrypted for the feature (encryptForFeature in @carchalabs/seal-core). The
+ * content key never reaches JavaScript.
+ */
+export function decryptFeature(token: string, check: LeaseCheck, licenseKey: string, feature: string, data: Buffer): FeatureDecrypt;
+
+/** Ids of the lease signing keys this build trusts (keyId in @carchalabs/seal-core). */
+export function leaseKeyIds(): string[];
+
+/**
+ * This machine's X25519 device public key (base64url) for a product key, derived from its system UUID,
+ * motherboard serial, system disk serial and OS install id; null when it reports none of them. The
+ * secret half never leaves the module. It changes when one of those parts changes.
+ */
+export function devicePublicKey(key: string | Buffer): string | null;
+
+/** Version of the native core, e.g. "0.1.0". */
+export function version(): string;

package/index.js

@@ -0,0 +1,26 @@
+'use strict';
+// Loads the prebuilt addon for this platform: a local build next to this file (development),
+// otherwise the platform package npm installed (@carchalabs/seal-hwid-<target>, one of
+// the optionalDependencies). Fails loudly when there is none: the SDK then sends no components
+// rather than a weaker fingerprint.
+const path = require('node:path');
+const { existsSync } = require('node:fs');
+const { target } = require('./target');
+
+function unavailable(detail) {
+  const err = new Error(`@carchalabs/seal-hwid: no native module for ${process.platform}-${process.arch}: ${detail}`);
+  err.code = 'HWID_UNAVAILABLE';
+  return err;
+}
+
+const name = target();
+if (!name) throw unavailable('this platform has no prebuilt module');
+const local = path.join(__dirname, `seal-hwid.${name}.node`);
+let addon;
+try {
+  addon = existsSync(local) ? require(local) : require(`@carchalabs/seal-hwid-${name}`);
+} catch (e) {
+  throw unavailable(e.message);
+}
+
+module.exports = { collect: addon.collect, devicePublicKey: addon.devicePublicKey, verifyLease: addon.verifyLease, leaseKeyIds: addon.leaseKeyIds, decryptFeature: addon.decryptFeature, version: addon.version };

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@carchalabs/seal-hwid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Hardware component hashes for Carcha Seal (formerly LicenseKit) machine binding (Node.js and Electron).",
+  "keywords": ["hardware-id", "machine-id", "licensing", "electron", "carcha-seal"],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "target.js"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "MIT",
+  "optionalDependencies": {
+    "@carchalabs/seal-hwid-darwin-arm64": "0.3.0",
+    "@carchalabs/seal-hwid-darwin-x64": "0.3.0",
+    "@carchalabs/seal-hwid-win32-x64-msvc": "0.3.0",
+    "@carchalabs/seal-hwid-linux-x64-gnu": "0.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carcha-labs/carcha-seal-sdk.git",
+    "directory": "packages/hwid-node"
+  },
+  "bugs": {
+    "url": "https://github.com/carcha-labs/carcha-seal-sdk/issues"
+  },
+  "homepage": "https://seal.carchalabs.com/docs/",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/target.js

@@ -0,0 +1,17 @@
+'use strict';
+// The napi-rs target name for this machine (the platform package suffix), or null when
+// no prebuilt module exists for it. Shared by index.js (loading) and scripts/build.js.
+function isMusl() {
+  // glibc reports its version in the process report; musl does not.
+  const report = typeof process.report?.getReport === 'function' ? process.report.getReport() : null;
+  return !report?.header?.glibcVersionRuntime;
+}
+
+function target(platform = process.platform, arch = process.arch, musl = platform === 'linux' && isMusl()) {
+  if (platform === 'darwin' && (arch === 'arm64' || arch === 'x64')) return `darwin-${arch}`;
+  if (platform === 'win32' && arch === 'x64') return 'win32-x64-msvc';
+  if (platform === 'linux' && arch === 'x64' && !musl) return 'linux-x64-gnu';
+  return null;
+}
+
+module.exports = { target, TARGETS: ['darwin-arm64', 'darwin-x64', 'win32-x64-msvc', 'linux-x64-gnu'] };