@alexkroman1/aai 1.1.0 → 1.2.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @alexkroman1/aai@1.1.0 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.2.1 build /home/runner/work/agent/agent/packages/aai
 > tsdown && tsc -p tsconfig.build.json
 
 ℹ tsdown v0.21.7 powered by rolldown v1.0.0-rc.12
@@ -9,12 +9,12 @@
 ℹ tsconfig: tsconfig.json
 ℹ Build start
 ℹ dist/host/runtime-barrel.js       50.02 kB │ gzip: 15.70 kB
+ℹ dist/index.js                      6.38 kB │ gzip:  2.49 kB
 ℹ dist/sdk/protocol.js               4.75 kB │ gzip:  1.76 kB
-ℹ dist/index.js                      2.49 kB │ gzip:  1.04 kB
 ℹ dist/sdk/manifest-barrel.js        0.26 kB │ gzip:  0.17 kB
 ℹ dist/constants-VTFoymJ-.js         2.75 kB │ gzip:  1.23 kB
 ℹ dist/_internal-types-CoDTiBd1.js   2.33 kB │ gzip:  0.99 kB
 ℹ dist/types-Cfx_4QDK.js             1.74 kB │ gzip:  0.93 kB
 ℹ dist/ws-upgrade-BeOQ7fXL.js        1.14 kB │ gzip:  0.54 kB
-ℹ 8 files, total: 65.47 kB
-✔ Build complete in 51ms
+ℹ 8 files, total: 69.36 kB
+✔ Build complete in 39ms

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @alexkroman1/aai
 
+## 1.2.1
+
+### Patch Changes
+
+- 7af69b8: Fix gVisor/Deno binary discovery in distroless Docker images
+
+## 1.2.0
+
+### Minor Changes
+
+- ed0dfbb: Add allowedHosts manifest field and host-proxied fetch for sandbox agents
+
+### Patch Changes
+
+- 231ebc1: Fix Docker build (missing unzip, CI=true for pnpm) and add test:adversarial command with CI integration
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * Types, KV interface, utils, and constants used across
  * aai-cli, aai-server, and aai-ui.
  */
+export * from "./sdk/allowed-hosts.ts";
 export * from "./sdk/constants.ts";
 export * from "./sdk/define.ts";
 export * from "./sdk/kv.ts";

package/dist/index.js

@@ -1,6 +1,95 @@
 import { _ as WS_OPEN, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, i as DEFAULT_SESSION_START_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, n as DEFAULT_IDLE_TIMEOUT_MS, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, r as DEFAULT_MAX_HISTORY, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP, u as MAX_MESSAGE_BUFFER_SIZE } from "./constants-VTFoymJ-.js";
 import { i as ToolChoiceSchema, n as DEFAULT_GREETING, r as DEFAULT_SYSTEM_PROMPT, t as BuiltinToolSchema } from "./types-Cfx_4QDK.js";
 import { i as toolError, n as errorDetail, r as errorMessage, t as parseWsUpgradeParams } from "./ws-upgrade-BeOQ7fXL.js";
