chati-dev 4.5.28 → 4.5.29

package/src/installer-v2/clickup-connection-storage.js

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto';
+import { lstatSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { installationAuthorityStateDirectory } from './installation-authority.js';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from './catalog-client.js';
+import { assertClickUpOAuthRedirect, CLICKUP_MCP_RESOURCE } from './clickup-oauth.js';
+
+const MAX_BYTES = 64 * 1024;
+const ID = /^clickup-[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+function fail(code) { throw Object.assign(new Error('ClickUp private connection storage rejected the operation'), { code }); }
+function hasControlOrSpace(value) {
+  return [...value].some((character) => character.codePointAt(0) <= 32 || character.codePointAt(0) === 127);
+}
+function exact(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.getOwnPropertySymbols(value).length === 0
+    && Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => Object.hasOwn(descriptor, 'value'))
+    && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+function validate(value) {
+  if (!exact(value, ['schema_version', 'connection_id', 'client', 'credentials', 'destination', 'created_at'])
+    || value.schema_version !== 1 || !ID.test(value.connection_id || '') || !Number.isFinite(Date.parse(value.created_at))) fail('CLICKUP_CONNECTION_INVALID');
+  const { client, credentials, destination } = value;
+  if (!exact(client, ['client_id', 'redirect_uri', 'issuer', 'resource'])
+    || typeof client.client_id !== 'string' || !client.client_id || client.client_id.length > 1024 || hasControlOrSpace(client.client_id)
+    || client.issuer !== 'https://mcp.clickup.com' || client.resource !== CLICKUP_MCP_RESOURCE) fail('CLICKUP_CONNECTION_INVALID');
+  assertClickUpOAuthRedirect(client.redirect_uri);
+  if (!exact(destination, ['workspace_id', 'list_id'])
+    || !['workspace_id', 'list_id'].every((key) => typeof destination[key] === 'string' && /^[0-9]{1,32}$/.test(destination[key]))) fail('CLICKUP_CONNECTION_INVALID');
+  const fields = ['token_type', 'access_token', 'scope', 'expires_at'];
+  if (Object.hasOwn(credentials || {}, 'refresh_token')) fields.push('refresh_token');
+  if (!exact(credentials, fields) || credentials.token_type !== 'Bearer' || credentials.scope !== 'read write'
+    || typeof credentials.access_token !== 'string' || credentials.access_token.length > 16384 || !/^[A-Za-z0-9._~+/-]+=*$/.test(credentials.access_token)
+    || !Number.isFinite(Date.parse(credentials.expires_at))
+    || (credentials.refresh_token !== undefined && (typeof credentials.refresh_token !== 'string' || !credentials.refresh_token
+      || credentials.refresh_token.length > 16384 || hasControlOrSpace(credentials.refresh_token)))) fail('CLICKUP_CONNECTION_INVALID');
+}
+
+function directory(authorityDirectory) {
+  // Same OS-account-derived private root already masked from Chati children.
+  // No project path, caller HOME, provider token store, or Keychain is used.
+  const root = installationAuthorityStateDirectory(authorityDirectory);
+  const target = join(root, 'clickup-connections');
+  for (const path of [dirname(root), root, target]) {
+    let stat;
+    try { stat = lstatSync(path); } catch (error) { if (error?.code === 'ENOENT') continue; fail('CLICKUP_CONNECTION_STORAGE_UNSAFE'); }
+    const forbidden = path === dirname(root) ? 0o022 : 0o077;
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & forbidden) !== 0
+      || (typeof process.geteuid === 'function' && stat.uid !== process.geteuid())) fail('CLICKUP_CONNECTION_STORAGE_UNSAFE');
+  }
+  return target;
+}
+
+/** Stores only an explicitly obtained connection. No refresh, global provider
+ * reconfiguration, external request, receipt signing or destination expansion.
+ * The returned summary is safe to display; the persisted file contains secrets.
+ */
+export function saveClickUpConnection({ client, credentials, destination, authorityDirectory, clock = Date.now } = {}) {
+  const now = clock();
+  if (!Number.isSafeInteger(now) || now < 0 || now > 8640000000000000) fail('CLICKUP_CONNECTION_INVALID');
+  const connection = { schema_version: 1, connection_id: `clickup-${randomUUID()}`, client, credentials, destination, created_at: new Date(now).toISOString() };
+  validate(connection);
+  if (Date.parse(credentials.expires_at) <= now) fail('CLICKUP_CONNECTION_EXPIRED');
+  const path = join(directory(authorityDirectory), `${connection.connection_id}.json`);
+  try {
+    persistImmutableInstallationFile(path, `${JSON.stringify(connection)}\n`, { maxBytes: MAX_BYTES, label: 'ClickUp private connection' });
+    // Check the actual writer's file and folder modes, not only requested modes.
+    loadClickUpConnection({ connectionId: connection.connection_id, authorityDirectory, clock });
+  } catch { fail('CLICKUP_CONNECTION_STORAGE_UNSAFE'); }
+  return Object.freeze({ connection_id: connection.connection_id, destination: Object.freeze({ ...destination }),
+    expires_at: credentials.expires_at, credential_storage: 'host_private_authority', refreshed: false });
+}
+
+/** Internal credential reader. Never serialize the result to a CLI transcript.
+ * A stored destination is a required bridge input, not upstream list-scoped OAuth.
+ */
+export function loadClickUpConnection({ connectionId, authorityDirectory, clock = Date.now } = {}) {
+  if (typeof connectionId !== 'string' || !ID.test(connectionId)) fail('CLICKUP_CONNECTION_INVALID');
+  let source;
+  try {
+    source = readSafeInstallationStorageFile(join(directory(authorityDirectory), `${connectionId}.json`),
+      { maxBytes: MAX_BYTES, label: 'ClickUp private connection' });
+  } catch { fail('CLICKUP_CONNECTION_STORAGE_UNSAFE'); }
+  if ((source.stat.mode & 0o077n) !== 0n || (typeof process.geteuid === 'function' && source.stat.uid !== BigInt(process.geteuid()))) fail('CLICKUP_CONNECTION_STORAGE_UNSAFE');
+  let value;
+  try { value = JSON.parse(source.content); } catch { fail('CLICKUP_CONNECTION_INVALID'); }
+  validate(value);
+  if (value.connection_id !== connectionId) fail('CLICKUP_CONNECTION_INVALID');
+  const now = clock();
+  if (!Number.isSafeInteger(now) || now < 0 || Date.parse(value.credentials.expires_at) <= now) fail('CLICKUP_CONNECTION_EXPIRED');
+  return Object.freeze({ ...value, client: Object.freeze(value.client), credentials: Object.freeze(value.credentials), destination: Object.freeze(value.destination) });
+}

