feat(workspace): 1119 define workspaces dataschema (#2431)

* feat(workspaces): add workspaces module with roles and scopes

* feat(workspaces): add domain, graphql and persistent storage dataschema

* fix(workspaces): correct db injections

* chore(workspaces): add EE license

* chore(license): mentions workspaces separately in license file

* fix(core): roles import in migration

* fix(workspaces): drop workspace_acl on down migration

* fix(workspaces): roles constants

* fix(workspaces): coding standards

---------

Co-authored-by: Dimitrie Stefanescu <didimitrie@gmail.com>

LICENSE

@@ -1,3 +1,10 @@
+Copyright (c) 2020-present AEC Systems.
+
+Portions of this software are licensed as follows:
+
+- All content residing under the "packages/server/modules/workspaces/" directory of this repository is licensed under "The Speckle Enterprise Edition (EE) license".
+- Content outside of the above mentioned directories or restrictions above is available under the "Apache License" license as defined below.
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -186,7 +193,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2020 AEC Systems
+  Copyright 2020-present AEC Systems
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.

packages/server/assets/workspaces/workspaces.graphql

@@ -0,0 +1,91 @@
+type Workspace {
+  id: ID!
+  name: String!
+  description: String
+  createdAt: DateTime!
+  updatedAt: DateTime!
+  createdBy: LimitedUser
+  """
+  Active user's role for this workspace. `null` if request is not authenticated, or the workspace is not explicitly shared with you.
+  """
+  role: String
+  team: [WorkspaceCollaborator!]!
+  invitedTeam: [PendingWorkspaceCollaborator!]
+  projects(
+    limit: Int! = 25
+    cursor: String
+    filter: UserProjectsFilter
+  ): ProjectCollection!
+}
+
+type WorkspaceCollaborator {
+  id: ID!
+  role: String!
+  user: LimitedUser!
+}
+
+type PendingWorkspaceCollaborator {
+  id: ID!
+  inviteId: String!
+  workspaceId: String!
+  workspaceName: String!
+  """
+  E-mail address or name of the invited user
+  """
+  title: String!
+  role: String!
+  invitedBy: LimitedUser!
+  """
+  Set only if user is registered
+  """
+  user: LimitedUser
+  """
+  Only available if the active user is the pending workspace collaborator
+  """
+  token: String
+}
+
+type WorkspaceCollection {
+  totalCount: Int!
+  cursor: String
+  items: [Workspace!]!
+}
+
+extend type User {
+  """
+  Get the workspaces for the user
+  """
+  workspaces(
+    limit: Int! = 25
+    cursor: String = null
+    filter: UserWorkspacesFilter
+  ): WorkspaceCollection! @isOwner
+}
+
+extend type Project {
+  workspace: Workspace
+}
+
+type ServerWorkspacesInfo {
+  """
+  This is a backend control variable for the workspaces feature set.
+  Since workspaces need a backend logic to be enabled, this is not enough as a feature flag.
+  """
+  workspacesEnabled: Boolean!
+}
+
+extend type ServerInfo {
+  workspaces: ServerWorkspacesInfo!
+}
+
+extend type AdminQueries {
+  workspaceList(
+    query: String
+    limit: Int! = 25
+    cursor: String = null
+  ): WorkspaceCollection!
+}
+
+input UserWorkspacesFilter {
+  search: String
+}

packages/server/modules/auth/helpers/types.ts

@@ -2,9 +2,3 @@ export type ServerAppsScopesRecord = {
   appId: string
   scopeName: string
 }
-
-export type ScopeRecord = {
-  name: string
-  description: string
-  public: boolean
-}

packages/server/modules/auth/index.js

@@ -1,6 +1,7 @@
 'use strict'
-const { registerOrUpdateScope } = require('@/modules/shared')
+const { registerOrUpdateScopeFactory } = require('@/modules/shared/repositories/scopes')
 const { moduleLogger } = require('@/logging/logging')
+const db = require('@/db/knex')
 
 exports.init = async (app) => {
   moduleLogger.info('🔑 Init auth module')
@@ -13,8 +14,9 @@ exports.init = async (app) => {
 
   // Register core-based scopes
   const scopes = require('./scopes.js')
+  const registerFunc = registerOrUpdateScopeFactory({ db })
   for (const scope of scopes) {
-    await registerOrUpdateScope(scope)
+    await registerFunc({ scope })
   }
 }
 

packages/server/modules/auth/repositories/index.ts

@@ -7,8 +7,9 @@ import {
 } from '@/modules/core/dbSchema'
 import { InvalidArgumentError } from '@/modules/shared/errors'
 import { Nullable } from '@/modules/shared/helpers/typeHelper'
-import { ScopeRecord, ServerAppsScopesRecord } from '@/modules/auth/helpers/types'
+import { ServerAppsScopesRecord } from '@/modules/auth/helpers/types'
 import { groupBy, mapValues } from 'lodash'
+import { TokenScopeData } from '@/modules/shared/domain/rolesAndScopes/types'
 
 export type RefreshTokenRecord = {
   id: string
@@ -59,7 +60,7 @@ export async function deleteExistingAuthTokens(userId: string) {
 
 export async function getAppScopes(appIds: string[]) {
   const items = await ServerAppsScopes.knex<
-    Array<ServerAppsScopesRecord & ScopeRecord>
+    Array<ServerAppsScopesRecord & TokenScopeData>
   >()
     .whereIn(ServerAppsScopes.col.appId, appIds)
     .innerJoin(Scopes.name, Scopes.col.name, ServerAppsScopes.col.scopeName)

packages/server/modules/automate/index.ts

@@ -13,9 +13,8 @@ import {
   getAutomationRevision,
   getFullAutomationRunById
 } from '@/modules/automate/repositories/automations'
-import { ScopeRecord } from '@/modules/auth/helpers/types'
 import { Scopes } from '@speckle/shared'
-import { registerOrUpdateScope } from '@/modules/shared'
+import { registerOrUpdateScopeFactory } from '@/modules/shared/repositories/scopes'
 import { triggerAutomationRun } from '@/modules/automate/clients/executionEngine'
 import logStreamRest from '@/modules/automate/rest/logStream'
 import {
@@ -32,12 +31,14 @@ import authGithubAppRest from '@/modules/automate/rest/authGithubApp'
 import { getFeatureFlags } from '@/modules/shared/helpers/envHelper'
 import { getUserById } from '@/modules/core/services/users'
 import { getCommit } from '@/modules/core/repositories/commits'
+import { TokenScopeData } from '@/modules/shared/domain/rolesAndScopes/types'
+import db from '@/db/knex'
 
 const { FF_AUTOMATE_MODULE_ENABLED } = getFeatureFlags()
 let quitListeners: Optional<() => void> = undefined
 
 async function initScopes() {
-  const scopes: ScopeRecord[] = [
+  const scopes: TokenScopeData[] = [
     {
       name: Scopes.Automate.ReportResults,
       description: 'Report automation results to the server.',
@@ -55,8 +56,9 @@ async function initScopes() {
     }
   ]
 
+  const registerFunc = registerOrUpdateScopeFactory({ db })
   for (const scope of scopes) {
-    await registerOrUpdateScope(scope)
+    await registerFunc({ scope })
   }
 }
 

packages/server/modules/core/dbSchema.ts

@@ -261,7 +261,8 @@ export const Streams = buildTableHelper(
     'createdAt',
     'updatedAt',
     'allowPublicComments',
-    'isDiscoverable'
+    'isDiscoverable',
+    'workspaceId'
   ],
   StreamsMeta
 )

packages/server/modules/core/index.ts

@@ -1,4 +1,3 @@
-import { registerOrUpdateScope, registerOrUpdateRole } from '@/modules/shared'
 import { moduleLogger } from '@/logging/logging'
 import {
   setupResultListener,
@@ -19,6 +18,9 @@ import Redis from 'ioredis'
 import { createRedisClient } from '@/modules/shared/redis/redis'
 import { getRedisUrl } from '@/modules/shared/helpers/envHelper'
 import { UninitializedResourceAccessError } from '@/modules/shared/errors'
+import { registerOrUpdateScopeFactory } from '@/modules/shared/repositories/scopes'
+import db from '@/db/knex'
+import { registerOrUpdateRole } from '@/modules/shared/repositories/roles'
 
 let genericRedisClient: Optional<Redis> = undefined
 
@@ -42,14 +44,16 @@ const coreModule: SpeckleModule<{
     diffUpload(app)
     diffDownload(app)
 
+    const scopeRegisterFunc = registerOrUpdateScopeFactory({ db })
     // Register core-based scoeps
     for (const scope of scopes) {
-      await registerOrUpdateScope(scope)
+      await scopeRegisterFunc({ scope })
     }
 
+    const roleRegisterFunc = registerOrUpdateRole({ db })
     // Register core-based roles
     for (const role of roles) {
-      await registerOrUpdateRole(role)
+      await roleRegisterFunc({ role })
     }
 
     if (isInitial) {

packages/server/modules/core/migrations/20211119105730_de_duplicate_users.js

@@ -5,7 +5,7 @@ https://speckle.community/t/error-in-grasshopper-while-receiving-data-you-dont-h
 */
 
 exports.up = async (knex) => {
-  const roles = require('@/modules/core/roles.js')
+  const roles = require('@/modules/core/roles')
 
   const Users = () => knex('users')
 

packages/server/modules/core/roles.ts

@@ -1,12 +1,15 @@
-'use strict'
-const { Roles } = require('@/modules/core/helpers/mainConstants')
+import {
+  UserServerRole,
+  UserStreamRole
+} from '@/modules/shared/domain/rolesAndScopes/types'
+import { Roles } from '@/modules/core/helpers/mainConstants'
 
 // Conventions:
 // "weight: 1000" => resource owner
 // "weight: 100" => resource viewer / basic user
 // Anything in between 100 and 1000 can be used for escalating privileges.
 
-module.exports = [
+const coreUserRoles: Array<UserServerRole | UserStreamRole> = [
   /**
    * Roles for "this" server.
    */
@@ -76,3 +79,5 @@ module.exports = [
     public: true
   }
 ]
+
+export default coreUserRoles

packages/server/modules/index.js

@@ -42,7 +42,11 @@ function autoloadFromDirectory(dirPath) {
 }
 
 const getEnabledModuleNames = () => {
-  const { FF_AUTOMATE_MODULE_ENABLED, FF_GENDOAI_MODULE_ENABLED } = getFeatureFlags()
+  const {
+    FF_AUTOMATE_MODULE_ENABLED,
+    FF_GENDOAI_MODULE_ENABLED,
+    FF_WORKSPACES_MODULE_ENABLED
+  } = getFeatureFlags()
   const moduleNames = [
     'accessrequests',
     'activitystream',
@@ -64,6 +68,7 @@ const getEnabledModuleNames = () => {
 
   if (FF_AUTOMATE_MODULE_ENABLED) moduleNames.push('automate')
   if (FF_GENDOAI_MODULE_ENABLED) moduleNames.push('gendo')
+  if (FF_WORKSPACES_MODULE_ENABLED) moduleNames.push('workspaces')
   return moduleNames
 }
 

packages/server/modules/serverinvites/index.js

@@ -1,13 +1,15 @@
 'use strict'
-const { registerOrUpdateScope } = require('@/modules/shared')
+const { registerOrUpdateScopeFactory } = require('@/modules/shared/repositories/scopes')
 const { moduleLogger } = require('@/logging/logging')
+const db = require('@/db/knex')
 
 exports.init = async () => {
   moduleLogger.info('💌 Init invites module')
 
   const scopes = require('./scopes.js')
+  const registerFunc = registerOrUpdateScopeFactory({ db })
   for (const scope of scopes) {
-    await registerOrUpdateScope(scope)
+    await registerFunc({ scope })
   }
 }
 

packages/server/modules/shared/authz.ts

@@ -1,10 +1,5 @@
-import {
-  Scopes,
-  Roles,
-  ServerRoles,
-  StreamRoles
-} from '@/modules/core/helpers/mainConstants'
-import { getRoles } from '@/modules/shared/roles'
+import { Scopes, Roles } from '@/modules/core/helpers/mainConstants'
+import { getRolesFactory } from '@/modules/shared/repositories/roles'
 import { getStream } from '@/modules/core/services/streams'
 
 import {
@@ -15,10 +10,18 @@ import {
   BadRequestError
 } from '@/modules/shared/errors'
 import { adminOverrideEnabled } from '@/modules/shared/helpers/envHelper'
-import { MaybeNullOrUndefined, Nullable } from '@speckle/shared'
+import {
+  AvailableRoles,
+  MaybeNullOrUndefined,
+  Nullable,
+  ServerRoles,
+  StreamRoles
+} from '@speckle/shared'
 import { TokenResourceIdentifier } from '@/modules/core/domain/tokens/types'
 import { isResourceAllowed } from '@/modules/core/helpers/token'
 import { getAutomationProject } from '@/modules/automate/repositories/automations'
+import { UserRoleData } from '@/modules/shared/domain/rolesAndScopes/types'
+import db from '@/db/knex'
 
 interface AuthResult {
   authorized: boolean
@@ -84,13 +87,6 @@ export const authSuccess = (context: AuthContext): AuthData => ({
   authResult: { authorized: true }
 })
 
-type AvailableRoles = ServerRoles | StreamRoles
-
-interface RoleData<T extends AvailableRoles> {
-  weight: number
-  name: T
-}
-
 export type AuthPipelineFunction = ({
   context,
   authResult,
@@ -102,18 +98,11 @@ export const authHasFailed = (authResult: AuthResult): authResult is AuthFailedR
 
 interface RoleValidationInput<T extends AvailableRoles> {
   requiredRole: T
-  rolesLookup: () => Promise<RoleData<T>[]>
+  rolesLookup: () => Promise<UserRoleData<T>[]>
   iddqd: T
   roleGetter: (context: AuthContext) => T | null
 }
 
-// interface StreamRoleValidationInput {
-// requiredRole: StreamRoles
-// rolesLookup: () => Promise<StreamRoleData[]>
-// iddqd: StreamRoles
-// roleGetter: (AuthContext) => StreamRoles
-// }
-
 export function validateRole<T extends AvailableRoles>({
   requiredRole,
   rolesLookup,
@@ -155,7 +144,7 @@ export function validateRole<T extends AvailableRoles>({
 export const validateServerRole = ({ requiredRole }: { requiredRole: ServerRoles }) =>
   validateRole({
     requiredRole,
-    rolesLookup: getRoles,
+    rolesLookup: getRolesFactory({ db }),
     iddqd: Roles.Server.Admin,
     roleGetter: (context) => context.role || null
   })
@@ -163,7 +152,7 @@ export const validateServerRole = ({ requiredRole }: { requiredRole: ServerRoles
 export const validateStreamRole = ({ requiredRole }: { requiredRole: StreamRoles }) =>
   validateRole({
     requiredRole,
-    rolesLookup: getRoles,
+    rolesLookup: getRolesFactory({ db }),
     iddqd: Roles.Stream.Owner,
     roleGetter: (context) => context?.stream?.role || null
   })

packages/server/modules/shared/domain/rolesAndScopes/operations.ts

@@ -0,0 +1,6 @@
+import { TokenScopeData, UserRole } from '@/modules/shared/domain/rolesAndScopes/types'
+
+export type GetRoles = () => Promise<UserRole[]>
+export type UpsertRole = (args: { role: UserRole }) => Promise<void>
+
+export type GetScopes = () => Promise<TokenScopeData[]>

packages/server/modules/shared/domain/rolesAndScopes/types.ts

@@ -0,0 +1,39 @@
+import {
+  AvailableRoles,
+  ServerRoles,
+  StreamRoles,
+  WorkspaceRoles,
+  ServerScope
+} from '@speckle/shared'
+
+export type UserRoleData<T extends AvailableRoles> = {
+  description: string
+  weight: number
+  public: boolean
+  name: T
+}
+
+export type UserServerRole = UserRoleData<ServerRoles> & {
+  resourceTarget: 'server'
+  aclTableName: 'server_acl'
+}
+
+export type UserStreamRole = UserRoleData<StreamRoles> & {
+  resourceTarget: 'streams'
+  aclTableName: 'stream_acl'
+  name: StreamRoles
+}
+
+export type UserWorkspaceRole = UserRoleData<WorkspaceRoles> & {
+  resourceTarget: 'workspace'
+  aclTableName: 'workspace_acl'
+  name: WorkspaceRoles
+}
+
+export type UserRole = UserServerRole | UserStreamRole | UserWorkspaceRole
+
+export type TokenScopeData = {
+  name: ServerScope
+  description: string
+  public: boolean
+}

packages/server/modules/shared/index.js

@@ -11,12 +11,12 @@ const { Roles } = require('@speckle/shared')
 const { adminOverrideEnabled } = require('@/modules/shared/helpers/envHelper')
 
 const { ServerAcl: ServerAclSchema } = require('@/modules/core/dbSchema')
-const { getRoles } = require('@/modules/shared/roles')
+const { getRolesFactory } = require('@/modules/shared/repositories/roles')
 const {
   roleResourceTypeToTokenResourceType,
   isResourceAllowed
 } = require('@/modules/core/helpers/token')
-
+const db = require('@/db/knex')
 const ServerAcl = () => ServerAclSchema.knex()
 
 /**
@@ -49,7 +49,7 @@ async function authorizeResolver(
   userResourceAccessLimits
 ) {
   userId = userId || null
-  const roles = await getRoles()
+  const roles = await getRolesFactory({ db })()
 
   // TODO: Cache these results with a TTL of 1 mins or so, it's pointless to query the db every time we get a ping.
 
@@ -99,37 +99,10 @@ async function authorizeResolver(
   throw new ForbiddenError('You are not authorized.')
 }
 
-const Scopes = () => knex('scopes')
-
-async function registerOrUpdateScope(scope) {
-  await knex.raw(
-    `${Scopes()
-      .insert(scope)
-      .toString()} on conflict (name) do update set public = ?, description = ? `,
-    [scope.public, scope.description]
-  )
-  return
-}
-
-const UserRoles = () => knex('user_roles')
-async function registerOrUpdateRole(role) {
-  await knex.raw(
-    `${UserRoles()
-      .insert(role)
-      .toString()} on conflict (name) do update set weight = ?, description = ?, "resourceTarget" = ? `,
-    [role.weight, role.description, role.resourceTarget]
-  )
-  return
-}
-
 module.exports = {
-  registerOrUpdateScope,
-  registerOrUpdateRole,
-  // validateServerRole,
   validateScopes,
   authorizeResolver,
   pubsub,
-  getRoles,
   StreamPubsubEvents: StreamSubscriptions,
   CommitPubsubEvents: CommitSubscriptions,
   BranchPubsubEvents: BranchSubscriptions

packages/server/modules/shared/repositories/roles.ts

@@ -0,0 +1,22 @@
+import { GetRoles, UpsertRole } from '@/modules/shared/domain/rolesAndScopes/operations'
+import { UserRole } from '@/modules/shared/domain/rolesAndScopes/types'
+import { Knex } from 'knex'
+
+let roles: UserRole[]
+
+export const getRolesFactory =
+  ({ db }: { db: Knex }): GetRoles =>
+  async () => {
+    if (roles) return roles
+    roles = await db('user_roles').select('*')
+    return roles
+  }
+
+export const registerOrUpdateRole =
+  ({ db }: { db: Knex }): UpsertRole =>
+  async ({ role }) => {
+    await db('user_roles')
+      .insert(role)
+      .onConflict('name')
+      .merge(['weight', 'description', 'resourceTarget'])
+  }

packages/server/modules/shared/repositories/scopes.ts

@@ -0,0 +1,8 @@
+import { TokenScopeData } from '@/modules/shared/domain/rolesAndScopes/types'
+import { Knex } from 'knex'
+
+export const registerOrUpdateScopeFactory =
+  ({ db }: { db: Knex }) =>
+  async ({ scope }: { scope: TokenScopeData }) => {
+    await db('scopes').insert(scope).onConflict('name').merge(['public', 'description'])
+  }

packages/server/modules/shared/roles.js

@@ -1,12 +0,0 @@
-const knex = require(`@/db/knex`)
-let roles
-
-const getRoles = async () => {
-  if (roles) return roles
-  roles = await knex('user_roles').select('*')
-  return roles
-}
-
-module.exports = {
-  getRoles
-}

packages/server/modules/workspaces/LICENSE

@@ -0,0 +1,13 @@
+The Speckle Enterprise Edition (EE) license (the “EE License”)
+
+Copyright (c) 2024-present AEC Systems LTD.
+
+With regard to the Speckle Software:
+
+This software and associated documentation files (the "Software") may only be used, if you (and any entity that you represent) have agreed to, and are in compliance with, the AEC Systems Terms of Service, available at https://speckle.systems/terms/ (the “EE Terms”), or other agreement governing the use of the Software, as agreed by you and AEC Systems, and otherwise have a valid Speckle Enterprise Edition subscription for the correct number of user seats. Subject to the foregoing sentence, you are free to modify this Software and publish patches to the Software. You agree that AEC Systems and/or its licensors (as applicable) retain all right, title and interest in and to all such modifications and/or patches, and all such modifications and/or patches may only be used, copied, modified, displayed, distributed, or otherwise exploited with a valid Speckle Enterprise Edition subscription for the correct number of user seats. Notwithstanding the foregoing, you may copy and modify the Software for development and testing purposes, without requiring a subscription. You agree that AEC Systems and/or its licensors (as applicable) retain all right, title and interest in and to all such modifications. You are not granted any other rights beyond what is expressly stated herein. Subject to the foregoing, it is forbidden to copy, merge, publish, distribute, sublicense, and/or sell the Software.
+
+This EE License applies only to the part of this Software that is not distributed as part of Speckle Community Edition (CE). Any part of this Software distributed as part of Speckle CE or is served client-side as an image, font, cascading stylesheet (CSS), file which produces or is compiled, arranged, augmented, or combined into client-side JavaScript, in whole or in part, is copyrighted under the Apache 2.0 license. The full text of this EE License shall be included in all copies or substantial portions of the Software. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For all third party components incorporated into the Speckle Software, those components are licensed under the original license provided by the owner of the applicable component.

packages/server/modules/workspaces/domain/events.ts

@@ -0,0 +1,11 @@
+export enum WorkspaceEvents {
+  Created = 'created',
+  Deleted = 'deleted',
+  RoleAssigned = 'roleAssigned',
+  RoleRemoved = 'roleRemoved',
+  ProjectAdded = 'projectAdded',
+  ProjectRemoved = 'projectRemoved'
+}
+
+// export type WorkspaceEventsPayloads = {
+// }

packages/server/modules/workspaces/domain/types.ts

@@ -0,0 +1,12 @@
+export type Workspace = {
+  id: string
+  name: string
+  description: string | null
+  createdAt: Date
+  updatedAt: Date
+  // the user who created it, might not be a server user any more
+  createdByUserId: string | null
+  logoUrl: string | null
+}
+
+export type GetUsersWorkspaces = (args: { userId: string }) => Promise<Workspace[]>

packages/server/modules/workspaces/index.ts

@@ -0,0 +1,30 @@
+import { moduleLogger } from '@/logging/logging'
+import { getFeatureFlags } from '@/modules/shared/helpers/envHelper'
+import { registerOrUpdateScopeFactory } from '@/modules/shared/repositories/scopes'
+import db from '@/db/knex'
+import { SpeckleModule } from '@/modules/shared/helpers/typeHelper'
+import { workspaceRoles } from '@/modules/workspaces/roles'
+import { workspaceScopes } from '@/modules/workspaces/scopes'
+import { registerOrUpdateRole } from '@/modules/shared/repositories/roles'
+
+const { FF_WORKSPACES_MODULE_ENABLED } = getFeatureFlags()
+
+const initScopes = () => {
+  const registerFunc = registerOrUpdateScopeFactory({ db })
+  return Promise.all(workspaceScopes.map((scope) => registerFunc({ scope })))
+}
+
+const initRoles = () => {
+  const registerFunc = registerOrUpdateRole({ db })
+  return Promise.all(workspaceRoles.map((role) => registerFunc({ role })))
+}
+
+const workspacesModule: SpeckleModule = {
+  async init() {
+    if (!FF_WORKSPACES_MODULE_ENABLED) return
+    moduleLogger.info('⚒️  Init workspaces module')
+    await Promise.all([initScopes(), initRoles()])
+  }
+}
+
+export = workspacesModule

packages/server/modules/workspaces/migrations/20240621174016_workspaces.ts

@@ -0,0 +1,35 @@
+import { Knex } from 'knex'
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('workspaces', (table) => {
+    table.text('id').primary()
+    table.text('name').notNullable()
+    table.text('description')
+    table.timestamp('createdAt', { precision: 3, useTz: true }).notNullable()
+    table.timestamp('updatedAt', { precision: 3, useTz: true }).notNullable()
+    table.text('createdByUserId').references('id').inTable('users').onDelete('set null')
+    table.text('logoUrl')
+  })
+  await knex.schema.alterTable('streams', (table) => {
+    table.string('workspaceId').references('id').inTable('workspaces')
+  })
+  await knex.schema.createTable('workspace_acl', (table) => {
+    table.text('userId').references('id').inTable('users').onDelete('cascade')
+    table.text('workspaceId').references('id').inTable('workspaces').onDelete('cascade')
+    table.primary(['userId', 'workspaceId'])
+    table
+      .text('role')
+      .references('name')
+      .inTable('user_roles')
+      .notNullable()
+      .onDelete('cascade')
+  })
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTable('workspaces')
+  await knex.schema.alterTable('streams', (table) => {
+    table.dropColumn('workspaceId')
+  })
+  await knex.schema.dropTable('workspace_acl')
+}

packages/server/modules/workspaces/roles.ts

@@ -0,0 +1,32 @@
+import { UserWorkspaceRole } from '@/modules/shared/domain/rolesAndScopes/types'
+import { Roles } from '@speckle/shared'
+
+const aclTableName = 'workspace_acl'
+const resourceTarget = 'workspace'
+
+export const workspaceRoles: UserWorkspaceRole[] = [
+  {
+    name: Roles.Workspace.Admin,
+    description: 'Has root on the workspace',
+    weight: 1000,
+    public: true,
+    resourceTarget,
+    aclTableName
+  },
+  {
+    name: Roles.Workspace.Member,
+    description: 'A regular member of the workspace',
+    weight: 100,
+    public: true,
+    resourceTarget,
+    aclTableName
+  },
+  {
+    name: Roles.Workspace.Guest,
+    description: 'An external guest member of the workspace with limited rights',
+    weight: 50,
+    public: true,
+    resourceTarget,
+    aclTableName
+  }
+]

packages/server/modules/workspaces/scopes.ts

@@ -0,0 +1,20 @@
+import { TokenScopeData } from '@/modules/shared/domain/rolesAndScopes/types'
+import { Scopes } from '@speckle/shared'
+
+export const workspaceScopes: TokenScopeData[] = [
+  {
+    name: Scopes.Workspaces.Create,
+    description: 'Required for the creation of a workspace',
+    public: true
+  },
+  {
+    name: Scopes.Workspaces.Update,
+    description: 'Required for editing workspace information',
+    public: true
+  },
+  {
+    name: Scopes.Workspaces.Delete,
+    description: 'Required for deleting workspaces',
+    public: true
+  }
+]

packages/shared/src/core/constants.ts

@@ -11,6 +11,11 @@ export const Roles = Object.freeze(<const>{
     Contributor: 'stream:contributor',
     Reviewer: 'stream:reviewer'
   },
+  Workspace: {
+    Admin: 'workspace:admin',
+    Member: 'workspace:member',
+    Guest: 'workspace:guest'
+  },
   Server: {
     Admin: 'server:admin',
     User: 'server:user',
@@ -41,12 +46,33 @@ export const RoleInfo = Object.freeze(<const>{
     [Roles.Server.User]: 'User',
     [Roles.Server.Guest]: 'Guest',
     [Roles.Server.ArchivedUser]: 'Archived'
+  },
+  Workspace: {
+    [Roles.Workspace.Admin]: {
+      title: 'Admin',
+      description:
+        'A role assigned workspace administrators. They have full control over the workspace.'
+    },
+    [Roles.Workspace.Member]: {
+      title: 'Member',
+      description:
+        'A role assigned workspace members. They have access to resources in the workspace.'
+    },
+    [Roles.Workspace.Guest]: {
+      title: 'Member',
+      description:
+        'A role assigned workspace guests. Their access to resources in the workspace is limited to resources they have explicit roles on.'
+    }
   }
 })
 
 export type ServerRoles = (typeof Roles)['Server'][keyof (typeof Roles)['Server']]
+export type WorkspaceRoles =
+  (typeof Roles)['Workspace'][keyof (typeof Roles)['Workspace']]
 export type StreamRoles = (typeof Roles)['Stream'][keyof (typeof Roles)['Stream']]
 
+export type AvailableRoles = ServerRoles | StreamRoles | WorkspaceRoles
+
 /**
  * Speckle scope constants
  * - Scopes define what kind of access has a user approved for a specific access token
@@ -84,9 +110,38 @@ export const Scopes = Object.freeze(<const>{
   AutomateFunctions: {
     Read: 'automate-functions:read',
     Write: 'automate-functions:write'
+  },
+  Workspaces: {
+    Create: 'workspace:create',
+    Update: 'workspace:update',
+    Delete: 'workspace:delete'
   }
 })
 
+export type StreamScopes = (typeof Scopes)['Streams'][keyof (typeof Scopes)['Streams']]
+export type ProfileScopes = (typeof Scopes)['Profile'][keyof (typeof Scopes)['Profile']]
+export type UserScopes = (typeof Scopes)['Users'][keyof (typeof Scopes)['Users']]
+export type ServerScopes = (typeof Scopes)['Server'][keyof (typeof Scopes)['Server']]
+export type TokenScopes = (typeof Scopes)['Tokens'][keyof (typeof Scopes)['Tokens']]
+export type AppScopes = (typeof Scopes)['Apps'][keyof (typeof Scopes)['Apps']]
+export type AutomateScopes =
+  (typeof Scopes)['Automate'][keyof (typeof Scopes)['Automate']]
+export type AutomateFunctionScopes =
+  (typeof Scopes)['AutomateFunctions'][keyof (typeof Scopes)['AutomateFunctions']]
+export type WorkspaceScopes =
+  (typeof Scopes)['Workspaces'][keyof (typeof Scopes)['Workspaces']]
+
+export type AvailableScopes =
+  | StreamScopes
+  | ProfileScopes
+  | UserScopes
+  | ServerScopes
+  | TokenScopes
+  | AppScopes
+  | AutomateScopes
+  | AutomateFunctionScopes
+  | WorkspaceRoles
+
 /**
  * All scopes
  */

packages/shared/src/environment/index.ts

@@ -16,6 +16,11 @@ function parseFeatureFlags() {
       defaults: { production: false, _: true }
     },
     // Disables writing to the closure table in the create objects batched services (re object upload routes)
+    // Enables the workspaces module
+    FF_WORKSPACES_MODULE_ENABLED: {
+      schema: z.boolean(),
+      defaults: { production: false, _: true }
+    },
     FF_NO_CLOSURE_WRITES: {
       schema: z.boolean(),
       defaults: { production: false, _: false }
@@ -29,6 +34,7 @@ export function getFeatureFlags(): {
   FF_AUTOMATE_MODULE_ENABLED: boolean
   FF_GENDOAI_MODULE_ENABLED: boolean
   FF_NO_CLOSURE_WRITES: boolean
+  FF_WORKSPACES_MODULE_ENABLED: boolean
 } {
   if (!parsedFlags) parsedFlags = parseFeatureFlags()
   return parsedFlags