@fjall/components-infrastructure 3.3.0 → 3.5.2

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

@@ -23,15 +23,24 @@ export declare class Buildkite extends Construct {
     readonly secretsBucketName: string;
     readonly autoScalingGroupName: string;
     constructor(scope: Construct, id: string, props: BuildkiteConstructProps);
+    /**
+     * Derive an agent-cluster secret path from the app namespace — the same
+     * `buildParameterPath` derivation `fjall secrets` and the ECS pattern use,
+     * so derived parameters stay manageable by the shared tooling. Explicit
+     * props bypass this entirely; it throws only when derivation is the last
+     * resort and no valid `applicationId` exists to derive from.
+     */
+    private deriveAgentSecretPath;
     /**
      * Ship the per-job `env` hook into the managed secrets bucket. The
      * s3-secrets-hooks plugin sources this file at the start of EVERY job, so
-     * FJALL_API_KEY is read fresh from SSM per job — rotation takes effect on
-     * the next job with no instance replacement (design § D4(iii)). The script
-     * is configuration, not a secret: shipping it through a CDK asset is fine;
-     * the secret VALUE only ever moves SSM → instance at job runtime.
+     * FJALL_API_KEY and the per-pipeline job secrets are read fresh from SSM
+     * per job — rotation takes effect on the next job with no instance
+     * replacement (design § D4(iii)). The script is configuration, not a
+     * secret: shipping it through a CDK asset is fine; secret VALUES only ever
+     * move SSM → instance at job runtime.
      */
-    private addFjallApiKeyEnvHook;
+    private addAgentSecretsEnvHook;
 }
 /**
  * Object key the s3-secrets-hooks plugin sources at the start of every job —
@@ -39,8 +48,44 @@ export declare class Buildkite extends Construct {
  */
 export declare const FJALL_ENV_HOOK_OBJECT_KEY = "env";
 /**
- * The per-job env hook's script content (design § D4(iii)): FJALL_API_KEY is
- * read fresh from SSM per job, so rotation takes effect on the next job with
- * no instance replacement. Pure — the unit test pins the exact content.
+ * Cluster segment of derived agent secret paths
+ * (`/<applicationId>/agents/<name>`) — the namespace the live estate already
+ * uses for its explicitly-provisioned parameters.
+ */
+export declare const BUILDKITE_SECRETS_CLUSTER = "agents";
+/** Derived secret name for the cluster-scoped Buildkite agent token. */
+export declare const AGENT_TOKEN_SECRET_NAME = "agent-token";
+/** Derived secret name for the FJALL_API_KEY env-hook parameter. */
+export declare const FJALL_API_KEY_SECRET_NAME = "fjall-api-key";
+/** Inputs to {@link buildAgentSecretsEnvHookScript}; omitted members skip their block. */
+export interface AgentSecretsEnvHookOptions {
+    /** Resolved FJALL_API_KEY parameter path (explicit prop or derived). */
+    readonly fjallApiKeyParameterName?: string;
+    /**
+     * Namespace root for per-pipeline job secrets (`/<applicationId>/agents`);
+     * the hook lists `<prefix>/<BUILDKITE_PIPELINE_SLUG>` per job. Jobs read
+     * the whole `/<app>/agents/*` subtree via the paired IAM grant — identical
+     * flatness to the previous whole-bucket S3 read; isolation stays per-fleet.
+     */
+    readonly pipelineSecretsPrefix?: string;
+    readonly region: string;
+}
+/**
+ * The per-job env hook's script content (design § D4(iii) + Phase B):
+ * FJALL_API_KEY and the per-pipeline job secrets are read fresh from SSM per
+ * job, so rotation takes effect on the next job with no instance replacement.
+ * Pure — the unit tests byte-pin both emitted variants and `sh -n` them.
+ *
+ * The script is eval'd by the s3secrets plugin under bash
+ * `set -Eeuo pipefail` + an ERR trap that exits 53 (fails the job) +
+ * `set -o allexport` (every assignment auto-exports) + `nounset` — pinned in
+ * `lib/__tests__/fixtures/buildkite/upstream-hooks-v6.68.1/`. Hence: every
+ * fallible command is guarded, every env read uses `${VAR:-}`, every temp
+ * variable is unset after use, and the script never exits. `private_ssh_key`
+ * loads into an ephemeral ssh-agent (stdin → agent memory, never disk or
+ * argv); the upstream pre-exit hook kills whatever `SSH_AGENT_PID` is
+ * exported, so our agent's lifecycle is owned upstream. Every fetched value
+ * is registered with the agent redactor (stdin form) before use — the
+ * upstream helper cannot see values we fetch at eval time.
  */
-export declare function buildFjallApiKeyEnvHookScript(parameterName: string, region: string): string;
+export declare function buildAgentSecretsEnvHookScript(options: AgentSecretsEnvHookOptions): string;

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

@@ -1,4 +1,5 @@
-import { CfnOutput, Duration, RemovalPolicy, Stack, Token } from "aws-cdk-lib";
+import { Annotations, CfnOutput, Duration, RemovalPolicy, Stack, Token } from "aws-cdk-lib";
+import { SSM_COMPONENT_PATTERN, buildParameterPath } from "@fjall/util";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { InstanceArchitecture, InstanceType, MachineImage, SubnetType } from "aws-cdk-lib/aws-ec2";
 import { PolicyStatement } from "aws-cdk-lib/aws-iam";
