@electron/osx-sign 1.3.3: validate and walk electron app bundle for signing with @electron/osx-sign

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: validate and walk electron app bundle for signing with @electron/osx-sign
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40electron/osx-sign@1.3.3
Demonstrate these symbols/APIs:
  - signApp
  - signAsync
  - walkAsync

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:b01cfb0e52774b1ba0f0981184b9156886d75597baad395c66cf60eaf0aaba9b","contract":["signAsync is an exported function and an alias for signApp","signApp validates options and rejects with an Error if app path is not specified or does not end with .app","signApp rejects with an Error if the target application bundle does not exist on disk","walkAsync recursively traverses an application bundle directory and returns binary paths and nested .framework bundles while removing .cstemp files"],"goal":"validate and walk electron app bundle for signing with @electron/osx-sign","kind":"HOW","packages":["pkg:npm/%40electron/osx-sign@1.3.3"],"schemaVersion":1,"symbols":["signApp","signAsync","walkAsync"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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/%40electron/osx-sign@1.3.3"],"schemaVersion":1,"subject":"pkg:npm/%40electron/osx-sign@1.3.3","symbols":["signApp","signAsync","walkAsync"],"verifierAdapter":"node-typescript@1"}

'use strict';

const { signApp, signAsync, walkAsync } = require('@electron/osx-sign');

/**
 * Validates options for signing an Electron macOS application bundle.
 * @param {import('@electron/osx-sign').SignOptions} opts
 */
async function validateAndPrepareSigning(opts) {
  if (!opts || !opts.app) {
    throw new Error('Path to application must be specified.');
  }
  return opts;
}

/**
 * Discovers binaries and frameworks inside an app bundle directory.
 * @param {string} contentsPath Path to App.app/Contents directory
 * @returns {Promise<string[]>} List of discovered paths
 */
async function discoverSigningTargets(contentsPath) {
  return await walkAsync(contentsPath);
}

module.exports = {
  signApp,
  signAsync,
  walkAsync,
  validateAndPrepareSigning,
  discoverSigningTargets
};

