pac-resolver 7.0.1

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/pac-resolver@7.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pac-resolver@7.0.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:c23db3c2da907ce4f6b5aac0e03e34aaeee6baac764f99f1a5aae27eea9ddd4c","contract":["createPacResolver generates an asynchronous FindProxyForURL function from PAC script string or Buffer","FindProxyForURL resolves proxies using built-in sandbox helpers including isPlainHostName, dnsDomainIs, shExpMatch, and isInNet","createPacResolver accepts custom sandbox functions passed in options","FindProxyForURL accepts both URL strings and WHATWG URL instances with optional host override","FindProxyForURL rejects with TypeError when host cannot be determined"],"goal":"verify pkg:npm/pac-resolver@7.0.1","kind":"HOW","packages":["pkg:npm/pac-resolver@7.0.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/pac-resolver@7.0.1"],"schemaVersion":1,"subject":"pkg:npm/pac-resolver@7.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-pac-resolver",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-pac-resolver",
      "version": "1.0.0",
      "dependencies": {
        "@tootallnate/quickjs-emscripten": "^0.23.0",
        "pac-resolver": "7.0.1"
      }
    },
    "node_modules/@tootallnate/quickjs-emscripten": {
      "version": "0.23.0",
      "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz",
      "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==",
      "license": "MIT"
    },
    "node_modules/ast-types": {
      "version": "0.13.4",
      "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.13.4.tgz",
      "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==",
      "license": "MIT",
      "dependencies": {
        "tslib": "^2.0.1"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/degenerator": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/degenerator/-/degenerator-5.0.1.tgz",
      "integrity": "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==",
      "license": "MIT",
      "dependencies": {
        "ast-types": "^0.13.4",
        "escodegen": "^2.1.0",
        "esprima": "^4.0.1"
      },
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/escodegen": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz",
      "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "esprima": "^4.0.1",
        "estraverse": "^5.2.0",
        "esutils": "^2.0.2"
      },
      "bin": {
        "escodegen": "bin/escodegen.js",
        "esgenerate": "bin/esgenerate.js"
      },
      "engines": {
        "node": ">=6.0"
      },
      "optionalDependencies": {
        "source-map": "~0.6.1"
      }
    },
    "node_modules/esprima": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
      "license": "BSD-2-Clause",
      "bin": {
        "esparse": "bin/esparse.js",
        "esvalidate": "bin/esvalidate.js"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/estraverse": {
      "version": "5.3.0",
      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=4.0"
      }
    },
    "node_modules/esutils": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/netmask": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.1.1.tgz",
      "integrity": "sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4.0"
      }
    },
    "node_modules/pac-resolver": {
      "version": "7.0.1",
      "resolved": "https://registry.npmjs.org/pac-resolver/-/pac-resolver-7.0.1.tgz",
      "integrity": "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==",
      "license": "MIT",
      "dependencies": {
        "degenerator": "^5.0.0",
        "netmask": "^2.0.2"
      },
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/source-map": {
      "version": "0.6.1",
      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
      "license": "BSD-3-Clause",
      "optional": true,
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
      "license": "0BSD"
    }
  }
}

{
  "name": "sample-pac-resolver",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of pac-resolver",
  "type": "module",
  "main": "src/index.js",
  "dependencies": {
    "@tootallnate/quickjs-emscripten": "^0.23.0",
    "pac-resolver": "7.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/pac-resolver@7.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pac-resolver@7.0.1"
  ]
}

import { createPacResolver, sandbox } from 'pac-resolver';

/**
 * Compiles PAC script code into an asynchronous FindProxyForURL function.
 *
 * @param {import('@tootallnate/quickjs-emscripten').QuickJSWASMModule} qjs - QuickJS WASM module instance
 * @param {string | Buffer} pacScript - PAC file contents as string or Buffer
 * @param {object} [options] - Options passed to pac-resolver (filename, sandbox, etc.)
 * @returns {(url: string | URL, host?: string) => Promise<string>} FindProxyForURL resolver function
 */
export function compilePac(qjs, pacScript, options) {
  return createPacResolver(qjs, pacScript, options);
}

/**
 * Evaluates a PAC resolver function against a target URL and optional host override.
 *
 * @param {(url: string | URL, host?: string) => Promise<string>} resolver - PAC resolver function
 * @param {string | URL} targetUrl - URL to evaluate proxy for
 * @param {string} [customHost] - Optional host override
 * @returns {Promise<string>} PAC proxy directive (e.g. "DIRECT" or "PROXY host:port")
 */
export async function evaluatePac(resolver, targetUrl, customHost) {
  if (typeof resolver !== 'function') {
    throw new TypeError('Expected resolver to be a function');
  }
  return resolver(targetUrl, customHost);
}

export { createPacResolver, sandbox };

