Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

33.5 KB
Raw Blame
import {
  Controller,
  Get,
  Put,
  Post,
  Body,
  BadRequestException,
  HttpException,
  HttpCode,
  HttpStatus,
  Optional,
} from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiBody } from '@nestjs/swagger';
import { InfraConfigResponseDto, InfraConfigSaveResponseDto, InfraRestartResponseDto } from './dto/infra-response.dto';
import { RestartDto } from './dto/restart.dto';
import { RequireRole, RequireUnscopedKey } from '../auth/decorators/auth.decorators';
import { ApiKeyRole } from '../auth/entities/api-key.entity';
import { writeSecretFile } from '../../common/utils/secret-file';
import { EngineFactory } from '../../engine/engine.factory';
import {
  BUNDLED_SERVICE_ENV,
  DockerService,
  MANAGED_DOCKER_PROFILES,
  datastoreInUse,
  hostPinnedElsewhere,
  namesBundledContainer,
} from '../docker';
import { ShutdownService } from '../../common/services/shutdown.service';
import { createLogger } from '../../common/services/logger.service';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import { SaveConfigDto } from './dto/save-config.dto';
import { assertNoDefaultSecretsInProduction } from '../../config/bootstrap-security';
import { s3EndpointError, validateEnv } from '../../config/env.validation';
import { BLANK_SHADOWED_ENV_KEYS, isEnvPinned, isOsProvidedEnv } from '../../config/env-precedence';
import { resolveStorageRoot } from '../../config/storage-root';
import { randomUUID } from 'crypto';
import * as fs from 'fs';
import * as path from 'path';
import * as dotenv from 'dotenv';
import { encodeGeneratedEnvValue, generatedEnvPath, readGeneratedEnv } from './generated-env';
import { savedBuiltInMode } from './saved-builtin-mode';
import {
  applyDatabaseSection,
  applyEngineSection,
  applyRedisSection,
  applyStorageSection,
  ConfigSectionContext,
} from './config-sections';

// The PUT /infra/config body DTOs live in ./dto/save-config.dto.ts and the restart body in
// ./dto/restart.dto.ts: as *.dto.ts classes they are covered by the input-coercion drift gate
// (src/common/utils/dto-strict-coercion.spec.ts), which controller-local classes escape, and their
// boolean/numeric fields carry the @ToStrictBoolean / @ToStrictNumber transforms that keep a form-encoded
// 'false' from being coerced to `true`.

// Saved infrastructure config returned to the dashboard form for hydration. Secret
// values are never echoed back — a `*Set` boolean indicates whether one is stored.
interface SavedConfigResponse {
  database: {
    type: 'sqlite' | 'postgres';
    builtIn: boolean;
    builtInSet: boolean;
    host: string;
    port: string;
    username: string;
    database: string;
    schema: string;
    poolSize: number;
    sslEnabled: boolean;
    sslRejectUnauthorized: boolean;
    passwordSet: boolean;
  };
  redis: { enabled: boolean; builtIn: boolean; builtInSet: boolean; host: string; port: string; passwordSet: boolean };
  queue: { enabled: boolean };
  storage: {
    type: 'local' | 's3';
    builtIn: boolean;
    builtInSet: boolean;
    localPath: string;
    s3Bucket: string;
    s3Region: string;
    s3Endpoint: string;
    s3CredentialsSet: boolean;
  };
  engine: { type: string; headless: boolean; sessionDataPath: string; browserArgs: string };
}

// Errors of replacing the overlay by rename that the in-place write v0.25.0 used can still get past.
const IN_PLACE_FALLBACK_CODES = ['EBUSY', 'EXDEV', 'EACCES', 'EPERM', 'EROFS'];

@ApiTags('infrastructure')
@Controller('infra')
// Every route here is deployment-global (data export/import, infra config, service orchestration),
// so the guard's route-param session fence can never bite. Reject session-scoped keys outright at
// class level, which also covers routes added later. @Public routes are unaffected: the guard
// returns before it reads this metadata.
@RequireUnscopedKey()
export class InfraConfigController {
  private readonly logger = createLogger('InfraConfigController');

