@aaronsb/google-workspace-mcp 4.6.1 → 4.7.0

package/build/server/preview-gate.js

@@ -0,0 +1,105 @@
+/**
+ * The preview gate for standing-effect writes (ADR-309).
+ *
+ * A preview mints a token over the exact payload it evaluated; the write refuses without
+ * one. The token is an HMAC under a key made at process start, so nothing is stored and
+ * nothing needs cleaning up. A restart invalidates every outstanding token, and the remedy
+ * is to preview again.
+ *
+ * A token proves the evaluation was returned to the caller. It does not prove a person
+ * read it; that is the MCP client's per-call permission prompt.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { currentCallId } from './call-context.js';
+const KEY = randomBytes(32);
+/** How long a preview stays good. Match counts and conflicts drift as mail arrives. */
+export const PREVIEW_TTL_MS = 30 * 60_000;
+/** Tolerated clock skew for a token that claims to come from the future. */
+const SKEW_MS = 60_000;
+/** JSON with object keys sorted at every depth, so equal payloads serialize equally. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function mac(headerPart, account, payload) {
+    return createHmac('sha256', KEY)
+        .update(headerPart).update('\n')
+        .update(account.toLowerCase()).update('\n')
+        .update(canonicalJson(payload))
+        .digest();
+}
+/** Mint a token for `kind`, bound to this account, this payload, now, and this call. */
+export function mintPreviewToken(kind, account, payload, now = Date.now()) {
+    const header = { k: kind, t: now, c: currentCallId() };
+    const headerPart = Buffer.from(JSON.stringify(header)).toString('base64url');
+    return `${headerPart}.${mac(headerPart, account, payload).toString('base64url')}`;
+}
+/** Check a token against the write about to happen. */
+export function checkPreviewToken(token, kind, account, payload, now = Date.now()) {
+    if (typeof token !== 'string' || token.trim() === '')
+        return { ok: false, failure: 'missing' };
+    const [headerPart, macPart, extra] = token.trim().split('.');
+    if (!headerPart || !macPart || extra !== undefined)
+        return { ok: false, failure: 'malformed' };
+    let header;
+    try {
+        header = JSON.parse(Buffer.from(headerPart, 'base64url').toString('utf-8'));
+    }
+    catch {
+        return { ok: false, failure: 'malformed' };
+    }
+    if (typeof header?.k !== 'string' || typeof header.t !== 'number' || typeof header.c !== 'number') {
+        return { ok: false, failure: 'malformed' };
+    }
+    // The kind is read before the MAC because sibling operations sign different payloads, so
+    // a token meant for one always fails the other's MAC and would be reported as a changed
+    // parameter. Reading the unverified header here can only choose which refusal to give;
+    // nothing in it is trusted until the MAC agrees.
+    if (header.k !== kind)
+        return { ok: false, failure: 'wrong-kind', issuedFor: header.k };
+    const expected = mac(headerPart, account, payload);
+    const given = Buffer.from(macPart, 'base64url');
+    const genuine = given.length === expected.length && timingSafeEqual(given, expected);
+    if (!genuine)
+        return { ok: false, failure: 'mismatch' };
+    if (header.t > now + SKEW_MS || now - header.t > PREVIEW_TTL_MS)
+        return { ok: false, failure: 'expired' };
+    if (header.c !== 0 && header.c === currentCallId())
+        return { ok: false, failure: 'same-call' };
+    return { ok: true };
+}
+/**
+ * The sentence a refused write returns.
+ *
+ * @param write The operation refused, e.g. `createFilter`.
+ * @param preview The operation that mints its token, e.g. `previewFilter`.
+ */
+export function describeTokenFailure(check, write, preview) {
+    const again = `Call \`${preview}\` with these exact parameters and pass the previewToken it returns.`;
+    switch (check.failure) {
+        case 'missing':
+            return `\`${write}\` needs a previewToken. It changes what happens to mail that has not arrived yet, ` +
+                `so it runs only after a preview of this exact change has been returned. ${again}`;
+        case 'malformed':
+            return `The previewToken is not one this server issued. ${again}`;
+        case 'wrong-kind':
+            return `This previewToken came from a preview for ${check.issuedFor ?? 'another operation'}, not \`${write}\`. ${again}`;
+        case 'mismatch':
+            return `This previewToken does not match this change on this account. Either a parameter changed since ` +
+                `the preview, the token came from another account, or the server restarted. ${again}`;
+        case 'expired':
+            return `This previewToken has expired; previews are good for ${PREVIEW_TTL_MS / 60_000} minutes because ` +
+                `what they match changes as mail arrives. ${again}`;
+        case 'same-call':
+            return `This previewToken was minted earlier in this same tool call, so the preview was never returned ` +
+                `before \`${write}\` ran. Run the preview as its own call, read it, then call \`${write}\`.`;
+    }
+}
+//# sourceMappingURL=preview-gate.js.map

