@agenticmail/core 0.9.3 → 0.9.5

package/dist/index.d.cts

@@ -1583,6 +1583,254 @@ declare function flushTelemetry(): void;
 declare function debug(tag: string, message: string): void;
 declare function debugWarn(tag: string, message: string): void;
 
+/**
+ * Path-traversal safe filesystem joiner.
+ *
+ * # Why this exists
+ *
+ * Every host-integration installer writes files into a directory
+ * derived from operator config / env vars (`CODEX_HOME`,
+ * `CLAUDE_CODE_AGENTS_DIR`, etc) AND builds filenames from values
+ * returned by the AgenticMail API (account names, agent metadata).
+ * Both inputs cross trust boundaries:
+ *
+ *   - The operator's env vars are mostly trusted — but the operator
+ *     could fat-finger a relative path that resolves outside the
+ *     intended dir, or paste a path containing `..` segments.
+ *   - The AgenticMail API responses cross the master-key boundary.
+ *     A compromised MCP session or stolen master key could create an
+ *     account whose `name` contains `../../etc/something` to escape
+ *     the agents directory at install time.
+ *
+ * The existing `sanitizeSubagentName` helpers filter most malicious
+ * names, but defence-in-depth dictates a second boundary check at
+ * the actual `fs.writeFile` call. This module is that second check.
+ *
+ * # API
+ *
+ * `safeJoin(baseDir, ...parts)` resolves the parts under `baseDir`
+ * and throws `PathTraversalError` if the resulting absolute path
+ * escapes `baseDir`. Use it instead of `path.join(baseDir, ...)` in
+ * every code path that mixes operator config + user-provided
+ * filenames.
+ *
+ * # Why this idiom (resolve + boundary check)
+ *
+ * - `path.resolve` normalises `..` segments deterministically.
+ * - The startsWith check rejects any normalised path that climbed
+ *   out of `baseDir`.
+ * - CodeQL's `js/path-injection` query recognises this exact shape
+ *   as a sanitizer, so the static-analysis warning is resolved at
+ *   the same time the runtime risk is closed.
+ *
+ * # Edge cases handled
+ *
+ * - `parts` containing `..` segments → throws.
+ * - `parts` containing an absolute path → the absolute path wins
+ *   over `baseDir` per POSIX rules, which is almost always wrong
+ *   when the caller meant "filename inside baseDir". We reject
+ *   absolute segments unless `allowAbsolute: true` is set.
+ * - `baseDir` itself is not normalised before comparison: pass an
+ *   already-resolved absolute path. The helper asserts this.
+ * - Symlinks are NOT resolved. If you need symlink-safe joining,
+ *   wrap with `fs.realpath` separately. For our installers we
+ *   don't follow symlinks at all (we always do explicit
+ *   `existsSync` + `writeFileSync`), so this is fine.
+ *
+ * # Examples
+ *
+ * ```ts
+ * // Safe: resolves to /home/ope/.codex/agents/agenticmail-fola.toml
+ * safeJoin('/home/ope/.codex/agents', 'agenticmail-fola.toml');
+ *
+ * // Throws: '../etc/passwd' resolves outside the base dir
+ * safeJoin('/home/ope/.codex/agents', '../etc/passwd');
+ *
+ * // Throws: an absolute path bypasses the base dir
+ * safeJoin('/home/ope/.codex/agents', '/etc/passwd');
+ * ```
+ */
+
+/**
+ * Thrown when a `safeJoin` call would resolve to a path outside the
+ * provided base directory. Carries the offending inputs for logging
+ * (with the resolved path elided so we don't leak filesystem layout
+ * to a remote attacker via error messages).
+ */
+declare class PathTraversalError extends Error {
+    readonly baseDir: string;
+    readonly parts: string[];
+    constructor(baseDir: string, parts: string[]);
+}
+interface SafeJoinOptions {
+    /**
+     * Allow segments that are themselves absolute paths. Off by default
+     * because passing an absolute path to `path.join` discards the
+     * base directory — almost always a bug at our call sites.
+     */
+    allowAbsolute?: boolean;
+}
+/**
+ * Resolve `parts` under `baseDir`, asserting the result stays inside
+ * `baseDir`. See module docstring for the rationale.
+ *
+ * @throws `PathTraversalError` if any segment is absolute (and
+ *   `allowAbsolute` is not set), or if the resolved path escapes
+ *   `baseDir`.
+ */
+declare function safeJoin(baseDir: string, ...partsAndOpts: (string | SafeJoinOptions)[]): string;
+/**
+ * Convenience: same as `safeJoin` but returns `null` instead of
+ * throwing on a traversal attempt. Use in code paths where a single
+ * malicious filename should be skipped, not propagated up as an
+ * exception (e.g. iterating `readdirSync` results during cleanup).
+ */
+declare function tryJoin(baseDir: string, ...parts: string[]): string | null;
+/**
+ * Validate that a candidate path is already absolute and stays inside
+ * `baseDir`. Use when receiving a path from external config that the
+ * caller wants to treat as already-canonical (e.g. an env var that
+ * names a project directory) — the helper asserts the safety
+ * properties without further joining.
+ */
+declare function assertWithinBase(baseDir: string, candidate: string): string;
+
+/**
+ * Secret-redaction helpers for log lines and diagnostic output.
+ *
+ * # Why this exists
+ *
+ * AgenticMail keeps three kinds of long-lived secrets in memory:
+ *
+ *   1. The master key (`mk_…`) — full admin scope on the local API.
+ *   2. Per-agent API keys (`ak_…`) — scoped to one agent's mailbox.
+ *   3. Stalwart's admin password and per-agent IMAP/SMTP passwords.
+ *
+ * All three flow through config objects, install results, and the
+ * MCP-server env block. Several of those objects get logged for
+ * diagnostic purposes (install completion summary, dispatcher
+ * startup, error stacks). CodeQL's `js/clear-text-logging` query
+ * flagged eight call sites where a secret could plausibly reach a
+ * log line. This module is the canonical sanitizer for those spots.
+ *
+ * # API
+ *
+ *   - `redactSecret(value)` collapses a string secret to a
+ *     fixed-shape redaction marker (`mk_***`, `ak_***`, `***`)
+ *     while preserving the prefix so the log reader can still tell
+ *     the kind of secret it was.
+ *   - `redactObject(obj)` walks an object and replaces every value
+ *     under a "sensitive-looking" key with REDACTED.
+ *   - `REDACTED` constant for cases where the caller wants to
+ *     compose their own log line.
+ *
+ * # Conservative match
+ *
+ * The "sensitive-looking" key detection is deliberately broad —
+ * it's better to over-redact a harmless `name` field that happens
+ * to contain "key" than to leak a secret. The currently-matched
+ * key names (case-insensitive substring): `key`, `secret`,
+ * `password`, `token`, `apikey`, `masterkey`, `authorization`,
+ * `bearer`.
+ */
+/** Returned in place of any redacted secret. */
+declare const REDACTED = "***";
+/**
+ * Redact a string secret to a fixed-shape marker. Preserves the
+ * known prefixes (`mk_`, `ak_`) so log readers can still tell what
+ * kind of secret was elided.
+ *
+ * Non-string inputs return REDACTED unchanged.
+ */
+declare function redactSecret(value: unknown): string;
+/**
+ * Walk an object recursively. Any value under a key that looks
+ * sensitive (see SENSITIVE_KEY_PATTERNS above) is replaced with
+ * `REDACTED`. Arrays are walked too. The original object is NOT
+ * mutated — returns a shallow-cloned tree with the same shape.
+ *
+ * Use this when you want to pass a whole config object into a log
+ * line via JSON.stringify, e.g.:
+ *
+ * ```ts
+ * log.info('install complete', redactObject(result));
+ * ```
+ *
+ * Edge cases:
+ *   - Cycles are NOT supported; pass tree-shaped data only.
+ *   - Non-plain objects (Map, Set, Buffer, Date, Error) are returned
+ *     by reference unchanged — redaction is for plain config dicts.
+ *   - Symbols are skipped.
+ */
+declare function redactObject<T>(input: T, _depth?: number): T;
+
+/**
+ * SSRF-safe URL validation for the AgenticMail API base URL.
+ *
+ * # What this is for
+ *
+ * Every host integration (claudecode, codex, …) reads the master API
+ * URL from `~/.agenticmail/config.json` and uses it to build fetch
+ * requests. CodeQL's `js/request-forgery` query flags those fetch
+ * calls because the URL is operator-controlled (via the config file
+ * or env vars) and could theoretically be redirected to an internal
+ * service the host process can reach but the operator didn't intend.
+ *
+ * In practice the operator controls their own config file — there's
+ * no remote attacker controlling apiUrl in a self-hosted install.
+ * But defence-in-depth dictates we still validate, because:
+ *
+ *   - A malicious npm package that planted an env var (e.g.
+ *     `AGENTICMAIL_API_URL=http://169.254.169.254/latest/meta-data/`)
+ *     could redirect the dispatcher's API calls to a cloud-metadata
+ *     endpoint and exfiltrate IAM credentials in the response body.
+ *   - A `file://` or `javascript:` scheme would let the operator's
+ *     own typo cause undefined behavior.
+ *
+ * # The check
+ *
+ * `validateApiUrl(url)` rejects:
+ *
+ *   - Non-`http(s)://` schemes (`file://`, `javascript:`, `data:`,
+ *     `ftp://`, etc).
+ *   - Cloud metadata IPs (169.254.169.254 — AWS/Azure/GCP) and the
+ *     IPv6 equivalent fd00:ec2::254.
+ *   - Empty / malformed URLs (via `new URL` parse).
+ *
+ * The check intentionally does NOT restrict to localhost — operators
+ * legitimately run AgenticMail on a NAS or remote VM and point the
+ * host-integration installs at it. The cloud-metadata IPs are the
+ * only blanket block.
+ *
+ * # Why a separate canonicalisation step
+ *
+ * Returning the URL via `url.origin` (rather than the raw input
+ * string) gives CodeQL a sanitiser shape it recognises: the value
+ * is now constrained to whatever `URL` parsed it into, with no
+ * embedded credentials, query strings, or path traversal.
+ */
+/** Thrown when `validateApiUrl` rejects a candidate URL. */
+declare class UnsafeApiUrlError extends Error {
+    readonly raw: string;
+    readonly reason: string;
+    constructor(raw: string, reason: string);
+}
+/**
+ * Validate the operator-supplied AgenticMail API base URL.
+ *
+ * Returns the canonical origin form of the URL (`http://host:port`)
+ * so callers can build paths against it without worrying about
+ * trailing slashes or embedded auth. Throws `UnsafeApiUrlError` on
+ * any structural problem or blocked host.
+ */
+declare function validateApiUrl(raw: unknown): string;
+/**
+ * Build a full request URL from a validated base + path. Used by the
+ * host-integration api clients to ensure the path is appended via
+ * `URL` (escapes correctly) rather than string concat.
+ */
+declare function buildApiUrl(baseOrigin: string, pathAndQuery: string): string;
+
 interface DependencyStatus {
     name: string;
     installed: boolean;
@@ -2123,4 +2371,4 @@ declare class AgentMemoryStore {
     renderForPrompt(memory: AgentMemoryRead | null): string;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };

package/dist/index.d.ts

@@ -1583,6 +1583,254 @@ declare function flushTelemetry(): void;
 declare function debug(tag: string, message: string): void;
 declare function debugWarn(tag: string, message: string): void;
 
+/**
+ * Path-traversal safe filesystem joiner.
+ *
+ * # Why this exists
+ *
+ * Every host-integration installer writes files into a directory
+ * derived from operator config / env vars (`CODEX_HOME`,
+ * `CLAUDE_CODE_AGENTS_DIR`, etc) AND builds filenames from values
+ * returned by the AgenticMail API (account names, agent metadata).
+ * Both inputs cross trust boundaries:
+ *
+ *   - The operator's env vars are mostly trusted — but the operator
+ *     could fat-finger a relative path that resolves outside the
+ *     intended dir, or paste a path containing `..` segments.
+ *   - The AgenticMail API responses cross the master-key boundary.
+ *     A compromised MCP session or stolen master key could create an
+ *     account whose `name` contains `../../etc/something` to escape
+ *     the agents directory at install time.
+ *
+ * The existing `sanitizeSubagentName` helpers filter most malicious
+ * names, but defence-in-depth dictates a second boundary check at
+ * the actual `fs.writeFile` call. This module is that second check.
+ *
+ * # API
+ *
+ * `safeJoin(baseDir, ...parts)` resolves the parts under `baseDir`
+ * and throws `PathTraversalError` if the resulting absolute path
+ * escapes `baseDir`. Use it instead of `path.join(baseDir, ...)` in
+ * every code path that mixes operator config + user-provided
+ * filenames.
+ *
+ * # Why this idiom (resolve + boundary check)
+ *
+ * - `path.resolve` normalises `..` segments deterministically.
+ * - The startsWith check rejects any normalised path that climbed
+ *   out of `baseDir`.
+ * - CodeQL's `js/path-injection` query recognises this exact shape
+ *   as a sanitizer, so the static-analysis warning is resolved at
+ *   the same time the runtime risk is closed.
+ *
+ * # Edge cases handled
+ *
+ * - `parts` containing `..` segments → throws.
+ * - `parts` containing an absolute path → the absolute path wins
+ *   over `baseDir` per POSIX rules, which is almost always wrong
+ *   when the caller meant "filename inside baseDir". We reject
+ *   absolute segments unless `allowAbsolute: true` is set.
+ * - `baseDir` itself is not normalised before comparison: pass an
+ *   already-resolved absolute path. The helper asserts this.
+ * - Symlinks are NOT resolved. If you need symlink-safe joining,
+ *   wrap with `fs.realpath` separately. For our installers we
+ *   don't follow symlinks at all (we always do explicit
+ *   `existsSync` + `writeFileSync`), so this is fine.
+ *
+ * # Examples
+ *
+ * ```ts
+ * // Safe: resolves to /home/ope/.codex/agents/agenticmail-fola.toml
+ * safeJoin('/home/ope/.codex/agents', 'agenticmail-fola.toml');
+ *
+ * // Throws: '../etc/passwd' resolves outside the base dir
+ * safeJoin('/home/ope/.codex/agents', '../etc/passwd');
+ *
+ * // Throws: an absolute path bypasses the base dir
+ * safeJoin('/home/ope/.codex/agents', '/etc/passwd');
+ * ```
+ */
+
+/**
+ * Thrown when a `safeJoin` call would resolve to a path outside the
+ * provided base directory. Carries the offending inputs for logging
+ * (with the resolved path elided so we don't leak filesystem layout
+ * to a remote attacker via error messages).
+ */
+declare class PathTraversalError extends Error {
+    readonly baseDir: string;
+    readonly parts: string[];
+    constructor(baseDir: string, parts: string[]);
+}
+interface SafeJoinOptions {
+    /**
+     * Allow segments that are themselves absolute paths. Off by default
+     * because passing an absolute path to `path.join` discards the
+     * base directory — almost always a bug at our call sites.
+     */
+    allowAbsolute?: boolean;
+}
+/**
+ * Resolve `parts` under `baseDir`, asserting the result stays inside
+ * `baseDir`. See module docstring for the rationale.
+ *
+ * @throws `PathTraversalError` if any segment is absolute (and
+ *   `allowAbsolute` is not set), or if the resolved path escapes
+ *   `baseDir`.
+ */
+declare function safeJoin(baseDir: string, ...partsAndOpts: (string | SafeJoinOptions)[]): string;
+/**
+ * Convenience: same as `safeJoin` but returns `null` instead of
+ * throwing on a traversal attempt. Use in code paths where a single
+ * malicious filename should be skipped, not propagated up as an
+ * exception (e.g. iterating `readdirSync` results during cleanup).
+ */
+declare function tryJoin(baseDir: string, ...parts: string[]): string | null;
+/**
+ * Validate that a candidate path is already absolute and stays inside
+ * `baseDir`. Use when receiving a path from external config that the
+ * caller wants to treat as already-canonical (e.g. an env var that
+ * names a project directory) — the helper asserts the safety
+ * properties without further joining.
+ */
+declare function assertWithinBase(baseDir: string, candidate: string): string;
+
+/**
+ * Secret-redaction helpers for log lines and diagnostic output.
+ *
+ * # Why this exists
+ *
+ * AgenticMail keeps three kinds of long-lived secrets in memory:
+ *
+ *   1. The master key (`mk_…`) — full admin scope on the local API.
+ *   2. Per-agent API keys (`ak_…`) — scoped to one agent's mailbox.
+ *   3. Stalwart's admin password and per-agent IMAP/SMTP passwords.
+ *
+ * All three flow through config objects, install results, and the
+ * MCP-server env block. Several of those objects get logged for
+ * diagnostic purposes (install completion summary, dispatcher
+ * startup, error stacks). CodeQL's `js/clear-text-logging` query
+ * flagged eight call sites where a secret could plausibly reach a
+ * log line. This module is the canonical sanitizer for those spots.
+ *
+ * # API
+ *
+ *   - `redactSecret(value)` collapses a string secret to a
+ *     fixed-shape redaction marker (`mk_***`, `ak_***`, `***`)
+ *     while preserving the prefix so the log reader can still tell
+ *     the kind of secret it was.
+ *   - `redactObject(obj)` walks an object and replaces every value
+ *     under a "sensitive-looking" key with REDACTED.
+ *   - `REDACTED` constant for cases where the caller wants to
+ *     compose their own log line.
+ *
+ * # Conservative match
+ *
+ * The "sensitive-looking" key detection is deliberately broad —
+ * it's better to over-redact a harmless `name` field that happens
+ * to contain "key" than to leak a secret. The currently-matched
+ * key names (case-insensitive substring): `key`, `secret`,
+ * `password`, `token`, `apikey`, `masterkey`, `authorization`,
+ * `bearer`.
+ */
+/** Returned in place of any redacted secret. */
+declare const REDACTED = "***";
+/**
+ * Redact a string secret to a fixed-shape marker. Preserves the
+ * known prefixes (`mk_`, `ak_`) so log readers can still tell what
+ * kind of secret was elided.
+ *
+ * Non-string inputs return REDACTED unchanged.
+ */
+declare function redactSecret(value: unknown): string;
+/**
+ * Walk an object recursively. Any value under a key that looks
+ * sensitive (see SENSITIVE_KEY_PATTERNS above) is replaced with
+ * `REDACTED`. Arrays are walked too. The original object is NOT
+ * mutated — returns a shallow-cloned tree with the same shape.
+ *
+ * Use this when you want to pass a whole config object into a log
+ * line via JSON.stringify, e.g.:
+ *
+ * ```ts
+ * log.info('install complete', redactObject(result));
+ * ```
+ *
+ * Edge cases:
+ *   - Cycles are NOT supported; pass tree-shaped data only.
+ *   - Non-plain objects (Map, Set, Buffer, Date, Error) are returned
+ *     by reference unchanged — redaction is for plain config dicts.
+ *   - Symbols are skipped.
+ */
+declare function redactObject<T>(input: T, _depth?: number): T;
+
+/**
+ * SSRF-safe URL validation for the AgenticMail API base URL.
+ *
+ * # What this is for
+ *
+ * Every host integration (claudecode, codex, …) reads the master API
+ * URL from `~/.agenticmail/config.json` and uses it to build fetch
+ * requests. CodeQL's `js/request-forgery` query flags those fetch
+ * calls because the URL is operator-controlled (via the config file
+ * or env vars) and could theoretically be redirected to an internal
+ * service the host process can reach but the operator didn't intend.
+ *
+ * In practice the operator controls their own config file — there's
+ * no remote attacker controlling apiUrl in a self-hosted install.
+ * But defence-in-depth dictates we still validate, because:
+ *
+ *   - A malicious npm package that planted an env var (e.g.
+ *     `AGENTICMAIL_API_URL=http://169.254.169.254/latest/meta-data/`)
+ *     could redirect the dispatcher's API calls to a cloud-metadata
+ *     endpoint and exfiltrate IAM credentials in the response body.
+ *   - A `file://` or `javascript:` scheme would let the operator's
+ *     own typo cause undefined behavior.
+ *
+ * # The check
+ *
+ * `validateApiUrl(url)` rejects:
+ *
+ *   - Non-`http(s)://` schemes (`file://`, `javascript:`, `data:`,
+ *     `ftp://`, etc).
+ *   - Cloud metadata IPs (169.254.169.254 — AWS/Azure/GCP) and the
+ *     IPv6 equivalent fd00:ec2::254.
+ *   - Empty / malformed URLs (via `new URL` parse).
+ *
+ * The check intentionally does NOT restrict to localhost — operators
+ * legitimately run AgenticMail on a NAS or remote VM and point the
+ * host-integration installs at it. The cloud-metadata IPs are the
+ * only blanket block.
+ *
+ * # Why a separate canonicalisation step
+ *
+ * Returning the URL via `url.origin` (rather than the raw input
+ * string) gives CodeQL a sanitiser shape it recognises: the value
+ * is now constrained to whatever `URL` parsed it into, with no
+ * embedded credentials, query strings, or path traversal.
+ */
+/** Thrown when `validateApiUrl` rejects a candidate URL. */
+declare class UnsafeApiUrlError extends Error {
+    readonly raw: string;
+    readonly reason: string;
+    constructor(raw: string, reason: string);
+}
+/**
+ * Validate the operator-supplied AgenticMail API base URL.
+ *
+ * Returns the canonical origin form of the URL (`http://host:port`)
+ * so callers can build paths against it without worrying about
+ * trailing slashes or embedded auth. Throws `UnsafeApiUrlError` on
+ * any structural problem or blocked host.
+ */
+declare function validateApiUrl(raw: unknown): string;
+/**
+ * Build a full request URL from a validated base + path. Used by the
+ * host-integration api clients to ensure the path is appended via
+ * `URL` (escapes correctly) rather than string concat.
+ */
+declare function buildApiUrl(baseOrigin: string, pathAndQuery: string): string;
+
 interface DependencyStatus {
     name: string;
     installed: boolean;
@@ -2123,4 +2371,4 @@ declare class AgentMemoryStore {
     renderForPrompt(memory: AgentMemoryRead | null): string;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };