@jini-ai/platform 0.3.0 → 0.5.1

package/dist/fs/index.d.ts

@@ -0,0 +1,8 @@
+export * from "../fs.js";
+export * from "./atomic-write.js";
+export * from "./env-text.js";
+export * from "./strict-containment.js";
+export * from "./guarded-reader.js";
+export * from "./durable-json.js";
+export { withFileLock, withFileLockSync, isLockStale } from "./file-lock.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/fs/index.js

@@ -0,0 +1,9 @@
+// Filesystem exports share atomic replacement and token/inode-owned lock primitives.
+export * from "../fs.js";
+export * from "./atomic-write.js";
+export * from "./env-text.js";
+export * from "./strict-containment.js";
+export * from "./guarded-reader.js";
+export * from "./durable-json.js";
+export { withFileLock, withFileLockSync, isLockStale } from "./file-lock.js";
+//# sourceMappingURL=index.js.map

package/dist/fs/strict-containment.d.ts

@@ -0,0 +1,5 @@
+export declare function resolvePathWithin({ root, segment }: {
+    root: string;
+    segment: string;
+}): string | null;
+//# sourceMappingURL=strict-containment.d.ts.map

package/dist/fs/strict-containment.js

@@ -0,0 +1,13 @@
+/** Preserve strict lexical containment: relative roots, root equality and traversal are refused (except the filesystem-root edge case). Symlinks require a separate physical-path guard. */
+import path from "node:path";
+export function resolvePathWithin({ root, segment }) {
+    const resolved = path.resolve(root, segment);
+    if (resolved !== path.join(root, segment))
+        return null;
+    const normalizedRoot = path.resolve(root);
+    const prefix = normalizedRoot === path.sep ? normalizedRoot : `${normalizedRoot}${path.sep}`;
+    if (!resolved.startsWith(prefix))
+        return null;
+    return resolved;
+}
+//# sourceMappingURL=strict-containment.js.map

package/dist/fs.js

