Contract Parity Architecture for a C Desktop and Cross-Language Services

Full report

On this page

Executive Summary

Design recommendation: The uploaded brief removes the “unspecified topic” ambiguity and makes the research target specific: a contract-first, security-conscious protocol architecture for a fixed stack consisting of a Windows C#/.NET desktop client, browser TypeScript clients, Python services, server-side TypeScript services, and selectively used Rust services, with special emphasis on identity, protected remote commands, offline-capable local use, and honest consistency claims. This report therefore treats the uploaded architecture brief as the controlling scope document.

Design recommendation: The best default research angle is a decision-ready normative protocol profile and conformance architecture rather than a pure market scan or a purely academic literature review. That angle produces the most leverage because it lets the team make one set of contract, security, and rollout decisions that can be implemented consistently across C#, Python, TypeScript, and Rust while preserving the fixed desktop architecture in the brief. The strongest contract choice is a deliberate mix: OpenAPI plus JSON Schema as the normative source of truth for HTTP resources and persisted JSON envelopes, with AsyncAPI as a companion specification for message-driven surfaces, rather than a second independent source of truth. OpenAPI is purpose-built for HTTP APIs, JSON Schema 2020-12 gives the broadest JSON validation vocabulary, and AsyncAPI is explicitly designed for message-driven and protocol-agnostic API descriptions. Smithy is credible but weaker for this exact stack’s browser-and-JSON-centric interoperability needs, while Protobuf-first maximizes binary efficiency but weakens inspectability, canonical JSON interoperability, and standards alignment for browser-facing security-sensitive flows.

Protocol requirement: Identity must be separated into at least five distinct planes: human authentication, browser session, desktop/device enrollment, service workload identity, and per-request delegated authority. For interactive login, the secure baseline is authorization code + PKCE, with S256, not implicit grant. Device authorization remains a fallback only when a device truly lacks a practical browser or is materially input-constrained. Service-to-service calls should prefer workload identity and mutual TLS, while sender-constrained access tokens such as DPoP are useful for public clients or where bearer-token replay is a real concern. Token exchange is appropriate only for explicit delegation chains and should not be used to blur actor identity.

Protocol requirement: The strongest honest reliability claim for protected remote desktop commands is not exactly-once desktop effects. HTTP is stateless, HTTP method idempotence is limited to the semantics of the requested method, and retries are only automatically safe when the method is idempotent or the client has independent knowledge that replay is safe. Once a remote command crosses into a desktop-side effect boundary outside a shared transactional system, the architecture can honestly promise durable acceptance, deduplicated processing, auditable state transitions, and at-least-once delivery attempts, but only operation-specific idempotent outcomes or explicit “outcome unknown” when crash windows remain unresolved. The practical control set is: idempotency keys, request hashing, preconditions, outbox/inbox records, bounded retries, content digests, and—where non-repudiation or proxy-resistant signing matters—HTTP Message Signatures. Problem Details should be the error envelope baseline.

Design recommendation: The most important recent developments in the last five years materially strengthen this architecture choice: W3C Trace Context reached Recommendation status in late 2021; JSON Schema Draft 2020-12 was published in 2022; RFC 9457 and RFC 9449 were published in 2023; RFC 9421 and RFC 9530 in 2024; RFC 9700 and OpenAPI 3.2.0 in 2025. Together, those standards materially improved the available guidance for tracing, JSON-aligned schemas, structured API errors, sender-constrained tokens, message signing, digest integrity, OAuth hardening, and HTTP API documentation.

Open question: The brief explicitly withholds live system access, internal schemas, deployment evidence, and product telemetry. That means the report can define a strong external architecture baseline, but it cannot finalize several product-specific decisions: the actual desktop attestation mechanism, the command classes that require local approval, retention periods, exact queue topology, which operations are safely idempotent, or whether the desktop transport should be primarily pull, push, or hybrid. Those remain validation items for an authorized internal phase.

Topic Framing and Research Angles

Design recommendation: Because the brief is now specific, the right way to handle the originally “unspecified” assumptions is to treat scope, audience, deadline, and deliverable format as choice variables within a fixed topic rather than as unknowns about the topic itself. The fixed topic is the cross-language protocol and security architecture described in the uploaded brief.

Design recommendation: The default audience should be a joint architecture review group consisting of a principal architect, API/platform engineering, identity/security, desktop engineering, and verification/QA. The default deadline should be an eight-week decision cycle, because the brief spans trust boundaries, OAuth, transport, conformance, desktop-side execution semantics, and cross-language parity. The default deliverable format should be Markdown plus machine-readable companion artifacts because that aligns with the brief’s requested package and supports both human review and CI automation.

