jorgex-stack 1.9.61 → 1.9.63

package/dist/pi-ci-artifact.d.ts

@@ -0,0 +1,21 @@
+interface ObservedPiCiArtifact {
+    version: string;
+    tarballUrl: string;
+    integrity: string;
+    bytes: number;
+    sha256: string;
+    sha512: string;
+}
+interface PrepareObservedPiCiArtifactInput {
+    tarballPath: string;
+    candidatePath: string;
+    fetchImpl: typeof fetch;
+}
+/**
+ * T06 CI observed artifact: resolve the live `dist-tags.latest` candidate,
+ * download the exact verified tarball, then freeze the observed identity as
+ * a bounded private JSON. Filesystem guards run before any network.
+ */
+declare function prepareObservedPiCiArtifact(input: PrepareObservedPiCiArtifactInput): Promise<ObservedPiCiArtifact>;
+
+export { type ObservedPiCiArtifact, type PrepareObservedPiCiArtifactInput, prepareObservedPiCiArtifact };

package/dist/pi-ci-artifact.js

@@ -0,0 +1,473 @@
+#!/usr/bin/env node
+
+// src/lib/pi-ci-artifact.ts
+import fs2 from "fs";
+import path2 from "path";
+import { randomBytes as randomBytes2 } from "crypto";
+import { pathToFileURL } from "url";
+
+// src/lib/npm-provider.ts
+import fs from "fs";
+import path from "path";
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+var REGISTRY_HOST = "registry.npmjs.org";
+var ACCEPT = "application/vnd.npm.install-v1+json";
+var MAX_METADATA_BYTES = 4 * 1024 * 1024;
+var FETCH_TIMEOUT_MS = 1e4;
+var STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+var PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+function isStableSemverVersion(value) {
+  return typeof value === "string" && STABLE_SEMVER.test(value);
+}
+function isCanonicalSha512Integrity(integrity) {
+  if (typeof integrity !== "string" || !integrity.startsWith("sha512-")) return false;
+  const b64 = integrity.slice("sha512-".length);
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) return false;
+  let bytes;
+  try {
+    bytes = Buffer.from(b64, "base64");
+  } catch {
+    return false;
+  }
+  return bytes.length === 64 && bytes.toString("base64") === b64;
+}
+function fail(message) {
+  throw new Error(`npm-provider: ${message}`);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function registryUrl(packageName) {
+  return `https://${REGISTRY_HOST}/${packageName}`;
+}
+function canonicalTarballUrl(packageName, version) {
+  const shortName = packageName.includes("/") ? packageName.slice(packageName.lastIndexOf("/") + 1) : packageName;
+  return `https://${REGISTRY_HOST}/${packageName}/-/${shortName}-${version}.tgz`;
+}
+async function readBoundedText(response) {
+  if (response.body === null) fail("missing response body");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total >= MAX_METADATA_BYTES) {
+        await reader.cancel().catch(() => {
+        });
+        fail("metadata exceeds 4 MiB");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+}
+function assertCanonicalIntegrity(integrity) {
+  if (!isCanonicalSha512Integrity(integrity)) fail("invalid integrity (expected canonical sha512 SRI)");
+}
+async function resolveLatestNpmPackageRelease(packageName, fetchImpl) {
+  if (typeof packageName !== "string" || !PACKAGE_NAME.test(packageName)) {
+    fail("invalid package name");
+  }
+  const url = registryUrl(packageName);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { Accept: ACCEPT },
+      redirect: "error",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    fail(`registry fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) fail(`registry responded ${response.status}`);
+  if (response.url !== url) fail(`unexpected response URL ${response.url}`);
+  const lengthHeader = response.headers.get("content-length");
+  if (lengthHeader !== null) {
+    const trimmed = lengthHeader.trim();
+    if (!/^\d+$/.test(trimmed)) fail("invalid content-length");
+    if (Number(trimmed) > MAX_METADATA_BYTES) fail("metadata exceeds 4 MiB");
+  }
+  const text = await readBoundedText(response);
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    fail("malformed packument JSON");
+  }
+  if (!isRecord(data) || data["name"] !== packageName) fail("malformed packument name");
+  const tags = data["dist-tags"];
+  if (!isRecord(tags) || typeof tags["latest"] !== "string") fail("missing dist-tags.latest");
+  const latest = tags["latest"];
+  if (!isStableSemverVersion(latest)) fail(`unstable or malformed version ${latest}`);
+  const versions = data["versions"];
+  if (!isRecord(versions)) fail("missing versions map");
+  const entry = versions[latest];
+  if (!isRecord(entry)) fail(`missing versions[${latest}]`);
+  if (entry["name"] !== packageName || entry["version"] !== latest) {
+    fail("version mismatch in versions entry");
+  }
+  if (entry["deprecated"] !== void 0) fail(`version ${latest} is deprecated`);
+  const dist = entry["dist"];
+  if (!isRecord(dist)) fail("missing dist");
+  const { tarball, integrity } = dist;
+  if (typeof tarball !== "string" || typeof integrity !== "string") {
+    fail("missing dist.tarball/integrity");
+  }
+  let parsed;
+  try {
+    parsed = new URL(tarball);
+  } catch {
+    fail("foreign tarball URL");
+  }
+  if (parsed.protocol !== "https:" || parsed.host !== REGISTRY_HOST || tarball !== canonicalTarballUrl(packageName, latest)) {
+    fail("foreign tarball URL");
+  }
+  assertCanonicalIntegrity(integrity);
+  return { version: latest, tarballUrl: tarball, integrity };
+}
+var MAX_TARBALL_BYTES = 128 * 1024 * 1024;
+var TARBALL_FETCH_TIMEOUT_MS = 12e4;
+function expectedSha512Digest(integrity) {
+  assertCanonicalIntegrity(integrity);
+  return Buffer.from(integrity.slice("sha512-".length), "base64");
+}
+function assertCanonicalReleaseInput(packageName, release) {
+  if (!isRecord(release)) fail("invalid release");
+  const { version, tarballUrl, integrity } = release;
+  if (!isStableSemverVersion(version)) fail("invalid release version");
+  if (typeof tarballUrl !== "string") fail("foreign tarball URL");
+  let parsed;
+  try {
+    parsed = new URL(tarballUrl);
+  } catch {
+    fail("foreign tarball URL");
+  }
+  if (parsed.protocol !== "https:" || parsed.host !== REGISTRY_HOST || tarballUrl !== canonicalTarballUrl(packageName, version)) {
+    fail("foreign tarball URL");
+  }
+  return { tarballUrl, expectedSha512: expectedSha512Digest(integrity) };
+}
+function readExistingArtifact(file) {
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (stat === void 0) return null;
+  if (stat.isSymbolicLink() || !stat.isFile()) fail("destination is not a regular file");
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    fail("cannot read existing destination");
+  }
+  const sha256 = createHash("sha256");
+  const sha512 = createHash("sha512");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  let bytes = 0;
+  try {
+    for (; ; ) {
+      const read = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (read === 0) break;
+      bytes += read;
+      if (bytes >= MAX_TARBALL_BYTES) fail("existing destination exceeds tarball bound");
+      sha256.update(buffer.subarray(0, read));
+      sha512.update(buffer.subarray(0, read));
+    }
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+    }
+  }
+  return { bytes, sha256: sha256.digest("hex"), sha512: sha512.digest("hex") };
+}
+async function downloadVerifiedNpmPackageTarball(packageName, release, destination, fetchImpl) {
+  if (typeof packageName !== "string" || !PACKAGE_NAME.test(packageName)) {
+    fail("invalid package name");
+  }
+  const { tarballUrl, expectedSha512 } = assertCanonicalReleaseInput(packageName, release);
+  if (typeof destination !== "string" || destination === "") fail("invalid destination");
+  const existing = readExistingArtifact(destination);
+  if (existing !== null) {
+    const existing512 = Buffer.from(existing.sha512, "hex");
+    if (existing512.length === expectedSha512.length && timingSafeEqual(existing512, expectedSha512)) {
+      return { path: destination, bytes: existing.bytes, sha256: existing.sha256, sha512: existing.sha512 };
+    }
+    fail("destination bytes do not match requested integrity");
+  }
+  let response;
+  try {
+    response = await fetchImpl(tarballUrl, {
+      headers: { accept: "application/octet-stream" },
+      redirect: "error",
+      signal: AbortSignal.timeout(TARBALL_FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    fail(`tarball fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) fail(`tarball responded ${response.status}`);
+  if (response.url !== tarballUrl) fail(`unexpected tarball response URL ${response.url}`);
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    const trimmed = declared.trim();
+    if (!/^\d+$/.test(trimmed)) fail("invalid tarball content-length");
+    if (Number(trimmed) > MAX_TARBALL_BYTES) fail("tarball exceeds 128 MiB");
+  }
+  if (response.body === null) fail("missing tarball body");
+  const tempPath = path.join(
+    path.dirname(destination),
+    `npm-tarball-partial-${process.pid}-${randomBytes(8).toString("hex")}`
+  );
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, "wx", 384);
+  } catch {
+    fail("cannot stage tarball temp");
+  }
+  let fdClosed = false;
+  const closeFd = () => {
+    if (fdClosed) return;
+    fdClosed = true;
+    try {
+      fs.closeSync(fd);
+    } catch {
+    }
+  };
+  const discardStaged = () => {
+    closeFd();
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+    }
+  };
+  try {
+    const reader = response.body.getReader();
+    const sha256 = createHash("sha256");
+    const sha512 = createHash("sha512");
+    let bytes = 0;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.byteLength;
+        if (bytes + value.byteLength >= MAX_TARBALL_BYTES) {
+          await reader.cancel().catch(() => {
+          });
+          fail("tarball exceeds 128 MiB");
+        }
+        sha256.update(value);
+        sha512.update(value);
+        let offset = 0;
+        while (offset < value.byteLength) {
+          offset += fs.writeSync(fd, value, offset, value.byteLength - offset);
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    closeFd();
+    const actual512 = sha512.digest();
+    if (!timingSafeEqual(actual512, expectedSha512)) fail("tarball integrity mismatch");
+    try {
+      fs.linkSync(tempPath, destination);
+    } catch {
+      fail("tarball publish raced with existing destination");
+    }
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+    }
+    return { path: destination, bytes, sha256: sha256.digest("hex"), sha512: actual512.toString("hex") };
+  } catch (error) {
+    discardStaged();
+    if (error instanceof Error && error.message.startsWith("npm-provider: ")) throw error;
+    fail(`tarball download failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/lib/pi-release-resolver.ts
+var MAX_METADATA_BYTES2 = 4 * 1024 * 1024;
+async function resolveLatestPiRelease(fetchImpl) {
+  try {
+    return await resolveLatestNpmPackageRelease("jorgex-pi", fetchImpl);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("pi-release-resolver: ")) throw error;
+    if (error instanceof Error) {
+      const detail = error.message.startsWith("npm-provider: ") ? error.message.slice("npm-provider: ".length) : error.message;
+      throw new Error(`pi-release-resolver: ${detail}`);
+    }
+    throw new Error(`pi-release-resolver: ${String(error)}`);
+  }
+}
+async function downloadVerifiedPiTarball(release, destination, fetchImpl) {
+  try {
+    return await downloadVerifiedNpmPackageTarball("jorgex-pi", release, destination, fetchImpl);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("pi-release-resolver: ")) throw error;
+    if (error instanceof Error) {
+      const detail = error.message.startsWith("npm-provider: ") ? error.message.slice("npm-provider: ".length) : error.message;
+      throw new Error(`pi-release-resolver: ${detail}`);
+    }
+    throw new Error(`pi-release-resolver: ${String(error)}`);
+  }
+}
+
+// src/lib/pi-ci-artifact.ts
+var MAX_CANDIDATE_BYTES = 64 * 1024;
+function fail2(message) {
+  throw new Error(`pi-ci-artifact: ${message}`);
+}
+function lstatOrNull(p) {
+  try {
+    return fs2.lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+function assertAbsolute(label, value) {
+  if (typeof value !== "string" || value === "" || !path2.isAbsolute(value)) {
+    fail2(`${label} must be a non-empty absolute path`);
+  }
+  return path2.resolve(value);
+}
+function assertParentRealDir(resolvedFile, label) {
+  const dir = path2.dirname(resolvedFile);
+  const st = lstatOrNull(dir);
+  if (st === null || !st.isDirectory() || st.isSymbolicLink()) {
+    fail2(`${label} parent must be a real directory: ${dir}`);
+  }
+  return dir;
+}
+async function prepareObservedPiCiArtifact(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    fail2("input must be an object");
+  }
+  const { tarballPath, candidatePath, fetchImpl } = input;
+  if (typeof fetchImpl !== "function") {
+    fail2("fetchImpl must be a function");
+  }
+  const tarballResolved = assertAbsolute("tarballPath", tarballPath);
+  const candidateResolved = assertAbsolute("candidatePath", candidatePath);
+  if (tarballResolved === candidateResolved) {
+    fail2("tarballPath and candidatePath must differ");
+  }
+  const candidateDir = assertParentRealDir(candidateResolved, "candidatePath");
+  assertParentRealDir(tarballResolved, "tarballPath");
+  const candidateExisting = lstatOrNull(candidateResolved);
+  if (candidateExisting !== null) {
+    fail2(`candidate already exists: ${candidateResolved}`);
+  }
+  const tarballExisting = lstatOrNull(tarballResolved);
+  if (tarballExisting !== null && tarballExisting.isSymbolicLink()) {
+    fail2(`tarball path must not be a symlink: ${tarballResolved}`);
+  }
+  let release;
+  try {
+    release = await resolveLatestPiRelease(fetchImpl);
+  } catch (error) {
+    if (error instanceof Error && /^(pi-ci-artifact|pi-release-resolver): /.test(error.message)) {
+      throw error;
+    }
+    fail2(`provider release resolution failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let artifact;
+  try {
+    artifact = await downloadVerifiedPiTarball(
+      release,
+      tarballResolved,
+      fetchImpl
+    );
+  } catch (error) {
+    if (error instanceof Error && /^(pi-ci-artifact|pi-release-resolver): /.test(error.message)) {
+      throw error;
+    }
+    fail2(`verified tarball acquisition failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const payload = {
+    version: release.version,
+    tarballUrl: release.tarballUrl,
+    integrity: release.integrity,
+    bytes: artifact.bytes,
+    sha256: artifact.sha256,
+    sha512: artifact.sha512
+  };
+  const serialized = `${JSON.stringify(payload)}
+`;
+  if (Buffer.byteLength(serialized, "utf8") >= MAX_CANDIDATE_BYTES) {
+    fail2("candidate JSON exceeds 64 KiB");
+  }
+  const tempPath = path2.join(
+    candidateDir,
+    `pi-ci-candidate-partial-${process.pid}-${randomBytes2(8).toString("hex")}.json`
+  );
+  let fd;
+  try {
+    fd = fs2.openSync(tempPath, "wx", 384);
+  } catch {
+    fail2(`cannot stage candidate temp: ${tempPath}`);
+  }
+  let fdClosed = false;
+  const closeFd = () => {
+    if (fdClosed) return;
+    fdClosed = true;
+    try {
+      fs2.closeSync(fd);
+    } catch {
+    }
+  };
+  const discardStaged = () => {
+    closeFd();
+    try {
+      fs2.rmSync(tempPath, { force: true });
+    } catch {
+    }
+  };
+  try {
+    try {
+      fs2.writeSync(fd, serialized, null, "utf8");
+    } catch {
+      fail2("cannot write candidate temp");
+    }
+    closeFd();
+    try {
+      fs2.chmodSync(tempPath, 384);
+    } catch {
+      fail2("cannot secure candidate temp");
+    }
+    try {
+      fs2.linkSync(tempPath, candidateResolved);
+    } catch {
+      fail2(`candidate already exists: ${candidateResolved}`);
+    }
+    try {
+      fs2.rmSync(tempPath, { force: true });
+    } catch {
+    }
+  } catch (error) {
+    discardStaged();
+    if (error instanceof Error && error.message.startsWith("pi-ci-artifact: ")) throw error;
+    fail2(`candidate publish failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return payload;
+}
+if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  if (args.length !== 2 || args[0] === void 0 || args[1] === void 0) {
+    console.error("pi-ci-artifact: expected <absolute-tarball> <absolute-candidate>");
+    process.exit(1);
+  }
+  const [tarballArg, candidateArg] = args;
+  await prepareObservedPiCiArtifact({
+    tarballPath: tarballArg,
+    candidatePath: candidateArg,
+    fetchImpl: fetch
+  }).catch((error) => {
+    console.error(error instanceof Error ? error.message : "pi-ci-artifact: failed");
+    process.exit(1);
+  });
+}
+export {
+  prepareObservedPiCiArtifact
+};