  constructor(
    private readonly engineFactory: EngineFactory,
    private readonly dockerService: DockerService,
    private readonly shutdownService: ShutdownService,
    // Best-effort audit emission for the sensitive infra operations below. Injected @Optional and
    // appended last so it never shifts the existing positional args: the running app always provides
    // the @Global AuditService, while the direct-construction unit tests omit it — the `?.` at each
    // call site then makes emission a no-op there instead of forcing every test to wire a mock.
    @Optional()
    private readonly auditService?: AuditService,
  ) {}

  @Get('config')
  @RequireRole(ApiKeyRole.ADMIN)
  @ApiOperation({ summary: 'Read the effective infrastructure configuration for the dashboard form' })
  @ApiResponse({ status: 200, description: 'Effective configuration (secrets omitted)', type: InfraConfigResponseDto })
  getConfig(): SavedConfigResponse {
    const saved = readGeneratedEnv();

    // A value supplied by the host environment or the project .env outranks data/.env.generated at
    // every boot (load-env's override:false order), so the form must read it back instead of the
    // first-run defaults — otherwise a compose `environment:` deployment shows whatsapp-web.js/sqlite
    // while the process actually runs baileys/postgres (#1313). isEnvPinned's boot snapshot excludes
    // file-sourced keys, so a value that only ever lived in data/.env.generated is NOT pinned and the
    // freshly-saved file still wins over process.env's stale boot-time copy — keeping the
    // "saved, pending restart" form state intact until the reboot applies it (#226/#1082). A pinned
    // blank is read as-is: boot's clearBlankEnv drops blank host forwards before the snapshot, so a
    // blank that is still pinned is a `KEY=` line in ./.env, which the file can never fill at boot.
    const effective = (key: string): string | undefined =>
      (isEnvPinned(key) ? process.env[key] : undefined) ?? saved[key];

    // Secrets (passwords, S3 keys) are never returned; the form shows a "set" indicator
    // and an empty submission preserves the stored value (see saveConfig). This lets
    // the dashboard hydrate the form so a save no longer overwrites unseen fields (#226).
    const databaseType = effective('DATABASE_TYPE') === 'postgres' ? 'postgres' : 'sqlite';
    return {
      database: {
        type: databaseType,
        ...savedBuiltInMode('database', saved),
        host: effective('DATABASE_HOST') || '',
        port: effective('DATABASE_PORT') || '',
        username: effective('DATABASE_USERNAME') || '',
        // The form sends this back for a PostgreSQL save; under SQLite the key holds a file path, not a name.
        database: databaseType === 'postgres' ? effective('DATABASE_NAME') || '' : '',
        schema: effective('POSTGRES_SCHEMA') || 'public',
        poolSize: Number(effective('DATABASE_POOL_SIZE')) || 10,
        sslEnabled: effective('DATABASE_SSL') === 'true',
        sslRejectUnauthorized: effective('DATABASE_SSL_REJECT_UNAUTHORIZED') !== 'false',
        passwordSet: Boolean(effective('DATABASE_PASSWORD')),
      },
      redis: {
        enabled: effective('REDIS_ENABLED') === 'true',
        ...savedBuiltInMode('redis', saved),
        host: effective('REDIS_HOST') || '',
        port: effective('REDIS_PORT') || '',
        passwordSet: Boolean(effective('REDIS_PASSWORD')),
      },
      queue: { enabled: effective('QUEUE_ENABLED') === 'true' },
      storage: {
        type: effective('STORAGE_TYPE') === 's3' ? 's3' : 'local',
        ...savedBuiltInMode('storage', saved),
        localPath: effective('STORAGE_LOCAL_PATH') || '',
        s3Bucket: effective('S3_BUCKET') || '',
        s3Region: effective('S3_REGION') || '',
        s3Endpoint: effective('S3_ENDPOINT') || '',
        s3CredentialsSet: Boolean(
          (effective('S3_ACCESS_KEY_ID') || effective('S3_ACCESS_KEY')) &&
          (effective('S3_SECRET_ACCESS_KEY') || effective('S3_SECRET_KEY')),
        ),
      },
      engine: {
        type: effective('ENGINE_TYPE') || 'whatsapp-web.js',
        headless: effective('PUPPETEER_HEADLESS') !== 'false',
        sessionDataPath: effective('SESSION_DATA_PATH') || '',
        browserArgs: effective('PUPPETEER_ARGS') || '',
      },
    };
  }

