plist 3.1.0

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 pkg:npm/plist@3.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/plist@3.1.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:3a9d995dbc9e24a08a1ee0c2f21a0eabf812e7479dd2103a72e531b1016b4477","constraints":{"executionContext":"node"},"contract":["plist.build serializes JavaScript primitives, objects, and arrays into valid XML plist format","plist.parse parses XML plist strings containing strings, integers, reals, dates, buffers, and booleans","plist.build and plist.parse preserve nested data structures across round-trip serialization","plist.build properly escapes special XML characters in dictionary keys and string values","plist.parse throws an error when given invalid or malformed XML without a plist root element","plist.parse ignores __proto__ keys to prevent prototype pollution vulnerabilities"],"goal":"verify pkg:npm/plist@3.1.0","kind":"HOW","packages":["pkg:npm/plist@3.1.0"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"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/plist@3.1.0"],"schemaVersion":1,"subject":"pkg:npm/plist@3.1.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-plist-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-plist-verify",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "plist": "3.1.0"
      }
    },
    "node_modules/@xmldom/xmldom": {
      "version": "0.8.15",
      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.15.tgz",
      "integrity": "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      }
    },
    "node_modules/base64-js": {
      "version": "1.5.1",
      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/plist": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/plist/-/plist-3.1.0.tgz",
      "integrity": "sha512-uysumyrvkUX0rX/dEVqt8gC3sTBzd4zoWfLeS29nb53imdaXVvLINYXTI2GNqzaMuvacNx4uJQ8+b3zXR0pkgQ==",
      "license": "MIT",
      "dependencies": {
        "@xmldom/xmldom": "^0.8.8",
        "base64-js": "^1.5.1",
        "xmlbuilder": "^15.1.1"
      },
      "engines": {
        "node": ">=10.4.0"
      }
    },
    "node_modules/xmlbuilder": {
      "version": "15.1.1",
      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
      "integrity": "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==",
      "license": "MIT",
      "engines": {
        "node": ">=8.0"
      }
    }
  }
}

