local-serverless-stack 0.17.2 → 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,37 +12,219 @@ function realpathOrSelf(dir) {
         return dir;
     }
 }
-// Two config keys are deliberately absent (and rejected on write):
-// `localstackAuthToken` — the supported channel is the LOCALSTACK_AUTH_TOKEN
-// env var, the token must never transit the dashboard API — and `secrets`,
-// which holds seed material that belongs in the file/env only.
-const BLOCKED_CONFIG_KEYS = new Set(['localstackAuthToken', 'secrets']);
+// 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' },
-    localstackPort: { kind: 'port' },
-    localstackEndpoint: { kind: 'string' },
-    mode: { kind: 'string', enum: ['managed', 'external'] },
-    localstackEdition: { kind: 'string', enum: ['community', 'pro'] },
-    localstackVersion: { kind: 'string' },
-    localstackImage: { kind: 'string' },
     enableDynamoProxy: { kind: 'boolean' },
     dynamoProxyPort: { kind: 'port' },
     region: { kind: 'string' },
-    services: { kind: 'stringArray' },
     persistence: { kind: 'boolean' },
     debug: { kind: 'boolean' },
     seedsDir: { kind: 'string' },
     stateDir: { kind: 'string' },
     autoPackage: { kind: 'boolean' },
-    packageCommand: { kind: 'string' },
-    packageArgs: { kind: 'stringArray' },
-    packageEnv: { kind: 'stringRecord' },
+    packageCommand: { kind: 'packageCommand' },
+    packageArgs: { kind: 'packageArgs' },
+    packageEnv: { kind: 'envRecord' },
     servicePackaging: {
         kind: 'object',
         entrySubKeys: {
-            packageCommand: { kind: 'string' },
-            packageArgs: { kind: 'stringArray' },
-            packageEnv: { kind: 'stringRecord' },
+            // 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' },
         },
     },
@@ -54,6 +237,9 @@ const EDITABLE_CONFIG_KEYS = {
             watch: { kind: 'boolean' },
             invokePortOffset: { kind: 'positiveInt' },
             invokeHost: { kind: 'string' },
+            lazy: { kind: 'boolean' },
+            idleTimeoutMs: { kind: 'nonNegativeInt' },
+            maxWarmWorkers: { kind: 'nonNegativeInt' },
         },
     },
     serviceRuntime: {
@@ -66,7 +252,6 @@ const EDITABLE_CONFIG_KEYS = {
             watch: { kind: 'boolean' },
         },
     },
