@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/core/McpTokenService.js

@@ -0,0 +1,921 @@
+import { randomBytes, createHash } from 'crypto';
+import { TaskforceRuleError } from './types.js';
+import { hashMcpAccessTokenSecret, verifyMcpAccessTokenSecret, hashMcpOAuthSecret, verifyMcpOAuthSecret, generateUuidV7, } from './shared.js';
+// ─── Constants ───────────────────────────────────────────────────────────────
+const MCP_ACCESS_TOKEN_MAX_ACTIVE_PER_USER_WORKSPACE = 10;
+const MCP_ACCESS_TOKEN_DEFAULT_PAGE_SIZE = 20;
+const MCP_ACCESS_TOKEN_MAX_PAGE_SIZE = 100;
+const MCP_ACCESS_TOKEN_ALLOWED_SCOPES = ['tasks:read', 'tasks:write', 'workspace:read'];
+const MCP_OAUTH_AUTH_CODE_TTL_MS = 10 * 60 * 1000;
+/**
+ * Handles MCP direct-access tokens and MCP OAuth connector flow
+ * (client registration, authorization codes, token exchange, grant lifecycle).
+ */
+export class McpTokenService {
+    db;
+    tenantId;
+    deps;
+    constructor(db, tenantId, deps) {
+        this.db = db;
+        this.tenantId = tenantId;
+        this.deps = deps;
+    }
+    // ─── Pure helpers (no external deps) ────────────────────────────────────
+    generateEntityId(prefix) {
+        return `${prefix}-${generateUuidV7()}`;
+    }
+    normalizeAccessRole(role, fallback = 'member') {
+        const normalized = String(role || '').trim().toLowerCase();
+        if (normalized === 'owner' || normalized === 'admin' || normalized === 'member' || normalized === 'read-only') {
+            return normalized;
+        }
+        if (normalized === 'readonly')
+            return 'read-only';
+        return fallback;
+    }
+    normalizePermissionMode(mode, fallback = 'read-write') {
+        const normalized = String(mode || '').trim().toLowerCase();
+        if (normalized === 'read-only' || normalized === 'readonly')
+            return 'read-only';
+        if (normalized === 'read-write' || normalized === 'readwrite')
+            return 'read-write';
+        return fallback;
+    }
+    normalizeMcpAccessTokenScopes(scopes) {
+        const values = Array.isArray(scopes) ? scopes : [];
+        const normalized = values
+            .map((value) => String(value || '').trim())
+            .filter((value) => MCP_ACCESS_TOKEN_ALLOWED_SCOPES.includes(value));
+        const unique = Array.from(new Set(normalized));
+        if (unique.length === 0) {
+            throw new TaskforceRuleError('At least one valid MCP token scope is required', 400, 'MCP_TOKEN_SCOPE_REQUIRED');
+        }
+        return unique;
+    }
+    createMcpAccessTokenPrefix() {
+        return `tfmcp_${randomBytes(6).toString('hex')}`;
+    }
+    parseMcpAccessToken(rawToken) {
+        const normalized = String(rawToken || '').trim();
+        if (!normalized.startsWith('tfmcp_'))
+            return null;
+        const parts = normalized.split('_');
+        if (parts.length < 3)
+            return null;
+        const tokenPrefix = `${parts[0]}_${parts[1]}`;
+        const secret = parts.slice(2).join('_').trim();
+        if (!tokenPrefix || !secret)
+            return null;
+        return { tokenPrefix, secret };
+    }
+    normalizeMcpOAuthProvider(raw) {
+        const normalized = String(raw || '').trim().toLowerCase();
+        if (normalized === 'chatgpt')
+            return 'chatgpt';
+        if (normalized === 'claude')
+            return 'claude';
+        throw new TaskforceRuleError('Unsupported MCP OAuth provider', 400, 'MCP_OAUTH_PROVIDER_INVALID');
+    }
+    defaultMcpOAuthClientName(provider) {
+        return provider === 'claude' ? 'Claude Desktop Connector' : 'ChatGPT Connector';
+    }
+    createMcpOAuthCodePrefix() {
+        return `tfmcpoauthcode_${randomBytes(6).toString('hex')}`;
+    }
+    createMcpOAuthAccessTokenPrefix() {
+        return `tfmcpoauth_${randomBytes(6).toString('hex')}`;
+    }
+    parseMcpOAuthOpaqueSecret(rawToken, expectedPrefix) {
+        const normalized = String(rawToken || '').trim();
+        if (!normalized.startsWith(expectedPrefix))
+            return null;
+        const marker = expectedPrefix.endsWith('_') ? expectedPrefix.slice(0, -1) : expectedPrefix;
+        const parts = normalized.split('_');
+        if (parts.length < 3)
+            return null;
+        const tokenPrefix = `${marker}_${parts[1]}`;
+        const secret = parts.slice(2).join('_').trim();
+        if (!tokenPrefix || !secret)
+            return null;
+        return { tokenPrefix, secret };
+    }
+    normalizeRedirectUris(value) {
+        const redirectUris = Array.isArray(value) ? value : [];
+        const normalized = Array.from(new Set(redirectUris
+            .map((uri) => String(uri || '').trim())
+            .filter(Boolean)
+            .filter((uri) => {
+            try {
+                const parsed = new URL(uri);
+                return parsed.protocol === 'https:' || parsed.protocol === 'http:';
+            }
+            catch {
+                return false;
+            }
+        })));
+        if (normalized.length === 0) {
+            throw new TaskforceRuleError('At least one valid redirect URI is required', 400, 'MCP_OAUTH_REDIRECT_URI_REQUIRED');
+        }
+        return normalized;
+    }
+    normalizePkceMethod(raw) {
+        const normalized = String(raw || '').trim().toUpperCase();
+        if (!normalized || normalized === 'S256')
+            return 'S256';
+        throw new TaskforceRuleError('Unsupported PKCE code challenge method', 400, 'MCP_OAUTH_PKCE_METHOD_INVALID');
+    }
+    resolveMcpOAuthGrantStatus(row) {
+        if (String(row.status || '').trim().toLowerCase() === 'revoked')
+            return 'revoked';
+        if (row.revoked_at)
+            return 'revoked';
+        return 'active';
+    }
+    getMcpOAuthClientRow(clientId, provider) {
+        const normalizedClientId = String(clientId || '').trim();
+        if (!normalizedClientId)
+            return null;
+        if (provider) {
+            return this.db.prepare(`
+                SELECT id, provider, client_name, redirect_uris_json, status, created_at, updated_at
+                FROM mcp_oauth_clients
+                WHERE tenant_id = ? AND id = ? AND provider = ?
+                LIMIT 1
+            `).get(this.tenantId, normalizedClientId, provider) || null;
+        }
+        return this.db.prepare(`
+            SELECT id, provider, client_name, redirect_uris_json, status, created_at, updated_at
+            FROM mcp_oauth_clients
+            WHERE tenant_id = ? AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedClientId) || null;
+    }
+    rowToMcpOAuthClientRecord(row) {
+        let redirectUris = [];
+        try {
+            redirectUris = this.normalizeRedirectUris(JSON.parse(String(row?.redirect_uris_json || '[]')));
+        }
+        catch {
+            redirectUris = [];
+        }
+        return {
+            id: String(row?.id || ''),
+            provider: this.normalizeMcpOAuthProvider(row?.provider),
+            clientName: String(row?.client_name || ''),
+            redirectUris,
+            status: String(row?.status || '').trim().toLowerCase() === 'revoked' ? 'revoked' : 'active',
+            createdAt: String(row?.created_at || ''),
+            updatedAt: row?.updated_at ? String(row.updated_at) : null,
+        };
+    }
+    rowToMcpOAuthConnectorGrantRecord(row) {
+        let scopes = [];
+        try {
+            scopes = this.normalizeMcpAccessTokenScopes(JSON.parse(String(row?.scopes_json || '[]')));
+        }
+        catch {
+            scopes = [];
+        }
+        return {
+            id: String(row?.id || ''),
+            provider: this.normalizeMcpOAuthProvider(row?.provider),
+            clientId: String(row?.client_id || ''),
+            clientName: String(row?.client_name || ''),
+            workspaceId: String(row?.workspace_id || ''),
+            userId: String(row?.user_id || ''),
+            scopes,
+            tokenPrefix: String(row?.token_prefix || ''),
+            status: this.resolveMcpOAuthGrantStatus(row),
+            lastUsedAt: row?.last_used_at ? String(row.last_used_at) : null,
+            revokedAt: row?.revoked_at ? String(row.revoked_at) : null,
+            revokedByUserId: row?.revoked_by_user_id ? String(row.revoked_by_user_id) : null,
+            createdAt: String(row?.created_at || ''),
+            updatedAt: row?.updated_at ? String(row.updated_at) : null,
+        };
+    }
+    getActiveWorkspaceMemberForMcp(userId, workspaceId) {
+        const normalizedUserId = String(userId || '').trim();
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedUserId) {
+            throw new TaskforceRuleError('userId is required', 400, 'USER_ID_REQUIRED');
+        }
+        if (!normalizedWorkspaceId || normalizedWorkspaceId.toLowerCase() === 'default') {
+            throw new TaskforceRuleError('A non-default workspaceId is required', 400, 'WORKSPACE_ID_REQUIRED');
+        }
+        const row = this.db.prepare(`
+            SELECT
+                u.id AS user_id,
+                u.email,
+                u.display_name,
+                COALESCE(u.is_disabled, 0) AS is_disabled,
+                m.workspace_id,
+                COALESCE(m.role, 'member') AS role,
+                COALESCE(m.permission_mode, 'read-write') AS permission_mode,
+                COALESCE(m.status, 'active') AS membership_status
+            FROM workspace_memberships m
+            JOIN users u ON u.tenant_id = m.tenant_id AND u.id = m.user_id
+            WHERE m.tenant_id = ?
+              AND m.workspace_id = ?
+              AND m.user_id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedWorkspaceId, normalizedUserId);
+        if (!row?.user_id || !row.workspace_id || !row.email) {
+            throw new TaskforceRuleError('Workspace membership not found', 404, 'WORKSPACE_MEMBERSHIP_NOT_FOUND');
+        }
+        if (Boolean(row.is_disabled)) {
+            throw new TaskforceRuleError('User is disabled', 403, 'USER_DISABLED');
+        }
+        if (String(row.membership_status || 'active').toLowerCase() !== 'active') {
+            throw new TaskforceRuleError('Workspace membership is not active', 403, 'WORKSPACE_MEMBERSHIP_INACTIVE');
+        }
+        return {
+            userId: row.user_id,
+            workspaceId: row.workspace_id,
+            email: row.email,
+            displayName: row.display_name || null,
+            role: this.normalizeAccessRole(row.role || 'member', 'member'),
+            permissionMode: this.normalizePermissionMode(row.permission_mode, 'read-write'),
+            disabled: Boolean(row.is_disabled),
+        };
+    }
+    isMcpPrincipalActive(userId, workspaceId) {
+        try {
+            this.getActiveWorkspaceMemberForMcp(userId, workspaceId);
+        }
+        catch {
+            return false;
+        }
+        try {
+            const accountAccess = this.deps.getAccountAccessStatus(userId);
+            return accountAccess.canAccessApp;
+        }
+        catch {
+            return false;
+        }
+    }
+    getMcpAccessTokenRow(tokenId, workspaceId) {
+        const normalizedTokenId = String(tokenId || '').trim();
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedTokenId || !normalizedWorkspaceId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT
+                t.id,
+                t.workspace_id,
+                t.user_id,
+                u.email AS user_email,
+                t.name,
+                t.scopes_json,
+                t.token_prefix,
+                t.token_hash,
+                t.status,
+                t.last_used_at,
+                t.last_used_ip,
+                t.last_used_user_agent,
+                t.created_by_ip,
+                t.expires_at,
+                t.revoked_at,
+                t.revoked_by_user_id,
+                t.created_at,
+                t.updated_at
+            FROM mcp_access_tokens t
+            LEFT JOIN users u ON u.tenant_id = t.tenant_id AND u.id = t.user_id
+            WHERE t.tenant_id = ?
+              AND t.workspace_id = ?
+              AND t.id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedWorkspaceId, normalizedTokenId);
+        return row ? row : null;
+    }
+    resolveMcpAccessTokenStatus(row) {
+        const now = new Date().toISOString();
+        if (row.revoked_at || String(row.status || '').toLowerCase() === 'revoked')
+            return 'revoked';
+        if (row.expires_at && String(row.expires_at) < now)
+            return 'expired';
+        return 'active';
+    }
+    rowToMcpAccessTokenRecord(row) {
+        let scopes = [];
+        try {
+            const parsed = JSON.parse(String(row?.scopes_json || '[]'));
+            scopes = this.normalizeMcpAccessTokenScopes(parsed);
+        }
+        catch {
+            scopes = [];
+        }
+        return {
+            id: String(row.id || ''),
+            workspaceId: String(row.workspace_id || ''),
+            userId: String(row.user_id || ''),
+            userEmail: row.user_email ? String(row.user_email) : null,
+            name: String(row.name || ''),
+            scopes,
+            tokenPrefix: String(row.token_prefix || ''),
+            status: this.resolveMcpAccessTokenStatus(row),
+            lastUsedAt: row.last_used_at ? String(row.last_used_at) : null,
+            lastUsedIp: row.last_used_ip ? String(row.last_used_ip) : null,
+            lastUsedUserAgent: row.last_used_user_agent ? String(row.last_used_user_agent) : null,
+            createdByIp: row.created_by_ip ? String(row.created_by_ip) : null,
+            expiresAt: row.expires_at ? String(row.expires_at) : null,
+            revokedAt: row.revoked_at ? String(row.revoked_at) : null,
+            revokedByUserId: row.revoked_by_user_id ? String(row.revoked_by_user_id) : null,
+            createdAt: String(row.created_at || ''),
+            updatedAt: row.updated_at ? String(row.updated_at) : null,
+        };
+    }
+    assertCanManageOwnMcpAccessToken(actorUserId, token) {
+        const normalizedActorUserId = String(actorUserId || '').trim();
+        if (!normalizedActorUserId) {
+            throw new TaskforceRuleError('userId is required', 400, 'USER_ID_REQUIRED');
+        }
+        if (String(token.user_id || '').trim() !== normalizedActorUserId) {
+            throw new TaskforceRuleError('Forbidden', 403, 'FORBIDDEN');
+        }
+    }
+    countActiveMcpAccessTokens(userId, workspaceId) {
+        const now = new Date().toISOString();
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS token_count
+            FROM mcp_access_tokens
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND user_id = ?
+              AND status = 'active'
+              AND revoked_at IS NULL
+              AND (expires_at IS NULL OR expires_at >= ?)
+        `).get(this.tenantId, workspaceId, userId, now);
+        return Number(row?.token_count || 0);
+    }
+    // ─── Credential revocation (called from workspace/membership operations) ─
+    revokeMcpCredentialsForUserWorkspace(userId, workspaceId, revokedByUserId) {
+        const normalizedUserId = String(userId || '').trim();
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedUserId || !normalizedWorkspaceId)
+            return;
+        const now = new Date().toISOString();
+        const revokedBy = revokedByUserId ? String(revokedByUserId).trim() || null : null;
+        this.db.prepare(`
+            UPDATE mcp_access_tokens
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND user_id = ?
+              AND COALESCE(status, 'active') = 'active'
+        `).run(now, revokedBy, now, this.tenantId, normalizedWorkspaceId, normalizedUserId);
+        this.db.prepare(`
+            UPDATE mcp_oauth_connector_grants
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND user_id = ?
+              AND COALESCE(status, 'active') = 'active'
+        `).run(now, revokedBy, now, this.tenantId, normalizedWorkspaceId, normalizedUserId);
+    }
+    revokeMcpCredentialsForWorkspace(workspaceId, revokedByUserId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId)
+            return;
+        const now = new Date().toISOString();
+        const revokedBy = revokedByUserId ? String(revokedByUserId).trim() || null : null;
+        this.db.prepare(`
+            UPDATE mcp_access_tokens
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND COALESCE(status, 'active') = 'active'
+        `).run(now, revokedBy, now, this.tenantId, normalizedWorkspaceId);
+        this.db.prepare(`
+            UPDATE mcp_oauth_connector_grants
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND COALESCE(status, 'active') = 'active'
+        `).run(now, revokedBy, now, this.tenantId, normalizedWorkspaceId);
+    }
+    // ─── Public methods — MCP access tokens ──────────────────────────────────
+    listMcpAccessTokens(input) {
+        const member = this.getActiveWorkspaceMemberForMcp(input.userId, input.workspaceId);
+        const page = Math.max(1, Math.floor(Number(input.page) || 1));
+        const pageSize = Math.max(1, Math.min(MCP_ACCESS_TOKEN_MAX_PAGE_SIZE, Math.floor(Number(input.pageSize) || MCP_ACCESS_TOKEN_DEFAULT_PAGE_SIZE)));
+        const offset = (page - 1) * pageSize;
+        const totalRow = this.db.prepare(`
+            SELECT COUNT(*) AS total
+            FROM mcp_access_tokens
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND user_id = ?
+        `).get(this.tenantId, member.workspaceId, member.userId);
+        const rows = this.db.prepare(`
+            SELECT
+                t.id,
+                t.workspace_id,
+                t.user_id,
+                u.email AS user_email,
+                t.name,
+                t.scopes_json,
+                t.token_prefix,
+                t.token_hash,
+                t.status,
+                t.last_used_at,
+                t.last_used_ip,
+                t.last_used_user_agent,
+                t.created_by_ip,
+                t.expires_at,
+                t.revoked_at,
+                t.revoked_by_user_id,
+                t.created_at,
+                t.updated_at
+            FROM mcp_access_tokens t
+            LEFT JOIN users u ON u.tenant_id = t.tenant_id AND u.id = t.user_id
+            WHERE t.tenant_id = ?
+              AND t.workspace_id = ?
+              AND t.user_id = ?
+            ORDER BY t.created_at DESC
+            LIMIT ? OFFSET ?
+        `).all(this.tenantId, member.workspaceId, member.userId, pageSize, offset);
+        return {
+            items: rows.map((row) => this.rowToMcpAccessTokenRecord(row)),
+            total: Number(totalRow?.total || 0),
+            page,
+            pageSize,
+        };
+    }
+    createMcpAccessToken(input) {
+        const member = this.getActiveWorkspaceMemberForMcp(input.userId, input.workspaceId);
+        const name = String(input.name || '').trim();
+        if (!name) {
+            throw new TaskforceRuleError('Token name is required', 400, 'MCP_TOKEN_NAME_REQUIRED');
+        }
+        const scopes = this.normalizeMcpAccessTokenScopes(input.scopes);
+        const expiresAt = input.expiresAt ? String(input.expiresAt).trim() : null;
+        const now = new Date().toISOString();
+        if (expiresAt && expiresAt <= now) {
+            throw new TaskforceRuleError('expiresAt must be in the future', 400, 'MCP_TOKEN_EXPIRY_INVALID');
+        }
+        if (this.countActiveMcpAccessTokens(member.userId, member.workspaceId) >= MCP_ACCESS_TOKEN_MAX_ACTIVE_PER_USER_WORKSPACE) {
+            throw new TaskforceRuleError(`Maximum ${MCP_ACCESS_TOKEN_MAX_ACTIVE_PER_USER_WORKSPACE} active MCP tokens allowed per user per workspace`, 400, 'MCP_TOKEN_LIMIT_REACHED');
+        }
+        const tokenId = this.generateEntityId('mcp-token');
+        let tokenPrefix = this.createMcpAccessTokenPrefix();
+        while (this.db.prepare(`
+            SELECT 1 FROM mcp_access_tokens WHERE tenant_id = ? AND token_prefix = ? LIMIT 1
+        `).get(this.tenantId, tokenPrefix)) {
+            tokenPrefix = this.createMcpAccessTokenPrefix();
+        }
+        const secret = randomBytes(32).toString('base64url');
+        const token = `${tokenPrefix}_${secret}`;
+        const tokenHash = hashMcpAccessTokenSecret(secret);
+        const createdByIp = input.createdByIp ? String(input.createdByIp).trim() : null;
+        this.db.prepare(`
+            INSERT INTO mcp_access_tokens (
+                id, tenant_id, workspace_id, user_id, name, scopes_json, token_prefix, token_hash, status,
+                last_used_at, last_used_ip, last_used_user_agent, created_by_ip, expires_at, revoked_at,
+                revoked_by_user_id, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?, NULL, NULL, ?, ?)
+        `).run(tokenId, this.tenantId, member.workspaceId, member.userId, name, JSON.stringify(scopes), tokenPrefix, tokenHash, createdByIp, expiresAt, now, now);
+        const row = this.getMcpAccessTokenRow(tokenId, member.workspaceId);
+        if (!row) {
+            throw new TaskforceRuleError('Failed to create MCP token', 500, 'MCP_TOKEN_CREATE_FAILED');
+        }
+        return {
+            token,
+            record: this.rowToMcpAccessTokenRecord(row),
+        };
+    }
+    revokeMcpAccessToken(input) {
+        this.getActiveWorkspaceMemberForMcp(input.actorUserId, input.workspaceId);
+        const row = this.getMcpAccessTokenRow(input.tokenId, input.workspaceId);
+        if (!row) {
+            throw new TaskforceRuleError('MCP token not found', 404, 'MCP_TOKEN_NOT_FOUND');
+        }
+        this.assertCanManageOwnMcpAccessToken(input.actorUserId, row);
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mcp_access_tokens
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ? AND id = ?
+        `).run(now, input.actorUserId, now, this.tenantId, row.id);
+        const updated = this.getMcpAccessTokenRow(row.id, input.workspaceId);
+        if (!updated) {
+            throw new TaskforceRuleError('MCP token not found', 404, 'MCP_TOKEN_NOT_FOUND');
+        }
+        return this.rowToMcpAccessTokenRecord(updated);
+    }
+    regenerateMcpAccessToken(input) {
+        this.getActiveWorkspaceMemberForMcp(input.actorUserId, input.workspaceId);
+        const existing = this.getMcpAccessTokenRow(input.tokenId, input.workspaceId);
+        if (!existing) {
+            throw new TaskforceRuleError('MCP token not found', 404, 'MCP_TOKEN_NOT_FOUND');
+        }
+        this.assertCanManageOwnMcpAccessToken(input.actorUserId, existing);
+        const tx = this.db.transaction(() => {
+            const revoked = this.revokeMcpAccessToken({
+                actorUserId: input.actorUserId,
+                workspaceId: input.workspaceId,
+                tokenId: input.tokenId,
+            });
+            return this.createMcpAccessToken({
+                userId: revoked.userId,
+                workspaceId: revoked.workspaceId,
+                name: revoked.name,
+                scopes: revoked.scopes,
+                expiresAt: revoked.expiresAt || null,
+                createdByIp: input.createdByIp || null,
+            });
+        });
+        return tx();
+    }
+    authenticateMcpAccessToken(token, workspaceId) {
+        const parsed = this.parseMcpAccessToken(token);
+        if (!parsed)
+            return null;
+        const row = this.db.prepare(`
+            SELECT id, workspace_id, user_id, scopes_json, token_hash, status, expires_at, revoked_at
+            FROM mcp_access_tokens
+            WHERE tenant_id = ?
+              AND token_prefix = ?
+            LIMIT 1
+        `).get(this.tenantId, parsed.tokenPrefix);
+        if (!row?.id || !row.workspace_id || !row.user_id || !row.token_hash)
+            return null;
+        if (workspaceId && String(workspaceId).trim() && String(row.workspace_id).trim() !== String(workspaceId).trim()) {
+            return null;
+        }
+        if (!verifyMcpAccessTokenSecret(parsed.secret, row.token_hash))
+            return null;
+        if (!this.isMcpPrincipalActive(row.user_id, row.workspace_id))
+            return null;
+        const status = this.resolveMcpAccessTokenStatus(row);
+        let scopes = [];
+        try {
+            scopes = this.normalizeMcpAccessTokenScopes(JSON.parse(String(row.scopes_json || '[]')));
+        }
+        catch {
+            return null;
+        }
+        return {
+            tokenId: row.id,
+            workspaceId: row.workspace_id,
+            userId: row.user_id,
+            scopes,
+            status,
+        };
+    }
+    inspectMcpAccessToken(token) {
+        const parsed = this.parseMcpAccessToken(token);
+        if (!parsed)
+            return null;
+        const row = this.db.prepare(`
+            SELECT id, workspace_id, user_id, name, scopes_json, token_hash, status, expires_at, revoked_at
+            FROM mcp_access_tokens
+            WHERE tenant_id = ?
+              AND token_prefix = ?
+            LIMIT 1
+        `).get(this.tenantId, parsed.tokenPrefix);
+        if (!row?.id || !row.workspace_id || !row.user_id || !row.token_hash)
+            return null;
+        if (!verifyMcpAccessTokenSecret(parsed.secret, row.token_hash))
+            return null;
+        let scopes = [];
+        try {
+            scopes = this.normalizeMcpAccessTokenScopes(JSON.parse(String(row.scopes_json || '[]')));
+        }
+        catch {
+            return null;
+        }
+        return {
+            tokenId: row.id,
+            tokenPrefix: parsed.tokenPrefix,
+            workspaceId: row.workspace_id,
+            userId: row.user_id,
+            name: String(row.name || ''),
+            scopes,
+            status: this.resolveMcpAccessTokenStatus(row),
+        };
+    }
+    recordMcpAccessTokenUsage(input) {
+        const tokenId = String(input.tokenId || '').trim();
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (!tokenId || !workspaceId)
+            return false;
+        const now = new Date().toISOString();
+        const result = this.db.prepare(`
+            UPDATE mcp_access_tokens
+            SET last_used_at = ?,
+                last_used_ip = ?,
+                last_used_user_agent = ?,
+                updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `).run(now, input.ip ? String(input.ip).trim() : null, input.userAgent ? String(input.userAgent).trim() : null, now, this.tenantId, workspaceId, tokenId);
+        return Number(result?.changes || 0) > 0;
+    }
+    // ─── Public methods — MCP OAuth ───────────────────────────────────────────
+    registerMcpOAuthClient(input) {
+        const provider = this.normalizeMcpOAuthProvider(input.provider);
+        const clientName = String(input.clientName || '').trim() || this.defaultMcpOAuthClientName(provider);
+        const redirectUris = this.normalizeRedirectUris(input.redirectUris);
+        const now = new Date().toISOString();
+        const clientId = this.generateEntityId(`mcp-oauth-client-${provider}`);
+        this.db.prepare(`
+            INSERT INTO mcp_oauth_clients (
+                id, tenant_id, provider, client_name, redirect_uris_json, status, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, 'active', ?, ?)
+        `).run(clientId, this.tenantId, provider, clientName, JSON.stringify(redirectUris), now, now);
+        const row = this.getMcpOAuthClientRow(clientId, provider);
+        if (!row) {
+            throw new TaskforceRuleError('Failed to register MCP OAuth client', 500, 'MCP_OAUTH_CLIENT_CREATE_FAILED');
+        }
+        return this.rowToMcpOAuthClientRecord(row);
+    }
+    getMcpOAuthClient(clientId, provider) {
+        const normalizedProvider = provider ? this.normalizeMcpOAuthProvider(provider) : undefined;
+        const row = this.getMcpOAuthClientRow(clientId, normalizedProvider);
+        return row ? this.rowToMcpOAuthClientRecord(row) : null;
+    }
+    issueMcpOAuthAuthorizationCode(input) {
+        const provider = this.normalizeMcpOAuthProvider(input.provider);
+        const client = this.getMcpOAuthClientRow(input.clientId, provider);
+        if (!client) {
+            throw new TaskforceRuleError('OAuth client not found', 404, 'MCP_OAUTH_CLIENT_NOT_FOUND');
+        }
+        if (String(client.status || '').trim().toLowerCase() === 'revoked') {
+            throw new TaskforceRuleError('OAuth client is revoked', 403, 'MCP_OAUTH_CLIENT_REVOKED');
+        }
+        const member = this.getActiveWorkspaceMemberForMcp(input.userId, input.workspaceId);
+        const redirectUri = String(input.redirectUri || '').trim();
+        const redirectUris = this.rowToMcpOAuthClientRecord(client).redirectUris;
+        if (!redirectUri || !redirectUris.includes(redirectUri)) {
+            throw new TaskforceRuleError('Redirect URI is not registered for this OAuth client', 400, 'MCP_OAUTH_REDIRECT_URI_INVALID');
+        }
+        const scopes = this.normalizeMcpAccessTokenScopes(input.scopes);
+        const codeChallenge = String(input.codeChallenge || '').trim();
+        if (!codeChallenge) {
+            throw new TaskforceRuleError('PKCE code challenge is required', 400, 'MCP_OAUTH_CODE_CHALLENGE_REQUIRED');
+        }
+        const codeChallengeMethod = this.normalizePkceMethod(input.codeChallengeMethod);
+        const codeId = this.generateEntityId(`mcp-oauth-code-${provider}`);
+        let codePrefix = this.createMcpOAuthCodePrefix();
+        while (this.db.prepare(`
+            SELECT 1 FROM mcp_oauth_auth_codes WHERE tenant_id = ? AND code_prefix = ? LIMIT 1
+        `).get(this.tenantId, codePrefix)) {
+            codePrefix = this.createMcpOAuthCodePrefix();
+        }
+        const secret = randomBytes(32).toString('base64url');
+        const code = `${codePrefix}_${secret}`;
+        const codeHash = hashMcpOAuthSecret(secret);
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + MCP_OAUTH_AUTH_CODE_TTL_MS).toISOString();
+        this.db.prepare(`
+            INSERT INTO mcp_oauth_auth_codes (
+                id, tenant_id, provider, client_id, user_id, workspace_id, redirect_uri, scopes_json,
+                code_prefix, code_hash, code_challenge, code_challenge_method, expires_at, used_at, created_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)
+        `).run(codeId, this.tenantId, provider, String(client.id || ''), member.userId, member.workspaceId, redirectUri, JSON.stringify(scopes), codePrefix, codeHash, codeChallenge, codeChallengeMethod, expiresAt, now.toISOString());
+        return { code, expiresAt };
+    }
+    exchangeMcpOAuthAuthorizationCode(input) {
+        const provider = this.normalizeMcpOAuthProvider(input.provider);
+        const client = this.getMcpOAuthClientRow(input.clientId, provider);
+        if (!client) {
+            throw new TaskforceRuleError('OAuth client not found', 404, 'MCP_OAUTH_CLIENT_NOT_FOUND');
+        }
+        const parsed = this.parseMcpOAuthOpaqueSecret(input.code, 'tfmcpoauthcode_');
+        if (!parsed) {
+            throw new TaskforceRuleError('Invalid authorization code', 400, 'MCP_OAUTH_CODE_INVALID');
+        }
+        const row = this.db.prepare(`
+            SELECT id, client_id, user_id, workspace_id, redirect_uri, scopes_json, code_hash, code_challenge, code_challenge_method, expires_at, used_at
+            FROM mcp_oauth_auth_codes
+            WHERE tenant_id = ? AND provider = ? AND code_prefix = ?
+            LIMIT 1
+        `).get(this.tenantId, provider, parsed.tokenPrefix);
+        if (!row?.id || !row.client_id || !row.user_id || !row.workspace_id || !row.code_hash) {
+            throw new TaskforceRuleError('Invalid authorization code', 400, 'MCP_OAUTH_CODE_INVALID');
+        }
+        if (String(row.client_id) !== String(client.id)) {
+            throw new TaskforceRuleError('OAuth client mismatch', 400, 'MCP_OAUTH_CLIENT_MISMATCH');
+        }
+        if (row.used_at) {
+            throw new TaskforceRuleError('Authorization code already used', 400, 'MCP_OAUTH_CODE_ALREADY_USED');
+        }
+        const now = new Date().toISOString();
+        if (!row.expires_at || String(row.expires_at) < now) {
+            throw new TaskforceRuleError('Authorization code expired', 400, 'MCP_OAUTH_CODE_EXPIRED');
+        }
+        if (String(row.redirect_uri || '').trim() !== String(input.redirectUri || '').trim()) {
+            throw new TaskforceRuleError('Redirect URI mismatch', 400, 'MCP_OAUTH_REDIRECT_URI_INVALID');
+        }
+        if (!verifyMcpOAuthSecret(parsed.secret, String(row.code_hash))) {
+            throw new TaskforceRuleError('Invalid authorization code', 400, 'MCP_OAUTH_CODE_INVALID');
+        }
+        const codeVerifier = String(input.codeVerifier || '').trim();
+        if (!codeVerifier) {
+            throw new TaskforceRuleError('PKCE code verifier is required', 400, 'MCP_OAUTH_CODE_VERIFIER_REQUIRED');
+        }
+        const derivedChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+        if (String(row.code_challenge_method || 'S256').trim().toUpperCase() !== 'S256' || derivedChallenge !== String(row.code_challenge || '')) {
+            throw new TaskforceRuleError('PKCE verification failed', 400, 'MCP_OAUTH_PKCE_VERIFICATION_FAILED');
+        }
+        let scopes = [];
+        try {
+            scopes = this.normalizeMcpAccessTokenScopes(JSON.parse(String(row.scopes_json || '[]')));
+        }
+        catch {
+            throw new TaskforceRuleError('Authorization code scopes are invalid', 400, 'MCP_OAUTH_SCOPE_INVALID');
+        }
+        const clientName = String(client.client_name || this.defaultMcpOAuthClientName(provider)).trim() || this.defaultMcpOAuthClientName(provider);
+        const tx = this.db.transaction(() => {
+            const existingRows = this.db.prepare(`
+                SELECT id
+                FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ?
+                  AND provider = ?
+                  AND user_id = ?
+                  AND workspace_id = ?
+                  AND status = 'active'
+            `).all(this.tenantId, provider, String(row.user_id), String(row.workspace_id));
+            const revokeTime = new Date().toISOString();
+            existingRows.forEach((existing) => {
+                if (!existing?.id)
+                    return;
+                this.db.prepare(`
+                    UPDATE mcp_oauth_connector_grants
+                    SET status = 'revoked',
+                        revoked_at = COALESCE(revoked_at, ?),
+                        revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                        updated_at = ?
+                    WHERE tenant_id = ? AND id = ?
+                `).run(revokeTime, String(row.user_id), revokeTime, this.tenantId, String(existing.id));
+            });
+            const grantId = this.generateEntityId(`mcp-oauth-grant-${provider}`);
+            let tokenPrefix = this.createMcpOAuthAccessTokenPrefix();
+            while (this.db.prepare(`
+                SELECT 1 FROM mcp_oauth_connector_grants WHERE tenant_id = ? AND token_prefix = ? LIMIT 1
+            `).get(this.tenantId, tokenPrefix)) {
+                tokenPrefix = this.createMcpOAuthAccessTokenPrefix();
+            }
+            const secret = randomBytes(32).toString('base64url');
+            const accessToken = `${tokenPrefix}_${secret}`;
+            const tokenHash = hashMcpOAuthSecret(secret);
+            this.db.prepare(`
+                INSERT INTO mcp_oauth_connector_grants (
+                    id, tenant_id, provider, client_id, client_name, user_id, workspace_id, scopes_json,
+                    token_prefix, token_hash, status, last_used_at, revoked_at, revoked_by_user_id, created_at, updated_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?)
+            `).run(grantId, this.tenantId, provider, String(client.id || ''), clientName, String(row.user_id), String(row.workspace_id), JSON.stringify(scopes), tokenPrefix, tokenHash, now, now);
+            this.db.prepare(`
+                UPDATE mcp_oauth_auth_codes
+                SET used_at = ?
+                WHERE tenant_id = ? AND id = ?
+            `).run(now, this.tenantId, String(row.id));
+            const grantRow = this.db.prepare(`
+                SELECT *
+                FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ? AND id = ?
+                LIMIT 1
+            `).get(this.tenantId, grantId);
+            if (!grantRow) {
+                throw new TaskforceRuleError('Failed to create OAuth connector grant', 500, 'MCP_OAUTH_GRANT_CREATE_FAILED');
+            }
+            return {
+                accessToken,
+                grant: this.rowToMcpOAuthConnectorGrantRecord(grantRow),
+            };
+        });
+        const result = tx();
+        return {
+            accessToken: result.accessToken,
+            tokenType: 'Bearer',
+            scopes,
+            grant: result.grant,
+        };
+    }
+    listMcpOAuthConnectorGrants(input) {
+        const member = this.getActiveWorkspaceMemberForMcp(input.userId, input.workspaceId);
+        const provider = input.provider ? this.normalizeMcpOAuthProvider(input.provider) : null;
+        const rows = provider
+            ? this.db.prepare(`
+                SELECT *
+                FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ?
+                  AND workspace_id = ?
+                  AND user_id = ?
+                  AND provider = ?
+                ORDER BY created_at DESC
+            `).all(this.tenantId, member.workspaceId, member.userId, provider)
+            : this.db.prepare(`
+                SELECT *
+                FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ?
+                  AND workspace_id = ?
+                  AND user_id = ?
+                ORDER BY created_at DESC
+            `).all(this.tenantId, member.workspaceId, member.userId);
+        return rows.map((row) => this.rowToMcpOAuthConnectorGrantRecord(row));
+    }
+    revokeMcpOAuthConnectorGrant(input) {
+        const member = this.getActiveWorkspaceMemberForMcp(input.actorUserId, input.workspaceId);
+        const row = this.db.prepare(`
+            SELECT *
+            FROM mcp_oauth_connector_grants
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, member.workspaceId, String(input.grantId || '').trim());
+        if (!row?.id) {
+            throw new TaskforceRuleError('MCP connector grant not found', 404, 'MCP_OAUTH_GRANT_NOT_FOUND');
+        }
+        if (String(row.user_id || '').trim() !== member.userId) {
+            throw new TaskforceRuleError('Forbidden', 403, 'FORBIDDEN');
+        }
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mcp_oauth_connector_grants
+            SET status = 'revoked',
+                revoked_at = COALESCE(revoked_at, ?),
+                revoked_by_user_id = COALESCE(revoked_by_user_id, ?),
+                updated_at = ?
+            WHERE tenant_id = ? AND id = ?
+        `).run(now, member.userId, now, this.tenantId, String(row.id));
+        const updated = this.db.prepare(`
+            SELECT *
+            FROM mcp_oauth_connector_grants
+            WHERE tenant_id = ? AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, String(row.id));
+        if (!updated) {
+            throw new TaskforceRuleError('MCP connector grant not found', 404, 'MCP_OAUTH_GRANT_NOT_FOUND');
+        }
+        return this.rowToMcpOAuthConnectorGrantRecord(updated);
+    }
+    authenticateMcpOAuthAccessToken(token, workspaceId) {
+        const parsed = this.parseMcpOAuthOpaqueSecret(token, 'tfmcpoauth_');
+        if (!parsed)
+            return null;
+        const row = this.db.prepare(`
+            SELECT id, provider, client_id, user_id, workspace_id, scopes_json, token_hash, status, revoked_at
+            FROM mcp_oauth_connector_grants
+            WHERE tenant_id = ?
+              AND token_prefix = ?
+            LIMIT 1
+        `).get(this.tenantId, parsed.tokenPrefix);
+        if (!row?.id || !row?.workspace_id || !row?.user_id || !row?.client_id || !row?.token_hash)
+            return null;
+        if (workspaceId && String(workspaceId).trim() && String(row.workspace_id).trim() !== String(workspaceId).trim()) {
+            return null;
+        }
+        if (!verifyMcpOAuthSecret(parsed.secret, String(row.token_hash)))
+            return null;
+        if (!this.isMcpPrincipalActive(String(row.user_id), String(row.workspace_id)))
+            return null;
+        let scopes = [];
+        try {
+            scopes = this.normalizeMcpAccessTokenScopes(JSON.parse(String(row.scopes_json || '[]')));
+        }
+        catch {
+            return null;
+        }
+        return {
+            grantId: String(row.id),
+            workspaceId: String(row.workspace_id),
+            userId: String(row.user_id),
+            clientId: String(row.client_id),
+            provider: this.normalizeMcpOAuthProvider(row.provider),
+            scopes,
+            status: this.resolveMcpOAuthGrantStatus(row),
+        };
+    }
+    recordMcpOAuthConnectorGrantUsage(input) {
+        const grantId = String(input.grantId || '').trim();
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (!grantId || !workspaceId)
+            return false;
+        const now = new Date().toISOString();
+        const result = this.db.prepare(`
+            UPDATE mcp_oauth_connector_grants
+            SET last_used_at = ?,
+                updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `).run(now, now, this.tenantId, workspaceId, grantId);
+        return Number(result?.changes || 0) > 0;
+    }
+}