cli-claw-kit 0.0.1

package/dist/logger.js

@@ -0,0 +1,22 @@
+import pino from 'pino';
+export const logger = pino({
+    level: process.env.LOG_LEVEL || 'info',
+    transport: {
+        target: 'pino-pretty',
+        options: {
+            colorize: true,
+            translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l',
+        },
+    },
+});
+// Route uncaught errors through pino so they get timestamps in stderr
+process.on('uncaughtException', (err) => {
+    logger.fatal({ err }, 'Uncaught exception');
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    logger.error({ err: reason }, 'Unhandled rejection');
+    // 不立即退出：unhandled rejection 通常非致命（如 API 超时未 catch），
+    // 立即 exit 会导致长期运行服务丢失正在处理的消息和容器管理状态。
+    // uncaughtException 仍保持 exit(1)，因为异常会破坏进程状态。
+});

package/dist/mcp-utils.js

@@ -0,0 +1,66 @@
+/**
+ * Shared MCP server loading utilities.
+ * Used by container-runner (Docker + Host modes) and routes/mcp-servers.
+ */
+import fs from 'fs';
+import path from 'path';
+import { DATA_DIR } from './config.js';
+/**
+ * Load enabled MCP server configs from a servers.json file.
+ * Returns only enabled servers with fields needed for settings.json.
+ * Supports both stdio (command/args/env) and http/sse (type/url/headers) server types.
+ */
+function loadMcpServersFromFile(serversFile) {
+    try {
+        if (!fs.existsSync(serversFile))
+            return {};
+        const file = JSON.parse(fs.readFileSync(serversFile, 'utf8'));
+        const raw = file.servers || {};
+        const result = {};
+        for (const [name, server] of Object.entries(raw)) {
+            if (!server.enabled)
+                continue;
+            const isHttpType = server.type === 'http' || server.type === 'sse';
+            if (isHttpType) {
+                if (!server.url)
+                    continue;
+                const entry = {
+                    type: server.type,
+                    url: server.url,
+                };
+                if (server.headers &&
+                    typeof server.headers === 'object' &&
+                    Object.keys(server.headers).length > 0) {
+                    entry.headers = server.headers;
+                }
+                result[name] = entry;
+            }
+            else {
+                if (!server.command)
+                    continue;
+                const entry = { command: server.command };
+                if (server.args)
+                    entry.args = server.args;
+                if (server.env &&
+                    typeof server.env === 'object' &&
+                    Object.keys(server.env).length > 0) {
+                    entry.env = server.env;
+                }
+                result[name] = entry;
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Load enabled MCP server configs for a user.
+ * Reads ~/.cli-claw/mcp-servers/{userId}/servers.json.
+ * All workspaces owned by this user share the same MCP server set.
+ */
+export function loadUserMcpServers(userId) {
+    const serversFile = path.join(DATA_DIR, 'mcp-servers', userId, 'servers.json');
+    return loadMcpServersFromFile(serversFile);
+}

package/dist/message-attachments.js

@@ -0,0 +1,69 @@
+import { detectImageMimeTypeFromBase64Strict } from './image-detector.js';
+const DATA_URL_BASE64_RE = /^\s*data:([^;,]+);base64,(.*)\s*$/is;
+function normalizeImageMimeType(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const lowered = raw.trim().toLowerCase();
+    if (!lowered.startsWith('image/'))
+        return undefined;
+    return lowered;
+}
+function unwrapBase64Payload(raw) {
+    const match = DATA_URL_BASE64_RE.exec(raw);
+    if (!match)
+        return { base64: raw.replace(/\s+/g, '') };
+    return {
+        hintedMime: normalizeImageMimeType(match[1]),
+        base64: match[2].replace(/\s+/g, ''),
+    };
+}
+function resolveImageMimeType(declaredMime, detectedMime, options) {
+    if (declaredMime && detectedMime && declaredMime !== detectedMime) {
+        options?.onMimeMismatch?.({ declaredMime, detectedMime });
+        return detectedMime;
+    }
+    if (declaredMime)
+        return declaredMime;
+    if (detectedMime)
+        return detectedMime;
+    return 'image/jpeg';
+}
+export function normalizeImageAttachment(input, options) {
+    // 历史附件数据可能缺少 type 字段，缺失时默认视为 image
+    if ((input.type ?? 'image') !== 'image')
+        return null;
+    if (typeof input.data !== 'string' || input.data.length === 0)
+        return null;
+    const { base64, hintedMime } = unwrapBase64Payload(input.data);
+    if (base64.length === 0)
+        return null;
+    const declared = normalizeImageMimeType(input.mimeType) || hintedMime;
+    const detected = detectImageMimeTypeFromBase64Strict(base64);
+    const mimeType = resolveImageMimeType(declared, detected, options);
+    return {
+        type: 'image',
+        data: base64,
+        mimeType,
+    };
+}
+export function normalizeImageAttachments(inputs, options) {
+    if (!Array.isArray(inputs))
+        return [];
+    const normalized = [];
+    for (const item of inputs) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const out = normalizeImageAttachment(item, options);
+        if (out)
+            normalized.push(out);
+    }
+    return normalized;
+}
+export function toAgentImages(attachments) {
+    if (!attachments || attachments.length === 0)
+        return undefined;
+    return attachments.map((att) => ({
+        data: att.data,
+        mimeType: att.mimeType,
+    }));
+}

package/dist/message-notifier.js

@@ -0,0 +1,36 @@
+/**
+ * Lightweight notification mechanism for IM messages.
+ *
+ * The message polling loop in index.ts sleeps for POLL_INTERVAL (2s) between
+ * iterations.  When a Feishu / Telegram / QQ handler stores a new message it
+ * calls `notifyNewImMessage()` which wakes the loop immediately so the message
+ * is picked up without waiting for the remaining sleep time.
+ *
+ * Web messages are NOT routed through this notifier — they already bypass the
+ * polling loop via direct IPC injection + `enqueueMessageCheck()`.
+ */
+let wakeup = null;
+/**
+ * Returns a Promise that resolves after `ms` milliseconds **or** as soon as
+ * `notifyNewImMessage()` is called — whichever comes first.
+ */
+export function interruptibleSleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            wakeup = null;
+            resolve();
+        }, ms);
+        wakeup = () => {
+            clearTimeout(timer);
+            wakeup = null;
+            resolve();
+        };
+    });
+}
+/**
+ * Wake the message loop immediately.  Safe to call at any time — if the loop
+ * is not sleeping this is a no-op.
+ */
+export function notifyNewImMessage() {
+    wakeup?.();
+}

