@aaronsb/google-workspace-mcp 4.6.1 → 4.8.0

package/build/server/preview-gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** How long a preview stays good. Match counts and conflicts drift as mail arrives. */
+export declare const PREVIEW_TTL_MS: number;
+export type TokenFailure = 'missing' | 'malformed' | 'wrong-kind' | 'mismatch' | 'expired' | 'same-call';
+export type TokenCheck = {
+    ok: true;
+} | {
+    ok: false;
+    failure: TokenFailure;
+    issuedFor?: string;
+};
+/** JSON with object keys sorted at every depth, so equal payloads serialize equally. */
+export declare function canonicalJson(value: unknown): string;
+/** Mint a token for `kind`, bound to this account, this payload, now, and this call. */
+export declare function mintPreviewToken(kind: string, account: string, payload: unknown, now?: number): string;
+/** Check a token against the write about to happen. */
+export declare function checkPreviewToken(token: unknown, kind: string, account: string, payload: unknown, now?: number): TokenCheck;
+/**
+ * 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`.
+ * @param why What makes the write need a preview, in a clause, e.g. "It changes what
+ *   happens to mail that has not arrived yet". Shown when the token is missing.
+ */
+export declare function describeTokenFailure(check: Extract<TokenCheck, {
+    ok: false;
+}>, write: string, preview: string, why: string): string;

package/build/server/preview-gate.js

@@ -0,0 +1,107 @@
+/**
+ * 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`.
+ * @param why What makes the write need a preview, in a clause, e.g. "It changes what
+ *   happens to mail that has not arrived yet". Shown when the token is missing.
+ */
+export function describeTokenFailure(check, write, preview, why) {
+    const again = `Call \`${preview}\` with these exact parameters and pass the previewToken it returns.`;
+    switch (check.failure) {
+        case 'missing':
+            return `\`${write}\` needs a previewToken. ${why}, 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":"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"}

package/build/server/preview-sets.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sets resolved at preview and held for the write that applies them (ADR-310).
+ *
+ * A query-scoped bulk write resolves its query once, at preview, so the apply changes
+ * exactly what the preview counted. The set is kept here, keyed by the preview token,
+ * and the token covers a digest of it, so a set that went missing or changed cannot be
+ * applied. Memory is bounded three ways: ids per set, a set's age, and sets per process.
+ * A restart drops every set, as it already invalidates every token.
+ */
+/** Most ids one preview may hold. A larger result is narrowed by the caller instead. */
+export declare const MAX_SET_SIZE = 10000;
+/** Most previews held at once; the oldest goes first. */
+export declare const MAX_PENDING_SETS = 20;
+/** A digest of the set, independent of order, for the token to cover. */
+export declare function setDigest(ids: readonly string[]): string;
+/** Hold a set under its preview token. */
+export declare function holdSet(token: string, account: string, ids: readonly string[], now?: number): void;
+/** The set held under this token for this account, if it is still held. Does not remove it. */
+export declare function heldSet(token: string, account: string, now?: number): string[] | undefined;
+/** Remove a set; an applied preview is used once. */
+export declare function releaseSet(token: string): void;
+/** How many sets are held. For tests and diagnostics. */
+export declare function heldSetCount(now?: number): number;
+/** Drop every held set. For tests. */
+export declare function clearHeldSets(): void;

package/build/server/preview-sets.js

@@ -0,0 +1,58 @@
+/**
+ * Sets resolved at preview and held for the write that applies them (ADR-310).
+ *
+ * A query-scoped bulk write resolves its query once, at preview, so the apply changes
+ * exactly what the preview counted. The set is kept here, keyed by the preview token,
+ * and the token covers a digest of it, so a set that went missing or changed cannot be
+ * applied. Memory is bounded three ways: ids per set, a set's age, and sets per process.
+ * A restart drops every set, as it already invalidates every token.
+ */
+import { createHash } from 'node:crypto';
+import { PREVIEW_TTL_MS } from './preview-gate.js';
+/** Most ids one preview may hold. A larger result is narrowed by the caller instead. */
+export const MAX_SET_SIZE = 10_000;
+/** Most previews held at once; the oldest goes first. */
+export const MAX_PENDING_SETS = 20;
+const held = new Map();
+/** A digest of the set, independent of order, for the token to cover. */
+export function setDigest(ids) {
+    return createHash('sha256').update([...ids].sort().join('\n')).digest('base64url');
+}
+function dropExpired(now) {
+    for (const [key, set] of held) {
+        if (now - set.heldAt > PREVIEW_TTL_MS)
+            held.delete(key);
+    }
+}
+/** Hold a set under its preview token. */
+export function holdSet(token, account, ids, now = Date.now()) {
+    if (ids.length > MAX_SET_SIZE)
+        throw new Error(`A previewed set holds at most ${MAX_SET_SIZE} ids, not ${ids.length}.`);
+    dropExpired(now);
+    held.delete(token);
+    while (held.size >= MAX_PENDING_SETS) {
+        // Map iterates in insertion order, so the first key is the oldest preview.
+        held.delete(held.keys().next().value);
+    }
+    held.set(token, { account: account.toLowerCase(), ids: [...ids], heldAt: now });
+}
+/** The set held under this token for this account, if it is still held. Does not remove it. */
+export function heldSet(token, account, now = Date.now()) {
+    dropExpired(now);
+    const set = held.get(token);
+    return set && set.account === account.toLowerCase() ? [...set.ids] : undefined;
+}
+/** Remove a set; an applied preview is used once. */
+export function releaseSet(token) {
+    held.delete(token);
+}
+/** How many sets are held. For tests and diagnostics. */
+export function heldSetCount(now = Date.now()) {
+    dropExpired(now);
+    return held.size;
+}
+/** Drop every held set. For tests. */
+export function clearHeldSets() {
+    held.clear();
+}
+//# sourceMappingURL=preview-sets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview-sets.js","sourceRoot":"","sources":["../../src/server/preview-sets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAQnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;AAExC,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,GAAsB;IAC9C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAC9B,IAAI,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,cAAc;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,OAAe,EAAE,GAAsB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC9F,IAAI,GAAG,CAAC,MAAM,GAAG,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,YAAY,aAAa,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACxH,WAAW,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,IAAI,CAAC,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACrC,2EAA2E;QAC3E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,OAAe,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACtE,WAAW,CAAC,GAAG,CAAC,CAAC;IACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC3C,WAAW,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,81 @@
+/**
+ * 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';
+import { type Effect } from './labels.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>;
+export declare function describeActions(action: FilterAction, names: 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 {};