package/build/server/preview-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-gate.js","sourceRoot":"","sources":["../../src/server/preview-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;AAE5B,uFAAuF;AACvF,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,MAAM,CAAC;AAE1C,4EAA4E;AAC5E,MAAM,OAAO,GAAG,MAAM,CAAC;AAiBvB,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3E,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;aAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC9F,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,GAAG,CAAC,UAAkB,EAAE,OAAe,EAAE,OAAgB;IAChE,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC;SAC7B,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;SAC/B,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;SAC1C,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;SAC9B,MAAM,EAAE,CAAC;AACd,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe,EAAE,OAAgB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAChG,MAAM,MAAM,GAAgB,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC;IACpE,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC7E,OAAO,GAAG,UAAU,IAAI,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,IAAY,EACZ,OAAe,EACf,OAAgB,EAChB,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAE/F,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAE/F,IAAI,MAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAgB,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAC7C,CAAC;IACD,IAAI,OAAO,MAAM,EAAE,CAAC,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;QAClG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAC7C,CAAC;IAED,yFAAyF;IACzF,wFAAwF;IACxF,uFAAuF;IACvF,iDAAiD;IACjD,IAAI,MAAM,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IACxF,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrF,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACxD,IAAI,MAAM,CAAC,CAAC,GAAG,GAAG,GAAG,OAAO,IAAI,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,cAAc;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAC1G,IAAI,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,aAAa,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAC/F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAyC,EAAE,KAAa,EAAE,OAAe;IAC5G,MAAM,KAAK,GAAG,UAAU,OAAO,sEAAsE,CAAC;IACtG,QAAQ,KAAK,CAAC,OAAO,EAAE,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,KAAK,KAAK,qFAAqF;gBACpG,2EAA2E,KAAK,EAAE,CAAC;QACvF,KAAK,WAAW;YACd,OAAO,mDAAmD,KAAK,EAAE,CAAC;QACpE,KAAK,YAAY;YACf,OAAO,6CAA6C,KAAK,CAAC,SAAS,IAAI,mBAAmB,WAAW,KAAK,OAAO,KAAK,EAAE,CAAC;QAC3H,KAAK,UAAU;YACb,OAAO,iGAAiG;gBACtG,8EAA8E,KAAK,EAAE,CAAC;QAC1F,KAAK,SAAS;YACZ,OAAO,wDAAwD,cAAc,GAAG,MAAM,mBAAmB;gBACvG,4CAA4C,KAAK,EAAE,CAAC;QACxD,KAAK,WAAW;YACd,OAAO,iGAAiG;gBACtG,YAAY,KAAK,iEAAiE,KAAK,KAAK,CAAC;IACnG,CAAC;AACH,CAAC"}