package/dist/middleware/auth.js

@@ -0,0 +1,85 @@
+// Authentication and authorization middleware
+import { lastActiveCache, LAST_ACTIVE_DEBOUNCE_MS, parseCookie, getCachedSessionWithUser, invalidateSessionCache, } from '../web-context.js';
+import { updateSessionLastActive, deleteUserSession } from '../db.js';
+import { isSessionExpired } from '../auth.js';
+import { hasPermission } from '../permissions.js';
+import { SESSION_COOKIE_NAME_SECURE, SESSION_COOKIE_NAME_PLAIN, } from '../config.js';
+export const authMiddleware = async (c, next) => {
+    const cookies = parseCookie(c.req.header('cookie'));
+    // Accept either cookie name — the browser will send whichever was set
+    const token = cookies[SESSION_COOKIE_NAME_SECURE] || cookies[SESSION_COOKIE_NAME_PLAIN];
+    if (!token) {
+        return c.json({ error: 'Unauthorized' }, 401);
+    }
+    const session = getCachedSessionWithUser(token);
+    if (!session) {
+        invalidateSessionCache(token);
+        return c.json({ error: 'Unauthorized' }, 401);
+    }
+    if (isSessionExpired(session.expires_at)) {
+        deleteUserSession(token);
+        invalidateSessionCache(token);
+        return c.json({ error: 'Session expired' }, 401);
+    }
+    if (session.status === 'disabled') {
+        return c.json({ error: 'Account disabled' }, 403);
+    }
+    if (session.status === 'deleted') {
+        return c.json({ error: 'Account deleted' }, 403);
+    }
+    c.set('user', {
+        id: session.user_id,
+        username: session.username,
+        role: session.role,
+        status: session.status,
+        display_name: session.display_name,
+        permissions: session.permissions,
+        must_change_password: session.must_change_password,
+    });
+    c.set('sessionId', token);
+    const requestPath = c.req.path;
+    const canBypassForcedChange = requestPath === '/api/auth/me' ||
+        requestPath === '/api/auth/password' ||
+        requestPath === '/api/auth/logout' ||
+        requestPath === '/api/auth/profile' ||
+        requestPath.startsWith('/api/auth/sessions');
+    if (session.must_change_password && !canBypassForcedChange) {
+        return c.json({ error: 'Password change required', code: 'PASSWORD_CHANGE_REQUIRED' }, 403);
+    }
+    // Low-frequency last_active_at update (every 5 min)
+    const now = Date.now();
+    const lastUpdate = lastActiveCache.get(token) || 0;
+    if (now - lastUpdate > LAST_ACTIVE_DEBOUNCE_MS) {
+        lastActiveCache.set(token, now);
+        try {
+            updateSessionLastActive(token);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    await next();
+};
+export const requirePermission = (permission) => async (c, next) => {
+    const user = c.get('user');
+    if (!hasPermission(user, permission)) {
+        return c.json({ error: `Forbidden: ${permission} required` }, 403);
+    }
+    await next();
+};
+export const requireAnyPermission = (permissions) => async (c, next) => {
+    const user = c.get('user');
+    const ok = permissions.some((permission) => hasPermission(user, permission));
+    if (!ok) {
+        return c.json({ error: `Forbidden: one of [${permissions.join(', ')}] required` }, 403);
+    }
+    await next();
+};
+export const systemConfigMiddleware = requirePermission('manage_system_config');
+export const groupEnvMiddleware = requireAnyPermission([
+    'manage_group_env',
+    'manage_system_config',
+]);
+export const usersManageMiddleware = requirePermission('manage_users');
+export const inviteManageMiddleware = requirePermission('manage_invites');
+export const auditViewMiddleware = requirePermission('view_audit_log');

package/dist/mount-security.js

@@ -0,0 +1,315 @@
+/**
+ * Mount Security Module for cli-claw
+ *
+ * Validates additional mounts against an allowlist stored in the project config/ directory.
+ *
+ * Allowlist location: config/mount-allowlist.json
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { MOUNT_ALLOWLIST_PATH } from './config.js';
+import { logger } from './logger.js';
+// Cache the allowlist in memory - only reloads on process restart
+let cachedAllowlist = null;
+let allowlistLoadError = null;
+/**
+ * Default blocked patterns - paths that should never be mounted
+ */
+const DEFAULT_BLOCKED_PATTERNS = [
+    '.ssh',
+    '.gnupg',
+    '.gpg',
+    '.aws',
+    '.azure',
+    '.gcloud',
+    '.kube',
+    '.docker',
+    'credentials',
+    '.env',
+    '.netrc',
+    '.npmrc',
+    '.pypirc',
+    'id_rsa',
+    'id_ed25519',
+    'private_key',
+    '.secret',
+];
+/**
+ * Load the mount allowlist from the external config location.
+ * Returns null if the file doesn't exist or is invalid.
+ * Result is cached in memory for the lifetime of the process.
+ */
+export function loadMountAllowlist() {
+    if (cachedAllowlist !== null) {
+        return cachedAllowlist;
+    }
+    if (allowlistLoadError !== null) {
+        // Already tried and failed, don't spam logs
+        return null;
+    }
+    try {
+        if (!fs.existsSync(MOUNT_ALLOWLIST_PATH)) {
+            allowlistLoadError = `Mount allowlist not found at ${MOUNT_ALLOWLIST_PATH}`;
+            logger.warn({ path: MOUNT_ALLOWLIST_PATH }, 'Mount allowlist not found - additional mounts will be BLOCKED. ' +
+                'Create the file to enable additional mounts.');
+            return null;
+        }
+        const content = fs.readFileSync(MOUNT_ALLOWLIST_PATH, 'utf-8');
+        const allowlist = JSON.parse(content);
+        // Validate structure
+        if (!Array.isArray(allowlist.allowedRoots)) {
+            throw new Error('allowedRoots must be an array');
+        }
+        if (!Array.isArray(allowlist.blockedPatterns)) {
+            throw new Error('blockedPatterns must be an array');
+        }
+        if (typeof allowlist.nonMainReadOnly !== 'boolean') {
+            throw new Error('nonMainReadOnly must be a boolean');
+        }
+        // Merge with default blocked patterns
+        const mergedBlockedPatterns = [
+            ...new Set([...DEFAULT_BLOCKED_PATTERNS, ...allowlist.blockedPatterns]),
+        ];
+        allowlist.blockedPatterns = mergedBlockedPatterns;
+        cachedAllowlist = allowlist;
+        logger.info({
+            path: MOUNT_ALLOWLIST_PATH,
+            allowedRoots: allowlist.allowedRoots.length,
+            blockedPatterns: allowlist.blockedPatterns.length,
+        }, 'Mount allowlist loaded successfully');
+        return cachedAllowlist;
+    }
+    catch (err) {
+        allowlistLoadError = err instanceof Error ? err.message : String(err);
+        logger.error({
+            path: MOUNT_ALLOWLIST_PATH,
+            error: allowlistLoadError,
+        }, 'Failed to load mount allowlist - additional mounts will be BLOCKED');
+        return null;
+    }
+}
+/**
+ * Expand ~ to home directory and resolve to absolute path
+ */
+export function expandPath(p) {
+    const homeDir = os.homedir();
+    if (p.startsWith('~/')) {
+        return path.join(homeDir, p.slice(2));
+    }
+    if (p === '~') {
+        return homeDir;
+    }
+    return path.resolve(p);
+}
+/**
+ * Get the real path, resolving symlinks.
+ * Returns null if the path doesn't exist.
+ */
+function getRealPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a path matches any blocked pattern
+ */
+export function matchesBlockedPattern(realPath, blockedPatterns) {
+    const pathParts = realPath.split(path.sep);
+    for (const pattern of blockedPatterns) {
+        // Check if any path component exactly matches the pattern
+        for (const part of pathParts) {
+            if (part === pattern) {
+                return pattern;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Check if a real path is under an allowed root
+ */
+export function findAllowedRoot(realPath, allowedRoots) {
+    for (const root of allowedRoots) {
+        const expandedRoot = expandPath(root.path);
+        const realRoot = getRealPath(expandedRoot);
+        if (realRoot === null) {
+            // Allowed root doesn't exist, skip it
+            continue;
+        }
+        // Check if realPath is under realRoot
+        const relative = path.relative(realRoot, realPath);
+        if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+            return root;
+        }
+    }
+    return null;
+}
+/**
+ * Validate the container path to prevent escaping /workspace/extra/
+ */
+function isValidContainerPath(containerPath) {
+    // Must not contain .. to prevent path traversal
+    if (containerPath.includes('..')) {
+        return false;
+    }
+    // Must not be absolute (it will be prefixed with /workspace/extra/)
+    if (containerPath.startsWith('/')) {
+        return false;
+    }
+    // Must not be empty
+    if (!containerPath || containerPath.trim() === '') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validate a single additional mount against the allowlist.
+ * Returns validation result with reason.
+ */
+export function validateMount(mount, isMain) {
+    const allowlist = loadMountAllowlist();
+    // If no allowlist, block all additional mounts
+    if (allowlist === null) {
+        return {
+            allowed: false,
+            reason: `No mount allowlist configured at ${MOUNT_ALLOWLIST_PATH}`,
+        };
+    }
+    // Derive containerPath from hostPath basename if not specified
+    const containerPath = mount.containerPath || path.basename(mount.hostPath);
+    // Validate container path (cheap check)
+    if (!isValidContainerPath(containerPath)) {
+        return {
+            allowed: false,
+            reason: `Invalid container path: "${containerPath}" - must be relative, non-empty, and not contain ".."`,
+        };
+    }
+    // Expand and resolve the host path
+    const expandedPath = expandPath(mount.hostPath);
+    const realPath = getRealPath(expandedPath);
+    if (realPath === null) {
+        return {
+            allowed: false,
+            reason: `Host path does not exist: "${mount.hostPath}" (expanded: "${expandedPath}")`,
+        };
+    }
+    // Check against blocked patterns
+    const blockedMatch = matchesBlockedPattern(realPath, allowlist.blockedPatterns);
+    if (blockedMatch !== null) {
+        return {
+            allowed: false,
+            reason: `Path matches blocked pattern "${blockedMatch}": "${realPath}"`,
+        };
+    }
+    // Check if under an allowed root
+    const allowedRoot = findAllowedRoot(realPath, allowlist.allowedRoots);
+    if (allowedRoot === null) {
+        return {
+            allowed: false,
+            reason: `Path "${realPath}" is not under any allowed root. Allowed roots: ${allowlist.allowedRoots
+                .map((r) => expandPath(r.path))
+                .join(', ')}`,
+        };
+    }
+    // Determine effective readonly status
+    const requestedReadWrite = mount.readonly === false;
+    let effectiveReadonly = true; // Default to readonly
+    if (requestedReadWrite) {
+        if (!isMain && allowlist.nonMainReadOnly) {
+            // Non-main groups forced to read-only
+            effectiveReadonly = true;
+            logger.info({
+                mount: mount.hostPath,
+            }, 'Mount forced to read-only for non-main group');
+        }
+        else if (!allowedRoot.allowReadWrite) {
+            // Root doesn't allow read-write
+            effectiveReadonly = true;
+            logger.info({
+                mount: mount.hostPath,
+                root: allowedRoot.path,
+            }, 'Mount forced to read-only - root does not allow read-write');
+        }
+        else {
+            // Read-write allowed
+            effectiveReadonly = false;
+        }
+    }
+    return {
+        allowed: true,
+        reason: `Allowed under root "${allowedRoot.path}"${allowedRoot.description ? ` (${allowedRoot.description})` : ''}`,
+        realHostPath: realPath,
+        resolvedContainerPath: containerPath,
+        effectiveReadonly,
+    };
+}
+/**
+ * Validate all additional mounts for a group.
+ * Returns array of validated mounts (only those that passed validation).
+ * Logs warnings for rejected mounts.
+ */
+export function validateAdditionalMounts(mounts, groupName, isMain) {
+    const validatedMounts = [];
+    for (const mount of mounts) {
+        const result = validateMount(mount, isMain);
+        if (result.allowed) {
+            validatedMounts.push({
+                hostPath: result.realHostPath,
+                containerPath: `/workspace/extra/${result.resolvedContainerPath}`,
+                readonly: result.effectiveReadonly,
+            });
+            logger.debug({
+                group: groupName,
+                hostPath: result.realHostPath,
+                containerPath: result.resolvedContainerPath,
+                readonly: result.effectiveReadonly,
+                reason: result.reason,
+            }, 'Mount validated successfully');
+        }
+        else {
+            logger.warn({
+                group: groupName,
+                requestedPath: mount.hostPath,
+                containerPath: mount.containerPath,
+                reason: result.reason,
+            }, 'Additional mount REJECTED');
+        }
+    }
+    return validatedMounts;
+}
+/**
+ * Generate a template allowlist file for users to customize
+ */
+export function generateAllowlistTemplate() {
+    const template = {
+        allowedRoots: [
+            {
+                path: '~/projects',
+                allowReadWrite: true,
+                description: 'Development projects',
+            },
+            {
+                path: '~/repos',
+                allowReadWrite: true,
+                description: 'Git repositories',
+            },
+            {
+                path: '~/Documents/work',
+                allowReadWrite: false,
+                description: 'Work documents (read-only)',
+            },
+        ],
+        blockedPatterns: [
+            // Additional patterns beyond defaults
+            'password',
+            'secret',
+            'token',
+        ],
+        nonMainReadOnly: true,
+    };
+    return JSON.stringify(template, null, 2);
+}

package/dist/permissions.js

@@ -0,0 +1,67 @@
+export const ALL_PERMISSIONS = [
+    'manage_system_config',
+    'manage_group_env',
+    'manage_users',
+    'manage_invites',
+    'view_audit_log',
+    'manage_billing',
+];
+export const PERMISSION_TEMPLATES = {
+    admin_full: {
+        key: 'admin_full',
+        label: '管理员（全权限）',
+        role: 'admin',
+        permissions: [...ALL_PERMISSIONS],
+    },
+    member_basic: {
+        key: 'member_basic',
+        label: '普通成员（基础权限）',
+        role: 'member',
+        permissions: [],
+    },
+    ops_manager: {
+        key: 'ops_manager',
+        label: '运维管理员（配置+工作区环境）',
+        role: 'member',
+        permissions: ['manage_system_config', 'manage_group_env'],
+    },
+    user_admin: {
+        key: 'user_admin',
+        label: '用户管理员（用户+邀请码+审计）',
+        role: 'member',
+        permissions: ['manage_users', 'manage_invites', 'view_audit_log'],
+    },
+};
+export const ROLE_DEFAULT_PERMISSIONS = {
+    admin: [...ALL_PERMISSIONS],
+    member: [],
+};
+export function normalizePermissions(input) {
+    if (!Array.isArray(input))
+        return [];
+    const set = new Set();
+    for (const value of input) {
+        if (typeof value !== 'string')
+            continue;
+        if (ALL_PERMISSIONS.includes(value)) {
+            set.add(value);
+        }
+    }
+    return Array.from(set);
+}
+export function getDefaultPermissions(role) {
+    return [...(ROLE_DEFAULT_PERMISSIONS[role] || [])];
+}
+export function resolveTemplate(template) {
+    if (!template)
+        return null;
+    const item = PERMISSION_TEMPLATES[template];
+    if (!item)
+        return null;
+    return { role: item.role, permissions: [...item.permissions] };
+}
+export function hasPermission(user, permission) {
+    if (user.role === 'admin')
+        return true;
+    return user.permissions.includes(permission);
+}

package/dist/project-memory.js

@@ -0,0 +1,6 @@
+import path from 'node:path';
+export const AGENT_MEMORY_FILENAME = 'AGENTS.md';
+export const AGENT_MEMORY_TEMPLATE_FILENAME = 'global-agents-md.template.md';
+export function getAgentMemoryPath(dir) {
+    return path.join(dir, AGENT_MEMORY_FILENAME);
+}