mustflow 2.116.1 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/file-upload-security-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.file-upload-security-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: file-upload-security-review
@@ -30,7 +30,9 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Review file upload security as a full lifecycle, not as an extension or MIME-type checklist.
+Review file upload security as a full lifecycle, not as an extension, MIME-type, or request-size
+checklist. Accepting a file also selects parsers, expansion work, storage authority, and a future
+serving path under attacker influence.
 
 The review question is not "does the upload route block `.exe`?" It is "what final bytes, filename,
 storage key, parser, visibility state, authorization check, and response headers can this uploaded
@@ -80,6 +82,9 @@ file reach after it enters the system?"
 - File identity ledger: original filename, normalized filename, final storage key, bucket or root,
   database record id, tenant or owner, checksum, size, content type, detected type, extension,
   visibility, status, and cleanup owner.
+- Storage-access ledger: public opaque file id, tenant and object version used for authorization,
+  internal exact object key or root capability, original display name, storage adapter owning raw
+  path or key access, and every caller that can bypass that adapter.
 - Validation ledger: extension allowlist, decoding and normalization, content-type trust, signature
   checks, parser-based validation, image rewriting, metadata stripping, antivirus, CDR, size limits,
   count limits, quota, rate limits, and failure behavior.
@@ -91,6 +96,17 @@ file reach after it enters the system?"
   admin preview, email attachments, and public/private transition.
 - Existing tests, abuse cases, security docs, storage policy docs, configured command intents, and
   any unavailable cloud or scanner evidence.
+- Byte-lineage ledger: quarantine object key and immutable version, received-byte digest, inspection
+  input digest, scanner and parser policy versions, approved object key and version, approved-byte
+  digest, and the operation that promoted or copied the approved bytes.
+- Decoded-resource ledger: raster pixels and frames, document pages and layers, archive entries and
+  actual emitted bytes, parser CPU, memory, temporary disk, file descriptors, child processes,
+  elapsed time, output bytes, concurrency, retries, storage, and external-service cost.
+- Remote-fetch ledger: original URL, canonical scheme and host, IDNA result, allowed port and method,
+  every resolved A and AAAA address, the address bound to the connection, TLS hostname, redirect
+  hops, egress decision, forwarded headers, and response limits.
+- Read `references/file-upload-parser-ssrf-resource-checklist.md` when native or complex parsers,
+  archives, direct object-storage uploads, remote fetches, or resource-safety claims are in scope.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -126,6 +142,8 @@ file reach after it enters the system?"
      store, record metadata, scan, transform, promote, preview, download, delete, and cleanup.
    - Include admin preview, email attachment, export, CDN, search index, and worker paths when they
      can read the uploaded bytes.
+   - Prove each accepted format and reachable parser is required by the product surface. Reject
+     unsupported containers or transformations instead of hardening an accidental feature.
 2. Treat frontend restrictions as usability only.
    - `<input accept>`, client-side size checks, mobile picker filters, and JavaScript extension
      checks do not prove security.
@@ -139,13 +157,24 @@ file reach after it enters the system?"
    - Blocklists for `.php`, `.jsp`, `.asp`, `.html`, `.svg`, config files, legacy plugin types, or
      executable server extensions are not enough by themselves.
 5. Validate the final storage name and key, not only the original filename.
-   - Confirm the server generates the stored basename, object key, upload id, and path.
+   - Prefer external APIs that accept an opaque file id rather than a path, folder, prefix, or
+     storage key. Resolve authorization from the trusted `(tenant, object_id, version)` tuple before
+     loading the internal storage locator.
+   - Treat the original filename as display metadata. Confirm the server generates the stored
+     basename, exact object key, upload id, and local relative path.
+   - Keep raw local paths and object-store keys private to one storage adapter. Expose typed
+     operations such as get-by-authorized-id, stream-put, and extract-to-staging rather than
+     allowing controllers, workers, previews, and admin tools to reconstruct locators independently.
    - Treat `destination`, `folder`, `key`, `path`, `filename`, `bucket`, and callback-provided
      storage locations as attacker-controlled unless derived on the server.
 6. Prove path containment after normalization and symlink resolution.