@@ -75,9 +75,8 @@ export async function atomicCopyFile(sourcePath, destinationPath, options = {})
     const tempPath = join(destinationDir, `.${basename(destination)}.${process.pid}.${Date.now().toString(36)}.${Math.random().toString(36).slice(2)}.tmp`);
     try {
         await copyFile(source, tempPath);
-        if (options.overwrite === true) {
-            await rm(destination, { force: true });
-        }
+        // Rename replaces the old file atomically. Removing it first opens a
+        // missing-file window and loses the previous contents if rename fails.
         await rename(tempPath, destination);
         const copied = await stat(destination);
         return { bytesCopied: copied.size, replaced: existing != null };

package/dist/http/guarded/client.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { GuardedHttpRequired } from "./ports.js";
+export type AddressClass = "public" | "private" | "loopback" | "link-local" | "reserved";
+/** Uses the canonical net address validator; labels preserve the guarded refusal contract. */
+export declare function classifyAddress({ ip }: {
+    ip: string;
+}): AddressClass;
+/** Builds an adapter-friendly outbound port. Every hop is resolved, checked, and pinned before I/O.
+ * Socket idle time is bounded on every hop. An optional totalDeadlineMs includes DNS,
+ * redirect hops and decoded body reads; it is never inferred from the idle budget.
+ */
+export declare function createHttpClient(required: GuardedHttpRequired): HttpClientPort;
+//# sourceMappingURL=client.d.ts.map

package/dist/http/guarded/client.js

@@ -0,0 +1,240 @@
+// Policy refusals use EgressRefusedError; DNS, connection and transport failures retain their
+// own errors because they are operational failures, not decisions that a different URL fixes.
+import { isPrivateAddress, expandIpv6 } from "../../net/address.js";
+import { FetchTimeoutError } from "../../fetch-with-timeout.js";
+import { isIP } from "node:net";
+import { EgressRefusedError } from "./errors.js";
+/** Uses the canonical net address validator; labels preserve the guarded refusal contract. */
+export function classifyAddress({ ip }) {
+    if (!isPrivateAddress({ address: ip })) {
+        if (ip.toLowerCase().startsWith("::0."))
+            return "reserved";
+        return "public";
+    }
+    if (isIP(ip) === 6) {
+        const g = expandIpv6({ address: ip });
+        if (g.slice(0, 5).every(n => n === 0) && g[5] === 0xffff) {
+            return classifyAddress({ ip: [g[6] >> 8, g[6] & 255, g[7] >> 8, g[7] & 255].join(".") });
+        }
+        if (g.slice(0, 7).every(n => n === 0) && g[7] === 1)
+            return "loopback";
+        if ((g[0] & 0xffc0) === 0xfe80)
+            return "link-local";
+        if ((g[0] & 0xfe00) === 0xfc00)
+            return "private";
+        return "reserved";
+    }
+    if (isIP(ip) !== 4)
+        return "reserved";
+    const [a, b] = ip.split(".").map(Number);
+    if (a === 127)
+        return "loopback";
+    // This range includes the cloud metadata address 169.254.169.254.
+    if (a === 169 && b === 254)
+        return "link-local";
+    if (a === 0 || a >= 224)
+        return "reserved";
+    // The remaining blocked IPv4 ranges include RFC 6598 shared carrier space (100.64.0.0/10):
+    // it is not globally routable and belongs with RFC 1918 private ranges for egress decisions.
+    return "private";
+}
+const SENSITIVE_HEADERS = new Set(["authorization", "cookie"]);
+// HTTP header names are case-insensitive; preserve the caller's explicit User-Agent in any casing.
+function hasUserAgentHeader(headers) {
+    return Object.keys(headers).some((key) => key.toLowerCase() === "user-agent");
+}
+function withDefaultUserAgent(headers, userAgent) {
+    if (hasUserAgentHeader(headers))
+        return { ...headers };
+    return { ...headers, "User-Agent": userAgent };
+}
+function isCrossOrigin(a, b) {
+    return a.protocol !== b.protocol || a.hostname !== b.hostname || a.port !== b.port;
+}
+function assertAllowedTarget(url, policy) {
+    if (!policy.allowedSchemes.includes(url.protocol.replace(":", ""))) {
+        const message = `scheme '${url.protocol}' is not in the allowed egress schemes`;
+        throw new EgressRefusedError({ message }, { callerSafeMessage: message });
+    }
+    if (url.username || url.password) {
+        const message = "credentials embedded in the target URL are not allowed";
+        throw new EgressRefusedError({ message }, { callerSafeMessage: message });
+    }
+}
+// WHATWG URL.hostname brackets IPv6 literals; IP classification, DNS and allowlists use bare IPs.
+function stripIpv6Brackets(hostname) {
+    if (hostname.startsWith("[") && hostname.endsWith("]"))
+        return hostname.slice(1, -1);
+    return hostname;
+}
+// IP literals resolve to themselves and must not depend on a DNS lookup.
+async function resolveHostAddresses(hostname, dns) {
+    const literal = stripIpv6Brackets(hostname);
+    if (isIP(literal) !== 0)
+        return [literal];
+    return [...await dns.resolve({ hostname })];
+}
+// Keep the resolved IP in internal diagnostics only; the caller-safe refusal must not disclose it.
+function assertNoPrivateAddress(hostname, addresses) {
+    for (const address of addresses) {
+        const addressClass = classifyAddress({ ip: address });
+        if (addressClass !== "public") {
+            throw new EgressRefusedError({ message: `egress to '${hostname}' (${address}) rejected: resolved address is ${addressClass}` }, {
+                callerSafeMessage: `egress to '${hostname}' rejected: resolved address is ${addressClass}`,
+            });
+        }
+    }
+}
+async function resolvePinnedPeer(url, policy, dns) {
+    assertAllowedTarget(url, policy);
+    const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+    const hostname = stripIpv6Brackets(url.hostname);
+    const isDevAllowlisted = policy.devHostAllowlist.includes(hostname);
+    const addresses = await resolveHostAddresses(url.hostname, dns);
+    if (addresses.length === 0) {
+        throw new Error(`could not resolve any address for host '${url.hostname}'`);
+    }
+    if (policy.denyPrivateAddresses && !isDevAllowlisted) {
+        assertNoPrivateAddress(url.hostname, addresses);
+    }
+    return {
+        ip: addresses[0],
+        port,
+        authority: url.host,
+        // RFC 6066 section 3: SNI names a hostname, never an IP literal of either family.
+        tlsServerName: isIP(hostname) === 0 ? url.hostname : undefined,
+    };
+}
+function withStrippedSensitiveHeaders(headers) {
+    const next = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (SENSITIVE_HEADERS.has(key.toLowerCase()))
+            continue;
+        next[key] = value;
+    }
+    return next;
+}
+function capBody(bodyText, maxBytes) {
+    const buffer = Buffer.from(bodyText, "utf8");
+    if (buffer.byteLength <= maxBytes)
+        return bodyText;
+    return buffer.subarray(0, maxBytes).toString("utf8");
+}
+// Cap text and raw bytes independently: invalid UTF-8 bytes become three-byte U+FFFD characters,
+// so a complete binary body can have a decoded text representation that crosses the cap.
+// The byte-specific flag prevents falsely treating that complete file as corrupt; the coarse
+// bodyTruncated flag remains the OR for callers that consume text.
+function capResponse(response, maxBytes) {
+    const bodyText = capBody(response.bodyText, maxBytes);
+    const bytes = response.bodyBytes;
+    const bytesOverCap = bytes !== undefined && bytes.byteLength > maxBytes;
+    // A producer's coarse flag names no shape and counts against both unless its byte flag says
+    // otherwise; assuming complete bytes from an unspecified truncation signal risks corruption.
+    const producerTruncated = response.bodyTruncated === true;
+    const bytesTruncated = bytesOverCap || (response.bodyBytesTruncated ?? producerTruncated);
+    return {
+        ...response,
+        bodyText,
+        ...(bytes !== undefined
+            ? { bodyBytes: bytesOverCap ? bytes.subarray(0, maxBytes) : bytes, bodyBytesTruncated: bytesTruncated }
+            : {}),
+        bodyTruncated: bodyText !== response.bodyText || bytesOverCap || producerTruncated,
+    };
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+async function sendWithPolicy(transport, policy, request, redirectsFollowed, dns, redirect) {
+    const url = new URL(request.url);
+    request.signal?.throwIfAborted();
+    const peer = await resolveBeforeDeadline(resolvePinnedPeer(url, policy, dns), request.signal);
+    request.signal?.throwIfAborted();
+    const boundedRequest = {
+        ...request,
+        // The policy timeout is a ceiling: callers may choose a shorter idle budget, never a longer one.
+        // Keep the legacy alias synchronized for host transport adapters. Activity resets
+        // Node's socket timer; a large progressing body must not spend a wall-clock budget.
+        idleTimeoutMs: Math.min(request.idleTimeoutMs ?? request.timeoutMs, policy.connectTimeoutMs),
+        timeoutMs: Math.min(request.idleTimeoutMs ?? request.timeoutMs, policy.connectTimeoutMs),
+        maxResponseBytes: Math.min(request.maxResponseBytes ?? Infinity, policy.maxResponseBytes, policy.maxDecompressedBytes),
+    };
+    const response = await resolveBeforeDeadline(transport.requestPinned({ request: boundedRequest, peer }), request.signal);
+    const effectiveCap = Math.min(request.maxResponseBytes ?? Infinity, policy.maxResponseBytes, policy.maxDecompressedBytes);
+    // Record the normalized URL actually resolved and pinned, not the caller's original spelling.
+    // A followed redirect returns the deeper hop's response, including that hop's finalUrl.
+    const cappedResponse = { ...capResponse(response, effectiveCap), finalUrl: url.href };
+    // A refused redirect is a policy decision like a refused address, so it carries the same type.
+    // The text names no Location target, which may be private, so both messages can share it.
+    if (redirect === "error" && REDIRECT_STATUSES.has(cappedResponse.status)) {
+        const message = "redirect response refused by the request's redirect policy";
+        throw new EgressRefusedError({ message }, { callerSafeMessage: message });
+    }
+    // Follow GET only even when the policy allows redirects: 307/308 preserve method and body,
+    // so following a mutating request would replay a write and leak its body to an unchosen target.
+    // With follow policy, a non-GET redirect stays a raw response rather than a target refusal.
+    const canFollowRedirect = redirect === "follow" && request.method === "GET" && REDIRECT_STATUSES.has(cappedResponse.status) && redirectsFollowed < policy.maxRedirects;
+    if (!canFollowRedirect) {
+        return cappedResponse;
+    }
+    const location = cappedResponse.headers.location ?? cappedResponse.headers.Location;
+    if (!location)
+        return cappedResponse;
+    const nextUrl = new URL(location, url);
+    // Cross-origin hops must not inherit authorization or cookies entrusted to the original origin.
+    const nextHeaders = isCrossOrigin(url, nextUrl)
+        ? withStrippedSensitiveHeaders(request.headers)
+        : request.headers;
+    return sendWithPolicy(transport, policy, { ...request, url: nextUrl.toString(), headers: nextHeaders }, redirectsFollowed + 1, dns, redirect);
+}
+/** Builds an adapter-friendly outbound port. Every hop is resolved, checked, and pinned before I/O.
+ * Socket idle time is bounded on every hop. An optional totalDeadlineMs includes DNS,
+ * redirect hops and decoded body reads; it is never inferred from the idle budget.
+ */
+export function createHttpClient(required) {
+    const { transport, policy, dns, clock, userAgent } = required;
+    if (!userAgent.trim())
+        throw new TypeError("userAgent is required");
+    for (const value of [policy.connectTimeoutMs, policy.maxResponseBytes, policy.maxDecompressedBytes]) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new TypeError("policy time and byte limits must be positive safe integers");
+    }
+    if (!Number.isSafeInteger(policy.maxRedirects) || policy.maxRedirects < 0)
+        throw new TypeError("maxRedirects must be a nonnegative safe integer");
+    return { async send({ request }, { redirect = "follow" } = {}) {
+            const idleTimeoutMs = request.idleTimeoutMs ?? request.timeoutMs;
+            if (!Number.isSafeInteger(idleTimeoutMs) || idleTimeoutMs <= 0) {
+                const timeoutName = request.idleTimeoutMs === undefined ? "timeoutMs" : "idleTimeoutMs";
+                throw new TypeError(`${timeoutName} must be a positive safe integer`);
+            }
+            if (request.totalDeadlineMs !== undefined && (!Number.isSafeInteger(request.totalDeadlineMs) || request.totalDeadlineMs <= 0))
+                throw new TypeError("totalDeadlineMs must be a positive safe integer");
+            if (request.maxResponseBytes !== undefined && (!Number.isSafeInteger(request.maxResponseBytes) || request.maxResponseBytes <= 0))
+                throw new TypeError("maxResponseBytes must be a positive safe integer");
+            const deadline = request.totalDeadlineMs === undefined ? undefined : clock.timeoutSignal({ timeoutMs: request.totalDeadlineMs });
+            const signal = request.signal && deadline ? AbortSignal.any([request.signal, deadline]) : request.signal ?? deadline;
+            try {
+                return await sendWithPolicy(transport, policy, { ...request, ...(signal === undefined ? {} : { signal }), headers: withDefaultUserAgent(request.headers, userAgent) }, 0, dns, redirect);
+            }
+            catch (error) {
+                if (deadline?.aborted && !request.signal?.aborted)
+                    throw new FetchTimeoutError(request.url, request.totalDeadlineMs);
+                throw error;
+            }
+        } };
+}
+async function resolveBeforeDeadline(work, signal) {
+    if (!signal)
+        return work;
+    let abort;
+    try {
+        return await Promise.race([work, new Promise((_resolve, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            })]);
+    }
+    finally {
+        if (abort)
+            signal.removeEventListener("abort", abort);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/http/guarded/errors.d.ts

@@ -0,0 +1,21 @@
+import { type PlatformMessages } from "../../messages.js";
+/** A pre-connect policy decision; callerSafeMessage never includes resolved private addresses.
+ * Export the refusal class so tool/HTTP boundaries can recognize a policy decision with instanceof
+ * instead of fragile message matching. A caller can correct a refused target; DNS failures and
+ * timeouts are operational failures. Reporting a policy refusal as an internal crash hides that fix.
+ * The full message is for server audit/logs. Only callerSafeMessage belongs at an external boundary:
+ * exposing resolved private addresses would let callers enumerate internal DNS one request at a time.
+ * Public address classifications remain actionable without revealing deployment-specific IPs.
+ * The safe message defaults to a generic refusal, never the full message, so omitted redaction fails
+ * toward disclosing less. Recognition of this class grants no access to an unguarded transport.
+ */
+export declare class EgressRefusedError extends Error {
+    readonly callerSafeMessage: string;
+    constructor({ message }: {
+        message: string;
+    }, { callerSafeMessage, messages }?: {
+        callerSafeMessage?: string;
+        messages?: PlatformMessages;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/http/guarded/errors.js

@@ -0,0 +1,20 @@
+import { defaultPlatformMessages } from "../../messages.js";
+/** A pre-connect policy decision; callerSafeMessage never includes resolved private addresses.
+ * Export the refusal class so tool/HTTP boundaries can recognize a policy decision with instanceof
+ * instead of fragile message matching. A caller can correct a refused target; DNS failures and
+ * timeouts are operational failures. Reporting a policy refusal as an internal crash hides that fix.
+ * The full message is for server audit/logs. Only callerSafeMessage belongs at an external boundary:
+ * exposing resolved private addresses would let callers enumerate internal DNS one request at a time.
+ * Public address classifications remain actionable without revealing deployment-specific IPs.
+ * The safe message defaults to a generic refusal, never the full message, so omitted redaction fails
+ * toward disclosing less. Recognition of this class grants no access to an unguarded transport.
+ */
+export class EgressRefusedError extends Error {
+    callerSafeMessage;
+    constructor({ message }, { callerSafeMessage, messages = defaultPlatformMessages } = {}) {
+        super(message);
+        this.name = "EgressRefusedError";
+        this.callerSafeMessage = callerSafeMessage ?? messages.egressRefused();
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/http/guarded/fetch-adapter.d.ts

@@ -0,0 +1,23 @@
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { HttpRequest, RequestRedirect } from "@jini-ai/core/primitives";
+export interface GuardedFetchOptions {
+    method?: HttpRequest["method"];
+    headers?: ConstructorParameters<typeof Headers>[0];
+    body?: string | URLSearchParams;
+    signal?: AbortSignal;
+    redirect?: RequestRedirect;
+    /** Override the legacy timeoutMs socket idle budget. */
+    idleTimeoutMs?: number;
+    /** Optional deadline over DNS, redirects and the complete decoded body. */
+    totalDeadlineMs?: number;
+}
+/** Projects guarded, complete decoded bytes into a Response for SDK/OAuth adapters.
+ * Defaults to redirect refusal. Hosts adapt their SDK's positional fetch signature to this object API.
+ * Strings and form bodies are supported; streaming uploads need a different transport contract.
+ */
+export declare function guardedFetch({ client, url, timeoutMs }: {
+    client: HttpClientPort;
+    url: string;
+    timeoutMs: number;
+}, { method, headers, body, signal, redirect, idleTimeoutMs, totalDeadlineMs }?: GuardedFetchOptions): Promise<Response>;
+//# sourceMappingURL=fetch-adapter.d.ts.map

package/dist/http/guarded/fetch-adapter.js

@@ -0,0 +1,30 @@
+/** Projects guarded, complete decoded bytes into a Response for SDK/OAuth adapters.
+ * Defaults to redirect refusal. Hosts adapt their SDK's positional fetch signature to this object API.
+ * Strings and form bodies are supported; streaming uploads need a different transport contract.
+ */
+export async function guardedFetch({ client, url, timeoutMs }, { method = "GET", headers = {}, body, signal, redirect = "error", idleTimeoutMs, totalDeadlineMs } = {}) {
+    const response = await client.send({ request: {
+            method, url, timeoutMs, headers: Object.fromEntries(new Headers(headers).entries()),
+            ...(body === undefined ? {} : { body: String(body) }),
+            ...(signal === undefined ? {} : { signal }),
+            ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+            ...(totalDeadlineMs === undefined ? {} : { totalDeadlineMs }),
+        } }, { redirect });
+    const truncated = response.bodyBytes === undefined
+        ? response.bodyTruncated : response.bodyBytesTruncated ?? response.bodyTruncated;
+    if (truncated)
+        throw new Error("guarded response was truncated by the byte policy");
+    const resultHeaders = new Headers(response.headers);
+    resultHeaders.delete("content-encoding");
+    resultHeaders.delete("content-length");
+    if (response.setCookies !== undefined) {
+        resultHeaders.delete("set-cookie");
+        for (const cookie of response.setCookies)
+            resultHeaders.append("set-cookie", cookie);
+    }
+    const bytes = response.bodyBytes === undefined ? response.bodyText : Buffer.from(response.bodyBytes);
+    // Fetch prohibits bodies for HEAD and these statuses, even when a transport supplies an empty buffer.
+    const bodyless = method === "HEAD" || [204, 205, 304].includes(response.status);
+    return new Response(bodyless ? null : bytes, { status: response.status, headers: resultHeaders });
+}
+//# sourceMappingURL=fetch-adapter.js.map

package/dist/http/guarded/index.d.ts

@@ -0,0 +1,12 @@
+export { createHttpClient, classifyAddress } from "./client.js";
+export type { AddressClass } from "./client.js";
+export { EgressRefusedError } from "./errors.js";
+export { FetchHttpTransportAdapter } from "./transport.fetch.js";
+export { createNodeGuardedHttpPorts } from "./node-ports.js";
+export { guardedFetch } from "./fetch-adapter.js";
+export type { GuardedFetchOptions } from "./fetch-adapter.js";
+export type * from "./types.js";
+export type * from "./ports.js";
+export { defaultPlatformMessages } from "../../messages.js";
+export type { PlatformMessages } from "../../messages.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/http/guarded/index.js

@@ -0,0 +1,7 @@
+export { createHttpClient, classifyAddress } from "./client.js";
+export { EgressRefusedError } from "./errors.js";
+export { FetchHttpTransportAdapter } from "./transport.fetch.js";
+export { createNodeGuardedHttpPorts } from "./node-ports.js";
+export { guardedFetch } from "./fetch-adapter.js";
+export { defaultPlatformMessages } from "../../messages.js";
+//# sourceMappingURL=index.js.map

package/dist/http/guarded/node-ports.d.ts

@@ -0,0 +1,8 @@
+import type { GuardedClock, DnsResolver, PinnedHttpTransport } from "./ports.js";
+/** Constructs native effect ports without resolving or connecting to any destination. */
+export declare function createNodeGuardedHttpPorts(_required: Record<string, never>): {
+    dns: DnsResolver;
+    clock: GuardedClock;
+    transport: PinnedHttpTransport;
+};
+//# sourceMappingURL=node-ports.d.ts.map

package/dist/http/guarded/node-ports.js

@@ -0,0 +1,11 @@
+import { lookup } from "node:dns/promises";
+import { FetchHttpTransportAdapter } from "./transport.fetch.js";
+/** Constructs native effect ports without resolving or connecting to any destination. */
+export function createNodeGuardedHttpPorts(_required) {
+    return {
+        dns: { resolve: async ({ hostname }) => (await lookup(hostname, { all: true, verbatim: true })).map(entry => entry.address) },
+        clock: { nowMs: () => Date.now(), timeoutSignal: ({ timeoutMs }) => AbortSignal.timeout(timeoutMs) },
+        transport: new FetchHttpTransportAdapter({}),
+    };
+}
+//# sourceMappingURL=node-ports.js.map

package/dist/http/guarded/ports.d.ts

@@ -0,0 +1,51 @@
+import type { Clock, HttpRequest, HttpResponse } from "@jini-ai/core/primitives";
+import type { PinnedPeer } from "./types.js";
+export type { PinnedPeer } from "./types.js";
+/** Resolver returns every peer address; a mixed public/private answer is refused as a whole. */
+export interface DnsResolver {
+    resolve(required: {
+        hostname: string;
+    }): Promise<readonly string[]>;
+}
+/** Supplies time and deadline cancellation without a global timer dependency in the guard. */
+export type GuardedClock = Clock & {
+    timeoutSignal(required: {
+        timeoutMs: number;
+    }): AbortSignal;
+};
+/** Transport must dial the supplied IP, preserve authority/SNI, bound decoded bytes,
+ * enforce idleTimeoutMs per socket, and honor request.signal through body completion. */
+export interface PinnedHttpTransport {
+    requestPinned(required: {
+        request: HttpRequest;
+        peer: PinnedPeer;
+    }): Promise<HttpResponse>;
+}
+export type HttpTransportAdapter = PinnedHttpTransport;
+/** Policy must cover IPv4 and IPv6, mapped-address/hostname normalization, URL credentials and
+ * redirects. Re-verify each redirected peer and strip sensitive headers across origins. */
+export interface EgressPolicy {
+    readonly allowedSchemes: readonly string[];
+    readonly denyPrivateAddresses: boolean;
+    /** Explicit development capability; IPv6 literals use their bracket-free hostname (e.g. fd00::1). */
+    readonly devHostAllowlist: readonly string[];
+    readonly maxRedirects: number;
+    /** Historical name: ceiling on each socket's idle timeout, not total transfer time. */
+    readonly connectTimeoutMs: number;
+    readonly maxResponseBytes: number;
+    readonly maxDecompressedBytes: number;
+    /** Reserved descriptor, not an implemented pacing mechanism. Untrusted fan-out requires a host
+     * concurrency/budget limiter; omission is appropriate only for trusted low-fan-out callers. */
+    readonly rateLimit?: {
+        readonly maxConcurrent: number;
+        readonly maxPerMinute: number;
+    };
+}
+export type GuardedHttpRequired = {
+    transport: PinnedHttpTransport;
+    policy: EgressPolicy;
+    dns: DnsResolver;
+    clock: GuardedClock;
+    userAgent: string;
+};
+//# sourceMappingURL=ports.d.ts.map

package/dist/http/guarded/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/http/guarded/transport.fetch.d.ts

@@ -0,0 +1,11 @@
+import type { HttpRequest, HttpResponse } from "@jini-ai/core/primitives";
+import type { PinnedPeer } from "./types.js";
+import type { HttpTransportAdapter } from "./ports.js";
+export declare class FetchHttpTransportAdapter implements HttpTransportAdapter {
+    constructor(_required: Record<string, never>);
+    requestPinned({ request: req, peer }: {
+        request: HttpRequest;
+        peer: PinnedPeer;
+    }): Promise<HttpResponse>;
+}
+//# sourceMappingURL=transport.fetch.d.ts.map

package/dist/http/guarded/transport.fetch.js

@@ -0,0 +1,109 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+/**
+ * Dial only the policy-vetted IP, never re-resolve the URL hostname: otherwise DNS rebinding
+ * could change the destination between validation and connection. Preserve the original Host
+ * authority and hostname TLS SNI for virtual hosting and certificate validation.
+ * This raw transport belongs behind the guarded client, which validates each redirect hop.
+ * Responses are buffered; the absolute ceiling bounds memory even without a caller byte limit.
+ */
+/** Last-resort decoded-byte bound independent of any caller's response policy. */
+const ABSOLUTE_MAX_BYTES = 100 * 1024 * 1024;
+export class FetchHttpTransportAdapter {
+    constructor(_required) { }
+    async requestPinned({ request: req, peer }) {
+        const url = new URL(req.url);
+        const isHttps = url.protocol === "https:";
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        const idleTimeoutMs = req.idleTimeoutMs ?? req.timeoutMs;
+        const options = {
+            method: req.method,
+            host: peer.ip,
+            port: peer.port,
+            path: `${url.pathname}${url.search}`,
+            headers: { ...req.headers, host: peer.authority },
+            // Node's timeout is per-socket inactivity, including the response body. Do not
+            // replace it with a timer over total transfer time: active large bodies can be slow.
+            timeout: idleTimeoutMs,
+            ...(req.signal ? { signal: req.signal } : {}),
+            // RFC 6066 forbids IP-literal SNI. Omit the option entirely when no hostname is supplied.
+            ...(isHttps && peer.tlsServerName ? { servername: peer.tlsServerName } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const clientRequest = requestFn(options, (res) => {
+                // HEAD can advertise GET's compression but has no body to decompress.
+                const decoded = req.method === "HEAD" ? res : decodeBody(res.headers["content-encoding"], res);
+                const chunks = [];
+                let totalBytes = 0;
+                let settled = false;
+                const finish = (truncated) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    // Concatenate once: text is a lossy UTF-8 view, while binary consumers retain the same
+                    // undecoded bytes. Buffer is a Uint8Array, so returning it needs no second byte copy.
+                    const body = Buffer.concat(chunks);
+                    resolve({
+                        status: res.statusCode ?? 0,
+                        headers: flattenHeaders(res.headers),
+                        setCookies: res.headers["set-cookie"] ?? [],
+                        bodyText: body.toString("utf8"), bodyBytes: body,
+                        ...(truncated ? { bodyTruncated: true, bodyBytesTruncated: true } : {}),
+                    });
+                };
+                const cap = req.maxResponseBytes === undefined ? ABSOLUTE_MAX_BYTES : Math.min(req.maxResponseBytes, ABSOLUTE_MAX_BYTES);
+                decoded.on("data", (chunk) => {
+                    if (settled)
+                        return;
+                    const remaining = cap - totalBytes;
+                    if (chunk.length > remaining) {
+                        if (req.maxResponseBytes === undefined) {
+                            clientRequest.destroy(new Error("response exceeded the absolute size ceiling"));
+                            return;
+                        }
+                        chunks.push(chunk.subarray(0, remaining));
+                        finish(true);
+                        decoded.destroy?.();
+                        res.destroy();
+                        clientRequest.destroy();
+                        return;
+                    }
+                    totalBytes += chunk.length;
+                    chunks.push(chunk);
+                });
+                decoded.on("end", () => finish(false));
+                decoded.on("error", reject);
+            });
+            clientRequest.on("timeout", () => {
+                clientRequest.destroy(new Error(`request timed out after ${idleTimeoutMs}ms`));
+            });
+            clientRequest.on("error", reject);
+            if (req.body !== undefined)
+                clientRequest.write(req.body);
+            clientRequest.end();
+        });
+    }
+}
+function decodeBody(contentEncoding, stream) {
+    switch (contentEncoding) {
+        case "gzip":
+            return stream.pipe(createGunzip());
+        case "deflate":
+            return stream.pipe(createInflate());
+        case "br":
+            return stream.pipe(createBrotliDecompress());
+        default:
+            return stream;
+    }
+}
+function flattenHeaders(headers) {
+    const flat = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        flat[key] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return flat;
+}
+//# sourceMappingURL=transport.fetch.js.map

package/dist/http/guarded/types.d.ts

@@ -0,0 +1,8 @@
+export interface PinnedPeer {
+    ip: string;
+    port: number;
+    authority: string;
+    /** RFC 6066 permits hostnames in SNI, never IP literals. Undefined means omit the extension. */
+    tlsServerName: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/http/guarded/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map