@highstate/backend 0.9.37 → 0.11.3

package/package.json

@@ -1,13 +1,7 @@
 {
   "name": "@highstate/backend",
-  "version": "0.9.37",
+  "version": "0.11.3",
   "type": "module",
-  "highstate": {
-    "sourceHash": {
-      "mode": "manual",
-      "version": ""
-    }
-  },
   "files": [
     "dist",
     "src",
@@ -29,19 +23,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "highstate build",
-    "typecheck": "tsgo --noEmit --skipLibCheck",
-    "biome": "biome check --write --unsafe --error-on-warnings",
-    "biome:check": "biome check --error-on-warnings",
-    "test": "vitest --run",
-    "generate:project": "yarn prisma generate --schema prisma/project",
-    "generate:backend": "yarn prisma generate --schema prisma/backend/postgresql && yarn prisma generate --schema prisma/backend/sqlite",
-    "migrate": "yarn prisma migrate deploy --config dist/database/local/prisma.config.js"
-  },
   "dependencies": {
     "@aws-crypto/crc32": "^5.2.0",
-    "@highstate/contract": "^0.9.37",
+    "@highstate/contract": "^0.10.0",
     "@msgpack/msgpack": "^3.1.2",
     "@napi-rs/keyring": "^1.1.8",
     "@noble/ciphers": "^1.3.0",
@@ -50,12 +34,12 @@
     "@prisma/adapter-libsql": "^6.14.0",
     "@prisma/client": "^6.14.0",
     "@prisma/driver-adapter-utils": "^6.14.0",
-    "@types/node": "^22.10.1",
     "age-encryption": "^0.2.3",
     "ajv": "^8.17.1",
     "ansi-colors": "^4.1.3",
     "ansi-styles": "^6.2.1",
     "better-lock": "^3.2.0",
+    "buffer": "^6.0.3",
     "consola": "^3.2.3",
     "crypto-hash": "^3.1.0",
     "dotenv": "^16.4.7",
@@ -92,7 +76,7 @@
     "@biomejs/biome": "2.2.0",
     "@typescript/native-preview": "^7.0.0-dev.20250920.1",
     "classic-level": "^3.0.0",
-    "highstate-cli-bootstrap": "patch:@highstate/cli@npm%3A0.9.16#~/.yarn/patches/@highstate-cli-npm-0.9.16-e03b564691.patch",
+    "highstate-cli-bootstrap": "npm:@highstate/cli",
     "pino-pretty": "^13.0.0",
     "prisma-json-types-generator": "^3.5.2",
     "rollup": "^4.28.1",
@@ -100,5 +84,17 @@
     "type-fest": "^4.41.0",
     "vitest": "^3.2.4"
   },
-  "gitHead": "67c620e16be8f1244181539b4799c9990a2d9449"
-}
+  "repository": {
+    "url": "https://github.com/highstate-io/highstate"
+  },
+  "scripts": {
+    "build": "highstate build",
+    "typecheck": "tsgo --noEmit --skipLibCheck",
+    "biome": "biome check --write --unsafe --error-on-warnings",
+    "biome:check": "biome check --error-on-warnings",
+    "test": "vitest --run",
+    "generate:project": "prisma generate --schema prisma/project",
+    "generate:backend": "prisma generate --schema prisma/backend/postgresql && prisma generate --schema prisma/backend/sqlite",
+    "migrate": "prisma migrate deploy --config dist/database/local/prisma.config.js"
+  }
+}

package/src/database/local/backend.ts

@@ -10,12 +10,17 @@ import { PrismaClient } from "../_generated/backend/sqlite/client"
 import { type BackendDatabaseBackend, backendDatabaseVersion } from "../abstractions"
 import { migrateDatabase } from "../migrate"
 import { ensureWellKnownEntitiesCreated } from "../well-known"
-import { getOrCreateBackendIdentity } from "./keyring"
+import {
+  type BackendIdentityConfig,
+  backendIdentityConfig,
+  getOrCreateBackendIdentity,
+} from "./keyring"
 import { type DatabaseMetaFile, readMetaFile, writeMetaFile } from "./meta"
 
 export const localBackendDatabaseConfig = z.object({
   ...codebaseConfig.shape,
   HIGHSTATE_BACKEND_DATABASE_LOCAL_PATH: z.string().optional(),
+  ...backendIdentityConfig.shape,
   HIGHSTATE_ENCRYPTION_ENABLED: z.stringbool().default(true),
 })
 