-   - `path.join(uploadDir, userName)` is not enough.
-   - Check real path containment, absolute paths, drive letters, backslashes, `..`, symlinks,
-     hardlinks, case-insensitive filesystems, and reserved names when local files are used.
+   - `path.join(uploadDir, userName)`, `realpath`, and a prefix check are early filters, not proof
+     when an attacker can change the tree.
+   - For local files, apply `cross-platform-filesystem-safety`: open relative to a trusted root
+     descriptor, HANDLE, or verified runtime root capability and keep the same opened-object
+     identity through scanning, transformation, promotion, and deletion.
+   - For object storage, directories are not a security boundary. Use the exact server-resolved key
+     and immutable version; do not authorize with user-built prefixes or prefix matching.
 7. Bound filenames and storage keys.
    - Check filename length, full path length, database column length, object-storage key length, log
      field length, CDN cache-key length, and error behavior for oversized or malformed names.
@@ -166,10 +195,11 @@ file reach after it enters the system?"
     - Polyglot files, metadata payloads, trailing content, and container formats can pass simple
       signature checks while still reaching dangerous parsers.
 12. Re-encode images when possible.
-    - Decode and write a new image instead of storing user bytes directly when the product only
-      needs raster images.
-    - Strip EXIF, comments, thumbnails, ICC surprises, and other metadata unless product policy
-      intentionally preserves them.
+    - Decode pixels and write a new image instead of storing user bytes directly when the product
+      only needs raster images.
+    - Apply orientation before size policy, choose a fixed output format and color space, and add
+      back only metadata the product explicitly needs. Do not copy arbitrary EXIF, comments,
+      thumbnails, profiles, or trailing bytes into the approved object.
 13. Treat SVG and HTML as active content.
     - Do not group SVG with ordinary raster images.
     - If SVG is allowed, require sanitization or rasterization, separate origin or strict CSP,
@@ -178,36 +208,66 @@ file reach after it enters the system?"
     - Check macros, embedded objects, JavaScript, external links, parser vulnerabilities, preview
       isolation, antivirus or CDR, and whether downloads are safer than inline rendering.
 15. Review archive extraction as the main feature.
-    - For ZIP, tar, and nested archives, validate every entry path after normalization and prove it
-      stays inside the extraction root.
-    - Bound extracted file count, total uncompressed bytes, compression ratio, nesting depth,
-      symlinks, hardlinks, absolute paths, duplicate entries, and processing time.
+   - For ZIP, tar, and nested archives, parse the complete bounded entry set before the first write
+     when feasible. Build one destination graph for duplicate normalized names, case and Unicode
+     aliases, alternate separators, file-directory prefix conflicts, and order-dependent link
+     traversal, then carry the validated entry object into extraction.
+   - Reject symlinks, hardlinks, devices, FIFOs, absolute paths, duplicate normalized names, and
+     unsupported entry types unless a narrower policy proves them safe.
+   - Ignore archive owner, group, mode, setuid, setgid, sticky, ACL, xattr, capability, and timestamp
+     metadata unless explicitly required and allowlisted. Create regular files and directories with
+     service-owned permissions inside a new attacker-nonwritable staging directory.
+   - Count actual bytes emitted while streaming extraction; do not trust archive headers or only a
+     compression ratio. Bound declared and actual size, sparse logical size and allocated storage,
+     entry and directory count, per-entry and cumulative emitted bytes, name length, depth, nesting,
+     parser work, and time under one shared budget.
+   - Pin and review the runtime extraction API and security options. Library filtering or path
+     cleanup remains defense in depth and does not replace the application entry policy.
+    - Treat every extracted entry as a fresh hostile upload with its own type, parser, filename,
+      and publication decision. Nested archives consume the parent budget rather than resetting it.
 16. Review CSV import and export for formula injection.
     - If user-supplied cells may later be opened in spreadsheets, handle cells beginning with `=`,
       `+`, `-`, `@`, tabs, carriage returns, line feeds, separators, quotes, and confusable
       variants according to local policy.
 17. Review remote URL import as SSRF plus upload.
