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

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

@@ -0,0 +1,143 @@
+/**
+ * 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 { type LookupAddress } from 'node:dns';
+import { OutboundTargetRejection, type OutboundTargetPolicy } from '../../security/ssrf/outbound-target-guard.backend.utils';
+/**
+ * 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 declare class OutboundTargetRefusedError extends Error {
+    readonly rejection: OutboundTargetRejection;
+    readonly refusedAddress?: string;
+    /**
+     * 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.
+     */
+    readonly code = "WILDO_OUTBOUND_TARGET_REFUSED";
+    constructor(rejection: OutboundTargetRejection, refusedAddress?: string);
+}
+/** The `dns.lookup` shape the connection hook needs, injectable so a test can drive both branches. */
+export type PinnedAddressResolver = (hostname: string) => Promise<readonly LookupAddress[]>;
+export interface PinnedOutboundRequestInit extends OutboundTargetPolicy {
+    method?: string;
+    headers?: Readonly<Record<string, string>>;
+    /** Already-serialized request body. `content-length` is computed here; do not pass one. */
+    body?: string;
+    signal?: AbortSignal;
+    /**
+     * OPERATOR-authored escape: admit an address the public internet cannot reach.
+     *
+     * It exists because one legitimate outbound target class genuinely lives on a private network — a
+     * self-hosted SIEM collector on the same VPC as the application. Refusing that unconditionally
+     * would not be "safe", it would break a supported deployment shape.
+     *
+     * Three properties keep it from being an SSRF bypass with a checkbox, and all three are the
+     * caller's obligation rather than this module's:
+     *
+     * 1. **It is never the default.** Absent means refuse.
+     * 2. **It must be authored by the DEPLOYMENT OPERATOR, never by the tenant whose row supplies the
+     *    URL.** A tenant-settable "allow private addresses" flag hands the attacker the switch that
+     *    disarms the guard aimed at them. This is why the SIEM escape lives on the application
+     *    configuration and not on `siemExportConfig`, which an organization administrator authors.
+     * 3. **It must never reach a target class whose URL comes from an UNAUTHENTICATED stranger.** CIMD
+     *    resolves a `client_id` supplied by anyone who can reach the authorization endpoint; there is
+     *    no operator on earth who means "let strangers address my metadata service".
+     *
+     * Note what it does NOT relax: the scheme policy and the credentials-in-URL refusal still apply,
+     * and the connection is still pinned. It widens WHICH addresses are admitted, never whether the
+     * address that was admitted is the one connected to.
+     */
+    admitPrivateAddresses?: boolean;
+    /**
+     * Resolver used by the connection hook. Defaults to the system resolver.
+     *
+     * Injectable for the same reason `resolvesOnlyToPublicAddresses` takes one: the two branches that
+     * matter (a name that answers public, a name that answers private) cannot be exercised against a
+     * real resolver without owning a zone, and a rebinding pin needs a resolver that answers
+     * DIFFERENTLY on its second call — which is exactly what no real resolver will do on demand.
+     */
+    resolveAddresses?: PinnedAddressResolver;
+}
+/**
+ * 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 declare function pinnedOutboundFetch(rawUrl: string, init: PinnedOutboundRequestInit): Promise<Response>;
+//# sourceMappingURL=pinned-outbound-fetch.backend.utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-outbound-fetch.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/ssrf/pinned-outbound-fetch.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAMnE,OAAO,EACL,uBAAuB,EAGvB,KAAK,oBAAoB,EAC1B,MAAM,sEAAsE,CAAC;AAE9E;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aASjC,SAAS,EAAE,uBAAuB;aAClC,cAAc,CAAC,EAAE,MAAM;IATzC;;;;OAIG;IACH,SAAgB,IAAI,mCAAmC;gBAGrC,SAAS,EAAE,uBAAuB,EAClC,cAAc,CAAC,EAAE,MAAM;CAK1C;AAED,sGAAsG;AACtG,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;AAE5F,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoH5G"}

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/security/token-invalidation-fence.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-invalidation-fence.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/token-invalidation-fence.backend.utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,WAAW,iCAAiC;IAChD,iGAAiG;IACjG,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAsB,kCAAkC,CACtD,YAAY,EAAE,gCAAgC,EAC9C,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,OAAO,CAAC,iCAAiC,CAAC,CAY5C"}
+{"version":3,"file":"token-invalidation-fence.backend.utils.d.ts","sourceRoot":"","sources":["../../../src/security/token-invalidation-fence.backend.utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,WAAW,iCAAiC;IAChD,iGAAiG;IACjG,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAsB,kCAAkC,CACtD,YAAY,EAAE,gCAAgC,EAC9C,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,OAAO,CAAC,iCAAiC,CAAC,CAY5C"}

package/dist/esm/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,yCAAyC,CAAC;AACxD,cAAc,yCAAyC,CAAC;AACxD,cAAc,sEAAsE,CAAC;AACrF,cAAc,2FAA2F,CAAC;AAC1G,cAAc,mFAAmF,CAAC;AAClG,cAAc,uEAAuE,CAAC;AACtF,cAAc,qDAAqD,CAAC;AACpE,cAAc,mDAAmD,CAAC;AAClE,cAAc,wDAAwD,CAAC;AACvE,cAAc,kFAAkF,CAAC;AACjG,cAAc,wEAAwE,CAAC;AACvF,cAAc,+DAA+D,CAAC;AAC9E,cAAc,uCAAuC,CAAC;AACtD,cAAc,8DAA8D,CAAC;AAC7E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,yDAAyD,CAAC;AACxE,cAAc,gEAAgE,CAAC;AAC/E,cAAc,mDAAmD,CAAC;AAClE,cAAc,0DAA0D,CAAC;AACzE,cAAc,2FAA2F,CAAC;AAC1G,cAAc,8EAA8E,CAAC;AAC7F,cAAc,8FAA8F,CAAC;AAC7G,cAAc,sGAAsG,CAAC;AACrH,cAAc,mFAAmF,CAAC;AAClG,cAAc,+EAA+E,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,yCAAyC,CAAC;AACxD,cAAc,yCAAyC,CAAC;AACxD,cAAc,sEAAsE,CAAC;AACrF,cAAc,2FAA2F,CAAC;AAC1G,cAAc,mFAAmF,CAAC;AAClG,cAAc,uEAAuE,CAAC;AACtF,cAAc,qDAAqD,CAAC;AACpE,cAAc,mDAAmD,CAAC;AAClE,cAAc,wDAAwD,CAAC;AACvE,cAAc,kFAAkF,CAAC;AACjG,cAAc,wEAAwE,CAAC;AACvF,cAAc,+DAA+D,CAAC;AAC9E,cAAc,uCAAuC,CAAC;AACtD,cAAc,8DAA8D,CAAC;AAC7E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,yDAAyD,CAAC;AACxE,cAAc,gEAAgE,CAAC;AAC/E,cAAc,mDAAmD,CAAC;AAClE,cAAc,0DAA0D,CAAC;AACzE,cAAc,2FAA2F,CAAC;AAC1G,cAAc,8EAA8E,CAAC;AAC7F,cAAc,8FAA8F,CAAC;AAC7G,cAAc,sGAAsG,CAAC;AACrH,cAAc,mFAAmF,CAAC;AAClG,cAAc,+EAA+E,CAAC"}

package/dist/esm/users/services/inbound-contact-custom-implementation.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound-contact-custom-implementation.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/users/services/inbound-contact-custom-implementation.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAGL,4BAA4B,EAG7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AACpH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iFAAiF,CAAC;AAGlI;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,4BAA4B,CAKjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,mBAAmB,EAAE,0BAA0B,EAC/C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,4BAA4B,CAAC,CAcvC;AAED,wBAAgB,mCAAmC,IAAI,0CAA0C,EAAE,CAuDlG"}
+{"version":3,"file":"inbound-contact-custom-implementation.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/users/services/inbound-contact-custom-implementation.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAGL,4BAA4B,EAG7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AACpH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iFAAiF,CAAC;AAGlI;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,4BAA4B,CAKjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,mBAAmB,EAAE,0BAA0B,EAC/C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,4BAA4B,CAAC,CAcvC;AAED,wBAAgB,mCAAmC,IAAI,0CAA0C,EAAE,CAuDlG"}

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

@@ -1 +1 @@
-{"version":3,"file":"user-deletion-audit.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/users/services/user-deletion-audit.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAUH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAsEpH;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAmB/F"}
+{"version":3,"file":"user-deletion-audit.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/users/services/user-deletion-audit.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAUH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAsEpH;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAmB/F"}

package/dist/esm/users/services/user-force-password-reset.custom-impl.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-force-password-reset.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/users/services/user-force-password-reset.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAUH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AA2GpH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qCAAqC,IAAI,0CAA0C,EAAE,CAwDpG"}
+{"version":3,"file":"user-force-password-reset.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/users/services/user-force-password-reset.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAUH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AA2GpH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qCAAqC,IAAI,0CAA0C,EAAE,CAwDpG"}

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"}