@vantageos/vantage-crm-mcp 0.1.0

package/dist/convex/lib/auth.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * Authentication & Authorization Utilities
+ *
+ * Provides helper functions for:
+ * - Getting authenticated user IDs (Clerk integration)
+ * - Checking user roles and enforcing admin-only access
+ * - Resource ownership validation
+ *
+ * Usage:
+ *   // Get Clerk user ID
+ *   const userId = await getAuthUserId(ctx);
+ *
+ *   // Require admin access
+ *   const user = await requireAdmin(ctx);
+ *
+ *   // In actions: require any logged-in user (Design Studio, etc.)
+ *   const identity = await requireUser(ctx);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIsAdmin = void 0;
+exports.getAuthUserId = getAuthUserId;
+exports.getAuthUserIdOptional = getAuthUserIdOptional;
+exports.assertUserOwnsResource = assertUserOwnsResource;
+exports.getUserMetadata = getUserMetadata;
+exports.getCurrentUser = getCurrentUser;
+exports.requireAuth = requireAuth;
+exports.isAdmin = isAdmin;
+exports.requireAdmin = requireAdmin;
+exports.getOrCreateUser = getOrCreateUser;
+exports.getOrCreateOrganization = getOrCreateOrganization;
+exports.getOrCreateMembership = getOrCreateMembership;
+exports.requireUser = requireUser;
+exports.requireAdminInAction = requireAdminInAction;
+exports.getOrgId = getOrgId;
+exports.getEntityId = getEntityId;
+exports.isInOrganization = isInOrganization;
+exports.requireOrganization = requireOrganization;
+exports.getWorkspaceContext = getWorkspaceContext;
+const values_1 = require("convex/values");
+const server_1 = require("../_generated/server");
+const { internal } = require('../_generated/api');
+// ============================================================================
+// EXISTING FUNCTIONS (Clerk user ID helpers)
+// ============================================================================
+/**
+ * Get the authenticated user's Clerk ID
+ * Throws error if not authenticated
+ */
+async function getAuthUserId(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        throw new Error('Unauthenticated - user must be logged in');
+    }
+    return identity.subject; // Clerk user ID
+}
+/**
+ * Get the authenticated user's Clerk ID or null if not authenticated
+ */
+async function getAuthUserIdOptional(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    return identity?.subject ?? null;
+}
+/**
+ * Check if the current user owns a resource
+ */
+async function assertUserOwnsResource(ctx, resourceUserId) {
+    const userId = await getAuthUserId(ctx);
+    if (userId !== resourceUserId) {
+        throw new Error("Unauthorized - you don't own this resource");
+    }
+}
+/**
+ * Get user metadata from Clerk
+ */
+async function getUserMetadata(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        return null;
+    }
+    return {
+        userId: identity.subject,
+        email: identity.email,
+        name: identity.name,
+        imageUrl: identity.pictureUrl,
+    };
+}
+// ============================================================================
+// NEW FUNCTIONS (Role-based access control)
+// ============================================================================
+/**
+ * Get the current authenticated user from the users table
+ * Returns null if not authenticated or user not found
+ */
+async function getCurrentUser(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        return null;
+    }
+    const user = await ctx.db
+        .query('users')
+        .withIndex('by_token', (q) => q.eq('tokenIdentifier', identity.tokenIdentifier))
+        .first();
+    return user;
+}
+/**
+ * Require authentication - throws if user not logged in
+ * Returns the user object
+ */
+async function requireAuth(ctx) {
+    const user = await getCurrentUser(ctx);
+    if (!user) {
+        throw new Error('Unauthorized: Authentication required');
+    }
+    return user;
+}
+/**
+ * Check if the current user is an admin
+ * Returns true if admin, false otherwise
+ */
+async function isAdmin(ctx) {
+    const user = await getCurrentUser(ctx);
+    return user?.role === 'admin';
+}
+/**
+ * Require admin access - throws if user is not an admin
+ * Returns the user object
+ */
+async function requireAdmin(ctx) {
+    const user = await requireAuth(ctx);
+    if (user.role !== 'admin') {
+        throw new Error('Forbidden: Admin access required');
+    }
+    return user;
+}
+/**
+ * Get or create user record in the database
+ * Called automatically after Clerk authentication
+ *
+ * This ensures every authenticated user has a record in our users table
+ * with a default "user" role. Admins must be promoted manually.
+ */
+async function getOrCreateUser(ctx, clerkId, tokenIdentifier, email, name, avatarUrl) {
+    // Check if user already exists by Clerk ID first
+    let existingUser = await ctx.db
+        .query('users')
+        .withIndex('by_clerk_id', (q) => q.eq('clerkId', clerkId))
+        .first();
+    // Fallback to token identifier for backwards compatibility
+    if (!existingUser) {
+        existingUser = await ctx.db
+            .query('users')
+            .withIndex('by_token', (q) => q.eq('tokenIdentifier', tokenIdentifier))
+            .first();
+    }
+    if (existingUser) {
+        // Update user if data changed
+        const updates = {};
+        if (existingUser.email !== email)
+            updates.email = email;
+        if (existingUser.name !== name && name)
+            updates.name = name;
+        if (existingUser.avatarUrl !== avatarUrl && avatarUrl)
+            updates.avatarUrl = avatarUrl;
+        if (!existingUser.clerkId)
+            updates.clerkId = clerkId;
+        if (Object.keys(updates).length > 0) {
+            updates.updatedAt = Date.now();
+            await ctx.db.patch(existingUser._id, updates);
+            return await ctx.db.get(existingUser._id);
+        }
+        return existingUser;
+    }
+    // Create new user with default "user" role
+    const userId = await ctx.db.insert('users', {
+        clerkId,
+        tokenIdentifier,
+        email,
+        name,
+        avatarUrl,
+        role: 'user',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+    return await ctx.db.get(userId);
+}
+/**
+ * Get or create organization record in the database
+ * Called when user accesses an organization context
+ */
+async function getOrCreateOrganization(ctx, clerkOrgId, name, slug, imageUrl) {
+    // Check if org already exists
+    const existingOrg = await ctx.db
+        .query('organizations')
+        .withIndex('by_clerk_id', (q) => q.eq('clerkId', clerkOrgId))
+        .first();
+    if (existingOrg) {
+        // Update org if data changed
+        const updates = {};
+        if (existingOrg.name !== name)
+            updates.name = name;
+        if (existingOrg.slug !== slug && slug)
+            updates.slug = slug;
+        if (existingOrg.imageUrl !== imageUrl && imageUrl)
+            updates.imageUrl = imageUrl;
+        if (Object.keys(updates).length > 0) {
+            updates.updatedAt = Date.now();
+            await ctx.db.patch(existingOrg._id, updates);
+            return await ctx.db.get(existingOrg._id);
+        }
+        return existingOrg;
+    }
+    // Create new organization
+    const orgId = await ctx.db.insert('organizations', {
+        clerkId: clerkOrgId,
+        name,
+        slug,
+        imageUrl,
+        plan: 'free',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+    return await ctx.db.get(orgId);
+}
+/**
+ * Get or create membership record
+ * Links a user to an organization
+ */
+async function getOrCreateMembership(ctx, userId, orgId, clerkUserId, clerkOrgId, role) {
+    // Check if membership already exists
+    const existingMembership = await ctx.db
+        .query('memberships')
+        .withIndex('by_user_org', (q) => q.eq('userId', userId).eq('orgId', orgId))
+        .first();
+    if (existingMembership) {
+        // Update role if changed
+        if (existingMembership.role !== role) {
+            await ctx.db.patch(existingMembership._id, {
+                role,
+                updatedAt: Date.now(),
+            });
+            return await ctx.db.get(existingMembership._id);
+        }
+        return existingMembership;
+    }
+    // Create new membership
+    const membershipId = await ctx.db.insert('memberships', {
+        userId,
+        orgId,
+        clerkUserId,
+        clerkOrgId,
+        role,
+        joinedAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+    return await ctx.db.get(membershipId);
+}
+/**
+ * Require authenticated user in actions - throws if not logged in.
+ * Returns Clerk identity (subject, tokenIdentifier, etc.) for use in Design Studio and other actions.
+ *
+ * Usage in actions:
+ *   const identity = await requireUser(ctx);
+ *   const userId = identity.subject;
+ */
+async function requireUser(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        throw new Error('Unauthorized: Authentication required');
+    }
+    return identity;
+}
+/**
+ * Require admin access in actions - throws if user is not an admin
+ *
+ * Since actions don't have direct database access, this function
+ * calls a mutation to check the user's role.
+ *
+ * Usage in actions:
+ *   await requireAdminInAction(ctx);
+ */
+async function requireAdminInAction(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        throw new Error('Unauthorized: Authentication required');
+    }
+    // Call a mutation to check the user's role
+    const isUserAdmin = await ctx.runMutation(internal.lib.auth.checkIsAdmin, {
+        tokenIdentifier: identity.tokenIdentifier,
+    });
+    if (!isUserAdmin) {
+        throw new Error('Forbidden: Admin access required');
+    }
+}
+/**
+ * Internal mutation to check if a user is an admin
+ * Used by requireAdminInAction
+ */
+exports.checkIsAdmin = (0, server_1.internalMutation)({
+    args: { tokenIdentifier: values_1.v.string() },
+    handler: async (ctx, { tokenIdentifier }) => {
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_token', (q) => q.eq('tokenIdentifier', tokenIdentifier))
+            .first();
+        return user?.role === 'admin';
+    },
+});
+// ============================================================================
+// MULTI-TENANCY FUNCTIONS (Organization support)
+// ============================================================================
+/**
+ * Get the current organization ID from Clerk token
+ * Returns null if user is in personal workspace
+ */
+async function getOrgId(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity)
+        return null;
+    // Clerk Organizations puts org_id in the token claims when org is active
+    return identity.org_id ?? null;
+}
+/**
+ * Get the entityId for Composio API calls
+ * Returns orgId if in organization, userId if in personal workspace
+ *
+ * This is the key function for multi-tenancy:
+ * - Personal workspace: entityId = userId (tools belong to user)
+ * - Team workspace: entityId = orgId (tools shared with team)
+ */
+async function getEntityId(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity)
+        throw new Error('Unauthenticated');
+    const orgId = identity.org_id;
+    return orgId ?? identity.subject; // orgId if in org, else userId
+}
+/**
+ * Check if current user is in an organization context
+ */
+async function isInOrganization(ctx) {
+    const orgId = await getOrgId(ctx);
+    return orgId !== null;
+}
+/**
+ * Require organization context - throws if in personal workspace
+ * Use this for team-only features
+ */
+async function requireOrganization(ctx) {
+    const orgId = await getOrgId(ctx);
+    if (!orgId) {
+        throw new Error('This action requires an organization context');
+    }
+    return orgId;
+}
+/**
+ * Get workspace context for queries
+ * Returns filter criteria based on current workspace
+ */
+async function getWorkspaceContext(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity)
+        throw new Error('Unauthenticated');
+    const userId = identity.subject;
+    const orgId = identity.org_id ?? null;
+    return {
+        userId,
+        orgId,
+        entityId: orgId ?? userId,
+        isPersonal: orgId === null,
+    };
+}

package/dist/convex/lib/rbac.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * convex/lib/rbac.ts
+ *
+ * 4-tier RBAC: vantage-crm:read / write / admin / cloud-admin
+ * requireScope enforces scope at function entry — wraps subscriptions check.
+ * D-003: field-level RBAC is handled at query time via custom_field_definitions.visibility.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §5 D-003 / D-010
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopeSatisfies = scopeSatisfies;
+exports.roleToScope = roleToScope;
+exports.requireScope = requireScope;
+exports.requireScopeFromScopes = requireScopeFromScopes;
+exports.assertAdminScope = assertAdminScope;
+exports.canViewField = canViewField;
+exports.checkSubscriptionScope = checkSubscriptionScope;
+const SCOPE_HIERARCHY = [
+    'vantage-crm:read',
+    'vantage-crm:write',
+    'vantage-crm:admin',
+    'vantage-crm:cloud-admin',
+];
+function scopeLevel(scope) {
+    return SCOPE_HIERARCHY.indexOf(scope);
+}
+/**
+ * Returns true if `grantedScope` satisfies `requiredScope`.
+ * Higher-tier scopes include all lower-tier permissions.
+ */
+function scopeSatisfies(grantedScope, requiredScope) {
+    return scopeLevel(grantedScope) >= scopeLevel(requiredScope);
+}
+// ---------------------------------------------------------------------------
+// Workspace-role → default CRM scope mapping
+// Used when no OAuth token is present (direct Clerk auth).
+// ---------------------------------------------------------------------------
+const ROLE_TO_SCOPE = {
+    owner: 'vantage-crm:admin',
+    admin: 'vantage-crm:admin',
+    editor: 'vantage-crm:write',
+    viewer: 'vantage-crm:read',
+};
+/**
+ * Returns the CRM scope implied by a workspace member role.
+ */
+function roleToScope(role) {
+    return ROLE_TO_SCOPE[role] ?? 'vantage-crm:read';
+}
+// ---------------------------------------------------------------------------
+// requireScope — core RBAC gate
+//
+// Checks that the caller's workspace role (or OAuth scopes) satisfies
+// the required scope level. Throws if not.
+//
+// Usage:
+//   const { role } = await validateWorkspaceAccess(ctx, workspaceId);
+//   await requireScope(ctx, 'vantage-crm:admin', role);
+// ---------------------------------------------------------------------------
+async function requireScope(_ctx, requiredScope, callerRole) {
+    const callerScope = roleToScope(callerRole);
+    if (!scopeSatisfies(callerScope, requiredScope)) {
+        throw new Error(`Insufficient scope: required ${requiredScope}, caller has ${callerScope} (role: ${callerRole})`);
+    }
+}
+// ---------------------------------------------------------------------------
+// requireScopeFromScopes — for OAuth token paths
+// Takes the raw scopes array from validateAccessToken result.
+// ---------------------------------------------------------------------------
+function requireScopeFromScopes(scopes, requiredScope) {
+    const hasSufficient = scopes.some((s) => {
+        const sScope = s;
+        if (!SCOPE_HIERARCHY.includes(sScope))
+            return false;
+        return scopeSatisfies(sScope, requiredScope);
+    });
+    if (!hasSufficient) {
+        throw new Error(`Insufficient OAuth scope: required ${requiredScope}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// assertAdminScope — shorthand for admin-only operations (hard delete, etc.)
+// ---------------------------------------------------------------------------
+async function assertAdminScope(ctx, callerRole) {
+    await requireScope(ctx, 'vantage-crm:admin', callerRole);
+}
+// ---------------------------------------------------------------------------
+// canViewField — D-003 field-level RBAC
+// Returns true if the caller role can see a field with the given visibility setting.
+// ---------------------------------------------------------------------------
+function canViewField(callerRole, visibility, visibleToRoles) {
+    if (visibility === 'all')
+        return true;
+    if (visibility === 'admin-only') {
+        return callerRole === 'owner' || callerRole === 'admin';
+    }
+    if (visibility === 'role-restricted') {
+        if (!visibleToRoles || visibleToRoles.length === 0)
+            return false;
+        return visibleToRoles.includes(callerRole);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// checkSubscriptionScope — validates org subscription against required scope.
+// Fetches the active subscription for the org and checks scopes array.
+// ---------------------------------------------------------------------------
+async function checkSubscriptionScope(ctx, orgId, requiredScope) {
+    const subscription = await ctx.db
+        .query('subscriptions')
+        .withIndex('by_org', (q) => q.eq('orgId', orgId))
+        .filter((q) => q.eq(q.field('status'), 'active'))
+        .first();
+    if (!subscription) {
+        // Free tier — only read is allowed
+        if (requiredScope !== 'vantage-crm:read') {
+            throw new Error(`No active subscription. Scope ${requiredScope} requires a paid plan.`);
+        }
+        return;
+    }
+    requireScopeFromScopes(subscription.scopes, requiredScope);
+}

package/dist/convex/lib/workspace.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * convex/lib/workspace.ts
+ *
+ * Workspace access validation + actor resolution helpers.
+ * Extended V0.1.0: getCurrentActor, getCurrentActorType, assertWorkspaceAccess.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §5 D-001 / OQ-1
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWorkspaceAccess = validateWorkspaceAccess;
+exports.checkWorkspaceAccess = checkWorkspaceAccess;
+exports.validateRecordAccess = validateRecordAccess;
+exports.getCurrentActor = getCurrentActor;
+exports.getCurrentActorType = getCurrentActorType;
+exports.buildActor = buildActor;
+exports.assertWorkspaceAccess = assertWorkspaceAccess;
+/**
+ * Validate workspace access for mutations
+ *
+ * Authorization logic (Option C - Convex Master Recommended):
+ * 1. Personal workspace: Only owner has access (fast path)
+ * 2. Org workspace: Check workspaceMembers table
+ *
+ * IMPORTANT: Does NOT use activeWorkspaceId - that's UI state, not auth!
+ *
+ * @param ctx - Convex mutation or query context
+ * @param workspaceId - The workspace ID to validate access for
+ * @returns WorkspaceAccessResult with user info and role
+ * @throws Error if not authenticated or no access to workspace
+ */
+async function validateWorkspaceAccess(ctx, workspaceId) {
+    // 1. Authenticate
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        throw new Error('Unauthorized: Not authenticated');
+    }
+    // 2. Get user record
+    const user = await ctx.db
+        .query('users')
+        .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+        .first();
+    if (!user) {
+        throw new Error('Unauthorized: User not found');
+    }
+    // 3. Get workspace
+    const workspace = await ctx.db.get(workspaceId);
+    if (!workspace) {
+        throw new Error('Not found: Workspace does not exist');
+    }
+    // 4. Check authorization based on workspace type
+    // Fast path: Personal workspace owner (2 DB reads total)
+    if (workspace.ownerType === 'user' && workspace.ownerId === user._id) {
+        return {
+            clerkId: identity.subject,
+            userId: user._id,
+            role: 'owner',
+            canWrite: true,
+        };
+    }
+    // Org workspace: Check membership table (3 DB reads total)
+    const membership = await ctx.db
+        .query('workspaceMembers')
+        .withIndex('by_workspace_user', (q) => q.eq('workspaceId', workspaceId).eq('userId', user._id))
+        .first();
+    if (membership) {
+        const canWrite = ['owner', 'admin', 'editor'].includes(membership.role);
+        return {
+            clerkId: identity.subject,
+            userId: user._id,
+            role: membership.role,
+            canWrite,
+        };
+    }
+    throw new Error('Unauthorized: No access to this workspace');
+}
+/**
+ * Lightweight version for queries - returns null instead of throwing
+ * Use this when you want to check access without throwing an error
+ */
+async function checkWorkspaceAccess(ctx, workspaceId) {
+    try {
+        return await validateWorkspaceAccess(ctx, workspaceId);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the workspace ID from a record and validates access.
+ * Use this when you have a record ID and need to validate workspace access.
+ * V0.1.0: accepts CRM entity tables (contacts, companies, deals, activities,
+ * custom_object_records, workflow_definitions, workflow_executions).
+ *
+ * @param ctx - Convex mutation context
+ * @param recordId - The record ID to get workspace from
+ * @param tableName - The table name
+ * @returns The access result and the record
+ */
+async function validateRecordAccess(ctx, recordId, tableName) {
+    const record = await ctx.db.get(recordId);
+    if (!record) {
+        throw new Error(`${tableName.slice(0, -1)} not found`);
+    }
+    const access = await validateWorkspaceAccess(ctx, record.workspaceId);
+    return { access, record };
+}
+/**
+ * Resolve the calling actor from Clerk identity or from a special header/token.
+ * For V0.1.0 with Clerk auth: returns user actor.
+ * Agent callers (Composio) set actorId explicitly in mutation args — they must
+ * pass actorId='agent:composio' as an argument; the function trusts it after
+ * workspace access is validated.
+ *
+ * @param ctx - Convex context
+ * @returns Actor object with actorId, actorType, auditActorType
+ */
+async function getCurrentActor(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+        throw new Error('Unauthorized: Not authenticated');
+    }
+    return {
+        actorId: identity.subject,
+        actorType: 'user',
+        auditActorType: 'user',
+    };
+}
+/**
+ * Returns the actorType string for the current caller.
+ * Convenience wrapper around getCurrentActor.
+ */
+async function getCurrentActorType(ctx) {
+    const actor = await getCurrentActor(ctx);
+    return actor.actorType;
+}
+/**
+ * Build an actor from an explicit actorId override (agent/system callers).
+ * Used when a mutation accepts an optional actorId arg for Composio integration.
+ */
+function buildActor(clerkId, overrideActorId) {
+    if (overrideActorId === 'agent:composio') {
+        return {
+            actorId: 'agent:composio',
+            actorType: 'agent:composio',
+            auditActorType: 'agent',
+        };
+    }
+    if (overrideActorId === 'system') {
+        return {
+            actorId: 'system',
+            actorType: 'system',
+            auditActorType: 'system',
+        };
+    }
+    return {
+        actorId: overrideActorId ?? clerkId,
+        actorType: 'user',
+        auditActorType: 'user',
+    };
+}
+/**
+ * assertWorkspaceAccess — alias for validateWorkspaceAccess with explicit
+ * callerActorId parameter for agent-driven mutations.
+ * Returns WorkspaceAccessResult + resolved Actor.
+ */
+async function assertWorkspaceAccess(ctx, workspaceId, overrideActorId) {
+    const access = await validateWorkspaceAccess(ctx, workspaceId);
+    const actor = buildActor(access.clerkId, overrideActorId);
+    return { ...access, actor };
+}