@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/security/ssrf.d.ts

@@ -0,0 +1,79 @@
+/** Who can safely reach a URL's host. */
+export declare const UrlReachability: {
+    /** Publicly routable — safe to hand to a third party to fetch itself. */
+    readonly PUBLIC: "public";
+    /**
+     * Within a trusted private network — safe for this server to fetch
+     * directly, but not to hand off to a third party that can't reach it.
+     */
+    readonly ALLOWED: "allowed";
+    /** Nobody should fetch it. */
+    readonly BLOCKED: "blocked";
+};
+export type UrlReachability = (typeof UrlReachability)[keyof typeof UrlReachability];
+/** A parsed IP address: its version and its value as a bigint. */
+export interface IPAddress {
+    version: 4 | 6;
+    value: bigint;
+}
+/**
+ * Parse an IPv4 or IPv6 address (Python's `ipaddress.ip_address`).
+ *
+ * @throws Error If `text` is not a valid address (upstream: ValueError).
+ */
+export declare function ipAddress(text: string): IPAddress;
+/** An IPv4 or IPv6 network in CIDR form (Python's `IPv4Network | IPv6Network`). */
+export declare class IPNetwork {
+    #private;
+    readonly version: 4 | 6;
+    readonly networkAddress: bigint;
+    readonly prefixlen: number;
+    /**
+     * @param cidr A network such as `"10.0.0.0/8"` or `"fd00::/8"`. A bare
+     *   address is a single-host network. Host bits must be zero, as Python's
+     *   strict default requires.
+     * @throws Error If `cidr` is not a valid network (upstream: ValueError).
+     */
+    constructor(cidr: string);
+    /** Whether `address` lies in this network (Python's `ip in network`). */
+    contains(address: IPAddress): boolean;
+    toString(): string;
+}
+/** Python's `ip_address(...).is_global`. */
+export declare function ipAddressIsGlobal(address: IPAddress): boolean;
+/** Resolve a hostname to its IP addresses (as `getaddrinfo` does). Throw if it fails. */
+export type HostResolver = (hostname: string) => Promise<string[]>;
+/** The default resolver: IP literals as-is, hostnames through `node:dns` if available. */
+export declare const defaultHostResolver: HostResolver;
+/** Install the resolver `classifyUrlReachability` uses. Pass `null` for the default. */
+export declare function setHostResolver(resolver: HostResolver | null): void;
+/**
+ * Return trusted networks from the `PIPECAT_ALLOWED_FILE_URL_NETWORKS` env var.
+ *
+ * Parses a comma-separated list of CIDR ranges (e.g.
+ * `10.0.0.0/8,192.168.0.0/16`). Returns an empty list (trust only the
+ * public internet) when the variable is unset or empty.
+ */
+export declare function defaultAllowedFileUrlNetworks(): string[];
+/**
+ * Classify who can safely reach `url`'s host: the public internet, this server, or no one.
+ *
+ * Resolution happens once, up front; it doesn't defend against a target
+ * that resolves differently between this check and the actual connection
+ * (DNS rebinding).
+ *
+ * @param url The URL to classify.
+ * @param allowedNetworks Private networks this server is trusted to reach
+ *   directly (e.g. where a deployment's own file servers live), beyond the
+ *   public internet.
+ * @returns `PUBLIC` if every resolved address is publicly routable — safe to
+ *   hand to a third party (e.g. an LLM provider) to fetch itself.
+ *   `ALLOWED` if not publicly routable, but every address falls within
+ *   `allowedNetworks` — safe for this server to fetch directly, but not to
+ *   hand off to a third party that can't reach it.
+ *   `BLOCKED` otherwise: loopback, link-local (including the cloud metadata
+ *   range `169.254.0.0/16`), private (RFC 1918), or unique-local (IPv6 ULA)
+ *   addresses outside `allowedNetworks`, or a host that fails to resolve.
+ */
+export declare function classifyUrlReachability(url: string, allowedNetworks?: readonly IPNetwork[]): Promise<UrlReachability>;
+//# sourceMappingURL=ssrf.d.ts.map

package/dist/utils/security/ssrf.js