+//#region sdk/allowed-hosts.ts
+/**
+* Allowlist matching for outbound host validation.
+*
+* Used at deploy time (manifest validation) and at runtime (SSRF enforcement)
+* to restrict which external hosts an agent is permitted to contact.
+*
+* Lives in sdk/ because it has zero Node.js dependencies and can run in any
+* environment (browser, Deno, Node.js sandboxes).
+*/
+/** Private/special-use TLDs that must never appear in allowedHosts patterns. */
+const BLOCKED_TLDS = [
+	"local",
+	"internal",
+	"localhost"
+];
+/**
+* Regex that matches an IPv4 address (four decimal octets separated by dots).
+* Anchored so partial matches like "192.168.1.1.example.com" don't trigger it.
+*/
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+function fail(reason) {
+	return {
+		valid: false,
+		reason
+	};
+}
+function checkStructural(pattern) {
+	if (pattern === "") return fail("Pattern must not be empty.");
+	if (pattern.includes("://")) return fail("Pattern must not include a protocol (e.g. remove 'https://').");
+	if (pattern.includes("/")) return fail("Pattern must not include a path component (remove '/').");
+	if (pattern.includes("?")) return fail("Pattern must not include a query string (remove '?').");
+	if (pattern.startsWith("[") || pattern.includes("::")) return fail("IP address literals are not allowed in allowedHosts patterns.");
+	if (pattern.includes(":")) return fail("Pattern must not include a port number (e.g. remove ':8080').");
+	return null;
+}
+function checkWildcard(pattern) {
+	if (!pattern.includes("*")) return null;
+	if (pattern === "*" || pattern === "**") return fail("Bare wildcard '*' is not allowed. Use '*.example.com' to allow all subdomains.");
+	if (pattern.indexOf("*") !== 0 || pattern[1] !== ".") return fail("Wildcard '*' may only appear as the leading segment (e.g. '*.example.com').");
+	if (pattern.lastIndexOf("*") !== 0) return fail("Only a single leading wildcard segment is supported.");
+	return null;
+}
+function checkHostPart(hostPart) {
+	if (IPV4_RE.test(hostPart)) return fail("IP address literals are not allowed in allowedHosts patterns.");
+	const tld = hostPart.split(".").at(-1)?.toLowerCase() ?? "";
+	if (BLOCKED_TLDS.includes(tld)) return fail(`Patterns ending in '.${tld}' are not allowed (private/special-use TLD).`);
+	return null;
+}
+/**
+* Validate a single `allowedHosts` pattern at deploy time.
+*
+* Returns `{ valid: true }` for acceptable patterns or
+* `{ valid: false; reason: string }` with a human-readable rejection reason.
+*/
+function validateAllowedHostPattern(pattern) {
+	const structural = checkStructural(pattern);
+	if (structural !== null) return structural;
+	const wildcard = checkWildcard(pattern);
+	if (wildcard !== null) return wildcard;
+	const hostCheck = checkHostPart(pattern.startsWith("*.") ? pattern.slice(2) : pattern);
+	if (hostCheck !== null) return hostCheck;
+	return { valid: true };
+}
+/**
+* Test whether `hostname` matches any pattern in `patterns`.
+*
+* - Exact match is case-insensitive; trailing dots on the hostname are stripped.
+* - Wildcard pattern `*.example.com` matches any hostname ending with
+*   `.example.com` (one or more labels), but does NOT match `example.com` itself.
+* - A port suffix on `hostname` (e.g. `api.example.com:8080`) is stripped before
+*   matching.
+* - Returns `false` when `patterns` is empty.
+*/
+function matchesAllowedHost(hostname, patterns) {
+	if (patterns.length === 0) return false;
+	const portIndex = hostname.lastIndexOf(":");
+	let host = portIndex !== -1 && !hostname.includes("[") ? hostname.slice(0, portIndex) : hostname;
+	host = host.toLowerCase().replace(/\.$/, "");
+	for (const pattern of patterns) {
+		const p = pattern.toLowerCase();
+		if (p.startsWith("*.")) {
+			const suffix = p.slice(1);
+			if (host.endsWith(suffix) && host.length > suffix.length) return true;
+		} else if (host === p) return true;
+	}
+	return false;
+}
+//#endregion
 //#region sdk/define.ts
 /**
 * Define a tool with typed parameters and execute function.
@@ -60,4 +149,4 @@ function agent(def) {
 	};
 }
 //#endregion
-export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, parseWsUpgradeParams, tool, toolError };
+export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, matchesAllowedHost, parseWsUpgradeParams, tool, toolError, validateAllowedHostPattern };

package/dist/sdk/allowed-hosts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Allowlist matching for outbound host validation.
+ *
+ * Used at deploy time (manifest validation) and at runtime (SSRF enforcement)
+ * to restrict which external hosts an agent is permitted to contact.
+ *
+ * Lives in sdk/ because it has zero Node.js dependencies and can run in any
+ * environment (browser, Deno, Node.js sandboxes).
+ */
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Validate a single `allowedHosts` pattern at deploy time.
+ *
+ * Returns `{ valid: true }` for acceptable patterns or
+ * `{ valid: false; reason: string }` with a human-readable rejection reason.
+ */
+export declare function validateAllowedHostPattern(pattern: string): ValidationResult;
+/**
+ * Test whether `hostname` matches any pattern in `patterns`.
+ *
+ * - Exact match is case-insensitive; trailing dots on the hostname are stripped.
+ * - Wildcard pattern `*.example.com` matches any hostname ending with
+ *   `.example.com` (one or more labels), but does NOT match `example.com` itself.
+ * - A port suffix on `hostname` (e.g. `api.example.com:8080`) is stripped before
+ *   matching.
+ * - Returns `false` when `patterns` is empty.
+ */
+export declare function matchesAllowedHost(hostname: string, patterns: string[]): boolean;
+export {};

package/dist/sdk/manifest.d.ts