-    - Check scheme allowlists, redirect chains, DNS rebinding, localhost, private networks,
-      link-local metadata endpoints, non-HTTP schemes, credential forwarding, response size,
-      timeout, and final file validation.
+    - Prefer product-owned identifiers or provider integrations over arbitrary URLs. If URLs remain,
+      parse once and carry the same structured result into connection setup.
+    - Fix allowed schemes, ports, and methods; canonicalize IDNA hostnames; inspect every A and AAAA
+      result plus CNAME outcome; normalize IPv4, IPv6, mapped, loopback, private, link-local,
+      multicast, unspecified, and metadata ranges before connecting.
+    - Bind one validated address to the socket while preserving the canonical hostname for TLS and
+      HTTP host semantics. Revalidate every redirect as a new request and prevent DNS or proxy
+      layers from silently choosing a different address.
+    - Do not forward inbound authorization, cookies, proxy credentials, or arbitrary user headers.
+      Enforce egress policy, connect/read/total deadlines, response-byte and decoded-work limits,
+      then send the fetched response through the same quarantine and upload pipeline.
 18. Keep scanner and conversion work behind a publication gate.
     - A file that is pending scan, failed scan, pending conversion, or failed conversion should not
       be public, previewable, downloadable, indexed, or emailed unless policy explicitly allows it.
+    - Bind inspection results to an immutable quarantine object version and digest. A database row
+      saying `clean` is not proof if the referenced object can be overwritten afterward.
 19. Sandbox file parsers and scanners.
     - ImageMagick, ffmpeg, LibreOffice, PDF parsers, OCR tools, unzip, antivirus, and CDR engines
-      need low privilege, no unnecessary network, timeouts, memory and CPU limits, temporary
-      directory isolation, and controlled input paths.
+      need low privilege, no unnecessary network, explicit coder or delegate allowlists, CPU,
+      memory, temporary disk, file descriptor, child-process, wall-time, and output limits,
+      temporary-directory isolation, and controlled input paths.
+    - Treat timeout, crash, partial output, unavailable scanner, and limit exhaustion as rejection or
+      quarantine, never as an implicit pass.
 20. Validate direct-to-storage uploads in two phases.
     - Before issuing a signed upload URL, authorize the target resource and fix method, bucket, key,
       prefix, content type policy, checksum, size range, overwrite policy, and expiration.
-    - After upload completion, verify actual object metadata before promoting it out of quarantine.
+    - After upload completion, read and hash the exact immutable object version that scanners and
+      parsers will inspect. Promote or copy only that exact version, record the approved digest and
+      policy or tool versions, and prevent the client from overwriting the approved destination.
 21. Treat presigned URLs as delegated authority.
     - Check method, bucket, key, prefix, expiry, reuse, checksum, content-length range, content type,
       ACL or public-read flags, revocation behavior, CDN caching, and whether the creator's
       privileges are too broad.
 22. Enforce tenant boundaries in storage keys and metadata.
-    - Server-generated keys should include trusted tenant, organization, project, or resource
-      context plus a random id when multi-tenant isolation matters.
+   - Authorize the `(tenant, object_id, version)` lookup before resolving the internal key. Knowing
+     or guessing a storage locator must not grant access.
+   - Server-generated keys should include trusted tenant, organization, project, or resource
+     context plus a random id when multi-tenant isolation matters.
     - Reads, writes, deletes, overwrites, cleanup, and promotion must use the same boundary.
 23. Recheck authorization at download and preview time.
     - Upload permission is not download permission.
@@ -216,16 +276,29 @@ file reach after it enters the system?"
 24. Set response headers deliberately.
     - Use safe `Content-Type`; default ambiguous private downloads to `application/octet-stream`.
     - Use `Content-Disposition: attachment` when inline rendering is not required.
-    - Add `X-Content-Type-Options: nosniff` and review CSP, origin isolation, and CDN header
-      preservation where browser execution risk exists.
+   - Add `X-Content-Type-Options: nosniff` and review CSP, origin isolation, and CDN header
+     preservation where browser execution risk exists.
+   - Treat `Content-Disposition` filenames as presentation only. Remove CR/LF and path segments,
+     generate a conservative ASCII `filename` fallback plus a correctly encoded UTF-8 `filename*`,
+     and never feed either value back into storage lookup or authorization.
+   - Serve static assets through an immutable build manifest. Keep SPA fallback fixed to one known
+     `index.html` after route classification instead of trying alternate extensions or arbitrary
+     filesystem candidates derived from the URL.
 25. Treat filename display as an injection surface.
     - Escape original filenames in HTML, email, admin tables, JSON-in-script, logs, and support
       views.
-    - For `Content-Disposition`, remove CR/LF and encode filenames safely for header context.
+   - For `Content-Disposition`, remove CR/LF and encode filenames safely for header context.
+   - Escape control characters and line breaks before logging rejected names. Record a bounded
+     display value and stable policy code, not the raw attacker-controlled string.
 26. Apply resource limits at every layer.
     - Bound request body size, per-file size, file count, concurrent uploads, chunk count, multipart
       sessions, user quota, tenant quota, daily quota, extracted size, transformed size, preview
       time, and retry volume.