@@ -0,0 +1,327 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/security/ssrf.py
+/**
+ * Guards against server-side request forgery via client-supplied URLs.
+ *
+ * Porting notes: Python's `ipaddress` module has no JavaScript counterpart, so
+ * this module carries the small part of it it needs (`IPNetwork`,
+ * `ipAddressIsGlobal`). Host resolution goes through a pluggable
+ * `HostResolver`; the default one uses `node:dns` through
+ * `process.getBuiltinModule` where the runtime provides it (Bun, Node, Deno),
+ * and otherwise only resolves IP literals, so a hostname that cannot be
+ * resolved is `BLOCKED`.
+ */
+import { abortable, rethrowIfCancelled } from "@pipedog/asyncio";
+/** Who can safely reach a URL's host. */
+export const UrlReachability = {
+    /** Publicly routable — safe to hand to a third party to fetch itself. */
+    PUBLIC: "public",
+    /**
+     * Within a trusted private network — safe for this server to fetch
+     * directly, but not to hand off to a third party that can't reach it.
+     */
+    ALLOWED: "allowed",
+    /** Nobody should fetch it. */
+    BLOCKED: "blocked",
+};
+function parseIPv4(text) {
+    const parts = text.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0n;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        // Python rejects leading zeros (ambiguous octal).
+        if (part.length > 1 && part.startsWith("0"))
+            return null;
+        const n = Number(part);
+        if (n > 255)
+            return null;
+        value = (value << 8n) | BigInt(n);
+    }
+    return value;
+}
+function parseIPv6(text) {
+    // Drop a scope id ("fe80::1%eth0").
+    const address = text.split("%")[0] ?? "";
+    if (!address.includes(":"))
+        return null;
+    let head = address;
+    let tailV4 = null;
+    const lastColon = address.lastIndexOf(":");
+    const last = address.slice(lastColon + 1);
+    if (last.includes(".")) {
+        tailV4 = parseIPv4(last);
+        if (tailV4 === null)
+            return null;
+        head = `${address.slice(0, lastColon + 1)}0:0`;
+    }
+    const halves = head.split("::");
+    if (halves.length > 2)
+        return null;
+    const parseGroups = (s) => {
+        if (s === "")
+            return [];
+        const groups = [];
+        for (const g of s.split(":")) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+                return null;
+            groups.push(Number.parseInt(g, 16));
+        }
+        return groups;
+    };
+    const left = parseGroups(halves[0] ?? "");
+    const right = halves.length === 2 ? parseGroups(halves[1] ?? "") : [];
+    if (left === null || right === null)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const missing = 8 - left.length - right.length;
+        if (missing < 1)
+            return null;
+        groups = [...left, ...new Array(missing).fill(0), ...right];
+    }
+    else {
+        groups = left;
+    }
+    if (groups.length !== 8)
+        return null;
+    let value = 0n;
+    for (const g of groups)
+        value = (value << 16n) | BigInt(g);
+    if (tailV4 !== null)
+        value = (value & ~0xffffffffn) | tailV4;
+    return value;
+}
+/**
+ * Parse an IPv4 or IPv6 address (Python's `ipaddress.ip_address`).
+ *
+ * @throws Error If `text` is not a valid address (upstream: ValueError).
+ */
+export function ipAddress(text) {
+    const v4 = parseIPv4(text);
+    if (v4 !== null)
+        return { version: 4, value: v4 };
+    const v6 = parseIPv6(text);
+    if (v6 !== null)
+        return { version: 6, value: v6 };
+    throw new Error(`'${text}' does not appear to be an IPv4 or IPv6 address`);
+}
+/** An IPv4 or IPv6 network in CIDR form (Python's `IPv4Network | IPv6Network`). */
+export class IPNetwork {
+    version;
+    networkAddress;
+    prefixlen;
+    #mask;
+    /**
+     * @param cidr A network such as `"10.0.0.0/8"` or `"fd00::/8"`. A bare
+     *   address is a single-host network. Host bits must be zero, as Python's
+     *   strict default requires.
+     * @throws Error If `cidr` is not a valid network (upstream: ValueError).
+     */
+    constructor(cidr) {
+        const [addressText, prefixText] = cidr.trim().split("/");
+        const address = ipAddress(addressText ?? "");
+        const bits = address.version === 4 ? 32 : 128;
+        const prefixlen = prefixText === undefined ? bits : Number(prefixText);
+        if (!Number.isInteger(prefixlen) || prefixlen < 0 || prefixlen > bits) {
+            throw new Error(`'${cidr}' does not appear to be an IPv4 or IPv6 network`);
+        }
+        const all = (1n << BigInt(bits)) - 1n;
+        const mask = (all << BigInt(bits - prefixlen)) & all;
+        if ((address.value & mask) !== address.value) {
+            throw new Error(`${cidr} has host bits set`);
+        }
+        this.version = address.version;
+        this.networkAddress = address.value;
+        this.prefixlen = prefixlen;
+        this.#mask = mask;
+    }
+    /** Whether `address` lies in this network (Python's `ip in network`). */
+    contains(address) {
+        return address.version === this.version && (address.value & this.#mask) === this.networkAddress;
+    }
+    toString() {
+        return `${formatAddress({ version: this.version, value: this.networkAddress })}/${this.prefixlen}`;
+    }
+}
+function formatAddress(address) {
+    if (address.version === 4) {
+        const v = address.value;
+        return [24n, 16n, 8n, 0n].map((s) => ((v >> s) & 0xffn).toString()).join(".");
+    }
+    const groups = [];
+    for (let s = 112n; s >= 0n; s -= 16n)
+        groups.push(((address.value >> s) & 0xffffn).toString(16));
+    return groups.join(":");
+}
+// The IANA special-purpose registries, as Python's `ipaddress` lists them.
+const IPV4_PRIVATE = [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.0.0.0/29",
+    "192.0.0.170/31",
+    "192.0.2.0/24",
+    "192.168.0.0/16",
+    "198.18.0.0/15",
+    "198.51.100.0/24",
+    "203.0.113.0/24",
+    "240.0.0.0/4",
+    "255.255.255.255/32",
+].map((n) => new IPNetwork(n));
+const IPV4_PRIVATE_EXCEPTIONS = ["192.0.0.9/32", "192.0.0.10/32"].map((n) => new IPNetwork(n));
+const IPV4_SHARED_ADDRESS_SPACE = new IPNetwork("100.64.0.0/10");
+const IPV6_PRIVATE = [
+    "::1/128",
+    "::/128",
+    "::ffff:0:0/96",
+    "64:ff9b:1::/48",
+    "100::/64",
+    "2001::/23",
+    "2001:db8::/32",
+    "2002::/16",
+    "3fff::/20",
+    "fc00::/7",
+    "fe80::/10",
+].map((n) => new IPNetwork(n));
+const IPV6_PRIVATE_EXCEPTIONS = [
+    "2001:1::1/128",
+    "2001:1::2/128",
+    "2001:3::/32",
+    "2001:4:112::/48",
+    "2001:20::/28",
+    "2001:30::/28",
+].map((n) => new IPNetwork(n));
+const IPV4_MAPPED = new IPNetwork("::ffff:0:0/96");
+/** Python's `ip_address(...).is_global`. */
+export function ipAddressIsGlobal(address) {
+    if (address.version === 4) {
+        const isPrivate = IPV4_PRIVATE.some((n) => n.contains(address)) &&
+            !IPV4_PRIVATE_EXCEPTIONS.some((n) => n.contains(address));
+        return !IPV4_SHARED_ADDRESS_SPACE.contains(address) && !isPrivate;
+    }
+    // An IPv4-mapped address is judged by the IPv4 address it carries.
+    if (IPV4_MAPPED.contains(address)) {
+        return ipAddressIsGlobal({ version: 4, value: address.value & 0xffffffffn });
+    }
+    const isPrivate = IPV6_PRIVATE.some((n) => n.contains(address)) &&
+        !IPV6_PRIVATE_EXCEPTIONS.some((n) => n.contains(address));
+    return !isPrivate;
+}
+function nodeDns() {
+    const proc = globalThis.process;
+    try {
+        return proc?.getBuiltinModule?.("node:dns")?.promises ?? null;
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        return null;
+    }
+}
+/** The default resolver: IP literals as-is, hostnames through `node:dns` if available. */
+export const defaultHostResolver = async (hostname) => {
+    try {
+        ipAddress(hostname);
+        return [hostname];
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+    }
+    const dns = nodeDns();
+    if (!dns) {
+        throw new Error(`no DNS resolver available to resolve '${hostname}'`);
+    }
+    const infos = await abortable(dns.lookup(hostname, { all: true }));
+    return infos.map((info) => info.address);
+};
+let hostResolver = defaultHostResolver;
+/** Install the resolver `classifyUrlReachability` uses. Pass `null` for the default. */
+export function setHostResolver(resolver) {
+    hostResolver = resolver ?? defaultHostResolver;
+}
+function getenv(name) {
+    return globalThis.process?.env?.[name];
+}
+/**
+ * Return trusted networks from the `PIPECAT_ALLOWED_FILE_URL_NETWORKS` env var.
+ *
+ * Parses a comma-separated list of CIDR ranges (e.g.
+ * `10.0.0.0/8,192.168.0.0/16`). Returns an empty list (trust only the
+ * public internet) when the variable is unset or empty.
+ */
+export function defaultAllowedFileUrlNetworks() {
+    const val = getenv("PIPECAT_ALLOWED_FILE_URL_NETWORKS") ?? "";
+    return val
+        .split(",")
+        .map((n) => n.trim())
+        .filter((n) => n);
+}
+function urlHostname(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        return null;
+    }
+    let hostname = parsed.hostname;
+    // `URL` keeps the brackets around IPv6 literals; `urlsplit` does not.
+    if (hostname.startsWith("[") && hostname.endsWith("]")) {
+        hostname = hostname.slice(1, -1);
+    }
+    return hostname ? hostname.toLowerCase() : null;
+}
+/**
+ * Classify who can safely reach `url`'s host: the public internet, this server, or no one.
+ *
+ * Resolution happens once, up front; it doesn't defend against a target
+ * that resolves differently between this check and the actual connection
+ * (DNS rebinding).
+ *
+ * @param url The URL to classify.
+ * @param allowedNetworks Private networks this server is trusted to reach
+ *   directly (e.g. where a deployment's own file servers live), beyond the
+ *   public internet.
+ * @returns `PUBLIC` if every resolved address is publicly routable — safe to
+ *   hand to a third party (e.g. an LLM provider) to fetch itself.
+ *   `ALLOWED` if not publicly routable, but every address falls within
+ *   `allowedNetworks` — safe for this server to fetch directly, but not to
+ *   hand off to a third party that can't reach it.
+ *   `BLOCKED` otherwise: loopback, link-local (including the cloud metadata
+ *   range `169.254.0.0/16`), private (RFC 1918), or unique-local (IPv6 ULA)
+ *   addresses outside `allowedNetworks`, or a host that fails to resolve.
+ */
+export async function classifyUrlReachability(url, allowedNetworks = []) {
+    const hostname = urlHostname(url);
+    if (!hostname) {
+        return UrlReachability.BLOCKED;
+    }
+    let addresses;
+    try {
+        addresses = await hostResolver(hostname);
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        return UrlReachability.BLOCKED;
+    }
+    if (addresses.length === 0) {
+        return UrlReachability.BLOCKED;
+    }
+    const ips = addresses.map((a) => ipAddress(a));
+    if (ips.every((ip) => ipAddressIsGlobal(ip))) {
+        return UrlReachability.PUBLIC;
+    }
+    if (ips.every((ip) => ipAddressIsGlobal(ip) || allowedNetworks.some((network) => network.contains(ip)))) {
+        return UrlReachability.ALLOWED;
+    }
+    return UrlReachability.BLOCKED;
+}
+//# sourceMappingURL=ssrf.js.map

