@hasna/skills 0.10.38 → 0.10.41

package/README.md

@@ -2418,3 +2418,29 @@ Migration compares the original witness before projecting the new contract,
 refuses native discovery or unknown control changes, and changes policy only.
 After explicit migration, ordinary supported local MCP updates require no
 coordinated policy write.
+
+### Reproduce a reviewed runtime dependency closure
+
+For an exact-version copyfile update, supply an owner-private absolute npm
+lockfile path and its reviewed SHA-256 together:
+
+```sh
+skills self-update --version <version> --reviewed-lock /absolute/package-lock.json \
+  --reviewed-lock-sha256 <sha256> --min-release-age 7 --json
+```
+
+Use the same lock for a separately reviewed bootstrap. The lock must describe
+the verified package archive as `file:./verified.tgz`, use lockfile format 3,
+and bind its version, integrity and dependency declarations. Registry packages
+must have exact versions and SHA-512 integrity at the configured npm registry.
+The updater verifies each frozen version against current registry metadata
+and the requested age policy, runs `npm ci` without re-resolving ranges, then
+checks lock byte continuity and the actual required dependency closure with
+`npm sbom --sbom-format=cyclonedx --package-lock-only=false`. This forces
+installed-manifest inspection; ordinary `npm ls` can trust a hidden lockfile.
+Existing publisher exemptions remain available through the repeatable
+`--min-release-age-exclude` option. The receipt records the reviewed lock hash.
+
+A reviewed lock does not authorize native skill loading, profile changes,
+credential provisioning or session reconciliation. Without this optional input,
+the existing update flow continues to resolve its dependency lock normally.

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.38",
+    version: "0.10.41",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -110034,8 +110034,139 @@ var init_remote_account2 = __esm(() => {
   init_remote_client();
 });
 
