@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/security/ssrf/pinned-outbound-fetch.backend.utils.js

@@ -0,0 +1,258 @@
+/**
+ * An outbound HTTP request that CONNECTS to the address it VALIDATED — the half
+ * {@link classifyOutboundTargetUrl} and {@link resolvesOnlyToPublicAddresses} structurally cannot do.
+ *
+ * ## The hole this closes, and why the classifier alone could never close it
+ *
+ * Every guard in the sibling module answers a question and then hands the answer to somebody else,
+ * who makes a SEPARATE connection. That is a check-then-connect, and the guard's own header says so:
+ *
+ *   "⚠️ Residual, stated rather than hidden: this is a check-then-connect, so a DNS entry that
+ *    changes between the two (rebinding) is not covered. Closing it needs the request pinned to the
+ *    validated address, which Node's `fetch` does not expose."
+ *
+ * So a name whose A record answers `93.184.216.34` to the validating resolver and `169.254.169.254`
+ * to the connecting one passes every check in this directory and still reaches cloud instance
+ * metadata. The window is small and entirely attacker-controlled: the attacker owns the zone, so the
+ * attacker chooses the TTL and therefore the width of the window.
+ *
+ * The classifier cannot fix this at any level of effort, because the defect is not in the answer —
+ * the answer was correct when it was given. The defect is that the answer is thrown away before the
+ * socket is opened.
+ *
+ * ## The mechanism, chosen after measuring the alternatives
+ *
+ * `net.Socket.connect` accepts a **`lookup` hook**, and `http.request` / `https.request` pass it
+ * straight through. Node calls it at CONNECT time, and the address it returns is the address the
+ * socket is opened to — there is no second resolution and therefore no window. Classifying inside
+ * the hook makes validation and connection the SAME event rather than two events with a gap.
+ *
+ * Measured on this Node (2026-09-08) rather than assumed, because each of these decided the design:
+ *
+ * | probe | result |
+ * |---|---|
+ * | is `lookup` called for a hostname? | yes, as `lookup(host, { hints, all: true }, cb)` — note `all` |
+ * | is `lookup` called for an IP LITERAL? | **no** — `net` short-circuits, so literals need the shape check |
+ * | does an error raised inside the hook reach the caller? | yes, same error object, `message` and `code` intact |
+ * | does TLS still verify against the NAME while connected to the pinned IP? | **yes** — a cert for `pinned.test` validated over a socket to `127.0.0.1` |
+ *
+ * That last row is what makes the whole approach viable. Pinning by rewriting the URL's host to the
+ * validated IP — the obvious alternative — breaks SNI and certificate verification, i.e. it trades an
+ * SSRF hole for a transport-security hole. Pinning through `lookup` keeps the hostname everywhere it
+ * is a security input (SNI, certificate subject, the `Host` header) and replaces it only where it is
+ * a routing input.
+ *
+ * ## Why this is not `fetch` with a dispatcher
+ *
+ * Node's `fetch` exposes no `lookup` hook. The undici route (`new Agent({ connect: { lookup } })`)
+ * would work, but undici is not a declared dependency of this package — it is present in the store
+ * only transitively — so taking it would add a second HTTP stack beside the one Node already embeds,
+ * for a hook `node:https` exposes natively. Rejected on that basis, not on preference.
+ *
+ * `node:https` also gives one property for free that `fetch` needs an option for: **it does not
+ * follow redirects at all.** A 302 arrives as a 302 the caller can see. `redirect: 'error'` is
+ * therefore not something this module has to remember to pass — following a redirect to a target the
+ * guard never saw is unrepresentable here.
+ *
+ * ## What this still does NOT do
+ *
+ * It does not defend a target that is public at connect time and hostile at the application layer,
+ * and it does not stop a public host from being an open proxy into somebody else's private network.
+ * Those are different problems with different answers. What it removes is the specific gap between
+ * "we checked this name" and "we opened this socket".
+ *
+ * assurance-control: WILDO.NETWORK.OUTBOUND_TARGET_CONTROL — a server-side request initiated from
+ * application- or tenant-authored configuration reaches only an address the deployment admits
+ */
+import { lookup as dnsLookup } from 'node:dns';
+import { request as httpRequest, Agent as HttpAgent } from 'node:http';
+import { request as httpsRequest, Agent as HttpsAgent } from 'node:https';
+import { Readable } from 'node:stream';
+import { OutboundTargetRejection, classifyOutboundTargetUrl, isPrivateOrReservedIpAddress, } from '../../security/ssrf/outbound-target-guard.backend.utils.js';
+/**
+ * Raised when the target was refused. Carries the closed-vocabulary reason so a caller can map it
+ * onto its OWN rejection vocabulary rather than pattern-matching a message.
+ *
+ * `refusedAddress` is present only for a connect-time refusal — it is the address the resolver
+ * returned at the moment of connection, which is the evidence that a rebinding attempt happened
+ * rather than a merely mis-authored URL.
+ */
+export class OutboundTargetRefusedError extends Error {
+    rejection;
+    refusedAddress;
+    /**
+     * A stable `code` alongside the class, because the error crosses `net`'s internals on its way out
+     * of the `lookup` hook. The class identity survives on this Node (measured), but a `code` is what
+     * every other error in that path carries and it costs nothing to be robust to a future wrap.
+     */
+    code = 'WILDO_OUTBOUND_TARGET_REFUSED';
+    constructor(rejection, refusedAddress) {
+        super(`Outbound target refused: ${rejection}${refusedAddress ? ` (${refusedAddress})` : ''}`);
+        this.rejection = rejection;
+        this.refusedAddress = refusedAddress;
+        this.name = 'OutboundTargetRefusedError';
+    }
+}
+/**
+ * Connections are NOT pooled, deliberately.
+ *
+ * Two reasons, in order of weight. First, a pooled socket skips the `lookup` hook on reuse, so the
+ * connect-time classification would run on the first request to a host and not on later ones — the
+ * guard would hold or not hold depending on pool state, which is the least auditable property a
+ * security control can have. (Reuse would in fact be SAFE, because a pooled socket is already
+ * connected to an address this module validated — but "safe because of a subtlety in another
+ * module's cache" is not a property to rest a control on.) Second, these targets are strangers:
+ * pooling keeps an idle socket open per tenant-authored host, which is an unbounded resource keyed
+ * on attacker-supplied strings.
+ *
+ * The cost is one TCP+TLS handshake per request, on a path that runs at webhook cadence rather than
+ * per user request.
+ */
+const PINNED_HTTP_AGENT = new HttpAgent({ keepAlive: false });
+const PINNED_HTTPS_AGENT = new HttpsAgent({ keepAlive: false });
+/**
+ * Classify the URL's SHAPE before anything leaves the process.
+ *
+ * This is not redundant with the connection hook, and the reason is measured: `net` short-circuits
+ * DNS for an IP LITERAL, so `https://169.254.169.254/latest/meta-data` never calls `lookup` and the
+ * hook would never see it. The shape check is the ONLY thing standing in front of a literal target.
+ */
+function classifyShape(rawUrl, init) {
+    const rejection = classifyOutboundTargetUrl(rawUrl, { admittedProtocols: init.admittedProtocols });
+    if (rejection === undefined)
+        return undefined;
+    if (init.admitPrivateAddresses
+        && (rejection === OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS
+            || rejection === OutboundTargetRejection.RESERVED_SPECIAL_USE_HOSTNAME)) {
+        // The operator declared this deployment reaches internal collectors. The scheme and
+        // credentials-in-URL refusals are NOT part of that declaration and fall through unchanged.
+        return undefined;
+    }
+    return rejection;
+}
+const defaultResolver = (hostname) => new Promise((resolve, reject) => {
+    dnsLookup(hostname, { all: true }, (error, addresses) => (error ? reject(error) : resolve(addresses)));
+});
+/**
+ * Make the request, connecting only to an address classified at the moment of connection.
+ *
+ * Returns a real {@link Response} built over the incoming message, so callers keep `ok`, `status`,
+ * `headers.get()`, `body.getReader()` and `text()` — every surface the `fetch` this replaces gave
+ * them. It is a genuine `Response`, not a look-alike: streaming size enforcement (CIMD reads the body
+ * with a running byte counter and cancels the reader) works unchanged.
+ *
+ * Throws {@link OutboundTargetRefusedError} for a refusal, and whatever `node:http` throws for a
+ * transport failure — callers already distinguish those, and conflating them would turn "your
+ * collector is down" into "your collector is an SSRF attempt".
+ */
+export async function pinnedOutboundFetch(rawUrl, init) {
+    const shapeRejection = classifyShape(rawUrl, init);
+    if (shapeRejection !== undefined)
+        throw new OutboundTargetRefusedError(shapeRejection);
+    const url = new URL(rawUrl);
+    const resolve = init.resolveAddresses ?? defaultResolver;
+    /**
+     * The refusal is recorded here as well as thrown, because the throw happens INSIDE a `net`
+     * callback. The error object does survive that path on this Node — measured — but a caught error
+     * on the outside is only usefully classified if we can answer "was it ours?" without depending on
+     * that. The box answers it from our own frame.
+     */
+    let connectRefusal;
+    const requestFn = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const agent = url.protocol === 'https:' ? PINNED_HTTPS_AGENT : PINNED_HTTP_AGENT;
+    const body = init.body;
+    const headers = { ...init.headers };
+    if (body !== undefined)
+        headers['content-length'] = String(Buffer.byteLength(body, 'utf8'));
+    try {
+        const response = await new Promise((resolveResponse, rejectResponse) => {
+            const request = requestFn({
+                protocol: url.protocol,
+                hostname: url.hostname.replace(/^\[|\]$/g, ''), // an IPv6 literal arrives bracketed from `URL`
+                port: url.port || undefined,
+                path: `${url.pathname}${url.search}`,
+                method: init.method ?? 'GET',
+                headers,
+                agent,
+                signal: init.signal,
+                /**
+                 * THE PIN. Every address the resolver returns is classified here, and the connection is
+                 * made to one of the addresses that passed — the same values, in the same event.
+                 *
+                 * ALL answers are checked rather than the one we hand back, because a hostile resolver can
+                 * return one public and one private address and rely on the client picking the other. That
+                 * is the same reasoning `resolvesOnlyToPublicAddresses` states; keeping it here means the
+                 * property does not depend on which resolver the caller pre-checked with.
+                 *
+                 * An empty answer is a refusal rather than a fall-through: the resolver succeeded and told
+                 * us nothing usable, which is not evidence the name is safe.
+                 */
+                lookup: ((hostname, options, callback) => {
+                    /**
+                     * `callback` is typed as requiring an address even on the error path, so every refusal
+                     * hands back an empty list beside the error. Node's `lookupAndConnect` tests the error
+                     * FIRST and destroys the socket, so the list is never read — this is a type obligation,
+                     * not a fallback the connection could take.
+                     */
+                    const refuse = (refusal) => {
+                        connectRefusal = refusal;
+                        callback(refusal, []);
+                    };
+                    resolve(hostname).then((resolved) => {
+                        const addresses = resolved.map((entry) => ({ address: entry.address, family: entry.family }));
+                        if (addresses.length === 0) {
+                            refuse(new OutboundTargetRefusedError(OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS));
+                            return;
+                        }
+                        if (!init.admitPrivateAddresses) {
+                            const refused = addresses.find((entry) => isPrivateOrReservedIpAddress(entry.address));
+                            if (refused) {
+                                refuse(new OutboundTargetRefusedError(OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS, refused.address));
+                                return;
+                            }
+                        }
+                        // `all` is what Node passes today; the single-address form is honoured so a future
+                        // Node calling the hook the other way does not silently reach the `Invalid IP
+                        // address: undefined` failure that the first draft of this hook produced.
+                        if (options.all)
+                            callback(null, addresses);
+                        else
+                            callback(null, addresses[0].address, addresses[0].family);
+                    }, (error) => callback(error, []));
+                }),
+            }, (incoming) => {
+                const responseHeaders = new Headers();
+                for (const [name, value] of Object.entries(incoming.headers)) {
+                    if (typeof value === 'string')
+                        responseHeaders.set(name, value);
+                    else if (Array.isArray(value))
+                        for (const one of value)
+                            responseHeaders.append(name, one);
+                }
+                resolveResponse(new Response(
+                // A 204/304 carries no body; `Response` refuses a body on those statuses, so the
+                // stream is only attached where one is permitted.
+                incoming.statusCode === 204 || incoming.statusCode === 304
+                    ? null
+                    : Readable.toWeb(incoming), {
+                    status: incoming.statusCode ?? 502,
+                    statusText: incoming.statusMessage ?? '',
+                    headers: responseHeaders,
+                }));
+            });
+            request.on('error', rejectResponse);
+            if (body !== undefined)
+                request.write(body);
+            request.end();
+        });
+        return response;
+    }
+    catch (error) {
+        // A refusal raised inside the hook surfaces here wrapped in whatever `net` did with it. Prefer
+        // our own record of it, so the caller's classification never depends on error identity.
+        if (connectRefusal)
+            throw connectRefusal;
+        throw error;
+    }
+}
+//# sourceMappingURL=pinned-outbound-fetch.backend.utils.js.map

