agents/dist/email-CL27preh.d.ts

A home for your AI agents

//#region src/email.d.ts
/**
 * Header object as returned by postal-mime and similar email parsing libraries.
 * Each header has a lowercase key and a string value.
 */
type EmailHeader = {
  /** Lowercase header name (e.g., "content-type", "x-custom-header") */ key: string /** Header value */;
  value: string;
};
/**
 * Check if an email appears to be an auto-reply based on standard headers.
 * Checks for Auto-Submitted (RFC 3834), X-Auto-Response-Suppress, and Precedence headers.
 *
 * @param headers - Headers array from postal-mime Email.headers or similar format
 * @returns true if email appears to be an auto-reply
 *
 * @example
 * ```typescript
 * if (isAutoReplyEmail(parsed.headers)) {
 *   // Skip processing auto-replies
 *   return;
 * }
 * ```
 */
declare function isAutoReplyEmail(headers: EmailHeader[]): boolean;
/** Default signature expiration: 30 days in seconds */
declare const DEFAULT_MAX_AGE_SECONDS: number;
/**
 * Sign agent routing headers for secure reply flows.
 * Use this when sending outbound emails to ensure replies can be securely routed back.
 *
 * @param secret - Secret key for HMAC signing (store in environment variables)
 * @param agentName - Name of the agent
 * @param agentId - ID of the agent instance
 * @returns Headers object with X-Agent-Name, X-Agent-ID, X-Agent-Sig, and X-Agent-Sig-Ts
 *
 * @example
 * ```typescript
 * const headers = await signAgentHeaders(env.EMAIL_SECRET, "MyAgent", this.name);
 * // Use these headers when sending outbound emails
 * ```
 */
declare function signAgentHeaders(
  secret: string,
  agentName: string,
  agentId: string
): Promise<Record<string, string>>;
type EmailResolverResult = {
  agentName: string;
  agentId: string /** @internal Indicates this resolver requires secure reply signing */;
  _secureRouted?: boolean;
} | null;
type EmailResolver<Env> = (
  email: ForwardableEmailMessage,
  env: Env
) => Promise<EmailResolverResult>;
/**
 * Reason for signature verification failure
 */
type SignatureFailureReason =
  | "missing_headers"
  | "expired"
  | "invalid"
  | "malformed_timestamp";
/**
 * Options for createSecureReplyEmailResolver
 */
type SecureReplyResolverOptions = {
  /**
   * Maximum age of signature in seconds.
   * Signatures older than this will be rejected.
   * Default: 30 days (2592000 seconds)
   */
  maxAge?: number;
  /**
   * Callback invoked when signature verification fails.
   * Useful for logging and debugging.
   */
  onInvalidSignature?: (
    email: ForwardableEmailMessage,
    reason: SignatureFailureReason
  ) => void;
};
/**
 * @deprecated REMOVED due to security vulnerability (IDOR via spoofed headers).
 * @throws Always throws an error with migration guidance.
 */
declare function createHeaderBasedEmailResolver<Env>(): EmailResolver<Env>;
/**
 * Create a resolver for routing email replies with signature verification.
 * This resolver verifies that replies contain a valid HMAC signature, preventing
 * attackers from routing emails to arbitrary agent instances.
 *
 * @param secret - Secret key for HMAC verification (must match the key used with signAgentHeaders)
 * @param options - Optional configuration for signature verification
 * @returns A function that resolves the agent to route the email to, or null if signature is invalid
 *
 * @example
 * ```typescript
 * // In your email handler
 * const secureResolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {
 *   maxAge: 7 * 24 * 60 * 60, // 7 days
 *   onInvalidSignature: (email, reason) => {
 *     console.warn(`Invalid signature from ${email.from}: ${reason}`);
 *   }
 * });
 * const addressResolver = createAddressBasedEmailResolver("MyAgent");
 *
 * await routeAgentEmail(email, env, {
 *   resolver: async (email, env) => {
 *     // Try secure reply routing first
 *     const replyRouting = await secureResolver(email, env);
 *     if (replyRouting) return replyRouting;
 *     // Fall back to address-based routing
 *     return addressResolver(email, env);
 *   }
 * });
 * ```
 */
declare function createSecureReplyEmailResolver<Env>(
  secret: string,
  options?: SecureReplyResolverOptions
): EmailResolver<Env>;
/**
 * Create a resolver that uses the email address to determine the agent to route the email to
 * @param defaultAgentName The default agent name to use if the email address does not contain a sub-address
 * @returns A function that resolves the agent to route the email to
 */
declare function createAddressBasedEmailResolver<Env>(
  defaultAgentName: string
): EmailResolver<Env>;
/**
 * Create a resolver that uses the agentName and agentId to determine the agent to route the email to
 * @param agentName The name of the agent to route the email to
 * @param agentId The id of the agent to route the email to
 * @returns A function that resolves the agent to route the email to
 */
declare function createCatchAllEmailResolver<Env>(
  agentName: string,
  agentId: string
): EmailResolver<Env>;
//#endregion
export {
  SecureReplyResolverOptions as a,
  createCatchAllEmailResolver as c,
  isAutoReplyEmail as d,
  signAgentHeaders as f,
  EmailResolverResult as i,
  createHeaderBasedEmailResolver as l,
  EmailHeader as n,
  SignatureFailureReason as o,
  EmailResolver as r,
  createAddressBasedEmailResolver as s,
  DEFAULT_MAX_AGE_SECONDS as t,
  createSecureReplyEmailResolver as u
};
//# sourceMappingURL=email-CL27preh.d.ts.map