  @Put('config')
  @RequireRole(ApiKeyRole.ADMIN)
  @ApiOperation({ summary: 'Save infrastructure configuration to .env file' })
  @ApiResponse({
    status: 200,
    description: 'Save outcome. A failed disk write answers 200 with `saved: false`, so read the flag, not the status.',
    type: InfraConfigSaveResponseDto,
  })
  @ApiResponse({
    status: 400,
    description:
      'Rejected before anything was written: an invalid or unknown field, an unknown engine type, a value with a ' +
      'line break or one that cannot be stored, a configuration that would not boot in production or that the boot ' +
      'environment validation rejects, or a media storage path the app cannot write to.',
  })
  @ApiBody({ description: 'Configuration to save', type: SaveConfigDto })
  saveConfig(@Body() config: SaveConfigDto): { message: string; saved: boolean; envPath: string; profiles: string[] } {
    try {
      const profiles: string[] = [];

      // Merge into the existing saved config rather than rebuilding from scratch, so a
      // partial payload (the dashboard only sends the sections it renders) cannot wipe
      // keys it didn't include (#226). The merge is per-section AND per-key: an absent
      // section leaves that section's keys alone, and within a present section an absent
      // field (`undefined`) leaves its stored key alone — only values actually submitted
      // are written. `existing` below is therefore the base for every key the payload
      // does not mention.
      const envPath = generatedEnvPath();
      const existing = readGeneratedEnv();
      const updates: Record<string, string> = {};
      // Keys to remove from the merged result — used to drop stale settings when the
      // user switches mode (postgres->sqlite, s3->local, built-in->external) so a reload
      // never sees the new mode alongside leftover keys from the old one.
      const staleKeys = new Set<string>();

      const ctx: ConfigSectionContext = { updates, staleKeys, profiles };

      this.applyConfigSections(config, existing, ctx);
      this.assertNoLineBreakValues(updates);
      const merged = this.mergeWithExisting(existing, ctx);
      this.assertProductionBootable(merged);
      this.assertBootValidates(existing, merged);
      this.assertStorageRootWritable(updates, merged);
      this.persistGeneratedEnv(envPath, merged);
      this.auditConfigSaved(config, profiles);

      return this.buildSaveResponse(envPath, profiles);
    } catch (error) {
      // A validation rejection (unknown engine type, or a newline-injected value) is a BadRequestException
      // and MUST surface as its real 4xx status, not be masked as an HTTP 200 {saved:false} — a client
      // branching on HTTP status alone would otherwise treat rejected input as success. Re-throw any
      // HttpException so the Nest layer maps it. A non-HTTP failure (e.g. a writeSecretFile disk/permission
      // error) stays a {saved:false} 200, preserving the dashboard's body.saved handling for I/O faults.
      if (error instanceof HttpException) {
        throw error;
      }
      return {
        message: `Failed to save configuration: ${error instanceof Error ? error.message : 'Unknown error'}`,
        saved: false,
        envPath: '',
        profiles: [],
      };
    }
  }

  // Dispatch each present payload section to its applier; an absent section leaves its saved keys alone.
  private applyConfigSections(
    config: SaveConfigDto,
    existing: Record<string, string>,
    ctx: ConfigSectionContext,
  ): void {
    const { updates } = ctx;
    if (config.database) {
      applyDatabaseSection(config.database, existing, ctx);
    }

    // Redis and queue are independent sections: a payload carrying only one of them must
    // not rewrite (or disable) the other's saved keys. The queue goes first because it reaches Redis
    // too, and the Redis section reads its new switch.
    if (config.queue) {
      if (config.queue.enabled !== undefined) updates.QUEUE_ENABLED = config.queue.enabled ? 'true' : 'false';
    }
    if (config.redis) {
      applyRedisSection(config.redis, existing, ctx);
    }

    if (config.storage) {
      applyStorageSection(config.storage, existing, ctx);
    }

    if (config.engine) {
      applyEngineSection(config.engine, existing, ctx, this.engineFactory);
    }
  }