{
  "name": "sample-plist-verify",
  "version": "1.0.0",
  "description": "verify pkg:npm/plist@3.1.0",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "plist": "3.1.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/plist@3.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/plist@3.1.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const plist = require('plist');

/**
 * Builds an XML Property List string from JavaScript data.
 *
 * @param {*} data - JavaScript data structure to serialize.
 * @param {object} [options] - Optional formatting options.
 * @returns {string} The formatted XML Property List document string.
 */
function buildPlist(data, options) {
  return plist.build(data, options);
}

/**
 * Parses an XML Property List string into a JavaScript data structure.
 *
 * @param {string} xml - The XML string to parse.
 * @returns {*} The parsed JavaScript structure.
 */
function parsePlist(xml) {
  return plist.parse(xml);
}

module.exports = {
  buildPlist,
  parsePlist,
};

const assert = require('node:assert/strict');
const plist = require('plist');
const { buildPlist, parsePlist } = require('../src/index.js');

// Contract 1: plist.build serializes JavaScript primitives, objects, and arrays into valid XML plist format
{
  const data = {
    title: 'CodeSampleX Configuration',
    version: 1,
    enabled: true,
    tags: ['core', 'parser'],
  };
  const xml = buildPlist(data);

  assert.ok(xml.includes('<?xml version="1.0" encoding="UTF-8"?>'), 'Must include standard XML declaration');
  assert.ok(xml.includes('DOCTYPE plist PUBLIC') && xml.includes('PropertyList-1.0.dtd'), 'Must include Apple plist DOCTYPE');
  assert.ok(xml.includes('<plist version="1.0">'), 'Must include plist root element');
  assert.ok(xml.includes('<dict>'), 'Objects must serialize as dict');
  assert.ok(xml.includes('<key>title</key>'), 'Object keys must serialize as key elements');
  assert.ok(xml.includes('<string>CodeSampleX Configuration</string>'), 'Strings must serialize as string elements');
  assert.ok(xml.includes('<integer>1</integer>'), 'Integers must serialize as integer elements');
  assert.ok(xml.includes('<true/>'), 'Booleans must serialize as true/false self-closing tags');
  assert.ok(xml.includes('<array>'), 'Arrays must serialize as array elements');
}

// Contract 2: plist.parse parses XML plist strings containing strings, integers, reals, dates, buffers, and booleans
{
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>name</key>
  <string>Sample Project</string>
  <key>count</key>
  <integer>100</integer>
  <key>ratio</key>
  <real>2.718</real>
  <key>active</key>
  <true/>
  <key>archived</key>
  <false/>
  <key>createdAt</key>
  <date>2026-08-27T16:00:00Z</date>
  <key>payload</key>
  <data>SGVsbG8gV29ybGQ=</data>
</dict>
</plist>`;

  const result = parsePlist(xml);
  assert.strictEqual(result.name, 'Sample Project');
  assert.strictEqual(result.count, 100);
  assert.strictEqual(result.ratio, 2.718);
  assert.strictEqual(result.active, true);
  assert.strictEqual(result.archived, false);
  assert.ok(result.createdAt instanceof Date);
  assert.strictEqual(result.createdAt.toISOString(), '2026-08-27T16:00:00.000Z');
  assert.ok(Buffer.isBuffer(result.payload));
  assert.strictEqual(result.payload.toString('utf8'), 'Hello World');
}

// Contract 3: plist.build and plist.parse preserve nested data structures across round-trip serialization
{
  const original = {
    service: 'CodeSampleX',
    metadata: {
      version: 3,
      tags: ['alpha', 'beta'],
      metrics: {
        score: 99.5,
      },
    },
    items: [
      { id: 1, label: 'first' },
      { id: 2, label: 'second' },
    ],
  };

  const xml = buildPlist(original);
  const parsed = parsePlist(xml);

  assert.deepStrictEqual(parsed, original, 'Round-trip parsing must preserve nested data structure');
}

// Contract 4: plist.build properly escapes special XML characters in dictionary keys and string values
{
  const specialData = {
    'custom&key<1>': 'AT&T <wireless> "quoted" \'single\'',
  };

  const xml = buildPlist(specialData);
  assert.ok(xml.includes('&amp;'), 'Ampersands must be escaped');
  assert.ok(xml.includes('&lt;'), 'Left angle brackets must be escaped');
  assert.ok(xml.includes('&gt;'), 'Right angle brackets must be escaped');
  assert.ok(!xml.includes('<wireless>'), 'Raw tag characters must not appear unescaped in text');

  const parsed = parsePlist(xml);
  assert.strictEqual(parsed['custom&key<1>'], 'AT&T <wireless> "quoted" \'single\'');
}

// Contract 5: plist.parse throws an error when given invalid or malformed XML without a plist root element
{
  const malformedXml = '<invalid><data>no plist tag</data></invalid>';
  assert.throws(
    () => {
      parsePlist(malformedXml);
    },
    (err) => {
      return err instanceof Error;
    },
    'Should throw an error on malformed XML lacking plist root'
  );
}

// Contract 6: plist.parse ignores __proto__ keys to prevent prototype pollution vulnerabilities
{
  const protoPollutionXml = `<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>__proto__</key>
  <dict>
    <key>polluted</key>
    <string>yes</string>
  </dict>
  <key>normalKey</key>
  <string>normalValue</string>
</dict>
</plist>`;

  // Parsing should either throw or safely drop/ignore __proto__ without polluting global Object.prototype
  try {
    const parsed = parsePlist(protoPollutionXml);
    assert.strictEqual(parsed.normalKey, 'normalValue');
  } catch (err) {
    assert.ok(err instanceof Error, 'If parse throws on __proto__, it must be an Error');
  }

  const testObj = {};
  assert.strictEqual(testObj.polluted, undefined, 'Object.prototype must not be polluted');
}

console.log('All contract tests passed successfully.');