stovesdk.js 0.3.1 → 0.3.2

package/README.md

@@ -4,7 +4,7 @@ Unofficial Node.js / Electron bindings for the **STOVE PC SDK** (N-API).
 
 The STOVE PC SDK ships official bindings for C, C#, and C++ only. This project wraps the native SDK so Electron and Node.js games can use it the way `steamworks.js` wraps Steamworks.
 
-> **Status: alpha.** Install from npm as `stovesdk.js`; the Windows x64 prebuild ships inside the package and is also attached to each [GitHub release](https://github.com/firejune/stovesdk.js/releases). See *Install* and *Build* below.
+> **Status: alpha.** Install from npm as `stovesdk.js`; the Windows x64 prebuild ships inside the package and is also attached to each [GitHub release](https://github.com/Blosharper/stovesdk.js/releases). See *Install* and *Build* below.
 
 ## Scope
 
@@ -26,10 +26,10 @@ Windows x64 only, which matches the STOVE PC SDK itself. The addon targets N-API
 
 The STOVE PC SDK is **not** included in this repository and is not redistributed by this package.
 
-1. Download the STOVE PC SDK from the STOVE developer portal under your own developer account.
+1. Download the STOVE PC SDK from the STOVE developer portal under your own developer account — or run `node tools/fetch-sdk.js sdk`, which fetches the drop this module is built against (version, URLs and SHA-256 of each archive are pinned in [`tools/sdk-manifest.json`](tools/sdk-manifest.json); a checksum mismatch fails the fetch).
 2. Place it under [`sdk/`](sdk/README.md), or point `STOVE_PCSDK_DIR` at your copy. The expected layout is documented in `sdk/README.md`; `npm run check-sdk` tells you what is missing.
 
-Your use of the SDK is governed by STOVE's own terms.
+Your use of the SDK is governed by STOVE's own terms — the developer agreement of your STOVE Studio account. That the archives download without a credential does not make them redistributable, and this package does not redistribute them.
 
 ## Install
 
@@ -57,10 +57,10 @@ An Electron app usually ships the `.node` in its own resources, next to the thre
 ### Installing from a git tag instead
 
 ```sh
-npm install github:firejune/stovesdk.js#vX.Y.Z
+npm install github:Blosharper/stovesdk.js#vX.Y.Z
 ```
 
-installs the same package without the prebuild (binaries are not tracked in git). Download `stovesdk.node` and `SHA256SUMS` from the [GitHub release](https://github.com/firejune/stovesdk.js/releases) of the same version, check the sum (`sha256sum -c SHA256SUMS`, or `CertUtil -hashfile stovesdk.node SHA256`), and put the binary in one of the places above. (v0.1.0 still runs `node-gyp rebuild` on install; add `--ignore-scripts` for that one.)
+installs the same package without the prebuild (binaries are not tracked in git). Download `stovesdk.node` and `SHA256SUMS` from the [GitHub release](https://github.com/Blosharper/stovesdk.js/releases) of the same version, check the sum (`sha256sum -c SHA256SUMS`, or `CertUtil -hashfile stovesdk.node SHA256`), and put the binary in one of the places above. (v0.1.0 still runs `node-gyp rebuild` on install; add `--ignore-scripts` for that one.)
 
 Or build the binary yourself, below.
 
@@ -160,6 +160,24 @@ Notes:
 - A stat that has never been written reports `currentValue` as `-2147483648`. That is the SDK's own `int32` value, passed through unchanged.
 - Leave a moment between `uninitialize()` and the next `initialize()`. The STOVE client re-creates its side of the connection after a disconnect, and an immediate re-initialize can answer `{ status: 'restart' }`.
 
+### Coverage — what is wrapped and what is not
+
+The SDK drop has seven modules. This module links three and wraps the calls a shipping game has needed so far; the rest is listed so you know before you start, not after. Coverage grows by consumer request (ROADMAP), not by the size of the SDK — open an issue naming the SDK call and what the game needs it for.
+
+| SDK module | Wrapped | Not wrapped (present in the SDK) |
+| --- | --- | --- |
+| **BaseSDK** | initialize / uninitialize (`Base_RestartAppIfNecessaryAsync`, `Base_Initialize`, `Base_UnInitialize`), the callback pump (`Base_RunCallback`), login identity (`Base_GetUser`, `Base_GetGds`), `Base_GetVersion` | access tokens for a game server (`Base_GetAccessToken`, `Base_GetRenewToken`, `Base_AccessTokenRenewed`); `Base_SetLanguage`, `Base_SetGameProfile`; the launcher's shutdown request (`Base_GetShutdown`, `Base_ShutdownNotification`); over-immersion notices (`Base_GetOverImmersion`, `Base_OverImmersionNotification`); `Base_GetSignin`, `Base_GetTraceHint`; `Base_RunCallbackWithTimeout`; the synchronous `Base_RestartAppIfNecessary` |
+| **OwnershipSDK** | everything: `Ownership_OwnershipList` (with `Ownership_Initialize` / `Ownership_UnInitialize` managed for you) | — |
+| **GameSupportSDK** | achievements and stats (`GameSupport_Achievement`, `GameSupport_AllAchievement`, `GameSupport_Stat`, `GameSupport_ModifyStat`) | leaderboards (`GameSupport_Rank`) |
+| **ViewSDK** | — | the whole module: overlay and in-game popups |
+| **IAPSDK** | — | the whole module: in-game purchases |
+| **GamingServicesSDK** | — | the whole module |
+| **PCBangSDK** | — | the whole module (PC-café entitlements) |
+
+Not provided by the SDK at all, so not something this module can add: an achievement "unlock" call (achievements complete through their stat — see *Notes*), an achievement reset, cloud-save queries (cloud save is configured in STOVE Studio, not in code), controller input, and anything Steam-specific such as rich presence or workshop.
+
+Also out of scope by design, whatever the SDK offers: decisions on the caller's behalf — what to do when ownership fails, when to quit, what to show. The module reports; the game decides.
+
 ### Error codes
 
 Rejected Promises carry `step`, `sdk`, `method`, `code` and `externalError`. `code` is the SDK's own result code (unsigned) when the SDK answered, or one of these negative addon codes when the addon refused the call:
@@ -189,7 +207,7 @@ SDK callbacks are plain C function pointers with no user-data slot, and the vend
 
 ## Prebuilds, publishing and CI
 
-[`.github/workflows/prebuild.yml`](.github/workflows/prebuild.yml) is a manually triggered Windows x64 build that expects the SDK to be present on the runner at `STOVE_PCSDK_DIR`. Because the SDK is not public, the workflow does not download it; how CI gets the SDK is an open design question — see the workflow header for the options under consideration. Until it is settled, the prebuild is built by the maintainer and attached to the GitHub release.
+[`.github/workflows/prebuild.yml`](.github/workflows/prebuild.yml) is dispatched by hand for a release tag. On a GitHub-hosted Windows x64 runner it fetches the pinned SDK drop from the vendor's download CDN (verifying each archive's checksum first), builds the tagged commit, runs the load-only smoke and attaches `stovesdk.node` and `SHA256SUMS` to the GitHub release — nothing from the SDK leaves the runner. The smoke involves no STOVE client; it proves the addon links and loads, not that it talks to STOVE.
 
 [`.github/workflows/publish.yml`](.github/workflows/publish.yml) publishes a tagged release to npm, by manual dispatch once its prebuild is attached: it takes `stovesdk.node` from the GitHub release, checks it against `SHA256SUMS`, checks that the tarball carries that one binary and nothing from the SDK, and publishes over OIDC trusted publishing with provenance. [RELEASING.md](RELEASING.md) has the sequence.
 

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "stovesdk.js",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Unofficial Node.js / Electron bindings for the STOVE PC SDK (N-API)",
   "license": "MIT",
   "author": "firejune",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/firejune/stovesdk.js.git"
+    "url": "git+https://github.com/Blosharper/stovesdk.js.git"
   },
+  "bugs": {
+    "url": "https://github.com/Blosharper/stovesdk.js/issues"
+  },
+  "homepage": "https://github.com/Blosharper/stovesdk.js#readme",
   "keywords": [
     "stove",
     "pcsdk",

package/prebuilds/win32-x64/SHA256SUMS

@@ -1 +1 @@
-f9ac8af314ddee58b85b57836ac7703acae28184691ce5401757aff36b906210 *./stovesdk.node
+799924d339bf570c0fbddc3a00d4a5289216af8f80b85aa91fed0ecbc3ddd77b *./stovesdk.node

package/tools/fetch-sdk.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict'
+
+// Fetches the pinned STOVE PC SDK drop from the vendor's download CDN into a directory laid out
+// the way lib/sdk-dir.js expects, verifying every archive against tools/sdk-manifest.json first.
+//
+//   node tools/fetch-sdk.js <dest>            fetch, verify, extract into <dest>, validate the layout
+//   node tools/fetch-sdk.js <dest> --check    only validate an existing <dest> against the manifest
+//
+// What this encodes (issue #21):
+//   - The SDK version, the archive URLs and their SHA-256 are pinned in the manifest and reviewed
+//     like code. Nothing here derives a URL or accepts an unlisted module.
+//   - Every archive is hashed before anything is extracted. A mismatch fails the whole fetch: no
+//     other version is tried, no hash is rewritten, nothing from that archive touches <dest>.
+//   - <dest> must be empty or absent, so two drops never mix; archives are downloaded under it and
+//     deleted after extraction, so nothing is cached between runs.
+//   - The vendor's zips unpack to `Deploy/…` with no module folder, so each one is extracted into
+//     <dest>/<Module>/; that is the layout sdk/README.md documents and binding.gyp reads.
+//   - The extracted files are the vendor's. This tool puts them in a build directory and nowhere
+//     else — never into the repository, a package or a release.
+
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+const { execFileSync } = require('child_process')
+const { SDK_MODULES, missingSdkFiles } = require('../lib/sdk-dir')
+
+const MANIFEST_FILE = path.join(__dirname, 'sdk-manifest.json')
+
+// Problems with a manifest object (empty = usable). Checked before any network access.
+function checkManifest(manifest) {
+  const problems = []
+  if (!manifest || typeof manifest !== 'object') return ['manifest is not an object']
+  if (typeof manifest.version !== 'string' || !/^\d+(\.\d+)+$/.test(manifest.version)) problems.push('version must be a dotted version string')
+  const modules = manifest.modules && typeof manifest.modules === 'object' ? manifest.modules : null
+  if (!modules) return [...problems, 'modules must be an object']
+  const names = Object.keys(modules)
+  for (const mod of SDK_MODULES) if (!names.includes(mod)) problems.push(`modules.${mod} is missing`)
+  for (const name of names) {
+    if (!SDK_MODULES.includes(name)) problems.push(`modules.${name} is not an SDK module this addon links (${SDK_MODULES.join(', ')})`)
+    const entry = modules[name]
+    if (!entry || typeof entry !== 'object') { problems.push(`modules.${name} must be an object`); continue }
+    if (typeof entry.url !== 'string' || !/^https:\/\/[^\s]+\.zip$/.test(entry.url)) problems.push(`modules.${name}.url must be an https URL to a .zip`)
+    if (typeof entry.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(entry.sha256)) problems.push(`modules.${name}.sha256 must be 64 lowercase hex characters`)
+  }
+  return problems
+}
+
+function loadManifest(file = MANIFEST_FILE) {
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
+  const problems = checkManifest(manifest)
+  if (problems.length) {
+    const err = new Error(`[stovesdk] ${path.basename(file)} is not usable:\n${problems.map(p => `  - ${p}`).join('\n')}`)
+    err.code = 'STOVE_PCSDK_SDK_MANIFEST'
+    throw err
+  }
+  return manifest
+}
+
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex')
+}
+
+// Throws (code STOVE_PCSDK_SDK_CHECKSUM_MISMATCH) unless the archive bytes hash to the pinned value.
+function verifyArchive(buffer, module, expected, url) {
+  const actual = sha256Hex(buffer)
+  if (actual === expected) return actual
+  const err = new Error(
+    `[stovesdk] ${module}: SHA-256 mismatch for ${url}\n  expected ${expected}\n  actual   ${actual}\n` +
+      'The archive is not the pinned drop. Nothing was extracted. If the vendor re-published this version, ' +
+      'review the change and update tools/sdk-manifest.json in a pull request of its own.'
+  )
+  err.code = 'STOVE_PCSDK_SDK_CHECKSUM_MISMATCH'
+  err.module = module
+  err.expected = expected
+  err.actual = actual
+  throw err
+}
+
+async function downloadBuffer(url) {
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) {
+    const err = new Error(`[stovesdk] download failed: HTTP ${res.status} for ${url}`)
+    err.code = 'STOVE_PCSDK_SDK_DOWNLOAD'
+    throw err
+  }
+  return Buffer.from(await res.arrayBuffer())
+}
+
+// bsdtar reads zip archives. On Windows it is System32\tar.exe (Windows 10 1803+), named in full
+// because a Git Bash PATH puts GNU tar — which does not read zip — in front of it. Elsewhere `tar`
+// is bsdtar on macOS; on Linux, where GNU tar is the default, `unzip` is tried next.
+function extractZip(zipFile, dir) {
+  fs.mkdirSync(dir, { recursive: true })
+  if (process.platform === 'win32') {
+    const tar = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe')
+    execFileSync(tar, ['-xf', zipFile, '-C', dir], { stdio: 'inherit' })
+    return
+  }
+  try {
+    execFileSync('tar', ['-xf', zipFile, '-C', dir], { stdio: ['ignore', 'inherit', 'pipe'] })
+  } catch (tarErr) {
+    try {
+      execFileSync('unzip', ['-q', '-o', zipFile, '-d', dir], { stdio: 'inherit' })
+    } catch {
+      const err = new Error(`[stovesdk] could not extract ${zipFile}: need bsdtar or unzip (tar said: ${String(tarErr.stderr || tarErr.message).trim()})`)
+      err.code = 'STOVE_PCSDK_SDK_EXTRACT'
+      throw err
+    }
+  }
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true
+  return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0
+}
+
+function layoutError(dest, missing) {
+  const err = new Error(`[stovesdk] SDK layout incomplete at ${dest}. Missing:\n${missing.map(f => `  - ${f}`).join('\n')}`)
+  err.code = 'STOVE_PCSDK_SDK_LAYOUT'
+  err.missing = missing
+  return err
+}
+
+// Fetches, verifies and extracts every module of the manifest into `dest`. Resolves with a summary.
+// `download` and `extract` are injectable so the rules above can be tested without the network.
+async function fetchSdk(dest, { manifest = loadManifest(), download = downloadBuffer, extract = extractZip, log = () => {} } = {}) {
+  const problems = checkManifest(manifest)
+  if (problems.length) {
+    const err = new Error(`[stovesdk] manifest is not usable:\n${problems.map(p => `  - ${p}`).join('\n')}`)
+    err.code = 'STOVE_PCSDK_SDK_MANIFEST'
+    throw err
+  }
+  dest = path.resolve(dest)
+  if (!isEmptyDir(dest)) {
+    const err = new Error(`[stovesdk] ${dest} exists and is not empty. The fetch only fills an empty directory, so two drops never mix.`)
+    err.code = 'STOVE_PCSDK_SDK_DEST_NOT_EMPTY'
+    throw err
+  }
+  fs.mkdirSync(dest, { recursive: true })
+  const downloads = path.join(dest, '.download')
+  fs.mkdirSync(downloads)
+  const modules = []
+  try {
+    for (const module of SDK_MODULES) {
+      const { url, sha256 } = manifest.modules[module]
+      log(`[stovesdk] ${module}: downloading ${url}`)
+      const buffer = await download(url)
+      verifyArchive(buffer, module, sha256, url)
+      log(`[stovesdk] ${module}: ${buffer.length} bytes, SHA-256 ${sha256} OK`)
+      const zipFile = path.join(downloads, `${module}.zip`)
+      fs.writeFileSync(zipFile, buffer)
+      extract(zipFile, path.join(dest, module))
+      fs.rmSync(zipFile, { force: true })
+      modules.push({ module, url, sha256, bytes: buffer.length })
+    }
+  } finally {
+    fs.rmSync(downloads, { recursive: true, force: true })
+  }
+  fs.writeFileSync(path.join(dest, 'VERSION'), `${manifest.version}\n`)
+  const missing = missingSdkFiles(dest)
+  if (missing.length) throw layoutError(dest, missing)
+  return { dest, version: manifest.version, modules }
+}
+
+module.exports = { MANIFEST_FILE, checkManifest, loadManifest, sha256Hex, verifyArchive, fetchSdk }
+
+if (require.main === module) {
+  const args = process.argv.slice(2)
+  const check = args.includes('--check')
+  const dest = args.find(a => !a.startsWith('--'))
+  if (!dest) {
+    console.error('usage: node tools/fetch-sdk.js <dest> [--check]')
+    process.exit(2)
+  }
+  if (check) {
+    const manifest = loadManifest()
+    const missing = missingSdkFiles(path.resolve(dest))
+    if (missing.length) { console.error(layoutError(path.resolve(dest), missing).message); process.exit(1) }
+    const version = fs.existsSync(path.join(dest, 'VERSION')) ? fs.readFileSync(path.join(dest, 'VERSION'), 'utf8').trim() : 'unknown'
+    if (version !== manifest.version) { console.error(`[stovesdk] ${dest} holds SDK ${version}, the manifest pins ${manifest.version}`); process.exit(1) }
+    console.log(`[stovesdk] SDK ${version} complete at ${path.resolve(dest)}`)
+    process.exit(0)
+  }
+  fetchSdk(dest, { log: console.log })
+    .then(summary => {
+      console.log(`[stovesdk] SDK ${summary.version} ready at ${summary.dest} (${summary.modules.length} modules, ${summary.modules.reduce((n, m) => n + m.bytes, 0)} bytes downloaded, archives removed)`)
+    })
+    .catch(err => {
+      console.error(err && err.message ? err.message : err)
+      process.exit(1)
+    })
+}

package/tools/sdk-manifest.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "The STOVE PC SDK drop that tools/fetch-sdk.js fetches and verifies (issue #21). Reviewed like code: the version is the one the addon has been built and smoke-tested against, and a change here is a pull request of its own, never combined with an addon change. Each archive is checked against its SHA-256 before extraction; a mismatch fails the fetch and nothing is substituted. The files are the vendor's and are never committed, packed or redistributed.",
+  "version": "3.3.2.19",
+  "source": "STOVE developer-center download CDN (the links behind the PC SDK download page)",
+  "modules": {
+    "BaseSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/BaseSDK_3.3.2.19.zip",
+      "sha256": "92e9a0e0a8522c8ef176769695f79aca89de33ae67c27f7c2f41fd26035f5faa"
+    },
+    "OwnershipSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/OwnershipSDK_3.3.2.19.zip",
+      "sha256": "b542032b9a4a53a2e7d3fdda7a871aeef4a9ea9222cd149deea60b0c29810409"
+    },
+    "GameSupportSDK": {
+      "url": "https://d2x8kymwjom7h7.cloudfront.net/live/application_no/STATIC/developer-center/Store/GameSupportSDK_3.3.2.19.zip",
+      "sha256": "ad3a339fbe28055a88839428333700efa34f3a59590dc3a67583145f437f25e9"
+    }
+  }
+}

