@lowdefy/node-utils 0.0.0-experimental-20260928105334 → 0.0.0-experimental-20260928120643

package/dist/createClientAddressResolver.js

@@ -0,0 +1,83 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import net from 'node:net';
+import { type } from '@lowdefy/helpers';
+import parseIpRange from './parseIpRange.js';
+// A dual-stack socket reports an IPv4 peer as "::ffff:203.0.113.7", and a
+// proxy on one may forward it that way. Both come out in the IPv4 form, so
+// logs and the session record carry one spelling of an address.
+function unmapIpv4(address) {
+    const mapped = /^::ffff:([\d.]+)$/i.exec(address);
+    if (mapped !== null && net.isIP(mapped[1]) === 4) {
+        return mapped[1];
+    }
+    return address;
+}
+// Some proxies write a hop with its port: "203.0.113.7:51234", "[2001:db8::1]:443".
+function parseForwardedHop(hop) {
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(hop);
+    if (bracketed !== null) {
+        return net.isIP(bracketed[1]) === 6 ? unmapIpv4(bracketed[1]) : null;
+    }
+    if (net.isIP(hop) !== 0) {
+        return unmapIpv4(hop);
+    }
+    const withPort = /^([\d.]+):\d+$/.exec(hop);
+    if (withPort !== null && net.isIP(withPort[1]) === 4) {
+        return withPort[1];
+    }
+    return null;
+}
+// The client address is the socket's peer unless that peer is a trusted proxy.
+// A trusted proxy appends the address it received from to X-Forwarded-For, so
+// the chain is read from the right: every trusted hop is skipped and the first
+// untrusted one is the client. Entries to its left were written by whoever sent
+// the request and are never believed. With no trusted proxies the header is not
+// read at all - a client cannot choose its own address.
+//
+// trustedProxies holds IP addresses and CIDR ranges the build has validated.
+function createClientAddressResolver({ trustedProxies }) {
+    const trusted = new net.BlockList();
+    (trustedProxies ?? []).forEach((entry)=>{
+        const { address, prefix, family } = parseIpRange(entry);
+        trusted.addSubnet(address, prefix, family);
+    });
+    function isTrusted(address) {
+        return trusted.check(address, net.isIP(address) === 6 ? 'ipv6' : 'ipv4');
+    }
+    return function resolveClientAddress({ peerAddress, forwardedFor }) {
+        if (!type.isString(peerAddress) || net.isIP(peerAddress) === 0) {
+            return null;
+        }
+        let address = unmapIpv4(peerAddress);
+        if (!isTrusted(address) || !type.isString(forwardedFor)) {
+            return address;
+        }
+        const hops = forwardedFor.split(',').map((hop)=>hop.trim()).filter((hop)=>hop !== '');
+        for(let index = hops.length - 1; index >= 0; index -= 1){
+            const hop = parseForwardedHop(hops[index]);
+            // A malformed hop ends the walk at the last address a trusted proxy vouched for.
+            if (hop === null) {
+                return address;
+            }
+            address = hop;
+            if (!isTrusted(address)) {
+                return address;
+            }
+        }
+        return address;
+    };
+}
+export default createClientAddressResolver;

package/dist/createSecretScrubber.js

