@maroonedsoftware/appconfig 1.5.1 → 1.7.0

package/dist/providers/app.config.provider.aws.secrets.d.ts

@@ -0,0 +1,106 @@
+import { AppConfigProvider } from '../app.config.provider.js';
+import { ObjectVisitorMeta } from '../object.visitor.js';
+/**
+ * Provider that resolves AWS Secrets Manager references in configuration values.
+ *
+ * This provider matches string values using a regex pattern and replaces them with
+ * secrets fetched from AWS Secrets Manager. The default pattern matches `${aws:SECRET_ID}`
+ * and extracts the secret id (a name or ARN) to look up in Secrets Manager.
+ *
+ * After retrieval, the secret value is attempted to be parsed as JSON. If parsing succeeds,
+ * the parsed value is used; otherwise, the string value is used.
+ *
+ * @remarks
+ * This provider requires valid AWS credentials to be configured. It uses the
+ * `@aws-sdk/client-secrets-manager` package and resolves credentials and region from the
+ * standard AWS provider chain (environment variables, shared config/credentials files,
+ * instance/task roles). The region can be passed explicitly to override the chain.
+ *
+ * @example
+ * ```typescript
+ * // With default pattern /\$\{aws:(.+)\}/g
+ * // Value: "${aws:DATABASE_PASSWORD}"
+ * // Fetches the latest version of the "DATABASE_PASSWORD" secret
+ *
+ * const config = await new AppConfigBuilder()
+ *   .addSource(new AppConfigSourceJson('./config.json'))
+ *   .addProvider(new AppConfigProviderAwsSecrets('us-east-1'))
+ *   .build();
+ * ```
+ */
+export declare class AppConfigProviderAwsSecrets implements AppConfigProvider {
+    private readonly region?;
+    private readonly secretsManagerClient;
+    private readonly prefix;
+    /**
+     * Creates a new AppConfigProviderAwsSecrets instance.
+     *
+     * @param region - The AWS region where secrets are stored. If omitted, the region is
+     *   resolved from the standard AWS provider chain (e.g. `AWS_REGION`).
+     * @param prefix - A regex pattern or string to match secret references.
+     *   If a string is provided, it will be converted to a RegExp. The regex must have
+     *   at least one capture group that extracts the secret id.
+     *   Defaults to `/\$\{aws:(.+)\}/g` which matches `${aws:SECRET_ID}` patterns.
+     *
+     * @example
+     * ```typescript
+     * // Default pattern, region from the AWS provider chain
+     * const provider1 = new AppConfigProviderAwsSecrets();
+     *
+     * // Explicit region
+     * const provider2 = new AppConfigProviderAwsSecrets('us-east-1');
+     *
+     * // Custom regex pattern
+     * const provider3 = new AppConfigProviderAwsSecrets('us-east-1', /\$\{secret:([^}]+)\}/g);
+     * ```
+     */
+    constructor(region?: string | undefined, prefix?: string | RegExp);
+    /**
+     * Checks if this provider can parse the given value.
+     *
+     * @param value - The string value to check.
+     * @returns `true` if the value matches the provider's regex pattern, `false` otherwise.
+     */
+    canParse(value: string): boolean;
+    /**
+     * Fetches a secret from AWS Secrets Manager.
+     *
+     * @param secretId - The id (name or ARN) of the secret to fetch.
+     * @returns A promise that resolves to the secret value.
+     * @throws {ServerkitError} When Secrets Manager rejects the access request (e.g. missing
+     *   secret, IAM denial, network failure). The original error is attached via `withCause`
+     *   and the failing `secretId` / `region` are recorded in `internalDetails`. Surfacing
+     *   the failure prevents callers booting with an empty password / API key.
+     * @internal
+     */
+    private getSecret;
+    /**
+     * Parses the value by replacing AWS secret references with actual secret values.
+     *
+     * The method:
+     * 1. Finds all matches of the regex pattern in the value
+     * 2. Fetches each secret from AWS Secrets Manager in parallel
+     * 3. Attempts to parse each result as JSON
+     * 4. Updates the configuration object with the final value
+     *
+     * @param value - The string value containing AWS secret references.
+     * @param meta - Metadata about the value's location in the configuration object.
+     * @returns A promise that resolves when all secrets have been fetched and the
+     *   transformation is complete.
+     * @throws {ServerkitError} Propagated from {@link getSecret} when any referenced secret
+     *   cannot be resolved. The build call site is expected to fail loud and stop boot.
+     *
+     * @example
+     * ```typescript
+     * // If AWS secret "API_KEY" contains "sk-abc123"
+     * // Value: "${aws:API_KEY}"
+     * // Result: "sk-abc123"
+     *
+     * // If AWS secret "CONFIG" contains '{"retries": 3}'
+     * // Value: "${aws:CONFIG}"
+     * // Result: { retries: 3 } (parsed as JSON object)
+     * ```
+     */
+    parse(value: string, meta: ObjectVisitorMeta): Promise<void>;
+}
+//# sourceMappingURL=app.config.provider.aws.secrets.d.ts.map

package/dist/providers/app.config.provider.aws.secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.provider.aws.secrets.d.ts","sourceRoot":"","sources":["../../src/providers/app.config.provider.aws.secrets.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,2BAA4B,YAAW,iBAAiB;IA2BjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IA1B1B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBAEgB,MAAM,CAAC,EAAE,MAAM,YAAA,EAChC,MAAM,GAAE,MAAM,GAAG,MAA0B;IAM7C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAQhC;;;;;;;;;;OAUG;YACW,SAAS;IAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maroonedsoftware/appconfig",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "A flexible, type-safe configuration management library with support for multiple sources and value transformation.",
   "author": {
     "name": "Marooned Software",
@@ -32,16 +32,19 @@
   "dependencies": {
     "deepmerge-ts": "^7.1.5",
     "dotenv": "^17.4.2",
-    "injectkit": "^1.4.1",
-    "@maroonedsoftware/errors": "1.7.0"
+    "injectkit": "^1.4.2",
+    "@maroonedsoftware/errors": "1.7.0",
+    "@maroonedsoftware/logger": "1.1.1"
   },
   "devDependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.1057.0",
     "@google-cloud/secret-manager": "^6.1.2",
     "yaml": "^2.9.0",
     "@repo/config-eslint": "0.2.1",
     "@repo/config-typescript": "0.1.0"
   },
   "peerDependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.1057.0",
     "@google-cloud/secret-manager": "^6.1.1",
     "yaml": "^2.8.2"
   },