fix: 8 CodeRabbit findings (Major/Minor/Trivial) + strict typecheck

Major fixes
- package.json: wire `tsc --noEmit` into `build` via new `typecheck`
  script. tsup transpiles but does not enforce TS diagnostics; the
  safety net is back.
- tsconfig.json: move to `module: NodeNext` / `moduleResolution: nodenext`
  and `target: ES2022` so the deprecated `node10` path no longer
  blocks tsc, `resolveJsonModule` added for completeness.
- src/*.ts: real unknown-error narrowing in 3 catch blocks, null-safe
  payload access in download_attachment, GmailLabel/GmailMessagePart
  now typed via `gmail_v1.Schema$*` instead of hand-written shapes
  that were stricter than the SDK reality.
- CHANGELOG.md: promote the accumulated content to `[0.1.0] - 2026-04-22`
  so the release-notes extractor can match the first tag. A fresh
  `[Unreleased]` stub keeps the next cycle unblocked.
- codecov.yml: drop `if_no_uploads: success` / `if_not_found: success`.
  Missing coverage now fails the gate instead of silently no-op'ing.
  Add an `ignore` list for doc/config-only PRs that legitimately
  produce no coverage.
- ASSURANCE_CASE.md CWE-79: reclassify from "N/A — no HTML output" to
  "out-of-scope for this process", documenting that download_email /
  read_email do surface HTML bodies and the consumer is responsible
  for sanitisation before rendering.

Minor
- ASSURANCE_CASE.md: Scorecard trigger description now matches the
  actual workflow (push to main + weekly + branch_protection_rule,
  not every commit).
- README.md: `gmail.readonly` scope row now clarifies that filter
  tools require `gmail.settings.basic`.

Trivial
- ci.yml: coverage instrumentation runs only on the Node 20 axis; the
  22/24 axes run plain `npm test` so we do not pay the vitest-v8
  overhead three times for one coverage upload. `fail_ci_if_error` on
  Codecov is now `true`.
- reply-all-helpers.test.ts: two regression tests lock the quoted-
  comma parser ('Doe, John' and multi-entry variants).

Tests: 129/129. Build + lint + format:check clean.

Author: klodr

.github/workflows/ci.yml

@@ -59,13 +59,18 @@ jobs:
       - name: Build
         run: npm run build
 
-      - name: Test with coverage
+      - name: Test
+        if: matrix.node != '20'
+        run: npm test
+
+      - name: Test with coverage (Node 20 only)
+        if: matrix.node == '20'
         run: npm run test:coverage
 
       - name: Upload coverage to Codecov
         if: matrix.node == '20'
         uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
         with:
-          fail_ci_if_error: false
+          fail_ci_if_error: true
           slug: klodr/gmail-mcp
           token: ${{ secrets.CODECOV_TOKEN }}

ASSURANCE_CASE.md

@@ -145,7 +145,7 @@ and scope filtering all live at that boundary.
 | **Fail closed** | Missing `~/.gmail-mcp/gcp-oauth.keys.json` → exit at startup with a clear error. Attachment path outside the jail → refuse before any write. Non-loopback OAuth callback hostname → reject at `authenticate()`. Invalid Zod input → refuse before the Gmail API call. |
 | **Minimise attack surface** | Single-file ESM bundle via `tsup` (no sourcemaps in the published tarball); only `dist/`, `README.md`, `LICENSE` in the npm files allowlist. No HTTP transport (stdio only) outside of the one-shot OAuth callback server. Tool list gated by OAuth scope. |
 | **Secrets are env-only / local-only** | OAuth refresh token at `~/.gmail-mcp/credentials.json` (mode `0o600`); client keys at `~/.gmail-mcp/gcp-oauth.keys.json` (user-provided). No secret ever travels over MCP stdout or MCP tool results. |
-| **Auditable & reproducible** | Every release is Sigstore-signed and SLSA-attested. Every commit triggers CI on Node 20/22/24 + CodeQL + Scorecard + Socket + CodeRabbit. |
+| **Auditable & reproducible** | Every release is Sigstore-signed and SLSA-attested. Every commit triggers CI on Node 20/22/24 + CodeQL + Socket + CodeRabbit. OpenSSF Scorecard runs on push to `main`, weekly on Monday, and on branch-protection rule changes (not on every PR commit). |
 | **Open source, MIT** | Anyone can audit. Project continuity documented in [CONTINUITY.md](./CONTINUITY.md). |
 
 ## 4. Common implementation weaknesses countered
@@ -158,7 +158,7 @@ Mapped to [CWE](https://cwe.mitre.org/) and [OWASP Top 10](https://owasp.org/Top
 | **CWE-59** Symlink following | Countered | Every leaf file write uses `fs.openSync` with `O_NOFOLLOW`; a pre-existing symlink at the destination causes the open to fail. |
 | **CWE-78 / CWE-94** Command / code injection | N/A | No `child_process`, no `eval`, no dynamic `require`. |
 | **CWE-89** SQL injection | N/A | No database. |
-| **CWE-79** XSS | N/A | No HTML output. |
+| **CWE-79** XSS | Out-of-scope for this process (MCP never renders HTML) — downstream responsibility | The `download_email` tool writes HTML bodies (via `emailToHtml()`) verbatim to `GMAIL_MCP_DOWNLOAD_DIR` and the `read_email` tool returns HTML string content to the MCP client. This MCP does not render HTML itself. If the consuming agent forwards that HTML to a browser, PDF pipeline, or any other HTML-executing surface, the agent must sanitise before rendering. Flagged transparently rather than claimed N/A. |
 | **CWE-88 / CWE-93 / CWE-113** CRLF / header injection | Countered | `sanitizeHeaderValue` strips `\r`, `\n`, `\0` from every user-supplied RFC-822 header value (`From`, `To`, `Cc`, `Bcc`, `Subject`, `In-Reply-To`, `References`). |
 | **CWE-117** Log injection | N/A | MCP emits no log file of its own (tracked as a future audit-log feature in [SECURITY.md](./SECURITY.md)). |
 | **CWE-200 / CWE-209** Information exposure / verbose errors | Countered | Error messages never include the OAuth refresh token or the Google OAuth client secret. |

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Placeholder for the next release cycle.
+
+## [0.1.0] - 2026-04-22
+
+### Added
+
 - **Attachment jail** (`GMAIL_MCP_ATTACHMENT_DIR`, default `~/GmailAttachments/`, mode `0o700`). Every attachment path passed to `send_email` / `draft_email` / `reply_all` is `realpath`-canonicalized and rejected if it escapes the jail. Symlink-to-outside is rejected. Closes the headline prompt-injection exfiltration vector (a crafted inbound email instructing the agent to attach `~/.ssh/id_rsa` etc.).
 - **Download jail** (`GMAIL_MCP_DOWNLOAD_DIR`, default `~/GmailDownloads/`, mode `0o700`). `download_email` and `download_attachment` write exclusively inside this directory. The leaf is opened with `O_NOFOLLOW` so a pre-existing symlink at the destination cannot be used to escape. Post-`mkdir` the resolved path is re-verified against the jail root (TOCTOU defense).
 - **Zod schema bounds**: `SearchEmailsSchema.maxResults` ≤ 500, `ListInboxThreadsSchema.maxResults` ≤ 500, `GetInboxWithThreadsSchema.maxResults` ≤ 500 (≤ 100 when `expandThreads=true`), `Batch*EmailsSchema.messageIds` ≤ 1000, `Batch*EmailsSchema.batchSize` ≤ 100. Blocks resource-exhaustion requests.

README.md

@@ -144,7 +144,7 @@ See [llms-install.md](./llms-install.md) for an LLM-readable install guide.
 
 | Scope shorthand | Full Gmail scope | What it grants |
 |---|---|---|
-| `gmail.readonly` | `…/auth/gmail.readonly` | Read messages, threads, labels, filters |
+| `gmail.readonly` | `…/auth/gmail.readonly` | Read messages, threads, labels (filter tools require `gmail.settings.basic`) |
 | `gmail.modify` | `…/auth/gmail.modify` | Readonly + apply/remove labels, delete messages |
 | `gmail.compose` | `…/auth/gmail.compose` | Create drafts |
 | `gmail.send` | `…/auth/gmail.send` | Send messages |

codecov.yml

@@ -5,17 +5,15 @@ coverage:
         target: auto
         threshold: 0.5%
         # Project coverage shouldn't drop more than 0.5% in any single PR.
-        if_no_uploads: success
-        if_not_found: success
-        # PRs that don't touch source code (CI bumps, doc-only, GitHub
-        # Actions updates) produce no coverage upload — pass instead of
-        # blocking on a missing report.
+        # if_no_uploads / if_not_found default to "failure" so a broken
+        # upload step (vitest crash, Codecov outage, missing token) is
+        # visible instead of silently turning the gate into a no-op.
+        only_pulls: false
     patch:
       default:
         target: 95%
         threshold: 1.5%
-        if_no_uploads: success
-        if_not_found: success
+        only_pulls: false
         # Strict patch gate (95% target, 1.5% threshold) — new code must
         # be ≥93.5% covered. The 1.5% threshold (vs an absolute 95%
         # requirement) exists for two narrow exceptions, not a blanket
@@ -24,6 +22,17 @@ coverage:
         #   branches) are intentionally hard to exercise in unit tests.
         # - Pure-formatting PRs (Prettier reflows, ESLint cleanups)
         #   surface as "new" lines but add no logic to test.
+        # A missing upload still fails by default so broken CI surfaces.
+  ignore:
+    # Doc-only / config-only PRs never touch these paths, so Codecov
+    # has no reason to demand coverage for them even though their file
+    # trees live under the repository root.
+    - "**/*.md"
+    - "**/*.yaml"
+    - "**/*.yml"
+    - "**/*.json"
+    - ".github/**"
+    - "scripts/**"
 
 comment:
   layout: "reach,diff,flags,files,footer"