@@ -26,6 +31,7 @@ class LocalBackendDatabaseBackend implements BackendDatabaseBackend {
   constructor(
     readonly database: BackendDatabase,
     private readonly databasePath: string,
+    private readonly config: BackendIdentityConfig,
     private readonly logger: Logger,
     readonly isEncryptionEnabled: boolean,
   ) {}
@@ -49,7 +55,7 @@ class LocalBackendDatabaseBackend implements BackendDatabaseBackend {
       return
     }
 
-    const identity = await getOrCreateBackendIdentity(this.logger)
+    const identity = await getOrCreateBackendIdentity(this.config, this.logger)
     const decrypter = new Decrypter()
     decrypter.addIdentity(identity)
 
@@ -72,8 +78,8 @@ class LocalBackendDatabaseBackend implements BackendDatabaseBackend {
   }
 }
 
-async function createMasterKey(logger: Logger) {
-  const identity = await getOrCreateBackendIdentity(logger)
+async function createMasterKey(config: BackendIdentityConfig, logger: Logger) {
+  const identity = await getOrCreateBackendIdentity(config, logger)
 
   const masterKey = randomBytes(32).toString("hex")
   const encrypter = new Encrypter()
@@ -98,6 +104,7 @@ type DatabaseInitializationResult = {
 async function ensureDatabaseInitialized(
   databasePath: string,
   encryptionEnabled: boolean,
+  config: BackendIdentityConfig,
   logger: Logger,
 ): Promise<DatabaseInitializationResult> {
   const meta = await readMetaFile(databasePath)
@@ -105,7 +112,7 @@ async function ensureDatabaseInitialized(
   if (!meta) {
     logger.info("creating new database")
 
-    const masterKey = encryptionEnabled ? await createMasterKey(logger) : undefined
+    const masterKey = encryptionEnabled ? await createMasterKey(config, logger) : undefined
 
     const metaFile: DatabaseMetaFile = {
       version: backendDatabaseVersion,
@@ -142,7 +149,7 @@ async function ensureDatabaseInitialized(
     )
   }
 
-  const identity = await getOrCreateBackendIdentity(logger)
+  const identity = await getOrCreateBackendIdentity(config, logger)
 
   const decrypter = new Decrypter()
   decrypter.addIdentity(identity)
@@ -150,8 +157,6 @@ async function ensureDatabaseInitialized(
   const encryptedMasterKey = armor.decode(meta.masterKey)
   const masterKey = await decrypter.decrypt(encryptedMasterKey, "text")
 
-  logger.info("loaded backend master key using OS keyring")
-
   return {
     shouldMigrate: meta.version < backendDatabaseVersion,
     masterKey,
@@ -179,7 +184,12 @@ export async function createLocalBackendDatabaseBackend(
   databasePath ??= await getCodebaseHighstatePath(config, logger)
 
   const { shouldMigrate, masterKey, metaFile, created, initialRecipient } =
-    await ensureDatabaseInitialized(databasePath, config.HIGHSTATE_ENCRYPTION_ENABLED, logger)
+    await ensureDatabaseInitialized(
+      databasePath,
+      config.HIGHSTATE_ENCRYPTION_ENABLED,
+      config,
+      logger,
+    )
 
   const databaseUrl = `file:${databasePath}/backend.db`
 
@@ -211,6 +221,7 @@ export async function createLocalBackendDatabaseBackend(
   return new LocalBackendDatabaseBackend(
     database,
     databasePath,
+    config,
     backendLogger,
     config.HIGHSTATE_ENCRYPTION_ENABLED,
   )

package/src/database/local/keyring.test.ts

@@ -0,0 +1,89 @@
+import type { Logger } from "pino"
+import { writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { generateIdentity } from "age-encryption"
+import pino from "pino"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { type BackendIdentityConfig, getOrCreateBackendIdentity } from "./keyring"
+
+const createLogger = (): Logger => pino({ level: "silent" })
+
+describe("getOrCreateBackendIdentity", () => {
+  let tempFilePath: string
+
+  beforeEach(() => {
+    tempFilePath = join(tmpdir(), `test-identity-${Date.now()}.key`)
+  })
+
+  afterEach(async () => {
+    try {
+      const { unlink } = await import("node:fs/promises")
+      await unlink(tempFilePath)
+    } catch {
+      // ignore cleanup errors
+    }
+  })
+
+  it("returns identity from HIGHSTATE_BACKEND_DATABASE_IDENTITY", async () => {
+    const testIdentity = await generateIdentity()
+    const config: BackendIdentityConfig = {
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY: testIdentity,
+    }
+
+    const identity = await getOrCreateBackendIdentity(config, createLogger())
+
+    expect(identity).toBe(testIdentity)
+  })
+
+  it("loads identity from HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH", async () => {
+    const testIdentity = await generateIdentity()
+    await writeFile(tempFilePath, testIdentity)
+
+    const config: BackendIdentityConfig = {
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH: tempFilePath,
+    }
+
+    const identity = await getOrCreateBackendIdentity(config, createLogger())
+
+    expect(identity).toBe(testIdentity)
+  })
+
+  it("trims whitespace from file-based identity", async () => {
+    const testIdentity = await generateIdentity()
+    await writeFile(tempFilePath, `  ${testIdentity}\n\n`)
+
+    const config: BackendIdentityConfig = {
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH: tempFilePath,
+    }
+
+    const identity = await getOrCreateBackendIdentity(config, createLogger())
+
+    expect(identity).toBe(testIdentity)
+  })
+
+  it("throws error if identity file does not exist", async () => {
+    const config: BackendIdentityConfig = {
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH: "/nonexistent/path/to/identity.key",
+    }
+
+    await expect(getOrCreateBackendIdentity(config, createLogger())).rejects.toThrow(
+      'Failed to read backend identity from "/nonexistent/path/to/identity.key"',
+    )
+  })
+
+  it("prioritizes HIGHSTATE_BACKEND_DATABASE_IDENTITY over PATH", async () => {
+    const directIdentity = await generateIdentity()
+    const fileIdentity = await generateIdentity()
+    await writeFile(tempFilePath, fileIdentity)
+
+    const config: BackendIdentityConfig = {
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY: directIdentity,
+      HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH: tempFilePath,
+    }
+
+    const identity = await getOrCreateBackendIdentity(config, createLogger())
+
+    expect(identity).toBe(directIdentity)
+  })
+})

package/src/database/local/keyring.ts

@@ -1,16 +1,66 @@
 import type { Logger } from "pino"
+import { readFile } from "node:fs/promises"
 import { AsyncEntry, findCredentialsAsync } from "@napi-rs/keyring"
 import { generateIdentity } from "age-encryption"
+import { z } from "zod"
 
 const serviceName = "io.highstate.backend"
 const accountName = "identity"
 
-export async function getOrCreateBackendIdentity(logger: Logger): Promise<string> {
+export const backendIdentityConfig = z.object({
+  HIGHSTATE_BACKEND_DATABASE_IDENTITY: z.string().optional(),
+  HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH: z.string().optional(),
+})
+
+export type BackendIdentityConfig = z.infer<typeof backendIdentityConfig>
+
+/**
+ * Retrieves or creates the backend identity for database encryption.
+ *
+ * The identity can be loaded from multiple sources in this priority order:
+ * 1. Environment variable HIGHSTATE_BACKEND_DATABASE_IDENTITY (direct identity string)
+ * 2. Environment variable HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH (path to identity file)
+ * 3. OS keyring (default behavior - creates new identity if not found)
+ *
+ * When using environment variables, the OS keyring is bypassed entirely.
+ * This is useful for environments where OS keyring is not available or for automation.
+ *
+ * @param config Configuration object containing optional identity environment variables.
+ * @param logger Logger instance for recording identity source and operations.
+ * @returns The AGE identity string used to decrypt the backend master key.
+ */
+export async function getOrCreateBackendIdentity(
+  config: BackendIdentityConfig,
+  logger: Logger,
+): Promise<string> {
+  // priority 1: direct identity from environment variable
+  if (config.HIGHSTATE_BACKEND_DATABASE_IDENTITY) {
+    logger.info("using backend identity from HIGHSTATE_BACKEND_DATABASE_IDENTITY")
+    return config.HIGHSTATE_BACKEND_DATABASE_IDENTITY
+  }
+
+  // priority 2: identity from file path specified in environment variable
+  if (config.HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH) {
+    try {
+      const identity = await readFile(config.HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH, "utf-8")
+      logger.info(
+        `using backend identity from path specified in HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH`,
+      )
+      return identity.trim()
+    } catch (error) {
+      throw new Error(
+        `Failed to read backend identity from "${config.HIGHSTATE_BACKEND_DATABASE_IDENTITY_PATH}"`,
+        { cause: error },
+      )
+    }
+  }
+
+  // priority 3: OS keyring (default behavior)
   const credentials = await findCredentialsAsync(serviceName)
   const entry = credentials.find(entry => entry.account === accountName)
 
   if (entry) {
-    logger.debug("found existing backend identity in keyring")
+    logger.info("using backend identity from OS keyring")
     return entry.password
   }