@agenticmail/core 0.9.4 → 0.9.6

package/dist/index.d.cts

@@ -1583,6 +1583,377 @@ 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;
+
+/**
+ * Persisted host-session registry.
+ *
+ * # What this is for
+ *
+ * When a sub-agent replies into the host bridge inbox
+ * (`claudecode@localhost` / `codex@localhost`), the dispatcher
+ * historically had no way to react: bridges are skipped by
+ * `shouldWatch` because they belong to the human operator's host CLI,
+ * not to an automated worker. The mail would sit unread until the
+ * operator opened their CLI again — sometimes hours later, sometimes
+ * never that day.
+ *
+ * This module is the missing link. Every time the host's mail-hook
+ * fires (on `SessionStart` / `UserPromptSubmit` / `Stop`), it captures
+ * the host CLI's current `session_id` and persists it here. The
+ * dispatcher can then check "what session was running last?" and
+ * attempt a headless resume against it when bridge mail arrives —
+ * the same way Telegram bridges (Fola, etc.) keep a session alive
+ * between bursts of activity.
+ *
+ * # The file
+ *
+ * `~/.agenticmail/host-sessions.json`:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "sessions": {
+ *     "claudecode": {
+ *       "sessionId": "01a2b3c4-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905200000,
+ *       "model": "claude-sonnet-4-5"
+ *     },
+ *     "codex": {
+ *       "sessionId": "019a2b3c-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905100000
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Per host we keep ONE session — the most recent. If the operator
+ * runs `claude` twice (e.g. one window for "general", one for "build
+ * the LinkedIn clone"), we only track the last-active one. The
+ * bridge resume always targets whichever was active most recently;
+ * the operator's intuition matches that ("I just left my Claude
+ * Code session a minute ago and the bridge ought to be able to
+ * resume it").
+ *
+ * # Freshness semantics
+ *
+ * A session is considered "resumable" if `lastSeenMs` is within the
+ * last 24 hours. Older than that, both Anthropic and OpenAI tend to
+ * have evicted the session from their resume cache (cost-driven
+ * decision; observed empirically). The dispatcher uses
+ * `isSessionFresh(session, maxAgeMs)` to gate the resume attempt and
+ * fall through to SMS / persistent storage when stale.
+ *
+ * # Atomic writes
+ *
+ * The mail-hook can fire concurrently with another hook on a
+ * different host CLI window. The write path goes through a tmp file
+ * + rename so a torn write can never leave a half-valid JSON file
+ * that crashes the next reader. Same shape as `dispatcher-state.ts`.
+ */
+/** Canonical names for the host integrations that own bridge inboxes. */
+type HostName = 'claudecode' | 'codex';
+/**
+ * A snapshot of one host CLI's last-known session. Persisted to disk
+ * by the mail-hook on every fire; loaded by the dispatcher when
+ * bridge mail arrives so a resume can be attempted.
+ */
+interface HostSession {
+    /** Stable session_id from the host CLI (Claude Code or Codex). */
+    sessionId: string;
+    /** Wall-clock timestamp of the last hook fire on this session. */
+    lastSeenMs: number;
+    /** Optional: project cwd the host CLI was opened in. Used by
+     *  resume to spawn the headless turn in the right directory. */
+    workspace?: string;
+    /** Optional: model name the host session was using, surfaced
+     *  in logs for diagnostic context. */
+    model?: string;
+}
+/** Default freshness window — sessions older than this are skipped. */
+declare const DEFAULT_SESSION_MAX_AGE_MS: number;
+/**
+ * Record the current host session. Called from the mail-hook on
+ * every fire with the `session_id` the host passed in. Updates the
+ * existing record for that host or creates one — last write wins.
+ *
+ * Failures are swallowed so the mail-hook never crashes the host CLI
+ * over a disk write. The bridge-wake path tolerates a missing record
+ * (falls through to SMS).
+ */
+declare function saveHostSession(host: HostName, session: Omit<HostSession, 'lastSeenMs'>): void;
+/**
+ * Look up the most-recent session for a host. Returns null when no
+ * record exists OR the record is older than `maxAgeMs` (default 24h).
+ *
+ * The age gate exists because both providers expire resume tokens
+ * after roughly a day; attempting resume against a stale token is
+ * almost always slower than starting fresh.
+ */
+declare function loadHostSession(host: HostName, maxAgeMs?: number): HostSession | null;
+/**
+ * Pure freshness predicate — exported for tests + for callers that
+ * want to read the raw record (e.g. to print "last seen 2 hours ago"
+ * in a diagnostic command).
+ */
+declare function isSessionFresh(session: HostSession, maxAgeMs?: number): boolean;
+/**
+ * Clear a host's recorded session. Called when the operator runs
+ * `agenticmail-<host> uninstall` so the next install doesn't try to
+ * resume a session that no longer exists.
+ */
+declare function forgetHostSession(host: HostName): void;
+/** Exposed for tests + the `agenticmail status` diagnostic command. */
+declare function hostSessionStoragePath(): string;
+
+/**
+ * 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 +2494,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, DEFAULT_SESSION_MAX_AGE_MS, 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 HostName, type HostSession, 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, forgetHostSession, getDatabase, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };