@fjall/components-infrastructure 0.96.0 → 0.99.1

package/dist/lib/resources/aws/database/clickhouseConstants.js

@@ -0,0 +1,181 @@
+/** Database name created at ClickHouse bootstrap; consumed by BACKUP DATABASE,
+ *  OPTIMIZE TABLE, and the DatabaseName CfnOutput so all four sites share one source. */
+export const CLICKHOUSE_DATABASE_NAME = "analytics";
+/** Default EC2 instance type for ClickHouse (Graviton3 — fixed-spec cores).
+ *
+ *  `m7g.medium` (1 vCPU sustained, 4 GiB) chosen over `t4g.medium` (2 vCPU
+ *  burst, 4 GiB) because CH's steady-state merge/scan/aggregation profile is
+ *  not bursty — burst credits run out under the per-5min metrics ingest plus
+ *  the OPTIMIZE FINAL sidecar, leaving the box throttled at baseline (10–20%
+ *  of 2 vCPU) for the rest of the hour. Graviton3 is also ~25% faster on
+ *  columnar scans than Graviton2.
+ *
+ *  Settings are tuned for 1 vCPU sustained (max_threads=1 across all profiles,
+ *  max_concurrent_queries=4) — see clickhouseUserData.ts. Bumping to a larger
+ *  instance MUST be paired with raising those thread/concurrency caps.
+ *
+ *  Next size up: `m7g.large` (2 vCPU, 8 GiB) for sustained workloads, or
+ *  `r7g.medium` (1 vCPU, 8 GiB) when memory-bound. Set via
+ *  `clickhouseInstanceType` CDK context or the `instanceType` prop, no code
+ *  change needed (see clickhouseDatabase.ts:162). */
+export const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
+/** ClickHouse container image. Explicit `docker.io/` prefix is required so
+ *  string-form consumers in `ecsImages.ts#getContainerImage()` route through
+ *  `ContainerImage.fromRegistry(...)` instead of the ECR-repo fallback (which
+ *  would otherwise append a service-tag suffix and produce a double-colon
+ *  malformed image reference).
+ *
+ *  Pin the full patch (not the floating `26.3`) so prod and local containers
+ *  always run the same digest. The floating tag bit us once when CH 26.3.10
+ *  tightened config.xml validation overnight while local Docker caches still
+ *  held the prior patch — keep this pin in lockstep with
+ *  `webapp/docker-compose.yaml`.
+ *
+ *  Default Ubuntu (glibc) variant chosen over `-alpine` (musl): musl's
+ *  threading/NPTL implementation is materially slower under CH's per-merge
+ *  / per-query-stage thread fan-out, and musl's 128 KB default thread stack
+ *  has a recurring history of stack-overflow incidents on deep query plans.
+ *  Image size is ~250 MB larger but irrelevant on a single-instance EC2 ASG
+ *  that pulls once per launch. Upstream CH CI runs its full perf + stress
+ *  matrix on the Ubuntu build; Alpine is community-tier coverage. */
+export const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.10.60";
+/** EBS volume configuration. */
+export const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 80;
+export const CLICKHOUSE_EBS_IOPS = 3000;
+export const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
+/** ECS task resource allocation. m7g.medium ships with 4 GB; reserve 1 GB
+ *  for the host (kernel + ECS agent + cloudwatch agent + IMDS) and give
+ *  ClickHouse the remaining 3 GB. Stays right when bumping to m7g.large
+ *  (8 GB) — raise this value in lockstep, or fall back to deriving from
+ *  the instance type if we ever support multiple sizes. */
+export const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
+/** ClickHouse ports. */
+export const CLICKHOUSE_HTTP_PORT = 8123;
+export const CLICKHOUSE_NATIVE_PORT = 9000;
+export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
+/** EBS device name for the data volume (must match user data script). */
+export const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
+/** EBS mount path on the EC2 host. */
+export const CLICKHOUSE_DATA_MOUNT_PATH = "/mnt/clickhouse-data";
+/** Secrets Manager path prefix. */
+export const CLICKHOUSE_SECRETS_PREFIX = "fjall/clickhouse";
+/** Canonical Secrets Manager secret name for a ClickHouse user.
+ *  Two sites compute this name and they MUST match:
+ *    (a) the secret mint inside `createClickHouseUserSecret(...)` in
+ *        `clickhouseDatabase.ts` — calls this helper directly;
+ *    (b) the SSM live-reload script that fetches the admin password via
+ *        `aws secretsmanager get-secret-value --secret-id` — also calls
+ *        this helper directly.
+ *  Drift between the two would silently break the live-reload path post-
+ *  deploy on a users.d S3 change (no compile or test signal). */
+export function clickHouseUserSecretName(userName) {
+    return `${CLICKHOUSE_SECRETS_PREFIX}/${userName.replace(/_/g, "-")}-password`;
+}
+/** ECS-injected env var name carrying a user's plaintext password.
+ *  Canonical source is `@fjall/util/migration § userPasswordEnvName` — re-exported
+ *  here so the construct-side import chain stays unchanged while the runner
+ *  (`webapp/scripts/migration-runner.mjs`) and any future consumer share a single
+ *  declaration. Coupled values per `.claude/rules/code-quality.md § "Coupled values:
+ *  shared source at 2 occurrences"`. */
+export { userPasswordEnvName } from "@fjall/util/migration";
+/** Env var name carrying the SHA-256 of a user's plaintext password.
+ *  The container entrypoint wrapper derives this name from the
+ *  `USER_<NAME>_PASSWORD` env var injected by ECS `secretsImport`, then
+ *  resolves `<password_sha256_hex from_env="..."/>` directives in
+ *  `users.d/fjall.xml` against it at server start. */
+export function userSha256EnvName(userName) {
+    return `USER_${userName.toUpperCase()}_SHA256`;
+}
+/** Canonical bash pipeline that hashes a ClickHouse user password.
+ *  Invoked from the container entrypoint wrapper
+ *  (`buildClickHouseEntrypointWrapper`) to derive `USER_<NAME>_SHA256` from
+ *  the ECS-injected plaintext at server start.
+ *  @param plaintextShellRef A quoted bash reference to the plaintext
+ *    password (e.g. `"\${!var}"` for the wrapper's indirect deref). */
+export function clickHousePasswordSha256Snippet(plaintextShellRef) {
+    return `printf '%s' ${plaintextShellRef} | sha256sum | awk '{print $1}'`;
+}
+/** Tag identifying ClickHouse server ASG instances.
+ *  Three sites carry this pair and they MUST match: (a) the `tags:` map on
+ *  the ClickHouse EC2 instance (threaded through to ASG instance tags),
+ *  (b) the SSM `Targets: [{ Key: "tag:<key>", Values: ["<value>"] }]` filter
+ *  on the live-reload `AwsCustomResource`, and (c) the synth snapshot tests
+ *  pinning the relationship. Drift between (a) and (b) silently routes the
+ *  reload command to zero instances — the `InvocationDoesNotExist` failure
+ *  is already suppressed by `ignoreErrorCodesMatching`, so the misroute
+ *  emits no signal. */
+export const CLICKHOUSE_SERVER_ROLE_TAG = {
+    key: "ClickHouseRole",
+    value: "server"
+};
+/** Shared secret generation options (all ClickHouse users share the same policy). */
+export const CLICKHOUSE_SECRET_OPTIONS = {
+    excludePunctuation: true,
+    passwordLength: 32
+};
+/** Health check configuration. */
+export const CLICKHOUSE_HEALTH_CHECK = {
+    INTERVAL_SECONDS: 30,
+    TIMEOUT_SECONDS: 5,
+    RETRIES: 3,
+    START_PERIOD_SECONDS: 120
+};
+/** Container stop timeout in seconds. ECS waits this long after SIGTERM
+ *  before sending SIGKILL. ClickHouse needs the longer-than-default window
+ *  (CDK default: 30s) to flush in-progress merges, finish writing parts,
+ *  and close the data directory cleanly — premature SIGKILL on a 1 vCPU
+ *  m7g.medium under merge load risks `max_suspicious_broken_parts` on the
+ *  next start. ECS upper bound is 120s. */
+export const CLICKHOUSE_STOP_TIMEOUT_SECONDS = 90;
+/** OPTIMIZE TABLE FINAL schedule.
+ *  RMT tables carry min_age_to_force_merge_seconds=600 so the engine already merges
+ *  old parts within 10 min; this task is a safety net for MVs (no engine-level setting)
+ *  and for ReplacingMergeTree dedup under skewed write patterns. 6 hours is sufficient. */
+export const OPTIMISE_FINAL_SCHEDULE = "rate(6 hours)";
+/** Tables requiring periodic OPTIMIZE FINAL (ReplacingMergeTree only).
+ *  Keep in sync with REPLACING_MERGE_TREE_TABLES in
+ *  webapp/app/.server/lib/clickhouse/tenantQuery/tableConstants.ts (auto-FINAL). */
+export const REPLACING_MERGE_TREE_TABLES = [
+    "application_metrics",
+    "cost_records",
+    "log_fingerprints",
+    "insights",
+    "asset_inventory"
+];
+/** Subdirectory on the EBS volume for server config files (must match CDK volume mount). */
+export const CLICKHOUSE_CONFIG_SUBDIR = "server-config.d";
+/** Subdirectory on the EBS volume for users config files (must match CDK volume mount). */
+export const CLICKHOUSE_USERS_SUBDIR = "server-users.d";
+/** Cloud Map service name (resolves to `clickhouse.<appName>.local` via the per-app namespace registered by `App.getInstance().registerService(...)`). */
+export const CLICKHOUSE_CLOUDMAP_SERVICE_NAME = "clickhouse";
+/** ECS container name for the ClickHouse server task. Threaded through both
+ *  the `addContainer` call site and the SSM reload script (which uses
+ *  `docker ps --filter "label=com.amazonaws.ecs.container-name=<name>"` to
+ *  locate the running container). Drift between the two sites turns the
+ *  live-reload path into a silent no-op without any compile/test signal,
+ *  so this lives as a single source of truth. */
+export const CLICKHOUSE_SERVER_CONTAINER_NAME = "clickhouse";
+/** Materialised views that benefit from periodic OPTIMIZE to reduce part count at read time.
+ *  These are not ReplacingMergeTree (no dedup needed) but un-merged parts force
+ *  read-time aggregation which degrades query performance. */
+export const OPTIMISE_MV_TABLES = [
+    "metrics_hourly_mv",
+    "metrics_daily_mv",
+    "response_time_quantiles_hourly_mv",
+    "deployment_duration_quantiles_daily_mv",
+    "log_severity_hourly_mv",
+    "compliance_score_daily_mv",
+    "ai_usage_daily_mv",
+    "finding_daily_aggregate",
+    "insight_pattern_dismissals"
+];
+/** Resource allocation for the lightweight optimise task. */
+export const OPTIMISE_TASK_MEMORY_MIB = 256;
+export const OPTIMISE_TASK_CPU_UNITS = 256;
+/** Automated backup schedule (daily 03:00 UTC — low-traffic window). */
+export const BACKUP_SCHEDULE = "cron(0 3 * * ? *)";
+/** Resource allocation for the backup task (lightweight — clickhouse-client only). */
+export const BACKUP_TASK_MEMORY_MIB = 256;
+export const BACKUP_TASK_CPU_UNITS = 256;
+/** Backup object expiration: 14 days (retains 14 daily snapshots). */
+export const BACKUP_RETENTION_DAYS = 14;