+    - Bound decoded pixels, cumulative animation frames, pages, layers, archive entries and actual
+      emitted bytes, parser CPU and memory, temporary disk, file descriptors, child processes,
+      output bytes, queue depth, concurrent conversions, storage growth, and paid external work.
+    - Put deadlines and cancellation around the whole operation; a per-read timeout does not cap a
+      peer that continuously dribbles bytes.
 27. Revalidate chunked and multipart uploads at assembly time.
     - Check final file size, content type, signature, chunk order, chunk count, checksum, session
       expiration, stale partial cleanup, and final key ownership after assembly.
@@ -241,7 +314,23 @@ file reach after it enters the system?"
     - Cover disallowed type, spoofed MIME, renamed extension, encoded extension, double extension,
       oversize body, quota exceeded, path traversal, archive escape, zip bomb, SVG active content,
       CSV formula, unauthorized upload target, unauthorized download, pending-scan download,
-      presigned overwrite, stale multipart session, and remote URL SSRF where relevant.
+      presigned overwrite, stale multipart session, type-detector disagreement, cumulative image
+      pixels or frames, archive special entries and actual emitted-byte overflow, parser timeout or
+      crash, quarantine-object replacement, DNS or redirect rebinding, forbidden egress, credential
+      forwarding, fetched-response revalidation, path-shaped public API input, prefix-authorized
+      object keys, file-directory archive conflicts, archive metadata restoration, sparse logical
+      size overflow, `Content-Disposition` CR/LF, static-extension fallback, and raw-name log
+      injection where relevant.
+    - Assert rejected, crashed, timed-out, or partially processed files never become public,
+      previewable, downloadable, indexed, emailed, or reusable as approved inputs.
+    - Classify each finding as publication-blocking, high-risk but contained, or defense-in-depth,
+      and name the exact missing invariant or evidence that would change the decision.
+      - Use publication-blocking when exact-byte identity, authorization, parser or expansion
+        bounds, remote-destination control, or fail-closed publication gating is missing.
+      - Use high-risk but contained only when an independent enforced control proves the risky
+        bytes or operation cannot reach a published, privileged, or cross-tenant path. Partial
+        hardening of the same vulnerable control is not containment.
+      - Use defense-in-depth only after the required lifecycle invariants are already proven.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -250,8 +339,14 @@ file reach after it enters the system?"
   record, validation gates, processing tools, visibility state, serving path, and cleanup owner.
 - Client-provided filenames, MIME labels, paths, keys, URLs, sizes, checksums, tenants, owners, and
   visibility flags are either ignored, verified, or explicitly reported as risky.
+- Public file identifiers, authorization tuples, display names, internal exact keys, immutable
+  versions, and local root capabilities are distinct; raw locators remain behind one storage adapter.
 - File type validation is tied to normalized final names and actual bytes, not only extension or
   request headers.
+- Scanner and parser results are bound to the exact immutable object version and digest later
+  promoted or served, with tool or policy versions recorded where decisions depend on them.
+- Decoded, expanded, parser, concurrency, output, storage, and external-cost budgets are explicit;
+  archive and remote-fetch paths cannot reset or bypass them.
 - Upload, processing, promotion, preview, download, CDN, email, admin, and cleanup paths are checked
   or explicitly scoped out.
 - Denial-case tests or missing evidence are named from the attacker-controlled file lifecycle.
@@ -273,9 +368,10 @@ Use configured oneshot command intents when available:
 - `mustflow_check`
 
 Prefer the narrowest configured tests that prove file lifecycle denial behavior: disallowed type,
-spoofed MIME, normalized extension bypass, path traversal, archive escape, resource limit,
-unauthorized upload target, unauthorized download, pending-scan access, presigned policy, and remote
-URL rejection.
+spoofed MIME, normalized extension bypass, path traversal, archive escape or actual-byte overflow,
+decoded-media and parser limits, immutable-object binding, unauthorized upload target, unauthorized
+download, pending-scan access, presigned policy, DNS and redirect rebinding, and fetched-response
+revalidation.
 
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
@@ -295,10 +391,15 @@ URL rejection.
 ## Output Format
 
 - File upload security reviewed