@@ -37,6 +37,8 @@ export type Manifest = {
     theme?: Record<string, string> | undefined;
     /** Custom tool definitions keyed by tool name. */
     tools: Record<string, ToolManifest>;
+    /** Hostnames the agent is allowed to fetch. Empty = no fetch access. */
+    allowedHosts: string[];
 };
 /**
  * Parse and normalize a raw agent manifest, applying defaults for all

package/dist/sdk/protocol.d.ts

@@ -60,6 +60,7 @@ export type KvRequest = z.infer<typeof KvRequestSchema>;
  * @public
  */
 export declare const SessionErrorCodeSchema: z.ZodEnum<{
+    internal: "internal";
     tool: "tool";
     connection: "connection";
     stt: "stt";
@@ -67,7 +68,6 @@ export declare const SessionErrorCodeSchema: z.ZodEnum<{
     tts: "tts";
     protocol: "protocol";
     audio: "audio";
-    internal: "internal";
 }>;
 /**
  * Error codes for categorizing session errors on the wire.
@@ -107,6 +107,7 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
+        internal: "internal";
         tool: "tool";
         connection: "connection";
         stt: "stt";
@@ -114,7 +115,6 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         tts: "tts";
         protocol: "protocol";
         audio: "audio";
-        internal: "internal";
     }>;
     message: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -189,6 +189,7 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
+        internal: "internal";
         tool: "tool";
         connection: "connection";
         stt: "stt";
@@ -196,7 +197,6 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         tts: "tts";
         protocol: "protocol";
         audio: "audio";
-        internal: "internal";
     }>;
     message: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{

package/index.ts

@@ -8,6 +8,7 @@
 
 // biome-ignore-all lint/performance/noReExportAll: barrel file by design
 
+export * from "./sdk/allowed-hosts.ts";
 export * from "./sdk/constants.ts";
 export * from "./sdk/define.ts";
 export * from "./sdk/kv.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "type": "module",
   "exports": {
     ".": {

package/sdk/__snapshots__/exports.test.ts.snap

@@ -26,9 +26,11 @@ exports[`export surface stability > @alexkroman1/aai main export 1`] = `
   "agent",
   "errorDetail",
   "errorMessage",
+  "matchesAllowedHost",
   "parseWsUpgradeParams",
   "tool",
   "toolError",
+  "validateAllowedHostPattern",
 ]
 `;
 

package/sdk/allowed-hosts.test.ts

@@ -0,0 +1,236 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { describe, expect, test } from "vitest";
+import { matchesAllowedHost, validateAllowedHostPattern } from "./allowed-hosts.ts";
+
+describe("validateAllowedHostPattern", () => {
+  describe("valid patterns", () => {
+    test("accepts exact hostname", () => {
+      expect(validateAllowedHostPattern("api.weather.com")).toEqual({
+        valid: true,
+      });
+    });
+
+    test("accepts exact hostname without subdomain", () => {
+      expect(validateAllowedHostPattern("example.com")).toEqual({ valid: true });
+    });
+
+    test("accepts wildcard subdomain", () => {
+      expect(validateAllowedHostPattern("*.mycompany.com")).toEqual({
+        valid: true,
+      });
+    });
+
+    test("accepts wildcard with multiple domain levels", () => {
+      expect(validateAllowedHostPattern("*.api.mycompany.com")).toEqual({
+        valid: true,
+      });
+    });
+  });
+
+  describe("rejects bare wildcards", () => {
+    test("rejects bare *", () => {
+      const result = validateAllowedHostPattern("*");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/bare/i);
+    });
+
+    test("rejects bare **", () => {
+      const result = validateAllowedHostPattern("**");
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("rejects wildcard in non-leading position", () => {
+    test("rejects wildcard in middle position", () => {
+      const result = validateAllowedHostPattern("api.*.com");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects wildcard at end", () => {
+      const result = validateAllowedHostPattern("api.com.*");
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("rejects IP addresses", () => {
+    test("rejects IPv4 address", () => {
+      const result = validateAllowedHostPattern("192.168.1.1");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
+    });
+
+    test("rejects IPv4 loopback", () => {
+      const result = validateAllowedHostPattern("127.0.0.1");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects IPv6 address", () => {
+      const result = validateAllowedHostPattern("::1");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
+    });
+
+    test("rejects full IPv6 address", () => {
+      const result = validateAllowedHostPattern("2001:db8::1");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
+    });
+  });
+
+  describe("rejects private TLDs", () => {
+    test("rejects *.local", () => {
+      const result = validateAllowedHostPattern("*.local");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects *.internal", () => {
+      const result = validateAllowedHostPattern("*.internal");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects *.localhost", () => {
+      const result = validateAllowedHostPattern("*.localhost");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects exact match foo.local", () => {
+      const result = validateAllowedHostPattern("foo.local");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects exact match foo.internal", () => {
+      const result = validateAllowedHostPattern("foo.internal");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects exact match foo.localhost", () => {
+      const result = validateAllowedHostPattern("foo.localhost");
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("rejects cloud metadata hostnames", () => {
+    test("rejects metadata.google.internal", () => {
+      const result = validateAllowedHostPattern("metadata.google.internal");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects instance-data.ec2.internal", () => {
+      const result = validateAllowedHostPattern("instance-data.ec2.internal");
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("rejects empty and malformed patterns", () => {
+    test("rejects empty string", () => {
+      const result = validateAllowedHostPattern("");
+      expect(result.valid).toBe(false);
+    });
+
+    test("rejects pattern with protocol", () => {
+      const result = validateAllowedHostPattern("https://api.example.com");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/protocol/i);
+    });
+
+    test("rejects pattern with path", () => {
+      const result = validateAllowedHostPattern("api.example.com/path");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/path/i);
+    });
+
+    test("rejects pattern with query", () => {
+      const result = validateAllowedHostPattern("api.example.com?query=1");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/query/i);
+    });
+
+    test("rejects pattern with port", () => {
+      const result = validateAllowedHostPattern("api.example.com:8080");
+      expect(result.valid).toBe(false);
+      expect((result as { valid: false; reason: string }).reason).toMatch(/port/i);
+    });
+  });
+});
+
+describe("matchesAllowedHost", () => {
+  describe("exact matching", () => {
+    test("exact match", () => {
+      expect(matchesAllowedHost("api.example.com", ["api.example.com"])).toBe(true);
+    });
+
+    test("case-insensitive exact match", () => {
+      expect(matchesAllowedHost("API.Example.COM", ["api.example.com"])).toBe(true);
+    });
+
+    test("strips trailing dot from hostname", () => {
+      expect(matchesAllowedHost("api.example.com.", ["api.example.com"])).toBe(true);
+    });
+
+    test("exact match doesn't match subdomain", () => {
+      expect(matchesAllowedHost("sub.api.example.com", ["api.example.com"])).toBe(false);
+    });
+
+    test("exact match doesn't match parent domain", () => {
+      expect(matchesAllowedHost("example.com", ["api.example.com"])).toBe(false);
+    });
+  });
+
+  describe("wildcard matching", () => {
+    test("wildcard matches one subdomain level", () => {
+      expect(matchesAllowedHost("foo.example.com", ["*.example.com"])).toBe(true);
+    });
+
+    test("wildcard matches multiple subdomain levels", () => {
+      expect(matchesAllowedHost("a.b.example.com", ["*.example.com"])).toBe(true);
+    });
+
+    test("wildcard does not match bare domain", () => {
+      expect(matchesAllowedHost("example.com", ["*.example.com"])).toBe(false);
+    });
+
+    test("wildcard is case-insensitive", () => {
+      expect(matchesAllowedHost("FOO.Example.COM", ["*.example.com"])).toBe(true);
+    });
+  });
+
+  describe("no match", () => {
+    test("no match returns false", () => {
+      expect(matchesAllowedHost("other.com", ["api.example.com"])).toBe(false);
+    });
+
+    test("empty patterns returns false", () => {
+      expect(matchesAllowedHost("api.example.com", [])).toBe(false);
+    });
+  });
+
+  describe("multiple patterns", () => {
+    test("matches against multiple patterns — first matches", () => {
+      expect(matchesAllowedHost("api.example.com", ["api.example.com", "other.com"])).toBe(true);
+    });
+
+    test("matches against multiple patterns — second matches", () => {
+      expect(matchesAllowedHost("other.com", ["api.example.com", "other.com"])).toBe(true);
+    });
+
+    test("matches against multiple patterns — none match", () => {
+      expect(matchesAllowedHost("nope.com", ["api.example.com", "other.com"])).toBe(false);
+    });
+  });
+
+  describe("port handling", () => {
+    test("port in hostname is stripped before matching exact", () => {
+      expect(matchesAllowedHost("api.weather.com:8080", ["api.weather.com"])).toBe(true);
+    });
+
+    test("port with wildcard pattern", () => {
+      expect(matchesAllowedHost("sub.example.com:443", ["*.example.com"])).toBe(true);
+    });
+  });
+
+  describe("IDN/punycode", () => {
+    test("ASCII hostnames compared normally", () => {
+      expect(matchesAllowedHost("xn--nxasmq6b.com", ["xn--nxasmq6b.com"])).toBe(true);
+    });
+  });
+});

package/sdk/allowed-hosts.ts

@@ -0,0 +1,113 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Allowlist matching for outbound host validation.
+ *
+ * Used at deploy time (manifest validation) and at runtime (SSRF enforcement)
+ * to restrict which external hosts an agent is permitted to contact.
+ *
+ * Lives in sdk/ because it has zero Node.js dependencies and can run in any
+ * environment (browser, Deno, Node.js sandboxes).
+ */
+
+/** Private/special-use TLDs that must never appear in allowedHosts patterns. */
+const BLOCKED_TLDS = ["local", "internal", "localhost"];
+
+/**
+ * Regex that matches an IPv4 address (four decimal octets separated by dots).
+ * Anchored so partial matches like "192.168.1.1.example.com" don't trigger it.
+ */
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+
+type ValidationResult = { valid: true } | { valid: false; reason: string };
+
+function fail(reason: string): { valid: false; reason: string } {
+  return { valid: false, reason };
+}
+
+function checkStructural(pattern: string): ValidationResult | null {
+  if (pattern === "") return fail("Pattern must not be empty.");
+  if (pattern.includes("://"))
+    return fail("Pattern must not include a protocol (e.g. remove 'https://').");
+  if (pattern.includes("/")) return fail("Pattern must not include a path component (remove '/').");
+  if (pattern.includes("?")) return fail("Pattern must not include a query string (remove '?').");
+  if (pattern.startsWith("[") || pattern.includes("::"))
+    return fail("IP address literals are not allowed in allowedHosts patterns.");
+  if (pattern.includes(":"))
+    return fail("Pattern must not include a port number (e.g. remove ':8080').");
+  return null;
+}
+
+function checkWildcard(pattern: string): ValidationResult | null {
+  if (!pattern.includes("*")) return null;
+  if (pattern === "*" || pattern === "**")
+    return fail("Bare wildcard '*' is not allowed. Use '*.example.com' to allow all subdomains.");
+  const wildcardIndex = pattern.indexOf("*");
+  if (wildcardIndex !== 0 || pattern[1] !== ".")
+    return fail("Wildcard '*' may only appear as the leading segment (e.g. '*.example.com').");
+  if (pattern.lastIndexOf("*") !== 0)
+    return fail("Only a single leading wildcard segment is supported.");
+  return null;
+}
+
+function checkHostPart(hostPart: string): ValidationResult | null {
+  if (IPV4_RE.test(hostPart))
+    return fail("IP address literals are not allowed in allowedHosts patterns.");
+  const tld = hostPart.split(".").at(-1)?.toLowerCase() ?? "";
+  if (BLOCKED_TLDS.includes(tld))
+    return fail(`Patterns ending in '.${tld}' are not allowed (private/special-use TLD).`);
+  return null;
+}
+
+/**
+ * Validate a single `allowedHosts` pattern at deploy time.
+ *
+ * Returns `{ valid: true }` for acceptable patterns or
+ * `{ valid: false; reason: string }` with a human-readable rejection reason.
+ */
+export function validateAllowedHostPattern(pattern: string): ValidationResult {
+  const structural = checkStructural(pattern);
+  if (structural !== null) return structural;
+
+  const wildcard = checkWildcard(pattern);
+  if (wildcard !== null) return wildcard;
+
+  const hostPart = pattern.startsWith("*.") ? pattern.slice(2) : pattern;
+  const hostCheck = checkHostPart(hostPart);
+  if (hostCheck !== null) return hostCheck;
+
+  return { valid: true };
+}
+
+/**
+ * Test whether `hostname` matches any pattern in `patterns`.
+ *
+ * - Exact match is case-insensitive; trailing dots on the hostname are stripped.
+ * - Wildcard pattern `*.example.com` matches any hostname ending with
+ *   `.example.com` (one or more labels), but does NOT match `example.com` itself.
+ * - A port suffix on `hostname` (e.g. `api.example.com:8080`) is stripped before
+ *   matching.
+ * - Returns `false` when `patterns` is empty.
+ */
+export function matchesAllowedHost(hostname: string, patterns: string[]): boolean {
+  if (patterns.length === 0) return false;
+
+  // Strip port — only when there are no brackets (IPv6 bracket notation).
+  const portIndex = hostname.lastIndexOf(":");
+  let host = portIndex !== -1 && !hostname.includes("[") ? hostname.slice(0, portIndex) : hostname;
+
+  // Normalise: lowercase + strip trailing dot
+  host = host.toLowerCase().replace(/\.$/, "");
+
+  for (const pattern of patterns) {
+    const p = pattern.toLowerCase();
+    if (p.startsWith("*.")) {
+      // Wildcard: hostname must end with the suffix (e.g. ".example.com")
+      const suffix = p.slice(1); // ".example.com"
+      if (host.endsWith(suffix) && host.length > suffix.length) return true;
+    } else if (host === p) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/sdk/manifest.test.ts

@@ -15,6 +15,7 @@ describe("parseManifest", () => {
       maxSteps: 5,
       toolChoice: "auto",
       builtinTools: [],
+      allowedHosts: [],
       tools: {},
     });
   });
@@ -56,6 +57,37 @@ describe("parseManifest", () => {
   test("rejects unknown builtinTools", () => {
     expect(() => parseManifest({ name: "X", builtinTools: ["not_a_tool"] })).toThrow();
   });
+
+  test("allowedHosts defaults to empty array when omitted", () => {
+    const result = parseManifest({ name: "test" });
+    expect(result.allowedHosts).toEqual([]);
+  });
+
+  test("allowedHosts passes through valid patterns", () => {
+    const result = parseManifest({
+      name: "test",
+      allowedHosts: ["api.weather.com", "*.mycompany.com"],
+    });
+    expect(result.allowedHosts).toEqual(["api.weather.com", "*.mycompany.com"]);
+  });
+
+  test("rejects invalid allowedHosts pattern", () => {
+    expect(() => parseManifest({ name: "test", allowedHosts: ["*"] })).toThrow();
+  });
+
+  test("rejects allowedHosts with IP address", () => {
+    expect(() => parseManifest({ name: "test", allowedHosts: ["192.168.1.1"] })).toThrow();
+  });
+
+  test("rejects allowedHosts with private TLD", () => {
+    expect(() => parseManifest({ name: "test", allowedHosts: ["*.internal"] })).toThrow();
+  });
+
+  test("rejects allowedHosts with protocol", () => {
+    expect(() =>
+      parseManifest({ name: "test", allowedHosts: ["https://api.example.com"] }),
+    ).toThrow();
+  });
 });
 
 // ── Property-based tests ─────────────────────────────────────────────────
@@ -117,4 +149,9 @@ describe("manifest type contracts", () => {
     const schemas = agentToolsToSchemas({});
     expectTypeOf(schemas).toEqualTypeOf<ToolSchema[]>();
   });
+
+  test("Manifest has allowedHosts as string[]", () => {
+    const result = parseManifest({ name: "test" });
+    expectTypeOf(result.allowedHosts).toEqualTypeOf<string[]>();
+  });
 });