import assert from 'node:assert/strict';
import { getQuickJS } from '@tootallnate/quickjs-emscripten';
import { createPacResolver, sandbox, compilePac, evaluatePac } from '../src/index.js';

// 1. Export verification
assert.equal(typeof createPacResolver, 'function', 'createPacResolver must be exported as a function');
assert.equal(typeof sandbox, 'object', 'sandbox must be exported as an object');
assert.equal(typeof compilePac, 'function', 'compilePac helper must be exported as a function');
assert.equal(typeof evaluatePac, 'function', 'evaluatePac helper must be exported as a function');

// 2. Built-in sandbox functions verification
const expectedSandboxFunctions = [
  'alert',
  'dateRange',
  'dnsDomainIs',
  'dnsDomainLevels',
  'dnsResolve',
  'isInNet',
  'isPlainHostName',
  'isResolvable',
  'localHostOrDomainIs',
  'myIpAddress',
  'shExpMatch',
  'timeRange',
  'weekdayRange'
];
for (const fnName of expectedSandboxFunctions) {
  assert.equal(typeof sandbox[fnName], 'function', `sandbox.${fnName} must be a function`);
}

// 3. Compile and resolve standard PAC script
const qjs = await getQuickJS();

const pacScript = `
  function FindProxyForURL(url, host) {
    if (isPlainHostName(host)) {
      return "DIRECT";
    }
    if (dnsDomainIs(host, ".internal.example.com")) {
      return "PROXY proxy-internal.example.com:3128";
    }
    if (shExpMatch(host, "*.secure.example.com")) {
      return "PROXY proxy-secure.example.com:8443";
    }
    if (isInNet(host, "10.0.0.0", "255.0.0.0")) {
      return "PROXY proxy-corp.example.com:8080";
    }
    return "DIRECT";
  }
`;

const resolver = compilePac(qjs, pacScript);
assert.equal(typeof resolver, 'function', 'compilePac should return a FindProxyForURL function');

// Test isPlainHostName
const plainResult = await evaluatePac(resolver, 'http://localhost/test');
assert.equal(plainResult, 'DIRECT', 'Plain host should resolve to DIRECT');

// Test dnsDomainIs
const internalResult = await evaluatePac(resolver, 'http://service.internal.example.com/api');
assert.equal(internalResult, 'PROXY proxy-internal.example.com:3128', 'Domain match should resolve to internal proxy');

// Test shExpMatch
const secureResult = await evaluatePac(resolver, 'https://gateway.secure.example.com/app');
assert.equal(secureResult, 'PROXY proxy-secure.example.com:8443', 'Wildcard match should resolve to secure proxy');

// Test isInNet with host override
const subnetResult = await evaluatePac(resolver, 'http://example.com/status', '10.50.1.2');
assert.equal(subnetResult, 'PROXY proxy-corp.example.com:8080', 'Subnet match should resolve to corp proxy');

// Test fallback DIRECT
const externalResult = await evaluatePac(resolver, 'http://example.com/index.html');
assert.equal(externalResult, 'DIRECT', 'Default route should resolve to DIRECT');

// 4. Support Buffer input
const bufferPac = Buffer.from(`
  function FindProxyForURL(url, host) {
    if (host === "buffer.example.com") {
      return "PROXY proxy-buffer.example.com:8080";
    }
    return "DIRECT";
  }
`);
const bufferResolver = createPacResolver(qjs, bufferPac);
assert.equal(await bufferResolver('http://buffer.example.com/'), 'PROXY proxy-buffer.example.com:8080');
assert.equal(await bufferResolver('http://example.com/'), 'DIRECT');

// 5. Support custom sandbox functions via options
const customSandboxPac = `
  function FindProxyForURL(url, host) {
    if (customRouteFilter(host)) {
      return "PROXY custom-proxy.example.com:8080";
    }
    return "DIRECT";
  }
`;
const customResolver = createPacResolver(qjs, customSandboxPac, {
  sandbox: {
    customRouteFilter: (host) => host.startsWith('special.')
  }
});
assert.equal(await customResolver('http://special.example.com/'), 'PROXY custom-proxy.example.com:8080');
assert.equal(await customResolver('http://example.com/'), 'DIRECT');

// 6. Support WHATWG URL instance input and host override
const targetUrlObj = new URL('http://example.com/resource');
const targetResult = await bufferResolver(targetUrlObj);
assert.equal(targetResult, 'DIRECT');

const overrideResult = await bufferResolver(targetUrlObj, 'buffer.example.com');
assert.equal(overrideResult, 'PROXY proxy-buffer.example.com:8080');

// 7. Error handling for invalid input / missing host
await assert.rejects(
  async () => {
    await resolver('');
  },
  {
    name: 'TypeError'
  },
  'Should reject when host cannot be determined from URL'
);

console.log('Contract tests passed successfully.');