securenow 8.23.0 → 8.25.0

package/app-config.js

@@ -8,14 +8,16 @@
  * Named runtime files such as ./.securenow/credentials.staging.json and
  * ./.securenow/credentials.production.json are also accepted when the
  * canonical file is not present. Filename selection is deterministic and does
- * not read environment variables.
+ * not depend on NODE_ENV.
  * Every SDK setting has a file-backed equivalent so customers do not need
- * .env files.
+ * .env files. Hosts that cannot mount a file (Vercel, Railway, Render, Heroku,
+ * Fly) pass the same JSON in one variable, SECURENOW_CREDENTIALS.
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { readPm2Env } = require('./pm2-env');
 
 // Shared SecureNow Cloud ingestion gateway (production collector for every
 // paying account and for the 14-day trial).
@@ -42,6 +44,7 @@ const ADMIN_CREDENTIALS_FILENAME = 'admin.json';
 const DEFAULT_CONFIG = Object.freeze({
   logging: {
     enabled: true,
+    redact: true,
   },
   capture: {
     body: true,
@@ -94,6 +97,11 @@ const DEFAULT_CONFIG = Object.freeze({
   networking: {
     trustedProxies: [],
   },
+  sessions: {
+    guard: false,
+    capture: false,
+    cookieNames: [],
+  },
 });
 
 const CONFIG_EXPLANATIONS = Object.freeze({
@@ -103,6 +111,7 @@ const CONFIG_EXPLANATIONS = Object.freeze({
   'app.name': 'Human-readable app label shown in CLI output.',
   'app.routing': 'Telemetry uses the default SecureNow ingestion gateway and routes by app.key; runtime credentials do not expose per-instance collector URLs.',
   'config.logging.enabled': 'Secure default: console log forwarding is on. Set false to disable OTLP logs.',
+  'config.logging.redact': 'Secure default: exported log lines are redacted. Credential fields (password, token, apiKey, authorization, cookie, OTP codes, card numbers...) in logged objects, JSON and key=value text, and secret shapes anywhere (JWTs, Bearer/Basic credentials, sk_/pk_/rk_/snk_ keys, card numbers, emails) become [REDACTED]; the terminal still shows the line as written. Set false to export lines as written.',
   'config.capture.body': 'Secure default: JSON, GraphQL, and form request bodies are captured with redaction.',
   'config.capture.multipart': 'Secure default: multipart text fields and file metadata are captured. File content is never buffered.',
   'config.capture.maxBodySize': 'Maximum body bytes captured per request. Default 10KB limits memory and sensitive data exposure.',
@@ -133,7 +142,10 @@ const CONFIG_EXPLANATIONS = Object.freeze({
   'config.firewall.cloudflare': 'Cloudflare API token/account id for Layer 4 WAF. Secrets: do not commit.',
   'config.firewall.aws': 'AWS WAF IP set configuration for Layer 4 WAF.',
   'config.firewall.gcp': 'GCP Cloud Armor policy configuration for Layer 4 WAF.',
-  'config.networking.trustedProxies': 'Additional proxies whose X-Forwarded-For headers should be trusted: IPs, IPv4 ranges (CIDR) or "cloudflare".',
+  'config.networking.trustedProxies': 'Additional proxies whose X-Forwarded-For headers should be trusted: IPs, IPv4 ranges (CIDR) or "cloudflare". Private, loopback and Unix-socket connections are trusted by default.',
+  'config.sessions.guard': 'If true, every request whose session or user was revoked gets a 401, in any framework, with no code (session = SHA-256 of the Bearer token or session cookie; user = JWT sub).',
+  'config.sessions.capture': 'If true, requests with a session send session.seen (deduplicated per session and IP every 5 minutes) so SecureNow can detect a stolen session.',
+  'config.sessions.cookieNames': 'Session cookie names to read besides next-auth, connect.sid, session and sid.',
 });
 
 function clone(value) {
@@ -240,7 +252,20 @@ function credentialRelativePaths() {
   return runtimeCredentialRelativePaths();
 }
 
-function resolveLocalFileFromRelativePaths(relativePaths) {
+// Where to look for .securenow/ files and package.json. A PM2 process is searched from the app
+// folder PM2 recorded and nowhere else: in cluster mode the worker's working directory is still
+// the PM2 daemon's when the preload runs, so searching from it found nothing, or another
+// project's credentials if the daemon was started inside that project.
+function searchStartDirs() {
+  const pm2 = readPm2Env();
+  if (pm2 && (pm2.cwd || pm2.execPath)) {
+    const appDir = pm2.cwd ? path.resolve(pm2.cwd) : null;
+    return uniq([
+      appDir,
+      pm2.execPath ? path.dirname(path.resolve(appDir || '.', pm2.execPath)) : null,
+    ]);
+  }
+
   const starts = [];
   try {
     if (typeof process !== 'undefined' && process.cwd) starts.push(process.cwd());
@@ -250,8 +275,12 @@ function resolveLocalFileFromRelativePaths(relativePaths) {
   if (process.argv && process.argv[1]) starts.push(path.dirname(process.argv[1]));
   if (require.main && require.main.filename) starts.push(path.dirname(require.main.filename));
 
+  return uniq(starts);
+}
+
+function resolveLocalFileFromRelativePaths(relativePaths) {
   const candidates = relativePaths;
-  for (const start of uniq(starts)) {
+  for (const start of searchStartDirs()) {
     const found = findUpFirstFile(start, candidates);
     if (found) return found;
   }
@@ -314,16 +343,7 @@ function runtimeCredentialsFromDocument(credentials) {
 }
 
 function resolvePackageJsonFile() {
-  const starts = [];
-  try {
-    if (typeof process !== 'undefined' && process.cwd) starts.push(process.cwd());
-  } catch {}
-
-  if (process.env.INIT_CWD) starts.push(process.env.INIT_CWD);
-  if (process.argv && process.argv[1]) starts.push(path.dirname(process.argv[1]));
-  if (require.main && require.main.filename) starts.push(path.dirname(require.main.filename));
-
-  for (const start of uniq(starts)) {
+  for (const start of searchStartDirs()) {
     const found = findUpFile(start, 'package.json');
     if (found) return found;
   }
@@ -347,7 +367,50 @@ function loadGlobalCredentials() {
   }
 }
 
+const ENV_CREDENTIALS_VAR = 'SECURENOW_CREDENTIALS';
+let _envCredentials = { raw: undefined, value: null };
+let _warnedBadEnvCredentials = false;
+
+// Runtime credentials passed in the environment, for hosts that cannot mount a file. The value is
+// the JSON written by `npx securenow credentials runtime`, raw or base64-encoded (`--format env`
+// prints it ready to paste). When set it takes precedence over credential files.
+function loadEnvCredentials() {
+  const raw = typeof process !== 'undefined' && process.env ? process.env[ENV_CREDENTIALS_VAR] : undefined;
+  if (raw !== _envCredentials.raw) {
+    let value = null;
+    const text = raw == null ? '' : String(raw).trim();
+    if (text) {
+      try {
+        const json = text.startsWith('{') ? text : Buffer.from(text, 'base64').toString('utf8');
+        value = withCredentialDefaults(runtimeCredentialsFromDocument(JSON.parse(json.replace(/^\uFEFF/, ''))));
+      } catch {
+        value = null;
+      }
+      if (!value && !_warnedBadEnvCredentials) {
+        _warnedBadEnvCredentials = true;
+        try {
+          console.warn('[securenow] %s is set but is not runtime credentials JSON (raw or base64); ignoring it.', ENV_CREDENTIALS_VAR);
+        } catch {}
+      }
+    }
+    _envCredentials = { raw, value };
+  }
+  return _envCredentials.value ? clone(_envCredentials.value) : null;
+}
+
+// Where the runtime credentials came from, for the startup log: never their content.
+function describeCredentialsSource() {
+  try {
+    if (loadEnvCredentials()) return `env:${ENV_CREDENTIALS_VAR}`;
+    return resolveLocalCredentialsFile() || resolveGlobalCredentialsFile() || 'none';
+  } catch {
+    return 'none';
+  }
+}
+
 function loadCredentials() {
+  const fromEnv = loadEnvCredentials();
+  if (fromEnv) return fromEnv;
   try {
     const localFile = resolveLocalCredentialsFile();
     if (localFile) {
@@ -692,6 +755,13 @@ function resolveEndpoints(options = {}) {
   };
 }
 
+function resolveSessionsOptions() {
+  return {
+    guard: boolConfig('sessions.guard', false),
+    capture: boolConfig('sessions.capture', false),
+  };
+}
+
 function resolveFirewallEnabled() {
   return true;
 }
@@ -764,6 +834,7 @@ module.exports = {
   resolveOtlpHeaderString,
   resolveEndpoints,
   resolveFirewallEnabled,
+  resolveSessionsOptions,
   normalizeFirewallApiUrl,
   resolveFirewallApiUrl,
   resolveFirewallApiFallbacks,
@@ -781,6 +852,10 @@ module.exports = {
   resolveLocalAdminCredentialsFile,
   resolveGlobalAdminCredentialsFile,
   loadCredentials,
+  loadEnvCredentials,
+  describeCredentialsSource,
+  searchStartDirs,
+  ENV_CREDENTIALS_VAR,
   loadLocalCredentials,
   loadGlobalCredentials,
   loadPackageJsonName,

package/cidr.js

@@ -2,7 +2,8 @@
 
 /**
  * Bitmask-based CIDR matching. No regex on user input — prevents ReDoS.
- * All operations use unsigned 32-bit integers for IPv4 addresses.
+ * IPv4 addresses are unsigned 32-bit integers; IPv6 addresses are 128-bit BigInts.
+ * An IPv4-mapped IPv6 address (::ffff:1.2.3.4) is treated as the IPv4 address it carries.
  */
 
 function ipToInt(ip) {
@@ -10,13 +11,99 @@ function ipToInt(ip) {
   if (parts.length !== 4) return null;
   let result = 0;
   for (let i = 0; i < 4; i++) {
+    if (!/^\d{1,3}$/.test(parts[i])) return null;
     const n = parseInt(parts[i], 10);
-    if (isNaN(n) || n < 0 || n > 255) return null;
+    if (n > 255) return null;
     result = (result << 8) + n;
   }
   return result >>> 0;
 }
 
+function intToIp(n) {
+  return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff].join('.');
+}
+
+const V6_BITS = 128n;
+const V6_ALL = (1n << V6_BITS) - 1n;
+
+// '2001:db8::1' -> BigInt. Accepts '::' compression, an IPv4 tail ('::ffff:1.2.3.4'),
+// brackets and a zone id ('fe80::1%eth0'). Returns null for anything else.
+function ipv6ToBigInt(ip) {
+  let s = String(ip || '').trim();
+  if (s.startsWith('[') && s.endsWith(']')) s = s.slice(1, -1);
+  const zone = s.indexOf('%');
+  if (zone !== -1) s = s.slice(0, zone);
+  if (!s.includes(':') || s.length > 45) return null;
+
+  // An IPv4 tail ('::ffff:1.2.3.4') is the last two groups.
+  let tail = [];
+  const lastColon = s.lastIndexOf(':');
+  if (s.indexOf('.', lastColon) !== -1) {
+    const v4 = ipToInt(s.slice(lastColon + 1));
+    if (v4 === null) return null;
+    tail = [(v4 >>> 16) & 0xffff, v4 & 0xffff];
+    s = s.slice(0, lastColon + 1);
+    if (!s.endsWith('::')) s = s.slice(0, -1);
+  }
+
+  const halves = s.split('::');
+  if (halves.length > 2) return null;
+  const groupsOf = (part) => {
+    if (part === '') return [];
+    const out = [];
+    for (const g of part.split(':')) {
+      if (!/^[0-9a-f]{1,4}$/i.test(g)) return null;
+      out.push(parseInt(g, 16));
+    }
+    return out;
+  };
+  const head = groupsOf(halves[0]);
+  const rest = halves.length === 2 ? groupsOf(halves[1]) : [];
+  if (!head || !rest) return null;
+  const total = head.length + rest.length + tail.length;
+  // '::' stands for at least one zero group.
+  if (halves.length === 2 ? total > 7 : total !== 8) return null;
+
+  const all = head.concat(new Array(8 - total).fill(0), rest, tail);
+  let n = 0n;
+  for (const g of all) n = (n << 16n) | BigInt(g);
+  return n;
+}
+
+function bigIntToIpv6(n) {
+  const groups = [];
+  for (let i = 7; i >= 0; i--) groups.push(Number((n >> BigInt(i * 16)) & 0xffffn).toString(16));
+  // Compress the longest run of zero groups (RFC 5952).
+  let best = -1; let bestLen = 0;
+  for (let i = 0; i < 8;) {
+    if (groups[i] !== '0') { i++; continue; }
+    let j = i;
+    while (j < 8 && groups[j] === '0') j++;
+    if (j - i > bestLen && j - i > 1) { best = i; bestLen = j - i; }
+    i = j;
+  }
+  if (best === -1) return groups.join(':');
+  return `${groups.slice(0, best).join(':')}::${groups.slice(best + bestLen).join(':')}`;
+}
+
+/**
+ * Classifies an address: { family: 4, int } or { family: 6, big }, with a canonical `key`
+ * for exact lookups. An IPv4-mapped IPv6 address comes back as family 4. Null if not an IP.
+ */
+function parseIp(ip) {
+  const s = String(ip || '').trim();
+  if (!s) return null;
+  const v4 = ipToInt(s);
+  if (v4 !== null) return { family: 4, int: v4, key: intToIp(v4) };
+  const big = ipv6ToBigInt(s);
+  if (big === null) return null;
+  if ((big >> 32n) === 0xffffn) {
+    const int = Number(big & 0xffffffffn) >>> 0;
+    return { family: 4, int, key: intToIp(int) };
+  }
+  return { family: 6, big, key: bigIntToIpv6(big) };
+}
+
 function parseCidr(cidr) {
   const slash = cidr.indexOf('/');
   if (slash === -1) return null;
@@ -29,44 +116,72 @@ function parseCidr(cidr) {
   return { network: (network & mask) >>> 0, mask };
 }
 
+/** '2001:db8::/32' -> { network, mask, bits } as BigInts. Null if not an IPv6 CIDR. */
+function parseCidr6(cidr) {
+  const slash = String(cidr || '').indexOf('/');
+  if (slash === -1) return null;
+  const suffix = cidr.slice(slash + 1).trim();
+  if (!/^\d{1,3}$/.test(suffix)) return null;
+  const bits = parseInt(suffix, 10);
+  if (bits > 128) return null;
+  const big = ipv6ToBigInt(cidr.slice(0, slash));
+  if (big === null) return null;
+  const mask = bits === 0 ? 0n : (V6_ALL << (V6_BITS - BigInt(bits))) & V6_ALL;
+  return { network: big & mask, mask, bits };
+}
+
 function matchesCidr(ipInt, cidrEntry) {
   return ((ipInt & cidrEntry.mask) >>> 0) === cidrEntry.network;
 }
 
 /**
- * Create a matcher from a list of IPs and CIDRs.
+ * Create a matcher from a list of IPv4/IPv6 addresses and CIDRs.
  * Returns { isBlocked(ip), stats() }.
- * Exact IPs use a Set for O(1) lookup; CIDRs use array scan (typically < 100 entries).
+ * Exact IPs use a Set of canonical forms for O(1) lookup ('2001:DB8:0::1' and '2001:db8::1'
+ * are the same entry); CIDRs use an array scan (typically < 100 entries).
  */
 function createMatcher(ipList) {
   const exactSet = new Set();
-  const cidrRanges = [];
+  const cidr4 = [];
+  const cidr6 = [];
 
-  for (const entry of ipList) {
+  for (const entry of ipList || []) {
     const trimmed = (entry || '').trim();
     if (!trimmed) continue;
 
     if (trimmed.includes('/')) {
-      const parsed = parseCidr(trimmed);
-      if (parsed) cidrRanges.push(parsed);
+      const v4 = parseCidr(trimmed);
+      if (v4) { cidr4.push(v4); continue; }
+      const v6 = parseCidr6(trimmed);
+      if (!v6) continue;
+      // ::ffff:0:0/96 and narrower are IPv4 ranges written in IPv6 form.
+      if (v6.bits >= 96 && (v6.network >> 32n) === 0xffffn) {
+        const bits = v6.bits - 96;
+        const mask = bits === 0 ? 0 : (~((1 << (32 - bits)) - 1)) >>> 0;
+        cidr4.push({ network: (Number(v6.network & 0xffffffffn) & mask) >>> 0, mask });
+      } else {
+        cidr6.push(v6);
+      }
     } else {
-      const normalized = trimmed.replace(/^::ffff:/, '');
-      exactSet.add(normalized);
+      const parsed = parseIp(trimmed);
+      exactSet.add(parsed ? parsed.key : trimmed);
     }
   }
 
   function isBlocked(ip) {
     if (!ip) return false;
-    const normalized = ip.replace(/^::ffff:/, '');
+    const parsed = parseIp(ip);
+    if (!parsed) return exactSet.has(String(ip).trim());
 
-    if (exactSet.has(normalized)) return true;
+    if (exactSet.has(parsed.key)) return true;
 
-    if (cidrRanges.length > 0) {
-      const ipInt = ipToInt(normalized);
-      if (ipInt !== null) {
-        for (const cidr of cidrRanges) {
-          if (matchesCidr(ipInt, cidr)) return true;
-        }
+    if (parsed.family === 4) {
+      for (const cidr of cidr4) {
+        if (matchesCidr(parsed.int, cidr)) return true;
+      }
+    } else {
+      for (const cidr of cidr6) {
+        if ((parsed.big & cidr.mask) === cidr.network) return true;
       }
     }
 
@@ -74,10 +189,14 @@ function createMatcher(ipList) {
   }
 
   function stats() {
-    return { exact: exactSet.size, cidr: cidrRanges.length, total: exactSet.size + cidrRanges.length };
+    const cidr = cidr4.length + cidr6.length;
+    return { exact: exactSet.size, cidr, total: exactSet.size + cidr };
   }
 
   return { isBlocked, stats };
 }
 
-module.exports = { ipToInt, parseCidr, matchesCidr, createMatcher };
+module.exports = {
+  ipToInt, intToIp, parseCidr, matchesCidr, createMatcher,
+  ipv6ToBigInt, bigIntToIpv6, parseCidr6, parseIp,
+};

package/cli/credentials.js

@@ -73,6 +73,17 @@ async function runtime(_args, flags) {
     warn('Runtime API key is missing. Run `npx securenow app connect` or `npx securenow api-key create` before generating production runtime credentials.');
   }
 
+  // For hosts that inject environment variables but cannot mount a file (Vercel, Railway,
+  // Render, Heroku, Fly): one line to paste as a secret. The SDK reads SECURENOW_CREDENTIALS
+  // (raw JSON or base64) before any credentials file.
+  if (flags.format === 'env' || flags['env-var']) {
+    const { ENV_CREDENTIALS_VAR } = appConfig;
+    const encoded = Buffer.from(JSON.stringify(creds), 'utf8').toString('base64');
+    console.log(`${ENV_CREDENTIALS_VAR}=${encoded}`);
+    console.error(`! This line contains the runtime API key. Store it as a secret variable named ${ENV_CREDENTIALS_VAR}; do not commit it.`);
+    return;
+  }
+
   if (flags.stdout) {
     console.log(JSON.stringify(creds, null, 2));
     return;

package/cli/init.js

@@ -5,7 +5,26 @@ const path = require('path');
 const ui = require('./ui');
 const config = require('./config');
 
+// The import sits inside the nodejs block, without webpackIgnore: Next.js drops the block from the
+// Edge build and traces securenow and its dependencies into standalone output (webpackIgnore hid
+// them from tracing, so a standalone image shipped without OpenTelemetry and every request failed).
+// The try/catch keeps the app serving if SecureNow cannot start.
 const INSTRUMENTATION = `export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const securenowNext = await import('securenow/nextjs');
+      const registerSecureNow = securenowNext.registerSecureNow || securenowNext.default?.registerSecureNow;
+      registerSecureNow({ captureBody: true });
+      await import('securenow/nextjs-auto-capture');
+    } catch (error) {
+      console.error('[securenow] SecureNow did not start; the app is running without it:', error);
+    }
+  }
+}
+`;
+
+// What init wrote before 8.24.0: replaced automatically when a file still holds exactly this.
+const LEGACY_INSTRUMENTATION = `export async function register() {
   if (process.env.NEXT_RUNTIME !== 'nodejs') return;
 
   const securenowNext = await import(/* webpackIgnore: true */ 'securenow/nextjs');
@@ -15,6 +34,10 @@ const INSTRUMENTATION = `export async function register() {
 }
 `;
 
+function isLegacyInstrumentation(content) {
+  return String(content || '').replace(/\r\n/g, '\n').trim() === LEGACY_INSTRUMENTATION.trim();
+}
+
 function detectProject(dir) {
   const pkgPath = path.join(dir, 'package.json');
   if (!fs.existsSync(pkgPath)) return { framework: 'unknown' };
@@ -39,6 +62,22 @@ function findInstrumentationFile(dir) {
   return null;
 }
 
+// Next.js loads instrumentation.* from the folder that holds app/ or pages/: src/ in a src layout,
+// where a file at the project root is never loaded.
+function usesSrcDir(dir) {
+  const inSrc = ['src/app', 'src/pages'].some((d) => fs.existsSync(path.join(dir, d)));
+  const inRoot = ['app', 'pages'].some((d) => fs.existsSync(path.join(dir, d)));
+  return inSrc && !inRoot;
+}
+
+function instrumentationIn(folder) {
+  for (const name of ['instrumentation.ts', 'instrumentation.js']) {
+    const p = path.join(folder, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
 function findNextConfig(dir) {
   for (const name of ['next.config.js', 'next.config.mjs', 'next.config.ts']) {
     const p = path.join(dir, name);
@@ -78,6 +117,7 @@ async function init(_args, flags) {
   } else {
     initNode(project);
   }
+  checkPm2Ecosystem(dir);
 
   console.log('');
   ui.success('Setup complete.');
@@ -108,17 +148,49 @@ function initCredentials(flags) {
 }
 
 async function initNextJs(dir, project, flags) {
-  const useTs = flags.javascript ? false : flags.typescript ? true : hasTypeScript(dir);
+  const useTs = (flags.javascript || flags.js) ? false : (flags.typescript || flags.ts) ? true : hasTypeScript(dir);
   const ext = useTs ? 'ts' : 'js';
-
-  const existing = findInstrumentationFile(dir);
-  if (existing) {
-    ui.info(`instrumentation file already exists: ${path.relative(dir, existing)}`);
-    printAgentPrompt('instrumentation', path.basename(existing), nextMajor(project), project);
+  const inSrc = flags.root ? false : flags.src ? true : usesSrcDir(dir);
+  const folder = inSrc ? path.join(dir, 'src') : dir;
+  const otherFolder = inSrc ? dir : path.join(dir, 'src');
+  const rel = (p) => path.relative(dir, p).split(path.sep).join('/');
+
+  // In a src/ layout, Next.js 14 and 15 load only src/instrumentation.*; 16 also loads a root file.
+  const major = nextMajor(project);
+  const existing = instrumentationIn(folder) || (inSrc && major >= 16 ? instrumentationIn(otherFolder) : null);
+  const misplaced = existing ? null : instrumentationIn(otherFolder);
+  if (existing && isLegacyInstrumentation(fs.readFileSync(existing, 'utf8'))) {
+    fs.writeFileSync(existing, INSTRUMENTATION, 'utf8');
+    ui.success(`Updated ${rel(existing)}: standalone builds now include SecureNow's dependencies`);
+  } else if (existing && flags.force) {
+    fs.copyFileSync(existing, `${existing}.bak`);
+    fs.writeFileSync(existing, INSTRUMENTATION, 'utf8');
+    ui.success(`Replaced ${rel(existing)} (--force); the previous file is in ${rel(existing)}.bak`);
+  } else if (existing) {
+    ui.info(`instrumentation file already exists: ${rel(existing)}`);
+    printAgentPrompt('instrumentation', rel(existing), nextMajor(project), project);
   } else {
-    const filePath = path.join(dir, `instrumentation.${ext}`);
-    fs.writeFileSync(filePath, INSTRUMENTATION, 'utf8');
-    ui.success(`Created instrumentation.${ext}`);
+    const filePath = path.join(folder, `instrumentation.${ext}`);
+    if (misplaced) {
+      // Next.js never loads a file in the other folder, so SecureNow would not start.
+      const ours = isLegacyInstrumentation(fs.readFileSync(misplaced, 'utf8'))
+        || fs.readFileSync(misplaced, 'utf8') === INSTRUMENTATION;
+      if (ours || flags.force) {
+        if (!ours) fs.copyFileSync(misplaced, `${misplaced}.bak`);
+        fs.mkdirSync(folder, { recursive: true });
+        fs.writeFileSync(filePath, INSTRUMENTATION, 'utf8');
+        fs.unlinkSync(misplaced);
+        ui.success(`Moved ${rel(misplaced)} to ${rel(filePath)}: Next.js loads instrumentation from ${inSrc ? 'src/' : 'the project root'} in this project${ours ? '' : ` (the previous file is in ${rel(misplaced)}.bak)`}`);
+      } else {
+        ui.warn(`${rel(misplaced)} is in the wrong folder: this project keeps app/ or pages/ ${inSrc ? 'in src/' : 'at the root'}, and Next.js loads instrumentation from there (${rel(filePath)}), so SecureNow would not start.`);
+        ui.info('Move it there (or rerun with --force to write SecureNow\'s file there and keep yours as .bak).');
+        printAgentPrompt('instrumentation', rel(filePath), major, project);
+      }
+    } else {
+      fs.mkdirSync(folder, { recursive: true });
+      fs.writeFileSync(filePath, INSTRUMENTATION, 'utf8');
+      ui.success(`Created ${rel(filePath)}`);
+    }
   }
 
   const configPath = findNextConfig(dir);
@@ -134,7 +206,12 @@ async function initNextJs(dir, project, flags) {
     }
   } else {
     const newConfigPath = path.join(dir, 'next.config.mjs');
-    fs.writeFileSync(newConfigPath, `/** @type {import('next').NextConfig} */
+    fs.writeFileSync(newConfigPath, nextMajor(project) < 15 ? NEXT14_CONFIG : NEXT_CONFIG, 'utf8');
+    ui.success('Created next.config.mjs');
+  }
+}
+
+const NEXT_CONFIG = `/** @type {import('next').NextConfig} */
 const nextConfig = {
   serverExternalPackages: ['securenow'],
   outputFileTracingIncludes: {
@@ -143,10 +220,22 @@ const nextConfig = {
 };
 
 export default nextConfig;
-`, 'utf8');
-    ui.success('Created next.config.mjs');
-  }
-}
+`;
+
+// Next.js 14 keeps these under experimental and needs the instrumentation hook switched on.
+const NEXT14_CONFIG = `/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    instrumentationHook: true,
+    serverComponentsExternalPackages: ['securenow'],
+    outputFileTracingIncludes: {
+      '/*': ['./node_modules/securenow/**/*'],
+    },
+  },
+};
+
+export default nextConfig;
+`;
 
 function patchNextConfig(configPath, major) {
   const content = fs.readFileSync(configPath, 'utf8');
@@ -239,13 +328,13 @@ function printAgentPrompt(kind, filename, major, project) {
       ? `Use the project scripts for verification when appropriate: ${commands}. Ask before starting long-running dev/start servers, and ask which command to use if these scripts are not the right customer workflow.`
       : 'Ask the customer which command starts, builds, and tests this app because package.json does not expose an obvious script.',
     kind === 'instrumentation'
-      ? `Merge this into ${filename}: in register(), return unless process.env.NEXT_RUNTIME === "nodejs"; then dynamically import "securenow/nextjs" and "securenow/nextjs-auto-capture" with /* webpackIgnore: true */ so Next does not bundle OpenTelemetry internals. Preserve all existing instrumentation.`
+      ? `Merge this into ${filename}: inside register(), in an if (process.env.NEXT_RUNTIME === "nodejs") { ... } block, wrapped in try/catch so the app keeps running if SecureNow cannot start, dynamically import "securenow/nextjs" (call its registerSecureNow({ captureBody: true })) and then "securenow/nextjs-auto-capture". Do not add webpackIgnore comments and do not use an early return: keeping the imports inside the nodejs block lets Next.js drop them from the Edge build and trace securenow's dependencies into standalone output. Preserve all existing instrumentation.`
       : null,
     kind === 'next-config' && major >= 15
       ? `Update ${filename} while preserving existing config: add securenow to serverExternalPackages, e.g. serverExternalPackages: [...(existing || []), "securenow"], and include SecureNow runtime files for standalone output with outputFileTracingIncludes: { "/*": ["./node_modules/securenow/**/*"] }.`
       : null,
     kind === 'next-config' && major < 15
-      ? `Update ${filename} while preserving existing config: enable experimental.instrumentationHook and add securenow to experimental.serverComponentsExternalPackages.`
+      ? `Update ${filename} while preserving existing config (Next.js 14): set experimental.instrumentationHook to true, add securenow to experimental.serverComponentsExternalPackages, and add experimental.outputFileTracingIncludes: { "/*": ["./node_modules/securenow/**/*"] } for standalone output.`
       : null,
     'Verify with: npx securenow env, npx securenow test-span, npx securenow status, plus the selected build/test command when available.',
     'Only smoke-test an HTTP URL when the user provides a local or production URL, the running app prints one, or project config clearly defines one. Do not invent localhost ports or production domains; ask for the URL and skip URL probes if none is available.',
@@ -267,6 +356,19 @@ function initNuxt(dir) {
   }
 }
 
+// In PM2 cluster mode Node resolves a bare `-r securenow/register` from the PM2 daemon's folder,
+// so workers started from elsewhere (pm2 resurrect at boot) crash with "Cannot find module".
+function checkPm2Ecosystem(dir) {
+  for (const name of ['ecosystem.config.cjs', 'ecosystem.config.js', 'ecosystem.config.mjs']) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    if (content.includes('securenow/register') && !/require\.resolve\(\s*['"]securenow\/register['"]\s*\)/.test(content)) {
+      ui.warn(`${name}: pass the preload as an absolute path, node_args: ['-r', require.resolve('securenow/register')]. A bare '-r securenow/register' is resolved from the PM2 daemon's folder in cluster mode, and the workers crash when the daemon starts elsewhere (pm2 resurrect at boot).`);
+    }
+  }
+}
+
 function initNode(project) {
   const scripts = project.pkg.scripts || {};
   const startScript = scripts.start || '';
@@ -293,4 +395,6 @@ function initNode(project) {
   }
 }
 
-module.exports = { init };
+module.exports = {
+  INSTRUMENTATION,
+  isLegacyInstrumentation, init };