v4.3 Development Plan — Governed Provider Execution Foundation

Release Theme

MultiModel Dev OS v4.3 introduces an explicitly enabled, security-bounded provider execution foundation around the v4.2 gateway contracts while preserving localhost defaults, deterministic routing, credential redaction, maintainer-controlled configuration, and a zero-runtime-dependency posture.

Release Statement: v4.3 establishes governed, opt-in execution capabilities for generic OpenAI-compatible model provider adapters without compromising local-first security boundaries or adding third-party dependencies.

---

Why This Comes Next

In v4.2.0, MultiModel Dev OS shipped the core Gateway control plane, including:

• Uniform request/response/error schemas and provider contract abstractions (src/gateway/protocol/)
• Deterministic model router and candidate scoring engine (src/gateway/router/)
• Resilience and circuit-breaker simulation (src/gateway/resilience/)
• Bounded local observability and usage accounting (src/gateway/observability/)
• Client configuration plan generation and previews (src/gateway/client/)
• Localhost mock runtime (src/gateway/runtime/)

While v4.2 established complete control, routing, and simulation interfaces, actual request execution was restricted to mock local runtimes. The logical and architectural prerequisite for downstream features (such as runtime guardrail enforcement, safe client config application, and operational state persistence) is a governed, standardized provider execution engine.

---

Current Baseline

• Package Version: 4.3.0-dev.0 (Development Lane open; v4.2.0 remains public/latest on npm and GitHub)
• Test Suite: Full unit and integration test suite passing at latest verification
• Strict Verifier: All release audit assertions passing cleanly
• Dependencies: 0 runtime dependencies (Node.js standard library crypto, fs, path, readline, https, etc.)
• Security Audit: 0 production vulnerabilities (npm audit --omit=dev)
• Package Tarball: Valid packed package verified clean

---

User Outcomes

1. Governed External Execution: Developers will be able to explicitly opt into proxying model execution requests to external generic OpenAI-compatible APIs using maintainer-controlled environment variables.
2. Local-First Safety Boundaries: Default behavior remains local with loopback bindings (127.0.0.1). External execution is planned to require explicit configuration enablement.
3. Strict Credential Redaction: Provider keys are planned to be read exclusively at request execution time from environment variables, never written to disk, never logged, and stripped from diagnostic/observability traces.
4. Normalized Streaming & Errors: Standardized SSE streaming and error responses across external provider endpoints with zero third-party SDK dependencies.

---

Architecture

[ Developer CLI / IDE Adapter ]
               │
               ▼
   [ Gateway Protocol & Contracts ]
               │
               ▼
   [ Deterministic Model Router ]
               │
               ▼
[ Governed Provider Execution Engine ] (v4.3 Scope)
   ├── Environment Credential Resolver (Request-Time Only)
   ├── Generic OpenAI-Compatible Transport (Node.js HTTPS)
   ├── Stream & Error Normalizer
   └── Strict Redaction & SSRF Guard
               │
               ▼
    [ External Model Provider ] (Explicit Opt-In Only)

---

Security Model

1. Opt-In Execution: Outbound execution is disabled by default. The local gateway refuses external provider requests unless explicitly enabled via local configuration.
2. Request-Time Credential Resolution: Credentials are read from named environment variables (e.g., OPENAI_API_KEY) at execution time and never cached or persisted.
3. SSRF & Address Boundaries: Outbound HTTPS client blocks private IP ranges (RFC 1918, loopback, link-local) for external provider calls to prevent Server-Side Request Forgery.
4. Header Allowlisting: Only specified standard headers (Authorization, Content-Type, User-Agent) are transmitted to external endpoints.
5. Bounded Observability: Observability collectors strip all auth tokens, prompt text, and completion text from metrics and trace logs.

---

Compatibility

• Backward Compatibility Target: Existing CLI commands (multimodel-dev-os scan, memory, status, workflow, handoff, catalog, plugin) are backward compatibility release targets. Migration impact is expected to be minimal.
• Contract Stability: Extends existing v4.2 gateway schemas and interfaces without altering schema identifiers.
• Node.js Compatibility: Targets Node.js LTS (ES modules, native HTTPS/fetch primitives).

