buffer-equal-constant-time 1.0.1: install

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify buffer-equal-constant-time.install in pkg:npm/buffer-equal-constant-time@1.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/buffer-equal-constant-time@1.0.1
Demonstrate these symbols/APIs:
  - buffer-equal-constant-time.install

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:4de35d70c27ce5784af9bb9f31722571a5487195bb288c8745db4ec8a77cded3","constraints":{"executionContext":"node"},"contract":["bufferEq.install attaches equal method to Buffer prototype and SlowBuffer prototype","Buffer.prototype.equal returns true for identical Buffer instances","Buffer.prototype.equal returns false for Buffers with different content","Buffer.prototype.equal returns false for Buffers of different lengths","Buffer.prototype.equal returns false when comparing a Buffer to non-Buffer values","SlowBuffer.prototype.equal accurately compares SlowBuffer and standard Buffer instances","bufferEq.restore removes or restores previous equal methods on Buffer and SlowBuffer prototypes","bufferEq standalone function performs constant-time equality check on two Buffers"],"goal":"verify buffer-equal-constant-time.install in pkg:npm/buffer-equal-constant-time@1.0.1","kind":"HOW","packages":["pkg:npm/buffer-equal-constant-time@1.0.1"],"schemaVersion":1,"symbols":["buffer-equal-constant-time.install"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/buffer-equal-constant-time@1.0.1"],"schemaVersion":1,"subject":"pkg:npm/buffer-equal-constant-time@1.0.1","symbols":["buffer-equal-constant-time.install"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-buffer-equal-constant-time",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-buffer-equal-constant-time",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "buffer-equal-constant-time": "1.0.1"
      }
    },
    "node_modules/buffer-equal-constant-time": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
      "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==",
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-buffer-equal-constant-time",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for buffer-equal-constant-time@1.0.1",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "buffer-equal-constant-time": "1.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify buffer-equal-constant-time.install in pkg:npm/buffer-equal-constant-time@1.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/buffer-equal-constant-time@1.0.1"
  ],
  "symbols": [
    "buffer-equal-constant-time.install"
  ]
}

const bufferEq = require("buffer-equal-constant-time");

/**
 * Installs the constant-time equal method onto Buffer and SlowBuffer prototypes.
 */
function installBufferEqual() {
  bufferEq.install();
}

/**
 * Restores original prototype equal methods.
 */
function restoreBufferEqual() {
  bufferEq.restore();
}

/**
 * Compares two buffers directly using buffer-equal-constant-time without installing on prototype.
 *
 * @param {Buffer} a - First buffer.
 * @param {Buffer} b - Second buffer.
 * @returns {boolean} True if buffers are equal, false otherwise.
 */
function compareDirect(a, b) {
  return bufferEq(a, b);
}

module.exports = {
  bufferEq,
  installBufferEqual,
  restoreBufferEqual,
  compareDirect
};

import assert from "node:assert/strict";
import { createRequire } from "node:module";
import { Buffer, SlowBuffer } from "node:buffer";

const require = createRequire(import.meta.url);
const {
  bufferEq,
  installBufferEqual,
  restoreBufferEqual,
  compareDirect
} = require("../src/index.js");

async function testAll() {
  // Test direct compare function
  const b1 = Buffer.from("secret-token-1234");
  const b2 = Buffer.from("secret-token-1234");
  const b3 = Buffer.from("secret-token-5678");
  const b4 = Buffer.from("short");

  assert.equal(compareDirect(b1, b2), true, "Identical buffers must be equal");
  assert.equal(compareDirect(b1, b3), false, "Different buffers must not be equal");
  assert.equal(compareDirect(b1, b4), false, "Different length buffers must not be equal");
  assert.equal(compareDirect(b1, "secret-token-1234"), false, "Non-buffer comparison must return false");
  assert.equal(compareDirect(null, b2), false, "Null comparison must return false");

  // Test bufferEq.install()
  installBufferEqual();

  assert.equal(typeof Buffer.prototype.equal, "function", "Buffer.prototype.equal must be a function after install");
  assert.equal(typeof SlowBuffer.prototype.equal, "function", "SlowBuffer.prototype.equal must be a function after install");

  // Buffer.prototype.equal tests
  const bufA = Buffer.from("secure-hash-abc");
  const bufB = Buffer.from("secure-hash-abc");
  const bufC = Buffer.from("secure-hash-xyz");
  const bufD = Buffer.from("secure");

  assert.equal(bufA.equal(bufB), true, "Buffer.prototype.equal returns true for identical Buffer instances");
  assert.equal(bufA.equal(bufC), false, "Buffer.prototype.equal returns false for Buffers with different content");
  assert.equal(bufA.equal(bufD), false, "Buffer.prototype.equal returns false for Buffers of different lengths");
  assert.equal(bufA.equal("secure-hash-abc"), false, "Buffer.prototype.equal returns false when comparing a Buffer to string");
  assert.equal(bufA.equal({}), false, "Buffer.prototype.equal returns false when comparing a Buffer to object");
  assert.equal(bufA.equal(null), false, "Buffer.prototype.equal returns false when comparing a Buffer to null");
  assert.equal(bufA.equal(undefined), false, "Buffer.prototype.equal returns false when comparing a Buffer to undefined");

  // SlowBuffer comparison test
  const slowA = new SlowBuffer(4);
  slowA.write("test");
  const slowB = new SlowBuffer(4);
  slowB.write("test");
  const slowC = new SlowBuffer(4);
  slowC.write("diff");
  const standardBuf = Buffer.from("test");

  assert.equal(slowA.equal(slowB), true, "SlowBuffer.prototype.equal returns true for identical SlowBuffer instances");
  assert.equal(slowA.equal(slowC), false, "SlowBuffer.prototype.equal returns false for different SlowBuffer instances");
  assert.equal(slowA.equal(standardBuf), true, "SlowBuffer.prototype.equal accurately compares SlowBuffer and standard Buffer");
  assert.equal(standardBuf.equal(slowA), true, "Buffer.prototype.equal accurately compares standard Buffer and SlowBuffer");

  // Test bufferEq.restore()
  restoreBufferEqual();

  // Verify restore behavior
  assert.equal(Buffer.prototype.equal, undefined, "Buffer.prototype.equal is restored");
  assert.equal(SlowBuffer.prototype.equal, undefined, "SlowBuffer.prototype.equal is restored");

  console.log("All buffer-equal-constant-time contract tests passed successfully.");
}

testAll().catch((err) => {
  console.error("Contract test failure:", err);
  process.exit(1);
});