@ganju/utils 0.0.1

package/src/jsonSchemaToZodShape.ts

@@ -0,0 +1,111 @@
+import * as z from 'zod';
+
+export type JsonSchemaProperty = {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: string[];
+  items?: JsonSchemaProperty;
+};
+
+export type JsonSchema = {
+  type: 'object';
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+};
+
+const propertyToZod = (prop: JsonSchemaProperty): z.ZodTypeAny => {
+  let field: z.ZodTypeAny;
+
+  switch (prop.type) {
+    case 'string': {
+      if (prop.enum) {
+        field = z.enum(prop.enum as [string, ...string[]]);
+      } else {
+        let str = z.string();
+        if (prop.minLength !== undefined) str = str.min(prop.minLength);
+        if (prop.maxLength !== undefined) str = str.max(prop.maxLength);
+        if (prop.pattern !== undefined)
+          str = str.regex(new RegExp(prop.pattern));
+        field = str;
+      }
+      break;
+    }
+    case 'number': {
+      let num = z.number();
+      if (prop.minimum !== undefined) num = num.min(prop.minimum);
+      if (prop.maximum !== undefined) num = num.max(prop.maximum);
+      field = num;
+      break;
+    }
+    case 'boolean':
+      field = z.boolean();
+      break;
+    case 'array':
+      field = z.array(prop.items ? propertyToZod(prop.items) : z.any());
+      break;
+    case 'object':
+      field = z.record(z.string(), z.any());
+      break;
+    default:
+      field = z.any();
+  }
+
+  if (prop.description) {
+    field = field.describe(prop.description);
+  }
+
+  return field;
+};
+
+export const jsonSchemaToZodShape = (
+  schema: JsonSchema
+): Record<string, z.ZodTypeAny> => {
+  const properties = schema.properties ?? {};
+  const required = schema.required ?? [];
+
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [key, prop] of Object.entries(properties)) {
+    const field = propertyToZod(prop);
+    shape[key] = required.includes(key) ? field : field.optional();
+  }
+
+  return shape;
+};
+
+export interface SchemaViolation {
+  // Dotted path to the offending field, empty for the value as a whole.
+  path: string;
+  message: string;
+}
+
+/**
+ * Check a value against a declared JSON schema, returning the violations.
+ *
+ * The same compiler the MCP boot loop registers tools with, pointed at a value
+ * instead of at a tool definition — so what the dashboard's Test panel calls
+ * invalid is exactly what an MCP client would have refused to send. Written here
+ * rather than in apps/api because zod lives here, and a second copy of this
+ * would be a second opinion about what "valid" means.
+ *
+ * Unknown keys are allowed through: a JSON Schema without
+ * `additionalProperties: false` does not forbid them, and refusing an extra
+ * field on a test input that a real client would have passed along would make
+ * the panel lie.
+ */
+export const validateAgainstJsonSchema = (
+  schema: JsonSchema,
+  value: unknown
+): SchemaViolation[] => {
+  const result = z.object(jsonSchemaToZodShape(schema)).safeParse(value ?? {});
+  if (result.success) return [];
+  return result.error.issues.map(issue => ({
+    path: issue.path.join('.'),
+    message: issue.message
+  }));
+};

package/src/l2Normalize.ts

@@ -0,0 +1,19 @@
+// Scale a vector to unit length.
+//
+// Needed because `gemini-embedding-001` only returns a normalised vector at its
+// full 3072 dimensions. Ask for fewer via `outputDimensionality` — as we do, to
+// halve storage — and the values come back UNNORMALISED, because truncating a
+// unit vector leaves it shorter than 1. Cosine distance in pgvector assumes
+// nothing about magnitude, but our stored vectors and query vectors have to be
+// treated identically, and an unnormalised mix silently skews ranking rather
+// than failing. So both the ingest path and the query path normalise here.
+//
+// Returns the input unchanged when the magnitude is zero, which would otherwise
+// divide by zero and produce NaNs that poison the whole index.
+export const l2Normalize = (values: number[]): number[] => {
+  let sum = 0;
+  for (const v of values) sum += v * v;
+  const magnitude = Math.sqrt(sum);
+  if (!magnitude || !Number.isFinite(magnitude)) return values;
+  return values.map(v => v / magnitude);
+};

package/src/languageCookieDomain.ts