package/tools/syntax-check.sh

@@ -5,6 +5,12 @@
 # nothing is linked, and MSVC-only behaviour is not exercised.
 #
 #   sh tools/syntax-check.sh            (needs: clang++, node_modules/node-addon-api, Node headers)
+#
+# The SDK root is passed with -iquote, not -I: the vendor headers include each other with quoted
+# paths relative to that root ("BaseSDK/Deploy/Include/…"), and a plain -I would also let the C++
+# standard library's `#include <version>` resolve to the drop's VERSION file on a case-insensitive
+# file system (macOS, Windows). binding.gyp's include_dirs are unaffected — MSVC builds have passed
+# with VERSION present.
 set -eu
 
 ROOT=$(cd "$(dirname "$0")/.." && pwd)
@@ -29,6 +35,6 @@ clang++ -fsyntax-only -std=c++17 -fshort-wchar -fdeclspec -fms-extensions \
   -Wno-ignored-attributes -Wno-microsoft -Wno-pragma-pack \
   -DSTOVE_PCSDK_SYNTAX_CHECK -DNAPI_VERSION=8 -DNAPI_DISABLE_CPP_EXCEPTIONS \
   -I "$STUB" -I "$NAPI_INC" -I "$NODE_INC" \
-  -I "$SDK_DIR" -I "$SDK_DIR/BaseSDK/Deploy/Include" -I "$SDK_DIR/OwnershipSDK/Deploy/Include" -I "$SDK_DIR/GameSupportSDK/Deploy/Include" \
+  -iquote "$SDK_DIR" -I "$SDK_DIR/BaseSDK/Deploy/Include" -I "$SDK_DIR/OwnershipSDK/Deploy/Include" -I "$SDK_DIR/GameSupportSDK/Deploy/Include" \
   "$ROOT/src/stovesdk.cc"
 echo "[syntax-check] OK: src/stovesdk.cc parses against the SDK headers at $SDK_DIR"