Standards and Evidence Base

Recent standards and literature that changed the design space

Design recommendation: This problem is unusually standards-heavy. The most load-bearing evidence is not vendor whitepapers but IETF RFCs, W3C recommendations, official language/runtime documentation, NIST identity guidance, and a small amount of supplementary research literature. That weighting is appropriate because the brief asks for deterministic interoperability across languages and for honest claims about security and reliability.

Design recommendation: The last five years produced precisely the standards this stack needs. OpenAPI 3.1 aligned more directly with JSON Schema 2020-12, and OpenAPI 3.2.0 added stronger treatment for streaming content and server-sent events. JSON Schema Draft 2020-12 stabilized the modern JSON validation vocabulary. AsyncAPI 3.1.0 matured message-driven interface description. RFC 9457 standardized a modern problem-details baseline, RFC 9449 standardized DPoP, RFC 9421 standardized HTTP Message Signatures, RFC 9530 standardized modern digest fields, and RFC 9700 consolidated OAuth 2.0 security best practice. Those developments make a 2026 architecture meaningfully better than a 2020 architecture for the same product problem.

Prioritized primary sources and seminal references

Design recommendation: The table below is a condensed source ledger. All web sources were accessed on July 12, 2026. The first group are the load-bearing primary sources; the second group are implementation and risk sources; the final group are supplementary seminal papers that explain why the OAuth and reliability recommendations are conservative.

Contract technology comparison and recommended default

Design recommendation: The comparative question is not “which single technology is best in the abstract,” but “which choice best satisfies this exact stack’s need for browser-compatible HTTP APIs, persisted envelopes, generated models across four languages, strong reviewability, and security-oriented contract clarity.” On that basis, a deliberate OpenAPI/JSON-Schema-first architecture with AsyncAPI as a derived companion wins.

Design recommendation: The score above is a synthesis of the documented traits of each technology, not a claim that any spec publishes this ranking. OpenAPI is explicitly a language-agnostic interface description for HTTP APIs; OpenAPI 3.1 aligns with JSON Schema 2020-12; AsyncAPI is explicitly for message-driven APIs; Smithy is explicitly protocol-agnostic and designed for code generation; Protobuf is explicitly language-neutral and extensible but also explicitly “not a formal standard of any organization,” which matters for governance-heavy external protocol decisions.

Protocol requirement: For this stack, there should be one normative contract source of truth for request/response/resource shapes and persisted JSON envelopes. AsyncAPI should reference or be generated from the same underlying schemas rather than redefining payloads independently. Generated models should remain thin, while domain behavior, invariants, and side-effect orchestration stay in handwritten adapters. That keeps protocol review deterministic and language idioms local.

Recommended Normative Architecture

Trust boundaries and actors

Protocol requirement: The architecture should model at least these trust boundaries: browser origin boundary, website/BFF boundary, service workload boundary, queue or broker boundary, desktop transport boundary, desktop installation boundary, local policy boundary, and local executor/side-effect boundary. The browser can help carry session state and user intent, but it must not be the final source of truth for tenant identity, device authority, local capability approval, or actor delegation. Federation guidance from NIST and the API authorization risks highlighted by OWASP both support keeping object and function authorization decisions on trusted service or desktop components rather than on browser claims.

Design recommendation: The core trust-boundary design is shown below. The important design property is that authorization remains multi-party: the hosted side authorizes the tenant/account/action, and the desktop side independently authorizes the local capability and execution safety. That dual-consent structure directly answers the brief’s requirement that remote authority and local approval both succeed.

flowchart LR
    subgraph WebTier["Browser and Web Tier"]
        Human["Human user"]
        Browser["Browser TypeScript client"]
        BFF["Website or BFF"]
        IdP["Identity provider"]
        Human --> Browser
        Browser --> BFF
        BFF --> IdP
    end

    subgraph ServiceTier["Hosted Services"]
        CommandAPI["Command API"]
        Policy["Hosted authorization policy"]
        Audit["Audit and state store"]
        Queue["Queue or delivery broker"]
        Token["Token and delegation service"]
        BFF --> CommandAPI
        CommandAPI --> Policy
        CommandAPI --> Audit
        CommandAPI --> Queue
        CommandAPI --> Token
    end

    subgraph DesktopTier["Desktop and Local Execution"]
        Desktop["C# desktop transport agent"]
        Inbox["Durable inbox"]
        LocalPolicy["Local policy engine"]
        Executor["Local executor"]
        Outbox["Result outbox"]
        Queue --> Desktop
        Desktop --> Inbox
        Inbox --> LocalPolicy
        LocalPolicy --> Executor
        Executor --> Outbox
        Outbox --> CommandAPI
    end

    CommandAPI --> BFF

