bare-posix 1.0.1: seteuid

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 bare-posix.seteuid in pkg:npm/bare-posix@1.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-posix@1.0.1
Demonstrate these symbols/APIs:
  - bare-posix.seteuid

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:4175b821dc3d2e424dcd04e795776b3b4d0357d69ff73248aa8d77d1a24cace4","contract":["package manifest specifies bare-posix 1.0.1 with Bare addon flag and subpath exports","declares seteuid accepting number or string and geteuid in TypeScript definitions (index.d.ts)","exports seteuid wrapper function in JavaScript interface delegating to binding.seteuid","resolves string username to numeric uid via getpwnam before calling binding.seteuid","throws TypeError when resolving unknown username string via getpwnam in seteuid","native binding registers bare_posix_seteuid calling POSIX seteuid with 32-bit unsigned integer","unsupported platform fallback implements seteuid throwing Platform not supported error","prebuilt native addon binaries exist across linux and darwin platforms","posix.seteuid successfully accepts numeric user ID and delegates to native binding","posix.seteuid resolves username string to user ID and delegates to native binding"],"goal":"verify bare-posix.seteuid in pkg:npm/bare-posix@1.0.1","kind":"HOW","packages":["pkg:npm/bare-posix@1.0.1"],"schemaVersion":1,"symbols":["bare-posix.seteuid"]},"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/bare-posix@1.0.1"],"schemaVersion":1,"subject":"pkg:npm/bare-posix@1.0.1","symbols":["bare-posix.seteuid"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-posix-seteuid",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-posix-seteuid",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-posix": "1.0.1"
      }
    },
    "node_modules/bare-posix": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/bare-posix/-/bare-posix-1.0.1.tgz",
      "integrity": "sha512-b4quA8dyRVvX0aFIAIiev5zFATHwIUGr42Gmt+CqiBNg/bdsNkrj4bbkeotMOMiljJS4DCME5kywJO/TFwKo1A==",
      "license": "Apache-2.0"
    }
  }
}

{
  "name": "sample-bare-posix-seteuid",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-posix": "1.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify bare-posix.seteuid in pkg:npm/bare-posix@1.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-posix@1.0.1"
  ],
  "symbols": [
    "bare-posix.seteuid"
  ]
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';

const require = createRequire(import.meta.url);

// 1. Resolve bare-posix package manifest and verify exports and metadata
const pkgPath = require.resolve('bare-posix/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-posix', 'Package name must be bare-posix');
assert.equal(pkg.version, '1.0.1', 'Package version must be 1.0.1');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as addon');

assert.ok(pkg.exports, 'Package must define exports map');
assert.equal(pkg.exports['.'].types, './index.d.ts', 'Root export must have index.d.ts types');
assert.equal(pkg.exports['.'].default, './index.js', 'Root export must have index.js default');
assert.equal(pkg.exports['.'].android, './unsupported.js', 'Android export must point to unsupported.js');
assert.equal(pkg.exports['.'].win32, './unsupported.js', 'Win32 export must point to unsupported.js');
assert.equal(pkg.exports['./package'], './package.json', 'Package export must point to package.json');

const pkgDir = path.dirname(pkgPath);

// 2. Verify TypeScript declarations (index.d.ts) for seteuid and geteuid
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(
  indexDts.includes('export function seteuid(id: number | string): void'),
  'index.d.ts must declare export function seteuid(id: number | string): void'
);
assert.ok(
  indexDts.includes('export function geteuid(): number'),
  'index.d.ts must declare export function geteuid(): number'
);
assert.ok(
  indexDts.includes('export interface Passwd'),
  'index.d.ts must declare Passwd interface'
);
assert.ok(
  indexDts.includes('export function getpwnam(name: string): Passwd | null'),
  'index.d.ts must declare getpwnam returning Passwd | null'
);

// 3. Verify JavaScript implementation exports seteuid wrapper logic
const indexJs = fs.readFileSync(path.join(pkgDir, 'index.js'), 'utf8');
assert.ok(
  indexJs.includes('exports.seteuid = function seteuid(id)'),
  'index.js must export seteuid wrapper function'
);
assert.ok(
  indexJs.includes("if (typeof id === 'string') id = exports.getpwnam(id).uid"),
  'index.js seteuid must resolve string username using getpwnam'
);
assert.ok(
  indexJs.includes('binding.seteuid(id)'),
  'index.js seteuid must delegate to binding.seteuid'
);

