resolve-alpn 1.2.1: resolveALPN

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/resolve-alpn@1.2.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/resolve-alpn@1.2.1
Demonstrate these symbols/APIs:
  - resolveALPN

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:5a4b964526a99aead63da98fffff8579189d84fe9c4719f967eebc9d4c6dce2a","contract":["resolveALPN negotiates and returns the selected ALPN protocol from a TLS server","resolveALPN destroys the socket by default and resolves with alpnProtocol and timeout status","resolveALPN with resolveSocket enabled returns the active TLSSocket alongside alpnProtocol","resolveALPN supports custom connect functions for custom socket factory integration","resolveALPN rejects when the socket connection encounters an error","resolveALPN sets timeout to true when socket times out"],"goal":"verify pkg:npm/resolve-alpn@1.2.1","kind":"HOW","packages":["pkg:npm/resolve-alpn@1.2.1"],"schemaVersion":1,"symbols":["resolveALPN"]},"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/resolve-alpn@1.2.1"],"schemaVersion":1,"subject":"pkg:npm/resolve-alpn@1.2.1","symbols":["resolveALPN"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-resolve-alpn",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-resolve-alpn",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "resolve-alpn": "1.2.1"
      }
    },
    "node_modules/resolve-alpn": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/resolve-alpn/-/resolve-alpn-1.2.1.tgz",
      "integrity": "sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-resolve-alpn",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of pkg:npm/resolve-alpn@1.2.1",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "resolve-alpn": "1.2.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/resolve-alpn@1.2.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/resolve-alpn@1.2.1"
  ],
  "symbols": [
    "resolveALPN"
  ]
}

const resolveALPN = require('resolve-alpn');

/**
 * Resolves the ALPN protocol for a given target.
 * @param {import('tls').ConnectionOptions & { resolveSocket?: boolean }} options
 * @param {Function} [connect]
 * @returns {Promise<{ alpnProtocol: string | false | null, socket?: import('tls').TLSSocket, timeout: boolean }>}
 */
async function detectAlpnProtocol(options, connect) {
  return resolveALPN(options, connect);
}

module.exports = {
  resolveALPN,
  detectAlpnProtocol
};

import assert from 'node:assert';
import { EventEmitter } from 'node:events';
import { createRequire } from 'node:module';
import tls from 'node:tls';

const require = createRequire(import.meta.url);
const { resolveALPN, detectAlpnProtocol } = require('../src/index.js');

