@namzu/sdk 27.0.0 → 28.0.0

package/src/connector/web/guarded-fetch.ts

@@ -0,0 +1,288 @@
+import { lookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+
+import {
+	type WebFetchProvider,
+	WebFetchRefusedError,
+	type WebFetchRequest,
+	type WebFetchResult,
+} from './types.js'
+
+/**
+ * Fetching a URL a model chose, without handing it the inside of the host.
+ *
+ * A model naming a URL is untrusted input reaching the network stack, and
+ * the network the agent runs on is not the network the model is thinking
+ * about. `http://169.254.169.254/` is a cloud metadata endpoint holding
+ * credentials; `http://localhost:6379/` is whatever the host runs on 6379;
+ * `file:///etc/passwd` is not even the network. None of those look unusual
+ * in a URL a model produced while reasoning about a public site.
+ *
+ * So this refuses rather than filtering afterwards. A response body already
+ * fetched is already a request that happened, and for a metadata endpoint
+ * the request IS the exfiltration — the body only decides whether the model
+ * gets to read what was taken.
+ */
+
+/** Every scheme this will follow. Everything else is refused by name. */
+const ALLOWED_SCHEMES = new Set(['http:', 'https:'])
+
+const DEFAULT_MAX_REDIRECTS = 5
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/**
+ * Headers this never forwards, whatever the caller asked for.
+ *
+ * A tool argument is model-authored, so `headers` is a channel from the
+ * model into an outbound request. `authorization` and `cookie` are the two
+ * that turn "fetch this page" into "fetch this page as me", and `host` is
+ * how a request to an allowed address gets routed to a different virtual
+ * host than the one that was checked.
+ */
+const STRIPPED_HEADERS = new Set(['authorization', 'cookie', 'host', 'proxy-authorization'])
+
+export interface GuardedFetchConfig {
+	/** Injected so a test needs no socket. Defaults to the global `fetch`. */
+	readonly fetch?: typeof globalThis.fetch
+	readonly maxRedirects?: number
+	readonly maxBytes?: number
+	readonly timeoutMs?: number
+	/**
+	 * Hostnames this must refuse regardless of where they resolve.
+	 *
+	 * A host's own belt on top of the address check: an internal name that
+	 * resolves publicly is not caught by an IP-range rule, and only the host
+	 * knows its own names.
+	 */
+	readonly blockedHosts?: readonly string[]
+	/**
+	 * Allow addresses the private-range check would refuse.
+	 *
+	 * `false`, and the default is the whole point. A test fixture on
+	 * `127.0.0.1` is the one legitimate case, and it is a decision a host
+	 * makes explicitly rather than one it inherits.
+	 */
+	readonly allowPrivateAddresses?: boolean
+	/**
+	 * How a hostname becomes addresses. Defaults to `node:dns`.
+	 *
+	 * Injected for the reason `fetch` is: a test that has to reach a real
+	 * resolver is a test that depends on somebody's DNS. It is also the seam
+	 * a host uses to pin resolution — see `assertAllowed` for the rebinding
+	 * gap this cannot close on its own.
+	 */
+	readonly resolve?: (hostname: string) => Promise<readonly string[]>
+}
+
+/**
+ * Is this address inside the host's own network?
+ *
+ * Written out rather than pulled from a dependency, because the list is
+ * short, stable, and the thing being protected is worth reading in full.
+ * IPv6 included: `::1` is loopback and `fc00::/7` is unique-local, and a
+ * guard that checked only IPv4 would be bypassed by a name with a AAAA
+ * record.
+ */
+export function isPrivateAddress(address: string): boolean {
+	const kind = isIP(address)
+	if (kind === 4) {
+		const parts = address.split('.').map(Number)
+		const [a = 0, b = 0] = parts
+		if (a === 127) return true // loopback
+		if (a === 10) return true // private
+		if (a === 172 && b >= 16 && b <= 31) return true // private
+		if (a === 192 && b === 168) return true // private
+		if (a === 169 && b === 254) return true // link-local, incl. cloud metadata
+		if (a === 0) return true // "this network"
+		if (a >= 224) return true // multicast and reserved
+		return false
+	}
+	if (kind === 6) {
+		const lower = address.toLowerCase().replace(/^\[|\]$/g, '')
+		if (lower === '::1' || lower === '::') return true
+		if (lower.startsWith('fe80')) return true // link-local
+		if (/^f[cd]/.test(lower)) return true // unique-local fc00::/7
+		// An IPv4-mapped address (::ffff:127.0.0.1) is an IPv4 address
+		// wearing an IPv6 spelling, and refusing it needs the IPv4 rules.
+		const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+		if (mapped?.[1]) return isPrivateAddress(mapped[1])
+		return false
+	}
+	return false
+}
+
+export class GuardedFetchProvider implements WebFetchProvider {
+	constructor(private readonly config: GuardedFetchConfig = {}) {}
+
+	private get maxRedirects(): number {
+		return this.config.maxRedirects ?? DEFAULT_MAX_REDIRECTS
+	}
+
+	/**
+	 * Refuse a URL before anything is sent.
+	 *
+	 * Called for the original URL AND for every redirect target. That
+	 * repetition is the point: checking once and then following redirects is
+	 * the classic version of this bug — a permitted public URL answers
+	 * `302 -> http://169.254.169.254/`, and a fetch that validated only what
+	 * the caller typed follows it happily.
+	 */
+	private async assertAllowed(rawUrl: string): Promise<URL> {
+		let url: URL
+		try {
+			url = new URL(rawUrl)
+		} catch {
+			throw new WebFetchRefusedError(`"${rawUrl}" is not a URL.`, {
+				url: rawUrl,
+				reason: 'scheme',
+			})
+		}
+
+		if (!ALLOWED_SCHEMES.has(url.protocol)) {
+			// Named rather than generic: `file:` and `data:` are the ones a
+			// model reaches for by accident, and telling it which scheme was
+			// refused is what lets it correct itself.
+			throw new WebFetchRefusedError(
+				`Refused "${url.protocol}" — only http and https are fetched.`,
+				{ url: rawUrl, reason: 'scheme' },
+			)
+		}
+
+		const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '')
+		if (this.config.blockedHosts?.some((blocked) => blocked.toLowerCase() === hostname)) {
+			throw new WebFetchRefusedError(`Refused "${hostname}" — the host blocks this name.`, {
+				url: rawUrl,
+				reason: 'blocked-host',
+			})
+		}
+
+		if (this.config.allowPrivateAddresses === true) return url
+
+		// RESOLVED, not just parsed. A hostname check alone is bypassed by any
+		// name whose A record points inside — which is a thing anyone can set
+		// up on a domain they own, and costs nothing to try.
+		//
+		// The residual gap is stated rather than hidden: between this lookup
+		// and the connection, the name can be re-resolved to something else
+		// (DNS rebinding). Closing that needs the fetch to pin the address it
+		// checked, which the platform `fetch` gives no way to do. A host that
+		// needs that guarantee supplies its own `fetch` that does.
+		const resolve =
+			this.config.resolve ??
+			(async (name: string) => (await lookup(name, { all: true })).map((r) => r.address))
+		let addresses: readonly string[]
+		if (isIP(hostname)) {
+			addresses = [hostname]
+		} else {
+			try {
+				addresses = await resolve(hostname)
+			} catch (err) {
+				// REFUSE. `.catch(() => [])` was the first version of this line
+				// and it is fail-open: an empty list satisfies the loop below,
+				// so a name nobody could resolve was treated as a name with no
+				// private addresses — and the fetch that followed would resolve
+				// it again for real, against whatever answered the second time.
+				throw new WebFetchRefusedError(
+					`Refused "${hostname}" — it could not be resolved (${err instanceof Error ? err.message : String(err)}), so nothing here can say where it points.`,
+					{ url: rawUrl, reason: 'private-address' },
+				)
+			}
+			if (addresses.length === 0) {
+				throw new WebFetchRefusedError(`Refused "${hostname}" — it resolves to no addresses.`, {
+					url: rawUrl,
+					reason: 'private-address',
+				})
+			}
+		}
+
+		for (const address of addresses) {
+			if (isPrivateAddress(address)) {
+				throw new WebFetchRefusedError(
+					`Refused "${hostname}" — it resolves to ${address}, inside this host's own network.`,
+					{ url: rawUrl, reason: 'private-address' },
+				)
+			}
+		}
+		return url
+	}
+
+	async fetch(request: WebFetchRequest): Promise<WebFetchResult> {
+		const doFetch = this.config.fetch ?? globalThis.fetch
+		const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+		const maxBytes = this.config.maxBytes ?? DEFAULT_MAX_BYTES
+
+		const headers: Record<string, string> = {}
+		for (const [key, value] of Object.entries(request.headers ?? {})) {
+			if (!STRIPPED_HEADERS.has(key.toLowerCase())) headers[key] = value
+		}
+
+		const timer = new AbortController()
+		const deadline = setTimeout(() => timer.abort(), timeoutMs)
+		// Both: the caller's cancel and our own deadline. Honouring only one
+		// leaves the other unable to stop a fetch that has stopped being
+		// wanted.
+		request.signal?.addEventListener('abort', () => timer.abort(), { once: true })
+
+		try {
+			const redirects: string[] = []
+			let current = await this.assertAllowed(request.url)
+
+			for (let hop = 0; ; hop++) {
+				if (hop > this.maxRedirects) {
+					throw new WebFetchRefusedError(
+						`Refused after ${this.maxRedirects} redirects from "${request.url}".`,
+						{ url: request.url, reason: 'redirect-limit' },
+					)
+				}
+				redirects.push(current.toString())
+
+				// `manual`, so every hop comes back here to be checked. Letting
+				// the platform follow redirects is exactly the hole this class
+				// exists to close: it would land on the final URL having never
+				// asked whether that URL was allowed.
+				const response = await doFetch(current, {
+					headers,
+					redirect: 'manual',
+					signal: timer.signal,
+				})
+
+				const location = response.headers.get('location')
+				if (response.status >= 300 && response.status < 400 && location) {
+					// Resolved against the current URL, because a `Location` may
+					// be relative — and a relative one that is not resolved would
+					// be checked as a different URL than the one followed.
+					const next = new URL(location, current)
+					try {
+						current = await this.assertAllowed(next.toString())
+					} catch (err) {
+						if (err instanceof WebFetchRefusedError) {
+							throw new WebFetchRefusedError(
+								`A redirect from "${current.toString()}" pointed at "${next.toString()}", which was refused: ${err.message}`,
+								{ url: next.toString(), reason: 'redirect-target' },
+							)
+						}
+						throw err
+					}
+					continue
+				}
+
+				const text = await response.text()
+				const truncated = Buffer.byteLength(text) > maxBytes
+				const body = truncated ? Buffer.from(text).subarray(0, maxBytes).toString('utf8') : text
+				const contentType = response.headers.get('content-type') ?? undefined
+
+				return {
+					url: current.toString(),
+					status: response.status,
+					...(contentType === undefined ? {} : { contentType }),
+					body,
+					truncated,
+					redirects,
+				}
+			}
+		} finally {
+			clearTimeout(deadline)
+		}
+	}
+}

package/src/connector/web/index.ts

@@ -0,0 +1,17 @@
+// Reaching the web, as a seam. Fetching is implemented here because its
+// rules are about the network and the same everywhere; searching is not,
+// and ships with no vendor. See `types.ts` for why that asymmetry is the
+// design rather than an omission.
+export { GuardedFetchProvider, isPrivateAddress } from './guarded-fetch.js'
+export type { GuardedFetchConfig } from './guarded-fetch.js'
+export { WebFetchRefusedError } from './types.js'
+export type {
+	WebFetchProvider,
+	WebFetchRefusalReason,
+	WebFetchRequest,
+	WebFetchResult,
+	WebSearchHit,
+	WebSearchProvider,
+	WebSearchRequest,
+	WebSearchResult,
+} from './types.js'

package/src/connector/web/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Reaching the web, as a seam rather than as a bundled vendor.
+ *
+ * Two providers, and they are separated on purpose. **Fetching a URL is a
+ * capability this kernel can implement**: the rules are about the network
+ * and the same everywhere, so a wrong answer is a defect rather than a
+ * preference. **Searching is not.** Every search backend has its own
+ * account, its own terms, its own result shape and its own opinion about
+ * what a result even is, and picking one here would make that choice for
+ * every consumer while adding a dependency nobody asked for.
+ *
+ * So `WebFetchProvider` ships with a guarded implementation and
+ * `WebSearchProvider` ships with none. A host that wants search brings one.
+ * That asymmetry is the design, not an omission — see
+ * `GuardedFetchProvider` for what "guarded" is doing the work of.
+ */
+
+export interface WebFetchRequest {
+	readonly url: string
+	/** Extra headers. The provider may refuse or strip some; see the guard. */
+	readonly headers?: Readonly<Record<string, string>>
+	readonly signal?: AbortSignal
+}
+
+export interface WebFetchResult {
+	readonly url: string
+	readonly status: number
+	readonly contentType?: string
+	readonly body: string
+	/**
+	 * Whether the body was cut off at the size cap.
+	 *
+	 * Reported, never silent. A truncated page that reads as complete is a
+	 * model concluding something from a document whose second half it never
+	 * saw — the same rule the tool-output cap and the background job buffer
+	 * already follow.
+	 */
+	readonly truncated: boolean
+	/** Every URL in the redirect chain, in order, including the final one. */
+	readonly redirects: readonly string[]
+}
+
+/** Why a fetch was refused before it left the process. */
+export type WebFetchRefusalReason =
+	| 'scheme'
+	| 'private-address'
+	| 'redirect-limit'
+	| 'redirect-target'
+	| 'blocked-host'
+
+export class WebFetchRefusedError extends Error {
+	readonly details: { url: string; reason: WebFetchRefusalReason }
+
+	constructor(message: string, details: { url: string; reason: WebFetchRefusalReason }) {
+		super(message)
+		this.name = 'WebFetchRefusedError'
+		this.details = details
+	}
+}
+
+export interface WebFetchProvider {
+	fetch(request: WebFetchRequest): Promise<WebFetchResult>
+}
+
+export interface WebSearchRequest {
+	readonly query: string
+	readonly limit?: number
+	readonly signal?: AbortSignal
+}
+
+export interface WebSearchHit {
+	readonly title: string
+	readonly url: string
+	/**
+	 * The backend's own excerpt, when it has one.
+	 *
+	 * Not synthesised here. A snippet this kernel wrote would be a claim
+	 * about a page nobody fetched, and a model citing it would be citing us.
+	 */
+	readonly snippet?: string
+}
+
+export interface WebSearchResult {
+	readonly query: string
+	readonly hits: readonly WebSearchHit[]
+}
+
+/**
+ * Search, which this kernel does NOT implement.
+ *
+ * Declared so the tool surface and the wiring can exist without a vendor,
+ * and so a host's backend has a shape to satisfy rather than a convention
+ * to guess at. There is deliberately no default: a search provider means an
+ * account, terms of service, and a result shape, and choosing one here
+ * would choose it for every consumer.
+ */
+export interface WebSearchProvider {
+	search(request: WebSearchRequest): Promise<WebSearchResult>
+}

