local-serverless-stack 0.17.1 → 1.0.0

package/dist/server/services/config-manager.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { projectCacheSegment } from './project-scope.js';
 // Symlink-stable spelling of a directory (e.g. macOS /tmp -> /private/tmp),
 // so the project identity matches the plugin's symlink-resolved process.cwd().
 function realpathOrSelf(dir) {
@@ -11,6 +12,506 @@ function realpathOrSelf(dir) {
         return dir;
     }
 }
+// One port for the whole stack: the REST API, the dashboard and the AWS wire
+// all answer here by default. Deliberately outside 4566–4599, which a real
+// LocalStack install intercepts on some hosts (Docker Desktop/WSL2).
+//
+// Setting `serverPort` and `selfEngine.port` to DIFFERENT values splits them
+// back onto two listeners — see isSingleListener().
+const DEFAULT_PORT = 14566;
+// `secrets` is deliberately absent (and rejected on write): it holds seed
+// material that belongs in the config file or the environment, never in a
+// payload that crosses the dashboard API.
+const BLOCKED_CONFIG_KEYS = new Set(['secrets']);
+// ---------------------------------------------------------------------------
+// What a package command written through PUT /api/config may become
+// ---------------------------------------------------------------------------
+//
+// A package command is handed to serverless-packager.ts, which tokenizes it and
+// calls spawn(firstToken, restTokens) with `packageArgs` appended to the argv.
+// PUT /api/config is unauthenticated, so an unconstrained command — or an
+// unconstrained arg list — is arbitrary code execution on this host:
+// `PUT /api/config {"packageCommand":"/bin/sh","packageArgs":["-c","…"]}`
+// followed by `POST /api/services/package` runs whatever the caller wrote. That
+// is the same class the /start and /install runner allowlists already close;
+// this is the third door into it.
+//
+// Fencing only the command's FIRST token does NOT close it, and that version of
+// this check was walked straight through: every package manager on the list is
+// itself an interpreter, one subcommand in.
+//
+//   npm exec -c '<shell string>'   spawn('npm', ['exec','-c',…]) runs the string
+//   npx -c '<shell string>'        as a shell command — no shell:true required,
+//                                  the payload is read straight off the argv
+//   npx -y <pkg> · npm exec -p <pkg> · yarn dlx · pnpm dlx   fetch and run any package
+//   yarn node -e '<js>' · yarn exec · pnpm exec              run an interpreter
+//   npm i <pkg> · yarn add <pkg>   run a fetched package's install scripts
+//
+// Each of those satisfies "the first token names a package manager". So the
+// fence is a grammar over the WHOLE command instead of a check on one token —
+// the shapes below and nothing else:
+//
+//   npm | yarn | pnpm     run | run-script   [script] [args…]
+//   serverless | sls | osls   package                 [args…]
+//   npx [-y|--yes]…   serverless|sls|osls[@version]   package   [args…]
+//
+// plus BLOCKED_PACKAGE_FLAGS applied to every token of the command AND to every
+// `packageArgs` element, since those reach the same argv without passing
+// through the tokenizer at all.
+//
+// RESIDUAL, stated plainly rather than papered over. `npm run <script>` still
+// runs whatever the service's own package.json declares, and `serverless
+// package` still reads the service's own serverless.yml (plugins included).
+// Both are the project's own code, which the operator already trusts by
+// pointing LSS at the directory; and forbidding them would mean the dashboard
+// could not set a package command at all, which is what the onboarding flow is
+// built on. What is gone is the part that made the /start and /install
+// allowlists worthless: through this API a caller can no longer choose the
+// program, only ask the project's own build to run.
+//
+// The fence is on the API and deliberately NOT on the read path — a
+// hand-edited lss.config.json and LSS_PACKAGE_COMMAND are the operator's own
+// shell, and anyone who can write either already runs code on this host.
+/**
+ * Runner names accepted as a command's first token, in the order the error
+ * message lists them. No entry contains a path separator, so membership alone
+ * rejects `/bin/sh`, `/usr/bin/env`, `./tool` and `..\x.exe`.
+ */
+const ALLOWED_PACKAGE_RUNNERS = [
+    'npm', 'npx', 'yarn', 'pnpm', 'serverless', 'sls', 'osls',
+];
+/**
+ * The subcommands each runner may be followed by — the wall the first-token
+ * check was missing. `run`/`run-script` execute a script the project declared;
+ * every other verb these CLIs expose either takes a command off the argv
+ * (`exec`, `x`, `node`, `dlx`) or fetches a package and runs its code (`add`,
+ * `install`, `create`, `plugin install`). The Serverless CLIs get `package` for
+ * the same reason: `serverless plugin install <pkg>` is a fetch-and-run, and
+ * packaging is the only thing this setting exists to do.
+ *
+ * A bare `yarn package` (yarn 1's implicit `run`) is rejected on purpose: the
+ * implicit form is exactly what makes `yarn node -e '<js>'` and `yarn dlx <pkg>`
+ * indistinguishable from a script name, so the explicit `yarn run package` is
+ * required instead. `npx` is absent because it is a launcher rather than a
+ * program — validatePackageCommand() strips it and validates what it launches.
+ */
+const PACKAGE_RUNNER_VERBS = {
+    npm: ['run', 'run-script'],
+    yarn: ['run'],
+    pnpm: ['run'],
+    serverless: ['package'],
+    sls: ['package'],
+    osls: ['package'],
+};
+/**
+ * The packages `npx` may fetch and run. Restricted to the Serverless CLIs
+ * because that is the entire reason npx appears here — LSS's own default is
+ * `npx serverless package`, i.e. "run the Serverless CLI without a global
+ * install". Anything else npx can reach is a package of the caller's choosing.
+ */
+const NPX_PACKAGES = ['serverless', 'sls', 'osls'];
+/**
+ * The only flags tolerated between `npx` and the package name. `-y` suppresses
+ * the "install it?" prompt and does nothing else; every other npx flag either
+ * names a different package to run (`-p`/`--package`) or takes a command string
+ * (`-c`/`--call`), which is the bypass itself.
+ */
+const NPX_PREFIX_FLAGS = ['-y', '--yes'];
+/**
+ * Flags that make an otherwise-allowed command run something other than the
+ * project's own build, whichever runner is in front of them. The grammar above
+ * pins the program; these pin what that program is allowed to be pointed at:
+ *
+ *   --node-options      npm/yarn/pnpm/npx set NODE_OPTIONS on the child, which
+ *                       is `--require <file>` under another name (the same hole
+ *                       BLOCKED_PACKAGE_ENV_KEYS closes on the env side)
+ *   --script-shell      npm chooses the binary that interprets the script;
+ *                       --shell/--shell-mode are the yarn/pnpm spellings
+ *   --call              npm exec's inline command string
+ *   --userconfig/--globalconfig/--use-yarnrc
+ *                       point the manager at another rc file, which can itself
+ *                       set script-shell, node-options or yarn 1's `yarn-path`
+ *   --registry          `npx serverless package` fetches `serverless` when the
+ *                       service has no local copy, and npm's arg parser reads
+ *                       its own config flags from anywhere in the argv — so a
+ *                       registry named after the package name still decides
+ *                       which code that fetch runs
+ *   --prefix/--cwd/--dir   run the scripts of a package.json somewhere else
+ *   --eval/--print/--require/--import/--loader/--experimental-loader/--input-type
+ *                       node's own code-loading flags, refused in case any
+ *                       runner forwards its argv to node
+ *
+ * Deliberately absent: `--package` (npm exec's package selector) and every
+ * short flag. Both are already unreachable — `npm exec` is not an allowed verb
+ * and npx accepts no flag but `-y` — while `-c`, `-p` and `-r` are `--config`,
+ * `--package` and `--region` to the Serverless CLI, so blocking them would
+ * break `sls package -c custom.yml` for nothing.
+ *
+ * Compared with dashes and underscores stripped, so `--nodeOptions` and
+ * `--node_options` cannot spell their way past the set.
+ */
+const BLOCKED_PACKAGE_FLAGS = new Set([
+    'nodeoptions',
+    'scriptshell',
+    'shell',
+    'shellmode',
+    'call',
+    'userconfig',
+    'globalconfig',
+    'useyarnrc',
+    'registry',
+    'prefix',
+    'cwd',
+    'dir',
+    'eval',
+    'print',
+    'require',
+    'import',
+    'loader',
+    'experimentalloader',
+    'inputtype',
+]);
+// Env vars that make the spawned child load attacker-chosen code no matter
+// WHICH binary runs, so they walk straight around the runner allowlist above:
+//   NODE_OPTIONS               `--require /tmp/x.js` into every node process
+//   NODE_REPL_EXTERNAL_MODULE  loads a module into node ahead of the program
+//   LD_PRELOAD / LD_AUDIT      inject a shared object into the dynamic linker
+//   LD_LIBRARY_PATH            re-points the linker at attacker libraries
+//   DYLD_INSERT_LIBRARIES / DYLD_LIBRARY_PATH   the macOS spellings of both
+//   PATH                       decides WHICH `npm` runs at all — see below
+//   NODE_PATH                  prepends a module search root for every require
+// Stored lowercase and compared case-insensitively: env lookup is
+// case-insensitive on Windows, so `node_options` would otherwise be the same
+// bypass one keystroke away.
+//
+// PATH is the one that looks harmless and is not. `runServerlessPackage` spawns
+// WITHOUT a shell, but a shell was never what resolved the binary: libuv runs
+// execvp(3) after installing the child's environment, so the child's PATH — not
+// the orchestrator's — decides which file named `npm` executes. Verified by
+// spawning `npm` with a prepended directory: the planted binary ran. That makes
+// PATH equivalent to naming an arbitrary command, which is exactly what
+// ALLOWED_PACKAGE_RUNNERS exists to prevent. The packaging child inherits the
+// orchestrator's PATH and no caller may replace it.
+const BLOCKED_PACKAGE_ENV_KEYS = new Set([
+    'node_options',
+    'node_repl_external_module',
+    'ld_preload',
+    'ld_audit',
+    'ld_library_path',
+    'dyld_insert_libraries',
+    'dyld_library_path',
+    'path',
+    'node_path',
+]);
+const EDITABLE_CONFIG_KEYS = {
+    serverPort: { kind: 'port' },
+    enableDynamoProxy: { kind: 'boolean' },
+    dynamoProxyPort: { kind: 'port' },
+    region: { kind: 'string' },
+    persistence: { kind: 'boolean' },
+    debug: { kind: 'boolean' },
+    seedsDir: { kind: 'string' },
+    stateDir: { kind: 'string' },
+    autoPackage: { kind: 'boolean' },
+    packageCommand: { kind: 'packageCommand' },
+    packageArgs: { kind: 'packageArgs' },
+    packageEnv: { kind: 'envRecord' },
+    servicePackaging: {
+        kind: 'object',
+        entrySubKeys: {
+            // Same fences as the global keys above — a per-service override is spawned
+            // by the exact same code path, so validating only the global copy would
+            // leave the door open one nesting level down.
+            packageCommand: { kind: 'packageCommand' },
+            packageArgs: { kind: 'packageArgs' },
+            packageEnv: { kind: 'envRecord' },
+            packageTimeoutMs: { kind: 'positiveInt' },
+        },
+    },
+    packageTimeoutMs: { kind: 'positiveInt' },
+    lambdaRuntime: {
+        kind: 'object',
+        subKeys: {
+            enabled: { kind: 'boolean' },
+            execution: { kind: 'string', enum: ['auto', 'artifact', 'source'] },
+            watch: { kind: 'boolean' },
+            invokePortOffset: { kind: 'positiveInt' },
+            invokeHost: { kind: 'string' },
+            lazy: { kind: 'boolean' },
+            idleTimeoutMs: { kind: 'nonNegativeInt' },
+            maxWarmWorkers: { kind: 'nonNegativeInt' },
+        },
+    },
+    serviceRuntime: {
+        kind: 'object',
+        entrySubKeys: {
+            enabled: { kind: 'boolean' },
+            apiPort: { kind: 'port' },
+            invokePort: { kind: 'port' },
+            execution: { kind: 'string', enum: ['auto', 'artifact', 'source'] },
+            watch: { kind: 'boolean' },
+        },
+    },
+    selfEngine: {
+        kind: 'object',
+        subKeys: {
+            port: { kind: 'port' },
+            dataDir: { kind: 'string' },
+            account: { kind: 'string' },
+            idleUnloadMs: { kind: 'positiveInt' },
+            memoryBudgetMb: { kind: 'positiveInt' },
+            fsync: { kind: 'boolean' },
+            fallbackEndpoint: { kind: 'string' },
+        },
+    },
+    branding: {
+        kind: 'object',
+        subKeys: {
+            title: { kind: 'string' },
+            subtitle: { kind: 'string' },
+            logo: { kind: 'string' },
+            favicon: { kind: 'string' },
+            defaultTheme: { kind: 'string', enum: ['dark', 'light'] },
+            colors: { kind: 'stringRecord' },
+            themeColors: {
+                kind: 'object',
+                subKeys: {
+                    dark: { kind: 'stringRecord' },
+                    light: { kind: 'stringRecord' },
+                },
+            },
+        },
+    },
+};
+// Env vars that mask each file key while set (loadFromEnv applies them AFTER
+// the file, and some getters fall back to env at call time). Surfaced so the
+// UI can flag fields whose saved value will not take effect until the env var
+// is unset.
+const CONFIG_ENV_OVERRIDES = {
+    serverPort: ['LSS_DASHBOARD_PORT', 'PORT'],
+    // Note: the deprecated unprefixed ENABLE_DYNAMO_PROXY is NOT listed — it is
+    // only a getter-time fallback (isEnableDynamoProxy) that a file value always
+    // beats, so it never masks a saved value.
+    enableDynamoProxy: ['LSS_ENABLE_DYNAMO_PROXY'],
+    dynamoProxyPort: ['LSS_DYNAMO_PROXY_PORT'],
+    region: ['AWS_REGION'],
+    services: ['LSS_SERVICES'],
+    persistence: ['LSS_PERSISTENCE'],
+    debug: ['LSS_DEBUG'],
+    seedsDir: ['LSS_SEEDS_DIR'],
+    autoPackage: ['LSS_AUTO_PACKAGE'],
+    packageCommand: ['LSS_PACKAGE_COMMAND'],
+    packageTimeoutMs: ['LSS_PACKAGE_TIMEOUT_MS'],
+    lambdaRuntime: ['LSS_LAMBDA_RUNTIME', 'LSS_LAMBDA_EXECUTION', 'LSS_LAMBDA_WATCH', 'LSS_INVOKE_HOST'],
+    selfEngine: ['LSS_ENGINE_PORT', 'LSS_ENGINE_DATA_DIR'],
+};
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The argv a package command would actually spawn, tokenized EXACTLY the way
+ * parseCommand() in serverless-packager.ts does (same regex, same
+ * per-quoted-segment stripping). Mirroring it is the whole point — the tokens
+ * validated here must be the tokens handed to spawn(), or the check and the
+ * execution disagree and the grammar means nothing. `"/bin/sh"` resolves to
+ * `/bin/sh` (rejected) and `'npm'` to `npm` (accepted), in both places.
+ * Keep the two in step if the packager's tokenizer ever changes.
+ */
+function packageCommandTokens(raw) {
+    const tokens = raw.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    return tokens.map(token => token.replace(/"([^"]*)"|'([^']*)'/g, '$1$2'));
+}
+/**
+ * Comparable spelling of a flag token: the name before any `=value`, lowercased
+ * with dashes and underscores removed (`--Node-Options=--require x` →
+ * `nodeoptions`). Only the name is compared — the value is what the flag would
+ * point at, and every value is dangerous once the name is.
+ */
+function normalizeFlagName(token) {
+    return token.split('=')[0].toLowerCase().replace(/[-_]/g, '');
+}
+/**
+ * A token that redirects the command at a program, shell or rc file of the
+ * caller's choosing. Only tokens that look like flags are screened, so a script
+ * or file name that happens to collide (`npm run print`) is untouched.
+ */
+function isBlockedPackageFlag(token) {
+    return token.startsWith('-') && BLOCKED_PACKAGE_FLAGS.has(normalizeFlagName(token));
+}
+function blockedFlagError(label, token) {
+    return `"${label}" cannot contain "${token}" — that flag points the package command at a program, shell or config file of the caller's choosing`;
+}
+/** `"run" or "run-script"` — verbs quoted the way the error message reads best. */
+function quotedList(values) {
+    const quoted = values.map(value => `"${value}"`);
+    return quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+/**
+ * Validate a `packageCommand` against the grammar documented above:
+ * runner → subcommand → free arguments, with `npx` stripped down to the
+ * Serverless CLI it launches, and no blocked flag anywhere in the argv.
+ */
+function validatePackageCommand(key, raw) {
+    const tokens = packageCommandTokens(raw);
+    // Two cursors because `npx serverless package` has two layers: `rest` is the
+    // slice the grammar is currently reading (it loses the `npx …` prefix), while
+    // `runner` names the program that will finally execute and therefore whose
+    // subcommand list applies.
+    let rest = tokens;
+    let runner = rest[0] ?? '';
+    if (runner === 'npx') {
+        rest = rest.slice(1);
+        while (NPX_PREFIX_FLAGS.includes(rest[0])) {
+            rest = rest.slice(1);
+        }
+        const spec = rest[0] ?? '';
+        if (spec.startsWith('-')) {
+            return `"${key}": npx may carry only ${quotedList(NPX_PREFIX_FLAGS)} before the package name — "${spec}" can name another package to run, or a command string to run as a shell`;
+        }
+        // `serverless@3.38.0` is the same program with a version pin. The `@` at
+        // index 0 belongs to a scope (`@scope/pkg`), which is never in the list.
+        const at = spec.lastIndexOf('@');
+        runner = at > 0 ? spec.slice(0, at) : spec;
+        if (!NPX_PACKAGES.includes(runner)) {
+            return `"${key}": npx may only run the Serverless CLI (${NPX_PACKAGES.join(', ')}) — "${spec}" is a package of the caller's choosing`;
+        }
+    }
+    else if (!ALLOWED_PACKAGE_RUNNERS.includes(runner)) {
+        return `"${key}" must start with one of: ${ALLOWED_PACKAGE_RUNNERS.join(', ')} — "${runner}" is not an allowed package runner`;
+    }
+    const verbs = PACKAGE_RUNNER_VERBS[runner];
+    const verb = rest[1] ?? '';
+    if (!verbs.includes(verb)) {
+        return `"${key}": "${runner}" may only be followed by ${quotedList(verbs)} — `
+            + (verb
+                ? `"${verb}" can run a program the caller chose instead of the project's build`
+                : 'the command names no subcommand at all');
+    }
+    // Screens the whole argv, not just the tail: a blocked flag is blocked
+    // wherever it sits, and the runner/verb tokens never start with a dash.
+    const blocked = tokens.find(isBlockedPackageFlag);
+    return blocked === undefined ? null : blockedFlagError(key, blocked);
+}
+function validateValue(key, value, spec) {
+    switch (spec.kind) {
+        case 'port':
+            return Number.isInteger(value) && value >= 1 && value <= 65535
+                ? null
+                : `"${key}" must be an integer port between 1 and 65535`;
+        case 'positiveInt':
+            return Number.isInteger(value) && value > 0
+                ? null
+                : `"${key}" must be a positive integer`;
+        // 0 is meaningful for these (idleTimeoutMs: 0 = never unload).
+        case 'nonNegativeInt':
+            return Number.isInteger(value) && value >= 0
+                ? null
+                : `"${key}" must be an integer >= 0`;
+        case 'boolean':
+            return typeof value === 'boolean' ? null : `"${key}" must be a boolean`;
+        case 'string':
+            if (typeof value !== 'string' || value.length === 0) {
+                return `"${key}" must be a non-empty string`;
+            }
+            return spec.enum && !spec.enum.includes(value)
+                ? `"${key}" must be one of: ${spec.enum.join(', ')}`
+                : null;
+        // A command that is spawned, not just stored: on top of the non-empty string
+        // check it must match the package-command grammar. See PACKAGE_RUNNER_VERBS
+        // for why an unfenced string — or a first-token-only check — is remote code
+        // execution here, and for the residual the grammar does not close.
+        case 'packageCommand': {
+            if (typeof value !== 'string' || value.length === 0) {
+                return `"${key}" must be a non-empty string`;
+            }
+            return validatePackageCommand(key, value);
+        }
+        // Appended to the spawned argv verbatim, with no tokenizer in between, so
+        // `packageCommand:"npm"` + `packageArgs:["exec","-c","<shell>"]` would be
+        // the identical bypass one key across. The grammar above already pins the
+        // program and its subcommand; the flag screen is what stops an arg from
+        // re-pointing that program somewhere else.
+        case 'packageArgs': {
+            if (!Array.isArray(value) || !value.every(v => typeof v === 'string')) {
+                return `"${key}" must be an array of strings`;
+            }
+            const index = value.findIndex(isBlockedPackageFlag);
+            return index === -1 ? null : blockedFlagError(`${key}[${index}]`, value[index]);
+        }
+        case 'stringRecord':
+        case 'envRecord': {
+            if (!isPlainObject(value) || !Object.values(value).every(v => typeof v === 'string')) {
+                return `"${key}" must be an object of string values`;
+            }
+            // An env map is merged into the packaging child's environment, where a
+            // handful of names are loader/interpreter hooks: they run code in the
+            // child whatever program the command grammar let through, which would
+            // make that grammar decorative.
+            if (spec.kind === 'envRecord') {
+                for (const envKey of Object.keys(value)) {
+                    if (BLOCKED_PACKAGE_ENV_KEYS.has(envKey.toLowerCase())) {
+                        return `"${key}.${envKey}" cannot be set — it injects code into the packaging process`;
+                    }
+                }
+            }
+            return null;
+        }
+        case 'object': {
+            if (!isPlainObject(value)) {
+                return `"${key}" must be an object`;
+            }
+            // null subvalues are always allowed — they delete the subkey on merge.
+            if (spec.subKeys) {
+                for (const [subKey, subValue] of Object.entries(value)) {
+                    // hasOwnProperty, not a plain read: `constructor`/`toString` would
+                    // otherwise resolve to an Object.prototype member, pass this guard
+                    // and reach the file as unvalidated JSON.
+                    const subSpec = Object.prototype.hasOwnProperty.call(spec.subKeys, subKey)
+                        ? spec.subKeys[subKey]
+                        : undefined;
+                    if (!subSpec)
+                        return `unknown config key "${key}.${subKey}"`;
+                    if (subValue === null)
+                        continue;
+                    const error = validateValue(`${key}.${subKey}`, subValue, subSpec);
+                    if (error)
+                        return error;
+                }
+            }
+            if (spec.entrySubKeys) {
+                for (const [entryKey, entryValue] of Object.entries(value)) {
+                    if (entryValue === null)
+                        continue;
+                    if (!isPlainObject(entryValue))
+                        return `"${key}.${entryKey}" must be an object`;
+                    for (const [subKey, subValue] of Object.entries(entryValue)) {
+                        const subSpec = Object.prototype.hasOwnProperty.call(spec.entrySubKeys, subKey)
+                            ? spec.entrySubKeys[subKey]
+                            : undefined;
+                        if (!subSpec)
+                            return `unknown config key "${key}.${entryKey}.${subKey}"`;
+                        if (subValue === null)
+                            continue;
+                        const error = validateValue(`${key}.${entryKey}.${subKey}`, subValue, subSpec);
+                        if (error)
+                            return error;
+                    }
+                }
+            }
+            return null;
+        }
+    }
+}
+// Thrown by updateConfig so the route can answer 400 with every problem at
+// once instead of failing on the first.
+export class ConfigValidationError extends Error {
+    details;
+    constructor(details) {
+        super(details.join('; '));
+        this.name = 'ConfigValidationError';
+        this.details = details;
+    }
+}
 export class ConfigManager {
     static instance;
     config = {};
@@ -46,15 +547,16 @@ export class ConfigManager {
                     this.config = JSON.parse(content);
                     this.configPath = candidate;
                     console.log(`✅ Configuration loaded from ${candidate}`);
-                    break;
                 }
                 catch (error) {
                     console.warn(`⚠️  Failed to parse config file ${candidate}:`, error instanceof Error ? error.message : 'Unknown error');
+                    continue;
                 }
+                break;
             }
         }
-        // Environment variables override file values so secrets like LOCALSTACK_AUTH_TOKEN
-        // can be injected without committing them to disk.
+        // Environment variables override file values, so an instance can be
+        // retargeted (ports, engine data dir, region) without touching the file.
         this.loadFromEnv();
     }
     loadFromEnv() {
@@ -63,33 +565,6 @@ export class ConfigManager {
             /* istanbul ignore next: the enclosing if guarantees one of these is truthy, so the `|| ''` fallback is unreachable */
             this.config.serverPort = parseInt(process.env.LSS_DASHBOARD_PORT || process.env.PORT || '', 10);
         }
-        if (process.env.LSS_LOCALSTACK_PORT) {
-            this.config.localstackPort = parseInt(process.env.LSS_LOCALSTACK_PORT, 10);
-        }
-        if (process.env.LSS_LOCALSTACK_ENDPOINT) {
-            this.config.localstackEndpoint = process.env.LSS_LOCALSTACK_ENDPOINT;
-        }
-        if (process.env.LSS_LOCALSTACK_MODE) {
-            const mode = process.env.LSS_LOCALSTACK_MODE.toLowerCase();
-            if (mode === 'managed' || mode === 'external') {
-                this.config.mode = mode;
-            }
-        }
-        if (process.env.LSS_LOCALSTACK_EDITION) {
-            const edition = process.env.LSS_LOCALSTACK_EDITION.toLowerCase();
-            if (edition === 'community' || edition === 'pro') {
-                this.config.localstackEdition = edition;
-            }
-        }
-        if (process.env.LSS_LOCALSTACK_VERSION) {
-            this.config.localstackVersion = process.env.LSS_LOCALSTACK_VERSION;
-        }
-        if (process.env.LSS_LOCALSTACK_IMAGE) {
-            this.config.localstackImage = process.env.LSS_LOCALSTACK_IMAGE;
-        }
-        if (process.env.LOCALSTACK_AUTH_TOKEN) {
-            this.config.localstackAuthToken = process.env.LOCALSTACK_AUTH_TOKEN;
-        }
         if (process.env.LSS_ENABLE_DYNAMO_PROXY) {
             this.config.enableDynamoProxy = process.env.LSS_ENABLE_DYNAMO_PROXY === 'true' || process.env.LSS_ENABLE_DYNAMO_PROXY === '1';
         }
@@ -99,9 +574,6 @@ export class ConfigManager {
         if (process.env.AWS_REGION) {
             this.config.region = process.env.AWS_REGION;
         }
-        if (process.env.LSS_SERVICES) {
-            this.config.services = process.env.LSS_SERVICES.split(',');
-        }
         if (process.env.LSS_PERSISTENCE) {
             this.config.persistence = process.env.LSS_PERSISTENCE === 'true' || process.env.LSS_PERSISTENCE === '1';
         }
@@ -147,61 +619,32 @@ export class ConfigManager {
                 invokeHost: process.env.LSS_INVOKE_HOST,
             };
         }
-        if (process.env.LSS_ENGINE) {
-            const engine = process.env.LSS_ENGINE.toLowerCase();
-            if (engine === 'localstack' || engine === 'self') {
-                this.config.engine = engine;
-            }
-        }
         if (process.env.LSS_ENGINE_PORT) {
             this.config.selfEngine = {
                 ...this.config.selfEngine,
                 port: parseInt(process.env.LSS_ENGINE_PORT, 10),
             };
         }
+        // Give every instance its own engine state without editing a config file:
+        // `LSS_ENGINE_DATA_DIR=... LSS_ENGINE_PORT=... lss start` is enough to run a
+        // second stack (a test run, a second checkout) beside the dev one.
+        if (process.env.LSS_ENGINE_DATA_DIR) {
+            this.config.selfEngine = {
+                ...this.config.selfEngine,
+                dataDir: process.env.LSS_ENGINE_DATA_DIR,
+            };
+        }
     }
     getConfig() {
         return this.config;
     }
     getServerPort() {
-        return this.config.serverPort ?? (parseInt(process.env.PORT || '', 10) || 3100);
+        return this.config.serverPort ?? (parseInt(process.env.PORT || '', 10) || DEFAULT_PORT);
     }
     // Alias for backward compatibility
     getDashboardPort() {
         return this.getServerPort();
     }
