security: require exact TLS trust and identity scalar values

[seonghobae]

Buyer-visible TLS configuration-integrity gap

Protected main 7faf7a3b8a47980113982914000e724ab6a6cda5 enforces the exact outer TLSConfiguration type, but retained trust, identity, and direct private-key-password scalar inputs admitted polymorphic built-in subclasses before trusted state was frozen.

Draft PR #214 is the canonical implementation lane, exact unchanged head 6ecc1b2e2caa1af5293a28a5d07a5eddda6f0327, based directly on that protected head. No predecessor, synthetic-merge, status-only, wrapper-only, or other-PR evidence transfers.

This is trusted startup/configuration integrity, not a claim that EgressWeave sandboxes arbitrary code already running in the host process. Exact strings/bytes/bytearrays, standard pathlib.Path, private trust, mTLS, and the intentionally explicit deferred password callback remain supported.

RCA and selected remedy

First boundary: scalar normalization before TLSConfiguration retains path, CA, and direct secret values.

Observed root cause: broad isinstance(..., str/bytes/bytearray) acceptance allowed direct subclasses or a path-like object returning a text subclass to run subclass-controlled normalization, length, or conversion behavior before rejection or retention.

Selected remedy:

• observe os.fspath() exactly once and require exact built-in str;
• require ca_data to be exact built-in str or bytes before emptiness checks/retention;
• require direct private-key passwords to be exact built-in str, bytes, or bytearray, copying an exact bytearray to immutable bytes;
• preserve the zero-argument callback as a separately explicit trusted deferred-secret contract.

Rejected alternatives: coercing polymorphic values, catching failures while retaining broad inputs, resolving filesystem paths during construction, or removing the explicit callback contract.

Immutable TDD evidence

Path, trust, and CA scalars

• RED head d523c640703cd322f45fb52ce58652b6d2fccfec;
• CI 31653524791, Python 3.14 job 94302784187: 10 failed, 1026 passed; package acceptance passed; hostile text/bytes methods executed;
• narrow source-fix head 1442fdb89b8b931992bc92d84f6ae9dcfba43801.

Direct private-key-password scalars

• RED head 00f75595571d8be2445da146d78dd17cffd301f6;
• CI 31655119628, Python 3.14 job 94307789645: 3 failed, 1039 passed; package acceptance passed; hostile direct password values were retained/converted;
• narrow source-fix head d3be1c0bb7ae11d2c8095b7730e5164a4c414920;
• GREEN CI 31655226108, Python 3.14 job 94308118509: 1042 passed, exact owned-production coverage 1758/1758 statements and 588/588 branches.

Exact-current-head evidence

On unchanged 6ecc1b2e2caa1af5293a28a5d07a5eddda6f0327 after directly affected TLS documentation alignment:

• CI 31655408048: success across package acceptance and Python 3.10–3.14;
• Python 3.14 job 94308654550: 1042 passed; exact coverage 1758/1758 statements and 588/588 branches; Ruff/product guard/compileall passed;
• SAST 31655408059: success;
• Strix required run 31655407058, job/check 94308699374: substantive exact-head quick scan completed and uploaded artifact 9164364412, SHA-256 ef1171b8f94cd6c71f8fa44f3979c84487134218bf18dff8d34b826b3e2822c3; scan_completed=true and the report found no vulnerability in the scoped TLS implementation;
• Security Scan 31655408082: OSV/Trivy/Scorecard succeeded, but dependency-review job 94308654474 skipped the actual immutable-pinned Dependency review action. Wrapper green is non-passing supply-chain evidence;
• CodeRabbit exact-head review PRR_kwDOTVyu-88AAAABJWhHXA reviewed range 7faf7a3...6ecc1b2 and identified one valid current finding: add the root [Unreleased] CHANGELOG entry;
• review thread PRRT_kwDOTVyu-86Yx2nP remains unresolved because the requested entry is not yet present;
• live rules currently require review-thread resolution and zero approving reviews. No approval is invented or required by count.

Exact-path single-writer defer

The CodeRabbit finding is valid, but root CHANGELOG.md is frozen for the current writer invocation. Ready PR #212, unchanged exact head 417ed4b066c50584b41942c61bc68bd82348d700, actively changes the same path together with its isolated-build reproducibility fix. Racing or independently rewriting the same release-history path would violate the single-writer lease and risk losing unrelated [Unreleased] history.

After #212 reaches protected integration, closes, or moves off CHANGELOG.md, reconstruct the TLS release-history entry on the then-current protected base. That mutation must preserve every unrelated entry and regenerate all exact-head CI/security/review evidence; none of the current checks or review conclusions transfer to the changed head.

Acceptance criteria

• Establish immutable test-first RED evidence for path/trust/CA scalar polymorphism.
• Require exact path text after one os.fspath() observation and exact built-in CA text/bytes.
• Establish immutable test-first RED evidence for direct password scalar polymorphism.
• Require exact direct password text/bytes/bytearray, copy exact bytearrays, and preserve explicit deferred callbacks.
• Preserve private trust, mTLS, TLS 1.3 default, explicit TLS 1.2 compatibility, hostname/certificate verification, exact outer configuration type, and public builders.
• Add no path resolution/filesystem access, runtime network, credential logging, persistence, workflow, release, or publication authority.
• Align directly affected TLS research/operator documentation.
• Maintain exact 100% owned-production statement/branch coverage, Python 3.10–3.14, package acceptance, Ruff, product guard, compileall, and SAST on the exact current head.
• Obtain substantive exact-current-head Strix semantic evidence.
• Obtain current semantic/source review and classify its sole finding as valid.
• Wait for the active CHANGELOG.md writer lane to stabilize, then add the TLS [Unreleased] entry without corrupting unrelated history.
• Regenerate exact-head CI/security/review evidence and resolve the CodeRabbit thread only after the entry is present.
• Integrate the separately governed fail-closed Dependency Review repair (ContextualWisdomLab/.github#897 or verified successor) and obtain a fresh Security Scan whose actual pinned action executes and succeeds.
• Revalidate exact head/live base/ruleset/reviews/findings/threads before protected merge and merge only the unchanged accepted tree.
• Verify behavior from protected main before closure.

Non-goals

• No arbitrary Python sandbox guarantee.
• No path canonicalization, expansion, symlink resolution, or filesystem access during immutable configuration construction.
• No removal of the explicit client-key password callback contract.
• No local substitute for organization-owned Dependency Review governance.