@gitpod/gitpod-protocol 0.1.5-update-ovsx.0 → 0.1.5-update-yarnlock.0

package/src/protocol.ts

@@ -1,33 +1,37 @@
 /**
- * Copyright (c) 2020 TypeFox GmbH. All rights reserved.
+ * Copyright (c) 2020 Gitpod GmbH. All rights reserved.
  * Licensed under the GNU Affero General Public License (AGPL).
- * See License-AGPL.txt in the project root for license information.
+ * See License.AGPL.txt in the project root for license information.
  */
 
 import { WorkspaceInstance, PortVisibility } from "./workspace-instance";
 import { RoleOrPermission } from "./permission";
+import { Project } from "./teams-projects-protocol";
+import { createHash } from "crypto";
+import { AttributionId } from "./attribution";
 
-export interface UserInfo {
-    name?: string
+export interface UserInfo {
+    name?: string;
 }
 
 export interface User {
     /** The user id */
-    id: string
+    id: string;
+
+    /** The ID of the Organization this user is owned by. If undefined, the user is owned by the installation */
+    organizationId?: string;
 
     /** The timestamp when the user entry was created */
-    creationDate: string
+    creationDate: string;
 
-    avatarUrl?: string
+    avatarUrl?: string;
 
-    name?: string
+    name?: string;
 
     /** Optional for backwards compatibility */
-    fullName?: string
-
-    identities: Identity[]
+    fullName?: string;
 
-    allowsMarketingCommunication: boolean;
+    identities: Identity[];
 
     /**
      * Whether the user has been blocked to use our service, because of TOS violation for example.
@@ -35,11 +39,6 @@ export interface User {
      */
     blocked?: boolean;
 
-    /**
-     * whether this user can run workspaces in privileged mode
-     */
-    privileged?: boolean;
-
     /** A map of random settings that alter the behaviour of Gitpod on a per-user basis */
     featureFlags?: UserFeatureSettings;
 
@@ -50,31 +49,61 @@ export interface User {
     markedDeleted?: boolean;
 
     additionalData?: AdditionalUserData;
+
+    // Identifies an explicit team or user ID to which all the user's workspace usage should be attributed to (e.g. for billing purposes)
+    usageAttributionId?: string;
+
+    // The last time this user got verified somehow. The user is not verified if this is empty.
+    lastVerificationTime?: string;
+
+    // The phone number used for the last phone verification.
+    verificationPhoneNumber?: string;
 }
 
 export namespace User {
     export function is(data: any): data is User {
-        return data
-            && data.hasOwnProperty('id')
-            && data.hasOwnProperty('identities')
+        return data && data.hasOwnProperty("id") && data.hasOwnProperty("identities");
     }
     export function getIdentity(user: User, authProviderId: string): Identity | undefined {
-        return user.identities.find(id => id.authProviderId === authProviderId);
+        return user.identities.find((id) => id.authProviderId === authProviderId);
+    }
+    export function censor(user: User): User {
+        const res = { ...user };
+        delete res.additionalData;
+        res.identities = res.identities.map((i) => {
+            delete i.tokens;
+
+            // The user field is not in the Identity shape, but actually exists on DBIdentity.
+            // Trying to push this object out via JSON RPC will fail because of the cyclic nature
+            // of this field.
+            delete (i as any).user;
+            return i;
+        });
+        return res;
     }
-    export function getPrimaryEmail(user: User): string {
-        const identities = user.identities.filter(i => !!i.primaryEmail);
+
+    /**
+     * Returns the stored email or if it doesn't exist returns the primaryEmail of the first identity this user signed up with.
+     * @param user
+     * @returns A primaryEmail, or undefined if there is none.
+     */
+    export function getPrimaryEmail(user: User): string | undefined {
+        if (user.additionalData?.profile?.emailAddress) {
+            return user.additionalData?.profile?.emailAddress;
+        }
+        const identities = user.identities.filter((i) => !!i.primaryEmail);
         if (identities.length <= 0) {
-            throw new Error(`No identity with primary email for user: ${user.id}!`);
+            return undefined;
         }
 
-        return identities[0].primaryEmail!;
+        return identities[0].primaryEmail || undefined;
     }
     export function getName(user: User): string | undefined {
         const name = user.fullName || user.name;
         if (name) {
             return name;
         }
-        
+
         for (const id of user.identities) {
             if (id.authName !== "") {
                 return id.authName;
@@ -82,15 +111,220 @@ export namespace User {
         }
         return undefined;
     }
+
+    export function hasPreferredIde(user: User) {
+        return (
+            typeof user?.additionalData?.ideSettings?.defaultIde !== "undefined" ||
+            typeof user?.additionalData?.ideSettings?.useLatestVersion !== "undefined"
+        );
+    }
+
+    export function isOnboardingUser(user: User) {
+        return !hasPreferredIde(user);
+    }
+
+    export function migrationIDESettings(user: User) {
+        if (
+            !user?.additionalData?.ideSettings ||
+            Object.keys(user.additionalData.ideSettings).length === 0 ||
+            user.additionalData.ideSettings.settingVersion === "2.0"
+        ) {
+            return;
+        }
+        const newIDESettings: IDESettings = {
+            settingVersion: "2.0",
+        };
+        const ideSettings = user.additionalData.ideSettings;
+        if (ideSettings.useDesktopIde) {
+            if (ideSettings.defaultDesktopIde === "code-desktop") {
+                newIDESettings.defaultIde = "code-desktop";
+            } else if (ideSettings.defaultDesktopIde === "code-desktop-insiders") {
+                newIDESettings.defaultIde = "code-desktop";
+                newIDESettings.useLatestVersion = true;
+            } else {
+                newIDESettings.defaultIde = ideSettings.defaultDesktopIde;
+                newIDESettings.useLatestVersion = ideSettings.useLatestVersion;
+            }
+        } else {
+            const useLatest = ideSettings.defaultIde === "code-latest";
+            newIDESettings.defaultIde = "code";
+            newIDESettings.useLatestVersion = useLatest;
+        }
+        user.additionalData.ideSettings = newIDESettings;
+    }
+
+    // TODO: make it more explicit that these field names are relied for our tracking purposes
+    // and decouple frontend from relying on them - instead use user.additionalData.profile object directly in FE
+    export function getProfile(user: User): Profile {
+        return {
+            name: User.getName(user!) || "",
+            email: User.getPrimaryEmail(user!) || "",
+            company: user?.additionalData?.profile?.companyName,
+            avatarURL: user?.avatarUrl,
+            companyWebsite: user?.additionalData?.profile?.companyWebsite,
+            jobRole: user?.additionalData?.profile?.jobRole,
+            jobRoleOther: user?.additionalData?.profile?.jobRoleOther,
+            explorationReasons: user?.additionalData?.profile?.explorationReasons,
+            signupGoals: user?.additionalData?.profile?.signupGoals,
+            signupGoalsOther: user?.additionalData?.profile?.signupGoalsOther,
+            companySize: user?.additionalData?.profile?.companySize,
+            onboardedTimestamp: user?.additionalData?.profile?.onboardedTimestamp,
+        };
+    }
+
+    export function setProfile(user: User, profile: Profile): User {
+        user.fullName = profile.name;
+        user.avatarUrl = profile.avatarURL;
+
+        if (!user.additionalData) {
+            user.additionalData = {};
+        }
+        if (!user.additionalData.profile) {
+            user.additionalData.profile = {};
+        }
+        user.additionalData.profile.emailAddress = profile.email;
+        user.additionalData.profile.companyName = profile.company;
+        user.additionalData.profile.lastUpdatedDetailsNudge = new Date().toISOString();
+
+        return user;
+    }
+
+    export function getDefaultAttributionId(user: User): AttributionId {
+        if (user.usageAttributionId) {
+            const result = AttributionId.parse(user.usageAttributionId);
+            if (!result) {
+                throw new Error("Invalid attribution ID: " + user.usageAttributionId);
+            }
+            return result;
+        }
+        return AttributionId.create(user);
+    }
+
+    // TODO: refactor where this is referenced so it's more clearly tied to just analytics-tracking
+    // Let other places rely on the ProfileDetails type since that's what we store
+    // This is the profile data we send to our Segment analytics tracking pipeline
+    export interface Profile {
+        name: string;
+        email: string;
+        company?: string;
+        avatarURL?: string;
+        companyWebsite?: string;
+        jobRole?: string;
+        jobRoleOther?: string;
+        explorationReasons?: string[];
+        signupGoals?: string[];
+        signupGoalsOther?: string;
+        onboardedTimestamp?: string;
+        companySize?: string;
+    }
+    export namespace Profile {
+        export function hasChanges(before: Profile, after: Profile) {
+            return (
+                before.name !== after.name ||
+                before.email !== after.email ||
+                before.company !== after.company ||
+                before.avatarURL !== after.avatarURL ||
+                before.companyWebsite !== after.companyWebsite ||
+                before.jobRole !== after.jobRole ||
+                before.jobRoleOther !== after.jobRoleOther ||
+                // not checking explorationReasons or signupGoals atm as it's an array - need to check deep equality
+                before.signupGoalsOther !== after.signupGoalsOther ||
+                before.onboardedTimestamp !== after.onboardedTimestamp ||
+                before.companySize !== after.companySize
+            );
+        }
+    }
+}
+
+export interface WorkspaceTimeoutSetting {
+    // user globol workspace timeout
+    workspaceTimeout: string;
+    // control whether to enable the closed timeout of a workspace, i.e. close web ide, disconnect ssh connection
+    disabledClosedTimeout: boolean;
 }
 
-export interface AdditionalUserData {
+export interface AdditionalUserData extends Partial<WorkspaceTimeoutSetting> {
     platforms?: UserPlatform[];
     emailNotificationSettings?: EmailNotificationSettings;
+    featurePreview?: boolean;
+    ideSettings?: IDESettings;
+    // key is the name of the news, string the iso date when it was seen
+    whatsNewSeen?: { [key: string]: string };
+    // key is the name of the OAuth client i.e. local app, string the iso date when it was approved
+    // TODO(rl): provide a management UX to allow rescinding of approval
+    oauthClientsApproved?: { [key: string]: string };
+    // to remember GH Orgs the user installed/updated the GH App for
+    knownGitHubOrgs?: string[];
+    // Git clone URL pointing to the user's dotfile repo
+    dotfileRepo?: string;
+    // preferred workspace classes
+    workspaceClasses?: WorkspaceClasses;
+    // additional user profile data
+    profile?: ProfileDetails;
+    // whether the user has been migrated to team attribution.
+    // a corresponding feature flag (team_only_attribution) triggers the migration.
+    isMigratedToTeamOnlyAttribution?: boolean;
+}
+export namespace AdditionalUserData {
+    export function set(user: User, partialData: Partial<AdditionalUserData>): User {
+        if (!user.additionalData) {
+            user.additionalData = {
+                ...partialData,
+            };
+        } else {
+            user.additionalData = {
+                ...user.additionalData,
+                ...partialData,
+            };
+        }
+        return user;
+    }
+}
+// The format in which we store User Profiles in
+export interface ProfileDetails {
+    // when was the last time the user updated their profile information or has been nudged to do so.
+    lastUpdatedDetailsNudge?: string;
+    // the user's company name
+    companyName?: string;
+    // the user's email
+    emailAddress?: string;
+    // the user's company website
+    companyWebsite?: string;
+    // type of role user has in their job
+    jobRole?: string;
+    // freeform entry for job role user works in (when jobRole is "other")
+    jobRoleOther?: string;
+    // Reasons user is exploring Gitpod when they signed up
+    explorationReasons?: string[];
+    // what user hopes to accomplish when they signed up
+    signupGoals?: string[];
+    // freeform entry for signup goals (when signupGoals is "other")
+    signupGoalsOther?: string;
+    // Set after a user completes the onboarding flow
+    onboardedTimestamp?: string;
+    // Onboarding question about a user's company size
+    companySize?: string;
 }
 
 export interface EmailNotificationSettings {
-    disallowTransactionalEmails?: boolean;
+    allowsChangelogMail?: boolean;
+    allowsDevXMail?: boolean;
+    allowsOnboardingMail?: boolean;
+}
+
+export type IDESettings = {
+    settingVersion?: string;
+    defaultIde?: string;
+    // DEPRECATED: Use defaultIde after `settingVersion: 2.0`, no more specialify desktop or browser.
+    useDesktopIde?: boolean;
+    // DEPRECATED: Same with useDesktopIde.
+    defaultDesktopIde?: string;
+    useLatestVersion?: boolean;
+};
+
+export interface WorkspaceClasses {
+    regular?: string;
+    prebuild?: string;
 }
 
 export interface UserPlatform {
@@ -104,7 +338,7 @@ export interface UserPlatform {
      * Since when does the user have the browser extension installe don this device.
      */
     browserExtensionInstalledSince?: string;
-    
+
     /**
      * Since when does the user not have the browser extension installed anymore (but previously had).
      */
@@ -112,14 +346,6 @@ export interface UserPlatform {
 }
 
 export interface UserFeatureSettings {
-    /**
-     * This field is used as marker to grant users a free trial for using private repositories,
-     * independent of any subscription or Chargebee.
-     *  - it is set when the user uses their first private repo
-     *  - whether the trial is expired or not is juged by the UserService
-     */
-    privateRepoTrialStartDate?: string;
-
     /**
      * Permanent feature flags are added to each and every workspace instance
      * this user starts.
@@ -127,19 +353,45 @@ export interface UserFeatureSettings {
     permanentWSFeatureFlags?: NamedWorkspaceFeatureFlag[];
 }
 
+export type BillingTier = "paid" | "free";
+
 /**
  * The values of this type MUST MATCH enum values in WorkspaceFeatureFlag from ws-manager/client/core_pb.d.ts
  * If they don't we'll break things during workspace startup.
  */
-export const WorkspaceFeatureFlags = { "privileged": undefined, "registry_facade": undefined, "full_workspace_backup": undefined, "fixed_resources": undefined };
-export type NamedWorkspaceFeatureFlag = keyof(typeof WorkspaceFeatureFlags);
+export const WorkspaceFeatureFlags = {
+    full_workspace_backup: undefined,
+    workspace_class_limiting: undefined,
+    workspace_connection_limiting: undefined,
+    workspace_psi: undefined,
+};
+export type NamedWorkspaceFeatureFlag = keyof typeof WorkspaceFeatureFlags;
+export namespace NamedWorkspaceFeatureFlag {
+    export const WORKSPACE_PERSISTED_FEATTURE_FLAGS: NamedWorkspaceFeatureFlag[] = ["full_workspace_backup"];
+    export function isWorkspacePersisted(ff: NamedWorkspaceFeatureFlag): boolean {
+        return WORKSPACE_PERSISTED_FEATTURE_FLAGS.includes(ff);
+    }
+}
 
-export interface UserEnvVarValue {
-    id?: string;
+export type EnvVar = UserEnvVar | ProjectEnvVarWithValue | EnvVarWithValue;
+
+export interface EnvVarWithValue {
     name: string;
-    repositoryPattern: string;
     value: string;
 }
+
+export interface ProjectEnvVarWithValue extends EnvVarWithValue {
+    id: string;
+    projectId: string;
+    censored: boolean;
+}
+
+export type ProjectEnvVar = Omit<ProjectEnvVarWithValue, "value">;
+
+export interface UserEnvVarValue extends EnvVarWithValue {
+    id?: string;
+    repositoryPattern: string; // DEPRECATED: Use ProjectEnvVar instead of repositoryPattern - https://github.com/gitpod-com/gitpod/issues/5322
+}
 export interface UserEnvVar extends UserEnvVarValue {
     id: string;
     userId: string;
@@ -147,26 +399,89 @@ export interface UserEnvVar extends UserEnvVarValue {
 }
 
 export namespace UserEnvVar {
+    /**
+     * @param variable
+     * @returns Either a string containing an error message or undefined.
+     */
+    export function validate(variable: UserEnvVarValue): string | undefined {
+        const name = variable.name;
+        const pattern = variable.repositoryPattern;
+        if (name.trim() === "") {
+            return "Name must not be empty.";
+        }
+        if (name.length > 255) {
+            return "Name too long. Maximum name length is 255 characters.";
+        }
+        if (!/^[a-zA-Z_]+[a-zA-Z0-9_]*$/.test(name)) {
+            return "Name must match /^[a-zA-Z_]+[a-zA-Z0-9_]*$/.";
+        }
+        if (variable.value.trim() === "") {
+            return "Value must not be empty.";
+        }
+        if (variable.value.length > 32767) {
+            return "Value too long. Maximum value length is 32767 characters.";
+        }
+        if (pattern.trim() === "") {
+            return "Scope must not be empty.";
+        }
+        const split = pattern.split("/");
+        if (split.length < 2) {
+            return "A scope must use the form 'organization/repo'.";
+        }
+        for (const name of split) {
+            if (name !== "*") {
+                if (!/^[a-zA-Z0-9_\-.\*]+$/.test(name)) {
+                    return "Invalid scope segment. Only ASCII characters, numbers, -, _, . or * are allowed.";
+                }
+            }
+        }
+        return undefined;
+    }
 
+    // DEPRECATED: Use ProjectEnvVar instead of repositoryPattern - https://github.com/gitpod-com/gitpod/issues/5322
     export function normalizeRepoPattern(pattern: string) {
         return pattern.toLocaleLowerCase();
     }
 
+    // DEPRECATED: Use ProjectEnvVar instead of repositoryPattern - https://github.com/gitpod-com/gitpod/issues/5322
+    export function score(value: UserEnvVarValue): number {
+        // We use a score to enforce precedence:
+        //      value/value = 0
+        //      value/*     = 1
+        //      */value     = 2
+        //      */*         = 3
+        //      #/#         = 4 (used for env vars passed through the URL)
+        // the lower the score, the higher the precedence.
+        const [ownerPattern, repoPattern] = splitRepositoryPattern(value.repositoryPattern);
+        let score = 0;
+        if (repoPattern == "*") {
+            score += 1;
+        }
+        if (ownerPattern == "*") {
+            score += 2;
+        }
+        if (ownerPattern == "#" || repoPattern == "#") {
+            score = 4;
+        }
+        return score;
+    }
+
+    // DEPRECATED: Use ProjectEnvVar instead of repositoryPattern - https://github.com/gitpod-com/gitpod/issues/5322
     export function filter<T extends UserEnvVarValue>(vars: T[], owner: string, repo: string): T[] {
-        let result = vars.filter(e => {
+        let result = vars.filter((e) => {
             const [ownerPattern, repoPattern] = splitRepositoryPattern(e.repositoryPattern);
-            if (ownerPattern !== '*' && ownerPattern !== '#' && (!!owner && ownerPattern !== owner.toLocaleLowerCase())) {
+            if (ownerPattern !== "*" && ownerPattern !== "#" && !!owner && ownerPattern !== owner.toLocaleLowerCase()) {
                 return false;
             }
-            if (repoPattern !== '*' && repoPattern !== '#' && (!!repo && repoPattern !== repo.toLocaleLowerCase())) {
+            if (repoPattern !== "*" && repoPattern !== "#" && !!repo && repoPattern !== repo.toLocaleLowerCase()) {
                 return false;
             }
             return true;
         });
 
         const resmap = new Map<string, T[]>();
-        result.forEach(e => {
-            const l = (resmap.get(e.name) || []);
+        result.forEach((e) => {
+            const l = resmap.get(e.name) || [];
             l.push(e);
             resmap.set(e.name, l);
         });
@@ -187,25 +502,7 @@ export namespace UserEnvVar {
             let minscore = 10;
             let bestCandidate: T | undefined;
             for (const e of candidates) {
-                // We use a score to enforce precedence:
-                //      value/value = 0
-                //      value/*     = 1
-                //      */value     = 2
-                //      */*         = 3
-                //      #/#         = 4 (used for env vars passed through the URL)
-                // the lower the score, the higher the precedence.
-                const [ownerPattern, repoPattern] = splitRepositoryPattern(e.repositoryPattern);
-                let score = 0;
-                if (repoPattern == "*") {
-                    score += 1;
-                }
-                if (ownerPattern == '*') {
-                    score += 2;
-                }
-                if (ownerPattern == "#" || repoPattern == "#") {
-                    score = 4;
-                }
-
+                const score = UserEnvVar.score(e);
                 if (!bestCandidate || score < minscore) {
                     minscore = score;
                     bestCandidate = e;
@@ -217,47 +514,109 @@ export namespace UserEnvVar {
         return result;
     }
 
-    function splitRepositoryPattern(repositoryPattern: string): string[] {
-        const patterns = repositoryPattern.split('/');
-        const repoPattern = patterns.pop() || "";
-        const ownerPattern = patterns.join('/');
+    // DEPRECATED: Use ProjectEnvVar instead of repositoryPattern - https://github.com/gitpod-com/gitpod/issues/5322
+    export function splitRepositoryPattern(repositoryPattern: string): string[] {
+        const patterns = repositoryPattern.split("/");
+        const repoPattern = patterns.slice(1).join("/");
+        const ownerPattern = patterns[0];
         return [ownerPattern, repoPattern];
     }
 }
 
-export interface GitpodToken {
+export interface SSHPublicKeyValue {
+    name: string;
+    key: string;
+}
+export interface UserSSHPublicKey extends SSHPublicKeyValue {
+    id: string;
+    key: string;
+    userId: string;
+    fingerprint: string;
+    creationTime: string;
+    lastUsedTime?: string;
+}
+
+export type UserSSHPublicKeyValue = Omit<UserSSHPublicKey, "userId">;
+
+export namespace SSHPublicKeyValue {
+    export function validate(value: SSHPublicKeyValue): string | undefined {
+        if (value.name.length === 0) {
+            return "Title must not be empty.";
+        }
+        if (value.name.length > 255) {
+            return "Title too long. Maximum value length is 255 characters.";
+        }
+        if (value.key.length === 0) {
+            return "Key must not be empty.";
+        }
+        try {
+            getData(value);
+        } catch (e) {
+            return "Key is invalid. You must supply a key in OpenSSH public key format.";
+        }
+        return;
+    }
+
+    export function getData(value: SSHPublicKeyValue) {
+        // Begins with 'ssh-rsa', 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384', 'ecdsa-sha2-nistp521', 'ssh-ed25519', 'sk-ecdsa-sha2-nistp256@openssh.com', or 'sk-ssh-ed25519@openssh.com'.
+        const regex =
+            /^(?<type>ssh-rsa|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521|ssh-ed25519|sk-ecdsa-sha2-nistp256@openssh\.com|sk-ssh-ed25519@openssh\.com) (?<key>.*?)( (?<email>.*?))?$/;
+        const resultGroup = regex.exec(value.key.trim());
+        if (!resultGroup) {
+            throw new Error("Key is invalid.");
+        }
+        return {
+            type: resultGroup.groups?.["type"] as string,
+            key: resultGroup.groups?.["key"] as string,
+            email: resultGroup.groups?.["email"] || undefined,
+        };
+    }
+
+    export function getFingerprint(value: SSHPublicKeyValue) {
+        const data = getData(value);
+        let buf = Buffer.from(data.key, "base64");
+        // gitlab style
+        // const hash = createHash("md5").update(buf).digest("hex");
+        // github style
+        const hash = createHash("sha256").update(buf).digest("base64");
+        return hash;
+    }
+
+    export const MAXIMUM_KEY_LENGTH = 5;
+}
 
+export interface GitpodToken {
     /** Hash value (SHA256) of the token (primary key). */
-    tokenHash: string
+    tokenHash: string;
 
     /** Human readable name of the token */
-    name?: string
+    name?: string;
 
     /** Token kind */
-    type: GitpodTokenType
+    type: GitpodTokenType;
 
     /** The user the token belongs to. */
-    user: User
-    
+    user: User;
+
     /** Scopes (e.g. limition to read-only) */
-    scopes: string[]
+    scopes: string[];
 
     /** Created timestamp */
-    created: string
-    
-    // token is deleted on the database and about to be collected by db-sync
-    deleted?: boolean
+    created: string;
+
+    // token is deleted on the database and about to be collected by periodic deleter
+    deleted?: boolean;
 }
 
 export enum GitpodTokenType {
     API_AUTH_TOKEN = 0,
-    MACHINE_AUTH_TOKEN = 1
+    MACHINE_AUTH_TOKEN = 1,
 }
 
 export interface OneTimeSecret {
-    id: string
+    id: string;
 
-    value: string
+    value: string;
 
     expirationTime: string;
 
@@ -289,13 +648,12 @@ export type IdentityLookup = Pick<Identity, "authProviderId" | "authId">;
 
 export namespace Identity {
     export function is(data: any): data is Identity {
-        return data.hasOwnProperty('authProviderId')
-            && data.hasOwnProperty('authId')
-            && data.hasOwnProperty('authName')
+        return (
+            data.hasOwnProperty("authProviderId") && data.hasOwnProperty("authId") && data.hasOwnProperty("authName")
+        );
     }
     export function equals(id1: IdentityLookup, id2: IdentityLookup) {
-        return id1.authProviderId === id2.authProviderId
-            && id1.authId === id2.authId
+        return id1.authProviderId === id2.authProviderId && id1.authId === id2.authId;
     }
 }
 
@@ -346,31 +704,35 @@ export interface PendingGithubEvent {
     creationDate: Date;
     type: string;
     event: string;
+    deleted: boolean;
 }
 
 export interface Snapshot {
     id: string;
     creationTime: string;
+    availableTime?: string;
     originalWorkspaceId: string;
     bucketId: string;
-    layoutData?: string;
+    state: SnapshotState;
+    message?: string;
 }
 
-export interface LayoutData {
-    workspaceId: string;
-    lastUpdatedTime: string;
-    layoutData: string;
-}
+export type SnapshotState = "pending" | "available" | "error";
 
 export interface Workspace {
     id: string;
     creationTime: string;
+    /**
+     * undefined means it is owned by the user (legacy mode, soon to be removed)
+     */
+    organizationId?: string;
     contextURL: string;
     description: string;
     ownerId: string;
+    projectId?: string;
     context: WorkspaceContext;
     config: WorkspaceConfig;
-    
+
     /**
      * The source where to get the workspace base image from. This source is resolved
      * during workspace creation. Once a base image has been built the information in here
@@ -382,18 +744,18 @@ export interface Workspace {
      * The resolved, fix name of the workspace image. We only use this
      * to access the logs during an image build.
      */
-    imageNameResolved?: string
+    imageNameResolved?: string;
 
     /**
      * The resolved/built fixed named of the base image. This field is only set if the workspace
      * already has its base image built.
      */
-    baseImageNameResolved?: string
+    baseImageNameResolved?: string;
 
     shareable?: boolean;
     pinned?: boolean;
 
-    // workspace is hard-deleted on the database and about to be collected by db-sync
+    // workspace is hard-deleted on the database and about to be collected by periodic deleter
     readonly deleted?: boolean;
 
     /**
@@ -422,20 +784,19 @@ export interface Workspace {
 
 export type WorkspaceSoftDeletion = "user" | "gc";
 
-export type WorkspaceType = "regular" | "prebuild" | "probe";
+export type WorkspaceType = "regular" | "prebuild";
 
 export namespace Workspace {
-
     export function getFullRepositoryName(ws: Workspace): string | undefined {
         if (CommitContext.is(ws.context)) {
-            return ws.context.repository.owner + '/' + ws.context.repository.name
+            return ws.context.repository.owner + "/" + ws.context.repository.name;
         }
         return undefined;
     }
 
     export function getFullRepositoryUrl(ws: Workspace): string | undefined {
         if (CommitContext.is(ws.context)) {
-            return `https://${ws.context.repository.host}/${getFullRepositoryName(ws)}`
+            return `https://${ws.context.repository.host}/${getFullRepositoryName(ws)}`;
         }
         return undefined;
     }
@@ -469,60 +830,85 @@ export namespace Workspace {
     }
 }
 
-export interface PreparePluginUploadParams {
-    fullPluginName: string;
+export interface GuessGitTokenScopesParams {
+    host: string;
+    repoUrl: string;
+    gitCommand: string;
+    currentToken: GitToken;
 }
 
-export interface ResolvePluginsParams {
-    config?: WorkspaceConfig
-    builtins?: ResolvedPlugins
+export interface GitToken {
+    token: string;
+    user: string;
+    scopes: string[];
 }
 
-export interface InstallPluginsParams {
-    pluginIds: string[]
+export interface GuessedGitTokenScopes {
+    message?: string;
+    scopes?: string[];
 }
 
-export interface UninstallPluginParams {
-    pluginId: string;
+export interface VSCodeConfig {
+    extensions?: string[];
 }
 
-export type ResolvedPluginKind = 'user' | 'workspace' | 'builtin';
-
-export interface ResolvedPlugins {
-    [pluginId: string]: ResolvedPlugin | undefined
+export interface JetBrainsConfig {
+    intellij?: JetBrainsProductConfig;
+    goland?: JetBrainsProductConfig;
+    pycharm?: JetBrainsProductConfig;
+    phpstorm?: JetBrainsProductConfig;
+    rubymine?: JetBrainsProductConfig;
+    webstorm?: JetBrainsProductConfig;
+    rider?: JetBrainsProductConfig;
+    clion?: JetBrainsProductConfig;
+}
+export interface JetBrainsProductConfig {
+    prebuilds?: JetBrainsPrebuilds;
+    vmoptions?: string;
+}
+export interface JetBrainsPrebuilds {
+    version?: "stable" | "latest" | "both";
 }
 
-export interface ResolvedPlugin {
-    fullPluginName: string;
+export interface RepositoryCloneInformation {
     url: string;
-    kind: ResolvedPluginKind;
+    checkoutLocation?: string;
 }
 
-export interface VSCodeConfig {
-    extensions?: string[];
+export interface CoreDumpConfig {
+    enabled?: boolean;
+    softLimit?: number;
+    hardLimit?: number;
 }
 
 export interface WorkspaceConfig {
+    mainConfiguration?: string;
+    additionalRepositories?: RepositoryCloneInformation[];
     image?: ImageConfig;
     ports?: PortConfig[];
     tasks?: TaskConfig[];
     checkoutLocation?: string;
     workspaceLocation?: string;
-    privileged?: boolean;
     gitConfig?: { [config: string]: string };
     github?: GithubAppConfig;
     vscode?: VSCodeConfig;
-    ide?: 'theia' | 'code' | string;
+    jetbrains?: JetBrainsConfig;
+    coreDump?: CoreDumpConfig;
+    ideCredentials?: string;
+
+    /** deprecated. Enabled by default **/
+    experimentalNetwork?: boolean;
 
     /**
      * Where the config object originates from.
-     * 
+     *
      * repo - from the repository
      * definitly-gp - from github.com/gitpod-io/definitely-gp
      * derived - computed based on analyzing the repository
+     * additional-content - config comes from additional content, usually provided through the project's configuration
      * default - our static catch-all default config
      */
-    _origin?: 'repo' | 'definitely-gp' | 'derived' | 'default';
+    _origin?: "repo" | "definitely-gp" | "derived" | "additional-content" | "default";
 
     /**
      * Set of automatically infered feature flags. That's not something the user can set, but
@@ -532,37 +918,33 @@ export interface WorkspaceConfig {
 }
 
 export interface GithubAppConfig {
-    prebuilds?: GithubAppPrebuildConfig
+    prebuilds?: GithubAppPrebuildConfig;
 }
 export interface GithubAppPrebuildConfig {
-    master?: boolean
-    branches?: boolean
-    pullRequests?: boolean
-    pullRequestsFromForks?: boolean
-    addCheck?: boolean
-    addBadge?: boolean
-    addLabel?: boolean | string
-    addComment?: boolean
+    master?: boolean;
+    branches?: boolean;
+    pullRequests?: boolean;
+    pullRequestsFromForks?: boolean;
+    addCheck?: boolean | "prevent-merge-on-error";
+    addBadge?: boolean;
+    addLabel?: boolean | string;
+    addComment?: boolean;
 }
 export namespace GithubAppPrebuildConfig {
     export function is(obj: boolean | GithubAppPrebuildConfig): obj is GithubAppPrebuildConfig {
-        return !(typeof obj === 'boolean');
+        return !(typeof obj === "boolean");
     }
 }
 
 export type WorkspaceImageSource = WorkspaceImageSourceDocker | WorkspaceImageSourceReference;
 export interface WorkspaceImageSourceDocker {
-    // TODO: clean this up. We should have the commit and an ImageSource in here, not duplicate the whole thing again.
-    //       We have a ton of those objects in the database, thus cleaning this up means lengthy DB migrations. Yuck.
-    dockerFileHash: string
-    dockerFileSource: Commit
-    dockerFilePath: string
+    dockerFilePath: string;
+    dockerFileHash: string;
+    dockerFileSource?: Commit;
 }
 export namespace WorkspaceImageSourceDocker {
     export function is(obj: object): obj is WorkspaceImageSourceDocker {
-        return 'dockerFileHash' in obj
-            && 'dockerFileSource' in obj
-            && 'dockerFilePath' in obj;
+        return "dockerFileHash" in obj && "dockerFilePath" in obj;
     }
 }
 export interface WorkspaceImageSourceReference {
@@ -571,34 +953,45 @@ export interface WorkspaceImageSourceReference {
 }
 export namespace WorkspaceImageSourceReference {
     export function is(obj: object): obj is WorkspaceImageSourceReference {
-        return 'baseImageResolved' in obj;
+        return "baseImageResolved" in obj;
     }
 }
 
-export type PrebuiltWorkspaceState
+export type PrebuiltWorkspaceState =
     // the prebuild is queued and may start at anytime
-    = "queued"
+    | "queued"
     // the workspace prebuild is currently running (i.e. there's a workspace pod deployed)
     | "building"
-    // the prebuild failed due to some issue with the system (e.g. missed a message, could not start workspace)
+    // the prebuild was aborted
     | "aborted"
     // the prebuild timed out
     | "timeout"
-    // the prebuild has finished and a snapshot is available
-    | "available";
+    // the prebuild has finished (even if a headless task failed) and a snapshot is available
+    | "available"
+    // the prebuild (headless workspace) failed due to some system error
+    | "failed";
 
 export interface PrebuiltWorkspace {
     id: string;
     cloneURL: string;
+    branch?: string;
+    projectId?: string;
     commit: string;
     buildWorkspaceId: string;
     creationTime: string;
     state: PrebuiltWorkspaceState;
+    statusVersion: number;
     error?: string;
     snapshot?: string;
 }
 
 export namespace PrebuiltWorkspace {
+    export function isDone(pws: PrebuiltWorkspace) {
+        return (
+            pws.state === "available" || pws.state === "timeout" || pws.state === "aborted" || pws.state === "failed"
+        );
+    }
+
     export function isAvailable(pws: PrebuiltWorkspace) {
         return pws.state === "available" && !!pws.snapshot;
     }
@@ -615,27 +1008,33 @@ export interface PrebuiltWorkspaceUpdatable {
     repo: string;
     isResolved: boolean;
     installationId: string;
+    /**
+     * the commitSHA of the commit that triggered the prebuild
+     */
+    commitSHA?: string;
     issue?: string;
     contextUrl?: string;
 }
 
 export interface WhitelistedRepository {
-    url: string
-    name: string
-    description?: string
-    avatar?: string
+    url: string;
+    name: string;
+    description?: string;
+    avatar?: string;
 }
 
-export type PortOnOpen = 'open-browser' | 'open-preview' | 'notify' | 'ignore';
+export type PortOnOpen = "open-browser" | "open-preview" | "notify" | "ignore";
 
 export interface PortConfig {
     port: number;
     onOpen?: PortOnOpen;
     visibility?: PortVisibility;
+    description?: string;
+    name?: string;
 }
 export namespace PortConfig {
     export function is(config: any): config is PortConfig {
-        return config && ('port' in config) && (typeof config.port === 'number');
+        return config && "port" in config && typeof config.port === "number";
     }
 }
 
@@ -645,7 +1044,7 @@ export interface PortRangeConfig {
 }
 export namespace PortRangeConfig {
     export function is(config: any): config is PortRangeConfig {
-        return config && ('port' in config) && (typeof config.port === 'string' || config.port instanceof String);
+        return config && "port" in config && (typeof config.port === "string" || config.port instanceof String);
     }
 }
 
@@ -655,33 +1054,32 @@ export interface TaskConfig {
     init?: string;
     prebuild?: string;
     command?: string;
-    env?: { [env: string]: string };
-    openIn?: 'bottom' | 'main' | 'left' | 'right';
-    openMode?: 'split-top' | 'split-left' | 'split-right' | 'split-bottom' | 'tab-before' | 'tab-after';
+    env?: { [env: string]: any };
+    openIn?: "bottom" | "main" | "left" | "right";
+    openMode?: "split-top" | "split-left" | "split-right" | "split-bottom" | "tab-before" | "tab-after";
 }
 
 export namespace TaskConfig {
     export function is(config: any): config is TaskConfig {
-        return config
-            && ('command' in config || 'init' in config || 'before' in config);
+        return config && ("command" in config || "init" in config || "before" in config);
     }
 }
 
 export namespace WorkspaceImageBuild {
-    export type Phase = 'BaseImage' | 'GitpodLayer' | 'Error' | 'Done';
+    export type Phase = "BaseImage" | "GitpodLayer" | "Error" | "Done";
     export interface StateInfo {
-        phase: Phase
-        currentStep?: number
-        maxSteps?: number
+        phase: Phase;
+        currentStep?: number;
+        maxSteps?: number;
     }
     export interface LogContent {
-        text: string
-        upToLine?: number
-        isDiff?: boolean
+        text: string;
+        upToLine?: number;
+        isDiff?: boolean;
     }
     export type LogCallback = (info: StateInfo, content: LogContent | undefined) => void;
     export namespace LogLine {
-        export const DELIMITER = '\r\n';
+        export const DELIMITER = "\r\n";
         export const DELIMITER_REGEX = /\r?\n/;
     }
 }
@@ -690,20 +1088,18 @@ export type ImageConfig = ImageConfigString | ImageConfigFile;
 export type ImageConfigString = string;
 export namespace ImageConfigString {
     export function is(config: ImageConfig | undefined): config is ImageConfigString {
-        return typeof config === 'string';
+        return typeof config === "string";
     }
-
 }
 export interface ImageConfigFile {
     // Path to the Dockerfile relative to repository root
-    file: string,
+    file: string;
     // Path to the docker build context relative to repository root
-    context?: string
+    context?: string;
 }
 export namespace ImageConfigFile {
     export function is(config: ImageConfig | undefined): config is ImageConfigFile {
-        return typeof config === 'object'
-            && 'file' in config;
+        return typeof config === "object" && "file" in config;
     }
 }
 export interface ExternalImageConfigFile extends ImageConfigFile {
@@ -711,22 +1107,22 @@ export interface ExternalImageConfigFile extends ImageConfigFile {
 }
 export namespace ExternalImageConfigFile {
     export function is(config: any | undefined): config is ExternalImageConfigFile {
-        return typeof config === 'object'
-            && 'file' in config
-            && 'externalSource' in config;
+        return typeof config === "object" && "file" in config && "externalSource" in config;
     }
 }
 
 export interface WorkspaceContext {
     title: string;
+    ref?: string;
+    /** This contains the URL portion of the contextURL (which might contain other modifiers as well). It's optional because it's not set for older workspaces. */
     normalizedContextURL?: string;
     forceCreateNewWorkspace?: boolean;
+    forceImageBuild?: boolean;
 }
 
 export namespace WorkspaceContext {
     export function is(context: any): context is WorkspaceContext {
-        return context
-            && 'title' in context;
+        return context && "title" in context;
     }
 }
 
@@ -735,22 +1131,38 @@ export interface WithSnapshot {
 }
 export namespace WithSnapshot {
     export function is(context: any): context is WithSnapshot {
-        return context
-            && 'snapshotBucketId' in context;
+        return context && "snapshotBucketId" in context;
     }
 }
 
-export interface WithPrebuild {
-    snapshotBucketId: string;
+export interface WithPrebuild extends WithSnapshot {
     prebuildWorkspaceId: string;
     wasPrebuilt: true;
 }
 export namespace WithPrebuild {
     export function is(context: any): context is WithPrebuild {
-        return context
-            && 'snapshotBucketId' in context
-            && 'prebuildWorkspaceId' in context
-            && 'wasPrebuilt' in context;
+        return context && WithSnapshot.is(context) && "prebuildWorkspaceId" in context && "wasPrebuilt" in context;
+    }
+}
+
+/**
+ * WithDefaultConfig contexts disable the download of the gitpod.yml from the repository
+ * and fall back to the built-in configuration.
+ */
+export interface WithDefaultConfig {
+    withDefaultConfig: true;
+}
+
+export namespace WithDefaultConfig {
+    export function is(context: any): context is WithDefaultConfig {
+        return context && "withDefaultConfig" in context && context.withDefaultConfig;
+    }
+
+    export function mark(ctx: WorkspaceContext): WorkspaceContext & WithDefaultConfig {
+        return {
+            ...ctx,
+            withDefaultConfig: true,
+        };
     }
 }
 
@@ -760,20 +1172,27 @@ export interface SnapshotContext extends WorkspaceContext, WithSnapshot {
 
 export namespace SnapshotContext {
     export function is(context: any): context is SnapshotContext {
-        return context 
-            && WithSnapshot.is(context)
-            && 'snapshotId' in context;
+        return context && WithSnapshot.is(context) && "snapshotId" in context;
     }
 }
 
-export interface StartPrebuildContext extends WorkspaceContext {
+export interface WithCommitHistory {
+    commitHistory?: string[];
+    additionalRepositoryCommitHistories?: {
+        cloneUrl: string;
+        commitHistory: string[];
+    }[];
+}
+
+export interface StartPrebuildContext extends WorkspaceContext, WithCommitHistory {
     actual: WorkspaceContext;
+    project: Project;
+    branch?: string;
 }
 
 export namespace StartPrebuildContext {
     export function is(context: any): context is StartPrebuildContext {
-        return context
-            && 'actual' in context;
+        return context && "actual" in context;
     }
 }
 
@@ -785,33 +1204,28 @@ export interface PrebuiltWorkspaceContext extends WorkspaceContext {
 
 export namespace PrebuiltWorkspaceContext {
     export function is(context: any): context is PrebuiltWorkspaceContext {
-        return context
-            && 'originalContext' in context
-            && 'prebuiltWorkspace' in context;
+        return context && "originalContext" in context && "prebuiltWorkspace" in context;
     }
 }
 
-export interface WithEnvvarsContext extends WorkspaceContext {
-    envvars: UserEnvVarValue[];
+export interface WithReferrerContext extends WorkspaceContext {
+    referrer: string;
+    referrerIde?: string;
 }
 
-export namespace WithEnvvarsContext {
-    export function is(context: any): context is WithEnvvarsContext {
-        return context
-            && 'envvars' in context
+export namespace WithReferrerContext {
+    export function is(context: any): context is WithReferrerContext {
+        return context && "referrer" in context;
     }
 }
 
-export interface WorkspaceProbeContext extends WorkspaceContext {
-    responseURL: string
-    responseToken: string
+export interface WithEnvvarsContext extends WorkspaceContext {
+    envvars: EnvVarWithValue[];
 }
 
-export namespace WorkspaceProbeContext {
-    export function is(context: any): context is WorkspaceProbeContext {
-        return context
-            && 'responseURL' in context
-            && 'responseToken' in context;
+export namespace WithEnvvarsContext {
+    export function is(context: any): context is WithEnvvarsContext {
+        return context && "envvars" in context;
     }
 }
 
@@ -823,30 +1237,90 @@ export namespace RefType {
         }
         // This fallback is meant to handle the cases where (for historic reasons) ref is present but refType is missing
         return commit.refType || "branch";
-    }
+    };
 }
 
 export interface Commit {
-    repository: Repository
-    revision: string
+    repository: Repository;
+    revision: string;
 
     // Might contain either a branch or a tag (determined by refType)
-    ref?: string
+    ref?: string;
 
     // refType is only set if ref is present (and not for old workspaces, before this feature was added)
-    refType?: RefType
+    refType?: RefType;
 }
 
-export interface CommitContext extends WorkspaceContext, Commit {
+export interface AdditionalContentContext extends WorkspaceContext {
+    /**
+     * utf-8 encoded contents that will be copied on top of the workspace's filesystem
+     */
+    additionalFiles: { [filePath: string]: string };
+}
+
+export namespace AdditionalContentContext {
+    export function is(ctx: any): ctx is AdditionalContentContext {
+        return "additionalFiles" in ctx;
+    }
+
+    export function hasDockerConfig(ctx: any, config: WorkspaceConfig): boolean {
+        return is(ctx) && ImageConfigFile.is(config.image) && !!ctx.additionalFiles[config.image.file];
+    }
+}
+
+export interface OpenPrebuildContext extends WorkspaceContext {
+    openPrebuildID: string;
+}
+
+export namespace OpenPrebuildContext {
+    export function is(ctx: any): ctx is OpenPrebuildContext {
+        return "openPrebuildID" in ctx;
+    }
+}
+
+export interface CommitContext extends WorkspaceContext, GitCheckoutInfo {
     /** @deprecated Moved to .repository.cloneUrl, left here for backwards-compatibility for old workspace contextes in the DB */
-    cloneUrl?: string
+    cloneUrl?: string;
+
+    /**
+     * The clone and checkout information for additional repositories in case of multi-repo projects.
+     */
+    additionalRepositoryCheckoutInfo?: GitCheckoutInfo[];
+}
+
+export namespace CommitContext {
+    /**
+     * Creates a hash for all the commits of the CommitContext and all sub-repo commit infos.
+     * The hash is max 255 chars long.
+     * @param commitContext
+     * @returns hash for commitcontext
+     */
+    export function computeHash(commitContext: CommitContext): string {
+        // for single commits we use the revision to be backward compatible.
+        if (
+            !commitContext.additionalRepositoryCheckoutInfo ||
+            commitContext.additionalRepositoryCheckoutInfo.length === 0
+        ) {
+            return commitContext.revision;
+        }
+        const hasher = createHash("sha256");
+        hasher.update(commitContext.revision);
+        for (const info of commitContext.additionalRepositoryCheckoutInfo) {
+            hasher.update(info.revision);
+        }
+        return hasher.digest("hex");
+    }
+}
+
+export interface GitCheckoutInfo extends Commit {
+    checkoutLocation?: string;
+    upstreamRemoteURI?: string;
+    localBranch?: string;
 }
 
 export namespace CommitContext {
     export function is(commit: any): commit is CommitContext {
-        return WorkspaceContext.is(commit)
-            && 'repository' in commit
-            && 'revision' in commit
+        return WorkspaceContext.is(commit) && "repository" in commit && "revision" in commit;
     }
 }
 
@@ -854,17 +1328,14 @@ export interface PullRequestContext extends CommitContext {
     nr: number;
     ref: string;
     base: {
-        repository: Repository
-        ref: string
-    }
+        repository: Repository;
+        ref: string;
+    };
 }
 
 export namespace PullRequestContext {
     export function is(ctx: any): ctx is PullRequestContext {
-        return CommitContext.is(ctx)
-            && 'nr' in ctx
-            && 'ref' in ctx
-            && 'base' in ctx
+        return CommitContext.is(ctx) && "nr" in ctx && "ref" in ctx && "base" in ctx;
     }
 }
 
@@ -876,10 +1347,7 @@ export interface IssueContext extends CommitContext {
 
 export namespace IssueContext {
     export function is(ctx: any): ctx is IssueContext {
-        return CommitContext.is(ctx)
-            && 'nr' in ctx
-            && 'ref' in ctx
-            && 'localBranch' in ctx
+        return CommitContext.is(ctx) && "nr" in ctx && "ref" in ctx && "localBranch" in ctx;
     }
 }
 
@@ -890,9 +1358,7 @@ export interface NavigatorContext extends CommitContext {
 
 export namespace NavigatorContext {
     export function is(ctx: any): ctx is NavigatorContext {
-        return CommitContext.is(ctx)
-            && 'path' in ctx
-            && 'isFile' in ctx
+        return CommitContext.is(ctx) && "path" in ctx && "isFile" in ctx;
     }
 }
 
@@ -901,6 +1367,8 @@ export interface Repository {
     owner: string;
     name: string;
     cloneUrl: string;
+    /* Optional kind to differentiate between repositories of orgs/groups/projects and personal repos. */
+    repoKind?: string;
     description?: string;
     avatarUrl?: string;
     webUrl?: string;
@@ -909,8 +1377,21 @@ export interface Repository {
     private?: boolean;
     fork?: {
         // The direct parent of this fork
-        parent: Repository
-    }
+        parent: Repository;
+    };
+}
+export interface Branch {
+    name: string;
+    commit: CommitInfo;
+    htmlUrl: string;
+}
+
+export interface CommitInfo {
+    author: string;
+    sha: string;
+    commitMessage: string;
+    authorAvatarUrl?: string;
+    authorDate?: string;
 }
 
 export namespace Repository {
@@ -922,21 +1403,25 @@ export namespace Repository {
 export interface WorkspaceInstancePortsChangedEvent {
     type: "PortsChanged";
     instanceID: string;
-    portsOpened: number[]
-    portsClosed: number[]
+    portsOpened: number[];
+    portsClosed: number[];
 }
 
 export namespace WorkspaceInstancePortsChangedEvent {
-
     export function is(data: any): data is WorkspaceInstancePortsChangedEvent {
         return data && data.type == "PortsChanged";
     }
-
 }
 
 export interface WorkspaceInfo {
-    workspace: Workspace
-    latestInstance?: WorkspaceInstance
+    workspace: Workspace;
+    latestInstance?: WorkspaceInstance;
+}
+
+export namespace WorkspaceInfo {
+    export function lastActiveISODate(info: WorkspaceInfo): string {
+        return info.latestInstance?.creationTime || info.workspace.creationTime;
+    }
 }
 
 export type RunningWorkspaceInfo = WorkspaceInfo & { latestInstance: WorkspaceInstance };
@@ -946,34 +1431,25 @@ export interface WorkspaceCreationResult {
     workspaceURL?: string;
     existingWorkspaces?: WorkspaceInfo[];
     runningWorkspacePrebuild?: {
-        prebuildID: string
-        workspaceID: string
-        starting: RunningWorkspacePrebuildStarting
-        sameCluster: boolean
-    }
+        prebuildID: string;
+        workspaceID: string;
+        instanceID: string;
+        starting: RunningWorkspacePrebuildStarting;
+        sameCluster: boolean;
+    };
     runningPrebuildWorkspaceID?: string;
 }
-export type RunningWorkspacePrebuildStarting = 'queued' | 'starting' | 'running';
-
-export enum CreateWorkspaceMode {
-    // Default returns a running prebuild if there is any, otherwise creates a new workspace (using a prebuild if one is available)
-    Default = 'default',
-    // ForceNew creates a new workspace irrespective of any running prebuilds. This mode is guaranteed to actually create a workspace - but may degrade user experience as currently runnig prebuilds are ignored.
-    ForceNew = 'force-new',
-    // UsePrebuild polls the database waiting for a currently running prebuild to become available. This mode exists to handle the db-sync delay.
-    UsePrebuild = 'use-prebuild',
-    // SelectIfRunning returns a list of currently running workspaces for the context URL if there are any, otherwise falls back to Default mode
-    SelectIfRunning = 'select-if-running',
-}
+export type RunningWorkspacePrebuildStarting = "queued" | "starting" | "running";
 
 export namespace WorkspaceCreationResult {
     export function is(data: any): data is WorkspaceCreationResult {
-        return data && (
-            'createdWorkspaceId' in data
-            || 'existingWorkspaces' in data
-            || 'runningWorkspacePrebuild' in data
-            || 'runningPrebuildWorkspaceID' in data
-        )
+        return (
+            data &&
+            ("createdWorkspaceId" in data ||
+                "existingWorkspaces" in data ||
+                "runningWorkspacePrebuild" in data ||
+                "runningPrebuildWorkspaceID" in data)
+        );
     }
 }
 
@@ -993,6 +1469,7 @@ export interface AuthProviderInfo {
     readonly authProviderType: string;
     readonly host: string;
     readonly ownerId?: string;
+    readonly organizationId?: string;
     readonly verified: boolean;
     readonly isReadonly?: boolean;
     readonly hiddenOnDashboard?: boolean;
@@ -1007,7 +1484,7 @@ export interface AuthProviderInfo {
         readonly default: string[];
         readonly publicRepo: string[];
         readonly privateRepo: string[];
-    }
+    };
 }
 
 export interface AuthProviderEntry {
@@ -1015,10 +1492,13 @@ export interface AuthProviderEntry {
     readonly type: AuthProviderEntry.Type;
     readonly host: string;
     readonly ownerId: string;
+    readonly organizationId?: string;
 
     readonly status: AuthProviderEntry.Status;
 
     readonly oauth: OAuth2Config;
+    /** A random string that is to change whenever oauth changes (enforced on DB level) */
+    readonly oauthRevision?: string;
 }
 
 export interface OAuth2Config {
@@ -1031,47 +1511,35 @@ export interface OAuth2Config {
     readonly scopeSeparator?: string;
 
     readonly settingsUrl?: string;
-    readonly authorizationParams?: { [key: string]: string }
+    readonly authorizationParams?: { [key: string]: string };
     readonly configURL?: string;
 }
 
 export namespace AuthProviderEntry {
     export type Type = "GitHub" | "GitLab" | string;
     export type Status = "pending" | "verified";
-    export type NewEntry = Pick<AuthProviderEntry, "ownerId" | "host" | "type">;
-    export type UpdateEntry = Pick<AuthProviderEntry, "id" | "ownerId"> & Pick<OAuth2Config, "clientId" | "clientSecret">;
-}
-
-export interface Branding {
-    readonly name: string;
-    readonly favicon?: string;
-    /** Either including domain OR absolute path (interpreted relative to host URL) */
-    readonly logo: string;
-    readonly startupLogo: string;
-    readonly showProductivityTips: boolean;
-    readonly redirectUrlIfNotAuthenticated?: string;
-    readonly redirectUrlAfterLogout?: string;
-    readonly homepage: string;
-    readonly ide?: {
-        readonly logo: string;
-        readonly showReleaseNotes: boolean;
-        readonly helpMenu: Branding.Link[];
-    }
-    readonly links: {
-        readonly header: Branding.Link[];
-        readonly footer: Branding.Link[];
-        readonly social: Branding.SocialLink[];
-        readonly legal: Branding.Link[];
-    }
-}
-export namespace Branding {
-    export interface Link {
-        readonly name: string;
-        readonly url: string;
-    }
-    export interface SocialLink {
-        readonly type: string;
-        readonly url: string;
+    export type NewEntry = Pick<AuthProviderEntry, "ownerId" | "host" | "type"> & {
+        clientId?: string;
+        clientSecret?: string;
+    };
+    export type UpdateEntry = Pick<AuthProviderEntry, "id" | "ownerId"> &
+        Pick<OAuth2Config, "clientId" | "clientSecret">;
+    export type NewOrgEntry = NewEntry & {
+        organizationId: string;
+    };
+    export type UpdateOrgEntry = Pick<AuthProviderEntry, "id"> & {
+        clientId: string;
+        clientSecret: string;
+        organizationId: string;
+    };
+    export function redact(entry: AuthProviderEntry): AuthProviderEntry {
+        return {
+            ...entry,
+            oauth: {
+                ...entry.oauth,
+                clientSecret: "redacted",
+            },
+        };
     }
 }
 
@@ -1100,3 +1568,23 @@ export namespace TheiaPlugin {
         CheckinFailed = "checkin-failed",
     }
 }
+
+export interface TermsAcceptanceEntry {
+    readonly userId: string;
+    readonly termsRevision: string;
+    readonly acceptionTime: string;
+}
+
+export interface Terms {
+    readonly revision: string;
+    readonly activeSince: string;
+    readonly adminOnlyTerms: boolean;
+    readonly updateMessage: string;
+    readonly content: string;
+    readonly formElements?: object;
+}
+
+export interface StripeConfig {
+    individualUsagePriceIds: { [currency: string]: string };
+    teamUsagePriceIds: { [currency: string]: string };
+}