package/src/constants/acp/index.ts

@@ -0,0 +1,104 @@
+/**
+ * The agent-client protocol's version and method set, pinned.
+ *
+ * A table rather than string literals scattered through the server, because
+ * the two things that go wrong with a wire protocol are a method spelled
+ * differently in one place and a method implemented but never advertised.
+ * Both are invisible at compile time and both present to a client as "that
+ * agent does not support this".
+ *
+ * `bridge/acp/server.ts` authors its handler map independently and a test
+ * compares the two SETS in both directions: a handler with no entry here
+ * fails, and an entry here with no handler fails. That is the only
+ * arrangement where the comparison can fail — deriving the handlers from
+ * this table would make the test a tautology, which is the shape
+ * `a-check-that-cannot-fail` names.
+ *
+ * Zero imports, deliberately: this is read by the types module, the server,
+ * and the CLI command, and a constant table that pulls in a dependency
+ * becomes a cycle the moment one of those three moves.
+ */
+
+/**
+ * The protocol revision this bridge speaks.
+ *
+ * A number, matching the wire field, and pinned rather than negotiated
+ * downward. A client asking for a version this does not implement is told
+ * what it does implement; guessing that an older client can be served by a
+ * newer agent is how a protocol bridge produces a session that half works.
+ */
+export const ACP_PROTOCOL_VERSION = 1
+
+/** Methods a client calls on this agent. */
+export const ACP_METHODS = {
+	INITIALIZE: 'initialize',
+	SESSION_NEW: 'session/new',
+	SESSION_PROMPT: 'session/prompt',
+	SESSION_CANCEL: 'session/cancel',
+	SESSION_LOAD: 'session/load',
+} as const
+
+export type AcpMethod = (typeof ACP_METHODS)[keyof typeof ACP_METHODS]
+
+/**
+ * Notifications this agent sends the client.
+ *
+ * Separate from `ACP_METHODS` because the drift test is about what a client
+ * may CALL. Mixing the two directions into one table would make that test
+ * demand a handler for a message this side only ever sends.
+ */
+export const ACP_CLIENT_NOTIFICATIONS = {
+	SESSION_UPDATE: 'session/update',
+} as const
+
+/**
+ * REQUESTS this agent makes of the client, which it answers.
+ *
+ * Distinct from a notification: each carries an id and this side waits for
+ * the response. That direction is what makes a permission prompt possible at
+ * all — the agent has a question and cannot proceed until the human behind
+ * the client answers it.
+ */
+export const ACP_CLIENT_REQUESTS = {
+	REQUEST_PERMISSION: 'session/request_permission',
+	FS_READ: 'fs/read_text_file',
+	FS_WRITE: 'fs/write_text_file',
+} as const
+
+/**
+ * JSON-RPC error codes this bridge answers with.
+ *
+ * `METHOD_NOT_FOUND` is the one with a behavioural requirement attached: an
+ * unknown method is answered and the connection STAYS OPEN. A bridge that
+ * closed on an unrecognised call would make a client's feature probe fatal.
+ */
+export const ACP_ERROR_CODES = {
+	PARSE_ERROR: -32700,
+	INVALID_REQUEST: -32600,
+	METHOD_NOT_FOUND: -32601,
+	INVALID_PARAMS: -32602,
+	INTERNAL_ERROR: -32603,
+} as const
+
+/**
+ * The capability a client must declare before a session is created.
+ *
+ * Approval routing is a later change, so a session that could not ask a
+ * human anything must not be created at all: it would run with every tool
+ * auto-approved, which is not a degraded version of asking — it is the
+ * opposite of it. The refusal names this string so a client author knows
+ * what to send.
+ */
+export const ACP_PERMISSION_CAPABILITY = 'permission'
+
+/**
+ * The capability that lets the EDITOR's buffers be the source of truth.
+ *
+ * Optional, unlike `permission`. A client that does not declare it gets an
+ * agent reading and writing the disk, which is correct and is what every
+ * non-editor peer wants. A client that DOES declare it is telling this
+ * agent that the file on disk may be stale — the user has unsaved changes —
+ * and that reading disk anyway would show the model a version of the file
+ * nobody is looking at.
+ */
+export const ACP_FILESYSTEM_CAPABILITY = 'fs'