package/dist/lib/resources/aws/database/clickhouseSchemas.d.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+/**
+ * Schema-admin user — the framework's bootstrap-privileged identity that
+ * customer SQL runs as. Owns DDL, schema migrations, GRANTs. Rendered into
+ * `users.d/fjall.xml` with `<access_management>1</access_management>` so it
+ * can manage GRANT / CREATE USER from SQL.
+ *
+ * The `profile` field names a key in the construct's `profiles:` prop (or
+ * `ClickHouseDefaultProfiles` if omitted) and is bound directly in the XML
+ * `<user><profile>…</profile></user>` block — not via the migration helper.
+ */
+export declare const ClickHouseSchemaAdminSchema: z.ZodObject<{
+    name: z.ZodString;
+    profile: z.ZodString;
+}, z.core.$strict>;
+export type ClickHouseSchemaAdmin = z.infer<typeof ClickHouseSchemaAdminSchema>;
+/**
+ * Managed-password workload user name. The framework mints a secret, grants
+ * IAM read on it, and the migration helper issues `CREATE USER … IDENTIFIED
+ * WITH sha256_password …` at runtime. Profile binding is NOT performed by
+ * the framework — customer SQL applies `ALTER USER <name> SETTINGS PROFILE
+ * <profile>` alongside their GRANTs.
+ */
+export declare const ManagedPasswordNameSchema: z.ZodString;
+export type ManagedPasswordName = z.infer<typeof ManagedPasswordNameSchema>;
+/**
+ * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
+ * element names (snake_case at the wire; camelCase here for TS ergonomics).
+ * Every field is `.optional()` — a profile may declare any subset.
+ *
+ * `renderUsersXml` maps each present field to the snake_case XML element
+ * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
+ * typo at the consumer doesn't silently ship a no-op profile.
+ */
+export declare const ProfileSpecSchema: z.ZodObject<{
+    maxThreads: z.ZodOptional<z.ZodNumber>;
+    maxInsertThreads: z.ZodOptional<z.ZodNumber>;
+    maxConcurrentQueriesForUser: z.ZodOptional<z.ZodNumber>;
+    maxMemoryUsage: z.ZodOptional<z.ZodNumber>;
+    maxMemoryUsageForUser: z.ZodOptional<z.ZodNumber>;
+    maxExecutionTime: z.ZodOptional<z.ZodNumber>;
+    maxRowsToRead: z.ZodOptional<z.ZodNumber>;
+    maxBytesBeforeExternalSort: z.ZodOptional<z.ZodNumber>;
+    maxBytesBeforeExternalGroupBy: z.ZodOptional<z.ZodNumber>;
+    logQueriesMinQueryDurationMs: z.ZodOptional<z.ZodNumber>;
+    optimizeMoveToPrewhere: z.ZodOptional<z.ZodBoolean>;
+    useQueryConditionCache: z.ZodOptional<z.ZodBoolean>;
+    useSkipIndexesIfFinal: z.ZodOptional<z.ZodBoolean>;
+    applyRowPolicyAfterFinal: z.ZodOptional<z.ZodBoolean>;
+    applyPrewhereAfterFinal: z.ZodOptional<z.ZodBoolean>;
+    doNotMergeAcrossPartitionsSelectFinal: z.ZodOptional<z.ZodBoolean>;
+    asyncInsert: z.ZodOptional<z.ZodBoolean>;
+    waitForAsyncInsert: z.ZodOptional<z.ZodBoolean>;
+    asyncInsertMaxDataSize: z.ZodOptional<z.ZodNumber>;
+    asyncInsertBusyTimeoutMinMs: z.ZodOptional<z.ZodNumber>;
+    asyncInsertBusyTimeoutMaxMs: z.ZodOptional<z.ZodNumber>;
+    asyncInsertUseAdaptiveBusyTimeout: z.ZodOptional<z.ZodBoolean>;
+    asyncInsertDeduplicate: z.ZodOptional<z.ZodBoolean>;
+    inputFormatParallelParsing: z.ZodOptional<z.ZodBoolean>;
+    outputFormatParallelFormatting: z.ZodOptional<z.ZodBoolean>;
+    queryPlanOptimizeLazyMaterialization: z.ZodOptional<z.ZodBoolean>;
+    materializeTtlAfterModify: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ProfileSpec = z.infer<typeof ProfileSpecSchema>;
+/**
+ * Re-exported for the construct's Stage 1 validation. Profile keys MUST
+ * match the same lowercase snake_case shape as user names — they emit as
+ * XML element names with no escaping.
+ */
+export declare const PROFILE_NAME_PATTERN: RegExp;
+export declare const ClickHouseDefaultProfiles: Readonly<Record<string, Readonly<ProfileSpec>>>;

package/dist/lib/resources/aws/database/clickhouseSchemas.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+/** ClickHouse user/profile name pattern — lowercase snake_case, leading
+ *  letter only. Shared by `ClickHouseUserSchema.name` and the per-profile
+ *  key regex applied inside `ClickHouseDatabase`'s construct-time validation
+ *  (Stage 1). Keeps the XML element names emit-safe (no escaping needed). */
+const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+/**
+ * Schema-admin user — the framework's bootstrap-privileged identity that
+ * customer SQL runs as. Owns DDL, schema migrations, GRANTs. Rendered into
+ * `users.d/fjall.xml` with `<access_management>1</access_management>` so it
+ * can manage GRANT / CREATE USER from SQL.
+ *
+ * The `profile` field names a key in the construct's `profiles:` prop (or
+ * `ClickHouseDefaultProfiles` if omitted) and is bound directly in the XML
+ * `<user><profile>…</profile></user>` block — not via the migration helper.
+ */
+export const ClickHouseSchemaAdminSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(63)
+        .regex(NAME_PATTERN, "Must be lowercase snake_case"),
+    profile: z.string().min(1)
+})
+    .strict();
+/**
+ * Managed-password workload user name. The framework mints a secret, grants
+ * IAM read on it, and the migration helper issues `CREATE USER … IDENTIFIED
+ * WITH sha256_password …` at runtime. Profile binding is NOT performed by
+ * the framework — customer SQL applies `ALTER USER <name> SETTINGS PROFILE
+ * <profile>` alongside their GRANTs.
+ */
+export const ManagedPasswordNameSchema = z
+    .string()
+    .min(1)
+    .max(63)
+    .regex(NAME_PATTERN, "Must be lowercase snake_case");
+/**
+ * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
+ * element names (snake_case at the wire; camelCase here for TS ergonomics).
+ * Every field is `.optional()` — a profile may declare any subset.
+ *
+ * `renderUsersXml` maps each present field to the snake_case XML element
+ * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
+ * typo at the consumer doesn't silently ship a no-op profile.
+ */
+export const ProfileSpecSchema = z
+    .object({
+    maxThreads: z.number().int().positive().optional(),
+    maxInsertThreads: z.number().int().positive().optional(),
+    maxConcurrentQueriesForUser: z.number().int().positive().optional(),
+    maxMemoryUsage: z.number().int().positive().optional(),
+    maxMemoryUsageForUser: z.number().int().positive().optional(),
+    maxExecutionTime: z.number().int().positive().optional(),
+    maxRowsToRead: z.number().int().positive().optional(),
+    maxBytesBeforeExternalSort: z.number().int().positive().optional(),
+    maxBytesBeforeExternalGroupBy: z.number().int().positive().optional(),
+    logQueriesMinQueryDurationMs: z.number().int().nonnegative().optional(),
+    optimizeMoveToPrewhere: z.boolean().optional(),
+    useQueryConditionCache: z.boolean().optional(),
+    useSkipIndexesIfFinal: z.boolean().optional(),
+    applyRowPolicyAfterFinal: z.boolean().optional(),
+    applyPrewhereAfterFinal: z.boolean().optional(),
+    doNotMergeAcrossPartitionsSelectFinal: z.boolean().optional(),
+    asyncInsert: z.boolean().optional(),
+    waitForAsyncInsert: z.boolean().optional(),
+    asyncInsertMaxDataSize: z.number().int().positive().optional(),
+    asyncInsertBusyTimeoutMinMs: z.number().int().nonnegative().optional(),
+    asyncInsertBusyTimeoutMaxMs: z.number().int().nonnegative().optional(),
+    asyncInsertUseAdaptiveBusyTimeout: z.boolean().optional(),
+    asyncInsertDeduplicate: z.boolean().optional(),
+    inputFormatParallelParsing: z.boolean().optional(),
+    outputFormatParallelFormatting: z.boolean().optional(),
+    queryPlanOptimizeLazyMaterialization: z.boolean().optional(),
+    materializeTtlAfterModify: z.boolean().optional()
+})
+    .strict();
+/**
+ * Re-exported for the construct's Stage 1 validation. Profile keys MUST
+ * match the same lowercase snake_case shape as user names — they emit as
+ * XML element names with no escaping.
+ */
+export const PROFILE_NAME_PATTERN = NAME_PATTERN;
+/**
+ * Four workload-class default profiles. Cap values lifted byte-for-byte
+ * from the pre-Phase-4b inline `<app_writer>` / `<audit_writer>` /
+ * `<backup_reader>` / `<schema_admin>` blocks at
+ * `clickhouseUserData.ts:296-382` — zero behavioural drift from the
+ * pre-4b prod resource caps.
+ *
+ * Frozen via `Object.freeze` on the outer record AND each sub-object so
+ * a consumer cannot mutate the defaults in place. Pass your own
+ * `profiles:` map to the construct to extend / override; never mutate
+ * this constant.
+ */
+const _ClickHouseDefaultProfilesRaw = {
+    high_throughput_ingest: {
+        maxThreads: 1,
+        maxInsertThreads: 1,
+        maxConcurrentQueriesForUser: 2,
+        logQueriesMinQueryDurationMs: 100,
+        optimizeMoveToPrewhere: true,
+        useQueryConditionCache: true,
+        useSkipIndexesIfFinal: true,
+        applyRowPolicyAfterFinal: true,
+        applyPrewhereAfterFinal: true,
+        doNotMergeAcrossPartitionsSelectFinal: true,
+        asyncInsert: true,
+        waitForAsyncInsert: true,
+        asyncInsertMaxDataSize: 10000000,
+        asyncInsertBusyTimeoutMinMs: 50,
+        asyncInsertBusyTimeoutMaxMs: 2000,
+        asyncInsertUseAdaptiveBusyTimeout: true,
+        asyncInsertDeduplicate: true,
+        inputFormatParallelParsing: false,
+        outputFormatParallelFormatting: false,
+        queryPlanOptimizeLazyMaterialization: true,
+        maxMemoryUsage: 1610612736,
+        maxMemoryUsageForUser: 2147483648,
+        maxBytesBeforeExternalSort: 536870912,
+        maxBytesBeforeExternalGroupBy: 536870912,
+        maxExecutionTime: 30,
+        maxRowsToRead: 10000000
+    },
+    audit_append: {
+        maxThreads: 1,
+        maxInsertThreads: 1,
+        maxConcurrentQueriesForUser: 2,
+        maxMemoryUsage: 500000000,
+        maxExecutionTime: 10,
+        asyncInsert: true,
+        waitForAsyncInsert: true
+    },
+    read_only: {
+        maxThreads: 1,
+        maxConcurrentQueriesForUser: 1,
+        maxMemoryUsage: 1000000000,
+        maxExecutionTime: 3600
+    },
+    ddl_admin: {
+        maxThreads: 1,
+        maxConcurrentQueriesForUser: 1,
+        maxMemoryUsage: 1000000000,
+        maxExecutionTime: 1800
+    }
+};
+export const ClickHouseDefaultProfiles = Object.freeze({
+    high_throughput_ingest: Object.freeze({
+        ..._ClickHouseDefaultProfilesRaw.high_throughput_ingest
+    }),
+    audit_append: Object.freeze({
+        ..._ClickHouseDefaultProfilesRaw.audit_append
+    }),
+    read_only: Object.freeze({ ..._ClickHouseDefaultProfilesRaw.read_only }),
+    ddl_admin: Object.freeze({ ..._ClickHouseDefaultProfilesRaw.ddl_admin })
+});

package/dist/lib/resources/aws/database/clickhouseSecurityGroup.d.ts

@@ -0,0 +1,14 @@
+import { type IVpc } from "aws-cdk-lib/aws-ec2";
+import type { Construct } from "constructs";
+import { SecurityGroup } from "../networking/securityGroup.js";
+/**
+ * Create the ClickHouse security group.
+ *
+ * No consumer ingress rules are added here — consumer ingress flows through
+ * the connector contract (`ISecurityGroupConnector` + `additionalTcpPorts`)
+ * so the SG is consumer-agnostic and reusable across compute consumers.
+ *
+ * Self-referencing native-port ingress is kept so the optimise/backup
+ * scheduled tasks (which share this SG) can reach the ClickHouse server.
+ */
+export declare function createClickHouseSecurityGroup(scope: Construct, vpc: IVpc, nativePort: number): SecurityGroup;

package/dist/lib/resources/aws/database/clickhouseSecurityGroup.js

@@ -0,0 +1,23 @@
+import { Peer, Port } from "aws-cdk-lib/aws-ec2";
+import { SecurityGroup } from "../networking/securityGroup.js";
+/**
+ * Create the ClickHouse security group.
+ *
+ * No consumer ingress rules are added here — consumer ingress flows through
+ * the connector contract (`ISecurityGroupConnector` + `additionalTcpPorts`)
+ * so the SG is consumer-agnostic and reusable across compute consumers.
+ *
+ * Self-referencing native-port ingress is kept so the optimise/backup
+ * scheduled tasks (which share this SG) can reach the ClickHouse server.
+ */
+export function createClickHouseSecurityGroup(scope, vpc, nativePort) {
+    const sg = new SecurityGroup(scope, "ClickHouseSecurityGroup", {
+        vpc,
+        description: "Security group for ClickHouse analytics instance",
+        allowAllOutbound: false
+    });
+    sg.addIngressRule(sg, Port.tcp(nativePort), "ClickHouse native protocol from sidecar tasks (self-referencing)");
+    sg.addEgressRule(Peer.anyIpv4(), Port.tcp(443), "HTTPS to AWS service endpoints (S3, Secrets Manager, IMDS)");
+    sg.addEgressRule(sg, Port.tcp(nativePort), "ClickHouse native protocol for sidecar tasks");
+    return sg;
+}

