@lowdefy/node-utils 6.0.0 → 6.1.0

package/dist/checkEnvironmentGuards.js

@@ -0,0 +1,34 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+import collectEnvironmentGuards from './collectEnvironmentGuards.js';
+// Checks the current environment's guards against this process's environment variables. The build
+// runs it before anything deploys, and the production server again at startup: an image built once
+// can be started with different variables. Values are never echoed: a failure names the variable,
+// not what it holds.
+function checkEnvironmentGuards({ name, guards, configKey }) {
+    const failures = collectEnvironmentGuards({
+        guards
+    }).filter(({ variable, pattern })=>{
+        const value = process.env[variable];
+        return !type.isString(value) || !new RegExp(pattern).test(value);
+    });
+    if (failures.length === 0) return;
+    throw new ConfigError(`Environment "${name}" guards failed: ${failures.map(({ label, variable })=>type.isString(process.env[variable]) ? `${label} does not match its guard` : `${label} is not set (${variable})`).join('; ')}. Update the guard in config.environments.${name}.guards together with the value, or fix the value.`, {
+        configKey
+    });
+}
+export default checkEnvironmentGuards;

package/dist/collectEnvironmentGuards.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.
+*/ // Guards pin an environment's secrets and environment variables to a pattern kept in code: the
+// value must match the regular expression, so changing a guarded value (the prod database URI,
+// say) takes a change to the deployment's variables AND a reviewed change to the app config — a
+// second factor for deploy-time configuration. Checked at build, before anything deploys.
+//
+//   guards:
+//     secrets: { MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net' }   # LOWDEFY_SECRET_<NAME>
+//     env: { BETTER_AUTH_URL: '^https://app\.acme\.com$' }
+//
+// Values are never echoed: a failure names the variable, not what it holds.
+function collectEnvironmentGuards({ guards }) {
+    const checks = [];
+    Object.entries(guards?.secrets ?? {}).forEach(([name, pattern])=>{
+        if (name.startsWith('~')) return;
+        checks.push({
+            label: `secret "${name}"`,
+            variable: `LOWDEFY_SECRET_${name}`,
+            pattern
+        });
+    });
+    Object.entries(guards?.env ?? {}).forEach(([name, pattern])=>{
+        if (name.startsWith('~')) return;
+        checks.push({
+            label: `environment variable "${name}"`,
+            variable: name,
+            pattern
+        });
+    });
+    return checks;
+}
+export default collectEnvironmentGuards;

package/dist/createSecretScrubber.js

@@ -0,0 +1,114 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+const REDACTED = '[REDACTED]';
+// Shorter values, like `true` or a port number, would shred unrelated text.
+const MIN_SECRET_LENGTH = 8;
+function collectStringLeaves(value, leaves) {
+    if (type.isString(value)) {
+        leaves.push(value);
+        return leaves;
+    }
+    if (type.isArray(value)) {
+        value.forEach((item)=>collectStringLeaves(item, leaves));
+        return leaves;
+    }
+    if (type.isObject(value)) {
+        Object.values(value).forEach((item)=>collectStringLeaves(item, leaves));
+    }
+    return leaves;
+}
+// Authors JSON-encode structured secrets and pick a leaf with `_json.parse`, so the leaf, not
+// the whole encoded string, is what ends up in an error message.
+function parseJsonLeaves(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    } catch  {
+        return [];
+    }
+    if (!type.isObject(parsed) && !type.isArray(parsed)) {
+        return [];
+    }
+    return collectStringLeaves(parsed, []);
+}
+// A secret embedded in a larger base64 payload (a Basic auth header built from
+// `user:password`) only matches the secret's own base64 when both start on the same 3-byte
+// boundary. Encoding at each offset and keeping only the characters whose 6 bits fall wholly
+// inside the secret's bytes gives a fragment that matches whatever surrounds it.
+function base64Fragments(value) {
+    const bytes = Buffer.from(value, 'utf8');
+    const fragments = [];
+    [
+        0,
+        1,
+        2
+    ].forEach((offset)=>{
+        const padded = Buffer.concat([
+            Buffer.alloc(offset),
+            bytes
+        ]);
+        const start = Math.ceil(8 * offset / 6);
+        const end = Math.floor(8 * (offset + bytes.length) / 6);
+        [
+            'base64',
+            'base64url'
+        ].forEach((encoding)=>{
+            fragments.push(padded.toString(encoding).replace(/=+$/, '').slice(start, end));
+        });
+    });
+    return fragments;
+}
+function secretForms(value) {
+    return [
+        value,
+        encodeURIComponent(value),
+        JSON.stringify(value).slice(1, -1),
+        ...base64Fragments(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);
+    const expanded = values.flatMap((value)=>[
+            value,
+            ...parseJsonLeaves(value)
+        ]);
+    const secretValues = new Set(expanded.filter((value)=>value.length >= MIN_SECRET_LENGTH));
+    const forms = new Set();
+    secretValues.forEach((value)=>{
+        secretForms(value).forEach((form)=>{
+            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([
+        ...forms
+    ].sort((a, b)=>b.length - a.length).map((form)=>form.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+    return function scrub(value) {
+        if (!type.isString(value)) return value;
+        return value.replace(pattern, REDACTED);
+    };
+}
+export default createSecretScrubber;

package/dist/index.js

@@ -12,8 +12,11 @@
   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 cleanDirectory from './cleanDirectory.js';
+*/ import checkEnvironmentGuards from './checkEnvironmentGuards.js';
+import cleanDirectory from './cleanDirectory.js';
+import collectEnvironmentGuards from './collectEnvironmentGuards.js';
 import copyFileOrDirectory from './copyFileOrDirectory.js';
+import createSecretScrubber from './createSecretScrubber.js';
 import findAvailablePort from './findAvailablePort.js';
 import getFileExtension, { getFileSubExtension } from './getFileExtension.js';
 import getSecretsFromEnv from './getSecretsFromEnv.js';
@@ -23,4 +26,4 @@ import spawnProcess from './spawnProcess.js';
 import readFile from './readFile.js';
 import writeFile from './writeFile.js';
 import writeFileIfChanged from './writeFileIfChanged.js';
-export { cleanDirectory, copyFileOrDirectory, findAvailablePort, getFileExtension, getFileSubExtension, getSecretsFromEnv, installIfPackageJsonChanged, isPortAvailable, spawnProcess, readFile, writeFile, writeFileIfChanged };
+export { checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, copyFileOrDirectory, createSecretScrubber, findAvailablePort, getFileExtension, getFileSubExtension, getSecretsFromEnv, installIfPackageJsonChanged, isPortAvailable, spawnProcess, readFile, writeFile, writeFileIfChanged };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/node-utils",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,8 +34,8 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "6.0.0",
-    "@lowdefy/helpers": "6.0.0",
+    "@lowdefy/errors": "6.1.0",
+    "@lowdefy/helpers": "6.1.0",
     "fs-extra": "11.3.4"
   },
   "devDependencies": {