@fjall/components-infrastructure 0.102.0 → 1.1.0

package/dist/lib/lambda-assets/cert-generator/asset/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "private": true
+}

package/dist/lib/patterns/aws/clickhouseDatabase.d.ts

@@ -4,6 +4,8 @@ import { type IBucket } from "aws-cdk-lib/aws-s3";
 import { Construct } from "constructs";
 import { Secret } from "../../resources/aws/secrets/secret.js";
 import { type ClickHouseSchemaAdmin, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
+import { type ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import type { ClickHouseTlsOptions } from "./clickhouseTls/index.js";
 import { type ClickHouseMigrationsConfig, type IClickHouseDatabase } from "./interfaces/database.js";
 import { type ISecurityGroupConnector } from "./interfaces/connector.js";
 import { type MigrationContributions } from "./interfaces/migrationContributor.js";
@@ -104,6 +106,15 @@ export interface ClickHouseDatabaseProps {
      * records in `_schema_migrations.ch_version`.
      */
     migrations?: ClickHouseMigrationsConfig;
+    /**
+     * TLS configuration. Default: `{ mode: "self-signed" }` — mints an ECDSA
+     * P-256 CA + leaf cert at deploy via a Lambda custom resource, stores both
+     * PEMs in Secrets Manager, and the EC2 user-data materialises them at boot
+     * for the CH server to read. Set `mode: "imported"` to bring your own CA;
+     * `mode: "none"` (acknowledgement literal required) opts out of TLS.
+     * See ./clickhouseTls/types.ts.
+     */
+    tls?: ClickHouseTlsOptions;
 }
 /**
  * ClickHouse analytics database wrapper implementing IClickHouseDatabase.
@@ -121,6 +132,25 @@ export declare class ClickHouseDatabase extends Construct implements IClickHouse
     readonly additionalTcpPorts: number[];
     readonly id: string;
     readonly connections: Connections;
+    /**
+     * CA cert secret. Self-signed: minted by `TlsCertGenerator`. Imported: the
+     * user-supplied ISecret. `undefined` when `tls.mode === "none"`.
+     * SecretString shape: raw PEM (single cert, no JSON wrapping).
+     */
+    readonly tlsCaSecret: ISecret | undefined;
+    /**
+     * Server cert + key secret. Self-signed: minted by `TlsCertGenerator`.
+     * Imported: the user-supplied ISecret. `undefined` when `tls.mode === "none"`.
+     * SecretString shape: JSON `{ "cert": "<leaf-pem>", "key": "<key-pem>" }`.
+     */
+    readonly tlsServerSecret: ISecret | undefined;
+    /**
+     * SHA-256 of the CA cert PEM. CFN token in self-signed mode (from the cert
+     * generator custom resource Data attribute). Plain string in imported mode
+     * when supplied. `undefined` when `tls.mode === "none"` or when imported
+     * without a digest. Surface on consumers as a task-replacement trigger.
+     */
+    readonly caCertSha256: string | undefined;
     constructor(scope: Construct, id: string, props: ClickHouseDatabaseProps);
     /**
      * Returns the Fjall `Secret` wrapper for the named user. Throws with a
@@ -138,6 +168,13 @@ export declare class ClickHouseDatabase extends Construct implements IClickHouse
     getHttpPort(): number;
     getNativePort(): number;
     getHostEndpoint(): string;
+    /**
+     * Canonical URL for the HTTP(S) interface. Scheme is `https` when TLS is
+     * active (default), `http` only when `tls: { mode: "none", … }` is set.
+     * Port matches: HTTPS (8443) under TLS, HTTP (8123) otherwise.
+     */
+    getUrl(): string;
+    /** @deprecated Alias for {@link getUrl}. Removed in a follow-up landing. */
     getHttpUrl(): string;
     getNativeUrl(): string;
     getDatabaseName(): string;

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -20,7 +20,8 @@ import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUser
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, ClickHouseDefaultProfiles, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
 import { inferAmiHardwareType } from "../../resources/aws/compute/ecsConstants.js";
-import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_TASK_MEMORY_MIB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
+import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_TASK_MEMORY_MIB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
+import { TlsCertGenerator } from "../../resources/aws/utilities/tlsCertGenerator.js";
 import { EcsCompute } from "./computeEcs.js";
 /**
  * Resolve the ECS desired task count for the ClickHouse service.
@@ -81,9 +82,30 @@ function createClickHouseUserSecret(scope, name) {
 export class ClickHouseDatabase extends Construct {
     databaseType = "ClickHouse";
     connectorType = "relational";
-    additionalTcpPorts = [CLICKHOUSE_NATIVE_PORT];
+    additionalTcpPorts;
     id;
     connections;
+    /**
+     * CA cert secret. Self-signed: minted by `TlsCertGenerator`. Imported: the
+     * user-supplied ISecret. `undefined` when `tls.mode === "none"`.
+     * SecretString shape: raw PEM (single cert, no JSON wrapping).
+     */
+    tlsCaSecret;
+    /**
+     * Server cert + key secret. Self-signed: minted by `TlsCertGenerator`.
+     * Imported: the user-supplied ISecret. `undefined` when `tls.mode === "none"`.
+     * SecretString shape: JSON `{ "cert": "<leaf-pem>", "key": "<key-pem>" }`.
+     */
+    tlsServerSecret;
+    /**
+     * SHA-256 of the CA cert PEM. CFN token in self-signed mode (from the cert
+     * generator custom resource Data attribute). Plain string in imported mode
+     * when supplied. `undefined` when `tls.mode === "none"` or when imported
+     * without a digest. Surface on consumers as a task-replacement trigger.
+     */
+    caCertSha256;
+    #httpPort;
+    #nativePort;
     #users;
     #schemaAdmin;
     #managedPasswordNames;
@@ -157,7 +179,46 @@ export class ClickHouseDatabase extends Construct {
             (props.backupRetentionDays < 1 || props.backupRetentionDays > 3650)) {
             throw new Error(`ClickHouseDatabase: backupRetentionDays must be between 1 and 3650; got ${props.backupRetentionDays}.`);
         }
-        const securityGroup = createClickHouseSecurityGroup(this, vpc, CLICKHOUSE_NATIVE_PORT);
+        const tlsOptions = props.tls ?? {
+            mode: "self-signed"
+        };
+        const tlsActive = tlsOptions.mode !== "none";
+        const httpPort = tlsActive ? CLICKHOUSE_HTTPS_PORT : CLICKHOUSE_HTTP_PORT;
+        const nativePort = tlsActive
+            ? CLICKHOUSE_TCP_SECURE_PORT
+            : CLICKHOUSE_NATIVE_PORT;
+        let tlsCaSecret;
+        let tlsServerSecret;
+        let caCertSha256;
+        if (tlsOptions.mode === "self-signed") {
+            const namespaceName = App.getInstance().getNamespace().namespaceName;
+            const hostname = `${CLICKHOUSE_CLOUDMAP_SERVICE_NAME}.${namespaceName}`;
+            const certGen = new TlsCertGenerator(this, "TlsCertGenerator", {
+                appName: App.getInstance().getName(),
+                hostname,
+                ...(tlsOptions.caValidityYears !== undefined && {
+                    caValidityYears: tlsOptions.caValidityYears
+                }),
+                ...(tlsOptions.leafValidityYears !== undefined && {
+                    leafValidityYears: tlsOptions.leafValidityYears
+                })
+            });
+            tlsCaSecret = certGen.caSecret.secret;
+            tlsServerSecret = certGen.serverSecret.secret;
+            caCertSha256 = certGen.caCertSha256;
+        }
+        else if (tlsOptions.mode === "imported") {
+            tlsCaSecret = tlsOptions.caCertSecret;
+            tlsServerSecret = tlsOptions.serverCertSecret;
+            caCertSha256 = tlsOptions.caCertSha256;
+        }
+        this.tlsCaSecret = tlsCaSecret;
+        this.tlsServerSecret = tlsServerSecret;
+        this.caCertSha256 = caCertSha256;
+        this.additionalTcpPorts = [nativePort];
+        this.#httpPort = httpPort;
+        this.#nativePort = nativePort;
+        const securityGroup = createClickHouseSecurityGroup(this, vpc, nativePort);
         const userSecrets = new Map();
         for (const name of allUserNames) {
             userSecrets.set(name, createClickHouseUserSecret(this, name));
@@ -200,6 +261,13 @@ export class ClickHouseDatabase extends Construct {
                     bucketName: coldTierBucket.bucketName,
                     region: Stack.of(this).region
                 }
+            }),
+            tlsActive,
+            ...(tlsActive &&
+                tlsCaSecret !== undefined &&
+                tlsServerSecret !== undefined && {
+                caSecretArn: tlsCaSecret.secretArn,
+                serverSecretArn: tlsServerSecret.secretArn
             })
         }));
         // Source.data wraps the content in a zip; the default `extract: true`
