@highstate/backend 0.9.14 → 0.9.16

package/src/state/manager.ts

@@ -1,33 +1,819 @@
-import type { InstanceState } from "../shared"
-import EventEmitter, { on } from "node:events"
+import type { Logger } from "pino"
+import type { HotStateManager } from "../hotstate"
+import { randomBytes } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import { z } from "zod"
+import { BetterLock } from "better-lock"
+import { v4 as uuidv4, v5 as uuidv5 } from "uuid"
+import { armor, Decrypter, Encrypter, identityToRecipient } from "age-encryption"
+import { LRUCache } from "lru-cache"
+import {
+  terminalSessionSchema,
+  triggerSchema,
+  unlockMethodSchema,
+  terminalSchema,
+  terminalSpecSchema,
+  pageSchema,
+  artifactSchema,
+  secretSchema,
+  operationSchema,
+  instanceStateSchema,
+  serviceAccountSchema,
+  projectApiKeySchema,
+  workerSchema,
+  workerUnitRegistrationSchema,
+  instanceLockSchema,
+  compositeInstanceSchema,
+  pageBlockSchema,
+  projectSchema,
+  projectUnlockSuiteSchema,
+} from "../shared"
+import {
+  ProjectLockedError,
+  type StateBackend,
+  type StateBatch,
+  type StateSnapshot,
+} from "./abstractions"
+import { MasterKeyEncryptionBackend, type EncryptionBackend } from "./encryption"
+import { StateIndexRepository, StateRepository, NO_KEY_HASHING } from "./repository"
+import { getOrCreateBackendIdentity } from "./keyring"
 
-export type StateEvents = Record<string, [Partial<InstanceState>]>
+export const stateManagerConfig = z.object({
+  HIGHSTATE_BACKEND_MASTER_KEY: z.string().optional(),
+  HIGHSTATE_BACKEND_MASTER_KEY_PATH: z.string().optional(),
+})
 
+/**
+ * StateManager handles the creation of repositories and provides a unified interface
+ * for accessing typed repositories with proper configuration.
+ */
 export class StateManager {
-  private readonly stateEE = new EventEmitter<StateEvents>()
+  constructor(
+    private readonly backendNamespace: string,
+    private readonly encryptionBackend: EncryptionBackend,
+    private readonly backend: StateBackend,
+    private readonly hotStateManager: HotStateManager,
+    private readonly logger: Logger,
+  ) {}
 
   /**
-   * Watches for all instance state changes in the project.
+   * Creates a new batch for atomic operations.
+   * This allows multiple operations to be executed atomically.
+   */
+  batch(): StateBatch {
+    return this.backend.createStateBatch()
+  }
+
+  /**
+   * Creates a snapshot of the current state.
+   * This allows for consistent reads without affecting ongoing writes.
+   */
+  snapshot(): StateSnapshot {
+    return this.backend.createStateSnapshot()
+  }
+
+  /**
+   * Gets a repository with projects.
+   */
+  getProjectRepository(): StateRepository<typeof projectSchema> {
+    return new StateRepository(
+      this.backend.createProjectCollection(),
+      projectSchema,
+      this.encryptionBackend,
+      this.configureBackendKeyHashing(), // to hide project IDs
+      this.logger,
+    )
+  }
+
+  /**
+   * Gets a repository for encrypted project master keys armored in AGE's format.
+   * These project keys are not ready to be used for encryption/decryption
+   * and must be first decrypted using one of the project unlock methods.
+   */
+  getProjectMasterKeyRepository(): StateRepository<z.ZodString> {
+    return new StateRepository(
+      this.backend.createProjectMasterKeyCollection(),
+      z.string(),
+      this.encryptionBackend,
+      this.configureBackendKeyHashing(), // to hide project IDs
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for project unlock suites.
+   * They contain encrypted AGE identities which can be used to unlock project master keys.
+   */
+  getProjectUnlockSuiteRepository(): StateRepository<typeof projectUnlockSuiteSchema> {
+    return new StateRepository(
+      this.backend.createProjectUnlockSuiteCollection(),
+      projectUnlockSuiteSchema,
+      this.encryptionBackend,
+      this.configureBackendKeyHashing(), // to hide project IDs
+      this.logger,
+    )
+  }
+
+  /**
+   * Gets a repository for terminal sessions.
+   *
+   * @param projectId The ID of the project owning the terminal sessions.
+   */
+  getTerminalSessionRepository(projectId: string): StateRepository<typeof terminalSessionSchema> {
+    return new StateRepository(
+      this.backend.createTerminalSessionCollection(projectId),
+      terminalSessionSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates index repository which keeps the list of terminal sessions for a specific instance.
    *
-   * @param projectId The project ID to watch.
-   * @param signal The signal to abort the operation.
+   * @param projectId The ID of the project owning the terminal sessions.
+   * @param instanceId The ID of the instance to which the terminal sessions belong.
    */
-  public async *watchInstanceStates(
+  getInstanceTerminalSessionIndexRepository(
     projectId: string,
-    signal?: AbortSignal,
-  ): AsyncIterable<Partial<InstanceState>> {
-    for await (const [state] of on(this.stateEE, projectId, { signal })) {
-      yield state
-    }
+    instanceId: string,
+  ): StateIndexRepository<typeof terminalSessionSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getTerminalSessionRepository(projectId),
+      new StateRepository(
+        this.backend.createInstanceTerminalSessionIndexCollection(projectId, instanceId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        NO_KEY_HASHING, // we want to sort by UUIDv7
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates index repository which keeps the list of active terminal sessions.
+   *
+   * @param projectId The ID of the project owning the terminal sessions.
+   */
+  getActiveTerminalSessionIndexRepository(
+    projectId: string,
+  ): StateIndexRepository<typeof terminalSessionSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getTerminalSessionRepository(projectId),
+      new StateRepository(
+        this.backend.createActiveTerminalSessionIndexCollection(projectId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        this.configureKeyHashing(projectId), // to hide which terminal sessions are active
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for terminal session lines.
+   *
+   * @param projectId The ID of the project owning the terminal session.
+   * @param sessionId The ID of the terminal session to which the lines belong.
+   */
+  getTerminalSessionLineRepository(
+    projectId: string,
+    sessionId: string,
+  ): StateRepository<z.ZodString> {
+    return new StateRepository(
+      this.backend.createTerminalSessionLineCollection(projectId, sessionId),
+      z.string(),
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for project terminals.
+   *
+   * @param projectId The ID of the project owning the terminals.
+   */
+  getTerminalRepository(projectId: string): StateRepository<typeof terminalSchema> {
+    return new StateRepository(
+      this.backend.createTerminalCollection(projectId),
+      terminalSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for specifications of project terminals.
+   *
+   * @param projectId The ID of the project owning the terminals.
+   */
+  getTerminalSpecRepository(projectId: string): StateRepository<typeof terminalSpecSchema> {
+    return new StateRepository(
+      this.backend.createTerminalSpecCollection(projectId),
+      terminalSpecSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // nothing to hide
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for pages.
+   *
+   * @param projectId The ID of the project owning the pages.
+   */
+  getPageRepository(projectId: string): StateRepository<typeof pageSchema> {
+    return new StateRepository(
+      this.backend.createPageCollection(projectId),
+      pageSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for page content.
+   *
+   * @param projectId The ID of the project owning the page content.
+   */
+  getPageContentRepository(projectId: string): StateRepository<z.ZodArray<typeof pageBlockSchema>> {
+    return new StateRepository(
+      this.backend.createPageContentCollection(projectId),
+      pageBlockSchema.array(),
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // nothing to hide
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for service accounts.
+   *
+   * @param projectId The ID of the project owning the service accounts.
+   */
+  getServiceAccountRepository(projectId: string): StateRepository<typeof serviceAccountSchema> {
+    return new StateRepository(
+      this.backend.createServiceAccountCollection(projectId),
+      serviceAccountSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for API keys.
+   *
+   * @param projectId The ID of the project owning the API keys.
+   */
+  getApiKeyRepository(projectId: string): StateRepository<typeof projectApiKeySchema> {
+    return new StateRepository(
+      this.backend.createApiKeyCollection(projectId),
+      projectApiKeySchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by ULID
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository which maps API key tokens to API key IDs.
+   * The tokens are hashed to prevent leaking sensitive information.
+   *
+   * @param projectId The ID of the project owning the API keys.
+   */
+  getApiKeyTokenIndexRepository(
+    projectId: string,
+  ): StateIndexRepository<typeof projectApiKeySchema> {
+    return new StateIndexRepository(
+      this,
+      this.getApiKeyRepository(projectId),
+      new StateRepository(
+        this.backend.createApiKeyTokenIndexCollection(projectId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        this.configureKeyHashing(projectId), // to hide the tokens
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for workers.
+   *
+   * @param projectId The ID of the project owning the workers.
+   */
+  getWorkerRepository(projectId: string): StateRepository<typeof workerSchema> {
+    return new StateRepository(
+      this.backend.createWorkerCollection(projectId),
+      workerSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for worker logs.
+   *
+   * @param projectId The ID of the project owning the worker logs.
+   * @param workerId The ID of the worker to which the logs belong.
+   */
+  getWorkerLogRepository(projectId: string, workerId: string): StateRepository<z.ZodString> {
+    return new StateRepository(
+      this.backend.createWorkerLogCollection(projectId, workerId),
+      z.string(),
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for worker registrations.
+   *
+   * @param projectId The ID of the project owning the worker registrations.
+   */
+  getWorkerRegistrationRepository(
+    projectId: string,
+  ): StateRepository<typeof workerUnitRegistrationSchema> {
+    return new StateRepository(
+      this.backend.createWorkerRegistrationCollection(projectId),
+      workerUnitRegistrationSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository which holds the list of worker registrations.
+   *
+   * @param projectId The ID of the project owning the workers.
+   * @param workerId The ID of the worker.
+   */
+  getWorkerRegistrationIndexRepository(
+    projectId: string,
+    workerId: string,
+  ): StateIndexRepository<typeof workerUnitRegistrationSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getWorkerRegistrationRepository(projectId),
+      new StateRepository(
+        this.backend.createWorkerRegistrationIndexCollection(projectId, workerId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        NO_KEY_HASHING, // we want to sort by UUIDv7
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Gets a repository for artifacts.
+   *
+   * @param projectId The ID of the project owning the artifacts.
+   */
+  getArtifactRepository(projectId: string): StateRepository<typeof artifactSchema> {
+    return new StateRepository(
+      this.backend.createArtifactCollection(projectId),
+      artifactSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository which maps artifact hashes to artifact IDs.
+   *
+   * @param projectId The ID of the project owning the artifacts.
+   */
+  getArtifactHashIndexRepository(projectId: string): StateIndexRepository<typeof artifactSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getArtifactRepository(projectId),
+      new StateRepository(
+        this.backend.createArtifactHashIndexCollection(projectId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        this.configureKeyHashing(projectId), // to hide the original sha256 hash
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for trigger info.
+   *
+   * @param projectId The ID of the project owning the triggers.
+   */
+  getTriggerRepository(projectId: string): StateRepository<typeof triggerSchema> {
+    return new StateRepository(
+      this.backend.createTriggerCollection(projectId),
+      triggerSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for unlock methods.
+   *
+   * @param projectId The ID of the project owning the unlock methods.
+   */
+  getUnlockMethodRepository(projectId: string): StateRepository<typeof unlockMethodSchema> {
+    return new StateRepository(
+      this.backend.createUnlockMethodCollection(projectId),
+      unlockMethodSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for secret info.
+   *
+   * @param projectId The ID of the project owning the secrets.
+   */
+  getSecretRepository(projectId: string): StateRepository<typeof secretSchema> {
+    const collection = this.backend.createSecretCollection(projectId)
+
+    return new StateRepository(
+      //
+      collection,
+      secretSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for secret content.
+   *
+   * The ID is secret ID, not UUIDv7.
+   *
+   * @param projectId The ID of the project owning the secret content.
+   */
+  getSecretContentRepository(projectId: string): StateRepository<z.ZodUnknown> {
+    return new StateRepository(
+      this.backend.createSecretContentCollection(projectId),
+      z.unknown(),
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // nothing to hide
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository to map descriptors like `instance:{instanceId}:{secretName}` or `system:{systemSecretName}`
+   * to UUIDv7 IDs of these secrets.
+   *
+   * @param projectId The ID of the project owning the secrets.
+   */
+  createSecretIndexRepository(projectId: string): StateIndexRepository<typeof secretSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getSecretRepository(projectId),
+      new StateRepository(
+        this.backend.createSecretIndexCollection(projectId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        this.configureKeyHashing(projectId), // to hide the descriptor
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for operation logs.
+   *
+   * @param projectId The ID of the project owning the operation logs.
+   * @param operationId The ID of the operation to which the logs belong.
+   */
+  getOperationLogRepository(projectId: string, operationId: string): StateRepository<z.ZodString> {
+    return new StateRepository(
+      this.backend.createOperationLogCollection(projectId, operationId),
+      z.string(),
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository for instance logs.
+   * This repository allows to retrieve operation logs by instance ID.
+   *
+   * @param projectId The ID of the project owning the operation logs.
+   * @param operationId The ID of the operation to which the logs belong.
+   * @param instanceId The ID of the instance to which the logs belong.
+   */
+  getInstanceLogIndexRepository(
+    projectId: string,
+    operationId: string,
+    instanceId: string,
+  ): StateIndexRepository<z.ZodString> {
+    return new StateIndexRepository(
+      this,
+      this.getOperationLogRepository(projectId, operationId),
+      new StateRepository(
+        this.backend.createInstanceLogIndexCollection(projectId, operationId, instanceId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        NO_KEY_HASHING, // we want to sort by UUIDv7
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for operation info.
+   *
+   * @param projectId The ID of the project owning the operations.
+   */
+  getOperationRepository(projectId: string): StateRepository<typeof operationSchema> {
+    return new StateRepository(
+      this.backend.createOperationCollection(projectId),
+      operationSchema,
+      this.getEncryptionBackend(projectId),
+      NO_KEY_HASHING, // we want to sort by UUIDv7
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates an index repository for active operations.
+   *
+   * @param projectId The ID of the project owning the operations.
+   */
+  getActiveOperationIndexRepository(
+    projectId: string,
+  ): StateIndexRepository<typeof operationSchema> {
+    return new StateIndexRepository(
+      this,
+      this.getOperationRepository(projectId),
+      new StateRepository(
+        this.backend.createActiveOperationIndexCollection(projectId),
+        z.string(),
+        this.getEncryptionBackend(projectId),
+        this.configureKeyHashing(projectId), // to hide which operations are active
+        this.logger,
+      ),
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for instance states with sensitive ID hashing.
+   *
+   * @param projectId The ID of the project owning the instance states.
+   */
+  getInstanceStateRepository(projectId: string): StateRepository<typeof instanceStateSchema> {
+    return new StateRepository(
+      this.backend.createInstanceStateCollection(projectId),
+      instanceStateSchema,
+      this.getEncryptionBackend(projectId),
+      this.configureKeyHashing(projectId), // to hide the instance ID
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for instance locks.
+   *
+   * @param projectId The ID of the project owning the instance locks.
+   */
+  getInstanceLockRepository(projectId: string): StateRepository<typeof instanceLockSchema> {
+    return new StateRepository(
+      this.backend.createInstanceLockCollection(projectId),
+      instanceLockSchema,
+      this.getEncryptionBackend(projectId),
+      this.configureKeyHashing(projectId), // to hide the instance ID
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for composite instances with sensitive ID hashing.
+   */
+  getCompositeInstanceRepository(
+    projectId: string,
+  ): StateRepository<typeof compositeInstanceSchema> {
+    return new StateRepository(
+      this.backend.createCompositeInstanceCollection(projectId),
+      compositeInstanceSchema,
+      this.getEncryptionBackend(projectId),
+      this.configureKeyHashing(projectId), // to hide the composite instance ID
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for user layouts.
+   */
+  getUserLayoutRepository(): StateRepository<z.ZodUnknown> {
+    return new StateRepository(
+      this.backend.createUserLayoutCollection(),
+      z.unknown(),
+      this.encryptionBackend,
+      this.configureBackendKeyHashing(), // to hide user IDs
+      this.logger,
+    )
+  }
+
+  /**
+   * Creates a repository for project viewports.
+   *
+   * @param projectId The ID of the project owning the viewports.
+   */
+  getProjectViewportRepository(projectId: string): StateRepository<z.ZodUnknown> {
+    return new StateRepository(
+      this.backend.createProjectViewportCollection(projectId),
+      z.unknown(),
+      this.getEncryptionBackend(projectId),
+      this.configureKeyHashing(projectId), // to hide user IDs
+      this.logger,
+    )
   }
 
   /**
-   * Emits a state patch for the instance in the project.
+   * Creates a repository for instance viewports.
    *
-   * @param projectId The project ID to emit the state patch for.
-   * @param patch The state patch to emit.
+   * @param projectId The ID of the project owning the viewports.
+   * @param instanceId The ID of the instance to which the viewports belong.
    */
-  public emitStatePatch(projectId: string, patch: Partial<InstanceState>): void {
-    this.stateEE.emit(projectId, patch)
+  getInstanceViewportRepository(
+    projectId: string,
+    instanceId: string,
+  ): StateRepository<z.ZodUnknown> {
+    return new StateRepository(
+      this.backend.createInstanceViewportCollection(projectId, instanceId),
+      z.unknown(),
+      this.getEncryptionBackend(projectId),
+      this.configureKeyHashing(projectId), // to hide user IDs
+      this.logger,
+    )
+  }
+
+  private idNamespaceHashCache = new Map<string, string>()
+  private idNamespaceHashLock = new BetterLock()
+
+  private getProjectIdHashNamespaceRepository(): StateRepository<z.ZodString> {
+    return new StateRepository(
+      this.backend.createProjectIdHashNamespaceCollection(),
+      z.string(),
+      this.encryptionBackend,
+      () => Promise.resolve(this.backendNamespace),
+      this.logger,
+    )
+  }
+
+  private configureBackendKeyHashing(): () => Promise<string> {
+    return () => Promise.resolve(this.backendNamespace)
+  }
+
+  public configureKeyHashing(projectId: string): () => Promise<string> {
+    return async () => {
+      const existing = this.idNamespaceHashCache.get(projectId)
+      if (existing) {
+        return existing
+      }
+
+      return await this.idNamespaceHashLock.acquire(projectId, async () => {
+        let stored = await this.getProjectIdHashNamespaceRepository().get(projectId)
+
+        if (!stored) {
+          stored = uuidv4()
+          await this.getProjectIdHashNamespaceRepository().put(projectId, stored)
+        }
+
+        this.idNamespaceHashCache.set(projectId, stored)
+        return stored
+      })
+    }
+  }
+
+  // store the master keys in memory cache for 30 seconds
+  private readonly masterKeyCache = new LRUCache<string, Uint8Array>({
+    ttl: 30_000,
+    ttlAutopurge: true,
+  })
+
+  async getProjectMasterKey(projectId: string): Promise<Uint8Array> {
+    const cachedKey = this.masterKeyCache.get(projectId)
+    if (cachedKey) {
+      return cachedKey
+    }
+
+    const masterKey = await this.hotStateManager.get(["project-master-key", projectId])
+    if (!masterKey) {
+      throw new ProjectLockedError(projectId)
+    }
+
+    this.masterKeyCache.set(projectId, masterKey)
+    return masterKey
+  }
+
+  public getEncryptionBackend(projectId: string): EncryptionBackend {
+    return new MasterKeyEncryptionBackend(() => this.getProjectMasterKey(projectId))
+  }
+
+  public getHashedProjectId(projectId: string): string {
+    return uuidv5(projectId, this.backendNamespace)
+  }
+
+  static async create(
+    config: z.infer<typeof stateManagerConfig>,
+    backend: StateBackend,
+    hotStateManager: HotStateManager,
+    logger: Logger,
+  ): Promise<StateManager> {
+    let backendId = await backend.getStaticBackendId()
+    if (!backendId) {
+      backendId = uuidv4()
+      await backend.setStaticBackendId(backendId)
+    }
+
+    const masterKey = await StateManager.loadBackendMasterKey(config, backend, logger)
+    const encryptionBackend = new MasterKeyEncryptionBackend(() => Promise.resolve(masterKey))
+
+    return new StateManager(backendId, encryptionBackend, backend, hotStateManager, logger)
+  }
+
+  static async loadBackendMasterKey(
+    config: z.infer<typeof stateManagerConfig>,
+    backend: StateBackend,
+    logger: Logger,
+  ): Promise<Uint8Array> {
+    // 1. try to load the master key from HIGHSTATE_BACKEND_MASTER_KEY
+    const configMasterKey = config.HIGHSTATE_BACKEND_MASTER_KEY
+    if (configMasterKey) {
+      logger.info("loaded backend master key from HIGHSTATE_BACKEND_MASTER_KEY")
+
+      return Buffer.from(configMasterKey, "hex")
+    }
+
+    // 2. try to load the master key from file path provided in HIGHSTATE_BACKEND_MASTER_KEY_PATH
+    const configMasterKeyPath = config.HIGHSTATE_BACKEND_MASTER_KEY_PATH
+    if (configMasterKeyPath) {
+      try {
+        const content = await readFile(configMasterKeyPath, "utf-8")
+
+        return Buffer.from(content.trim(), "hex")
+      } catch (error) {
+        throw new Error(`Failed to read backend master key from path: ${configMasterKeyPath}`, {
+          cause: error,
+        })
+      }
+    }
+
+    // 3. try to decrypt the master key using the keyring
+    try {
+      const identity = await getOrCreateBackendIdentity(logger)
+
+      let armoredMasterKey = await backend.getEncryptedBackendMasterKey()
+      if (!armoredMasterKey) {
+        const masterKey = randomBytes(32)
+        const encrypter = new Encrypter()
+
+        const recipient = await identityToRecipient(identity)
+        encrypter.addRecipient(recipient)
+
+        const encryptedMasterKey = await encrypter.encrypt(masterKey)
+        armoredMasterKey = armor.encode(encryptedMasterKey)
+        await backend.setEncryptedBackendMasterKey(armoredMasterKey)
+
+        logger.info("generated and stored new backend master key")
+      }
+
+      const decrypter = new Decrypter()
+      decrypter.addIdentity(identity)
+
+      const encryptedMasterKey = armor.decode(armoredMasterKey)
+      const masterKey = await decrypter.decrypt(encryptedMasterKey)
+
+      logger.info("loaded backend master key using OS keyring")
+
+      return masterKey
+    } catch (error) {
+      throw new Error("Failed to load master key using OS keyring", { cause: error })
+    }
   }
 }