package/src/constants/credential-env-keys.ts

@@ -0,0 +1,63 @@
+/**
+ * Credential-bearing environment variable KEY NAMES, in one place.
+ *
+ * A leaf with no imports, beside `secret-patterns.ts` and holding the
+ * complement of it: that file matches credential VALUES, this one matches
+ * the names variables carry them under. Neither re-declares the other's,
+ * because a value pattern and a key name answer different questions and a
+ * table that tried to do both would be wrong at whichever end it was not
+ * written for.
+ *
+ * Two readers, and that is the point of moving it here. The host-bash
+ * environment scrub uses it to decide what a shell command must not
+ * inherit, and `EnvCredentialProvider` uses it to decide what counts as a
+ * credential it can resolve. Those were about to become two tables — the
+ * CLI's provider registry already keeps a third, of `envVars` per provider
+ * — and a name in one and not another means a variable the CLI reads a
+ * credential from and the scrub happily hands to a shell.
+ */
+
+/**
+ * Key-name patterns that mark an inherited variable as credential-shaped.
+ *
+ * Matched case-insensitively against the whole key. Deliberately broad: a
+ * false positive costs a command one variable it can be handed back
+ * explicitly, while a false negative costs a leaked secret that cannot be
+ * recalled from a transcript.
+ */
+export const CREDENTIAL_KEY_PATTERNS: readonly RegExp[] = [
+	/KEY/i,
+	/SECRET/i,
+	/TOKEN/i,
+	/PASSWORD/i,
+	/PASSWD/i,
+	/CREDENTIAL/i,
+	/(^|_)AUTH(_|$)/i,
+	/PRIVATE/i,
+	/SESSION_ID/i,
+	/COOKIE/i,
+	/SIGNATURE/i,
+	/(^|_)PAT(_|$)/i,
+]
+
+/**
+ * Keys that are credential-bearing but whose names match none of the patterns
+ * above. Kept as an explicit list so each entry is a decision somebody can
+ * read, rather than a pattern nobody can evaluate.
+ */
+export const CREDENTIAL_KEY_EXACT: ReadonlySet<string> = new Set([
+	'AWS_SESSION_TOKEN',
+	'AWS_SECURITY_TOKEN',
+	'GOOGLE_APPLICATION_CREDENTIALS',
+	'NPM_CONFIG__AUTH',
+	'GH_ENTERPRISE_TOKEN',
+	'DOCKER_AUTH_CONFIG',
+	'KUBECONFIG',
+	'NETRC',
+])
+
+/** True when an inherited variable's name marks it as credential-shaped. */
+export function isCredentialEnvKey(key: string): boolean {
+	if (CREDENTIAL_KEY_EXACT.has(key.toUpperCase())) return true
+	return CREDENTIAL_KEY_PATTERNS.some((pattern) => pattern.test(key))
+}

package/src/constants/index.ts

@@ -1,3 +1,4 @@
+export * from './acp/index.js'
 export * from './a2a/index.js'
 export * from './advisory/index.js'
 export * from './compaction/index.js'
@@ -10,7 +11,8 @@ export * from './agent/index.js'
 export * from './continuation.js'
 export * from './limits.js'
 export * from './bus/index.js'
-export * from './verification/index.js'
+export * from './authorization/index.js'
 export * from './emergency.js'
 export * from './plugin/index.js'
 export * from './sandbox/index.js'
+export * from './secret-patterns.js'