cc-lark 0.1.1

package/src/core/config.ts

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration management for the cc-lark MCP Server.
+ *
+ * Loads configuration from environment variables and provides validation.
+ */
+
+import type { FeishuConfig, ConfigValidationResult, LarkBrand } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Environment variable names
+// ---------------------------------------------------------------------------
+
+export const ENV_VARS = {
+  APP_ID: 'FEISHU_APP_ID',
+  APP_SECRET: 'FEISHU_APP_SECRET',
+  USER_ACCESS_TOKEN: 'FEISHU_USER_ACCESS_TOKEN',
+  BRAND: 'FEISHU_BRAND',
+  ENCRYPT_KEY: 'FEISHU_ENCRYPT_KEY',
+  VERIFICATION_TOKEN: 'FEISHU_VERIFICATION_TOKEN',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Configuration loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load Feishu configuration from environment variables.
+ *
+ * Required:
+ * - FEISHU_APP_ID: Feishu App ID
+ * - FEISHU_APP_SECRET: Feishu App Secret
+ *
+ * Optional:
+ * - FEISHU_USER_ACCESS_TOKEN: User access token for user-authorized operations
+ * - FEISHU_BRAND: Platform brand ('feishu' | 'lark' | custom URL)
+ * - FEISHU_ENCRYPT_KEY: Encryption key for webhook events
+ * - FEISHU_VERIFICATION_TOKEN: Verification token for webhooks
+ */
+export function loadConfig(): FeishuConfig {
+  const appId = process.env[ENV_VARS.APP_ID];
+  const appSecret = process.env[ENV_VARS.APP_SECRET];
+  const userAccessToken = process.env[ENV_VARS.USER_ACCESS_TOKEN];
+  const brand = process.env[ENV_VARS.BRAND] as LarkBrand | undefined;
+  const encryptKey = process.env[ENV_VARS.ENCRYPT_KEY];
+  const verificationToken = process.env[ENV_VARS.VERIFICATION_TOKEN];
+
+  return {
+    appId: appId ?? '',
+    appSecret: appSecret ?? '',
+    userAccessToken,
+    brand: brand ?? 'feishu',
+    encryptKey,
+    verificationToken,
+  };
+}
+
+/**
+ * Validate the Feishu configuration.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors if any
+ */
+export function validateConfig(config: FeishuConfig): ConfigValidationResult {
+  const errors: string[] = [];
+
+  if (!config.appId) {
+    errors.push(`Missing required environment variable: ${ENV_VARS.APP_ID}`);
+  }
+
+  if (!config.appSecret) {
+    errors.push(`Missing required environment variable: ${ENV_VARS.APP_SECRET}`);
+  }
+
+  if (config.brand) {
+    const validBrands: LarkBrand[] = ['feishu', 'lark'];
+    if (!validBrands.includes(config.brand) && !config.brand.startsWith('https://')) {
+      errors.push(
+        `Invalid FEISHU_BRAND value: "${config.brand}". Must be "feishu", "lark", or a custom HTTPS URL`
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [], config };
+}
+
+/**
+ * Load and validate configuration in one step.
+ *
+ * @throws Error if configuration is invalid
+ * @returns Validated Feishu configuration
+ */
+export function loadAndValidateConfig(): FeishuConfig {
+  const config = loadConfig();
+  const result = validateConfig(config);
+
+  if (!result.valid) {
+    throw new Error(`Invalid configuration:\n${result.errors.map(e => `  - ${e}`).join('\n')}`);
+  }
+
+  return config;
+}
+
+/**
+ * Check if configuration has user access token.
+ *
+ * @param config - Configuration to check
+ * @returns True if user access token is configured
+ */
+export function hasUserAccessToken(config: FeishuConfig): boolean {
+  return typeof config.userAccessToken === 'string' && config.userAccessToken.length > 0;
+}
+
+/**
+ * Get the base URL for the Lark API based on brand.
+ *
+ * @param brand - Platform brand
+ * @returns Base URL for API calls
+ */
+export function getApiBaseUrl(brand: LarkBrand = 'feishu'): string {
+  if (brand === 'lark') {
+    return 'https://open.larksuite.com/open-apis';
+  }
+  if (brand.startsWith('https://')) {
+    return brand;
+  }
+  return 'https://open.feishu.cn/open-apis';
+}

package/src/core/device-flow.ts

@@ -0,0 +1,314 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) for Lark/Feishu.
+ *
+ * Two-step flow:
+ *   1. `requestDeviceAuthorization` – obtains device_code + user_code.
+ *   2. `pollDeviceToken` – polls the token endpoint until the user authorizes,
+ *      rejects, or the code expires.
+ *
+ * All HTTP calls use the built-in `fetch` (Node 18+). The Lark SDK is not
+ * used here because these OAuth endpoints are outside the SDK's scope.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import type { LarkBrand } from './types.js';
+import { logger } from '../utils/logger.js';
+import { getUserAgent } from './version.js';
+
+const log = logger('device-flow');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DeviceAuthResponse {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete: string;
+  expiresIn: number; // seconds
+  interval: number; // recommended polling interval (seconds)
+}
+
+export interface DeviceFlowTokenData {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number; // seconds
+  refreshExpiresIn: number; // seconds
+  scope: string;
+}
+
+export type DeviceFlowResult =
+  | { ok: true; token: DeviceFlowTokenData }
+  | { ok: false; error: DeviceFlowError; message: string };
+
+export type DeviceFlowError = 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Header-aware fetch for Lark API calls.
+ *
+ * Drop-in replacement for `fetch()` that automatically injects
+ * the User-Agent header.
+ */
+function larkFetch(url: string | URL | Request, init?: RequestInit): Promise<Response> {
+  const headers = {
+    ...init?.headers,
+    'User-Agent': getUserAgent(),
+  };
+
+  return fetch(url, { ...init, headers });
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the two OAuth endpoint URLs based on the configured brand.
+ */
+export function resolveOAuthEndpoints(brand: LarkBrand): {
+  deviceAuthorization: string;
+  token: string;
+} {
+  if (!brand || brand === 'feishu') {
+    return {
+      deviceAuthorization: 'https://accounts.feishu.cn/oauth/v1/device_authorization',
+      token: 'https://open.feishu.cn/open-apis/authen/v2/oauth/token',
+    };
+  }
+  if (brand === 'lark') {
+    return {
+      deviceAuthorization: 'https://accounts.larksuite.com/oauth/v1/device_authorization',
+      token: 'https://open.larksuite.com/open-apis/authen/v2/oauth/token',
+    };
+  }
+  // Custom domain – derive paths by convention.
+  // Smart derivation: open.X → accounts.X for the device authorization endpoint.
+  const base = brand.replace(/\/+$/, '');
+  let accountsBase = base;
+  try {
+    const parsed = new URL(base);
+    if (parsed.hostname.startsWith('open.')) {
+      accountsBase = `${parsed.protocol}//${parsed.hostname.replace(/^open\./, 'accounts.')}`;
+    }
+  } catch {
+    /* fallback to base */
+  }
+
+  return {
+    deviceAuthorization: `${accountsBase}/oauth/v1/device_authorization`,
+    token: `${base}/open-apis/authen/v2/oauth/token`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Step 1 – Device Authorization Request
+// ---------------------------------------------------------------------------
+
+/**
+ * Request a device authorization code from the Feishu OAuth server.
+ *
+ * Uses Confidential Client authentication (HTTP Basic with appId:appSecret).
+ * The `offline_access` scope is automatically appended so that the token
+ * response includes a refresh_token.
+ */
+export async function requestDeviceAuthorization(params: {
+  appId: string;
+  appSecret: string;
+  brand: LarkBrand;
+  scope?: string;
+}): Promise<DeviceAuthResponse> {
+  const { appId, appSecret, brand } = params;
+  const endpoints = resolveOAuthEndpoints(brand);
+
+  // Ensure offline_access is always requested.
+  let scope = params.scope ?? '';
+  if (!scope.includes('offline_access')) {
+    scope = scope ? `${scope} offline_access` : 'offline_access';
+  }
+
+  const basicAuth = Buffer.from(`${appId}:${appSecret}`).toString('base64');
+
+  const body = new URLSearchParams();
+  body.set('client_id', appId);
+  body.set('scope', scope);
+
+  log.info(
+    `requesting device authorization (scope="${scope}") url=${endpoints.deviceAuthorization} token_url=${endpoints.token}`
+  );
+
+  const resp = await larkFetch(endpoints.deviceAuthorization, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Authorization: `Basic ${basicAuth}`,
+    },
+    body: body.toString(),
+  });
+
+  const text = await resp.text();
+  log.info(`response status=${resp.status} body=${text.slice(0, 500)}`);
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    throw new Error(`Device authorization failed: HTTP ${resp.status} – ${text.slice(0, 200)}`);
+  }
+
+  if (!resp.ok || data.error) {
+    const msg = (data.error_description as string) ?? (data.error as string) ?? 'Unknown error';
+    throw new Error(`Device authorization failed: ${msg}`);
+  }
+
+  const expiresIn = (data.expires_in as number) ?? 240;
+  const interval = (data.interval as number) ?? 5;
+  log.info(
+    `device_code obtained, expires_in=${expiresIn}s (${Math.round(expiresIn / 60)}min), interval=${interval}s`
+  );
+
+  return {
+    deviceCode: data.device_code as string,
+    userCode: data.user_code as string,
+    verificationUri: data.verification_uri as string,
+    verificationUriComplete: (data.verification_uri_complete as string) ?? (data.verification_uri as string),
+    expiresIn,
+    interval,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 – Poll Token Endpoint
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException('Aborted', 'AbortError'));
+      },
+      { once: true }
+    );
+  });
+}
+
+/**
+ * Poll the token endpoint until the user authorizes, rejects, or the code
+ * expires.
+ *
+ * Handles `authorization_pending` (keep polling), `slow_down` (back off by
+ * +5 s), `access_denied` and `expired_token` (terminal errors).
+ *
+ * Pass an `AbortSignal` to cancel polling from the outside.
+ */
+export async function pollDeviceToken(params: {
+  appId: string;
+  appSecret: string;
+  brand: LarkBrand;
+  deviceCode: string;
+  interval: number;
+  expiresIn: number;
+  signal?: AbortSignal;
+}): Promise<DeviceFlowResult> {
+  const MAX_POLL_INTERVAL = 60; // slow_down max interval 60 seconds
+  const MAX_POLL_ATTEMPTS = 200; // Safety limit (well beyond device code expiry)
+
+  const { appId, appSecret, brand, deviceCode, expiresIn, signal } = params;
+  let interval = params.interval;
+  const endpoints = resolveOAuthEndpoints(brand);
+  const deadline = Date.now() + expiresIn * 1000;
+  let attempts = 0;
+
+  while (Date.now() < deadline && attempts < MAX_POLL_ATTEMPTS) {
+    attempts++;
+    if (signal?.aborted) {
+      return { ok: false, error: 'expired_token', message: 'Polling was cancelled' };
+    }
+
+    await sleep(interval * 1000, signal);
+
+    let data: Record<string, unknown>;
+    try {
+      const resp = await larkFetch(endpoints.token, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+          device_code: deviceCode,
+          client_id: appId,
+          client_secret: appSecret,
+        }).toString(),
+      });
+      data = (await resp.json()) as Record<string, unknown>;
+    } catch (err) {
+      log.warn(`poll network error: ${err}`);
+      interval = Math.min(interval + 1, MAX_POLL_INTERVAL);
+      continue;
+    }
+
+    const error = data.error as string | undefined;
+
+    if (!error && data.access_token) {
+      log.info('token obtained successfully');
+      const refreshToken = (data.refresh_token as string) ?? '';
+      const expiresIn = (data.expires_in as number) ?? 7200;
+      let refreshExpiresIn = (data.refresh_token_expires_in as number) ?? 604800;
+      if (!refreshToken) {
+        log.warn('no refresh_token in response, token will not be refreshable');
+        refreshExpiresIn = expiresIn;
+      }
+      return {
+        ok: true,
+        token: {
+          accessToken: data.access_token as string,
+          refreshToken,
+          expiresIn,
+          refreshExpiresIn,
+          scope: (data.scope as string) ?? '',
+        },
+      };
+    }
+
+    if (error === 'authorization_pending') {
+      log.debug('authorization_pending, retrying...');
+      continue;
+    }
+
+    if (error === 'slow_down') {
+      interval = Math.min(interval + 5, MAX_POLL_INTERVAL);
+      log.info(`slow_down, interval increased to ${interval}s`);
+      continue;
+    }
+
+    if (error === 'access_denied') {
+      log.info('user denied authorization');
+      return { ok: false, error: 'access_denied', message: 'User denied authorization' };
+    }
+
+    if (error === 'expired_token' || error === 'invalid_grant') {
+      log.info(`device code expired/invalid (error=${error})`);
+      return { ok: false, error: 'expired_token', message: 'Authorization code expired, please retry' };
+    }
+
+    // Unknown error – treat as terminal.
+    const desc = (data.error_description as string) ?? error ?? 'Unknown error';
+    log.warn(`unexpected error: error=${error}, desc=${desc}`);
+    return { ok: false, error: 'expired_token', message: desc };
+  }
+
+  if (attempts >= MAX_POLL_ATTEMPTS) {
+    log.warn(`max poll attempts (${MAX_POLL_ATTEMPTS}) reached`);
+  }
+  return { ok: false, error: 'expired_token', message: 'Authorization timed out, please retry' };
+}

package/src/core/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Core module exports for cc-lark MCP Server.
+ */
+
+export * from './types.js';
+export * from './config.js';
+export * from './api-error.js';
+export * from './lark-client.js';
+export * from './version.js';
+export * from './auth-errors.js';
+export * from './device-flow.js';
+export * from './token-store.js';
+export * from './uat-client.js';