@zdevzone/keyforge-client 0.0.0-stage → 0.1.0

package/dist/windows.js

@@ -0,0 +1,27 @@
+/** Optional Node-only Windows adapter. Never imported by the framework-independent entry point. */
+import { join } from "node:path";
+import { createSignalProvider, executeQuery } from "./device-signals-node.js";
+export { DeviceSignalQueryError as WindowsQueryError, hashDeviceIdentifier as hashWindowsIdentifier, normalizeDeviceIdentifier as normalizeWindowsIdentifier, } from "./device-signals-node.js";
+const kinds = ["machine-guid", "smbios-uuid", "volume-serial"];
+const queries = {
+    "machine-guid": "(Get-ItemProperty -LiteralPath 'HKLM:\\SOFTWARE\\Microsoft\\Cryptography' -Name MachineGuid -ErrorAction Stop).MachineGuid",
+    "smbios-uuid": "(Get-CimInstance -ClassName Win32_ComputerSystemProduct -ErrorAction Stop).UUID",
+    "volume-serial": "(Get-CimInstance -ClassName Win32_LogicalDisk -Filter ('DeviceID=' + [char]39 + $env:SystemDrive + [char]39) -ErrorAction Stop).VolumeSerialNumber",
+};
+function systemQuery(kind) {
+    const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const command = "$ErrorActionPreference='Stop'; try { " +
+        queries[kind] +
+        " } catch { if ($_.Exception -is [System.UnauthorizedAccessException] -or $_.FullyQualifiedErrorId -match 'AccessDenied|Unauthorized') { exit 5 }; exit 1 }";
+    return executeQuery(executable, [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        command,
+    ]);
+}
+export function createWindowsDeviceSignalsProvider(options = {}) {
+    return createSignalProvider("win32", kinds, options, systemQuery);
+}
+//# sourceMappingURL=windows.js.map