@@ -0,0 +1,37 @@
+/**
+ * Cookie `Domain` for the remembered language, derived from the host serving
+ * the request.
+ *
+ * `ganju.ai` and `app.ganju.ai` are two hosts, so a host-only cookie set by one
+ * is invisible to the other — someone who explicitly picks English on the
+ * marketing site would sign in and be handed Spanish again by the country
+ * lookup, which defeats the point of remembering the choice. Scoping the cookie
+ * to `.ganju.ai` makes one click cover both.
+ *
+ * Derived from the host rather than configured, because the two surfaces deploy
+ * separately and a value set in one place would silently rot in the other. The
+ * cost is the assumption below.
+ *
+ * **Assumes a single-label public suffix** — `ganju.ai`, `vocesqueabrazan.com`.
+ * A deploy under a multi-part suffix (`example.co.uk`) would compute `.co.uk`,
+ * which browsers reject, and the cookie would quietly go nowhere. Add that
+ * suffix here if it ever happens.
+ */
+export const languageCookieDomain = (hostname: string): string | undefined => {
+  const labels = hostname.split('.');
+
+  // `localhost`, and anything else with nothing to share with.
+  if (labels.length < 2) return undefined;
+
+  // A bare IP has no domain to scope to.
+  if (/^\d+$/.test(labels[labels.length - 1])) return undefined;
+
+  const apex = labels.slice(-2).join('.');
+
+  // Cloudflare's preview hosts are a public suffix: every Pages project on the
+  // planet shares them, so browsers refuse a cookie scoped there. Falling back
+  // to host-only keeps previews working on their own.
+  if (apex === 'pages.dev' || apex === 'workers.dev') return undefined;
+
+  return `.${apex}`;
+};

package/src/localizeZodIssue.ts