package/build/services/gmail/filters.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Gmail filters — routing applied to mail as it arrives. ADR-309, #202.
+ *
+ * A filter is a standing-effect write: it keeps acting after the call, on messages the
+ * call never saw. So the lifecycle is gated. `previewFilter` evaluates a filter against the
+ * mail already there and mints a token for that exact filter; `createFilter` and
+ * `updateFilter` refuse without it. Every action Gmail supports stays available, and the
+ * preview is where a dangerous one (trash, forward) is explained.
+ *
+ * Gmail has no `filters.update`. `updateFilter` creates the replacement first and deletes
+ * the original after, so a failure part-way leaves two filters, never none.
+ *
+ * Parameters are flat, like every other operation on this tool: criteria are `match*`,
+ * actions are `addLabelIds`, `removeLabelIds` and `forwardTo`.
+ */
+import { type HandlerResponse } from '../../server/formatting/markdown.js';
+export interface FilterCriteria {
+    from?: string;
+    to?: string;
+    subject?: string;
+    query?: string;
+    negatedQuery?: string;
+    hasAttachment?: boolean;
+    excludeChats?: boolean;
+    size?: number;
+    sizeComparison?: 'larger' | 'smaller';
+}
+export interface FilterAction {
+    addLabelIds?: string[];
+    removeLabelIds?: string[];
+    forward?: string;
+}
+/** Field names match Gmail's `Filter` resource, so a spec is also the request body. */
+export interface FilterSpec {
+    criteria: FilterCriteria;
+    action: FilterAction;
+}
+/** A filter as Google returns it, before normalizing. */
+type RawFilter = {
+    criteria?: Record<string, unknown>;
+    action?: Record<string, unknown>;
+};
+/**
+ * Reduce any filter, from our params or from Google, to one canonical spec, so two
+ * filters that do the same thing compare equal and a token minted over one matches the
+ * other. Empty strings, false booleans and empty label lists are absent.
+ */
+export declare function normalizeSpec(raw: RawFilter): FilterSpec;
+/** Build and validate the filter a call describes. Throws a sentence naming what is missing. */
+export declare function buildFilterSpec(params: Record<string, unknown>): FilterSpec;
+/** The Gmail search a filter's criteria amount to. Filters and search share one syntax. */
+export declare function criteriaToQuery(c: FilterCriteria): string;
+/** The tool params that describe this filter, for recreating or editing it. */
+export declare function specToParams(spec: FilterSpec): Record<string, string | number | boolean>;
+interface Effect {
+    /** What happens, in a clause: "skips the inbox". */
+    text: string;
+    /** Why it is worth a second look, shown in full previews only. */
+    detail?: string;
+    /** A consequence worth a second look before approving: disposal, or mail leaving the account. */
+    warn?: boolean;
+}
+export declare function describeActions(action: FilterAction, labelNames: Map<string, string>): Effect[];
+/** `filters` — every filter on the account, one line each. */
+export declare function handleListFilters(_params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/** `getFilter` — one filter, in words, with the parameters that recreate or edit it. */
+export declare function handleGetFilter(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/**
+ * `previewFilter` — evaluate a filter without creating it, and mint the token the write
+ * needs. With `filterId`, evaluates replacing that filter and mints an update token.
+ *
+ * Problems that would make the write fail or do nothing (an unknown label, an unverified
+ * forwarding address, an exact duplicate) are errors and withhold the token. Consequences
+ * worth a second look are shown, not refused.
+ */
+export declare function handlePreviewFilter(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/** `createFilter` — create a filter its preview has already shown. */
+export declare function handleCreateFilter(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/**
+ * `updateFilter` — replace a filter with the one its preview showed.
+ *
+ * The token covers the filter being replaced as it was at preview time, so a filter that
+ * changed in the meantime is not replaced on the strength of a preview of something else.
+ */
+export declare function handleUpdateFilter(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/** `deleteFilter` — stop a filter, and return what it was so it can be put back. */
+export declare function handleDeleteFilter(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+export {};