const keyB64 = "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRQy9tNHhJdEhXcWFSbDEKeVdvYjJLa2hJenlUdU82MmhtWnpwS0sveE9XK2xZUDk2VEVGeEpPb1N2enp1cUtKSnRhSTF3Z1FrUGZMNjZvVQpvZlBpK1F5enEvTTlseU9GQzVvQmtZNENRUFZIM0FESUxXMlNnRDdJQkQ4NXQxbGZHUHpUODZlS295NXJ6Wk1GCkJ4RnNQVEFYNm5hUWZDa0pYQUo2RUZDNkZLaTRvZlY2dW81YitmeUc5RGlOZ3B1dEJmNjUvWGxzSExLVnB4aHgKc1lYOGVJRm9JdjB1aEF3eTJPWXFyTmJqamR1dDNtYzU0dU02K1ltcUsvL3pxZ0dtY0VMUkpsUDQzU3IzUXB2YQp1MzArL0J2WEJwMlYzV24wdVhWLytFeWlTZlZMOGV5RmhOUjZTUy9qd0ppeWtrbFRuV0NoZUs2Y1FMZFlwMkdFCms0Vm5oOTUvQWdNQkFBRUNnZ0VBR3dLYjQzSGc5bTFMWkFISkhmVE1Ycm4vWTVtWnVRdzRMQXdrenlDNy9FSksKY1lRcVgzUkhGbDIveThIZkFMT0RZWlhpY3Fkazd3K2hFYmlFejFXcFZ6aWhtT2lSM3NMMGFrMHc5aHRmR0VxbwpwNDlUMTJlUnNoTjdNREVxL1k5aHNLVXoxSVROV2ZBSVRoaWhlWjhraFBLTjFTOVRmNWpEVnA2dktwUVg5ckxMCk8wa21oMmM0VTU0cFJ2MGxuem8vM2FpTkFGU2RCeHNEOXFtVmM4cjA4S3MxMGl3bUt3YjZpVktoZDE0NkwvdEQKbFNhS2l2eGtQMzMvcVViWWtaVkdNV1RlRG0reDBDTEEwMUo0ZzY4MWJBRFV1OEhQbDNyaHl1QWhOV0dGcjJ5SwpNWnJOZExMZzduUnRjR2Ywa0U4V0NpSWxOaEpPVFR0YVNsSGJlYWQ2K1FLQmdRRDNaM2VZaWhDVzdZbzJ4Tk8wClFmSEdUbHBCMEpTd2swemhWS2VUb2g2czJoamJReGU0NmtMSXc4TUMrMkNCNmtjWk1qQXFOTGo1alBaNys1Q0EKTTQ0S2Z0TXhHT0FYVlF0VFNXK0ZzVTZ1R1BjZk9QUUh1NDNIakhaY0Ivd09pT2w4SVZ5anF6NzE3WmVlOXFrNQpXU0hDa3diaEZLN2R1Yks5SHpPZWNEYTVod0tCZ1FER1E4eVM2RDA2UE1lTG43QXM4a3RLcTQyajlSbmd2TE9wCllwTjdrNitJQUl3cG5NaGE1aURVZVhYdm5mcFpQdC91WjZDTnE5SnZ1V1BzKzU1ZHUzMFNCWUszUktOL0xtMW4KQk5iNnVORGhmdC9hZElGdTd5aFl3MTBIRTB0UEJjN2h2OVlIU1B1aUtBQXBWSzNqWmo1UUhaakxtUU5GYVlwRApLNVRBU0UwUlNRS0JnRkw2bkExSWVXbjF2LzdBbzNUNURUdUMraGpLK2FRRHM2eDc5VHk2Q21uVk9MTUozTUlECnFHU243QmRxOHFLQVRscHdEK0dJRDJaNzFnd2Rnd2pNd2Q1WlRVSlJZby9RMFZ5YzY4KytlWEpCSTFtUWc2QzQKVWtSVW96b1kzM3lNaFN0Q0VVMC8yWDBvdEVyMzFpaEs4ZHpON1dlK3hTdk81ZGt5eHVCa0tLYXZBb0dBYVFlMQpzZ1Z4bWc1a3IyU3pFYnh4Z21jTEs5WkdGVFloL3hPSGlhbWREWEVzejBhTkpRcFFUZjdpS1VRSlFZbjdXdkp1CnJWNWVwbTBSc0pORE8raDh3elZFSUE0dWhzdHpqV1dVOVZFKzVwWXR4QzUvK3VLYS94clBoMVlEU1NPTWl5N3oKRlB6bXdPcHIyM2xPZk83SEIrNEY2YVZ2aEMvNjNNYVRrS0U4b25FQ2dZRUE0Wll4S1hOZ2d1a1BTNVdvZXFjTgpEQmIzMngvSnd3Z2NLZkFJZ3NYZlNSVGtqU3hoNk16anFkd2Y3T3Noa1N4dWEyVjUyZlJyYkFXTldqSGkzZ0hFCmZpZGYyeWxzTU5zazNBclU5Z2phOEpNems4TnZTKzdmNmJTOFQwYzc3d2RkOHc3SDQwQ0dCbE0xSjd6SXBoNlAKSE5qcTQ1T2JkbXEyc1p4N3R0V2VzZlE9Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K";
const certB64 = "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURDVENDQWZHZ0F3SUJBZ0lVYnFFeHZPZ1p1Ui93OWpubi93MERyN2RzcU5jd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0ZERVNNQkFHQTFVRUF3d0piRzlqWVd4b2IzTjBNQjRYRFRJMk1EZ3lPREExTVRVek9Gb1hEVE0yTURneQpOVEExTVRVek9Gb3dGREVTTUJBR0ExVUVBd3dKYkc5allXeG9iM04wTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGCkFBT0NBUThBTUlJQkNnS0NBUUVBdjV1TVNMUjFxbWtaZGNscUc5aXBJU004azdqdXRvWm1jNlNpdjhUbHZwV0QKL2VreEJjU1RxRXI4ODdxaWlTYldpTmNJRUpEM3krdXFGS0h6NHZrTXM2dnpQWmNqaFF1YUFaR09Ba0QxUjl3QQp5QzF0a29BK3lBUS9PYmRaWHhqODAvT25pcU11YTgyVEJRY1JiRDB3RitwMmtId3BDVndDZWhCUXVoU291S0gxCmVycU9XL244aHZRNGpZS2JyUVgrdWYxNWJCeXlsYWNZY2JHRi9IaUJhQ0w5TG9RTU10am1LcXpXNDQzYnJkNW4KT2VMak92bUpxaXYvODZvQnBuQkMwU1pUK04wcTkwS2IycnQ5UHZ3YjF3YWRsZDFwOUxsMWYvaE1va24xUy9IcwpoWVRVZWtrdjQ4Q1lzcEpKVTUxZ29YaXVuRUMzV0tkaGhKT0ZaNGZlZndJREFRQUJvMU13VVRBZEJnTlZIUTRFCkZnUVU0bkp5Z0ZEQnNsbWVPejVub1NJRGcwV2tZNWd3SHdZRFZSMGpCQmd3Rm9BVTRuSnlnRkRCc2xtZU96NW4Kb1NJRGcwV2tZNWd3RHdZRFZSMFRBUUgvQkFVd0F3RUIvekFOQmdrcWhraUc5dzBCQVFzRkFBT0NBUUVBaEFnOApNem1YdTFWOTJLbHQvR1owUmpIeUxRM2JZZmpLcXhRaEJ6QnlaQUlFYVZPSUcrWlJ4Y1FidWdLVjAvVVNWS2Y0CkV5RWgzUlNueTU1NG9hMG10Y1pBUklZUHE2aWZjMEJ4R0FaalZBYnJvdkw1WUhwOE90d0JaOVpzYitVNnYzS3YKWDREQ0x3eFpSZWpOWlFscVhOcUtka0FMSkdCTkhITDBPNk5KdG01SGdIU2FBSE11M2VPd2Zha0FxQVI2UXRqQQpMMGRjMFQycytaMFhkNWNFUUFkZHJIV0QyY0l3WUhwcUtoWDdzQmtFS3k5RnpyTmwzOE9ma0tVYU0wWkIvUmxnCjNuWnhqM3ZqeFJQM1g3a1FKY2x1UU5Dd2wwQ3ZleXp3dFJyelNhOVg1WTRUY1BoR25RQUxNV2RMdFZ5Vnh4U00KZFdrZXZ4a01jYithWTRsbnBRPT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=";

