feat(sdk): decryptVersioned and V4-aware crypto.decrypt (MRF envelope support) (2/4)

[kevin9foong]

Problem

Agencies consume FormSG webhooks through the SDK's crypto.decrypt, which only understands V1 content from storage-mode forms. Multirespondent (MRF) webhooks now deliver V4 content wrapped in the MRF envelope (encryptedSubmissionSecretKey on the payload), and the SDK returns null for them, leaving webhook integrators unable to decrypt MRF responses. Closes #9586.

Solution

DecryptParams gains an optional encryptedSubmissionSecretKey. When present, decryption opens the MRF envelope (submission secret key decrypted with the form key, content with the submission key); when absent, content decrypts directly with the form key. The new crypto.decryptVersioned returns the content in its submitted version — DecryptedContent | DecryptedContentV4 | null, discriminated by Array.isArray(result.responses) — with the V4 arm carrying the honestly-populated per-submission secret key. crypto.decrypt keeps its exact signature: it now delegates to decryptVersioned and adapts the V4 arm through adaptV4ToV1, dropping the key. Content version is detected by plaintext shape (array → V1, provenance-carrying record → V4, empty record → empty V4, anything else → null); the version param stays ignored as it always has been. Design is per ADR 0001; the README gains the consumer-contract section "Decrypting Multirespondent (V4) Submissions".

Alternatives considered

• We considered letting V4-shaped content decrypted without an MRF envelope return a result with submissionSecretKey set to the form secret key, but that hands consumers a key with form-wide blast radius disguised as a per-submission key, so it returns null instead. Making submissionSecretKey optional on the V4 arm was also skipped — it would widen the published DecryptedContentV4 type that cryptoV3.decryptToV4 already returns with the key required.
• We considered honouring the version field instead of shape detection, but there is no submission-version constant for V4 content (MRF submissions are version 3 whether their plaintext is V3 or V4), and making a long-ignored parameter load-bearing would break integrators who pass junk versions today (per ADR 0001).
• Verified content is decrypted only after shape validation, matching the legacy decrypt ordering — otherwise a malformed payload with verified content and no signing key would start throwing MissingPublicKeyError where it previously returned null.

Breaking Changes

No - backwards compatible. decrypt's signature and V1 behaviour are unchanged; the pre-existing crypto suite passes unmodified.

Tests

TC1: MRF webhook round-trip

• Point an MRF form's webhook at a consumer using this SDK build
• Submit a multirespondent response and pass the payload (including encryptedSubmissionSecretKey) to crypto.decrypt — responses arrive as FormField[]
• Pass the same payload to crypto.decryptVersioned — V4 structure with submissionSecretKey matching the envelope

TC2: storage-mode regression

• Submit to a storage-mode form webhook and confirm crypto.decrypt output is unchanged from the previous SDK version

[kevin9foong]

isFieldResponsesV4 returns false for {} (it inspects the first entry), but the PRD defines an empty record as a valid V4 submission with no answered fields. The empty check therefore runs before the first-entry check rather than tightening isFieldResponsesV4, which ADR 0001 says must be reused unchanged.