@husk-ai/core 0.1.1

package/dist/net.js

@@ -0,0 +1,219 @@
+import { HuskError } from './errors.js';
+/**
+ * Network policy, in one place.
+ *
+ * This lived in three copies -- `@husk-ai/runtime`, `@husk-ai/agent`, and by
+ * implication the docs -- and they drifted: one blocked the cloud metadata
+ * endpoint in `mode: 'full'` and one did not. A security check with two answers
+ * is not a security check, so it lives here and everything re-exports it.
+ */
+/** Match a hostname against one pattern. Supports a single leading `*.` wildcard. */
+export function hostMatches(host, pattern) {
+    const h = host.toLowerCase().replace(/\.$/, '');
+    const p = pattern.toLowerCase().replace(/\.$/, '');
+    if (p === '*')
+        return true;
+    if (p.startsWith('*.')) {
+        const suffix = p.slice(1); // ".example.com"
+        return h.endsWith(suffix) && h.length > suffix.length;
+    }
+    return h === p;
+}
+/**
+ * Hosts that are never reachable by default, whatever the mode says.
+ *
+ * `mode: 'full'` means "the internet", not "and also the cloud metadata
+ * service". 169.254.169.254 hands out IAM credentials to anything that asks,
+ * and a prompt-injected agent will ask. Loopback and the RFC1918 ranges are the
+ * same problem one hop out: the host's own admin panels, and the LAN.
+ *
+ * An operator who genuinely wants one of these names it in `allow`, where a
+ * reviewer reading the husk.yaml can see the decision.
+ */
+/**
+ * Normalise the many spellings of one IPv4 address.
+ *
+ * `127.1`, `2130706433` and `0x7f000001` are all `127.0.0.1` to every resolver
+ * that matters -- curl, the browser, and Python's urllib all accept them --
+ * and a rule that only understands four dotted octets waves each of them
+ * through. Measured: `isInternalHost('127.1')` returned false while
+ * `isInternalHost('127.0.0.1')` returned true.
+ *
+ * Returns the four octets, or null when this is not an IPv4 literal at all.
+ */
+function ipv4Octets(host) {
+    const parts = host.split('.');
+    if (parts.length > 4 || parts.some((p) => p === ''))
+        return null;
+    // Each part may be decimal, octal (leading zero) or hex (0x). inet_aton
+    // accepts all three, so refusing to understand them is not a defence.
+    const nums = [];
+    for (const part of parts) {
+        let value;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            value = parseInt(part, 16);
+        else if (/^0[0-7]+$/.test(part))
+            value = parseInt(part, 8);
+        else if (/^[0-9]+$/.test(part))
+            value = Number(part);
+        else
+            return null;
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+        nums.push(value);
+    }
+    // The last part absorbs the remaining octets: `127.1` is 127.0.0.1 and
+    // `2130706433` is the whole address in one number.
+    const last = nums.pop();
+    if (last === undefined)
+        return null;
+    const width = 4 - nums.length;
+    if (last >= 256 ** width)
+        return null;
+    if (nums.some((n) => n > 255))
+        return null;
+    const tail = [];
+    for (let i = width - 1; i >= 0; i--)
+        tail.push((last >>> (8 * i)) & 0xff);
+    const all = [...nums, ...tail];
+    return all.length === 4 ? all : null;
+}
+export function isInternalHost(host) {
+    const h = host.toLowerCase().replace(/\.$/, '').replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.local'))
+        return true;
+    if (h.endsWith('.internal') || h === 'metadata.google.internal')
+        return true;
+    if (h === '::1' || h === '0:0:0:0:0:0:0:1')
+        return true;
+    if (/^f[cd][0-9a-f]{2}:/.test(h) || /^fe80:/.test(h))
+        return true;
+    const v4 = ipv4Octets(h);
+    if (v4) {
+        const a = v4[0];
+        const b = v4[1];
+        if (a === 127 || a === 0 || a === 10)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, incl. the metadata endpoint
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+    }
+    return false;
+}
+/** Loopback specifically, as distinct from the rest of the private ranges. */
+export function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/\.$/, '').replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h.endsWith('.localhost'))
+        return true;
+    if (h === '::1' || h === '0:0:0:0:0:0:0:1')
+        return true;
+    const v4 = ipv4Octets(h);
+    return v4 !== null && (v4[0] === 127 || v4[0] === 0);
+}
+/**
+ * Providers where the computer has its own network namespace.
+ *
+ * On these, `127.0.0.1` inside the computer is the computer, so an agent can
+ * start a server and look at it -- the most common thing it will ever want to
+ * do. On `local` that address is the host's own loopback, and on `ssh` it
+ * belongs to a box the user may be running things on, so neither qualifies.
+ *
+ * This lives here, beside `isHostAllowed`, because it is the same policy
+ * question and it had already been copied into three files. `net.ts` exists to
+ * be the one answer: the last time this rule had two copies, they disagreed
+ * about whether `mode: 'full'` could reach the cloud metadata endpoint.
+ */
+const OWNS_LOOPBACK = new Set(['docker', 'podman', 'fly']);
+/** Whether this provider's loopback belongs to the computer rather than the host. */
+export function ownsLoopback(provider) {
+    return OWNS_LOOPBACK.has(provider);
+}
+/**
+ * Whether the computer shares a network stack with whoever is running husk.
+ *
+ * The inverse of {@link ownsLoopback}, named for the thing a caller usually
+ * wants to warn about.
+ */
+export function sharesHostNetwork(provider) {
+    return !OWNS_LOOPBACK.has(provider);
+}
+export function isHostAllowed(host, policy, ctx = {}) {
+    const explicitlyAllowed = (policy?.allow ?? []).some((p) => hostMatches(host, p));
+    // The floor is checked before the mode, so `full` cannot reach the metadata
+    // service. Loopback is carved out of it when the computer owns its own.
+    if (!explicitlyAllowed) {
+        if (isLoopbackHost(host)) {
+            if (!ctx.loopbackIsOwn)
+                return false;
+        }
+        else if (isInternalHost(host)) {
+            return false;
+        }
+    }
+    if (!policy)
+        return true;
+    if (policy.deny?.some((p) => hostMatches(host, p)))
+        return false;
+    switch (policy.mode) {
+        case 'none':
+            return false;
+        case 'full':
+            return true;
+        case 'egress':
+            // An egress policy with no allow-list allows nothing. Reading it as
+            // "unrestricted" would be the dangerous interpretation.
+            return explicitlyAllowed;
+    }
+}
+/** The hostname of a URL, or null when it does not parse. */
+export function urlHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse and authorise a URL in one step.
+ *
+ * Returns the parsed URL so a caller cannot accidentally check one string and
+ * then fetch a different one.
+ */
+export function assertUrlAllowed(url, policy, ctx = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new HuskError('E_EXEC_DENIED', `not a valid URL: ${url}`, {
+            hint: 'include the scheme, e.g. https://example.com',
+        });
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new HuskError('E_EXEC_DENIED', `refusing the ${parsed.protocol} scheme`, {
+            hint: 'only http and https are fetched; file:// would read the host filesystem',
+        });
+    }
+    if (!isHostAllowed(parsed.hostname, policy, ctx)) {
+        const loopback = isLoopbackHost(parsed.hostname);
+        const internal = isInternalHost(parsed.hostname);
+        throw new HuskError('E_EXEC_DENIED', `network policy refuses ${parsed.hostname}`, {
+            hint: loopback && !ctx.loopbackIsOwn
+                ? 'on this provider loopback is the host machine, not the computer -- use an isolated ' +
+                    'provider (docker, podman, fly) to reach a server the agent started, or name the ' +
+                    'host in computer.network.allow'
+                : internal
+                    ? 'link-local and RFC1918 hosts must be named in computer.network.allow'
+                    : `add it to computer.network.allow, or set computer.network.mode: full`,
+            details: { host: parsed.hostname, mode: policy?.mode ?? 'unset', internal, loopback },
+        });
+    }
+    return parsed;
+}
+//# sourceMappingURL=net.js.map

package/dist/net.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.js","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"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"}