@carchalabs/seal-hwid 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,109 @@
+Carcha Seal SDK License
+Version 1.0, 7 November 2026
+
+Copyright (c) 2026 Bugra Omer Aydemir (Carcha Labs) ("we", "us").
+All rights not expressly granted below are reserved.
+
+This license covers the software in the carcha-seal-sdk repository and the packages
+built from it (the "SDK"). The source code is published so that you can review it;
+publishing it does not make it open source. Versions of the SDK published before
+7 November 2026 were released under the MIT License, which still applies to those
+versions.
+
+1. Definitions
+
+"Carcha Seal Service" means a license server operated by us, or a license server you
+run under a written agreement with us.
+
+"Your Application" means software that you develop and provide to your own customers,
+that uses the SDK to obtain and check licenses from the Carcha Seal Service, and whose
+main purpose is not licensing, license management, copy protection or software
+protection.
+
+"End Users" means the people and organizations that receive Your Application from you.
+
+2. What you may do
+
+As long as you comply with this license, we grant you a non-exclusive, worldwide,
+royalty-free, non-transferable license, which you may not sublicense except as
+section 2(c) allows, to:
+
+(a) use, copy and modify the SDK to integrate Your Application with the Carcha Seal
+    Service;
+
+(b) read and study the SDK's source code, for example to evaluate the SDK or to review
+    its security; and
+
+(c) distribute the SDK, unmodified or modified under (a), only as part of Your
+    Application, in object code or source code form, and let your End Users use it
+    only as part of Your Application.
+
+3. What you may not do
+
+You may not, and may not allow anyone else to:
+
+(a) sell, license, rent, lend or otherwise distribute the SDK, or any part or modified
+    version of it, on its own or as part of a software development kit, library,
+    framework or other product for developers;
+
+(b) use the SDK, or any part or modified version of it, with a license server or
+    service other than the Carcha Seal Service, except a test server you run only to
+    test Your Application;
+
+(c) use the SDK, or any part, modified version or translation of it, in a product or
+    service that substitutes for the Carcha Seal Service or the SDK, or that offers the
+    same or substantially similar functionality;
+
+(d) reverse engineer, decompile or disassemble the compiled parts of the SDK (such as
+    its native libraries), or otherwise try to derive source code we have not
+    published, except to the extent applicable law permits it despite this
+    restriction;
+
+(e) disable, bypass or tamper with the SDK's license checks, signature verification,
+    encryption or device binding, or help anyone else do so, in any application that
+    uses the Carcha Seal Service, except in Your Application while you test it;
+
+(f) remove or change this license or any copyright or other notice in the SDK; or
+
+(g) use our names, logos or trademarks, including "Carcha Seal" and "Carcha Labs",
+    except to state truthfully that Your Application uses Carcha Seal.
+
+4. Your End Users
+
+Your terms for Your Application must not give your End Users more rights in the SDK
+than to use it as part of Your Application. You are responsible for your End Users'
+use of the SDK as part of Your Application.
+
+5. Contributions
+
+If you send us changes or suggestions for the SDK, you grant us a perpetual,
+irrevocable, worldwide, royalty-free license to use, modify and distribute them for
+any purpose.
+
+6. Termination
+
+Your rights under this license end automatically if you breach it. If you end the
+breach within 30 days after we notify you of it, your rights are restored, unless you
+have breached this license before. When your rights end, you must stop using and
+distributing the SDK; your End Users may keep using copies of Your Application they
+received before then. Sections 3, 5, 7 and 8 continue to apply after termination.
+
+7. No warranty
+
+To the extent the law allows, the SDK is provided "as is", without warranty of any
+kind, express or implied, including warranties of merchantability, fitness for a
+particular purpose and non-infringement. If you have a separate written agreement with
+us for the Carcha Seal Service, its terms on warranty and liability apply to the SDK
+instead of sections 7 and 8.
+
+8. Limitation of liability
+
+To the extent the law allows, we are not liable for any damages arising from the SDK
+or this license. Nothing in this license limits or excludes liability that cannot be
+limited or excluded under applicable law, including liability for intent or gross
+negligence, for death or personal injury, or under product liability law.
+
+9. New versions of this license
+
+We may publish new versions of this license. Each version of the SDK stays under the
+license it was published with.

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.4.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": "SEE LICENSE IN LICENSE",
+  "optionalDependencies": {
+    "@carchalabs/seal-hwid-darwin-arm64": "0.4.0",
+    "@carchalabs/seal-hwid-darwin-x64": "0.4.0",
+    "@carchalabs/seal-hwid-win32-x64-msvc": "0.4.0",
+    "@carchalabs/seal-hwid-linux-x64-gnu": "0.4.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'] };