package/dist/esm/security/ssrf/pinned-outbound-fetch.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-outbound-fetch.backend.utils.js","sourceRoot":"","sources":["../../../../../src/security/ssrf/pinned-outbound-fetch.backend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * An outbound HTTP request that CONNECTS to the address it VALIDATED — the half\n * {@link classifyOutboundTargetUrl} and {@link resolvesOnlyToPublicAddresses} structurally cannot do.\n *\n * ## The hole this closes, and why the classifier alone could never close it\n *\n * Every guard in the sibling module answers a question and then hands the answer to somebody else,\n * who makes a SEPARATE connection. That is a check-then-connect, and the guard's own header says so:\n *\n *   \"⚠️ Residual, stated rather than hidden: this is a check-then-connect, so a DNS entry that\n *    changes between the two (rebinding) is not covered. Closing it needs the request pinned to the\n *    validated address, which Node's `fetch` does not expose.\"\n *\n * So a name whose A record answers `93.184.216.34` to the validating resolver and `169.254.169.254`\n * to the connecting one passes every check in this directory and still reaches cloud instance\n * metadata. The window is small and entirely attacker-controlled: the attacker owns the zone, so the\n * attacker chooses the TTL and therefore the width of the window.\n *\n * The classifier cannot fix this at any level of effort, because the defect is not in the answer —\n * the answer was correct when it was given. The defect is that the answer is thrown away before the\n * socket is opened.\n *\n * ## The mechanism, chosen after measuring the alternatives\n *\n * `net.Socket.connect` accepts a **`lookup` hook**, and `http.request` / `https.request` pass it\n * straight through. Node calls it at CONNECT time, and the address it returns is the address the\n * socket is opened to — there is no second resolution and therefore no window. Classifying inside\n * the hook makes validation and connection the SAME event rather than two events with a gap.\n *\n * Measured on this Node (2026-09-08) rather than assumed, because each of these decided the design:\n *\n * | probe | result |\n * |---|---|\n * | is `lookup` called for a hostname? | yes, as `lookup(host, { hints, all: true }, cb)` — note `all` |\n * | is `lookup` called for an IP LITERAL? | **no** — `net` short-circuits, so literals need the shape check |\n * | does an error raised inside the hook reach the caller? | yes, same error object, `message` and `code` intact |\n * | does TLS still verify against the NAME while connected to the pinned IP? | **yes** — a cert for `pinned.test` validated over a socket to `127.0.0.1` |\n *\n * That last row is what makes the whole approach viable. Pinning by rewriting the URL's host to the\n * validated IP — the obvious alternative — breaks SNI and certificate verification, i.e. it trades an\n * SSRF hole for a transport-security hole. Pinning through `lookup` keeps the hostname everywhere it\n * is a security input (SNI, certificate subject, the `Host` header) and replaces it only where it is\n * a routing input.\n *\n * ## Why this is not `fetch` with a dispatcher\n *\n * Node's `fetch` exposes no `lookup` hook. The undici route (`new Agent({ connect: { lookup } })`)\n * would work, but undici is not a declared dependency of this package — it is present in the store\n * only transitively — so taking it would add a second HTTP stack beside the one Node already embeds,\n * for a hook `node:https` exposes natively. Rejected on that basis, not on preference.\n *\n * `node:https` also gives one property for free that `fetch` needs an option for: **it does not\n * follow redirects at all.** A 302 arrives as a 302 the caller can see. `redirect: 'error'` is\n * therefore not something this module has to remember to pass — following a redirect to a target the\n * guard never saw is unrepresentable here.\n *\n * ## What this still does NOT do\n *\n * It does not defend a target that is public at connect time and hostile at the application layer,\n * and it does not stop a public host from being an open proxy into somebody else's private network.\n * Those are different problems with different answers. What it removes is the specific gap between\n * \"we checked this name\" and \"we opened this socket\".\n *\n * assurance-control: WILDO.NETWORK.OUTBOUND_TARGET_CONTROL — a server-side request initiated from\n * application- or tenant-authored configuration reaches only an address the deployment admits\n */\n\nimport { lookup as dnsLookup, type LookupAddress } from 'node:dns';\nimport { request as httpRequest, Agent as HttpAgent, type ClientRequest, type IncomingMessage } from 'node:http';\nimport type { LookupFunction } from 'node:net';\nimport { request as httpsRequest, Agent as HttpsAgent } from 'node:https';\nimport { Readable } from 'node:stream';\n\nimport {\n  OutboundTargetRejection,\n  classifyOutboundTargetUrl,\n  isPrivateOrReservedIpAddress,\n  type OutboundTargetPolicy,\n} from '~wildo-backend-lib/security/ssrf/outbound-target-guard.backend.utils';\n\n/**\n * Raised when the target was refused. Carries the closed-vocabulary reason so a caller can map it\n * onto its OWN rejection vocabulary rather than pattern-matching a message.\n *\n * `refusedAddress` is present only for a connect-time refusal — it is the address the resolver\n * returned at the moment of connection, which is the evidence that a rebinding attempt happened\n * rather than a merely mis-authored URL.\n */\nexport class OutboundTargetRefusedError extends Error {\n  /**\n   * A stable `code` alongside the class, because the error crosses `net`'s internals on its way out\n   * of the `lookup` hook. The class identity survives on this Node (measured), but a `code` is what\n   * every other error in that path carries and it costs nothing to be robust to a future wrap.\n   */\n  public readonly code = 'WILDO_OUTBOUND_TARGET_REFUSED';\n\n  constructor(\n    public readonly rejection: OutboundTargetRejection,\n    public readonly refusedAddress?: string,\n  ) {\n    super(`Outbound target refused: ${rejection}${refusedAddress ? ` (${refusedAddress})` : ''}`);\n    this.name = 'OutboundTargetRefusedError';\n  }\n}\n\n/** The `dns.lookup` shape the connection hook needs, injectable so a test can drive both branches. */\nexport type PinnedAddressResolver = (hostname: string) => Promise<readonly LookupAddress[]>;\n\nexport interface PinnedOutboundRequestInit extends OutboundTargetPolicy {\n  method?: string;\n  headers?: Readonly<Record<string, string>>;\n  /** Already-serialized request body. `content-length` is computed here; do not pass one. */\n  body?: string;\n  signal?: AbortSignal;\n\n  /**\n   * OPERATOR-authored escape: admit an address the public internet cannot reach.\n   *\n   * It exists because one legitimate outbound target class genuinely lives on a private network — a\n   * self-hosted SIEM collector on the same VPC as the application. Refusing that unconditionally\n   * would not be \"safe\", it would break a supported deployment shape.\n   *\n   * Three properties keep it from being an SSRF bypass with a checkbox, and all three are the\n   * caller's obligation rather than this module's:\n   *\n   * 1. **It is never the default.** Absent means refuse.\n   * 2. **It must be authored by the DEPLOYMENT OPERATOR, never by the tenant whose row supplies the\n   *    URL.** A tenant-settable \"allow private addresses\" flag hands the attacker the switch that\n   *    disarms the guard aimed at them. This is why the SIEM escape lives on the application\n   *    configuration and not on `siemExportConfig`, which an organization administrator authors.\n   * 3. **It must never reach a target class whose URL comes from an UNAUTHENTICATED stranger.** CIMD\n   *    resolves a `client_id` supplied by anyone who can reach the authorization endpoint; there is\n   *    no operator on earth who means \"let strangers address my metadata service\".\n   *\n   * Note what it does NOT relax: the scheme policy and the credentials-in-URL refusal still apply,\n   * and the connection is still pinned. It widens WHICH addresses are admitted, never whether the\n   * address that was admitted is the one connected to.\n   */\n  admitPrivateAddresses?: boolean;\n\n  /**\n   * Resolver used by the connection hook. Defaults to the system resolver.\n   *\n   * Injectable for the same reason `resolvesOnlyToPublicAddresses` takes one: the two branches that\n   * matter (a name that answers public, a name that answers private) cannot be exercised against a\n   * real resolver without owning a zone, and a rebinding pin needs a resolver that answers\n   * DIFFERENTLY on its second call — which is exactly what no real resolver will do on demand.\n   */\n  resolveAddresses?: PinnedAddressResolver;\n}\n\n/**\n * Connections are NOT pooled, deliberately.\n *\n * Two reasons, in order of weight. First, a pooled socket skips the `lookup` hook on reuse, so the\n * connect-time classification would run on the first request to a host and not on later ones — the\n * guard would hold or not hold depending on pool state, which is the least auditable property a\n * security control can have. (Reuse would in fact be SAFE, because a pooled socket is already\n * connected to an address this module validated — but \"safe because of a subtlety in another\n * module's cache\" is not a property to rest a control on.) Second, these targets are strangers:\n * pooling keeps an idle socket open per tenant-authored host, which is an unbounded resource keyed\n * on attacker-supplied strings.\n *\n * The cost is one TCP+TLS handshake per request, on a path that runs at webhook cadence rather than\n * per user request.\n */\nconst PINNED_HTTP_AGENT = new HttpAgent({ keepAlive: false });\nconst PINNED_HTTPS_AGENT = new HttpsAgent({ keepAlive: false });\n\n/**\n * Classify the URL's SHAPE before anything leaves the process.\n *\n * This is not redundant with the connection hook, and the reason is measured: `net` short-circuits\n * DNS for an IP LITERAL, so `https://169.254.169.254/latest/meta-data` never calls `lookup` and the\n * hook would never see it. The shape check is the ONLY thing standing in front of a literal target.\n */\nfunction classifyShape(rawUrl: string, init: PinnedOutboundRequestInit): OutboundTargetRejection | undefined {\n  const rejection = classifyOutboundTargetUrl(rawUrl, { admittedProtocols: init.admittedProtocols });\n  if (rejection === undefined) return undefined;\n\n  if (init.admitPrivateAddresses\n    && (rejection === OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS\n      || rejection === OutboundTargetRejection.RESERVED_SPECIAL_USE_HOSTNAME)) {\n    // The operator declared this deployment reaches internal collectors. The scheme and\n    // credentials-in-URL refusals are NOT part of that declaration and fall through unchanged.\n    return undefined;\n  }\n  return rejection;\n}\n\nconst defaultResolver: PinnedAddressResolver = (hostname) =>\n  new Promise((resolve, reject) => {\n    dnsLookup(hostname, { all: true }, (error, addresses) => (error ? reject(error) : resolve(addresses)));\n  });\n\n/**\n * Make the request, connecting only to an address classified at the moment of connection.\n *\n * Returns a real {@link Response} built over the incoming message, so callers keep `ok`, `status`,\n * `headers.get()`, `body.getReader()` and `text()` — every surface the `fetch` this replaces gave\n * them. It is a genuine `Response`, not a look-alike: streaming size enforcement (CIMD reads the body\n * with a running byte counter and cancels the reader) works unchanged.\n *\n * Throws {@link OutboundTargetRefusedError} for a refusal, and whatever `node:http` throws for a\n * transport failure — callers already distinguish those, and conflating them would turn \"your\n * collector is down\" into \"your collector is an SSRF attempt\".\n */\nexport async function pinnedOutboundFetch(rawUrl: string, init: PinnedOutboundRequestInit): Promise<Response> {\n  const shapeRejection = classifyShape(rawUrl, init);\n  if (shapeRejection !== undefined) throw new OutboundTargetRefusedError(shapeRejection);\n\n  const url = new URL(rawUrl);\n  const resolve = init.resolveAddresses ?? defaultResolver;\n\n  /**\n   * The refusal is recorded here as well as thrown, because the throw happens INSIDE a `net`\n   * callback. The error object does survive that path on this Node — measured — but a caught error\n   * on the outside is only usefully classified if we can answer \"was it ours?\" without depending on\n   * that. The box answers it from our own frame.\n   */\n  let connectRefusal: OutboundTargetRefusedError | undefined;\n\n  const requestFn = url.protocol === 'https:' ? httpsRequest : httpRequest;\n  const agent = url.protocol === 'https:' ? PINNED_HTTPS_AGENT : PINNED_HTTP_AGENT;\n\n  const body = init.body;\n  const headers: Record<string, string> = { ...init.headers };\n  if (body !== undefined) headers['content-length'] = String(Buffer.byteLength(body, 'utf8'));\n\n  try {\n    const response = await new Promise<Response>((resolveResponse, rejectResponse) => {\n      const request: ClientRequest = requestFn(\n        {\n          protocol: url.protocol,\n          hostname: url.hostname.replace(/^\\[|\\]$/g, ''), // an IPv6 literal arrives bracketed from `URL`\n          port: url.port || undefined,\n          path: `${url.pathname}${url.search}`,\n          method: init.method ?? 'GET',\n          headers,\n          agent,\n          signal: init.signal,\n\n          /**\n           * THE PIN. Every address the resolver returns is classified here, and the connection is\n           * made to one of the addresses that passed — the same values, in the same event.\n           *\n           * ALL answers are checked rather than the one we hand back, because a hostile resolver can\n           * return one public and one private address and rely on the client picking the other. That\n           * is the same reasoning `resolvesOnlyToPublicAddresses` states; keeping it here means the\n           * property does not depend on which resolver the caller pre-checked with.\n           *\n           * An empty answer is a refusal rather than a fall-through: the resolver succeeded and told\n           * us nothing usable, which is not evidence the name is safe.\n           */\n          lookup: ((hostname, options, callback) => {\n            /**\n             * `callback` is typed as requiring an address even on the error path, so every refusal\n             * hands back an empty list beside the error. Node's `lookupAndConnect` tests the error\n             * FIRST and destroys the socket, so the list is never read — this is a type obligation,\n             * not a fallback the connection could take.\n             */\n            const refuse = (refusal: OutboundTargetRefusedError): void => {\n              connectRefusal = refusal;\n              callback(refusal as NodeJS.ErrnoException, []);\n            };\n            resolve(hostname).then(\n              (resolved) => {\n                const addresses: LookupAddress[] = resolved.map((entry) => ({ address: entry.address, family: entry.family }));\n                if (addresses.length === 0) {\n                  refuse(new OutboundTargetRefusedError(OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS));\n                  return;\n                }\n                if (!init.admitPrivateAddresses) {\n                  const refused = addresses.find((entry) => isPrivateOrReservedIpAddress(entry.address));\n                  if (refused) {\n                    refuse(new OutboundTargetRefusedError(OutboundTargetRejection.PRIVATE_OR_RESERVED_ADDRESS, refused.address));\n                    return;\n                  }\n                }\n                // `all` is what Node passes today; the single-address form is honoured so a future\n                // Node calling the hook the other way does not silently reach the `Invalid IP\n                // address: undefined` failure that the first draft of this hook produced.\n                if ((options as { all?: boolean }).all) callback(null, addresses);\n                else callback(null, addresses[0].address, addresses[0].family);\n              },\n              (error: NodeJS.ErrnoException) => callback(error, []),\n            );\n          }) satisfies LookupFunction,\n        },\n        (incoming: IncomingMessage) => {\n          const responseHeaders = new Headers();\n          for (const [name, value] of Object.entries(incoming.headers)) {\n            if (typeof value === 'string') responseHeaders.set(name, value);\n            else if (Array.isArray(value)) for (const one of value) responseHeaders.append(name, one);\n          }\n          resolveResponse(\n            new Response(\n              // A 204/304 carries no body; `Response` refuses a body on those statuses, so the\n              // stream is only attached where one is permitted.\n              incoming.statusCode === 204 || incoming.statusCode === 304\n                ? null\n                : (Readable.toWeb(incoming) as ReadableStream<Uint8Array>),\n              {\n                status: incoming.statusCode ?? 502,\n                statusText: incoming.statusMessage ?? '',\n                headers: responseHeaders,\n              },\n            ),\n          );\n        },\n      );\n\n      request.on('error', rejectResponse);\n      if (body !== undefined) request.write(body);\n      request.end();\n    });\n    return response;\n  } catch (error) {\n    // A refusal raised inside the hook surfaces here wrapped in whatever `net` did with it. Prefer\n    // our own record of it, so the caller's classification never depends on error identity.\n    if (connectRefusal) throw connectRefusal;\n    throw error;\n  }\n}\n"]}