  private assertNoLineBreakValues(updates: Record<string, string>): void {
    // .env.generated is one KEY=value per line, loaded on the next boot. A value carrying a
    // line break would write a second line and inject an arbitrary env var the operator never
    // set, so refuse any such value before writing anything.
    for (const [key, value] of Object.entries(updates)) {
      if (/[\r\n]/.test(value)) {
        throw new BadRequestException(`Invalid configuration value for ${key}: line breaks are not allowed`);
      }
    }
  }

  private mergeWithExisting(existing: Record<string, string>, ctx: ConfigSectionContext): Record<string, string> {
    const { updates, staleKeys } = ctx;
    // Existing values are the base; this payload's values win (secrets handled above).
    const merged: Record<string, string> = { ...existing, ...updates };
    // Drop keys made obsolete by a mode switch (postgres->sqlite, s3->local, built-in->external).
    for (const k of staleKeys) {
      delete merged[k];
    }
    return merged;
  }

  // The value the next boot reads for `key`, so the save-time guards judge what it will see.
  //
  // Evaluate what that boot would actually SEE, not just what the file holds: load-env.ts
  // loads with dotenv override:false, so a value supplied via the container environment
  // (compose `environment:`) wins over this file — the precedence the file header documents.
  // Without that, a deployment providing DATABASE_PASSWORD & co. through the environment is
  // refused on EVERY save even though its boot passes the guard. A pinned blank is kept as-is:
  // clearBlankEnv drops blank host forwards before either snapshot, so a blank that is still
  // pinned is a `KEY=` line in ./.env, and boot keeps it. Only without a snapshot (a process that
  // never ran load-env) does a blank on a blank-forwarded key count as unset, as clearBlankEnv would.
  //
  // Only a key from a layer ABOVE the file may win: the host, or the project .env, which load-env
  // also loads ahead of data/.env.generated with override:false. load-env merges the generated
  // file into process.env too, so reading process.env alone would hand back the very file this
  // save is replacing: the guard would then bless a flip by validating the OLD config (a
  // built-in -> external switch keeping the bundled 'openwa' password would save cleanly and
  // crash-loop the next production boot, the exact case this guard exists for). isEnvPinned's
  // snapshot is taken before that file loads; isOsProvidedEnv keeps the no-snapshot default of
  // assuming an override.
  private bootValueReader(merged: Record<string, string>): (key: string) => string | undefined {
    return (key: string): string | undefined => {
      if (isEnvPinned(key) && process.env[key] !== undefined) return process.env[key];
      const envValue = isOsProvidedEnv(key) ? process.env[key] : undefined;
      if (envValue !== undefined && (envValue.trim() !== '' || !BLANK_SHADOWED_ENV_KEYS.includes(key))) {
        return envValue;
      }
      return merged[key];
    };
  }

  // Save-time production guard. The file is loaded on the NEXT boot, which may run with
  // NODE_ENV=production regardless of this process's environment — so evaluate the merged
  // result with the very same boot guard (as production) and refuse the save when that boot
  // would refuse to start. This is what stops a built-in->external flip with no fresh
  // credentials from persisting a config that crash-loops the next production boot.
  private assertProductionBootable(merged: Record<string, string>): void {
    const bootValue = this.bootValueReader(merged);
    try {
      assertNoDefaultSecretsInProduction({
        nodeEnv: 'production',
        databaseType: bootValue('DATABASE_TYPE'),
        databasePassword: bootValue('DATABASE_PASSWORD'),
        postgresBuiltIn: bootValue('POSTGRES_BUILTIN'),
        databaseHost: bootValue('DATABASE_HOST'),
        storageType: bootValue('STORAGE_TYPE'),
        // The same canonical-with-legacy fallback main.ts and storage.service apply.
        s3AccessKey: bootValue('S3_ACCESS_KEY_ID') || bootValue('S3_ACCESS_KEY'),
        s3SecretKey: bootValue('S3_SECRET_ACCESS_KEY') || bootValue('S3_SECRET_KEY'),
        s3Endpoint: bootValue('S3_ENDPOINT'),
        minioBuiltIn: bootValue('MINIO_BUILTIN'),
        redisPassword: bootValue('REDIS_PASSWORD'),
      });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      throw new BadRequestException(
        `Refusing to save a configuration that would be rejected at production boot. ${detail}`,
      );
    }
  }