+// src/cli/commands/reviewed-runtime-lock.ts
+import { createHash as createHash30 } from "crypto";
+function row(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("REVIEWED_LOCK_SHAPE_INVALID");
+  return value;
+}
+function same4(a, b) {
+  const entries = (v) => Object.entries(row(v ?? {})).sort(([a2], [b2]) => a2.localeCompare(b2));
+  return JSON.stringify(entries(a)) === JSON.stringify(entries(b));
+}
+function packageName(path) {
+  const parts = path.split("/node_modules/");
+  if (!parts[0].startsWith("node_modules/"))
+    throw new Error("REVIEWED_LOCK_LOCATION_INVALID");
+  parts[0] = parts[0].slice("node_modules/".length);
+  if (parts.some((name) => !NAME.test(name) || name.split("/").some((part) => part === "." || part === "..")))
+    throw new Error("REVIEWED_LOCK_LOCATION_INVALID");
+  return parts.at(-1);
+}
+function excluded(name, patterns) {
+  return patterns.some((pattern) => new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`).test(name));
+}
+async function metadata(name, context2) {
+  const url2 = new URL(encodeURIComponent(name), `${context2.registryOrigin}/`);
+  const response = await (context2.fetcher ?? fetch)(url2, { redirect: "error", signal: AbortSignal.timeout(30000) });
+  if (!response.ok || !response.body)
+    throw new Error("REVIEWED_LOCK_METADATA_UNAVAILABLE");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size2 = 0;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      size2 += value.byteLength;
+      if (size2 > MAX_METADATA_BYTES) {
+        await reader.cancel();
+        throw new Error("REVIEWED_LOCK_METADATA_TOO_LARGE");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  try {
+    return row(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+  } catch {
+    throw new Error("REVIEWED_LOCK_METADATA_INVALID");
+  }
+}
+async function validateReviewedRuntimeLock(bytes, sha2562, context2) {
+  if (!/^[a-f0-9]{64}$/.test(sha2562))
+    throw new Error("REVIEWED_LOCK_SHA256_INVALID");
+  if (bytes.byteLength > MAX_LOCK_BYTES || createHash30("sha256").update(bytes).digest("hex") !== sha2562)
+    throw new Error("REVIEWED_LOCK_HASH_MISMATCH");
+  if (!Number.isSafeInteger(context2.minReleaseAge) || context2.minReleaseAge < 1)
+    throw new Error("REVIEWED_LOCK_RELEASE_AGE_REQUIRED");
+  let lock;
+  try {
+    lock = row(JSON.parse(Buffer.from(bytes).toString("utf8")));
+  } catch {
+    throw new Error("REVIEWED_LOCK_SHAPE_INVALID");
+  }
+  if (lock.lockfileVersion !== 3 || lock.requires !== true)
+    throw new Error("REVIEWED_LOCK_FORMAT_UNSUPPORTED");
+  const packages = row(lock.packages);
+  if (Object.keys(packages).length > 5000)
+    throw new Error("REVIEWED_LOCK_POPULATION_TOO_LARGE");
+  const root2 = row(packages[""]);
+  if (!same4(root2.dependencies, { [PACKAGE2]: "file:./verified.tgz" }) || Object.keys(row(root2.devDependencies ?? {})).length || Object.keys(row(root2.optionalDependencies ?? {})).length)
+    throw new Error("REVIEWED_LOCK_ROOT_MISMATCH");
+  const target = row(packages[`node_modules/${PACKAGE2}`]);
+  if (target.version !== context2.version || target.resolved !== "file:verified.tgz" || target.integrity !== context2.archiveIntegrity || target.name !== undefined && target.name !== PACKAGE2)
+    throw new Error("REVIEWED_LOCK_ARCHIVE_MISMATCH");
+  for (const field2 of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+    if (!same4(target[field2], context2.packageManifest[field2]))
+      throw new Error("REVIEWED_LOCK_MANIFEST_MISMATCH");
+  }
+  const registry2 = new URL(context2.registryOrigin);
+  const identities = new Map;
+  for (const [location, value] of Object.entries(packages)) {
+    if (!location)
+      continue;
+    const name = packageName(location), entry = row(value);
+    if (entry.link || entry.dev || entry.name !== undefined && entry.name !== name)
+      throw new Error("REVIEWED_LOCK_LOCATION_INVALID");
+    if (location === `node_modules/${PACKAGE2}`)
+      continue;
+    if (typeof entry.version !== "string" || !VERSION.test(entry.version) || typeof entry.resolved !== "string" || typeof entry.integrity !== "string" || !INTEGRITY.test(entry.integrity))
+      throw new Error("REVIEWED_LOCK_PACKAGE_INVALID");
+    let url2;
+    try {
+      url2 = new URL(entry.resolved);
+    } catch {
+      throw new Error("REVIEWED_LOCK_REGISTRY_INVALID");
+    }
+    if (url2.origin !== registry2.origin || url2.username || url2.password || url2.search || url2.hash || !url2.pathname.endsWith(".tgz"))
+      throw new Error("REVIEWED_LOCK_REGISTRY_INVALID");
+    const entries = identities.get(name) ?? [];
+    entries.push({ name, version: entry.version, resolved: entry.resolved, integrity: entry.integrity });
+    identities.set(name, entries);
+  }
+  const names = [...identities.keys()];
+  const now3 = context2.now ?? Date.now();
+  for (let offset = 0;offset < names.length; offset += 6) {
+    await Promise.all(names.slice(offset, offset + 6).map(async (name) => {
+      const data = await metadata(name, context2), versions2 = row(data.versions), times2 = row(data.time);
+      if (data.name !== name)
+        throw new Error("REVIEWED_LOCK_METADATA_IDENTITY_MISMATCH");
+      for (const entry of identities.get(name)) {
+        const version2 = row(versions2[entry.version]), dist = row(version2.dist);
+        if (version2.name !== name || version2.version !== entry.version || dist.integrity !== entry.integrity || dist.tarball !== entry.resolved)
+          throw new Error("REVIEWED_LOCK_METADATA_IDENTITY_MISMATCH");
+        const published = typeof times2[entry.version] === "string" ? Date.parse(times2[entry.version]) : NaN;
+        if (!Number.isFinite(published) || published > now3 || !excluded(name, context2.minReleaseAgeExclude) && now3 - published < context2.minReleaseAge * 86400000)
+          throw new Error("REVIEWED_LOCK_RELEASE_AGE_REFUSED");
+      }
+    }));
+  }
+}
+var PACKAGE2 = "@hasna/skills", NAME, VERSION, INTEGRITY, MAX_LOCK_BYTES, MAX_METADATA_BYTES;
+var init_reviewed_runtime_lock = __esm(() => {
+  NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/;
+  VERSION = /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/;
+  INTEGRITY = /^sha512-[A-Za-z0-9+/]{86}==$/;
+  MAX_LOCK_BYTES = 8 * 1024 * 1024;
+  MAX_METADATA_BYTES = 32 * 1024 * 1024;
+});
+
 // src/cli/commands/runtime-copyfile.ts
-import { createHash as createHash30, randomUUID as randomUUID9 } from "crypto";
+import { createHash as createHash31, randomUUID as randomUUID9 } from "crypto";
 import { Readable } from "stream";
 import { createGunzip as createGunzip2 } from "zlib";
 import {
@@ -110059,7 +110190,7 @@ function object9(value, code2) {
   return value;
 }
 function hash5(bytes) {
-  return createHash30("sha256").update(bytes).digest("hex");
+  return createHash31("sha256").update(bytes).digest("hex");
 }
 function isWithin(parent, child) {
   const rel = relative10(parent, child);
@@ -110210,7 +110341,7 @@ function verifyIntegrity(bytes, integrity) {
   const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(integrity);
   if (!match)
     throw new Error("REGISTRY_INTEGRITY_UNSUPPORTED");
-  const actual = createHash30("sha512").update(bytes).digest("base64");
+  const actual = createHash31("sha512").update(bytes).digest("base64");
   if (actual !== match[1])
     throw new Error("TARBALL_INTEGRITY_MISMATCH");
 }
@@ -110293,6 +110424,8 @@ async function preflightTarball(bytes, limits = {}) {
     const pathParts2 = rawPath.split("/");
     if (rawPath !== "package" && !rawPath.startsWith("package/") || rawPath.startsWith("/") || rawPath.includes("\\") || pathParts2.some((part) => !part || part === "." || part === ".."))
       throw new Error("TARBALL_PATH_INVALID");
+    if (pathParts2[1] === "node_modules")
+      throw new Error("TARBALL_BUNDLED_DEPENDENCIES_UNSUPPORTED");
     if (paths.has(rawPath))
       throw new Error("TARBALL_DUPLICATE_PATH");
     paths.add(rawPath);
@@ -110320,10 +110453,10 @@ async function downloadPackage(version2, stagingRoot, registryOrigin, fetcher) {
   const metadataResponse = await fetcher(metadataUrl, { redirect: "error", signal: timeout });
   if (!metadataResponse.ok || new URL(metadataResponse.url || metadataUrl).origin !== new URL(registryOrigin).origin)
     throw new Error("REGISTRY_METADATA_FETCH_FAILED");
-  const metadata = object9(JSON.parse(new TextDecoder().decode(await readBodyCapped(metadataResponse, 5 * 1024 * 1024, "REGISTRY_METADATA_SIZE_INVALID"))), "REGISTRY_METADATA_INVALID");
-  if (metadata.name !== PACKAGE_NAME || metadata.version !== version2 || metadata._id !== `${PACKAGE_NAME}@${version2}`)
+  const metadata2 = object9(JSON.parse(new TextDecoder().decode(await readBodyCapped(metadataResponse, 5 * 1024 * 1024, "REGISTRY_METADATA_SIZE_INVALID"))), "REGISTRY_METADATA_INVALID");
+  if (metadata2.name !== PACKAGE_NAME || metadata2.version !== version2 || metadata2._id !== `${PACKAGE_NAME}@${version2}`)
     throw new Error("REGISTRY_PACKAGE_IDENTITY_MISMATCH");
-  const dist = object9(metadata.dist, "REGISTRY_DIST_INVALID");
+  const dist = object9(metadata2.dist, "REGISTRY_DIST_INVALID");
   const integrity = typeof dist.integrity === "string" ? dist.integrity : "";
   const tarballUrl = expectedTarballUrl(dist.tarball, registryOrigin, version2);
   const response = await fetcher(tarballUrl, { redirect: "error", signal: AbortSignal.timeout(30000) });
@@ -110394,7 +110527,7 @@ async function readBodyCapped(response, limit, errorCode) {
   }
   return bytes;
 }
-function readTree(root2, includeModes) {
+function readTree(root2, includeModes, excludeNpmDependencies = false) {
   const base3 = realpathSync16(root2);
   const entries = [];
   const walk2 = (dir, prefix = "") => {
@@ -110402,6 +110535,11 @@ function readTree(root2, includeModes) {
       const path = join58(dir, item);
       const rel = prefix ? `${prefix}/${item}` : item;
       const stat3 = lstatSync30(path);
+      if (excludeNpmDependencies && !prefix && item === "node_modules") {
+        if (!stat3.isDirectory() || stat3.isSymbolicLink())
+          throw new Error("INSTALLED_DEPENDENCY_DIRECTORY_UNSAFE");
+        continue;
+      }
       if (stat3.isSymbolicLink()) {
         const link2 = readlinkSync5(path);
         const resolved = resolve25(dirname31(path), link2);
@@ -110610,8 +110748,10 @@ ${policy.minReleaseAgeExclude.map((pattern) => `min-release-age-exclude[]=${patt
   return npmVersion;
 }
 function comparePackageTrees(expectedRoot, installedRoot) {
+  if (entryExists(join58(expectedRoot, "node_modules")))
+    throw new Error("TARBALL_BUNDLED_DEPENDENCIES_UNSUPPORTED");
   const expected = readTree(expectedRoot, false);
-  const installed = readTree(installedRoot, false);
+  const installed = readTree(installedRoot, false, true);
   if (JSON.stringify(expected.entries) !== JSON.stringify(installed.entries))
     throw new Error("INSTALLED_PACKAGE_BYTES_MISMATCH");
   return expected.digest;
@@ -110987,6 +111127,24 @@ async function updateCopyfileRuntime(version2, options = {}) {
   if (!STABLE_SEMVER_PATTERN.test(version2))
     throw new Error("EXACT_STABLE_VERSION_REQUIRED");
   const policy = releaseAgePolicy(options);
+  let reviewedLockBytes;
+  if (options.reviewedLock !== undefined || options.reviewedLockSha256 !== undefined) {
+    if (!options.reviewedLock || !options.reviewedLockSha256)
+      throw new Error("REVIEWED_LOCK_INPUT_PAIR_REQUIRED");
+    if (!policy)
+      throw new Error("REVIEWED_LOCK_RELEASE_AGE_REQUIRED");
+    if (!isAbsolute25(options.reviewedLock))
+      throw new Error("REVIEWED_LOCK_ABSOLUTE_PATH_REQUIRED");
+    assertNoSymlinkAncestors(dirname31(options.reviewedLock));
+    const stat3 = lstatSync30(options.reviewedLock);
+    if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.nlink !== 1 || stat3.uid !== process.getuid?.() || stat3.mode & 63 || stat3.size > 8 * 1024 * 1024)
+      throw new Error("REVIEWED_LOCK_FILE_UNSAFE");
+    reviewedLockBytes = readFileSync38(options.reviewedLock);
+    if (!/^[a-f0-9]{64}$/.test(options.reviewedLockSha256))
+      throw new Error("REVIEWED_LOCK_SHA256_INVALID");
+    if (hash5(reviewedLockBytes) !== options.reviewedLockSha256)
+      throw new Error("REVIEWED_LOCK_HASH_MISMATCH");
+  }
   const home = resolve25(options.homeDir ?? process.env.HOME ?? "");
   if (!home || !existsSync34(home))
     throw new Error("HOME_NOT_FOUND");
@@ -111023,12 +111181,37 @@ async function updateCopyfileRuntime(version2, options = {}) {
     const stagePackage = join58(stagePath, "install");
     mkdirSync24(stagePackage, { mode: 448 });
     copyFileSync(artifact.tarballPath, join58(stagePackage, "verified.tgz"));
-    writeFileSync23(join58(stagePackage, "package.json"), JSON.stringify({ private: true, dependencies: { [PACKAGE_NAME]: "file:./verified.tgz" } }, null, 2), { mode: 384, flag: "wx" });
-    const npmVersion = await runNpm(["install", "--package-lock-only", "--prefix", stagePackage], stagePackage, home, stagePath, policy);
+    writeFileSync23(join58(stagePackage, "package.json"), JSON.stringify({ name: "skills-runtime-install", version: "0.0.0", private: true, dependencies: { [PACKAGE_NAME]: "file:./verified.tgz" } }, null, 2), { mode: 384, flag: "wx" });
+    let npmVersion;
+    if (reviewedLockBytes) {
+      await validateReviewedRuntimeLock(reviewedLockBytes, options.reviewedLockSha256, {
+        version: version2,
+        archiveIntegrity: artifact.integrity,
+        packageManifest: object9(JSON.parse(readFileSync38(join58(stagePath, "verified-archive", "package", "package.json"), "utf8")), "PACKAGE_MANIFEST_INVALID"),
+        registryOrigin: REGISTRY_ORIGIN,
+        ...policy,
+        fetcher
+      });
+      writeFileSync23(join58(stagePackage, "package-lock.json"), reviewedLockBytes, { mode: 384, flag: "wx" });
+      if (!readFileSync38(join58(stagePackage, "package-lock.json")).equals(reviewedLockBytes))
+        throw new Error("REVIEWED_LOCK_COPY_MISMATCH");
+    } else {
+      npmVersion = await runNpm(["install", "--package-lock-only", "--prefix", stagePackage], stagePackage, home, stagePath, policy);
+    }
     const ciNpmVersion = await runNpm(["ci", "--prefix", stagePackage], stagePackage, home, stagePath, policy);
-    if (npmVersion !== ciNpmVersion)
+    if (!reviewedLockBytes && npmVersion !== ciNpmVersion)
       throw new Error("NPM_VERSION_DRIFT_DURING_UPDATE");
+    npmVersion = ciNpmVersion;
     const lockBytes = readFileSync38(join58(stagePackage, "package-lock.json"));
+    if (reviewedLockBytes) {
+      if (!lockBytes.equals(reviewedLockBytes))
+        throw new Error("REVIEWED_LOCK_DRIFT_DURING_INSTALL");
+      const treeNpmVersion = await runNpm(["sbom", "--sbom-format=cyclonedx", "--package-lock-only=false", "--omit=dev", "--prefix", stagePackage], stagePackage, home, stagePath, policy);
+      if (treeNpmVersion !== npmVersion)
+        throw new Error("NPM_VERSION_DRIFT_DURING_UPDATE");
+      if (!readFileSync38(join58(stagePackage, "package-lock.json")).equals(reviewedLockBytes))
+        throw new Error("REVIEWED_LOCK_DRIFT_DURING_INSTALL");
+    }
     const installedPackage = join58(stagePackage, "node_modules", "@hasna", "skills");
     const installed = readPackage(join58(installedPackage, "package.json"));
     if (installed.version !== version2 || JSON.stringify(Object.entries(installed.bins).sort()) !== JSON.stringify(Object.entries(layout.bin).sort())) {
@@ -111069,6 +111252,7 @@ async function updateCopyfileRuntime(version2, options = {}) {
       configs: configPreimages,
       preimageSha256,
       ...policy ? { dependencyPolicy: { ...policy, npmVersion } } : {},
+      ...reviewedLockBytes ? { reviewedLockSha256: options.reviewedLockSha256 } : {},
       launchers,
       switchedLaunchers: [],
       rollbackCompletedLaunchers: []
@@ -111107,7 +111291,7 @@ async function updateCopyfileRuntime(version2, options = {}) {
     }
     receipt.state = "switched";
     persistReceipt(join58(finalPath, "rollout-receipt.json"), receipt);
-    return { updated: true, version: version2, currentVersion: layout.currentVersion, receiptId: id2, runtimeRoot: finalPath, tarballSha256: artifact.sha256, tarballIntegrity: artifact.integrity, runtimeTreeSha256: stagedTree.digest, launcherCount: launchers.length, configCount: configPreimages.length, ...policy ? { dependencyPolicy: { ...policy, npmVersion } } : {} };
+    return { updated: true, version: version2, currentVersion: layout.currentVersion, receiptId: id2, runtimeRoot: finalPath, tarballSha256: artifact.sha256, tarballIntegrity: artifact.integrity, runtimeTreeSha256: stagedTree.digest, launcherCount: launchers.length, configCount: configPreimages.length, ...policy ? { dependencyPolicy: { ...policy, npmVersion } } : {}, ...reviewedLockBytes ? { reviewedLockSha256: options.reviewedLockSha256 } : {} };
   } catch (error61) {
     if (switched.length > 0 || moved) {
       let rollbackFailed = false;
@@ -111244,6 +111428,7 @@ function rollbackCopyfileRuntime(receiptId, options = {}) {
 var PACKAGE_NAME = "@hasna/skills", REGISTRY_ORIGIN = "https://registry.npmjs.org", STABLE_SEMVER_PATTERN, MAX_TARBALL_BYTES, MAX_TARBALL_EXPANDED_BYTES, MAX_TARBALL_ENTRIES = 20000, CONFIG_PREIMAGE_PATHS;
 var init_runtime_copyfile = __esm(() => {
   init_skill_contract();
+  init_reviewed_runtime_lock();
   STABLE_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
   MAX_TARBALL_BYTES = 100 * 1024 * 1024;
   MAX_TARBALL_EXPANDED_BYTES = 256 * 1024 * 1024;
@@ -111260,7 +111445,7 @@ var exports_runtime = {};
 __export(exports_runtime, {
   registerRuntime: () => registerRuntime
 });
-import { createHash as createHash31, randomUUID as randomUUID10 } from "crypto";
+import { createHash as createHash32, randomUUID as randomUUID10 } from "crypto";
 import { lstatSync as lstatSync31, mkdirSync as mkdirSync25, readFileSync as readFileSync39, realpathSync as realpathSync17, writeFileSync as writeFileSync24 } from "fs";
 import { basename as basename16, isAbsolute as isAbsolute26, join as join59 } from "path";
 import { createInterface } from "readline";
@@ -111301,7 +111486,7 @@ function registerRuntime(parent) {
       if (!expected)
         throw new Error("Cloud artifact not found");
       const bytes = await client2.download(id2, name);
-      if (bytes.length !== expected.byteSize || createHash31("sha256").update(bytes).digest("hex") !== expected.sha256)
+      if (bytes.length !== expected.byteSize || createHash32("sha256").update(bytes).digest("hex") !== expected.sha256)
         throw new Error("Cloud artifact integrity verification failed");
       writeFileSync24(options.output, bytes, { flag: "wx", mode: 384 });
       console.log(JSON.stringify({ path: options.output, sha256: expected.sha256, byteSize: bytes.length }));
@@ -111331,7 +111516,12 @@ function registerRuntime(parent) {
   });
   const setup = parent.command("setup").description("Point this CLI at a Skills API server, or register agent integrations").option("--api-url <url>", "Skills API origin to send remote work to").option("--global", "Accepted for compatibility; the API origin is always per-user", false).option("--json", "Output setup result as JSON", false).action(async (options) => handleSetup(options));
   setup.command("agents").option("--json", "Output registration result as JSON", false).description("Register the Skills MCP server with all supported agents").action(async (options) => handleMcp({ register: "all", json: options.json }));
-  parent.command("self-update").description("Update @hasna/skills to the latest version").option("--json", "Output result as JSON", false).option("--version <version>", "Install this exact @hasna/skills version as a staged copyfile runtime").option("--min-release-age <days>", "Require a positive integer dependency release age in days for an exact-version update").option("--min-release-age-exclude <pattern>", "Exclude matching package identities from the release-age policy (repeatable)", (pattern, prior) => [...prior, pattern], []).option("--rollback <receipt-id>", "Restore launcher links from an exact copyfile rollout receipt").option("--adopt-aliases", "Switch verified legacy @hasna/skills aliases to the active copyfile runtime").option("--rollback-aliases <receipt-id>", "Restore aliases from an exact adoption receipt").action(async (options) => {
+  parent.command("self-update").description("Update @hasna/skills to the latest version").option("--json", "Output result as JSON", false).option("--version <version>", "Install this exact @hasna/skills version as a staged copyfile runtime").option("--min-release-age <days>", "Require a positive integer dependency release age in days for an exact-version update").option("--min-release-age-exclude <pattern>", "Exclude matching package identities from the release-age policy (repeatable)", (pattern, prior) => [...prior, pattern], []).option("--reviewed-lock <path>", "Install from this private absolute package-lock.json path without resolving dependency ranges").option("--reviewed-lock-sha256 <sha256>", "Exact reviewed SHA-256 of the supplied package-lock.json").option("--rollback <receipt-id>", "Restore launcher links from an exact copyfile rollout receipt").option("--adopt-aliases", "Switch verified legacy @hasna/skills aliases to the active copyfile runtime").option("--rollback-aliases <receipt-id>", "Restore aliases from an exact adoption receipt").action(async (options) => {
+    if ((options.reviewedLock !== undefined || options.reviewedLockSha256 !== undefined) && (!options.version || options.rollback || options.adoptAliases || options.rollbackAliases)) {
+      console.error(JSON.stringify({ error: "REVIEWED_LOCK_REQUIRES_EXACT_VERSION" }));
+      process.exitCode = 1;
+      return;
+    }
     if ((options.minReleaseAge !== undefined || options.minReleaseAgeExclude.length > 0) && (!options.version || options.rollback || options.adoptAliases || options.rollbackAliases)) {
       console.error(JSON.stringify({ error: "RELEASE_AGE_POLICY_REQUIRES_EXACT_VERSION" }));
       process.exitCode = 1;
@@ -111373,7 +111563,7 @@ function registerRuntime(parent) {
     if (options.version) {
       try {
         const minReleaseAge = options.minReleaseAge === undefined ? undefined : /^\d+$/.test(options.minReleaseAge) ? Number(options.minReleaseAge) : NaN;
-        const result2 = await updateCopyfileRuntime(options.version, { minReleaseAge, minReleaseAgeExclude: options.minReleaseAgeExclude });
+        const result2 = await updateCopyfileRuntime(options.version, { minReleaseAge, minReleaseAgeExclude: options.minReleaseAgeExclude, reviewedLock: options.reviewedLock, reviewedLockSha256: options.reviewedLockSha256 });
         if (options.json)
           console.log(JSON.stringify(result2));
         else
@@ -112950,7 +113140,7 @@ var init_portable_snapshot_filter = __esm(() => {
 });
 
 // src/lib/station-snapshot.ts
-import { createHash as createHash32 } from "crypto";
+import { createHash as createHash33 } from "crypto";
 import {
   copyFileSync as copyFileSync2,
   mkdirSync as mkdirSync26,
@@ -112965,7 +113155,7 @@ function validateStationId(stationId) {
   }
 }
 function sha256File(filePath) {
-  return createHash32("sha256").update(readFileSync40(filePath)).digest("hex");
+  return createHash33("sha256").update(readFileSync40(filePath)).digest("hex");
 }
 function scanHome(definition, homesRoot) {
   const homePath = homePathFor(definition, homesRoot);
@@ -113655,7 +113845,7 @@ var init_codex_hook_policy_recovery = __esm(() => {
 
 // src/lib/agent-codex-trust.ts
 import { lstatSync as lstatSync33, mkdirSync as mkdirSync27, readdirSync as readdirSync23, readFileSync as readFileSync41, realpathSync as realpathSync19, statSync as statSync22 } from "fs";
-import { createHash as createHash33, randomUUID as randomUUID11 } from "crypto";
+import { createHash as createHash34, randomUUID as randomUUID11 } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import { dirname as dirname35, isAbsolute as isAbsolute29, join as join63, resolve as resolve27 } from "path";
 import { homedir as homedir12 } from "os";
@@ -113665,11 +113855,11 @@ function verifyReleaseArtifact(proof, skillsCli) {
   const tarPath = realpathSync19(proof.packageTarPath);
   need5(statSync22(tarPath).isFile(), "RECONCILE_RELEASE_PROVENANCE_PATH");
   const tarBytes = readFileSync41(tarPath);
-  need5(tarBytes.byteLength === proof.packageTarBytes && createHash33("sha256").update(tarBytes).digest("hex") === proof.packageTarSha256, "RECONCILE_RELEASE_ARTIFACT_CHANGED");
+  need5(tarBytes.byteLength === proof.packageTarBytes && createHash34("sha256").update(tarBytes).digest("hex") === proof.packageTarSha256, "RECONCILE_RELEASE_ARTIFACT_CHANGED");
   const packageRoot = dirname35(dirname35(realpathSync19(skillsCli.receipt.path)));
   const manifest = readFileSync41(join63(packageRoot, "package.json"));
-  need5(createHash33("sha256").update(manifest).digest("hex") === skillsCli.receipt.manifestSha256 && skillsCli.receipt.manifestSha256 === proof.manifestSha256, "RECONCILE_RELEASE_MANIFEST_CHANGED");
-  need5(createHash33("sha256").update(readFileSync41(skillsCli.receipt.path)).digest("hex") === proof.executableSha256 && skillsCli.receipt.sha256 === proof.executableSha256, "RECONCILE_RELEASE_EXECUTABLE_CHANGED");
+  need5(createHash34("sha256").update(manifest).digest("hex") === skillsCli.receipt.manifestSha256 && skillsCli.receipt.manifestSha256 === proof.manifestSha256, "RECONCILE_RELEASE_MANIFEST_CHANGED");
+  need5(createHash34("sha256").update(readFileSync41(skillsCli.receipt.path)).digest("hex") === proof.executableSha256 && skillsCli.receipt.sha256 === proof.executableSha256, "RECONCILE_RELEASE_EXECUTABLE_CHANGED");
   const members2 = [["package/package.json", manifest], ["package/bin/index.js", readFileSync41(skillsCli.receipt.path)]];
   for (const [member, expected] of members2) {
     let actual;
@@ -113987,7 +114177,7 @@ async function enrollCodexNativeHooksUnlocked(options, connect) {
   }
 }
 var json2 = (value) => JSON.stringify(value, null, 2) + `
-`, structure3 = (text4) => JSON.parse(JSON.stringify(Bun.TOML.parse(text4))), eventNames, makePlanDigest = (value) => createHash33("sha256").update(json2(value)).digest("hex"), safeNativeHook = (hook) => ({ key: hook.key, eventName: hook.eventName, handlerType: hook.handlerType, command: hook.command, matcher: hook.matcher, timeoutSec: hook.timeoutSec, async: hook.async, statusMessage: hook.statusMessage, additionalContextLimit: hook.additionalContextLimit, sourcePath: hook.sourcePath, source: hook.source, pluginId: hook.pluginId, isManaged: hook.isManaged, currentHash: hook.currentHash, enabled: hook.enabled, trustStatus: hook.trustStatus }), withoutCodexCommand = (value) => {
+`, structure3 = (text4) => JSON.parse(JSON.stringify(Bun.TOML.parse(text4))), eventNames, makePlanDigest = (value) => createHash34("sha256").update(json2(value)).digest("hex"), safeNativeHook = (hook) => ({ key: hook.key, eventName: hook.eventName, handlerType: hook.handlerType, command: hook.command, matcher: hook.matcher, timeoutSec: hook.timeoutSec, async: hook.async, statusMessage: hook.statusMessage, additionalContextLimit: hook.additionalContextLimit, sourcePath: hook.sourcePath, source: hook.source, pluginId: hook.pluginId, isManaged: hook.isManaged, currentHash: hook.currentHash, enabled: hook.enabled, trustStatus: hook.trustStatus }), withoutCodexCommand = (value) => {
   const copy = structuredClone(value);
   if (copy?.bridge?.commands && Object.hasOwn(copy.bridge.commands, "codex"))
     copy.bridge.commands.codex = "<reviewed-codex-binding>";
@@ -114129,7 +114319,7 @@ __export(exports_agent_integration, {
   registerAgentIntegration: () => registerAgentIntegration
 });
 import { existsSync as existsSync36, lstatSync as lstatSync34, readFileSync as readFileSync42, readSync as readSync17, writeFileSync as writeFileSync26 } from "fs";
-import { createHash as createHash34 } from "crypto";
+import { createHash as createHash35 } from "crypto";
 import { homedir as homedir13 } from "os";
 import { isAbsolute as isAbsolute30 } from "path";
 function pinnedHookProfile(input3, configuredProfile) {
@@ -114254,7 +114444,7 @@ function registerAgentIntegration(parent) {
         skillCount: catalog.skills.length,
         output: options.output,
         bytes: Buffer.byteLength(bytes),
-        sha256: createHash34("sha256").update(bytes).digest("hex")
+        sha256: createHash35("sha256").update(bytes).digest("hex")
       };
       await writeCliOutput(options.json ? JSON.stringify(receipt) : `Captured ${receipt.skillCount} native Codex skill(s) in ${receipt.output}.`);
     } catch (error61) {
@@ -114770,7 +114960,7 @@ var init_grants = __esm(() => {
 });
 
 // src/lib/station-hydrate.ts
-import { createHash as createHash35 } from "crypto";
+import { createHash as createHash36 } from "crypto";
 import {
   copyFileSync as copyFileSync3,
   mkdirSync as mkdirSync28,
@@ -114973,7 +115163,7 @@ function skillSha256(skill) {
     return sha256File(skill.files[0].winner.fullPath);
   }
   const joined = skill.files.map((file2) => sha256File(file2.winner.fullPath));
-  return createHash35("sha256").update(joined.sort().join(`
+  return createHash36("sha256").update(joined.sort().join(`
 `)).digest("hex");
 }
 function writeStationHydration(options) {
@@ -115130,7 +115320,7 @@ var init_hydrate = __esm(() => {
 });
 
 // src/lib/prepare-skill.ts
-import { createHash as createHash36, randomUUID as randomUUID12 } from "crypto";
+import { createHash as createHash37, randomUUID as randomUUID12 } from "crypto";
 import { chmodSync as chmodSync5, existsSync as existsSync37, lstatSync as lstatSync35, mkdirSync as mkdirSync29, mkdtempSync as mkdtempSync6, readFileSync as readFileSync44, readdirSync as readdirSync25, renameSync as renameSync14, rmSync as rmSync9, writeFileSync as writeFileSync30 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
 import { dirname as dirname37, isAbsolute as isAbsolute31, join as join65, relative as relative12, resolve as resolve29, sep as sep15 } from "path";
@@ -115329,7 +115519,7 @@ function snapshot2(root2) {
   if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
     throw new Error("Skill root must be a real directory, not a symlink.");
   const files = [], directories = [];
-  const hash6 = createHash36("sha256").update(`${rootStat.dev}:${rootStat.ino}\x00`);
+  const hash6 = createHash37("sha256").update(`${rootStat.dev}:${rootStat.ino}\x00`);
   let count = 0, bytes = 0;
   const walk2 = (relative13) => {
     for (const name of readdirSync25(join65(root2, relative13)).sort()) {
@@ -115760,7 +115950,7 @@ function createRegistrySyncArtifact(options = {}) {
   const includeDocs = options.includeDocs ?? true;
   const includeRequirements = options.includeRequirements ?? true;
   const includeValidation = options.includeValidation ?? true;
-  const packageName = options.packageName ?? "@hasna/skills";
+  const packageName2 = options.packageName ?? "@hasna/skills";
   const packageVersion = options.packageVersion ?? package_default.version;
   const sourceRepository = options.sourceRepository ?? "hasna/skills";
   const registry2 = [...loadRegistryProfile(profile)].sort((a, b) => a.name.localeCompare(b.name));
@@ -115778,7 +115968,7 @@ function createRegistrySyncArtifact(options = {}) {
       tags: [...skill.tags].sort(),
       dependencies: [...skill.dependencies ?? []].sort(),
       source: {
-        packageName,
+        packageName: packageName2,
         packageVersion,
         repository: sourceRepository,
         directory: directory2
@@ -115796,7 +115986,7 @@ function createRegistrySyncArtifact(options = {}) {
   return {
     schemaVersion: 1,
     source: {
-      packageName,
+      packageName: packageName2,
       packageVersion,
       repository: sourceRepository,
       profile
@@ -115872,10 +116062,10 @@ async function exportSkillVersionForReview(spec, output2, client2) {
   const target = assertPrivateDestination(output2);
   if (existsSync38(target))
     throw new Error("Review output already exists; choose a new filename.");
-  const metadata = await client2.getSkillVersion(slug2, version2);
-  if (!metadata)
+  const metadata2 = await client2.getSkillVersion(slug2, version2);
+  if (!metadata2)
     throw new Error(`Published skill version ${slug2}@${version2} was not found.`);
-  if (!/^[a-f0-9]{64}$/i.test(metadata.bundleSha256) || !Number.isSafeInteger(metadata.bundleByteSize) || metadata.bundleByteSize < 1 || metadata.bundleByteSize > MAX_REVIEW_BUNDLE_BYTES) {
+  if (!/^[a-f0-9]{64}$/i.test(metadata2.bundleSha256) || !Number.isSafeInteger(metadata2.bundleByteSize) || metadata2.bundleByteSize < 1 || metadata2.bundleByteSize > MAX_REVIEW_BUNDLE_BYTES) {
     throw new Error("Published bundle metadata is invalid or exceeds the review size limit.");
   }
   const response = await client2.getBundle(slug2, version2);
@@ -115887,12 +116077,12 @@ async function exportSkillVersionForReview(spec, output2, client2) {
   }
   const headerSha = response.headers.get("X-Skill-Bundle-Sha256");
   const headerVersion = response.headers.get("X-Skill-Version");
-  if (!headerSha || headerSha.toLowerCase() !== metadata.bundleSha256.toLowerCase() || headerVersion !== version2) {
+  if (!headerSha || headerSha.toLowerCase() !== metadata2.bundleSha256.toLowerCase() || headerVersion !== version2) {
     response.body?.cancel().catch(() => {});
     throw new Error("Published bundle headers do not match the exact version metadata.");
   }
-  const bytes = await readBoundedResponse(response, Math.min(metadata.bundleByteSize, MAX_REVIEW_BUNDLE_BYTES));
-  if (bytes.byteLength !== metadata.bundleByteSize || sha256Hex(bytes) !== metadata.bundleSha256.toLowerCase()) {
+  const bytes = await readBoundedResponse(response, Math.min(metadata2.bundleByteSize, MAX_REVIEW_BUNDLE_BYTES));
+  if (bytes.byteLength !== metadata2.bundleByteSize || sha256Hex(bytes) !== metadata2.bundleSha256.toLowerCase()) {
     throw new Error("Published bundle bytes do not match the exact version metadata.");
   }
   const fd = openSync25(target, constants23.O_WRONLY | constants23.O_CREAT | constants23.O_EXCL | constants23.O_NOFOLLOW, 384);
@@ -115906,7 +116096,7 @@ async function exportSkillVersionForReview(spec, output2, client2) {
   } finally {
     closeSync25(fd);
   }
-  return { slug: slug2, version: version2, bundleSha256: metadata.bundleSha256.toLowerCase(), bundleByteSize: bytes.byteLength, output: target };
+  return { slug: slug2, version: version2, bundleSha256: metadata2.bundleSha256.toLowerCase(), bundleByteSize: bytes.byteLength, output: target };
 }
 var MAX_REVIEW_BUNDLE_BYTES, SLUG2, NATIVE_CONTAINERS;
 var init_review_export = __esm(() => {
@@ -118090,10 +118280,10 @@ async function reconcileRegistry(options = {}) {
     throw new ReconcileRegistryError(`Registry listing failed: expected an array of skills, got ${shape}.`, ["Check HASNA_SKILLS_API_URL and the resolved credential; a failed listing must not be read as an empty registry."]);
   }
   const remotes = new Map;
-  for (const row of remoteRowsPayload) {
-    if (!row || typeof row !== "object")
+  for (const row2 of remoteRowsPayload) {
+    if (!row2 || typeof row2 !== "object")
       continue;
-    const skill = remoteRowToSkill(row);
+    const skill = remoteRowToSkill(row2);
     if (skill)
       remotes.set(skill.slug, skill);
   }

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.38",
+    version: "0.10.41",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.38",
+  version: "0.10.41",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24122,7 +24122,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.38",
+  version: "0.10.41",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24125,7 +24125,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.38",
+  version: "0.10.41",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/cli/commands/reviewed-runtime-lock.d.ts

@@ -0,0 +1,17 @@
+type Row = Record<string, unknown>;
+export interface ReviewedRuntimeLockContext {
+    version: string;
+    archiveIntegrity: string;
+    packageManifest: Row;
+    registryOrigin: string;
+    minReleaseAge: number;
+    minReleaseAgeExclude: string[];
+    fetcher?: typeof fetch;
+    now?: number;
+}
+/** Validate the immutable install input without resolving any version ranges.
+ * npm ci subsequently verifies archive bytes and package/root range agreement;
+ * npm sbom forceActual validates the installed required closure, including optional peers.
+ */
+export declare function validateReviewedRuntimeLock(bytes: Uint8Array, sha256: string, context: ReviewedRuntimeLockContext): Promise<void>;
+export {};

package/dist/cli/commands/runtime-copyfile.d.ts

@@ -28,6 +28,8 @@ export declare function updateCopyfileRuntime(version: string, options?: {
     fetcher?: typeof fetch;
     minReleaseAge?: number;
     minReleaseAgeExclude?: string[];
+    reviewedLock?: string;
+    reviewedLockSha256?: string;
     onLauncherSwitched?: (path: string) => void;
 }): Promise<JsonObject>;
 export declare function rollbackCopyfileRuntime(receiptId: string, options?: {

package/dist/index.js

@@ -11040,7 +11040,7 @@ function replaceSkillSession(expected, replacement, plan, options = {}, beforeCo
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.38",
+  version: "0.10.41",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.38",
+  version: "0.10.41",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.38",
+  "version": "0.10.41",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {