@highstate/backend 0.9.15 → 0.9.16

package/src/business/project-unlock.ts

@@ -0,0 +1,242 @@
+import type { StateBatch, StateManager } from "../state"
+import type { Logger } from "pino"
+import type { HotStateManager } from "../hotstate"
+import type { PubSubManager } from "../pubsub"
+import { randomBytes } from "node:crypto"
+import { armor, Decrypter, Encrypter } from "age-encryption"
+import { type ProjectUnlockState, type UnlockMethod } from "../shared"
+
+type UnlockTask = {
+  name: string
+  handler: (projectId: string) => Promise<void> | void
+}
+
+export class ProjectUnlockService {
+  constructor(
+    private readonly stateManager: StateManager,
+    private readonly hotStateManager: HotStateManager,
+    private readonly pubsubManager: PubSubManager,
+    private readonly logger: Logger,
+  ) {}
+
+  private readonly unlockTasks: UnlockTask[] = []
+
+  /**
+   * Checks if the project is unlocked.
+   * A project is considered locked if it has no master key set in memory.
+   *
+   * @param projectId The ID of the project to check.
+   * @returns True if the project is locked, false otherwise.
+   */
+  async isProjectUnlocked(projectId: string): Promise<boolean> {
+    return await this.hotStateManager.exists(["project-master-key", projectId])
+  }
+
+  /**
+   * Gets the current unlock state of the project.
+   * If the project is unlocked, it returns an object with type "unlocked".
+   * If the project is locked, it returns an object with type "locked" and the unlock suite.
+   *
+   * @param projectId The ID of the project to get the unlock state for.
+   * @returns The unlock state of the project.
+   */
+  async getProjectUnlockState(projectId: string): Promise<ProjectUnlockState> {
+    const isUnlocked = await this.isProjectUnlocked(projectId)
+    if (isUnlocked) {
+      return { type: "unlocked" }
+    }
+
+    const unlockSuite = await this.stateManager.getProjectUnlockSuiteRepository().get(projectId)
+    return {
+      type: "locked",
+      unlockSuite,
+    }
+  }
+
+  /**
+   * Creates a new project state and generates a master key for it.
+   *
+   * @param projectId The ID of the project to create the state for.
+   * @param unlockMethod The unlock method to use to encrypt the master key. Should be provided by the frontend.
+   */
+  async createProjectState(projectId: string, unlockMethod: UnlockMethod): Promise<void> {
+    const masterKey = randomBytes(32)
+    await using batch = this.stateManager.batch()
+
+    // unlock the project by storing the master key in memory
+    await this.hotStateManager.set(["project-master-key", projectId], masterKey)
+
+    // store the master key in the backend
+    await this.updateUnlockSuite(projectId, [unlockMethod], batch)
+    await this.updateEncryptedMasterKey(projectId, [unlockMethod], batch, masterKey)
+
+    // persist the unlock method as any other project data
+    await this.stateManager
+      .getUnlockMethodRepository(projectId)
+      .put(unlockMethod.id, unlockMethod, batch)
+
+    await batch.write()
+  }
+
+  /**
+   * Unlocks the project state using the provided identity.
+   *
+   * @param projectId The ID of the project to unlock.
+   * @param decryptedIdentity The decrypted identity to use for unlocking the project. Should be provided by the frontend.
+   */
+  async unlockProject(projectId: string, decryptedIdentity: string): Promise<void> {
+    if (await this.isProjectUnlocked(projectId)) {
+      this.logger.warn(
+        { projectId },
+        `project "%s" is already unlocked, skipping unlock operation`,
+        projectId,
+      )
+      return
+    }
+
+    // load the encrypted master key for the project
+    const armoredMasterKey = await this.stateManager.getProjectMasterKeyRepository().get(projectId)
+    if (!armoredMasterKey) {
+      throw new Error(`Project ${projectId} does not have a master key set.`)
+    }
+
+    const encryptedMasterKey = armor.decode(armoredMasterKey)
+
+    const decrypter = new Decrypter()
+    decrypter.addIdentity(decryptedIdentity)
+
+    // decrypt the master key using the provided identity
+    const masterKey = await decrypter.decrypt(encryptedMasterKey)
+
+    // store the master key in memory to unlock the project
+    await this.hotStateManager.set(["project-master-key", projectId], masterKey)
+
+    // load instance states to the hot state
+    // TODO: this should be done by something else, ideally lazy-loaded when needed
+    const instanceStates = await this.stateManager
+      .getInstanceStateRepository(projectId)
+      .getAllItems()
+
+    await this.hotStateManager.hmset(
+      ["instance-states", projectId],
+      instanceStates.map(state => [state.id, state]),
+    )
+
+    await this.pubsubManager.publish(["project-unlock-state", projectId], { type: "unlocked" })
+
+    // run unlock tasks
+    await this.runUnlockTasks(projectId)
+  }
+
+  private async runUnlockTasks(projectId: string): Promise<void> {
+    for (const task of this.unlockTasks) {
+      try {
+        await task.handler(projectId)
+      } catch (error) {
+        this.logger.error({ error }, `unlock task "%s" failed`, task.name)
+      }
+    }
+  }
+
+  /**
+   * Adds a new unlock method to the project and updates the master identity set.
+   * The project must be unlocked.
+   *
+   * @param projectId The ID of the project to add the unlock method to.
+   * @param unlockMethod The unlock method to add. Should be provided by the frontend.
+   */
+  async addProjectUnlockMethod(projectId: string, unlockMethod: UnlockMethod): Promise<void> {
+    await using batch = this.stateManager.batch()
+
+    // add the unlock method to the repository
+    await this.stateManager
+      .getUnlockMethodRepository(projectId)
+      .put(unlockMethod.id, unlockMethod, batch)
+
+    // get all existing unlock methods
+    const existingMethods = await this.stateManager
+      .getUnlockMethodRepository(projectId)
+      .getAllItems()
+
+    // update the encrypted master identity set and master key
+    await this.updateUnlockSuite(projectId, existingMethods, batch)
+    await this.updateEncryptedMasterKey(projectId, existingMethods, batch)
+  }
+
+  /**
+   * Removes an unlock method from the project and updates the master identity set.
+   * The project must be unlocked.
+   *
+   * @param projectId The ID of the project to remove the unlock method from.
+   * @param unlockMethodId The ID of the unlock method to remove.
+   */
+  async removeProjectUnlockMethod(projectId: string, unlockMethodId: string): Promise<void> {
+    await using batch = this.stateManager.batch()
+
+    // get all existing unlock methods
+    let existingMethods = await this.stateManager.getUnlockMethodRepository(projectId).getAllItems()
+
+    // do not allow removing the last unlock method under any circumstances
+    if (existingMethods.length === 1) {
+      throw new Error("Rejected removing the last unlock method!")
+    }
+
+    // remove the unlock method from the repository
+    await this.stateManager.getUnlockMethodRepository(projectId).delete(unlockMethodId, batch)
+    existingMethods = existingMethods.filter(method => method.id !== unlockMethodId)
+
+    // update the encrypted master identity set and master key
+    await this.updateUnlockSuite(projectId, existingMethods, batch)
+    await this.updateEncryptedMasterKey(projectId, existingMethods, batch)
+
+    await batch.write()
+  }
+
+  /**
+   * Registers a new unlock task that will be executed when the project is unlocked.
+   * This can be used to perform additional actions after unlocking, such as loading instance states.
+   *
+   * @param name The name of the unlock task.
+   * @param handler The handler function for the unlock task. It receives the project ID as an argument.
+   */
+  registerUnlockTask(name: string, handler: (projectId: string) => Promise<void> | void): void {
+    this.unlockTasks.push({ name, handler })
+  }
+
+  private async updateUnlockSuite(
+    projectId: string,
+    unlockMethods: UnlockMethod[],
+    batch: StateBatch,
+  ): Promise<void> {
+    // write new encrypted master identity set
+    await this.stateManager.getProjectUnlockSuiteRepository().put(
+      projectId,
+      {
+        encryptedIdentities: unlockMethods.map(method => method.encryptedIdentity),
+        hasPasskey: unlockMethods.some(method => method.type === "passkey"),
+      },
+      batch,
+    )
+  }
+
+  private async updateEncryptedMasterKey(
+    projectId: string,
+    unlockMethods: UnlockMethod[],
+    batch: StateBatch,
+    masterKey?: Uint8Array,
+  ): Promise<void> {
+    masterKey ??= await this.stateManager.getProjectMasterKey(projectId)
+
+    const encrypter = new Encrypter()
+    for (const method of unlockMethods) {
+      encrypter.addRecipient(method.recipient)
+    }
+
+    // encrypt the master key for all unlock methods
+    const encryptedMasterKey = await encrypter.encrypt(masterKey)
+
+    // set the encrypted master key in the backend
+    const armoredMasterKey = armor.encode(encryptedMasterKey)
+    await this.stateManager.getProjectMasterKeyRepository().put(projectId, armoredMasterKey, batch)
+  }
+}

package/src/business/secret.ts

@@ -0,0 +1,187 @@
+import type { Logger } from "pino"
+import type { LibraryBackend } from "../library"
+import type { ProjectBackend } from "../project"
+import type { StateManager } from "../state"
+import type { InstanceStateService } from "./instance-state"
+import { v7 as uuidv7 } from "uuid"
+import { isUnitModel, parseInstanceId } from "@highstate/contract"
+import { formatSecretDescriptor, type Secret, type SecretDescriptor } from "../shared"
+
+export class SecretService {
+  constructor(
+    private readonly stateManager: StateManager,
+    private readonly libraryBackend: LibraryBackend,
+    private readonly projectBackend: ProjectBackend,
+    private readonly instanceStateService: InstanceStateService,
+    private readonly logger: Logger,
+  ) {}
+
+  /**
+   * Updates secrets for a specific instance, handling both creation/updates and deletions.
+   * Also updates the instance state's secretNames field.
+   *
+   * @param projectId The project ID.
+   * @param instanceId The instance ID.
+   * @param changedSecretValues The secrets to create or update.
+   * @param deletedSecretNames The names of secrets to delete.
+   * @param invalidateState Whether to invalidate the instance state after updating secrets.
+   */
+  async updateInstanceSecrets(
+    projectId: string,
+    instanceId: string,
+    changedSecretValues: Record<string, unknown>,
+    deletedSecretNames: string[],
+    invalidateState = true,
+  ): Promise<void> {
+    const projectInfo = await this.projectBackend.getProjectInfo(projectId)
+    const library = await this.libraryBackend.loadLibrary(projectInfo.libraryId)
+
+    const [type] = parseInstanceId(instanceId)
+    const component = library.components[type]
+    if (!component) {
+      throw new Error(`Component type ${type} not found in library`)
+    }
+
+    if (!isUnitModel(component)) {
+      throw new Error(`Component type ${type} is not a unit model`)
+    }
+
+    // validate changed secrets
+    for (const secretName of Object.keys(changedSecretValues)) {
+      if (!component.secrets[secretName]) {
+        throw new Error(`Secret ${secretName} not found in component ${type}`)
+      }
+    }
+
+    // validate deleted secrets
+    for (const secretName of deletedSecretNames) {
+      if (!component.secrets[secretName]) {
+        throw new Error(`Secret ${secretName} not found in component ${type}`)
+      }
+    }
+
+    // use a batch for atomic operations
+    await using batch = this.stateManager.batch()
+
+    const secretRepo = this.stateManager.getSecretRepository(projectId)
+    const secretContentRepo = this.stateManager.getSecretContentRepository(projectId)
+    const indexRepo = this.stateManager.createSecretIndexRepository(projectId)
+
+    // process changed secrets
+    for (const [secretName, value] of Object.entries(changedSecretValues)) {
+      const descriptor: SecretDescriptor = { type: "instance", instanceId, secretName }
+      const indexKey = formatSecretDescriptor(descriptor)
+
+      // check if secret already exists
+      const existingSecret = await indexRepo.get(indexKey)
+
+      // create or update secret info
+      const secret: Secret = {
+        id: existingSecret?.id ?? uuidv7(),
+        descriptor: descriptor,
+        meta: {
+          ...existingSecret?.meta,
+          ...component.secrets[secretName].meta,
+          icon: component.secrets[secretName].meta.primaryIcon ?? component.meta.primaryIcon,
+        },
+      }
+
+      // store secret info and content
+      await secretRepo.putItem(secret, batch)
+      await secretContentRepo.put(indexKey, value, batch)
+
+      // update index mapping
+      await indexRepo.indexRepository.put(indexKey, secret.id, batch)
+    }
+
+    // process deleted secrets
+    for (const secretName of deletedSecretNames) {
+      const indexKey = formatSecretDescriptor({ type: "instance", instanceId, secretName })
+
+      // get the secret ID from index
+      const secretId = await indexRepo.indexRepository.get(indexKey)
+      if (secretId) {
+        // delete secret info, content, and index entry
+        await secretRepo.delete(secretId, batch)
+        await secretContentRepo.delete(indexKey, batch)
+        await indexRepo.indexRepository.delete(indexKey, batch)
+      }
+    }
+
+    // write all changes atomically
+    await batch.write()
+
+    // update instance state secretNames
+    await this.instanceStateService.updateStateSecretNames(
+      projectId,
+      instanceId,
+      Object.keys(changedSecretValues),
+      deletedSecretNames,
+      invalidateState,
+    )
+
+    this.logger.info(
+      {
+        projectId,
+        instanceId,
+        changedCount: Object.keys(changedSecretValues).length,
+        deletedCount: deletedSecretNames.length,
+      },
+      "updated instance secrets for instance %s in project %s",
+      instanceId,
+      projectId,
+    )
+  }
+
+  /**
+   * Gets the secrets for a specific instance.
+   *
+   * @param projectId The project ID.
+   * @param instanceId The instance ID.
+   * @returns A record of secret key-value pairs.
+   */
+  async getInstanceSecrets(
+    projectId: string,
+    instanceId: string,
+  ): Promise<Record<string, unknown>> {
+    const projectInfo = await this.projectBackend.getProjectInfo(projectId)
+    const library = await this.libraryBackend.loadLibrary(projectInfo.libraryId)
+
+    const [type] = parseInstanceId(instanceId)
+    const component = library.components[type]
+    if (!component) {
+      throw new Error(`Component type ${type} not found in library`)
+    }
+
+    if (!isUnitModel(component)) {
+      throw new Error(`Component type ${type} is not a unit model`)
+    }
+
+    const secretNames = Object.keys(component.secrets)
+    if (secretNames.length === 0) {
+      return {}
+    }
+
+    // get all index keys for this instance's secrets
+    const indexKeys = secretNames.map(secretName =>
+      formatSecretDescriptor({ type: "instance", instanceId, secretName }),
+    )
+
+    // get the secret contents using the formatted secret IDs directly
+    const secretContentsMap = await this.stateManager
+      .getSecretContentRepository(projectId)
+      .getManyRecord(indexKeys)
+
+    // build the result mapping secret names to values
+    const secrets: Record<string, unknown> = {}
+    for (const secretName of secretNames) {
+      const indexKey = formatSecretDescriptor({ type: "instance", instanceId, secretName })
+      const value = secretContentsMap[indexKey]
+      if (value) {
+        secrets[secretName] = value
+      }
+    }
+
+    return secrets
+  }
+}

