@vlydev/cs2-masked-inspect 1.0.0 → 1.0.7

package/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      id-token: write  # required for npm trusted publishing (OIDC)
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          npm version "$VERSION" --no-git-tag-version
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance

package/README.md

@@ -98,6 +98,24 @@ InspectLink.isClassic(classicUrl); // true
 
 ---
 
+## Validation rules
+
+`deserialize()` enforces:
+
+| Rule | Limit | Error |
+|------|-------|-------|
+| Hex payload length | max 4,096 characters | `RangeError` |
+| Protobuf field count | max 100 per message | `RangeError` |
+
+`serialize()` enforces:
+
+| Field | Constraint | Error |
+|-------|-----------|-------|
+| `paintWear` | `[0.0, 1.0]` | `RangeError` |
+| `customName` | max 100 characters | `RangeError` |
+
+---
+
 ## How the format works
 
 Three URL formats are handled:

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@vlydev/cs2-masked-inspect",
-  "version": "1.0.0",
+  "version": "1.0.7",
   "description": "Offline decoder/encoder for CS2 masked inspect URLs — pure JavaScript, no dependencies",
   "main": "index.js",
   "scripts": {
     "test": "node --test tests/inspect_link.test.js"
   },
-  "keywords": ["cs2", "csgo", "inspect", "protobuf", "steam"],
+  "keywords": [
+    "cs2",
+    "csgo",
+    "inspect",
+    "protobuf",
+    "steam"
+  ],
   "author": {
     "name": "VlyDev",
     "email": "vladdnepr1989@gmail.com",
     "url": "https://github.com/vlydev"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vlydev/cs2-masked-inspect-js"
+  },
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/InspectLink.js

@@ -102,11 +102,14 @@ function extractHex(input) {
   const mh = stripped.match(HYBRID_URL_RE);
   if (mh && /[A-Fa-f]/.test(mh[1])) return mh[1];
 
-  // Classic/market URL: A<hex> preceded by %20, space, or + (A is a prefix marker, not hex)
+  // Classic/market URL: A<hex> preceded by %20, space, or + (A is a prefix marker, not hex).
+  // If stripping A yields odd-length hex, A is actually the first byte of the payload —
+  // fall through to the pure-masked check below which captures it with A included.
   const m = stripped.match(INSPECT_URL_RE);
-  if (m) return m[1];
+  if (m && m[1].length % 2 === 0) return m[1];
 
-  // Pure masked format: csgo_econ_action_preview%20<hexblob> (no S/A/M prefix)
+  // Pure masked format: csgo_econ_action_preview%20<hexblob> (no S/A/M prefix).
+  // Also handles payloads whose first hex character happens to be A.
   const mm = stripped.match(/csgo_econ_action_preview(?:%20|\s|\+)([0-9A-Fa-f]{10,})$/i);
   if (mm) return mm[1];
 
@@ -131,6 +134,7 @@ function encodeSticker(s) {
   if (s.offsetY  !== null) w.writeFloat32Fixed(8, s.offsetY);
   if (s.offsetZ  !== null) w.writeFloat32Fixed(9, s.offsetZ);
   w.writeUint32(10, s.pattern);
+  if (s.highlightReel != null) w.writeUint32(11, s.highlightReel);
   return w.toBytes();
 }
 
@@ -150,7 +154,8 @@ function decodeSticker(data) {
       case 7:  s.offsetX   = f.value.readFloatLE(0); break;
       case 8:  s.offsetY   = f.value.readFloatLE(0); break;
       case 9:  s.offsetZ   = f.value.readFloatLE(0); break;
-      case 10: s.pattern   = Number(f.value); break;
+      case 10: s.pattern      = Number(f.value); break;
+      case 11: s.highlightReel = Number(f.value); break;
       default: break;
     }
   }
