@st-gr/sail-proxy 0.9.3 → 0.9.4

package/bundled/gateway/services/gateway/src/plugins/pseudonymization/index.js

@@ -16,11 +16,14 @@
  *
  * Strategies: before + after + stream
  *
- * @see pseudonymization-proxy-prompt.md - Full specification
+ * @see ../pseudonymization.md - Usage, activation methods, and category configuration
+ * @see ../../../../../docs/security/pseudonymization-security-assessment.md - Security assessment
  */
+const logger_1 = require("@libs/logger");
 const replacementMap_1 = require("./replacementMap");
 const detectors_1 = require("./detectors");
 const replacer_1 = require("./replacer");
+const entityToggles_1 = require("./entityToggles");
 const unmasker_1 = require("./unmasker");
 const streamBuffer_1 = require("./streamBuffer");
 const entityCache_1 = require("./entityCache");
@@ -75,6 +78,12 @@ function extractResponseText(response) {
     if (response?.final_result?.choices?.[0]?.delta?.content) {
         return response.final_result.choices[0].delta.content;
     }
+    // Anthropic native streaming: content_block_delta with text_delta
+    if (response?.type === 'content_block_delta'
+        && response?.delta?.type === 'text_delta'
+        && typeof response.delta.text === 'string') {
+        return response.delta.text;
+    }
     // Anthropic format
     if (response?.content && Array.isArray(response.content)) {
         for (const block of response.content) {
@@ -101,6 +110,11 @@ function setResponseText(response, newText) {
     else if (response?.final_result?.choices?.[0]?.delta?.content !== undefined) {
         response.final_result.choices[0].delta.content = newText;
     }
+    else if (response?.type === 'content_block_delta'
+        && response?.delta?.type === 'text_delta'
+        && response.delta.text !== undefined) {
+        response.delta.text = newText;
+    }
     else if (response?.content && Array.isArray(response.content)) {
         for (const block of response.content) {
             if (block.type === 'text') {
@@ -135,6 +149,10 @@ const DEFAULT_MASKING_CONFIG = {
         { type: 'profile-url' },
         { type: 'profile-address' },
         { type: 'profile-username-password' },
+        { type: 'profile-nationalid' },
+        { type: 'profile-passport' },
+        { type: 'profile-driverlicense' },
+        { type: 'profile-pronouns-gender' },
         { type: 'profile-nationality' },
         { type: 'profile-ethnicity' },
         { type: 'profile-gender' },
@@ -146,6 +164,38 @@ const DEFAULT_MASKING_CONFIG = {
         { type: 'profile-location' },
     ],
 };
+// All category types the pseudonymizationPlugin understands, for toggle validation.
+const KNOWN_ENTITY_TYPES = (0, entityToggles_1.buildKnownEntityTypes)(DEFAULT_MASKING_CONFIG.entities);
+/**
+ * Resolve the DEFAULT entity set for this request by layering api_config.json
+ * toggles over DEFAULT_MASKING_CONFIG: global (api_config.pseudonymization.entities)
+ * → per-endpoint (defaultHooks[endpoint].pseudonymization.entities) → per-model
+ * (model_list_changes[model].pseudonymization.entities); later layers win.
+ * Reads dynamic config per request (hot in distributed mode; standalone requires
+ * a restart, as for all plugin config). Falls back to the code defaults on any error.
+ */
+function resolveDefaultEntities(req) {
+    try {
+        const configService = require('../../services/configService').default || require('../../services/configService');
+        const apiConfig = configService.getConfig()?.api_config;
+        if (!apiConfig)
+            return DEFAULT_MASKING_CONFIG.entities;
+        let entities = (0, entityToggles_1.applyEntityToggles)(DEFAULT_MASKING_CONFIG.entities, apiConfig.pseudonymization?.entities, KNOWN_ENTITY_TYPES);
+        const endpoint = req?.__endpoint;
+        if (endpoint) {
+            entities = (0, entityToggles_1.applyEntityToggles)(entities, apiConfig.defaultHooks?.[endpoint]?.pseudonymization?.entities, KNOWN_ENTITY_TYPES);
+        }
+        const modelName = req?.body?.model;
+        if (modelName) {
+            const substituted = configService.getSubstitutedModel('anthropic', modelName) || modelName;
+            entities = (0, entityToggles_1.applyEntityToggles)(entities, apiConfig.model_list_changes?.[substituted]?.pseudonymization?.entities, KNOWN_ENTITY_TYPES);
+        }
+        return entities;
+    }
+    catch {
+        return DEFAULT_MASKING_CONFIG.entities;
+    }
+}
 /**
  * Scan messages for triggerword, strip it, and return masking config if found
  */
@@ -197,7 +247,7 @@ function scanAndStripTriggerword(req) {
     }
     if (!found)
         return null;
-    return { ...DEFAULT_MASKING_CONFIG, method: found };
+    return { ...DEFAULT_MASKING_CONFIG, entities: resolveDefaultEntities(req), method: found };
 }
 /**
  * Check if the model has pseudonymization forced on via api_config.json.
@@ -217,7 +267,7 @@ function getModelForcedConfig(req) {
             if (modelConfig?.pseudonymization?.enabled) {
                 const method = modelConfig.pseudonymization.method || 'pseudonymization';
                 const allowBypass = modelConfig.pseudonymization.allow_user_bypass === true;
-                return { config: { ...DEFAULT_MASKING_CONFIG, method }, allowBypass, source: 'model' };
+                return { config: { ...DEFAULT_MASKING_CONFIG, entities: resolveDefaultEntities(req), method }, allowBypass, source: 'model' };
             }
         }
         // Per-endpoint force flag (defaultHooks[endpoint].pseudonymization.enabled)
@@ -227,7 +277,7 @@ function getModelForcedConfig(req) {
             if (endpointConfig?.pseudonymization?.enabled) {
                 const method = endpointConfig.pseudonymization.method || 'pseudonymization';
                 const allowBypass = endpointConfig.pseudonymization.allow_user_bypass === true;
-                return { config: { ...DEFAULT_MASKING_CONFIG, method }, allowBypass, source: 'endpoint' };
+                return { config: { ...DEFAULT_MASKING_CONFIG, entities: resolveDefaultEntities(req), method }, allowBypass, source: 'endpoint' };
             }
         }
         return null;
@@ -299,6 +349,27 @@ async function beforeHandler({ req, res, utils }) {
         const allEntities = [];
         const maskedInputs = [];
         const messages = req.body.messages || [];
+        // Residue guard: the incoming request may contain literal MASKED_* tokens from
+        // earlier turns/sessions. With content-derived (hash) placeholders these resolve
+        // on their own whenever the underlying value is present in this request (the same
+        // value re-mints the identical token). Legacy NUMERIC residue (from the old
+        // counter scheme) can never be re-minted; reserve those numbers so anonymization
+        // counters cannot collide with them, and log the residue for visibility.
+        try {
+            const rawBody = JSON.stringify(req.body);
+            const residue = new Set(rawBody.match(/MASKED_[A-Z_]+_[0-9a-f]+|(?:https?:\/\/)?masked-url-\d+\.invalid/g) || []);
+            if (residue.size > 0) {
+                for (const token of residue) {
+                    const m = token.match(/^(MASKED_[A-Z_]+)_(\d+)$/);
+                    // Cap the reservation so a digits-only hash id cannot blow up the counters.
+                    if (m && m[2].length <= 6)
+                        map.reserveMinCount(m[1], parseInt(m[2], 10));
+                }
+                const sample = Array.from(residue).slice(0, 10).join(', ');
+                logger.info(`Request contains ${residue.size} masked token(s) carried in from earlier turns (hash-stable tokens resolve automatically when their value is present): ${sample}${residue.size > 10 ? ', …' : ''}`);
+            }
+        }
+        catch { /* non-fatal: residue guard is best-effort */ }
         // Process system messages (Anthropic format)
         if (Array.isArray(req.body.system)) {
             for (let i = 0; i < req.body.system.length; i++) {
@@ -344,6 +415,45 @@ async function beforeHandler({ req, res, utils }) {
                 }
             }
         }
+        // Value-consistency propagation: mask every remaining exact occurrence of each
+        // detected value across the request, including nodes where no detector fired
+        // (e.g. the same secret riding through in an `Authorization: Bearer` header).
+        // Prevents the model from seeing the raw value alongside its mask.
+        const propagated = (0, replacer_1.propagateMaskedValues)(req.body, map);
+        // Tell the model to treat placeholder tokens as opaque and copy them verbatim.
+        // A garbled id cannot be unmasked (the value is unrecoverable), so copy fidelity
+        // is part of the design; observed in practice: models occasionally rewrite ids
+        // when reproducing them in generated files unless explicitly instructed not to.
+        if (maskingConfig.method === 'pseudonymization' && map.size > 0) {
+            const copyNote = 'Some values in this conversation are pseudonymized as placeholder tokens of the form '
+                + 'MASKED_<TYPE>_<id>. Treat each token as an opaque identifier: when you refer to a masked value, '
+                + 'copy its token EXACTLY, character for character. Never invent, alter, shorten, or merge token ids. '
+                + 'Only use MASKED_* tokens that appear verbatim in this conversation — NEVER invent, guess, or '
+                + 'construct a new MASKED_* token or id under any circumstances; a token you did not see in the input '
+                + 'is meaningless and will break the user\'s workflow. If a value you need appears unmasked in the '
+                + 'conversation, use that unmasked value as-is; do not create a token for it. '
+                + 'Masked URLs appear as hosts like https://masked-url-<id>.invalid — you MAY append paths and query '
+                + 'parameters to such a host to form new URLs, but never invent a masked-url host that is not present '
+                + 'in the conversation.';
+            if (Array.isArray(req.body.system)) {
+                req.body.system.push({ type: 'text', text: copyNote });
+            }
+            else if (typeof req.body.system === 'string') {
+                req.body.system = `${req.body.system}\n\n${copyNote}`;
+            }
+            else if (req.body.system === undefined || req.body.system === null) {
+                req.body.system = copyNote;
+            }
+        }
+        // Capture the masking_info debug opt-in before the config is stripped. The
+        // full masked-input diagnostic is off by default for pseudonymization (it
+        // bloats every client response); attach it only when explicitly requested via
+        // `masking.debug: true` or the out-of-band `x-sail-proxy-masking-debug: on`
+        // header (same channel pattern as the bypass header).
+        const maskingDebug = req.body?.masking?.debug === true
+            || (typeof req.headers?.['x-sail-proxy-masking-debug'] === 'string'
+                && req.headers['x-sail-proxy-masking-debug'].toLowerCase() === 'on');
+        req.__pseudonymizationDebug = maskingDebug;
         // Remove the masking config from the body before forwarding upstream
         delete req.body.masking;
         // Store state on request for after/stream handlers
@@ -362,7 +472,7 @@ async function beforeHandler({ req, res, utils }) {
         if (maskingConfig.method === 'pseudonymization' && res) {
             installSseUnmaskInterceptor(req, res, map);
         }
-        logger.info(`Masked ${allEntities.length} entities (${map.size} unique) across ${messages.length} messages`);
+        logger.info(`Masked ${allEntities.length} entities (${map.size} unique) across ${messages.length} messages; propagated ${propagated} additional occurrence(s)`);
         // Async: store detected entities in learned cache (non-blocking)
         if (allEntities.length > 0) {
             const toCache = allEntities
@@ -417,7 +527,11 @@ async function afterHandler({ req, upstreamResponse, utils }) {
             logger.debug(`Unmasked response text (${responseText.length} → ${unmasked.length} chars)`);
         }
         unmaskToolBlocks(upstreamResponse, map);
-        return attachMaskingInfo(upstreamResponse, state);
+        // Residue audit (the non-streaming path had none — this is the incident path).
+        // Scan the fully-unmasked client-facing body for surviving MASKED_* tokens and
+        // log per-token detail plus one aggregated, grep-stable counter line.
+        auditResponseResidue(upstreamResponse, map, req?.debugRequestId || 'unknown', logger);
+        return maybeAttachMaskingInfo(upstreamResponse, state, req);
     }
     catch (error) {
         logger.error(`Error in pseudonymization after handler: ${error.message}`, { stack: error.stack });
@@ -430,119 +544,292 @@ async function afterHandler({ req, upstreamResponse, utils }) {
  * directly without going through the after-plugin chain per chunk (e.g., AWS Bedrock
  * native streaming via BedrockStreamParser).
  *
- * Each event is an `event: <name>\ndata: <json>\n\n` block written via a single res.write.
- * We parse, mutate input_json_delta.partial_json and tool_calls.function.arguments deltas
- * through per-block StreamUnmaskBuffer instances, and re-serialize.
+ * The patched write re-frames arbitrary write boundaries into complete SSE blocks
+ * (`[event: <name>\n]data: <json>\n\n`), holding a partial tail across writes, so it
+ * also covers pipelines that pipe multiple or partial events per write (e.g. the
+ * converse-stream direct passthrough). Assistant text (text_delta), tool input
+ * (input_json_delta), and OpenAI tool_calls argument deltas are unmasked through
+ * per-content-block StreamUnmaskBuffer instances; retained fragments are flushed on
+ * content_block_stop / message_stop / finish_reason / res.end.
+ *
+ * Diagnostics: when a completed block still contains MASKED_* placeholders, an error
+ * (token was in the map — a genuine unmask miss) or warning (token unknown — residue
+ * leaked into the conversation by an earlier session) is logged, so leaks are never
+ * silent again.
  */
 function installSseUnmaskInterceptor(req, res, map) {
     if (res.__pseudoSseInterceptorInstalled)
         return;
+    if (typeof res.write !== 'function' || typeof res.end !== 'function')
+        return;
     res.__pseudoSseInterceptorInstalled = true;
-    const toolBuffers = new Map();
+    // Patch res.json so NON-streaming responses that bypass res.write are still unmasked.
+    // The awsBedrockResponseCache plugin serves non-streaming cache hits via res.status().json()
+    // and returns { stop: true }, which short-circuits the after-handler AND never touches
+    // res.write — so without this, cached placeholders reach the client masked. The cache stores
+    // the masked upstream response (pseudonymization unmasks at the wire, after caching); for an
+    // identical request the placeholder numbers are deterministic, so this request's map resolves
+    // them. Tokens not in the map (residue) are left untouched by unmaskText.
+    const logger = (0, logger_1.getDefaultLogger)();
+    if (typeof res.json === 'function') {
+        const originalJson = res.json.bind(res);
+        res.json = function patchedJson(body) {
+            try {
+                if (body && typeof body === 'object' && map.reverse.size > 0) {
+                    const serialized = JSON.stringify(body);
+                    if (serialized.includes('MASKED_')) {
+                        const unmasked = (0, unmasker_1.unmaskText)(serialized, map);
+                        if (unmasked !== serialized) {
+                            body = JSON.parse(unmasked);
+                            logger.debug('Pseudonymization', `Unmasked non-streaming JSON response body (requestId=${req?.debugRequestId || 'unknown'})`);
+                        }
+                    }
+                }
+            }
+            catch { /* fall through with original body */ }
+            return originalJson(body);
+        };
+    }
+    const requestId = req?.debugRequestId || 'unknown';
+    const buffers = new Map();
     const getBuf = (key) => {
-        let b = toolBuffers.get(key);
+        let b = buffers.get(key);
         if (!b) {
             b = new streamBuffer_1.StreamUnmaskBuffer(map);
-            toolBuffers.set(key, b);
+            buffers.set(key, b);
         }
         return b;
     };
-    const originalWrite = res.write.bind(res);
-    // Patch res.write. The Express Response.write signature has overloads; we accept any.
-    res.write = function patchedWrite(chunk, ...args) {
-        try {
-            const str = typeof chunk === 'string' ? chunk : (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : null);
-            if (!str)
-                return originalWrite(chunk, ...args);
-            // Two SSE formats are emitted by this gateway:
-            //   1) "event: <name>\ndata: <json>\n\n" (writeEventStream)
-            //   2) "data: <json>\n\n" (writeChunk — used by BedrockStreamParser)
-            let eventName = null;
-            let jsonStr = null;
-            const m1 = str.match(/^event: ([^\n]+)\ndata: (.+)\n\n$/s);
-            if (m1) {
-                eventName = m1[1];
-                jsonStr = m1[2];
+    // Per-block emitted content, used only for the leak audit below.
+    const emitted = new Map();
+    const track = (key, s) => {
+        if (s)
+            emitted.set(key, (emitted.get(key) || '') + s);
+    };
+    const auditBlock = (key) => {
+        const content = emitted.get(key);
+        emitted.delete(key);
+        if (!content)
+            return;
+        for (const token of new Set(content.match(/MASKED_[A-Z_]+_[0-9a-f]+|(?:https?:\/\/)?masked-url-\d+\.invalid/g) || [])) {
+            if (map.reverse.has(token)) {
+                logger.error('Pseudonymization', `Unmask miss on streaming block ${key}: ${token} was in the replacement map but reached the client masked (requestId=${requestId})`);
             }
             else {
-                const m2 = str.match(/^data: (.+)\n\n$/s);
-                if (m2) {
-                    jsonStr = m2[1];
-                }
+                logger.warn('Pseudonymization', `Unresolvable masked residue in streaming block ${key}: ${token} is not in this request's map — its value is absent from this request (leaked by an earlier session) (requestId=${requestId})`);
             }
-            if (!jsonStr)
-                return originalWrite(chunk, ...args);
-            let event;
-            try {
-                event = JSON.parse(jsonStr);
+        }
+    };
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    // Partial SSE block carried across write() calls (re-framing buffer).
+    let pending = '';
+    // Process one complete SSE block; returns the (possibly rewritten) block.
+    const processBlock = (block) => {
+        // Two SSE formats are emitted by this gateway:
+        //   1) "event: <name>\ndata: <json>\n\n" (writeEventStream)
+        //   2) "data: <json>\n\n" (writeChunk — used by BedrockStreamParser)
+        let eventName = null;
+        let jsonStr = null;
+        const m1 = block.match(/^event: ([^\n]+)\ndata: (.+)\n\n$/s);
+        if (m1) {
+            eventName = m1[1];
+            jsonStr = m1[2];
+        }
+        else {
+            const m2 = block.match(/^data: (.+)\n\n$/s);
+            if (m2) {
+                jsonStr = m2[1];
             }
-            catch {
-                return originalWrite(chunk, ...args);
+        }
+        if (!jsonStr)
+            return block;
+        let event;
+        try {
+            event = JSON.parse(jsonStr);
+        }
+        catch {
+            return block;
+        }
+        let modified = false;
+        let syntheticPrefix = '';
+        // Serialize a synthetic delta in the same format as the surrounding stream,
+        // emitted BEFORE the current event for correct ordering.
+        const synth = (idx, delta) => {
+            const ev = { type: 'content_block_delta', index: idx, delta };
+            const prefix = eventName ? 'event: content_block_delta\n' : '';
+            return `${prefix}data: ${JSON.stringify(ev)}\n\n`;
+        };
+        // Anthropic content_block_delta with text_delta (assistant prose)
+        if (event.type === 'content_block_delta'
+            && event.delta?.type === 'text_delta'
+            && typeof event.delta.text === 'string') {
+            const idx = event.index ?? 0;
+            const buf = getBuf(`text:${idx}`);
+            event.delta.text = buf.append(event.delta.text);
+            track(`text:${idx}`, event.delta.text);
+            modified = true;
+        }
+        // Anthropic content_block_delta with input_json_delta (tool call input)
+        if (event.type === 'content_block_delta'
+            && event.delta?.type === 'input_json_delta'
+            && typeof event.delta.partial_json === 'string') {
+            const idx = event.index ?? 0;
+            const buf = getBuf(`tool_use:${idx}`);
+            event.delta.partial_json = buf.append(event.delta.partial_json);
+            track(`tool_use:${idx}`, event.delta.partial_json);
+            modified = true;
+        }
+        // Anthropic content_block_stop — flush retained suffixes of this block's buffers
+        // as synthetic deltas emitted before the stop, then audit the block for leaks.
+        if (event.type === 'content_block_stop') {
+            const idx = event.index ?? 0;
+            const textBuf = buffers.get(`text:${idx}`);
+            if (textBuf) {
+                const remainder = textBuf.flush();
+                if (remainder) {
+                    syntheticPrefix += synth(idx, { type: 'text_delta', text: remainder });
+                    track(`text:${idx}`, remainder);
+                }
+                buffers.delete(`text:${idx}`);
             }
-            let modified = false;
-            const extraWrites = [];
-            // Anthropic content_block_delta with input_json_delta
-            if (event.type === 'content_block_delta'
-                && event.delta?.type === 'input_json_delta'
-                && typeof event.delta.partial_json === 'string') {
-                const idx = event.index ?? 0;
-                const buf = getBuf(`tool_use:${idx}`);
-                event.delta.partial_json = buf.append(event.delta.partial_json);
-                modified = true;
-            }
-            // Anthropic content_block_stop — flush any retained suffix as a synthetic delta
-            // emitted before the stop.
-            if (event.type === 'content_block_stop') {
-                const idx = event.index ?? 0;
-                const buf = toolBuffers.get(`tool_use:${idx}`);
-                if (buf) {
-                    const remainder = buf.flush();
-                    if (remainder) {
-                        const synthetic = {
-                            type: 'content_block_delta',
-                            index: idx,
-                            delta: { type: 'input_json_delta', partial_json: remainder },
-                        };
-                        // Match the source format (event: prefix only when present in the original write)
-                        const prefix = eventName ? `event: content_block_delta\n` : '';
-                        extraWrites.push(`${prefix}data: ${JSON.stringify(synthetic)}\n\n`);
-                    }
-                    toolBuffers.delete(`tool_use:${idx}`);
+            const toolBuf = buffers.get(`tool_use:${idx}`);
+            if (toolBuf) {
+                const remainder = toolBuf.flush();
+                if (remainder) {
+                    syntheticPrefix += synth(idx, { type: 'input_json_delta', partial_json: remainder });
+                    track(`tool_use:${idx}`, remainder);
                 }
+                buffers.delete(`tool_use:${idx}`);
             }
-            // OpenAI streaming via SSE (less common with this controller, but handle just in case)
-            if (Array.isArray(event?.choices?.[0]?.delta?.tool_calls)) {
-                const finishReason = event?.choices?.[0]?.finish_reason;
-                for (const call of event.choices[0].delta.tool_calls) {
-                    if (typeof call?.function?.arguments === 'string') {
-                        const idx = call.index ?? 0;
-                        const buf = getBuf(`oai_tool_call:${idx}`);
-                        if (finishReason) {
-                            call.function.arguments = buf.append(call.function.arguments) + buf.flush();
-                            toolBuffers.delete(`oai_tool_call:${idx}`);
-                        }
-                        else {
-                            call.function.arguments = buf.append(call.function.arguments);
-                        }
-                        modified = true;
+            auditBlock(`text:${idx}`);
+            auditBlock(`tool_use:${idx}`);
+        }
+        // Anthropic message_stop — safety flush of ALL remaining buffers (Anthropic streams
+        // have no choices[].finish_reason, so anything not flushed by a stop lands here).
+        if (event.type === 'message_stop') {
+            for (const [key, buf] of Array.from(buffers.entries())) {
+                const remainder = buf.flush();
+                if (remainder) {
+                    const idx = parseInt(key.split(':')[1], 10) || 0;
+                    const deltaType = key.startsWith('text:') ? 'text_delta' : 'input_json_delta';
+                    syntheticPrefix += synth(idx, deltaType === 'text_delta'
+                        ? { type: 'text_delta', text: remainder }
+                        : { type: 'input_json_delta', partial_json: remainder });
+                    track(key, remainder);
+                }
+                buffers.delete(key);
+            }
+            for (const key of Array.from(emitted.keys()))
+                auditBlock(key);
+        }
+        // OpenAI streaming via SSE (less common with this controller, but handle just in case)
+        if (Array.isArray(event?.choices?.[0]?.delta?.tool_calls)) {
+            const finishReason = event?.choices?.[0]?.finish_reason;
+            for (const call of event.choices[0].delta.tool_calls) {
+                if (typeof call?.function?.arguments === 'string') {
+                    const idx = call.index ?? 0;
+                    const key = `oai_tool_call:${idx}`;
+                    const buf = getBuf(key);
+                    if (finishReason) {
+                        call.function.arguments = buf.append(call.function.arguments) + buf.flush();
+                        track(key, call.function.arguments);
+                        buffers.delete(key);
+                        auditBlock(key);
+                    }
+                    else {
+                        call.function.arguments = buf.append(call.function.arguments);
+                        track(key, call.function.arguments);
                     }
+                    modified = true;
                 }
             }
-            // Emit any synthetic events first (they come before the original event for correct ordering)
-            for (const extra of extraWrites)
-                originalWrite(extra);
-            if (modified) {
-                const newStr = eventName
-                    ? `event: ${eventName}\ndata: ${JSON.stringify(event)}\n\n`
-                    : `data: ${JSON.stringify(event)}\n\n`;
-                return originalWrite(newStr, ...args);
+        }
+        if (modified) {
+            const newStr = eventName
+                ? `event: ${eventName}\ndata: ${JSON.stringify(event)}\n\n`
+                : `data: ${JSON.stringify(event)}\n\n`;
+            return syntheticPrefix + newStr;
+        }
+        return syntheticPrefix + block;
+    };
+    // Final safety net: unmask any COMPLETE placeholder still present in outgoing bytes.
+    // The structured per-block handling above only unmasks events it recognizes as
+    // content_block_delta text_delta / input_json_delta; text emitted through other
+    // shapes (notably the BedrockStreamParser raw-text fallback, which writes bare
+    // `data: <text>` on a parse miss) would otherwise reach the client masked. This is
+    // idempotent on already-unmasked output (no reverse-map keys remain to match) and
+    // only touches whole tokens, so it never disturbs the buffer's partial-retention.
+    const safetyNetUnmask = (s) => {
+        if (map.reverse.size === 0)
+            return s;
+        if (!s.includes('MASKED_') && !s.includes('masked-url-'))
+            return s;
+        return (0, unmasker_1.unmaskText)(s, map);
+    };
+    // Split accumulated data into complete SSE blocks, keep the partial tail pending.
+    const processIncoming = (str) => {
+        pending += str;
+        let out = '';
+        let sep;
+        while ((sep = pending.indexOf('\n\n')) !== -1) {
+            const block = pending.slice(0, sep + 2);
+            pending = pending.slice(sep + 2);
+            out += processBlock(block);
+        }
+        return safetyNetUnmask(out);
+    };
+    // Patch res.write. The Express Response.write signature has overloads; we accept any.
+    res.write = function patchedWrite(chunk, ...args) {
+        try {
+            const str = typeof chunk === 'string' ? chunk : (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : null);
+            if (str === null)
+                return originalWrite(chunk, ...args);
+            const out = processIncoming(str);
+            // Strip a callback argument if present — it must fire even when we buffer.
+            const cb = typeof args[args.length - 1] === 'function' ? args.pop() : undefined;
+            if (out) {
+                const result = originalWrite(out, ...args);
+                if (cb)
+                    cb();
+                return result;
             }
-            return originalWrite(chunk, ...args);
+            // Entire chunk retained as a partial block — report success, emit on next write/end.
+            if (cb)
+                cb();
+            return true;
         }
         catch {
             return originalWrite(chunk, ...args);
         }
     };
+    // Patch res.end so a trailing partial block (and any retained buffer content) is not lost.
+    res.end = function patchedEnd(chunk, ...args) {
+        try {
+            if (chunk && (typeof chunk === 'string' || Buffer.isBuffer(chunk))) {
+                const out = processIncoming(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+                if (out)
+                    originalWrite(out);
+                chunk = undefined;
+            }
+            if (pending) {
+                // Incomplete final block — pass through (best effort), still safety-net unmasked.
+                originalWrite(safetyNetUnmask(pending));
+                pending = '';
+            }
+            // Streams that ended without content_block_stop/message_stop: audit what remains.
+            for (const [key, buf] of Array.from(buffers.entries())) {
+                const remainder = buf.flush();
+                if (remainder)
+                    track(key, remainder);
+                buffers.delete(key);
+            }
+            for (const key of Array.from(emitted.keys()))
+                auditBlock(key);
+        }
+        catch { /* fall through to originalEnd */ }
+        return chunk !== undefined ? originalEnd(chunk, ...args) : originalEnd(...args);
+    };
 }
 /**
  * Walk a non-streaming response and unmask placeholders inside tool_use / tool_calls blocks.
@@ -638,15 +925,30 @@ function handleStreamingChunk(req, chunk, map, state, logger) {
         const idx = chunk.index ?? 0;
         const key = `tool_use:${idx}`;
         const buf = toolBuffers.get(key);
+        let toolFlushed = false;
         if (buf) {
             const remainder = buf.flush();
             if (remainder) {
                 if (!chunk.delta)
                     chunk.delta = { type: 'input_json_delta', partial_json: '' };
                 chunk.delta.partial_json = (chunk.delta.partial_json || '') + remainder;
+                toolFlushed = true;
             }
             toolBuffers.delete(key);
         }
+        // Text blocks: Anthropic streams never set choices[].finish_reason, so the shared
+        // text buffer's retained tail would otherwise be stranded. Flush it here, unless
+        // this stop already carries a tool remainder (don't mix delta types).
+        if (!toolFlushed) {
+            const textRemainder = buffer.flush();
+            if (textRemainder) {
+                if (!chunk.delta)
+                    chunk.delta = { type: 'text_delta', text: '' };
+                if (chunk.delta.type === 'text_delta') {
+                    chunk.delta.text = (chunk.delta.text || '') + textRemainder;
+                }
+            }
+        }
     }
     // ─── OpenAI streaming: choices[0].delta.tool_calls[].function.arguments ─
     const oaiToolCalls = chunk?.choices?.[0]?.delta?.tool_calls;
@@ -709,6 +1011,53 @@ function attachMaskingInfo(response, state) {
     }
     return response;
 }
+/**
+ * Attach masking_info, but for pseudonymization only when the request opted into the
+ * debug diagnostic (`masking.debug: true` or `x-sail-proxy-masking-debug: on`).
+ * Anonymization keeps its documented behavior of always attaching it.
+ */
+function maybeAttachMaskingInfo(response, state, req) {
+    if (state.config.method === 'pseudonymization' && !req?.__pseudonymizationDebug) {
+        return response;
+    }
+    return attachMaskingInfo(response, state);
+}
+// Placeholder-residue pattern (hash-hex ids and masked-url hosts), shared by the
+// streaming and non-streaming leak audits.
+const RESIDUE_REGEX = /MASKED_[A-Z_]+_[0-9a-f]+|(?:https?:\/\/)?masked-url-\d+\.invalid/g;
+/**
+ * Scan a fully-unmasked non-streaming response for surviving MASKED_* tokens.
+ * Logs per-token detail (ERROR if the token was in the map — a genuine unmask miss;
+ * WARN if it is unknown residue from an earlier session) plus one aggregated,
+ * grep-stable counter line so leak rates can be monitored.
+ */
+function auditResponseResidue(response, map, requestId, logger) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(response) || '';
+    }
+    catch {
+        return;
+    }
+    if (!serialized.includes('MASKED_') && !serialized.includes('masked-url-'))
+        return;
+    const tokens = new Set(serialized.match(RESIDUE_REGEX) || []);
+    if (tokens.size === 0)
+        return;
+    const byType = {};
+    for (const token of tokens) {
+        const type = token.match(/^(MASKED_[A-Z_]+)_/)?.[1] || 'MASKED_URL';
+        byType[type] = (byType[type] || 0) + 1;
+        if (map.reverse.has(token)) {
+            logger.error('Pseudonymization', `Unmask miss on response: ${token} was in the replacement map but reached the client masked (requestId=${requestId})`);
+        }
+        else {
+            logger.warn('Pseudonymization', `Unresolvable masked residue in response: ${token} is not in this request's map — its value is absent from this request (leaked by an earlier session) (requestId=${requestId})`);
+        }
+    }
+    const byTypeStr = Object.entries(byType).map(([t, n]) => `${t}:${n}`).join(',');
+    logger.warn('Pseudonymization', `pseudonymization_residue_unresolved_total=${tokens.size} by_type=${byTypeStr} requestId=${requestId}`);
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // STREAM HANDLER: Raw buffer processing (operates before SSE parsing)
 // ─────────────────────────────────────────────────────────────────────────────