Identity, enrollment, and delegated authority

Protocol requirement: Interactive browser sign-in should use authorization code flow with PKCE, and the authorization server must support PKCE with secure challenge methods such as S256. The implicit grant should not be used except under exceptional conditions with compensating controls because it is vulnerable to token leakage and replay. Since the browser is exposed to CSRF and cross-origin constraints, the preferred browser pattern is a server-managed session on the website/BFF, with same-site cookie controls and explicit CSRF defenses, not a design that pushes long-lived bearer tokens into browser JavaScript by default.

Protocol requirement: Desktop enrollment should default to system-browser authorization code + PKCE, not device authorization grant, because RFC 8628 is specifically designed for devices that lack a browser or are materially input-constrained. The desktop should use a per-installation keypair and bind redeemed authorization codes to that client instance. If sender-constrained tokens are needed for the desktop as a public client, DPoP is the lighter and more realistic option than browser-facing mutual TLS; if the desktop can operationally manage a client certificate, certificate-bound access tokens remain stronger against bearer replay.

Protocol requirement: Service workloads should not embed long-lived secrets in application configuration. They should authenticate with platform workload identity or short-lived service credentials and obtain downstream tokens or secret material just in time. OWASP’s guidance strongly favors centralized, standardized secrets management, least privilege, automation, and dynamic secrets over hardcoded or casually distributed credentials.

Protocol requirement: Request authority should distinguish subject, actor, and device. Token exchange is useful when a service acts on behalf of a user or another service and needs delegation rather than impersonation semantics. The command authority token should therefore carry at least: iss, aud, sub, tenant identifier, device identifier, scopes or capability grants, expiry, and a delegation or actor chain when relevant. The desktop should reject requests that collapse actor and subject semantics when policy requires explicit delegation visibility.

Contract profile, envelope rules, and canonical bytes

Protocol requirement: The normative wire format should be UTF-8 JSON for HTTP resources, persisted command envelopes, and browser-compatible real-time payloads. OpenAPI should own resource descriptions, JSON Schema should own reusable payload shapes, and AsyncAPI should describe event channels and send/receive operations while reusing those same schemas. This gives the stack one inspectable contract surface across C#, Python, TypeScript, and Rust.

Protocol requirement: Contract rules should explicitly define field names, optionality, nullability, unknown-property handling, timestamps, and number usage. Timestamps should use RFC 3339 and should be normalized to UTC in persisted records. Type names and field names should be stable ASCII identifiers even if end-user strings remain full Unicode. Optional fields should mean “omitted,” while null should only be used when its semantic meaning is distinct and documented.

Protocol requirement: Security-sensitive inputs must reject duplicate keys and non-standard numeric values such as NaN and Infinity. Python’s standard json module will accept or emit some JSON-adjacent values that are outside the strict JSON specification and will accept repeated names by default using the last value. That makes “whatever the runtime parser does” an unacceptable contract rule. Therefore, each language implementation should use strict parsing mode and common golden vectors to prove consistent behavior.

Design recommendation: Money, quotas, and values whose decimal semantics must survive every language boundary should not use unconstrained JSON number. Python defaults JSON floats to binary floating-point unless special parsing is configured, and browser JavaScript numbers remain IEEE-754 doubles. The cleanest cross-language rule is: use bounded integers for counts and durations; use decimal strings or scaled integers for precise business quantities.

Protocol requirement: When signatures, deduplication, or stable request hashing depend on stable bytes, JSON must be canonically serialized before hashing or signing. RFC 8785 provides a JSON Canonicalization Scheme; RFC 9530 provides standardized digest fields for HTTP message content and representations; RFC 9421 provides standardized HTTP message signing over selected message components. Those standards are a better baseline than ad hoc “sort keys and hope” logic.

A practical normalized command envelope should look conceptually like this:

{
  "envelopeVersion": "2026-07",
  "requestId": "req_...",
  "intentId": "intent_...",
  "tenantId": "ten_...",
  "accountId": "acct_...",
  "deviceId": "dev_...",
  "actorId": "svc_...",
  "subjectId": "user_...",
  "commandType": "app.operation",
  "createdAt": "2026-07-12T16:00:00Z",
  "expiresAt": "2026-07-12T16:05:00Z",
  "idempotencyKey": "idem_...",
  "traceparent": "00-...",
  "payload": { },
  "grant": { },
  "integrity": { }
}