package/src/installer-v2/clickup-mcp-client.js

@@ -0,0 +1,155 @@
+import { loadClickUpConnection } from './clickup-connection-storage.js';
+import { CLICKUP_MCP_RESOURCE } from './clickup-oauth.js';
+
+const PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const MAX_BYTES = 1024 * 1024;
+const TOOLS = new Set(['clickup_get_list', 'clickup_get_task', 'clickup_create_task', 'clickup_update_task', 'clickup_filter_tasks']);
+const diagnostics = new WeakMap();
+export function clickUpMcpFailureDiagnostic(error) {
+  return diagnostics.get(error) || Object.freeze({ code: 'CLICKUP_MCP_FAILURE_UNKNOWN' });
+}
+function fail(code, httpStatus) {
+  const error = Object.assign(new Error('ClickUp MCP operation failed; no automatic retry was made'), { code });
+  diagnostics.set(error, Object.freeze({ code, ...(Number.isInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599
+    ? { http_status: httpStatus } : {}) }));
+  throw error;
+}
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+
+/** Private, finite transport for the user's own explicit OAuth connection.
+ * This is not a certified observer or a delivery command. Its caller must bind
+ * task ownership, canonical payload and outbox admission BEFORE any mutation.
+ * No token getter, alternate endpoint, arbitrary tool or automatic retry.
+ */
+export async function openClickUpMcpClient({ connectionId, authorityDirectory, clock = Date.now, fetchImpl = globalThis.fetch } = {}) {
+  const connection = loadClickUpConnection({ connectionId, authorityDirectory, clock });
+  const destination = connection.destination;
+  let session;
+  let protocol;
+  let nextId = 0;
+  let closed = false;
+  const headers = () => ({ Authorization: `Bearer ${connection.credentials.access_token}`,
+    ...(session ? { 'MCP-Session-Id': session } : {}), ...(protocol ? { 'MCP-Protocol-Version': protocol } : {}) });
+
+  async function rpc(method, params, notification = false) {
+    const now = clock();
+    if (closed || !Number.isSafeInteger(now) || now < 0 || now >= Date.parse(connection.credentials.expires_at)) fail('CLICKUP_MCP_CONNECTION_UNAVAILABLE');
+    const id = notification ? undefined : ++nextId;
+    const body = JSON.stringify({ jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }), ...(notification ? {} : { id }) });
+    if (Buffer.byteLength(body) > MAX_BYTES) fail('CLICKUP_MCP_REQUEST_TOO_LARGE');
+    let response;
+    let reader;
+    try {
+      response = await fetchImpl(CLICKUP_MCP_RESOURCE, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15000),
+        headers: { ...headers(), 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' }, body });
+      if (!response.ok) fail('CLICKUP_MCP_HTTP_REJECTED', response.status);
+      if (method === 'initialize') {
+        const value = response.headers.get('mcp-session-id');
+        if (value && (value.length > 4096 || !/^[\x21-\x7e]+$/.test(value))) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        session = value;
+      }
+      if (notification) {
+        if (response.status !== 202) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        return undefined;
+      }
+      const type = (response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+      if (!['application/json', 'text/event-stream'].includes(type)
+        || Number(response.headers.get('content-length')) > MAX_BYTES) fail('CLICKUP_MCP_RESPONSE_INVALID');
+      reader = response.body?.getReader();
+      if (!reader) fail('CLICKUP_MCP_RESPONSE_INVALID');
+      const decoder = new TextDecoder('utf-8', { fatal: true });
+      let buffer = ''; let bytes = 0;
+      const result = (message) => {
+        if (!object(message) || message.jsonrpc !== '2.0' || message.id !== id
+          || Object.hasOwn(message, 'error') || !Object.hasOwn(message, 'result')) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        return message.result;
+      };
+      for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        bytes += chunk.value.byteLength;
+        if (bytes > MAX_BYTES) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        buffer += decoder.decode(chunk.value, { stream: true });
+        if (type === 'text/event-stream') {
+          // Keep a trailing CR until the next chunk; CRLF may span reads.
+          buffer = buffer.replace(/\r\n/g, '\n');
+          let end;
+          while ((end = buffer.indexOf('\n\n')) !== -1) {
+            const event = buffer.slice(0, end); buffer = buffer.slice(end + 2);
+            const data = event.split('\n').filter(line => line.startsWith('data:'))
+              .map(line => line.slice(5).replace(/^ /, '')).join('\n');
+            if (!data) continue;
+            const message = JSON.parse(data);
+            if (message?.id === id) return result(message);
+            // Notifications are harmless; never execute a server request.
+            if (!object(message) || message.jsonrpc !== '2.0' || Object.hasOwn(message, 'id')) fail('CLICKUP_MCP_RESPONSE_INVALID');
+          }
+        }
+      }
+      buffer += decoder.decode();
+      if (type === 'text/event-stream') fail('CLICKUP_MCP_RESPONSE_INVALID');
+      return result(JSON.parse(buffer));
+    } catch (error) {
+      if (diagnostics.has(error)) throw error;
+      return fail('CLICKUP_MCP_REQUEST_FAILED');
+    } finally {
+      try { if (reader) await reader.cancel(); else await response?.body?.cancel(); } catch { /* never expose remote failures */ }
+    }
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    if (!session) return;
+    try {
+      const response = await fetchImpl(CLICKUP_MCP_RESOURCE, { method: 'DELETE', redirect: 'error',
+        signal: AbortSignal.timeout(5000), headers: headers() });
+      await response.body?.cancel();
+    } catch { /* local handle is closed even if the finite remote session expires later */ }
+  }
+
+  try {
+    const initialized = await rpc('initialize', { protocolVersion: PROTOCOLS[0], capabilities: {}, clientInfo: { name: 'chati-dev', version: '4.5.28' } });
+    if (!object(initialized) || !PROTOCOLS.includes(initialized.protocolVersion) || !object(initialized.capabilities?.tools)) fail('CLICKUP_MCP_NEGOTIATION_FAILED');
+    protocol = initialized.protocolVersion;
+    await rpc('notifications/initialized', undefined, true);
+  } catch (error) { await close(); throw error; }
+
+  return Object.freeze({
+    destination, protocol,
+    async listTools() {
+      const tools = []; const cursors = new Set();
+      let cursor;
+      do {
+        const page = await rpc('tools/list', cursor === undefined ? {} : { cursor });
+        if (!object(page) || !Array.isArray(page.tools) || page.tools.length > 300) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        tools.push(...page.tools);
+        if (tools.length > 300 || tools.some(tool => !object(tool) || typeof tool.name !== 'string' || !object(tool.inputSchema))
+          || new Set(tools.map(tool => tool.name)).size !== tools.length) fail('CLICKUP_MCP_RESPONSE_INVALID');
+        cursor = page.nextCursor;
+        if (cursor !== undefined) {
+          if (typeof cursor !== 'string' || !cursor || cursor.length > 4096 || cursors.has(cursor) || cursors.size >= 4) fail('CLICKUP_MCP_RESPONSE_INVALID');
+          cursors.add(cursor);
+        }
+      } while (cursor !== undefined);
+      return tools;
+    },
+    async callTool(name, args) {
+      if (!TOOLS.has(name) || !object(args)) fail('CLICKUP_MCP_TOOL_NOT_ALLOWED');
+      // Copy before awaits and override no scope silently. Foreign fields remain
+      // subject to the discovered schema at the certified business-layer caller.
+      let input;
+      try { input = JSON.parse(JSON.stringify(args)); } catch { fail('CLICKUP_MCP_TOOL_NOT_ALLOWED'); }
+      if (!object(input)) fail('CLICKUP_MCP_TOOL_NOT_ALLOWED');
+      if (input.workspace_id !== undefined && input.workspace_id !== destination.workspace_id) fail('CLICKUP_MCP_DESTINATION_MISMATCH');
+      if (['clickup_get_list', 'clickup_create_task'].includes(name) && input.list_id !== destination.list_id) fail('CLICKUP_MCP_DESTINATION_MISMATCH');
+      if (input.list_name !== undefined) fail('CLICKUP_MCP_DESTINATION_MISMATCH');
+      if (name === 'clickup_filter_tasks' && (JSON.stringify(input.list_ids) !== JSON.stringify([destination.list_id])
+        || input.folder_ids !== undefined || input.space_ids !== undefined)) fail('CLICKUP_MCP_DESTINATION_MISMATCH');
+      if (['clickup_get_task', 'clickup_update_task'].includes(name) && (typeof input.task_id !== 'string'
+        || !/^[A-Za-z0-9_-]{1,128}$/.test(input.task_id))) fail('CLICKUP_MCP_TOOL_NOT_ALLOWED');
+      return rpc('tools/call', { name, arguments: { ...input, workspace_id: destination.workspace_id } });
+    },
+    close,
+  });
+}