package/dist/lib/resources/aws/database/clickhouseUserData.d.ts

@@ -0,0 +1,69 @@
+import type { ClickHouseSchemaAdmin, ProfileSpec } from "./clickhouseSchemas.js";
+/**
+ * Options for {@link buildClickHouseUserData}.
+ *
+ * Per design D27 + D12: Cloudflare R2 is dropped; cold storage targets S3
+ * with IAM-only auth via `<use_environment_credentials>true</use_environment_credentials>`.
+ * Zero env-var access keys are injected into the rendered config.
+ */
+export interface BuildClickHouseUserDataOptions {
+    /** S3 bucket name for `BACKUP DATABASE TO S3`; pre-authenticated via IAM. */
+    backupBucketName: string;
+    /** AWS region of the backup bucket. */
+    backupBucketRegion: string;
+    /**
+     * Optional S3 cold-tier configuration.
+     * When omitted, single-tier hot storage on the EC2 EBS volume is used.
+     */
+    coldTier?: {
+        bucketName: string;
+        region: string;
+    };
+}
+export declare function generateServerConfigXml(options: BuildClickHouseUserDataOptions): string;
+export interface GenerateUsersConfigXmlOptions {
+    schemaAdmin: ClickHouseSchemaAdmin;
+    profiles: Record<string, ProfileSpec>;
+    vpcCidr: string;
+}
+/**
+ * Construct-side thin wrapper around `renderUsersXml`. Always emits the
+ * prod shape: loopback-only `<default>` user, `from_env=` sha256 password
+ * directives. The container entrypoint wrapper (see
+ * `buildClickHouseEntrypointWrapper`) resolves the `USER_<NAME>_SHA256` env
+ * vars at server start from `sha256sum` of each ECS-injected plaintext.
+ *
+ * TODO secondary CIDRs: props.vpc.vpcCidrBlock returns only the primary CIDR.
+ * BYOC consumers with multi-CIDR VPCs need a per-CIDR `<ip>` emitter — see
+ * designs/2026-05-12-clickhouse-construct-leak-fixes.md § "Phase 1.5".
+ */
+export declare function generateUsersConfigXml(options: GenerateUsersConfigXmlOptions): string;
+/**
+ * Build the EC2 user-data script that bootstraps ClickHouse on the ASG instance.
+ *
+ * Per design D27 + D12: cold-storage and backups authenticate to S3 via IAM
+ * (the EC2 instance role's grants), not via env-var access keys. The rendered
+ * output contains zero `R2_*` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
+ * references — `<use_environment_credentials>true</use_environment_credentials>`
+ * tells ClickHouse to use the IMDS-derived credentials instead.
+ */
+export declare function buildClickHouseUserData(options: BuildClickHouseUserDataOptions): string;
+/**
+ * Build the bash wrapper executed as the CH container's entrypoint.
+ *
+ * The CH server reads `users.d/fjall.xml`, which carries
+ * `<password_sha256_hex from_env="USER_<NAME>_SHA256"/>` directives, and
+ * resolves those `from_env=` lookups against the server process's
+ * environment at startup. ECS injects the plaintext password for each user
+ * as `USER_<NAME>_PASSWORD` via `secretsImport`; this wrapper derives the
+ * matching `USER_<NAME>_SHA256` env var (via the same SHA-256 pipeline as
+ * the EC2 user-data loop in `buildClickHouseUserData()`) and then `exec`s
+ * the stock CH entrypoint so the server inherits the derived vars after
+ * the gosu privilege drop.
+ *
+ * Pure-bash iteration via `${!USER_@}` avoids spawning `env`/`grep` and
+ * guarantees only ECS-injected secrets are considered. The `case` filter
+ * skips any future `USER_*_HOST`/`USER_*_PORT` envs that don't match the
+ * password convention.
+ */
+export declare function buildClickHouseEntrypointWrapper(): string;