callsy-cdk-secure-parameter 1.0.0__tar.gz

callsy_cdk_secure_parameter-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+### Python ###
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+### CDK ###
+cdk.out/
+.cdk.staging/
+
+### Node ###
+node_modules/
+
+### JetBrains ###
+.idea/
+*.iml
+
+### macOS ###
+.DS_Store
+._*
+
+### Environment ###
+.env
+.env.*

callsy_cdk_secure_parameter-1.0.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here.
+This project adheres to [semantic versioning](https://semver.org/).
+
+## 1.0.0
+
+Initial release. Extracted from the Callsy infrastructure repositories, where the construct
+had already been running in production.
+
+- `SecureParameter` — one encrypted SecureString parameter, written once with a placeholder
+  and never rewritten by a later deploy.
+- One IAM role per stack, granted over the whole parameter prefix rather than per parameter.
+- `SecureParameter.build_name` — the full name a parameter carries under a prefix.
+- `SecureParameter.chain` — serialises a group of parameters so Parameter Store does not throttle.
+- `SecureParameter.as_string_parameter` / `as_ecs_secret` — read the deployed value at runtime.
+- New over the in-repo version: an explicit `prefix` instead of a repository local config
+  object, plus `tags`, `placeholder`, `key_id`, `tier` and `ignore_existing` options.

callsy_cdk_secure_parameter-1.0.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Laimonas Sutkus
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

callsy_cdk_secure_parameter-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: callsy-cdk-secure-parameter
+Version: 1.0.0
+Summary: AWS CDK construct that creates an encrypted SSM parameter a deploy never overwrites.
+Project-URL: Homepage, https://github.com/CallsyAI/callsy-cdk-secure-parameter
+Project-URL: Repository, https://github.com/CallsyAI/callsy-cdk-secure-parameter
+Project-URL: Changelog, https://github.com/CallsyAI/callsy-cdk-secure-parameter/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/CallsyAI/callsy-cdk-secure-parameter/issues
+Author: Laimonas Sutkus
+License-Expression: ISC
+License-File: LICENSE
+Keywords: aws,cdk,cloudformation,custom-resource,parameter-store,secrets,securestring,ssm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aws-cdk-lib<3.0.0,>=2.180.0
+Requires-Dist: constructs<11.0.0,>=10.0.0
+Description-Content-Type: text/markdown
+
+# callsy-cdk-secure-parameter
+
+An AWS CDK construct that creates an encrypted SSM SecureString parameter, writes a placeholder into it once, and then never touches the value again. Populate it by hand, redeploy as often as you like, and the secret stays where you put it.
+
+## Features
+
+- **Write-once semantics** — the parameter is created with a placeholder and has no update call. A later deploy can never rewrite a value you filled in by hand.
+- **Secrets never touch your repository** — no value passes through the codebase, through git, or through a CloudFormation template.
+- **Encrypted at rest** — every parameter is a `SecureString`, encrypted with the account default KMS key or one of your own.
+- **One IAM role per stack** — a single role is shared by every parameter and granted over the whole prefix. A grant per parameter races IAM propagation; this one does not.
+- **Safe deletes** — removing the stack removes the parameter, and a parameter already deleted by hand does not wedge the delete.
+- **Throttle-aware** — `SecureParameter.chain()` serialises a group of parameters, because Parameter Store throttles a burst of concurrent writes.
+- **Reads its own value back** — `as_string_parameter()` and `as_ecs_secret()` hand the deployed parameter to whatever consumes it, resolved at runtime rather than at synthesis.
+- **No Lambda, no Docker, no bundling** — built on the CDK's own `AwsCustomResource` singleton.
+- **Typed** — ships a `py.typed` marker, so mypy and your IDE see the full signature.
+
+## Installation
+
+```bash
+pip install callsy-cdk-secure-parameter
+```
+
+**Requirements:** Python >= 3.10, `aws-cdk-lib` >= 2.180.0.
+
+## Quick start
+
+```python
+from aws_cdk import Stack
+from callsy_cdk.secure_parameter import SecureParameter
+
+class SecretsStack(Stack):
+    def __init__(self, scope):
+        super().__init__(scope, "SecretsStack")
+
+        SecureParameter(
+            scope=self,
+            name="STRIPE_SECRET_KEY",
+            description="Stripe secret key used by the billing service.",
+            prefix="MyProject"
+        )
+```
+
+Deploy, and you have `/MyProject/STRIPE_SECRET_KEY` in Parameter Store, encrypted, holding the placeholder `-`. Open the console (or run `aws ssm put-parameter --overwrite`) and set the real value once. Every deploy after that leaves it alone.
+
+## How the value is managed
+
+This is the whole point of the construct, so it is worth being explicit about what happens on each CloudFormation event.
+
+| Event | What the construct does |
+|---|---|
+| **Create** | `ssm:PutParameter` with `Overwrite: false`, `Type: SecureString`, and the placeholder as the value. |
+| **Update** | **Nothing.** No update call is registered, so a deploy can never overwrite the value you set by hand. |
+| **Delete** | `ssm:DeleteParameter`. A `ParameterNotFound` error is tolerated, so a parameter you already removed does not block the delete. |
+
+Two consequences worth knowing:
+
+- **Changing `description` in code does nothing.** Because there is no update call, the description in Parameter Store keeps whatever it was given at create time. This is the deliberate cost of never rewriting the value.
+- **A parameter that already exists fails the create.** `Overwrite: false` means `PutParameter` raises `ParameterAlreadyExists`, which is usually what you want — it stops a deploy from silently adopting a parameter it does not own. If a rolled-back stack has left one behind, pass `ignore_existing=True` to adopt it instead.
+
+## Naming and the prefix
+
+Every parameter is named `/<prefix>/<name>`:
+
+```python
+SecureParameter(scope=stack, name="STRIPE_SECRET_KEY", description="...", prefix="MyProject")
+# -> /MyProject/STRIPE_SECRET_KEY
+```
+
+The prefix is what the shared IAM role is granted over (`arn:aws:ssm:<region>:<account>:parameter/MyProject/*`), and it is the default value of the `Project` tag. Use one prefix per project and environment, e.g. `MyProjectProd` and `MyProjectDev`.
+
+If you already carry a project prefix in your own config, a thin wrapper keeps every call site short:
+
+```python
+def project_parameter(scope: Stack, name: str, description: str) -> SecureParameter:
+    """
+    Returns one secure parameter under this project's prefix.
+    """
+    return SecureParameter(scope=scope, name=name, description=description, prefix=config.prefix)
+```
+
+## Grouping parameters
+
+Parameter Store throttles a burst of concurrent writes, and a stack with dozens of parameters will hit it. `chain()` makes each parameter depend on the one before it, so CloudFormation creates them one at a time.
+
+```python
+from callsy_cdk.secure_parameter import SecureParameter
+
+parameters = [
+    SecureParameter(scope=self, name="STRIPE_SECRET_KEY", description="...", prefix=prefix),
+    SecureParameter(scope=self, name="STRIPE_WEBHOOK_SECRET", description="...", prefix=prefix),
+    SecureParameter(scope=self, name="TWILIO_AUTH_TOKEN", description="...", prefix=prefix)
+]
+
+SecureParameter.chain(parameters)
+```
+
+## Reading the value back
+
+The deployed value is never resolved at synthesis. These helpers hand the parameter to a consumer that reads it at runtime.
+
+```python
+# As a CDK parameter, for anything that takes an IStringParameter.
+parameter = secure_parameter.as_string_parameter(scope=self)
+
+# As a container secret, injected as an environment variable when the task starts.
+container.add_container(
+    "App",
+    secrets={"STRIPE_SECRET_KEY": secure_parameter.as_ecs_secret(scope=self)}
+)
+```
+
+Both helpers set `simple_name=False`, because the full name holds a slash and is therefore a path. Left undetected, the rendered ARN carries a doubled slash and matches nothing.
+
+## API
+
+### `SecureParameter(scope, name, description, *, prefix, ...)`
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `scope` | `Stack` | — | The stack the parameter belongs to. The shared IAM role is built here. |
+| `name` | `str` | — | The parameter name, appended to the prefix. A slash is allowed and is stripped from the construct id. |
+| `description` | `str` | — | What the parameter holds. Set at create and never updated. |
+| `prefix` | `str` | — | The project prefix. Keyword-only. |
+| `tags` | `Mapping[str, str] \| None` | `{"Project": prefix}` | Tags applied to the parameter. |
+| `placeholder` | `str` | `"-"` | The value written at create. |
+| `key_id` | `str \| None` | `None` | KMS key id or alias. The account default key is used when omitted. |
+| `tier` | `str \| None` | `None` | One of `Standard`, `Advanced` or `Intelligent-Tiering`. |
+| `ignore_existing` | `bool` | `False` | Tolerate `ParameterAlreadyExists` on create, adopting a parameter left behind by a rolled-back stack. |
+
+**Attributes**
+
+| Attribute | Type | Description |
+|---|---|---|
+| `parameter_name` | `str` | The full name, `/<prefix>/<name>`. |
+| `prefix` | `str` | The prefix this parameter was built with. |
+
+**Methods**
+
+| Method | Signature | Description |
+|---|---|---|
+| `build_name` | `build_name(prefix: str, name: str) -> str` | Static. The full name a parameter carries under a prefix, without building anything. |
+| `chain` | `chain(parameters: Sequence[SecureParameter]) -> None` | Static. Makes each parameter wait for the one before it. |
+| `as_string_parameter` | `as_string_parameter(scope, id=None) -> IStringParameter` | The deployed parameter, for anything taking an `IStringParameter`. |
+| `as_ecs_secret` | `as_ecs_secret(scope, id=None) -> EcsSecret` | The deployed parameter, as a container secret. |
+
+`SecureParameter` extends `AwsCustomResource`, so the whole construct API (`node`, `add_dependency`, and the rest) is available as usual.
+
+### `get_role(scope, prefix) -> Role`
+
+The IAM role every parameter of a stack shares, built on first use under the construct id `SecureParameterRole` and reused after that. Each new prefix widens its policy exactly once. Call it directly only if you need to grant the role something extra.
+
+## IAM
+
+The shared role is a Lambda execution role with `AWSLambdaBasicExecutionRole` and one statement per prefix:
+
+```
+ssm:PutParameter
+ssm:AddTagsToResource
+ssm:DeleteParameter
+    on arn:aws:ssm:<region>:<account>:parameter/<prefix>/*
+```
+
+It holds no `ssm:GetParameter`, so the custom resource can create and delete a parameter but can never read one back.
+
+## License
+
+ISC

callsy_cdk_secure_parameter-1.0.0/README.md

@@ -0,0 +1,167 @@
+# callsy-cdk-secure-parameter
+
+An AWS CDK construct that creates an encrypted SSM SecureString parameter, writes a placeholder into it once, and then never touches the value again. Populate it by hand, redeploy as often as you like, and the secret stays where you put it.
+
+## Features
+
+- **Write-once semantics** — the parameter is created with a placeholder and has no update call. A later deploy can never rewrite a value you filled in by hand.
+- **Secrets never touch your repository** — no value passes through the codebase, through git, or through a CloudFormation template.
+- **Encrypted at rest** — every parameter is a `SecureString`, encrypted with the account default KMS key or one of your own.
+- **One IAM role per stack** — a single role is shared by every parameter and granted over the whole prefix. A grant per parameter races IAM propagation; this one does not.
+- **Safe deletes** — removing the stack removes the parameter, and a parameter already deleted by hand does not wedge the delete.
+- **Throttle-aware** — `SecureParameter.chain()` serialises a group of parameters, because Parameter Store throttles a burst of concurrent writes.
+- **Reads its own value back** — `as_string_parameter()` and `as_ecs_secret()` hand the deployed parameter to whatever consumes it, resolved at runtime rather than at synthesis.
+- **No Lambda, no Docker, no bundling** — built on the CDK's own `AwsCustomResource` singleton.
+- **Typed** — ships a `py.typed` marker, so mypy and your IDE see the full signature.
+
+## Installation
+
+```bash
+pip install callsy-cdk-secure-parameter
+```
+
+**Requirements:** Python >= 3.10, `aws-cdk-lib` >= 2.180.0.
+
+## Quick start
+
+```python
+from aws_cdk import Stack
+from callsy_cdk.secure_parameter import SecureParameter
+
+class SecretsStack(Stack):
+    def __init__(self, scope):
+        super().__init__(scope, "SecretsStack")
+
+        SecureParameter(
+            scope=self,
+            name="STRIPE_SECRET_KEY",
+            description="Stripe secret key used by the billing service.",
+            prefix="MyProject"
+        )
+```
+
+Deploy, and you have `/MyProject/STRIPE_SECRET_KEY` in Parameter Store, encrypted, holding the placeholder `-`. Open the console (or run `aws ssm put-parameter --overwrite`) and set the real value once. Every deploy after that leaves it alone.
+
+## How the value is managed
+
+This is the whole point of the construct, so it is worth being explicit about what happens on each CloudFormation event.
+
+| Event | What the construct does |
+|---|---|
+| **Create** | `ssm:PutParameter` with `Overwrite: false`, `Type: SecureString`, and the placeholder as the value. |
+| **Update** | **Nothing.** No update call is registered, so a deploy can never overwrite the value you set by hand. |
+| **Delete** | `ssm:DeleteParameter`. A `ParameterNotFound` error is tolerated, so a parameter you already removed does not block the delete. |
+
+Two consequences worth knowing:
+
+- **Changing `description` in code does nothing.** Because there is no update call, the description in Parameter Store keeps whatever it was given at create time. This is the deliberate cost of never rewriting the value.
+- **A parameter that already exists fails the create.** `Overwrite: false` means `PutParameter` raises `ParameterAlreadyExists`, which is usually what you want — it stops a deploy from silently adopting a parameter it does not own. If a rolled-back stack has left one behind, pass `ignore_existing=True` to adopt it instead.
+
+## Naming and the prefix
+
+Every parameter is named `/<prefix>/<name>`:
+
+```python
+SecureParameter(scope=stack, name="STRIPE_SECRET_KEY", description="...", prefix="MyProject")
+# -> /MyProject/STRIPE_SECRET_KEY
+```
+
+The prefix is what the shared IAM role is granted over (`arn:aws:ssm:<region>:<account>:parameter/MyProject/*`), and it is the default value of the `Project` tag. Use one prefix per project and environment, e.g. `MyProjectProd` and `MyProjectDev`.
+
+If you already carry a project prefix in your own config, a thin wrapper keeps every call site short:
+
+```python
+def project_parameter(scope: Stack, name: str, description: str) -> SecureParameter:
+    """
+    Returns one secure parameter under this project's prefix.
+    """
+    return SecureParameter(scope=scope, name=name, description=description, prefix=config.prefix)
+```
+
+## Grouping parameters
+
+Parameter Store throttles a burst of concurrent writes, and a stack with dozens of parameters will hit it. `chain()` makes each parameter depend on the one before it, so CloudFormation creates them one at a time.
+
+```python
+from callsy_cdk.secure_parameter import SecureParameter
+
+parameters = [
+    SecureParameter(scope=self, name="STRIPE_SECRET_KEY", description="...", prefix=prefix),
+    SecureParameter(scope=self, name="STRIPE_WEBHOOK_SECRET", description="...", prefix=prefix),
+    SecureParameter(scope=self, name="TWILIO_AUTH_TOKEN", description="...", prefix=prefix)
+]
+
+SecureParameter.chain(parameters)
+```
+
+## Reading the value back
+
+The deployed value is never resolved at synthesis. These helpers hand the parameter to a consumer that reads it at runtime.
+
+```python
+# As a CDK parameter, for anything that takes an IStringParameter.
+parameter = secure_parameter.as_string_parameter(scope=self)
+
+# As a container secret, injected as an environment variable when the task starts.
+container.add_container(
+    "App",
+    secrets={"STRIPE_SECRET_KEY": secure_parameter.as_ecs_secret(scope=self)}
+)
+```
+
+Both helpers set `simple_name=False`, because the full name holds a slash and is therefore a path. Left undetected, the rendered ARN carries a doubled slash and matches nothing.
+
+## API
+
+### `SecureParameter(scope, name, description, *, prefix, ...)`
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `scope` | `Stack` | — | The stack the parameter belongs to. The shared IAM role is built here. |
+| `name` | `str` | — | The parameter name, appended to the prefix. A slash is allowed and is stripped from the construct id. |
+| `description` | `str` | — | What the parameter holds. Set at create and never updated. |
+| `prefix` | `str` | — | The project prefix. Keyword-only. |
+| `tags` | `Mapping[str, str] \| None` | `{"Project": prefix}` | Tags applied to the parameter. |
+| `placeholder` | `str` | `"-"` | The value written at create. |
+| `key_id` | `str \| None` | `None` | KMS key id or alias. The account default key is used when omitted. |
+| `tier` | `str \| None` | `None` | One of `Standard`, `Advanced` or `Intelligent-Tiering`. |
+| `ignore_existing` | `bool` | `False` | Tolerate `ParameterAlreadyExists` on create, adopting a parameter left behind by a rolled-back stack. |
+
+**Attributes**
+
+| Attribute | Type | Description |
+|---|---|---|
+| `parameter_name` | `str` | The full name, `/<prefix>/<name>`. |
+| `prefix` | `str` | The prefix this parameter was built with. |
+
+**Methods**
+
+| Method | Signature | Description |
+|---|---|---|
+| `build_name` | `build_name(prefix: str, name: str) -> str` | Static. The full name a parameter carries under a prefix, without building anything. |
+| `chain` | `chain(parameters: Sequence[SecureParameter]) -> None` | Static. Makes each parameter wait for the one before it. |
+| `as_string_parameter` | `as_string_parameter(scope, id=None) -> IStringParameter` | The deployed parameter, for anything taking an `IStringParameter`. |
+| `as_ecs_secret` | `as_ecs_secret(scope, id=None) -> EcsSecret` | The deployed parameter, as a container secret. |
+
+`SecureParameter` extends `AwsCustomResource`, so the whole construct API (`node`, `add_dependency`, and the rest) is available as usual.
+
+### `get_role(scope, prefix) -> Role`
+
+The IAM role every parameter of a stack shares, built on first use under the construct id `SecureParameterRole` and reused after that. Each new prefix widens its policy exactly once. Call it directly only if you need to grant the role something extra.
+
+## IAM
+
+The shared role is a Lambda execution role with `AWSLambdaBasicExecutionRole` and one statement per prefix:
+
+```
+ssm:PutParameter
+ssm:AddTagsToResource
+ssm:DeleteParameter
+    on arn:aws:ssm:<region>:<account>:parameter/<prefix>/*
+```
+
+It holds no `ssm:GetParameter`, so the custom resource can create and delete a parameter but can never read one back.
+
+## License
+
+ISC

callsy_cdk_secure_parameter-1.0.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "callsy-cdk-secure-parameter"
+version = "1.0.0"
+description = "AWS CDK construct that creates an encrypted SSM parameter a deploy never overwrites."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "ISC"
+license-files = ["LICENSE"]
+authors = [{ name = "Laimonas Sutkus" }]
+keywords = [
+    "aws",
+    "cdk",
+    "cloudformation",
+    "ssm",
+    "parameter-store",
+    "securestring",
+    "custom-resource",
+    "secrets",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aws-cdk-lib>=2.180.0,<3.0.0",
+    "constructs>=10.0.0,<11.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CallsyAI/callsy-cdk-secure-parameter"
+Repository = "https://github.com/CallsyAI/callsy-cdk-secure-parameter"
+Changelog = "https://github.com/CallsyAI/callsy-cdk-secure-parameter/blob/main/CHANGELOG.md"
+Issues = "https://github.com/CallsyAI/callsy-cdk-secure-parameter/issues"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18",
+    "ruff>=0.14",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/callsy_cdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 120
+src = ["src"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4", "SIM", "RUF"]
+ignore = [
+    # A single line `if ...: return` is the established style of this codebase.
+    "E701",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+mypy_path = "src"
+namespace_packages = true
+explicit_package_bases = true

callsy_cdk_secure_parameter-1.0.0/src/callsy_cdk/secure_parameter/__init__.py

@@ -0,0 +1,17 @@
+from callsy_cdk.secure_parameter.role import ROLE_ACTIONS, ROLE_ID, get_role
+from callsy_cdk.secure_parameter.secure_parameter import (
+    PARAMETER_ALREADY_EXISTS,
+    PARAMETER_NOT_FOUND,
+    PLACEHOLDER,
+    SecureParameter,
+)
+
+__all__ = [
+    "PARAMETER_ALREADY_EXISTS",
+    "PARAMETER_NOT_FOUND",
+    "PLACEHOLDER",
+    "ROLE_ACTIONS",
+    "ROLE_ID",
+    "SecureParameter",
+    "get_role",
+]

callsy_cdk_secure_parameter-1.0.0/src/callsy_cdk/secure_parameter/role.py

@@ -0,0 +1,66 @@
+import re
+from typing import cast
+
+from aws_cdk import Stack
+from aws_cdk.aws_iam import ManagedPolicy, PolicyStatement, Role, ServicePrincipal
+from constructs import Construct
+
+# Construct id of the role that every secure parameter of a stack shares.
+ROLE_ID = "SecureParameterRole"
+
+# Actions the role needs to create, tag and remove one parameter.
+ROLE_ACTIONS = ["ssm:PutParameter", "ssm:AddTagsToResource", "ssm:DeleteParameter"]
+
+
+def get_role(scope: Stack, prefix: str) -> Role:
+    """
+    Returns the role that writes every secure parameter of this stack.
+    The role is built once and reused, and each new prefix widens its policy once.
+    """
+    existing = scope.node.try_find_child(ROLE_ID)
+    role = cast(Role, existing) if existing is not None else _create_role(scope)
+
+    _grant_prefix(scope=scope, role=role, prefix=prefix)
+
+    return role
+
+
+def _create_role(scope: Stack) -> Role:
+    """
+    Builds the role the custom resource assumes while it writes a parameter.
+    """
+    return Role(
+        scope=scope,
+        id=ROLE_ID,
+        assumed_by=ServicePrincipal("lambda.amazonaws.com"),
+        managed_policies=[
+            ManagedPolicy.from_aws_managed_policy_name("service-role/AWSLambdaBasicExecutionRole")
+        ]
+    )
+
+
+def _grant_prefix(scope: Stack, role: Role, prefix: str) -> None:
+    """
+    Grants the role every parameter under one prefix, and does so once per prefix.
+    One grant covers the whole prefix because a grant per parameter races IAM propagation.
+    """
+    # An empty construct marks the prefix as granted. The stack tree is the one place that
+    # outlives two parameters built far apart in the same synthesis.
+    marker_id = f"{ROLE_ID}Grant{re.sub(r'[^A-Za-z0-9]', '', prefix)}"
+
+    if scope.node.try_find_child(marker_id) is not None: return
+
+    Construct(scope=scope, id=marker_id)
+
+    role.add_to_policy(
+        PolicyStatement(
+            actions=ROLE_ACTIONS,
+            resources=[
+                scope.format_arn(
+                    service="ssm",
+                    resource="parameter",
+                    resource_name=f"{prefix}/*"
+                )
+            ]
+        )
+    )

callsy_cdk_secure_parameter-1.0.0/src/callsy_cdk/secure_parameter/secure_parameter.py

@@ -0,0 +1,133 @@
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from aws_cdk import Stack
+from aws_cdk.aws_ecs import Secret as EcsSecret
+from aws_cdk.aws_ssm import IStringParameter, StringParameter
+from aws_cdk.custom_resources import AwsCustomResource, AwsSdkCall, PhysicalResourceId
+from constructs import Construct
+
+from callsy_cdk.secure_parameter.role import get_role
+
+# Value written at create. The real value is filled in by hand afterwards.
+PLACEHOLDER = "-"
+
+# Error the delete call tolerates, so a parameter removed by hand does not wedge a stack.
+PARAMETER_NOT_FOUND = "ParameterNotFound"
+
+# Error the create call tolerates when `ignore_existing` is set, so a parameter left behind
+# by a rolled back stack does not block the next deploy.
+PARAMETER_ALREADY_EXISTS = "ParameterAlreadyExists"
+
+
+class SecureParameter(AwsCustomResource):
+    """
+    Creates one encrypted parameter in Parameter Store.
+    The value is written once and later deploys leave it alone.
+    The parameter is removed when the stack is deleted.
+    """
+
+    def __init__(
+            self,
+            scope: Stack,
+            name: str,
+            description: str,
+            *,
+            prefix: str,
+            tags: Mapping[str, str] | None = None,
+            placeholder: str = PLACEHOLDER,
+            key_id: str | None = None,
+            tier: str | None = None,
+            ignore_existing: bool = False
+    ) -> None:
+        parameter_name = self.build_name(prefix=prefix, name=name)
+
+        # Tag this custom resource with a project prefix (as the rest of the resources).
+        parameter_tags = dict(tags) if tags is not None else {"Project": prefix}
+
+        parameters: dict[str, Any] = {
+            "Name": parameter_name,
+            "Description": description,
+            "Value": placeholder,
+            "Type": "SecureString",
+            # Never override the value as they are populated manually.
+            "Overwrite": False,
+            "Tags": [{"Key": key, "Value": value} for key, value in parameter_tags.items()]
+        }
+
+        # The account default key encrypts the parameter when no key is named.
+        if key_id is not None: parameters["KeyId"] = key_id
+
+        # One of `Standard`, `Advanced` or `Intelligent-Tiering`.
+        if tier is not None: parameters["Tier"] = tier
+
+        # SecureString is written through the SSM API.
+        create_call = AwsSdkCall(
+            service="SSM",
+            action="putParameter",
+            parameters=parameters,
+            physical_resource_id=PhysicalResourceId.of(parameter_name),
+            ignore_error_codes_matching=PARAMETER_ALREADY_EXISTS if ignore_existing else None
+        )
+
+        delete_call = AwsSdkCall(
+            service="SSM",
+            action="deleteParameter",
+            parameters={"Name": parameter_name},
+            # A parameter removed by hand must not wedge the stack.
+            ignore_error_codes_matching=PARAMETER_NOT_FOUND
+        )
+
+        super().__init__(
+            scope=scope,
+            # A construct id can not hold the slash that separates the provider from the key.
+            id=name.replace("/", ""),
+            # No `update` call is given. A deploy must never rewrite a populated value.
+            on_create=create_call,
+            on_delete=delete_call,
+            role=get_role(scope=scope, prefix=prefix),
+            install_latest_aws_sdk=False
+        )
+
+        self.prefix = prefix
+        self.parameter_name = parameter_name
+
+    @staticmethod
+    def build_name(prefix: str, name: str) -> str:
+        """
+        Returns the full name a parameter carries under one prefix.
+        """
+        return f"/{prefix}/{name}"
+
+    @staticmethod
+    def chain(parameters: Sequence["SecureParameter"]) -> None:
+        """
+        Makes each parameter wait for the one before it.
+        Parameter Store throttles a burst of writes, so they are created one after another.
+        """
+        previous: SecureParameter | None = None
+
+        for parameter in parameters:
+            if previous is not None: parameter.node.add_dependency(previous)
+            previous = parameter
+
+    def as_string_parameter(self, scope: Construct, id: str | None = None) -> IStringParameter:
+        """
+        Returns the deployed parameter, read by whatever consumes it.
+        The value is never resolved at synthesis.
+        """
+        return StringParameter.from_secure_string_parameter_attributes(
+            scope=scope,
+            id=id or f"{self.node.id}Parameter",
+            parameter_name=self.parameter_name,
+            # The full name holds a slash, so it is a path and not a simple name. Left
+            # undetected, the rendered arn carries a doubled slash and matches nothing.
+            simple_name=False
+        )
+
+    def as_ecs_secret(self, scope: Construct, id: str | None = None) -> EcsSecret:
+        """
+        Returns the container secret that reads this parameter.
+        The container reads the value when it starts, never at synthesis.
+        """
+        return EcsSecret.from_ssm_parameter(self.as_string_parameter(scope=scope, id=id))