const key = Buffer.from(keyB64, 'base64').toString('utf8');
const cert = Buffer.from(certB64, 'base64').toString('utf8');

async function runTests() {
  const server = tls.createServer({
    key,
    cert,
    ALPNProtocols: ['h2', 'http/1.1']
  }, (socket) => {
    socket.end();
  });

  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
  const port = server.address().port;

  try {
    // 1. resolveALPN negotiates and returns the selected ALPN protocol from a TLS server
    const r1 = await resolveALPN({
      host: '127.0.0.1',
      port,
      ALPNProtocols: ['h2'],
      rejectUnauthorized: false
    });
    assert.strictEqual(r1.alpnProtocol, 'h2');
    assert.strictEqual(r1.timeout, false);

    // 2. resolveALPN destroys the socket by default and resolves with alpnProtocol and timeout status
    const r2 = await detectAlpnProtocol({
      host: '127.0.0.1',
      port,
      ALPNProtocols: ['http/1.1'],
      rejectUnauthorized: false
    });
    assert.strictEqual(r2.alpnProtocol, 'http/1.1');
    assert.strictEqual(r2.socket, undefined);
    assert.strictEqual(r2.timeout, false);

    // 3. resolveALPN with resolveSocket enabled returns the active TLSSocket alongside alpnProtocol
    const r3 = await resolveALPN({
      host: '127.0.0.1',
      port,
      ALPNProtocols: ['h2'],
      resolveSocket: true,
      rejectUnauthorized: false
    });
    assert.strictEqual(r3.alpnProtocol, 'h2');
    assert.ok(r3.socket);
    assert.strictEqual(r3.socket.destroyed, false);
    r3.socket.destroy();

    // 4. resolveALPN supports custom connect functions for custom socket factory integration
    const fakeSocket = new EventEmitter();
    fakeSocket.alpnProtocol = 'custom-proto';
    fakeSocket.destroy = () => {
      fakeSocket.destroyed = true;
    };
    fakeSocket.off = fakeSocket.removeListener;

    const customConnect = (opts, cb) => {
      setImmediate(cb);
      return fakeSocket;
    };

    const r4 = await resolveALPN({ resolveSocket: true }, customConnect);
    assert.strictEqual(r4.alpnProtocol, 'custom-proto');
    assert.strictEqual(r4.socket, fakeSocket);
    assert.strictEqual(fakeSocket.destroyed, undefined);

    // 5. resolveALPN rejects when the socket connection encounters an error
    const errorSocket = new EventEmitter();
    errorSocket.off = errorSocket.removeListener;
    const errorConnect = (opts, cb) => {
      setImmediate(() => errorSocket.emit('error', new Error('TLS connection failed')));
      return errorSocket;
    };

    await assert.rejects(resolveALPN({}, errorConnect), /TLS connection failed/);

    // 6. resolveALPN sets timeout to true when socket times out
    const timeoutSocket = new EventEmitter();
    timeoutSocket.alpnProtocol = 'h2';
    timeoutSocket.off = timeoutSocket.removeListener;
    timeoutSocket.destroy = () => {
      timeoutSocket.destroyed = true;
    };
    const timeoutConnect = (opts, cb) => {
      setImmediate(() => {
        timeoutSocket.emit('timeout');
      });
      return timeoutSocket;
    };

    const r6 = await resolveALPN({}, timeoutConnect);
    assert.strictEqual(r6.timeout, true);
    assert.strictEqual(r6.alpnProtocol, 'h2');

    console.log('All contract tests passed successfully.');
  } finally {
    server.close();
  }
}

runTests().catch((error) => {
  console.error(error);
  process.exit(1);
});