package/dist/utils/shared.d.ts

@@ -0,0 +1,35 @@
+type AsyncMethod<This, A extends unknown[], T> = (this: This, ...args: A) => Promise<T>;
+/**
+ * Run the decorated method for the first owner to acquire `name`.
+ *
+ * Owners that arrive while the first is still running wait for it to finish,
+ * so no caller continues against a half-built resource. Later owners return
+ * `null` without running the method again.
+ *
+ * A method that throws leaves the resource unbuilt, and every owner of it is
+ * told: the error is re-thrown to each one that arrives later, rather than the
+ * method being attempted again. So the owners of a resource share its verdict,
+ * and a pair of processors sharing a client either both come up or both fail.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that acquires the same resource.
+ *
+ * @param name The resource being acquired. Names are per instance, so paired
+ *   operations on the same object (e.g. `setup`/`cleanup` and `join`/`leave`)
+ *   count their owners separately.
+ */
+export declare function acquires(name: string): <This extends object, A extends unknown[], T>(func: AsyncMethod<This, A, T>, _context?: unknown) => AsyncMethod<This, A, T | null>;
+/**
+ * Run the decorated method for the last owner to release `name`.
+ *
+ * Every other owner returns `null`, as does a release that no acquire
+ * matched.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that releases the same resource.
+ *
+ * @param name The resource being released, matching the `acquires` name.
+ */
+export declare function releases(name: string): <This extends object, A extends unknown[], T>(func: AsyncMethod<This, A, T>, _context?: unknown) => AsyncMethod<This, A, T | null>;
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/utils/shared.js

