cdk-ssm-refs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanielCaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# cdk-ssm-refs
+
+Typed registry for AWS Systems Manager parameters and Secrets Manager secrets in AWS CDK.
+
+Declare your parameters and secrets once, and get a consistent path prefix, compile-time
+checked keys, ready-made dynamic references, and IAM read policies scoped to exactly that
+prefix.
+
+## Install
+
+```bash
+bun add cdk-ssm-refs
+```
+
+`aws-cdk-lib`, `constructs`, and `typescript` are peer dependencies, so your CDK app
+supplies them.
+
+## Usage
+
+```ts
+import { defineParamRegistry } from 'cdk-ssm-refs';
+
+export const params = defineParamRegistry({
+  prefix: '/team/my-app', // must start with '/'; trailing slashes are ignored
+  parameters: {
+    vpcId: 'vpc-id',
+    subnetIds: 'subnet-ids',
+  },
+  secrets: {
+    dbPassword: 'db-password',
+  },
+});
+```
+
+The keys of `parameters` and `secrets` are the only values accepted by the `key` argument
+of every method, so an unknown key is a compile error.
+
+### Writing parameters
+
+```ts
+import { ParameterTier } from 'aws-cdk-lib/aws-ssm';
+
+// Creates /team/my-app/vpc-id
+params.putParameter(this, 'VpcIdParam', 'vpcId', vpc.vpcId);
+
+// Any other StringParameterProps are passed through
+params.putParameter(this, 'SubnetIdsParam', 'subnetIds', subnetIds.join(','), {
+  description: 'Private subnet ids',
+  tier: ParameterTier.STANDARD,
+});
+```
+
+`putParameter` returns the `StringParameter` it creates, so you can keep working with the
+construct. To pin one, call `applyRemovalPolicy(RemovalPolicy.RETAIN)` on the return value,
+importing `RemovalPolicy` from `aws-cdk-lib/core`.
+
+### Emitting stack outputs
+
+```ts
+const params = defineParamRegistry({
+  prefix: '/team/my-app',
+  parameters: { vpcId: 'vpc-id' },
+  emitOutputs: true,
+});
+
+params.putParameter(this, 'VpcIdParam', 'vpcId', vpc.vpcId);
+// Also creates a CfnOutput from the construct id 'VpcIdParam-output'
+```
+
+With `emitOutputs` enabled every `putParameter` call additionally emits a `CfnOutput` whose
+value is the raw parameter value. See the caveats below before turning this on.
+
+### Reading parameters from another stack
+
+```ts
+// '{{resolve:ssm:/team/my-app/vpc-id}}'
+const vpcId = params.parameterRef('vpcId');
+
+// Pinned to a specific version, for drift detection
+const pinned = params.parameterRef('vpcId', { version: 3 });
+
+// Encrypted reference - requires a SecureString parameter
+const secure = params.secureParameterRef('vpcId');
+```
+
+### Secrets
+
+```ts
+const secret = params.createSecret(this, 'DbPassword', 'dbPassword', {
+  description: 'Database password',
+  generateSecretString: { excludePunctuation: true },
+});
+
+// Use secret.secretValue directly within the creating stack
+```
+
+### IAM read policies
+
+```ts
+import { Stack } from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+
+const role = new iam.Role(this, 'Reader', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+});
+
+// ssm:GetParameter(s) plus secretsmanager:GetSecretValue, both scoped
+// to the registry prefix in the region and account of the stack.
+for (const statement of params.readPolicyStatements(Stack.of(this))) {
+  role.addToPolicy(statement);
+}
+```
+
+The ARN patterns are also exposed on their own via `parameterArnPattern(stack)` and
+`secretArnPattern(stack)` if you need to build a different policy.
+
+## API
+
+| Member                                                            | Description                                                      |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `defineParamRegistry(config)`                                     | Creates a `ParamRegistry`.                                       |
+| `ParamRegistry`                                                   | The class itself, if you need it as a type.                      |
+| `config.prefix`                                                   | Path prefix. Must start with `/`; trailing slashes ignored.      |
+| `config.parameters`                                               | Key to path-segment map for SSM parameters.                      |
+| `config.secrets`                                                  | Key to path-segment map for Secrets Manager secrets. Optional.   |
+| `config.emitOutputs`                                              | Emit a `CfnOutput` per `putParameter` call. Defaults to `false`. |
+| `parameterName(key)` → `string`                                   | Fully qualified parameter name, e.g. `/team/my-app/vpc-id`.      |
+| `putParameter(scope, id, key, value, props?)` → `StringParameter` | Creates a `StringParameter`.                                     |
+| `parameterRef(key, options?)` → `string`                          | `{{resolve:ssm:...}}` dynamic reference.                         |
+| `secureParameterRef(key, options?)` → `string`                    | `{{resolve:ssm-secure:...}}` dynamic reference.                  |
+| `createSecret(scope, id, key, props?)` → `Secret`                 | Creates a `Secret`.                                              |
+| `parameterArnPattern(stack)` → `string`                           | ARN pattern for every parameter under the prefix.                |
+| `secretArnPattern(stack)` → `string`                              | ARN pattern for every secret under the prefix.                   |
+| `readPolicyStatements(stack)` → `PolicyStatement[]`               | Read-only IAM statements for both patterns.                      |
+| `normalizePrefix(prefix)` → `{ withSlash, withoutSlash }`         | Low-level prefix normalizer used by the constructor.             |
+
+`ParamRegistryConfig` and `DynamicRefOptions` are also exported as types, for annotating
+your own helpers.
+
+## Caveats
+
+- **`prefix` must start with `/`.** `defineParamRegistry` throws on `'team/my-app'`, so write
+  `'/team/my-app'`. Trailing slashes are ignored, and empty segments (`//`) are rejected.
+- **Dynamic references resolve at deploy time.** The parameter must already exist in the
+  target account and region, so calling `putParameter` and `parameterRef` for the same
+  key in one stack will not work — the reference is resolved before the parameter is
+  created.
+- **References are not version-pinned by default.** `parameterRef('vpcId')` resolves
+  whatever version is current at deploy time and will not report drift when the value
+  changes. Pass `{ version }` if you want that.
+- **`version` must be an integer from 1 to 100.** CloudFormation accepts no other
+  parameter versions, so `parameterRef('vpcId', { version: 0 })` throws.
+- **`emitOutputs` writes the value into the template.** Each `CfnOutput` carries the raw
+  parameter value, which anyone who can read the stack can see, so leave it off for
+  sensitive values. CloudFormation logical ids cannot contain `-`, so CDK strips it during
+  synthesis and the `'VpcIdParam-output'` construct id is deployed as `VpcIdParamoutput`.
+- **`secureParameterRef` requires a `SecureString` parameter.** Plain `String`
+  parameters cannot be read through `ssm-secure`.
+- **Secret names get a random suffix.** CloudFormation appends six characters to every
+  secret name it creates, so a secret cannot be looked up by its exact name from another
+  stack.
+- **`StringParameterProps` has no `removalPolicy`.** Call
+  `parameter.applyRemovalPolicy(...)` on the construct returned by `putParameter`
+  instead.
+- **`readPolicyStatements` grants `GetParameter`/`GetParameters` only.** Add
+  `ssm:GetParametersByPath` yourself if you load the whole subtree by path.
+- **ARN patterns are pinned to the `aws` partition.** `parameterArnPattern` and
+  `secretArnPattern` return `arn:aws:...` strings built from the stack's region and account,
+  with no partition lookup, feature flag or partition pseudo parameter involved, so for a
+  stack with an explicit environment they are plain strings that are easy to assert on.
+- **ESM only.** The package ships ESM and requires Node >= 20.19.0, which is the
+  first release where `require(esm)` works without a flag.
+
+## Development
+
+```bash
+bun install
+bun run test
+bun run typecheck
+bun run build
+```
+
+# License
+
+MIT License
+
+# Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub. Make sure to follow the existing code style and include tests for any new functionality.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineParamRegistry, ParamRegistry } from './registry.js';
+export { normalizePrefix } from './paths.js';
+export type { DynamicRefOptions, ParamRegistryConfig } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/registry.ts
+import * as cdk from "aws-cdk-lib/core";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as sm from "aws-cdk-lib/aws-secretsmanager";
+import * as ssm from "aws-cdk-lib/aws-ssm";
+
+// src/paths.ts
+function normalizePrefix(prefix) {
+  if (!prefix.startsWith("/")) {
+    throw new Error(`[cdk-ssm-refs] prefix must start with "/", received ${JSON.stringify(prefix)}`);
+  }
+  const trimmed = prefix.replace(/\/+$/, "");
+  if (trimmed.length === 0) {
+    throw new Error(`[cdk-ssm-refs] prefix must contain at least one path segment, received ${JSON.stringify(prefix)}`);
+  }
+  if (trimmed.includes("//")) {
+    throw new Error(`[cdk-ssm-refs] prefix must not contain empty path segments, received ${JSON.stringify(prefix)}`);
+  }
+  return { withSlash: trimmed, withoutSlash: trimmed.slice(1) };
+}
+
+// src/registry.ts
+var MIN_PARAM_VERSION = 1;
+var MAX_PARAM_VERSION = 100;
+
+class ParamRegistry {
+  config;
+  parameterPath;
+  arnPath;
+  emitOutputs;
+  constructor(config) {
+    this.config = config;
+    const { withSlash, withoutSlash } = normalizePrefix(config.prefix);
+    this.parameterPath = withSlash;
+    this.arnPath = withoutSlash;
+    this.emitOutputs = config.emitOutputs ?? false;
+  }
+  parameterName(key) {
+    const segment = this.config.parameters[key];
+    if (typeof segment !== "string" || segment.length === 0) {
+      throw new Error(`[cdk-ssm-refs] unknown parameter key: ${String(key)}`);
+    }
+    return `${this.parameterPath}/${segment}`;
+  }
+  putParameter(scope, id, key, value, props = {}) {
+    const parameterName = this.parameterName(key);
+    const parameter = new ssm.StringParameter(scope, `${id}-param`, {
+      ...props,
+      parameterName,
+      stringValue: value
+    });
+    if (this.emitOutputs) {
+      new cdk.CfnOutput(scope, `${id}-output`, {
+        value,
+        description: parameterName
+      });
+    }
+    return parameter;
+  }
+  parameterRef(key, options = {}) {
+    return this.dynamicRef("ssm", key, options);
+  }
+  secureParameterRef(key, options = {}) {
+    return this.dynamicRef("ssm-secure", key, options);
+  }
+  dynamicRef(service, key, options) {
+    const { version } = options;
+    if (version !== undefined && (!Number.isInteger(version) || version < MIN_PARAM_VERSION || version > MAX_PARAM_VERSION)) {
+      throw new Error(`[cdk-ssm-refs] version must be an integer between ${MIN_PARAM_VERSION} and ${MAX_PARAM_VERSION}, received ${version}`);
+    }
+    const suffix = version === undefined ? "" : `:${version}`;
+    return `{{resolve:${service}:${this.parameterName(key)}${suffix}}}`;
+  }
+  createSecret(scope, id, key, props = {}) {
+    const segment = this.config.secrets?.[key];
+    if (typeof segment !== "string" || segment.length === 0) {
+      throw new Error(`[cdk-ssm-refs] unknown secret key: ${String(key)}`);
+    }
+    return new sm.Secret(scope, `${id}-secret`, {
+      ...props,
+      secretName: `${this.parameterPath}/${segment}`
+    });
+  }
+  parameterArnPattern(stack) {
+    return `arn:aws:ssm:${stack.region}:${stack.account}:parameter/${this.arnPath}/*`;
+  }
+  secretArnPattern(stack) {
+    return `arn:aws:secretsmanager:${stack.region}:${stack.account}:secret:${this.parameterPath}/*`;
+  }
+  readPolicyStatements(stack) {
+    return [
+      new iam.PolicyStatement({
+        actions: ["ssm:GetParameter", "ssm:GetParameters"],
+        resources: [this.parameterArnPattern(stack)]
+      }),
+      new iam.PolicyStatement({
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [this.secretArnPattern(stack)]
+      })
+    ];
+  }
+}
+function defineParamRegistry(config) {
+  return new ParamRegistry(config);
+}
+export {
+  ParamRegistry,
+  defineParamRegistry,
+  normalizePrefix
+};