@@ -0,0 +1,124 @@
+import esLocale from 'zod/v4/locales/es.js';
+
+import { constants } from './constants';
+
+/**
+ * Re-render a Zod validation issue in the reader's language.
+ *
+ * Zod already ships a complete Spanish locale, so all ~305 built-in validators
+ * in `schema.ts` are covered without hand-translating anything. The trick is
+ * *where* to apply it. There are ~100 parse call sites across the three
+ * services; threading a per-parse error map through all of them is a hundred
+ * chances to miss one. Instead this runs once, in `handleError`'s ZodError
+ * branch, on the way out.
+ *
+ * That works because a Zod 4 issue keeps its structured fields — `code`,
+ * `origin`, `minimum`, `divisor`, `keys` — alongside the rendered `message`,
+ * and a locale error map is exactly a function from that structured issue to a
+ * string. So the English message Zod produced at parse time can be thrown away
+ * and rebuilt in Spanish at catch time.
+ *
+ * **Do not reach for `z.config({ localeError })` instead.** It mutates a
+ * module-level global (`zod/src/v4/core/config.ts`), and a Workers isolate
+ * serves concurrent requests in different languages — one request would set the
+ * locale for whatever else happened to be in flight. Nothing here holds state.
+ *
+ * What lands in `error_log` is untouched: `handleError` persists `err.message`,
+ * which is still Zod's own English dump from parse time. Nothing about
+ * persistence, and no migration, is involved.
+ */
+
+/** Minimal shape of the issue we need; Zod's own type lives in `zod`. */
+export interface ZodIssueLike {
+  code?: string;
+  message: string;
+  path?: PropertyKey[];
+}
+
+type LocaleError = (issue: never) => string | { message: string };
+
+/**
+ * Messages we wrote ourselves. Zod renders a custom `message:` verbatim, so the
+ * locale map never sees them — they arrive here as the exact English string,
+ * which is what these keys are. Keying on our own text rather than on a code
+ * keeps `schema.ts` free of translation concerns, and keeps the English in
+ * `error_log` identical to what it has always been.
+ */
+const CUSTOM_MESSAGES: Record<string, Record<string, string>> = {
+  'This title is reserved as a bot command': {
+    es: 'Este título está reservado como comando del bot'
+  },
+  'Enter a valid email address': {
+    es: 'Escribe un correo electrónico válido'
+  },
+  'Unsupported mime type': {
+    es: 'Tipo de archivo no admitido'
+  },
+  'Slug is reserved': {
+    es: 'Ese slug está reservado'
+  },
+  [constants.RESERVED_TOOL_NAME_MESSAGE]: {
+    es: 'Nombre de herramienta no válido — reservado por la plataforma'
+  },
+  [constants.CUSTOM_CODE_UNKNOWN_CONNECTION_MESSAGE]: {
+    es: 'Conexión no válida — no existe un proveedor gestionado con ese nombre'
+  },
+  [constants.OUTPUT_SCHEMA_NOT_OBJECT_MESSAGE]: {
+    es: 'Esquema de salida no válido — debe describir un objeto'
+  },
+  [constants.CUSTOM_CODE_RESOURCE_PAYLOAD_MESSAGE]: {
+    es: 'Envía exactamente uno de content (texto) o bytes (base64)'
+  },
+  [constants.CUSTOM_CODE_RESOURCE_TEXT_TOO_LARGE_MESSAGE]: {
+    es: `El contenido en línea supera el límite de ${constants.CUSTOM_CODE_MAX_RESOURCE_TEXT_BYTES / (1024 * 1024)}MB`
+  },
+  [constants.CUSTOM_CODE_RESOURCE_FILE_TOO_LARGE_MESSAGE]: {
+    es: `Los bytes del archivo superan el límite de ${constants.CUSTOM_CODE_MAX_RESOURCE_FILE_BYTES / (1024 * 1024)}MB`
+  }
+};
+
+// Built once. `esLocale()` allocates its dictionaries on every call, and this
+// runs per issue, per failed request.
+const LOCALE_ERRORS: Record<string, LocaleError> = {
+  [constants.LANGUAGE_ES]: esLocale().localeError as LocaleError
+};
+
+/**
+ * Narrow an `Accept-Language` header to a language we ship.
+ *
+ * `fetcher` sends the app's own locale rather than the browser's list, so this
+ * is normally a bare `en` or `es` — but the header is public, and a browser
+ * hitting the API directly will send the full `es-CO,es;q=0.9,en;q=0.8` form.
+ * Take the first tag and match on its primary subtag.
+ */
+export const languageFromHeader = (header?: string | null): string => {
+  const tag = header?.split(',')[0]?.trim().toLowerCase() ?? '';
+  return tag.startsWith(constants.LANGUAGE_ES)
+    ? constants.LANGUAGE_ES
+    : constants.LANGUAGE_EN;
+};
+
+/** The issue's message in `language`, or its original English. */
+export const localizeZodIssue = (
+  issue: ZodIssueLike,
+  language: string
+): string => {
+  if (language === constants.LANGUAGE_EN) return issue.message;
+
+  const custom = CUSTOM_MESSAGES[issue.message]?.[language];
+  if (custom) return custom;
+
+  const localeError = LOCALE_ERRORS[language];
+  if (!localeError) return issue.message;
+
+  try {
+    const rendered = localeError(issue as never);
+    const message = typeof rendered === 'string' ? rendered : rendered?.message;
+    // A locale map may decline an issue it does not recognise; English is a
+    // better answer than an empty string.
+    return message || issue.message;
+  } catch {
+    // Never let a formatting failure turn a 400 into a 500.
+    return issue.message;
+  }
+};

package/src/mailHeaders.ts

@@ -0,0 +1,12 @@
+import { utf8ToBase64 } from './base64';
+
+const ASCII_ONLY = /^[\x00-\x7F]*$/;
+
+export const sanitizeMailHeader = (value: string): string =>
+  value.replace(/[\r\n]+/g, ' ').trim();
+
+export const encodeRfc2047 = (value: string): string =>
+  ASCII_ONLY.test(value) ? value : `=?UTF-8?B?${utf8ToBase64(value)}?=`;
+
+export const formatMailHeader = (value: string): string =>
+  encodeRfc2047(sanitizeMailHeader(value));

package/src/mcpProxy.ts

@@ -0,0 +1,20 @@
+import { constants } from './constants';
+
+// Remote MCP tool keys are untrusted (the remote chooses them). Only allow the
+// charset MCP clients accept for tool names so the composed local name can't
+// break registration or downstream API calls.
+const REMOTE_TOOL_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+// Compose the local MCP tool name for a proxied remote tool (`<prefix><sep><key>`),
+// or return null when the remote key can't be safely surfaced — bad charset, or
+// the composed name exceeds the tool-name length limit clients enforce. Callers
+// skip-and-log nulls rather than registering an unusable tool.
+export const buildProxyToolName = (
+  prefix: string,
+  remoteName: string
+): string | null => {
+  if (!remoteName || !REMOTE_TOOL_NAME_RE.test(remoteName)) return null;
+  const name = `${prefix}${constants.MCP_PROXY_TOOL_NAME_SEP}${remoteName}`;
+  if (name.length > constants.MCP_PROXY_TOOL_NAME_MAX) return null;
+  return name;
+};

