@msgly/gmail 0.2.1 → 0.2.3

package/README.md

@@ -224,6 +224,31 @@ Without any of these, the adapter still sends — just as a fresh email with sub
 | typing        | —         |
 | templates     | —         |
 
+## Production notes
+
+### Multi-instance deployments
+
+The "last seen historyId" is held in adapter memory. If you horizontally scale (multiple Node processes behind a load balancer), each instance has its own historyId tracker, and notifications routed to a different instance than the previous one will see a stale baseline.
+
+**Mitigations:**
+- Pin one process per inbox (sticky routing for the `/webhook/gmail` path), OR
+- Run a single worker for Gmail webhook handling (load balancer routes only one backend), OR
+- Wait for v2 which will accept a `historyIdStore` callback so you can persist to Redis/Postgres.
+
+In all cases, msgly's externalId-based idempotency means **duplicate fetches are deduplicated**, so the worst-case observable behavior is briefly missed messages (not duplicate emits). For a v1 deploy on a single instance, this is not a concern.
+
+### Push subscription authentication
+
+The three modes ranked by security:
+
+1. **`{ kind: 'jwt' }` (recommended for production)** — Pub/Sub signs each push with an OIDC token, we verify against Google's JWKS. Strongest. Requires enabling authentication on the Pub/Sub subscription.
+2. **`{ kind: 'token' }`** — A shared secret appended as `?token=...` to the push endpoint URL. The token lives in your Cloud Pub/Sub configuration and your env vars; if either leaks, an attacker can forge inbound notifications. Comparison is constant-time. **Acceptable for staging, not great for production.**
+3. **`{ kind: 'none' }`** — Skips verification entirely. **Local development only.** Anyone who knows your URL can forge inbound messages.
+
+### Header injection
+
+The adapter strips CR/LF from every header value (`From`, `To`, `Subject`, `In-Reply-To`, `References`) before constructing the outgoing RFC 5322 email. Even if upstream metadata is adversarial (malicious sender, compromised user input), the outgoing message can't have additional injected headers like `Bcc:` or `Reply-To:`.
+
 ## Common pitfalls
 
 - **No notifications arriving**: confirm the Pub/Sub topic grants `gmail-api-push@system.gserviceaccount.com` publish access. Confirm `users.watch()` returned a `historyId` (didn't error). Watches expire after ~7 days — schedule a daily re-call.

package/dist/index.cjs

@@ -0,0 +1,544 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createGmailAdapter: () => createGmailAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var DEFAULT_API_BASE = "https://gmail.googleapis.com";
+var DEFAULT_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs";
+var DEFAULT_CLOCK_SKEW_SEC = 300;
+var DEFAULT_MAX_MESSAGES = 25;
+var CAPABILITIES = {
+  text: true,
+  media: { image: false, video: false, audio: false, file: false },
+  interactive: { buttons: false, quickReplies: false },
+  templates: false,
+  reactions: false,
+  typing: false
+};
+function randomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function headerValue(headers, name) {
+  const v = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+function b64urlEncode(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/=+$/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function b64urlDecodeToBytes(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function b64urlDecodeToString(input) {
+  return new TextDecoder().decode(b64urlDecodeToBytes(input));
+}
+function createJwksCache(jwksUrl, ttlMs) {
+  let cache = null;
+  let inflight = null;
+  async function load(force = false) {
+    if (!force && cache && Date.now() - cache.fetchedAt < ttlMs) return cache;
+    if (inflight) return inflight;
+    inflight = (async () => {
+      const res = await fetch(jwksUrl);
+      if (!res.ok) throw new Error(`JWKS fetch failed: ${res.status}`);
+      const data = await res.json();
+      const keys = /* @__PURE__ */ new Map();
+      for (const jwk of data.keys ?? []) {
+        if (!jwk.kid || jwk.kty !== "RSA") continue;
+        try {
+          const key = await globalThis.crypto.subtle.importKey(
+            "jwk",
+            jwk,
+            { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+            false,
+            ["verify"]
+          );
+          keys.set(jwk.kid, key);
+        } catch {
+        }
+      }
+      const entry = { keys, fetchedAt: Date.now() };
+      cache = entry;
+      return entry;
+    })();
+    try {
+      return await inflight;
+    } finally {
+      inflight = null;
+    }
+  }
+  async function getKey(kid) {
+    let jwks = await load();
+    if (jwks.keys.has(kid)) return jwks.keys.get(kid);
+    jwks = await load(true);
+    return jwks.keys.get(kid) ?? null;
+  }
+  return { getKey };
+}
+async function verifyGoogleJwt(token, getKey, expectedAudience, expectedServiceAccountEmail, clockSkewSec) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  const [headerB64, payloadB64, sigB64] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(b64urlDecodeToString(headerB64));
+    claims = JSON.parse(b64urlDecodeToString(payloadB64));
+  } catch {
+    return false;
+  }
+  if (header.alg !== "RS256" || !header.kid) return false;
+  const key = await getKey(header.kid);
+  if (!key) return false;
+  const signature = b64urlDecodeToBytes(sigB64);
+  const signedInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const ok = await globalThis.crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    signature,
+    signedInput
+  );
+  if (!ok) return false;
+  const nowSec = Math.floor(Date.now() / 1e3);
+  if (typeof claims.exp === "number" && nowSec > claims.exp + clockSkewSec) return false;
+  if (typeof claims.nbf === "number" && nowSec + clockSkewSec < claims.nbf) return false;
+  if (claims.iss !== "https://accounts.google.com" && claims.iss !== "accounts.google.com") {
+    return false;
+  }
+  if (claims.aud !== expectedAudience) return false;
+  if (expectedServiceAccountEmail && claims.email !== expectedServiceAccountEmail) {
+    return false;
+  }
+  return true;
+}
+function createTokenCache(tokenUrl, clientId, clientSecret, refreshToken) {
+  let accessToken = null;
+  let expiresAt = 0;
+  let inflight = null;
+  async function fetchToken() {
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: clientId,
+        client_secret: clientSecret,
+        refresh_token: refreshToken
+      }).toString()
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.access_token) {
+      throw new Error(
+        `Google token refresh failed (${res.status}): ${data.error_description ?? data.error ?? "no body"}`
+      );
+    }
+    accessToken = data.access_token;
+    expiresAt = Date.now() + (data.expires_in ?? 3600) * 1e3 - 6e4;
+    return accessToken;
+  }
+  async function get() {
+    if (accessToken && Date.now() < expiresAt) return accessToken;
+    if (inflight) return inflight;
+    inflight = fetchToken();
+    try {
+      return await inflight;
+    } finally {
+      inflight = null;
+    }
+  }
+  return { get };
+}
+function findHeader(payload, name) {
+  const lower = name.toLowerCase();
+  for (const h of payload?.headers ?? []) {
+    if (h.name.toLowerCase() === lower) return h.value;
+  }
+  return void 0;
+}
+function findBodyByMimeType(payload, mimeType) {
+  if (!payload) return null;
+  if (payload.mimeType === mimeType && payload.body?.data) {
+    try {
+      return b64urlDecodeToString(payload.body.data);
+    } catch {
+      return null;
+    }
+  }
+  for (const part of payload.parts ?? []) {
+    const t = findBodyByMimeType(part, mimeType);
+    if (t !== null) return t;
+  }
+  return null;
+}
+function extractPlainText(payload) {
+  const plain = findBodyByMimeType(payload, "text/plain");
+  if (plain !== null) return plain.trim() || null;
+  const html = findBodyByMimeType(payload, "text/html");
+  if (html === null) return null;
+  return html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim() || null;
+}
+function parseEmailAddress(header) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  const angle = trimmed.match(/^(?:"?([^"<]+?)"?\s*)?<([^>]+)>$/);
+  if (angle) {
+    return {
+      address: angle[2].trim(),
+      displayName: angle[1]?.trim() || void 0
+    };
+  }
+  if (/^\S+@\S+$/.test(trimmed)) return { address: trimmed };
+  return null;
+}
+function sanitizeHeaderValue(value) {
+  return value.replace(/[\r\n]/g, "");
+}
+function buildReplyEmail(opts) {
+  const headers = [
+    `From: ${sanitizeHeaderValue(opts.from)}`,
+    `To: ${sanitizeHeaderValue(opts.to)}`,
+    `Subject: ${sanitizeHeaderValue(opts.subject)}`,
+    "MIME-Version: 1.0",
+    "Content-Type: text/plain; charset=utf-8",
+    "Content-Transfer-Encoding: 8bit",
+    `Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`
+  ];
+  if (opts.inReplyTo) headers.push(`In-Reply-To: ${sanitizeHeaderValue(opts.inReplyTo)}`);
+  if (opts.references) headers.push(`References: ${sanitizeHeaderValue(opts.references)}`);
+  return `${headers.join("\r\n")}\r
+\r
+${opts.body}`;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function stripReplyPrefix(subject) {
+  return subject.replace(/^(?:re|RE|Re)\s*:\s*/i, "").trim();
+}
+function createGmailAdapter(config) {
+  const tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+  const jwksUrl = config.jwksUrl ?? DEFAULT_JWKS_URL;
+  const clockSkewSec = config.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const maxMessages = config.maxMessagesPerNotification ?? DEFAULT_MAX_MESSAGES;
+  const tokens = createTokenCache(tokenUrl, config.clientId, config.clientSecret, config.refreshToken);
+  const jwks = createJwksCache(jwksUrl, 24 * 60 * 60 * 1e3);
+  let lastHistoryId = null;
+  async function authedFetch(path, init = {}) {
+    const token = await tokens.get();
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${token}`);
+    if (!headers.has("content-type") && init.body) {
+      headers.set("content-type", "application/json");
+    }
+    return fetch(`${apiBase}${path}`, { ...init, headers });
+  }
+  async function watch(topicName, labelIds = ["INBOX"]) {
+    const res = await authedFetch("/gmail/v1/users/me/watch", {
+      method: "POST",
+      body: JSON.stringify({ topicName, labelIds, labelFilterAction: "include" })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.historyId) {
+      throw new Error(`Gmail watch failed (${res.status}): ${data.error?.message ?? "no historyId"}`);
+    }
+    lastHistoryId = data.historyId;
+    return { historyId: data.historyId };
+  }
+  async function stopWatch() {
+    await authedFetch("/gmail/v1/users/me/stop", { method: "POST" });
+  }
+  async function fetchMessage(messageId) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}?format=full`
+    );
+    if (!res.ok) return null;
+    return await res.json();
+  }
+  async function listRecentInboxMessageIds(limit) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/messages?maxResults=${limit}&q=${encodeURIComponent("in:inbox -in:drafts is:unread")}`
+    );
+    if (!res.ok) return [];
+    const data = await res.json();
+    return (data.messages ?? []).map((m) => m.id);
+  }
+  async function listMessageIdsSince(startHistoryId) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/history?startHistoryId=${encodeURIComponent(startHistoryId)}&historyTypes=messageAdded&labelId=INBOX`
+    );
+    if (!res.ok) return [];
+    const data = await res.json();
+    const ids = /* @__PURE__ */ new Set();
+    for (const entry of data.history ?? []) {
+      for (const added of entry.messagesAdded ?? []) {
+        if (added.message?.id) ids.add(added.message.id);
+      }
+    }
+    return [...ids].slice(0, maxMessages);
+  }
+  function messageToInbound(msg) {
+    const text = extractPlainText(msg.payload);
+    if (!text) return null;
+    const from = parseEmailAddress(findHeader(msg.payload, "From"));
+    if (!from) return null;
+    const messageIdHeader = findHeader(msg.payload, "Message-ID") ?? findHeader(msg.payload, "Message-Id");
+    const subject = findHeader(msg.payload, "Subject") ?? "";
+    const references = findHeader(msg.payload, "References");
+    const dateHeader = findHeader(msg.payload, "Date");
+    const timestamp = (() => {
+      if (msg.internalDate) {
+        const ms = Number(msg.internalDate);
+        if (Number.isFinite(ms)) return new Date(ms).toISOString();
+      }
+      if (dateHeader) {
+        const parsed = Date.parse(dateHeader);
+        if (Number.isFinite(parsed)) return new Date(parsed).toISOString();
+      }
+      return (/* @__PURE__ */ new Date()).toISOString();
+    })();
+    return {
+      id: randomId(),
+      externalId: msg.id,
+      channel: "gmail",
+      direction: "inbound",
+      account: { channel: "gmail", channelAccountId: config.emailAddress },
+      contact: {
+        channel: "gmail",
+        channelUserId: from.address,
+        ...from.displayName ? { displayName: from.displayName } : {}
+      },
+      content: { type: "text", text },
+      timestamp,
+      raw: msg,
+      metadata: {
+        ...msg.threadId ? { threadId: msg.threadId } : {},
+        ...messageIdHeader ? { messageId: messageIdHeader } : {},
+        ...subject ? { subject } : {},
+        ...references ? { references } : {}
+      }
+    };
+  }
+  async function handleWebhook(req) {
+    const body = req.body;
+    const dataB64 = body?.message?.data;
+    if (!dataB64) return [];
+    let notification;
+    try {
+      notification = JSON.parse(b64urlDecodeToString(dataB64.replace(/=+$/g, "")));
+    } catch {
+      return [];
+    }
+    if (!notification.historyId) return [];
+    let messageIds;
+    if (lastHistoryId) {
+      messageIds = await listMessageIdsSince(lastHistoryId);
+    } else {
+      messageIds = await listRecentInboxMessageIds(maxMessages);
+    }
+    lastHistoryId = notification.historyId;
+    const out = [];
+    for (const id of messageIds) {
+      const msg = await fetchMessage(id);
+      if (!msg) continue;
+      const inbound = messageToInbound(msg);
+      if (inbound) out.push(inbound);
+    }
+    return out;
+  }
+  async function verifySignature(req) {
+    switch (config.pushAuth.kind) {
+      case "none":
+        return true;
+      case "token": {
+        const provided = req.query["token"];
+        const value = Array.isArray(provided) ? provided[0] : provided;
+        if (typeof value !== "string") return false;
+        return constantTimeEqual(value, config.pushAuth.token);
+      }
+      case "jwt": {
+        const auth = headerValue(req.headers, "authorization");
+        if (!auth || !auth.toLowerCase().startsWith("bearer ")) return false;
+        const token = auth.slice(7).trim();
+        if (!token) return false;
+        try {
+          return await verifyGoogleJwt(
+            token,
+            (kid) => jwks.getKey(kid),
+            config.pushAuth.expectedAudience,
+            config.pushAuth.expectedServiceAccountEmail,
+            clockSkewSec
+          );
+        } catch {
+          return false;
+        }
+      }
+    }
+  }
+  async function send(message) {
+    if (message.content.type !== "text") {
+      return {
+        messageId: message.id,
+        status: "failed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        error: {
+          code: "gmail_unsupported_content",
+          message: `Gmail adapter only supports text content in v1 (received: ${message.content.type})`
+        }
+      };
+    }
+    const subjectMeta = message.metadata?.["subject"];
+    const baseSubject = subjectMeta ? stripReplyPrefix(subjectMeta) : "";
+    const subject = baseSubject ? `Re: ${baseSubject}` : "(no subject)";
+    const inReplyTo = message.metadata?.["messageId"];
+    const referencesPrev = message.metadata?.["references"];
+    const references = inReplyTo ? referencesPrev ? `${referencesPrev} ${inReplyTo}` : inReplyTo : void 0;
+    const raw = buildReplyEmail({
+      from: config.emailAddress,
+      to: message.contact.channelUserId,
+      subject,
+      body: message.content.text,
+      inReplyTo,
+      references
+    });
+    const payload = { raw: b64urlEncode(raw) };
+    const threadId = message.metadata?.["threadId"];
+    if (threadId) payload["threadId"] = threadId;
+    const res = await authedFetch("/gmail/v1/users/me/messages/send", {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (res.status >= 200 && res.status < 300 && data.id) {
+      return {
+        messageId: message.id,
+        externalId: data.id,
+        status: "sent",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    return {
+      messageId: message.id,
+      status: "failed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: {
+        code: `gmail_${data.error?.code ?? res.status}`,
+        message: data.error?.message ?? `HTTP ${res.status}`
+      }
+    };
+  }
+  async function verifyCredentials() {
+    if (!config.clientId || !config.clientSecret) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.clientId / clientSecret missing. Generate them in Google Cloud Console \u2192 APIs & Services \u2192 Credentials \u2192 OAuth 2.0 Client ID."
+      };
+    }
+    if (!config.refreshToken) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.refreshToken missing. Run the consent flow once with prompt=consent and access_type=offline to obtain a long-lived refresh token."
+      };
+    }
+    if (!config.emailAddress) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.emailAddress missing. Set this to the mailbox the refresh token belongs to (e.g. agent@yourcompany.com)."
+      };
+    }
+    try {
+      const token = await tokens.get();
+      const res = await fetch(`${apiBase}/gmail/v1/users/me/profile`, {
+        headers: { authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401 || res.status === 403) {
+        return {
+          ok: false,
+          reason: "unauthorized",
+          hint: "Google rejected the access token. Check scopes (need gmail.modify) and re-run consent with prompt=consent."
+        };
+      }
+      if (!res.ok) {
+        return {
+          ok: false,
+          reason: "unknown",
+          hint: `Gmail profile lookup returned ${res.status}`
+        };
+      }
+      const data = await res.json();
+      return { ok: true, accountInfo: data.emailAddress ?? config.emailAddress };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/401|invalid_grant|invalid_client/i.test(msg)) {
+        return {
+          ok: false,
+          reason: "unauthorized",
+          hint: `Google rejected credentials: ${msg}. Re-check clientId/clientSecret/refreshToken.`
+        };
+      }
+      return { ok: false, reason: "network_error", hint: msg };
+    }
+  }
+  async function uploadMedia(_file) {
+    throw new Error("Gmail uploadMedia is not yet implemented in v1.");
+  }
+  async function downloadMedia(_ref) {
+    throw new Error("Gmail downloadMedia is not yet implemented in v1.");
+  }
+  return {
+    channel: "gmail",
+    capabilities: CAPABILITIES,
+    send,
+    handleWebhook,
+    verifySignature,
+    verifyCredentials,
+    uploadMedia,
+    downloadMedia,
+    watch,
+    stopWatch
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGmailAdapter
+});

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+import { Adapter } from '@msgly/core';
+
+interface GmailConfig {
+    /** OAuth client id from Google Cloud Console → Credentials → OAuth 2.0 Client ID. */
+    clientId: string;
+    /** OAuth client secret from the same place. */
+    clientSecret: string;
+    /**
+     * Long-lived refresh token for the agent's mailbox. Generated once via the
+     * OAuth 2.0 consent flow with `prompt=consent` and `access_type=offline`.
+     * Required scopes: `https://www.googleapis.com/auth/gmail.modify` (read +
+     * send + watch).
+     */
+    refreshToken: string;
+    /**
+     * The email address of the mailbox the refresh token belongs to.
+     * Used as the `From:` header on outgoing replies and as
+     * `account.channelAccountId`.
+     */
+    emailAddress: string;
+    /**
+     * How Pub/Sub push requests prove they came from Google. Pick ONE:
+     *
+     *   { kind: 'jwt', expectedAudience }
+     *     — Verify the OIDC JWT in `Authorization: Bearer <token>`.
+     *       expectedAudience should match the audience you configured on the
+     *       Pub/Sub push subscription (often the webhook URL itself).
+     *
+     *   { kind: 'token', token }
+     *     — Simpler: configure your push subscription with
+     *       `?token=...` and we'll match it against `req.query.token`.
+     *
+     *   { kind: 'none' } — DEV ONLY. No verification.
+     */
+    pushAuth: {
+        kind: 'jwt';
+        expectedAudience: string;
+        expectedServiceAccountEmail?: string;
+    } | {
+        kind: 'token';
+        token: string;
+    } | {
+        kind: 'none';
+    };
+    /** Cap how many messages we fetch per Pub/Sub notification. Default: 25. */
+    maxMessagesPerNotification?: number;
+    /** Override the Google OAuth token endpoint. Default: oauth2.googleapis.com. */
+    tokenUrl?: string;
+    /** Override the Gmail API base. Default: gmail.googleapis.com. */
+    apiBase?: string;
+    /** Override the JWKS URL used when `pushAuth.kind === 'jwt'`. Default: Google certs. */
+    jwksUrl?: string;
+    /** Allowed clock skew (sec) when validating JWT exp/nbf. Default: 300. */
+    clockSkewSec?: number;
+}
+interface GmailAdapter extends Adapter {
+    readonly channel: 'gmail';
+    /**
+     * Call once at deploy time to subscribe the mailbox to a Pub/Sub topic.
+     * The topic must already grant publish permission to
+     * `gmail-api-push@system.gserviceaccount.com`. Returns the historyId
+     * baseline.
+     */
+    watch(topicName: string, labelIds?: string[]): Promise<{
+        historyId: string;
+    }>;
+    /** Stop the existing watch. Mailbox stops emitting notifications. */
+    stopWatch(): Promise<void>;
+}
+/**
+ * Gmail adapter for Msgly — receives via Pub/Sub push notifications,
+ * sends via the Gmail REST API.
+ *
+ * **Receive flow.** Gmail publishes change notifications to a Pub/Sub topic
+ * (you set this up once via `users.watch`). Pub/Sub forwards each event to
+ * your webhook with body `{ message: { data: base64, ... }, subscription }`.
+ * `data` decodes to `{ emailAddress, historyId }`. The adapter calls
+ * `history.list` from the previously-seen historyId to discover new message
+ * IDs, fetches each via `messages.get?format=full`, and emits an inbound
+ * message per item.
+ *
+ * **State.** The "last seen historyId" is held in adapter memory. On the
+ * very first notification (cold start), the adapter falls back to fetching
+ * recent unread INBOX messages so nothing gets lost between deploys.
+ *
+ * **Send flow.** Builds an RFC 5322 email with proper In-Reply-To /
+ * References headers and posts to `users.messages.send`. If you pass
+ * `metadata.threadId` from the inbound message, Gmail keeps the reply in
+ * the original thread.
+ *
+ * **Auth.** Pub/Sub authenticates inbound webhooks via OIDC JWT
+ * (Authorization: Bearer) or a shared verification token, configurable via
+ * `pushAuth`. JWT verification uses Google's public JWKS and runs on pure
+ * WebCrypto (Node 18+, Bun, Deno, browsers).
+ */
+declare function createGmailAdapter(config: GmailConfig): GmailAdapter;
+
+export { type GmailAdapter, type GmailConfig, createGmailAdapter };