---

Proposed Sprints

Sprint 0 — Development Lane Bootstrap and Scope Lock (Completed)

• Locked v4.3 release theme and architecture.
• Opened 4.3.0-dev.0 development lane.
• Updated version metadata, prepublish guard, and package verifiers.
• Aligned public roadmap and release-state docs.

Sprint A — Execution Contracts and Threat Model (Completed)

• Defined complete execution contract set (execution-request.js, execution-result.js, credential-ref.js, provider-endpoint.js, execution-policy.js, provider-execution-capability.js, execution-error.js).
• Implemented 7 formal JSON Schemas in .ai/schema/.
• Enforced factory secure defaults and un-overridable redacted: true in createExecutionResult and createExecutionError.
• Enforced strict environment variable regex (^[A-Z_][A-Z0-9_]{0,127}$), prototype property rejection, and key allowlisting.
• Updated Governed Provider Execution Threat Model in docs/security-threat-model.md.
• Added 7 JSON test fixtures and comprehensive network-free unit test suites.
• Hardened gateway contracts verifier with schema, contract, fixture, and secure default assertions.

Sprint B — Generic OpenAI-Compatible Adapter Core (Completed)

• Implemented request payload normalizer (request.js) with allowlisted fields, capability assertions, deep-reference isolation, and undefined-property removal.
• Implemented response payload normalizer (response.js) with multi-choice validation, tool call capability checks, allowlisted roles/finish reasons, and deterministic fallback timestamps (zero Date.now() / new Date()).
• Implemented error payload normalizer (error.js) using EXECUTION_CONTRACT_VERSION, safe circular object cleaning, throwing getter guards, path redaction, and non-throwing error handling.
• Implemented stateful, transport-independent incremental SSE parser (sse.js) with factory option validation, UTF-8 streaming decoder (TextDecoder), byte-bounded accounting (Buffer.byteLength), multi-line data: joining (\n), terminal [DONE] state, and multi-choice delta allowlisting.
• Added JSON/text test fixtures under tests/fixtures/gateway/adapters/openai-compatible/.
• Added unit test suites covering request, response, error, and SSE stream normalization.
• Extended release verifier with OpenAI adapter validation rules (ambient time ban, terminal DONE enforcement, event accumulation bounds, and documentation check).

Sprint C — Credential Resolution and Redaction (Completed)