package/src/business/worker.ts

@@ -0,0 +1,161 @@
+import type { Logger } from "pino"
+import type { LockManager } from "../lock"
+import type { WorkerManager } from "../worker"
+import type { InstanceStateService } from "./instance-state"
+import { randomBytes } from "node:crypto"
+import { v7 as uuidv7 } from "uuid"
+import {
+  getWorkerIdentity,
+  type InstanceState,
+  type ProjectApiKey,
+  type ServiceAccount,
+  type UnitWorker,
+  type Worker,
+  type WorkerUnitRegistration,
+} from "../shared"
+import { SAME_KEY, type StateManager } from "../state"
+
+export class WorkerService {
+  constructor(
+    private readonly stateManager: StateManager,
+    private readonly workerManager: WorkerManager,
+    private readonly lockManager: LockManager,
+    private readonly instanceStateService: InstanceStateService,
+    private readonly logger: Logger,
+  ) {}
+
+  async handleUnitWorker(
+    projectId: string,
+    state: InstanceState,
+    unitWorker: UnitWorker,
+  ): Promise<void> {
+    await this.lockManager.acquire(["worker-image", projectId, unitWorker.image], async () => {
+      const existingRegistrations = await this.stateManager
+        .getWorkerRegistrationRepository(projectId)
+        .getManyItems(state.extra?.workerRegistrationIds ?? [])
+
+      const existingReg = existingRegistrations.find(reg => reg.image === unitWorker.image)
+      if (existingReg && JSON.stringify(existingReg.params) === JSON.stringify(unitWorker.params)) {
+        this.logger.debug(
+          `instance "%s" already registered with worker "%s" with the same parameters`,
+          state.id,
+          unitWorker.image,
+        )
+        return
+      }
+
+      let workerId = existingReg?.workerId
+      if (!workerId) {
+        workerId = await this.ensureWorkerCreated(projectId, unitWorker)
+      }
+
+      const registration: WorkerUnitRegistration = {
+        id: existingReg?.id ?? uuidv7(),
+        meta: existingReg?.meta ?? {},
+        image: unitWorker.image,
+        params: unitWorker.params,
+        instanceId: state.id,
+        workerId,
+      }
+
+      const batch = this.stateManager.batch()
+
+      await this.stateManager
+        .getWorkerRegistrationRepository(projectId)
+        .putItem(registration, batch)
+
+      if (!existingReg) {
+        // update the index if this is a new registration
+        await this.stateManager
+          .getWorkerRegistrationIndexRepository(projectId, workerId)
+          .indexRepository.put(registration.id, SAME_KEY, batch)
+
+        // update the instance state with the new registration ID
+        await this.instanceStateService.patchInstanceState(projectId, {
+          id: state.id,
+          extra: {
+            workerRegistrationIds: [...(state.extra?.workerRegistrationIds ?? []), registration.id],
+          },
+        })
+      }
+
+      await batch.write()
+    })
+  }
+
+  private async ensureWorkerCreated(projectId: string, unitWorker: UnitWorker): Promise<string> {
+    const identity = getWorkerIdentity(unitWorker.image)
+
+    return await this.lockManager.acquire(["worker-image", projectId, identity], async () => {
+      // it is not critical to fetch all workers since their count is not expected to be high
+      const workers = await this.stateManager.getWorkerRepository(projectId).getAllItems()
+
+      const existingWorker = workers.find(worker => worker.image === unitWorker.image)
+      if (existingWorker) {
+        this.logger.debug(`worker with image "%s" already exists, reusing it`, unitWorker.image)
+        return existingWorker.id
+      }
+
+      let serviceAccountId: string | undefined
+
+      const siblingWorker = workers.find(worker => worker.identity === identity)
+      if (siblingWorker) {
+        this.logger.debug(
+          `sibling worker with identity "%s" already exists, using its service account`,
+          identity,
+        )
+
+        serviceAccountId = siblingWorker.serviceAccountId
+      }
+
+      const batch = this.stateManager.batch()
+
+      // create an empty service account if it is the first worker with this identity
+      // the meta of the account will be updated by the worker itself
+      if (!serviceAccountId) {
+        const serviceAccount: ServiceAccount = {
+          id: uuidv7(),
+          meta: {},
+        }
+
+        serviceAccountId = serviceAccount.id
+        await this.stateManager
+          .getServiceAccountRepository(projectId)
+          .putItem(serviceAccount, batch)
+      }
+
+      const apiKey: ProjectApiKey = {
+        id: uuidv7(),
+        meta: {},
+        token: randomBytes(32).toString("hex"),
+        scopes: [
+          {
+            type: "service-account",
+            actions: ["full"],
+            serviceAccountIds: [serviceAccountId],
+          },
+        ],
+      }
+
+      await this.stateManager.getApiKeyRepository(projectId).putItem(apiKey, batch)
+
+      const worker: Worker = {
+        id: uuidv7(),
+        meta: {},
+        status: "starting",
+        failedStartAttempts: 5,
+        identity,
+        image: unitWorker.image,
+        serviceAccountId,
+        apiKeyId: apiKey.id,
+      }
+
+      await this.stateManager.getWorkerRepository(projectId).putItem(worker, batch)
+      await batch.write()
+
+      this.workerManager.startWorker(projectId, worker)
+
+      return worker.id
+    })
+  }
+}