package/dist/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validates and normalizes an SSM / Secrets Manager path prefix.
+ *
+ * A prefix must start with `/` and contain at least one path segment, so
+ * `/team/my-app` is accepted and `team/my-app` is rejected. Trailing slashes are
+ * ignored, and empty path segments (`//`) are rejected.
+ *
+ * Returns both of the forms the AWS APIs need: the leading-slash form used in
+ * parameter and secret names, and that same value with the single leading
+ * slash removed, which is how ARN resource names are written.
+ *
+ * @throws If `prefix` does not start with `/`, has no path segment, or
+ * contains an empty path segment.
+ */
+export declare function normalizePrefix(prefix: string): {
+    withSlash: string;
+    withoutSlash: string;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,CAsBA"}

package/dist/registry.d.ts

@@ -0,0 +1,83 @@
+import type { Construct } from 'constructs';
+import * as cdk from 'aws-cdk-lib/core';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as sm from 'aws-cdk-lib/aws-secretsmanager';
+import * as ssm from 'aws-cdk-lib/aws-ssm';
+import type { DynamicRefOptions, ParamRegistryConfig } from './types.js';
+export declare class ParamRegistry<P extends Record<string, string>, S extends Record<string, string>> {
+    private readonly config;
+    private readonly parameterPath;
+    private readonly arnPath;
+    private readonly emitOutputs;
+    constructor(config: ParamRegistryConfig<P, S>);
+    /**
+     * The fully qualified SSM parameter name for `key`,
+     * e.g. `/team/my-app/vpc-id`.
+     */
+    parameterName(key: keyof P): string;
+    /**
+     * Creates an SSM `StringParameter` for `key` under the registry prefix.
+     *
+     * Any other `StringParameterProps` (`description`, `tier`,
+     * `allowedPattern`, `type`, `dataType`, ...) are passed straight through.
+     *
+     * Note that `StringParameterProps` does not accept a `removalPolicy`; call
+     * `parameter.applyRemovalPolicy(...)` on the returned construct instead.
+     */
+    putParameter(scope: Construct, id: string, key: keyof P, value: string, props?: Omit<ssm.StringParameterProps, 'parameterName' | 'stringValue'>): ssm.StringParameter;
+    /**
+     * A CloudFormation dynamic reference to the parameter, e.g.
+     * `{{resolve:ssm:/team/my-app/vpc-id}}`.
+     *
+     * Dynamic references are resolved at deploy time, so the parameter must
+     * already exist in the target account and region. Calling `putParameter` and
+     * `parameterRef` for the same key in a single stack does not work: the
+     * reference is resolved before the parameter is created.
+     */
+    parameterRef(key: keyof P, options?: DynamicRefOptions): string;
+    /**
+     * An encrypted dynamic reference to the parameter, e.g.
+     * `{{resolve:ssm-secure:/team/my-app/vpc-id}}`.
+     *
+     * The referenced parameter must have been created as a `SecureString`.
+     */
+    secureParameterRef(key: keyof P, options?: DynamicRefOptions): string;
+    private dynamicRef;
+    /**
+     * Creates a Secrets Manager secret for `key` under the registry prefix.
+     *
+     * CloudFormation appends a random six character suffix to every secret
+     * name it creates, so the resulting name is not exactly
+     * `prefix/key` and cannot be referenced by name from another stack.
+     */
+    createSecret(scope: Construct, id: string, key: keyof S, props?: Omit<sm.SecretProps, 'secretName'>): sm.Secret;
+    /**
+     * ARN pattern matching every parameter under the registry prefix, in the
+     * region and account of `stack`.
+     *
+     * The partition is fixed to `aws`, the US commercial partition, so no
+     * partition lookup, feature flag or pseudo parameter is involved. For a
+     * stack with an explicit environment the result is a plain string with no
+     * tokens in it; an environment agnostic stack still yields the
+     * `AWS::Region` and `AWS::AccountId` tokens. The pattern carries no
+     * permissions by itself: `readPolicyStatements` attaches read actions to
+     * it, and you can reuse it for custom read or write policies.
+     */
+    parameterArnPattern(stack: cdk.Stack): string;
+    /**
+     * ARN pattern matching every secret under the registry prefix.
+     *
+     * Secrets Manager separates the name from the resource type with `:`
+     * rather than `/`, hence the `secret:` prefix, and the trailing wildcard
+     * covers the suffix CloudFormation appends to each name.
+     */
+    secretArnPattern(stack: cdk.Stack): string;
+    /**
+     * Read-only IAM statements scoped to the registry prefix: `ssm:GetParameter`
+     * and `ssm:GetParameters` for the parameters, and
+     * `secretsmanager:GetSecretValue` for the secrets.
+     */
+    readPolicyStatements(stack: cdk.Stack): iam.PolicyStatement[];
+}
+export declare function defineParamRegistry<P extends Record<string, string>, S extends Record<string, string> = Record<never, string>>(config: ParamRegistryConfig<P, S>): ParamRegistry<P, S>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AACxC,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AACrD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMzE,qBAAa,aAAa,CACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;gBAET,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;IAO9D;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM;IAUnC;;;;;;;;OAQG;IACH,YAAY,CACV,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,CAAC,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,eAAe,GAAG,aAAa,CAAM,GAC1E,GAAG,CAAC,eAAe;IAmBtB;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM;IAInE;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM;IAIzE,OAAO,CAAC,UAAU;IAuBlB;;;;;;OAMG;IACH,YAAY,CACV,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,CAAC,EACZ,KAAK,GAAE,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,CAAM,GAC7C,EAAE,CAAC,MAAM;IAaZ;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,MAAM;IAI7C;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,MAAM;IAI1C;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,eAAe,EAAE;CAY9D;AAED,wBAAgB,mBAAmB,CACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,EACxD,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAExD"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration for a {@link ParamRegistry}.
+ */
+export interface ParamRegistryConfig<P extends Record<string, string> = Record<string, string>, S extends Record<string, string> = Record<never, string>> {
+    /**
+     * Path prefix shared by every parameter and secret in this registry.
+     *
+     * Must start with `/` and contain at least one path segment, so
+     * `/team/my-app` is valid while `team/my-app` throws. Trailing slashes are
+     * ignored.
+     */
+    readonly prefix: string;
+    /**
+     * Maps a logical key to the final path segment of an SSM parameter.
+     *
+     * These keys become the only values accepted by the `key` argument of
+     * {@link ParamRegistry.putParameter}, {@link ParamRegistry.parameterRef}
+     * and {@link ParamRegistry.secureParameterRef}, so an unknown key is a
+     * compile error.
+     */
+    readonly parameters: P;
+    /**
+     * Maps a logical key to the final path segment of a Secrets Manager secret.
+     *
+     * Omit this entirely if the registry has no secrets, which also makes
+     * {@link ParamRegistry.createSecret} uncallable.
+     */
+    readonly secrets?: S;
+    /**
+     * Emit a `CfnOutput` containing the raw value for every `putParameter`
+     * call.
+     *
+     * Defaults to `false`. When enabled the value is rendered into the stack
+     * outputs, where anyone with stack read access can see it, so only turn
+     * this on for non-sensitive values you actually want surfaced.
+     */
+    readonly emitOutputs?: boolean;
+}
+/**
+ * Options accepted by {@link ParamRegistry.parameterRef} and
+ * {@link ParamRegistry.secureParameterRef}.
+ */
+export interface DynamicRefOptions {
+    /**
+     * Pin the dynamic reference to a specific parameter version.
+     *
+     * Without this, CloudFormation resolves whatever version is current at
+     * deploy time and never reports drift when the value changes.
+     */
+    readonly version?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;IAExD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAErB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cdk-ssm-refs",
+  "version": "0.1.0",
+  "description": "Typed registry for SSM parameters and Secrets Manager secrets in AWS CDK.",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "bun run build"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "aws-cdk-lib": "^2.271.0",
+    "constructs": "^10.8.1",
+    "prettier": "^3.9.9",
+    "vitest": "^5.0.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3",
+    "aws-cdk-lib": "^2.271.0",
+    "constructs": "^10.8.1"
+  }
+}