package/dist/esm/users/services/user-read-retained.custom-impl.backend.service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `users | read_retained` — the operator surface for the audited see-through read (#490).
+ *
+ * # What this replaced: a capability nothing could reach
+ *
+ * `SystemAccessBackendService.readRetainedAsSystem` is the sanctioned way to reveal a RETAINED
+ * (erased-and-impersonalized) user row. It has been complete and correct since retention landed —
+ * it asserts the `seeRetained` policy verb, demands a privileged role, refuses a blank attribution,
+ * sets the see-through flag for that read only, and emits a human-attributed `RETAINED_DATA_ACCESS`
+ * audit row.
+ *
+ * And it had **no caller**. Measured: the only references were the factory that derives its grant
+ * and the schema prose describing it as LIVE. So the capability existed, was audited by
+ * construction, and the only route an operator actually had to a retained record was a database
+ * console — which is precisely the unaudited path the primitive was built to replace.
+ *
+ * # Why an authenticated resource operation, and not an admin controller
+ *
+ * The engine already has an operator-facing admin controller pattern (`data-seeding-admin`), and it
+ * is the wrong shape here: it authenticates with a shared `X-Admin-Secret`, which yields no user id
+ * and no roles. The primitive requires BOTH — it fail-closes on a blank `accessingUserId`, and the
+ * audit row's entire purpose is to say WHO looked. A shared secret answers "someone who holds the
+ * secret", which is the question the record exists to improve on.
+ *
+ * A resource operation runs inside the application's own authentication and authorization, so the
+ * caller's identity and roles arrive already established and cannot be self-asserted.
+ *
+ * # Application tier, deliberately — not platform tier
+ *
+ * A retention policy is an application's decision about its own data, the role gate the primitive
+ * enforces (`APP_ADMIN_SUPER_ADMIN`) is an application role, and the system context the primitive
+ * builds is APPLICATION-scoped. A platform-tier version would cross tenants, and would therefore
+ * come under the declared cross-tenant admission rules and the `PLATFORM_ACCESS_GRANTS` requirement
+ * rather than an ordinary role check. That is a bigger, different door; it is not this one, and it
+ * should not be added by widening this one.
+ */
+import { type ResourceCustomServiceImplementationFactory } from '../../base-classes/services/services/resource-operation-custom-implementation.factory.backend';
+export declare function createUserReadRetainedFactories(): ResourceCustomServiceImplementationFactory[];
+//# sourceMappingURL=user-read-retained.custom-impl.backend.service.d.ts.map

package/dist/esm/users/services/user-read-retained.custom-impl.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-read-retained.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/users/services/user-read-retained.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAWH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AA0GpH,wBAAgB,+BAA+B,IAAI,0CAA0C,EAAE,CA4D9F"}

package/dist/esm/users/services/user-read-retained.custom-impl.backend.service.js

@@ -0,0 +1,159 @@
+/**
+ * `users | read_retained` — the operator surface for the audited see-through read (#490).
+ *
+ * # What this replaced: a capability nothing could reach
+ *
+ * `SystemAccessBackendService.readRetainedAsSystem` is the sanctioned way to reveal a RETAINED
+ * (erased-and-impersonalized) user row. It has been complete and correct since retention landed —
+ * it asserts the `seeRetained` policy verb, demands a privileged role, refuses a blank attribution,
+ * sets the see-through flag for that read only, and emits a human-attributed `RETAINED_DATA_ACCESS`
+ * audit row.
+ *
+ * And it had **no caller**. Measured: the only references were the factory that derives its grant
+ * and the schema prose describing it as LIVE. So the capability existed, was audited by
+ * construction, and the only route an operator actually had to a retained record was a database
+ * console — which is precisely the unaudited path the primitive was built to replace.
+ *
+ * # Why an authenticated resource operation, and not an admin controller
+ *
+ * The engine already has an operator-facing admin controller pattern (`data-seeding-admin`), and it
+ * is the wrong shape here: it authenticates with a shared `X-Admin-Secret`, which yields no user id
+ * and no roles. The primitive requires BOTH — it fail-closes on a blank `accessingUserId`, and the
+ * audit row's entire purpose is to say WHO looked. A shared secret answers "someone who holds the
+ * secret", which is the question the record exists to improve on.
+ *
+ * A resource operation runs inside the application's own authentication and authorization, so the
+ * caller's identity and roles arrive already established and cannot be self-asserted.
+ *
+ * # Application tier, deliberately — not platform tier
+ *
+ * A retention policy is an application's decision about its own data, the role gate the primitive
+ * enforces (`APP_ADMIN_SUPER_ADMIN`) is an application role, and the system context the primitive
+ * builds is APPLICATION-scoped. A platform-tier version would cross tenants, and would therefore
+ * come under the declared cross-tenant admission rules and the `PLATFORM_ACCESS_GRANTS` requirement
+ * rather than an ordinary role check. That is a bigger, different door; it is not this one, and it
+ * should not be added by widening this one.
+ */
+import { CoreResourceType, ErrorCustomMessageReference, ErrorType, ResourceOperationVariantType, Users_Operations, } from '@wildo-ai/saas-models';
+import { createResourceCustomServiceImplementation, } from '../../base-classes/services/services/resource-operation-custom-implementation.factory.backend.js';
+import { describeUnaddressableShape, resolveSingleSubjectId, } from '../../base-classes/utils/single-subject-addressing.backend.utils.js';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+/**
+ * Resolve and validate the whole request, or throw.
+ *
+ * PURE and idempotent, so the PREFIX phase can run it to refuse before anything happens and the
+ * REPLACE phase can re-derive the same values without state threaded between them — the shape the
+ * sibling `force_password_reset` implementation records.
+ */
+function resolveValidatedRetainedReadRequest(id, input, executionContext, utils) {
+    // Exactly one subject. A population-addressed reveal would disclose every retained row matching a
+    // filter on one operator's single stated reason, and the audit row would record that reason
+    // against a disclosure nobody sized.
+    const subjectUserId = resolveSingleSubjectId(id);
+    if (subjectUserId === undefined) {
+        throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+            context: {
+                reason: 'read_retained requires a single addressed user id',
+                receivedAddressing: describeUnaddressableShape(id),
+            },
+        });
+    }
+    /*
+     * A HUMAN, and only a human.
+     *
+     * The sibling `force_password_reset` accepts a machine credential as attribution, and that is
+     * right there: a forced reset is an administrative ACT whose provenance is the strongest
+     * attribution available for a machine caller. This is different. The record being written says a
+     * named person chose to look at data an erasure removed, for a reason they wrote down — and an
+     * API key can supply neither half. `machineCredential` would answer "which credential", never
+     * "who", and the audit row is the whole reason this read is permitted at all.
+     */
+    const accessingUserId = executionContext.initiatorIds?.userId;
+    if (!accessingUserId) {
+        throw utils.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+            context: {
+                reason: 'read_retained_requires_human_principal',
+                message: 'Revealing a retained (erased) record requires an authenticated human principal. A machine '
+                    + 'credential cannot supply the attribution this reveal is audited on.',
+            },
+        });
+    }
+    /*
+     * Roles from the ESTABLISHED session, never from the request body.
+     *
+     * The primitive re-asserts the privileged role itself, and it can only assert what it is handed —
+     * so handing it a request-supplied list would let a caller name their own authorization. The
+     * execution context's roles were established by authentication and cannot be written by the
+     * caller. Flattened across scopes because the primitive tests for one member, not for a scope.
+     */
+    const accessingUserRoles = (executionContext.initiatorRoles ?? []).flatMap((roleInfo) => [...roleInfo.roles]);
+    const reason = typeof input?.reason === 'string'
+        ? (input.reason).trim()
+        : '';
+    if (!reason) {
+        // Also enforced by the request DTO and again inside the primitive. Three sites, because the
+        // audit store persists `eventData` unparsed: a blank reason that reached the row would produce a
+        // reveal recorded with no justification, which is indistinguishable from an unaudited one.
+        throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+            context: {
+                reason: 'read_retained requires a non-empty justification',
+                message: 'Provide `reason`: why this retained record is being revealed (legal hold, dispute, investigation).',
+            },
+        });
+    }
+    return { subjectUserId, accessingUserId, accessingUserRoles, reason };
+}
+export function createUserReadRetainedFactories() {
+    const factory = (_resourcesRegistryService, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.USERS,
+            operationIdentifier: Users_Operations.READ_RETAINED,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'users.read_retained.see-through-reveal',
+        handlers: {
+            // Every refusal lives in PREFIX, the only phase that runs before the core write — so a
+            // rejected request cannot have touched the row on its way to being rejected.
+            prefixCoreOperations: async (id, input, executionContext, _operationPath, utils) => {
+                resolveValidatedRetainedReadRequest(id, input, executionContext, utils);
+                return input;
+            },
+            /*
+             * REPLACE, because the operation is UPDATE-like and must WRITE NOTHING.
+             *
+             * `resourceOperationLike: UPDATE` is how the operation gets a PUT with a body — the request
+             * carries a free-text justification, and a GET would put it in the URL and therefore in
+             * every access log between the operator and the server. Left to the generic core path, that
+             * declaration would make this a real update: a retained row is frozen, so it would fail, and
+             * on a resource that did not freeze it, it would silently write. Replacing the core
+             * operation is what makes an UPDATE-shaped route a read.
+             */
+            replaceCoreOperations: async (id, input, executionContext, _operationPath, utils) => {
+                const { subjectUserId, accessingUserId, accessingUserRoles, reason } = resolveValidatedRetainedReadRequest(id, input, executionContext, utils);
+                const systemAccess = container.get(SAAS_SERVICE_TYPES.SystemAccessService);
+                /*
+                 * Through the PRIMITIVE, never through the repository.
+                 *
+                 * This is the line the whole issue turns on. The same row is reachable by building a
+                 * super-admin context and reading it directly — and that path asserts no `seeRetained`
+                 * grant, sets no see-through flag, and writes no audit row. Reaching the repository here
+                 * would reveal exactly the same personal data with no record of it, which is the outcome
+                 * the audited pair exists to prevent.
+                 */
+                return await systemAccess.readRetainedAsSystem(CoreResourceType.USERS, subjectUserId, { accessingUserId, accessingUserRoles, reason }, {
+                    // Scoped to the organization the caller is acting in, when there is one. The primitive
+                    // suppresses the RETENTION predicate only — never the scope filter — so this cannot
+                    // widen the read beyond what the caller could otherwise address.
+                    scopeContext: executionContext.initiatorIds?.organizationId
+                        ? { organizationId: executionContext.initiatorIds.organizationId }
+                        : undefined,
+                });
+            },
+        },
+    });
+    return [factory];
+}
+//# sourceMappingURL=user-read-retained.custom-impl.backend.service.js.map