package/dist/index.js

@@ -198,22 +198,33 @@ function parseEmailAddress(header) {
   if (/^\S+@\S+$/.test(trimmed)) return { address: trimmed };
   return null;
 }
+function sanitizeHeaderValue(value) {
+  return value.replace(/[\r\n]/g, "");
+}
 function buildReplyEmail(opts) {
   const headers = [
-    `From: ${opts.from}`,
-    `To: ${opts.to}`,
-    `Subject: ${opts.subject}`,
+    `From: ${sanitizeHeaderValue(opts.from)}`,
+    `To: ${sanitizeHeaderValue(opts.to)}`,
+    `Subject: ${sanitizeHeaderValue(opts.subject)}`,
     "MIME-Version: 1.0",
     "Content-Type: text/plain; charset=utf-8",
     "Content-Transfer-Encoding: 8bit",
     `Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`
   ];
-  if (opts.inReplyTo) headers.push(`In-Reply-To: ${opts.inReplyTo}`);
-  if (opts.references) headers.push(`References: ${opts.references}`);
+  if (opts.inReplyTo) headers.push(`In-Reply-To: ${sanitizeHeaderValue(opts.inReplyTo)}`);
+  if (opts.references) headers.push(`References: ${sanitizeHeaderValue(opts.references)}`);
   return `${headers.join("\r\n")}\r
 \r
 ${opts.body}`;
 }
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
 function stripReplyPrefix(subject) {
   return subject.replace(/^(?:re|RE|Re)\s*:\s*/i, "").trim();
 }
@@ -355,7 +366,8 @@ function createGmailAdapter(config) {
       case "token": {
         const provided = req.query["token"];
         const value = Array.isArray(provided) ? provided[0] : provided;
-        return value === config.pushAuth.token;
+        if (typeof value !== "string") return false;
+        return constantTimeEqual(value, config.pushAuth.token);
       }
       case "jwt": {
         const auth = headerValue(req.headers, "authorization");

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@msgly/gmail",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Gmail adapter for Msgly — receive and reply to emails via Gmail API + Pub/Sub push",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -18,7 +19,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@msgly/core": "0.2.1"
+    "@msgly/core": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
@@ -44,8 +45,8 @@
     "webhook"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "test": "vitest run",
     "lint": "eslint src --ext .ts",
     "typecheck": "tsc --noEmit",