@@ -173,8 +178,9 @@ function encodeItem(item) {
   w.writeUint32(6, item.quality);
 
   // paintwear: float32 reinterpreted as uint32 varint
-  const pwUint32 = float32ToUint32(item.paintWear);
-  w.writeUint32(7, pwUint32);
+  if (item.paintWear != null) {
+    w.writeUint32(7, float32ToUint32(item.paintWear));
+  }
 
   w.writeUint32(8, item.paintSeed);
   w.writeUint32(9, item.killEaterScoreType);
@@ -249,6 +255,16 @@ class InspectLink {
    * @returns {string} uppercase hex string
    */
   static serialize(data) {
+    if (data.paintWear != null && (data.paintWear < 0.0 || data.paintWear > 1.0)) {
+      throw new RangeError(
+        `paintwear must be in [0.0, 1.0], got ${data.paintWear}`,
+      );
+    }
+    if (data.customName != null && data.customName.length > 100) {
+      throw new RangeError(
+        `customname must not exceed 100 characters, got ${data.customName.length}`,
+      );
+    }
     const protoBytes = encodeItem(data);
     const buffer     = Buffer.concat([Buffer.from([0x00]), protoBytes]);
     const checksum   = computeChecksum(buffer, protoBytes.length);
@@ -291,6 +307,11 @@ class InspectLink {
    */
   static deserialize(input) {
     const hex = extractHex(input);
+    if (hex.length > 4096) {
+      throw new RangeError(
+        `Payload too long (max 4096 hex chars): "${input.slice(0, 64)}..."`,
+      );
+    }
     const raw = Buffer.from(hex, 'hex');
 
     if (raw.length < 6) {

package/src/ItemPreviewData.js

@@ -21,7 +21,7 @@ class ItemPreviewData {
    * @param {number}  [opts.paintIndex=0]
    * @param {number}  [opts.rarity=0]
    * @param {number}  [opts.quality=0]
-   * @param {number}  [opts.paintWear=0.0]
+   * @param {number|null} [opts.paintWear=null]
    * @param {number}  [opts.paintSeed=0]
    * @param {number}  [opts.killEaterScoreType=0]
    * @param {number}  [opts.killEaterValue=0]
@@ -43,7 +43,7 @@ class ItemPreviewData {
     paintIndex = 0,
     rarity = 0,
     quality = 0,
-    paintWear = 0.0,
+    paintWear = null,
     paintSeed = 0,
     killEaterScoreType = 0,
     killEaterValue = 0,

package/src/Sticker.js

@@ -19,6 +19,7 @@ class Sticker {
    * @param {number|null} [opts.offsetY=null]
    * @param {number|null} [opts.offsetZ=null]
    * @param {number}  [opts.pattern=0]
+   * @param {number|null} [opts.highlightReel=null]
    */
   constructor({
     slot = 0,
@@ -31,6 +32,7 @@ class Sticker {
     offsetY = null,
     offsetZ = null,
     pattern = 0,
+    highlightReel = null,
   } = {}) {
     this.slot = slot;
     this.stickerId = stickerId;
@@ -42,6 +44,7 @@ class Sticker {
     this.offsetY = offsetY;
     this.offsetZ = offsetZ;
     this.pattern = pattern;
+    this.highlightReel = highlightReel;
   }
 }
 

package/src/proto/reader.js

@@ -94,8 +94,12 @@ class ProtoReader {
    */
   readAllFields() {
     const fields = [];
+    let fieldCount = 0;
 
     while (this.remaining() > 0) {
+      if (++fieldCount > 100) {
+        throw new RangeError('Protobuf field count exceeds limit of 100');
+      }
       const [fieldNum, wireType] = this.readTag();
 
       let value;

package/tests/inspect_link.test.js

@@ -359,3 +359,91 @@ describe('checksum', () => {
     assert.equal(InspectLink.serialize(data), TOOL_HEX);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Defensive validation tests
+// ---------------------------------------------------------------------------
+
+describe('deserialize — payload too long', () => {
+  test('throws RangeError for hex payload exceeding 4096 chars (4098 chars)', () => {
+    const longHex = '00'.repeat(2049); // 4098 hex chars
+    assert.throws(() => InspectLink.deserialize(longHex), RangeError);
+  });
+});
+
+describe('serialize — paintwear validation', () => {
+  test('throws RangeError when paintwear > 1.0', () => {
+    const data = new ItemPreviewData({ paintWear: 1.1 });
+    assert.throws(() => InspectLink.serialize(data), RangeError);
+  });
+
+  test('throws RangeError when paintwear < 0.0', () => {
+    const data = new ItemPreviewData({ paintWear: -0.1 });
+    assert.throws(() => InspectLink.serialize(data), RangeError);
+  });
+
+  test('does not throw when paintwear = 0.0 (boundary)', () => {
+    const data = new ItemPreviewData({ paintWear: 0.0 });
+    assert.doesNotThrow(() => InspectLink.serialize(data));
+  });
+
+  test('does not throw when paintwear = 1.0 (boundary)', () => {
+    const data = new ItemPreviewData({ paintWear: 1.0 });
+    assert.doesNotThrow(() => InspectLink.serialize(data));
+  });
+});
+
+describe('serialize — customname validation', () => {
+  test('throws RangeError when customName is 101 characters', () => {
+    const data = new ItemPreviewData({ customName: 'a'.repeat(101) });
+    assert.throws(() => InspectLink.serialize(data), RangeError);
+  });
+
+  test('does not throw when customName is exactly 100 characters', () => {
+    const data = new ItemPreviewData({ customName: 'a'.repeat(100) });
+    assert.doesNotThrow(() => InspectLink.serialize(data));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CSFloat/gen.test.ts vectors
+// ---------------------------------------------------------------------------
+
+const CSFLOAT_A = '00180720DA03280638FBEE88F90340B2026BC03C96';
+const CSFLOAT_B = '00180720C80A280638A4E1F5FB03409A0562040800104C62040801104C62040802104C62040803104C6D4F5E30';
+const CSFLOAT_C = 'A2B2A2BA69A882A28AA192AECAA2D2B700A3A5AAA2B286FA7BA0D684BE72';
+
+describe('CSFloat test vectors', () => {
+  test('VectorA: defindex', () => assert.equal(InspectLink.deserialize(CSFLOAT_A).defIndex, 7));
+  test('VectorA: paintindex', () => assert.equal(InspectLink.deserialize(CSFLOAT_A).paintIndex, 474));
+  test('VectorA: paintseed', () => assert.equal(InspectLink.deserialize(CSFLOAT_A).paintSeed, 306));
+  test('VectorA: rarity', () => assert.equal(InspectLink.deserialize(CSFLOAT_A).rarity, 6));
+  test('VectorA: paintwear not null', () => assert.notEqual(InspectLink.deserialize(CSFLOAT_A).paintWear, null));
+  test('VectorA: paintwear approx', () => assert.ok(Math.abs(InspectLink.deserialize(CSFLOAT_A).paintWear - 0.6337) < 0.001));
+
+  test('VectorB: 4 stickers', () => assert.equal(InspectLink.deserialize(CSFLOAT_B).stickers.length, 4));
+  test('VectorB: sticker ids all 76', () => {
+    InspectLink.deserialize(CSFLOAT_B).stickers.forEach(s => assert.equal(s.stickerId, 76));
+  });
+  test('VectorB: paintindex', () => assert.equal(InspectLink.deserialize(CSFLOAT_B).paintIndex, 1352));
+  test('VectorB: paintwear approx 0.99', () => assert.ok(Math.abs(InspectLink.deserialize(CSFLOAT_B).paintWear - 0.99) < 0.01));
+
+  test('VectorC: defindex', () => assert.equal(InspectLink.deserialize(CSFLOAT_C).defIndex, 1355));
+  test('VectorC: quality', () => assert.equal(InspectLink.deserialize(CSFLOAT_C).quality, 12));
+  test('VectorC: keychain count', () => assert.equal(InspectLink.deserialize(CSFLOAT_C).keychains.length, 1));
+  test('VectorC: keychain highlightReel', () => assert.equal(InspectLink.deserialize(CSFLOAT_C).keychains[0].highlightReel, 345));
+  test('VectorC: no paintwear', () => assert.equal(InspectLink.deserialize(CSFLOAT_C).paintWear, null));
+});
+
+describe('Roundtrip: highlight_reel and nullable paintWear', () => {
+  test('highlightReel roundtrip', () => {
+    const data = new ItemPreviewData({ defIndex: 7, keychains: [new Sticker({ slot: 0, stickerId: 36, highlightReel: 345 })] });
+    const result = InspectLink.deserialize(InspectLink.serialize(data));
+    assert.equal(result.keychains[0].highlightReel, 345);
+  });
+  test('null paintWear roundtrip', () => {
+    const data = new ItemPreviewData({ defIndex: 7, paintWear: null });
+    const result = InspectLink.deserialize(InspectLink.serialize(data));
+    assert.equal(result.paintWear, null);
+  });
+});