package.json

@@ -8,7 +8,8 @@
     "gmail-mcp": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck && tsup",
     "start": "node dist/index.js",
     "auth": "node dist/index.js auth",
     "test": "vitest run",

src/index.ts

@@ -84,22 +84,11 @@ const OAUTH_PATH = process.env.GMAIL_OAUTH_PATH || path.join(CONFIG_DIR, "gcp-oa
 const CREDENTIALS_PATH =
   process.env.GMAIL_CREDENTIALS_PATH || path.join(CONFIG_DIR, "credentials.json");
 
-// Type definitions for Gmail API responses
-interface GmailMessagePart {
-  partId?: string;
-  mimeType?: string;
-  filename?: string;
-  headers?: Array<{
-    name: string;
-    value: string;
-  }>;
-  body?: {
-    attachmentId?: string;
-    size?: number;
-    data?: string;
-  };
-  parts?: GmailMessagePart[];
-}
+// Type definitions for Gmail API responses.
+// Accepts both our canonical shape and googleapis' `Schema$MessagePart`,
+// which differs only by widening every optional `string` to `string | null`.
+import type { gmail_v1 as gmail_v1_types } from "googleapis";
+type GmailMessagePart = gmail_v1_types.Schema$MessagePart;
 
 interface EmailContent {
   text: string;
@@ -478,8 +467,9 @@ async function main() {
               }
             }
           } catch (threadError: unknown) {
+            const msg = threadError instanceof Error ? threadError.message : String(threadError);
             console.warn(
-              `Warning: Could not fetch thread ${validatedArgs.threadId} for header resolution: ${threadError.message}`,
+              `Warning: Could not fetch thread ${validatedArgs.threadId} for header resolution: ${msg}`,
             );
             // Continue without threading headers - degraded but not broken
           }
