feat: introduce TTL-based caching for Secrets Manager

[TheUnderScorer]

This pull request introduces support for configurable TTL (time-to-live) caching of secrets retrieved from AWS Secrets Manager in the CloudFront proxy.

Caching improvements:

• Added a generic TTLCache class in proxy/utils/cache.ts that supports storing, retrieving, expiring, and clearing cached items based on a default or per-item TTL.
• Replaced the previous in-memory cache in retrieve-secret.ts with the new TTLCache, defaulting to a 5-minute expiry, and updated the cache logic to support custom TTLs.

Secret retrieval and configuration:

• Updated the SecretsManagerVariables class and its usage to accept an optional TTL value for secret caching, which is passed through to the cache. [1] [2] [3]
• Introduced the getSecretCacheTtlMs helper in proxy/utils/headers.ts to extract the TTL value from the fpjs_proxy_secret_cache_ttl_ms request header, allowing per-request cache configuration. [1] [2]

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	92.27% (-0.12% 🔻)	716/776
🟢	Branches	85.39% (-0.6% 🔻)	187/219
🟢	Functions	91.22% (+0.5% 🔼)	135/148
🟢	Lines	92.4% (-0.13% 🔻)	681/737

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / cache.ts	100%	90%	100%	100%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / headers.ts	96.15% (-3.85% 🔻)	92.59% (-7.41% 🔻)	100%	95.89% (-4.11% 🔻)

Test suite run success

204 tests passing in 22 suites.

Report generated by 🧪jest coverage report action from da20f1d

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	92.26	85.38	91.21	92.4
🟢	mgmt-lambda	98.93	93.33	100	98.93
🟢	DefaultSettings.ts	100	100	100	100
🟢	app.ts	97.91	95	100	97.91	26
🟢	auth.ts	100	100	100	100
🟢	exceptions.ts	100	66.66	100	100	20
🟢	routing.ts	100	100	100	100
🟢	mgmt-lambda/handlers	87.22	72.5	93.33	87.15
🟢	errorHandlers.ts	100	71.42	100	100	22,41
🟡	statusHandler.ts	80	50	100	80	76-80,84-89
🟢	updateHandler.ts	87.21	75.86	87.5	87.12	50-51,67-68,139-142,214,219-228,290-291,319
🟢	mgmt-lambda/utils	81.25	88.88	66.66	100
🟢	cloudfrontUtils.ts	100	88.88	100	100	6
🔴	delay.ts	40	100	0	100
🟢	proxy/handlers	98.48	94.59	100	98.48
🟢	handleIngress.ts	97.43	92.3	100	97.43	62
🟢	handleStatus.ts	100	95.83	100	100	57
🟡	proxy/test	77.77	100	50	71.42
🟡	aws.ts	77.77	100	50	71.42	4-5
🟢	proxy/test/utils/customer-variables	100	100	100	100
🟢	in-memory-customer-variables.ts	100	100	100	100
🟢	proxy/utils	89.6	78.57	89.47	89.4
🟢	buffer.ts	100	100	100	100
🟢	cache-control.ts	100	100	100	100
🟢	cache.ts	100	90	100	100	15
🟢	cookie.ts	100	100	100	100
🔴	generateErrorResponse.ts	23.07	100	25	25	15-30
🟢	headers.ts	96.15	92.59	100	95.89	240-242
🔴	is-blob.ts	0	0	0	0	6-7
🟢	log.ts	85.71	33.33	100	83.33	11
🟢	paths.ts	100	87.5	100	100	19
🟢	request.ts	93.54	66.66	85.71	91.66	7-8
🟢	routing.ts	100	100	100	100
🔴	string.ts	14.28	100	0	14.28	2-8
🟢	traffic.ts	100	100	100	100
🟢	transport.ts	93.1	62.5	100	93.1	33,58
🟢	proxy/utils/customer-variables	98.79	88.88	95.45	98.52
🟢	customer-variables.ts	100	100	100	100
🟢	defaults.ts	100	100	100	100
🟢	header-customer-variables.ts	100	100	100	100
🟢	maybe-obfuscate-variable.ts	100	100	100	100
🟢	selectors.ts	96.66	100	90	94.11	22
🟢	types.ts	100	75	100	100	19
🟢	proxy/utils/customer-variables/secrets-manager	95.71	100	100	95.65
🟢	normalize-secret.ts	100	100	100	100
🟢	retrieve-secret.ts	100	100	100	100
🟢	secrets-manager-variables.ts	87.5	100	100	87.5	31,53-58
🟢	validate-secret.ts	100	100	100	100

[Copilot]

Pull request overview

This PR introduces TTL-based caching for AWS Secrets Manager–backed customer variables, enabling secrets to be refreshed after a configured time window while keeping a default cache duration.

Changes:

• Add a generic TTLCache utility (default TTL + optional per-entry TTL) and unit tests for it.
• Switch Secrets Manager secret caching from a permanent in-memory map to TTLCache with a 5-minute default TTL.
• Allow overriding the secrets cache TTL via a CloudFront origin custom header (fpjs_proxy_secret_cache_ttl_ms) and thread it through the request path.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
proxy/utils/headers.ts	Adds header parsing helper for secret cache TTL configuration.
proxy/utils/customer-variables/secrets-manager/secrets-manager-variables.ts	Plumbs optional TTL into Secrets Manager secret retrieval.
proxy/utils/customer-variables/secrets-manager/retrieve-secret.ts	Replaces map-based cache with TTLCache and supports per-call TTL override.
proxy/utils/cache.ts	Introduces the TTLCache implementation.
proxy/test/utils/cache.test.ts	Adds unit tests covering TTLCache behavior (expiry, custom TTL, null values, etc.).
proxy/app.ts	Wires TTL header parsing into SecretsManagerVariables instantiation.
.changeset/cuddly-tires-tan.md	Declares a minor release for introducing TTL-based secret caching.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Introduces a reusable TTL-based in-memory cache and applies it to AWS Secrets Manager secret retrieval to enable default and per-request cache expiration control within the CloudFront proxy.

Changes:

• Added a generic TTLCache utility with per-item TTL override support.
• Switched Secrets Manager secret caching to use TTLCache with a 5-minute default TTL and optional custom TTL.
• Added a helper to read a secret-cache TTL value from CloudFront origin custom headers and wired it into request handling.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
proxy/utils/cache.ts	New TTLCache implementation used as the shared caching primitive.
proxy/utils/customer-variables/secrets-manager/retrieve-secret.ts	Replaces Map-based cache with TTLCache and adds optional TTL parameter.
proxy/utils/customer-variables/secrets-manager/secrets-manager-variables.ts	Threads optional cache TTL through to secret retrieval.
proxy/utils/headers.ts	Adds getSecretCacheTtlMs helper for reading/parsing TTL from headers.
proxy/app.ts	Wires parsed TTL into SecretsManagerVariables construction per request.
proxy/test/utils/cache.test.ts	New unit tests for TTLCache behavior.
proxy/test/utils/customer-variables/secrets-manager/retrieve-secret.test.ts	Adds fake-timer-based test to verify cache expiry/refetch behavior.
.changeset/cuddly-tires-tan.md	Declares a minor release for the new TTL caching feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[github-actions]

🚀 Following releases will be created using changesets from this PR:

@fingerprint/aws-cloudfront-proxy@2.2.0-rc.0

Minor Changes

• Add support for API V4 (ff1b644)
• Introduce TTL for secret caching (fd2eef5)

Bug Fixes

• bundle AWS SDKs inside Lambda functions to avoid runtime issues (95f8d78)