package/dist/esm/users/services/user-read-retained.custom-impl.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-read-retained.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../src/users/services/user-read-retained.custom-impl.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `users | read_retained` — the operator surface for the audited see-through read (#490).\n *\n * # What this replaced: a capability nothing could reach\n *\n * `SystemAccessBackendService.readRetainedAsSystem` is the sanctioned way to reveal a RETAINED\n * (erased-and-impersonalized) user row. It has been complete and correct since retention landed —\n * it asserts the `seeRetained` policy verb, demands a privileged role, refuses a blank attribution,\n * sets the see-through flag for that read only, and emits a human-attributed `RETAINED_DATA_ACCESS`\n * audit row.\n *\n * And it had **no caller**. Measured: the only references were the factory that derives its grant\n * and the schema prose describing it as LIVE. So the capability existed, was audited by\n * construction, and the only route an operator actually had to a retained record was a database\n * console — which is precisely the unaudited path the primitive was built to replace.\n *\n * # Why an authenticated resource operation, and not an admin controller\n *\n * The engine already has an operator-facing admin controller pattern (`data-seeding-admin`), and it\n * is the wrong shape here: it authenticates with a shared `X-Admin-Secret`, which yields no user id\n * and no roles. The primitive requires BOTH — it fail-closes on a blank `accessingUserId`, and the\n * audit row's entire purpose is to say WHO looked. A shared secret answers \"someone who holds the\n * secret\", which is the question the record exists to improve on.\n *\n * A resource operation runs inside the application's own authentication and authorization, so the\n * caller's identity and roles arrive already established and cannot be self-asserted.\n *\n * # Application tier, deliberately — not platform tier\n *\n * A retention policy is an application's decision about its own data, the role gate the primitive\n * enforces (`APP_ADMIN_SUPER_ADMIN`) is an application role, and the system context the primitive\n * builds is APPLICATION-scoped. A platform-tier version would cross tenants, and would therefore\n * come under the declared cross-tenant admission rules and the `PLATFORM_ACCESS_GRANTS` requirement\n * rather than an ordinary role check. That is a bigger, different door; it is not this one, and it\n * should not be added by widening this one.\n */\n\nimport {\n  CoreResourceType,\n  ErrorCustomMessageReference,\n  ErrorType,\n  ResourceOperationVariantType,\n  Users_Operations,\n} from '@wildo-ai/saas-models';\nimport type { Container } from 'inversify';\n\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport {\n  describeUnaddressableShape,\n  resolveSingleSubjectId,\n} from '~wildo-backend-lib/base-classes/utils/single-subject-addressing.backend.utils';\nimport type { SystemAccessBackendService } from '~wildo-backend-lib/base-classes/services/services/system-access.backend.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\ninterface ErrorBuildingUtils {\n  errorBuilder: {\n    buildError: (\n      type: ErrorType,\n      executionContext?: unknown,\n      options?: { customMessageReference?: ErrorCustomMessageReference; context?: Record<string, unknown> },\n    ) => unknown;\n  };\n}\n\n/** Everything the reveal needs, resolved from the request and the established session. */\ninterface ValidatedRetainedReadRequest {\n  subjectUserId: string;\n  accessingUserId: string;\n  accessingUserRoles: string[];\n  reason: string;\n}\n\n/**\n * Resolve and validate the whole request, or throw.\n *\n * PURE and idempotent, so the PREFIX phase can run it to refuse before anything happens and the\n * REPLACE phase can re-derive the same values without state threaded between them — the shape the\n * sibling `force_password_reset` implementation records.\n */\nfunction resolveValidatedRetainedReadRequest(\n  id: unknown,\n  input: unknown,\n  executionContext: ExecutionContext<any>,\n  utils: ErrorBuildingUtils,\n): ValidatedRetainedReadRequest {\n  // Exactly one subject. A population-addressed reveal would disclose every retained row matching a\n  // filter on one operator's single stated reason, and the audit row would record that reason\n  // against a disclosure nobody sized.\n  const subjectUserId = resolveSingleSubjectId(id as never);\n  if (subjectUserId === undefined) {\n    throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n      customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,\n      context: {\n        reason: 'read_retained requires a single addressed user id',\n        receivedAddressing: describeUnaddressableShape(id as never),\n      },\n    });\n  }\n\n  /*\n   * A HUMAN, and only a human.\n   *\n   * The sibling `force_password_reset` accepts a machine credential as attribution, and that is\n   * right there: a forced reset is an administrative ACT whose provenance is the strongest\n   * attribution available for a machine caller. This is different. The record being written says a\n   * named person chose to look at data an erasure removed, for a reason they wrote down — and an\n   * API key can supply neither half. `machineCredential` would answer \"which credential\", never\n   * \"who\", and the audit row is the whole reason this read is permitted at all.\n   */\n  const accessingUserId = executionContext.initiatorIds?.userId;\n  if (!accessingUserId) {\n    throw utils.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {\n      context: {\n        reason: 'read_retained_requires_human_principal',\n        message:\n          'Revealing a retained (erased) record requires an authenticated human principal. A machine '\n          + 'credential cannot supply the attribution this reveal is audited on.',\n      },\n    });\n  }\n\n  /*\n   * Roles from the ESTABLISHED session, never from the request body.\n   *\n   * The primitive re-asserts the privileged role itself, and it can only assert what it is handed —\n   * so handing it a request-supplied list would let a caller name their own authorization. The\n   * execution context's roles were established by authentication and cannot be written by the\n   * caller. Flattened across scopes because the primitive tests for one member, not for a scope.\n   */\n  const accessingUserRoles = (executionContext.initiatorRoles ?? []).flatMap((roleInfo) => [...roleInfo.roles]);\n\n  const reason = typeof (input as { reason?: unknown })?.reason === 'string'\n    ? ((input as { reason: string }).reason).trim()\n    : '';\n  if (!reason) {\n    // Also enforced by the request DTO and again inside the primitive. Three sites, because the\n    // audit store persists `eventData` unparsed: a blank reason that reached the row would produce a\n    // reveal recorded with no justification, which is indistinguishable from an unaudited one.\n    throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n      customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,\n      context: {\n        reason: 'read_retained requires a non-empty justification',\n        message: 'Provide `reason`: why this retained record is being revealed (legal hold, dispute, investigation).',\n      },\n    });\n  }\n\n  return { subjectUserId, accessingUserId, accessingUserRoles, reason };\n}\n\nexport function createUserReadRetainedFactories(): ResourceCustomServiceImplementationFactory[] {\n  const factory = (_resourcesRegistryService: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.USERS,\n        operationIdentifier: Users_Operations.READ_RETAINED,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'users.read_retained.see-through-reveal',\n      handlers: {\n        // Every refusal lives in PREFIX, the only phase that runs before the core write — so a\n        // rejected request cannot have touched the row on its way to being rejected.\n        prefixCoreOperations: async (id, input, executionContext, _operationPath, utils) => {\n          resolveValidatedRetainedReadRequest(id, input, executionContext, utils);\n          return input;\n        },\n        /*\n         * REPLACE, because the operation is UPDATE-like and must WRITE NOTHING.\n         *\n         * `resourceOperationLike: UPDATE` is how the operation gets a PUT with a body — the request\n         * carries a free-text justification, and a GET would put it in the URL and therefore in\n         * every access log between the operator and the server. Left to the generic core path, that\n         * declaration would make this a real update: a retained row is frozen, so it would fail, and\n         * on a resource that did not freeze it, it would silently write. Replacing the core\n         * operation is what makes an UPDATE-shaped route a read.\n         */\n        replaceCoreOperations: async (id, input, executionContext, _operationPath, utils) => {\n          const { subjectUserId, accessingUserId, accessingUserRoles, reason } =\n            resolveValidatedRetainedReadRequest(id, input, executionContext, utils);\n\n          const systemAccess = container.get<SystemAccessBackendService>(SAAS_SERVICE_TYPES.SystemAccessService);\n\n          /*\n           * Through the PRIMITIVE, never through the repository.\n           *\n           * This is the line the whole issue turns on. The same row is reachable by building a\n           * super-admin context and reading it directly — and that path asserts no `seeRetained`\n           * grant, sets no see-through flag, and writes no audit row. Reaching the repository here\n           * would reveal exactly the same personal data with no record of it, which is the outcome\n           * the audited pair exists to prevent.\n           */\n          return await systemAccess.readRetainedAsSystem(\n            CoreResourceType.USERS,\n            subjectUserId,\n            { accessingUserId, accessingUserRoles, reason },\n            {\n              // Scoped to the organization the caller is acting in, when there is one. The primitive\n              // suppresses the RETENTION predicate only — never the scope filter — so this cannot\n              // widen the read beyond what the caller could otherwise address.\n              scopeContext: executionContext.initiatorIds?.organizationId\n                ? { organizationId: executionContext.initiatorIds.organizationId }\n                : undefined,\n            },\n          );\n        },\n      },\n    });\n\n  return [factory];\n}\n"]}