@@ -599,9 +589,10 @@ async function main() {
       } catch (error: unknown) {
         // Log attachment-related errors for debugging
         if (validatedArgs.attachments && validatedArgs.attachments.length > 0) {
+          const msg = error instanceof Error ? error.message : String(error);
           console.error(
             `Failed to send email with ${validatedArgs.attachments.length} attachments:`,
-            error.message,
+            msg,
           );
         }
         throw error;
@@ -812,11 +803,12 @@ async function main() {
               ],
             };
           } catch (error: unknown) {
+            const msg = error instanceof Error ? error.message : String(error);
             return {
               content: [
                 {
                   type: "text",
-                  text: `Failed to download email: ${error.message}`,
+                  text: `Failed to download email: ${msg}`,
                 },
               ],
             };
@@ -1320,8 +1312,9 @@ async function main() {
               };
 
               filename =
-                findAttachment(messageResponse.data.payload) ||
-                `attachment-${validatedArgs.attachmentId}`;
+                (messageResponse.data.payload
+                  ? findAttachment(messageResponse.data.payload)
+                  : null) || `attachment-${validatedArgs.attachmentId}`;
             }
 
             // Sanitize filename to prevent path traversal
@@ -1348,11 +1341,12 @@ async function main() {
               ],
             };
           } catch (error: unknown) {
+            const msg = error instanceof Error ? error.message : String(error);
             return {
               content: [
                 {
                   type: "text",
-                  text: `Failed to download attachment: ${error.message}`,
+                  text: `Failed to download attachment: ${msg}`,
                 },
               ],
             };
@@ -1403,7 +1397,7 @@ async function main() {
               }
             };
             if (msg.payload) {
-              processAttachmentParts(msg.payload as GmailMessagePart);
+              processAttachmentParts(msg.payload);
             }
 
             return {
@@ -1597,7 +1591,7 @@ async function main() {
                   }
                 };
                 if (msg.payload) {
-                  processAttachmentParts(msg.payload as GmailMessagePart);
+                  processAttachmentParts(msg.payload);
                 }
 
                 return {
@@ -1752,11 +1746,12 @@ async function main() {
           throw new Error(`Unknown tool: ${name}`);
       }
     } catch (error: unknown) {
+      const msg = error instanceof Error ? error.message : String(error);
       return {
         content: [
           {
             type: "text",
-            text: `Error: ${error.message}`,
+            text: `Error: ${msg}`,
           },
         ],
       };

src/label-manager.ts

@@ -6,20 +6,10 @@
 import type { gmail_v1 } from "googleapis";
 import { asGmailApiError } from "./gmail-errors.js";
 
-// Type definitions for Gmail API labels
-export interface GmailLabel {
-  id: string;
-  name: string;
-  type?: string;
-  messageListVisibility?: string;
-  labelListVisibility?: string;
-  messagesTotal?: number;
-  messagesUnread?: number;
-  color?: {
-    textColor?: string;
-    backgroundColor?: string;
-  };
-}
+// Re-export googleapis' Schema$Label under our historical name so call
+// sites can keep using `GmailLabel` unchanged while benefiting from the
+// canonical (nullable) typing the SDK actually returns.
+export type GmailLabel = gmail_v1.Schema$Label;
 
 /**
  * Creates a new Gmail label

src/reply-all-helpers.test.ts

@@ -49,6 +49,24 @@ describe("parseEmailAddresses", () => {
   it("ignores entries without @ symbol", () => {
     expect(parseEmailAddresses("invalid, user@example.com")).toEqual(["user@example.com"]);
   });
+
+  it("does not split on commas inside quoted display names", () => {
+    // Regression: a naive split(",") would produce three garbage tokens
+    // for '"Doe, John" <john@example.com>, jane@example.com'. The
+    // quote-aware tokenizer must return two recipients.
+    expect(parseEmailAddresses('"Doe, John" <john@example.com>, jane@example.com')).toEqual([
+      "john@example.com",
+      "jane@example.com",
+    ]);
+  });
+
+  it("handles multiple quoted display names with commas", () => {
+    expect(
+      parseEmailAddresses(
+        '"Smith, Alice" <alice@example.com>, "Jones, Bob" <bob@example.com>, "Brown, Carol" <carol@example.com>',
+      ),
+    ).toEqual(["alice@example.com", "bob@example.com", "carol@example.com"]);
+  });
 });
 
 describe("filterOutEmail", () => {

src/tools.ts

@@ -343,6 +343,9 @@ export interface ToolAnnotations {
 export interface ToolDefinition {
   name: string;
   description: string;
+  // zod-to-json-schema@3's public signature widens to `z.ZodType<any>`;
+  // using a tighter generic here causes a structural mismatch at the
+  // consumer call site. The `any` is fenced inside ToolDefinition only.
   schema: z.ZodType<unknown>;
   scopes: string[]; // Any of these scopes grants access
   annotations: ToolAnnotations;
@@ -544,12 +547,17 @@ export const toolDefinitions: ToolDefinition[] = [
   },
 ];
 
-// Convert tool definitions to MCP tool format
+// Convert tool definitions to MCP tool format.
+// The cast bridges a generics mismatch between Zod v4's `ZodType` shape
+// and zod-to-json-schema@3's expected `ZodType<any, ZodTypeDef, any>`.
+// Runtime behaviour is unaffected — both APIs consume the same schema
+// instance, only the TS generic signatures differ.
 export function toMcpTools(tools: ToolDefinition[]) {
   return tools.map((tool) => ({
     name: tool.name,
     description: tool.description,
-    inputSchema: zodToJsonSchema(tool.schema),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    inputSchema: zodToJsonSchema(tool.schema as any),
     annotations: tool.annotations,
   }));
 }