package/src/common/index.ts

@@ -1,3 +1,4 @@
 export * from "./utils"
-export * from "./pulumi"
 export * from "./local"
+export * from "./tree"
+export * from "./performance"

package/src/common/performance.ts

@@ -0,0 +1,44 @@
+import type { Logger } from "pino"
+
+export class PerformanceLogger {
+  private readonly start: number
+  private last: number
+
+  constructor(private readonly logger: Logger) {
+    this.start = Date.now()
+    this.last = this.start
+
+    this.logger.child({})
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  log(message: string, ...args: any[]): void {
+    const now = Date.now()
+    const diff = now - this.last
+    const absDiff = now - this.start
+
+    this.last = now
+
+    this.logger.debug(
+      {
+        message,
+        diff: PerformanceLogger.msToHumanReadable(diff),
+        absDiff: PerformanceLogger.msToHumanReadable(absDiff),
+      },
+      message,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      ...args,
+    )
+  }
+
+  private static msToHumanReadable(ms: number): string {
+    const seconds = Math.floor(ms / 1000)
+    const msPart = ms % 1000
+
+    if (seconds > 0) {
+      return `${seconds}s ${msPart}ms`
+    } else {
+      return `${msPart}ms`
+    }
+  }
+}

package/src/common/tree.ts

@@ -0,0 +1,33 @@
+export type TreeNode = {
+  text: string
+  children: TreeNode[]
+}
+
+/**
+ * Renders a tree structure similar to the Linux tree command output.
+ * Uses box-drawing characters to create visual hierarchy.
+ */
+export function renderTree(node: TreeNode): string {
+  const lines: string[] = []
+
+  function renderNode(node: TreeNode, prefix: string = "", isLast: boolean = true): void {
+    // Add current node
+    lines.push(prefix + (isLast ? "└── " : "├── ") + node.text)
+
+    // Add children
+    const childPrefix = prefix + (isLast ? "    " : "│   ")
+    node.children.forEach((child, index) => {
+      const isLastChild = index === node.children.length - 1
+      renderNode(child, childPrefix, isLastChild)
+    })
+  }
+
+  // Start with root node (no prefix)
+  lines.push(node.text)
+  node.children.forEach((child, index) => {
+    const isLastChild = index === node.children.length - 1
+    renderNode(child, "", isLastChild)
+  })
+
+  return lines.join("\n")
+}