Design recommendation: The identifiers above should all be distinct. A tenant is not an account, an account is not a session, a session is not a device, a device is not a request, and a request is not an audit record. Keeping those namespaces separate materially reduces confused-deputy risk, replay ambiguity, and forensic confusion.

Resource semantics, status reporting, retries, and honest guarantees

Protocol requirement: HTTP method usage should follow RFC 9110 semantics. Read-only operations should use safe methods. State-changing operations should not be tunneled through GET. Automatic retries are only acceptable for idempotent methods, or for non-idempotent methods when the client has independent evidence that replay is safe—typically because the operation defines an idempotency key and the server persists it durably. Conditional requests and preconditions should be used for resource version protection and lost-update prevention.

Protocol requirement: Every command lifecycle state exposed to the website must correspond to an actual evidence boundary, not a guessed one. “Queued” should mean durably accepted by the command service. “Delivered” should mean durably persisted in the desktop inbox, not merely placed on a socket. “Awaiting local approval” should mean the local policy engine has accepted the request for review but has not authorized execution. “Executing” should mean the desktop has begun side-effect work. “Succeeded” and “failed” require durable desktop evidence. “Cancelled” should only apply when execution was prevented or a real compensating action completed. “Outcome unknown” must exist for crash windows where the side effect may have happened but durable confirmation did not. That is the only honest state model for a desktop-side effect system.

Protocol requirement: Problem Details should be the standard error body for non-successful HTTP responses, with stable URI-identified problem types and product-specific extension members. The type URI, not the title, should be the primary machine identifier. Sensitive implementation details, stack traces, raw secrets, and accidental privacy leaks must not appear in problem payloads.

Design recommendation: A baseline retry taxonomy should look like this.

Design recommendation: The retry table is a synthesized client policy derived from HTTP semantics, preconditions, rate-limit signaling, and the brief’s requirement for honest guarantees rather than transport mythologies. Retry-After should be honored when present, and retries should be bounded by a request deadline and a retry budget so that the caller can still surface an honest timeout or outcome unknown instead of retrying indefinitely. .NET’s official guidance aligns with shared clients, pooled connections, and resilience pipelines using exponential backoff.

Protocol requirement: Cancellation must be defined as a phase-specific semantic, not a universal promise. Before dispatch, cancellation can be definitive. After inbox persistence but before execution, cancellation can be best-effort but usually definitive if the desktop can tombstone the request. During execution, cancellation means “attempted interruption” and must depend on whether the local operation exposes a safe stop point. After an irreversible side effect, cancellation cannot imply rollback unless a compensating action actually completed. Browser AbortController, Python async cancellation, and Tokio task cancellation mechanisms are useful implementation tools, but they do not change the business truth that side effects may survive a transport or task cancellation signal.

Observability, privacy, and browser constraints

Protocol requirement: Trace propagation should use W3C traceparent and optional tracestate, and the implementation should adopt OpenTelemetry-style separation between API and SDK concerns so that instrumentation stays portable across C#, Python, TypeScript, and Rust. Every request should also carry product-level requestId, correlationId, and causationId, because trace context alone is not a substitute for business identity.

Protocol requirement: Browser restrictions must be treated as first-class design constraints, not incidental details. Browsers restrict cross-origin scripted requests unless the target authorizes them with CORS. Cookies require CSRF controls because browsers auto-attach them. SameSite helps but is defense in depth, not a complete CSRF defense in most deployments. For one-way status feeds, SSE is often operationally simpler than WebSockets. Where WebSockets are used in browsers, the standard API lacks built-in backpressure, which means it should not become the only correctness-bearing delivery path for critical command status.

Protocol requirement: Logs should default to metadata, not payload content. Safe logging fields usually include opaque identifiers, timestamps, versions, latency measurements, HTTP status, problem type URI, retry classification, and digest values. Tokens, raw command arguments, secret values, unredacted user content, and anything that could reconstruct a local side effect should be omitted or aggressively redacted. Problem Details itself warns against exposing sensitive implementation details in error content, and OWASP secrets guidance reinforces minimizing secret exposure paths.

Implementation and Conformance Strategy

Generated models and handwritten adapters