  // The environment validation the next boot runs (env.validation.ts), applied to the same view of the merged result.
  // Without it a save the dashboard accepts, a PostgreSQL selection with no host or a pool size that is not a plain
  // integer, crash-loops the instance and the dashboard that could undo it.
  // The boot only reports an S3 endpoint the client cannot use, so an instance that stored one keeps starting and keeps
  // saving. The dashboard sends the storage type and endpoint with every save, so the endpoint is refused only when this
  // save changes what the boot reads for it or newly selects S3; resubmitting it, an environment pin the page cannot
  // change, or a switch to local storage goes through.
  private assertBootValidates(existing: Record<string, string>, merged: Record<string, string>): void {
    const bootValue = this.bootValueReader(merged);
    const before = this.bootValueReader(existing);
    try {
      const env = Object.fromEntries(Object.keys({ ...process.env, ...merged }).map(key => [key, bootValue(key)]));
      validateEnv(env);
      const endpointChanged = (before('S3_ENDPOINT') ?? '').trim() !== (bootValue('S3_ENDPOINT') ?? '').trim();
      const newlyS3 = before('STORAGE_TYPE') !== 's3' && bootValue('STORAGE_TYPE') === 's3';
      const s3Problem = endpointChanged || newlyS3 ? s3EndpointError(env) : null;
      if (s3Problem) throw new Error(s3Problem);
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      throw new BadRequestException(`Refusing to save a configuration that fails boot validation. ${detail}`);
    }
  }

  // A storage path the app cannot create or write is refused by the next boot before Nest builds, which
  // crash-loops the instance with the dashboard that could undo the save down. Only a path this save
  // names is judged, and only when the boot will read it: a value the host or the project .env pins
  // outranks the file, so the submitted one never reaches the boot. The probe is the boot's own, so the
  // fossil `./uploads` it tolerates is tolerated here too. It names the submitted value only, not the
  // absolute path it resolves to, as the save response does not disclose the host's layout.
  private assertStorageRootWritable(updates: Record<string, string>, merged: Record<string, string>): void {
    const submitted = updates.STORAGE_LOCAL_PATH;
    if (submitted === undefined || this.bootValueReader(merged)('STORAGE_LOCAL_PATH') !== submitted) return;
    try {
      resolveStorageRoot({ configured: submitted });
    } catch {
      throw new BadRequestException(
        `Refusing to save the storage path '${submitted}': the app cannot create or write it, and the next start ` +
          'would refuse to boot. Use a directory the app user owns, inside the data volume when running in ' +
          'Docker (for example ./data/media).',
      );
    }
  }