package/src/mimeMessage.ts

@@ -0,0 +1,82 @@
+import { sanitizeMailHeader, formatMailHeader } from './mailHeaders';
+
+export interface MimeAttachment {
+  filename: string;
+  mimeType: string;
+  base64: string;
+}
+
+export interface MimeMessageInput {
+  to: string;
+  subject: string;
+  body: string;
+  cc?: string;
+  bcc?: string;
+  inReplyTo?: string;
+  references?: string;
+  contentType?: 'text/html' | 'text/plain';
+  attachments?: MimeAttachment[];
+}
+
+export const sanitizeFilename = (name: string): string => {
+  const cleaned = name.replace(/[\r\n"]/g, '').trim();
+  return cleaned || 'attachment';
+};
+
+export const formatFilenameHeader = (name: string): string => {
+  const safe = sanitizeFilename(name);
+  if (/^[\x20-\x7E]+$/.test(safe)) {
+    return `filename="${safe.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  return `filename*=UTF-8''${encodeURIComponent(safe)}`;
+};
+
+export const chunkBase64 = (b64: string): string =>
+  b64.replace(/(.{76})/g, '$1\r\n');
+
+export const buildMimeMessage = (input: MimeMessageInput): string => {
+  const headers: string[] = [];
+  headers.push(`To: ${formatMailHeader(input.to)}`);
+  if (input.cc) headers.push(`Cc: ${formatMailHeader(input.cc)}`);
+  if (input.bcc) headers.push(`Bcc: ${formatMailHeader(input.bcc)}`);
+  headers.push(`Subject: ${formatMailHeader(input.subject)}`);
+  if (input.inReplyTo)
+    headers.push(`In-Reply-To: ${sanitizeMailHeader(input.inReplyTo)}`);
+  if (input.references)
+    headers.push(`References: ${sanitizeMailHeader(input.references)}`);
+  headers.push('MIME-Version: 1.0');
+
+  const bodyContentType = input.contentType || 'text/html';
+
+  if (!input.attachments || input.attachments.length === 0) {
+    headers.push(`Content-Type: ${bodyContentType}; charset=utf-8`);
+    return `${headers.join('\r\n')}\r\n\r\n${input.body}`;
+  }
+
+  const boundary = `_ganju_${crypto.randomUUID().replace(/-/g, '')}`;
+  headers.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+
+  const parts: string[] = [headers.join('\r\n'), ''];
+  parts.push(`--${boundary}`);
+  parts.push(`Content-Type: ${bodyContentType}; charset=utf-8`);
+  parts.push('Content-Transfer-Encoding: 7bit');
+  parts.push('');
+  parts.push(input.body);
+
+  for (const att of input.attachments) {
+    const safeName = sanitizeFilename(att.filename);
+    parts.push(`--${boundary}`);
+    parts.push(
+      `Content-Type: ${att.mimeType}; name="${safeName.replace(/"/g, '\\"')}"`
+    );
+    parts.push('Content-Transfer-Encoding: base64');
+    parts.push(
+      `Content-Disposition: attachment; ${formatFilenameHeader(att.filename)}`
+    );
+    parts.push('');
+    parts.push(chunkBase64(att.base64));
+  }
+
+  parts.push(`--${boundary}--`);
+  return parts.join('\r\n');
+};

package/src/oauth.ts