• Implemented explicit, provider-bound environment credential resolver (resolveEnvironmentCredential).
• Created Opaque Credential Container (ResolvedCredential) using private class fields (#secret) with controlled withSecret() callback access and destroy().
• Implemented secret-aware redaction utility (redactSensitiveValue) sanitizing objects, circular references, throwing getters, error stacks, and messages.
• Hardened validateProviderAdapter with strict STRICT_ENV_VAR_REGEX and prototype property checks on credential_env.
• Added formal JSON schema .ai/schema/gateway-credential-resolution-result.schema.json.
• Added comprehensive unit test suite tests/unit/gateway-credential-resolution.test.js.
• Extended gateway verifier with Sprint C credential checks (process.env enumeration ban, opaque container redaction, and secret-aware redaction assertions).

Sprint D — Explicit Opt-In Execution Path (Completed)

• Implemented pure deterministic preflight execution gate (evaluateExecutionGate) enforcing default-disabled state, provider allowlisting, capability assertions, HTTPS requirements, no-redirects, SSRF flags, and bounded budgets.
• Defined injected transport contract (validateTransport) prohibiting global transport state or network primitives.
• Implemented explicit single-attempt governed executor (executeGovernedRequest) with ephemeral credential lifecycle cleanup in finally blocks.
• Added comprehensive unit test suite (tests/unit/gateway-execution.test.js) and Sprint C closure regression tests.
• Extended gateway verifier (scripts/verify/gateway-contracts.js) with Sprint D checks.
• Created docs/governed-execution.md architecture guide.

Sprint E1 — Governed Non-Stream Runtime Integration (Completed)

• Integrated governed executor into local HTTP gateway server (src/gateway/runtime/).
• Hardened dispatcher trust boundaries with frozen compiled adapter facades, safe runtime config validation, encapsulated route execution, sanitized credential error messages (omitting environment variable names), and strict cancellation / timeout accounting.

Sprint E2 — Governed External Streaming Integration (Completed)

• Implemented governed external SSE streaming executor (executeGovernedStream) in src/gateway/execution/stream-executor.js.
• Extended transport interface (transport.stream()) supporting status, headers, async iterable body, and credential destruction.
• Integrated governed external streaming into /v1/chat/completions route in src/gateway/runtime/app.js.
• Enforced preflight validation, mid-stream safe SSE error payloads, backpressure handling, client disconnect / abort handling, single credential destruction, and zero network primitives in stream executor.
• Added integration test suite tests/integration/gateway-governed-runtime-stream.test.js and documentation in docs/gateway-streaming.md.

Sprint F0 — Secure Outbound Transport Threat Model & Architecture (Completed)

• Conducted E2 acceptance audit and confirmed streaming executor & runtime integration stability.
• Created docs/secure-outbound-transport-threat-model.md with complete STRIDE analysis and honest status mapping.
• Designed zero-runtime-dependency native transport architecture (docs/secure-outbound-transport-design.md) selecting Option A (Native Pinned-Address HTTPS Transport).
• Defined local test strategy (docs/secure-outbound-transport-test-plan.md) utilizing mock DNS resolvers and loopback HTTPS servers.

Sprint F1 — Pure Destination & Address Policy (Planned)

• Modules / Files: src/gateway/transport/destination-policy.js, src/gateway/transport/ipv4-policy.js, src/gateway/transport/ipv6-policy.js, src/gateway/transport/address-policy.js, src/gateway/transport/resolver-contract.js, src/gateway/transport/index.js.
• Exported Public APIs: validateDestinationUrl(url), classifyIPAddress(ip), validateResolvedAddresses(addresses), validateResolver(resolver).
• Internal APIs: parseIPv4Canonical(str), parseIPv6Canonical(str), isIPv4InCidr(ip, cidr), isIPv6InCidr(ip, cidr).
• Schemas / Contracts: Injected pure resolver contract interface (resolve4(host), resolve6(host)).
• Unit / Integration Tests: tests/unit/transport-destination-policy.test.js, tests/unit/transport-address-classification.test.js.
• Verifier Assertions: Assert pure destination module exports, 0 network imports in transport F1 files, strict zero-dependency posture.
• Documentation: docs/secure-outbound-transport-design.md.
• Explicit Non-Goals: No network socket creation, no HTTP calls, no system DNS lookups (dns.lookup).
• Acceptance Criteria: 100% pass rate on table-driven URL canonicalization and IP classification tests.
• Rollback Boundary: Pure transport module isolated under src/gateway/transport/.

Sprint F2 — Secure Non-Stream Native Transport (Planned)

• Modules / Files: src/gateway/transport/native-transport.js, src/gateway/transport/tls-policy.js, src/gateway/transport/header-boundary.js.
• Exported Public APIs: createNativeTransport(options), executeNativeRequest(params).
• Internal APIs: createPinnedLookup(pinnedIp), buildTransportHeaders(credential, allowlist).
• Schemas / Contracts: Implements validateTransport() interface (execute(params)).
• Unit / Integration Tests: tests/unit/transport-native-http.test.js, tests/unit/transport-tls-verification.test.js, tests/unit/transport-header-boundary.test.js.
• Verifier Assertions: Assert native transport adheres to pinned socket lookup, TLS verification (rejectUnauthorized: true), CR/LF header rejection, 6-phase timeout lifecycles.
• Documentation: docs/secure-outbound-transport-design.md.
• Explicit Non-Goals: No streaming support, no auto-redirects, no ambient proxy usage (HTTP_PROXY).
• Acceptance Criteria: Successful non-stream HTTP requests to local HTTPS test server; fails on TLS mismatch or 3xx redirect.
• Rollback Boundary: Injected transport instance passed optionally to executor.

Sprint F3 — Secure Streaming Native Transport (Planned)

• Modules / Files: src/gateway/transport/native-stream-transport.js, src/gateway/transport/socket-wrapper.js.
• Exported Public APIs: executeNativeStream(params).
• Internal APIs: createAsyncIterableSocket(socket, options).
• Schemas / Contracts: Implements validateTransport() streaming interface (stream(params)).
• Unit / Integration Tests: tests/unit/transport-sse-streaming.test.js, tests/integration/gateway-native-streaming.test.js.
• Verifier Assertions: Assert stream response validation (text/event-stream), AsyncIterable wrapper backpressure handling, prompt socket destruction on abort.
• Documentation: docs/gateway-streaming.md.
• Explicit Non-Goals: No multi-provider retries, no transparent decompression (accept-encoding: identity).
• Acceptance Criteria: Governed streaming completes cleanly or destroys socket on abort/timeout.
• Rollback Boundary: Isolated stream() method on native transport.

Sprint F4 — Security Closure & Verification (Planned)

• Modules / Files: tests/integration/transport-adversarial.test.js, scripts/verify/gateway-transport.js.
• Exported Public APIs: Verifier suite additions.
• Internal APIs: Adversarial test fixtures.
• Schemas / Contracts: Verification assertions.
• Unit / Integration Tests: tests/integration/transport-adversarial.test.js.
• Verifier Assertions: Adversarial SSRF tests, DNS rebinding simulation tests, HTTP 3xx redirect blocking, secret redaction audit across error/trace logs.
• Documentation: docs/secure-outbound-transport-threat-model.md.
• Explicit Non-Goals: No production transport schema breaking changes.
• Acceptance Criteria: 100% verifier pass across all release checks.
• Rollback Boundary: Test and verifier scripts only.

Sprint G — Compatibility and Documentation (Planned)

• Document provider configuration guidelines and security best practices.
• Update gateway architecture and provider strategy documentation.

Sprint H — Release Hardening (Planned)

• Complete full release audit and verification.
• Verify zero runtime dependency posture.
• Finalize CHANGELOG and readiness documentation.

---

Acceptance Criteria

1. Governed Adapter: Executable OpenAI-compatible adapter passes all schema validation and request/response normalization tests.
2. Security: Credentials resolved purely from environment variables; 0 secrets written to disk or logged in observability traces.
3. SSRF Guard: Private IP addresses and non-HTTPS schemes rejected for external execution.
4. Zero Dependencies: 0 new runtime packages added to package.json.
5. Test Coverage: 100% pass rate across unit test suite and npm run verify.

---

Non-Goals

• No Third-Party SDKs: Official provider SDKs (e.g. openai, anthropic) will not be added as dependencies.
• No Uncontrolled Live Fallback: Automatic multi-provider live retry/failover is deferred.
• No Cloud Telemetry: Local metrics remain strictly local.
• No Secret Persistence: Storing secrets in local files or gateway state is strictly prohibited.

---

Migration Impact

None. v4.3 is a minor release that is fully backward-compatible with v4.2 configuration and CLI commands.

---

Risks and Mitigations

Risk	Mitigation
Secret leakage in error logs	Mandatory redaction pass on all error objects before serializing
SSRF via custom provider URL	Rejection of private IP ranges, non-HTTPS protocols, and redirects
Dependency bloat	Native Node.js https module used exclusively

---

Testing Strategy

• All tests use local HTTP mock servers or in-memory fixtures.
• Unit tests must never make real outbound network requests or require real API keys.
• Coverage enforced via Vitest integration tests.

---

Documentation Strategy

• Keep clear demarcation between released v4.2.0 capabilities and planned v4.3 development features.
• Provide step-by-step guides for enabling generic OpenAI-compatible execution.

---

Release Boundaries

• No npm Publish: Package will not be published until release hardening is complete.
• No Git Tag Modification: Tag v4.2.0 remains unchanged.
• Immutable v4.2: Release notes and artifacts for v4.2.0 are strictly read-only.