TASK22224: document downloadblob hotfix closure and next file-guard slice

memory-bank/change-log.md

@@ -175,3 +175,43 @@ Validation:
 Follow-ups:
 
 - If desired, next slice can target remaining file-route parity candidates outside this bundle, but this closes the planned TASK22224 scope.
+
+---
+
+### CL-005: TASK22224 downloadblob hotfix closure (path normalization + hash compatibility)
+
+date: 2026-03-23  
+author: Cline  
+scope: `pages/api/file/downloadblob.js`  
+type: change  
+rationale: Close post-merge runtime regressions reported on live links where download URLs alternated between filename-only/full-path blob names and mixed encoded/raw hash input variants.  
+impact: Restored reliable blob downloads without relaxing hash security guarantees (still HMAC validated), and preserved existing caller compatibility across legacy/new URL encodings.  
+status: completed
+
+Summary:
+
+- Hotfix 1 (`f09f3b7`): normalized blob path resolution
+    - accepts both forms of `blobname` input:
+        - filename only (legacy)
+        - full prefixed path (already includes `casefolderID/...`)
+    - prevents double-prefix lookup failures
+    - sets attachment filename from final path segment only
+- Hotfix 2 (`bd3bf68`): hash compatibility validation
+    - validates against a bounded set of canonical query-path variants (raw/encoded combinations for `casefolderID` and `blobname`)
+    - fixes `INVALID_HASH` false negatives for legitimate caller-generated links
+    - keeps strict HMAC requirement in place (no unauthenticated bypass)
+
+Validation:
+
+- `node tests/phase21/file-handler-contract.test.cjs` -> pass (17/17)
+- `node tests/phase21/api-contract-slice1.test.cjs` -> pass
+    - helper: 4/4
+    - file-handler: 17/17
+    - email-handler: 12/12
+    - endpoint-handler: 149/149
+- User confirmation: "downloadblob now works"
+
+Follow-ups:
+
+- Next recommended slice on this branch: complete file-route guard parity for `deleteblob.js`, `deleteblobcase.js`, and `deleteblobrep.js` by aligning hash validation canonicalization and explicit `respondError` contracts (`MISSING_REQUIRED_QUERY`, `INVALID_HASH`, operation-specific `*_FAILED`).
+- Extend `tests/phase21/file-handler-contract.test.cjs` for the above routes with mixed encoded/raw hash cases to lock compatibility.

memory-bank/refactor-backlog.md

@@ -32,6 +32,28 @@ Last updated: 2026-03-12
 - **Target outcome:** Shared guard middleware for hash/auth/input validation + consistent negative-path responses.
 - **Initial scope:** enforce a common pre-handler contract on high-risk routes first.
 
+### Priority 4 — Current slice status (2026-03-23)
+
+- Completed on `TASK22224-file-endpoint-contract-bundle`:
+    - `pages/api/file/downloadblob.js` hardening + hotfix closure
+    - path normalization compatibility (filename-only + prefixed path)
+    - encoded/raw hash validation compatibility guard
+- Confirmed outcome:
+    - user-reported download failures resolved
+    - phase21 file + combined contract suites passing
+
+### Priority 4 — Next recommended slice on this branch
+
+- Target routes:
+    - `pages/api/file/deleteblob.js`
+    - `pages/api/file/deleteblobcase.js`
+    - `pages/api/file/deleteblobrep.js`
+- Scope:
+    - align hash canonicalization strategy with `downloadblob.js`
+    - enforce explicit `respondError` contracts (`MISSING_REQUIRED_QUERY`, `INVALID_HASH`, route-specific `*_FAILED`)
+    - preserve existing success payload shapes
+    - extend `tests/phase21/file-handler-contract.test.cjs` with mixed encoded/raw hash variants and negative paths
+
 ## Priority 5 — Establish minimum automated regression baseline
 
 - **Problem:** Limited automated tests for high-risk logic.