package/sdk/manifest.ts

@@ -7,6 +7,7 @@
  */
 
 import { z } from "zod";
+import { validateAllowedHostPattern } from "./allowed-hosts.ts";
 import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_SYSTEM_PROMPT } from "./types.ts";
 
 /**
@@ -43,6 +44,8 @@ export type Manifest = {
   theme?: Record<string, string> | undefined;
   /** Custom tool definitions keyed by tool name. */
   tools: Record<string, ToolManifest>;
+  /** Hostnames the agent is allowed to fetch. Empty = no fetch access. */
+  allowedHosts: string[];
 };
 
 const ToolManifestSchema = z.object({
@@ -61,6 +64,21 @@ const ManifestSchema = z.object({
   idleTimeoutMs: z.number().int().positive().optional(),
   theme: z.record(z.string(), z.string()).optional(),
   tools: z.record(z.string(), ToolManifestSchema).optional(),
+  allowedHosts: z
+    .array(z.string())
+    .optional()
+    .superRefine((hosts, ctx) => {
+      if (!hosts) return;
+      for (const h of hosts) {
+        const result = validateAllowedHostPattern(h);
+        if (!result.valid) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Invalid allowedHosts pattern "${h}": ${result.reason}`,
+          });
+        }
+      }
+    }),
 });
 
 /**
@@ -85,5 +103,6 @@ export function parseManifest(input: unknown): Manifest {
     idleTimeoutMs: parsed.idleTimeoutMs,
     theme: parsed.theme,
     tools: parsed.tools ?? {},
+    allowedHosts: parsed.allowedHosts ?? [],
   };
 }