@@ -0,0 +1,103 @@
+import { constants } from './constants';
+
+export interface RefreshOAuthTokenInput {
+  tokenUrl: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+
+export interface RefreshedOAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+}
+
+export class OAuthReauthRequiredError extends Error {
+  readonly code: string;
+
+  constructor(code: string) {
+    super(`OAuth reauth required (${code})`);
+    this.name = 'OAuthReauthRequiredError';
+    this.code = code;
+  }
+}
+
+const parseErrorCode = (body: string): string | undefined => {
+  try {
+    return (JSON.parse(body) as { error?: string })?.error;
+  } catch {
+    return undefined;
+  }
+};
+
+export const refreshOAuthToken = async (
+  input: RefreshOAuthTokenInput
+): Promise<RefreshedOAuthToken> => {
+  const response = await fetch(input.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: input.clientId,
+      client_secret: input.clientSecret,
+      grant_type: 'refresh_token',
+      refresh_token: input.refreshToken
+    })
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    const code = parseErrorCode(body);
+    if (code && constants.REAUTH_ERROR_CODES.includes(code)) {
+      throw new OAuthReauthRequiredError(code);
+    }
+    throw new Error(`oauth refresh failed (${response.status}): ${body}`);
+  }
+
+  const tokens = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+  };
+
+  if (!tokens.access_token) {
+    throw new Error('oauth refresh missing access_token');
+  }
+
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresIn: tokens.expires_in,
+    scope: tokens.scope
+  };
+};
+
+export const buildReauthMetadata = (
+  previous: Record<string, unknown> | null,
+  reason: string
+): Record<string, unknown> => ({
+  ...(previous || {}),
+  needsReauth: true,
+  reauthReason: reason,
+  reauthAt: new Date().toISOString()
+});
+
+export const clearReauthMetadata = (
+  previous: Record<string, unknown> | null
+): Record<string, unknown> | null => {
+  if (!previous) return null;
+  const next: Record<string, unknown> = { ...previous };
+  delete next.needsReauth;
+  delete next.reauthReason;
+  delete next.reauthAt;
+  return Object.keys(next).length > 0 ? next : null;
+};
+
+export const isCredentialNeedingReauth = (
+  metadata: unknown
+): boolean => {
+  if (!metadata || typeof metadata !== 'object') return false;
+  return (metadata as Record<string, unknown>).needsReauth === true;
+};

package/src/oauthProviders.ts

@@ -0,0 +1,118 @@
+import { constants } from './constants';
+
+export interface OAuthProviderConfig {
+  authUrl: string;
+  tokenUrl: string;
+  clientIdEnv: string;
+  clientSecretEnv: string;
+  defaultScopes: string[];
+  // Slack distinguishes the bot scope bucket (`scope=`) from the user scope
+  // bucket (`user_scope=`). Default is 'scope'; the slack-user provider sets
+  // this to 'user_scope' so its scopes are requested in the user bucket.
+  scopeParam?: 'scope' | 'user_scope';
+  // For providers (Slack user flow) whose token-exchange response carries
+  // the credential under `authed_user` instead of at top level. Default is
+  // 'top'.
+  tokenSource?: 'top' | 'authed_user';
+  // Slack's oauth.v2.access endpoint returns `internal_error` when the
+  // standard OAuth2 `grant_type=authorization_code` body param is included
+  // on the code-exchange call. Set true to omit it. Refresh-token requests
+  // still send `grant_type=refresh_token` (Slack does document that one).
+  omitGrantType?: boolean;
+}
+
+// The managed OAuth apps we run. This lives in @ganju/utils rather than in
+// apps/api because three workers now need it: apps/api (the authorization flow),
+// and apps/tool-broker, which mints short-lived access tokens for user code and
+// must refresh with the same client credentials against the same token URLs.
+// Adding a provider in one place and not the other is exactly the drift this
+// prevents.
+export const oauthProviders: Record<string, OAuthProviderConfig> = {
+  [constants.OAUTH_PROVIDER_GOOGLE_GMAIL]: {
+    authUrl: constants.GOOGLE_OAUTH_AUTH_URL,
+    tokenUrl: constants.GOOGLE_OAUTH_TOKEN_URL,
+    clientIdEnv: 'GOOGLE_CLIENT_ID',
+    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+    defaultScopes: [
+      'https://www.googleapis.com/auth/gmail.readonly',
+      'https://www.googleapis.com/auth/gmail.send',
+      'https://www.googleapis.com/auth/gmail.modify',
+      'https://www.googleapis.com/auth/gmail.compose',
+      'https://www.googleapis.com/auth/gmail.labels'
+    ]
+  },
+  [constants.OAUTH_PROVIDER_GOOGLE_DRIVE]: {
+    authUrl: constants.GOOGLE_OAUTH_AUTH_URL,
+    tokenUrl: constants.GOOGLE_OAUTH_TOKEN_URL,
+    clientIdEnv: 'GOOGLE_CLIENT_ID',
+    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+    defaultScopes: [
+      'https://www.googleapis.com/auth/drive.readonly',
+      'https://www.googleapis.com/auth/drive.metadata.readonly'
+    ]
+  },
+  [constants.OAUTH_PROVIDER_GOOGLE_CALENDAR]: {
+    authUrl: constants.GOOGLE_OAUTH_AUTH_URL,
+    tokenUrl: constants.GOOGLE_OAUTH_TOKEN_URL,
+    clientIdEnv: 'GOOGLE_CLIENT_ID',
+    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+    defaultScopes: [
+      'https://www.googleapis.com/auth/calendar.events',
+      'https://www.googleapis.com/auth/calendar.readonly'
+    ]
+  },
+  [constants.OAUTH_PROVIDER_MICROSOFT_OUTLOOK]: {
+    authUrl: constants.MICROSOFT_OAUTH_AUTH_URL,
+    tokenUrl: constants.MICROSOFT_OAUTH_TOKEN_URL,
+    clientIdEnv: 'MICROSOFT_CLIENT_ID',
+    clientSecretEnv: 'MICROSOFT_CLIENT_SECRET',
+    defaultScopes: [
+      'https://graph.microsoft.com/Mail.ReadWrite',
+      'https://graph.microsoft.com/Mail.Send',
+      'https://graph.microsoft.com/User.Read',
+      'offline_access'
+    ]
+  },
+  [constants.OAUTH_PROVIDER_ONE_DRIVE]: {
+    authUrl: constants.MICROSOFT_OAUTH_AUTH_URL,
+    tokenUrl: constants.MICROSOFT_OAUTH_TOKEN_URL,
+    clientIdEnv: 'MICROSOFT_CLIENT_ID',
+    clientSecretEnv: 'MICROSOFT_CLIENT_SECRET',
+    defaultScopes: [
+      'https://graph.microsoft.com/Files.Read',
+      'https://graph.microsoft.com/Files.Read.All',
+      'offline_access'
+    ]
+  },
+  [constants.OAUTH_PROVIDER_SLACK]: {
+    authUrl: constants.SLACK_OAUTH_AUTH_URL,
+    tokenUrl: constants.SLACK_OAUTH_TOKEN_URL,
+    clientIdEnv: 'SLACK_CLIENT_ID',
+    clientSecretEnv: 'SLACK_CLIENT_SECRET',
+    defaultScopes: [
+      'chat:write',
+      'channels:read',
+      'groups:read',
+      'mpim:read',
+      'im:read',
+      'users:read',
+      'users:read.email',
+      'files:write'
+    ],
+    omitGrantType: true
+  },
+  [constants.OAUTH_PROVIDER_SLACK_USER]: {
+    authUrl: constants.SLACK_OAUTH_AUTH_URL,
+    tokenUrl: constants.SLACK_OAUTH_TOKEN_URL,
+    clientIdEnv: 'SLACK_CLIENT_ID',
+    clientSecretEnv: 'SLACK_CLIENT_SECRET',
+    // search.messages is the only Slack endpoint that needs a user (xoxp)
+    // token. Kept as its own provider so the OAuth flow stays generic —
+    // scopes are requested in the user_scope bucket, and the access_token
+    // is read from authed_user on callback.
+    defaultScopes: ['search:read'],
+    scopeParam: 'user_scope',
+    tokenSource: 'authed_user',
+    omitGrantType: true
+  }
+};

