Merge branch 'fix/cli-40-41-44'

docs/ClientBehaviorFixtures.md

@@ -70,6 +70,40 @@ The rules those fixtures lock in are:
   negative. Positive COM success codes such as `S_FALSE` pass, matching COM
   semantics.
 
+### Malformed-Reply And Credential-Redaction Conformance
+
+Three further command reply fixtures pin the id/handle-extraction and
+credential-redaction contracts for the credential-bearing helpers:
+
+| Fixture | Reply | Expected behavior |
+|---|---|---|
+| `authenticate-user.echoed-credential.reply.json` | OK envelope, negative `hresult`, and the caller's credential echoed into `protocolStatus.message`, `statuses[0].diagnosticText`, and `diagnosticMessage` | the surfaced error redacts the exact secret from **both** the rendered message and the structured reply accessors (never leaks the verbatim value) |
+| `authenticate-user.echoed-credential-mxaccess-failure.reply.json` | the same echo, but coded `PROTOCOL_STATUS_CODE_MXACCESS_FAILURE` | identical redaction; confirms every client routes the MXAccess-failure protocol code to its MXAccess error type and scrubs it |
+| `authenticate-user.missing-payload.reply.json` | OK envelope, no `AuthenticateUser` payload, no `return_value` | a typed malformed-reply error, never a proto3 default `0` and never an NRE |
+| `authenticate-user.return-value-only.reply.json` | OK envelope, `return_value.int32_value = 7`, no typed payload | the id resolves to `7` via the legacy `return_value` compatibility path |
+
+The rules those fixtures lock in are:
+
+- **Malformed-reply extraction (CLI-41).** Every helper that extracts a scalar
+  id/handle (`AuthenticateUser`, `ArchestrAUserToId`, `AddBufferedItem`, and the
+  handle extractors) prefers the typed payload; when it is absent it falls back
+  to `return_value` **only** when `return_value` is present with the expected
+  int32 variant; when neither is present it raises a typed malformed-reply error.
+  It never surfaces a proto3 default `0` and never throws a null-reference.
+- **Credential redaction (CLI-40).** The credential-bearing helpers
+  (`AuthenticateUser`, `WriteSecured`/`WriteSecured2`) scrub the exact secret
+  values they were called with from any surfaced error — both the rendered
+  message text **and** the structured reply the error still exposes (a
+  server-echoed credential lives in `protocolStatus.message` and
+  `statuses[].diagnosticText`, which the error's raw-reply accessor would
+  otherwise re-expose to a logger dumping structured fields). The redacted error
+  therefore carries a scrubbed clone of the reply. This is defense-in-depth on
+  top of the by-construction guarantee that exceptions carry reply-derived text,
+  not the request. The marker is `<redacted>` in the Go, Rust, and Java clients
+  and `[redacted]` in the Python client and the .NET CLI; each suite asserts that
+  neither the surfaced message nor the exposed reply still contains the
+  credential, and that the message contains the client's marker.
+
 ## Event Streams
 
 Event stream fixtures live in
@@ -100,6 +134,12 @@ behavior. A language helper may expose native booleans, integers, strings,
 arrays, and timestamps, but it must keep `rawDiagnostic`, raw data type fields,
 and raw byte payloads accessible when conversion is incomplete.
 
+Each status case also carries an independent `wantSuccess` boolean alongside its
+`status` object. The success/failure conformance tests assert the helper's
+verdict against this fixture-declared expectation rather than recomputing it from
+`category` (the same formula under test), so a regression in the verdict rule
+cannot hide behind a self-consistent computation.
+
 ## Auth, Timeout, And Cancel Behavior
 
 Authentication fixtures live in `clients/proto/fixtures/behavior/auth/`. They

docs/ClientLibrariesDesign.md

@@ -126,11 +126,28 @@ rules across all five clients (see
 failing before a prior `AuthenticateUser` + `AdviseSupervisory` surfaces the
 native failure unchanged — the helper does not pre-validate or reorder it.
 
+**Malformed-reply extraction:** the id/handle-returning helpers
+(`AuthenticateUser`, `ArchestrAUserToId`, `AddBufferedItem`, and the handle
+extractors) follow one contract across all five clients — prefer the typed
+payload; fall back to `return_value` only when it is present with the expected
+int32 variant; when neither is present, raise a typed malformed-reply error.
+They never surface a proto3 default `0` and never throw a null-reference (CLI-41).
+
 **Credential handling:** `AuthenticateUser` credentials and `WriteSecured`
 secured payloads route through each client's secret-redaction seam so they never
 reach logs, exception text, or `ToString`/`Debug`/`Display` — the value is carried
-only on the wire. Each client's test suite asserts a distinctive credential is
-absent from any surfaced error.
+only on the wire. In addition to that by-construction guarantee (exceptions carry
+reply-derived text, not the request), every client scrubs the **exact** secret
+values it was called with from any surfaced error as defense-in-depth, so a
+gateway or MXAccess diagnostic that echoes a credential back cannot leak it
+(CLI-40). The scrub covers **both** the rendered message and the structured reply
+the error still exposes (`protocolStatus.message`, `statuses[].diagnosticText`,
+`diagnosticMessage`): the redacted error carries a scrubbed clone of the reply so
+a logger dumping the exception's structured fields cannot reintroduce the leak.
+This holds regardless of whether the reply is coded `OK` (with a failing HRESULT)
+or `MXACCESS_FAILURE` — every client routes both to its MXAccess error type. Each
+client's test suite asserts the distinctive credential is absent from both the
+surfaced message and the exposed reply, and that the redaction marker is present.
 
 Shipped in all five clients (.NET / Go / Rust / Python / Java).