package/dist/windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.js","sourceRoot":"","sources":["../src/windows.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE9E,OAAO,EACL,sBAAsB,IAAI,iBAAiB,EAC3C,oBAAoB,IAAI,qBAAqB,EAC7C,yBAAyB,IAAI,0BAA0B,GACxD,MAAM,0BAA0B,CAAC;AAClC,MAAM,KAAK,GAAG,CAAC,cAAc,EAAE,aAAa,EAAE,eAAe,CAAU,CAAC;AACxE,MAAM,OAAO,GAA2B;IACtC,cAAc,EACZ,4HAA4H;IAC9H,aAAa,EAAE,iFAAiF;IAChG,eAAe,EACb,oJAAoJ;CACvJ,CAAC;AAOF,SAAS,WAAW,CAAC,IAAsB;IACzC,MAAM,UAAU,GAAG,IAAI,CACrB,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,aAAa,EACvC,UAAU,EACV,mBAAmB,EACnB,MAAM,EACN,gBAAgB,CACjB,CAAC;IACF,MAAM,OAAO,GACX,uCAAuC;QACvC,OAAO,CAAC,IAAI,CAAC;QACb,4JAA4J,CAAC;IAC/J,OAAO,YAAY,CAAC,UAAU,EAAE;QAC9B,SAAS;QACT,YAAY;QACZ,iBAAiB;QACjB,UAAU;QACV,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AACD,MAAM,UAAU,kCAAkC,CAChD,OAAO,GAAgC,EAAE;IAEzC,OAAO,oBAAoB,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@zdevzone/keyforge-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Typed KeyForge installation client and signed offline authorization verifier",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zdevzone/keyforge.git",
+    "directory": "packages/keyforge-client"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skill"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./windows": {
+      "types": "./dist/windows.d.ts",
+      "import": "./dist/windows.js"
+    },
+    "./linux": {
+      "types": "./dist/linux.d.ts",
+      "import": "./dist/linux.js"
+    },
+    "./macos": {
+      "types": "./dist/macos.d.ts",
+      "import": "./dist/macos.js"
+    },
+    "./device-signals": {
+      "types": "./dist/device-signals.d.ts",
+      "import": "./dist/device-signals.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/skill/keyforge-integrate/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: keyforge-integrate
+description: Integrate an existing desktop or service app with KeyForge using its TypeScript client SDK, online license/trial onboarding, secure installation storage, offline authorization and optional customer messaging. Use for dependent-app integration, not license-server administration or payment recording.
+---
+
+# Integrate KeyForge into a dependent app
+
+Inspect the target application's language, runtime, onboarding, protected operations, storage and test workflow first. Use `@zdevzone/keyforge-client` where its Fetch/Web Crypto runtime requirements fit; do not assume Electron, invent a backend, or add a second auth system. Ask for the deployment URL, stable product ID and trusted public keys when unavailable. Product/license keys are customer inputs; the SDK automatically creates the separate installation secret.
+
+Read [the integration contract](references/integration.md) before changing licensing. Prefer the installed SDK README/types and this contract; when the KeyForge source repository is available, consult `docs/dependent-app-integration.md`, `docs/verify-token.md`, `docs/client-openapi.json` and `examples/keyforge-node.ts`. Do not infer API fields from old unscoped routes or JWT libraries.
+
+## Implement the host integration
+
+- Add the publishable SDK archive/workspace dependency using the target repository's package manager. The package may not yet be on a public registry; obtain the built archive/source rather than installing an unrelated similarly named package. Respect target framework/version and existing UI components.
+- Implement and test a platform-appropriate `SecureStorage` adapter. Keep one SDK owner in a trusted process, expose only required status/actions to UI, and atomically persist a coherent state record. Use the existing credential vault or a vault-held encryption key plus atomic encrypted-file replacement. Never silently fall back to plaintext persistence or `MemoryStorage` in production.
+- Offer online key activation and provider-permitted trial onboarding. Skipping leaves the app unlicensed with only explicitly free app features. Enforce access at actual protected operations, including backend/IPC boundaries where present, rather than only hiding buttons.
+- Refresh while online ahead of the signed deadline; evaluate cached authorization on startup and at protected operations. Handle expired/revoked/reconnect states visibly. Keep app-specific trial usage durable and separate from token refresh. Preserve the target app's work/data when authorization ends.
+- For optional Windows recognition, import `createWindowsDeviceSignalsProvider` from `@zdevzone/keyforge-client/windows` in the trusted Node process and supply `deviceSignalsProvider`. Keep Node imports out of browser/mobile bundles. Do not collect CPU IDs, MAC/IP addresses or send raw identifiers. Read the SDK's Windows diagnostics and recovery guidance; partial/unsupported reports must leave installation-based licensing usable. Backfill existing installations with `updateDeviceSignals()`, never a new registration request. Preserve secure storage and the original registration body across restarts. Explain URL/product scoping, legacy backfill and recognition limitations; do not describe this as physical-device enforcement.
+- For Windows/Linux/macOS targets, prefer the automatic `createDeviceSignalsProvider()` from `@zdevzone/keyforge-client/device-signals`; explicit `/linux` and `/macos` factories also exist. Never request sudo to read Linux DMI identifiers. Honor missing/permission-denied signals and OS-specific complete sets (Mac two; Windows/Linux three). Browser/mobile sandbox limitations remain. For non-JS/TS apps, use the HTTP/OpenAPI and exact hash/token contracts; do not claim a native SDK exists or introduce Node just to wrap REST. Consult `docs/device-identity.md` when available and the packaged README; choose language-specific ports only for a real target's needs.
+- For optional inbox/notifications, use public customer methods and polling/backoff. Add a durable app outbox for support messages; keep UUID/body unchanged after timeouts. Do not imply that email delivery or customer portal accounts exist.
+
+Avoid handling signing secrets, admin tokens, financial operations or trusted metering credentials in the client. Never print keys, tokens, installation state, request-link secrets or authorization headers in tools/logs. Reading public key material is sufficient for verification. Installing this skill does not authorize modifying live operator/license data.
+
+## Verify the integration
+
+Test against an isolated KeyForge fixture or provider-approved test product. Verify online activation, offline restart within grace, reconnect after grace, altered/wrong-context tokens, signed HTTP-200 revocation, interrupted registration, exhausted seats, disabled/spent trials and retained consumption. Test the host storage adapter for atomic-save failure/restart and single-owner serialization. For communication, verify exact message replay and isolation from other installations/internal notes. Run the target repository's checks and explain runtime/storage limitations. Do not reset the server or issue live licenses merely to exercise the integration.

package/skill/keyforge-integrate/references/integration.md

@@ -0,0 +1,51 @@
+# Current KeyForge client contract
+
+The SDK supports Node 22.18+ as its reference runtime and needs Fetch, Web Crypto Ed25519, TextEncoder/TextDecoder, base64 helpers and secure randomness. It contains no UI or framework-specific credential vault. Keep installation identity in the desktop trusted/main process. For another language, implement against the server's OpenAPI and token contracts with shared test vectors; do not import Node-specific assumptions.
+
+## Setup and state
+
+```ts
+import { KeyForgeClient, type SecureStorage } from "@zdevzone/keyforge-client";
+declare const storage: SecureStorage;
+declare const publicKeys: Record<string, string>;
+const client = new KeyForgeClient({
+  serverUrl: "https://licenses.example.com",
+  productId: "your-product",
+  publicKeys,
+  storage,
+});
+```
+
+`SecureStorage.load()` returns a snapshot of `ClientState | null`; `save(state)` atomically replaces it. Scope a record to server URL, product and subject kind. Preserve identity, pending registration UUID/body, tokens, consumed trial usage, denial and clock checkpoint across restarts. Only a truly new installation returns null. Lost credentials need operator-assisted seat recovery, not silent state deletion. `MemoryStorage` is test-only/ephemeral. One SDK owner serializes calls; the host must prevent multiple writers across processes.
+
+## Online onboarding and offline usage
+
+- `activate(key)` registers if needed, activates online, verifies and saves the returned license, then returns authorization.
+- `startTrial()` requires online access and explicitly selects the previously obtained/server-issued trial. Registration alone does not select it; skipping onboarding grants no paid features.
+- `register()` persists identity and exact request before networking. Its bearer is a generated installation secret, not the product key or an administrator credential. Retry the same body/UUID after an ambiguous timeout. Do not change pending registration metadata.
+- `validate(key)` is online inspection; it does not bind a seat or create offline authorization.
+- `getAuthorization()` needs no network. Allow paid operations only for `state === "licensed"` and the exact required signed entitlement. Trial behavior must be defined by the app; trial grants do not contain paid plan entitlements.
+- `refresh()` requires a bound license and internet. Schedule before the returned paid `deadline`; the SDK does not run background workers. Transport retries bounded network/429/502/503/504 failures. A transient failure leaves an otherwise usable cached grant. Explicit binding/identity denials block fallback.
+- `deactivate()` releases the seat online, clears local paid use after success, and does not silently enable trial use.
+- States: `unlicensed`, `trial`, `licensed`, `reconnect_required`, `expired`, `revoked`. Reason codes explain failures. Correct a rolled-back system clock before reconnecting.
+- `consumeTrial(units)` persists cumulative consumption independently of grants and returns post-consumption state. Check available units before allowing work. No refresh/restart may reset consumption. Local counters are not authoritative on compromised devices.
+
+## Verification invariants
+
+`createDeviceSignalsProvider()` from `@zdevzone/keyforge-client/device-signals` automatically selects Windows, Linux or macOS in a trusted Node process. Explicit `/linux` and `/macos` exports are available; the `/windows` contract remains compatible. Consult the packaged README or `docs/device-identity.md` for per-OS sources and hash vectors. Never elevate to obtain DMI signals. Unsupported/sandboxed platforms still use installation credentials, not fabricated fingerprints. Only JS/TS has an official SDK; other languages implement the same HTTPS, secure-storage, retry and signed-token contracts. OpenAPI generation covers HTTP plumbing, not offline authorization.
+
+For opt-in Windows recognition, use `@zdevzone/keyforge-client/windows` only in a trusted Node process. Follow the SDK README's exact v1 normalization/hash scope; never invent an all-platform fingerprint. Preserve pending registration signals before networking. Use `getDeviceSignalsDiagnostics()` to explain partial/unsupported collection and `updateDeviceSignals()` for existing authenticated identities. Backfill does not register, reset trial consumption, change meters/seats or merge groups. Test permission/timeout/placeholder cases, interrupted registration with changed hardware, legacy backfill and wrong-product credentials. URL/product changes require coordinated state migration, not silent identity replacement. Hardware signals are forgeable hints; do not promise physical-device enforcement or offline seat transfer.
+
+License v4/trial v2 tokens are `base64url(JSON bytes).base64url(Ed25519 signature)`. The signature covers **decoded UTF-8 JSON bytes**, without reserialization. These are not JWTs. `verifySignedToken` authenticates payload/context even for negative statuses; it alone does not grant access. Prefer `getAuthorization` for permission.
+
+Pin approved SPKI public PEMs by `kid`. Never automatically trust keys fetched beside a token. Reject malformed payloads, unknown versions/kids, wrong issuer/product/installation/subject, implausible future issuance and invalid signatures. Paid access ends at the earlier of expiry and offline grace. A signed revoked/expired refresh can be HTTP 200: save it before evaluating access. Trial `spent`, allowance exhaustion and expiry fail closed. Trials use their own nullable expiry/allowance contract, not the paid offline-grace field. Offline revocation is bounded by the signed deadline; no client can promise immediate offline revocation or prevent all local tampering.
+
+## Optional communication
+
+Register first, then use `getNotifications()`, `setNotificationPreferences({messages, expirations})`, and `markNotificationRead(eventId)`. Poll while online, pause when backgrounded/offline, and back off on failures. There is no email/realtime delivery; collections are currently unpaginated at the server.
+
+`collectLicense(licenseId)` retrieves a key targeted to this installation. It does not activate it. Construct collection through the SDK instead of following arbitrary `collectPath` URLs with a credential.
+
+Use `listSupportThreads()`/`getSupportThread(id)`. `createSupportThread` takes `requestId`, `licenseId`, `category`, `urgency`, `subject`, `message`, `createdAt` and optional reporter/app metadata. The SDK sets `Idempotency-Key` to requestId. Technical/feature/other categories require an active binding; licensing/billing also permit existing expired/released bindings; trial-only installations cannot create cases.
+
+`replyToSupportThread(id, {requestId, revision, message})` requires the latest revision. Persist exact request/body in a durable host outbox before sending. On revision conflict reload and reconcile; on ambiguous timeout replay exactly. Customer replies reopen resolved/waiting cases, while closed cases require a new case. Internal notes and assignments remain server-private. Request-link secrets for preinstallation customers are separate from installation credentials. Usage metering uses a trusted backend's scoped service credential and is intentionally absent from this desktop SDK.