package/src/installer-v2/clickup-oauth-loopback.js

@@ -0,0 +1,96 @@
+import { createServer } from 'node:http';
+import { CLICKUP_OAUTH_REQUEST_TIMEOUT_MS, inheritClickUpOAuthFailureDiagnostic } from './clickup-oauth.js';
+
+const MAX_URL_LENGTH = 16 * 1024;
+const INVALID_CALLBACK_CODES = new Set(['CLICKUP_OAUTH_CALLBACK_INVALID']);
+
+function failure(code, message) { return Object.assign(new Error(message), { code }); }
+
+/** Finite local callback, not a public service. It accepts one authorization.
+ * The browser gets only fixed text, never the query, code, tokens or raw errors.
+ * On a remote host, any loopback forwarding must be authorized separately.
+ */
+export async function listenForClickUpOAuth({ port = 0, timeoutMs = 10 * 60_000 } = {}) {
+  if (!Number.isInteger(port) || (port !== 0 && (port < 1024 || port > 65535))
+    || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 10 * 60_000) {
+    throw failure('CLICKUP_OAUTH_LISTENER_INVALID', 'ClickUp callback requires a finite loopback listener');
+  }
+  let authorization;
+  let settled = false;
+  let resolveResult;
+  let rejectResult;
+  let timer;
+  const result = new Promise((resolve, reject) => { resolveResult = resolve; rejectResult = reject; });
+  // A user can decline before the caller starts awaiting the promise.
+  result.catch(() => {});
+  const server = createServer({ maxHeaderSize: MAX_URL_LENGTH, requestTimeout: 5000, headersTimeout: 5000 });
+  server.maxConnections = 16;
+  server.maxRequestsPerSocket = 1;
+  server.setTimeout(5000, (socket) => socket.destroy());
+  const finish = (error, credentials) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    timer = undefined;
+    server.close();
+    if (error) rejectResult(error);
+    else resolveResult(credentials);
+  };
+  server.on('error', () => finish(failure('CLICKUP_OAUTH_LISTENER_FAILED', 'ClickUp callback listener failed')));
+  await new Promise((resolve, reject) => {
+    const onError = () => reject(failure('CLICKUP_OAUTH_LISTENER_UNAVAILABLE', 'ClickUp loopback callback port is unavailable'));
+    server.once('error', onError);
+    server.listen({ host: '127.0.0.1', port, exclusive: true }, () => { server.off('error', onError); resolve(); });
+  });
+  const authority = `127.0.0.1:${server.address().port}`;
+  const redirectUri = `http://${authority}/oauth/callback`;
+  server.on('request', async (request, response) => {
+    const reply = (status, message) => {
+      response.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store',
+        'Referrer-Policy': 'no-referrer', 'Content-Security-Policy': "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
+        'X-Content-Type-Options': 'nosniff', Connection: 'close' });
+      response.end(message);
+    };
+    if (settled || !authorization || request.method !== 'GET' || request.headers.host !== authority
+      || typeof request.url !== 'string' || request.url.length > MAX_URL_LENGTH || !request.url.startsWith('/oauth/callback?')
+      || (request.headers.origin !== undefined && request.headers.origin !== 'https://mcp.clickup.com')) {
+      reply(400, 'Invalid CHATI.DEV authorization callback.');
+      return;
+    }
+    // Headers are complete. Do not disconnect the browser at the 5s idle limit
+    // while its valid token exchange is still within the upstream 15s deadline.
+    // This socket remains bounded, as does the whole authorization listener.
+    response.setTimeout(CLICKUP_OAUTH_REQUEST_TIMEOUT_MS + 5000, () => request.socket.destroy());
+    try {
+      const credentials = await authorization.exchange(`http://${authority}${request.url}`);
+      reply(200, 'ClickUp authorized for this CHATI.DEV connection. You may close this tab.');
+      finish(null, credentials);
+    } catch (error) {
+      if (INVALID_CALLBACK_CODES.has(error?.code) || error?.code === 'CLICKUP_OAUTH_ALREADY_USED') {
+        // A duplicate callback must not cancel the legitimate in-flight exchange.
+        reply(400, 'Invalid or already used CHATI.DEV authorization callback.');
+        return;
+      }
+      reply(400, 'ClickUp connection was not completed. Return to CHATI.DEV for its status.');
+      finish(inheritClickUpOAuthFailureDiagnostic(
+        failure('CLICKUP_OAUTH_CONNECTION_FAILED', 'ClickUp connection was denied, expired or its token exchange failed'), error));
+    }
+  });
+  timer = setTimeout(() => {
+    finish(failure('CLICKUP_OAUTH_LISTENER_EXPIRED', 'ClickUp authorization callback expired'));
+    server.closeAllConnections();
+  }, timeoutMs);
+  return Object.freeze({
+    redirect_uri: redirectUri, result,
+    attach(value) {
+      if (settled || authorization || value?.redirect_uri !== redirectUri || typeof value.exchange !== 'function') {
+        throw failure('CLICKUP_OAUTH_LISTENER_BINDING_INVALID', 'ClickUp callback must bind exactly one matching authorization');
+      }
+      authorization = value;
+    },
+    close() {
+      finish(failure('CLICKUP_OAUTH_CONNECTION_CANCELLED', 'ClickUp connection was cancelled'));
+      server.closeAllConnections();
+    },
+  });
+}

