@stigmer/server 3.14.0-dev.20260910084630

package/src/pipeline/interceptors/auth.ts

@@ -0,0 +1,431 @@
+/**
+ * Identity chassis — chain position 1, outermost (reserved by DD-004;
+ * filled by O2, 20260827.01, per DD-007 §1). Every request enters the
+ * server through exactly one of the two identity sources this module
+ * owns, and every request leaves position 1 with a CallerIdentity stashed
+ * under `callerIdentityKey`:
+ *
+ *   - createVerifierChainInterceptor — the serving chain's source: an
+ *     ordered claim-or-pass walk over the composed IdentityVerifiers (the
+ *     TS rendering of the Java ProviderManager chain), followed by the
+ *     composed CallerGuards over the stamped identity (entry 20260902.02
+ *     ruling Q1 — see extensions/caller-guards.ts for the contract and
+ *     its doctrine).
+ *   - createInProcessCallerInterceptor — the in-process router
+ *     transport's source: stamps the `internal` caller class (ruling Q4,
+ *     the TS rendering of the Java in-process authorization skip). It
+ *     takes NO guards — the in-process exemption is structural
+ *     (caller-guards.ts), not a runtime skip.
+ *
+ * The serving source's inner walk, authenticateBearerToken, is ALSO
+ * exported on its own (stigmer#991): a composition's extension-owned HTTP
+ * lanes are not Connect requests, so they cannot ride the interceptor, but
+ * they must authenticate with the same chain — one walk, two edges.
+ *
+ * The internal class is mintable ONLY here, only by the in-process
+ * interceptor: the serving chain always overwrites the position-1 value
+ * from the wire, contextValues never cross a transport, and no
+ * IdentityVerifier may produce the class (contract on CallerClass).
+ * Spoofing is structurally impossible, not policed.
+ *
+ * # Conditional strictness (ruling Q6 — pinned contract)
+ *
+ * Strictness is a function of whether any verifier is configured:
+ *
+ *   - ZERO verifiers (every shipped OSS composition today): a presented
+ *     token that nothing claims falls through SILENTLY to the
+ *     trusted-local identity. This preserves wire behavior byte-for-byte
+ *     — the runner presents a Bearer token on every control-plane RPC
+ *     when STIGMER_TOKEN is set, and domains that verify tokens (the
+ *     executioncontext decrypt lane) read the raw header themselves.
+ *   - ONE OR MORE verifiers: a presented-but-unclaimed token is
+ *     UNAUTHENTICATED. A configured issuer must never silently admit
+ *     garbage tokens as trusted-local.
+ *   - An ABSENT token falls to trusted-local UNLESS the composition asks
+ *     for the require-authentication posture (O3 rulings Q1+Q2,
+ *     20260827.06): with requireAuthentication on — compose.ts sets it
+ *     when STIGMER_OIDC_ISSUER is configured OR when a composed extension
+ *     unit declares `requireAuthentication` (entry 20260904.02, the
+ *     cloud's ask: its own lanes resolve its users, and the issuer knob
+ *     cannot stand in because it also registers the OSS OIDC verifier
+ *     ahead of them; the OSS API-key lane, by contrast, rides EITHER
+ *     posture source — stigmer#984) — a tokenless request is
+ *     UNAUTHENTICATED "authentication token missing" (the Java
+ *     interceptor's byte-pinned copy), EXCEPT where isAuthenticationExempt
+ *     says so: is_public-marked methods (the Java isPublic skip) and the
+ *     gRPC health service by name (the Java by-name skip — a third-party
+ *     proto cannot carry our option, and a Kubernetes `grpc:` probe is a
+ *     tokenless Health/Check; without this arm the posture crash-loops the
+ *     pod, stigmer#974). Extension-only verifier sets that declare
+ *     nothing keep the fall-to-trusted-local arm: strictness against
+ *     PRESENTED tokens is a function of verifier count (Q6); strictness
+ *     against ABSENT tokens is the composition's explicit ask.
+ *
+ * # Trusted-local identity (the explicit modeled state)
+ *
+ * No issuer + no claim = the single-operator trust domain's one
+ * principal, minted from the #400 operator seam (steps/defaults.ts):
+ * identityId is the operator email (email-first, matching the audit
+ * doctrine there), or "system" when unconfigured. The audit-actor seam
+ * derives from this identity the exact bytes currentAuditActor stamped
+ * before O2.
+ *
+ * # Verifier faults
+ *
+ * A verifier that throws a ConnectError chose its wire shape (signature/
+ * expiry/audience failures are UNAUTHENTICATED by the verifier's own
+ * mapping); any other throw is an infrastructure fault — INTERNAL, never
+ * softened into an auth denial (the DD-007 unavailable doctrine, applied
+ * to the verification side).
+ */
+import { Code, ConnectError, createContextKey } from "@connectrpc/connect";
+import type {
+  HandlerContext,
+  Interceptor,
+  StreamRequest,
+  UnaryRequest,
+} from "@connectrpc/connect";
+import { getOption } from "@bufbuild/protobuf";
+import type { DescMethod } from "@bufbuild/protobuf";
+
+import { is_public } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerGuard } from "../../extensions/caller-guards.js";
+import type {
+  CallerIdentity,
+  IdentityVerifier,
+} from "../../extensions/identity.js";
+import { internalError } from "../errors.js";
+import { operatorIdentitySnapshot } from "../steps/defaults.js";
+
+/**
+ * The tokenless-request refusal under the require-authentication posture —
+ * the Java interceptor's copy (GrpcSecurityConfigBase), byte-pinned.
+ */
+export const AUTHENTICATION_TOKEN_MISSING_MESSAGE =
+  "authentication token missing";
+
+/**
+ * Services reachable WITHOUT a credential under the require-authentication
+ * posture, by fully-qualified service name — the Java interceptor's
+ * by-name skip list (GrpcSecurityConfigBase), for services whose protos
+ * are not ours and so cannot carry the `is_public` method option. The
+ * standard gRPC health service is the one entry OSS serves: Kubernetes
+ * `grpc:` probes call Health/Check tokenless, and a refused probe is a
+ * pod that never becomes Ready (stigmer#974). Java's second entry,
+ * `grpc.reflection.v1alpha.ServerReflection`, is deliberately absent —
+ * OSS registers no reflection service; a future registration joins this
+ * set in the same change, or the posture refuses it.
+ */
+export const AUTHENTICATION_EXEMPT_SERVICES: ReadonlySet<string> = new Set([
+  "grpc.health.v1.Health",
+]);
+
+/**
+ * Whether a method stays reachable tokenless under the
+ * require-authentication posture: `is_public` on the method (our protos)
+ * or an exempt service by name (third-party protos). The ONE predicate
+ * the refusal arm consults, so both exemption doctrines read as a single
+ * decision and are pinned together.
+ */
+export function isAuthenticationExempt(method: DescMethod): boolean {
+  return (
+    getOption(method, is_public) ||
+    AUTHENTICATION_EXEMPT_SERVICES.has(method.parent.typeName)
+  );
+}
+
+/**
+ * Context key for the request's caller identity. The default is
+ * `undefined` so a read BEFORE position 1 has stamped (a wiring bug — both
+ * chains stamp unconditionally) is loud through callerIdentityOf, never a
+ * silent placeholder principal.
+ */
+export const callerIdentityKey = createContextKey<CallerIdentity | undefined>(
+  undefined,
+  { description: "caller identity produced at chain position 1" },
+);
+
+/**
+ * The request's caller identity — the ONE read idiom for controllers
+ * (threaded into RequestContext exactly once, ruling Q3). Throws the
+ * composition-root wiring fault when position 1 did not stamp: that state
+ * is unreachable through either chain, so reaching it means a transport
+ * was built without an identity source.
+ */
+export function callerIdentityOf(ctx: HandlerContext): CallerIdentity {
+  const identity = ctx.values.get(callerIdentityKey);
+  if (identity === undefined) {
+    throw internalError(
+      new Error("no caller identity in context (chain wiring bug)"),
+      "internal server error",
+    );
+  }
+  return identity;
+}
+
+/**
+ * The trusted-local single-user identity — the explicit modeled state for
+ * "no verifier claimed this request". Read per request (not cached at
+ * chain build) so composeServer stays re-entrant for tests while the
+ * operator seam remains process-global.
+ */
+export function trustedLocalIdentity(): CallerIdentity {
+  const operator = operatorIdentitySnapshot();
+  if (operator.email === "") {
+    return {
+      identityId: "system",
+      callerClass: "user",
+      issuer: "",
+      rawToken: "",
+    };
+  }
+  return {
+    identityId: operator.email,
+    callerClass: "user",
+    issuer: "",
+    rawToken: "",
+    email: operator.email,
+    displayName: operator.displayName,
+  };
+}
+
+/**
+ * The serving chain's position-1 identity source: walks the composed
+ * verifiers in order (OSS entries first, extension entries after, in
+ * extension-unit order — registry contract), stamps the claimed identity
+ * or the trusted-local fallback per the strictness contract above, then
+ * runs the composed caller guards over the stamped identity (entry
+ * 20260902.02 ruling Q1). Covers unary AND streams — identity is
+ * per-request state, not a unary-pipeline concern like the apiresource
+ * kind.
+ *
+ * `guards` is REQUIRED, like the identity source on buildInterceptorChain:
+ * a serving transport that forgets its guards must be a compile error,
+ * never a silently unenforced edge — the exact failure class this seam
+ * exists to close (the cloud's platform-client controls went unported
+ * through five green readouts because nothing forced them).
+ */
+export function createVerifierChainInterceptor(
+  verifiers: ReadonlyArray<IdentityVerifier>,
+  guards: ReadonlyArray<CallerGuard>,
+  logger: Logger,
+  requireAuthentication = false,
+): Interceptor {
+  return (next) => async (request) => {
+    // The in-process propagation header is meaningless — and forgeable —
+    // on the wire: stripped unconditionally before anything downstream
+    // could read it (ruling R5's unspoofability-by-construction arm).
+    request.header.delete(IN_PROCESS_CALLER_HEADER);
+    const token = parseBearerToken(request.header.get("authorization") ?? "");
+    let identity: CallerIdentity | undefined;
+    if (token !== "") {
+      identity = await authenticateBearerToken(verifiers, token, logger);
+      if (identity === undefined && verifiers.length > 0) {
+        // Position 1 is outside the logging interceptor, so the rejection
+        // is recorded here (the wire carries only the sanitized copy).
+        logger.warn("presented token not claimed by any identity verifier", {
+          verifiers: verifiers.map((v) => v.name).join(", "),
+        });
+        throw new ConnectError(
+          "the presented token was not accepted by any configured identity verifier",
+          Code.Unauthenticated,
+        );
+      }
+    } else if (
+      requireAuthentication &&
+      !isAuthenticationExempt(request.method)
+    ) {
+      // Rulings Q1+Q2: the auth-enabled posture requires a credential on
+      // every non-exempt method — the Java interceptor's exact behavior
+      // and copy. is_public methods and the health service stay reachable
+      // tokenless (the Java isPublic and by-name skips), so the console's
+      // anonymous reads and the pod's probes survive.
+      throw new ConnectError(
+        AUTHENTICATION_TOKEN_MISSING_MESSAGE,
+        Code.Unauthenticated,
+      );
+    }
+    const stamped = identity ?? trustedLocalIdentity();
+    request.contextValues.set(callerIdentityKey, stamped);
+    await runCallerGuards(guards, stamped, request, logger);
+    return next(request);
+  };
+}
+
+/**
+ * The composed-order guard walk (caller-guards.ts contract): every guard
+ * runs against the FINAL stamped identity; the first throw wins. A
+ * ConnectError is the guard's own wire mapping; any other throw is an
+ * infrastructure fault (INTERNAL — a store outage during a liveness read
+ * must never read as an admission refusal). Both arms are recorded here:
+ * position 1 sits outside the logging interceptor, so this is a guard
+ * outcome's only operator record (the verifier-rejection precedent
+ * above).
+ */
+async function runCallerGuards(
+  guards: ReadonlyArray<CallerGuard>,
+  caller: CallerIdentity,
+  request: UnaryRequest | StreamRequest,
+  logger: Logger,
+): Promise<void> {
+  for (const guard of guards) {
+    try {
+      await guard.guard(caller, request.method, request.header);
+    } catch (error) {
+      const procedure = `/${request.service.typeName}/${request.method.name}`;
+      if (error instanceof ConnectError) {
+        logger.warn("caller guard refused the request", {
+          guard: guard.name,
+          procedure,
+          code: Code[error.code],
+        });
+        throw error;
+      }
+      logger.error("caller guard failed", {
+        guard: guard.name,
+        procedure,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw internalError(error, "internal server error");
+    }
+  }
+}
+
+/**
+ * The caller-propagation header of the in-process lane (C2 Stage 3,
+ * ruling R5). Client CallOptions carry no contextValues across the
+ * router transport, so the asCaller adapters (boot/inprocess.ts) ride
+ * the one channel that does cross it: a request header, base64url JSON.
+ * Unspoofable from the wire BY CONSTRUCTION: the serving chassis strips
+ * it before anything can read it, and only the in-process interceptor —
+ * reachable only by server code — honors it.
+ */
+export const IN_PROCESS_CALLER_HEADER = "x-stigmer-inprocess-caller";
+
+/** Encodes a CallerIdentity for the propagation header. */
+export function encodeInProcessCaller(caller: CallerIdentity): string {
+  return Buffer.from(JSON.stringify(caller)).toString("base64url");
+}
+
+/**
+ * The in-process transport's position-1 identity source. Two arms since
+ * C2 Stage 3 (ruling R5 — the caller-propagation amendment restoring the
+ * Java posture, where in-process calls carried the ORIGINAL caller):
+ *
+ *   - PROPAGATED: a request-origin adapter passed the original caller's
+ *     identity through {@link IN_PROCESS_CALLER_HEADER} (the asCaller
+ *     edges) — it forwards with `origin: "in-process"` stamped, so
+ *     attribution (owner/creator tuples, audit) lands on the real user
+ *     while transport-trust arms (the reserved-label guard) still see
+ *     the server-composed origin.
+ *   - MINTED: no propagated identity — the daemon-origin default (the
+ *     schedule clock, the project reconciler): the internal caller class
+ *     carrying the operator's identity fields, so audit stamps on
+ *     daemon writes stay byte-identical to the pre-R5 posture. The
+ *     Authorize step treats the internal class as the in-process
+ *     authorization skip (ruling Q4).
+ *
+ * A malformed propagation header is a WIRING BUG (only server code can
+ * write it) — loud INTERNAL, never a silent fall-through to a wrong
+ * identity.
+ */
+export function createInProcessCallerInterceptor(): Interceptor {
+  return (next) => (request) => {
+    const encoded = request.header.get(IN_PROCESS_CALLER_HEADER);
+    let identity: CallerIdentity;
+    if (encoded !== null) {
+      request.header.delete(IN_PROCESS_CALLER_HEADER);
+      try {
+        identity = {
+          ...(JSON.parse(
+            Buffer.from(encoded, "base64url").toString("utf8"),
+          ) as CallerIdentity),
+          origin: "in-process",
+        };
+      } catch (error) {
+        throw internalError(
+          error instanceof Error ? error : new Error(String(error)),
+          "internal server error",
+        );
+      }
+    } else {
+      identity = {
+        ...trustedLocalIdentity(),
+        callerClass: "internal",
+        origin: "in-process",
+      };
+    }
+    request.contextValues.set(callerIdentityKey, identity);
+    return next(request);
+  };
+}
+
+/**
+ * The claim-or-pass walk (identity.ts contract): a claim wins, null moves
+ * to the next verifier, a ConnectError throw is the verifier's own wire
+ * mapping, any other throw is an infrastructure fault (INTERNAL — a JWKS
+ * outage must never read as a credential rejection). `undefined` means no
+ * verifier claimed the token — the CALLER decides what that means
+ * (the serving interceptor applies the Q6 strictness contract above).
+ *
+ * Exported (stigmer#991) so a composition's extension-owned HTTP lanes —
+ * edges that are not Connect requests and so never pass through
+ * createVerifierChainInterceptor — authenticate a presented bearer with
+ * the SAME composed chain, in the same order, under the same fault
+ * doctrine. The alternative, a composition re-instantiating its verifier
+ * list at the HTTP edge, is a second copy of chain order and fault
+ * mapping — exactly the drift DD-007's "one chain" rules out. This is the
+ * identity walk ONLY: caller guards (caller-guards.ts) are RPC-shaped by
+ * contract and stay the serving interceptor's; an HTTP edge that wants
+ * them is a contract widening, not a call site.
+ */
+export async function authenticateBearerToken(
+  verifiers: ReadonlyArray<IdentityVerifier>,
+  token: string,
+  logger: Logger,
+): Promise<CallerIdentity | undefined> {
+  for (const verifier of verifiers) {
+    let claimed: CallerIdentity | null;
+    try {
+      claimed = await verifier.verify(token);
+    } catch (error) {
+      if (error instanceof ConnectError) {
+        throw error;
+      }
+      logger.error("identity verifier failed", {
+        verifier: verifier.name,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw internalError(error, "internal server error");
+    }
+    if (claimed !== null) {
+      return claimed;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The Bearer credential from a (possibly comma-joined) authorization
+ * header value; empty when absent or differently shaped. One shared
+ * definition of the shape both consumers use (this chassis and the
+ * executioncontext decrypt lane): case-insensitive "bearer " prefix, the
+ * remainder non-empty before trimming. Node's http2 layer joins repeated
+ * headers with ", " — the first comma segment IS the first value, and a
+ * genuine token (base64url segments joined by dots) can never contain a
+ * comma, so the split is lossless for every legitimate shape (the Go
+ * server read metadata values[0], same result).
+ */
+export function parseBearerToken(joinedHeaderValue: string): string {
+  const header = joinedHeaderValue.split(",")[0] ?? "";
+  const prefix = "bearer ";
+  if (
+    header.length <= prefix.length ||
+    header.slice(0, prefix.length).toLowerCase() !== prefix
+  ) {
+    return "";
+  }
+  return header.slice(prefix.length).trim();
+}

package/src/pipeline/interceptors/error-boundary.ts

@@ -0,0 +1,246 @@
+/**
+ * Error-boundary interceptor — the serving chain's position 0, the TS
+ * port of the cloud Java VisitorErrorSanitizerInterceptor posture (cloud
+ * DD-005 of 20260810.02, shipped for stigmer-cloud#242; ported by
+ * convergence entry 20260830.03.sp.visitor-error-sanitizer, all six gate
+ * rulings as recommended).
+ *
+ * Two arms, one structural guarantee each:
+ *
+ *   1. RAW-ERROR CONVERSION (always on, gate ruling Q2): a non-ConnectError
+ *      escaping any handler — the direct handlers whose internalError
+ *      wrapping is per-site discipline, not structure — becomes the
+ *      pipeline executor's exact sanitized Internal
+ *      ("internal server error") instead of connect-node's default
+ *      Unknown-with-raw-message conversion. This closes the
+ *      leak-by-default class for direct handlers the way
+ *      pipeline.ts closes it for chains (stigmer#478's sibling). The
+ *      guidelines' self-sanitize discipline still applies — a handler's
+ *      own "failed to <do thing>" copy beats this generic net.
+ *
+ *   2. VISITOR SANITIZATION (policy-driven, empty by default): when a
+ *      composition registers a VisitorErrorPolicy, descriptions of the
+ *      six leak-prone codes are rewritten for callers the policy deems
+ *      on the anonymous surface (the cloud: guest / channel / is_public),
+ *      the code ALWAYS preserved so SDK retry semantics stay honest, a
+ *      minted support ref appended in the Java byte-pinned format, and
+ *      the original description kept operator-visible via the boundary
+ *      WARN (log-based correlation — the TS serving path has no OTel
+ *      span to stamp, gate ruling Q3). The sanitized error is a FRESH
+ *      ConnectError: details and metadata never survive sanitization
+ *      (the Java trailers-drop, and rethrownStatusError's metadata
+ *      lesson).
+ *
+ * Placement contract: OUTERMOST on the SERVING chain only (chain.ts).
+ * Outermost keeps the Java pin "sanitizes even with no identity context"
+ * (identity is read from contextValues at error time — stamped by
+ * position 1 when the error rose from inside it, absent when position 1
+ * itself refused) and covers identity-chassis faults; the logging
+ * interceptor sits inside, so operators keep the ORIGINAL error at error
+ * level while the wire carries the rewrite. The in-process chain never
+ * composes this interceptor — in-process hops are exempt by
+ * construction (the outer handler needs the full inner diagnostic), the
+ * TS rendering of the Java InProcessCallContextHolder exemption.
+ *
+ * Streams: mid-iteration errors bypass a plain `await next(request)`
+ * wrapper, so stream responses are re-wrapped with a guarded iterable —
+ * without it, server-stream errors would escape both arms.
+ */
+import { randomBytes } from "node:crypto";
+import { Code, ConnectError } from "@connectrpc/connect";
+import type {
+  Interceptor,
+  StreamRequest,
+  UnaryRequest,
+} from "@connectrpc/connect";
+import type { DescMethod } from "@bufbuild/protobuf";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { internalError } from "../errors.js";
+import { INTERNAL_FALLBACK_MESSAGE } from "../pipeline.js";
+import { callerIdentityKey } from "./auth.js";
+
+/**
+ * The codes whose descriptions may carry internals — the deny-leaky
+ * matrix ratified by cloud DD-005 (20260810.02) and byte-pinned across
+ * editions. Deliberate-refusal codes (PermissionDenied,
+ * FailedPrecondition, ResourceExhausted, …) pass through untouched:
+ * their descriptions are authored copy, including owner-customized
+ * refusal messages and machine tokens brokers branch on.
+ */
+const SANITIZED_CODES: ReadonlySet<Code> = new Set([
+  Code.Internal,
+  Code.Unknown,
+  Code.DataLoss,
+  Code.Unavailable,
+  Code.DeadlineExceeded,
+  Code.Unimplemented,
+]);
+
+/**
+ * The visitor-sanitization policy a composition registers through
+ * ExtensionDrivers.visitorErrorPolicy (single-instance point). The
+ * boundary owns the mechanism — the code set, code preservation, the
+ * ref format, details/metadata dropping, the boundary WARN; the policy
+ * owns the edition semantics — WHO is on the anonymous surface and WHAT
+ * copy replaces the description.
+ */
+export interface VisitorErrorPolicy {
+  /**
+   * Whether this caller+method pair is on the anonymous surface (the
+   * cloud rule: guest or channel caller class, or an is_public method).
+   * Synchronous and cheap — it runs on every boundary error. `identity`
+   * is undefined when the error rose from position 1 before stamping
+   * (the Java "no interceptor context" arm — an is_public rule must
+   * still answer there). A throw is treated as eligible: over-sanitizing
+   * an org member's diagnostics is recoverable, leaking internals to a
+   * visitor is not.
+   */
+  eligible(identity: CallerIdentity | undefined, method: DescMethod): boolean;
+  /**
+   * The replacement description (WITHOUT the support ref — the boundary
+   * appends it). Runs only on the error path, so per-call resolution
+   * work (the cloud's per-share owner copy) is admissible. A rejection
+   * falls back to the pipeline's sanitized-Internal copy — never the
+   * original description.
+   */
+  replacementCopy(
+    identity: CallerIdentity | undefined,
+    method: DescMethod,
+  ): Promise<string>;
+}
+
+/**
+ * The Java supportRef format, byte-pinned (gate ruling Q3):
+ * `" (ref: <8 hex chars>)"`. Java derives the ref from the first 8 of
+ * the trace id; the TS serving path has no trace id, so the boundary
+ * mints one on the error path and the boundary WARN is the correlation
+ * point.
+ */
+export function supportRefSuffix(ref: string): string {
+  return ` (ref: ${ref})`;
+}
+
+function mintSupportRef(): string {
+  return randomBytes(4).toString("hex");
+}
+
+/**
+ * Builds the boundary for the serving chain. `policy` is the composed
+ * VisitorErrorPolicy or undefined (the OSS default) — arm 1 runs either
+ * way, arm 2 only with a policy.
+ */
+export function createErrorBoundaryInterceptor(
+  logger: Logger,
+  policy?: VisitorErrorPolicy,
+): Interceptor {
+  return (next) => async (request) => {
+    let response;
+    try {
+      response = await next(request);
+    } catch (error) {
+      throw await boundaryError(error, request, logger, policy);
+    }
+    if (response.stream) {
+      return {
+        ...response,
+        message: guardStreamMessages(response.message, request, logger, policy),
+      };
+    }
+    return response;
+  };
+}
+
+/** Re-raises mid-stream errors through the same two boundary arms. */
+async function* guardStreamMessages<T>(
+  messages: AsyncIterable<T>,
+  request: UnaryRequest | StreamRequest,
+  logger: Logger,
+  policy: VisitorErrorPolicy | undefined,
+): AsyncIterable<T> {
+  try {
+    yield* messages;
+  } catch (error) {
+    throw await boundaryError(error, request, logger, policy);
+  }
+}
+
+async function boundaryError(
+  error: unknown,
+  request: UnaryRequest | StreamRequest,
+  logger: Logger,
+  policy: VisitorErrorPolicy | undefined,
+): Promise<ConnectError> {
+  const procedure = `/${request.service.typeName}/${request.method.name}`;
+
+  // Arm 1: the structural raw-error conversion (Q2). The logging
+  // interceptor inside already recorded unary failures; this line is the
+  // only record for mid-stream and identity-chassis raws, and it names
+  // the conversion the operator would otherwise not know happened.
+  let connectError: ConnectError;
+  if (error instanceof ConnectError) {
+    connectError = error;
+  } else {
+    logger.error("unhandled non-ConnectError at the transport boundary", {
+      procedure,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    connectError = internalError(error, INTERNAL_FALLBACK_MESSAGE);
+  }
+
+  // Arm 2: the visitor rewrite — only with a composed policy, only on
+  // the leak-prone codes.
+  if (policy === undefined || !SANITIZED_CODES.has(connectError.code)) {
+    return connectError;
+  }
+  const identity = request.contextValues.get(callerIdentityKey);
+  let eligible: boolean;
+  try {
+    eligible = policy.eligible(identity, request.method);
+  } catch (policyFault) {
+    // Fail toward sanitizing: the recoverable direction (see the
+    // contract's eligible() doc).
+    logger.error("visitor error policy eligibility check threw", {
+      procedure,
+      error:
+        policyFault instanceof Error
+          ? policyFault.message
+          : String(policyFault),
+    });
+    eligible = true;
+  }
+  if (!eligible) {
+    return connectError;
+  }
+
+  let copy: string;
+  try {
+    copy = await policy.replacementCopy(identity, request.method);
+  } catch (policyFault) {
+    logger.warn("visitor error copy resolution failed, using fallback", {
+      procedure,
+      error:
+        policyFault instanceof Error
+          ? policyFault.message
+          : String(policyFault),
+    });
+    copy = INTERNAL_FALLBACK_MESSAGE;
+  }
+
+  const ref = mintSupportRef();
+  // The correlation point (Q3): the visitor holds the ref, this line
+  // holds the original description — the log-based rendering of the
+  // Java span attribute + boundary WARN pair.
+  logger.warn("sanitized a visitor-facing error", {
+    procedure,
+    code: Code[connectError.code],
+    callerClass: identity?.callerClass ?? "(unstamped)",
+    ref,
+    error: connectError.rawMessage,
+  });
+  // A FRESH error: same code (never changed — SDK retry semantics stay
+  // honest), rewritten description + ref, and NO inherited details or
+  // metadata (the Java trailers-drop; rethrownStatusError's lesson).
+  return new ConnectError(copy + supportRefSuffix(ref), connectError.code);
+}