-    getLocalStackPort() {
-        return this.config.localstackPort ?? 4566;
-    }
-    getLocalStackEndpoint() {
-        if (this.config.localstackEndpoint) {
-            return this.config.localstackEndpoint;
-        }
-        const port = this.getLocalStackPort();
-        return `http://localhost:${port}`;
-    }
-    getMode() {
-        return this.config.mode ?? 'managed';
-    }
-    isExternal() {
-        return this.getMode() === 'external';
-    }
-    getLocalStackEdition() {
-        return this.config.localstackEdition ?? 'community';
-    }
-    getLocalStackVersion() {
-        return this.config.localstackVersion ?? 'latest';
-    }
-    getLocalStackImage() {
-        if (this.config.localstackImage) {
-            return this.config.localstackImage;
-        }
-        const repo = this.getLocalStackEdition() === 'pro' ? 'localstack/localstack-pro' : 'localstack/localstack';
-        return `${repo}:${this.getLocalStackVersion()}`;
-    }
-    getLocalStackAuthToken() {
-        return this.config.localstackAuthToken;
-    }
     isEnableDynamoProxy() {
         if (this.config.enableDynamoProxy !== undefined) {
             return this.config.enableDynamoProxy;
@@ -215,9 +658,6 @@ export class ConfigManager {
     getRegion() {
         return this.config.region ?? (process.env.AWS_REGION || 'us-east-1');
     }
-    getServices() {
-        return this.config.services ?? ['dynamodb', 'sqs', 'sns', 's3', 'lambda', 'events'];
-    }
     isPersistence() {
         if (this.config.persistence !== undefined) {
             return this.config.persistence;
@@ -265,11 +705,7 @@ export class ConfigManager {
      * as the global baseline.
      */
     getPackageConfigForService(servicePath) {
-        const map = this.config.servicePackaging ?? {};
-        const baseName = path.basename(servicePath);
-        const configDir = path.resolve(this.configPath ? path.dirname(this.configPath) : process.cwd());
-        const relPath = path.relative(configDir, servicePath).split(path.sep).join('/');
-        const perService = map[relPath] ?? map[baseName] ?? {};
+        const perService = this.lookupServiceEntry(this.config.servicePackaging, servicePath);
         return {
             command: perService.packageCommand ?? this.getPackageCommand(),
             args: [...(this.config.packageArgs ?? []), ...(perService.packageArgs ?? [])],
@@ -277,6 +713,40 @@ export class ConfigManager {
             timeoutMs: perService.packageTimeoutMs ?? this.getPackageTimeoutMs(),
         };
     }
+    /**
+     * The keys a `servicePackaging`/`serviceRuntime` entry may be written under,
+     * most specific first: the path relative to the config file's directory, the
+     * path relative to the project root, then the directory basename.
+     *
+     * The two relative forms are usually the same string — but not always, and
+     * the difference used to silently drop overrides: `getProjectRoot()`
+     * realpath-resolves (and falls back to the cwd for a home-directory config),
+     * while a raw `dirname(configPath)` does not. A checkout reached through a
+     * symlink, or a config loaded from `~`, made the key the dashboard writes
+     * (project-root relative, from the scan) unreachable by the lookup. Both
+     * spellings resolve here so a written override always applies.
+     */
+    serviceEntryKeys(servicePath) {
+        const target = realpathOrSelf(path.resolve(servicePath));
+        const bases = [
+            this.configPath ? realpathOrSelf(path.resolve(path.dirname(this.configPath))) : null,
+            this.getProjectRoot(),
+        ];
+        const keys = bases
+            .filter((base) => base !== null)
+            .map(base => path.relative(base, target).split(path.sep).join('/'))
+            .filter(Boolean);
+        keys.push(path.basename(target));
+        return [...new Set(keys)];
+    }
+    lookupServiceEntry(map, servicePath) {
+        const entries = map ?? {};
+        for (const key of this.serviceEntryKeys(servicePath)) {
+            if (Object.prototype.hasOwnProperty.call(entries, key))
+                return entries[key];
+        }
+        return {};
+    }
     isLambdaRuntimeEnabled() {
         return this.config.lambdaRuntime?.enabled ?? true;
     }
@@ -286,13 +756,36 @@ export class ConfigManager {
     getInvokePortOffset() {
         return this.config.lambdaRuntime?.invokePortOffset ?? 10000;
     }
+    // Defer forking a service's worker to its first invocation. On by default:
+    // one Node process per registered service is ~48 MB, which a 40-service
+    // monorepo pays entirely up front for handlers it may never call.
+    isLambdaRuntimeLazy() {
+        return this.config.lambdaRuntime?.lazy ?? true;
+    }
+    // A worker only stays resident while it is being used. 0 disables unloading.
+    getLambdaIdleTimeoutMs() {
+        const raw = this.config.lambdaRuntime?.idleTimeoutMs;
+        if (raw === undefined)
+            return 60_000;
+        return typeof raw === 'number' && raw > 0 ? raw : 0;
+    }
+    // Ceiling on resident workers. Default: one per GB of system RAM, clamped to
+    // 2..12 — the point is that the host's memory is bounded by how many services
+    // are in flight, never by how many are registered. 0 disables the ceiling.
+    getLambdaMaxWarmWorkers() {
+        const raw = this.config.lambdaRuntime?.maxWarmWorkers;
+        if (typeof raw === 'number' && raw >= 0)
+            return Math.floor(raw);
+        const gib = Math.floor(os.totalmem() / (1024 ** 3));
+        return Math.max(2, Math.min(12, gib));
+    }
     getInvokeHost() {
         if (this.config.lambdaRuntime?.invokeHost) {
             return this.config.lambdaRuntime.invokeHost;
         }
-        // Self engine: nothing runs inside Docker, so callbacks into the invoke
-        // listeners resolve on the loopback directly.
-        return this.isSelfEngine() ? '127.0.0.1' : 'host.docker.internal';
+        // Nothing runs inside a container, so callbacks into the invoke listeners
+        // resolve on the loopback directly.
+        return '127.0.0.1';
     }
     /**
      * Resolve the effective runtime settings for one service, merging the global
@@ -302,11 +795,7 @@ export class ConfigManager {
      * (true for source, false for artifact).
      */
     getRuntimeConfigForService(servicePath) {
-        const map = this.config.serviceRuntime ?? {};
-        const baseName = path.basename(servicePath);
-        const configDir = path.resolve(this.configPath ? path.dirname(this.configPath) : process.cwd());
-        const relPath = path.relative(configDir, servicePath).split(path.sep).join('/');
-        const perService = map[relPath] ?? map[baseName] ?? {};
+        const perService = this.lookupServiceEntry(this.config.serviceRuntime, servicePath);
         return {
             enabled: perService.enabled ?? this.isLambdaRuntimeEnabled(),
             execution: perService.execution ?? this.getLambdaExecutionMode(),
@@ -315,19 +804,13 @@ export class ConfigManager {
             invokePort: perService.invokePort,
         };
     }
-    getEngineKind() {
-        return this.config.engine ?? 'localstack';
-    }
-    isSelfEngine() {
-        return this.getEngineKind() === 'self';
-    }
     getSelfEngineConfig() {
         const selfEngine = this.config.selfEngine ?? {};
         const stateDir = this.getStateDir();
         const rawDataDir = selfEngine.dataDir
-            ?? (stateDir ? path.join(stateDir, 'engine') : path.join(os.homedir(), '.lss', 'engine'));
+            ?? (stateDir ? path.join(stateDir, 'engine') : this.homeStateDir('engine'));
         return {
-            port: selfEngine.port ?? 14566,
+            port: selfEngine.port ?? DEFAULT_PORT,
             dataDir: path.isAbsolute(rawDataDir) ? rawDataDir : path.resolve(process.cwd(), rawDataDir),
             account: selfEngine.account ?? '000000000000',
             idleUnloadMs: selfEngine.idleUnloadMs ?? 300000,
@@ -338,27 +821,27 @@ export class ConfigManager {
             region: this.getRegion(),
         };
     }
-    getAossSidecarConfig() {
-        // The self engine serves aoss natively — the sidecar must never run there.
-        const enabled = !this.isSelfEngine() && this.config.aossSidecar?.enabled !== false;
-        const port = this.config.aossSidecar?.port ?? 14567;
-        const stateDir = this.getStateDir();
-        return {
-            enabled,
-            port,
-            endpoint: `http://localhost:${port}`,
-            // Mirrors the self-engine default so both persistence roots sit side by
-            // side (<stateDir>/aoss for test isolation, else ~/.lss/aoss).
-            dataDir: stateDir ? path.join(stateDir, 'aoss') : path.join(os.homedir(), '.lss', 'aoss'),
-        };
+    // Fallback state root when the config declares no stateDir. Scoped to this
+    // project: a flat ~/.lss/<kind> meant every project on the machine shared one
+    // set of DynamoDB tables, queues and OpenSearch indices, so opening a second
+    // repo silently showed the first one's data.
+    homeStateDir(kind) {
+        return path.join(os.homedir(), '.lss', 'projects', projectCacheSegment(this.getProjectRoot()), kind);
     }
     // The AWS endpoint every SDK-based consumer (provisioner, explorers, seeds)
-    // should target for the active engine.
+    // targets. Reads the port directly rather than through getSelfEngineConfig(),
+    // which would also resolve the data dir — needless work for a URL, and it
+    // drags the project-root lookup into every caller that only wants an endpoint.
     getEngineEndpoint() {
-        if (this.isSelfEngine()) {
-            return `http://localhost:${this.getSelfEngineConfig().port}`;
-        }
-        return this.getLocalStackEndpoint();
+        return `http://localhost:${this.config.selfEngine?.port ?? DEFAULT_PORT}`;
+    }
+    /**
+     * True when the orchestrator and the engine share one listener — the default,
+     * since both ports default to the same value. Give them different values to
+     * go back to two listeners.
+     */
+    isSingleListener() {
+        return this.getServerPort() === (this.config.selfEngine?.port ?? DEFAULT_PORT);
     }
     getConfigPath() {
         return this.configPath;
@@ -423,35 +906,208 @@ export class ConfigManager {
             },
         };
     }
+    // Config keys currently masked by an environment variable (env wins over the
+    // file). The UI flags these fields so a save that "doesn't stick" is
+    // explained instead of silent.
+    getEnvOverriddenKeys() {
+        // Truthy check on purpose: loadFromEnv only applies truthy env values, so
+        // a variable exported as an empty string does not actually override the
+        // file and must not be reported as masking it.
+        return Object.keys(CONFIG_ENV_OVERRIDES).filter(key => CONFIG_ENV_OVERRIDES[key].some(name => Boolean(process.env[name])));
+    }
+    // Resolved values that are materialized into listeners, containers, engines
+    // or child processes at boot. Everything NOT listed here is consumed lazily
+    // (per request/registration/seed run) and follows a reload immediately.
+    resolvedBootValues() {
+        const selfEngine = this.getSelfEngineConfig();
+        return {
+            serverPort: this.getServerPort(),
+            enableDynamoProxy: this.isEnableDynamoProxy(),
+            dynamoProxyPort: this.getDynamoProxyPort(),
+            region: this.getRegion(),
+            persistence: this.isPersistence(),
+            debug: this.isDebug(),
+            stateDir: this.getStateDir(),
+            // Only the block's OWN settings: region/persistence are tracked under
+            // their own keys above, so one change never flags two entries.
+            selfEngine: {
+                port: selfEngine.port,
+                dataDir: selfEngine.dataDir,
+                account: selfEngine.account,
+                idleUnloadMs: selfEngine.idleUnloadMs,
+                memoryBudgetMb: selfEngine.memoryBudgetMb,
+                fsync: selfEngine.fsync,
+                fallbackEndpoint: selfEngine.fallbackEndpoint,
+            },
+        };
+    }
+    static diffKeys(before, after) {
+        return Object.keys(before).filter(key => JSON.stringify(before[key]) !== JSON.stringify(after[key]));
+    }
+    resetAndReload() {
+        this.config = {};
+        this.configPath = '';
+        this.loadConfig();
+    }
+    /**
+     * Re-read the config file from disk — after a hand edit, or after
+     * updateConfig() wrote it. Runs the exact boot sequence (file search + env
+     * override pass), so the result matches what a fresh process would resolve.
+     * Boot-materialized keys that changed are reported as restartRequired: the
+     * running listeners/engine keep the old value until `lss stop && lss start`.
+     */
+    reloadFromDisk() {
+        // A hand-edit typo must not silently discard the working config: when the
+        // loaded file still exists but no longer parses, keep the current config
+        // and fail loudly instead of letting loadConfig fall through to the next
+        // search candidate (the user-global home config, or nothing at all).
+        if (this.configPath && fs.existsSync(this.configPath)) {
+            try {
+                JSON.parse(fs.readFileSync(this.configPath, 'utf-8'));
+            }
+            catch {
+                throw new ConfigValidationError([
+                    `${this.configPath} is not valid JSON — fix the file and reload again`,
+                ]);
+            }
+        }
+        const before = this.resolvedBootValues();
+        this.resetAndReload();
+        return {
+            path: this.configPath,
+            restartRequired: ConfigManager.diffKeys(before, this.resolvedBootValues()),
+        };
+    }
+    /**
+     * Validate a partial config patch, write it into the loaded config file (or
+     * create lss.config.json in the project root when none is loaded) and reload
+     * in-memory. The raw file is re-read and patched key-by-key — never the
+     * env-resolved in-memory config — so env-var overrides are not baked into
+     * the file on save. The human commits the file; LSS never touches git.
+     */
+    updateConfig(patch) {
+        if (!isPlainObject(patch)) {
+            throw new ConfigValidationError(['config patch must be a JSON object of top-level lss.config.json keys']);
+        }
+        const errors = [];
+        for (const [key, value] of Object.entries(patch)) {
+            if (BLOCKED_CONFIG_KEYS.has(key)) {
+                errors.push(`"${key}" cannot be edited via the API — set it in the config file or environment directly`);
+                continue;
+            }
+            const spec = Object.prototype.hasOwnProperty.call(EDITABLE_CONFIG_KEYS, key)
+                ? EDITABLE_CONFIG_KEYS[key]
+                : undefined;
+            if (!spec) {
+                errors.push(`unknown config key "${key}"`);
+                continue;
+            }
+            if (value === null)
+                continue; // null deletes the key (or subkey) from the file
+            const error = validateValue(key, value, spec);
+            if (error)
+                errors.push(error);
+        }
+        if (errors.length > 0) {
+            throw new ConfigValidationError(errors);
+        }
+        // Snapshot the resolved boot values BEFORE any mutation, so a failure
+        // later in this method can never compare against poisoned state.
+        const before = this.resolvedBootValues();
+        const target = this.configPath || path.join(this.getProjectRoot(), 'lss.config.json');
+        let fileConfig = {};
+        if (fs.existsSync(target)) {
+            try {
+                fileConfig = JSON.parse(fs.readFileSync(target, 'utf-8'));
+            }
+            catch {
+                // Never clobber a file the user may be hand-editing mid-typo.
+                throw new ConfigValidationError([
+                    `${target} exists but is not valid JSON — fix or remove it before saving from the dashboard`,
+                ]);
+            }
+        }
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === null) {
+                delete fileConfig[key];
+            }
+            else if (EDITABLE_CONFIG_KEYS[key].kind === 'object') {
+                // One-level merge so a partial block edit (e.g. branding.title) never
+                // drops sibling settings the UI does not round-trip (branding.logo).
+                // Map-shaped blocks (serviceRuntime/servicePackaging) merge one level
+                // deeper for the same reason: onboarding sending { apiPort } for one
+                // service must not drop that entry's execution/packageEnv siblings.
+                const perEntry = Boolean(EDITABLE_CONFIG_KEYS[key].entrySubKeys);
+                const existing = isPlainObject(fileConfig[key])
+                    ? fileConfig[key]
+                    : {};
+                const merged = { ...existing };
+                for (const [subKey, subValue] of Object.entries(value)) {
+                    if (subValue === null) {
+                        delete merged[subKey];
+                    }
+                    else if (perEntry && isPlainObject(subValue)) {
+                        const entryExisting = isPlainObject(merged[subKey])
+                            ? merged[subKey]
+                            : {};
+                        const entryMerged = { ...entryExisting };
+                        for (const [entryKey, entryValue] of Object.entries(subValue)) {
+                            if (entryValue === null) {
+                                delete entryMerged[entryKey];
+                            }
+                            else {
+                                entryMerged[entryKey] = entryValue;
+                            }
+                        }
+                        // An entry left with no settings carries no meaning and would
+                        // shadow a basename-keyed entry for the same service (an empty
+                        // object is truthy), so it is dropped rather than written.
+                        if (Object.keys(entryMerged).length === 0) {
+                            delete merged[subKey];
+                        }
+                        else {
+                            merged[subKey] = entryMerged;
+                        }
+                    }
+                    else {
+                        merged[subKey] = subValue;
+                    }
+                }
+                fileConfig[key] = merged;
+            }
+            else {
+                fileConfig[key] = value;
+            }
+        }
+        fs.writeFileSync(target, `${JSON.stringify(fileConfig, null, 2)}\n`);
+        this.resetAndReload();
+        return {
+            // The written file is a search candidate, so the reload finds it again;
+            // fall back to the target path defensively.
+            path: this.configPath || target,
+            restartRequired: ConfigManager.diffKeys(before, this.resolvedBootValues()),
+            // Truthy check to mirror loadFromEnv: an empty-string env var does not
+            // actually override the file, so it must not be reported as a mask.
+            envOverridden: Object.keys(patch).filter(key => (CONFIG_ENV_OVERRIDES[key] ?? []).some(name => Boolean(process.env[name]))),
+        };
+    }
     /**
      * Print configuration summary
      */
     printSummary() {
         console.log('\n📋 Configuration Summary:');
         console.log(`  Server Port: ${this.getServerPort()} (http://localhost:${this.getServerPort()})`);
-        console.log(`  Engine: ${this.getEngineKind()}`);
-        if (this.isSelfEngine()) {
-            const selfEngine = this.getSelfEngineConfig();
-            console.log(`  Self Engine Port: ${selfEngine.port} (http://localhost:${selfEngine.port})`);
-            console.log(`  Self Engine Data Dir: ${selfEngine.dataDir}`);
-            if (selfEngine.fallbackEndpoint) {
-                console.log(`  Self Engine Fallback: ${selfEngine.fallbackEndpoint}`);
-            }
-        }
-        else {
-            console.log(`  LocalStack Mode: ${this.getMode()}`);
-            console.log(`  LocalStack Port: ${this.getLocalStackPort()} (${this.getLocalStackEndpoint()})`);
-            if (!this.isExternal()) {
-                console.log(`  LocalStack Image: ${this.getLocalStackImage()} (${this.getLocalStackEdition()})`);
-                console.log(`  LocalStack Auth Token: ${this.getLocalStackAuthToken() ? 'set' : 'not set'}`);
-            }
+        const selfEngine = this.getSelfEngineConfig();
+        console.log(`  Self Engine Port: ${selfEngine.port} (http://localhost:${selfEngine.port})`);
+        console.log(`  Self Engine Data Dir: ${selfEngine.dataDir}`);
+        if (selfEngine.fallbackEndpoint) {
+            console.log(`  Self Engine Fallback: ${selfEngine.fallbackEndpoint}`);
         }
         console.log(`  DynamoDB Proxy Enabled: ${this.isEnableDynamoProxy()}`);
         if (this.isEnableDynamoProxy()) {
             console.log(`  DynamoDB Proxy Port: ${this.getDynamoProxyPort()}`);
         }
         console.log(`  AWS Region: ${this.getRegion()}`);
-        console.log(`  Services: ${this.getServices().join(', ')}`);
         console.log(`  Persistence: ${this.isPersistence()}`);
         console.log(`  Seeds Dir: ${this.getSeedsDir()}`);
         const secretSeedCount = Object.keys(this.getSecretSeeds()).length;