// 4. Verify C native addon binding (binding.c) for bare_posix_seteuid
const bindingC = fs.readFileSync(path.join(pkgDir, 'binding.c'), 'utf8');
assert.ok(
  bindingC.includes('bare_posix_seteuid(js_env_t *env, js_callback_info_t *info)'),
  'binding.c must implement bare_posix_seteuid'
);
assert.ok(
  bindingC.includes('err = js_get_value_uint32(env, argv[0], &uid);'),
  'binding.c must extract uint32 uid from argv[0]'
);
assert.ok(
  bindingC.includes('err = seteuid(uid);'),
  'binding.c must invoke POSIX seteuid system call'
);
assert.ok(
  bindingC.includes('V("seteuid", bare_posix_seteuid)'),
  'binding.c must export seteuid symbol in bare_posix_exports'
);
assert.ok(
  bindingC.includes('BARE_MODULE(bare_posix, bare_posix_exports)'),
  'binding.c must register bare_posix module'
);

// 5. Verify unsupported platform fallback behavior (unsupported.js)
const unsupportedJs = fs.readFileSync(path.join(pkgDir, 'unsupported.js'), 'utf8');
assert.ok(
  unsupportedJs.includes('exports.seteuid = function setgid() {\n  throw new Error(\'Platform not supported\')\n}'),
  'unsupported.js must throw Platform not supported for seteuid on unsupported platforms'
);

const unsupportedModule = require(path.join(pkgDir, 'unsupported.js'));
assert.throws(
  () => unsupportedModule.seteuid(0),
  /Platform not supported/,
  'unsupported.seteuid must throw Platform not supported error'
);

// 6. Verify prebuilt native addon artifacts exist for supported platforms
const prebuildsDir = path.join(pkgDir, 'prebuilds');
const expectedTargets = [
  'linux-x64',
  'linux-arm64',
  'darwin-x64',
  'darwin-arm64'
];
for (const target of expectedTargets) {
  const prebuildPath = path.join(prebuildsDir, target, 'bare-posix.bare');
  assert.ok(fs.existsSync(prebuildPath), `Prebuild binary for ${target} must exist`);
  const stats = fs.statSync(prebuildPath);
  assert.ok(stats.size > 0, `Prebuild binary for ${target} must not be empty`);
}

// 7. Verify runtime behavior of seteuid using simulated native binding
const bindingPath = path.join(pkgDir, 'binding.js');
let currentEuid = typeof process.geteuid === 'function' ? process.geteuid() : 1000;
let lastSetEuid = null;
const seteuidCallLog = [];

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    geteuid: () => currentEuid,
    seteuid: (id) => {
      if (typeof id !== 'number' || id < 0) {
        throw new Error('invalid uid');
      }
      lastSetEuid = id;
      seteuidCallLog.push(id);
    },
    getpwnam: (name) => {
      if (name === 'currentuser') {
        return { username: 'currentuser', passwd: 'x', uid: currentEuid, gid: 1000, gecos: '', homedir: '', shell: '' };
      }
      if (name === 'daemon') {
        return { username: 'daemon', passwd: 'x', uid: 1, gid: 1, gecos: '', homedir: '', shell: '' };
      }
      return null;
    }
  }
};

const posix = require('bare-posix');
assert.equal(typeof posix.seteuid, 'function', 'bare-posix must export seteuid function');

// Verify seteuid with current numeric euid
posix.seteuid(currentEuid);
assert.equal(lastSetEuid, currentEuid, 'seteuid must successfully pass numeric uid to binding');
assert.equal(seteuidCallLog[seteuidCallLog.length - 1], currentEuid);

// Verify seteuid with another numeric uid
posix.seteuid(1005);
assert.equal(lastSetEuid, 1005, 'seteuid must pass 1005 directly to binding');

// Verify seteuid resolving username via getpwnam
posix.seteuid('currentuser');
assert.equal(lastSetEuid, currentEuid, 'seteuid must resolve username string to uid and set it');

posix.seteuid('daemon');
assert.equal(lastSetEuid, 1, 'seteuid must resolve daemon username to uid 1');

// Verify seteuid with unknown username throws TypeError (null.uid access)
assert.throws(
  () => posix.seteuid('nonexistent_user_test'),
  (err) => err instanceof TypeError,
  'seteuid with unknown username should throw TypeError accessing null.uid'
);

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