package/src/outlookSend.ts

@@ -0,0 +1,44 @@
+// Wire protocol shared between the MCP worker (which builds the request) and
+// the resource-handler container (which talks to Microsoft Graph).
+//
+// The worker sends a multipart/form-data POST with one `metadata` field (JSON
+// matching OutlookSendRequest) and zero-or-more `attachment` fields. The
+// container decides per-attachment whether to inline it in the Graph message
+// JSON (≤3MB) or upload it via createUploadSession with chunked PUTs.
+
+export type OutlookOperation =
+  | 'send-email'
+  | 'reply-email'
+  | 'forward-email'
+  | 'create-draft'
+  | 'update-draft';
+
+export interface OutlookSendRequest {
+  accessToken: string;
+  operation: OutlookOperation;
+  body: string;
+  // Graph terms: 'html' or 'text'. Defaults to 'html' on the container side.
+  contentType?: 'html' | 'text';
+
+  // send-email / forward-email / create-draft / update-draft
+  to?: string;
+  subject?: string;
+  cc?: string;
+  bcc?: string;
+
+  // reply-email / forward-email need the source message
+  messageId?: string;
+  // reply-email
+  replyAll?: boolean;
+
+  // update-draft target
+  draftId?: string;
+}
+
+export interface OutlookSendResponse {
+  // Resulting message ID for send / reply / forward. Draft ID for
+  // create-draft / update-draft. Empty string when Graph returns 202 with
+  // no body (sendMail without saveToSentItems).
+  id: string;
+  conversationId?: string;
+}