package/src/installer-v2/clickup-oauth.js

@@ -0,0 +1,233 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+// This client is intentionally restricted to the official ClickUp MCP service.
+// Metadata must not turn an authorization exchange into a caller-selected POST.
+export const CLICKUP_MCP_RESOURCE = 'https://mcp.clickup.com/mcp';
+const ISSUER = 'https://mcp.clickup.com';
+const SCOPES = 'read write';
+const MAX_RESPONSE_BYTES = 64 * 1024;
+export const CLICKUP_OAUTH_REQUEST_TIMEOUT_MS = 15_000;
+const AUTHORIZATION_LIFETIME_MS = 10 * 60_000;
+const MAX_LOCAL_TOKEN_LIFETIME_SECONDS = 366 * 86400;
+const REDIRECT_PATH = '/oauth/callback';
+const failureDiagnostics = new WeakMap();
+const UNKNOWN_FAILURE = Object.freeze({ code: 'CLICKUP_OAUTH_FAILURE_UNKNOWN' });
+const OAUTH_ERROR_CODES = new Set(['invalid_grant', 'invalid_client', 'invalid_request', 'unauthorized_client',
+  'unsupported_grant_type', 'invalid_scope', 'server_error', 'temporarily_unavailable', 'access_denied']);
+
+/** Only diagnostics constructed here are trusted; never serialize foreign errors. */
+export function clickUpOAuthFailureDiagnostic(error) {
+  return failureDiagnostics.get(error) || UNKNOWN_FAILURE;
+}
+
+/** Carry only locally constructed metadata across a fixed-message wrapper. */
+export function inheritClickUpOAuthFailureDiagnostic(target, source) {
+  failureDiagnostics.set(target, clickUpOAuthFailureDiagnostic(source));
+  return target;
+}
+
+function fail(code, message, diagnostic = {}) {
+  const error = Object.assign(new Error(message), { code });
+  failureDiagnostics.set(error, Object.freeze({ code, ...diagnostic }));
+  throw error;
+}
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function text(value, max = 8192) {
+  return typeof value === 'string' && value.length > 0 && value.length <= max
+    && ![...value].some((character) => character.codePointAt(0) <= 32 || character.codePointAt(0) === 127);
+}
+function includes(array, value) { return Array.isArray(array) && array.includes(value); }
+
+function readWriteScope(value) {
+  if (typeof value !== 'string') return false;
+  const parts = value.split(' ');
+  return parts.length === 2 && new Set(parts).size === 2 && includes(parts, 'read') && includes(parts, 'write');
+}
+
+export function assertClickUpOAuthRedirect(value) {
+  let url;
+  try { url = new URL(value); } catch { fail('CLICKUP_OAUTH_REDIRECT_INVALID', 'ClickUp OAuth requires an exact loopback callback'); }
+  if (url.href !== value || url.protocol !== 'http:' || url.hostname !== '127.0.0.1'
+    || !/^\d+$/.test(url.port) || Number(url.port) < 1024
+    || url.pathname !== REDIRECT_PATH || url.username || url.password || url.search || url.hash) {
+    fail('CLICKUP_OAUTH_REDIRECT_INVALID', 'ClickUp OAuth requires an exact loopback callback');
+  }
+  return value;
+}
+
+async function requestJson(url, init, fetchImpl) {
+  let response;
+  let reader;
+  try {
+    response = await fetchImpl(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(CLICKUP_OAUTH_REQUEST_TIMEOUT_MS) });
+    const httpDiagnostic = Number.isInteger(response.status) && response.status >= 100 && response.status <= 599
+      ? { http_status: response.status } : {};
+    if (!/^application\/json(?:;|$)/i.test(response.headers.get('content-type') || '')) {
+      fail('CLICKUP_OAUTH_HTTP_REJECTED', 'ClickUp OAuth endpoint rejected the request', httpDiagnostic);
+    }
+    if (Number(response.headers.get('content-length')) > MAX_RESPONSE_BYTES) {
+      fail('CLICKUP_OAUTH_RESPONSE_INVALID', 'ClickUp OAuth response exceeded its size limit');
+    }
+    reader = response.body?.getReader();
+    if (!reader) fail('CLICKUP_OAUTH_RESPONSE_INVALID', 'ClickUp OAuth response was empty');
+    const chunks = [];
+    let bytes = 0;
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) fail('CLICKUP_OAUTH_RESPONSE_INVALID', 'ClickUp OAuth response exceeded its size limit');
+      chunks.push(chunk.value);
+    }
+    let result;
+    try { result = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+    catch { fail('CLICKUP_OAUTH_RESPONSE_INVALID', 'ClickUp OAuth response was not valid JSON'); }
+    if (!object(result)) fail('CLICKUP_OAUTH_RESPONSE_INVALID', 'ClickUp OAuth response was not an object');
+    if (!response.ok) {
+      fail('CLICKUP_OAUTH_HTTP_REJECTED', 'ClickUp OAuth endpoint rejected the request', {
+        ...httpDiagnostic, oauth_error: OAUTH_ERROR_CODES.has(result.error) ? result.error : 'unrecognized',
+      });
+    }
+    return result;
+  } catch (error) {
+    // Remote bodies, Location headers and thrown fetch errors may contain codes
+    // or credentials. No external exception message/cause crosses this boundary.
+    if (failureDiagnostics.has(error)) throw error;
+    return fail('CLICKUP_OAUTH_NETWORK_FAILED', 'ClickUp OAuth request failed or timed out; no automatic retry was made');
+  } finally {
+    try {
+      if (reader) await reader.cancel();
+      else if (response?.body) await response.body.cancel();
+    } catch { /* best-effort cancellation, never disclose a remote error */ }
+  }
+}
+
+/** Public metadata only. This does not register a client or read credentials. */
+export async function discoverClickUpOAuth({ fetchImpl = globalThis.fetch } = {}) {
+  const resource = await requestJson(`${ISSUER}/.well-known/oauth-protected-resource/mcp`, { headers: { Accept: 'application/json' } }, fetchImpl);
+  if (resource.resource !== CLICKUP_MCP_RESOURCE || !Array.isArray(resource.authorization_servers)
+    || resource.authorization_servers.length !== 1 || resource.authorization_servers[0] !== ISSUER
+    || !includes(resource.scopes_supported, 'read') || !includes(resource.scopes_supported, 'write')) {
+    fail('CLICKUP_OAUTH_METADATA_INVALID', 'ClickUp protected-resource metadata does not match the pinned service');
+  }
+  const server = await requestJson(`${ISSUER}/.well-known/oauth-authorization-server`, { headers: { Accept: 'application/json' } }, fetchImpl);
+  if (server.issuer !== ISSUER || server.authorization_endpoint !== `${ISSUER}/oauth/authorize`
+    || server.token_endpoint !== `${ISSUER}/oauth/token` || server.registration_endpoint !== `${ISSUER}/oauth/register`
+    || !includes(server.code_challenge_methods_supported, 'S256')
+    || !includes(server.response_types_supported, 'code')
+    || !includes(server.grant_types_supported, 'authorization_code')
+    || !includes(server.token_endpoint_auth_methods_supported, 'none')) {
+    fail('CLICKUP_OAUTH_METADATA_INVALID', 'ClickUp authorization metadata does not support the pinned public PKCE client');
+  }
+  return Object.freeze({ resource: CLICKUP_MCP_RESOURCE, issuer: ISSUER, scope: SCOPES });
+}
+
+/** Explicit external registration. Never falls back to a borrowed client ID. */
+export async function registerClickUpOAuthClient({ redirectUri, fetchImpl = globalThis.fetch } = {}) {
+  assertClickUpOAuthRedirect(redirectUri);
+  await discoverClickUpOAuth({ fetchImpl });
+  const result = await requestJson(`${ISSUER}/oauth/register`, {
+    method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_name: 'CHATI.DEV local ClickUp connection', redirect_uris: [redirectUri],
+      grant_types: ['authorization_code'], response_types: ['code'],
+      token_endpoint_auth_method: 'none', scope: SCOPES }),
+  }, fetchImpl);
+  if (!text(result.client_id, 1024) || result.token_endpoint_auth_method !== 'none'
+    || !Array.isArray(result.redirect_uris) || result.redirect_uris.length !== 1 || result.redirect_uris[0] !== redirectUri
+    || Object.hasOwn(result, 'client_secret') || (result.scope !== undefined && !readWriteScope(result.scope))) {
+    fail('CLICKUP_OAUTH_CLIENT_INVALID', 'ClickUp registration did not return the requested public client binding');
+  }
+  return Object.freeze({ client_id: result.client_id, redirect_uri: redirectUri, issuer: ISSUER, resource: CLICKUP_MCP_RESOURCE });
+}
+
+function assertClient(client) {
+  if (!object(client) || client.issuer !== ISSUER || client.resource !== CLICKUP_MCP_RESOURCE || !text(client.client_id, 1024)) {
+    fail('CLICKUP_OAUTH_CLIENT_INVALID', 'ClickUp OAuth client binding is invalid');
+  }
+  assertClickUpOAuthRedirect(client.redirect_uri);
+}
+
+function tokenResult(result, now) {
+  const bearer = (value) => typeof value === 'string' && value.length > 0 && value.length <= 16384 && /^[A-Za-z0-9._~+/-]+=*$/.test(value);
+  const expiryState = result.expires_in === undefined ? 'missing'
+    : !Number.isSafeInteger(result.expires_in) ? 'not_integer'
+      : result.expires_in < 1 ? 'nonpositive' : 'valid';
+  const invalidFields = [];
+  if (typeof result.token_type !== 'string' || result.token_type.toLowerCase() !== 'bearer') invalidFields.push('token_type');
+  if (!bearer(result.access_token)) invalidFields.push('access_token');
+  if (expiryState !== 'valid') invalidFields.push('expires_in');
+  if (result.refresh_token !== undefined && !text(result.refresh_token, 16384)) invalidFields.push('refresh_token');
+  if (result.scope !== undefined && !readWriteScope(result.scope)) invalidFields.push('scope');
+  if (invalidFields.length) {
+    fail('CLICKUP_OAUTH_TOKEN_INVALID', 'ClickUp token response does not match the requested authorization', {
+      invalid_fields: Object.freeze(invalidFields), expiry_state: expiryState,
+    });
+  }
+  // RFC6749 defines expires_in as a duration, not a maximum permitted lifetime.
+  // Bound OUR use of a long-lived token instead of rejecting it. Cap before
+  // multiplication to avoid overflow; never extend a shorter upstream lifetime.
+  const lifetimeSeconds = Math.min(result.expires_in, MAX_LOCAL_TOKEN_LIFETIME_SECONDS);
+  return Object.freeze({ token_type: 'Bearer', access_token: result.access_token,
+    ...(result.refresh_token === undefined ? {} : { refresh_token: result.refresh_token }),
+    scope: SCOPES, expires_at: new Date(now + lifetimeSeconds * 1000).toISOString() });
+}
+
+/** Ephemeral authorization. PKCE verifier/code are never returned or logged.
+ * The caller must keep returned credentials outside projects and transcripts.
+ * There is no CLI surface accepting a model-supplied token or callback result.
+ */
+export function createClickUpOAuthAuthorization({ client, fetchImpl = globalThis.fetch, clock = Date.now } = {}) {
+  assertClient(client);
+  // Copy the binding: caller mutation after consent must not redirect the token.
+  const binding = Object.freeze({ ...client });
+  const createdAt = clock();
+  if (!Number.isSafeInteger(createdAt) || createdAt < 0) fail('CLICKUP_OAUTH_TIME_INVALID', 'ClickUp OAuth requires a valid clock');
+  const state = randomBytes(32).toString('base64url');
+  let verifier = randomBytes(32).toString('base64url');
+  const url = new URL(`${ISSUER}/oauth/authorize`);
+  url.search = new URLSearchParams({ response_type: 'code', client_id: binding.client_id,
+    redirect_uri: binding.redirect_uri, scope: SCOPES, resource: CLICKUP_MCP_RESOURCE, state,
+    code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256' }).toString();
+  let consumed = false;
+  return Object.freeze({
+    authorization_url: url.href, redirect_uri: binding.redirect_uri,
+    expires_at: new Date(createdAt + AUTHORIZATION_LIFETIME_MS).toISOString(),
+    async exchange(callbackUrl) {
+      const now = clock();
+      if (consumed) fail('CLICKUP_OAUTH_ALREADY_USED', 'ClickUp authorization has already been consumed');
+      if (!Number.isSafeInteger(now) || now < createdAt || now - createdAt >= AUTHORIZATION_LIFETIME_MS) {
+        consumed = true; verifier = undefined;
+        fail('CLICKUP_OAUTH_EXPIRED', 'ClickUp authorization expired; start a new explicit connection');
+      }
+      if (typeof callbackUrl !== 'string' || callbackUrl.length > 16384) fail('CLICKUP_OAUTH_CALLBACK_INVALID', 'ClickUp OAuth callback is invalid');
+      let callback;
+      try { callback = new URL(callbackUrl); } catch { fail('CLICKUP_OAUTH_CALLBACK_INVALID', 'ClickUp OAuth callback is invalid'); }
+      const expected = new URL(binding.redirect_uri);
+      const params = callback.searchParams;
+      const returnedState = params.get('state');
+      if (callback.origin !== expected.origin || callback.pathname !== expected.pathname || callback.hash
+        || callback.username || callback.password || [...params.keys()].some((key) => params.getAll(key).length !== 1)
+        || typeof returnedState !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(returnedState)
+        || !timingSafeEqual(Buffer.from(returnedState), Buffer.from(state))) {
+        fail('CLICKUP_OAUTH_CALLBACK_INVALID', 'ClickUp OAuth callback does not match this authorization');
+      }
+      if (params.has('iss') && params.get('iss') !== ISSUER) fail('CLICKUP_OAUTH_CALLBACK_INVALID', 'ClickUp OAuth callback issuer does not match');
+      if (params.has('error')) {
+        consumed = true; verifier = undefined;
+        fail('CLICKUP_OAUTH_CONSENT_DENIED', 'ClickUp authorization was not granted');
+      }
+      const code = params.get('code');
+      if (!text(code, 8192)) fail('CLICKUP_OAUTH_CALLBACK_INVALID', 'ClickUp OAuth callback has no valid authorization code');
+      // Consume before I/O. A timeout may have consumed the code upstream.
+      consumed = true;
+      const body = new URLSearchParams({ grant_type: 'authorization_code', client_id: binding.client_id,
+        code, redirect_uri: binding.redirect_uri, resource: CLICKUP_MCP_RESOURCE, code_verifier: verifier }).toString();
+      verifier = undefined;
+      const result = await requestJson(`${ISSUER}/oauth/token`, {
+        method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' }, body,
+      }, fetchImpl);
+      // Use request start time, not response time, so network delay cannot extend validity.
+      return tokenResult(result, now);
+    },
+  });
+}