Protocol requirement: Generated types should be treated as transport DTOs, not as the domain model. The generator owns serialization names, optionality, and basic validation scaffolding. Handwritten adapters own richer invariants, local policy checks, capability mapping, and translation into language-idiomatic public APIs. Smithy’s documentation explicitly emphasizes protocol-agnostic models and code generation, while OpenAPI emphasizes use across documentation, generation, testing, and discovery; those strengths should be used for DTO generation, not to turn the generator into the application architecture.

Protocol requirement: Validation must exist at every trust boundary even when generated validators are available. TypeScript’s value proposition is a static typechecker that runs before code runs, which means boundary safety still requires runtime validation. JSON Schema should therefore drive generated or referenced runtime validators in browser TypeScript, server-side TypeScript, Python services, Rust services, and desktop ingress. OWASP’s API risks reinforce that improper object authorization and overly trusting external input are recurring causes of compromise.

Language-specific implementation guidance

Design recommendation: The two highest-risk cross-language defects are numeric semantics and error taxonomy drift. Numeric rules should be contract-level, not language-default. Error categories should be product-level, not library-specific. The public HTTP/service error model should therefore be a small, fixed taxonomy—authentication, authorization, validation, conflict, throttling, dependency failure, transient failure, cancellation, and outcome unknown—projected into language-idiomatic exception or result styles rather than reverse-engineered from those styles.

Evolution, deterministic testing, and deployment safety

Protocol requirement: Additive and breaking change rules must be codified in CI. OpenAPI and JSON Schema artifacts should be linted, diffed, and regeneration-tested on every change. Stored envelopes need stronger compatibility guarantees than transient internal calls because they can outlive a release. Unknown fields may be tolerated in forward-compatible readers, but security-sensitive command inputs should reject undeclared top-level fields unless the contract explicitly defines an extension escape hatch. That protects against mass assignment and authorization confusion while still permitting controlled evolution.

Protocol requirement: A conformance corpus should include golden vectors consumed unchanged by C#, Python, TypeScript, and Rust. Each vector should fix the exact JSON bytes, canonicalized JSON bytes, digest values, timestamps, Unicode edge cases, duplicate-key rejection cases, enum unknown cases, idempotency-key duplicates, state-machine sequences, cancellation races, and problem-detail examples. Canonicalization and digest vectors are especially important because they expose invisible cross-runtime differences early.

Design recommendation: The deterministic test harness should include a fake authorization server, fake command API, fake queue, and fake desktop transport with scripted failures: reorderings, duplicate deliveries, cursor loss, sleep/resume, rate limiting, token expiry, cancellation races, partial network partitions, and crash windows that force outcome unknown. That is the minimum viable proof that the architecture can make the honest claims the brief requires without relying on access to live product infrastructure.

Research Plan and Open Questions

Recommended plan and timeline

Design recommendation: The default execution plan should be an eight-week architecture-and-conformance cycle rather than a short design-spike. The brief is too broad for a purely synchronous design memo and too implementation-adjacent for a purely academic review. An eight-week cycle balances decision quality with implementation momentum.

gantt
    title Recommended eight-week research and architecture cycle
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d

    section Standards and trust model
    Source triage and standards ledger        :a1, 2026-07-13, 7d
    Trust-boundary and actor model            :a2, after a1, 7d

    section Contract decisions
    Contract technology decision              :b1, 2026-07-20, 7d
    Normative envelope and HTTP profile       :b2, 2026-07-27, 10d
    Identity and delegation profile           :b3, 2026-07-27, 10d

    section Conformance artifacts
    Golden vectors and schema corpus          :c1, 2026-08-03, 10d
    Fake server and fake desktop transport    :c2, 2026-08-03, 10d

    section Verification and rollout
    Cross-language adapter review             :d1, 2026-08-10, 7d
    Failure-mode and chaos scenarios          :d2, 2026-08-10, 7d
    Decision review and implementation handoff:d3, 2026-08-17, 5d

Estimated resources

Design recommendation: The baseline staffing profile should be:

Open questions that require authorized internal validation

Open question: The following items cannot be responsibly closed from public standards and the uploaded brief alone.

Design recommendation: The practical next-step package should be: adopt the OpenAPI/JSON-Schema-first contract baseline; ratify the dual-authorization model where hosted authorization and local capability approval are both required; define the command envelope and lifecycle states including outcome unknown; require runtime validation in every language despite code generation; and stand up the golden-vector corpus before any large-scale implementation begins. Those steps retire the most architectural risk earliest and create a stable foundation for the rest of the brief’s deliverables.