aws / aws/aws-durable-execution-sdk-js
[Feature]: Harden createFileSystemSerdes publication and reference validation
- Dominant language
- TypeScript
- Stars
- 84
- Forks
- 28
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 43
Description
## What would you like?
Harden `createFileSystemSerdes()` so checkpoint file references remain immutable, integrity-checked, and bound to the durable payload that produced them.
The current implementation writes JSON to a deterministic `.json` path with `writeFile`, then stores an unversioned `{"file": ...}` envelope. A later serialization for the same entity can overwrite content referenced by an older checkpoint, and deserialization trusts the file path carried in the envelope.
Previous fixes addressed entity-ID filename encoding and overflow sizing. The remaining desired guarantees are:
- immutable file publication;
- a versioned, self-identifying envelope;
- durable-execution/entity ownership metadata;
- content-integrity and path-safety validation;
- continued support for `ALWAYS`, `OVERFLOW`, previews, URI, and hash modes.
## Possible Implementation
- Serialize once, compute a SHA-256 digest, and create a unique payload file with `writeFile(..., { flag: "wx" })` or equivalent exclusive-create behavior.
- Include an envelope marker/version, owner durable execution ARN, owner entity ID, payload type, file path, and content digest.
- On deserialization, validate the recognized envelope, expected execution directory and filename, base-path containment, symbolic links, owner rules, and content digest.
- Define explicit rules for safe incoming cross-execution references such as invoke input/results. Forwarded exceptions should be decoded and reserialized under the receiving child context when ownership changes.
- Preserve compatibility by continuing to read the current legacy envelope format for an appropriate migration period.
- Document storage lifecycle guidance because immutable publication can leave files that are no longer referenced by the latest checkpoint.
- Extend the cloud coverage tracked by #710 with immutable publication and ownership/integrity scenarios.
## Is this a breaking change?
No. Existing configuration should remain compatible, and legacy envelopes can continue to be readable.
## Does this require an RFC?
Yes.
## Additional Context
The Java SDK filesystem SerDes work in aws/aws-durable-execution-sdk-java#648 uses immutable publication, versioned ownership metadata, content hashes, containment checks, and symbolic-link rejection. This issue requests equivalent guarantees adapted to the async TypeScript implementation.
Contributor guide
Research direction
Start by locating createFileSystemSerdes() and reviewing the existing envelope, publication, and deserialization paths. Compare the requested guarantees with aws/aws-durable-execution-sdk-java#648 and the cloud coverage tracked by #710, then clarify the RFC before implementation. Done means immutable, versioned, ownership-bound, integrity-checked references while preserving legacy envelopes and all listed modes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100