@@ -82,7 +82,7 @@ function secretForms(value) {
 function createSecretScrubber({ secrets, env = process.env }) {
     const values = collectStringLeaves(secrets, []);
     if (!type.isNone(env.CRON_SECRET)) values.push(env.CRON_SECRET);
-    if (!type.isNone(env.AUTH_SECRET)) values.push(env.AUTH_SECRET);
+    if (!type.isNone(env.BETTER_AUTH_SECRET)) values.push(env.BETTER_AUTH_SECRET);
     const expanded = values.flatMap((value)=>[
             value,
             ...parseJsonLeaves(value)
@@ -94,21 +94,13 @@ function createSecretScrubber({ secrets, env = process.env }) {
             if (form.length > 0) forms.add(form);
         });
     });
-    // No secrets means no pattern: an empty alternation would match at every position.
-    if (forms.size === 0) {
-        return function scrub(value) {
-            return value;
-        };
-    }
-    // One alternation, so every log line and Sentry string takes a single pass however many
-    // secrets there are. Longest first, so a form is replaced whole before a shorter form it
-    // contains can match at the same position.
-    const pattern = new RegExp([
+    // Longest first, so a form is replaced whole before a shorter form it contains can break it up.
+    const sortedForms = [
         ...forms
-    ].sort((a, b)=>b.length - a.length).map((form)=>form.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+    ].sort((a, b)=>b.length - a.length);
     return function scrub(value) {
         if (!type.isString(value)) return value;
-        return value.replace(pattern, REDACTED);
+        return sortedForms.reduce((text, form)=>text.split(form).join(REDACTED), value);
     };
 }
 export default createSecretScrubber;

package/dist/getDevInstancePath.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import path from 'path';
+// Keyed on the config directory, not the dev server directory, so one app has
+// one record however it was launched (CLI, --dev-directory, the monorepo dev
+// script) and every reader - CLI, MCP shim, hub - finds it the same way.
+function getDevInstancePath({ configDirectory }) {
+    return path.join(configDirectory, '.lowdefy', 'instance.json');
+}
+export default getDevInstancePath;

package/dist/getProcessStartTime.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { spawnSync } from 'child_process';
+// A pid alone does not identify a process: after a reboot, or enough churn,
+// the pid in the hub's registry can belong to something else entirely. The pid
+// plus its start time does. Windows has no ps; there the hub relies on the pid.
+//
+// ps prints lstart in the caller's time zone and locale. Hubs, shims and CLIs
+// run with the environment of whichever session started them, so without
+// pinning both, a reader in another session would read another string for
+// the same process - and a hub would drop, orphaning, every server it should
+// adopt.
+function getProcessStartTime({ pid }) {
+    if (process.platform === 'win32') {
+        return null;
+    }
+    const result = spawnSync('ps', [
+        '-o',
+        'lstart=',
+        '-p',
+        String(pid)
+    ], {
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            LC_ALL: 'C',
+            TZ: 'UTC'
+        }
+    });
+    const startTime = (result.stdout ?? '').trim();
+    return startTime === '' ? null : startTime;
+}
+export default getProcessStartTime;

package/dist/index.js

@@ -16,14 +16,20 @@
 import cleanDirectory from './cleanDirectory.js';
 import collectEnvironmentGuards from './collectEnvironmentGuards.js';
 import copyFileOrDirectory from './copyFileOrDirectory.js';
+import createClientAddressResolver from './createClientAddressResolver.js';
 import createSecretScrubber from './createSecretScrubber.js';
 import findAvailablePort from './findAvailablePort.js';
+import getDevInstancePath from './getDevInstancePath.js';
 import getFileExtension, { getFileSubExtension } from './getFileExtension.js';
+import getProcessStartTime from './getProcessStartTime.js';
 import getSecretsFromEnv from './getSecretsFromEnv.js';
 import installIfPackageJsonChanged from './installIfPackageJsonChanged.js';
+import isPidAlive from './isPidAlive.js';
 import isPortAvailable from './isPortAvailable.js';
+import parseIpRange from './parseIpRange.js';
+import readDevInstance from './readDevInstance.js';
 import spawnProcess from './spawnProcess.js';
 import readFile from './readFile.js';
 import writeFile from './writeFile.js';
 import writeFileIfChanged from './writeFileIfChanged.js';
-export { checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, copyFileOrDirectory, createSecretScrubber, findAvailablePort, getFileExtension, getFileSubExtension, getSecretsFromEnv, installIfPackageJsonChanged, isPortAvailable, spawnProcess, readFile, writeFile, writeFileIfChanged };
+export { checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, copyFileOrDirectory, createClientAddressResolver, createSecretScrubber, findAvailablePort, getDevInstancePath, getFileExtension, getFileSubExtension, getProcessStartTime, getSecretsFromEnv, installIfPackageJsonChanged, isPidAlive, isPortAvailable, parseIpRange, readDevInstance, spawnProcess, readFile, writeFile, writeFileIfChanged };

package/dist/isPidAlive.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        // EPERM means the process exists but belongs to another user.
+        return error.code === 'EPERM';
+    }
+}
+export default isPidAlive;

package/dist/parseIpRange.js