  private persistGeneratedEnv(envPath: string, merged: Record<string, string>): void {
    const unreadable = (key: string) =>
      new BadRequestException(
        `Invalid configuration value for ${key}: it cannot be stored so that it reads back unchanged`,
      );
    const keys = Object.keys(merged).sort();
    const body = keys.map(key => {
      // Quoted where a raw line would read back differently (a `#` in a password would otherwise
      // truncate it on the next boot); refused, before anything is written, where no form can carry it.
      const encoded = encodeGeneratedEnvValue(key, merged[key]);
      if (encoded === undefined) throw unreadable(key);
      return `${key}=${encoded}`;
    });
    const contents = [
      '# OpenWA Configuration',
      `# Generated at ${new Date().toISOString()}`,
      '# Managed via Dashboard > Infrastructure. Values in process env or project .env take precedence.',
      '',
      ...body,
      '',
    ].join('\n');
    // The next boot parses the file as a whole, where a quoted value can run on into a later line
    // (a trailing `\'` escapes its own closing quote), so each line reading back alone is not enough.
    const back = dotenv.parse(contents);
    const drifted = keys.find(key => back[key] !== merged[key]);
    if (drifted !== undefined) throw unreadable(drifted);

    // Write to data/ so it persists across container restarts. Owner-only (0600): this file holds
    // the DB/S3/Redis credentials, so it must not be world-readable between save and next restart.
    // Staged beside the target and renamed over it: a write that fails part-way (disk full) would
    // otherwise leave a truncated overlay for the next boot to load. A symlink is written through to its
    // target. A file the filesystem will not replace by rename (a single-file bind mount, another device) or
    // that cannot be staged beside (a directory the app cannot write, holding a file it can) is written in
    // place, as before. Any other failure, a full disk included, leaves the previous overlay untouched.
    const target = this.overlayTarget(envPath);
    if (target === undefined) {
      writeSecretFile(envPath, contents);
    } else {
      const staged = `${target}.${randomUUID()}.tmp`;
      try {
        writeSecretFile(staged, contents);
        fs.renameSync(staged, target);
      } catch (error) {
        try {
          fs.rmSync(staged, { force: true });
        } catch {
          // Keep the original write or rename error if cleanup also fails.
        }
        if (!IN_PLACE_FALLBACK_CODES.includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
        writeSecretFile(target, contents);
      }
    }
    this.logger.log('Configuration saved', { envPath });
  }

  // The file a save replaces: the overlay itself, or what a symlink at its path points to. Undefined for a link
  // that points nowhere, which only an in-place write through it can create.
  private overlayTarget(envPath: string): string | undefined {
    let isLink: boolean;
    try {
      isLink = fs.lstatSync(envPath).isSymbolicLink();
    } catch {
      return envPath;
    }
    if (!isLink) return envPath;
    try {
      return fs.realpathSync(envPath);
    } catch {
      return undefined;
    }
  }

  private auditConfigSaved(config: SaveConfigDto, profiles: string[]): void {
    // Audit the credential-bearing env mutation. Fire-and-forget (not awaited) so saveConfig stays
    // synchronous — its validation rejections must remain synchronous throws the tests assert via
    // `.toThrow`. Only section names + Docker profiles are recorded; secret values are never logged.
    void this.auditService?.logInfo(AuditAction.INFRA_CONFIG_SAVED, {
      metadata: { sections: Object.keys(config ?? {}), profiles },
    });
  }

  private buildSaveResponse(
    envPath: string,
    profiles: string[],
  ): { message: string; saved: boolean; envPath: string; profiles: string[] } {
    const profileMsg = profiles.length > 0 ? ` Docker profiles required: ${profiles.join(', ')}.` : '';

    return {
      message: `Configuration saved successfully.${profileMsg} Server restart required to apply changes.`,
      saved: true,
      // Return a cwd-relative path so the response doesn't disclose the absolute host filesystem layout.
      envPath: path.relative(process.cwd(), envPath),
      profiles,
    };
  }

  @Post('restart')
  @HttpCode(HttpStatus.OK)
  @RequireRole(ApiKeyRole.ADMIN)
  @ApiOperation({ summary: 'Request server restart with Docker orchestration' })
  @ApiResponse({ status: 200, description: 'Server will restart with new profiles', type: InfraRestartResponseDto })
  @ApiBody({ required: false, type: RestartDto })
  async requestRestart(@Body() body?: RestartDto): Promise<{
    message: string;
    restarting: boolean;
    profiles: string[];
    profilesToRemove: string[];
    estimatedTime: number;
    orchestration?: object;
    removal?: object;
  }> {
    // Never start a bundled service whose host the environment pins elsewhere: the pin outranks the saved file, so
    // the next boot dials the pinned host and the container would run with nothing using it.
    const requestedStart = body?.profiles || [];
    const pinnedElsewhere = requestedStart.filter(p => hostPinnedElsewhere(p));
    const profiles = requestedStart.filter(p => !pinnedElsewhere.includes(p));
    if (pinnedElsewhere.length > 0) {
      this.logger.warn('Not starting profiles whose host the environment pins elsewhere', { pinnedElsewhere });
    }
    // Never stop a bundled service the NEXT boot still dials, whatever the page asked for: the restarted
    // app would point at a stopped container and fail to boot, with the dashboard that could undo it. The
    // host it dials is the one the environment pins (e.g. the documented manual built-in Postgres with
    // DATABASE_HOST=postgres in .env, which outranks the saved config), else the one in the saved file,
    // which already holds the save that precedes this restart. Any spelling that reaches the container counts (the
    // container name, another letter case). A host moved away from the bundled name still stops its container.
    let saved: Record<string, string> | undefined;
    const dialsBundled = (profile: string): boolean => {
      const bundled = BUNDLED_SERVICE_ENV[profile];
      if (!bundled) return false;
      const [key] = bundled;
      const bootValue = this.bootValueReader((saved ??= readGeneratedEnv()));
      // A host that still names the container keeps it only while the next boot uses that datastore.
      return datastoreInUse(profile, bootValue) && namesBundledContainer(profile, bootValue(key));
    };
    const requestedRemoval = body?.profilesToRemove || [];
    const keptRunning = requestedRemoval.filter(dialsBundled);
    const profilesToRemove = requestedRemoval.filter(p => !keptRunning.includes(p));
    if (keptRunning.length > 0) {
      this.logger.warn('Keeping profiles the next boot still dials', { keptRunning });
    }
    let orchestrationResult: object | undefined;
    // Teardown is stop-only (see DockerService.stopManagedService): containers are stopped and
    // retained for re-enable, never deleted — the result below reports exactly that.
    let removalResult: { stopped: string[]; errors: string[] } | undefined;

    this.logger.log('Restart requested', { profiles });
    this.logger.log('Profiles to remove', { profilesToRemove });

    // If profiles are specified, orchestrate Docker containers
    if (this.dockerService.isDockerAvailable()) {
      // Remove only the profiles the Save flow explicitly asked to remove, and never one we're about to
      // (re)start. We deliberately do NOT infer teardown from the saved *_BUILTIN flag: the default
      // data/.env.generated carries POSTGRES_BUILTIN=false, so a bare compose-profile restart would
      // otherwise tear down the very backend the app is running on. The dashboard fills this list from the
      // live /infra/status at save time: the builtIn services minus the new profiles, plus a running container
      // OpenWA created whose host the environment pins elsewhere, less any whose next-boot host (the pinned one,
      // else the saved config read back, else the one the save sent when that read fails) still reaches it, and
      // less any whose host it cannot tell. A container is left running when that status read had failed, or when
      // the next boot still dials it (dropped above).
      // Only ever tear down OpenWA-managed services. An arbitrary profile name (or the empty string)
      // would otherwise reach stopManagedService and, via container-name matching, could stop an unrelated
      // container — so constrain teardown to the managed allowlist and drop anything else.
      const requested = profilesToRemove.filter(p => !profiles.includes(p));
      const toRemove = requested.filter(p => MANAGED_DOCKER_PROFILES.includes(p));
      const ignored = requested.filter(p => !MANAGED_DOCKER_PROFILES.includes(p));
      if (ignored.length > 0) {
        this.logger.warn('Ignoring non-managed profiles in profilesToRemove', { ignored });
      }

      // First, stop containers for disabled services (stop-only: retained, never deleted)
      if (toRemove.length > 0) {
        this.logger.log('Stopping disabled profiles (containers retained)...', { toRemove });
        removalResult = { stopped: [], errors: [] };

        for (const profile of toRemove) {
          try {
            const success = await this.dockerService.stopManagedService(profile);
            if (success) {
              removalResult.stopped.push(profile);
            } else {
              removalResult.errors.push(`Failed to stop ${profile}`);
            }
          } catch (err) {
            removalResult.errors.push(`Error stopping ${profile}: ${err instanceof Error ? err.message : String(err)}`);
          }
        }
        this.logger.log('Teardown result', { removalResult });
      }

      // Then, start containers for enabled services. Start shares the SAME managed allowlist as
      // teardown above: a non-managed name reaching orchestrateProfiles could, via container-name
      // matching, select an unrelated host container, so constrain start to the managed profiles too
      // and drop anything else. (DockerService already hard-prefixes openwa-<service> and filters on
      // the com.openwa.service label, so this is defense-in-depth, not the sole control.)
      const toStart = profiles.filter(p => MANAGED_DOCKER_PROFILES.includes(p));
      const ignoredStart = profiles.filter(p => !MANAGED_DOCKER_PROFILES.includes(p));
      if (ignoredStart.length > 0) {
        this.logger.warn('Ignoring non-managed profiles in profiles', { ignoredStart });
      }
      if (toStart.length > 0) {
        this.logger.log('Orchestrating enabled profiles...');
        orchestrationResult = await this.dockerService.orchestrateProfiles(toStart);
        this.logger.log('Orchestration result', { orchestrationResult });
      }
    } else {
      this.logger.warn('Docker not available, writing signal file instead');
      // Fallback: write signal file for host script — but apply the SAME managed-profile
      // constraint as the Docker path above: the external consumer of this file must never be
      // handed a profile name the in-process path would have refused.
      try {
        const signalFile = path.resolve(process.cwd(), 'data', '.orchestration-request.json');
        const toStart = profiles.filter(p => MANAGED_DOCKER_PROFILES.includes(p));
        const toRemove = profilesToRemove.filter(p => !profiles.includes(p) && MANAGED_DOCKER_PROFILES.includes(p));
        const ignored = [...profiles, ...profilesToRemove].filter(p => !MANAGED_DOCKER_PROFILES.includes(p));
        if (ignored.length > 0) {
          this.logger.warn('Ignoring non-managed profiles in the signal-file request', { ignored });
        }
        const orchestrationRequest = {
          timestamp: new Date().toISOString(),
          profiles: toStart,
          profilesToRemove: toRemove,
          action: 'restart-with-profiles',
        };
        fs.writeFileSync(signalFile, JSON.stringify(orchestrationRequest, null, 2), 'utf8');
        this.logger.log('Orchestration request written', { signalFile });
      } catch (err) {
        this.logger.error('Failed to write orchestration request', err instanceof Error ? err.message : String(err));
      }
    }

    // Record the operational action (Docker orchestration + scheduled restart) BEFORE starting the
    // shutdown, awaited so the row is persisted even as the process goes down.
    await this.auditService?.logInfo(AuditAction.INFRA_RESTART_REQUESTED, {
      metadata: { profiles, profilesToRemove },
    });

    // Schedule graceful shutdown after the configurable bounded grace (SHUTDOWN_DELAY_MS,
    // default 3s) — readiness reports 503 during the window so traffic drains first.
    void this.shutdownService.shutdown();

    // Calculate estimated time - base 15s + additional for each service (increased for reliability).
    // A typical healthy value, not a bound: ShutdownService force-exits teardown 67s after the grace.
    let estimatedTime = 15;
    if (profiles.includes('postgres')) estimatedTime += 20;
    if (profiles.includes('redis')) estimatedTime += 13;
    if (profiles.includes('minio')) estimatedTime += 15;
    if (profilesToRemove.length > 0) estimatedTime += profilesToRemove.length * 5; // +5s per removal

    return {
      message:
        profiles.length > 0 || profilesToRemove.length > 0
          ? `Server is restarting. Enabling: ${profiles.join(', ') || 'none'}. Disabling: ${profilesToRemove.join(', ') || 'none'}.`
          : 'Server is restarting. Please wait...',
      restarting: true,
      profiles,
      profilesToRemove,
      estimatedTime,
      orchestration: orchestrationResult,
      removal: removalResult,
    };
  }
}