[Commercial Gap] Ship a fail-closed, bounded Clearfolio production adapter

[seonghobae]

Buyer problem

ScopeWeave currently treats an absent CLEARFOLIO_URL as an immediately successful in-memory conversion service. That behavior is useful for local demonstrations but is commercially misleading and can persist fake SUCCEEDED attachment state in a production deployment.

Closed PR #457 established the right direction but is not yet a complete production boundary. The replacement must preserve its explicit development adapter and sanitized downstream failures while closing the remaining transport, response, configuration, and artifact-trust gaps.

Required vertical slice

Configuration and feature readiness

• enable the in-memory adapter only under an explicit development/test mode;
• represent an unconfigured production adapter as an unavailable capability, never a successful conversion;
• validate configured URL and HMAC policy before serving the feature and expose feature readiness without taking unrelated ScopeWeave capabilities down;
• reject URL credentials, fragments, unexpected query configuration, non-HTTPS production transport, weak/blank shared secrets, and ambiguous trailing-path construction;
• keep loopback HTTP limited to explicit local development.

Bounded provider transport

• bound connection, headers, total request, redirects, and response-body bytes;
• disable redirects or validate every hop without forwarding tenant-claim credentials cross-origin;
• validate response media type before parsing and stream-enforce the body limit rather than buffering first;
• never expose provider body text, network addresses, tenant claims, or secrets through browser errors, logs, or metrics;
• validate job IDs and exact conversion states with explicit length and enum limits.

Artifact URL trust

• parse returned links with URL;
• reject credentials, fragments, unsupported schemes, HTTPS downgrade, malformed ports, and unapproved cross-origin links;
• allow same-origin Clearfolio viewer links by default and require an explicit reviewed artifact-origin allowlist for CDN/object-storage hosts;
• never move an artifactToken from an untrusted origin into a trusted viewer URL;
• bind every artifact operation to the authenticated organization, user, and persisted provider job.

Resource and lifecycle contracts

• validate document name, MIME, and byte length before constructing Blob/FormData;
• retain the 100 MiB ceiling only if API upload and storage paths enforce the same or a stricter limit;
• persist provider state transitions idempotently and preserve the last trusted status on timeout, malformed responses, and partial downstream failures;
• document retries, cancellation, stale-status handling, incident diagnosis, and rollback.

Verification

• production-unconfigured and explicit-development tests;
• HTTPS/loopback URL, credentials, query/fragment, redirect, timeout, streaming-size, media-type, malformed JSON, enum, and secret tests;
• same-origin and approved-cross-origin artifact tests, including token-confusion and downgrade cases;
• tenant-claim HMAC contract tests against Clearfolio's real verifier;
• API tests proving fake routes/artifacts cannot exist outside development mode;
• production statement/branch/function/line coverage and public docstrings at 100%;
• CHANGELOG, deployment/readiness, security, incident/rollback, and APA 7th doctoring records.

Ecosystem contract

Treat Clearfolio as a replaceable MSA adapter. Keep ScopeWeave usable without it, but report the document-viewer capability as unavailable and give the operator a concrete configuration action. Coordinate any contract change with the owned Clearfolio repository rather than inventing a second wire protocol.

[seonghobae]

Bounded implementation is now split into two ordered slices rather than one oversized provider rewrite.

• fix(clearfolio): fail closed on production configuration #493 (c8da068538e5f5032136f0a39a68ab387edc3646) owns explicit-development mock semantics, production-unconfigured fail-closed behavior, canonical root provider origin + HMAC policy, loopback-only development HTTP, sanitized provider failures, exact conversion states, and cross-origin artifactToken non-transplant. Its six repository-native checks are terminal-success and it remains open solely for current-head independent review/protected integration.
• fix(clearfolio): bound provider transport and JSON responses #498 (a733a2f3c78a43b1fed178524067b25cfde76ff7) is stacked on fix(clearfolio): fail closed on production configuration #493 and now owns non-redirecting hosted provider requests, a hard 15 s request budget with caller cancellation composition, application/json media validation, independent 256 KiB streamed-response enforcement, document metadata/10 MiB byte validation before Blob/FormData allocation, and bounded provider job IDs before persistence/URL construction. Its Server Tests, Dependency Review, and OSV checks are exact-head success; it has been marked Ready so remaining applicable central security/SAST/review evidence can run. No missing gate is being treated as passing.

#489 intentionally remains open. The still-unimplemented reviewed boundary is the artifact URL policy itself: reject returned URL credentials/fragments/malformed ports and default-deny cross-origin artifact hosts unless they match an explicit reviewed allowlist. Retry/idempotency/cancellation recovery and the complete persisted provider lifecycle also remain later work; neither current PR claims them.