-- Upload entrypoints, file identity, storage, validation, processing, serving, and cleanup map
-- Filename, type, path, overwrite, web-root, parser, archive, CSV, remote URL, scanner, signed URL,
-  tenant, authorization, header, and resource-limit findings
+- Upload entrypoints, byte lineage, immutable object versions and digests, storage, validation,
+  processing, serving, and cleanup map
+- Filename, opaque identity, exact storage key, root capability, type, path, overwrite, web-root,
+  static-manifest serving, parser isolation, decoded-resource, archive metadata and sparse budgets, CSV,
+  remote-fetch resolution and redirect, scanner, signed URL, tenant, authorization, header, and
+  resource-limit findings
 - Fixes made or recommendation
+- Finding disposition: publication-blocking, high-risk but contained, or defense-in-depth, with the
+  enforcing control and missing invariant or evidence needed to change the decision
 - Denial tests, fixtures, or invariant evidence
 - Command intents run
 - Skipped checks and reasons

package/templates/default/locales/en/.mustflow/skills/file-upload-security-review/references/file-upload-parser-ssrf-resource-checklist.md

@@ -0,0 +1,306 @@
+# File Upload Parser, SSRF, and Resource Checklist
+
+Use this reference when the short procedure needs concrete review ledgers for complex parsers,
+archive extraction, direct object-storage uploads, remote imports, or resource-exhaustion claims.
+It is a review aid, not a universal numeric policy. Record repository-specific limits and evidence.
+
+## Contents
+
+1. [Lifecycle and publication states](#1-lifecycle-and-publication-states)
+2. [Byte lineage and immutable objects](#2-byte-lineage-and-immutable-objects)
+3. [Type and parser decision matrix](#3-type-and-parser-decision-matrix)
+4. [Decoded media and document budgets](#4-decoded-media-and-document-budgets)
+5. [Archive extraction ledger](#5-archive-extraction-ledger)
+6. [Remote-fetch SSRF ledger](#6-remote-fetch-ssrf-ledger)
+7. [Parser sandbox and capability matrix](#7-parser-sandbox-and-capability-matrix)
+8. [Resource, concurrency, and cost budget](#8-resource-concurrency-and-cost-budget)
+9. [Layer responsibility handoff](#9-layer-responsibility-handoff)
+10. [Denial and differential test matrix](#10-denial-and-differential-test-matrix)
+11. [Primary reference anchors](#11-primary-reference-anchors)
+
+## 1. Lifecycle and publication states
+
+Model visibility as an explicit state machine. A useful minimum is:
+
+`receiving -> quarantined -> inspecting -> approved -> published`
+
+Terminal or side states include `rejected`, `processing_failed`, `expired`, and `deleted`.
+
+For every state, record:
+
+| Question | Evidence |
+| --- | --- |
+| Who may write or replace bytes? | Storage policy and application authorization |
+| Who may read bytes? | Download, preview, worker, admin, and support paths |
+| Which parser may run? | Tool and policy version |
+| Can a CDN, indexer, emailer, or previewer observe it? | Publication gate |
+| What advances the state? | Atomic condition and authenticated actor |
+| What happens on timeout, crash, or unavailable scanner? | Fail-closed transition |
+
+Do not treat a `clean = true` column as the state machine. The decision must identify the exact
+bytes inspected and the exact bytes made visible.
+
+## 2. Byte lineage and immutable objects
+
+Maintain this ledger across receive, inspect, transform, promote, and serve:
+
+| Field | Required meaning |
+| --- | --- |
+| `upload_id` | Server-issued lifecycle identifier |
+| `quarantine_key` | Server-generated private location |
+| `quarantine_version` | Immutable object version or equivalent generation id |
+| `received_digest` | Digest computed from bytes actually received |
+| `inspected_digest` | Digest of exact scanner/parser input |
+| `inspection_policy_version` | Allowlist, parser, scanner, and budget policy identity |
+| `derived_digest` | Digest of rewritten or converted output when applicable |
+| `approved_key` and `approved_version` | Exact immutable object selected for serving |
+| `approved_digest` | Digest verified during promotion or copy |
+| `publication_event` | Atomic operation that made the object visible |
+
+Reject these broken chains:
+
+- the client can overwrite a quarantined object after inspection;
+- the scanner reads `key` without an immutable version while the uploader can replace `key`;
+- metadata is approved but a later download resolves a different object generation;
+- transformation output is public before its own type and resource checks finish;
+- promotion copies the latest object instead of the inspected object;
+- retries overwrite a prior approved destination without an explicit replacement policy.
+
+Keep these identities separate:
+
+| Identity | Security role |
+| --- | --- |
+| Public `file_id` | Opaque request identifier with no path meaning. |
+| `(tenant, object_id, version)` | Authorization lookup tuple resolved before any storage locator is used. |
+| Original filename | Display metadata only; never a storage key or authorization fact. |
+| Exact object key and immutable version | Server-owned object-store locator returned by the authorized record. Prefix agreement is not authorization. |
+| Local root capability and validated relative entry | Filesystem adapter authority; never exposed as a controller or queue string. |
+
+Require one storage adapter to own raw path and object-key APIs. Controllers, workers, thumbnailers,
+archive tools, admin surfaces, and serving code should consume typed file identities or opened streams
+rather than reconstructing paths or prefixes independently.
+
+## 3. Type and parser decision matrix
+
+Do not ask whether one detector is authoritative. Ask which parser the product needs and which
+evidence is sufficient to select it.
+
+| Signal | Use | Never proves alone |
+| --- | --- | --- |
+| Normalized extension | Product allowlist and UX | Actual byte format |
+| Request `Content-Type` | Logging and disagreement detection | Safe parser choice |
+| Signature or magic | Candidate family | Entire container safety |
+| Structural parser | Format conformance | Safe active content or bounded cost |
+| Rewrite/conversion | Produces controlled derivative | Safety if parser is unbounded |
+
+Record disagreement policy. An allowed extension with a mismatched signature or parser result
+should not silently choose whichever interpretation is most permissive.
+
+For raster-only products, prefer decode-to-pixels and deterministic rewrite. Apply orientation,
+then enforce dimensions, select a fixed output format and color space, and add back only required
+metadata. Do not preserve arbitrary original chunks or trailing bytes.
+
+Treat SVG, HTML, PDF, Office, media containers, fonts, and archives as parser-bearing formats with
+their own active-content and resource policies.
+
+## 4. Decoded media and document budgets
+
+Compressed bytes are only the wire envelope. Record limits on decoded work:
+
+| Format family | Minimum budget dimensions |
+| --- | --- |
+| Raster image | Width, height, total pixels, channels, bit depth, output bytes |
+| Animated image | Per-frame pixels, cumulative frame pixels, frame count, duration |
+| Layered image | Layers, cumulative layer pixels, memory, temporary disk |
+| PDF | Pages, objects, recursion, embedded files, render pixels, output bytes |
+| Office document | Entries, XML nodes, relationships, embedded objects, pages or slides |
+| Audio/video | Duration, tracks, dimensions, frames, decoded bytes, transcode time |
+| OCR | Input pixels or pages, languages, CPU, elapsed time, output text bytes |
+
+Limits must apply before or during allocation. A check performed only after a decoder has allocated
+the full image or document does not protect the process.
+
+For multi-item containers, track both per-item and cumulative budgets. An animation with many small
+frames or a PDF with many modest pages can exhaust resources while each item passes alone.
+
+## 5. Archive extraction ledger
+
+Before extraction, define allowed archive families and allowed entry types. During extraction,
+record and enforce:
+
+| Budget or invariant | Enforcement point |
+| --- | --- |
+| Complete bounded entry inventory | Before the first filesystem write when the format permits it |
+| File-directory prefix graph | Before accepting both `a` and `a/b` or another order-dependent topology |
+| Normalized contained path | Before creating each entry |
+| Duplicate normalized name | Before overwrite or allocation |
+| Entry type | Before filesystem operation |
+| Metadata allowlist | Before applying owner, group, mode, timestamp, ACL, xattr, or capability fields |
+| Per-entry emitted bytes | While streaming output |
+| Logical size and sparse extents | Before and during allocation |
+| Cumulative emitted bytes | Shared counter across all entries |
+| Entry count | Before accepting the next entry |
+| Nesting depth | Before opening a nested container |
+| Parser CPU and elapsed time | Whole extraction deadline |
+| Temporary disk and files | Sandbox or quota boundary |
+
+Reject symlinks, hardlinks, devices, FIFOs, absolute paths, traversal, alternate separators,
+reserved names, and duplicate normalized destinations unless the product has a narrower explicit
+contract. Do not trust declared uncompressed sizes; stop when actual emitted bytes exceed budget.
+
+Reject case, Unicode, trailing-dot, trailing-space, short-name, and separator aliases under the
+final consumer platform. Preserve the validated entry object through extraction so a second parser
+cannot reinterpret the raw name. Accept regular files and directories only by default, use exclusive
+creation below a root capability, and never merge into an existing or attacker-writable tree.
+
+Do not restore archive uid, gid, owner names, original modes, setuid, setgid, sticky bits, ACLs,
+xattrs, capabilities, or timestamps by default. Sparse entries require both logical-size and actual
+storage budgets. Extract into a new private staging directory and publish only the verified tree.
+
+Library path cleanup, extraction filters, or non-local-name warnings are versioned defense in depth.
+Pin the runtime and API option, but keep the application entry, collision, metadata, capability,
+and resource policies independent of the current library default.
+
+Each extracted regular file re-enters filename, type, parser, authorization, and publication
+checks. Nested containers consume the same parent budget. They do not get a fresh unlimited quota.
+
+## 6. Remote-fetch SSRF ledger
+
+Arbitrary URL import combines network authority with the upload pipeline. Prefer provider-owned ids
+or preconfigured integrations. If arbitrary URLs are necessary, record every decision:
+
+| Phase | Required evidence |
+| --- | --- |
+| Parse | One strict parser result; no validate-with-one, connect-with-another split |
+| Scheme and method | Small fixed allowlist, normally `https` and `GET` |
+| Host | Canonical host and IDNA result; reject ambiguous userinfo and fragments |
+| Port | Fixed or narrow allowlist |
+| Resolve | Every A and AAAA result plus relevant CNAME outcome |
+| Address policy | Normalized IPv4, IPv6, and mapped-address classification |
+| Connect | One validated address bound to the socket |
+| TLS and HTTP | Canonical hostname retained for certificate and host semantics |
+| Redirect | Every hop reparsed, resolved, classified, and budgeted |
+| Headers | No inbound auth, cookies, proxy credentials, or arbitrary user headers |
+| Egress | Network firewall or proxy independently blocks forbidden ranges |
+| Response | Header, body, decoded-work, connect, read, and total deadline limits |
+| Handoff | Response enters quarantine as a new hostile upload |
+
+Reject loopback, private, link-local, multicast, unspecified, reserved, and infrastructure metadata
+destinations according to deployment policy. Check both address families. A hostname with one public
+and one forbidden result is not safely public just because the first answer looked acceptable.
+
+Disable redirects by default. When enabled, cap hop count and treat each `Location` as fresh input.
+Do not let a generic HTTP client silently re-resolve or follow a proxy path that bypasses the
+validated address.
+
+## 7. Parser sandbox and capability matrix
+
+For each native tool, library, delegate, or subprocess, record:
+
+| Capability | Policy question |
+| --- | --- |
+| Input formats | Which coders or parsers are enabled? |
+| Delegates | Can input launch another interpreter or executable? |
+| Filesystem read | Can it read outside the isolated input directory? |
+| Filesystem write | Can it write outside bounded temporary and output directories? |
+| Network | Is outbound access disabled by runtime policy? |
+| Processes | Can it spawn children, and how many? |
+| Privilege | Which user, group, namespace, or container runs it? |
+| Resources | CPU, memory, map, disk, files, descriptors, threads, wall time, output |
+| Failure | What happens on crash, timeout, truncation, or partial output? |
+| Version | Which tool and security policy version made the decision? |
+
+An application timeout without process termination is incomplete. Cancellation must stop child
+work, close streams, prevent publication, and clean bounded temporary artifacts.
+
+## 8. Resource, concurrency, and cost budget
+
+Build one budget ledger from edge to worker instead of isolated `10MB` checks:
+
+- wire bytes: request body, file, multipart overhead, chunks, remote response;
+- structure: files, archive entries, pages, frames, layers, tracks, nodes, relationships;
+- decoded work: pixels, samples, decompressed bytes, parser tokens or objects;
+- runtime: CPU, memory, temporary disk, descriptors, processes, threads, elapsed time;
+- outputs: thumbnails, previews, rewritten objects, extracted files, logs, metadata;
+- concurrency: per-user, per-tenant, per-worker, global in-flight jobs, queue depth;
+- retries and lifecycle: attempts, total age, stale partials, cleanup backlog;
+- durable cost: storage bytes, CDN bytes, scanner calls, OCR pages, transcode minutes.
+
+Define reservation and release points. A quota checked after expensive conversion or after object
+storage has already grown is accounting, not prevention.
+
+## 9. Layer responsibility handoff
+
+Keep every layer honest about what it can prove:
+
+| Layer | Owns | Does not prove |
+| --- | --- | --- |
+| Frontend | Early feedback, picker hints, progress | Security or final type |
+| Edge/proxy | Wire envelope, coarse rate and timeout | Parser semantics |
+| Upload API | Strict multipart syntax, auth, quarantine identity | Safe derived output |
+| Domain service | Allowed use, owner, state transition, publication policy | Native parser isolation |
+| Storage | Immutability, versioning, conditional writes, retention | Content safety |
+| Worker | Exact-version parsing, budgets, derived output, result evidence | Download authorization |
+| Database | Constraints and atomic state transitions | Object bytes by itself |
+| Serving layer | Current authorization, headers, origin, exact approved object, immutable asset manifest | Prior client checks or path-prefix ownership |
+
+Queue consumers must revalidate durable facts. A queued message carrying `approved = true` is not a
+substitute for loading current state and the immutable object identity.
+
+For downloads, resolve authorization before the exact object key, treat `Content-Disposition`
+filenames as presentation, remove CR/LF and path components, and generate a conservative ASCII
+`filename` fallback plus a correctly encoded UTF-8 `filename*`. Never reuse either header value as a
+storage locator. Serve built assets through an immutable URL-to-asset manifest; a SPA fallback should
+return one fixed `index.html` only after route classification, not probe alternate filesystem names.
+
+Escape control characters in rejected filenames before logging. Store a bounded display value and a
+stable policy code rather than allowing raw names to forge log lines.
+
+## 10. Denial and differential test matrix
+
+Use safe synthetic fixtures. Cover at least the paths present in the product:
+
+- extension, request MIME, signature, and structural parser disagree;
+- image dimensions, frames, layers, or metadata exceed cumulative budgets;
+- document page or object counts exceed policy before unbounded rendering;
+- archive traversal, absolute path, alternate separator, duplicate normalized name, symlink,
+  hardlink, device, FIFO, file-directory prefix conflict, order-dependent link, metadata restore,
+  sparse logical-size overflow, false size header, nested-budget exhaustion;
+- parser timeout, crash, partial output, unavailable scanner, and cancellation;
+- quarantine object replaced between upload and inspection or inspection and promotion;
+- promotion reads latest generation instead of the recorded immutable version;
+- hostname resolves to mixed public and forbidden addresses;
+- redirect changes scheme, port, host, address class, or exhausts the total budget;
+- DNS re-resolution or proxy routing chooses a different address than the validated one;
+- inbound credentials or cookies would be forwarded to a remote target;
+- remote response passes network policy but fails ordinary upload type or parser policy;
+- rejected or failed files remain unavailable through download, preview, CDN, email, admin, search,
+  and derived-object paths.
+- public path or prefix input cannot bypass opaque-id authorization and exact-version lookup;
+- `Content-Disposition` CR/LF and path fragments cannot alter headers or storage lookup;
+- static extension probing and raw-name log injection are rejected.
+
+Where two detectors or parsers exist, add differential fixtures so disagreement is an explicit
+failure or policy branch rather than an accidental first-match winner.
+
+## 11. Primary reference anchors
+
+Use current primary documentation when refreshing claims:
+
+- OWASP File Upload Cheat Sheet for defense-in-depth upload controls, generated names, storage
+  placement, type signals, size limits, scanning, CDR, and archive expansion limits.
+- OWASP SSRF Prevention Cheat Sheet for URL allowlisting limits, redirect control, scheme policy,
+  DNS pinning checks, and A/AAAA review.
+- OWASP API Security API4 for memory, CPU, file descriptor, process, upload, operation-count, page,
+  and third-party spending limits.
+- ImageMagick security policy documentation for coder, delegate, path, memory, map, disk, file,
+  thread, time, width, height, and list-length controls when ImageMagick is in the parser path.
+- Go `os.Root` and Java `SecureDirectoryStream` official documentation for root-relative runtime
+  capabilities and their platform or provider limits.
+- Python `tarfile` and `zipfile`, plus Go `archive/zip`, for versioned extraction filters, caller-owned
+  path validation, special entry metadata, sparse members, and non-local-name diagnostics.
+- RFC 6266 for treating response filenames as advisory presentation values and handling path
+  components, control characters, device names, `filename`, and `filename*` safely.
+
+External guidance is a floor. The repository's concrete parser, object-storage, network, tenant,
+and serving contracts decide the actual implementation and test evidence.