@@ -0,0 +1,136 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/shared.py
+/**
+ * Decorators for operations on a resource shared by several owners.
+ *
+ * An input and an output transport share a single client, so both set it up,
+ * both join its room, and both tear it down. Processors are set up and cleaned
+ * up concurrently, so those calls overlap.
+ *
+ * Decorate the paired operations with `acquires` and `releases` and the work
+ * runs once: the first owner to acquire runs the body while the rest wait for
+ * it, and only the last owner to release runs the undo.
+ *
+ * The returned decorators work both as standard (TC39) method decorators and
+ * as plain functions, since runtimes that strip types (Node) do not run
+ * decorator syntax:
+ *
+ * @example
+ * class Client {
+ *   async setup(): Promise<void> { ... }
+ *   async cleanup(): Promise<void> { ... }
+ *   static {
+ *     this.prototype.setup = acquires("client")(this.prototype.setup);
+ *     this.prototype.cleanup = releases("client")(this.prototype.cleanup);
+ *   }
+ * }
+ */
+import { Lock } from "@pipedog/asyncio";
+/** How many owners hold a resource, and the lock serializing them. */
+class SharedResource {
+    owners = 0;
+    lock = new Lock();
+    // What acquiring raised, if it did, so later owners fail the same way.
+    error = null;
+    hasError = false;
+}
+// Upstream keeps the state in the instance's `__dict__`; a WeakMap keeps it
+// per instance without touching the object.
+const RESOURCES = new WeakMap();
+/**
+ * Get the named resource's state, creating it on first use.
+ *
+ * The state lives with the instance so a class doesn't need to initialize it,
+ * and so two instances of the same class count their owners separately.
+ */
+function sharedResource(obj, name) {
+    let resources = RESOURCES.get(obj);
+    if (!resources) {
+        resources = new Map();
+        RESOURCES.set(obj, resources);
+    }
+    let resource = resources.get(name);
+    if (!resource) {
+        resource = new SharedResource();
+        resources.set(name, resource);
+    }
+    return resource;
+}
+/**
+ * Run the decorated method for the first owner to acquire `name`.
+ *
+ * Owners that arrive while the first is still running wait for it to finish,
+ * so no caller continues against a half-built resource. Later owners return
+ * `null` without running the method again.
+ *
+ * A method that throws leaves the resource unbuilt, and every owner of it is
+ * told: the error is re-thrown to each one that arrives later, rather than the
+ * method being attempted again. So the owners of a resource share its verdict,
+ * and a pair of processors sharing a client either both come up or both fail.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that acquires the same resource.
+ *
+ * @param name The resource being acquired. Names are per instance, so paired
+ *   operations on the same object (e.g. `setup`/`cleanup` and `join`/`leave`)
+ *   count their owners separately.
+ */
+export function acquires(name) {
+    return function decorator(func, _context) {
+        return async function wrapper(...args) {
+            const resource = sharedResource(this, name);
+            return await resource.lock.run(async () => {
+                if (resource.hasError) {
+                    throw resource.error;
+                }
+                resource.owners += 1;
+                if (resource.owners === 1) {
+                    try {
+                        return await func.apply(this, args);
+                    }
+                    catch (e) {
+                        // Nothing was built, so nothing is owned and nothing is released
+                        // later. Upstream catches BaseException, so cancellation counts too.
+                        resource.owners -= 1;
+                        resource.error = e;
+                        resource.hasError = true;
+                        throw e;
+                    }
+                }
+                return null;
+            });
+        };
+    };
+}
+/**
+ * Run the decorated method for the last owner to release `name`.
+ *
+ * Every other owner returns `null`, as does a release that no acquire
+ * matched.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that releases the same resource.
+ *
+ * @param name The resource being released, matching the `acquires` name.
+ */
+export function releases(name) {
+    return function decorator(func, _context) {
+        return async function wrapper(...args) {
+            const resource = sharedResource(this, name);
+            return await resource.lock.run(async () => {
+                if (resource.owners === 0) {
+                    return null;
+                }
+                resource.owners -= 1;
+                if (resource.owners === 0) {
+                    return await func.apply(this, args);
+                }
+                return null;
+            });
+        };
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/utils/startup.d.ts

@@ -0,0 +1,17 @@
+/** Absolute paths of the files listed in `PIPECAT_SETUP_FILES`. */
+export declare function _setupFilePaths(): string[];
+export interface RunSetupHookOptions {
+    /** Object passed to the hook function. */
+    target: unknown;
+    /** Name of the async function to call in each setup file (e.g. `"setup_worker_runner"`). */
+    functionName: string;
+}
+/**
+ * Run `functionName(target)` from every `PIPECAT_SETUP_FILES` module.
+ *
+ * @param options.target Object passed to the hook function.
+ * @param options.functionName Name of the async function to call in each
+ *   setup file. Its camelCase spelling is accepted too.
+ */
+export declare function runSetupHook(options: RunSetupHookOptions): Promise<void>;
+//# sourceMappingURL=startup.d.ts.map