@prairielearn/config 4.1.1 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/config
 
+## 4.2.0
+
+### Minor Changes
+
+- 7a9cda5: Add a KMS config source that decrypts encrypted config value objects.
+
+### Patch Changes
+
+- b6e03e9: Upgrade dependencies
+- Updated dependencies [b6e03e9]
+  - @prairielearn/aws-imds@3.0.3
+
 ## 4.1.1
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,13 @@
 # `@prairielearn/config`
 
-Utilities to help load configuration from various sources including a JSON file and AWS Secrets Manager. Config is made type-safe through a [Zod](https://github.com/colinhacks/zod) schema.
+Utilities to help load configuration from various sources including a JSON file, AWS Secrets Manager, and AWS KMS encrypted values. Config is made type-safe through a [Zod](https://github.com/colinhacks/zod) schema.
 
 This package _should not_ be depended upon by other packages directly. Instead, import it into your application, load the config, and then provide any necessary values to other packages.
 
 ## Usage
 
 ```ts
-import { ConfigLoader, makeFileConfig } from '@prairielearn/config';
+import { ConfigLoader, makeFileConfigSource } from '@prairielearn/config';
 import { z } from 'zod';
 
 const ConfigSchema = z.object({
@@ -16,7 +16,7 @@ const ConfigSchema = z.object({
 
 const configLoader = new ConfigLoader(ConfigSchema);
 
-await configLoader.loadAndValidate([makeFileConfig('config.json')]);
+await configLoader.loadAndValidate([makeFileConfigSource('config.json')]);
 
 console.log(configLoader.config);
 // { hello: "world" }
@@ -25,13 +25,13 @@ console.log(configLoader.config);
 Typically, you'll want to have a `config.ts` file in your own project that encapsulates this. Then, you can import the config elsewhere in the project.
 
 ```ts
-import { ConfigLoader, makeFileConfig } from '@prairielearn/config';
+import { ConfigLoader, makeFileConfigSource } from '@prairielearn/config';
 import { z } from 'zod';
 
 const configLoader = new ConfigLoader(z.any());
 
 export async function loadAndValidate(path: string) {
-  await configLoader.loadAndValidate([makeFileConfig(path)]);
+  await configLoader.loadAndValidate([makeFileConfigSource(path)]);
 }
 
 export default configLoader.config;
@@ -39,12 +39,42 @@ export default configLoader.config;
 
 ### Loading config from AWS
 
-If you're running in AWS, you can use `makeImdsConfig()` and `makeSecretsManagerConfig()` to load config from IMDS and Secrets Manager, respectively:
+If you're running in AWS, you can use `makeImdsConfigSource()`, `makeSecretsManagerConfigSource()`, and `makeKmsConfigSource()` to load config from IMDS, Secrets Manager, and AWS KMS, respectively:
 
-- `makeImdsConfig()` will load `hostname`, `instanceId`, and `awsRegion`, which will be available if you config schema contains these values.
-- `makeSecretsManagerConfig()` will look for a `ConfSecret` tag on the instance. If found, the value of that tag will be used treated as a Secrets Manager secret ID, and that secret's value will be parsed as JSON and merged into the config.
+- `makeImdsConfigSource()` will load `hostname`, `instanceId`, and `awsRegion`, which will be available if your config schema contains these values.
+- `makeSecretsManagerConfigSource()` will look for a `ConfSecret` tag on the instance. If found, the value of that tag will be used as a Secrets Manager secret ID, and that secret's value will be parsed as JSON and merged into the config.
+- `makeKmsConfigSource()` will recursively decrypt encrypted config value objects already loaded into the accumulated config. It is a transforming source, so place it after any source that may introduce encrypted values and before final validation.
 
-Note that both of these config sources are no-ops by default. To active them, you must do one of the following:
+```ts
+await configLoader.loadAndValidate([
+  makeFileConfigSource('config.json'),
+  makeImdsConfigSource(),
+  makeSecretsManagerConfigSource('ConfSecret'),
+  makeKmsConfigSource(),
+]);
+```
+
+Note that `makeImdsConfigSource()` and `makeSecretsManagerConfigSource()` are no-ops by default. To activate them, you must do one of the following:
 
 - Set `CONFIG_LOAD_FROM_AWS=1` in the process environment.
-- Chain them after `makeFileConfig()`, and ensure that the config file contains `{"runningInEc2": true}`.
+- Chain them after `makeFileConfigSource()`, and ensure that the config file contains `{"runningInEc2": true}`.
+
+`makeKmsConfigSource()` only creates a KMS client when encrypted config values are present. It resolves its region from `awsRegion` in the accumulated config or from the AWS SDK's default region provider chain.
+
+Encrypted config values use this JSON object shape:
+
+```json
+{
+  "__encrypted": "aws-kms-v1",
+  "ciphertext": "base64-encoded KMS CiphertextBlob",
+  "context": {
+    "environment": "us-prod"
+  },
+  "metadata": {
+    "key": "alias/service-config/us-prod",
+    "description": "prairietest postgresql password"
+  }
+}
+```
+
+The required runtime fields are `__encrypted`, `ciphertext`, and `context`. `ciphertext` is base64-decoded and passed to KMS as the `CiphertextBlob`, and `context` is passed to KMS as the exact encryption context with all values as strings. `metadata` is optional review/debug information; the example above shows recommended fields, but runtime decryption ignores metadata instead of trusting, validating, or passing it to KMS. KMS infers the key from the ciphertext during decrypt. Decrypted plaintext must be valid UTF-8 and is returned as a string.

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod';
-type AbstractConfig = Record<string, unknown>;
-export interface ConfigSource<T extends AbstractConfig = AbstractConfig> {
-    load: (existingConfig: T) => Promise<Partial<T>>;
-}
+import type { AbstractConfig, ConfigSource } from './types.js';
+export { makeKmsConfigSource } from './sources/kms.js';
+export type { AbstractConfig, ConfigSource } from './types.js';
 export declare function makeLiteralConfigSource(config: AbstractConfig): {
     load: () => Promise<AbstractConfig>;
 };
@@ -25,5 +24,4 @@ export declare class ConfigLoader<Schema extends z.ZodTypeAny> {
     reset(): void;
     get config(): z.TypeOf<Schema>;
 }
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IACrE,IAAI,EAAE,CAAC,cAAc,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAClD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc;;EAI7D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAS/D;AAED;;;GAGG;AACH,KAAK,oBAAoB,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAChD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAC7D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GACtE,YAAY,CAed;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAoC3E;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAiBnD;AAED,qBAAa,YAAY,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,cAAc,CAAkB;IAExC,YAAY,MAAM,EAAE,MAAM,EAOzB;IAEK,eAAe,CAAC,OAAO,GAAE,YAAY,CAAC,GAAG,CAAC,EAAO,iBAWtD;IAED,KAAK,SAEJ;IAED,IAAI,MAAM,qBAET;CACF","sourcesContent":["import { DescribeTagsCommand, EC2Client } from '@aws-sdk/client-ec2';\nimport { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';\nimport { mergeWith } from 'es-toolkit';\nimport fs from 'fs-extra';\nimport { z } from 'zod';\n\nimport { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';\n\ntype AbstractConfig = Record<string, unknown>;\n\nexport interface ConfigSource<T extends AbstractConfig = AbstractConfig> {\n  load: (existingConfig: T) => Promise<Partial<T>>;\n}\n\nexport function makeLiteralConfigSource(config: AbstractConfig) {\n  return {\n    load: async () => config,\n  };\n}\n\nexport function makeFileConfigSource(path: string): ConfigSource {\n  return {\n    load: async () => {\n      if (!(await fs.pathExists(path))) return {};\n\n      const config = await fs.readJson(path);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\n/**\n * Extracts keys from T where string is assignable to the value type.\n * This ensures we only map environment variables to fields that accept strings.\n */\ntype StringAssignableKeys<T> = {\n  [K in keyof T]: string extends T[K] ? K : never;\n}[keyof T];\n\nexport function makeEnvConfigSource<Schema extends z.ZodTypeAny>(\n  mapping: Partial<Record<StringAssignableKeys<z.infer<Schema>>, string>>,\n): ConfigSource {\n  return {\n    load: async () => {\n      const config: Record<string, string> = {};\n\n      for (const [key, envVar] of Object.entries(mapping) as [string, string][]) {\n        const value = process.env[envVar];\n        if (value !== undefined) {\n          config[key] = value;\n        }\n      }\n\n      return config;\n    },\n  };\n}\n\nexport function makeSecretsManagerConfigSource(tagKey: string): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const identity = await fetchInstanceIdentity();\n\n      // We disable the ESLint rule here because we don't care about sharing\n      // configs between clients in this case. We only want to share configs\n      // to avoid spamming the IMDS API when creating lots of clients, but\n      // this client will only be used once, typically at application startup.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const ec2Client = new EC2Client({ region: identity.region });\n      const tags = await ec2Client.send(\n        new DescribeTagsCommand({\n          Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],\n        }),\n      );\n\n      const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;\n      if (!secretId) return {};\n\n      // As above, we don't care about sharing configs between clients.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const secretsManagerClient = new SecretsManagerClient({ region: identity.region });\n      const secretValue = await secretsManagerClient.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!secretValue.SecretString) return {};\n\n      const config = JSON.parse(secretValue.SecretString);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\nexport function makeImdsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const hostname = await fetchInstanceHostname();\n      const identity = await fetchInstanceIdentity();\n\n      return {\n        hostname,\n        instanceId: identity.instanceId,\n        awsRegion: identity.region,\n      };\n    },\n  };\n}\n\nexport class ConfigLoader<Schema extends z.ZodTypeAny> {\n  private readonly schema: Schema;\n  private resolvedConfig: z.infer<Schema>;\n\n  constructor(schema: Schema) {\n    this.schema = schema;\n\n    // Get the default values from the schema. This ensures that all values\n    // have defaults, and also allows us to override nested defaults with\n    // `_.merge()` in `loadAndValidate()`.\n    this.resolvedConfig = schema.parse({});\n  }\n\n  async loadAndValidate(sources: ConfigSource<any>[] = []) {\n    let config = this.schema.parse({});\n    // If the config setting is an array, override instead of merge\n    const mergeRule = (_obj: any, src: any) => (Array.isArray(src) ? src : undefined);\n\n    for (const source of sources) {\n      config = mergeWith(config, await source.load(config), mergeRule);\n    }\n\n    const parsedConfig = this.schema.parse(config);\n    mergeWith(this.resolvedConfig, parsedConfig, mergeRule);\n  }\n\n  reset() {\n    this.resolvedConfig = this.schema.parse({});\n  }\n\n  get config() {\n    return this.resolvedConfig;\n  }\n}\n"]}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc;;EAI7D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAS/D;AAED;;;GAGG;AACH,KAAK,oBAAoB,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAChD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAC7D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GACtE,YAAY,CAed;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAoC3E;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAiBnD;AAED,qBAAa,YAAY,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,cAAc,CAAkB;IAExC,YAAY,MAAM,EAAE,MAAM,EAOzB;IAEK,eAAe,CAAC,OAAO,GAAE,YAAY,CAAC,GAAG,CAAC,EAAO,iBAWtD;IAED,KAAK,SAEJ;IAED,IAAI,MAAM,qBAET;CACF","sourcesContent":["import { DescribeTagsCommand, EC2Client } from '@aws-sdk/client-ec2';\nimport { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';\nimport { mergeWith } from 'es-toolkit';\nimport fs from 'fs-extra';\nimport { z } from 'zod';\n\nimport { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';\n\nimport type { AbstractConfig, ConfigSource } from './types.js';\n\nexport { makeKmsConfigSource } from './sources/kms.js';\nexport type { AbstractConfig, ConfigSource } from './types.js';\n\nexport function makeLiteralConfigSource(config: AbstractConfig) {\n  return {\n    load: async () => config,\n  };\n}\n\nexport function makeFileConfigSource(path: string): ConfigSource {\n  return {\n    load: async () => {\n      if (!(await fs.pathExists(path))) return {};\n\n      const config = await fs.readJson(path);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\n/**\n * Extracts keys from T where string is assignable to the value type.\n * This ensures we only map environment variables to fields that accept strings.\n */\ntype StringAssignableKeys<T> = {\n  [K in keyof T]: string extends T[K] ? K : never;\n}[keyof T];\n\nexport function makeEnvConfigSource<Schema extends z.ZodTypeAny>(\n  mapping: Partial<Record<StringAssignableKeys<z.infer<Schema>>, string>>,\n): ConfigSource {\n  return {\n    load: async () => {\n      const config: Record<string, string> = {};\n\n      for (const [key, envVar] of Object.entries(mapping) as [string, string][]) {\n        const value = process.env[envVar];\n        if (value !== undefined) {\n          config[key] = value;\n        }\n      }\n\n      return config;\n    },\n  };\n}\n\nexport function makeSecretsManagerConfigSource(tagKey: string): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const identity = await fetchInstanceIdentity();\n\n      // We disable the ESLint rule here because we don't care about sharing\n      // configs between clients in this case. We only want to share configs\n      // to avoid spamming the IMDS API when creating lots of clients, but\n      // this client will only be used once, typically at application startup.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const ec2Client = new EC2Client({ region: identity.region });\n      const tags = await ec2Client.send(\n        new DescribeTagsCommand({\n          Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],\n        }),\n      );\n\n      const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;\n      if (!secretId) return {};\n\n      // As above, we don't care about sharing configs between clients.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const secretsManagerClient = new SecretsManagerClient({ region: identity.region });\n      const secretValue = await secretsManagerClient.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!secretValue.SecretString) return {};\n\n      const config = JSON.parse(secretValue.SecretString);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\nexport function makeImdsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const hostname = await fetchInstanceHostname();\n      const identity = await fetchInstanceIdentity();\n\n      return {\n        hostname,\n        instanceId: identity.instanceId,\n        awsRegion: identity.region,\n      };\n    },\n  };\n}\n\nexport class ConfigLoader<Schema extends z.ZodTypeAny> {\n  private readonly schema: Schema;\n  private resolvedConfig: z.infer<Schema>;\n\n  constructor(schema: Schema) {\n    this.schema = schema;\n\n    // Get the default values from the schema. This ensures that all values\n    // have defaults, and also allows us to override nested defaults with\n    // `_.merge()` in `loadAndValidate()`.\n    this.resolvedConfig = schema.parse({});\n  }\n\n  async loadAndValidate(sources: ConfigSource<any>[] = []) {\n    let config = this.schema.parse({});\n    // If the config setting is an array, override instead of merge\n    const mergeRule = (_obj: any, src: any) => (Array.isArray(src) ? src : undefined);\n\n    for (const source of sources) {\n      config = mergeWith(config, await source.load(config), mergeRule);\n    }\n\n    const parsedConfig = this.schema.parse(config);\n    mergeWith(this.resolvedConfig, parsedConfig, mergeRule);\n  }\n\n  reset() {\n    this.resolvedConfig = this.schema.parse({});\n  }\n\n  get config() {\n    return this.resolvedConfig;\n  }\n}\n"]}

package/dist/index.js

@@ -4,6 +4,7 @@ import { mergeWith } from 'es-toolkit';
 import fs from 'fs-extra';
 import { z } from 'zod';
 import { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';
+export { makeKmsConfigSource } from './sources/kms.js';
 export function makeLiteralConfigSource(config) {
     return {
         load: async () => config,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { DescribeTagsCommand, EC2Client } from '@aws-sdk/client-ec2';\nimport { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';\nimport { mergeWith } from 'es-toolkit';\nimport fs from 'fs-extra';\nimport { z } from 'zod';\n\nimport { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';\n\ntype AbstractConfig = Record<string, unknown>;\n\nexport interface ConfigSource<T extends AbstractConfig = AbstractConfig> {\n  load: (existingConfig: T) => Promise<Partial<T>>;\n}\n\nexport function makeLiteralConfigSource(config: AbstractConfig) {\n  return {\n    load: async () => config,\n  };\n}\n\nexport function makeFileConfigSource(path: string): ConfigSource {\n  return {\n    load: async () => {\n      if (!(await fs.pathExists(path))) return {};\n\n      const config = await fs.readJson(path);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\n/**\n * Extracts keys from T where string is assignable to the value type.\n * This ensures we only map environment variables to fields that accept strings.\n */\ntype StringAssignableKeys<T> = {\n  [K in keyof T]: string extends T[K] ? K : never;\n}[keyof T];\n\nexport function makeEnvConfigSource<Schema extends z.ZodTypeAny>(\n  mapping: Partial<Record<StringAssignableKeys<z.infer<Schema>>, string>>,\n): ConfigSource {\n  return {\n    load: async () => {\n      const config: Record<string, string> = {};\n\n      for (const [key, envVar] of Object.entries(mapping) as [string, string][]) {\n        const value = process.env[envVar];\n        if (value !== undefined) {\n          config[key] = value;\n        }\n      }\n\n      return config;\n    },\n  };\n}\n\nexport function makeSecretsManagerConfigSource(tagKey: string): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const identity = await fetchInstanceIdentity();\n\n      // We disable the ESLint rule here because we don't care about sharing\n      // configs between clients in this case. We only want to share configs\n      // to avoid spamming the IMDS API when creating lots of clients, but\n      // this client will only be used once, typically at application startup.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const ec2Client = new EC2Client({ region: identity.region });\n      const tags = await ec2Client.send(\n        new DescribeTagsCommand({\n          Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],\n        }),\n      );\n\n      const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;\n      if (!secretId) return {};\n\n      // As above, we don't care about sharing configs between clients.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const secretsManagerClient = new SecretsManagerClient({ region: identity.region });\n      const secretValue = await secretsManagerClient.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!secretValue.SecretString) return {};\n\n      const config = JSON.parse(secretValue.SecretString);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\nexport function makeImdsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const hostname = await fetchInstanceHostname();\n      const identity = await fetchInstanceIdentity();\n\n      return {\n        hostname,\n        instanceId: identity.instanceId,\n        awsRegion: identity.region,\n      };\n    },\n  };\n}\n\nexport class ConfigLoader<Schema extends z.ZodTypeAny> {\n  private readonly schema: Schema;\n  private resolvedConfig: z.infer<Schema>;\n\n  constructor(schema: Schema) {\n    this.schema = schema;\n\n    // Get the default values from the schema. This ensures that all values\n    // have defaults, and also allows us to override nested defaults with\n    // `_.merge()` in `loadAndValidate()`.\n    this.resolvedConfig = schema.parse({});\n  }\n\n  async loadAndValidate(sources: ConfigSource<any>[] = []) {\n    let config = this.schema.parse({});\n    // If the config setting is an array, override instead of merge\n    const mergeRule = (_obj: any, src: any) => (Array.isArray(src) ? src : undefined);\n\n    for (const source of sources) {\n      config = mergeWith(config, await source.load(config), mergeRule);\n    }\n\n    const parsedConfig = this.schema.parse(config);\n    mergeWith(this.resolvedConfig, parsedConfig, mergeRule);\n  }\n\n  reset() {\n    this.resolvedConfig = this.schema.parse({});\n  }\n\n  get config() {\n    return this.resolvedConfig;\n  }\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { DescribeTagsCommand, EC2Client } from '@aws-sdk/client-ec2';\nimport { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';\nimport { mergeWith } from 'es-toolkit';\nimport fs from 'fs-extra';\nimport { z } from 'zod';\n\nimport { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';\n\nimport type { AbstractConfig, ConfigSource } from './types.js';\n\nexport { makeKmsConfigSource } from './sources/kms.js';\nexport type { AbstractConfig, ConfigSource } from './types.js';\n\nexport function makeLiteralConfigSource(config: AbstractConfig) {\n  return {\n    load: async () => config,\n  };\n}\n\nexport function makeFileConfigSource(path: string): ConfigSource {\n  return {\n    load: async () => {\n      if (!(await fs.pathExists(path))) return {};\n\n      const config = await fs.readJson(path);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\n/**\n * Extracts keys from T where string is assignable to the value type.\n * This ensures we only map environment variables to fields that accept strings.\n */\ntype StringAssignableKeys<T> = {\n  [K in keyof T]: string extends T[K] ? K : never;\n}[keyof T];\n\nexport function makeEnvConfigSource<Schema extends z.ZodTypeAny>(\n  mapping: Partial<Record<StringAssignableKeys<z.infer<Schema>>, string>>,\n): ConfigSource {\n  return {\n    load: async () => {\n      const config: Record<string, string> = {};\n\n      for (const [key, envVar] of Object.entries(mapping) as [string, string][]) {\n        const value = process.env[envVar];\n        if (value !== undefined) {\n          config[key] = value;\n        }\n      }\n\n      return config;\n    },\n  };\n}\n\nexport function makeSecretsManagerConfigSource(tagKey: string): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const identity = await fetchInstanceIdentity();\n\n      // We disable the ESLint rule here because we don't care about sharing\n      // configs between clients in this case. We only want to share configs\n      // to avoid spamming the IMDS API when creating lots of clients, but\n      // this client will only be used once, typically at application startup.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const ec2Client = new EC2Client({ region: identity.region });\n      const tags = await ec2Client.send(\n        new DescribeTagsCommand({\n          Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],\n        }),\n      );\n\n      const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;\n      if (!secretId) return {};\n\n      // As above, we don't care about sharing configs between clients.\n      // eslint-disable-next-line @prairielearn/aws-client-shared-config\n      const secretsManagerClient = new SecretsManagerClient({ region: identity.region });\n      const secretValue = await secretsManagerClient.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!secretValue.SecretString) return {};\n\n      const config = JSON.parse(secretValue.SecretString);\n      return z.record(z.string(), z.any()).parse(config);\n    },\n  };\n}\n\nexport function makeImdsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {\n        return {};\n      }\n\n      const hostname = await fetchInstanceHostname();\n      const identity = await fetchInstanceIdentity();\n\n      return {\n        hostname,\n        instanceId: identity.instanceId,\n        awsRegion: identity.region,\n      };\n    },\n  };\n}\n\nexport class ConfigLoader<Schema extends z.ZodTypeAny> {\n  private readonly schema: Schema;\n  private resolvedConfig: z.infer<Schema>;\n\n  constructor(schema: Schema) {\n    this.schema = schema;\n\n    // Get the default values from the schema. This ensures that all values\n    // have defaults, and also allows us to override nested defaults with\n    // `_.merge()` in `loadAndValidate()`.\n    this.resolvedConfig = schema.parse({});\n  }\n\n  async loadAndValidate(sources: ConfigSource<any>[] = []) {\n    let config = this.schema.parse({});\n    // If the config setting is an array, override instead of merge\n    const mergeRule = (_obj: any, src: any) => (Array.isArray(src) ? src : undefined);\n\n    for (const source of sources) {\n      config = mergeWith(config, await source.load(config), mergeRule);\n    }\n\n    const parsedConfig = this.schema.parse(config);\n    mergeWith(this.resolvedConfig, parsedConfig, mergeRule);\n  }\n\n  reset() {\n    this.resolvedConfig = this.schema.parse({});\n  }\n\n  get config() {\n    return this.resolvedConfig;\n  }\n}\n"]}

package/dist/sources/kms.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigSource } from '../types.js';
+export declare function makeKmsConfigSource(): ConfigSource;
+//# sourceMappingURL=kms.d.ts.map

package/dist/sources/kms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.d.ts","sourceRoot":"","sources":["../../src/sources/kms.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA6GhD,wBAAgB,mBAAmB,IAAI,YAAY,CA0BlD","sourcesContent":["import { DecryptCommand, type DecryptCommandOutput, KMSClient } from '@aws-sdk/client-kms';\nimport { z } from 'zod';\n\nimport type { ConfigSource } from '../types.js';\n\nconst EncryptedValueSchema = z.object({\n  __encrypted: z.literal('aws-kms-v1'),\n  ciphertext: z.string(),\n  context: z.record(z.string(), z.string()),\n});\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isEncryptedValue(value: unknown): boolean {\n  return isPlainObject(value) && Object.hasOwn(value, '__encrypted');\n}\n\nfunction formatConfigPath(path: (string | number)[]): string {\n  return path.length === 0\n    ? '<root>'\n    : path\n        .map((part, index) =>\n          typeof part === 'number' ? `[${part}]` : index === 0 ? part : `.${part}`,\n        )\n        .join('');\n}\n\nfunction formatZodIssues(error: z.ZodError): string {\n  return error.issues\n    .map((issue) => `${issue.path.join('.') || '<value>'}: ${issue.message}`)\n    .join('; ');\n}\n\nfunction parseEncryptedValue(value: unknown, path: (string | number)[]) {\n  const result = EncryptedValueSchema.safeParse(value);\n  if (!result.success) {\n    throw new Error(\n      `Malformed encrypted config value at ${formatConfigPath(path)}: ${formatZodIssues(result.error)}`,\n    );\n  }\n\n  return result.data;\n}\n\nasync function decryptEncryptedValue(\n  value: unknown,\n  path: (string | number)[],\n  getKmsClient: () => KMSClient,\n): Promise<string> {\n  const encryptedValue = parseEncryptedValue(value, path);\n  const ciphertextBlob = Buffer.from(encryptedValue.ciphertext, 'base64');\n  const kmsClient = getKmsClient();\n\n  let result: DecryptCommandOutput;\n  try {\n    result = await kmsClient.send(\n      new DecryptCommand({\n        CiphertextBlob: ciphertextBlob,\n        EncryptionContext: encryptedValue.context,\n      }),\n    );\n  } catch (error) {\n    throw new Error(`KMS decrypt failed for encrypted config value at ${formatConfigPath(path)}`, {\n      cause: error,\n    });\n  }\n\n  if (!result.Plaintext) {\n    throw new Error(\n      `KMS decrypt result missing Plaintext for encrypted config value at ${formatConfigPath(path)}`,\n    );\n  }\n\n  try {\n    return new TextDecoder('utf-8', { fatal: true }).decode(result.Plaintext);\n  } catch (error) {\n    throw new Error(\n      `KMS decrypt result Plaintext is not valid UTF-8 for encrypted config value at ${formatConfigPath(path)}`,\n      { cause: error },\n    );\n  }\n}\n\nasync function decryptEncryptedValuesInPlace(\n  value: unknown,\n  path: (string | number)[],\n  getKmsClient: () => KMSClient,\n): Promise<unknown> {\n  if (isEncryptedValue(value)) {\n    return await decryptEncryptedValue(value, path, getKmsClient);\n  }\n\n  if (Array.isArray(value)) {\n    for (const [index, item] of value.entries()) {\n      value[index] = await decryptEncryptedValuesInPlace(item, [...path, index], getKmsClient);\n    }\n    return value;\n  }\n\n  if (!isPlainObject(value)) {\n    return value;\n  }\n\n  for (const [key, childValue] of Object.entries(value)) {\n    value[key] = await decryptEncryptedValuesInPlace(childValue, [...path, key], getKmsClient);\n  }\n\n  return value;\n}\n\nexport function makeKmsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      let kmsClient: KMSClient | undefined;\n\n      // The client is created lazily so this source remains a no-op when there\n      // are no encrypted values. If a client is created, it's then reused for\n      // all decrypts in this load.\n      const getKmsClient = () => {\n        if (!kmsClient) {\n          const region =\n            typeof existingConfig.awsRegion === 'string' ? existingConfig.awsRegion : undefined;\n\n          // We don't care about sharing configs between clients here; this\n          // client is only used once, typically at application startup.\n          // eslint-disable-next-line @prairielearn/aws-client-shared-config\n          kmsClient = new KMSClient({ region });\n        }\n        return kmsClient;\n      };\n\n      const resolvedConfig = structuredClone(existingConfig);\n      await decryptEncryptedValuesInPlace(resolvedConfig, [], getKmsClient);\n      return resolvedConfig as Partial<typeof existingConfig>;\n    },\n  };\n}\n"]}

package/dist/sources/kms.js

@@ -0,0 +1,100 @@
+import { DecryptCommand, KMSClient } from '@aws-sdk/client-kms';
+import { z } from 'zod';
+const EncryptedValueSchema = z.object({
+    __encrypted: z.literal('aws-kms-v1'),
+    ciphertext: z.string(),
+    context: z.record(z.string(), z.string()),
+});
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isEncryptedValue(value) {
+    return isPlainObject(value) && Object.hasOwn(value, '__encrypted');
+}
+function formatConfigPath(path) {
+    return path.length === 0
+        ? '<root>'
+        : path
+            .map((part, index) => typeof part === 'number' ? `[${part}]` : index === 0 ? part : `.${part}`)
+            .join('');
+}
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join('.') || '<value>'}: ${issue.message}`)
+        .join('; ');
+}
+function parseEncryptedValue(value, path) {
+    const result = EncryptedValueSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`Malformed encrypted config value at ${formatConfigPath(path)}: ${formatZodIssues(result.error)}`);
+    }
+    return result.data;
+}
+async function decryptEncryptedValue(value, path, getKmsClient) {
+    const encryptedValue = parseEncryptedValue(value, path);
+    const ciphertextBlob = Buffer.from(encryptedValue.ciphertext, 'base64');
+    const kmsClient = getKmsClient();
+    let result;
+    try {
+        result = await kmsClient.send(new DecryptCommand({
+            CiphertextBlob: ciphertextBlob,
+            EncryptionContext: encryptedValue.context,
+        }));
+    }
+    catch (error) {
+        throw new Error(`KMS decrypt failed for encrypted config value at ${formatConfigPath(path)}`, {
+            cause: error,
+        });
+    }
+    if (!result.Plaintext) {
+        throw new Error(`KMS decrypt result missing Plaintext for encrypted config value at ${formatConfigPath(path)}`);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(result.Plaintext);
+    }
+    catch (error) {
+        throw new Error(`KMS decrypt result Plaintext is not valid UTF-8 for encrypted config value at ${formatConfigPath(path)}`, { cause: error });
+    }
+}
+async function decryptEncryptedValuesInPlace(value, path, getKmsClient) {
+    if (isEncryptedValue(value)) {
+        return await decryptEncryptedValue(value, path, getKmsClient);
+    }
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            value[index] = await decryptEncryptedValuesInPlace(item, [...path, index], getKmsClient);
+        }
+        return value;
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    for (const [key, childValue] of Object.entries(value)) {
+        value[key] = await decryptEncryptedValuesInPlace(childValue, [...path, key], getKmsClient);
+    }
+    return value;
+}
+export function makeKmsConfigSource() {
+    return {
+        load: async (existingConfig) => {
+            let kmsClient;
+            // The client is created lazily so this source remains a no-op when there
+            // are no encrypted values. If a client is created, it's then reused for
+            // all decrypts in this load.
+            const getKmsClient = () => {
+                if (!kmsClient) {
+                    const region = typeof existingConfig.awsRegion === 'string' ? existingConfig.awsRegion : undefined;
+                    // We don't care about sharing configs between clients here; this
+                    // client is only used once, typically at application startup.
+                    // eslint-disable-next-line @prairielearn/aws-client-shared-config
+                    kmsClient = new KMSClient({ region });
+                }
+                return kmsClient;
+            };
+            const resolvedConfig = structuredClone(existingConfig);
+            await decryptEncryptedValuesInPlace(resolvedConfig, [], getKmsClient);
+            return resolvedConfig;
+        },
+    };
+}
+//# sourceMappingURL=kms.js.map

package/dist/sources/kms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.js","sourceRoot":"","sources":["../../src/sources/kms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA6B,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;CAC1C,CAAC,CAAC;AAEH,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAyB;IACjD,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC;QACtB,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,IAAI;aACD,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACnB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CACzE;aACA,IAAI,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,eAAe,CAAC,KAAiB;IACxC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;SACxE,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc,EAAE,IAAyB;IACpE,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,uCAAuC,gBAAgB,CAAC,IAAI,CAAC,KAAK,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAClG,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,KAAc,EACd,IAAyB,EACzB,YAA6B;IAE7B,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,IAAI,MAA4B,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAC3B,IAAI,cAAc,CAAC;YACjB,cAAc,EAAE,cAAc;YAC9B,iBAAiB,EAAE,cAAc,CAAC,OAAO;SAC1C,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oDAAoD,gBAAgB,CAAC,IAAI,CAAC,EAAE,EAAE;YAC5F,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,sEAAsE,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAC/F,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,iFAAiF,gBAAgB,CAAC,IAAI,CAAC,EAAE,EACzG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,6BAA6B,CAC1C,KAAc,EACd,IAAyB,EACzB,YAA6B;IAE7B,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,MAAM,qBAAqB,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,6BAA6B,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,6BAA6B,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;YAC7B,IAAI,SAAgC,CAAC;YAErC,yEAAyE;YACzE,wEAAwE;YACxE,6BAA6B;YAC7B,MAAM,YAAY,GAAG,GAAG,EAAE;gBACxB,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,MAAM,GACV,OAAO,cAAc,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;oBAEtF,iEAAiE;oBACjE,8DAA8D;oBAC9D,kEAAkE;oBAClE,SAAS,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;gBACxC,CAAC;gBACD,OAAO,SAAS,CAAC;YACnB,CAAC,CAAC;YAEF,MAAM,cAAc,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;YACvD,MAAM,6BAA6B,CAAC,cAAc,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC;YACtE,OAAO,cAAgD,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { DecryptCommand, type DecryptCommandOutput, KMSClient } from '@aws-sdk/client-kms';\nimport { z } from 'zod';\n\nimport type { ConfigSource } from '../types.js';\n\nconst EncryptedValueSchema = z.object({\n  __encrypted: z.literal('aws-kms-v1'),\n  ciphertext: z.string(),\n  context: z.record(z.string(), z.string()),\n});\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isEncryptedValue(value: unknown): boolean {\n  return isPlainObject(value) && Object.hasOwn(value, '__encrypted');\n}\n\nfunction formatConfigPath(path: (string | number)[]): string {\n  return path.length === 0\n    ? '<root>'\n    : path\n        .map((part, index) =>\n          typeof part === 'number' ? `[${part}]` : index === 0 ? part : `.${part}`,\n        )\n        .join('');\n}\n\nfunction formatZodIssues(error: z.ZodError): string {\n  return error.issues\n    .map((issue) => `${issue.path.join('.') || '<value>'}: ${issue.message}`)\n    .join('; ');\n}\n\nfunction parseEncryptedValue(value: unknown, path: (string | number)[]) {\n  const result = EncryptedValueSchema.safeParse(value);\n  if (!result.success) {\n    throw new Error(\n      `Malformed encrypted config value at ${formatConfigPath(path)}: ${formatZodIssues(result.error)}`,\n    );\n  }\n\n  return result.data;\n}\n\nasync function decryptEncryptedValue(\n  value: unknown,\n  path: (string | number)[],\n  getKmsClient: () => KMSClient,\n): Promise<string> {\n  const encryptedValue = parseEncryptedValue(value, path);\n  const ciphertextBlob = Buffer.from(encryptedValue.ciphertext, 'base64');\n  const kmsClient = getKmsClient();\n\n  let result: DecryptCommandOutput;\n  try {\n    result = await kmsClient.send(\n      new DecryptCommand({\n        CiphertextBlob: ciphertextBlob,\n        EncryptionContext: encryptedValue.context,\n      }),\n    );\n  } catch (error) {\n    throw new Error(`KMS decrypt failed for encrypted config value at ${formatConfigPath(path)}`, {\n      cause: error,\n    });\n  }\n\n  if (!result.Plaintext) {\n    throw new Error(\n      `KMS decrypt result missing Plaintext for encrypted config value at ${formatConfigPath(path)}`,\n    );\n  }\n\n  try {\n    return new TextDecoder('utf-8', { fatal: true }).decode(result.Plaintext);\n  } catch (error) {\n    throw new Error(\n      `KMS decrypt result Plaintext is not valid UTF-8 for encrypted config value at ${formatConfigPath(path)}`,\n      { cause: error },\n    );\n  }\n}\n\nasync function decryptEncryptedValuesInPlace(\n  value: unknown,\n  path: (string | number)[],\n  getKmsClient: () => KMSClient,\n): Promise<unknown> {\n  if (isEncryptedValue(value)) {\n    return await decryptEncryptedValue(value, path, getKmsClient);\n  }\n\n  if (Array.isArray(value)) {\n    for (const [index, item] of value.entries()) {\n      value[index] = await decryptEncryptedValuesInPlace(item, [...path, index], getKmsClient);\n    }\n    return value;\n  }\n\n  if (!isPlainObject(value)) {\n    return value;\n  }\n\n  for (const [key, childValue] of Object.entries(value)) {\n    value[key] = await decryptEncryptedValuesInPlace(childValue, [...path, key], getKmsClient);\n  }\n\n  return value;\n}\n\nexport function makeKmsConfigSource(): ConfigSource {\n  return {\n    load: async (existingConfig) => {\n      let kmsClient: KMSClient | undefined;\n\n      // The client is created lazily so this source remains a no-op when there\n      // are no encrypted values. If a client is created, it's then reused for\n      // all decrypts in this load.\n      const getKmsClient = () => {\n        if (!kmsClient) {\n          const region =\n            typeof existingConfig.awsRegion === 'string' ? existingConfig.awsRegion : undefined;\n\n          // We don't care about sharing configs between clients here; this\n          // client is only used once, typically at application startup.\n          // eslint-disable-next-line @prairielearn/aws-client-shared-config\n          kmsClient = new KMSClient({ region });\n        }\n        return kmsClient;\n      };\n\n      const resolvedConfig = structuredClone(existingConfig);\n      await decryptEncryptedValuesInPlace(resolvedConfig, [], getKmsClient);\n      return resolvedConfig as Partial<typeof existingConfig>;\n    },\n  };\n}\n"]}

package/dist/sources/kms.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kms.test.d.ts.map

package/dist/sources/kms.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.test.d.ts","sourceRoot":"","sources":["../../src/sources/kms.test.ts"],"names":[],"mappings":"","sourcesContent":["import { DecryptCommand, KMSClient } from '@aws-sdk/client-kms';\nimport { assert, beforeEach, describe, expect, it, vi } from 'vitest';\nimport { z } from 'zod';\n\nimport { ConfigLoader, makeKmsConfigSource, makeLiteralConfigSource } from '../index.js';\n\nconst sendMock = vi.hoisted(() => vi.fn());\n\nvi.mock('@aws-sdk/client-kms', () => ({\n  DecryptCommand: vi.fn(function DecryptCommand(input: unknown) {\n    return { input };\n  }),\n  KMSClient: vi.fn(function KMSClient() {\n    return { send: sendMock };\n  }),\n}));\n\nfunction makeEncryptedValue(ciphertext = Buffer.from('ciphertext').toString('base64')) {\n  return {\n    __encrypted: 'aws-kms-v1',\n    ciphertext,\n    context: {\n      environment: 'us-prod',\n    },\n    metadata: {\n      key: 'alias/service-config/us-prod',\n      description: 'prairietest postgresql password',\n    },\n  };\n}\n\ndescribe('makeKmsConfigSource', () => {\n  beforeEach(() => {\n    sendMock.mockReset();\n    vi.mocked(DecryptCommand).mockClear();\n    vi.mocked(KMSClient).mockClear();\n  });\n\n  it('returns an unchanged config and does not create a KMS client when there are no encrypted values', async () => {\n    const source = makeKmsConfigSource();\n\n    assert.deepEqual(await source.load({ secret: 'plaintext' }), { secret: 'plaintext' });\n    expect(KMSClient).not.toHaveBeenCalled();\n  });\n\n  it('decrypts a top-level encrypted string', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n    const schema = z.object({\n      secret: z.string().default(''),\n    });\n    const loader = new ConfigLoader(schema);\n\n    await loader.loadAndValidate([\n      makeLiteralConfigSource({\n        secret: makeEncryptedValue(),\n      }),\n      makeKmsConfigSource(),\n    ]);\n\n    assert.equal(loader.config.secret, 'decrypted');\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        environment: 'us-prod',\n      },\n    });\n  });\n\n  it('ignores metadata when decrypting', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      secret: {\n        ...makeEncryptedValue(),\n        metadata: {\n          key: 42,\n          description: {\n            text: 'metadata is not used by runtime decryption',\n          },\n          owner: ['course-staff'],\n        },\n      },\n    });\n\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        environment: 'us-prod',\n      },\n    });\n  });\n\n  it('passes encryption context through to KMS without requiring PrairieLearn-specific keys', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      secret: {\n        ...makeEncryptedValue(),\n        context: {\n          deployment: 'self-hosted',\n          purpose: 'config',\n        },\n      },\n    });\n\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        deployment: 'self-hosted',\n        purpose: 'config',\n      },\n    });\n  });\n\n  it('uses awsRegion from existing config', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      awsRegion: 'us-west-2',\n      secret: makeEncryptedValue(),\n    });\n\n    expect(KMSClient).toHaveBeenCalledWith({ region: 'us-west-2' });\n  });\n\n  it('returns the full transformed config when encrypted values exist', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    const result = await makeKmsConfigSource().load({\n      database: {\n        host: 'db.example.com',\n        password: makeEncryptedValue(),\n      },\n      courseDirs: ['exampleCourse'],\n    });\n\n    assert.deepEqual(result, {\n      database: {\n        host: 'db.example.com',\n        password: 'decrypted',\n      },\n      courseDirs: ['exampleCourse'],\n    });\n  });\n\n  it('decrypts nested object and array values', async () => {\n    sendMock\n      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('nested') })\n      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('array') });\n    const schema = z.object({\n      nested: z\n        .object({\n          secret: z.string().default(''),\n          unchanged: z.string().default('kept'),\n        })\n        .default({ secret: '', unchanged: 'kept' }),\n      values: z.array(z.union([z.string(), z.object({ secret: z.string() })])).default([]),\n    });\n    const loader = new ConfigLoader(schema);\n\n    await loader.loadAndValidate([\n      makeLiteralConfigSource({\n        nested: {\n          secret: makeEncryptedValue(),\n          unchanged: 'kept',\n        },\n        values: ['first', { secret: makeEncryptedValue() }],\n      }),\n      makeKmsConfigSource(),\n    ]);\n\n    assert.deepEqual(loader.config, {\n      nested: {\n        secret: 'nested',\n        unchanged: 'kept',\n      },\n      values: ['first', { secret: 'array' }],\n    });\n    expect(KMSClient).toHaveBeenCalledTimes(1);\n  });\n\n  it('does not mutate the source object when decrypting encrypted values', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n    const encryptedValue = makeEncryptedValue();\n    const sourceConfig = {\n      secret: encryptedValue,\n    };\n\n    const result = await makeKmsConfigSource().load(sourceConfig);\n\n    assert.deepEqual(encryptedValue, makeEncryptedValue());\n    assert.deepEqual(sourceConfig, { secret: encryptedValue });\n    assert.deepEqual(result, { secret: 'decrypted' });\n  });\n\n  it('throws on malformed encrypted values', async () => {\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v1',\n          ciphertext: Buffer.from('ciphertext').toString('base64'),\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v1',\n          context: {\n            environment: 'us-prod',\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*ciphertext/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          ...makeEncryptedValue(),\n          context: 'us-prod',\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          ...makeEncryptedValue(),\n          context: {\n            environment: 42,\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context\\.environment/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v2',\n          ciphertext: Buffer.from('ciphertext').toString('base64'),\n          context: {\n            environment: 'us-prod',\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*__encrypted.*aws-kms-v1/);\n  });\n\n  it('throws on invalid decrypt results', async () => {\n    sendMock.mockResolvedValueOnce({});\n    await expect(\n      makeKmsConfigSource().load({\n        secret: makeEncryptedValue(),\n      }),\n    ).rejects.toThrow(/missing Plaintext/);\n\n    sendMock.mockResolvedValueOnce({ Plaintext: new Uint8Array([0xff]) });\n    await expect(\n      makeKmsConfigSource().load({\n        secret: makeEncryptedValue(),\n      }),\n    ).rejects.toThrow(/not valid UTF-8/);\n  });\n\n  it('includes the config path when KMS decrypt fails', async () => {\n    const cause = new Error('AccessDeniedException');\n    sendMock.mockRejectedValue(cause);\n\n    let thrown: unknown;\n    try {\n      await makeKmsConfigSource().load({\n        nested: {\n          secret: makeEncryptedValue(),\n        },\n      });\n    } catch (error) {\n      thrown = error;\n    }\n\n    assert.instanceOf(thrown, Error);\n    assert.match(thrown.message, /KMS decrypt failed.*nested\\.secret/);\n    assert.strictEqual(thrown.cause, cause);\n  });\n});\n"]}

package/dist/sources/kms.test.js

@@ -0,0 +1,235 @@
+import { DecryptCommand, KMSClient } from '@aws-sdk/client-kms';
+import { assert, beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { ConfigLoader, makeKmsConfigSource, makeLiteralConfigSource } from '../index.js';
+const sendMock = vi.hoisted(() => vi.fn());
+vi.mock('@aws-sdk/client-kms', () => ({
+    DecryptCommand: vi.fn(function DecryptCommand(input) {
+        return { input };
+    }),
+    KMSClient: vi.fn(function KMSClient() {
+        return { send: sendMock };
+    }),
+}));
+function makeEncryptedValue(ciphertext = Buffer.from('ciphertext').toString('base64')) {
+    return {
+        __encrypted: 'aws-kms-v1',
+        ciphertext,
+        context: {
+            environment: 'us-prod',
+        },
+        metadata: {
+            key: 'alias/service-config/us-prod',
+            description: 'prairietest postgresql password',
+        },
+    };
+}
+describe('makeKmsConfigSource', () => {
+    beforeEach(() => {
+        sendMock.mockReset();
+        vi.mocked(DecryptCommand).mockClear();
+        vi.mocked(KMSClient).mockClear();
+    });
+    it('returns an unchanged config and does not create a KMS client when there are no encrypted values', async () => {
+        const source = makeKmsConfigSource();
+        assert.deepEqual(await source.load({ secret: 'plaintext' }), { secret: 'plaintext' });
+        expect(KMSClient).not.toHaveBeenCalled();
+    });
+    it('decrypts a top-level encrypted string', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        const schema = z.object({
+            secret: z.string().default(''),
+        });
+        const loader = new ConfigLoader(schema);
+        await loader.loadAndValidate([
+            makeLiteralConfigSource({
+                secret: makeEncryptedValue(),
+            }),
+            makeKmsConfigSource(),
+        ]);
+        assert.equal(loader.config.secret, 'decrypted');
+        expect(DecryptCommand).toHaveBeenCalledWith({
+            CiphertextBlob: Buffer.from('ciphertext'),
+            EncryptionContext: {
+                environment: 'us-prod',
+            },
+        });
+    });
+    it('ignores metadata when decrypting', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        await makeKmsConfigSource().load({
+            secret: {
+                ...makeEncryptedValue(),
+                metadata: {
+                    key: 42,
+                    description: {
+                        text: 'metadata is not used by runtime decryption',
+                    },
+                    owner: ['course-staff'],
+                },
+            },
+        });
+        expect(DecryptCommand).toHaveBeenCalledWith({
+            CiphertextBlob: Buffer.from('ciphertext'),
+            EncryptionContext: {
+                environment: 'us-prod',
+            },
+        });
+    });
+    it('passes encryption context through to KMS without requiring PrairieLearn-specific keys', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        await makeKmsConfigSource().load({
+            secret: {
+                ...makeEncryptedValue(),
+                context: {
+                    deployment: 'self-hosted',
+                    purpose: 'config',
+                },
+            },
+        });
+        expect(DecryptCommand).toHaveBeenCalledWith({
+            CiphertextBlob: Buffer.from('ciphertext'),
+            EncryptionContext: {
+                deployment: 'self-hosted',
+                purpose: 'config',
+            },
+        });
+    });
+    it('uses awsRegion from existing config', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        await makeKmsConfigSource().load({
+            awsRegion: 'us-west-2',
+            secret: makeEncryptedValue(),
+        });
+        expect(KMSClient).toHaveBeenCalledWith({ region: 'us-west-2' });
+    });
+    it('returns the full transformed config when encrypted values exist', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        const result = await makeKmsConfigSource().load({
+            database: {
+                host: 'db.example.com',
+                password: makeEncryptedValue(),
+            },
+            courseDirs: ['exampleCourse'],
+        });
+        assert.deepEqual(result, {
+            database: {
+                host: 'db.example.com',
+                password: 'decrypted',
+            },
+            courseDirs: ['exampleCourse'],
+        });
+    });
+    it('decrypts nested object and array values', async () => {
+        sendMock
+            .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('nested') })
+            .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('array') });
+        const schema = z.object({
+            nested: z
+                .object({
+                secret: z.string().default(''),
+                unchanged: z.string().default('kept'),
+            })
+                .default({ secret: '', unchanged: 'kept' }),
+            values: z.array(z.union([z.string(), z.object({ secret: z.string() })])).default([]),
+        });
+        const loader = new ConfigLoader(schema);
+        await loader.loadAndValidate([
+            makeLiteralConfigSource({
+                nested: {
+                    secret: makeEncryptedValue(),
+                    unchanged: 'kept',
+                },
+                values: ['first', { secret: makeEncryptedValue() }],
+            }),
+            makeKmsConfigSource(),
+        ]);
+        assert.deepEqual(loader.config, {
+            nested: {
+                secret: 'nested',
+                unchanged: 'kept',
+            },
+            values: ['first', { secret: 'array' }],
+        });
+        expect(KMSClient).toHaveBeenCalledTimes(1);
+    });
+    it('does not mutate the source object when decrypting encrypted values', async () => {
+        sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+        const encryptedValue = makeEncryptedValue();
+        const sourceConfig = {
+            secret: encryptedValue,
+        };
+        const result = await makeKmsConfigSource().load(sourceConfig);
+        assert.deepEqual(encryptedValue, makeEncryptedValue());
+        assert.deepEqual(sourceConfig, { secret: encryptedValue });
+        assert.deepEqual(result, { secret: 'decrypted' });
+    });
+    it('throws on malformed encrypted values', async () => {
+        await expect(makeKmsConfigSource().load({
+            secret: {
+                __encrypted: 'aws-kms-v1',
+                ciphertext: Buffer.from('ciphertext').toString('base64'),
+            },
+        })).rejects.toThrow(/Malformed encrypted config value.*context/);
+        await expect(makeKmsConfigSource().load({
+            secret: {
+                __encrypted: 'aws-kms-v1',
+                context: {
+                    environment: 'us-prod',
+                },
+            },
+        })).rejects.toThrow(/Malformed encrypted config value.*ciphertext/);
+        await expect(makeKmsConfigSource().load({
+            secret: {
+                ...makeEncryptedValue(),
+                context: 'us-prod',
+            },
+        })).rejects.toThrow(/Malformed encrypted config value.*context/);
+        await expect(makeKmsConfigSource().load({
+            secret: {
+                ...makeEncryptedValue(),
+                context: {
+                    environment: 42,
+                },
+            },
+        })).rejects.toThrow(/Malformed encrypted config value.*context\.environment/);
+        await expect(makeKmsConfigSource().load({
+            secret: {
+                __encrypted: 'aws-kms-v2',
+                ciphertext: Buffer.from('ciphertext').toString('base64'),
+                context: {
+                    environment: 'us-prod',
+                },
+            },
+        })).rejects.toThrow(/Malformed encrypted config value.*__encrypted.*aws-kms-v1/);
+    });
+    it('throws on invalid decrypt results', async () => {
+        sendMock.mockResolvedValueOnce({});
+        await expect(makeKmsConfigSource().load({
+            secret: makeEncryptedValue(),
+        })).rejects.toThrow(/missing Plaintext/);
+        sendMock.mockResolvedValueOnce({ Plaintext: new Uint8Array([0xff]) });
+        await expect(makeKmsConfigSource().load({
+            secret: makeEncryptedValue(),
+        })).rejects.toThrow(/not valid UTF-8/);
+    });
+    it('includes the config path when KMS decrypt fails', async () => {
+        const cause = new Error('AccessDeniedException');
+        sendMock.mockRejectedValue(cause);
+        let thrown;
+        try {
+            await makeKmsConfigSource().load({
+                nested: {
+                    secret: makeEncryptedValue(),
+                },
+            });
+        }
+        catch (error) {
+            thrown = error;
+        }
+        assert.instanceOf(thrown, Error);
+        assert.match(thrown.message, /KMS decrypt failed.*nested\.secret/);
+        assert.strictEqual(thrown.cause, cause);
+    });
+});
+//# sourceMappingURL=kms.test.js.map

package/dist/sources/kms.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.test.js","sourceRoot":"","sources":["../../src/sources/kms.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { DecryptCommand, KMSClient } from '@aws-sdk/client-kms';\nimport { assert, beforeEach, describe, expect, it, vi } from 'vitest';\nimport { z } from 'zod';\n\nimport { ConfigLoader, makeKmsConfigSource, makeLiteralConfigSource } from '../index.js';\n\nconst sendMock = vi.hoisted(() => vi.fn());\n\nvi.mock('@aws-sdk/client-kms', () => ({\n  DecryptCommand: vi.fn(function DecryptCommand(input: unknown) {\n    return { input };\n  }),\n  KMSClient: vi.fn(function KMSClient() {\n    return { send: sendMock };\n  }),\n}));\n\nfunction makeEncryptedValue(ciphertext = Buffer.from('ciphertext').toString('base64')) {\n  return {\n    __encrypted: 'aws-kms-v1',\n    ciphertext,\n    context: {\n      environment: 'us-prod',\n    },\n    metadata: {\n      key: 'alias/service-config/us-prod',\n      description: 'prairietest postgresql password',\n    },\n  };\n}\n\ndescribe('makeKmsConfigSource', () => {\n  beforeEach(() => {\n    sendMock.mockReset();\n    vi.mocked(DecryptCommand).mockClear();\n    vi.mocked(KMSClient).mockClear();\n  });\n\n  it('returns an unchanged config and does not create a KMS client when there are no encrypted values', async () => {\n    const source = makeKmsConfigSource();\n\n    assert.deepEqual(await source.load({ secret: 'plaintext' }), { secret: 'plaintext' });\n    expect(KMSClient).not.toHaveBeenCalled();\n  });\n\n  it('decrypts a top-level encrypted string', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n    const schema = z.object({\n      secret: z.string().default(''),\n    });\n    const loader = new ConfigLoader(schema);\n\n    await loader.loadAndValidate([\n      makeLiteralConfigSource({\n        secret: makeEncryptedValue(),\n      }),\n      makeKmsConfigSource(),\n    ]);\n\n    assert.equal(loader.config.secret, 'decrypted');\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        environment: 'us-prod',\n      },\n    });\n  });\n\n  it('ignores metadata when decrypting', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      secret: {\n        ...makeEncryptedValue(),\n        metadata: {\n          key: 42,\n          description: {\n            text: 'metadata is not used by runtime decryption',\n          },\n          owner: ['course-staff'],\n        },\n      },\n    });\n\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        environment: 'us-prod',\n      },\n    });\n  });\n\n  it('passes encryption context through to KMS without requiring PrairieLearn-specific keys', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      secret: {\n        ...makeEncryptedValue(),\n        context: {\n          deployment: 'self-hosted',\n          purpose: 'config',\n        },\n      },\n    });\n\n    expect(DecryptCommand).toHaveBeenCalledWith({\n      CiphertextBlob: Buffer.from('ciphertext'),\n      EncryptionContext: {\n        deployment: 'self-hosted',\n        purpose: 'config',\n      },\n    });\n  });\n\n  it('uses awsRegion from existing config', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    await makeKmsConfigSource().load({\n      awsRegion: 'us-west-2',\n      secret: makeEncryptedValue(),\n    });\n\n    expect(KMSClient).toHaveBeenCalledWith({ region: 'us-west-2' });\n  });\n\n  it('returns the full transformed config when encrypted values exist', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n\n    const result = await makeKmsConfigSource().load({\n      database: {\n        host: 'db.example.com',\n        password: makeEncryptedValue(),\n      },\n      courseDirs: ['exampleCourse'],\n    });\n\n    assert.deepEqual(result, {\n      database: {\n        host: 'db.example.com',\n        password: 'decrypted',\n      },\n      courseDirs: ['exampleCourse'],\n    });\n  });\n\n  it('decrypts nested object and array values', async () => {\n    sendMock\n      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('nested') })\n      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('array') });\n    const schema = z.object({\n      nested: z\n        .object({\n          secret: z.string().default(''),\n          unchanged: z.string().default('kept'),\n        })\n        .default({ secret: '', unchanged: 'kept' }),\n      values: z.array(z.union([z.string(), z.object({ secret: z.string() })])).default([]),\n    });\n    const loader = new ConfigLoader(schema);\n\n    await loader.loadAndValidate([\n      makeLiteralConfigSource({\n        nested: {\n          secret: makeEncryptedValue(),\n          unchanged: 'kept',\n        },\n        values: ['first', { secret: makeEncryptedValue() }],\n      }),\n      makeKmsConfigSource(),\n    ]);\n\n    assert.deepEqual(loader.config, {\n      nested: {\n        secret: 'nested',\n        unchanged: 'kept',\n      },\n      values: ['first', { secret: 'array' }],\n    });\n    expect(KMSClient).toHaveBeenCalledTimes(1);\n  });\n\n  it('does not mutate the source object when decrypting encrypted values', async () => {\n    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });\n    const encryptedValue = makeEncryptedValue();\n    const sourceConfig = {\n      secret: encryptedValue,\n    };\n\n    const result = await makeKmsConfigSource().load(sourceConfig);\n\n    assert.deepEqual(encryptedValue, makeEncryptedValue());\n    assert.deepEqual(sourceConfig, { secret: encryptedValue });\n    assert.deepEqual(result, { secret: 'decrypted' });\n  });\n\n  it('throws on malformed encrypted values', async () => {\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v1',\n          ciphertext: Buffer.from('ciphertext').toString('base64'),\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v1',\n          context: {\n            environment: 'us-prod',\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*ciphertext/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          ...makeEncryptedValue(),\n          context: 'us-prod',\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          ...makeEncryptedValue(),\n          context: {\n            environment: 42,\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*context\\.environment/);\n\n    await expect(\n      makeKmsConfigSource().load({\n        secret: {\n          __encrypted: 'aws-kms-v2',\n          ciphertext: Buffer.from('ciphertext').toString('base64'),\n          context: {\n            environment: 'us-prod',\n          },\n        },\n      }),\n    ).rejects.toThrow(/Malformed encrypted config value.*__encrypted.*aws-kms-v1/);\n  });\n\n  it('throws on invalid decrypt results', async () => {\n    sendMock.mockResolvedValueOnce({});\n    await expect(\n      makeKmsConfigSource().load({\n        secret: makeEncryptedValue(),\n      }),\n    ).rejects.toThrow(/missing Plaintext/);\n\n    sendMock.mockResolvedValueOnce({ Plaintext: new Uint8Array([0xff]) });\n    await expect(\n      makeKmsConfigSource().load({\n        secret: makeEncryptedValue(),\n      }),\n    ).rejects.toThrow(/not valid UTF-8/);\n  });\n\n  it('includes the config path when KMS decrypt fails', async () => {\n    const cause = new Error('AccessDeniedException');\n    sendMock.mockRejectedValue(cause);\n\n    let thrown: unknown;\n    try {\n      await makeKmsConfigSource().load({\n        nested: {\n          secret: makeEncryptedValue(),\n        },\n      });\n    } catch (error) {\n      thrown = error;\n    }\n\n    assert.instanceOf(thrown, Error);\n    assert.match(thrown.message, /KMS decrypt failed.*nested\\.secret/);\n    assert.strictEqual(thrown.cause, cause);\n  });\n});\n"]}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type AbstractConfig = Record<string, unknown>;
+export interface ConfigSource<T extends AbstractConfig = AbstractConfig> {
+    load: (existingConfig: T) => Promise<Partial<T>>;
+}
+//# 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,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IACrE,IAAI,EAAE,CAAC,cAAc,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAClD","sourcesContent":["export type AbstractConfig = Record<string, unknown>;\n\nexport interface ConfigSource<T extends AbstractConfig = AbstractConfig> {\n  load: (existingConfig: T) => Promise<Partial<T>>;\n}\n"]}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["export type AbstractConfig = Record<string, unknown>;\n\nexport interface ConfigSource<T extends AbstractConfig = AbstractConfig> {\n  load: (existingConfig: T) => Promise<Partial<T>>;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/config",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,9 +17,10 @@
     "test": "vitest run --coverage"
   },
   "dependencies": {
-    "@aws-sdk/client-ec2": "^3.1002.0",
-    "@aws-sdk/client-secrets-manager": "^3.1002.0",
-    "@prairielearn/aws-imds": "^3.0.2",
+    "@aws-sdk/client-ec2": "^3.1023.0",
+    "@aws-sdk/client-kms": "^3.1023.0",
+    "@aws-sdk/client-secrets-manager": "^3.1023.0",
+    "@prairielearn/aws-imds": "^3.0.3",
     "es-toolkit": "^1.45.1",
     "fs-extra": "^11.3.4",
     "zod": "^3.25.76"
@@ -27,12 +28,12 @@
   "devDependencies": {
     "@prairielearn/tsconfig": "^2.0.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^24.11.0",
+    "@types/node": "^24.12.2",
     "@typescript/native-preview": "^7.0.0-dev.20260305.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.2",
     "tmp-promise": "^3.0.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.2"
   }
 }

package/src/index.ts

@@ -6,11 +6,10 @@ import { z } from 'zod';
 
 import { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';
 
-type AbstractConfig = Record<string, unknown>;
+import type { AbstractConfig, ConfigSource } from './types.js';
 
-export interface ConfigSource<T extends AbstractConfig = AbstractConfig> {
-  load: (existingConfig: T) => Promise<Partial<T>>;
-}
+export { makeKmsConfigSource } from './sources/kms.js';
+export type { AbstractConfig, ConfigSource } from './types.js';
 
 export function makeLiteralConfigSource(config: AbstractConfig) {
   return {

package/src/sources/kms.test.ts

@@ -0,0 +1,285 @@
+import { DecryptCommand, KMSClient } from '@aws-sdk/client-kms';
+import { assert, beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+import { ConfigLoader, makeKmsConfigSource, makeLiteralConfigSource } from '../index.js';
+
+const sendMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@aws-sdk/client-kms', () => ({
+  DecryptCommand: vi.fn(function DecryptCommand(input: unknown) {
+    return { input };
+  }),
+  KMSClient: vi.fn(function KMSClient() {
+    return { send: sendMock };
+  }),
+}));
+
+function makeEncryptedValue(ciphertext = Buffer.from('ciphertext').toString('base64')) {
+  return {
+    __encrypted: 'aws-kms-v1',
+    ciphertext,
+    context: {
+      environment: 'us-prod',
+    },
+    metadata: {
+      key: 'alias/service-config/us-prod',
+      description: 'prairietest postgresql password',
+    },
+  };
+}
+
+describe('makeKmsConfigSource', () => {
+  beforeEach(() => {
+    sendMock.mockReset();
+    vi.mocked(DecryptCommand).mockClear();
+    vi.mocked(KMSClient).mockClear();
+  });
+
+  it('returns an unchanged config and does not create a KMS client when there are no encrypted values', async () => {
+    const source = makeKmsConfigSource();
+
+    assert.deepEqual(await source.load({ secret: 'plaintext' }), { secret: 'plaintext' });
+    expect(KMSClient).not.toHaveBeenCalled();
+  });
+
+  it('decrypts a top-level encrypted string', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+    const schema = z.object({
+      secret: z.string().default(''),
+    });
+    const loader = new ConfigLoader(schema);
+
+    await loader.loadAndValidate([
+      makeLiteralConfigSource({
+        secret: makeEncryptedValue(),
+      }),
+      makeKmsConfigSource(),
+    ]);
+
+    assert.equal(loader.config.secret, 'decrypted');
+    expect(DecryptCommand).toHaveBeenCalledWith({
+      CiphertextBlob: Buffer.from('ciphertext'),
+      EncryptionContext: {
+        environment: 'us-prod',
+      },
+    });
+  });
+
+  it('ignores metadata when decrypting', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+
+    await makeKmsConfigSource().load({
+      secret: {
+        ...makeEncryptedValue(),
+        metadata: {
+          key: 42,
+          description: {
+            text: 'metadata is not used by runtime decryption',
+          },
+          owner: ['course-staff'],
+        },
+      },
+    });
+
+    expect(DecryptCommand).toHaveBeenCalledWith({
+      CiphertextBlob: Buffer.from('ciphertext'),
+      EncryptionContext: {
+        environment: 'us-prod',
+      },
+    });
+  });
+
+  it('passes encryption context through to KMS without requiring PrairieLearn-specific keys', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+
+    await makeKmsConfigSource().load({
+      secret: {
+        ...makeEncryptedValue(),
+        context: {
+          deployment: 'self-hosted',
+          purpose: 'config',
+        },
+      },
+    });
+
+    expect(DecryptCommand).toHaveBeenCalledWith({
+      CiphertextBlob: Buffer.from('ciphertext'),
+      EncryptionContext: {
+        deployment: 'self-hosted',
+        purpose: 'config',
+      },
+    });
+  });
+
+  it('uses awsRegion from existing config', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+
+    await makeKmsConfigSource().load({
+      awsRegion: 'us-west-2',
+      secret: makeEncryptedValue(),
+    });
+
+    expect(KMSClient).toHaveBeenCalledWith({ region: 'us-west-2' });
+  });
+
+  it('returns the full transformed config when encrypted values exist', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+
+    const result = await makeKmsConfigSource().load({
+      database: {
+        host: 'db.example.com',
+        password: makeEncryptedValue(),
+      },
+      courseDirs: ['exampleCourse'],
+    });
+
+    assert.deepEqual(result, {
+      database: {
+        host: 'db.example.com',
+        password: 'decrypted',
+      },
+      courseDirs: ['exampleCourse'],
+    });
+  });
+
+  it('decrypts nested object and array values', async () => {
+    sendMock
+      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('nested') })
+      .mockResolvedValueOnce({ Plaintext: new TextEncoder().encode('array') });
+    const schema = z.object({
+      nested: z
+        .object({
+          secret: z.string().default(''),
+          unchanged: z.string().default('kept'),
+        })
+        .default({ secret: '', unchanged: 'kept' }),
+      values: z.array(z.union([z.string(), z.object({ secret: z.string() })])).default([]),
+    });
+    const loader = new ConfigLoader(schema);
+
+    await loader.loadAndValidate([
+      makeLiteralConfigSource({
+        nested: {
+          secret: makeEncryptedValue(),
+          unchanged: 'kept',
+        },
+        values: ['first', { secret: makeEncryptedValue() }],
+      }),
+      makeKmsConfigSource(),
+    ]);
+
+    assert.deepEqual(loader.config, {
+      nested: {
+        secret: 'nested',
+        unchanged: 'kept',
+      },
+      values: ['first', { secret: 'array' }],
+    });
+    expect(KMSClient).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not mutate the source object when decrypting encrypted values', async () => {
+    sendMock.mockResolvedValue({ Plaintext: new TextEncoder().encode('decrypted') });
+    const encryptedValue = makeEncryptedValue();
+    const sourceConfig = {
+      secret: encryptedValue,
+    };
+
+    const result = await makeKmsConfigSource().load(sourceConfig);
+
+    assert.deepEqual(encryptedValue, makeEncryptedValue());
+    assert.deepEqual(sourceConfig, { secret: encryptedValue });
+    assert.deepEqual(result, { secret: 'decrypted' });
+  });
+
+  it('throws on malformed encrypted values', async () => {
+    await expect(
+      makeKmsConfigSource().load({
+        secret: {
+          __encrypted: 'aws-kms-v1',
+          ciphertext: Buffer.from('ciphertext').toString('base64'),
+        },
+      }),
+    ).rejects.toThrow(/Malformed encrypted config value.*context/);
+
+    await expect(
+      makeKmsConfigSource().load({
+        secret: {
+          __encrypted: 'aws-kms-v1',
+          context: {
+            environment: 'us-prod',
+          },
+        },
+      }),
+    ).rejects.toThrow(/Malformed encrypted config value.*ciphertext/);
+
+    await expect(
+      makeKmsConfigSource().load({
+        secret: {
+          ...makeEncryptedValue(),
+          context: 'us-prod',
+        },
+      }),
+    ).rejects.toThrow(/Malformed encrypted config value.*context/);
+
+    await expect(
+      makeKmsConfigSource().load({
+        secret: {
+          ...makeEncryptedValue(),
+          context: {
+            environment: 42,
+          },
+        },
+      }),
+    ).rejects.toThrow(/Malformed encrypted config value.*context\.environment/);
+
+    await expect(
+      makeKmsConfigSource().load({
+        secret: {
+          __encrypted: 'aws-kms-v2',
+          ciphertext: Buffer.from('ciphertext').toString('base64'),
+          context: {
+            environment: 'us-prod',
+          },
+        },
+      }),
+    ).rejects.toThrow(/Malformed encrypted config value.*__encrypted.*aws-kms-v1/);
+  });
+
+  it('throws on invalid decrypt results', async () => {
+    sendMock.mockResolvedValueOnce({});
+    await expect(
+      makeKmsConfigSource().load({
+        secret: makeEncryptedValue(),
+      }),
+    ).rejects.toThrow(/missing Plaintext/);
+
+    sendMock.mockResolvedValueOnce({ Plaintext: new Uint8Array([0xff]) });
+    await expect(
+      makeKmsConfigSource().load({
+        secret: makeEncryptedValue(),
+      }),
+    ).rejects.toThrow(/not valid UTF-8/);
+  });
+
+  it('includes the config path when KMS decrypt fails', async () => {
+    const cause = new Error('AccessDeniedException');
+    sendMock.mockRejectedValue(cause);
+
+    let thrown: unknown;
+    try {
+      await makeKmsConfigSource().load({
+        nested: {
+          secret: makeEncryptedValue(),
+        },
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    assert.instanceOf(thrown, Error);
+    assert.match(thrown.message, /KMS decrypt failed.*nested\.secret/);
+    assert.strictEqual(thrown.cause, cause);
+  });
+});

package/src/sources/kms.ts

@@ -0,0 +1,139 @@
+import { DecryptCommand, type DecryptCommandOutput, KMSClient } from '@aws-sdk/client-kms';
+import { z } from 'zod';
+
+import type { ConfigSource } from '../types.js';
+
+const EncryptedValueSchema = z.object({
+  __encrypted: z.literal('aws-kms-v1'),
+  ciphertext: z.string(),
+  context: z.record(z.string(), z.string()),
+});
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isEncryptedValue(value: unknown): boolean {
+  return isPlainObject(value) && Object.hasOwn(value, '__encrypted');
+}
+
+function formatConfigPath(path: (string | number)[]): string {
+  return path.length === 0
+    ? '<root>'
+    : path
+        .map((part, index) =>
+          typeof part === 'number' ? `[${part}]` : index === 0 ? part : `.${part}`,
+        )
+        .join('');
+}
+
+function formatZodIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.join('.') || '<value>'}: ${issue.message}`)
+    .join('; ');
+}
+
+function parseEncryptedValue(value: unknown, path: (string | number)[]) {
+  const result = EncryptedValueSchema.safeParse(value);
+  if (!result.success) {
+    throw new Error(
+      `Malformed encrypted config value at ${formatConfigPath(path)}: ${formatZodIssues(result.error)}`,
+    );
+  }
+
+  return result.data;
+}
+
+async function decryptEncryptedValue(
+  value: unknown,
+  path: (string | number)[],
+  getKmsClient: () => KMSClient,
+): Promise<string> {
+  const encryptedValue = parseEncryptedValue(value, path);
+  const ciphertextBlob = Buffer.from(encryptedValue.ciphertext, 'base64');
+  const kmsClient = getKmsClient();
+
+  let result: DecryptCommandOutput;
+  try {
+    result = await kmsClient.send(
+      new DecryptCommand({
+        CiphertextBlob: ciphertextBlob,
+        EncryptionContext: encryptedValue.context,
+      }),
+    );
+  } catch (error) {
+    throw new Error(`KMS decrypt failed for encrypted config value at ${formatConfigPath(path)}`, {
+      cause: error,
+    });
+  }
+
+  if (!result.Plaintext) {
+    throw new Error(
+      `KMS decrypt result missing Plaintext for encrypted config value at ${formatConfigPath(path)}`,
+    );
+  }
+
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(result.Plaintext);
+  } catch (error) {
+    throw new Error(
+      `KMS decrypt result Plaintext is not valid UTF-8 for encrypted config value at ${formatConfigPath(path)}`,
+      { cause: error },
+    );
+  }
+}
+
+async function decryptEncryptedValuesInPlace(
+  value: unknown,
+  path: (string | number)[],
+  getKmsClient: () => KMSClient,
+): Promise<unknown> {
+  if (isEncryptedValue(value)) {
+    return await decryptEncryptedValue(value, path, getKmsClient);
+  }
+
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      value[index] = await decryptEncryptedValuesInPlace(item, [...path, index], getKmsClient);
+    }
+    return value;
+  }
+
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  for (const [key, childValue] of Object.entries(value)) {
+    value[key] = await decryptEncryptedValuesInPlace(childValue, [...path, key], getKmsClient);
+  }
+
+  return value;
+}
+
+export function makeKmsConfigSource(): ConfigSource {
+  return {
+    load: async (existingConfig) => {
+      let kmsClient: KMSClient | undefined;
+
+      // The client is created lazily so this source remains a no-op when there
+      // are no encrypted values. If a client is created, it's then reused for
+      // all decrypts in this load.
+      const getKmsClient = () => {
+        if (!kmsClient) {
+          const region =
+            typeof existingConfig.awsRegion === 'string' ? existingConfig.awsRegion : undefined;
+
+          // We don't care about sharing configs between clients here; this
+          // client is only used once, typically at application startup.
+          // eslint-disable-next-line @prairielearn/aws-client-shared-config
+          kmsClient = new KMSClient({ region });
+        }
+        return kmsClient;
+      };
+
+      const resolvedConfig = structuredClone(existingConfig);
+      await decryptEncryptedValuesInPlace(resolvedConfig, [], getKmsClient);
+      return resolvedConfig as Partial<typeof existingConfig>;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+export type AbstractConfig = Record<string, unknown>;
+
+export interface ConfigSource<T extends AbstractConfig = AbstractConfig> {
+  load: (existingConfig: T) => Promise<Partial<T>>;
+}