{
  "name": "sample-electron-osx-sign",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-electron-osx-sign",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@electron/osx-sign": "1.3.3"
      }
    },
    "node_modules/@electron/osx-sign": {
      "version": "1.3.3",
      "resolved": "https://registry.npmjs.org/@electron/osx-sign/-/osx-sign-1.3.3.tgz",
      "integrity": "sha512-KZ8mhXvWv2rIEgMbWZ4y33bDHyUKMXnx4M0sTyPNK/vcB81ImdeY9Ggdqy0SWbMDgmbqyQ+phgejh6V3R2QuSg==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "compare-version": "^0.1.2",
        "debug": "^4.3.4",
        "fs-extra": "^10.0.0",
        "isbinaryfile": "^4.0.8",
        "minimist": "^1.2.6",
        "plist": "^3.0.5"
      },
      "bin": {
        "electron-osx-flat": "bin/electron-osx-flat.js",
        "electron-osx-sign": "bin/electron-osx-sign.js"
      },
      "engines": {
        "node": ">=12.0.0"
      }
    },
    "node_modules/@xmldom/xmldom": {
      "version": "0.9.12",
      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.9.12.tgz",
      "integrity": "sha512-5AXjrcMClTryPe9LgZrygpB1lj7s0S9E0+W+AHaVKAVyHanafK86iPSvG5xHVSp/jC+VH1UXu0TAEmY279xH7A==",
      "license": "MIT",
      "engines": {
        "node": ">=14.6"
      }
    },
    "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/compare-version": {
      "version": "0.1.2",
      "resolved": "https://registry.npmjs.org/compare-version/-/compare-version-0.1.2.tgz",
      "integrity": "sha512-pJDh5/4wrEnXX/VWRZvruAGHkzKdr46z11OlTPN+VrATlWWhSKewNCJ1futCO5C7eJB3nPMFZA1LeYtcFboZ2A==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/fs-extra": {
      "version": "10.1.0",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz",
      "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==",
      "license": "MIT",
      "dependencies": {
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=12"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
    "node_modules/isbinaryfile": {
      "version": "4.0.10",
      "resolved": "https://registry.npmjs.org/isbinaryfile/-/isbinaryfile-4.0.10.tgz",
      "integrity": "sha512-iHrqe5shvBUcFbmZq9zOQHBoeOhZJu6RQGrDpBgenUm/Am+F3JM2MgQj+rK3Z601fzrL5gLZWtAPH2OBaSVcyw==",
      "license": "MIT",
      "engines": {
        "node": ">= 8.0.0"
      },
      "funding": {
        "url": "https://github.com/sponsors/gjtorikian/"
      }
    },
    "node_modules/jsonfile": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
      "license": "MIT",
      "dependencies": {
        "universalify": "^2.0.0"
      },
      "optionalDependencies": {
        "graceful-fs": "^4.1.6"
      }
    },
    "node_modules/minimist": {
      "version": "1.2.8",
      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/plist": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/plist/-/plist-3.1.1.tgz",
      "integrity": "sha512-ZIfcLJC+7E7FBFnDxm9MPmt7D+DidyQ26lewieO75AdhA2ayMtsJSES0iWzqJQbcVRSrTufQoy0DR94xHue0oA==",
      "license": "MIT",
      "dependencies": {
        "@xmldom/xmldom": "^0.9.10",
        "base64-js": "^1.5.1",
        "xmlbuilder": "^15.1.1"
      },
      "engines": {
        "node": ">=10.4.0"
      }
    },
    "node_modules/universalify": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
      "license": "MIT",
      "engines": {
        "node": ">= 10.0.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-electron-osx-sign",
  "version": "1.0.0",
  "private": true,
  "description": "validate and walk electron app bundle for signing with @electron/osx-sign",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "@electron/osx-sign": "1.3.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "validate and walk electron app bundle for signing with @electron/osx-sign",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40electron/osx-sign@1.3.3"
  ],
  "symbols": [
    "signApp",
    "signAsync",
    "walkAsync"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const {
  signApp,
  signAsync,
  walkAsync,
  validateAndPrepareSigning,
  discoverSigningTargets
} = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'osx-sign-contract-'));

  try {
    // 1. Verify signAsync is an exported function and alias for signApp
    assert.strictEqual(typeof signApp, 'function', 'signApp must be a function');
    assert.strictEqual(typeof signAsync, 'function', 'signAsync must be a function');
    assert.strictEqual(signApp, signAsync, 'signAsync must be an alias for signApp');

    // 2. Verify signApp validates options and rejects if app is not specified or invalid extension
    await assert.rejects(
      async () => {
        await signApp({});
      },
      /Path to application must be specified/,
      'signApp must reject when app path is missing'
    );

    await assert.rejects(
      async () => {
        await signApp({ app: 'InvalidName.txt' });
      },
      /Extension of application must be `\.app`/,
      'signApp must reject when extension is not .app'
    );

    // 3. Verify signApp rejects when application bundle does not exist on disk
    const nonExistentApp = path.join(tmpDir, 'NonExistent.app');
    await assert.rejects(
      async () => {
        await signApp({ app: nonExistentApp });
      },
      /could not be found/,
      'signApp must reject when app path does not exist'
    );

    // 4. Verify walkAsync recursively traverses bundle, returns binary paths and nested frameworks, removes .cstemp
    const dummyApp = path.join(tmpDir, 'Sample.app');
    const contentsDir = path.join(dummyApp, 'Contents');
    const macOSDir = path.join(contentsDir, 'MacOS');
    const frameworksDir = path.join(contentsDir, 'Frameworks');
    const testFrameworkDir = path.join(frameworksDir, 'Helper.framework');
    const resourcesDir = path.join(contentsDir, 'Resources');

    fs.mkdirSync(macOSDir, { recursive: true });
    fs.mkdirSync(testFrameworkDir, { recursive: true });
    fs.mkdirSync(resourcesDir, { recursive: true });

    // Binary file (contains null byte so isbinaryfile identifies it as binary)
    const mainBin = path.join(macOSDir, 'Sample');
    fs.writeFileSync(mainBin, Buffer.from([0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01, 0x01, 0x00]));

    // Framework binary file
    const fwBin = path.join(testFrameworkDir, 'Helper');
    fs.writeFileSync(fwBin, Buffer.from([0xca, 0xfe, 0xba, 0xbe, 0x00, 0x00, 0x00, 0x02]));

    // Plain text resource file (non-binary)
    const textFile = path.join(resourcesDir, 'config.json');
    fs.writeFileSync(textFile, JSON.stringify({ name: 'Sample' }), 'utf8');

    // Temporary cstemp file that should be cleaned up
    const cstempFile = path.join(resourcesDir, 'codesign-temp.cstemp');
    fs.writeFileSync(cstempFile, 'temporary data', 'utf8');

    // Call walkAsync and verify results
    const discoveredPaths = await walkAsync(contentsDir);
    assert(Array.isArray(discoveredPaths), 'walkAsync must return an array');
    assert(discoveredPaths.includes(mainBin), 'walkAsync must discover main binary');
    assert(discoveredPaths.includes(testFrameworkDir), 'walkAsync must discover .framework directory');
    assert(discoveredPaths.includes(fwBin), 'walkAsync must discover binary within .framework');
    assert(!discoveredPaths.includes(textFile), 'walkAsync must exclude non-binary text files');
    assert(!fs.existsSync(cstempFile), 'walkAsync must remove .cstemp temporary files');

    // 5. Test helper wrappers in index.js
    const helperTargetResult = await discoverSigningTargets(contentsDir);
    assert.deepStrictEqual(helperTargetResult, discoveredPaths, 'discoverSigningTargets must match walkAsync result');

    const prepResult = await validateAndPrepareSigning({ app: dummyApp });
    assert.strictEqual(prepResult.app, dummyApp, 'validateAndPrepareSigning must return options');

    await assert.rejects(
      async () => {
        await validateAndPrepareSigning({});
      },
      /Path to application must be specified/,
      'validateAndPrepareSigning must reject without app'
    );

    console.log('Contract tests passed successfully.');
    process.exit(0);
  } finally {
    try {
      if (fs.existsSync(tmpDir)) {
        fs.rmSync(tmpDir, { recursive: true, force: true });
      }
    } catch (e) {
      // Ignore cleanup error
    }
  }
}

run().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});