@electron/osx-sign 1.3.1: signApp, signAsync, flatAsync

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/%40electron/osx-sign@1.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40electron/osx-sign@1.3.1

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:8c5fab99cf5b1e669b32bee09dbdb5c07ddf3ed7ff5effbb7d6d951b0fc3907b","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","flatAsync is an exported function and an alias for buildPkg","flatAsync validates options and rejects with an Error if app path is not specified or does not end with .app, or if pkg output does not end with .pkg","walkAsync recursively traverses an application bundle directory and returns binary paths and nested .framework bundles while removing .cstemp files"],"goal":"verify pkg:npm/%40electron/osx-sign@1.3.1","kind":"HOW","packages":["pkg:npm/%40electron/osx-sign@1.3.1"],"schemaVersion":1,"symbols":["signApp","signAsync","flatAsync","buildPkg","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.1"],"schemaVersion":1,"subject":"pkg:npm/%40electron/osx-sign@1.3.1","symbols":["signApp","signAsync","flatAsync","buildPkg","walkAsync"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Validates options for signing an Electron macOS application bundle.
 * @param {import('@electron/osx-sign').SignOptions} opts
 */
async function validateSigningOptions(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 = {
  sign,
  signApp,
  signAsync,
  flat,
  flatAsync,
  buildPkg,
  walkAsync,
  validateSigningOptions,
  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.1"
      }
    },
    "node_modules/@electron/osx-sign": {
      "version": "1.3.1",
      "resolved": "https://registry.npmjs.org/@electron/osx-sign/-/osx-sign-1.3.1.tgz",
      "integrity": "sha512-BAfviURMHpmb1Yb50YbCxnOY0wfwaLXH5KJ4+80zS0gUkzDX3ec23naTlEqKsN+PwYn+a1cCzM7BJ4Wcd3sGzw==",
      "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": "verify pkg:npm/%40electron/osx-sign@1.3.1",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "@electron/osx-sign": "1.3.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40electron/osx-sign@1.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40electron/osx-sign@1.3.1"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const {
  sign,
  signApp,
  signAsync,
  flat,
  flatAsync,
  buildPkg,
  walkAsync,
  validateSigningOptions,
  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 an 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 flatAsync and buildPkg are exported functions and flatAsync is an alias for buildPkg
    assert.strictEqual(typeof flatAsync, 'function', 'flatAsync must be a function');
    assert.strictEqual(typeof buildPkg, 'function', 'buildPkg must be a function');
    assert.strictEqual(flatAsync, buildPkg, 'flatAsync must be an alias for buildPkg');

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

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

    await assert.rejects(
      async () => {
        await flatAsync({ app: nonExistentApp });
      },
      /could not be found/,
      'flatAsync must reject when app path does not exist'
    );

    // 6. Verify flatAsync rejects if pkg output does not have .pkg extension
    const dummyApp = path.join(tmpDir, 'Sample.app');
    fs.mkdirSync(dummyApp, { recursive: true });

    await assert.rejects(
      async () => {
        await flatAsync({ app: dummyApp, pkg: 'invalid-output.zip' });
      },
      /Extension of output package must be `\.pkg`/,
      'flatAsync must reject when pkg extension is not .pkg'
    );

    // 7. Verify walkAsync recursively traverses bundle, returns binary paths and nested frameworks, removes .cstemp
    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');

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

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

    await assert.rejects(
      async () => {
        await validateSigningOptions({});
      },
      /Path to application must be specified/,
      'validateSigningOptions 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);
});