@@ -239,9 +307,10 @@ export class ClickHouseDatabase extends Construct {
                     "--host",
                     clickHouseHost,
                     "--port",
-                    String(CLICKHOUSE_NATIVE_PORT),
+                    String(nativePort),
                     "--user",
                     schemaAdmin.name,
+                    ...(tlsActive ? ["--secure", "--accept-invalid-certificate"] : []),
                     "--query",
                     `${optimiseQuery};`
                 ],
@@ -263,7 +332,7 @@ export class ClickHouseDatabase extends Construct {
                     "sh",
                     "-c",
                     // Password via CLICKHOUSE_PASSWORD env, not --password on argv (argv → /proc/<pid>/cmdline).
-                    `STAMP=$(date +%Y%m%d-%H%M%S) && clickhouse-client --host ${clickHouseHost} --port ${CLICKHOUSE_NATIVE_PORT} --user ${schemaAdmin.name} --query "BACKUP DATABASE ${CLICKHOUSE_DATABASE_NAME} TO S3('${backupDestUrl}weekly-$STAMP/')"`
+                    `STAMP=$(date +%Y%m%d-%H%M%S) && clickhouse-client --host ${clickHouseHost} --port ${nativePort} --user ${schemaAdmin.name}${tlsActive ? " --secure --accept-invalid-certificate" : ""} --query "BACKUP DATABASE ${CLICKHOUSE_DATABASE_NAME} TO S3('${backupDestUrl}weekly-$STAMP/')"`
                 ],
                 secrets: {
                     CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(adminSecret.secret, "password")
@@ -331,12 +400,12 @@ export class ClickHouseDatabase extends Construct {
                             secretsImport: clickHouseContainerSecrets,
                             portMappings: [
                                 {
-                                    containerPort: CLICKHOUSE_HTTP_PORT,
-                                    hostPort: CLICKHOUSE_HTTP_PORT
+                                    containerPort: httpPort,
+                                    hostPort: httpPort
                                 },
                                 {
-                                    containerPort: CLICKHOUSE_NATIVE_PORT,
-                                    hostPort: CLICKHOUSE_NATIVE_PORT
+                                    containerPort: nativePort,
+                                    hostPort: nativePort
                                 },
                                 {
                                     containerPort: CLICKHOUSE_PROMETHEUS_PORT,
@@ -360,12 +429,24 @@ export class ClickHouseDatabase extends Construct {
                                     hostSourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/${CLICKHOUSE_USERS_SUBDIR}`,
                                     mountPath: "/etc/clickhouse-server/users.d",
                                     readOnly: true
-                                }
+                                },
+                                ...(tlsActive
+                                    ? [
+                                        {
+                                            name: "clickhouse-certs",
+                                            hostSourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/server-certs`,
+                                            mountPath: CLICKHOUSE_TLS_CERT_MOUNT_PATH,
+                                            readOnly: true
+                                        }
+                                    ]
+                                    : [])
                             ],
                             healthCheck: {
                                 command: [
                                     "CMD-SHELL",
-                                    `wget -q -O /dev/null http://127.0.0.1:${CLICKHOUSE_HTTP_PORT}/ping || exit 1`
+                                    tlsActive
+                                        ? `wget -q --no-check-certificate -O /dev/null https://127.0.0.1:${httpPort}/ping || exit 1`
+                                        : `wget -q -O /dev/null http://127.0.0.1:${httpPort}/ping || exit 1`
                                 ],
                                 interval: CLICKHOUSE_HEALTH_CHECK.INTERVAL_SECONDS,
                                 timeout: CLICKHOUSE_HEALTH_CHECK.TIMEOUT_SECONDS,
@@ -390,6 +471,10 @@ export class ClickHouseDatabase extends Construct {
         instanceRole.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("AmazonSSMManagedInstanceCore"));
         backupBucket.grantRead(instanceRole, "config/*");
         adminSecret.secret.grantRead(instanceRole);
+        if (tlsCaSecret !== undefined)
+            tlsCaSecret.grantRead(instanceRole);
+        if (tlsServerSecret !== undefined)
+            tlsServerSecret.grantRead(instanceRole);
         const adminSecretName = clickHouseUserSecretName(schemaAdmin.name);
         // Password via CLICKHOUSE_CLIENT_PASSWORD env, not --password on argv
         // (argv → /proc/<pid>/cmdline). `jq -r .password` on an empty pipeline
@@ -404,7 +489,7 @@ export class ClickHouseDatabase extends Construct {
             `ADMIN_PASSWORD=$(aws secretsmanager get-secret-value --secret-id "${adminSecretName}" --query SecretString --output text | jq -r .password)`,
             `if [ -z "$ADMIN_PASSWORD" ] || [ "$ADMIN_PASSWORD" = "null" ]; then echo "fjall:reload:status=failed reason=password-fetch" >&2; exit 1; fi`,
             `mv /var/lib/clickhouse/users.d/fjall.xml.new /var/lib/clickhouse/users.d/fjall.xml`,
-            `docker exec -i -e CLICKHOUSE_CLIENT_PASSWORD="$ADMIN_PASSWORD" "$CONTAINER" clickhouse-client --port 9000 --user ${schemaAdmin.name} -q "SYSTEM RELOAD USERS"`
+            `docker exec -i -e CLICKHOUSE_CLIENT_PASSWORD="$ADMIN_PASSWORD" "$CONTAINER" clickhouse-client${tlsActive ? " --secure --accept-invalid-certificate" : ""} --port ${nativePort} --user ${schemaAdmin.name} -q "SYSTEM RELOAD USERS"`
         ].join("\n");
         const region = Stack.of(this).region;
         const account = Stack.of(this).account;
@@ -456,15 +541,21 @@ export class ClickHouseDatabase extends Construct {
         reloadCustomResource.node.addDependency(usersConfigDeployment);
         this.connections = new Connections({
             securityGroups: [securityGroup],
-            defaultPort: Port.tcp(CLICKHOUSE_HTTP_PORT)
+            defaultPort: Port.tcp(httpPort)
         });
         const declareOutput = (name, value) => {
             const output = new CfnOutput(this, name, { value });
             output.overrideLogicalId(name);
         };
         declareOutput("Endpoint", clickHouseHost);
-        declareOutput("HttpPort", String(CLICKHOUSE_HTTP_PORT));
-        declareOutput("NativePort", String(CLICKHOUSE_NATIVE_PORT));
+        declareOutput("HttpPort", String(httpPort));
+        declareOutput("NativePort", String(nativePort));
+        if (tlsActive) {
+            declareOutput("TlsActive", "true");
+        }
+        if (caCertSha256 !== undefined) {
+            declareOutput("CaCertSha256", caCertSha256);
+        }
         declareOutput("DatabaseName", CLICKHOUSE_DATABASE_NAME);
         for (const [name, secret] of userSecrets) {
             declareOutput(`${toPascalCase(name)}SecretArn`, secret.secret.secretArn);
@@ -497,19 +588,29 @@ export class ClickHouseDatabase extends Construct {
         return this.#users.get(name);
     }
     getHttpPort() {
-        return CLICKHOUSE_HTTP_PORT;
+        return this.#httpPort;
     }
     getNativePort() {
-        return CLICKHOUSE_NATIVE_PORT;
+        return this.#nativePort;
     }
     getHostEndpoint() {
         return `${CLICKHOUSE_CLOUDMAP_SERVICE_NAME}.${App.getInstance().getNamespace().namespaceName}`;
     }
+    /**
+     * Canonical URL for the HTTP(S) interface. Scheme is `https` when TLS is
+     * active (default), `http` only when `tls: { mode: "none", … }` is set.
+     * Port matches: HTTPS (8443) under TLS, HTTP (8123) otherwise.
+     */
+    getUrl() {
+        const scheme = this.tlsCaSecret !== undefined ? "https" : "http";
+        return `${scheme}://${this.getHostEndpoint()}:${this.#httpPort}`;
+    }
+    /** @deprecated Alias for {@link getUrl}. Removed in a follow-up landing. */
     getHttpUrl() {
-        return `http://${this.getHostEndpoint()}:${this.getHttpPort()}`;
+        return this.getUrl();
     }
     getNativeUrl() {
-        return `tcp://${this.getHostEndpoint()}:${this.getNativePort()}`;
+        return `tcp://${this.getHostEndpoint()}:${this.#nativePort}`;
     }
     getDatabaseName() {
         return CLICKHOUSE_DATABASE_NAME;

package/dist/lib/patterns/aws/clickhouseTls/index.d.ts

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/lib/patterns/aws/clickhouseTls/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/lib/patterns/aws/clickhouseTls/types.d.ts

@@ -0,0 +1,48 @@
+import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
+/**
+ * Self-signed mode (default). The construct mints an ECDSA P-256 CA + leaf
+ * cert at stack deploy via a custom-resource Lambda. Bumping
+ * `caValidityYears` / `leafValidityYears` triggers re-issuance on the next
+ * deploy.
+ */
+export interface ClickHouseSelfSignedTls {
+    readonly mode: "self-signed";
+    readonly caValidityYears?: number;
+    readonly leafValidityYears?: number;
+}
+/**
+ * Imported mode. Caller owns the CA + server-cert secrets in Secrets
+ * Manager. `serverCertSecret`'s SecretString MUST be JSON of the shape
+ * `{ "cert": "<pem>", "key": "<pem>" }`. `caCertSha256` is optional — when
+ * supplied the construct surfaces it as a CFN env-var token so consumers
+ * can wire it into containers for rotation-triggers-task-replacement
+ * parity with self-signed mode. Omit it and rotation requires manual task
+ * restart (documented in `aiDocs/patterns/clickhouse-tls-pattern.md § "Imported mode"`).
+ */
+export interface ClickHouseImportedTls {
+    readonly mode: "imported";
+    readonly caCertSecret: ISecret;
+    readonly serverCertSecret: ISecret;
+    readonly caCertSha256?: string;
+}
+/**
+ * Plaintext escape hatch. Disables TLS entirely. The acknowledgement is a
+ * literal-string type so misuse fails at compile time — passing any other
+ * string fails `tsc --noEmit`.
+ */
+export interface ClickHouseNoTls {
+    readonly mode: "none";
+    readonly acknowledgement: "I understand plaintext-only ClickHouse fails SOC2 DP5";
+}
+export type ClickHouseTlsOptions = ClickHouseSelfSignedTls | ClickHouseImportedTls | ClickHouseNoTls;
+/**
+ * The resolved TLS surface a `ClickHouseDatabase` carries after dispatch.
+ * Every field is `undefined` in `mode: "none"`. `certGeneratorFunction`
+ * is `undefined` in `mode: "imported"`. `caCertSha256` is `undefined` in
+ * `mode: "none"` AND in `mode: "imported"` unless the caller supplied it.
+ */
+export interface ClickHouseTlsResolved {
+    readonly caSecret: ISecret | undefined;
+    readonly serverSecret: ISecret | undefined;
+    readonly caCertSha256: string | undefined;
+}

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

@@ -53,6 +53,27 @@ export declare const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
 export declare const CLICKHOUSE_HTTP_PORT = 8123;
 export declare const CLICKHOUSE_NATIVE_PORT = 9000;
 export declare const CLICKHOUSE_PROMETHEUS_PORT = 9363;
+/** TLS-mode ClickHouse ports.
+ *  HTTPS replaces 8123; secure native protocol replaces 9000.
+ *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+export declare const CLICKHOUSE_HTTPS_PORT = 8443;
+export declare const CLICKHOUSE_TCP_SECURE_PORT = 9440;
+/** Mount path inside the main ClickHouse container for the materialised
+ *  TLS cert + key. The init container writes to a shared task-scoped volume
+ *  mounted here read-only on the main container. */
+export declare const CLICKHOUSE_TLS_CERT_MOUNT_PATH = "/etc/clickhouse-server/certs";
+/** Task-scoped Docker volume name shared between the TLS init container
+ *  (writer) and the main ClickHouse container (reader). */
+export declare const CLICKHOUSE_TLS_CERT_VOLUME_NAME = "tls-certs";
+/** UID:GID the official ClickHouse image runs as. Init container `chown`s
+ *  the materialised cert files to this UID so the server can read them. */
+export declare const CLICKHOUSE_UID = 101;
+/** Digest-pinned alpine image used by the TLS init container. The init
+ *  container needs `jq` (extracts `cert`+`key` from the server-cert JSON
+ *  secret); alpine ships it via `apk add` — but pinning the digest avoids
+ *  fetching `:latest` on every deploy. Bump in lockstep with renovate
+ *  alerts; CI verifies the digest resolves. */
+export declare const ALPINE_INIT_CONTAINER_IMAGE = "public.ecr.aws/docker/library/alpine:3.20@sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367effd16dc0d06d";
 /** EBS device name for the data volume (must match user data script). */
 export declare const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
 /** EBS mount path on the EC2 host. */

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

@@ -53,6 +53,27 @@ export const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
 export const CLICKHOUSE_HTTP_PORT = 8123;
 export const CLICKHOUSE_NATIVE_PORT = 9000;
 export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
+/** TLS-mode ClickHouse ports.
+ *  HTTPS replaces 8123; secure native protocol replaces 9000.
+ *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+export const CLICKHOUSE_HTTPS_PORT = 8443;
+export const CLICKHOUSE_TCP_SECURE_PORT = 9440;
+/** Mount path inside the main ClickHouse container for the materialised
+ *  TLS cert + key. The init container writes to a shared task-scoped volume
+ *  mounted here read-only on the main container. */
+export const CLICKHOUSE_TLS_CERT_MOUNT_PATH = "/etc/clickhouse-server/certs";
+/** Task-scoped Docker volume name shared between the TLS init container
+ *  (writer) and the main ClickHouse container (reader). */
+export const CLICKHOUSE_TLS_CERT_VOLUME_NAME = "tls-certs";
+/** UID:GID the official ClickHouse image runs as. Init container `chown`s
+ *  the materialised cert files to this UID so the server can read them. */
+export const CLICKHOUSE_UID = 101;
+/** Digest-pinned alpine image used by the TLS init container. The init
+ *  container needs `jq` (extracts `cert`+`key` from the server-cert JSON
+ *  secret); alpine ships it via `apk add` — but pinning the digest avoids
+ *  fetching `:latest` on every deploy. Bump in lockstep with renovate
+ *  alerts; CI verifies the digest resolves. */
+export const ALPINE_INIT_CONTAINER_IMAGE = "public.ecr.aws/docker/library/alpine:3.20@sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367effd16dc0d06d";
 /** 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. */

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

@@ -10,5 +10,7 @@ import { SecurityGroup } from "../networking/securityGroup.js";
  *
  * Self-referencing native-port ingress is kept so the optimise/backup
  * scheduled tasks (which share this SG) can reach the ClickHouse server.
+ * Under TLS modes, the secure native port (9440) is the self-referencing
+ * port; under `mode: "none"` the plaintext native port stays.
  */
 export declare function createClickHouseSecurityGroup(scope: Construct, vpc: IVpc, nativePort: number): SecurityGroup;

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

@@ -9,6 +9,8 @@ import { SecurityGroup } from "../networking/securityGroup.js";
  *
  * Self-referencing native-port ingress is kept so the optimise/backup
  * scheduled tasks (which share this SG) can reach the ClickHouse server.
+ * Under TLS modes, the secure native port (9440) is the self-referencing
+ * port; under `mode: "none"` the plaintext native port stays.
  */
 export function createClickHouseSecurityGroup(scope, vpc, nativePort) {
     const sg = new SecurityGroup(scope, "ClickHouseSecurityGroup", {

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

@@ -19,6 +19,27 @@ export interface BuildClickHouseUserDataOptions {
         bucketName: string;
         region: string;
     };
+    /**
+     * When true, the server config emits `<https_port>`, `<tcp_port_secure>`,
+     * and an `<openSSL><server>` block referencing the cert files materialised
+     * at `CLICKHOUSE_TLS_CERT_MOUNT_PATH` by the user-data bootstrap step.
+     * Plaintext `<http_port>` is omitted to avoid mixed-protocol exposure.
+     * Default: false. When true, `caSecretArn` and `serverSecretArn` MUST be
+     * supplied so the bootstrap step can materialise the cert PEMs.
+     */
+    tlsActive?: boolean;
+    /**
+     * Secrets Manager ARN holding the CA cert as raw PEM. Required when
+     * `tlsActive` is true. Fetched at instance boot via the EC2 instance role
+     * and written to `${dataMount}/server-certs/ca.crt`.
+     */
+    caSecretArn?: string;
+    /**
+     * Secrets Manager ARN holding the server cert + key as JSON
+     * `{ "cert": "<pem>", "key": "<pem>" }`. Required when `tlsActive` is true.
+     * Fetched at instance boot and written to `${dataMount}/server-certs/server.{crt,key}`.
+     */
+    serverSecretArn?: string;
 }
 export declare function generateServerConfigXml(options: BuildClickHouseUserDataOptions): string;
 export interface GenerateUsersConfigXmlOptions {

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

@@ -1,7 +1,8 @@
-import { CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_PROMETHEUS_PORT, clickHousePasswordSha256Snippet } from "./clickhouseConstants.js";
+import { CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, clickHousePasswordSha256Snippet } from "./clickhouseConstants.js";
 import { renderUsersXml } from "./clickhouseXmlRenderer.js";
 export function generateServerConfigXml(options) {
     const { backupBucketName, backupBucketRegion, coldTier } = options;
+    const tlsActive = options.tlsActive ?? false;
     const storageBlock = coldTier !== undefined
         ? `    <storage_configuration>
         <!-- Same CH 26 rule as the no-cold-tier branch: a <local_ssd> disk
@@ -145,7 +146,19 @@ export function generateServerConfigXml(options) {
         <number_of_free_entries_in_pool_to_lower_max_size_of_merge>1</number_of_free_entries_in_pool_to_lower_max_size_of_merge>
         <number_of_free_entries_in_pool_to_execute_optimize_entire_partition>1</number_of_free_entries_in_pool_to_execute_optimize_entire_partition>
     </merge_tree>
-    <http_port>${CLICKHOUSE_HTTP_PORT}</http_port>
+${tlsActive
+        ? `    <https_port>${CLICKHOUSE_HTTPS_PORT}</https_port>
+    <tcp_port_secure>${CLICKHOUSE_TCP_SECURE_PORT}</tcp_port_secure>
+    <openSSL>
+        <server>
+            <certificateFile>${CLICKHOUSE_TLS_CERT_MOUNT_PATH}/server.crt</certificateFile>
+            <privateKeyFile>${CLICKHOUSE_TLS_CERT_MOUNT_PATH}/server.key</privateKeyFile>
+            <verificationMode>relaxed</verificationMode>
+            <disableProtocols>sslv2,sslv3,tlsv1,tlsv1_1</disableProtocols>
+            <preferServerCiphers>true</preferServerCiphers>
+        </server>
+    </openSSL>`
+        : `    <http_port>${CLICKHOUSE_HTTP_PORT}</http_port>`}
     <custom_settings_prefixes>current_</custom_settings_prefixes>
     <!-- HTTP keep-alive window. Must exceed @clickhouse/client idle_socket_ttl (15 s)
          so the client always closes the socket first. Prevents ECONNRESET on reuse. -->
@@ -247,6 +260,38 @@ function compactUserDataScript(script) {
  */
 export function buildClickHouseUserData(options) {
     const serverConfigXml = generateServerConfigXml(options);
+    const tlsActive = options.tlsActive ?? false;
+    if (tlsActive &&
+        (options.caSecretArn === undefined || options.serverSecretArn === undefined)) {
+        throw new Error("buildClickHouseUserData: tlsActive=true requires both caSecretArn and serverSecretArn");
+    }
+    const tlsBootstrap = tlsActive
+        ? `
+# Materialise TLS certs from Secrets Manager. The EC2 instance role carries
+# the secretsmanager:GetSecretValue grant; certs land on the EBS-backed mount
+# at \`$MOUNT_POINT/server-certs/\` and are bind-mounted read-only into the
+# CH container at /etc/clickhouse-server/certs. Cert rotation triggers task
+# replacement via the CA_CERT_SHA256 env on dependent services (the cert
+# generator emits the digest as a CFN Data attribute).
+mkdir -p "$MOUNT_POINT/server-certs"
+
+# jq is needed to extract cert + key fields from the server bundle JSON.
+# AL2023 ECS-optimised AMIs ship without jq; install it if missing.
+command -v jq >/dev/null 2>&1 || dnf install -y jq || yum install -y jq
+
+# Fetch CA (raw PEM SecretString). Quoting prevents word-splitting on multi-line PEM.
+CA_PEM=$(aws secretsmanager get-secret-value --secret-id "${options.caSecretArn ?? ""}" --query SecretString --output text)
+printf '%s\\n' "$CA_PEM" > "$MOUNT_POINT/server-certs/ca.crt"
+
+# Fetch server bundle (JSON { "cert": "<pem>", "key": "<pem>" }).
+SERVER_JSON=$(aws secretsmanager get-secret-value --secret-id "${options.serverSecretArn ?? ""}" --query SecretString --output text)
+printf '%s' "$SERVER_JSON" | jq -r .cert > "$MOUNT_POINT/server-certs/server.crt"
+printf '%s' "$SERVER_JSON" | jq -r .key > "$MOUNT_POINT/server-certs/server.key"
+
+chown -R 101:101 "$MOUNT_POINT/server-certs"
+chmod 600 "$MOUNT_POINT/server-certs/server.key"
+`
+        : "";
     const script = `#!/bin/bash
 set -euo pipefail
 
@@ -333,7 +378,7 @@ if [ "$USERS_CONFIG_RETRIEVED" != "1" ]; then
 fi
 
 chown -R 101:101 "$MOUNT_POINT"
-`;
+${tlsBootstrap}`;
     return compactUserDataScript(script);
 }
 /**

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

@@ -45,7 +45,7 @@ export interface RenderUsersXmlOptions {
  *
  * **Schema-admin-only emission.** Only the schema admin lands in the XML.
  * Managed-password workload users are created at runtime by the migration
- * helper (`@fjall/clickhouse-migrations § provisionUsersFromEnv`) — they
+ * helper (`@fjall/clickhouse § provisionUsersFromEnv`) — they
  * authenticate via plaintext from `USER_<NAME>_PASSWORD` env vars at runtime
  * and bind their profiles via customer SQL.
  *

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

@@ -73,7 +73,7 @@ ${body}
  *
  * **Schema-admin-only emission.** Only the schema admin lands in the XML.
  * Managed-password workload users are created at runtime by the migration
- * helper (`@fjall/clickhouse-migrations § provisionUsersFromEnv`) — they
+ * helper (`@fjall/clickhouse § provisionUsersFromEnv`) — they
  * authenticate via plaintext from `USER_<NAME>_PASSWORD` env vars at runtime
  * and bind their profiles via customer SQL.
  *

package/dist/lib/resources/aws/secrets/index.d.ts

@@ -2,3 +2,5 @@ export * from "./alias.js";
 export * from "./kms.js";
 export * from "./parameter.js";
 export * from "./secret.js";
+export * from "./tlsCaSecret.js";
+export * from "./tlsServerSecret.js";

package/dist/lib/resources/aws/secrets/index.js

@@ -2,3 +2,5 @@ export * from "./alias.js";
 export * from "./kms.js";
 export * from "./parameter.js";
 export * from "./secret.js";
+export * from "./tlsCaSecret.js";
+export * from "./tlsServerSecret.js";

package/dist/lib/resources/aws/secrets/tlsCaSecret.d.ts

@@ -0,0 +1,13 @@
+import type { Construct } from "constructs";
+import { Secret } from "./secret.js";
+export interface TlsCaSecretProps {
+    /** Drives the deterministic secret name `fjall-<appName>-clickhouse-tls-ca`. */
+    readonly appName: string;
+}
+/**
+ * ClickHouse TLS CA cert (public — clients pin against this). Retained on
+ * delete so client-side trust anchors survive accidental stack teardown.
+ */
+export declare class TlsCaSecret extends Secret {
+    constructor(scope: Construct, id: string, props: TlsCaSecretProps);
+}

package/dist/lib/resources/aws/secrets/tlsCaSecret.js

@@ -0,0 +1,15 @@
+import { RemovalPolicy } from "aws-cdk-lib";
+import { Secret } from "./secret.js";
+/**
+ * ClickHouse TLS CA cert (public — clients pin against this). Retained on
+ * delete so client-side trust anchors survive accidental stack teardown.
+ */
+export class TlsCaSecret extends Secret {
+    constructor(scope, id, props) {
+        super(scope, id, {
+            secretName: `fjall-${props.appName}-clickhouse-tls-ca`,
+            description: "ClickHouse TLS CA cert (public — clients pin against this)"
+        });
+        this.secret.applyRemovalPolicy(RemovalPolicy.RETAIN);
+    }
+}

package/dist/lib/resources/aws/secrets/tlsServerSecret.d.ts

@@ -0,0 +1,15 @@
+import type { Construct } from "constructs";
+import { Secret } from "./secret.js";
+export interface TlsServerSecretProps {
+    /** Drives the deterministic secret name `fjall-<appName>-clickhouse-tls-server`. */
+    readonly appName: string;
+}
+/**
+ * ClickHouse TLS server cert + key (JSON: `{ cert, key }`). Retained on
+ * delete so cert material survives accidental stack teardown; the private
+ * key only leaves Secrets Manager via ECS executionRole + the TLS init
+ * container that materialises it onto the shared volume.
+ */
+export declare class TlsServerSecret extends Secret {
+    constructor(scope: Construct, id: string, props: TlsServerSecretProps);
+}