@@ -0,0 +1,52 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import net from 'node:net';
+const PREFIX_PATTERN = /^\d{1,3}$/;
+// Parses an IP address ("10.0.0.7", "2001:db8::1") or a CIDR range
+// ("10.0.0.0/8", "2001:db8::/32") into the arguments net.BlockList.addSubnet
+// takes. A bare address is a range of one. Returns null for anything else, so
+// a malformed entry is refused rather than silently matching nothing.
+function parseIpRange(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const [address, prefixPart, ...rest] = value.trim().split('/');
+    const version = net.isIP(address);
+    if (version === 0 || rest.length > 0) {
+        return null;
+    }
+    const family = version === 6 ? 'ipv6' : 'ipv4';
+    const maxPrefix = version === 6 ? 128 : 32;
+    if (prefixPart === undefined) {
+        return {
+            address,
+            prefix: maxPrefix,
+            family
+        };
+    }
+    if (!PREFIX_PATTERN.test(prefixPart)) {
+        return null;
+    }
+    const prefix = Number(prefixPart);
+    if (prefix > maxPrefix) {
+        return null;
+    }
+    return {
+        address,
+        prefix,
+        family
+    };
+}
+export default parseIpRange;

package/dist/readDevInstance.js

@@ -0,0 +1,91 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import fs from 'fs';
+import { type } from '@lowdefy/helpers';
+import getDevInstancePath from './getDevInstancePath.js';
+import getProcessStartTime from './getProcessStartTime.js';
+import isPidAlive from './isPidAlive.js';
+function readRecord(instancePath) {
+    try {
+        return JSON.parse(fs.readFileSync(instancePath, 'utf8'));
+    } catch  {
+        // No record, or one mid-write - either way no live instance to report.
+        return null;
+    }
+}
+// Readers poll the record (every 100 ms while waiting on a build), and a
+// start time costs a ps process, so it is read once a few seconds per pid.
+const START_TIME_TTL_MS = 5000;
+const startTimes = new Map();
+function readStartTime(pid) {
+    const cached = startTimes.get(pid);
+    if (!type.isUndefined(cached) && Date.now() - cached.readAt < START_TIME_TTL_MS) {
+        return cached.startTime;
+    }
+    const now = Date.now();
+    startTimes.forEach((entry, key)=>{
+        if (now - entry.readAt >= START_TIME_TTL_MS) {
+            startTimes.delete(key);
+        }
+    });
+    const startTime = getProcessStartTime({
+        pid
+    });
+    startTimes.set(pid, {
+        startTime,
+        readAt: now
+    });
+    return startTime;
+}
+// A pid alone does not name a process: after a crash (kill -9 skips the
+// manager's cleanup) or a reboot, the record's pid can belong to something
+// else. The manager records its start time too. A record from a manager that
+// predates it, or a start time ps could not read, leaves the pid to decide -
+// never "not running", which would let a second dev server start beside it.
+function isRecordProcess(record) {
+    if (!isPidAlive(record.pid)) {
+        return false;
+    }
+    if (type.isNone(record.processStartTime)) {
+        return true;
+    }
+    const startTime = readStartTime(record.pid);
+    return type.isNone(startTime) || startTime === record.processStartTime;
+}
+// A record is live only when it was written for this exact directory and its
+// process still runs. The directory check matters because .lowdefy/ gets
+// copied between git worktrees - a copied record names the source checkout
+// and must not make this checkout look occupied.
+function readDevInstance({ configDirectory }) {
+    const record = readRecord(getDevInstancePath({
+        configDirectory
+    }));
+    if (record === null) {
+        return null;
+    }
+    let realConfigDirectory;
+    try {
+        // The path as stored on disk, as the manager records it, so a case
+        // variant of the directory (macOS) still finds its record.
+        realConfigDirectory = fs.realpathSync.native(configDirectory);
+    } catch  {
+        return null;
+    }
+    if (record.configDirectory !== realConfigDirectory || !isRecordProcess(record)) {
+        return null;
+    }
+    return record;
+}
+export default readDevInstance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/node-utils",
-  "version": "0.0.0-experimental-20260928105334",
+  "version": "0.0.0-experimental-20260928120643",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,11 +34,12 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "0.0.0-experimental-20260928105334",
-    "@lowdefy/helpers": "0.0.0-experimental-20260928105334",
+    "@lowdefy/errors": "0.0.0-experimental-20260928120643",
+    "@lowdefy/helpers": "0.0.0-experimental-20260928120643",
     "fs-extra": "11.3.4"
   },
   "devDependencies": {
+    "@jest/globals": "28.1.3",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",