@@ -38,6 +39,37 @@ export class Buildkite extends Construct {
         super(scope, id);
         const { vpc, ...plainProps } = props;
         const config = validateBuildkiteProps(plainProps);
+        // Deliberate asymmetry: the agent token is load-bearing (boot + scaler),
+        // so underivable throws; the api-key hook and per-pipeline job secrets
+        // are capabilities, so underivable — including a pattern-invalid
+        // applicationId, which pre-derivation callers could always pass —
+        // degrades to "not shipped" with a warning.
+        const agentTokenParameterName = config.agentTokenSsmParameterName ??
+            this.deriveAgentSecretPath(config.applicationId, AGENT_TOKEN_SECRET_NAME);
+        const derivableApplicationId = config.applicationId !== undefined &&
+            config.applicationId !== "" &&
+            SSM_COMPONENT_PATTERN.test(config.applicationId)
+            ? config.applicationId
+            : undefined;
+        const fjallApiKeyParameterName = config.fjallApiKeySsmParameterName ??
+            (derivableApplicationId !== undefined
+                ? this.deriveAgentSecretPath(derivableApplicationId, FJALL_API_KEY_SECRET_NAME)
+                : undefined);
+        const pipelineSecretsPrefix = derivableApplicationId !== undefined
+            ? buildParameterPath({
+                app: derivableApplicationId,
+                cluster: BUILDKITE_SECRETS_CLUSTER
+            })
+            : undefined;
+        if (derivableApplicationId === undefined &&
+            config.applicationId !== undefined &&
+            config.applicationId !== "") {
+            Annotations.of(this).addWarningV2("fjall:buildkite:fjall-api-key-hook-skipped", `applicationId '${config.applicationId}' is not a valid SSM path ` +
+                `component, so namespace-derived agent secrets are disabled: ` +
+                `per-pipeline job secrets will not load, and the FJALL_API_KEY env ` +
+                `hook is not shipped unless fjallApiKeySsmParameterName is set ` +
+                `explicitly. Rename the app or set the parameter-name props.`);
+        }
         const stack = Stack.of(this);
         if (Token.isUnresolved(stack.region)) {
             throw new Error("Buildkite requires a concrete env region at synth (the pinned AMI " +
@@ -61,17 +93,27 @@ export class Buildkite extends Construct {
         // and accidental overwrite; the artifact bucket is scratch output and
         // keeps the wrapper's env-aware default (DESTROY + pre-empty off prod).
         const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`, { versioned: true, removalPolicy: RemovalPolicy.RETAIN });
-        if (config.fjallApiKeySsmParameterName !== undefined) {
-            this.addFjallApiKeyEnvHook(id, managedSecretsBucket, config.fjallApiKeySsmParameterName, region);
+        if (fjallApiKeyParameterName !== undefined ||
+            pipelineSecretsPrefix !== undefined) {
+            this.addAgentSecretsEnvHook(id, managedSecretsBucket, {
+                ...(fjallApiKeyParameterName !== undefined && {
+                    fjallApiKeyParameterName
+                }),
+                ...(pipelineSecretsPrefix !== undefined && { pipelineSecretsPrefix }),
+                region
+            });
         }
         const parameterArn = (name) => `arn:${stack.partition}:ssm:${region}:${stack.account}:parameter${name}`;
         const agentRole = buildAgentRole(this, `${id}AgentRole`, {
-            agentTokenParameterArn: parameterArn(config.agentTokenSsmParameterName),
+            agentTokenParameterArn: parameterArn(agentTokenParameterName),
             ...(config.agentTokenKmsKeyArn !== undefined && {
                 agentTokenKmsKeyArn: config.agentTokenKmsKeyArn
             }),
-            ...(config.fjallApiKeySsmParameterName !== undefined && {
-                fjallApiKeyParameterArn: parameterArn(config.fjallApiKeySsmParameterName)
+            ...(fjallApiKeyParameterName !== undefined && {
+                fjallApiKeyParameterArn: parameterArn(fjallApiKeyParameterName)
+            }),
+            ...(pipelineSecretsPrefix !== undefined && {
+                pipelineSecretsPrefixArn: parameterArn(pipelineSecretsPrefix)
             }),
             secretsBucketArn: managedSecretsBucket.bucketArn,
             artifactBucketArn: artifactBucket.bucketArn,
@@ -82,7 +124,8 @@ export class Buildkite extends Construct {
             stackName: stack.stackName,
             region,
             secretsBucketName: managedSecretsBucket.bucketName,
-            artifactBucketName: artifactBucket.bucketName
+            artifactBucketName: artifactBucket.bucketName,
+            agentTokenParameterName
         });
         // Deliberate deviation from upstream's InstanceScaleInProtection
         // (design § D7): the wrapper's `newInstancesProtectedFromScaleIn: false`
@@ -146,7 +189,7 @@ export class Buildkite extends Construct {
             applicationId: resolveScalerSarApplicationArn(architecture),
             semanticVersion: BUILDKITE_STACK_PINS.scalerVersion,
             parameters: {
-                BuildkiteAgentTokenParameter: config.agentTokenSsmParameterName,
+                BuildkiteAgentTokenParameter: agentTokenParameterName,
                 ...(config.agentTokenKmsKeyArn !== undefined && {
                     BuildkiteAgentTokenParameterStoreKMSKey: config.agentTokenKmsKeyArn
                 }),
@@ -201,18 +244,43 @@ export class Buildkite extends Construct {
             value: artifactBucket.bucketName
         });
     }
+    /**
+     * Derive an agent-cluster secret path from the app namespace — the same
+     * `buildParameterPath` derivation `fjall secrets` and the ECS pattern use,
+     * so derived parameters stay manageable by the shared tooling. Explicit
+     * props bypass this entirely; it throws only when derivation is the last
+     * resort and no valid `applicationId` exists to derive from.
+     */
+    deriveAgentSecretPath(applicationId, secretName) {
+        if (applicationId === undefined || applicationId === "") {
+            throw new Error(`Buildkite: no explicit SSM parameter name was set for '${secretName}' ` +
+                `and no applicationId is available to derive ` +
+                `'/<applicationId>/${BUILDKITE_SECRETS_CLUSTER}/${secretName}' from. ` +
+                `Construct via App.addBuildkite (which injects applicationId) or set ` +
+                `the parameter-name prop explicitly.`);
+        }
+        if (!SSM_COMPONENT_PATTERN.test(applicationId)) {
+            throw new Error(`Buildkite: cannot derive the '${secretName}' SSM parameter path — ` +
+                `applicationId '${applicationId}' is not a valid SSM path component ` +
+                `(must start with a letter; letters, numbers, periods, hyphens, ` +
+                `underscores only). Rename the app or set the parameter-name prop ` +
+                `explicitly.`);
+        }
+        return buildParameterPath({ app: applicationId, cluster: BUILDKITE_SECRETS_CLUSTER }, secretName);
+    }
     /**
      * Ship the per-job `env` hook into the managed secrets bucket. The
      * s3-secrets-hooks plugin sources this file at the start of EVERY job, so
-     * FJALL_API_KEY is read fresh from SSM per job — rotation takes effect on
-     * the next job with no instance replacement (design § D4(iii)). The script
-     * is configuration, not a secret: shipping it through a CDK asset is fine;
-     * the secret VALUE only ever moves SSM → instance at job runtime.
+     * FJALL_API_KEY and the per-pipeline job secrets are read fresh from SSM
+     * per job — rotation takes effect on the next job with no instance
+     * replacement (design § D4(iii)). The script is configuration, not a
+     * secret: shipping it through a CDK asset is fine; secret VALUES only ever
+     * move SSM → instance at job runtime.
      */
-    addFjallApiKeyEnvHook(id, secretsBucket, parameterName, region) {
+    addAgentSecretsEnvHook(id, secretsBucket, options) {
         new BucketDeployment(this, `${id}EnvHookDeployment`, {
             sources: [
-                Source.data(FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript(parameterName, region))
+                Source.data(FJALL_ENV_HOOK_OBJECT_KEY, buildAgentSecretsEnvHookScript(options))
             ],
             destinationBucket: secretsBucket,
             // The secrets bucket also holds out-of-band objects the deployment
@@ -230,17 +298,57 @@ export class Buildkite extends Construct {
  */
 export const FJALL_ENV_HOOK_OBJECT_KEY = "env";
 /**
- * The per-job env hook's script content (design § D4(iii)): FJALL_API_KEY is
- * read fresh from SSM per job, so rotation takes effect on the next job with
- * no instance replacement. Pure — the unit test pins the exact content.
+ * Cluster segment of derived agent secret paths
+ * (`/<applicationId>/agents/<name>`) — the namespace the live estate already
+ * uses for its explicitly-provisioned parameters.
+ */
+export const BUILDKITE_SECRETS_CLUSTER = "agents";
+/** Derived secret name for the cluster-scoped Buildkite agent token. */
+export const AGENT_TOKEN_SECRET_NAME = "agent-token";
+/** Derived secret name for the FJALL_API_KEY env-hook parameter. */
+export const FJALL_API_KEY_SECRET_NAME = "fjall-api-key";
+/**
+ * The per-job env hook's script content (design § D4(iii) + Phase B):
+ * FJALL_API_KEY and the per-pipeline job secrets are read fresh from SSM per
+ * job, so rotation takes effect on the next job with no instance replacement.
+ * Pure — the unit tests byte-pin both emitted variants and `sh -n` them.
+ *
+ * The script is eval'd by the s3secrets plugin under bash
+ * `set -Eeuo pipefail` + an ERR trap that exits 53 (fails the job) +
+ * `set -o allexport` (every assignment auto-exports) + `nounset` — pinned in
+ * `lib/__tests__/fixtures/buildkite/upstream-hooks-v6.68.1/`. Hence: every
+ * fallible command is guarded, every env read uses `${VAR:-}`, every temp
+ * variable is unset after use, and the script never exits. `private_ssh_key`
+ * loads into an ephemeral ssh-agent (stdin → agent memory, never disk or
+ * argv); the upstream pre-exit hook kills whatever `SSH_AGENT_PID` is
+ * exported, so our agent's lifecycle is owned upstream. Every fetched value
+ * is registered with the agent redactor (stdin form) before use — the
+ * upstream helper cannot see values we fetch at eval time.
  */
-export function buildFjallApiKeyEnvHookScript(parameterName, region) {
-    return [
-        `FJALL_API_KEY="$(aws ssm get-parameter --name '${parameterName}' --with-decryption --query Parameter.Value --output text --region '${region}')"`,
-        "export FJALL_API_KEY",
-        ""
-    ].join("\n");
+export function buildAgentSecretsEnvHookScript(options) {
+    const { fjallApiKeyParameterName, pipelineSecretsPrefix, region } = options;
+    const lines = ["set +x", "set +v"];
+    if (fjallApiKeyParameterName !== undefined) {
+        lines.push(`FJALL_API_KEY="$(aws ssm get-parameter --name '${fjallApiKeyParameterName}' --with-decryption --query Parameter.Value --output text --region '${region}' 2>/dev/null)" || true`, 'if [ -n "${FJALL_API_KEY:-}" ]; then', `  printf '%s' "$FJALL_API_KEY" | buildkite-agent redactor add >/dev/null 2>&1 || true`, "  export FJALL_API_KEY", "else", "  unset FJALL_API_KEY", `  echo 'fjall-secrets: could not fetch ${fjallApiKeyParameterName}' >&2`, "fi");
+    }
+    if (pipelineSecretsPrefix !== undefined) {
+        lines.push('if [ -n "${BUILDKITE_PIPELINE_SLUG:-}" ]; then', `  _fjall_names="$(aws ssm get-parameters-by-path --path "${pipelineSecretsPrefix}/\${BUILDKITE_PIPELINE_SLUG:-}" --query 'Parameters[].Name' --output text --region '${region}' 2>/dev/null)" || true`, "  for _fjall_param in ${_fjall_names:-}; do", '    _fjall_name="${_fjall_param##*/}"', `    _fjall_value="$(aws ssm get-parameter --name "$_fjall_param" --with-decryption --query Parameter.Value --output text --region '${region}' 2>/dev/null)" || true`, '    if [ -z "${_fjall_value:-}" ]; then', '      echo "fjall-secrets: could not fetch $_fjall_param" >&2', "      unset _fjall_value", "      continue", "    fi", `    printf '%s' "$_fjall_value" | buildkite-agent redactor add >/dev/null 2>&1 || true`, `    if [ "$_fjall_name" = 'private_ssh_key' ]; then`, `      _fjall_agent_out="$(ssh-agent -s 2>/dev/null)" || true`, '      if [ -n "${_fjall_agent_out:-}" ]; then', '        eval "$_fjall_agent_out" >/dev/null 2>&1 || true', `        printf '%s\\n' "$_fjall_value" | ssh-add - >/dev/null 2>&1 || echo 'fjall-secrets: ssh-add failed for private_ssh_key' >&2`, "      else", `        echo 'fjall-secrets: ssh-agent unavailable - private_ssh_key not loaded' >&2`, "      fi", "      unset _fjall_agent_out", `    elif printf '%s' "$_fjall_name" | grep -Eq '${JOB_ENV_NAME_ALLOW_REGEX}' && ! printf '%s' "$_fjall_name" | grep -Eq '${JOB_ENV_NAME_DENY_REGEX}'; then`, `      export "$_fjall_name=$_fjall_value" 2>/dev/null || echo "fjall-secrets: could not export $_fjall_name" >&2`, "    else", '      echo "fjall-secrets: skipping non-conforming secret name $_fjall_name" >&2', "    fi", "    unset _fjall_value", "  done", "  unset _fjall_names", "  unset _fjall_param", "  unset _fjall_name", "fi");
+    }
+    lines.push("");
+    return lines.join("\n");
 }
+/**
+ * Job-env eligibility for per-pipeline secret names: the allow shape is a
+ * portable shell identifier; the deny list removes the bash-readonly names
+ * (`export UID=…` fails "readonly variable" — under the upstream ERR trap
+ * that would exit-53 EVERY job on the pipeline until the parameter is
+ * deleted), the ssh-agent lifecycle vars the D-B3 flow owns, the
+ * loader-injection vector vars, and the `BUILDKITE_`/`AWS_` prefixes.
+ * `private_ssh_key` is handled before this filter; denied/non-conforming
+ * names are skipped with an identifier-only warning.
+ */
+const JOB_ENV_NAME_ALLOW_REGEX = "^[A-Za-z_][A-Za-z0-9_]*$";
+const JOB_ENV_NAME_DENY_REGEX = "^(PATH|HOME|IFS|LD_PRELOAD|LD_LIBRARY_PATH|BASH_ENV|SSH_AUTH_SOCK|SSH_AGENT_PID|UID|EUID|PPID|SHELLOPTS|BASHOPTS|BASH_VERSINFO)$|^(BUILDKITE_|AWS_)";
 function deriveCpuArchitecture(instanceTypeIdentifier) {
     const architecture = new InstanceType(instanceTypeIdentifier).architecture;
     return architecture === InstanceArchitecture.ARM_64 ? "arm64" : "amd64";

package/dist/lib/patterns/aws/buildkite/iam.d.ts

@@ -11,11 +11,18 @@ import { Role } from "../../../resources/aws/iam/index.js";
  * subset of this list, so an upstream bump (or a future edit) that grows
  * permissions fails loudly instead of shipping silently.
  */
-export declare const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST: readonly ["ssm:GetParameter", "kms:Decrypt", "s3:GetObject", "s3:ListBucket", "s3:GetObjectVersion", "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutRetentionPolicy", "ssm:DescribeInstanceProperties", "ssm:ListAssociations", "ssm:PutInventory", "ssm:UpdateInstanceInformation", "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel", "ec2messages:AcknowledgeMessage", "ec2messages:DeleteMessage", "ec2messages:FailMessage", "ec2messages:GetEndpoint", "ec2messages:GetMessages", "ec2messages:SendReply", "autoscaling:DescribeAutoScalingInstances", "autoscaling:SetInstanceHealth", "autoscaling:TerminateInstanceInAutoScalingGroup", "cloudwatch:PutMetricData", "cloudformation:DescribeStackResource", "ec2:DescribeTags"];
+export declare const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST: readonly ["ssm:GetParameter", "ssm:GetParametersByPath", "kms:Decrypt", "s3:GetObject", "s3:ListBucket", "s3:GetObjectVersion", "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutRetentionPolicy", "ssm:DescribeInstanceProperties", "ssm:ListAssociations", "ssm:PutInventory", "ssm:UpdateInstanceInformation", "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel", "ec2messages:AcknowledgeMessage", "ec2messages:DeleteMessage", "ec2messages:FailMessage", "ec2messages:GetEndpoint", "ec2messages:GetMessages", "ec2messages:SendReply", "autoscaling:DescribeAutoScalingInstances", "autoscaling:SetInstanceHealth", "autoscaling:TerminateInstanceInAutoScalingGroup", "cloudwatch:PutMetricData", "cloudformation:DescribeStackResource", "ec2:DescribeTags"];
 export interface BuildkiteAgentRoleParams {
     readonly agentTokenParameterArn: string;
     readonly agentTokenKmsKeyArn?: string;
     readonly fjallApiKeyParameterArn?: string;
+    /**
+     * `arn:…:parameter/<app>/agents` — per-pipeline job-secrets subtree root;
+     * grants list + read on `<root>/*`. Jobs can read the whole subtree
+     * (identical flatness to the whole-bucket S3 read this replaces);
+     * isolation stays per-fleet.
+     */
+    readonly pipelineSecretsPrefixArn?: string;
     readonly secretsBucketArn: string;
     readonly artifactBucketArn: string;
     /** Own-stack ARN — `cloudformation:DescribeStackResource` scope. */

package/dist/lib/patterns/aws/buildkite/iam.js

@@ -13,6 +13,9 @@ import { Role } from "../../../resources/aws/iam/index.js";
  */
 export const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST = [
     "ssm:GetParameter",
+    // Read-only, scoped to the /<app>/agents/* subtree (per-pipeline job
+    // secrets) — never account-wide.
+    "ssm:GetParametersByPath",
     "kms:Decrypt",
     "s3:GetObject",
     "s3:ListBucket",
@@ -77,6 +80,14 @@ function buildAgentPolicyDocuments(params) {
                             : [])
                     ]
                 }),
+                ...(params.pipelineSecretsPrefixArn !== undefined
+                    ? [
+                        new PolicyStatement({
+                            actions: ["ssm:GetParameter", "ssm:GetParametersByPath"],
+                            resources: [`${params.pipelineSecretsPrefixArn}/*`]
+                        })
+                    ]
+                    : []),
                 ...(params.agentTokenKmsKeyArn !== undefined
                     ? [
                         new PolicyStatement({

package/dist/lib/patterns/aws/buildkite/userData.d.ts

@@ -11,6 +11,13 @@ export interface BuildkiteUserDataContext {
     readonly region: string;
     readonly secretsBucketName: string;
     readonly artifactBucketName: string;
+    /**
+     * RESOLVED agent-token parameter path (explicit prop or namespace-derived)
+     * — never `props.agentTokenSsmParameterName`, which is optional since the
+     * derivation landed and would render the literal string "undefined" into
+     * BUILDKITE_AGENT_TOKEN_PATH through the template literal.
+     */
+    readonly agentTokenParameterName: string;
 }
 /**
  * The pinned AMI's boot scripts run under `set -Eeuo pipefail` and
@@ -42,7 +49,7 @@ export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): str
  * `bk-install-elastic-stack.sh`, mirroring the upstream block key-for-key in
  * upstream order (so a fixture-bump diff reads line-by-line). Keys with no
  * schema knob carry the upstream v6.68.1 parameter default verbatim, with
- * four deliberate deviations:
+ * five deliberate deviations:
  *
  * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
  *   disabled), where S3 rejects every canned ACL EXCEPT
@@ -54,6 +61,11 @@ export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): str
  *   is out of scope for the Phase-1 deploy fleet; a future signing knob must
  *   land WITH the kms:Sign/Verify/GetPublicKey grants it needs (the prior
  *   knob shipped without them — a dead toggle that broke agents when set).
+ * - `BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING`: hard-pinned
+ *   `true` (upstream default `false`). Since the Phase-B migration the git
+ *   deploy key lives in SSM and is loaded by our env hook — the plugin's S3
+ *   `private_ssh_key` object is intentionally absent, so its per-job
+ *   not-found warning is pure noise.
  * - `ENABLE_EC2_LOG_RETENTION_POLICY`: hard-pinned `true` (upstream default
  *   `false`, "preserve all logs"). Fjall's log-group lifecycle posture is
  *   bounded retention everywhere: each booting instance applies

package/dist/lib/patterns/aws/buildkite/userData.js

@@ -149,7 +149,7 @@ export function buildBuildkiteDockerCommands(props) {
  * `bk-install-elastic-stack.sh`, mirroring the upstream block key-for-key in
  * upstream order (so a fixture-bump diff reads line-by-line). Keys with no
  * schema knob carry the upstream v6.68.1 parameter default verbatim, with
- * four deliberate deviations:
+ * five deliberate deviations:
  *
  * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
  *   disabled), where S3 rejects every canned ACL EXCEPT
@@ -161,6 +161,11 @@ export function buildBuildkiteDockerCommands(props) {
  *   is out of scope for the Phase-1 deploy fleet; a future signing knob must
  *   land WITH the kms:Sign/Verify/GetPublicKey grants it needs (the prior
  *   knob shipped without them — a dead toggle that broke agents when set).
+ * - `BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING`: hard-pinned
+ *   `true` (upstream default `false`). Since the Phase-B migration the git
+ *   deploy key lives in SSM and is loaded by our env hook — the plugin's S3
+ *   `private_ssh_key` object is intentionally absent, so its per-job
+ *   not-found warning is pure noise.
  * - `ENABLE_EC2_LOG_RETENTION_POLICY`: hard-pinned `true` (upstream default
  *   `false`, "preserve all logs"). Fjall's log-group lifecycle posture is
  *   bounded retention everywhere: each booting instance applies
@@ -181,11 +186,11 @@ export function buildBuildkiteInstallCommands(props, context) {
         `BUILDKITE_SCALE_IN_IDLE_PERIOD='${props.scaleInIdlePeriodSeconds}' \\`,
         `BUILDKITE_SECRETS_BUCKET='${context.secretsBucketName}' \\`,
         `BUILDKITE_SECRETS_BUCKET_REGION='${context.region}' \\`,
-        "BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING='false' \\",
+        "BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING='true' \\",
         `BUILDKITE_ARTIFACTS_BUCKET='${context.artifactBucketName}' \\`,
         `BUILDKITE_S3_DEFAULT_REGION='${context.region}' \\`,
         "BUILDKITE_S3_ACL='bucket-owner-full-control' \\",
-        `BUILDKITE_AGENT_TOKEN_PATH='${props.agentTokenSsmParameterName}' \\`,
+        `BUILDKITE_AGENT_TOKEN_PATH='${context.agentTokenParameterName}' \\`,
         `BUILDKITE_AGENTS_PER_INSTANCE='${props.agentsPerInstance}' \\`,
         "BUILDKITE_AGENT_ENDPOINT='https://agent-edge.buildkite.com/v3' \\",
         `BUILDKITE_AGENT_TAGS='${props.buildkiteAgentTags}' \\`,

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

@@ -4,7 +4,7 @@
  * Construct instantiated via `App.addBuildkite()`; design:
  * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
  */
-export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript, type BuildkiteConstructProps } from "./buildkite/buildkite.js";
+export { AGENT_TOKEN_SECRET_NAME, BUILDKITE_SECRETS_CLUSTER, Buildkite, FJALL_API_KEY_SECRET_NAME, FJALL_ENV_HOOK_OBJECT_KEY, buildAgentSecretsEnvHookScript, type AgentSecretsEnvHookOptions, type BuildkiteConstructProps } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn, type BuildkiteCpuArchitecture } from "./buildkite/pins.js";
 export { BuildkitePropsSchema, validateBuildkiteProps, type BuildkiteProps, type BuildkitePropsInput } from "./buildkite/schema.js";
 export { BuildkiteFactory, type BuildkiteFactoryFn } from "./buildkite/factory.js";

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

@@ -4,7 +4,7 @@
  * Construct instantiated via `App.addBuildkite()`; design:
  * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
  */
-export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript } from "./buildkite/buildkite.js";
+export { AGENT_TOKEN_SECRET_NAME, BUILDKITE_SECRETS_CLUSTER, Buildkite, FJALL_API_KEY_SECRET_NAME, FJALL_ENV_HOOK_OBJECT_KEY, buildAgentSecretsEnvHookScript } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./buildkite/pins.js";
 export { BuildkitePropsSchema, validateBuildkiteProps } from "./buildkite/schema.js";
 export { BuildkiteFactory } from "./buildkite/factory.js";

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

@@ -69,6 +69,12 @@ export interface AuroraDatabaseProps extends BaseDatabaseProps {
     clusterIdentifier?: string;
     /** Physical name of the generated master-credentials secret. */
     credentialsSecretName?: string;
+    /**
+     * KMS alias for the CMK encrypting the master-credentials secret. Must be
+     * app-scoped when the same `databaseName` deploys once per app in a shared
+     * account (aliases are account+region-unique).
+     */
+    credentialsKmsAliasName?: string;
     /** Serverless-v2 floor in ACU. 0 enables scale-to-zero (auto-pause). */
     serverlessV2MinCapacity?: number;
     /** Serverless-v2 ceiling in ACU. */

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

@@ -16,7 +16,7 @@ import { Duration } from "aws-cdk-lib";
 export { isAwsManagedKey, isCMKRequested, AWS_MANAGED, USE_CMK } from "../../utils/databaseTypes.js";
 export const DATABASE_ENGINE_CONFIG = Object.freeze({
     postgresql: {
-        aurora: { version: "16.6", majorVersion: "16" },
+        aurora: { version: "16.10", majorVersion: "16" },
         instance: { version: "17.5", majorVersion: "17" },
         defaultUsername: "postgres",
         sslParameters: { "rds.force_ssl": "1" }
@@ -372,6 +372,7 @@ export class RelationalDatabase extends Construct {
             engineConfig,
             clusterIdentifier: props.clusterIdentifier,
             credentialsSecretName: props.credentialsSecretName,
+            credentialsKmsAliasName: props.credentialsKmsAliasName,
             serverlessV2MinCapacity: props.serverlessV2MinCapacity,
             serverlessV2MaxCapacity: props.serverlessV2MaxCapacity,
             serverlessV2AutoPauseDuration: props.serverlessV2AutoPauseDuration,

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

@@ -161,6 +161,8 @@ export class DevSubstrate extends Construct {
             databaseName: DEV_SUBSTRATE_DATABASE_NAME,
             clusterIdentifier: devFenceName(props.appKebab),
             credentialsSecretName: `${devFenceName(props.appKebab)}-master`,
+            // Default alias derives from the fixed databaseName — collides account-wide.
+            credentialsKmsAliasName: `cmk/${devFenceName(props.appKebab)}-master`,
             engineVersion: props.engineVersion ?? DEV_AURORA_DEFAULTS.ENGINE_VERSION,
             serverlessV2MinCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MIN_CAPACITY,
             serverlessV2MaxCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MAX_CAPACITY,
@@ -205,8 +207,14 @@ export class DevSubstrate extends Construct {
         // createBaseExecutionRole DELIBERATELY omits logs (auto-granted only on the
         // ECS-pattern path via AwsLogDriver.bind()). Slot task-defs reference this
         // shared role by ARN, so that auto-grant never fires — add the log-write grant
-        // explicitly.
-        const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID);
+        // explicitly. Path + name pin the role inside the /fjall/dev/ fence: the dev
+        // deploy role's only iam:PassRole grant is on role/fjall/dev/*, so the CDK
+        // defaults (path "/", CFN-generated name) would AccessDeny slot task-def
+        // registration.
+        const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID, {
+            path: "/fjall/dev/",
+            roleName: `${devFenceName(props.appKebab)}-slot-exec`
+        });
         const { partition, region, account } = Stack.of(this);
         slotExecutionRole.addToPolicy(new PolicyStatement({
             effect: Effect.ALLOW,
@@ -376,9 +384,11 @@ export class DevSubstrate extends Construct {
      * the hand-created G2 slot service consumes these to place tasks, register a
      * host-header rule, inject DB creds and point a sleeping slot at the waker.
      *
-     * No KMS-alias export: the substrate's Aurora + waker use the AWS-managed default
-     * key (design VF4 — the waker's kms:Decrypt is ViaService-scoped precisely
-     * because there is no per-app CMK), so there is no alias to export.
+     * No KMS-alias export: cluster storage and SSM SecureStrings ride AWS-managed
+     * default keys, and while the master-credentials secret IS CMK-encrypted (the
+     * Secret wrapper mints `cmk/fjall-dev-<app>-master`), no consumer addresses
+     * that key by alias — the provisioner's and waker's kms:Decrypt are
+     * ViaService-scoped (Secrets Manager / SSM), so there is no alias to export.
      *
      * The Aurora slot-SG ingress (A2.5) makes the Database stack depend on the
      * Compute stack. So the two DB exports are scoped under `databaseScope` (the

package/dist/lib/resources/aws/compute/ecsRoles.d.ts

@@ -16,9 +16,16 @@ import type { EcsServiceProps } from "./ecsTypes.js";
  * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
  * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
  * the explicit `logs` / `secretsmanager` statements itself.
+ *
+ * `path`/`roleName` pin the IAM path and physical name — needed when an IAM
+ * grant fences on the role's path (the dev-role `iam:PassRole` grant on
+ * `role/fjall/dev/*`), since the CDK default is path `/` + a CFN-generated
+ * name no path- or prefix-scoped grant can match.
  */
 export declare function createBaseExecutionRole(scope: Construct, id: string, opts?: {
     ssmSecretsPath?: string;
+    path?: string;
+    roleName?: string;
 }): Role;
 /**
  * Creates the execution role for ECS infrastructure operations.

package/dist/lib/resources/aws/compute/ecsRoles.js

@@ -15,10 +15,17 @@ import { deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
  * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
  * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
  * the explicit `logs` / `secretsmanager` statements itself.
+ *
+ * `path`/`roleName` pin the IAM path and physical name — needed when an IAM
+ * grant fences on the role's path (the dev-role `iam:PassRole` grant on
+ * `role/fjall/dev/*`), since the CDK default is path `/` + a CFN-generated
+ * name no path- or prefix-scoped grant can match.
  */
 export function createBaseExecutionRole(scope, id, opts = {}) {
     const executionRole = new Role(scope, id, {
-        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
+        path: opts.path,
+        roleName: opts.roleName
     });
     // GetAuthorizationToken is an account-level API that requires resources: ["*"].
     // The image-pull actions also use "*" because ecrRepository can be a string URI

package/dist/lib/resources/aws/compute/ecsServiceFactory.d.ts

@@ -1,9 +1,9 @@
 import { FargateService, Ec2Service, AsgCapacityProvider, type DeploymentCircuitBreaker } from "aws-cdk-lib/aws-ecs";
 import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
-import { TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
+import { type EcsServiceProps, type Ec2CapacityConfig, type QueueScalingResources } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
 /**
  * Resolves the user's `circuitBreaker` config to the CDK
@@ -41,4 +41,4 @@ export declare function createService(ctx: EcsConstructContext, serviceName: str
  * policy on utilisation; `QUEUE` emits a step-scaling policy on SQS backlog
  * that can wake the service from `desiredCount: 0`.
  */
-export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy | StepScalingPolicy;
+export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy | QueueScalingResources;

package/dist/lib/resources/aws/compute/ecsServiceFactory.js

@@ -3,8 +3,9 @@ import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
 import { CfnOutput, Duration, Token } from "aws-cdk-lib";
-import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
-import { MathExpression } from "aws-cdk-lib/aws-cloudwatch";
+import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, StepScalingAction, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { Alarm, ComparisonOperator, MathExpression } from "aws-cdk-lib/aws-cloudwatch";
+import { ApplicationScalingAction } from "aws-cdk-lib/aws-cloudwatch-actions";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Ec2Instance } from "./ec2.js";
@@ -283,13 +284,14 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
     return service;
 }
 /**
- * Step-scaling intervals on the queue-backlog metric, with
- * `AdjustmentType.EXACT_CAPACITY` (`change` is the absolute DesiredCount).
- * Backlog 0 → 0 tasks (wake-to-zero); ≥1 → 1; ≥100 → 2; ≥500 → 3. Capacities
- * are clamped to the service's `maxCapacity` at build time.
+ * Wake-ladder intervals on the queue-backlog metric, with
+ * `AdjustmentType.EXACT_CAPACITY` (`capacity` is the absolute DesiredCount).
+ * Backlog ≥1 → 1 task; ≥100 → 2; ≥500 → 3. Capacities are clamped to the
+ * service's `maxCapacity` at build time. Bounds are absolute backlog values;
+ * `buildQueueScalingPolicy` re-expresses them relative to the wake alarm's
+ * threshold (the first interval's `lower`).
  */
-const DEFAULT_QUEUE_SCALING_STEPS = [
-    { lower: 0, upper: 1, capacity: 0 },
+const QUEUE_WAKE_SCALING_STEPS = [
     { lower: 1, upper: 100, capacity: 1 },
     { lower: 100, upper: 500, capacity: 2 },
     { lower: 500, capacity: 3 }
@@ -327,11 +329,21 @@ export function addServiceScaling(ctx, serviceName, serviceProps, service) {
     });
 }
 /**
- * Builds the step-scaling policy for `ScalingType.QUEUE`. The alarm metric is a
- * `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
+ * Builds the wake/sleep step-scaling pair for `ScalingType.QUEUE`. The alarm
+ * metric is a `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
  * (+`…NotVisible` when `includeInFlight`) across the consumed queues, sampled at
  * `Maximum` over 1-minute periods — published independent of running-task count,
- * so the policy fires (and DesiredCount rises from 0) on backlog alone.
+ * so the alarms fire (and DesiredCount rises from 0) on backlog alone.
+ *
+ * The actions and alarms are wired explicitly rather than via
+ * `ScalableTarget.scaleOnMetric`: CDK's `StepScalingPolicy` middle-splits an
+ * all-`EXACT_CAPACITY` interval ladder to place its two alarm thresholds
+ * (`findAlarmThresholds` in aws-autoscaling-common), which for a
+ * 0/1/100/500 ladder puts BOTH thresholds at 100. Step policies are only
+ * invoked on alarm state transitions, so backlog 1–99 produced no transition
+ * and could never wake a zero-task service. The explicit pair pins the wake
+ * threshold at the ladder's first bound (backlog ≥ 1) and the sleep threshold
+ * at 0, making every 0↔1 backlog crossing a state transition.
  */
 function buildQueueScalingPolicy(serviceName, config, scalableTarget, maxCapacity) {
     if (config === undefined || config.queues.length === 0) {
@@ -363,16 +375,46 @@ function buildQueueScalingPolicy(serviceName, config, scalableTarget, maxCapacit
         period: Duration.minutes(1),
         label: `${serviceName}QueueBacklog`
     });
-    return scalableTarget.scaleOnMetric(`${serviceName}QueueScaling`, {
+    const cooldown = config.cooldown ?? DEFAULT_QUEUE_SCALE_COOLDOWN;
+    const wakeThreshold = QUEUE_WAKE_SCALING_STEPS[0]?.lower ?? 1;
+    const wakeAction = new StepScalingAction(scalableTarget, `${serviceName}QueueWakeAction`, {
+        scalingTarget: scalableTarget,
+        adjustmentType: AdjustmentType.EXACT_CAPACITY,
+        cooldown
+    });
+    QUEUE_WAKE_SCALING_STEPS.forEach((step, index) => {
+        wakeAction.addAdjustment({
+            adjustment: Math.min(step.capacity, maxCapacity),
+            lowerBound: step.lower - wakeThreshold,
+            ...(index < QUEUE_WAKE_SCALING_STEPS.length - 1 &&
+                step.upper !== undefined && { upperBound: step.upper - wakeThreshold })
+        });
+    });
+    const wakeAlarm = new Alarm(scalableTarget, `${serviceName}QueueWakeAlarm`, {
         metric: backlogMetric,
+        alarmDescription: `Scale out '${serviceName}' on queue backlog`,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: wakeThreshold,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1
+    });
+    wakeAlarm.addAlarmAction(new ApplicationScalingAction(wakeAction));
+    const sleepAction = new StepScalingAction(scalableTarget, `${serviceName}QueueSleepAction`, {
+        scalingTarget: scalableTarget,
         adjustmentType: AdjustmentType.EXACT_CAPACITY,
-        scalingSteps: DEFAULT_QUEUE_SCALING_STEPS.map((step) => ({
-            lower: step.lower,
-            ...(step.upper !== undefined && { upper: step.upper }),
-            change: Math.min(step.capacity, maxCapacity)
-        })),
-        cooldown: config.cooldown ?? DEFAULT_QUEUE_SCALE_COOLDOWN,
+        cooldown
+    });
+    // upperBound is relative to the alarm threshold (0), so this single
+    // open-ended interval covers exactly backlog ≤ 0.
+    sleepAction.addAdjustment({ adjustment: 0, upperBound: 0 });
+    const sleepAlarm = new Alarm(scalableTarget, `${serviceName}QueueSleepAlarm`, {
+        metric: backlogMetric,
+        alarmDescription: `Scale '${serviceName}' to zero on empty queue`,
+        comparisonOperator: ComparisonOperator.LESS_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: 0,
         evaluationPeriods: 1,
         datapointsToAlarm: 1
     });
+    sleepAlarm.addAlarmAction(new ApplicationScalingAction(sleepAction));
+    return { wakeAction, wakeAlarm, sleepAction, sleepAlarm };
 }

package/dist/lib/resources/aws/compute/ecsTypes.d.ts

@@ -4,7 +4,8 @@ import { type Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { type IService } from "aws-cdk-lib/aws-servicediscovery";
 import { type IManagedPolicy, type PolicyDocument } from "aws-cdk-lib/aws-iam";
 import type { DockerBuild } from "@fjall/util/manifest/schemas";
-import { type TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type TargetTrackingScalingPolicy, type StepScalingAction } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type Duration } from "aws-cdk-lib";
 import { type GeoLocation } from "aws-cdk-lib/aws-route53";
@@ -63,6 +64,29 @@ export interface QueueScalingConfig {
     /** Cooldown after a scale action. Default: 5 minutes. */
     cooldown?: Duration;
 }
+/**
+ * The explicitly-wired wake/sleep alarm pair emitted for `ScalingType.QUEUE`.
+ *
+ * Built by hand (NOT via `ScalableTarget.scaleOnMetric`) because CDK's
+ * `StepScalingPolicy` places its two alarm thresholds by middle-splitting the
+ * interval ladder when every `EXACT_CAPACITY` step carries a change — for the
+ * default 4-step ladder that puts BOTH thresholds at backlog 100, and since
+ * step policies are only invoked on alarm state transitions, a backlog of
+ * 1–99 can never wake a `desiredCount: 0` service (observed live: the prod
+ * deploy-worker sat at 0 tasks with 1 queued message indefinitely). The
+ * explicit pair pins the wake boundary at backlog ≥ 1 and the sleep boundary
+ * at backlog 0.
+ */
+export interface QueueScalingResources {
+    /** Scale-out action: backlog ≥ 1 → capacity ladder (1/2/3, clamped). */
+    wakeAction: StepScalingAction;
+    /** Alarm at backlog ≥ 1 driving `wakeAction`. */
+    wakeAlarm: Alarm;
+    /** Scale-in action: backlog 0 → capacity 0. */
+    sleepAction: StepScalingAction;
+    /** Alarm at backlog ≤ 0 driving `sleepAction`. */
+    sleepAlarm: Alarm;
+}
 import type { EcsCapacityProvider } from "@fjall/generator";
 export type { EcsCapacityProvider };
 /**
@@ -607,7 +631,7 @@ export interface ServiceData {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;
     targetGroup?: IApplicationTargetGroup;
-    scalingPolicy?: TargetTrackingScalingPolicy | StepScalingPolicy;
+    scalingPolicy?: TargetTrackingScalingPolicy | QueueScalingResources;
     /** Explicit log group shared by all of the service's containers. */
     logGroup: ILogGroup;
 }

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

@@ -20,6 +20,13 @@ interface RdsProps {
     clusterIdentifier?: string;
     /** Physical name of the generated master-credentials secret. */
     credentialsSecretName?: string;
+    /**
+     * KMS alias for the CMK encrypting the master-credentials secret. Aliases are
+     * account+region-unique, so a caller with a fixed `databaseName` deployed once
+     * per app (e.g. the dev substrate) must pass an app-scoped alias or the second
+     * app's deploy fails on the alias collision.
+     */
+    credentialsKmsAliasName?: string;
     /** Serverless-v2 floor in ACU. 0 enables scale-to-zero (auto-pause). */
     serverlessV2MinCapacity?: number;
     /** Serverless-v2 ceiling in ACU. */

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

@@ -100,6 +100,7 @@ export class RdsAurora extends Construct {
             this.databaseCredentials = new Secret(this, `${this.databaseNameValue}Credentials`, {
                 secretName: props.credentialsSecretName ??
                     ResourceNaming.credentialsSecretName(id),
+                aliasName: props.credentialsKmsAliasName,
                 generateSecretString: {
                     secretStringTemplate: JSON.stringify({ username }),
                     excludePunctuation: true,
@@ -151,7 +152,7 @@ export class RdsAurora extends Construct {
         const readers = this.buildReaders(props, piEnabled, performanceInsightsKey, performanceInsightsRetention);
         const engine = props.engine ||
             DatabaseClusterEngine.auroraPostgres({
-                version: AuroraPostgresEngineVersion.of("16.6", "16")
+                version: AuroraPostgresEngineVersion.of("16.10", "16")
             });
         const parameterGroup = new ParameterGroup(this, `${this.databaseNameValue}ParameterGroup`, {
             engine,

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

@@ -16,15 +16,18 @@ export declare const RDS_DEFAULTS: Readonly<{
  * (fast dev-envs Phase 3). `min 0` ACU scales the shared cluster to zero when
  * idle; `enableDataApi` lets slot DDL run over HTTPS with no VPC connection, and
  * is the only mode under which min-0 actually saves (a live pooled connection
- * pins the cluster above 0 ACU). Engine 16.6 satisfies the auto-pause-capable
- * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`).
+ * pins the cluster above 0 ACU). Engine 16.10 satisfies the auto-pause-capable
+ * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`). AWS removes old minors from
+ * the creatable list over time (16.6 rejected with "Cannot find version" by
+ * 2026-07) — pin a mid-window minor, not the oldest available, and expect this
+ * to need a bump roughly yearly.
  */
 export declare const DEV_AURORA_DEFAULTS: Readonly<{
     readonly SERVERLESS_V2_MIN_CAPACITY: 0;
     readonly SERVERLESS_V2_MAX_CAPACITY: 4;
     readonly AUTO_PAUSE_SECONDS: 1200;
     readonly ENABLE_DATA_API: true;
-    readonly ENGINE_VERSION: "16.6";
+    readonly ENGINE_VERSION: "16.10";
 }>;
 /**
  * Bounds AWS enforces on `ServerlessV2ScalingConfiguration.SecondsUntilAutoPause`

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

@@ -16,15 +16,18 @@ export const RDS_DEFAULTS = Object.freeze({
  * (fast dev-envs Phase 3). `min 0` ACU scales the shared cluster to zero when
  * idle; `enableDataApi` lets slot DDL run over HTTPS with no VPC connection, and
  * is the only mode under which min-0 actually saves (a live pooled connection
- * pins the cluster above 0 ACU). Engine 16.6 satisfies the auto-pause-capable
- * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`).
+ * pins the cluster above 0 ACU). Engine 16.10 satisfies the auto-pause-capable
+ * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`). AWS removes old minors from
+ * the creatable list over time (16.6 rejected with "Cannot find version" by
+ * 2026-07) — pin a mid-window minor, not the oldest available, and expect this
+ * to need a bump roughly yearly.
  */
 export const DEV_AURORA_DEFAULTS = Object.freeze({
     SERVERLESS_V2_MIN_CAPACITY: 0,
     SERVERLESS_V2_MAX_CAPACITY: 4,
     AUTO_PAUSE_SECONDS: 1200,
     ENABLE_DATA_API: true,
-    ENGINE_VERSION: "16.6"
+    ENGINE_VERSION: "16.10"
 });
 /**
  * Bounds AWS enforces on `ServerlessV2ScalingConfiguration.SecondsUntilAutoPause`

package/dist/lib/resources/aws/networking/domainCertificate.js

@@ -1,6 +1,7 @@
 import { CfnOutput, Tags } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { getDomainExportNames } from "@fjall/util";
+import { sanitiseAcmTagValue } from "../../../utils/acmTagValue.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 /**
@@ -33,10 +34,12 @@ export class DomainCertificate extends Certificate {
         this.description =
             props.description ??
                 `Fjall-managed ACM certificate for ${props.domainName}`;
-        Tags.of(this).add("fjall:description", this.description);
+        // ACM's tag-value charset excludes `*`, so a wildcard domainName in either
+        // tag fails CreateCertificate — sanitise both (see utils/acmTagValue.ts).
+        Tags.of(this).add("fjall:description", sanitiseAcmTagValue(this.description));
         applyCostAllocationTags(this, {
             service: "certificate",
-            domain: props.costAllocationDomain ?? props.domainName,
+            domain: sanitiseAcmTagValue(props.costAllocationDomain ?? props.domainName),
             environment: props.costAllocationEnvironment,
             inheritEnvironment: props.inheritCostAllocationEnvironment
         });

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

@@ -17,6 +17,12 @@ interface SecretProps {
      */
     secretStringValue?: string;
     description?: string;
+    /**
+     * KMS alias for the wrapper-minted encryption CMK. Aliases are unique per
+     * account+region, so callers whose construct id is not account-unique (e.g.
+     * a fixed-name pattern deployed once per app) MUST pass an app-scoped alias.
+     * @default cmk/<construct id>
+     */
     aliasName?: string;
     generateSecretString?: SecretStringGenerator;
     /** Regions where this secret should be replicated (for Global Aurora) */

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

@@ -71,7 +71,7 @@ export class Secret extends Construct {
         }
         // Create KMS key for new secrets only
         const customerManagedKey = new CustomerManagedKey(this, `${id}CustomerManagedKey`, {
-            aliasName: `cmk/${id}`
+            aliasName: props.aliasName ?? `cmk/${id}`
         });
         this.secretsCustomerManagedKey = customerManagedKey;
         /**

package/dist/lib/utils/acmTagValue.d.ts

@@ -0,0 +1,2 @@
+/** Replace every ACM-disallowed character with `_` (an allowed character). */
+export declare function sanitiseAcmTagValue(value: string): string;

package/dist/lib/utils/acmTagValue.js

@@ -0,0 +1,13 @@
+/**
+ * ACM rejects tag values containing characters outside
+ * `[\p{L}\p{Z}\p{N}_.:/=+\-@]*` (letters, spaces, numbers, `_ . : / = + - @`)
+ * with a CreateCertificate ValidationException — notably `*`, so any tag
+ * embedding a wildcard domain (`*.dev.example.com`) fails the whole stack at
+ * deploy time. Most other taggable services (S3, EC2, Route53) accept `*`,
+ * which is why the constraint only surfaces at the certificate boundary.
+ */
+const ACM_TAG_VALUE_DISALLOWED = /[^\p{L}\p{Z}\p{N}_.:/=+\-@]/gu;
+/** Replace every ACM-disallowed character with `_` (an allowed character). */
+export function sanitiseAcmTagValue(value) {
+    return value.replace(ACM_TAG_VALUE_DISALLOWED, "_");
+}

package/dist/lib/utils/costAllocationTags.d.ts

@@ -1,11 +1,6 @@
+import { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "@fjall/util/aws";
 import type { IConstruct } from "constructs";
-export declare const COST_ALLOCATION_TAGS: {
-    readonly ENVIRONMENT: "fjall:costAllocation:environment";
-    readonly SERVICE: "fjall:costAllocation:service";
-    readonly DOMAIN: "fjall:costAllocation:domain";
-    readonly OWNER: "fjall:costAllocation:owner";
-};
-export declare const DEFAULT_COST_ALLOCATION_ENVIRONMENT: "management";
+export { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT };
 export interface CostAllocationTagsArgs {
     readonly service: string;
     readonly domain: string;

package/dist/lib/utils/costAllocationTags.js

@@ -1,11 +1,9 @@
+import { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "@fjall/util/aws";
 import { Tags } from "aws-cdk-lib";
-export const COST_ALLOCATION_TAGS = {
-    ENVIRONMENT: "fjall:costAllocation:environment",
-    SERVICE: "fjall:costAllocation:service",
-    DOMAIN: "fjall:costAllocation:domain",
-    OWNER: "fjall:costAllocation:owner"
-};
-export const DEFAULT_COST_ALLOCATION_ENVIRONMENT = "management";
+// Canonical home: @fjall/util (`util/src/aws/costAllocationTags.ts`) — shared
+// with deploy-core's `cdk bootstrap --tags` stamping. Re-exported here so
+// construct-package consumers keep their existing import path.
+export { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT };
 export function applyCostAllocationTags(scope, args) {
     if (args.environment !== undefined) {
         Tags.of(scope).add(COST_ALLOCATION_TAGS.ENVIRONMENT, args.environment);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "3.3.0",
+  "version": "3.5.2",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^3.3.0",
-    "@fjall/util": "^3.3.0",
+    "@fjall/generator": "^3.5.2",
+    "@fjall/util": "^3.5.2",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "cc1e0f520f4b6b5312e16df3751d60ea746dfb7d"
+  "gitHead": "f59755647b2fd81ff692a3545e8e199d93c3bdf8"
 }