-    engine: { kind: 'string', enum: ['localstack', 'self'] },
     selfEngine: {
         kind: 'object',
         subKeys: {
@@ -79,13 +264,6 @@ const EDITABLE_CONFIG_KEYS = {
             fallbackEndpoint: { kind: 'string' },
         },
     },
-    aossSidecar: {
-        kind: 'object',
-        subKeys: {
-            enabled: { kind: 'boolean' },
-            port: { kind: 'port' },
-        },
-    },
     branding: {
         kind: 'object',
         subKeys: {
@@ -111,13 +289,6 @@ const EDITABLE_CONFIG_KEYS = {
 // is unset.
 const CONFIG_ENV_OVERRIDES = {
     serverPort: ['LSS_DASHBOARD_PORT', 'PORT'],
-    localstackPort: ['LSS_LOCALSTACK_PORT'],
-    localstackEndpoint: ['LSS_LOCALSTACK_ENDPOINT'],
-    mode: ['LSS_LOCALSTACK_MODE'],
-    localstackEdition: ['LSS_LOCALSTACK_EDITION'],
-    localstackVersion: ['LSS_LOCALSTACK_VERSION'],
-    localstackImage: ['LSS_LOCALSTACK_IMAGE'],
-    localstackAuthToken: ['LOCALSTACK_AUTH_TOKEN'],
     // 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.
@@ -132,12 +303,95 @@ const CONFIG_ENV_OVERRIDES = {
     packageCommand: ['LSS_PACKAGE_COMMAND'],
     packageTimeoutMs: ['LSS_PACKAGE_TIMEOUT_MS'],
     lambdaRuntime: ['LSS_LAMBDA_RUNTIME', 'LSS_LAMBDA_EXECUTION', 'LSS_LAMBDA_WATCH', 'LSS_INVOKE_HOST'],
-    engine: ['LSS_ENGINE'],
-    selfEngine: ['LSS_ENGINE_PORT'],
+    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':
@@ -148,6 +402,11 @@ function validateValue(key, value, spec) {
             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':
@@ -157,14 +416,46 @@ function validateValue(key, value, spec) {
             return spec.enum && !spec.enum.includes(value)
                 ? `"${key}" must be one of: ${spec.enum.join(', ')}`
                 : null;
-        case 'stringArray':
-            return Array.isArray(value) && value.every(v => typeof v === 'string')
-                ? null
-                : `"${key}" must be an array of strings`;
+        // 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':
-            return isPlainObject(value) && Object.values(value).every(v => typeof v === 'string')
-                ? null
-                : `"${key}" must be an object of string values`;
+        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`;
@@ -172,7 +463,12 @@ function validateValue(key, value, spec) {
             // null subvalues are always allowed — they delete the subkey on merge.
             if (spec.subKeys) {
                 for (const [subKey, subValue] of Object.entries(value)) {
-                    const subSpec = spec.subKeys[subKey];
+                    // 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)
@@ -189,7 +485,9 @@ function validateValue(key, value, spec) {
                     if (!isPlainObject(entryValue))
                         return `"${key}.${entryKey}" must be an object`;
                     for (const [subKey, subValue] of Object.entries(entryValue)) {
-                        const subSpec = spec.entrySubKeys[subKey];
+                        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)
@@ -249,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() {
@@ -266,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';
         }
@@ -302,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';
         }
@@ -350,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;
@@ -418,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;
@@ -468,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 ?? [])],
@@ -480,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;
     }
@@ -489,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
@@ -505,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(),
@@ -518,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,
@@ -541,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;
@@ -640,26 +920,16 @@ export class ConfigManager {
     // (per request/registration/seed run) and follows a reload immediately.
     resolvedBootValues() {
         const selfEngine = this.getSelfEngineConfig();
-        const aossSidecar = this.getAossSidecarConfig();
         return {
             serverPort: this.getServerPort(),
-            localstackPort: this.getLocalStackPort(),
-            localstackEndpoint: this.getLocalStackEndpoint(),
-            mode: this.getMode(),
-            localstackEdition: this.getLocalStackEdition(),
-            localstackVersion: this.getLocalStackVersion(),
-            localstackImage: this.getLocalStackImage(),
             enableDynamoProxy: this.isEnableDynamoProxy(),
             dynamoProxyPort: this.getDynamoProxyPort(),
             region: this.getRegion(),
-            services: this.getServices(),
             persistence: this.isPersistence(),
             debug: this.isDebug(),
             stateDir: this.getStateDir(),
-            engine: this.getEngineKind(),
-            // Only the block's OWN settings: region/persistence (self engine) and the
-            // stateDir-derived dataDir (aoss) are tracked under their own keys above,
-            // so one change never flags two entries.
+            // 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,
@@ -669,7 +939,6 @@ export class ConfigManager {
                 fsync: selfEngine.fsync,
                 fallbackEndpoint: selfEngine.fallbackEndpoint,
             },
-            aossSidecar: { enabled: aossSidecar.enabled, port: aossSidecar.port },
         };
     }
     static diffKeys(before, after) {
@@ -726,7 +995,9 @@ export class ConfigManager {
                 errors.push(`"${key}" cannot be edited via the API — set it in the config file or environment directly`);
                 continue;
             }
-            const spec = EDITABLE_CONFIG_KEYS[key];
+            const spec = Object.prototype.hasOwnProperty.call(EDITABLE_CONFIG_KEYS, key)
+                ? EDITABLE_CONFIG_KEYS[key]
+                : undefined;
             if (!spec) {
                 errors.push(`unknown config key "${key}"`);
                 continue;
@@ -763,6 +1034,10 @@ export class ConfigManager {
             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]
                     : {};
@@ -771,6 +1046,29 @@ export class ConfigManager {
                     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;
                     }
@@ -799,29 +1097,17 @@ export class ConfigManager {
     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;